git update 9/7/2010

49 files changed, 72310 insertions, 49318 deletions

diff --git a/libX11/specs/libX11/AppA b/libX11/specs/libX11/AppA
deleted file mode 100644
index 26a1ba32f..000000000
--- a/libX11/specs/libX11/AppA
+++ /dev/null
@@ -1,604 +0,0 @@
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-.\" OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" Except as contained in this notice, the name of the X Consortium shall
-.\" not be used in advertising or otherwise to promote the sale, use or
-.\" other dealings in this Software without prior written authorization
-.\" from the X Consortium.
-.\"
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
-.\" Digital Equipment Corporation
-.\"
-.\" Portions Copyright \(co 1990, 1991 by
-.\" Tektronix, Inc.
-.\"
-.\" Permission to use, copy, modify and distribute this documentation for
-.\" any purpose and without fee is hereby granted, provided that the above
-.\" copyright notice appears in all copies and that both that copyright notice
-.\" and this permission notice appear in all copies, and that the names of
-.\" Digital and Tektronix not be used in in advertising or publicity pertaining
-.\" to this documentation without specific, written prior permission.
-.\" Digital and Tektronix makes no representations about the suitability
-.\" of this documentation for any purpose.
-.\" It is provided ``as is'' without express or implied warranty.
-.\" 
-\&
-.sp 1
-.ce 3
-\s+1\fBAppendix A\fP\s-1
-
-\s+1\fBXlib Functions and Protocol Requests\fP\s-1
-.sp 2
-.na
-.LP
-.XS
-Appendix A: Xlib Functions and Protocol Requests
-.XE
-This appendix provides two tables that relate to Xlib functions 
-and the X protocol.
-The following table lists each Xlib function (in alphabetical order)
-and the corresponding protocol request that it generates.
-.LP
-.TS H
-lw(2.5i) lw(2.5i).
-_
-.sp 6p
-.B
-Xlib Function	Protocol Request
-.sp 6p
-_
-.sp 6p
-.TH
-.R
-XActivateScreenSaver	ForceScreenSaver
-XAddHost	ChangeHosts
-XAddHosts	ChangeHosts
-XAddToSaveSet	ChangeSaveSet
-XAllocColor	AllocColor
-XAllocColorCells	AllocColorCells
-XAllocColorPlanes	AllocColorPlanes
-XAllocNamedColor	AllocNamedColor
-XAllowEvents	AllowEvents
-XAutoRepeatOff	ChangeKeyboardControl
-XAutoRepeatOn	ChangeKeyboardControl
-XBell	Bell
-XChangeActivePointerGrab	ChangeActivePointerGrab
-XChangeGC	ChangeGC
-XChangeKeyboardControl	ChangeKeyboardControl
-XChangeKeyboardMapping	ChangeKeyboardMapping
-XChangePointerControl	ChangePointerControl
-XChangeProperty	ChangeProperty
-XChangeSaveSet	ChangeSaveSet
-XChangeWindowAttributes	ChangeWindowAttributes
-XCirculateSubwindows	CirculateWindow
-XCirculateSubwindowsDown	CirculateWindow
-XCirculateSubwindowsUp	CirculateWindow
-XClearArea	ClearArea
-XClearWindow	ClearArea
-XConfigureWindow	ConfigureWindow
-XConvertSelection	ConvertSelection
-XCopyArea	CopyArea
-XCopyColormapAndFree	CopyColormapAndFree
-XCopyGC	CopyGC
-XCopyPlane	CopyPlane
-XCreateBitmapFromData	CreateGC
-	CreatePixmap
-	FreeGC
-	PutImage
-XCreateColormap	CreateColormap
-XCreateFontCursor	CreateGlyphCursor
-XCreateGC	CreateGC
-XCreateGlyphCursor	CreateGlyphCursor
-XCreatePixmap	CreatePixmap
-XCreatePixmapCursor	CreateCursor
-XCreatePixmapFromData	CreateGC
-	CreatePixmap
-	FreeGC
-	PutImage
-XCreateSimpleWindow	CreateWindow
-XCreateWindow	CreateWindow
-XDefineCursor	ChangeWindowAttributes
-XDeleteProperty	DeleteProperty
-XDestroySubwindows	DestroySubwindows
-XDestroyWindow	DestroyWindow
-XDisableAccessControl	SetAccessControl
-XDrawArc	PolyArc
-XDrawArcs	PolyArc
-XDrawImageString	ImageText8
-XDrawImageString16	ImageText16
-XDrawLine	PolySegment
-XDrawLines	PolyLine
-XDrawPoint	PolyPoint 
-XDrawPoints	PolyPoint
-XDrawRectangle	PolyRectangle
-XDrawRectangles	PolyRectangle
-XDrawSegments	PolySegment
-XDrawString	PolyText8
-XDrawString16	PolyText16
-XDrawText	PolyText8
-XDrawText16	PolyText16
-XEnableAccessControl	SetAccessControl
-XFetchBytes	GetProperty
-XFetchName	GetProperty
-XFillArc	PolyFillArc
-XFillArcs	PolyFillArc
-XFillPolygon	FillPoly
-XFillRectangle	PolyFillRectangle
-XFillRectangles	PolyFillRectangle
-XForceScreenSaver	ForceScreenSaver
-XFreeColormap	FreeColormap
-XFreeColors	FreeColors
-XFreeCursor	FreeCursor
-XFreeFont	CloseFont
-XFreeGC	FreeGC
-XFreePixmap	FreePixmap
-XGetAtomName	GetAtomName
-XGetClassHint	GetProperty
-XGetFontPath	GetFontPath
-XGetGeometry	GetGeometry
-XGetIconName	GetProperty
-XGetIconSizes	GetProperty
-XGetImage	GetImage
-XGetInputFocus	GetInputFocus
-XGetKeyboardControl	GetKeyboardControl
-XGetKeyboardMapping	GetKeyboardMapping
-XGetModifierMapping	GetModifierMapping
-XGetMotionEvents	GetMotionEvents
-XGetNormalHints	GetProperty
-XGetPointerControl	GetPointerControl
-XGetPointerMapping	GetPointerMapping
-XGetRGBColormaps	GetProperty
-XGetScreenSaver	GetScreenSaver
-XGetSelectionOwner	GetSelectionOwner
-XGetSizeHints	GetProperty
-XGetTextProperty	GetProperty
-XGetTransientForHint	GetProperty
-XGetWMClientMachine	GetProperty
-XGetWMColormapWindows	GetProperty
-	InternAtom
-XGetWMHints	GetProperty
-XGetWMIconName	GetProperty
-XGetWMName	GetProperty
-XGetWMNormalHints	GetProperty
-XGetWMProtocols	GetProperty
-	InternAtom
-XGetWMSizeHints	GetProperty
-XGetWindowAttributes	GetWindowAttributes
-	GetGeometry
-XGetWindowProperty	GetProperty
-XGetZoomHints	GetProperty
-XGrabButton	GrabButton
-XGrabKey	GrabKey
-XGrabKeyboard	GrabKeyboard
-XGrabPointer	GrabPointer
-XGrabServer	GrabServer
-XIconifyWindow	InternAtom
-	SendEvent
-XInitExtension	QueryExtension
-XInstallColormap	InstallColormap
-XInternAtom	InternAtom
-XKillClient	KillClient
-XListExtensions	ListExtensions
-XListFonts	ListFonts
-XListFontsWithInfo	ListFontsWithInfo
-XListHosts	ListHosts
-XListInstalledColormaps	ListInstalledColormaps
-XListProperties	ListProperties
-XLoadFont	OpenFont
-XLoadQueryFont	OpenFont
-	QueryFont
-XLookupColor	LookupColor
-XLowerWindow	ConfigureWindow
-XMapRaised	ConfigureWindow
-	MapWindow
-XMapSubwindows	MapSubwindows
-XMapWindow	MapWindow
-XMoveResizeWindow	ConfigureWindow
-XMoveWindow	ConfigureWindow
-XNoOp	NoOperation
-XOpenDisplay	CreateGC
-XParseColor	LookupColor
-XPutImage	PutImage
-XQueryBestCursor	QueryBestSize
-XQueryBestSize	QueryBestSize
-XQueryBestStipple	QueryBestSize
-XQueryBestTile	QueryBestSize
-XQueryColor	QueryColors 
-XQueryColors	QueryColors
-XQueryExtension	QueryExtension
-XQueryFont	QueryFont
-XQueryKeymap	QueryKeymap
-XQueryPointer	QueryPointer
-XQueryTextExtents	QueryTextExtents
-XQueryTextExtents16	QueryTextExtents
-XQueryTree	QueryTree
-XRaiseWindow	ConfigureWindow
-XReadBitmapFile	CreateGC
-	CreatePixmap
-	FreeGC
-	PutImage
-XRecolorCursor	RecolorCursor
-XReconfigureWMWindow	ConfigureWindow
-	SendEvent
-XRemoveFromSaveSet	ChangeSaveSet
-XRemoveHost	ChangeHosts
-XRemoveHosts	ChangeHosts
-XReparentWindow	ReparentWindow
-XResetScreenSaver	ForceScreenSaver
-XResizeWindow	ConfigureWindow 
-XRestackWindows    	ConfigureWindow
-XRotateBuffers	RotateProperties
-XRotateWindowProperties	RotateProperties
-XSelectInput	ChangeWindowAttributes
-XSendEvent	SendEvent
-XSetAccessControl	SetAccessControl
-XSetArcMode	ChangeGC
-XSetBackground	ChangeGC 
-XSetClassHint	ChangeProperty
-XSetClipMask	ChangeGC
-XSetClipOrigin	ChangeGC
-XSetClipRectangles	SetClipRectangles
-XSetCloseDownMode	SetCloseDownMode
-XSetCommand	ChangeProperty
-XSetDashes	SetDashes
-XSetFillRule	ChangeGC
-XSetFillStyle	ChangeGC
-XSetFont	ChangeGC 
-XSetFontPath	SetFontPath
-XSetForeground	ChangeGC 
-XSetFunction	ChangeGC 
-XSetGraphicsExposures	ChangeGC
-XSetIconName	ChangeProperty
-XSetIconSizes	ChangeProperty
-XSetInputFocus	SetInputFocus
-XSetLineAttributes	ChangeGC
-XSetModifierMapping	SetModifierMapping
-XSetNormalHints	ChangeProperty
-XSetPlaneMask	ChangeGC 
-XSetPointerMapping	SetPointerMapping
-XSetRGBColormaps	ChangeProperty
-XSetScreenSaver	SetScreenSaver
-XSetSelectionOwner	SetSelectionOwner
-XSetSizeHints	ChangeProperty
-XSetStandardProperties	ChangeProperty
-XSetState	ChangeGC
-XSetStipple	ChangeGC
-XSetSubwindowMode	ChangeGC
-XSetTextProperty	ChangeProperty
-XSetTile	ChangeGC
-XSetTransientForHint	ChangeProperty
-XSetTSOrigin	ChangeGC
-XSetWMClientMachine	ChangeProperty
-XSetWMColormapWindows	ChangeProperty
-	InternAtom
-XSetWMHints	ChangeProperty
-XSetWMIconName	ChangeProperty
-XSetWMName	ChangeProperty
-XSetWMNormalHints	ChangeProperty
-XSetWMProperties	ChangeProperty
-XSetWMProtocols	ChangeProperty
-	InternAtom
-XSetWMSizeHints	ChangeProperty
-XSetWindowBackground	ChangeWindowAttributes
-XSetWindowBackgroundPixmap	ChangeWindowAttributes
-XSetWindowBorder	ChangeWindowAttributes
-XSetWindowBorderPixmap	ChangeWindowAttributes
-XSetWindowBorderWidth	ConfigureWindow
-XSetWindowColormap	ChangeWindowAttributes
-XSetZoomHints	ChangeProperty
-XStoreBuffer	ChangeProperty
-XStoreBytes	ChangeProperty
-XStoreColor	StoreColors 
-XStoreColors	StoreColors
-XStoreName	ChangeProperty
-XStoreNamedColor	StoreNamedColor
-XSync	GetInputFocus
-XSynchronize	GetInputFocus
-XTranslateCoordinates	TranslateCoordinates
-XUndefineCursor	ChangeWindowAttributes
-XUngrabButton	UngrabButton
-XUngrabKey	UngrabKey
-XUngrabKeyboard	UngrabKeyboard
-XUngrabPointer	UngrabPointer
-XUngrabServer	UngrabServer
-XUninstallColormap	UninstallColormap
-XUnloadFont	CloseFont
-XUnmapSubwindows	UnmapSubwindows
-XUnmapWindow	UnmapWindow
-XWarpPointer	WarpPointer
-XWithdrawWindow	SendEvent
-	UnmapWindow
-.TE
-.bp
-.LP
-The following table lists each X protocol request (in alphabetical
-order) and the Xlib functions that reference it.
-.TS H
-lw(2.5i) lw(2.5i).
-_
-.sp 6p
-.B
-Protocol Request	Xlib Function
-.sp 6p
-_
-.sp 6p
-.TH
-.R
-AllocColor	XAllocColor
-AllocColorCells	XAllocColorCells
-AllocColorPlanes	XAllocColorPlanes
-AllocNamedColor	XAllocNamedColor
-AllowEvents	XAllowEvents
-Bell	XBell
-ChangeActivePointerGrab	XChangeActivePointerGrab
-ChangeGC	XChangeGC
-	XSetArcMode
-	XSetBackground
-	XSetClipMask
-	XSetClipOrigin
-	XSetFillRule
-	XSetFillStyle
-	XSetFont
-	XSetForeground
-	XSetFunction
-	XSetGraphicsExposures
-	XSetLineAttributes
-	XSetPlaneMask
-	XSetState
-	XSetStipple
-	XSetSubwindowMode
-	XSetTile
-	XSetTSOrigin
-ChangeHosts	XAddHost
-	XAddHosts
-	XRemoveHost
-	XRemoveHosts
-ChangeKeyboardControl	XAutoRepeatOff
-	XAutoRepeatOn
-	XChangeKeyboardControl
-ChangeKeyboardMapping	XChangeKeyboardMapping
-ChangePointerControl	XChangePointerControl
-ChangeProperty	XChangeProperty
-	XSetClassHint
-	XSetCommand
-	XSetIconName
-	XSetIconSizes
-	XSetNormalHints
-	XSetRGBColormaps
-	XSetSizeHints
-	XSetStandardProperties
-	XSetTextProperty
-	XSetTransientForHint
-	XSetWMClientMachine
-	XSetWMColormapWindows
-	XSetWMHints
-	XSetWMIconName
-	XSetWMName
-	XSetWMNormalHints
-	XSetWMProperties
-	XSetWMProtocols
-	XSetWMSizeHints
-	XSetZoomHints
-	XStoreBuffer
-	XStoreBytes
-	XStoreName
-ChangeSaveSet	XAddToSaveSet
-	XChangeSaveSet
-	XRemoveFromSaveSet
-ChangeWindowAttributes	XChangeWindowAttributes
-	XDefineCursor
-	XSelectInput
-	XSetWindowBackground
-	XSetWindowBackgroundPixmap
-	XSetWindowBorder
-	XSetWindowBorderPixmap
-	XSetWindowColormap
-	XUndefineCursor
-CirculateWindow	XCirculateSubwindowsDown
-	XCirculateSubwindowsUp
-	XCirculateSubwindows
-ClearArea	XClearArea
-	XClearWindow
-CloseFont	XFreeFont
-	XUnloadFont
-ConfigureWindow	XConfigureWindow
-	XLowerWindow
-	XMapRaised
-	XMoveResizeWindow
-	XMoveWindow
-	XRaiseWindow
-	XReconfigureWMWindow
-	XResizeWindow
-	XRestackWindows
-	XSetWindowBorderWidth
-ConvertSelection	XConvertSelection
-CopyArea	XCopyArea
-CopyColormapAndFree	XCopyColormapAndFree
-CopyGC	XCopyGC
-CopyPlane	XCopyPlane
-CreateColormap	XCreateColormap
-CreateCursor	XCreatePixmapCursor
-CreateGC	XCreateGC
-	XCreateBitmapFromData
-	XCreatePixmapFromData
-	XOpenDisplay
-	XReadBitmapFile
-CreateGlyphCursor	XCreateFontCursor
-	XCreateGlyphCursor
-CreatePixmap	XCreatePixmap
-	XCreateBitmapFromData
-	XCreatePixmapFromData
-	XReadBitmapFile
-CreateWindow	XCreateSimpleWindow
-	XCreateWindow
-DeleteProperty	XDeleteProperty
-DestroySubwindows	XDestroySubwindows
-DestroyWindow	XDestroyWindow
-FillPoly	XFillPolygon
-ForceScreenSaver	XActivateScreenSaver
-	XForceScreenSaver
-	XResetScreenSaver
-FreeColormap	XFreeColormap
-FreeColors	XFreeColors
-FreeCursor	XFreeCursor
-FreeGC	XFreeGC
-	XCreateBitmapFromData
-	XCreatePixmapFromData
-	XReadBitmapFile
-FreePixmap	XFreePixmap
-GetAtomName	XGetAtomName
-GetFontPath	XGetFontPath
-GetGeometry	XGetGeometry
-	XGetWindowAttributes
-GetImage	XGetImage
-GetInputFocus	XGetInputFocus
-	XSync
-	XSynchronize
-GetKeyboardControl	XGetKeyboardControl
-GetKeyboardMapping	XGetKeyboardMapping
-GetModifierMapping	XGetModifierMapping
-GetMotionEvents	XGetMotionEvents
-GetPointerControl	XGetPointerControl
-GetPointerMapping	XGetPointerMapping
-GetProperty	XFetchBytes
-	XFetchName
-	XGetClassHint
-	XGetIconName
-	XGetIconSizes
-	XGetNormalHints
-	XGetRGBColormaps
-	XGetSizeHints
-	XGetTextProperty
-	XGetTransientForHint
-	XGetWMClientMachine
-	XGetWMColormapWindows
-	XGetWMHints
-	XGetWMIconName
-	XGetWMName
-	XGetWMNormalHints
-	XGetWMProtocols
-	XGetWMSizeHints
-	XGetWindowProperty
-	XGetZoomHints
-GetSelectionOwner	XGetSelectionOwner
-GetWindowAttributes	XGetWindowAttributes
-GrabButton	XGrabButton
-GrabKey	XGrabKey
-GrabKeyboard	XGrabKeyboard
-GrabPointer	XGrabPointer
-GrabServer	XGrabServer
-ImageText8	XDrawImageString
-ImageText16	XDrawImageString16
-InstallColormap	XInstallColormap
-InternAtom	XGetWMColormapWindows
-	XGetWMProtocols
-	XIconifyWindow
-	XInternAtom
-	XSetWMColormapWindows
-	XSetWMProtocols
-KillClient	XKillClient
-ListExtensions	XListExtensions
-ListFonts	XListFonts
-ListFontsWithInfo	XListFontsWithInfo
-ListHosts	XListHosts
-ListInstalledColormaps	XListInstalledColormaps
-ListProperties	XListProperties
-LookupColor	XLookupColor
-	XParseColor
-MapSubwindows	XMapSubwindows
-MapWindow	XMapRaised
-	XMapWindow
-NoOperation	XNoOp
-OpenFont	XLoadFont
-	XLoadQueryFont
-PolyArc	XDrawArc
-	XDrawArcs
-PolyFillArc	XFillArc
-	XFillArcs
-PolyFillRectangle	XFillRectangle
-	XFillRectangles
-PolyLine	XDrawLines
-PolyPoint	XDrawPoint
-	XDrawPoints
-PolyRectangle	XDrawRectangle
-	XDrawRectangles
-PolySegment	XDrawLine
-	XDrawSegments
-PolyText8	XDrawString
-	XDrawText
-PolyText16	XDrawString16
-	XDrawText16
-PutImage	XPutImage
-	XCreateBitmapFromData
-	XCreatePixmapFromData
-	XReadBitmapFile
-QueryBestSize	XQueryBestCursor
-	XQueryBestSize
-	XQueryBestStipple
-	XQueryBestTile
-QueryColors	XQueryColor
-	XQueryColors
-QueryExtension	XInitExtension
-	XQueryExtension
-QueryFont	XLoadQueryFont
-	XQueryFont
-QueryKeymap	XQueryKeymap
-QueryPointer	XQueryPointer
-QueryTextExtents	XQueryTextExtents
-	XQueryTextExtents16
-QueryTree	XQueryTree
-RecolorCursor	XRecolorCursor
-ReparentWindow	XReparentWindow
-RotateProperties	XRotateBuffers
-	XRotateWindowProperties
-SendEvent	XIconifyWindow
-	XReconfigureWMWindow
-	XSendEvent
-	XWithdrawWindow
-SetAccessControl	XDisableAccessControl
-	XEnableAccessControl
-	XSetAccessControl
-SetClipRectangles	XSetClipRectangles
-SetCloseDownMode	XSetCloseDownMode
-SetDashes	XSetDashes
-SetFontPath	XSetFontPath
-SetInputFocus	XSetInputFocus
-SetModifierMapping	XSetModifierMapping
-SetPointerMapping	XSetPointerMapping
-SetScreenSaver	XGetScreenSaver
-	XSetScreenSaver
-SetSelectionOwner	XSetSelectionOwner
-StoreColors	XStoreColor
-	XStoreColors
-StoreNamedColor	XStoreNamedColor
-TranslateCoordinates	XTranslateCoordinates
-UngrabButton	XUngrabButton
-UngrabKey	XUngrabKey
-UngrabKeyboard	XUngrabKeyboard
-UngrabPointer	XUngrabPointer
-UngrabServer	XUngrabServer
-UninstallColormap	XUninstallColormap
-UnmapSubwindows	XUnmapSubWindows
-UnmapWindow	XUnmapWindow
-	XWithdrawWindow
-WarpPointer	XWarpPointer
-.TE
-.bp
diff --git a/libX11/specs/libX11/AppA.xml b/libX11/specs/libX11/AppA.xml
new file mode 100644
index 000000000..8c71b269d
--- /dev/null
+++ b/libX11/specs/libX11/AppA.xml
@@ -0,0 +1,540 @@
+<appendix id="xlib_functions_and_protocol_requests">

+<title>Xlib Functions and Protocol Requests</title>

+<para>

+This appendix provides two tables that relate to Xlib functions 

+and the X protocol.

+The following table lists each Xlib function (in alphabetical order)

+and the corresponding protocol request that it generates.

+</para>

+<literallayout class="monospaced">

+--------------------------------------------------------------------------

+Xlib Function                                                 Protocol Request

+--------------------------------------------------------------------------

+XActivateScreenSaver                 ForceScreenSaver

+XAddHost                             ChangeHosts

+XAddHosts                            ChangeHosts

+XAddToSaveSet                        ChangeSaveSet

+XAllocColor                          AllocColor

+XAllocColorCells                     AllocColorCells

+XAllocColorPlanes                    AllocColorPlanes

+XAllocNamedColor                     AllocNamedColor

+XAllowEvents                         AllowEvents

+XAutoRepeatOff                       ChangeKeyboardControl

+XAutoRepeatOn                        ChangeKeyboardControl

+XBell                                Bell

+XChangeActivePointerGrab             ChangeActivePointerGrab

+XChangeGC                            ChangeGC

+XChangeKeyboardControl               ChangeKeyboardControl

+XChangeKeyboardMapping               ChangeKeyboardMapping

+XChangePointerControl                ChangePointerControl

+XChangeProperty                      ChangeProperty

+XChangeSaveSet                       ChangeSaveSet

+XChangeWindowAttributes              ChangeWindowAttributes

+XCirculateSubwindows                 CirculateWindow

+XCirculateSubwindowsDown             CirculateWindow

+XCirculateSubwindowsUp               CirculateWindow

+XClearArea                           ClearArea

+XClearWindow                         ClearArea

+XConfigureWindow                     ConfigureWindow

+XConvertSelection                    ConvertSelection

+XCopyArea                            CopyArea

+XCopyColormapAndFree                 CopyColormapAndFree

+XCopyGC                              CopyGC

+XCopyPlane                           CopyPlane

+XCreateBitmapFromData                CreateGC

+                                     CreatePixmap

+                                     FreeGC

+                                     PutImage

+XCreateColormap                      CreateColormap

+XCreateFontCursor                    CreateGlyphCursor

+XCreateGC                            CreateGC

+XCreateGlyphCursor                   CreateGlyphCursor

+XCreatePixmap                        CreatePixmap

+XCreatePixmapCursor                  CreateCursor

+XCreatePixmapFromData                CreateGC

+                                     CreatePixmap

+                                     FreeGC

+                                     PutImage

+XCreateSimpleWindow                  CreateWindow

+XCreateWindow                        CreateWindow

+XDefineCursor                        ChangeWindowAttributes

+XDeleteProperty                      DeleteProperty

+XDestroySubwindows                   DestroySubwindows

+XDestroyWindow                       DestroyWindow

+XDisableAccessControl                SetAccessControl

+XDrawArc                             PolyArc

+XDrawArcs                            PolyArc

+XDrawImageString                     ImageText8

+XDrawImageString16                   ImageText16

+XDrawLine                            PolySegment

+XDrawLines                           PolyLine

+XDrawPoint                           PolyPoint 

+XDrawPoints                          PolyPoint

+XDrawRectangle                       PolyRectangle

+XDrawRectangles                      PolyRectangle

+XDrawSegments                        PolySegment

+XDrawString                          PolyText8

+XDrawString16                        PolyText16

+XDrawText                            PolyText8

+XDrawText16                          PolyText16

+XEnableAccessControl                 SetAccessControl

+XFetchBytes                          GetProperty

+XFetchName                           GetProperty

+XFillArc                             PolyFillArc

+XFillArcs                            PolyFillArc

+XFillPolygon                         FillPoly

+XFillRectangle                       PolyFillRectangle

+XFillRectangles                      PolyFillRectangle

+XForceScreenSaver                    ForceScreenSaver

+XFreeColormap                        FreeColormap

+XFreeColors                          FreeColors

+XFreeCursor                          FreeCursor

+XFreeFont                            CloseFont

+XFreeGC                              FreeGC

+XFreePixmap                          FreePixmap

+XGetAtomName                         GetAtomName

+XGetClassHint                        GetProperty

+XGetFontPath                         GetFontPath

+XGetGeometry                         GetGeometry

+XGetIconName                         GetProperty

+XGetIconSizes                        GetProperty

+XGetImage                            GetImage

+XGetInputFocus                       GetInputFocus

+XGetKeyboardControl                  GetKeyboardControl

+XGetKeyboardMapping                  GetKeyboardMapping

+XGetModifierMapping                  GetModifierMapping

+XGetMotionEvents                     GetMotionEvents

+XGetNormalHints                      GetProperty

+XGetPointerControl                   GetPointerControl

+XGetPointerMapping                   GetPointerMapping

+XGetRGBColormaps                     GetProperty

+XGetScreenSaver                      GetScreenSaver

+XGetSelectionOwner                   GetSelectionOwner

+XGetSizeHints                        GetProperty

+XGetTextProperty                     GetProperty

+XGetTransientForHint                 GetProperty

+XGetWMClientMachine                  GetProperty

+XGetWMColormapWindows                GetProperty

+                                     InternAtom

+XGetWMHints                          GetProperty

+XGetWMIconName                       GetProperty

+XGetWMName                           GetProperty

+XGetWMNormalHints                    GetProperty

+XGetWMProtocols                      GetProperty

+                                     InternAtom

+XGetWMSizeHints                      GetProperty

+XGetWindowAttributes                 GetWindowAttributes

+                                     GetGeometry

+XGetWindowProperty                   GetProperty

+XGetZoomHints                        GetProperty

+XGrabButton                          GrabButton

+XGrabKey                             GrabKey

+XGrabKeyboard                        GrabKeyboard

+XGrabPointer                         GrabPointer

+XGrabServer                          GrabServer

+XIconifyWindow                       InternAtom

+                                     SendEvent

+XInitExtension                       QueryExtension

+XInstallColormap                     InstallColormap

+XInternAtom                          InternAtom

+XKillClient                          KillClient

+XListExtensions                      ListExtensions

+XListFonts                           ListFonts

+XListFontsWithInfo                   ListFontsWithInfo

+XListHosts                           ListHosts

+XListInstalledColormaps              ListInstalledColormaps

+XListProperties                      ListProperties

+XLoadFont                            OpenFont

+XLoadQueryFont                       OpenFont

+                                     QueryFont

+XLookupColor                         LookupColor

+XLowerWindow                         ConfigureWindow

+XMapRaised                           ConfigureWindow

+                                     MapWindow

+XMapSubwindows                       MapSubwindows

+XMapWindow                           MapWindow

+XMoveResizeWindow                    ConfigureWindow

+XMoveWindow                          ConfigureWindow

+XNoOp                                NoOperation

+XOpenDisplay                         CreateGC

+XParseColor                          LookupColor

+XPutImage                            PutImage

+XQueryBestCursor                     QueryBestSize

+XQueryBestSize                       QueryBestSize

+XQueryBestStipple                    QueryBestSize

+XQueryBestTile                       QueryBestSize

+XQueryColor                          QueryColors 

+XQueryColors                         QueryColors

+XQueryExtension                      QueryExtension

+XQueryFont                           QueryFont

+XQueryKeymap                         QueryKeymap

+XQueryPointer                        QueryPointer

+XQueryTextExtents                    QueryTextExtents

+XQueryTextExtents16                  QueryTextExtents

+XQueryTree                           QueryTree

+XRaiseWindow                         ConfigureWindow

+XReadBitmapFile                      CreateGC

+                                     CreatePixmap

+                                     FreeGC

+                                     PutImage

+XRecolorCursor                       RecolorCursor

+XReconfigureWMWindow                 ConfigureWindow

+                                     SendEvent

+XRemoveFromSaveSet                   ChangeSaveSet

+XRemoveHost                          ChangeHosts

+XRemoveHosts                         ChangeHosts

+XReparentWindow                      ReparentWindow

+XResetScreenSaver                    ForceScreenSaver

+XResizeWindow                        ConfigureWindow 

+XRestackWindows                      ConfigureWindow

+XRotateBuffers                       RotateProperties

+XRotateWindowProperties              RotateProperties

+XSelectInput                         ChangeWindowAttributes

+XSendEvent                           SendEvent

+XSetAccessControl                    SetAccessControl

+XSetArcMode                          ChangeGC

+XSetBackground                       ChangeGC 

+XSetClassHint                        ChangeProperty

+XSetClipMask                         ChangeGC

+XSetClipOrigin                       ChangeGC

+XSetClipRectangles                   SetClipRectangles

+XSetCloseDownMode                    SetCloseDownMode

+XSetCommand                          ChangeProperty

+XSetDashes                           SetDashes

+XSetFillRule                         ChangeGC

+XSetFillStyle                        ChangeGC

+XSetFont                             ChangeGC 

+XSetFontPath                         SetFontPath

+XSetForeground                       ChangeGC 

+XSetFunction                         ChangeGC 

+XSetGraphicsExposures                ChangeGC

+XSetIconName                         ChangeProperty

+XSetIconSizes                        ChangeProperty

+XSetInputFocus                       SetInputFocus

+XSetLineAttributes                   ChangeGC

+XSetModifierMapping                  SetModifierMapping

+XSetNormalHints                      ChangeProperty

+XSetPlaneMask                        ChangeGC 

+XSetPointerMapping                   SetPointerMapping

+XSetRGBColormaps                     ChangeProperty

+XSetScreenSaver                      SetScreenSaver

+XSetSelectionOwner                   SetSelectionOwner

+XSetSizeHints                        ChangeProperty

+XSetStandardProperties               ChangeProperty

+XSetState                            ChangeGC

+XSetStipple                          ChangeGC

+XSetSubwindowMode                    ChangeGC

+XSetTextProperty                     ChangeProperty

+XSetTile                             ChangeGC

+XSetTransientForHint                 ChangeProperty

+XSetTSOrigin                         ChangeGC

+XSetWMClientMachine                  ChangeProperty

+XSetWMColormapWindows                ChangeProperty

+                                     InternAtom

+XSetWMHints                          ChangeProperty

+XSetWMIconName                       ChangeProperty

+XSetWMName                           ChangeProperty

+XSetWMNormalHints                    ChangeProperty

+XSetWMProperties                     ChangeProperty

+XSetWMProtocols                      ChangeProperty

+                                     InternAtom

+XSetWMSizeHints                      ChangeProperty

+XSetWindowBackground                 ChangeWindowAttributes

+XSetWindowBackgroundPixmap           ChangeWindowAttributes

+XSetWindowBorder                     ChangeWindowAttributes

+XSetWindowBorderPixmap               ChangeWindowAttributes

+XSetWindowBorderWidth                ConfigureWindow

+XSetWindowColormap                   ChangeWindowAttributes

+XSetZoomHints                        ChangeProperty

+XStoreBuffer                         ChangeProperty

+XStoreBytes                          ChangeProperty

+XStoreColor                          StoreColors 

+XStoreColors                         StoreColors

+XStoreName                           ChangeProperty

+XStoreNamedColor                     StoreNamedColor

+XSync                                GetInputFocus

+XSynchronize                         GetInputFocus

+XTranslateCoordinates                TranslateCoordinates

+XUndefineCursor                      ChangeWindowAttributes

+XUngrabButton                        UngrabButton

+XUngrabKey                           UngrabKey

+XUngrabKeyboard                      UngrabKeyboard

+XUngrabPointer                       UngrabPointer

+XUngrabServer                        UngrabServer

+XUninstallColormap                   UninstallColormap

+XUnloadFont                          CloseFont

+XUnmapSubwindows                     UnmapSubwindows

+XUnmapWindow                         UnmapWindow

+XWarpPointer                         WarpPointer

+XWithdrawWindow                      SendEvent

+                                     UnmapWindow

+</literallayout>

+<para>

+The following table lists each X protocol request (in alphabetical

+order) and the Xlib functions that reference it.

+</para>

+<literallayout class="monospaced">

+--------------------------------------------------------------------------

+Protocol Request                     Xlib Function

+--------------------------------------------------------------------------

+AllocColor                           XAllocColor

+AllocColorCells                      XAllocColorCells

+AllocColorPlanes                     XAllocColorPlanes

+AllocNamedColor                      XAllocNamedColor

+AllowEvents                          XAllowEvents

+Bell                                 XBell

+ChangeActivePointerGrab              XChangeActivePointerGrab

+ChangeGC                             XChangeGC

+                                     XSetArcMode

+                                     XSetBackground

+                                     XSetClipMask

+                                     XSetClipOrigin

+                                     XSetFillRule

+                                     XSetFillStyle

+                                     XSetFont

+                                     XSetForeground

+                                     XSetFunction

+                                     XSetGraphicsExposures

+                                     XSetLineAttributes

+                                     XSetPlaneMask

+                                     XSetState

+                                     XSetStipple

+                                     XSetSubwindowMode

+                                     XSetTile

+                                     XSetTSOrigin

+ChangeHosts                          XAddHost

+                                     XAddHosts

+                                     XRemoveHost

+                                     XRemoveHosts

+ChangeKeyboardControl                XAutoRepeatOff

+                                     XAutoRepeatOn

+                                     XChangeKeyboardControl

+ChangeKeyboardMapping                XChangeKeyboardMapping

+ChangePointerControl                 XChangePointerControl

+ChangeProperty                       XChangeProperty

+                                     XSetClassHint

+                                     XSetCommand

+                                     XSetIconName

+                                     XSetIconSizes

+                                     XSetNormalHints

+                                     XSetRGBColormaps

+                                     XSetSizeHints

+                                     XSetStandardProperties

+                                     XSetTextProperty

+                                     XSetTransientForHint

+                                     XSetWMClientMachine

+                                     XSetWMColormapWindows

+                                     XSetWMHints

+                                     XSetWMIconName

+                                     XSetWMName

+                                     XSetWMNormalHints

+                                     XSetWMProperties

+                                     XSetWMProtocols

+                                     XSetWMSizeHints

+                                     XSetZoomHints

+                                     XStoreBuffer

+                                     XStoreBytes

+                                     XStoreName

+ChangeSaveSet                        XAddToSaveSet

+                                     XChangeSaveSet

+                                     XRemoveFromSaveSet

+ChangeWindowAttributes               XChangeWindowAttributes

+                                     XDefineCursor

+                                     XSelectInput

+                                     XSetWindowBackground

+                                     XSetWindowBackgroundPixmap

+                                     XSetWindowBorder

+                                     XSetWindowBorderPixmap

+                                     XSetWindowColormap

+                                     XUndefineCursor

+CirculateWindow                      XCirculateSubwindowsDown

+                                     XCirculateSubwindowsUp

+                                     XCirculateSubwindows

+ClearArea                            XClearArea

+                                     XClearWindow

+CloseFont                            XFreeFont

+                                     XUnloadFont

+ConfigureWindow                      XConfigureWindow

+                                     XLowerWindow

+                                     XMapRaised

+                                     XMoveResizeWindow

+                                     XMoveWindow

+                                     XRaiseWindow

+                                     XReconfigureWMWindow

+                                     XResizeWindow

+                                     XRestackWindows

+                                     XSetWindowBorderWidth

+ConvertSelection                     XConvertSelection

+CopyArea                             XCopyArea

+CopyColormapAndFree                  XCopyColormapAndFree

+CopyGC                               XCopyGC

+CopyPlane                            XCopyPlane

+CreateColormap                       XCreateColormap

+CreateCursor                         XCreatePixmapCursor

+CreateGC                             XCreateGC

+                                     XCreateBitmapFromData

+                                     XCreatePixmapFromData

+                                     XOpenDisplay

+                                     XReadBitmapFile

+CreateGlyphCursor                    XCreateFontCursor

+                                     XCreateGlyphCursor

+CreatePixmap                         XCreatePixmap

+                                     XCreateBitmapFromData

+                                     XCreatePixmapFromData

+                                     XReadBitmapFile

+CreateWindow                         XCreateSimpleWindow

+                                     XCreateWindow

+DeleteProperty                       XDeleteProperty

+DestroySubwindows                    XDestroySubwindows

+DestroyWindow                        XDestroyWindow

+FillPoly                             XFillPolygon

+ForceScreenSaver                     XActivateScreenSaver

+                                     XForceScreenSaver

+                                     XResetScreenSaver

+FreeColormap                         XFreeColormap

+FreeColors                           XFreeColors

+FreeCursor                           XFreeCursor

+FreeGC                               XFreeGC

+                                     XCreateBitmapFromData

+                                     XCreatePixmapFromData

+                                     XReadBitmapFile

+FreePixmap                           XFreePixmap

+GetAtomName                          XGetAtomName

+GetFontPath                          XGetFontPath

+GetGeometry                          XGetGeometry

+                                     XGetWindowAttributes

+GetImage                             XGetImage

+GetInputFocus                        XGetInputFocus

+                                     XSync

+                                     XSynchronize

+GetKeyboardControl                   XGetKeyboardControl

+GetKeyboardMapping                   XGetKeyboardMapping

+GetModifierMapping                   XGetModifierMapping

+GetMotionEvents                      XGetMotionEvents

+GetPointerControl                    XGetPointerControl

+GetPointerMapping                    XGetPointerMapping

+GetProperty                          XFetchBytes

+                                     XFetchName

+                                     XGetClassHint

+                                     XGetIconName

+                                     XGetIconSizes

+                                     XGetNormalHints

+                                     XGetRGBColormaps

+                                     XGetSizeHints

+                                     XGetTextProperty

+                                     XGetTransientForHint

+                                     XGetWMClientMachine

+                                     XGetWMColormapWindows

+                                     XGetWMHints

+                                     XGetWMIconName

+                                     XGetWMName

+                                     XGetWMNormalHints

+                                     XGetWMProtocols

+                                     XGetWMSizeHints

+                                     XGetWindowProperty

+                                     XGetZoomHints

+GetSelectionOwner                    XGetSelectionOwner

+GetWindowAttributes                  XGetWindowAttributes

+GrabButton                           XGrabButton

+GrabKey                              XGrabKey

+GrabKeyboard                         XGrabKeyboard

+GrabPointer                          XGrabPointer

+GrabServer                           XGrabServer

+ImageText8                           XDrawImageString

+ImageText16                          XDrawImageString16

+InstallColormap                      XInstallColormap

+InternAtom                           XGetWMColormapWindows

+                                     XGetWMProtocols

+                                     XIconifyWindow

+                                     XInternAtom

+                                     XSetWMColormapWindows

+                                     XSetWMProtocols

+KillClient                           XKillClient

+ListExtensions                       XListExtensions

+ListFonts                            XListFonts

+ListFontsWithInfo                    XListFontsWithInfo

+ListHosts                            XListHosts

+ListInstalledColormaps               XListInstalledColormaps

+ListProperties                       XListProperties

+LookupColor                          XLookupColor

+                                     XParseColor

+MapSubwindows                        XMapSubwindows

+MapWindow                            XMapRaised

+                                     XMapWindow

+NoOperation                          XNoOp

+OpenFont                             XLoadFont

+                                     XLoadQueryFont

+PolyArc                              XDrawArc

+                                     XDrawArcs

+PolyFillArc                          XFillArc

+                                     XFillArcs

+PolyFillRectangle                    XFillRectangle

+                                     XFillRectangles

+PolyLine                             XDrawLines

+PolyPoint                            XDrawPoint

+                                     XDrawPoints

+PolyRectangle                        XDrawRectangle

+                                     XDrawRectangles

+PolySegment                          XDrawLine

+                                     XDrawSegments

+PolyText8                            XDrawString

+                                     XDrawText

+PolyText16                           XDrawString16

+                                     XDrawText16

+PutImage                             XPutImage

+                                     XCreateBitmapFromData

+                                     XCreatePixmapFromData

+                                     XReadBitmapFile

+QueryBestSize                        XQueryBestCursor

+                                     XQueryBestSize

+                                     XQueryBestStipple

+                                     XQueryBestTile

+QueryColors                          XQueryColor

+                                     XQueryColors

+QueryExtension                       XInitExtension

+                                     XQueryExtension

+QueryFont                            XLoadQueryFont

+                                     XQueryFont

+QueryKeymap                          XQueryKeymap

+QueryPointer                         XQueryPointer

+QueryTextExtents                     XQueryTextExtents

+                                     XQueryTextExtents16

+QueryTree                            XQueryTree

+RecolorCursor                        XRecolorCursor

+ReparentWindow                       XReparentWindow

+RotateProperties                     XRotateBuffers

+                                     XRotateWindowProperties

+SendEvent                            XIconifyWindow

+                                     XReconfigureWMWindow

+                                     XSendEvent

+                                     XWithdrawWindow

+SetAccessControl                     XDisableAccessControl

+                                     XEnableAccessControl

+                                     XSetAccessControl

+SetClipRectangles                    XSetClipRectangles

+SetCloseDownMode                     XSetCloseDownMode

+SetDashes                            XSetDashes

+SetFontPath                          XSetFontPath

+SetInputFocus                        XSetInputFocus

+SetModifierMapping                   XSetModifierMapping

+SetPointerMapping                    XSetPointerMapping

+SetScreenSaver                       XGetScreenSaver

+                                     XSetScreenSaver

+SetSelectionOwner                    XSetSelectionOwner

+StoreColors                          XStoreColor

+                                     XStoreColors

+StoreNamedColor                      XStoreNamedColor

+TranslateCoordinates                 XTranslateCoordinates

+UngrabButton                         XUngrabButton

+UngrabKey                            XUngrabKey

+UngrabKeyboard                       XUngrabKeyboard

+UngrabPointer                        XUngrabPointer

+UngrabServer                         XUngrabServer

+UninstallColormap                    XUninstallColormap

+UnmapSubwindows                      XUnmapSubWindows

+UnmapWindow                          XUnmapWindow

+                                     XWithdrawWindow

+WarpPointer                          XWarpPointer

+

+</literallayout>

+</appendix>

diff --git a/libX11/specs/libX11/AppB b/libX11/specs/libX11/AppB
deleted file mode 100644
index 2e57ede86..000000000
--- a/libX11/specs/libX11/AppB
+++ /dev/null
@@ -1,101 +0,0 @@
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-.\" OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" Except as contained in this notice, the name of the X Consortium shall
-.\" not be used in advertising or otherwise to promote the sale, use or
-.\" other dealings in this Software without prior written authorization
-.\" from the X Consortium.
-.\"
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
-.\" Digital Equipment Corporation
-.\"
-.\" Portions Copyright \(co 1990, 1991 by
-.\" Tektronix, Inc.
-.\"
-.\" Permission to use, copy, modify and distribute this documentation for
-.\" any purpose and without fee is hereby granted, provided that the above
-.\" copyright notice appears in all copies and that both that copyright notice
-.\" and this permission notice appear in all copies, and that the names of
-.\" Digital and Tektronix not be used in in advertising or publicity pertaining
-.\" to this documentation without specific, written prior permission.
-.\" Digital and Tektronix makes no representations about the suitability
-.\" of this documentation for any purpose.
-.\" It is provided ``as is'' without express or implied warranty.
-.\" 
-\&
-.sp 1
-.ce 3
-\s+1\fBAppendix B\fP\s-1
-
-\s+1\fBX Font Cursors\fP\s-1
-.sp 2
-.na
-.LP
-.XS
-Appendix B:  X Font Cursors
-.XE
-The following are the available cursors that can be used with
-.PN XCreateFontCursor .
-.LP
-.Ds 0
-.TA 3i
-.ta 3i
-#define XC_X_cursor 0	#define XC_ll_angle 76
-#define XC_arrow 2	#define XC_lr_angle 78
-#define XC_based_arrow_down 4	#define XC_man 80
-#define XC_based_arrow_up 6	#define XC_middlebutton 82
-#define XC_boat 8	#define XC_mouse 84
-#define XC_bogosity 10	#define XC_pencil 86
-#define XC_bottom_left_corner 12	#define XC_pirate 88
-#define XC_bottom_right_corner 14	#define XC_plus 90
-#define XC_bottom_side 16	#define XC_question_arrow 92
-#define XC_bottom_tee 18 	#define XC_right_ptr 94
-#define XC_box_spiral 20	#define XC_right_side 96
-#define XC_center_ptr 22	#define XC_right_tee 98
-#define XC_circle 24	#define XC_rightbutton 100
-#define XC_clock 26	#define XC_rtl_logo 102
-#define XC_coffee_mug 28	#define XC_sailboat 104
-#define XC_cross 30	#define XC_sb_down_arrow 106
-#define XC_cross_reverse 32	#define XC_sb_h_double_arrow 108
-#define XC_crosshair 34	#define XC_sb_left_arrow 110
-#define XC_diamond_cross 36	#define XC_sb_right_arrow 112
-#define XC_dot 38	#define XC_sb_up_arrow 114
-#define XC_dot_box_mask 40	#define XC_sb_v_double_arrow 116
-#define XC_double_arrow 42	#define XC_shuttle 118
-#define XC_draft_large 44	#define XC_sizing 120
-#define XC_draft_small 46	#define XC_spider 122
-#define XC_draped_box 48	#define XC_spraycan 124
-#define XC_exchange 50	#define XC_star 126
-#define XC_fleur 52	#define XC_target 128
-#define XC_gobbler 54	#define XC_tcross 130
-#define XC_gumby 56	#define XC_top_left_arrow 132
-#define XC_hand1 58	#define XC_top_left_corner 134
-#define XC_hand2 60	#define XC_top_right_corner 136
-#define XC_heart 62	#define XC_top_side 138
-#define XC_icon 64	#define XC_top_tee 140
-#define XC_iron_cross 66	#define XC_trek 142
-#define XC_left_ptr 68	#define XC_ul_angle 144
-#define XC_left_side 70	#define XC_umbrella 146
-#define XC_left_tee 72	#define XC_ur_angle 148
-#define XC_leftbutton 74	#define XC_watch 150
-	#define XC_xterm 152
-.De
-.bp
diff --git a/libX11/specs/libX11/AppB.xml b/libX11/specs/libX11/AppB.xml
new file mode 100644
index 000000000..8d9886aac
--- /dev/null
+++ b/libX11/specs/libX11/AppB.xml
@@ -0,0 +1,49 @@
+<appendix id="x_font_cursors">

+<title>X Font Cursors</title>

+<para>

+The following are the available cursors that can be used with

+<function>XCreateFontCursor</function>.

+</para>

+<literallayout class="monospaced">

+#define XC_X_cursor 0                     #define XC_ll_angle 76

+#define XC_arrow 2                        #define XC_lr_angle 78

+#define XC_based_arrow_down 4             #define XC_man 80

+#define XC_based_arrow_up 6               #define XC_middlebutton 82

+#define XC_boat 8                         #define XC_mouse 84

+#define XC_bogosity 10                    #define XC_pencil 86

+#define XC_bottom_left_corner 12          #define XC_pirate 88

+#define XC_bottom_right_corner 14         #define XC_plus 90

+#define XC_bottom_side 16                 #define XC_question_arrow 92

+#define XC_bottom_tee 18                  #define XC_right_ptr 94

+#define XC_box_spiral 20                  #define XC_right_side 96

+#define XC_center_ptr 22                  #define XC_right_tee 98

+#define XC_circle 24                      #define XC_rightbutton 100

+#define XC_clock 26                       #define XC_rtl_logo 102

+#define XC_coffee_mug 28                  #define XC_sailboat 104

+#define XC_cross 30                       #define XC_sb_down_arrow 106

+#define XC_cross_reverse 32               #define XC_sb_h_double_arrow 108

+#define XC_crosshair 34                   #define XC_sb_left_arrow 110

+#define XC_diamond_cross 36               #define XC_sb_right_arrow 112

+#define XC_dot 38                         #define XC_sb_up_arrow 114

+#define XC_dot_box_mask 40                #define XC_sb_v_double_arrow 116

+#define XC_double_arrow 42                #define XC_shuttle 118

+#define XC_draft_large 44                 #define XC_sizing 120

+#define XC_draft_small 46                 #define XC_spider 122

+#define XC_draped_box 48                  #define XC_spraycan 124

+#define XC_exchange 50                    #define XC_star 126

+#define XC_fleur 52                       #define XC_target 128

+#define XC_gobbler 54                     #define XC_tcross 130

+#define XC_gumby 56                       #define XC_top_left_arrow 132

+#define XC_hand1 58                       #define XC_top_left_corner 134

+#define XC_hand2 60                       #define XC_top_right_corner 136

+#define XC_heart 62                       #define XC_top_side 138

+#define XC_icon 64                        #define XC_top_tee 140

+#define XC_iron_cross 66                  #define XC_trek 142

+#define XC_left_ptr 68                    #define XC_ul_angle 144

+#define XC_left_side 70                   #define XC_umbrella 146

+#define XC_left_tee 72                    #define XC_ur_angle 148

+#define XC_leftbutton 74                  #define XC_watch 150

+                                          #define XC_xterm 152

+</literallayout>

+</appendix>

+

diff --git a/libX11/specs/libX11/AppC b/libX11/specs/libX11/AppC
deleted file mode 100644
index 43261ba83..000000000
--- a/libX11/specs/libX11/AppC
+++ /dev/null
@@ -1,2230 +0,0 @@
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-.\" OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" Except as contained in this notice, the name of the X Consortium shall
-.\" not be used in advertising or otherwise to promote the sale, use or
-.\" other dealings in this Software without prior written authorization
-.\" from the X Consortium.
-.\"
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
-.\" Digital Equipment Corporation
-.\"
-.\" Portions Copyright \(co 1990, 1991 by
-.\" Tektronix, Inc.
-.\"
-.\" Permission to use, copy, modify and distribute this documentation for
-.\" any purpose and without fee is hereby granted, provided that the above
-.\" copyright notice appears in all copies and that both that copyright notice
-.\" and this permission notice appear in all copies, and that the names of
-.\" Digital and Tektronix not be used in in advertising or publicity pertaining
-.\" to this documentation without specific, written prior permission.
-.\" Digital and Tektronix makes no representations about the suitability
-.\" of this documentation for any purpose.
-.\" It is provided ``as is'' without express or implied warranty.
-.\" 
-\&
-.sp 1
-.ce 3
-\s+1\fBAppendix C\fP\s-1
-
-\s+1\fBExtensions\fP\s-1
-.sp 2
-.na
-.LP
-.XS
-Appendix C: Extensions
-.XE
-Because X can evolve by extensions to the core protocol, 
-it is important that extensions not be perceived as second-class citizens.
-At some point, 
-your favorite extensions may be adopted as additional parts of the 
-X Standard.
-.LP
-Therefore, there should be little to distinguish the use of an extension from 
-that of the core protocol.
-To avoid having to initialize extensions explicitly in application programs, 
-it is also important that extensions perform lazy evaluations,
-automatically initializing themselves when called for the first time.  
-.LP
-This appendix describes techniques for writing extensions to Xlib that will
-run at essentially the same performance as the core protocol requests.
-.NT
-It is expected that a given extension to X consists of multiple
-requests.
-Defining 10 new features as 10 separate extensions is a bad practice.
-Rather, they should be packaged into a single extension
-and should use minor opcodes to distinguish the requests.
-.NE
-.LP
-The symbols and macros used for writing stubs to Xlib are listed in
-.hN X11/Xlibint.h .
-.SH
-Basic Protocol Support Routines
-.LP
-The basic protocol requests for extensions are 
-.PN XQueryExtension
-and
-.PN XListExtensions .
-.IN "XQueryExtension" "" "@DEF@"
-.sM
-.FD 0
-Bool XQueryExtension(\^\fIdisplay\fP, \fIname\fP, \fImajor_opcode_return\fP, \
-\fIfirst_event_return\fP, \fIfirst_error_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      char *\fIname;\fP\^
-.br
-      int *\fImajor_opcode_return\fP\^;
-.br
-      int *\fIfirst_event_return\fP\^;
-.br
-      int *\fIfirst_error_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIname\fP 1i
-Specifies the extension name.
-.IP \fImajor_opcode_return\fP 1i
-Returns the major opcode.
-.IP \fIfirst_event_return\fP 1i
-Returns the first event code, if any.
-.IP \fIfirst_error_return\fP 1i
-Returns the first error code, if any.
-.LP
-.eM
-The
-.PN XQueryExtension
-function determines if the named extension is present.  
-If the extension is not present,
-.PN XQueryExtension
-returns
-.PN False ;
-otherwise, it returns
-.PN True .
-If the extension is present,
-.PN XQueryExtension
-returns the major opcode for the extension to major_opcode_return;
-otherwise,
-it returns zero.
-Any minor opcode and the request formats are specific to the
-extension.  
-If the extension involves additional event types, 
-.PN XQueryExtension
-returns the base event type code to first_event_return;
-otherwise, 
-it returns zero.  
-The format of the events is specific to the extension.  
-If the extension involves additional error codes, 
-.PN XQueryExtension
-returns the base error code to first_error_return;
-otherwise, 
-it returns zero.  
-The format of additional data in the errors is specific to the extension.
-.LP
-If the extension name is not in the Host Portable Character Encoding
-the result is implementation-dependent.
-Uppercase and lowercase matter;
-the strings ``thing'', ``Thing'', and ``thinG'' 
-are all considered different names.
-.IN "XListExtensions" "" "@DEF@"
-.sM
-.FD 0
-char **XListExtensions(\^\fIdisplay\fP, \fInextensions_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int *\fInextensions_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fInextensions_return\fP 1i
-Returns the number of extensions listed.
-.LP
-.eM
-The
-.PN XListExtensions   
-function returns a list of all extensions supported by the server.
-If the data returned by the server is in the Latin Portable Character Encoding,
-then the returned strings are in the Host Portable Character Encoding.
-Otherwise, the result is implementation-dependent.
-.IN "XFreeExtensionList" "" "@DEF@"
-.sM
-.FD 0
-XFreeExtensionList(\^\fIlist\fP\^)
-.br
-      char **\fIlist\fP\^;
-.FN
-.IP \fIlist\fP 1i
-Specifies the list of extension names.
-.LP
-.eM
-The
-.PN XFreeExtensionList
-function frees the memory allocated by 
-.PN XListExtensions .
-.SH
-Hooking into Xlib 
-.LP
-These functions allow you to hook into the library.  
-They are not normally used by application programmers but are used 
-by people who need to extend the core X protocol and
-the X library interface.
-The functions, which generate protocol requests for X, are typically
-called stubs.
-.LP
-In extensions, stubs first should check to see if they have initialized 
-themselves on a connection.
-If they have not, they then should call 
-.PN XInitExtension 
-to attempt to initialize themselves on the connection.
-.LP
-If the extension needs to be informed of GC/font allocation or
-deallocation or if the extension defines new event types, 
-the functions described here allow the extension to be 
-called when these events occur.
-.LP
-The
-.PN XExtCodes
-structure returns the information from 
-.PN XInitExtension 
-and is defined in
-.hN X11/Xlib.h : 
-.LP
-.IN "XExtCodes" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct _XExtCodes {	/* public to extension, cannot be changed */
-	int extension;	/* extension number */
-	int major_opcode;	/* major op-code assigned by server */
-	int first_event;	/* first event number for the extension */
-	int first_error;	/* first error number for the extension */
-} XExtCodes;
-.De
-.LP
-.eM
-.IN "XInitExtension" "" "@DEF@"
-.sM
-.FD 0
-XExtCodes *XInitExtension(\^\fIdisplay\fP, \fIname\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      char *\fIname\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIname\fP 1i
-Specifies the extension name.
-.LP
-.eM
-The
-.PN XInitExtension
-function determines if the named extension exists. 
-Then, it allocates storage for maintaining the 
-information about the extension on the connection, 
-chains this onto the extension list for the connection,
-and returns the information the stub implementor will need to access
-the extension.
-If the extension does not exist,
-.PN XInitExtension
-returns NULL.
-.LP
-If the extension name is not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-Uppercase and lowercase matter;
-the strings ``thing'', ``Thing'', and ``thinG'' 
-are all considered different names.
-.LP
-The extension number in the 
-.PN XExtCodes 
-structure is
-needed in the other calls that follow.  
-This extension number is unique only to a single connection.
-.LP
-.IN "XAddExtension" "" "@DEF@"
-.sM
-.FD 0
-XExtCodes *XAddExtension\^(\^\fIdisplay\fP\^)
-.br
-        Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-For local Xlib extensions, the
-.PN XAddExtension
-function allocates the
-.PN XExtCodes
-structure, bumps the extension number count,
-and chains the extension onto the extension list.
-(This permits extensions to Xlib without requiring server extensions.)
-.SH
-Hooks into the Library
-.LP
-These functions allow you to define procedures that are to be
-called when various circumstances occur.
-The procedures include the creation of a new GC for a connection,
-the copying of a GC, the freeing of a GC, the creating and freeing of fonts,
-the conversion of events defined by extensions to and from wire
-format, and the handling of errors.
-.LP
-All of these functions return the previous procedure defined for this
-extension.
-.IN "XESetCloseDisplay" "" "@DEF@"
-.sM
-.FD 0
-int (*XESetCloseDisplay(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIextension\fP\^;
-.br
-      int (\^*\fIproc\fP\^)(\^);
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIextension\fP 1i
-Specifies the extension number.
-.IP \fIproc\fP 1i
-Specifies the procedure to call when the display is closed.
-.LP
-.eM
-The
-.PN XESetCloseDisplay
-function defines a procedure to be called whenever
-.PN XCloseDisplay 
-is called.  
-It returns any previously defined procedure, usually NULL.
-.LP
-When 
-.PN XCloseDisplay 
-is called, 
-your procedure is called 
-with these arguments:
-.LP
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-.R
-(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIcodes\fP\^)
-	Display *\fIdisplay\fP\^;
-	XExtCodes *\fIcodes\fP\^;
-.De
-.LP
-.eM
-.IN "XESetCreateGC" "" "@DEF@"
-.sM
-.FD 0
-int (*XESetCreateGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIextension\fP\^;
-.br
-      int (\^*\fIproc\fP\^)(\^);
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIextension\fP 1i
-Specifies the extension number.
-.IP \fIproc\fP 1i
-Specifies the procedure to call when a GC is closed.
-.LP
-.eM
-The
-.PN XESetCreateGC
-function defines a procedure to be called whenever
-a new GC is created.  
-It returns any previously defined procedure, usually NULL.
-.LP
-When a GC is created, 
-your procedure is called with these arguments:
-.LP
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-.R
-(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIgc\fP, \fIcodes\fP\^)
-	Display *\fIdisplay\fP\^;
-	GC \fIgc\fP\^;
-	XExtCodes *\fIcodes\fP\^;
-.De
-.LP
-.eM
-.IN "XESetCopyGC" "" "@DEF@"
-.sM
-.FD 0
-int (*XESetCopyGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIextension\fP\^;
-.br
-      int (\^*\fIproc\fP\^)(\^);
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIextension\fP 1i
-Specifies the extension number.
-.IP \fIproc\fP 1i
-Specifies the procedure to call when GC components are copied.
-.LP
-.eM
-The
-.PN XESetCopyGC
-function defines a procedure to be called whenever
-a GC is copied.  
-It returns any previously defined procedure, usually NULL.
-.LP
-When a GC is copied, 
-your procedure is called with these arguments:
-.LP
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-.R
-(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIgc\fP, \fIcodes\fP\^)
-	Display *\fIdisplay\fP\^;
-	GC \fIgc\fP\^;
-	XExtCodes *\fIcodes\fP\^;
-.De
-.LP
-.eM
-.IN "XESetFreeGC" "" "@DEF@"
-.sM
-.FD 0
-int (*XESetFreeGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc)\fP\^)(\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIextension\fP\^;
-.br
-      int (\^*\fIproc\fP\^)(\^);
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIextension\fP 1i
-Specifies the extension number.
-.IP \fIproc\fP 1i
-Specifies the procedure to call when a GC is freed.
-.LP
-.eM
-The
-.PN XESetFreeGC
-function defines a procedure to be called whenever
-a GC is freed.  
-It returns any previously defined procedure, usually NULL.
-.LP
-When a GC is freed, 
-your procedure is called with these arguments:
-.LP
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-.R
-(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIgc\fP, \fIcodes\fP\^)
-	Display *\fIdisplay\fP\^;
-	GC \fIgc\fP\^;
-	XExtCodes *\fIcodes\fP\^;
-.De
-.LP
-.eM
-.IN "XESetCreateFont" "" "@DEF@"
-.sM
-.FD 0
-int (*XESetCreateFont(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP))(\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIextension\fP\^;
-.br
-      int (\^*\fIproc\fP\^)(\^);
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIextension\fP 1i
-Specifies the extension number.
-.IP \fIproc\fP 1i
-Specifies the procedure to call when a font is created.
-.LP
-.eM
-The
-.PN XESetCreateFont
-function defines a procedure to be called whenever
-.PN XLoadQueryFont 
-and
-.PN XQueryFont
-are called.  
-It returns any previously defined procedure, usually NULL.
-.LP
-When 
-.PN XLoadQueryFont 
-or
-.PN XQueryFont
-is called, 
-your procedure is called with these arguments:
-.LP
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-.R
-(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIfs\fP, \fIcodes\fP\^)
-	Display *\fIdisplay\fP\^;
-	XFontStruct *\fIfs\fP\^;
-	XExtCodes *\fIcodes\fP\^;
-.De
-.LP
-.eM
-.IN "XESetFreeFont" "" "@DEF@"
-.sM
-.FD 0
-int (*XESetFreeFont(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIextension\fP\^;
-.br
-      int (\^*\fIproc\fP)(\^);
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIextension\fP 1i
-Specifies the extension number.
-.IP \fIproc\fP 1i
-Specifies the procedure to call when a font is freed.
-.LP
-.eM
-The
-.PN XESetFreeFont
-function defines a procedure to be called whenever
-.PN XFreeFont 
-is called.  
-It returns any previously defined procedure, usually NULL.
-.LP
-When 
-.PN XFreeFont 
-is called, your procedure is called with these arguments:
-.LP
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-.R
-(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIfs\fP, \fIcodes\fP\^)
-	Display *\fIdisplay\fP\^;
-	XFontStruct *\fIfs\fP\^;
-	XExtCodes *\fIcodes\fP\^;
-.De
-.LP
-.eM
-The 
-.PN XESetWireToEvent
-and
-.PN XESetEventToWire
-functions allow you to define new events to the library.
-An 
-.PN XEvent
-structure always has a type code (type
-.PN int )
-as the first component.
-This uniquely identifies what kind of event it is.
-The second component is always the serial number (type
-.PN unsigned
-.PN long )
-of the last request processed by the server.
-The third component is always a Boolean (type
-.PN Bool )
-indicating whether the event came from a
-.PN SendEvent
-protocol request.
-The fourth component is always a pointer to the display
-the event was read from.
-The fifth component is always a resource ID of one kind or another,
-usually a window, carefully selected to be useful to toolkit dispatchers.
-The fifth component should always exist, even if
-the event does not have a natural destination;
-if there is no value
-from the protocol to put in this component, initialize it to zero.
-.NT
-There is an implementation limit such that your host event
-structure size cannot be bigger than the size of the
-.PN XEvent 
-union of structures.
-There also is no way to guarantee that more than 24 elements or 96 characters
-in the structure will be fully portable between machines.
-.NE
-.IN "XESetWireToEvent" "" "@DEF@"
-.sM
-.FD 0
-int (*XESetWireToEvent(\^\fIdisplay\fP, \fIevent_number\fP, \fIproc\fP\^))(\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIevent_number\fP\^;
-.br
-      Status (\^*\fIproc\fP\^)(\^);
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIevent_number\fP 1i
-Specifies the event code.
-.IP \fIproc\fP 1i
-Specifies the procedure to call when converting an event.
-.LP
-.eM
-The
-.PN XESetWireToEvent
-function defines a procedure to be called when an event
-needs to be converted from wire format 
-.Pn ( xEvent )
-to host format 
-.Pn ( XEvent ).
-The event number defines which protocol event number to install a
-conversion procedure for.
-.PN XESetWireToEvent
-returns any previously defined procedure.
-.NT
-You can replace a core event conversion function with one
-of your own, although this is not encouraged.
-It would, however, allow you to intercept a core event 
-and modify it before being placed in the queue or otherwise examined.
-.NE
-When Xlib needs to convert an event from wire format to host
-format, your procedure is called with these arguments:
-.LP
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-.R
-Status (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIre\fP, \fIevent\fP\^)
-	Display *\fIdisplay\fP\^;
-	XEvent *\fIre\fP\^;
-	xEvent *\fIevent\fP\^;
-.De
-.LP
-.eM
-Your procedure must return status to indicate if the conversion succeeded.
-The re argument is a pointer to where the host format event should be stored,
-and the event argument is the 32-byte wire event structure.
-In the 
-.PN XEvent 
-structure you are creating, 
-you must fill in the five required members of the event structure.
-You should fill in the type member with the type specified for the 
-.PN xEvent 
-structure.
-You should copy all other members from the 
-.PN xEvent 
-structure (wire format) to the
-.PN XEvent 
-structure (host format).
-Your conversion procedure should return 
-.PN True
-if the event should be placed in the queue or
-.PN False
-if it should not be placed in the queue.
-.LP
-To initialize the serial number component of the event, call
-.PN _XSetLastRequestRead
-with the event and use the return value.
-.LP
-.IN "_XSetLastRequestRead" "" "@DEF@"
-.sM
-.FD 0
-unsigned long _XSetLastRequestRead(\^\fIdisplay\fP, \fIrep\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      xGenericReply *\fIrep\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIrep\fP 1i
-Specifies the wire event structure.
-.LP
-.eM
-The
-.PN _XSetLastRequestRead
-function computes and returns a complete serial number from the partial
-serial number in the event.
-.sp
-.LP
-.IN "XESetEventToWire" "" "@DEF@"
-.sM
-.FD 0
-Status (*XESetEventToWire(\^\fIdisplay\fP, \fIevent_number\fP, \fIproc\fP\^))(\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIevent_number\fP\^;
-.br
-      int (\^*\fIproc\fP\^)(\^);
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIevent_number\fP 1i
-Specifies the event code.
-.IP \fIproc\fP 1i
-Specifies the procedure to call when converting an event.
-.LP
-.eM
-The
-.PN XESetEventToWire
-function defines a procedure to be called when an event
-needs to be converted from host format
-.Pn ( XEvent ) 
-to wire format
-.Pn ( xEvent )
-form.  
-The event number defines which protocol event number to install a
-conversion procedure for.
-.PN XESetEventToWire
-returns any previously defined procedure.
-It returns zero if the conversion fails or nonzero otherwise.
-.NT
-You can replace a core event conversion function with one
-of your own, although this is not encouraged.  
-It would, however, allow you to intercept a core event 
-and modify it before being sent to another client.
-.NE
-When Xlib needs to convert an event from host format to wire format, 
-your procedure is called with these arguments:
-.LP
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-.R
-(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIre\fP, \fIevent\fP\^)
-	Display *\fIdisplay\fP\^;
-	XEvent *\fIre\fP\^;
-	xEvent *\fIevent\fP\^;
-.De
-.LP
-.eM
-The re argument is a pointer to the host format event,
-and the event argument is a pointer to where the 32-byte wire event 
-structure should be stored.
-You should fill in the type with the type from the 
-.PN XEvent 
-structure.
-All other members then should be copied from the host format to the 
-.PN xEvent 
-structure.
-.IN "XESetWireToError" "" "@DEF@"
-.sM
-.FD 0
-Bool (*XESetWireToError(\^\fIdisplay\fP, \fIerror_number\fP, \fIproc\fP\^)(\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIerror_number\fP\^;
-.br
-      Bool (\^*\fIproc\fP\^)(\^);
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIerror_number\fP 1i
-Specifies the error code.
-.IP \fIproc\fP 1i
-Specifies the procedure to call when an error is received.
-.LP
-.eM
-The
-.PN XESetWireToError
-function defines a procedure to be called when an extension
-error needs to be converted from wire format to host format.
-The error number defines which protocol error code to install
-the conversion procedure for.
-.PN XESetWireToError
-returns any previously defined procedure.
-.LP
-Use this function for extension errors that contain additional error values
-beyond those in a core X error, when multiple wire errors must be combined
-into a single Xlib error, or when it is necessary to intercept an
-X error before it is otherwise examined.
-.LP
-When Xlib needs to convert an error from wire format to host format,
-the procedure is called with these arguments:
-.LP
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-.R
-Bool (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIhe\fP, \fIwe\fP\^)
-	Display *\fIdisplay\fP\^;
-	XErrorEvent *\fIhe\fP\^;
-	xError *\fIwe\fP\^;
-.De
-.LP
-.eM
-The he argument is a pointer to where the host format error should be stored.
-The structure pointed at by he is guaranteed to be as large as an
-.PN XEvent
-structure and so can be cast to a type larger than an
-.PN XErrorEvent
-to store additional values.
-If the error is to be completely ignored by Xlib
-(for example, several protocol error structures will be combined into
-one Xlib error),
-then the function should return
-.PN False ;
-otherwise, it should return
-.PN True .
-.IN "XESetError" "" "@DEF@"
-.sM
-.FD 0
-int (*XESetError(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIextension\fP\^;
-.br
-      int (\^*\fIproc\fP\^)(\^);
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIextension\fP 1i
-Specifies the extension number.
-.IP \fIproc\fP 1i
-Specifies the procedure to call when an error is received.
-.LP
-.eM
-Inside Xlib, there are times that you may want to suppress the
-calling of the external error handling when an error occurs.
-This allows status to be returned on a call at the cost of the call
-being synchronous (though most such functions are query operations, in any
-case, and are typically programmed to be synchronous).
-.LP
-When Xlib detects a protocol error in 
-.PN _XReply , 
-it calls your procedure with these arguments:
-.LP
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-.R
-int (*\fIproc\fP\^)(\fIdisplay\fP, \fIerr\fP, \fIcodes\fP, \fIret_code\fP\^)
-	Display *\fIdisplay\fP\^;
-	xError *\fIerr\fP\^;
-	XExtCodes *\fIcodes\fP\^;
-	int *\fIret_code\fP\^;
-.De
-.LP
-.eM
-The err argument is a pointer to the 32-byte wire format error.
-The codes argument is a pointer to the extension codes structure.
-The ret_code argument is the return code you may want 
-.PN _XReply 
-returned to.
-.LP
-If your procedure returns a zero value, 
-the error is not suppressed, and 
-the client's error handler is called.
-(For further information, see section 11.8.2.)
-If your procedure returns nonzero, 
-the error is suppressed, and 
-.PN _XReply 
-returns the value of ret_code.
-.IN "XESetErrorString" "" "@DEF@"
-.sM
-.FD 0
-char  *(*XESetErrorString(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIextension\fP\^;
-.br
-      char *(\^*\fIproc\fP\^)(\^);
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIextension\fP 1i
-Specifies the extension number.
-.IP \fIproc\fP 1i
-Specifies the procedure to call to obtain an error string.
-.LP
-.eM
-The 
-.PN XGetErrorText 
-function returns a string to the user for an error.
-.PN XESetErrorString
-allows you to define a procedure to be called that
-should return a pointer to the error message.
-The following is an example.
-.LP
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-.R
-(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIcode\fP, \fIcodes\fP, \fIbuffer\fP, \fInbytes\fP\^)
-	Display *\fIdisplay\fP\^;
-	int \fIcode\fP\^;
-	XExtCodes *\fIcodes\fP\^;
-	char *\fIbuffer\fP\^;
-	int \fInbytes\fP\^;
-.De
-.LP
-.eM
-Your procedure is called with the error code for every error detected.
-You should copy nbytes of a null-terminated string containing the
-error message into buffer.
-.IN "XESetPrintErrorValues" "" "@DEF@"
-.sM
-.FD 0
-void (*XESetPrintErrorValues(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIextension\fP\^;
-.br
-      void (\^*\fIproc\fP\^)(\^);
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIextension\fP 1i
-Specifies the extension number.
-.IP \fIproc\fP 1i
-Specifies the procedure to call when an error is printed.
-.LP
-.eM
-The
-.PN XESetPrintErrorValues
-function defines a procedure to be called when an extension
-error is printed, to print the error values.
-Use this function for extension errors that contain additional error values
-beyond those in a core X error.
-It returns any previously defined procedure.
-.LP
-When Xlib needs to print an error,
-the procedure is called with these arguments:
-.LP
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-.R
-void (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIev\fP, \fIfp\fP\^)
-	Display *\fIdisplay\fP\^;
-	XErrorEvent *\fIev\fP\^;
-	void *\fIfp\fP\^;
-.De
-.LP
-.eM
-The structure pointed at by ev is guaranteed to be as large as an
-.PN XEvent
-structure and so can be cast to a type larger than an
-.PN XErrorEvent
-to obtain additional values set by using
-.PN XESetWireToError .
-The underlying type of the fp argument is system dependent;
-on a POSIX-compliant system, fp should be cast to type FILE*.
-.IN "XESetFlushGC" "" "@DEF@"
-.sM
-.FD 0
-int (*XESetFlushGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIextension\fP\^;
-.br
-      int *(\^*\fIproc\fP\^)(\^);
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIextension\fP 1i
-Specifies the extension number.
-.IP \fIproc\fP 1i
-Specifies the procedure to call when a GC is flushed.
-.LP
-.eM
-The procedure set by the
-.PN XESetFlushGC
-function has the same interface as the procedure set by the
-.PN XESetCopyGC
-function, but is called when a GC cache needs to be updated in the server.
-.IN "XESetBeforeFlush" "" "@DEF@"
-.sM
-.FD 0
-int (*XESetBeforeFlush(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIextension\fP\^;
-.br
-      int *(\^*\fIproc\fP\^)(\^);
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIextension\fP 1i
-Specifies the extension number.
-.IP \fIproc\fP 1i
-Specifies the procedure to call when a buffer is flushed.
-.LP
-.eM
-The
-.PN XESetBeforeFlush
-function defines a procedure to be called when data is about to be
-sent to the server.  When data is about to be sent, your procedure is  
-called one or more times with these arguments:
-.LP
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-.R
-void (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIcodes\fP, \fIdata\fP, \fIlen\fP\^)
-	Display *\fIdisplay\fP\^;
-	XExtCodes *\fIcodes\fP\^;
-	char *\fIdata\fP\^;
-	long \fIlen\fP\^;
-.De
-.LP
-.eM
-The data argument specifies a portion of the outgoing data buffer,
-and its length in bytes is specified by the len argument.
-Your procedure must not alter the contents of the data and must not
-do additional protocol requests to the same display.
-.SH
-Hooks onto Xlib Data Structures
-.LP
-Various Xlib data structures have provisions for extension procedures
-to chain extension supplied data onto a list.
-These structures are
-.PN GC , 
-.PN Visual , 
-.PN Screen , 
-.PN ScreenFormat , 
-.PN Display , 
-and 
-.PN XFontStruct .
-Because the list pointer is always the first member in the structure, 
-a single set of procedures can be used to manipulate the data
-on these lists.
-.LP
-The following structure is used in the functions in this section
-and is defined in 
-.hN X11/Xlib.h :
-.LP
-.IN "XExtData" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct _XExtData {
-	int number;	/* number returned by XInitExtension */
-	struct _XExtData *next;	/* next item on list of data for structure */
-	int (*free_private)();	/* if defined,  called to free private */
-	XPointer private_data;	/* data private to this extension. */
-} XExtData;
-.De
-.LP
-.eM
-When any of the data structures listed above are freed, 
-the list is walked, and the structure's free procedure (if any) is called. 
-If free is NULL, 
-then the library frees both the data pointed to by the private_data member
-and the structure itself. 
-.LP
-.sM
-.Ds 0
-.TA .5i
-.ta .5i
-union {	Display *display;
-	GC gc;
-	Visual *visual;
-	Screen *screen;
-	ScreenFormat *pixmap_format;
-	XFontStruct *font } XEDataObject;
-.De
-.LP
-.eM
-.IN "XEHeadOfExtensionList" "" "@DEF@"
-.sM
-.FD 0
-XExtData **XEHeadOfExtensionList(\^\fIobject\fP\^)
-	XEDataObject \fIobject\fP\^;
-.FN
-.IP \fIobject\fP 1i
-Specifies the object.
-.LP
-.eM
-The
-.PN XEHeadOfExtensionList
-function returns a pointer to the list of extension structures attached
-to the specified object.
-In concert with 
-.PN XAddToExtensionList ,
-.PN XEHeadOfExtensionList
-allows an extension to attach arbitrary data to any of the structures
-of types contained in
-.PN XEDataObject .
-.LP
-.IN "XAddToExtensionList" "" "@DEF@"
-.sM
-.FD 0
-XAddToExtensionList(\^\fIstructure\fP, \fIext_data\fP\^)
-.br
-      XExtData **\fIstructure\fP\^;
-.br
-      XExtData *\fIext_data\fP\^;
-.FN
-.IP \fIstructure\fP 1i
-Specifies the extension list.
-.IP \fIext_data\fP 1i
-Specifies the extension data structure to add.
-.LP
-.eM
-The structure argument is a pointer to one of the data structures
-enumerated above.
-You must initialize ext_data->number with the extension number
-before calling this function.
-.IN "XFindOnExtensionList" "" "@DEF@"
-.sM
-.FD 0
-XExtData *XFindOnExtensionList(\^\fIstructure\fP, \fInumber\fP\^)
-.br
-      struct _XExtData **\fIstructure\fP\^;
-.br
-      int \fInumber\fP\^;
-.FN
-.IP \fIstructure\fP 1i
-Specifies the extension list.
-.IP \fInumber\fP 1i
-Specifies the extension number from
-.PN XInitExtension .
-.LP
-.eM
-The
-.PN XFindOnExtensionList
-function returns the first extension data structure
-for the extension numbered number.
-It is expected that an extension will add at most one extension
-data structure to any single data structure's extension data list.
-There is no way to find additional structures.
-.LP
-The 
-.PN XAllocID 
-macro, which allocates and returns a resource ID, is defined in 
-.hN X11/Xlib.h .
-.IN "XAllocID" "" "@DEF@"
-.sM
-.FD 0
-XAllocID\^(\fIdisplay\fP\^)
-.br
-     Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-This macro is a call through the 
-.PN Display
-structure to an internal resource ID allocator.
-It returns a resource ID that you can use when creating new resources.
-.LP
-The 
-.PN XAllocIDs
-macro allocates and returns an array of resource ID.
-.IN "XAllocIDs" "" "@DEF@"
-.sM
-.FD 0
-XAllocIDs\^(\fIdisplay\fP, \fIids_return\fP, \fIcount\fP\^)
-.br
-     Display *\fIdisplay\fP\^;
-.br
-     XID *\fIids_return\fP\^;
-.br
-     int \fIcount\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIids_return\fP 1i
-Returns the resource IDs.
-.IP \fIrep\fP 1i
-Specifies the number of resource IDs requested.
-.LP
-.eM
-This macro is a call through the 
-.PN Display
-structure to an internal resource ID allocator.
-It returns resource IDs to the array supplied by the caller.
-To correctly handle automatic reuse of resource IDs, you must call
-.PN XAllocIDs
-when requesting multiple resource IDs.  This call might generate
-protocol requests.
-.SH
-GC Caching
-.LP
-GCs are cached by the library to allow merging of independent change
-requests to the same GC into single protocol requests.
-This is typically called a write-back cache.
-Any extension procedure whose behavior depends on the contents of a GC
-must flush the GC cache to make sure the server has up-to-date contents
-in its GC.
-.LP
-The 
-.PN FlushGC
-macro checks the dirty bits in the library's GC structure and calls
-.PN _XFlushGCCache 
-if any elements have changed.
-The
-.PN FlushGC
-macro is defined as follows:
-.IN "FlushGC" "" "@DEF@"
-.sM
-.FD 0
-FlushGC\^(\^\fIdisplay\fP\^, \fIgc\fP\^)
-.br
-      Display *\^\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.LP
-.eM
-Note that if you extend the GC to add additional resource ID components,
-you should ensure that the library stub sends the change request immediately.
-This is because a client can free a resource immediately after
-using it, so if you only stored the value in the cache without
-forcing a protocol request, the resource might be destroyed before being
-set into the GC.
-You can use the
-.PN _XFlushGCCache 
-procedure 
-to force the cache to be flushed.
-The
-.PN _XFlushGCCache 
-procedure
-is defined as follows:
-.IN "_XFlushGCCache" "" "@DEF@"
-.sM
-.FD 0
-_XFlushGCCache\^(\^\fIdisplay\fP\^, \fIgc\fP\^)
-.br
-      Display *\^\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.LP
-.eM
-.SH
-Graphics Batching
-.LP
-If you extend X to add more poly graphics primitives, you may be able to
-take advantage of facilities in the library to allow back-to-back 
-single calls to be transformed into poly requests.
-This may dramatically improve performance of programs that are not
-written using poly requests. 
-A pointer to an 
-.PN xReq ,
-called last_req in the display structure, is the last request being processed.  
-By checking that the last request
-type, drawable, gc, and other options are the same as the new one
-and that there is enough space left in the buffer, you may be able
-to just extend the previous graphics request by extending the length
-field of the request and appending the data to the buffer.  
-This can improve performance by five times or more in naive programs.  
-For example, here is the source for the 
-.PN XDrawPoint 
-stub.
-(Writing extension stubs is discussed in the next section.)
-.IP
-.sM
-.nf
-
-#include <X11/Xlibint.h>
-
-/* precompute the maximum size of batching request allowed */
-
-static int size = sizeof(xPolyPointReq) + EPERBATCH * sizeof(xPoint);
-
-XDrawPoint(dpy, d, gc, x, y)
-    register Display *dpy;
-    Drawable d;
-    GC gc;
-    int x, y; /* INT16 */
-{
-    xPoint *point;
-    LockDisplay(dpy);
-    FlushGC(dpy, gc);
-    {
-    register xPolyPointReq *req = (xPolyPointReq *) dpy->last_req;
-    /* if same as previous request, with same drawable, batch requests */
-    if (
-          (req->reqType == X_PolyPoint)
-       && (req->drawable == d)
-       && (req->gc == gc->gid)
-       && (req->coordMode == CoordModeOrigin)
-       && ((dpy->bufptr + sizeof (xPoint)) <= dpy->bufmax)
-       && (((char *)dpy->bufptr - (char *)req) < size) ) {
-         point = (xPoint *) dpy->bufptr;
-         req->length += sizeof (xPoint) >> 2;
-         dpy->bufptr += sizeof (xPoint);
-         }
-
-    else {
-        GetReqExtra(PolyPoint, 4, req); /* 1 point = 4 bytes */
-        req->drawable = d;
-        req->gc = gc->gid;
-        req->coordMode = CoordModeOrigin;
-        point = (xPoint *) (req + 1);
-        }
-    point->x = x;
-    point->y = y;
-    }
-    UnlockDisplay(dpy);
-    SyncHandle();
-}
-.fi
-.LP
-.eM
-To keep clients from generating very long requests that may monopolize the 
-server,
-there is a symbol defined in
-.hN X11/Xlibint.h
-of EPERBATCH on the number of requests batched.
-Most of the performance benefit occurs in the first few merged requests.
-Note that 
-.PN FlushGC 
-is called \fIbefore\fP picking up the value of last_req,
-because it may modify this field.
-.SH
-Writing Extension Stubs
-.LP
-All X requests always contain the length of the request,
-expressed as a 16-bit quantity of 32 bits.
-This means that a single request can be no more than 256K bytes in
-length.
-Some servers may not support single requests of such a length.
-The value of dpy->max_request_size contains the maximum length as
-defined by the server implementation.
-For further information,
-see ``X Window System Protocol.''
-.SH
-Requests, Replies, and Xproto.h
-.LP
-The 
-.hN X11/Xproto.h
-file contains three sets of definitions that
-are of interest to the stub implementor:  
-request names, request structures, and reply structures.
-.LP
-You need to generate a file equivalent to 
-.hN X11/Xproto.h
-for your extension and need to include it in your stub procedure.
-Each stub procedure also must include 
-.hN X11/Xlibint.h .
-.LP
-The identifiers are deliberately chosen in such a way that, if the
-request is called X_DoSomething, then its request structure is
-xDoSomethingReq, and its reply is xDoSomethingReply.  
-The GetReq family of macros, defined in 
-.hN X11/Xlibint.h , 
-takes advantage of this naming scheme.
-.LP
-For each X request, 
-there is a definition in 
-.hN X11/Xproto.h
-that looks similar to this:
-.LP
-.Ds 
-.R
-#define X_DoSomething   42
-.De
-In your extension header file, 
-this will be a minor opcode, 
-instead of a major opcode.
-.SH
-Request Format
-.LP
-Every request contains an 8-bit major opcode and a 16-bit length field
-expressed in units of 4 bytes.  
-Every request consists of 4 bytes of header
-(containing the major opcode, the length field, and a data byte) followed by
-zero or more additional bytes of data. 
-The length field defines the total length of the request, including the header.
-The length field in a request must equal the minimum length required to contain 
-the request. 
-If the specified length is smaller or larger than the required length, 
-the server should generate a 
-.PN BadLength 
-error.
-Unused bytes in a request are not required to be zero.  
-Extensions should be designed in such a way that long protocol requests
-can be split up into smaller requests,
-if it is possible to exceed the maximum request size of the server.
-The protocol guarantees the maximum request size to be no smaller than
-4096 units (16384 bytes).
-.LP
-Major opcodes 128 through 255 are reserved for extensions.
-Extensions are intended to contain multiple requests, 
-so extension requests typically have an additional minor opcode encoded 
-in the second data byte in the request header, 
-but the placement and interpretation of this minor opcode as well as all
-other fields in extension requests are not defined by the core protocol.
-Every request is implicitly assigned a sequence number (starting with one)
-used in replies, errors, and events.
-.LP
-To help but not cure portability problems to certain machines, the
-.PN B16
-and
-.PN B32
-macros have been defined so that they can become bitfield specifications 
-on some machines.
-For example, on a Cray,
-these should be used for all 16-bit and 32-bit quantities, as discussed below.
-.LP
-Most protocol requests have a corresponding structure typedef in
-.hN X11/Xproto.h ,
-which looks like:
-.LP
-.IN "xDoSomethingReq" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct _DoSomethingReq {
-	CARD8 reqType;	/* X_DoSomething */
-	CARD8 someDatum;	/* used differently in different requests */
-	CARD16 length B16;	/* total # of bytes in request, divided by 4 */
-	...
-	/* request-specific data */
-	...
-} xDoSomethingReq;
-.De
-.LP
-.eM
-If a core protocol request has a single 32-bit argument, 
-you need not declare a request structure in your extension header file.
-Instead, such requests use the
-.PN xResourceReq
-structure in
-.hN X11/Xproto.h .
-This structure is used for any request whose single argument is a 
-.PN Window , 
-.PN Pixmap ,
-.PN Drawable , 
-.PN GContext , 
-.PN Font , 
-.PN Cursor , 
-.PN Colormap , 
-.PN Atom , 
-or
-.PN VisualID .
-.LP
-.IN "xResourceReq" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct _ResourceReq {
-	CARD8 reqType;	/* the request type, e.g. X_DoSomething */
-	BYTE pad;	/* not used */
-	CARD16 length B16;	/* 2 (= total # of bytes in request, divided by 4) */
-	CARD32 id B32;	/* the Window, Drawable, Font, GContext, etc. */
-} xResourceReq;
-.De
-.LP
-.eM
-If convenient,
-you can do something similar in your extension header file. 
-.LP
-In both of these structures, 
-the reqType field identifies the type of the request (for example, 
-X_MapWindow or X_CreatePixmap).  
-The length field tells how long the request is
-in units of 4-byte longwords. 
-This length includes both the request structure itself and any
-variable-length data, such as strings or lists, that follow the
-request structure.  
-Request structures come in different sizes, 
-but all requests are padded to be multiples of four bytes long.
-.LP
-A few protocol requests take no arguments at all. 
-Instead, they use the
-.PN xReq 
-structure in
-.hN X11/Xproto.h ,
-which contains only a reqType and a length (and a pad byte).
-.LP 
-If the protocol request requires a reply, 
-then
-.hN X11/Xproto.h
-also contains a reply structure typedef:
-.LP
-.IN "xDoSomethingReply" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct _DoSomethingReply {
-	BYTE type;	/* always X_Reply */
-	BYTE someDatum;	/* used differently in different requests */
-	CARD16 sequenceNumber B16;	/* # of requests sent so far */
-	CARD32 length B32;	/* # of additional bytes, divided by 4 */
-	...
-	/* request-specific data */
-	...
-} xDoSomethingReply;
-.De
-.LP
-.eM
-Most of these reply structures are 32 bytes long. 
-If there are not that many reply values, 
-then they contain a sufficient number of pad fields
-to bring them up to 32 bytes.  
-The length field is the total number of bytes in the request minus 32, 
-divided by 4.  
-This length will be nonzero only if:
-.IP \(bu 5
-The reply structure is followed by variable-length data,
-such as a list or string.
-.IP \(bu 5
-The reply structure is longer than 32 bytes.
-.LP
-Only 
-.PN GetWindowAttributes , 
-.PN QueryFont , 
-.PN QueryKeymap , 
-and
-.PN GetKeyboardControl 
-have reply structures longer than 32 bytes in the core protocol.
-.LP
-A few protocol requests return replies that contain no data.  
-.hN X11/Xproto.h
-does not define reply structures for these.
-Instead, they use the 
-.PN xGenericReply
-structure, which contains only a type, length,
-and sequence number (and sufficient padding to make it 32 bytes long).
-.SH
-Starting to Write a Stub Procedure
-.LP
-An Xlib stub procedure should start like this:
-.LP
-.Ds 
-.R
-#include "<X11/Xlibint.h>
-
-XDoSomething (arguments, ... )
-/* argument declarations */
-{
-
-register XDoSomethingReq *req;
-\^...
-.De
-If the protocol request has a reply, 
-then the variable declarations should include the reply structure for the request.
-The following is an example:
-.LP
-.Ds 
-.R
-xDoSomethingReply rep;
-.De 
-.SH
-Locking Data Structures
-.LP
-To lock the display structure for systems that
-want to support multithreaded access to a single display connection,
-each stub will need to lock its critical section.
-Generally, this section is the point from just before the appropriate GetReq
-call until all arguments to the call have been stored into the buffer.
-The precise instructions needed for this locking depend upon the machine
-architecture. 
-Two calls, which are generally implemented as macros, have been provided.
-.IN "LockDisplay" "" "@DEF@"
-.sM
-.FD 0
-LockDisplay(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.LP
-.IN "UnlockDisplay" "" "@DEF@"
-.FD 0
-UnlockDisplay(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-.SH
-Sending the Protocol Request and Arguments
-.LP
-After the variable declarations, 
-a stub procedure should call one of four macros defined in 
-.hN X11/Xlibint.h : 
-.PN GetReq , 
-.PN GetReqExtra , 
-.PN GetResReq , 
-or 
-.PN GetEmptyReq .  
-All of these macros take, as their first argument,
-the name of the protocol request as declared in 
-.hN X11/Xproto.h
-except with X_ removed.   
-Each one declares a 
-.PN Display 
-structure pointer,
-called dpy, and a pointer to a request structure, called req,
-which is of the appropriate type.
-The macro then appends the request structure to the output buffer, 
-fills in its type and length field, and sets req to point to it.
-.LP
-If the protocol request has no arguments (for instance, X_GrabServer),
-then use 
-.PN GetEmptyReq .
-.LP
-.Ds
-.R 
-GetEmptyReq (DoSomething, req);
-.De
-If the protocol request has a single 32-bit argument (such as a
-.PN Pixmap , 
-.PN Window , 
-.PN Drawable , 
-.PN Atom , 
-and so on),
-then use 
-.PN GetResReq .  
-The second argument to the macro is the 32-bit object.  
-.PN X_MapWindow 
-is a good example.
-.LP
-.Ds
-.R
-GetResReq (DoSomething, rid, req);
-.De
-The rid argument is the 
-.PN Pixmap , 
-.PN Window , 
-or other resource ID.
-.LP
-If the protocol request takes any other argument list, 
-then call 
-.PN GetReq .  
-After the 
-.PN GetReq , 
-you need to set all the other fields in the request structure,
-usually from arguments to the stub procedure.
-.LP
-.Ds 
-.R
-GetReq (DoSomething, req);
-/* fill in arguments here */
-req->arg1 = arg1;
-req->arg2 = arg2;
-\^...
-.De
-A few stub procedures (such as 
-.PN XCreateGC 
-and 
-.PN XCreatePixmap ) 
-return a resource ID to the caller but pass a resource ID as an argument
-to the protocol request.   
-Such procedures use the macro 
-.PN XAllocID 
-to allocate a resource ID from the range of IDs 
-that were assigned to this client when it opened the connection.
-.LP
-.Ds 
-.R
-rid = req->rid = XAllocID();
-\^...
-return (rid);
-.De
-Finally, some stub procedures transmit a fixed amount of variable-length
-data after the request.  
-Typically, these procedures (such as
-.PN XMoveWindow 
-and 
-.PN XSetBackground ) 
-are special cases of more general functions like 
-.PN XMoveResizeWindow 
-and 
-.PN XChangeGC .   
-These procedures use 
-.PN GetReqExtra , 
-which is the same as 
-.PN GetReq
-except that it takes an additional argument (the number of
-extra bytes to allocate in the output buffer after the request structure).  
-This number should always be a multiple of four.
-.SH
-Variable Length Arguments
-.LP
-Some protocol requests take additional variable-length data that
-follow the 
-.PN xDoSomethingReq 
-structure.    
-The format of this data varies from request to request. 
-Some requests require a sequence of 8-bit bytes, 
-others a sequence of 16-bit or 32-bit entities, 
-and still others a sequence of structures.
-.LP
-It is necessary to add the length of any variable-length data to the
-length field of the request structure.  
-That length field is in units of 32-bit longwords.  
-If the data is a string or other sequence of 8-bit bytes, 
-then you must round the length up and shift it before adding:
-.LP
-.Ds
-.R
-req->length += (nbytes+3)>>2;
-.De
-To transmit variable-length data, use the 
-.PN Data 
-macros.
-If the data fits into the output buffer, 
-then this macro copies it to the buffer.  
-If it does not fit, however,
-the 
-.PN Data 
-macro calls 
-.PN _XSend , 
-which transmits first the contents of the buffer and then your data.
-The 
-.PN Data 
-macros take three arguments:  
-the display, a pointer to the beginning of the data, 
-and the number of bytes to be sent.
-.sM
-.FD 0
-Data(\^\fIdisplay\fP, (char *) \fIdata\fP, \fInbytes\fP\^);
-.sp
-Data16(\^\fIdisplay\fP, (short *) \fIdata\fP, \fInbytes\fP\^);
-.sp
-Data32(\^\fIdisplay\fP, (long *) \fIdata\fP, \fInbytes\fP\^);
-.FN
-.LP
-.eM
-.PN Data ,
-.PN Data16 ,
-and
-.PN Data32
-are macros that may use their last argument
-more than once, so that argument should be a variable rather than
-an expression such as ``nitems*sizeof(item)''.  
-You should do that kind of computation in a separate statement before calling 
-them.
-Use the appropriate macro when sending byte, short, or long data.
-.LP
-If the protocol request requires a reply, 
-then call the procedure 
-.PN _XSend 
-instead of the 
-.PN Data 
-macro.  
-.PN _XSend 
-takes the same arguments, but because it sends your data immediately instead of 
-copying it into the output buffer (which would later be flushed
-anyway by the following call on 
-.PN _XReply ), 
-it is faster.
-.SH
-Replies
-.LP
-If the protocol request has a reply, 
-then call 
-.PN _XReply 
-after you have finished dealing with 
-all the fixed-length and variable-length arguments.  
-.PN _XReply 
-flushes the output buffer and waits for an 
-.PN xReply 
-packet to arrive.  
-If any events arrive in the meantime,
-.PN _XReply 
-places them in the queue for later use.
-.IN "_XReply" "" "@DEF@"
-.sM
-.FD 0
-Status _XReply(\^\fIdisplay\fP, \fIrep\fP, \fIextra\fP, \fIdiscard\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      xReply *\fIrep\fP\^;
-.br
-      int \fIextra\fP\^;
-.br
-      Bool \fIdiscard\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIrep\fP 1i
-Specifies the reply structure.
-.IP \fIextra\fP 1i
-Specifies the number of 32-bit words expected after the replay.
-.IP \fIdiscard\fP 1i
-Specifies if any data beyond that specified in the extra argument
-should be discarded.
-.LP
-.eM
-The
-.PN _XReply 
-function waits for a reply packet and copies its contents into the
-specified rep.  
-.PN _XReply 
-handles error and event packets that occur before the reply is received.
-.PN _XReply 
-takes four arguments:
-.IP \(bu 5
-A 
-.PN Display 
-* structure
-.IP \(bu 5
-A pointer to a reply structure (which must be cast to an 
-.PN xReply 
-*)
-.IP \(bu 5
-The number of additional 32-bit words (beyond 
-.Pn sizeof( xReply ) 
-= 32 bytes)
-in the reply structure
-.IP \(bu 5
-A Boolean that indicates whether
-.PN _XReply 
-is to discard any additional bytes
-beyond those it was told to read
-.LP
-Because most reply structures are 32 bytes long, 
-the third argument is usually 0.  
-The only core protocol exceptions are the replies to 
-.PN GetWindowAttributes , 
-.PN QueryFont , 
-.PN QueryKeymap , 
-and 
-.PN GetKeyboardControl ,
-which have longer replies.
-.LP
-The last argument should be 
-.PN False 
-if the reply structure is followed
-by additional variable-length data (such as a list or string).  
-It should be 
-.PN True 
-if there is not any variable-length data.
-.NT
-This last argument is provided for upward-compatibility reasons
-to allow a client to communicate properly with a hypothetical later
-version of the server that sends more data than the client expected.
-For example, some later version of 
-.PN GetWindowAttributes 
-might use a
-larger, but compatible, 
-.PN xGetWindowAttributesReply 
-that contains additional attribute data at the end.
-.NE
-.PN _XReply 
-returns 
-.PN True
-if it received a reply successfully or 
-.PN False 
-if it received any sort of error. 
-.LP
-For a request with a reply that is not followed by variable-length
-data, you write something like:
-.LP
-.Ds 
-.R
-_XReply(display, (xReply *)&rep, 0, True);
-*ret1 = rep.ret1;
-*ret2 = rep.ret2;
-*ret3 = rep.ret3;
-\^...
-UnlockDisplay(dpy);
-SyncHandle();
-return (rep.ret4);
-}
-.De
-If there is variable-length data after the reply, 
-change the 
-.PN True 
-to 
-.PN False , 
-and use the appropriate
-.PN _XRead 
-function to read the variable-length data.
-.LP
-.sM
-.FD 0
-_XRead(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^)
-       Display *\fIdisplay\fP\^;
-       char *\fIdata_return\fP\^;
-       long \fInbytes\fP\^;	
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIdata_return\fP 1i
-Specifies the buffer.
-.IP \fInbytes\fP 1i
-Specifies the number of bytes required.
-.LP
-.eM
-The
-.PN _XRead
-function reads the specified number of bytes into data_return.
-.LP
-.sM
-.FD 0
-_XRead16(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^)
-       Display *\fIdisplay\fP\^;
-       short *\fIdata_return\fP\^;
-       long \fInbytes\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIdata_return\fP 1i
-Specifies the buffer.
-.IP \fInbytes\fP 1i
-Specifies the number of bytes required.
-.LP
-.eM
-The
-.PN _XRead16
-function reads the specified number of bytes,
-unpacking them as 16-bit quantities,
-into the specified array as shorts.
-.LP
-.sM
-.FD 0
-_XRead32(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^)
-       Display *\fIdisplay\fP\^;
-       long *\fIdata_return\fP\^;
-       long \fInbytes\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIdata_return\fP 1i
-Specifies the buffer.
-.IP \fInbytes\fP 1i
-Specifies the number of bytes required.
-.LP
-.eM
-The
-.PN _XRead32
-function reads the specified number of bytes,
-unpacking them as 32-bit quantities,
-into the specified array as longs.
-.LP
-.sM
-.FD 0
-_XRead16Pad(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^)
-       Display *\fIdisplay\fP\^;
-       short *\fIdata_return\fP\^;
-       long \fInbytes\fP\^; 
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIdata_return\fP 1i
-Specifies the buffer.
-.IP \fInbytes\fP 1i
-Specifies the number of bytes required.
-.LP
-.eM
-The
-.PN _XRead16Pad
-function reads the specified number of bytes,
-unpacking them as 16-bit quantities,
-into the specified array as shorts.
-If the number of bytes is not a multiple of four,
-.PN _XRead16Pad
-reads and discards up to two additional pad bytes.
-.LP
-.sM
-.FD 0
-_XReadPad(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^)
-       Display *\fIdisplay\fP\^;
-       char *\fIdata_return\fP\^;
-       long \fInbytes\fP\^; 
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIdata_return\fP 1i
-Specifies the buffer.
-.IP \fInbytes\fP 1i
-Specifies the number of bytes required.
-.LP
-.eM
-The
-.PN _XReadPad
-function reads the specified number of bytes into data_return.
-If the number of bytes is not a multiple of four,
-.PN _XReadPad
-reads and discards up to three additional pad bytes.
-.LP
-Each protocol request is a little different. 
-For further information,
-see the Xlib sources for examples.
-.SH
-Synchronous Calling
-.LP
-Each procedure should have a call, just before returning to the user, 
-to a macro called
-.PN SyncHandle .
-If synchronous mode is enabled (see 
-.PN XSynchronize ), 
-the request is sent immediately.
-The library, however, waits until any error the procedure could generate
-at the server has been handled.
-.SH
-Allocating and Deallocating Memory
-.LP
-To support the possible reentry of these procedures, 
-you must observe several conventions when allocating and deallocating memory,
-most often done when returning data to the user from the window
-system of a size the caller could not know in advance
-(for example, a list of fonts or a list of extensions).
-The standard C library functions on many systems
-are not protected against signals or other multithreaded uses.
-The following analogies to standard I/O library functions
-have been defined:
-.TS
-l l.
-T{
-.PN Xmalloc ()
-T}	T{
-Replaces 
-.PN malloc ()
-T}
-T{
-.PN XFree ()
-T}	T{
-Replaces 
-.PN free ()
-T}
-T{
-.PN Xcalloc ()
-T}	T{
-Replaces 
-.PN calloc ()
-T}
-.TE
-.LP
-These should be used in place of any calls you would make to the normal
-C library functions.
-.LP
-If you need a single scratch buffer inside a critical section 
-(for example, to pack and unpack data to and from the wire protocol),
-the general memory allocators may be too expensive to use
-(particularly in output functions, which are performance critical).  
-The following function returns a scratch buffer for use within a
-critical section:
-.IN "_XAllocScratch" "" "@DEF@"
-.sM
-.FD 0
-char *_XAllocScratch(\^\fIdisplay\fP, \fInbytes\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      unsigned long \fInbytes\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fInbytes\fP 1i
-Specifies the number of bytes required.
-.LP
-.eM
-This storage must only be used inside of a critical section of your
-stub.  The returned pointer cannot be assumed valid after any call
-that might permit another thread to execute inside Xlib.  For example,
-the pointer cannot be assumed valid after any use of the
-.PN GetReq
-or
-.PN Data
-families of macros,
-after any use of
-.PN _XReply ,
-or after any use of the
-.PN _XSend
-or
-.PN _XRead
-families of functions.
-.LP
-.sp
-The following function returns a scratch buffer for use across
-critical sections:
-.IN "_XAllocTemp" "" "@DEF@"
-.sM
-.FD 0
-char *_XAllocTemp(\^\fIdisplay\fP, \fInbytes\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      unsigned long \fInbytes\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fInbytes\fP 1i
-Specifies the number of bytes required.
-.LP
-.eM
-This storage can be used across calls that might permit another thread to
-execute inside Xlib.  The storage must be explicitly returned to Xlib.
-The following function returns the storage:
-.IN "_XFreeTemp" "" "@DEF@"
-.sM
-.FD 0
-void _XFreeTemp(\^\fIdisplay\fP, \fIbuf\fP, \fInbytes\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      char *\fIbuf\fP\^;
-.br
-      unsigned long \fInbytes\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIbuf\fP 1i
-Specifies the buffer to return.
-.IP \fInbytes\fP 1i
-Specifies the size of the buffer.
-.LP
-.eM
-You must pass back the same pointer and size that were returned by
-.PN _XAllocTemp .
-.SH
-Portability Considerations
-.LP
-Many machine architectures, 
-including many of the more recent RISC architectures, 
-do not correctly access data at unaligned locations; 
-their compilers pad out structures to preserve this characteristic.
-Many other machines capable of unaligned references pad inside of structures
-as well to preserve alignment, because accessing aligned data is
-usually much faster.
-Because the library and the server use structures to access data at
-arbitrary points in a byte stream,
-all data in request and reply packets \fImust\fP be naturally aligned;
-that is, 16-bit data starts on 16-bit boundaries in the request
-and 32-bit data on 32-bit boundaries.
-All requests \fImust\fP be a multiple of 32 bits in length to preserve
-the natural alignment in the data stream.
-You must pad structures out to 32-bit boundaries.
-Pad information does not have to be zeroed unless you want to
-preserve such fields for future use in your protocol requests.
-Floating point varies radically between machines and should be
-avoided completely if at all possible.
-.LP
-This code may run on machines with 16-bit ints.  
-So, if any integer argument, variable, or return value either can take 
-only nonnegative values or is declared as a
-.PN CARD16
-in the protocol, be sure to declare it as
-.PN unsigned
-.PN int
-and not as
-.PN int .
-(This, of course, does not apply to Booleans or enumerations.)
-.LP
-Similarly, 
-if any integer argument or return value is declared
-.PN CARD32
-in the protocol, 
-declare it as an
-.PN unsigned
-.PN long
-and not as
-.PN int
-or
-.PN long .
-This also goes for any internal variables that may
-take on values larger than the maximum 16-bit
-.PN unsigned
-.PN int .
-.LP
-The library currently assumes that a
-.PN char
-is 8 bits, a
-.PN short
-is 16 bits, an
-.PN int
-is 16 or 32 bits, and a
-.PN long
-is 32 bits.  
-The 
-.PN PackData 
-macro is a half-hearted attempt to deal with the possibility of 32 bit shorts. 
-However, much more work is needed to make this work properly.
-.SH
-Deriving the Correct Extension Opcode
-.LP
-The remaining problem a writer of an extension stub procedure faces that
-the core protocol does not face is to map from the call to the proper
-major and minor opcodes.  
-While there are a number of strategies, 
-the simplest and fastest is outlined below.
-.IP 1. 5
-Declare an array of pointers, _NFILE long (this is normally found
-in 
-.hN stdio.h
-and is the number of file descriptors supported on the system)
-of type 
-.PN XExtCodes .
-Make sure these are all initialized to NULL.
-.IP 2. 5
-When your stub is entered, your initialization test is just to use
-the display pointer passed in to access the file descriptor and an index
-into the array.  
-If the entry is NULL, then this is the first time you
-are entering the procedure for this display.  
-Call your initialization procedure and pass to it the display pointer.
-.IP 3. 5
-Once in your initialization procedure, call 
-.PN XInitExtension ;
-if it succeeds, store the pointer returned into this array.  
-Make sure to establish a close display handler to allow you to zero the entry.
-Do whatever other initialization your extension requires.
-(For example, install event handlers and so on.)
-Your initialization procedure would normally return a pointer to the
-.PN XExtCodes 
-structure for this extension, which is what would normally
-be found in your array of pointers.
-.IP 4. 5
-After returning from your initialization procedure, 
-the stub can now continue normally, because it has its major opcode safely 
-in its hand in the 
-.PN XExtCodes 
-structure.
-.bp
diff --git a/libX11/specs/libX11/AppC.xml b/libX11/specs/libX11/AppC.xml
new file mode 100644
index 000000000..4af2de3fd
--- /dev/null
+++ b/libX11/specs/libX11/AppC.xml
@@ -0,0 +1,3352 @@
+<appendix id="extensions">

+<title>Extensions</title>

+<para>

+<!-- .XE -->

+Because X can evolve by extensions to the core protocol, 

+it is important that extensions not be perceived as second-class citizens.

+At some point, 

+your favorite extensions may be adopted as additional parts of the 

+X Standard.

+</para>

+<para>

+<!-- .LP -->

+Therefore, there should be little to distinguish the use of an extension from 

+that of the core protocol.

+To avoid having to initialize extensions explicitly in application programs, 

+it is also important that extensions perform lazy evaluations,

+automatically initializing themselves when called for the first time.  

+</para>

+<para>

+<!-- .LP -->

+This appendix describes techniques for writing extensions to Xlib that will

+run at essentially the same performance as the core protocol requests.

+</para>

+<!-- .NT -->

+<note><para>

+It is expected that a given extension to X consists of multiple

+requests.

+Defining 10 new features as 10 separate extensions is a bad practice.

+Rather, they should be packaged into a single extension

+and should use minor opcodes to distinguish the requests.

+</para></note>

+<!-- .NE -->

+<para>

+<!-- .LP -->

+The symbols and macros used for writing stubs to Xlib are listed in

+&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>

+<indexterm significance="preferred"><primary>XQueryExtension</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool<function> XQueryExtension</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>char<parameter> *name</parameter></paramdef>

+  <paramdef>int<parameter> *major_opcode_return</parameter></paramdef>

+  <paramdef>int<parameter> *first_event_return</parameter></paramdef>

+  <paramdef>int<parameter> *first_error_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>display</term>

+    <listitem>

+      <para>Specifies the connection to the X server.</para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>name</term>

+    <listitem>

+      <para>Specifies the extension name.</para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>major_opcode_return</term>

+    <listitem>

+      <para>Returns the major opcode.</para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>first_event_return</term>

+    <listitem>

+      <para>Returns the first event code, if any.</para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>first_error_return</term>

+    <listitem>

+      <para>Returns the first error code, if any.</para>

+    </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XQueryExtension</function>

+function determines if the named extension is present.  

+If the extension is not present,

+<function>XQueryExtension</function>

+returns

+<function>False</function>;

+otherwise, it returns

+<function>True</function>.

+If the extension is present,

+<function>XQueryExtension</function>

+returns the major opcode for the extension to major_opcode_return;

+otherwise,

+it returns zero.

+Any minor opcode and the request formats are specific to the

+extension.  

+If the extension involves additional event types, 

+<function>XQueryExtension</function>

+returns the base event type code to first_event_return;

+otherwise, 

+it returns zero.  

+The format of the events is specific to the extension.  

+If the extension involves additional error codes, 

+<function>XQueryExtension</function>

+returns the base error code to first_error_return;

+otherwise, 

+it returns zero.  

+The format of additional data in the errors is specific to the extension.

+</para>

+<para>

+<!-- .LP -->

+If the extension name is not in the Host Portable Character Encoding

+the result is implementation-dependent.

+Uppercase and lowercase matter;

+the strings ``thing'', ``Thing'', and ``thinG'' 

+are all considered different names.

+<indexterm significance="preferred"><primary>XListExtensions</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> **XListExtensions</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> *nextensions_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nextensions_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of extensions listed.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XListExtensions   </function>

+function returns a list of all extensions supported by the server.

+If the data returned by the server is in the Latin Portable Character Encoding,

+then the returned strings are in the Host Portable Character Encoding.

+Otherwise, the result is implementation-dependent.

+<indexterm significance="preferred"><primary>XFreeExtensionList</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XFreeExtensionList</function></funcdef>

+  <paramdef>char<parameter> **list</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>list</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the list of extension names.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XFreeExtensionList</function>

+function frees the memory allocated by 

+<function>XListExtensions</function>.

+<!-- .SH -->

+Hooking into Xlib 

+</para>

+<para>

+<!-- .LP -->

+These functions allow you to hook into the library.  

+They are not normally used by application programmers but are used 

+by people who need to extend the core X protocol and

+the X library interface.

+The functions, which generate protocol requests for X, are typically

+called stubs.

+</para>

+<para>

+<!-- .LP -->

+In extensions, stubs first should check to see if they have initialized 

+themselves on a connection.

+If they have not, they then should call 

+<function>XInitExtension </function>

+to attempt to initialize themselves on the connection.

+</para>

+<para>

+<!-- .LP -->

+If the extension needs to be informed of GC/font allocation or

+deallocation or if the extension defines new event types, 

+the functions described here allow the extension to be 

+called when these events occur.

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XExtCodes</function>

+structure returns the information from 

+<function>XInitExtension </function>

+and is defined in

+&lt;X11/Xlib.h&gt; :

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XExtCodes</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct _XExtCodes {	/* public to extension, cannot be changed */

+	int extension;	/* extension number */

+	int major_opcode;	/* major op-code assigned by server */

+	int first_event;	/* first event number for the extension */

+	int first_error;	/* first error number for the extension */

+} XExtCodes;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>XInitExtension</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XExtCodes<function> *XInitExtension</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>char<parameter> *name</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the extension name.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XInitExtension</function>

+function determines if the named extension exists. 

+Then, it allocates storage for maintaining the 

+information about the extension on the connection, 

+chains this onto the extension list for the connection,

+and returns the information the stub implementor will need to access

+the extension.

+If the extension does not exist,

+<function>XInitExtension</function>

+returns NULL.

+</para>

+<para>

+<!-- .LP -->

+If the extension name is not in the Host Portable Character Encoding,

+the result is implementation-dependent.

+Uppercase and lowercase matter;

+the strings ``thing'', ``Thing'', and ``thinG'' 

+are all considered different names.

+</para>

+<para>

+<!-- .LP -->

+The extension number in the 

+<function>XExtCodes </function>

+structure is

+needed in the other calls that follow.  

+This extension number is unique only to a single connection.

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XAddExtension</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XExtCodes<function> *XAddExtension</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+For local Xlib extensions, the

+<function>XAddExtension</function>

+function allocates the

+<function>XExtCodes</function>

+structure, bumps the extension number count,

+and chains the extension onto the extension list.

+(This permits extensions to Xlib without requiring server extensions.)

+<!-- .SH -->

+Hooks into the Library

+</para>

+<para>

+<!-- .LP -->

+These functions allow you to define procedures that are to be

+called when various circumstances occur.

+The procedures include the creation of a new GC for a connection,

+the copying of a GC, the freeing of a GC, the creating and freeing of fonts,

+the conversion of events defined by extensions to and from wire

+format, and the handling of errors.

+</para>

+<para>

+<!-- .LP -->

+All of these functions return the previous procedure defined for this

+extension.

+<indexterm significance="preferred"><primary>XESetCloseDisplay</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XESetCloseDisplay</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> extension</parameter></paramdef>

+  <paramdef>int<parameter> (*proc)()</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>extension</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the extension number.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>proc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the procedure to call when the display is closed.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XESetCloseDisplay</function>

+function defines a procedure to be called whenever

+<function>XCloseDisplay </function>

+is called.  

+It returns any previously defined procedure, usually NULL.

+</para>

+<para>

+<!-- .LP -->

+When 

+<function>XCloseDisplay </function>

+is called, 

+your procedure is called 

+with these arguments:

+</para>

+<literallayout class="monospaced">

+(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>codes</emphasis>)

+	Display *<emphasis remap='I'>display</emphasis>;

+	XExtCodes *<emphasis remap='I'>codes</emphasis>;

+</literallayout>

+<para>

+<indexterm significance="preferred"><primary>XESetCreateGC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> *XESetCreateGC</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> extension</parameter></paramdef>

+  <paramdef>int<parameter> (*proc)()</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>extension</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the extension number.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>proc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the procedure to call when a GC is closed.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XESetCreateGC</function>

+function defines a procedure to be called whenever

+a new GC is created.  

+It returns any previously defined procedure, usually NULL.

+</para>

+<para>

+<!-- .LP -->

+When a GC is created, 

+your procedure is called with these arguments:

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>gc</emphasis>, <emphasis remap='I'>codes</emphasis>)

+	Display *<emphasis remap='I'>display</emphasis>;

+	GC <emphasis remap='I'>gc</emphasis>;

+	XExtCodes *<emphasis remap='I'>codes</emphasis>;

+</literallayout>

+</para>

+<indexterm significance="preferred"><primary>XESetCopyGC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> *XESetCopyGC</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> extension</parameter></paramdef>

+  <paramdef>int<parameter> (*proc)()</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>extension</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the extension number.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>proc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the procedure to call when GC components are copied.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XESetCopyGC</function>

+function defines a procedure to be called whenever

+a GC is copied.  

+It returns any previously defined procedure, usually NULL.

+</para>

+<para>

+<!-- .LP -->

+When a GC is copied, 

+your procedure is called with these arguments:

+</para>

+<literallayout class="monospaced">

+(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>gc</emphasis>, <emphasis remap='I'>codes</emphasis>)

+	Display *<emphasis remap='I'>display</emphasis>;

+	GC <emphasis remap='I'>gc</emphasis>;

+	XExtCodes *<emphasis remap='I'>codes</emphasis>;

+</literallayout>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> *XESetFreeGC</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> extension</parameter></paramdef>

+  <paramdef>int<parameter> (*proc)()</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>extension</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the extension number.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>proc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the procedure to call when a GC is freed.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+The

+<function>XESetFreeGC</function>

+function defines a procedure to be called whenever

+a GC is freed.  

+It returns any previously defined procedure, usually NULL.

+</para>

+<para>

+<!-- .LP -->

+When a GC is freed, 

+your procedure is called with these arguments:

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+<!-- .R -->

+(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>gc</emphasis>, <emphasis remap='I'>codes</emphasis>)

+	Display *<emphasis remap='I'>display</emphasis>;

+	GC <emphasis remap='I'>gc</emphasis>;

+	XExtCodes *<emphasis remap='I'>codes</emphasis>;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>XESetCreateFont</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> *XESetCreateFont</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> extension</parameter></paramdef>

+  <paramdef>int<parameter> (*proc)()</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>extension</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the extension number.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>proc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the procedure to call when a font is created.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XESetCreateFont</function>

+function defines a procedure to be called whenever

+<function>XLoadQueryFont </function>

+and

+<function>XQueryFont</function>

+are called.  

+It returns any previously defined procedure, usually NULL.

+</para>

+<para>

+<!-- .LP -->

+When 

+<function>XLoadQueryFont </function>

+or

+<function>XQueryFont</function>

+is called, 

+your procedure is called with these arguments:

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+<!-- .R -->

+(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>fs</emphasis>, <emphasis remap='I'>codes</emphasis>)

+	Display *<emphasis remap='I'>display</emphasis>;

+	XFontStruct *<emphasis remap='I'>fs</emphasis>;

+	XExtCodes *<emphasis remap='I'>codes</emphasis>;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>XESetFreeFont</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> *XESetFreeFont</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> extension</parameter></paramdef>

+  <paramdef>int<parameter> (*proc)()</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>extension</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the extension number.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>proc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the procedure to call when a font is freed.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XESetFreeFont</function>

+function defines a procedure to be called whenever

+<function>XFreeFont </function>

+is called.  

+It returns any previously defined procedure, usually NULL.

+</para>

+<para>

+<!-- .LP -->

+When 

+<function>XFreeFont </function>

+is called, your procedure is called with these arguments:

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+<!-- .R -->

+(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>fs</emphasis>, <emphasis remap='I'>codes</emphasis>)

+	Display *<emphasis remap='I'>display</emphasis>;

+	XFontStruct *<emphasis remap='I'>fs</emphasis>;

+	XExtCodes *<emphasis remap='I'>codes</emphasis>;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XESetWireToEvent</function>

+and

+<function>XESetEventToWire</function>

+functions allow you to define new events to the library.

+An 

+<function>XEvent</function>

+structure always has a type code (type

+<function>int</function>)

+as the first component.

+This uniquely identifies what kind of event it is.

+The second component is always the serial number (type

+<function>unsigned</function>

+<function>long</function>)

+of the last request processed by the server.

+The third component is always a Boolean (type

+<function>Bool</function>)

+indicating whether the event came from a

+<function>SendEvent</function>

+protocol request.

+The fourth component is always a pointer to the display

+the event was read from.

+The fifth component is always a resource ID of one kind or another,

+usually a window, carefully selected to be useful to toolkit dispatchers.

+The fifth component should always exist, even if

+the event does not have a natural destination;

+if there is no value

+from the protocol to put in this component, initialize it to zero.

+<!-- .NT -->

+There is an implementation limit such that your host event

+structure size cannot be bigger than the size of the

+<function>XEvent </function>

+union of structures.

+There also is no way to guarantee that more than 24 elements or 96 characters

+in the structure will be fully portable between machines.

+<!-- .NE -->

+<indexterm significance="preferred"><primary>XESetWireToEvent</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> *XESetWireToEvent</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> event_number</parameter></paramdef>

+  <paramdef>Status<parameter> (*proc)()</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the event code.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>proc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the procedure to call when converting an event.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XESetWireToEvent</function>

+function defines a procedure to be called when an event

+needs to be converted from wire format 

+(<function>xEvent</function>)

+to host format 

+(<function>XEvent</function>).

+The event number defines which protocol event number to install a

+conversion procedure for.

+<function>XESetWireToEvent</function>

+returns any previously defined procedure.

+<!-- .NT -->

+You can replace a core event conversion function with one

+of your own, although this is not encouraged.

+It would, however, allow you to intercept a core event 

+and modify it before being placed in the queue or otherwise examined.

+<!-- .NE -->

+When Xlib needs to convert an event from wire format to host

+format, your procedure is called with these arguments:

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+<!-- .R -->

+Status (*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>re</emphasis>, <emphasis remap='I'>event</emphasis>)

+	Display *<emphasis remap='I'>display</emphasis>;

+	XEvent *<emphasis remap='I'>re</emphasis>;

+	xEvent *<emphasis remap='I'>event</emphasis>;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Your procedure must return status to indicate if the conversion succeeded.

+The re argument is a pointer to where the host format event should be stored,

+and the event argument is the 32-byte wire event structure.

+In the 

+<function>XEvent </function>

+structure you are creating, 

+you must fill in the five required members of the event structure.

+You should fill in the type member with the type specified for the 

+<function>xEvent </function>

+structure.

+You should copy all other members from the 

+<function>xEvent </function>

+structure (wire format) to the

+<function>XEvent </function>

+structure (host format).

+Your conversion procedure should return 

+<function>True</function>

+if the event should be placed in the queue or

+<function>False</function>

+if it should not be placed in the queue.

+</para>

+<para>

+<!-- .LP -->

+To initialize the serial number component of the event, call

+<function>_XSetLastRequestRead</function>

+with the event and use the return value.

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>_XSetLastRequestRead</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>unsigned long<function> _XSetLastRequestRead</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>xGenericReply<parameter> *rep</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>rep</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the wire event structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>_XSetLastRequestRead</function>

+function computes and returns a complete serial number from the partial

+serial number in the event.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XESetEventToWire</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> *XESetEventToWire</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> event_number</parameter></paramdef>

+  <paramdef>int<parameter> (*proc)()</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the event code.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>proc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the procedure to call when converting an event.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XESetEventToWire</function>

+function defines a procedure to be called when an event

+needs to be converted from host format

+(<function>XEvent</function>)

+to wire format

+(<function>xEvent</function>)

+form.  

+The event number defines which protocol event number to install a

+conversion procedure for.

+<function>XESetEventToWire</function>

+returns any previously defined procedure.

+It returns zero if the conversion fails or nonzero otherwise.

+<!-- .NT -->

+You can replace a core event conversion function with one

+of your own, although this is not encouraged.  

+It would, however, allow you to intercept a core event 

+and modify it before being sent to another client.

+<!-- .NE -->

+When Xlib needs to convert an event from host format to wire format, 

+your procedure is called with these arguments:

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+<!-- .R -->

+(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>re</emphasis>, <emphasis remap='I'>event</emphasis>)

+	Display *<emphasis remap='I'>display</emphasis>;

+	XEvent *<emphasis remap='I'>re</emphasis>;

+	xEvent *<emphasis remap='I'>event</emphasis>;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The re argument is a pointer to the host format event,

+and the event argument is a pointer to where the 32-byte wire event 

+structure should be stored.

+You should fill in the type with the type from the 

+<function>XEvent </function>

+structure.

+All other members then should be copied from the host format to the 

+<function>xEvent </function>

+structure.

+<indexterm significance="preferred"><primary>XESetWireToError</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool<function> *XESetWireToError</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> error_number</parameter></paramdef>

+  <paramdef>Bool<parameter> (*proc)()</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>error_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the error code.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>proc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the procedure to call when an error is received.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XESetWireToError</function>

+function defines a procedure to be called when an extension

+error needs to be converted from wire format to host format.

+The error number defines which protocol error code to install

+the conversion procedure for.

+<function>XESetWireToError</function>

+returns any previously defined procedure.

+</para>

+<para>

+<!-- .LP -->

+Use this function for extension errors that contain additional error values

+beyond those in a core X error, when multiple wire errors must be combined

+into a single Xlib error, or when it is necessary to intercept an

+X error before it is otherwise examined.

+</para>

+<para>

+<!-- .LP -->

+When Xlib needs to convert an error from wire format to host format,

+the procedure is called with these arguments:

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+<!-- .R -->

+Bool (*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>he</emphasis>, <emphasis remap='I'>we</emphasis>)

+	Display *<emphasis remap='I'>display</emphasis>;

+	XErrorEvent *<emphasis remap='I'>he</emphasis>;

+	xError *<emphasis remap='I'>we</emphasis>;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The he argument is a pointer to where the host format error should be stored.

+The structure pointed at by he is guaranteed to be as large as an

+<function>XEvent</function>

+structure and so can be cast to a type larger than an

+<function>XErrorEvent</function>

+to store additional values.

+If the error is to be completely ignored by Xlib

+(for example, several protocol error structures will be combined into

+one Xlib error),

+then the function should return

+<function>False</function>;

+otherwise, it should return

+<function>True</function>.

+<indexterm significance="preferred"><primary>XESetError</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> *XESetError</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> extension</parameter></paramdef>

+  <paramdef>int<parameter> (*proc)()</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>extension</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the extension number.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>proc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the procedure to call when an error is received.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Inside Xlib, there are times that you may want to suppress the

+calling of the external error handling when an error occurs.

+This allows status to be returned on a call at the cost of the call

+being synchronous (though most such functions are query operations, in any

+case, and are typically programmed to be synchronous).

+</para>

+<para>

+<!-- .LP -->

+When Xlib detects a protocol error in 

+<function>_XReply</function>,

+it calls your procedure with these arguments:

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+<!-- .R -->

+int (*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>err</emphasis>, <emphasis remap='I'>codes</emphasis>, <emphasis remap='I'>ret_code</emphasis>)

+	Display *<emphasis remap='I'>display</emphasis>;

+	xError *<emphasis remap='I'>err</emphasis>;

+	XExtCodes *<emphasis remap='I'>codes</emphasis>;

+	int *<emphasis remap='I'>ret_code</emphasis>;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The err argument is a pointer to the 32-byte wire format error.

+The codes argument is a pointer to the extension codes structure.

+The ret_code argument is the return code you may want 

+<function>_XReply </function>

+returned to.

+</para>

+<para>

+<!-- .LP -->

+If your procedure returns a zero value, 

+the error is not suppressed, and 

+the client's error handler is called.

+(For further information, see section 11.8.2.)

+If your procedure returns nonzero, 

+the error is suppressed, and 

+<function>_XReply </function>

+returns the value of ret_code.

+<indexterm significance="preferred"><primary>XESetErrorString</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> *XESetErrorString</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> extension</parameter></paramdef>

+  <paramdef>char<parameter> *(*proc)()</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>extension</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the extension number.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>proc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the procedure to call to obtain an error string.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XGetErrorText </function>

+function returns a string to the user for an error.

+<function>XESetErrorString</function>

+allows you to define a procedure to be called that

+should return a pointer to the error message.

+The following is an example.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+<!-- .R -->

+(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>code</emphasis>, <emphasis remap='I'>codes</emphasis>, <emphasis remap='I'>buffer</emphasis>, <emphasis remap='I'>nbytes</emphasis>)

+	Display *<emphasis remap='I'>display</emphasis>;

+	int <emphasis remap='I'>code</emphasis>;

+	XExtCodes *<emphasis remap='I'>codes</emphasis>;

+	char *<emphasis remap='I'>buffer</emphasis>;

+	int <emphasis remap='I'>nbytes</emphasis>;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Your procedure is called with the error code for every error detected.

+You should copy nbytes of a null-terminated string containing the

+error message into buffer.

+<indexterm significance="preferred"><primary>XESetPrintErrorValues</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> *XESSetPrintErrorValues</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> extension</parameter></paramdef>

+  <paramdef>void<parameter> (*proc)()</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>extension</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the extension number.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>proc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the procedure to call when an error is printed.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XESetPrintErrorValues</function>

+function defines a procedure to be called when an extension

+error is printed, to print the error values.

+Use this function for extension errors that contain additional error values

+beyond those in a core X error.

+It returns any previously defined procedure.

+</para>

+<para>

+<!-- .LP -->

+When Xlib needs to print an error,

+the procedure is called with these arguments:

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+<!-- .R -->

+void (*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>ev</emphasis>, <emphasis remap='I'>fp</emphasis>)

+	Display *<emphasis remap='I'>display</emphasis>;

+	XErrorEvent *<emphasis remap='I'>ev</emphasis>;

+	void *<emphasis remap='I'>fp</emphasis>;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The structure pointed at by ev is guaranteed to be as large as an

+<function>XEvent</function>

+structure and so can be cast to a type larger than an

+<function>XErrorEvent</function>

+to obtain additional values set by using

+<function>XESetWireToError</function>.

+The underlying type of the fp argument is system dependent;

+on a <acronym>POSIX</acronym>-compliant system, fp should be cast to type FILE*.

+<indexterm significance="preferred"><primary>XESetFlushGC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> *XESetFlushGC</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> extension</parameter></paramdef>

+  <paramdef>int<parameter> *(*proc)()</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>extension</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the extension number.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>proc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the procedure to call when a GC is flushed.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The procedure set by the

+<function>XESetFlushGC</function>

+function has the same interface as the procedure set by the

+<function>XESetCopyGC</function>

+function, but is called when a GC cache needs to be updated in the server.

+<indexterm significance="preferred"><primary>XESetBeforeFlush</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> *XESetCopyGC</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> extension</parameter></paramdef>

+  <paramdef>int<parameter> *(*proc)()</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>extension</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the extension number.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>proc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the procedure to call when a buffer is flushed.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XESetBeforeFlush</function>

+function defines a procedure to be called when data is about to be

+sent to the server.  When data is about to be sent, your procedure is  

+called one or more times with these arguments:

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+<!-- .R -->

+void (*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>codes</emphasis>, <emphasis remap='I'>data</emphasis>, <emphasis remap='I'>len</emphasis>)

+	Display *<emphasis remap='I'>display</emphasis>;

+	XExtCodes *<emphasis remap='I'>codes</emphasis>;

+	char *<emphasis remap='I'>data</emphasis>;

+	long <emphasis remap='I'>len</emphasis>;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The data argument specifies a portion of the outgoing data buffer,

+and its length in bytes is specified by the len argument.

+Your procedure must not alter the contents of the data and must not

+do additional protocol requests to the same display.

+<!-- .SH -->

+Hooks onto Xlib Data Structures

+</para>

+<para>

+<!-- .LP -->

+Various Xlib data structures have provisions for extension procedures

+to chain extension supplied data onto a list.

+These structures are

+<function>GC</function>,

+<function>Visual</function>,

+<function>Screen</function>,

+<function>ScreenFormat</function>,

+<function>Display</function>,

+and 

+<function>XFontStruct</function>.

+Because the list pointer is always the first member in the structure, 

+a single set of procedures can be used to manipulate the data

+on these lists.

+</para>

+<para>

+<!-- .LP -->

+The following structure is used in the functions in this section

+and is defined in 

+&lt;X11/Xlib.h&gt;

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XExtData</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct _XExtData {

+	int number;	/* number returned by XInitExtension */

+	struct _XExtData *next;	/* next item on list of data for structure */

+	int (*free_private)();	/* if defined,  called to free private */

+	XPointer private_data;	/* data private to this extension. */

+} XExtData;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+When any of the data structures listed above are freed, 

+the list is walked, and the structure's free procedure (if any) is called. 

+If free is NULL, 

+then the library frees both the data pointed to by the private_data member

+and the structure itself. 

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i -->

+<!-- .ta .5i -->

+union {	Display *display;

+	GC gc;

+	Visual *visual;

+	Screen *screen;

+	ScreenFormat *pixmap_format;

+	XFontStruct *font } XEDataObject;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>XEHeadOfExtensionList</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XExtData<function> **XEHeadOfExtensionList</function></funcdef>

+  <paramdef>XEDataObject<parameter> object</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>object</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the object.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XEHeadOfExtensionList</function>

+function returns a pointer to the list of extension structures attached

+to the specified object.

+In concert with 

+<function>XAddToExtensionList</function>,

+<function>XEHeadOfExtensionList</function>

+allows an extension to attach arbitrary data to any of the structures

+of types contained in

+<function>XEDataObject</function>.

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XAddToExtensionList</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XAddToExtensionList</function></funcdef>

+  <paramdef>XExtData<parameter> **structure</parameter></paramdef>

+  <paramdef>XExtData<parameter> *ext_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>structure</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the extension list.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ext_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the extension data structure to add.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The structure argument is a pointer to one of the data structures

+enumerated above.

+You must initialize ext_data-&gt;number with the extension number

+before calling this function.

+<indexterm significance="preferred"><primary>XFindOnExtensionList</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XExtData<function> *XFindOnExtensionList</function></funcdef>

+  <paramdef>struct_XExtData<parameter> **structure</parameter></paramdef>

+  <paramdef>int<parameter> number</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>structure</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the extension list.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the extension number from

+<function>XInitExtension</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XFindOnExtensionList</function>

+function returns the first extension data structure

+for the extension numbered number.

+It is expected that an extension will add at most one extension

+data structure to any single data structure's extension data list.

+There is no way to find additional structures.

+</para>

+<para>

+<!-- .LP -->

+The 

+<function>XAllocID </function>

+macro, which allocates and returns a resource ID, is defined in 

+&lt;X11/Xlib.h&gt;.

+<indexterm significance="preferred"><primary>XAllocID</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XAllocID</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+This macro is a call through the 

+<function>Display</function>

+structure to an internal resource ID allocator.

+It returns a resource ID that you can use when creating new resources.

+</para>

+<para>

+<!-- .LP -->

+The 

+<function>XAllocIDs</function>

+macro allocates and returns an array of resource ID.

+<indexterm significance="preferred"><primary>XAllocIDs</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XAllocIDs</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XID<parameter> *ids_return</parameter></paramdef>

+  <paramdef>int<parameter> count</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ids_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the resource IDs.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>rep</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of resource IDs requested.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+This macro is a call through the 

+<function>Display</function>

+structure to an internal resource ID allocator.

+It returns resource IDs to the array supplied by the caller.

+To correctly handle automatic reuse of resource IDs, you must call

+<function>XAllocIDs</function>

+when requesting multiple resource IDs.  This call might generate

+protocol requests.

+<!-- .SH -->

+GC Caching

+</para>

+<para>

+<!-- .LP -->

+GCs are cached by the library to allow merging of independent change

+requests to the same GC into single protocol requests.

+This is typically called a write-back cache.

+Any extension procedure whose behavior depends on the contents of a GC

+must flush the GC cache to make sure the server has up-to-date contents

+in its GC.

+</para>

+<para>

+<!-- .LP -->

+The 

+<function>FlushGC</function>

+macro checks the dirty bits in the library's GC structure and calls

+<function>_XFlushGCCache </function>

+if any elements have changed.

+The

+<function>FlushGC</function>

+macro is defined as follows:

+<indexterm significance="preferred"><primary>FlushGC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> FlushGC</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Note that if you extend the GC to add additional resource ID components,

+you should ensure that the library stub sends the change request immediately.

+This is because a client can free a resource immediately after

+using it, so if you only stored the value in the cache without

+forcing a protocol request, the resource might be destroyed before being

+set into the GC.

+You can use the

+<function>_XFlushGCCache </function>

+procedure 

+to force the cache to be flushed.

+The

+<function>_XFlushGCCache </function>

+procedure

+is defined as follows:

+<indexterm significance="preferred"><primary>_XFlushGCCache</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> _XFlushGCCache</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .SH -->

+Graphics Batching

+</para>

+<para>

+<!-- .LP -->

+If you extend X to add more poly graphics primitives, you may be able to

+take advantage of facilities in the library to allow back-to-back 

+single calls to be transformed into poly requests.

+This may dramatically improve performance of programs that are not

+written using poly requests. 

+A pointer to an 

+<function>xReq</function>,

+called last_req in the display structure, is the last request being processed.  

+By checking that the last request

+type, drawable, gc, and other options are the same as the new one

+and that there is enough space left in the buffer, you may be able

+to just extend the previous graphics request by extending the length

+field of the request and appending the data to the buffer.  

+This can improve performance by five times or more in naive programs.  

+For example, here is the source for the 

+<function>XDrawPoint </function>

+stub.

+(Writing extension stubs is discussed in the next section.)

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+<!-- .sM -->

+<!-- .nf -->

+

+#include &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 -->

+<indexterm significance="preferred"><primary>xDoSomethingReq</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct _DoSomethingReq {

+	CARD8 reqType;	/* X_DoSomething */

+	CARD8 someDatum;	/* used differently in different requests */

+	CARD16 length B16;	/* total # of bytes in request, divided by 4 */

+	...

+	/* request-specific data */

+	...

+} xDoSomethingReq;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If a core protocol request has a single 32-bit argument, 

+you need not declare a request structure in your extension header file.

+Instead, such requests use the

+<function>xResourceReq</function>

+structure in

+&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 -->

+<indexterm significance="preferred"><primary>xResourceReq</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct _ResourceReq {

+	CARD8 reqType;	/* the request type, e.g. X_DoSomething */

+	BYTE pad;	/* not used */

+	CARD16 length B16;	/* 2 (= total # of bytes in request, divided by 4) */

+	CARD32 id B32;	/* the Window, Drawable, Font, GContext, etc. */

+} xResourceReq;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If convenient,

+you can do something similar in your extension header file. 

+</para>

+<para>

+<!-- .LP -->

+In both of these structures, 

+the reqType field identifies the type of the request (for example, 

+X_MapWindow or X_CreatePixmap).  

+The length field tells how long the request is

+in units of 4-byte longwords. 

+This length includes both the request structure itself and any

+variable-length data, such as strings or lists, that follow the

+request structure.  

+Request structures come in different sizes, 

+but all requests are padded to be multiples of four bytes long.

+</para>

+<para>

+<!-- .LP -->

+A few protocol requests take no arguments at all. 

+Instead, they use the

+<function>xReq </function>

+structure in

+&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 -->

+<indexterm significance="preferred"><primary>xDoSomethingReply</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct _DoSomethingReply {

+	BYTE type;	/* always X_Reply */

+	BYTE someDatum;	/* used differently in different requests */

+	CARD16 sequenceNumber B16;	/* # of requests sent so far */

+	CARD32 length B32;	/* # of additional bytes, divided by 4 */

+	...

+	/* request-specific data */

+	...

+} xDoSomethingReply;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Most of these reply structures are 32 bytes long. 

+If there are not that many reply values, 

+then they contain a sufficient number of pad fields

+to bring them up to 32 bytes.  

+The length field is the total number of bytes in the request minus 32, 

+divided by 4.  

+This length will be nonzero only if:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+The reply structure is followed by variable-length data,

+such as a list or string.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The reply structure is longer than 32 bytes.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+Only 

+<function>GetWindowAttributes</function>,

+<function>QueryFont</function>,

+<function>QueryKeymap</function>,

+and

+<function>GetKeyboardControl </function>

+have reply structures longer than 32 bytes in the core protocol.

+</para>

+<para>

+<!-- .LP -->

+A few protocol requests return replies that contain no data.  

+&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.

+<indexterm significance="preferred"><primary>LockDisplay</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> LockDisplay</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>UnlockDisplay</primary></indexterm>

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> UnlockDisplay</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .SH -->

+Sending the Protocol Request and Arguments

+</para>

+<para>

+<!-- .LP -->

+After the variable declarations, 

+a stub procedure should call one of four macros defined in 

+&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.

+<indexterm significance="preferred"><primary>_XReply</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> _XReply</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>xReply<parameter> *rep</parameter></paramdef>

+  <paramdef>int<parameter> extra</parameter></paramdef>

+  <paramdef>Bool<parameter> discard</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>rep</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the reply structure.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>extra</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of 32-bit words expected after the replay.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>discard</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies if any data beyond that specified in the extra argument

+should be discarded.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>_XReply </function>

+function waits for a reply packet and copies its contents into the

+specified rep.  

+<function>_XReply </function>

+handles error and event packets that occur before the reply is received.

+<function>_XReply </function>

+takes four arguments:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+A 

+<function>Display </function>

+* structure

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A pointer to a reply structure (which must be cast to an 

+<function>xReply </function>

+*)

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The number of additional 32-bit words (beyond 

+<function>sizeof( xReply</function>)

+= 32 bytes)

+in the reply structure

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A Boolean that indicates whether

+<function>_XReply </function>

+is to discard any additional bytes

+beyond those it was told to read

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+Because most reply structures are 32 bytes long, 

+the third argument is usually 0.  

+The only core protocol exceptions are the replies to 

+<function>GetWindowAttributes</function>,

+<function>QueryFont</function>,

+<function>QueryKeymap</function>,

+and 

+<function>GetKeyboardControl</function>,

+which have longer replies.

+</para>

+<para>

+<!-- .LP -->

+The last argument should be 

+<function>False </function>

+if the reply structure is followed

+by additional variable-length data (such as a list or string).  

+It should be 

+<function>True </function>

+if there is not any variable-length data.

+<!-- .NT -->

+This last argument is provided for upward-compatibility reasons

+to allow a client to communicate properly with a hypothetical later

+version of the server that sends more data than the client expected.

+For example, some later version of 

+<function>GetWindowAttributes </function>

+might use a

+larger, but compatible, 

+<function>xGetWindowAttributesReply </function>

+that contains additional attribute data at the end.

+<!-- .NE -->

+<function>_XReply </function>

+returns 

+<function>True</function>

+if it received a reply successfully or 

+<function>False </function>

+if it received any sort of error. 

+</para>

+<para>

+<!-- .LP -->

+For a request with a reply that is not followed by variable-length

+data, you write something like:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .R -->

+_XReply(display, (xReply *)&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:

+<indexterm significance="preferred"><primary>_XAllocScratch</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> *_XAllocScratch</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> nbytes</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nbytes</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of bytes required.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+This storage must only be used inside of a critical section of your

+stub.  The returned pointer cannot be assumed valid after any call

+that might permit another thread to execute inside Xlib.  For example,

+the pointer cannot be assumed valid after any use of the

+<function>GetReq</function>

+or

+<function>Data</function>

+families of macros,

+after any use of

+<function>_XReply</function>,

+or after any use of the

+<function>_XSend</function>

+or

+<function>_XRead</function>

+families of functions.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+The following function returns a scratch buffer for use across

+critical sections:

+<indexterm significance="preferred"><primary>_XAllocTemp</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> *_XAllocTemp</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> nbytes</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nbytes</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of bytes required.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+This storage can be used across calls that might permit another thread to

+execute inside Xlib.  The storage must be explicitly returned to Xlib.

+The following function returns the storage:

+<indexterm significance="preferred"><primary>_XFreeTemp</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> _XFreeTemp</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>char<parameter> *buf</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> nbytes</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>buf</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the buffer to return.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nbytes</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the size of the buffer.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+You must pass back the same pointer and size that were returned by

+<function>_XAllocTemp</function>.

+<!-- .SH -->

+Portability Considerations

+</para>

+<para>

+<!-- .LP -->

+Many machine architectures, 

+including many of the more recent <acronym>RISC</acronym> architectures,

+do not correctly access data at unaligned locations; 

+their compilers pad out structures to preserve this characteristic.

+Many other machines capable of unaligned references pad inside of structures

+as well to preserve alignment, because accessing aligned data is

+usually much faster.

+Because the library and the server use structures to access data at

+arbitrary points in a byte stream,

+all data in request and reply packets <emphasis remap='I'>must</emphasis> be naturally aligned;

+that is, 16-bit data starts on 16-bit boundaries in the request

+and 32-bit data on 32-bit boundaries.

+All requests <emphasis remap='I'>must</emphasis> be a multiple of 32 bits in length to preserve

+the natural alignment in the data stream.

+You must pad structures out to 32-bit boundaries.

+Pad information does not have to be zeroed unless you want to

+preserve such fields for future use in your protocol requests.

+Floating point varies radically between machines and should be

+avoided completely if at all possible.

+</para>

+<para>

+<!-- .LP -->

+This code may run on machines with 16-bit ints.  

+So, if any integer argument, variable, or return value either can take 

+only nonnegative values or is declared as a

+<function>CARD16</function>

+in the protocol, be sure to declare it as

+<function>unsigned</function>

+<function>int</function>

+and not as

+<function>int</function>.

+(This, of course, does not apply to Booleans or enumerations.)

+</para>

+<para>

+<!-- .LP -->

+Similarly, 

+if any integer argument or return value is declared

+<function>CARD32</function>

+in the protocol, 

+declare it as an

+<function>unsigned</function>

+<function>long</function>

+and not as

+<function>int</function>

+or

+<function>long</function>.

+This also goes for any internal variables that may

+take on values larger than the maximum 16-bit

+<function>unsigned</function>

+<function>int</function>.

+</para>

+<para>

+<!-- .LP -->

+The library currently assumes that a

+<function>char</function>

+is 8 bits, a

+<function>short</function>

+is 16 bits, an

+<function>int</function>

+is 16 or 32 bits, and a

+<function>long</function>

+is 32 bits.  

+The 

+<function>PackData </function>

+macro is a half-hearted attempt to deal with the possibility of 32 bit shorts. 

+However, much more work is needed to make this work properly.

+<!-- .SH -->

+Deriving the Correct Extension Opcode

+</para>

+<para>

+<!-- .LP -->

+The remaining problem a writer of an extension stub procedure faces that

+the core protocol does not face is to map from the call to the proper

+major and minor opcodes.  

+While there are a number of strategies, 

+the simplest and fastest is outlined below.

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Declare an array of pointers, _NFILE long (this is normally found

+in 

+&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/libX11/specs/libX11/AppD b/libX11/specs/libX11/AppD
deleted file mode 100644
index f96e06175..000000000
--- a/libX11/specs/libX11/AppD
+++ /dev/null
@@ -1,1183 +0,0 @@
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-.\" OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" Except as contained in this notice, the name of the X Consortium shall
-.\" not be used in advertising or otherwise to promote the sale, use or
-.\" other dealings in this Software without prior written authorization
-.\" from the X Consortium.
-.\"
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
-.\" Digital Equipment Corporation
-.\"
-.\" Portions Copyright \(co 1990, 1991 by
-.\" Tektronix, Inc.
-.\"
-.\" Permission to use, copy, modify and distribute this documentation for
-.\" any purpose and without fee is hereby granted, provided that the above
-.\" copyright notice appears in all copies and that both that copyright notice
-.\" and this permission notice appear in all copies, and that the names of
-.\" Digital and Tektronix not be used in in advertising or publicity pertaining
-.\" to this documentation without specific, written prior permission.
-.\" Digital and Tektronix makes no representations about the suitability
-.\" of this documentation for any purpose.
-.\" It is provided ``as is'' without express or implied warranty.
-.\" 
-\&
-.sp 1
-.ce 3
-\s+1\fBAppendix D\fP\s-1
-
-\s+1\fBCompatibility Functions\fP\s-1
-.sp 2
-.na
-.LP
-.XS
-Appendix D: Compatibility Functions
-.XE
-.LP
-The X Version 11 and X Version 10 functions discussed in this appendix 
-are obsolete, have been superseded by newer X Version 11 functions,
-and are maintained for compatibility reasons only.
-.SH
-X Version 11 Compatibility Functions
-.LP
-You can use the X Version 11 compatibility functions to:
-.IP \(bu 5
-Set standard properties 
-.IP \(bu 5
-Set and get window sizing hints 
-.IP \(bu 5
-Set and get an
-.PN XStandardColormap
-structure 
-.IP \(bu 5
-Parse window geometry
-.IP \(bu 5
-Get X environment defaults
-.SH
-Setting Standard Properties
-.LP
-To specify a minimum set of properties describing the simplest application,
-use
-.PN XSetStandardProperties .
-This function has been superseded by
-.PN XSetWMProperties
-and sets all or portions of the 
-WM_NAME, WM_ICON_NAME, WM_HINTS, WM_COMMAND, 
-and WM_NORMAL_HINTS properties.
-.IN "XSetStandardProperties" "" "@DEF@"
-.sM
-.FD 0
-XSetStandardProperties\^(\^\fIdisplay\fP, \fIw\fP, \fIwindow_name\fP, \fIicon_name\fP, \fIicon_pixmap\fP, \fIargv\fP, \fIargc\fP, \fIhints\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      char *\fIwindow_name\fP\^;
-.br
-      char *\fIicon_name\fP\^;
-.br
-      Pixmap \fIicon_pixmap\fP\^;
-.br
-      char **\fIargv\fP\^;
-.br
-      int \fIargc\fP\^;
-.br
-      XSizeHints *\fIhints\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIwindow_name\fP 1i
-Specifies the window name,
-which should be a null-terminated string.
-.IP \fIicon_name\fP 1i
-Specifies the icon name,
-which should be a null-terminated string.
-.IP \fIicon_pixmap\fP 1i
-Specifies the bitmap that is to be used for the icon or
-.PN None .
-.IP \fIargv\fP 1i
-Specifies the application's argument list.
-.IP \fIargc\fP 1i
-Specifies the number of arguments.
-.IP \fIhints\fP 1i
-Specifies a pointer to the size hints for the window in its normal state.
-.LP
-.eM
-The
-.PN XSetStandardProperties
-function provides a means by which simple applications set the
-most essential properties with a single call.
-.PN XSetStandardProperties
-should be used to give a window manager some information about 
-your program's preferences. 
-It should not be used by applications that need
-to communicate more information than is possible with
-.PN XSetStandardProperties .
-(Typically, argv is the argv array of your main program.)
-If the strings are not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-.LP
-.PN XSetStandardProperties
-can generate
-.PN BadAlloc
-and
-.PN BadWindow 
-errors.
-.SH
-Setting and Getting Window Sizing Hints
-.LP
-Xlib provides functions that you can use to set or get window sizing hints.
-The functions discussed in this section use the flags and the
-.PN XSizeHints 
-structure, as defined in the
-.hN X11/Xutil.h
-header file and use the WM_NORMAL_HINTS property.
-.LP
-.sp
-To set the size hints for a given window in its normal state, use
-.PN XSetNormalHints .
-This function has been superseded by
-.PN XSetWMNormalHints .
-.IN "XSetNormalHints" "" "@DEF@"
-.sM
-.FD 0
-XSetNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XSizeHints *\fIhints\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIhints\fP 1i
-Specifies a pointer to the size hints for the window in its normal state.
-.LP
-.eM
-The
-.PN XSetNormalHints
-function sets the size hints structure for the specified window.
-Applications use
-.PN XSetNormalHints
-to inform the window manager of the size
-or position desirable for that window.
-In addition, 
-an application that wants to move or resize itself should call
-.PN XSetNormalHints
-and specify its new desired location and size
-as well as making direct Xlib calls to move or resize.  
-This is because window managers may ignore redirected
-configure requests, but they pay attention to property changes.
-.LP
-To set size hints, 
-an application not only must assign values to the appropriate members
-in the hints structure but also must set the flags member of the structure 
-to indicate which information is present and where it came from.  
-A call to
-.PN XSetNormalHints
-is meaningless, unless the flags member is set to indicate which members of
-the structure have been assigned values.
-.LP
-.PN XSetNormalHints
-can generate
-.PN BadAlloc
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To return the size hints for a window in its normal state, use
-.PN XGetNormalHints .
-This function has been superseded by
-.PN XGetWMNormalHints .
-.IN "XGetNormalHints" "" "@DEF@"
-.sM
-.FD 0
-Status XGetNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XSizeHints *\fIhints_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIhints_return\fP 1i
-Returns the size hints for the window in its normal state.
-.LP
-.eM
-The
-.PN XGetNormalHints
-function returns the size hints for a window in its normal state.
-It returns a nonzero status if it succeeds or zero if
-the application specified no normal size hints for this window.
-.LP
-.PN XGetNormalHints
-can generate a
-.PN BadWindow 
-error.
-.LP
-.sp
-The next two functions set and read the WM_ZOOM_HINTS property.
-.LP
-To set the zoom hints for a window, use
-.PN XSetZoomHints .
-This function is no longer supported by the
-\fIInter-Client Communication Conventions Manual\fP.
-.IN "XSetZoomHints" "" "@DEF@"
-.sM
-.FD 0
-XSetZoomHints\^(\^\fIdisplay\fP, \fIw\fP, \fIzhints\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XSizeHints *\fIzhints\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIzhints\fP 1i
-Specifies a pointer to the zoom hints.
-.LP
-.eM
-Many window managers think of windows in one of three states:
-iconic, normal, or zoomed.
-The
-.PN XSetZoomHints
-function provides the window manager with information for the window in the
-zoomed state.
-.LP
-.PN XSetZoomHints
-can generate
-.PN BadAlloc
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To read the zoom hints for a window, use
-.PN XGetZoomHints .
-This function is no longer supported by the
-\fIInter-Client Communication Conventions Manual\fP.
-.IN "XGetZoomHints" "" "@DEF@"
-.sM
-.FD 0
-Status XGetZoomHints\^(\^\fIdisplay\fP, \fIw\fP, \fIzhints_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XSizeHints *\fIzhints_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIzhints_return\fP 1i
-Returns the zoom hints.
-.LP
-.eM
-The
-.PN XGetZoomHints
-function returns the size hints for a window in its zoomed state.
-It returns a nonzero status if it succeeds or zero if
-the application specified no zoom size hints for this window.
-.LP
-.PN XGetZoomHints
-can generate a
-.PN BadWindow 
-error.
-.LP
-.sp
-To set the value of any property of type WM_SIZE_HINTS, use
-.PN XSetSizeHints .
-This function has been superseded by
-.PN XSetWMSizeHints .
-.IN "XSetSizeHints" "" "@DEF@"
-.sM
-.FD 0
-XSetSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP, \fIproperty\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XSizeHints *\fIhints\fP\^;
-.br
-      Atom \fIproperty\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIhints\fP 1i
-Specifies a pointer to the size hints.
-.IP \fIproperty\fP 1i
-Specifies the property name.
-.LP
-.eM
-The
-.PN XSetSizeHints
-function sets the
-.PN XSizeHints
-structure for the named property and the specified window.
-This is used by
-.PN XSetNormalHints
-and
-.PN XSetZoomHints
-and can be used to set the value of any property of type WM_SIZE_HINTS.
-Thus, it may be useful if other properties of that type get defined.
-.LP
-.PN XSetSizeHints
-can generate
-.PN BadAlloc ,
-.PN BadAtom ,
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To read the value of any property of type WM_SIZE_HINTS, use
-.PN XGetSizeHints .
-This function has been superseded by
-.PN XGetWMSizeHints .
-.IN "XGetSizeHints" "" "@DEF@"
-.sM
-.FD 0
-Status XGetSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP, \fIproperty\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XSizeHints *\fIhints_return\fP\^;
-.br
-      Atom \fIproperty\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIhints_return\fP 1i
-Returns the size hints.
-.IP \fIproperty\fP 1i
-Specifies the property name.
-.LP
-.eM
-The
-.PN XGetSizeHints
-function returns the
-.PN XSizeHints
-structure for the named property and the specified window.
-This is used by
-.PN XGetNormalHints
-and
-.PN XGetZoomHints .
-It also can be used to retrieve the value of any property of type
-WM_SIZE_HINTS.
-Thus, it may be useful if other properties of that type get defined.
-.PN XGetSizeHints
-returns a nonzero status if a size hint was defined
-or zero otherwise.
-.LP
-.PN XGetSizeHints
-can generate
-.PN BadAtom
-and 
-.PN BadWindow 
-errors.
-.SH
-Getting and Setting an XStandardColormap Structure
-.LP
-To get the 
-.PN XStandardColormap 
-structure associated with one of the described atoms, use
-.PN XGetStandardColormap .
-This function has been superseded by
-.PN XGetRGBColormap .
-.IN "XGetStandardColormap" "" "@DEF@"
-.sM
-.FD 0
-Status XGetStandardColormap(\^\fIdisplay\fP, \fIw\fP, \fIcolormap_return\fP, \fIproperty\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XStandardColormap *\fIcolormap_return\fP\^;
-.br
-      Atom \fIproperty\fP\^;	/* RGB_BEST_MAP, etc. */
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIcolormap_return\fP 1i
-Returns the colormap associated with the specified atom.
-.IP \fIproperty\fP 1i
-Specifies the property name.
-.LP
-.eM
-The
-.PN XGetStandardColormap
-function returns the colormap definition associated with the atom supplied
-as the property argument.
-.PN XGetStandardColormap
-returns a nonzero status if successful and zero otherwise.
-For example,
-to fetch the standard
-.PN GrayScale
-colormap for a display,
-you use
-.PN XGetStandardColormap
-with the following syntax:
-.LP
-.sM
-.Ds 0
-.TA .5i 1.5i
-.ta .5i 1.5i
-XGetStandardColormap(dpy, DefaultRootWindow(dpy), &cmap, XA_RGB_GRAY_MAP);
-.De
-.LP
-.eM
-See section 14.3 for the semantics of standard colormaps.
-.LP
-.PN XGetStandardColormap
-can generate
-.PN BadAtom
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To set a standard colormap, use
-.PN XSetStandardColormap .
-This function has been superseded by
-.PN XSetRGBColormap .
-.IN "XSetStandardColormap" "" "@DEF@"
-.sM
-.FD 0
-XSetStandardColormap(\^\fIdisplay\fP, \fIw\fP, \fIcolormap\fP, \fIproperty\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XStandardColormap *\fIcolormap\fP\^;
-.br
-      Atom \fIproperty\fP\^;	/* RGB_BEST_MAP, etc. */
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.IP \fIproperty\fP 1i
-Specifies the property name.
-.LP
-.eM
-The
-.PN XSetStandardColormap
-function usually is only used by window or session managers.
-.LP
-.PN XSetStandardColormap
-can generate
-.PN BadAlloc ,
-.PN BadAtom ,
-.PN BadDrawable ,
-and
-.PN BadWindow 
-errors.
-.SH
-Parsing Window Geometry
-.LP
-To parse window geometry given a user-specified position 
-and a default position, use
-.PN XGeometry .
-This function has been superseded by
-.PN XWMGeometry .
-.IN "Window" "determining location"
-.IN "XGeometry" "" "@DEF@"
-.sM
-.FD 0
-int XGeometry\^(\^\fIdisplay\fP, \fIscreen\fP, \fIposition\fP\^, \fIdefault_position\fP\^, \fIbwidth\fP\^, \fIfwidth\fP\^, \fIfheight\fP\^, \fIxadder\fP\^, 
-.br
-                  \fIyadder\fP\^, \fIx_return\fP\^, \fIy_return\fP\^, \fIwidth_return\fP\^, \fIheight_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIscreen\fP\^;
-.br
-      char *\fIposition\fP\^, *\fIdefault_position\fP\^;	
-.br
-      unsigned int \fIbwidth\fP\^;
-.br
-      unsigned int \fIfwidth\fP\^, \fIfheight\fP\^;	
-.br
-      int \fIxadder\fP\^, \fIyadder\fP\^;	
-.br
-      int *\fIx_return\fP\^, *\fIy_return\fP\^;
-.br
-      int *\fIwidth_return\fP\^, *\fIheight_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIscreen\fP 1i
-Specifies the screen.
-.IP \fIposition\fP 1i
-.br
-.ns
-.IP \fIdefault_position\fP 1i
-Specify the geometry specifications.
-.IP \fIbwidth\fP 1i
-Specifies the border width.
-.IP \fIfheight\fP 1i
-.br
-.ns
-.IP \fIfwidth\fP 1i
-Specify the font height and width in pixels (increment size).
-.IP \fIxadder\fP 1i
-.br
-.ns
-.IP \fIyadder\fP 1i
-Specify additional interior padding needed in the window.
-.IP \fIx_return\fP 1i
-.br
-.ns
-.IP \fIy_return\fP 1i
-Return the x and y offsets.
-.IP \fIwidth_return\fP 1i
-.br
-.ns
-.IP \fIheight_return\fP 1i
-Return the width and height determined.
-.LP
-.eM
-You pass in the border width (bwidth),
-size of the increments fwidth and fheight
-(typically font width and height),
-and any additional interior space (xadder and yadder)
-to make it easy to compute the resulting size.
-The
-.PN XGeometry 
-function returns the position the window should be placed given a position and
-a default position.
-.PN XGeometry
-determines the placement of
-a window using a geometry specification as specified by
-.PN XParseGeometry 
-and the additional information about the window.
-Given a fully qualified default geometry specification and
-an incomplete geometry specification, 
-.PN XParseGeometry
-returns a bitmask value as defined above in the 
-.PN XParseGeometry
-call,
-by using the position argument.
-.LP
-The returned width and height will be the width and height specified
-by default_position as overridden by any user-specified position.
-They are not affected by fwidth, fheight, xadder, or yadder.
-The x and y coordinates are computed by using the border width,
-the screen width and height, padding as specified by xadder and yadder,
-and the fheight and fwidth times the width and height from the
-geometry specifications.
-.SH
-Getting the X Environment Defaults
-.LP
-The
-.PN XGetDefault
-function provides a primitive interface to the resource manager facilities 
-discussed in chapter 15.
-It is only useful in very simple applications.
-.LP
-.sp
-.IN "XGetDefault" "" "@DEF@"
-.sM
-.FD 0
-char *XGetDefault\^(\^\fIdisplay\fP, \fIprogram\fP\^, \fIoption\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      char *\fIprogram\fP\^;
-.br
-      char *\fIoption\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIprogram\fP 1i
-Specifies the program name for the Xlib defaults (usually argv[0] 
-of the main program).
-.IP \fIoption\fP 1i
-Specifies the option name.
-.LP
-.eM
-The
-.PN XGetDefault
-function returns the value of the resource \fIprog\fP.\fIoption\fP,
-where \fIprog\fP is the program argument with the directory prefix removed
-and \fIoption\fP must be a single component.
-Note that multilevel resources cannot be used with
-.PN XGetDefault .
-The class "Program.Name" is always used for the resource lookup.
-If the specified option name does not exist for this program,
-.PN XGetDefault
-returns NULL.
-The strings returned by
-.PN XGetDefault
-are owned by Xlib and should not be modified or freed by the client.
-.LP
-If a database has been set with 
-.PN XrmSetDatabase , 
-that database is used for the lookup.
-Otherwise, a database is created
-and is set in the display (as if by calling 
-.PN XrmSetDatabase ).
-The database is created in the current locale.
-To create a database,
-.PN XGetDefault
-uses resources from the RESOURCE_MANAGER property on the root
-window of screen zero.
-If no such property exists,
-a resource file in the user's home directory is used.
-On a POSIX-conformant system, 
-this file is
-.PN "$HOME/.Xdefaults" .
-.IN "Files" "$HOME/.Xdefaults"
-After loading these defaults,
-.PN XGetDefault
-merges additional defaults specified by the XENVIRONMENT
-environment variable.
-If XENVIRONMENT is defined,
-it contains a full path name for the additional resource file.
-If XENVIRONMENT is not defined,
-.PN XGetDefault
-looks for
-.PN "$HOME/.Xdefaults-\fIname\fP" ,
-where \fIname\fP specifies the name of the machine on which the application
-is running.
-.SH
-X Version 10 Compatibility Functions
-.LP
-You can use the X Version 10 compatibility functions to:
-.IP \(bu 5
-Draw and fill polygons and curves
-.IP \(bu 5
-Associate user data with a value
-.SH
-Drawing and Filling Polygons and Curves
-.LP
-Xlib provides functions that you can use to draw or fill
-arbitrary polygons or curves.  
-These functions are provided mainly for compatibility with X Version 10 
-and have no server support.  
-That is, they call other Xlib functions, not the server directly.  
-Thus, if you just have straight lines to draw, using 
-.PN XDrawLines 
-.IN "XDrawLines"
-or
-.PN XDrawSegments 
-.IN "XDrawSegments" 
-is much faster.
-.LP
-The functions discussed here provide all the functionality of the 
-X Version 10 functions 
-.PN XDraw , 
-.IN "X10 compatibility" "XDraw" 
-.PN XDrawFilled , 
-.IN "X10 compatibility" "XDrawFilled"
-.PN XDrawPatterned , 
-.IN "X10 compatibility" "XDrawPatterned" 
-.PN XDrawDashed , 
-.IN "X10 compatibility" "XDrawDashed"
-and
-.PN XDrawTiled .  
-.IN "X10 compatibility" "XDrawTiled"
-They are as compatible as possible given X Version 11's new line-drawing 
-functions.  
-One thing to note, however, is that
-.PN VertexDrawLastPoint 
-is no longer supported. 
-Also, the error status returned is the opposite of what it was under 
-X Version 10 (this is the X Version 11 standard error status).  
-.PN XAppendVertex 
-and 
-.PN XClearVertexFlag 
-from X Version 10 also are not supported.
-.LP
-Just how the graphics context you use is set up actually
-determines whether you get dashes or not, and so on.  
-Lines are properly joined if they connect and include
-the closing of a closed figure  (see 
-.PN XDrawLines ).
-The functions discussed here fail (return zero) only if they run out of memory
-or are passed a 
-.PN Vertex 
-list that has a 
-.PN Vertex 
-with 
-.PN VertexStartClosed
-set that is not followed by a 
-.PN Vertex 
-with 
-.PN VertexEndClosed 
-set.
-.LP
-.sp
-To achieve the effects of the X Version 10
-.PN XDraw , 
-.IN "X10 compatibility" "XDraw" 
-.PN XDrawDashed , 
-.IN "X10 compatibility" "XDrawDashed"
-and 
-.PN XDrawPatterned , 
-.IN "X10 compatibility" "XDrawPatterned" 
-use
-.PN XDraw .  
-.IN "XDraw" "" "@DEF@" 
-.sM
-.FD 0
-#include <X11/X10.h>
-
-Status XDraw(\^\fIdisplay\fP, \fId\fP, \fIgc\fP, \fIvlist\fP, \fIvcount\fP\^)
-.br
-	Display *\fIdisplay\fP\^;
-.br
-	Drawable \fId\fP\^;
-.br
-	GC \fIgc\fP\^;
-.br
-	Vertex *\fIvlist\fP\^;
-.br
-	int \fIvcount\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIvlist\fP 1i
-Specifies a pointer to the list of vertices that indicate what to draw.
-.IP \fIvcount\fP 1i
-Specifies how many vertices are in vlist.
-.LP
-.eM
-The
-.PN XDraw 
-function draws an arbitrary polygon or curve.  
-The figure drawn is defined by the specified list of vertices (vlist).
-The points are connected by lines as specified in the flags in the
-vertex structure.
-.LP
-Each Vertex, as defined in
-.hN X11/X10.h ,
-is a structure with the following members:
-.LP
-.IN "Vertex" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 1.5i
-.ta .5i 1.5i
-typedef struct _Vertex {
-	short x,y;
-	unsigned short flags;
-} Vertex;
-.De
-.LP
-.eM
-The x and y members are the coordinates of the vertex 
-that are relative to either the upper left inside corner of the drawable 
-(if 
-.PN VertexRelative 
-is zero) or the previous vertex (if 
-.PN VertexRelative 
-is one).
-.LP
-The flags, as defined in 
-.hN X11/X10.h , 
-are as follows:
-.IN "VertexRelative" "" "@DEF@"
-.IN "VertexDontDraw" "" "@DEF@"
-.IN "VertexCurved" "" "@DEF@"
-.IN "VertexStartClosed" "" "@DEF@"
-.IN "VertexEndClosed" "" "@DEF@"
-.sM
-.TS
-l l l.
-T{
-.PN VertexRelative
-T}	T{
-0x0001
-T}	T{
-/* else absolute */
-T}
-T{
-.PN VertexDontDraw
-T}	T{
-0x0002
-T}	T{
-/* else draw */
-T}
-T{
-.PN VertexCurved
-T}	T{
-0x0004
-T}	T{
-/* else straight */
-T}
-T{
-.PN VertexStartClosed
-T}	T{
-0x0008
-T}	T{
-/* else not */
-T}
-T{
-.PN VertexEndClosed
-T}	T{
-0x0010
-T}	T{
-/* else not */
-T}
-.TE
-.LP
-.eM
-.IP \(bu 5
-If 
-.PN VertexRelative 
-is not set,  
-the coordinates are absolute (that is, relative to the drawable's origin).  
-The first vertex must be an absolute vertex.
-.IP \(bu 5
-If
-.PN VertexDontDraw 
-is one, 
-no line or curve is drawn from the previous vertex to this one.  
-This is analogous to picking up the pen and moving to another place 
-before drawing another line.
-.IP \(bu 5
-If 
-.PN VertexCurved 
-is one, 
-a spline algorithm is used to draw a smooth curve from the previous vertex
-through this one to the next vertex.  
-Otherwise, a straight line is drawn from the previous vertex to this one.  
-It makes sense to set 
-.PN VertexCurved 
-to one only if a previous and next vertex are both defined
-(either explicitly in the array or through the definition of a closed 
-curve).
-.IP \(bu 5
-It is permissible for 
-.PN VertexDontDraw 
-bits and 
-.PN VertexCurved
-bits both to be one. 
-This is useful if you want to define the previous point for the smooth curve
-but do not want an actual curve drawing to start until this point.
-.IP \(bu 5
-If 
-.PN VertexStartClosed 
-is one, 
-then this point marks the beginning of a closed curve.  
-This vertex must be followed later in the array by another vertex 
-whose effective coordinates are identical
-and that has a
-.PN VertexEndClosed 
-bit of one.
-The points in between form a cycle to determine predecessor 
-and successor vertices for the spline algorithm.
-.LP
-This function uses these GC components:
-function, plane-mask, line-width, line-style, cap-style, join-style,
-fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and
-clip-mask.
-It also uses these GC mode-dependent components: 
-foreground, background, tile, stipple,
-tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and dash-list.
-.LP
-.sp
-To achieve the effects of the X Version 10
-.PN XDrawTiled 
-.IN "X10 compatibility" "XDrawTiled"
-and 
-.PN XDrawFilled , 
-.IN "X10 compatibility" "XDrawFilled"
-use
-.PN XDrawFilled .
-.IN "XDrawFilled" "" "@DEF@"
-.sM
-.FD 0
-#include <X11/X10.h>
-
-Status XDrawFilled(\^\fIdisplay\fP, \fId\fP, \fIgc\fP, \fIvlist\fP, \fIvcount\fP\^)
-.br
-	Display *\fIdisplay\fP\^;
-.br
-	Drawable \fId\fP\^;
-.br
-	GC \fIgc\fP\^;
-.br
-	Vertex *\fIvlist\fP\^;
-.br
-	int \fIvcount\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIvlist\fP 1i
-Specifies a pointer to the list of vertices that indicate what to draw.
-.IP \fIvcount\fP 1i
-Specifies how many vertices are in vlist.
-.LP
-.eM
-The
-.PN XDrawFilled 
-function draws arbitrary polygons or curves and then fills them.
-.LP
-This function uses these GC components:
-function, plane-mask, line-width, line-style, cap-style, join-style,
-fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and
-clip-mask.
-It also uses these GC mode-dependent components: 
-foreground, background, tile, stipple,
-tile-stipple-x-origin, tile-stipple-y-origin, 
-dash-offset, dash-list, fill-style, and fill-rule.
-.SH
-Associating User Data with a Value
-.LP
-These functions have been superseded by the context management functions
-(see section 16.10). 
-It is often necessary to associate arbitrary information with resource IDs.
-Xlib provides the 
-.PN XAssocTable 
-functions that you can use to make such an association.
-.IN "Hash Lookup"
-.IN "Window" "IDs"
-.IN "Resource IDs"
-Application programs often need to be able to easily refer to
-their own data structures when an event arrives.
-The 
-.PN XAssocTable
-system provides users of the X library with a method
-for associating their own data structures with X resources
-.Pn ( Pixmaps , 
-.PN Fonts , 
-.PN Windows , 
-and so on).
-.LP
-An 
-.PN XAssocTable
-can be used to type X resources.  
-For example, the user
-may want to have three or four types of windows,
-each with different properties. 
-This can be accomplished by associating each X window ID
-with a pointer to a window property data structure  defined  by  the
-user.
-A generic type has been defined in the X library for resource IDs.
-It is called an XID.
-.LP
-There are a few  guidelines  that  should be observed when using an
-.PN XAssocTable :
-.IP \(bu 5
-All  XIDs  are  relative  to  the  specified display.
-.IP \(bu 5
-Because  of  the  hashing  scheme  used  by  the  association mechanism,
-the following rules for determining the size of a
-.PN XAssocTable
-should be followed.  
-Associations will be  made  and  looked  up  more
-efficiently  if  the  table  size  (number  of  buckets in the hashing
-system) is a power of two and if there are not more than 8 XIDs  per
-bucket.
-.LP
-.sp
-To return a pointer to a new
-.PN XAssocTable , 
-use 
-.PN XCreateAssocTable .
-.IN "XCreateAssocTable" "" "@DEF@"
-.sM
-.FD 0
-XAssocTable *XCreateAssocTable\^(\^\fIsize\fP\^)
-.br
-      int \fIsize\fP\^;	
-.FN
-.IP \fIsize\fP 1i
-Specifies the number of buckets in the hash system of
-.PN XAssocTable .
-.LP
-.eM
-The size argument specifies the number of buckets in the 
-hash system of
-.PN XAssocTable .
-For  reasons  of  efficiency  the number of buckets
-should be a power of two.
-Some size  suggestions  might  be:  use  32 buckets  per  100  objects,
-and a reasonable maximum number of objects per buckets is 8.
-If  an  error  allocating  memory  for  the
-.PN XAssocTable 
-occurs, 
-a NULL pointer is returned. 
-.LP
-.sp
-To create an entry in a given 
-.PN XAssocTable ,
-use 
-.PN XMakeAssoc .
-.IN "XMakeAssoc" "" "@DEF@"
-.sM
-.FD 0
-XMakeAssoc\^(\^\fIdisplay\fP, \fItable\fP\^, \fIx_id\fP\^, \fIdata\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XAssocTable *\fItable\fP\^;	
-.br
-      XID \fIx_id\fP\^;
-.br
-      char *\fIdata\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fItable\fP 1i
-Specifies the assoc table. 
-.IP \fIx_id\fP 1i
-Specifies the X resource ID.
-.IP \fIdata\fP 1i
-Specifies the data to be associated with the X resource ID.
-.LP
-.eM
-The
-.PN XMakeAssoc
-function inserts data into an 
-.PN XAssocTable
-keyed on an XID.
-Data is inserted into the table only once.
-Redundant inserts are ignored.
-The queue in each association bucket is sorted from the lowest XID to 
-the highest XID.
-.LP
-.sp
-To obtain data from a given 
-.PN XAssocTable ,
-use 
-.PN XLookUpAssoc .
-.IN "XLookUpAssoc" "" "@DEF@"
-.sM
-.FD 0
-char *XLookUpAssoc\^(\^\fIdisplay\fP, \fItable\fP\^, \fIx_id\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XAssocTable *\fItable\fP\^;
-.br
-      XID \fIx_id\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fItable\fP 1i
-Specifies the assoc table. 
-.IP \fIx_id\fP 1i
-Specifies the X resource ID.
-.LP
-.eM
-The
-.PN XLookUpAssoc
-function retrieves the data stored in an 
-.PN XAssocTable
-by its XID.  
-If  an appropriately  matching XID can be found in the table,
-.PN XLookUpAssoc
-returns the data associated with it.
-If the x_id cannot be found in the table,
-it returns NULL.
-.LP
-.sp
-To delete an entry from a given 
-.PN XAssocTable ,
-use 
-.PN XDeleteAssoc .
-.IN "XDeleteAssoc" "" "@DEF@"
-.sM
-.FD 0
-XDeleteAssoc\^(\^\fIdisplay\fP, \fItable\fP\^, \fIx_id\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XAssocTable *\fItable\fP\^;
-.br
-      XID \fIx_id\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fItable\fP 1i
-Specifies the assoc table. 
-.IP \fIx_id\fP 1i
-Specifies the X resource ID.
-.LP
-.eM
-The
-.PN XDeleteAssoc
-function deletes an association in an 
-.PN XAssocTable
-keyed on its XID.
-Redundant deletes (and deletes of nonexistent XIDs) are ignored.
-Deleting associations in no way impairs the performance of an 
-.PN XAssocTable .
-.LP
-.sp
-To free the memory associated with a given 
-.PN XAssocTable ,
-use 
-.PN XDestroyAssocTable .
-.IN "XDestroyAssocTable" "" "@DEF@"
-.sM
-.FD 0
-XDestroyAssocTable\^(\^\fItable\fP\^)
-.br
-      XAssocTable *\fItable\fP\^;
-.FN
-.IP \fItable\fP 1i
-Specifies the assoc table. 
-.LP
-.eM
-.bp
diff --git a/libX11/specs/libX11/AppD.xml b/libX11/specs/libX11/AppD.xml
new file mode 100644
index 000000000..57d60a219
--- /dev/null
+++ b/libX11/specs/libX11/AppD.xml
@@ -0,0 +1,1900 @@
+<appendix id="compatibility_functions">

+<title>Compatibility Functions</title>

+<para>

+<!-- .LP -->

+The X Version 11 and X Version 10 functions discussed in this appendix 

+are obsolete, have been superseded by newer X Version 11 functions,

+and are maintained for compatibility reasons only.

+<!-- .SH -->

+X Version 11 Compatibility Functions

+</para>

+<para>

+<!-- .LP -->

+You can use the X Version 11 compatibility functions to:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Set standard properties 

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Set and get window sizing hints 

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Set and get an

+<function>XStandardColormap</function>

+structure 

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Parse window geometry

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Get X environment defaults

+<!-- .SH -->

+Setting Standard Properties

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+To specify a minimum set of properties describing the simplest application,

+use

+<function>XSetStandardProperties</function>.

+This function has been superseded by

+<function>XSetWMProperties</function>

+and sets all or portions of the 

+WM_NAME, WM_ICON_NAME, WM_HINTS, WM_COMMAND, 

+and WM_NORMAL_HINTS properties.

+<indexterm significance="preferred"><primary>XSetStandardProperties</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetStandardProperties</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>char<parameter> *window_name</parameter></paramdef>

+  <paramdef>char<parameter> *icon_name</parameter></paramdef>

+  <paramdef>Pixmap<parameter> icon_pixmap</parameter></paramdef>

+  <paramdef>char<parameter> **argv</parameter></paramdef>

+  <paramdef>int<parameter> argc</parameter></paramdef>

+  <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>window_name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window name,

+which should be a null-terminated string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>icon_name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the icon name,

+which should be a null-terminated string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>icon_pixmap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the bitmap that is to be used for the icon or

+<function>None</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>argv</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the application's argument list.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>argc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of arguments.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hints</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a pointer to the size hints for the window in its normal state.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetStandardProperties</function>

+function provides a means by which simple applications set the

+most essential properties with a single call.

+<function>XSetStandardProperties</function>

+should be used to give a window manager some information about 

+your program's preferences. 

+It should not be used by applications that need

+to communicate more information than is possible with

+<function>XSetStandardProperties</function>.

+(Typically, argv is the argv array of your main program.)

+If the strings are not in the Host Portable Character Encoding,

+the result is implementation-dependent.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetStandardProperties</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadWindow </function>

+errors.

+<!-- .SH -->

+</para>

+<para>

+Setting and Getting Window Sizing Hints

+</para>

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to set or get window sizing hints.

+The functions discussed in this section use the flags and the

+<function>XSizeHints </function>

+structure, as defined in the

+<!-- .hN X11/Xutil.h -->

+header file and use the WM_NORMAL_HINTS property.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the size hints for a given window in its normal state, use

+<function>XSetNormalHints</function>.

+This function has been superseded by

+<function>XSetWMNormalHints</function>.

+<indexterm significance="preferred"><primary>XSetNormalHints</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetNormalHints</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hints</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a pointer to the size hints for the window in its normal state.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetNormalHints</function>

+function sets the size hints structure for the specified window.

+Applications use

+<function>XSetNormalHints</function>

+to inform the window manager of the size

+or position desirable for that window.

+In addition, 

+an application that wants to move or resize itself should call

+<function>XSetNormalHints</function>

+and specify its new desired location and size

+as well as making direct Xlib calls to move or resize.  

+This is because window managers may ignore redirected

+configure requests, but they pay attention to property changes.

+</para>

+<para>

+<!-- .LP -->

+To set size hints, 

+an application not only must assign values to the appropriate members

+in the hints structure but also must set the flags member of the structure 

+to indicate which information is present and where it came from.  

+A call to

+<function>XSetNormalHints</function>

+is meaningless, unless the flags member is set to indicate which members of

+the structure have been assigned values.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetNormalHints</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To return the size hints for a window in its normal state, use

+<function>XGetNormalHints</function>.

+This function has been superseded by

+<function>XGetWMNormalHints</function>.

+<indexterm significance="preferred"><primary>XGetNormalHints</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XGetNormalHints</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hints_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the size hints for the window in its normal state.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetNormalHints</function>

+function returns the size hints for a window in its normal state.

+It returns a nonzero status if it succeeds or zero if

+the application specified no normal size hints for this window.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetNormalHints</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+The next two functions set and read the WM_ZOOM_HINTS property.

+</para>

+<para>

+<!-- .LP -->

+To set the zoom hints for a window, use

+<function>XSetZoomHints</function>.

+This function is no longer supported by the

+<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.

+<indexterm significance="preferred"><primary>XSetZoomHints</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetZoomHints</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XSizeHints<parameter> *zhints</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>zhints</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a pointer to the zoom hints.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Many window managers think of windows in one of three states:

+iconic, normal, or zoomed.

+The

+<function>XSetZoomHints</function>

+function provides the window manager with information for the window in the

+zoomed state.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetZoomHints</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To read the zoom hints for a window, use

+<function>XGetZoomHints</function>.

+This function is no longer supported by the

+<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.

+<indexterm significance="preferred"><primary>XGetZoomHints</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XGetZoomHints</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XSizeHints<parameter> *zhints_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>zhints_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the zoom hints.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetZoomHints</function>

+function returns the size hints for a window in its zoomed state.

+It returns a nonzero status if it succeeds or zero if

+the application specified no zoom size hints for this window.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetZoomHints</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the value of any property of type WM_SIZE_HINTS, use

+<function>XSetSizeHints</function>.

+This function has been superseded by

+<function>XSetWMSizeHints</function>.

+<indexterm significance="preferred"><primary>XSetSizeHints</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetSizeHints</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>

+  <paramdef>Atom<parameter> property</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hints</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a pointer to the size hints.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>property</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the property name.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetSizeHints</function>

+function sets the

+<function>XSizeHints</function>

+structure for the named property and the specified window.

+This is used by

+<function>XSetNormalHints</function>

+and

+<function>XSetZoomHints</function>

+and can be used to set the value of any property of type WM_SIZE_HINTS.

+Thus, it may be useful if other properties of that type get defined.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetSizeHints</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadAtom</function>,

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To read the value of any property of type WM_SIZE_HINTS, use

+<function>XGetSizeHints</function>.

+This function has been superseded by

+<function>XGetWMSizeHints</function>.

+<indexterm significance="preferred"><primary>XGetSizeHints</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XGetSizeHints</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef>

+  <paramdef>Atom<parameter> property</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hints_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the size hints.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>property</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the property name.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetSizeHints</function>

+function returns the

+<function>XSizeHints</function>

+structure for the named property and the specified window.

+This is used by

+<function>XGetNormalHints</function>

+and

+<function>XGetZoomHints</function>.

+It also can be used to retrieve the value of any property of type

+WM_SIZE_HINTS.

+Thus, it may be useful if other properties of that type get defined.

+<function>XGetSizeHints</function>

+returns a nonzero status if a size hint was defined

+or zero otherwise.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetSizeHints</function>

+can generate

+<function>BadAtom</function>

+and 

+<function>BadWindow </function>

+errors.

+<!-- .SH -->

+Getting and Setting an XStandardColormap Structure

+</para>

+<para>

+<!-- .LP -->

+To get the 

+<function>XStandardColormap </function>

+structure associated with one of the described atoms, use

+<function>XGetStandardColormap</function>.

+This function has been superseded by

+<function>XGetRGBColormap</function>.

+<indexterm significance="preferred"><primary>XGetStandardColormap</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XGetStandardColormap</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XStandardColormap<parameter> *colormap_return</parameter></paramdef>

+  <paramdef>Atom<parameter> property</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the colormap associated with the specified atom.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>property</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the property name.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetStandardColormap</function>

+function returns the colormap definition associated with the atom supplied

+as the property argument.

+<function>XGetStandardColormap</function>

+returns a nonzero status if successful and zero otherwise.

+For example,

+to fetch the standard

+<function>GrayScale</function>

+colormap for a display,

+you use

+<function>XGetStandardColormap</function>

+with the following syntax:

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 1.5i -->

+<!-- .ta .5i 1.5i -->

+XGetStandardColormap(dpy, DefaultRootWindow(dpy), &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>.

+<indexterm significance="preferred"><primary>XSetStandardColormap</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetStandardColormap</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XStandardColormap<parameter> *colormap</parameter></paramdef>

+  <paramdef>Atom<parameter> property</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>property</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the property name.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetStandardColormap</function>

+function usually is only used by window or session managers.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetStandardColormap</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadAtom</function>,

+<function>BadDrawable</function>,

+and

+<function>BadWindow </function>

+errors.

+<!-- .SH -->

+Parsing Window Geometry

+</para>

+<para>

+<!-- .LP -->

+To parse window geometry given a user-specified position 

+and a default position, use

+<function>XGeometry</function>.

+This function has been superseded by

+<function>XWMGeometry</function>.

+<indexterm><primary>Window</primary><secondary>determining location</secondary></indexterm>

+<indexterm significance="preferred"><primary>XGeometry</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> XGeometry</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> screen</parameter></paramdef>

+  <paramdef>char*position,<parameter> *default_position</parameter></paramdef>

+  <paramdef>unsignedint<parameter> bwidth</parameter></paramdef>

+  <paramdef>unsignedintfwidth,<parameter> fheight</parameter></paramdef>

+  <paramdef>intxadder,<parameter> yadder</parameter></paramdef>

+  <paramdef>int*x_return,<parameter> *y_return</parameter></paramdef>

+  <paramdef>int*width_return,<parameter> *height_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the screen.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>position</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>default_position</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the geometry specifications.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>bwidth</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the border width.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>fheight</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>fwidth</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the font height and width in pixels (increment size).

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>xadder</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>yadder</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify additional interior padding needed in the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Return the x and y offsets.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Return the width and height determined.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+You pass in the border width (bwidth),

+size of the increments fwidth and fheight

+(typically font width and height),

+and any additional interior space (xadder and yadder)

+to make it easy to compute the resulting size.

+The

+<function>XGeometry </function>

+function returns the position the window should be placed given a position and

+a default position.

+<function>XGeometry</function>

+determines the placement of

+a window using a geometry specification as specified by

+<function>XParseGeometry </function>

+and the additional information about the window.

+Given a fully qualified default geometry specification and

+an incomplete geometry specification, 

+<function>XParseGeometry</function>

+returns a bitmask value as defined above in the 

+<function>XParseGeometry</function>

+call,

+by using the position argument.

+</para>

+<para>

+<!-- .LP -->

+The returned width and height will be the width and height specified

+by default_position as overridden by any user-specified position.

+They are not affected by fwidth, fheight, xadder, or yadder.

+The x and y coordinates are computed by using the border width,

+the screen width and height, padding as specified by xadder and yadder,

+and the fheight and fwidth times the width and height from the

+geometry specifications.

+<!-- .SH -->

+</para>

+<para>

+Getting the X Environment Defaults

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XGetDefault</function>

+function provides a primitive interface to the resource manager facilities 

+discussed in chapter 15. <!-- xref -->

+It is only useful in very simple applications.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<indexterm significance="preferred"><primary>XGetDefault</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> *XGetDefault</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>char<parameter> *program</parameter></paramdef>

+  <paramdef>char<parameter> *option</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>program</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the program name for the Xlib defaults (usually argv[0] 

+of the main program).

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>option</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the option name.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetDefault</function>

+function returns the value of the resource <emphasis remap='I'>prog</emphasis>.<emphasis remap='I'>option</emphasis>,

+where <emphasis remap='I'>prog</emphasis> is the program argument with the directory prefix removed

+and <emphasis remap='I'>option</emphasis> must be a single component.

+Note that multilevel resources cannot be used with

+<function>XGetDefault</function>.

+The class "Program.Name" is always used for the resource lookup.

+If the specified option name does not exist for this program,

+<function>XGetDefault</function>

+returns NULL.

+The strings returned by

+<function>XGetDefault</function>

+are owned by Xlib and should not be modified or freed by the client.

+</para>

+<para>

+<!-- .LP -->

+If a database has been set with 

+<function>XrmSetDatabase</function>,

+that database is used for the lookup.

+Otherwise, a database is created

+and is set in the display (as if by calling 

+<function>XrmSetDatabase</function>).

+The database is created in the current locale.

+To create a database,

+<function>XGetDefault</function>

+uses resources from the RESOURCE_MANAGER property on the root

+window of screen zero.

+If no such property exists,

+a resource file in the user's home directory is used.

+On a <acronym>POSIX</acronym>-conformant system,

+this file is

+<function>"$HOME/.Xdefaults"</function>.

+<indexterm><primary>Files</primary><secondary>$HOME/.Xdefaults</secondary></indexterm>

+After loading these defaults,

+<function>XGetDefault</function>

+merges additional defaults specified by the XENVIRONMENT

+environment variable.

+If XENVIRONMENT is defined,

+it contains a full path name for the additional resource file.

+If XENVIRONMENT is not defined,

+<function>XGetDefault</function>

+looks for

+"$HOME/.Xdefaults-<emphasis remap='I'>name</emphasis>" ,

+where <emphasis remap='I'>name</emphasis> specifies the name of the machine on which the application

+is running.

+<!-- .SH -->

+X Version 10 Compatibility Functions

+</para>

+<para>

+<!-- .LP -->

+You can use the X Version 10 compatibility functions to:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Draw and fill polygons and curves

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Associate user data with a value

+<!-- .SH -->

+Drawing and Filling Polygons and Curves

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to draw or fill

+arbitrary polygons or curves.  

+These functions are provided mainly for compatibility with X Version 10 

+and have no server support.  

+That is, they call other Xlib functions, not the server directly.  

+Thus, if you just have straight lines to draw, using 

+<function>XDrawLines </function>

+<indexterm><primary>XDrawLines</primary></indexterm>

+or

+<function>XDrawSegments </function>

+<indexterm><primary>XDrawSegments</primary></indexterm>

+is much faster.

+</para>

+<para>

+<!-- .LP -->

+The functions discussed here provide all the functionality of the 

+X Version 10 functions 

+<function>XDraw</function>,

+<indexterm ><primary>X10 compatibility</primary><secondary>XDraw</secondary></indexterm>

+<function>XDrawFilled</function>,

+<indexterm><primary>X10 compatibility</primary><secondary>XDrawFilled</secondary></indexterm>

+<function>XDrawPatterned</function>,

+<indexterm ><primary>X10 compatibility</primary><secondary>XDrawPatterned</secondary></indexterm>

+<function>XDrawDashed</function>,

+<indexterm><primary>X10 compatibility</primary><secondary>XDrawDashed</secondary></indexterm>

+and

+<function>XDrawTiled</function>.

+<indexterm><primary>X10 compatibility</primary><secondary>XDrawTiled</secondary></indexterm>

+They are as compatible as possible given X Version 11's new line-drawing 

+functions.  

+One thing to note, however, is that

+<function>VertexDrawLastPoint </function>

+is no longer supported. 

+Also, the error status returned is the opposite of what it was under 

+X Version 10 (this is the X Version 11 standard error status).  

+<function>XAppendVertex </function>

+and 

+<function>XClearVertexFlag </function>

+from X Version 10 also are not supported.

+</para>

+<para>

+<!-- .LP -->

+Just how the graphics context you use is set up actually

+determines whether you get dashes or not, and so on.  

+Lines are properly joined if they connect and include

+the closing of a closed figure  (see 

+<function>XDrawLines</function>).

+The functions discussed here fail (return zero) only if they run out of memory

+or are passed a 

+<function>Vertex </function>

+list that has a 

+<function>Vertex </function>

+with 

+<function>VertexStartClosed</function>

+set that is not followed by a 

+<function>Vertex </function>

+with 

+<function>VertexEndClosed </function>

+set.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To achieve the effects of the X Version 10

+<function>XDraw</function>,

+<indexterm ><primary>X10 compatibility</primary><secondary>XDraw</secondary></indexterm>

+<function>XDrawDashed</function>,

+<indexterm><primary>X10 compatibility</primary><secondary>XDrawDashed</secondary></indexterm>

+and 

+<function>XDrawPatterned</function>,

+<indexterm ><primary>X10 compatibility</primary><secondary>XDrawPatterned</secondary></indexterm>

+use

+<function>XDraw</function>.

+</para>

+

+<para>

+#include &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 -->

+<indexterm significance="preferred"><primary>Vertex</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 1.5i -->

+<!-- .ta .5i 1.5i -->

+typedef struct _Vertex {

+	short x,y;

+	unsigned short flags;

+} Vertex;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The x and y members are the coordinates of the vertex 

+that are relative to either the upper left inside corner of the drawable 

+(if 

+<function>VertexRelative </function>

+is zero) or the previous vertex (if 

+<function>VertexRelative </function>

+is one).

+</para>

+<para>

+<!-- .LP -->

+The flags, as defined in 

+<!-- .hN X11/X10.h ,  -->

+are as follows:

+<indexterm significance="preferred"><primary>VertexRelative</primary></indexterm>

+<indexterm significance="preferred"><primary>VertexDontDraw</primary></indexterm>

+<indexterm significance="preferred"><primary>VertexCurved</primary></indexterm>

+<indexterm significance="preferred"><primary>VertexStartClosed</primary></indexterm>

+<indexterm significance="preferred"><primary>VertexEndClosed</primary></indexterm>

+<!-- .sM -->

+</para>

+

+<literallayout class="monospaced">

+VertexRelative     0x0001     /* else absolute */

+VertexDontDraw     0x0002     /* else draw */

+VertexCurved       0x0004     /* else straight */

+VertexStartClosed  0x0008     /* else not */

+VertexEndClosed    0x0010     /* else not */

+</literallayout>

+

+<itemizedlist>

+  <listitem>

+    <para>

+If 

+<function>VertexRelative </function>

+is not set,  

+the coordinates are absolute (that is, relative to the drawable's origin).  

+The first vertex must be an absolute vertex.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If

+<function>VertexDontDraw </function>

+is one, 

+no line or curve is drawn from the previous vertex to this one.  

+This is analogous to picking up the pen and moving to another place 

+before drawing another line.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If 

+<function>VertexCurved </function>

+is one, 

+a spline algorithm is used to draw a smooth curve from the previous vertex

+through this one to the next vertex.  

+Otherwise, a straight line is drawn from the previous vertex to this one.  

+It makes sense to set 

+<function>VertexCurved </function>

+to one only if a previous and next vertex are both defined

+(either explicitly in the array or through the definition of a closed 

+curve).

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It is permissible for 

+<function>VertexDontDraw </function>

+bits and 

+<function>VertexCurved</function>

+bits both to be one. 

+This is useful if you want to define the previous point for the smooth curve

+but do not want an actual curve drawing to start until this point.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If 

+<function>VertexStartClosed </function>

+is one, 

+then this point marks the beginning of a closed curve.  

+This vertex must be followed later in the array by another vertex 

+whose effective coordinates are identical

+and that has a

+<function>VertexEndClosed </function>

+bit of one.

+The points in between form a cycle to determine predecessor 

+and successor vertices for the spline algorithm.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+This function uses these GC components:

+function, plane-mask, line-width, line-style, cap-style, join-style,

+fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and

+clip-mask.

+It also uses these GC mode-dependent components: 

+foreground, background, tile, stipple,

+tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and dash-list.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To achieve the effects of the X Version 10

+<function>XDrawTiled </function>

+<indexterm><primary>X10 compatibility</primary><secondary>XDrawTiled</secondary></indexterm>

+and 

+<function>XDrawFilled</function>,

+<indexterm><primary>X10 compatibility</primary><secondary>XDrawFilled</secondary></indexterm>

+use

+<function>XDrawFilled</function>.

+</para>

+

+<para>#include &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.

+<indexterm><primary>Hash Lookup</primary></indexterm>

+<indexterm><primary>Window</primary><secondary>IDs</secondary></indexterm>

+<indexterm><primary>Resource IDs</primary></indexterm>

+Application programs often need to be able to easily refer to

+their own data structures when an event arrives.

+The 

+<function>XAssocTable</function>

+system provides users of the X library with a method

+for associating their own data structures with X resources

+(<function>Pixmaps</function>,

+<function>Fonts</function>,

+<function>Windows</function>,

+and so on).

+</para>

+<para>

+<!-- .LP -->

+An 

+<function>XAssocTable</function>

+can be used to type X resources.  

+For example, the user

+may want to have three or four types of windows,

+each with different properties. 

+This can be accomplished by associating each X window ID

+with a pointer to a window property data structure  defined  by  the

+user.

+A generic type has been defined in the X library for resource IDs.

+It is called an XID.

+</para>

+<para>

+<!-- .LP -->

+There are a few  guidelines  that  should be observed when using an

+<function>XAssocTable :</function>

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+All  XIDs  are  relative  to  the  specified display.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Because  of  the  hashing  scheme  used  by  the  association mechanism,

+the following rules for determining the size of a

+<function>XAssocTable</function>

+should be followed.  

+Associations will be  made  and  looked  up  more

+efficiently  if  the  table  size  (number  of  buckets in the hashing

+system) is a power of two and if there are not more than 8 XIDs  per

+bucket.

+    </para>

+  </listitem>

+</itemizedlist>

+

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To return a pointer to a new

+<function>XAssocTable</function>,

+use 

+<function>XCreateAssocTable</function>.

+<indexterm significance="preferred"><primary>XCreateAssocTable</primary></indexterm>

+<!-- .sM -->

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XAssocTable<function> *XCreateAssocTable</function></funcdef>

+  <paramdef>int<parameter> size</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>size</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of buckets in the hash system of

+<function>XAssocTable</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The size argument specifies the number of buckets in the 

+hash system of

+<function>XAssocTable</function>.

+For  reasons  of  efficiency  the number of buckets

+should be a power of two.

+Some size  suggestions  might  be:  use  32 buckets  per  100  objects,

+and a reasonable maximum number of objects per buckets is 8.

+If  an  error  allocating  memory  for  the

+<function>XAssocTable </function>

+occurs, 

+a NULL pointer is returned. 

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To create an entry in a given 

+<function>XAssocTable</function>,

+use 

+<function>XMakeAssoc</function>.

+<indexterm significance="preferred"><primary>XMakeAssoc</primary></indexterm>

+<!-- .sM -->

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XMakeAssoc</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XAssocTable<parameter> *table</parameter></paramdef>

+  <paramdef>XID<parameter> x_id</parameter></paramdef>

+  <paramdef>char<parameter> *data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>table</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the assoc table. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x_id</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the X resource ID.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the data to be associated with the X resource ID.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XMakeAssoc</function>

+function inserts data into an 

+<function>XAssocTable</function>

+keyed on an XID.

+Data is inserted into the table only once.

+Redundant inserts are ignored.

+The queue in each association bucket is sorted from the lowest XID to 

+the highest XID.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain data from a given 

+<function>XAssocTable</function>,

+use 

+<function>XLookUpAssoc</function>.

+<indexterm significance="preferred"><primary>XLookUpAssoc</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> *XLookUpAssoc</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XAssocTable<parameter> *table</parameter></paramdef>

+  <paramdef>XID<parameter> x_id</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>table</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the assoc table. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x_id</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the X resource ID.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XLookUpAssoc</function>

+function retrieves the data stored in an 

+<function>XAssocTable</function>

+by its XID.  

+If  an appropriately  matching XID can be found in the table,

+<function>XLookUpAssoc</function>

+returns the data associated with it.

+If the x_id cannot be found in the table,

+it returns NULL.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To delete an entry from a given 

+<function>XAssocTable</function>,

+use 

+<function>XDeleteAssoc</function>.

+<indexterm significance="preferred"><primary>XDeleteAssoc</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDeleteAssoc</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XAssocTable<parameter> *table</parameter></paramdef>

+  <paramdef>XID<parameter> x_id</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>table</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the assoc table. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x_id</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the X resource ID.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XDeleteAssoc</function>

+function deletes an association in an 

+<function>XAssocTable</function>

+keyed on its XID.

+Redundant deletes (and deletes of nonexistent XIDs) are ignored.

+Deleting associations in no way impairs the performance of an 

+<function>XAssocTable</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To free the memory associated with a given 

+<function>XAssocTable</function>,

+use 

+<function>XDestroyAssocTable</function>.

+</para>

+<indexterm significance="preferred"><primary>XDestroyAssocTable</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDestroyAssocTable</function></funcdef>

+  <paramdef>XAssocTable<parameter> *table</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>table</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the assoc table. 

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</appendix>

diff --git a/libX11/specs/libX11/CH01 b/libX11/specs/libX11/CH01.xml
index 765e4b5fb..0e86e7496 100644
--- a/libX11/specs/libX11/CH01
+++ b/libX11/specs/libX11/CH01.xml
@@ -1,663 +1,825 @@
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-.\" OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" Except as contained in this notice, the name of the X Consortium shall
-.\" not be used in advertising or otherwise to promote the sale, use or
-.\" other dealings in this Software without prior written authorization
-.\" from the X Consortium.
-.\"
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
-.\" Digital Equipment Corporation
-.\"
-.\" Portions Copyright \(co 1990, 1991 by
-.\" Tektronix, Inc.
-.\"
-.\" Permission to use, copy, modify and distribute this documentation for
-.\" any purpose and without fee is hereby granted, provided that the above
-.\" copyright notice appears in all copies and that both that copyright notice
-.\" and this permission notice appear in all copies, and that the names of
-.\" Digital and Tektronix not be used in in advertising or publicity pertaining
-.\" to this documentation without specific, written prior permission.
-.\" Digital and Tektronix makes no representations about the suitability
-.\" of this documentation for any purpose.
-.\" It is provided ``as is'' without express or implied warranty.
-.\" 
-.EH '\fBXlib \- C Library\fP''\fB\*(xV\fP'
-.OH '\fBXlib \- C Library\fP''\fB\*(xV\fP'
-.EF ''\fB % \fP''
-.OF ''\fB % \fP''
-.hw WM_NORMAL_HINTS
-\&
-.sp 1
-.ce 3
-\s+1\fBChapter 1\fP\s-1
-
-\s+1\fBIntroduction to Xlib\fP\s-1
-.sp 2
-.if \n(GS .nr nh*hl 1
-.nr H1 1
-.nr H2 0
-.nr H3 0
-.nr H4 0
-.nr H5 0
-.na
-.LP
-.XS
-Chapter 1: Introduction to Xlib
-.XE
-The X Window System is a network-transparent window system
-that was designed at MIT.
-X display servers run on computers with either monochrome or color
-bitmap display hardware.
-The server distributes user input to and accepts output requests from various
-client programs located either on the same machine or elsewhere in
-the network.
-Xlib is a C subroutine library that application programs (clients)
-use to interface with the window system by means of a stream connection.
-Although a client usually runs on the same machine as the X server 
-it is talking to, this need not be the case.
-.LP
-\fIXlib \- C Language X Interface\fP is a reference guide to the low-level 
-C language interface to the X Window System protocol.
-It is neither a tutorial nor a user's guide to programming the X Window System.
-Rather, it provides a detailed description of each function in the library
-as well as a discussion of the related background information.
-\fIXlib \- C Language X Interface\fP assumes a basic understanding of a graphics 
-window system and of the C programming language.
-Other higher-level abstractions
-(for example, those provided by the toolkits for X)
-are built on top of the Xlib library.
-For further information about these higher-level libraries,
-see the appropriate toolkit documentation.
-The \fIX Window System Protocol\fP provides the definitive word on the
-behavior of X.
-Although additional information appears here,
-the protocol document is the ruling document.
-.LP
-To provide an introduction to X programming,
-this chapter discusses:
-.IP \(bu 5
-Overview of the X Window System
-.IP \(bu 5
-Errors
-.IP \(bu 5
-Standard header files
-.IP \(bu 5
-Generic values and types
-.IP \(bu 5
-Naming and argument conventions within Xlib
-.IP \(bu 5
-Programming considerations
-.IP \(bu 5
-Character sets and encodings
-.IP \(bu 5
-Formatting conventions
-.NH 2
-Overview of the X Window System
-.XS
-\*(SN Overview of the X Window System
-.XE
-.LP
-Some of the terms used in this book are unique to X,
-and other terms that are common to other window systems 
-have different meanings in X.
-You may find it helpful to refer to the glossary, 
-which is located at the end of the book.
-.LP
-The X Window System supports one or more screens containing
-overlapping windows or subwindows.
-A screen is a physical monitor and hardware
-that can be color, grayscale, or monochrome.
-There can be multiple screens for each display or workstation.
-A single X server can provide display services for any number of screens.
-A set of screens for a single user with one keyboard and one pointer
-(usually a mouse) is called a display.
-.LP
-.IN "Screen"
-All the windows in an X server are arranged in strict hierarchies.
-At the top of each hierarchy is a root window,
-which covers each of the display screens.
-Each root window is partially or completely covered by child windows.
-All windows, except for root windows, have parents.
-There is usually at least one window for each application program.
-.IN "Child window"
-.IN "Parent Window"
-Child windows may in turn have their own children.
-In this way, 
-an application program can create an arbitrarily deep tree 
-on each screen.
-X provides graphics, text, and raster operations for windows.
-.LP
-A child window can be larger than its parent. 
-That is, part or all of
-the child window can extend beyond the boundaries of the parent,
-but all output to a window is clipped by its parent.
-.IN "Stacking order"
-If several children of a window have overlapping locations, 
-one of the children is considered to be on top of or raised over the
-others, thus obscuring them.
-Output to areas covered by other windows is suppressed by the window
-system unless the window has backing store.
-If a window is obscured by a second window, 
-the second window obscures only those ancestors of the second window
-that are also ancestors of the first window.
-.LP
-.IN "Window" "" "@DEF@"
-A window has a border zero or more pixels in width, which can
-be any pattern (pixmap) or solid color you like.
-A window usually but not always has a background pattern,
-which will be repainted by the window system when uncovered.
-Child windows obscure their parents,
-and graphic operations in the parent window usually
-are clipped by the children.
-.LP
-Each window and pixmap has its own coordinate system.
-The coordinate system has the X axis horizontal and the Y axis vertical
-with the origin [0, 0] at the upper-left corner.
-Coordinates are integral,
-in terms of pixels,
-and coincide with pixel centers.
-For a window, 
-the origin is inside the border at the inside, upper-left corner.
-.LP
-X does not guarantee to preserve the contents of windows. 
-When part or all of a window is hidden and then brought back onto the screen,
-its contents may be lost. 
-The server then sends the client program an
-.PN Expose
-event to notify it that part or all of the window needs to be repainted.
-Programs must be prepared to regenerate the contents of windows on demand.
-.LP
-.IN "Pixmap"
-.IN "Drawable"
-.IN "Tile"
-.IN "Bitmap"
-X also provides off-screen storage of graphics objects,
-called pixmaps.
-Single plane (depth 1) pixmaps are sometimes referred to as bitmaps.
-Pixmaps can be used in most graphics functions interchangeably with
-windows and are used in various graphics operations to define patterns or tiles.
-Windows and pixmaps together are referred to as drawables.
-.LP
-Most of the functions in Xlib just add requests to an output buffer.
-These requests later execute asynchronously on the X server.
-Functions that return values of information stored in
-the server do not return (that is, they block)
-until an explicit reply is received or an error occurs.
-You can provide an error handler,
-which will be called when the error is reported.
-.LP
-.IN "XSync"
-If a client does not want a request to execute asynchronously, 
-it can follow the request with a call to 
-.PN XSync , 
-which blocks until all previously buffered
-asynchronous events have been sent and acted on.
-As an important side effect, 
-the output buffer in Xlib is always flushed by a call to any function
-that returns a value from the server or waits for input.
-.LP
-.IN "Resource IDs"
-.IN "Resource IDs" "Window"
-.IN "Resource IDs" "Font"
-.IN "Resource IDs" "Pixmap"
-.IN "Resource IDs" "Cursor"
-.IN "Resource IDs" "GContext"
-Many Xlib functions will return an integer resource ID,
-which allows you to refer to objects stored on the X server.
-These can be of type 
-.PN Window , 
-.PN Font , 
-.PN Pixmap , 
-.PN Colormap ,
-.PN Cursor , 
-and 
-.PN GContext ,
-as defined in the file
-.hN X11/X.h .
-These resources are created by requests and are destroyed
-(or freed) by requests or when connections are closed.
-Most of these resources are potentially sharable between
-applications, and in fact, windows are manipulated explicitly by
-window manager programs.
-Fonts and cursors are shared automatically across multiple screens.
-Fonts are loaded and unloaded as needed and are shared by multiple clients.
-Fonts are often cached in the server.
-Xlib provides no support for sharing graphics contexts between applications.
-.LP
-.IN "Event"
-Client programs are informed of events.
-Events may either be side effects of a request (for example, restacking windows
-generates 
-.PN Expose 
-events) or completely asynchronous (for example, from the keyboard).
-A client program asks to be informed of events.
-Because other applications can send events to your application,
-programs must be prepared to handle (or ignore) events of all types.
-.LP
-Input events (for example, a key pressed or the pointer moved) 
-arrive asynchronously from the server and are queued until they are 
-requested by an explicit call (for example,
-.PN XNextEvent
-or
-.PN XWindowEvent ).
-In addition, some library
-functions (for example,
-.PN XRaiseWindow )
-generate 
-.PN Expose
-and
-.PN ConfigureRequest
-events.
-These events also arrive asynchronously, but the client may
-.IN "XSync"
-wish to explicitly wait for them by calling
-.PN XSync
-after calling a function that can cause the server to generate events.
-.NH 2
-Errors
-.XS
-\*(SN Errors
-.XE
-.LP
-Some functions return 
-.PN Status , 
-an integer error indication.
-If the function fails, it returns a zero.
-If the function returns a status of zero,
-it has not updated the return arguments.
-.IN "Status"
-Because C does not provide multiple return values, 
-many functions must return their results by writing into client-passed storage. 
-.IN "Error" "handling"
-By default, errors are handled either by a standard library function
-or by one that you provide.
-Functions that return pointers to strings return NULL pointers if
-the string does not exist.
-.LP
-The X server reports protocol errors at the time that it detects them.
-If more than one error could be generated for a given request,
-the server can report any of them.
-.LP
-Because Xlib usually does not transmit requests to the server immediately
-(that is, it buffers them), errors can be reported much later than they
-actually occur.
-For debugging purposes, however,
-Xlib provides a mechanism for forcing synchronous behavior 
-(see section 11.8.1).
-When synchronization is enabled, 
-errors are reported as they are generated.
-.LP
-When Xlib detects an error,
-it calls an error handler,
-which your program can provide.
-If you do not provide an error handler,
-the error is printed, and your program terminates.
-.NH 2
-Standard Header Files
-.XS
-\*(SN Standard Header Files
-.XE
-.LP
-The following include files are part of the Xlib standard:
-.IP \(bu 5
-.hN X11/Xlib.h
-.IP
-This is the main header file for Xlib.
-The majority of all Xlib symbols are declared by including this file.
-This file also contains the preprocessor symbol
-.PN XlibSpecificationRelease .
-.IN "XlibSpecificationRelease" "" "@DEF@"
-This symbol is defined to have the 6 in this release of the standard.
-(Release 5 of Xlib was the first release to have this symbol.)
-.IP \(bu 5
-.hN X11/X.h
-.IP
-This file declares types and constants for the X protocol that are
-to be used by applications.
-It is included automatically from
-.hN X11/Xlib.h ,
-so application code should never need to reference this file directly.
-.IP \(bu 5
-.hN X11/Xcms.h
-.IP
-This file contains symbols for much of the color management facilities
-described in chapter 6.
-All functions, types, and symbols with the prefix ``Xcms'',
-plus the Color Conversion Contexts macros, are declared in this file.
-.hN X11/Xlib.h
-must be included before including this file.
-.IP \(bu 5
-.hN X11/Xutil.h
-.IP
-This file declares various functions, types, and symbols used for
-inter-client communication and application utility functions,
-which are described in chapters 14 and 16.
-.hN X11/Xlib.h
-must be included before including this file.
-.IP \(bu 5
-.hN X11/Xresource.h
-.IP
-This file declares all functions, types, and symbols for the
-resource manager facilities, which are described in chapter 15.
-.hN X11/Xlib.h
-must be included before including this file.
-.IP \(bu 5
-.hN X11/Xatom.h
-.IP
-This file declares all predefined atoms, 
-which are symbols with the prefix ``XA_''.
-.IP \(bu 5
-.hN X11/cursorfont.h
-.IP
-This file declares the cursor symbols for the standard cursor font,
-which are listed in appendix B.
-All cursor symbols have the prefix ``XC_''.
-.IP \(bu 5
-.hN X11/keysymdef.h
-.IP
-This file declares all standard KeySym values,
-which are symbols with the prefix ``XK_''.
-The KeySyms are arranged in groups, and a preprocessor symbol controls
-inclusion of each group.  The preprocessor symbol must be defined
-prior to inclusion of the file to obtain the associated values.
-The preprocessor symbols are XK_MISCELLANY, XK_XKB_KEYS, XK_3270,
-XK_LATIN1, XK_LATIN2,
-XK_LATIN3, XK_LATIN4, XK_KATAKANA, XK_ARABIC, XK_CYRILLIC, XK_GREEK,
-XK_TECHNICAL, XK_SPECIAL, XK_PUBLISHING, XK_APL, XK_HEBREW,
-XK_THAI, and XK_KOREAN.
-.IP \(bu 5
-.hN X11/keysym.h
-.IP
-This file defines the preprocessor symbols
-XK_MISCELLANY, XK_XKB_KEYS, XK_LATIN1, XK_LATIN2, XK_LATIN3,
-XK_LATIN4, and XK_GREEK
-and then includes
-.hN X11/keysymdef.h .
-.IP \(bu 5
-.hN X11/Xlibint.h
-.IP
-This file declares all the functions, types, and symbols used for
-extensions, which are described in appendix C.
-This file automatically includes
-.hN X11/Xlib.h .
-.IP \(bu 5
-.hN X11/Xproto.h
-.IP
-This file declares types and symbols for the basic X protocol,
-for use in implementing extensions.
-It is included automatically from
-.hN X11/Xlibint.h ,
-so application and extension code should never need to
-reference this file directly.
-.IP \(bu 5
-.hN X11/Xprotostr.h
-.IP
-This file declares types and symbols for the basic X protocol,
-for use in implementing extensions.
-It is included automatically from
-.hN X11/Xproto.h ,
-so application and extension code should never need to
-reference this file directly.
-.IP \(bu 5
-.hN X11/X10.h
-.IP
-This file declares all the functions, types, and symbols used for the
-X10 compatibility functions, which are described in appendix D.
-.NH 2
-Generic Values and Types
-.XS
-\*(SN Generic Values and Types
-.XE
-.LP
-The following symbols are defined by Xlib and used throughout the manual:
-.IN "Bool" "" "@DEF@"
-.IN "True" "" "@DEF@"
-.IN "False" "" "@DEF@"
-.IP \(bu 5
-Xlib defines the type
-.PN Bool
-and the Boolean values
-.PN True
-and
-.PN False .
-.IN "None" "" "@DEF@"
-.IP \(bu 5
-.PN None
-is the universal null resource ID or atom.
-.IN "XID" "" "@DEF@"
-.IP \(bu 5
-The type
-.PN XID
-is used for generic resource IDs.
-.IN "XPointer" "" "@DEF@"
-.IP \(bu 5
-The type
-.PN XPointer
-is defined to be char\^* and is used as a generic opaque pointer to data.
-.NH 2
-Naming and Argument Conventions within Xlib
-.XS
-\*(SN Naming and Argument Conventions within Xlib
-.XE
-.LP
-Xlib follows a number of conventions for the naming and syntax of the functions.
-Given that you remember what information the function requires,
-these conventions are intended to make the syntax of the functions more 
-predictable.
-.LP
-The major naming conventions are:
-.IP \(bu 5
-To differentiate the X symbols from the other symbols,
-the library uses mixed case for external symbols.
-It leaves lowercase for variables and all uppercase for user macros,
-as per existing convention.
-.IP \(bu 5
-All Xlib functions begin with a capital X.
-.IP \(bu 5
-The beginnings of all function names and symbols are capitalized.
-.IP \(bu 5
-All user-visible data structures begin with a capital X.
-More generally,
-anything that a user might dereference begins with a capital X.
-.IP \(bu 5
-Macros and other symbols do not begin with a capital X.
-To distinguish them from all user symbols,
-each word in the macro is capitalized.
-.IP \(bu 5
-All elements  of or variables in a data structure are in lowercase.
-Compound words, where needed, are constructed with underscores (\^_\^).
-.IP \(bu 5
-The display argument, where used, is always first in the argument list.
-.IP \(bu 5
-All resource objects, where used, occur at the beginning of the argument list
-immediately after the display argument.
-.IP \(bu 5
-When a  graphics context is present together with
-another type of resource (most commonly, a drawable), the
-graphics context occurs in the argument list after the other
-resource.
-Drawables outrank all other resources.
-.IP \(bu 5
-Source arguments always precede the destination arguments in the argument list.
-.IP \(bu 5
-The x argument always precedes the y argument in the argument list.
-.IP \(bu 5
-The width argument always precedes the height argument in the argument list.
-.IP \(bu 5
-Where the x, y, width, and height arguments are used together,
-the x and y arguments always precede the width and height arguments.
-.IP \(bu 5
-Where a mask is accompanied with a structure,
-the mask always precedes the pointer to the structure in the argument list.
-.NH 2
-Programming Considerations
-.XS
-\*(SN Programming Considerations
-.XE
-.LP
-The major programming considerations are:
-.IP \(bu 5
-Coordinates and sizes in X are actually 16-bit quantities.
-This decision was made to minimize the bandwidth required for a
-given level of performance.
-Coordinates usually are declared as an
-.PN int 
-in the interface.
-Values larger than 16 bits are truncated silently.
-Sizes (width and height) are declared as unsigned quantities.
-.IP \(bu 5
-Keyboards are the greatest variable between different
-manufacturers' workstations.
-If you want your program to be portable,
-you should be particularly conservative here.
-.IP \(bu 5
-Many display systems have limited amounts of off-screen memory.
-If you can, you should minimize use of pixmaps and backing
-store.
-.IP \(bu 5
-The user should have control of his screen real estate.
-Therefore, you should write your applications to react to window management
-rather than presume control of the entire screen.
-What you do inside of your top-level window, however,
-is up to your application.
-For further information,
-see chapter 14
-and the \fIInter-Client Communication Conventions Manual\fP.
-.NH 2
-Character Sets and Encodings
-.XS
-\*(SN Character Sets and Encodings
-.XE
-.LP
-Some of the Xlib functions make reference to specific character sets
-and character encodings.
-The following are the most common:
-.IP \(bu 5
-X Portable Character Set
-.IP
-A basic set of 97 characters, 
-which are assumed to exist in all locales supported by Xlib.
-This set contains the following characters:
-.IP
-.Ds 0
-.EQ
-delim DD
-.EN
-a..z A..Z 0..9
-!"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~
-<space>, <tab>, and <newline>
-.EQ
-delim %%
-.EN
-.De
-.IP
-This set is the left/lower half
-of the graphic character set of ISO8859-1 plus space, tab, and newline.
-It is also the set of graphic characters in 7-bit ASCII plus the same
-three control characters.
-The actual encoding of these characters on the host is system dependent.
-.IP \(bu 5
-Host Portable Character Encoding
-.IP
-The encoding of the X Portable Character Set on the host.
-The encoding itself is not defined by this standard,
-but the encoding must be the same in all locales supported by Xlib on the host.
-If a string is said to be in the Host Portable Character Encoding,
-then it only contains characters from the X Portable Character Set,
-in the host encoding.
-.IP \(bu 5
-Latin-1
-.IP
-The coded character set defined by the ISO8859-1 standard.
-.IP \(bu 5
-Latin Portable Character Encoding
-.IP
-The encoding of the X Portable Character Set using the Latin-1 codepoints
-plus ASCII control characters.
-If a string is said to be in the Latin Portable Character Encoding,
-then it only contains characters from the X Portable Character Set,
-not all of Latin-1.
-.IP \(bu 5
-STRING Encoding
-.IP
-Latin-1, plus tab and newline.
-.IP \(bu 5
-POSIX Portable Filename Character Set
-.IP
-The set of 65 characters, 
-which can be used in naming files on a POSIX-compliant host,
-that are correctly processed in all locales.
-The set is:
-.IP
-.Ds 0
-a..z A..Z 0..9 ._-
-.De
-.NH 2
-Formatting Conventions
-.XS
-\*(SN Formatting Conventions
-.XE
-.LP
-\fIXlib \- C Language X Interface\fP uses the following conventions:
-.IP \(bu 5
-Global symbols are printed in 
-.PN this 
-.PN special 
-.PN font .
-These can be either function names,
-symbols defined in include files, or structure names.
-When declared and defined,
-function arguments are printed in \fIitalics\fP.
-In the explanatory text that follows,
-they usually are printed in regular type.
-.IP \(bu 5
-Each function is introduced by a general discussion that 
-distinguishes it from other functions.
-The function declaration itself follows,
-and each argument is specifically explained.
-Although ANSI C function prototype syntax is not used,
-Xlib header files normally declare functions using function prototypes
-in ANSI C environments.
-General discussion of the function, if any is required,
-follows the arguments.
-Where applicable, 
-the last paragraph of the explanation lists the possible 
-Xlib error codes that the function can generate.
-For a complete discussion of the Xlib error codes,
-see section 11.8.2.
-.IP \(bu 5
-To eliminate any ambiguity between those arguments that you pass and those that 
-a function returns to you,
-the explanations for all arguments that you pass start with the word
-\fIspecifies\fP or, in the case of multiple arguments, the word \fIspecify\^\fP.
-The explanations for all arguments that are returned to you start with the
-word \fIreturns\fP or, in the case of multiple arguments, the word \fIreturn\^\fP.
-The explanations for all arguments that you can pass and are returned start
-with the words \fIspecifies and returns\^\fP.
-.IP \(bu 5
-Any pointer to a structure that is used to return a value is designated as 
-such by the \fI_return\fP suffix as part of its name.
-All other pointers passed to these functions are
-used for reading only.
-A few arguments use pointers to structures that are used for
-both input and output and are indicated by using the \fI_in_out\fP suffix.
-.bp
+<chapter><title>Introduction to Xlib</title>

+

+<para>

+The X Window System is a network-transparent window system that was designed at MIT. X

+display servers run on computers with either monochrome or color bitmap display hardware. The

+server distributes user input to and accepts output requests from various client programs located

+either on the same machine or elsewhere in the network. Xlib is a C subroutine library that appli-

+cation programs (clients) use to interface with the window system by means of a stream connec-

+tion. Although a client usually runs on the same machine as the X server it is talking to, this need

+not be the case.

+</para>

+<para>

+Xlib − C Language X Interface is a reference guide to the low-level C language interface to the X

+Window System protocol. It is neither a tutorial nor a user’s guide to programming the X Win-

+dow System. Rather, it provides a detailed description of each function in the library as well as a

+discussion of the related background information. Xlib − C Language X Interface assumes a

+basic understanding of a graphics window system and of the C programming language. Other

+higher-level abstractions (for example, those provided by the toolkits for X) are built on top of the

+Xlib library. For further information about these higher-level libraries, see the appropriate toolkit

+documentation. The X Window System Protocol provides the definitive word on the behavior of

+X. Although additional information appears here, the protocol document is the ruling document.

+</para>

+<para>

+To provide an introduction to X programming, this chapter discusses:

+</para>

+

+<itemizedlist>

+  <listitem><para>Overview of the X Window System</para></listitem>

+  <listitem><para>Errors</para></listitem>

+  <listitem><para>Standard header files</para></listitem>

+  <listitem><para>Generic values and types</para></listitem>

+  <listitem><para>Naming and argument conventions within Xlib</para></listitem>

+  <listitem><para>Programming considerations</para></listitem>

+  <listitem><para>Character sets and encodings</para></listitem>

+  <listitem><para>Formatting conventions</para></listitem>

+</itemizedlist>

+

+

+<sect1 id="Overview_of_the_X_Window_System">

+<title>Overview of the X Window System</title>

+<!-- .XS -->

+<!-- (SN Overview of the X Window System -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Some of the terms used in this book are unique to X,

+and other terms that are common to other window systems 

+have different meanings in X.

+You may find it helpful to refer to the glossary, 

+which is located at the end of the book.

+</para>

+<para>

+<!-- .LP -->

+The X Window System supports one or more screens containing

+overlapping windows or subwindows.

+A screen is a physical monitor and hardware

+that can be color, grayscale, or monochrome.

+There can be multiple screens for each display or workstation.

+A single X server can provide display services for any number of screens.

+A set of screens for a single user with one keyboard and one pointer

+(usually a mouse) is called a display.

+</para>

+<para>

+<!-- .LP -->

+<indexterm><primary>Screen</primary></indexterm>

+All the windows in an X server are arranged in strict hierarchies.

+At the top of each hierarchy is a root window,

+which covers each of the display screens.

+Each root window is partially or completely covered by child windows.

+All windows, except for root windows, have parents.

+There is usually at least one window for each application program.

+<indexterm><primary>Child window</primary></indexterm>

+<indexterm><primary>Parent Window</primary></indexterm>

+Child windows may in turn have their own children.

+In this way, 

+an application program can create an arbitrarily deep tree 

+on each screen.

+X provides graphics, text, and raster operations for windows.

+</para>

+<para>

+<!-- .LP -->

+A child window can be larger than its parent. 

+That is, part or all of

+the child window can extend beyond the boundaries of the parent,

+but all output to a window is clipped by its parent.

+<indexterm><primary>Stacking order</primary></indexterm>

+If several children of a window have overlapping locations, 

+one of the children is considered to be on top of or raised over the

+others, thus obscuring them.

+Output to areas covered by other windows is suppressed by the window

+system unless the window has backing store.

+If a window is obscured by a second window, 

+the second window obscures only those ancestors of the second window

+that are also ancestors of the first window.

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>Window</primary></indexterm>

+A window has a border zero or more pixels in width, which can

+be any pattern (pixmap) or solid color you like.

+A window usually but not always has a background pattern,

+which will be repainted by the window system when uncovered.

+Child windows obscure their parents,

+and graphic operations in the parent window usually

+are clipped by the children.

+</para>

+<para>

+<!-- .LP -->

+Each window and pixmap has its own coordinate system.

+The coordinate system has the X axis horizontal and the Y axis vertical

+with the origin [0, 0] at the upper-left corner.

+Coordinates are integral,

+in terms of pixels,

+and coincide with pixel centers.

+For a window, 

+the origin is inside the border at the inside, upper-left corner.

+</para>

+<para>

+<!-- .LP -->

+X does not guarantee to preserve the contents of windows. 

+When part or all of a window is hidden and then brought back onto the screen,

+its contents may be lost. 

+The server then sends the client program an

+<function>Expose</function>

+event to notify it that part or all of the window needs to be repainted.

+Programs must be prepared to regenerate the contents of windows on demand.

+</para>

+<para>

+<!-- .LP -->

+<indexterm><primary>Pixmap</primary></indexterm>

+<indexterm><primary>Drawable</primary></indexterm>

+<indexterm><primary>Tile</primary></indexterm>

+<indexterm><primary>Bitmap</primary></indexterm>

+X also provides off-screen storage of graphics objects,

+called pixmaps.

+Single plane (depth 1) pixmaps are sometimes referred to as bitmaps.

+Pixmaps can be used in most graphics functions interchangeably with

+windows and are used in various graphics operations to define patterns or tiles.

+Windows and pixmaps together are referred to as drawables.

+</para>

+<para>

+<!-- .LP -->

+Most of the functions in Xlib just add requests to an output buffer.

+These requests later execute asynchronously on the X server.

+Functions that return values of information stored in

+the server do not return (that is, they block)

+until an explicit reply is received or an error occurs.

+You can provide an error handler,

+which will be called when the error is reported.

+</para>

+<para>

+<!-- .LP -->

+<indexterm><primary>XSync</primary></indexterm>

+If a client does not want a request to execute asynchronously, 

+it can follow the request with a call to 

+<function>XSync</function>,

+which blocks until all previously buffered

+asynchronous events have been sent and acted on.

+As an important side effect, 

+the output buffer in Xlib is always flushed by a call to any function

+that returns a value from the server or waits for input.

+</para>

+<para>

+<!-- .LP -->

+<indexterm><primary>Resource IDs</primary></indexterm>

+<indexterm><primary>Resource IDs</primary><secondary>Window</secondary></indexterm>

+<indexterm><primary>Resource IDs</primary><secondary>Font</secondary></indexterm>

+<indexterm><primary>Resource IDs</primary><secondary>Pixmap</secondary></indexterm>

+<indexterm><primary>Resource IDs</primary><secondary>Cursor</secondary></indexterm>

+<indexterm><primary>Resource IDs</primary><secondary>GContext</secondary></indexterm>

+Many Xlib functions will return an integer resource ID,

+which allows you to refer to objects stored on the X server.

+These can be of type 

+<function>Window</function>,

+<function>Font</function>,

+<function>Pixmap</function>,

+<function>Colormap</function>,

+<function>Cursor</function>,

+and 

+<function>GContext</function>,

+as defined in the file

+<!-- .hN X11/X.h . -->

+These resources are created by requests and are destroyed

+(or freed) by requests or when connections are closed.

+Most of these resources are potentially sharable between

+applications, and in fact, windows are manipulated explicitly by

+window manager programs.

+Fonts and cursors are shared automatically across multiple screens.

+Fonts are loaded and unloaded as needed and are shared by multiple clients.

+Fonts are often cached in the server.

+Xlib provides no support for sharing graphics contexts between applications.

+</para>

+<para>

+<!-- .LP -->

+<indexterm><primary>Event</primary></indexterm>

+Client programs are informed of events.

+Events may either be side effects of a request (for example, restacking windows

+generates 

+<function>Expose </function>

+events) or completely asynchronous (for example, from the keyboard).

+A client program asks to be informed of events.

+Because other applications can send events to your application,

+programs must be prepared to handle (or ignore) events of all types.

+</para>

+<para>

+<!-- .LP -->

+Input events (for example, a key pressed or the pointer moved) 

+arrive asynchronously from the server and are queued until they are 

+requested by an explicit call (for example,

+<function>XNextEvent</function>

+or

+<function>XWindowEvent</function>).

+In addition, some library

+functions (for example,

+<function>XRaiseWindow</function>)

+generate 

+<function>Expose</function>

+and

+<function>ConfigureRequest</function>

+events.

+These events also arrive asynchronously, but the client may

+<indexterm><primary>XSync</primary></indexterm>

+wish to explicitly wait for them by calling

+<function>XSync</function>

+after calling a function that can cause the server to generate events.

+</para>

+</sect1>

+<sect1 id="Errors">

+<title>Errors</title>

+<!-- .XS -->

+<!-- (SN Errors -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Some functions return 

+<function>Status</function>,

+an integer error indication.

+If the function fails, it returns a zero.

+If the function returns a status of zero,

+it has not updated the return arguments.

+<indexterm><primary>Status</primary></indexterm>

+Because C does not provide multiple return values, 

+many functions must return their results by writing into client-passed storage. 

+<indexterm><primary>Error</primary><secondary>handling</secondary></indexterm>

+By default, errors are handled either by a standard library function

+or by one that you provide.

+Functions that return pointers to strings return NULL pointers if

+the string does not exist.

+</para>

+<para>

+<!-- .LP -->

+The X server reports protocol errors at the time that it detects them.

+If more than one error could be generated for a given request,

+the server can report any of them.

+</para>

+<para>

+<!-- .LP -->

+Because Xlib usually does not transmit requests to the server immediately

+(that is, it buffers them), errors can be reported much later than they

+actually occur.

+For debugging purposes, however,

+Xlib provides a mechanism for forcing synchronous behavior 

+(see section 11.8.1). <!-- xref -->

+When synchronization is enabled, 

+errors are reported as they are generated.

+</para>

+<para>

+<!-- .LP -->

+When Xlib detects an error,

+it calls an error handler,

+which your program can provide.

+If you do not provide an error handler,

+the error is printed, and your program terminates.

+</para>

+</sect1>

+<sect1 id="Standard_Header_Files">

+<title>Standard Header Files</title>

+<!-- .XS -->

+<!-- (SN Standard Header Files -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The following include files are part of the Xlib standard:

+</para>

+<!-- .IP \(bu 5 -->

+<!-- .hN X11/Xlib.h -->

+<!-- .IP -->

+

+<variablelist>

+  <varlistentry>

+    <term>&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

+<function>XlibSpecificationRelease</function>.

+<indexterm significance="preferred"><primary>XlibSpecificationRelease</primary></indexterm>

+This symbol is defined to have the 6 in this release of the standard.

+(Release 5 of Xlib was the first release to have this symbol.)

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>&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

+&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", <!-- xref -->

+plus the Color Conversion Contexts macros, are declared in this file.

+&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. <!-- 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.

+&lt;X11/Xlib.h&gt; <!-- xref -->

+must be included before including this file.

+      </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_".

+      </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_".

+      </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_".

+The KeySyms are arranged in groups, and a preprocessor symbol controls

+inclusion of each group.  The preprocessor symbol must be defined

+prior to inclusion of the file to obtain the associated values.

+The preprocessor symbols are <function>XK_MISCELLANY, XK_XKB_KEYS, XK_3270,

+XK_LATIN1, XK_LATIN2, XK_LATIN3, XK_LATIN4, XK_KATAKANA, XK_ARABIC, 

+XK_CYRILLIC, XK_GREEK, XK_TECHNICAL, XK_SPECIAL, XK_PUBLISHING, XK_APL, 

+XK_HEBREW, XK_THAI, and XK_KOREAN</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>&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 &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

+&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

+&lt;X11/Xlibint.h&lt;,

+so application and extension code should never need to

+reference this file directly.

+      </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

+&lt;X11/Xproto.h&lt;,

+so application and extension code should never need to

+reference this file directly.

+      </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.

+      </para>

+    </listitem>

+  </varlistentry>

+</variablelist>

+</sect1>

+

+

+

+<sect1 id="Generic_Values_and_Types">

+<title>Generic Values and Types</title>

+<!-- .XS -->

+<!-- (SN Generic Values and Types -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The following symbols are defined by Xlib and used throughout the manual:

+<indexterm significance="preferred"><primary>Bool</primary></indexterm>

+<indexterm significance="preferred"><primary>True</primary></indexterm>

+<indexterm significance="preferred"><primary>False</primary></indexterm>

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Xlib defines the type

+<function>Bool</function>

+and the Boolean values

+<function>True</function>

+and

+<function>False</function>.

+<indexterm significance="preferred"><primary>None</primary></indexterm>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>None</function>

+is the universal null resource ID or atom.

+<indexterm significance="preferred"><primary>XID</primary></indexterm>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The type

+<function>XID</function>

+is used for generic resource IDs.

+<indexterm significance="preferred"><primary>XPointer</primary></indexterm>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The type

+<function>XPointer</function>

+is defined to be char\^* and is used as a generic opaque pointer to data.

+    </para>

+  </listitem>

+</itemizedlist>

+</sect1>

+<sect1 id="Naming_and_Argument_Conventions_within_Xlib">

+<title>Naming and Argument Conventions within Xlib</title>

+<!-- .XS -->

+<!-- (SN Naming and Argument Conventions within Xlib -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib follows a number of conventions for the naming and syntax of the functions.

+Given that you remember what information the function requires,

+these conventions are intended to make the syntax of the functions more 

+predictable.

+</para>

+<para>

+<!-- .LP -->

+The major naming conventions are:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+To differentiate the X symbols from the other symbols,

+the library uses mixed case for external symbols.

+It leaves lowercase for variables and all uppercase for user macros,

+as per existing convention.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+All Xlib functions begin with a capital X.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The beginnings of all function names and symbols are capitalized.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+All user-visible data structures begin with a capital X.

+More generally,

+anything that a user might dereference begins with a capital X.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Macros and other symbols do not begin with a capital X.

+To distinguish them from all user symbols,

+each word in the macro is capitalized.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+All elements  of or variables in a data structure are in lowercase.

+Compound words, where needed, are constructed with underscores (_).

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The display argument, where used, is always first in the argument list.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+All resource objects, where used, occur at the beginning of the argument list

+immediately after the display argument.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+When a  graphics context is present together with

+another type of resource (most commonly, a drawable), the

+graphics context occurs in the argument list after the other

+resource.

+Drawables outrank all other resources.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Source arguments always precede the destination arguments in the argument list.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The x argument always precedes the y argument in the argument list.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The width argument always precedes the height argument in the argument list.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Where the x, y, width, and height arguments are used together,

+the x and y arguments always precede the width and height arguments.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Where a mask is accompanied with a structure,

+the mask always precedes the pointer to the structure in the argument list.

+    </para>

+  </listitem>

+</itemizedlist>

+</sect1>

+<sect1 id="Programming_Considerations">

+<title>Programming Considerations</title>

+<!-- .XS -->

+<!-- (SN Programming Considerations -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The major programming considerations are:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Coordinates and sizes in X are actually 16-bit quantities.

+This decision was made to minimize the bandwidth required for a

+given level of performance.

+Coordinates usually are declared as an

+<function>int </function>

+in the interface.

+Values larger than 16 bits are truncated silently.

+Sizes (width and height) are declared as unsigned quantities.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Keyboards are the greatest variable between different

+manufacturers' workstations.

+If you want your program to be portable,

+you should be particularly conservative here.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Many display systems have limited amounts of off-screen memory.

+If you can, you should minimize use of pixmaps and backing

+store.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The user should have control of his screen real estate.

+Therefore, you should write your applications to react to window management

+rather than presume control of the entire screen.

+What you do inside of your top-level window, however,

+is up to your application.

+For further information,

+see chapter 14 <!-- xref -->

+and the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.

+    </para>

+  </listitem>

+</itemizedlist>

+</sect1>

+<sect1 id="Character_Sets_and_Encodings">

+<title>Character Sets and Encodings</title>

+<!-- .XS -->

+<!-- (SN Character Sets and Encodings -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Some of the Xlib functions make reference to specific character sets

+and character encodings.

+The following are the most common:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+X Portable Character Set

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A basic set of 97 characters, 

+which are assumed to exist in all locales supported by Xlib.

+This set contains the following characters:

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+a..z A..Z 0..9 !"#$%&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.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Host Portable Character Encoding

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The encoding of the X Portable Character Set on the host.

+The encoding itself is not defined by this standard,

+but the encoding must be the same in all locales supported by Xlib on the host.

+If a string is said to be in the Host Portable Character Encoding,

+then it only contains characters from the X Portable Character Set,

+in the host encoding.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Latin-1

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The coded character set defined by the ISO8859-1 standard.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Latin Portable Character Encoding

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The encoding of the X Portable Character Set using the Latin-1 codepoints

+plus ASCII control characters.

+If a string is said to be in the Latin Portable Character Encoding,

+then it only contains characters from the X Portable Character Set,

+not all of Latin-1.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+STRING Encoding

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Latin-1, plus tab and newline.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<acronym>POSIX</acronym> Portable Filename Character Set

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The set of 65 characters, 

+which can be used in naming files on a <acronym>POSIX</acronym>-compliant host,

+that are correctly processed in all locales.

+The set is:

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<literallayout class="monospaced">

+a..z A..Z 0..9 ._-

+</literallayout>

+    </para>

+  </listitem>

+</itemizedlist>

+</sect1>

+<sect1 id="Formatting_Conventions">

+<title>Formatting Conventions</title>

+<!-- .XS -->

+<!-- (SN Formatting Conventions -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<emphasis remap='I'>Xlib \- C Language X Interface</emphasis> uses the following conventions:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Global symbols are printed in 

+<function>this </function>

+<function>special </function>

+<function>font</function>.

+These can be either function names,

+symbols defined in include files, or structure names.

+When declared and defined,

+function arguments are printed in <emphasis remap='I'>italics</emphasis>.

+In the explanatory text that follows,

+they usually are printed in regular type.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Each function is introduced by a general discussion that 

+distinguishes it from other functions.

+The function declaration itself follows,

+and each argument is specifically explained.

+Although ANSI C function prototype syntax is not used,

+Xlib header files normally declare functions using function prototypes

+in ANSI C environments.

+General discussion of the function, if any is required,

+follows the arguments.

+Where applicable, 

+the last paragraph of the explanation lists the possible 

+Xlib error codes that the function can generate.

+For a complete discussion of the Xlib error codes,

+see section 11.8.2. <!-- xref -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+To eliminate any ambiguity between those arguments that you pass and those that 

+a function returns to you,

+the explanations for all arguments that you pass start with the word

+<emphasis remap='I'>specifies</emphasis> or, in the case of multiple arguments, the word <emphasis remap='I'>specify\^</emphasis>.

+The explanations for all arguments that are returned to you start with the

+word <emphasis remap='I'>returns</emphasis> or, in the case of multiple arguments, the word <emphasis remap='I'>return\^</emphasis>.

+The explanations for all arguments that you can pass and are returned start

+with the words <emphasis remap='I'>specifies and returns\^</emphasis>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Any pointer to a structure that is used to return a value is designated as 

+such by the <emphasis remap='I'>_return</emphasis> suffix as part of its name.

+All other pointers passed to these functions are

+used for reading only.

+A few arguments use pointers to structures that are used for

+both input and output and are indicated by using the <emphasis remap='I'>_in_out</emphasis> suffix.

+<!-- .bp -->

+    </para>

+  </listitem>

+</itemizedlist>

+</sect1>

+</chapter>

diff --git a/libX11/specs/libX11/CH02 b/libX11/specs/libX11/CH02
deleted file mode 100644
index dbf0b4850..000000000
--- a/libX11/specs/libX11/CH02
+++ /dev/null
@@ -1,2051 +0,0 @@
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996, 2000 The Open Group
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-.\" OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" Except as contained in this notice, the name of The Open Group shall
-.\" not be used in advertising or otherwise to promote the sale, use or
-.\" other dealings in this Software without prior written authorization
-.\" from The Open Group.
-.\"
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
-.\" Digital Equipment Corporation
-.\"
-.\" Portions Copyright \(co 1990, 1991 by
-.\" Tektronix, Inc.
-.\"
-.\" Permission to use, copy, modify and distribute this documentation for
-.\" any purpose and without fee is hereby granted, provided that the above
-.\" copyright notice appears in all copies and that both that copyright notice
-.\" and this permission notice appear in all copies, and that the names of
-.\" Digital and Tektronix not be used in in advertising or publicity pertaining
-.\" to this documentation without specific, written prior permission.
-.\" Digital and Tektronix makes no representations about the suitability
-.\" of this documentation for any purpose.
-.\" It is provided ``as is'' without express or implied warranty.
-.\" 
-\&
-.sp 1
-.ce 3
-\s+1\fBChapter 2\fP\s-1
-
-\s+1\fBDisplay Functions\fP\s-1
-.sp 2
-.nr H1 2
-.nr H2 0
-.nr H3 0
-.nr H4 0
-.nr H5 0
-.na
-.LP
-.XS
-Chapter 2: Display Functions
-.XE
-Before your program can use a display, you must establish a connection
-to the X server.
-Once you have established a connection,
-you then can use the Xlib macros and functions discussed in this chapter
-to return information about the display.
-This chapter discusses how to:
-.IP \(bu 5
-Open (connect to) the display
-.IP \(bu 5
-Obtain information about the display, image formats, or screens
-.IP \(bu 5
-Generate a
-.PN NoOperation
-protocol request
-.IP \(bu 5
-Free client-created data
-.IP \(bu 5
-Close (disconnect from) a display
-.IP \(bu 5
-Use X Server connection close operations
-.IP \(bu 5
-Use Xlib with threads
-.IP \(bu 5
-Use internal connections
-.NH 2
-Opening the Display
-.XS
-\*(SN Opening the Display
-.XE
-.LP
-To open a connection to the X server that controls a display, use
-.PN XOpenDisplay .
-.IN "XOpenDisplay" "" "@DEF@"
-.LP
-.sM
-.FD 0
-Display *XOpenDisplay\^(\^\fIdisplay_name\fP\^)
-.br
-      char *\fIdisplay_name\fP\^;
-.FN	
-.IP \fIdisplay_name\fP 1i
-Specifies the hardware display name, which determines the display
-and communications domain to be used.
-On a POSIX-conformant system, if the display_name is NULL, 
-it defaults to the value of the DISPLAY environment variable. 
-.IN "Environment" "DISPLAY"
-.LP
-.eM
-The encoding and interpretation of the display name are
-implementation-dependent.
-Strings in the Host Portable Character Encoding are supported;
-support for other characters is implementation-dependent.
-On POSIX-conformant systems,
-the display name or DISPLAY environment variable can be a string in the format:
-.LP
-.sM
-.Ds 0
-.TA 1i
-.ta 1i
-	\fIprotocol\fP\^/\^\fIhostname\fP\^:\^\fInumber\fP\^.\^\fIscreen_number\fP
-.De
-.IP \fIprotocol\fP 1i
-Specifies a protocol family or an alias for a protocol family.  Supported 
-protocol families are implementation dependent.  The protocol entry is 
-optional.  If protocol is not specified, the / separating protocol and 
-hostname must also not be specified.
-.IP \fIhostname\fP 1i
-Specifies the name of the host machine on which the display is physically
-attached.
-You follow the hostname with either a single colon (:) or a double colon (::).
-.IP \fInumber\fP 1i
-Specifies the number of the display server on that host machine.
-You may optionally follow this display number with a period (.).
-A single CPU can have more than one display.
-Multiple displays are usually numbered starting with zero.
-.IN "Screen"
-.IP \fIscreen_number\fP 1i
-Specifies the screen to be used on that server.
-Multiple screens can be controlled by a single X server.
-The screen_number sets an internal variable that can be accessed by
-using the 
-.PN DefaultScreen 
-macro or the 
-.PN XDefaultScreen
-function if you are using languages other than C (see section 2.2.1).
-.LP
-.eM
-For example, the following would specify screen 1 of display 0 on the 
-machine named ``dual-headed'':
-.LP
-.Ds
-dual-headed:0.1
-.De
-.LP
-The
-.PN XOpenDisplay
-function returns a 
-.PN Display 
-structure that serves as the
-connection to the X server and that contains all the information
-about that X server.
-.PN XOpenDisplay
-connects your application to the X server through TCP 
-or DECnet communications protocols,
-or through some local inter-process communication protocol.
-.IN "Protocol" "TCP"
-.IN "Protocol" "DECnet"
-If the protocol is specified as "tcp", "inet", or "inet6", or
-if no protocol is specified and the hostname is a host machine name and a single colon (:)
-separates the hostname and display number,
-.PN XOpenDisplay
-connects using TCP streams.  (If the protocol is specified as "inet", TCP over
-IPv4 is used.  If the protocol is specified as "inet6", TCP over IPv6 is used.
-Otherwise, the implementation determines which IP version is used.)
-If the hostname and protocol are both not specified,
-Xlib uses whatever it believes is the fastest transport.
-If the hostname is a host machine name and a double colon (::)
-separates the hostname and display number,
-.PN XOpenDisplay
-connects using DECnet.
-A single X server can support any or all of these transport mechanisms
-simultaneously.
-A particular Xlib implementation can support many more of these transport
-mechanisms.
-.LP
-.IN "Display"
-If successful, 
-.PN XOpenDisplay 
-returns a pointer to a 
-.PN Display 
-structure,
-which is defined in 
-.hN X11/Xlib.h .
-If 
-.PN XOpenDisplay 
-does not succeed, it returns NULL.
-After a successful call to
-.PN XOpenDisplay ,
-all of the screens in the display can be used by the client.
-The screen number specified in the display_name argument is returned 
-by the 
-.PN DefaultScreen
-macro (or the
-.PN XDefaultScreen
-function).
-You can access elements of the
-.PN Display
-and
-.PN Screen
-structures only by using the information macros or functions.
-For information about using macros and functions to obtain information from 
-the
-.PN Display 
-structure,
-see section 2.2.1.
-.LP
-X servers may implement various types of access control mechanisms
-(see section 9.8).
-.NH 2
-Obtaining Information about the Display, Image Formats, or Screens
-.XS
-\*(SN Obtaining Information about the Display, Image Formats, or Screens
-.XE
-.LP
-The Xlib library provides a number of useful macros 
-and corresponding functions that return data from the 
-.PN Display 
-structure.
-The macros are used for C programming, 
-and their corresponding function equivalents are for other language bindings.
-This section discusses the:
-.IP \(bu 5
-Display macros
-.IP \(bu 5
-Image format functions and macros
-.IP \(bu 5
-Screen information macros
-.LP
-.IN "Display" "data structure" 
-All other members of the 
-.PN Display 
-structure (that is, those for which no macros are defined) are private to Xlib 
-and must not be used.
-Applications must never directly modify or inspect these private members of the 
-.PN Display 
-structure.
-.NT Note
-The
-.PN XDisplayWidth ,
-.PN XDisplayHeight ,
-.PN XDisplayCells ,
-.PN XDisplayPlanes ,
-.PN XDisplayWidthMM ,
-and
-.PN XDisplayHeightMM
-functions in the next sections are misnamed.
-These functions really should be named Screen\fIwhatever\fP 
-and XScreen\fIwhatever\fP, not Display\fIwhatever\fP or XDisplay\fIwhatever\fP.
-Our apologies for the resulting confusion.
-.NE
-.NH 3
-Display Macros 
-.XS
-\*(SN Display Macros
-.XE
-.LP
-Applications should not directly modify any part of the
-.PN Display
-and
-.PN Screen
-structures.
-The members should be considered read-only,
-although they may change as the result of other operations on the display.
-.LP 
-The following lists the C language macros,
-their corresponding function equivalents that are for other language bindings,
-and what data both can return.
-.LP
-.sp
-.sM
-.FD 0
-AllPlanes
-.sp
-unsigned long XAllPlanes(\^) 
-.FN
-.LP
-.eM
-.IN "AllPlanes" "" "@DEF@"
-.IN "XAllPlanes" "" "@DEF@"
-Both return a value with all bits set to 1 suitable for use in a plane argument to
-a procedure.
-.LP
-.sp
-Both 
-.PN BlackPixel 
-and 
-.PN WhitePixel 
-can be used in implementing a monochrome application.
-These pixel values are for permanently allocated entries in the default
-colormap.
-The actual RGB (red, green, and blue) values are settable on some screens 
-and, in any case, may not actually be black or white.
-The names are intended to convey the expected relative intensity of the colors.
-.sM
-.FD 0
-BlackPixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.sp
-unsigned long XBlackPixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIscreen_number\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIscreen_number\fP 1i
-Specifies the appropriate screen number on the host server.
-.LP
-.eM
-.IN "BlackPixel" "" "@DEF@"
-.IN "XBlackPixel" "" "@DEF@"
-Both return the black pixel value for the specified screen.
-.LP
-.sp
-.sM
-.FD 0
-WhitePixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.sp
-unsigned long XWhitePixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIscreen_number\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIscreen_number\fP 1i
-Specifies the appropriate screen number on the host server.
-.LP
-.eM
-.IN "WhitePixel" "" "@DEF@"
-.IN "XWhitePixel" "" "@DEF@"
-Both return the white pixel value for the specified screen. 
-.LP
-.sp
-.sM
-.FD 0
-ConnectionNumber\^(\^\fIdisplay\fP\^)
-.sp
-int XConnectionNumber\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-.IN "ConnectionNumber" "" "@DEF@"
-.IN "XConnectionNumber" "" "@DEF@"
-Both return a connection number for the specified display.
-On a POSIX-conformant system,
-this is the file descriptor of the connection.
-.LP
-.sp
-.sM
-.FD 0
-DefaultColormap\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.sp
-Colormap XDefaultColormap\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIscreen_number\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIscreen_number\fP 1i
-Specifies the appropriate screen number on the host server.
-.LP
-.eM
-.IN "DefaultColormap" "" "@DEF@"
-.IN "XDefaultColormap" "" "@DEF@"
-Both return the default colormap ID for allocation on the specified screen.
-Most routine allocations of color should be made out of this colormap.
-.LP
-.sp
-.sM
-.FD 0
-DefaultDepth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.sp
-int XDefaultDepth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIscreen_number\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIscreen_number\fP 1i
-Specifies the appropriate screen number on the host server.
-.LP
-.eM
-.IN "DefaultDepth" "" "@DEF@"
-.IN "XDefaultDepth" "" "@DEF@"
-Both return the depth (number of planes) of the default root window for the
-specified screen.
-Other depths may also be supported on this screen (see
-.PN XMatchVisualInfo ).
-.LP
-.sp
-.IN "XListDepths" "" "@DEF@"
-To determine the number of depths that are available on a given screen, use
-.PN XListDepths .
-.sM
-.FD 0
-int *XListDepths\^(\^\fIdisplay\fP, \fIscreen_number\fP, \fIcount_return\fP\^)
-.br
-      Display *\fIdisplay\fP;
-.br
-      int \fIscreen_number\fP;
-.br
-      int *\fIcount_return\fP;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIscreen_number\fP 1i
-Specifies the appropriate screen number on the host server.
-.ds Cn depths
-.IP \fIcount_return\fP 1i
-Returns the number of \*(Cn.
-.LP
-.eM
-The
-.PN XListDepths
-function returns the array of depths 
-that are available on the specified screen.
-If the specified screen_number is valid and sufficient memory for the array
-can be allocated,
-.PN XListDepths
-sets count_return to the number of available depths.
-Otherwise, it does not set count_return and returns NULL.
-To release the memory allocated for the array of depths, use
-.PN XFree .
-.LP
-.sp
-.sM
-.FD 0
-DefaultGC\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.sp
-GC XDefaultGC\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIscreen_number\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIscreen_number\fP 1i
-Specifies the appropriate screen number on the host server.
-.LP
-.eM
-.IN "DefaultGC" "" "@DEF@"
-.IN "XDefaultGC" "" "@DEF@"
-Both return the default graphics context for the root window of the 
-specified screen.
-This GC is created for the convenience of simple applications
-and contains the default GC components with the foreground and
-background pixel values initialized to the black and white
-pixels for the screen, respectively.
-You can modify its contents freely because it is not used in any Xlib
-function.
-This GC should never be freed.
-.LP
-.sp
-.sM
-.FD 0
-DefaultRootWindow\^(\^\fIdisplay\fP\^)
-.sp
-Window XDefaultRootWindow\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-.IN "DefaultRootWindow" "" "@DEF@"
-.IN "XDefaultRootWindow" "" "@DEF@"
-Both return the root window for the default screen.
-.LP
-.sp
-.sM
-.FD 0
-DefaultScreenOfDisplay\^(\^\fIdisplay\fP\^)
-.sp
-Screen *XDefaultScreenOfDisplay\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-.IN "DefaultScreenOfDisplay" "" "@DEF@"
-.IN "XDefaultScreenOfDisplay" "" "@DEF@"
-Both return a pointer to the default screen.
-.LP
-.sp
-.sM
-.FD 0
-ScreenOfDisplay\^(\^\fIdisplay\fP, \fIscreen_number\fP\^)
-.sp
-Screen *XScreenOfDisplay\^(\^\fIdisplay\fP, \fIscreen_number\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIscreen_number\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIscreen_number\fP 1i
-Specifies the appropriate screen number on the host server.
-.LP
-.eM
-.IN "ScreenOfDisplay" "" "@DEF@"
-.IN "XScreenOfDisplay" "" "@DEF@"
-Both return a pointer to the indicated screen.
-.LP
-.sp
-.sM
-.FD 0
-DefaultScreen\^(\^\fIdisplay\fP\^)
-.sp
-int XDefaultScreen\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-.IN "DefaultScreen" "" "@DEF@"
-.IN "XDefaultScreen" "" "@DEF@"
-Both return the default screen number referenced by the 
-.PN XOpenDisplay
-function. 
-This macro or function should be used to retrieve the screen number 
-in applications that will use only a single screen.
-.LP
-.sp
-.sM
-.FD 0
-DefaultVisual\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.sp
-Visual *XDefaultVisual\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIscreen_number\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIscreen_number\fP 1i
-Specifies the appropriate screen number on the host server.
-.LP
-.eM
-.IN "DefaultVisual" "" "@DEF@"
-.IN "XDefaultVisual" "" "@DEF@"
-Both return the default visual type for the specified screen.
-For further information about visual types,
-see section 3.1.
-.LP
-.sp
-.sM
-.FD 0
-DisplayCells\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.sp
-int XDisplayCells\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIscreen_number\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIscreen_number\fP 1i
-Specifies the appropriate screen number on the host server.
-.LP
-.eM
-.IN "DisplayCells" "" "@DEF@"
-.IN "XDisplayCells" "" "@DEF@"
-Both return the number of entries in the default colormap.
-.LP
-.sp
-.sM
-.FD 0
-DisplayPlanes\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.sp
-int XDisplayPlanes\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIscreen_number\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIscreen_number\fP 1i
-Specifies the appropriate screen number on the host server.
-.LP
-.eM
-.IN "DisplayPlanes" "" "@DEF@"
-.IN "XDisplayPlanes" "" "@DEF@"
-Both return the depth of the root window of the specified screen.
-For an explanation of depth,
-see the glossary.
-.LP
-.sp
-.sM
-.FD 0
-DisplayString\^(\^\fIdisplay\fP\^)
-.sp
-char *XDisplayString\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-.IN "DisplayString" "" "@DEF@"
-.IN "XDisplayString" "" "@DEF@"
-Both return the string that was passed to 
-.PN XOpenDisplay
-when the current display was opened. 
-On POSIX-conformant systems, 
-if the passed string was NULL, these return the value of
-the DISPLAY environment variable when the current display was opened.
-.IN "POSIX System Call" "fork"
-These are useful to applications that invoke the 
-.PN fork
-system call and want to open a new connection to the same display from the 
-child process as well as for printing error messages.
-.LP
-.sp
-.sM
-.FD 0
-long XExtendedMaxRequestSize(\^\fIdisplay\fP\^)
-	Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-.IN "XExtendedMaxRequestSize" "" "@DEF@"
-The
-.PN XExtendedMaxRequestSize
-function returns zero if the specified display does not support an
-extended-length protocol encoding; otherwise,
-it returns the maximum request size (in 4-byte units) supported
-by the server using the extended-length encoding.
-The Xlib functions
-.PN XDrawLines ,
-.PN XDrawArcs ,
-.PN XFillPolygon ,
-.PN XChangeProperty ,
-.PN XSetClipRectangles ,
-and
-.PN XSetRegion
-will use the extended-length encoding as necessary, if supported
-by the server.  Use of the extended-length encoding in other Xlib
-functions (for example,
-.PN XDrawPoints ,
-.PN XDrawRectangles ,
-.PN XDrawSegments ,
-.PN XFillArcs ,
-.PN XFillRectangles ,
-.PN XPutImage )
-is permitted but not required; an Xlib implementation may choose to
-split the data across multiple smaller requests instead.
-.LP
-.sp
-.sM
-.FD 0
-long XMaxRequestSize(\^\fIdisplay\fP\^)
-	Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-.IN "XMaxRequestSize" "" "@DEF@"
-The
-.PN XMaxRequestSize
-function returns the maximum request size (in 4-byte units) supported
-by the server without using an extended-length protocol encoding.
-Single protocol requests to the server can be no larger than this size
-unless an extended-length protocol encoding is supported by the server.
-The protocol guarantees the size to be no smaller than 4096 units
-(16384 bytes).
-Xlib automatically breaks data up into multiple protocol requests
-as necessary for the following functions:
-.PN XDrawPoints ,
-.PN XDrawRectangles ,
-.PN XDrawSegments ,
-.PN XFillArcs ,
-.PN XFillRectangles ,
-and 
-.PN XPutImage .
-.LP
-.sp
-.sM
-.FD 0
-LastKnownRequestProcessed\^(\^\fIdisplay\fP\^)
-.sp
-unsigned long XLastKnownRequestProcessed\^(\^\fIdisplay\fP\^)
-.br
-     Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-.IN "LastKnownRequestProcessed" "" "@DEF@"
-.IN "XLastKnownRequestProcessed" "" "@DEF@"
-Both extract the full serial number of the last request known by Xlib
-to have been processed by the X server.
-Xlib automatically sets this number when replies, events, and errors
-are received.
-.LP
-.sp
-.sM
-.FD 0
-NextRequest\^(\^\fIdisplay\fP\^)
-.sp
-unsigned long XNextRequest\^(\^\fIdisplay\fP\^)
-.br
-     Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-.IN "NextRequest" "" "@DEF@"
-.IN "XNextRequest" "" "@DEF@"
-Both extract the full serial number that is to be used for the next
-request.
-Serial numbers are maintained separately for each display connection.
-.LP
-.sp
-.sM
-.FD 0
-ProtocolVersion\^(\^\fIdisplay\fP\^)
-.sp
-int XProtocolVersion\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-.IN "ProtocolVersion" "" "@DEF@"
-.IN "XProtocolVersion" "" "@DEF@"
-Both return the major version number (11) of the X protocol associated with 
-the connected display.
-.LP
-.sp
-.sM
-.FD 0
-ProtocolRevision\^(\^\fIdisplay\fP\^)
-.sp
-int XProtocolRevision\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-.IN "ProtocolRevision" "" "@DEF@"
-.IN "XProtocolRevision" "" "@DEF@"
-Both return the minor protocol revision number of the X server.
-.LP
-.sp
-.sM
-.FD 0
-QLength\^(\^\fIdisplay\fP\^)
-.sp
-int XQLength\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-.IN "QLength" "" "@DEF@"
-.IN "XQLength" "" "@DEF@"
-Both return the length of the event queue for the connected display.
-Note that there may be more events that have not been read into
-the queue yet (see
-.PN XEventsQueued ).
-.LP
-.sp
-.sM
-.FD 0
-RootWindow\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.sp
-Window XRootWindow\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIscreen_number\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIscreen_number\fP 1i
-Specifies the appropriate screen number on the host server.
-.LP
-.eM
-.IN "Window" "RootWindow"
-.IN "RootWindow" "" "@DEF@"
-.IN "Window" "XRootWindow"
-.IN "XRootWindow" "" "@DEF@"
-Both return the root window.
-These are useful with functions that need a drawable of a particular screen
-and for creating top-level windows.
-.LP
-.sp
-.sM
-.FD 0
-ScreenCount\^(\^\fIdisplay\fP\^)
-.sp
-int XScreenCount\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-.IN "ScreenCount" "" "@DEF@"
-.IN "XScreenCount" "" "@DEF@"
-Both return the number of available screens.
-.LP
-.sp
-.sM
-.FD 0
-ServerVendor\^(\^\fIdisplay\fP\^)
-.sp
-char *XServerVendor\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-.IN "ServerVendor" "" "@DEF@"
-.IN "XServerVendor" "" "@DEF@"
-Both return a pointer to a null-terminated string that provides
-some identification of the owner of the X server implementation.
-If the data returned by the server is in the Latin Portable Character Encoding,
-then the string is in the Host Portable Character Encoding.
-Otherwise, the contents of the string are implementation-dependent.
-.LP
-.sp
-.sM
-.FD 0
-VendorRelease\^(\^\fIdisplay\fP\^)
-.sp
-int XVendorRelease\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-.IN "VendorRelease" "" "@DEF@"
-.IN "XVendorRelease" "" "@DEF@"
-Both return a number related to a vendor's release of the X server.
-.NH 3
-Image Format Functions and Macros
-.XS
-\*(SN Image Format Functions and Macros
-.XE
-.LP
-Applications are required to present data to the X server
-in a format that the server demands.
-To help simplify applications,
-most of the work required to convert the data is provided by Xlib
-(see sections 8.7 and 16.8).
-.LP
-The
-.PN XPixmapFormatValues
-structure provides an interface to the pixmap format information
-that is returned at the time of a connection setup.
-It contains:
-.LP
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int depth;
-	int bits_per_pixel;
-	int scanline_pad;
-} XPixmapFormatValues;
-.De
-.LP
-.eM
-.sp
-To obtain the pixmap format information for a given display, use
-.PN XListPixmapFormats .
-.IN "XListPixmapFormats" "" "@DEF@"
-.sM
-.FD 0
-XPixmapFormatValues *XListPixmapFormats\^(\^\fIdisplay\fP, \fIcount_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int *\fIcount_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Cn pixmap formats that are supported by the display
-.IP \fIcount_return\fP 1i
-Returns the number of \*(Cn.
-.LP
-.eM
-The
-.PN XListPixmapFormats
-function returns an array of
-.PN XPixmapFormatValues
-structures that describe the types of Z format images supported
-by the specified display.
-If insufficient memory is available,
-.PN XListPixmapFormats
-returns NULL.
-To free the allocated storage for the
-.PN XPixmapFormatValues
-structures, use
-.PN XFree .
-.LP 
-The following lists the C language macros,
-their corresponding function equivalents that are for other language bindings,
-and what data they both return for the specified server and screen.
-These are often used by toolkits as well as by simple applications.
-.LP
-.sp
-.sM
-.FD 0
-ImageByteOrder\^(\^\fIdisplay\fP\^)
-.sp
-int XImageByteOrder\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-.IN "ImageByteOrder" "" "@DEF@"
-.IN "XImageByteOrder" "" "@DEF@"
-Both specify the required byte order for images for each scanline unit in 
-XY format (bitmap) or for each pixel value in 
-Z format.
-The macro or function can return either
-.PN LSBFirst 
-or 
-.PN MSBFirst .
-.LP
-.sp
-.sM
-.FD 0
-BitmapUnit\^(\^\fIdisplay\fP\^)
-.sp
-int XBitmapUnit\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-.IN "BitmapUnit" "" "@DEF@"
-.IN "XBitmapUnit" "" "@DEF@"
-Both return the size of a bitmap's scanline unit in bits.
-The scanline is calculated in multiples of this value.
-.LP
-.sp
-.sM
-.FD 0
-BitmapBitOrder\^(\^\fIdisplay\fP\^)
-.sp
-int XBitmapBitOrder\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-.IN "BitmapBitOrder" "" "@DEF@"
-.IN "XBitmapBitOrder" "" "@DEF@"
-Within each bitmap unit, the left-most bit in the bitmap as displayed
-on the screen is either the least significant or most significant bit in the
-unit.
-This macro or function can return 
-.PN LSBFirst
-or 
-.PN MSBFirst .
-.LP
-.sp
-.sM
-.FD 0
-BitmapPad\^(\^\fIdisplay\fP\^)
-.sp
-int XBitmapPad\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-.IN "BitmapPad" "" "@DEF@"
-.IN "XBitmapPad" "" "@DEF@"
-Each scanline must be padded to a multiple of bits returned
-by this macro or function.
-.LP
-.sp
-.sM
-.FD 0
-DisplayHeight\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.sp
-int XDisplayHeight\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIscreen_number\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIscreen_number\fP 1i
-Specifies the appropriate screen number on the host server.
-.LP
-.eM
-.IN "DisplayHeight" "" "@DEF@"
-.IN "XDisplayHeight" "" "@DEF@"
-Both return an integer that describes the height of the screen
-in pixels.
-.LP
-.sp
-.sM
-.FD 0
-DisplayHeightMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.sp
-int XDisplayHeightMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIscreen_number\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIscreen_number\fP 1i
-Specifies the appropriate screen number on the host server.
-.LP
-.eM
-.IN "DisplayHeightMM" "" "@DEF@"
-.IN "XDisplayHeightMM" "" "@DEF@"
-Both return the height of the specified screen in millimeters.
-.LP
-.sp
-.sM
-.FD 0
-DisplayWidth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.sp
-int XDisplayWidth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIscreen_number\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIscreen_number\fP 1i
-Specifies the appropriate screen number on the host server.
-.LP
-.eM
-.IN "DisplayWidth" "" "@DEF@"
-.IN "XDisplayWidth" "" "@DEF@"
-Both return the width of the screen in pixels.
-.LP
-.sp
-.sM
-.FD 0
-DisplayWidthMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.sp
-int XDisplayWidthMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIscreen_number\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIscreen_number\fP 1i
-Specifies the appropriate screen number on the host server.
-.LP
-.eM
-.IN "DisplayWidthMM" "" "@DEF@"
-.IN "XDisplayWidthMM" "" "@DEF@"
-Both return the width of the specified screen in millimeters.
-.NH 3
-Screen Information Macros
-.XS
-\*(SN Screen Information Macros
-.XE
-.LP
-The following lists the C language macros,
-their corresponding function equivalents that are for other language bindings,
-and what data they both can return.
-These macros or functions all take a pointer to the appropriate screen
-structure.
-.LP
-.sp
-.sM
-.FD 0
-BlackPixelOfScreen\^(\^\fIscreen\fP\^)
-.sp
-unsigned long XBlackPixelOfScreen\^(\^\fIscreen\fP\^)
-.br
-      Screen *\fIscreen\fP\^;
-.FN
-.IP \fIscreen\fP 1i
-Specifies the appropriate 
-.PN Screen
-structure.
-.LP
-.eM
-.IN "BlackPixelOfScreen" "" "@DEF@"
-.IN "XBlackPixelOfScreen" "" "@DEF@"
-Both return the black pixel value of the specified screen.
-.LP
-.sp
-.sM
-.FD 0
-WhitePixelOfScreen\^(\^\fIscreen\fP\^)
-.sp
-unsigned long XWhitePixelOfScreen\^(\^\fIscreen\fP\^)
-.br
-      Screen *\fIscreen\fP\^;
-.FN
-.IP \fIscreen\fP 1i
-Specifies the appropriate 
-.PN Screen
-structure.
-.LP
-.eM
-.IN "WhitePixelOfScreen" "" "@DEF@"
-.IN "XWhitePixelOfScreen" "" "@DEF@"
-Both return the white pixel value of the specified screen.
-.LP
-.sp
-.sM
-.FD 0
-CellsOfScreen\^(\^\fIscreen\fP\^)
-.sp
-int XCellsOfScreen\^(\^\fIscreen\fP\^)
-.br
-      Screen *\fIscreen\fP\^;
-.FN
-.IP \fIscreen\fP 1i
-Specifies the appropriate 
-.PN Screen
-structure.
-.LP
-.eM
-.IN "CellsOfScreen" "" "@DEF@"
-.IN "XCellsOfScreen" "" "@DEF@"
-Both return the number of colormap cells in the default colormap 
-of the specified screen.
-.LP
-.sp
-.sM
-.FD 0
-DefaultColormapOfScreen\^(\^\fIscreen\fP\^)
-.sp
-Colormap XDefaultColormapOfScreen\^(\^\fIscreen\fP\^)
-.br
-      Screen *\fIscreen\fP\^;
-.FN
-.IP \fIscreen\fP 1i
-Specifies the appropriate 
-.PN Screen
-structure.
-.LP
-.eM
-.IN "DefaultColormapOfScreen" "" "@DEF@"
-.IN "XDefaultColormapOfScreen" "" "@DEF@"
-Both return the default colormap of the specified screen.
-.LP
-.sp
-.sM
-.FD 0
-DefaultDepthOfScreen\^(\^\fIscreen\fP\^)
-.sp 
-int XDefaultDepthOfScreen\^(\^\fIscreen\fP\^)
-.br
-      Screen *\fIscreen\fP\^;
-.FN
-.IP \fIscreen\fP 1i
-Specifies the appropriate 
-.PN Screen
-structure.
-.LP
-.eM
-.IN "DefaultDepthOfScreen" "" "@DEF@"
-.IN "XDefaultDepthOfScreen" "" "@DEF@"
-Both return the depth of the root window.
-.LP
-.sp
-.sM
-.FD 0
-DefaultGCOfScreen\^(\^\fIscreen\fP\^)
-.sp
-GC XDefaultGCOfScreen\^(\^\fIscreen\fP\^)
-.br
-      Screen *\fIscreen\fP\^;
-.FN
-.IP \fIscreen\fP 1i
-Specifies the appropriate 
-.PN Screen
-structure.
-.LP
-.eM
-.IN "DefaultGCOfScreen" "" "@DEF@"
-.IN "XDefaultGCOfScreen" "" "@DEF@"
-Both return a default graphics context (GC) of the specified screen,
-which has the same depth as the root window of the screen.
-The GC must never be freed.
-.LP
-.sp
-.sM
-.FD 0
-DefaultVisualOfScreen\^(\^\fIscreen\fP\^)
-.sp
-Visual *XDefaultVisualOfScreen\^(\^\fIscreen\fP\^)
-.br
-      Screen *\fIscreen\fP\^;
-.FN
-.IP \fIscreen\fP 1i
-Specifies the appropriate 
-.PN Screen
-structure.
-.LP
-.eM
-.IN "DefaultVisualOfScreen" "" "@DEF@"
-.IN "XDefaultVisualOfScreen" "" "@DEF@"
-Both return the default visual of the specified screen.
-For information on visual types,
-see section 3.1.
-.LP
-.sp
-.sM
-.FD 0
-DoesBackingStore\^(\^\fIscreen\fP\^)
-.sp
-int XDoesBackingStore\^(\^\fIscreen\fP\^)
-.br
-      Screen *\fIscreen\fP\^;
-.FN
-.IP \fIscreen\fP 1i
-Specifies the appropriate 
-.PN Screen
-structure.
-.LP
-.eM
-.IN "DoesBackingStore" "" "@DEF@"
-.IN "XDoesBackingStore" "" "@DEF@"
-Both return a value indicating whether the screen supports backing
-stores.
-The value returned can be one of 
-.PN WhenMapped ,
-.PN NotUseful ,
-or
-.PN Always 
-(see section 3.2.4).
-.LP
-.sp
-.sM
-.FD 0
-DoesSaveUnders\^(\^\fIscreen\fP\^)
-.sp
-Bool XDoesSaveUnders\^(\^\fIscreen\fP\^)
-.br
-      Screen *\fIscreen\fP\^;
-.FN
-.IP \fIscreen\fP 1i
-Specifies the appropriate 
-.PN Screen
-structure.
-.LP
-.eM
-.IN "DoesSaveUnders" "" "@DEF@"
-.IN "XDoesSaveUnders" "" "@DEF@"
-Both return a Boolean value indicating whether the
-screen supports save unders.
-If
-.PN True ,
-the screen supports save unders.
-If
-.PN False ,
-the screen does not support save unders (see section 3.2.5).
-.LP
-.sp
-.sM
-.FD 0
-DisplayOfScreen\^(\^\fIscreen\fP\^)
-.sp
-Display *XDisplayOfScreen\^(\^\fIscreen\fP\^)
-.br
-      Screen *\fIscreen\fP\^;
-.FN
-.IP \fIscreen\fP 1i
-Specifies the appropriate 
-.PN Screen
-structure.
-.LP
-.eM
-.IN "DisplayOfScreen" "" "@DEF@"
-.IN "XDisplayOfScreen" "" "@DEF@"
-Both return the display of the specified screen.
-.LP
-.sp
-.sM
-.IN "XScreenNumberOfScreen" "" "@DEF@"
-.FD 0
-int XScreenNumberOfScreen\^(\^\fIscreen\fP\^)
-.br
-      Screen *\fIscreen\fP\^;
-.FN
-.IP \fIscreen\fP 1i
-Specifies the appropriate 
-.PN Screen
-structure.
-.LP
-.eM
-The
-.PN XScreenNumberOfScreen
-function returns the screen index number of the specified screen.
-.LP
-.sp
-.sM
-.FD 0
-EventMaskOfScreen\^(\^\fIscreen\fP\^)
-.sp
-long XEventMaskOfScreen\^(\^\fIscreen\fP\^)
-.br
-      Screen *\fIscreen\fP\^;
-.FN
-.IP \fIscreen\fP 1i
-Specifies the appropriate 
-.PN Screen
-structure.
-.LP
-.eM
-.IN "EventMaskOfScreen" "" "@DEF@"
-.IN "XEventMaskOfScreen" "" "@DEF@"
-Both return the event mask of the root window for the specified screen
-at connection setup time.
-.LP
-.sp
-.sM
-.FD 0
-WidthOfScreen\^(\^\fIscreen\fP\^)
-.sp
-int XWidthOfScreen\^(\^\fIscreen\fP\^)
-.br
-      Screen *\fIscreen\fP\^;
-.FN
-.IP \fIscreen\fP 1i
-Specifies the appropriate 
-.PN Screen
-structure.
-.LP
-.eM
-.IN "WidthOfScreen" "" "@DEF@"
-.IN "XWidthOfScreen" "" "@DEF@"
-Both return the width of the specified screen in pixels.
-.LP
-.sp
-.sM
-.FD 0
-HeightOfScreen\^(\^\fIscreen\fP\^)
-.sp
-int XHeightOfScreen\^(\^\fIscreen\fP\^)
-.br
-      Screen *\fIscreen\fP\^;
-.FN
-.IP \fIscreen\fP 1i
-Specifies the appropriate 
-.PN Screen
-structure.
-.LP
-.eM
-.IN "HeightOfScreen" "" "@DEF@"
-.IN "XHeightOfScreen" "" "@DEF@"
-Both return the height of the specified screen in pixels.
-.LP
-.sp
-.sM
-.FD 0
-WidthMMOfScreen\^(\^\fIscreen\fP\^)
-.sp
-int XWidthMMOfScreen\^(\^\fIscreen\fP\^)
-.br
-      Screen *\fIscreen\fP\^;
-.FN
-.IP \fIscreen\fP 1i
-Specifies the appropriate 
-.PN Screen
-structure.
-.LP
-.eM
-.IN "WidthMMOfScreen" "" "@DEF@"
-.IN "XWidthMMOfScreen" "" "@DEF@"
-Both return the width of the specified screen in millimeters.
-.LP
-.sp
-.sM
-.FD 0
-HeightMMOfScreen\^(\^\fIscreen\fP\^)
-.sp
-int XHeightMMOfScreen\^(\^\fIscreen\fP\^)
-.br
-      Screen *\fIscreen\fP\^;
-.FN
-.IP \fIscreen\fP 1i
-Specifies the appropriate 
-.PN Screen
-structure.
-.LP
-.eM
-.IN "HeightMMOfScreen" "" "@DEF@"
-.IN "XHeightMMOfScreen" "" "@DEF@"
-Both return the height of the specified screen in millimeters.
-.LP
-.sp
-.sM
-.FD 0
-MaxCmapsOfScreen\^(\^\fIscreen\fP\^)
-.sp
-int XMaxCmapsOfScreen\^(\^\fIscreen\fP\^)
-.br
-      Screen *\fIscreen\fP\^;
-.FN
-.IP \fIscreen\fP 1i
-Specifies the appropriate 
-.PN Screen
-structure.
-.LP
-.eM
-.IN "MaxCmapsOfScreen" "" "@DEF@"
-.IN "XMaxCmapsOfScreen" "" "@DEF@"
-Both return the maximum number of installed colormaps supported 
-by the specified screen (see section 9.3).
-.LP
-.sp
-.sM
-.FD 0
-MinCmapsOfScreen\^(\^\fIscreen\fP\^)
-.sp
-int XMinCmapsOfScreen\^(\^\fIscreen\fP\^)
-.br
-      Screen *\fIscreen\fP\^;
-.FN
-.IP \fIscreen\fP 1i
-Specifies the appropriate 
-.PN Screen
-structure.
-.LP
-.eM
-.IN "MinCmapsOfScreen" "" "@DEF@"
-.IN "XMinCmapsOfScreen" "" "@DEF@"
-Both return the minimum number of installed colormaps supported 
-by the specified screen (see section 9.3).
-.LP
-.sp
-.sM
-.FD 0
-PlanesOfScreen\^(\^\fIscreen\fP\^)
-.sp
-int XPlanesOfScreen\^(\^\fIscreen\fP\^)
-.br
-      Screen *\fIscreen\fP\^;
-.FN
-.IP \fIscreen\fP 1i
-Specifies the appropriate 
-.PN Screen
-structure.
-.LP
-.eM
-.IN "PlanesOfScreen" "" "@DEF@"
-.IN "XPlanesOfScreen" "" "@DEF@"
-Both return the depth of the root window.
-.LP
-.sp
-.sM
-.FD 0
-RootWindowOfScreen\^(\^\fIscreen\fP\^)
-.sp
-Window XRootWindowOfScreen\^(\^\fIscreen\fP\^)
-.br
-      Screen *\fIscreen\fP\^;
-.FN
-.IP \fIscreen\fP 1i
-Specifies the appropriate 
-.PN Screen
-structure.
-.LP
-.eM
-.IN "RootWindowOfScreen" "" "@DEF@"
-.IN "XRootWindowOfScreen" "" "@DEF@"
-Both return the root window of the specified screen.
-.NH 2
-Generating a NoOperation Protocol Request
-.XS
-\*(SN Generating a NoOperation Protocol Request
-.XE
-.LP
-To execute a 
-.PN NoOperation 
-protocol request, use
-.PN XNoOp .
-.IN "XNoOp" "" "@DEF@"
-.sM
-.FD 0
-XNoOp\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-The
-.PN XNoOp
-function sends a 
-.PN NoOperation 
-protocol request to the X server,
-thereby exercising the connection.
-.NH 2
-Freeing Client-Created Data
-.XS
-\*(SN Freeing Client-Created Data
-.XE
-.LP
-To free in-memory data that was created by an Xlib function, use
-.PN XFree .
-.IN "XFree" "" "@DEF@"
-.sM
-.FD 0
-XFree\^(\^\fIdata\fP\^)
-.br
-     void *\fIdata\fP\^; 
-.FN
-.IP \fIdata\fP 1i
-Specifies the data that is to be freed.
-.LP
-.eM
-The
-.PN XFree
-function is a general-purpose Xlib routine that frees the specified data.
-You must use it to free any objects that were allocated by Xlib,
-unless an alternate function is explicitly specified for the object.
-A NULL pointer cannot be passed to this function.
-.NH 2
-Closing the Display
-.XS
-\*(SN Closing the Display
-.XE
-.LP
-To close a display or disconnect from the X server, use
-.PN XCloseDisplay .
-.IN "XCloseDisplay" "" "@DEF@"
-.LP
-.sM
-.FD 0
-XCloseDisplay\^(\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-The
-.PN XCloseDisplay
-function closes the connection to the X server for the display specified in the
-.PN Display
-structure and destroys all windows, resource IDs
-.Pn ( Window ,
-.PN Font ,
-.PN Pixmap ,
-.PN Colormap ,
-.PN Cursor ,
-and
-.PN GContext ),
-or other resources that the client has created
-on this display, unless the close-down mode of the resource has been changed
-(see
-.PN XSetCloseDownMode ).
-Therefore, these windows, resource IDs, and other resources should never be 
-referenced again or an error will be generated.
-Before exiting, you should call
-.PN XCloseDisplay
-explicitly so that any pending errors are reported as
-.PN XCloseDisplay
-performs a final
-.PN XSync
-operation.
-.IN "Resource IDs"
-.IN "XCloseDisplay"
-.LP
-.PN XCloseDisplay
-can generate a
-.PN BadGC
-error.
-.sp
-.LP
-Xlib provides a function to permit the resources owned by a client
-to survive after the client's connection is closed.
-To change a client's close-down mode, use
-.PN XSetCloseDownMode .
-.IN "XSetCloseDownMode" "" "@DEF@"
-.sM
-.FD 0
-XSetCloseDownMode\^(\^\fIdisplay\fP, \fIclose_mode\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIclose_mode\fP\^;	
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIclose_mode\fP 1i
-Specifies the client close-down mode.
-You can pass 
-.PN DestroyAll , 
-.PN RetainPermanent , 
-or
-.PN RetainTemporary . 
-.LP
-.eM
-The
-.PN XSetCloseDownMode
-defines what will happen to the client's resources at connection close.
-A connection starts in
-.PN DestroyAll
-mode.
-For information on what happens to the client's resources when the
-close_mode argument is
-.PN RetainPermanent
-or
-.PN RetainTemporary ,
-see section 2.6.
-.LP
-.PN XSetCloseDownMode
-can generate a
-.PN BadValue 
-error.
-.NH 2
-Using X Server Connection Close Operations 
-.XS
-\*(SN Using X Server Connection Close Operations
-.XE
-.LP
-When the X server's connection to a client is closed
-either by an explicit call to
-.PN XCloseDisplay
-or by a process that exits, the X server performs the following
-automatic operations:
-.IP \(bu 5
-It disowns all selections owned by the client
-(see 
-.PN XSetSelectionOwner ).
-.IP \(bu 5
-It performs an
-.PN XUngrabPointer
-and
-.PN XUngrabKeyboard 
-if the client has actively grabbed the pointer 
-or the keyboard.
-.IP \(bu 5
-It performs an
-.PN XUngrabServer 
-if the client has grabbed the server.
-.IP \(bu 5
-It releases all passive grabs made by the client.  
-.IP \(bu 5
-It marks all resources (including colormap entries) allocated 
-by the client either as permanent or temporary, 
-depending on whether the close-down mode is 
-.PN RetainPermanent
-or
-.PN RetainTemporary .
-However, this does not prevent other client applications from explicitly
-destroying the resources (see 
-.PN XSetCloseDownMode ).
-.LP
-When the close-down mode is
-.PN DestroyAll ,
-the X server destroys all of a client's resources as follows:
-.IP \(bu 5
-It examines each window in the client's save-set to determine if it is an inferior
-(subwindow) of a window created by the client.
-(The save-set is a list of other clients' windows
-that are referred to as save-set windows.)
-If so, the X server reparents the save-set window to the closest ancestor so
-that the save-set window is not an inferior of a window created by the client.
-The reparenting leaves unchanged the absolute coordinates (with respect to
-the root window) of the upper-left outer corner of the save-set
-window.
-.IP \(bu 5
-It performs a
-.PN MapWindow
-request on the save-set window if the save-set window is unmapped.
-The X server does this even if the save-set window was not an inferior of 
-a window created by the client.
-.IP \(bu 5
-It destroys all windows created by the client.
-.IP \(bu 5
-It performs the appropriate free request on each nonwindow resource created by
-the client in the server (for example, 
-.PN Font , 
-.PN Pixmap , 
-.PN Cursor , 
-.PN Colormap , 
-and 
-.PN GContext ).
-.IP \(bu 5
-It frees all colors and colormap entries allocated by a client application.
-.LP
-Additional processing occurs when the last connection to the X server closes.
-An X server goes through a cycle of having no connections and having some
-connections.
-When the last connection to the X server closes as a result of a connection
-closing with the close_mode of
-.PN DestroyAll ,
-the X server does the following: 
-.IP \(bu 5
-It resets its state as if it had just been
-started.  
-The X server begins by destroying all lingering resources from
-clients that have terminated in 
-.PN RetainPermanent
-or
-.PN RetainTemporary
-mode.
-.IP \(bu 5
-It deletes all but the predefined atom identifiers.
-.IP \(bu 5
-It deletes all properties on all root windows (see section 4.3).
-.IP \(bu 5
-It resets all device maps and attributes 
-(for example, key click, bell volume, and acceleration) 
-as well as the access control list.
-.IP \(bu 5
-It restores the standard root tiles and cursors.
-.IP \(bu 5
-It restores the default font path.
-.IP \(bu 5
-It restores the input focus to state
-.PN PointerRoot .
-.LP
-However, the X server does not reset if you close a connection with a close-down
-mode set to
-.PN RetainPermanent
-or
-.PN RetainTemporary .
-.NH 2
-Using Xlib with Threads
-.XS
-\*(SN Using Xlib with Threads
-.XE
-.LP
-On systems that have threads, support may be provided to permit
-multiple threads to use Xlib concurrently.
-.LP
-.sp
-To initialize support for concurrent threads, use
-.PN XInitThreads .
-.IN "XInitThreads" "" "@DEF@"
-.sM
-.FD 0
-Status XInitThreads\^(\|);
-.FN
-.LP
-.eM
-The
-.PN XInitThreads
-function initializes Xlib support for concurrent threads.
-This function must be the first Xlib function a
-multi-threaded program calls, and it must complete
-before any other Xlib call is made.
-This function returns a nonzero status if initialization was
-successful; otherwise, it returns zero.
-On systems that do not support threads, this function always returns zero.
-.LP
-It is only necessary to call this function if multiple threads
-might use Xlib concurrently.  If all calls to Xlib functions
-are protected by some other access mechanism (for example,
-a mutual exclusion lock in a toolkit or through explicit client
-programming), Xlib thread initialization is not required.
-It is recommended that single-threaded programs not call this function.
-
-.LP
-.sp
-To lock a display across several Xlib calls, use
-.PN XLockDisplay .
-.IN "XLockDisplay" "" "@DEF@"
-.sM
-.FD 0
-void XLockDisplay\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-The
-.PN XLockDisplay
-function locks out all other threads from using the specified display.
-Other threads attempting to use the display will block until
-the display is unlocked by this thread.
-Nested calls to
-.PN XLockDisplay
-work correctly; the display will not actually be unlocked until
-.PN XUnlockDisplay
-has been called the same number of times as
-.PN XLockDisplay .
-This function has no effect unless Xlib was successfully initialized
-for threads using
-.PN XInitThreads .
-.LP
-.sp
-To unlock a display, use
-.PN XUnlockDisplay .
-.IN "XUnlockDisplay" "" "@DEF@"
-.sM
-.FD 0
-void XUnlockDisplay\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-The
-.PN XUnlockDisplay
-function allows other threads to use the specified display again.
-Any threads that have blocked on the display are allowed to continue.
-Nested locking works correctly; if
-.PN XLockDisplay
-has been called multiple times by a thread, then
-.PN XUnlockDisplay
-must be called an equal number of times before the display is
-actually unlocked.
-This function has no effect unless Xlib was successfully initialized
-for threads using
-.PN XInitThreads .
-.NH 2
-Using Internal Connections
-.XS
-\*(SN Using Internal Connections
-.XE
-.LP
-In addition to the connection to the X server, an Xlib implementation
-may require connections to other kinds of servers (for example, to
-input method servers as described in chapter 13).  Toolkits and clients
-that use multiple displays, or that use displays in combination with
-other inputs, need to obtain these additional connections to correctly
-block until input is available and need to process that input
-when it is available.  Simple clients that use a single display and
-block for input in an Xlib event function do not need to use these
-facilities.
-.LP
-To track internal connections for a display, use
-.PN XAddConnectionWatch .
-.LP
-.IN "XWatchProc" "" "@DEF@"
-.IN "XAddConnectionWatch" "" "@DEF@"
-.sM
-.FD 0
-typedef void (*XConnectionWatchProc)\^(\^\fIdisplay\fP, \fIclient_data\fP, \fIfd\fP, \fIopening\fP, \fIwatch_data\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XPointer \fIclient_data\fP\^;
-.br
-      int \fIfd\fP\^;
-.br
-      Bool \fIopening\fP\^;
-.br
-      XPointer *\fIwatch_data\fP\^;
-.sp
-Status XAddConnectionWatch\^(\^\fIdisplay\fP, \fIprocedure\fP\^, \fIclient_data\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XWatchProc \fIprocedure\fP\^;
-.br
-      XPointer \fIclient_data\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIprocedure\fP 1i
-Specifies the procedure to be called.
-.IP \fIclient_data\fP 1i
-Specifies the additional client data.
-.LP
-.eM
-The
-.PN XAddConnectionWatch
-function registers a procedure to be called each time Xlib opens or closes an
-internal connection for the specified display.  The procedure is passed the
-display, the specified client_data, the file descriptor for the connection,
-a Boolean indicating whether the connection is being opened or closed, and a
-pointer to a location for private watch data.  If opening is
-.PN True ,
-the procedure can store a pointer to private data in the location pointed
-to by watch_data;
-when the procedure is later called for this same connection and opening is
-.PN False ,
-the location pointed to by watch_data will hold this same private data pointer.
-.LP
-This function can be called at any time after a display is opened.
-If internal connections already exist, the registered procedure will
-immediately be called for each of them, before
-.PN XAddConnectionWatch
-returns.
-.PN XAddConnectionWatch
-returns a nonzero status if the procedure is successfully registered;
-otherwise, it returns zero.
-.LP
-The registered procedure should not call any Xlib functions.
-If the procedure directly or indirectly causes the state of internal
-connections or watch procedures to change, the result is not defined.
-If Xlib has been initialized for threads, the procedure is called with
-the display locked and the result of a call by the procedure to any
-Xlib function that locks the display is not defined unless the executing
-thread has externally locked the display using
-.PN XLockDisplay .
-.LP
-.sp
-To stop tracking internal connections for a display, use
-.PN XRemoveConnectionWatch .
-.IN "XRemoveConnectionWatch" "" "@DEF@"
-.sM
-.FD 0
-Status XRemoveConnectionWatch\^(\^\fIdisplay\fP, \fIprocedure\fP\^, \fIclient_data\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XWatchProc \fIprocedure\fP\^;
-.br
-      XPointer \fIclient_data\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIprocedure\fP 1i
-Specifies the procedure to be called.
-.IP \fIclient_data\fP 1i
-Specifies the additional client data.
-.LP
-.eM
-The
-.PN XRemoveConnectionWatch
-function removes a previously registered connection watch procedure.
-The client_data must match the client_data used when the procedure
-was initially registered.
-
-.LP
-.sp
-To process input on an internal connection, use
-.PN XProcessInternalConnection .
-.IN "XProcessInternalConnection" "" "@DEF@"
-.sM
-.FD 0
-void XProcessInternalConnection\^(\^\fIdisplay\fP, \fIfd\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIfd\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIfd\fP 1i
-Specifies the file descriptor.
-.LP
-.eM
-The
-.PN XProcessInternalConnection
-function processes input available on an internal connection.
-This function should be called for an internal connection only
-after an operating system facility (for example,
-.PN select
-or
-.PN poll )
-has indicated that input is available; otherwise,
-the effect is not defined.
-.LP
-.sp
-To obtain all of the current internal connections for a display, use
-.PN XInternalConnectionNumbers .
-.IN "XInternalConnectionNumbers" "" "@DEF@"
-.sM
-.FD 0
-Status XInternalConnectionNumbers\^(\^\fIdisplay\fP, \fIfd_return\fP\^, \fIcount_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int **\fIfd_return\fP\^;
-.br
-      int *\fIcount_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIfd_return\fP 1i
-Returns the file descriptors.
-.ds Cn file descriptors
-.IP \fIcount_return\fP 1i
-Returns the number of \*(Cn.
-.LP
-.eM
-The
-.PN XInternalConnectionNumbers
-function returns a list of the file descriptors for all internal
-connections currently open for the specified display.
-When the allocated list is no longer needed,
-free it by using
-.PN XFree .
-This functions returns a nonzero status if the list is successfully allocated;
-otherwise, it returns zero.
-.LP
-.bp
diff --git a/libX11/specs/libX11/CH02.xml b/libX11/specs/libX11/CH02.xml
new file mode 100644
index 000000000..23f9f1ce2
--- /dev/null
+++ b/libX11/specs/libX11/CH02.xml
@@ -0,0 +1,3488 @@
+<chapter id="display_functions">

+<title>Display Functions</title>

+<para>

+Before your program can use a display, you must establish a connection

+to the X server.

+Once you have established a connection,

+you then can use the Xlib macros and functions discussed in this chapter

+to return information about the display.

+This chapter discusses how to:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Open (connect to) the display

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Obtain information about the display, image formats, or screens

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Generate a

+<function>NoOperation</function>

+protocol request

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Free client-created data

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Close (disconnect from) a display

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Use X Server connection close operations

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Use Xlib with threads

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Use internal connections

+    </para>

+  </listitem>

+</itemizedlist>

+<sect1 id="Opening_the_Display">

+<title>Opening the Display</title>

+<!-- .XS -->

+<!-- (SN Opening the Display -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To open a connection to the X server that controls a display, use

+<function>XOpenDisplay</function>.

+<indexterm significance="preferred"><primary>XOpenDisplay</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+</para>

+<para>

+AllPlanes()

+</para>

+<para>

+XAllPlanes

+</para>

+

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display_name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the hardware display name, which determines the display

+and communications domain to be used.

+On a <acronym>POSIX</acronym>-conformant system, if the display_name is NULL, 

+it defaults to the value of the DISPLAY environment variable. 

+<indexterm><primary>Environment</primary><secondary>DISPLAY</secondary></indexterm>

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The encoding and interpretation of the display name are

+implementation-dependent.

+Strings in the Host Portable Character Encoding are supported;

+support for other characters is implementation-dependent.

+On <acronym>POSIX</acronym>-conformant systems,

+the display name or DISPLAY environment variable can be a string in the format:

+</para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA 1i -->

+<!-- .ta 1i -->

+	<emphasis remap='I'>protocol</emphasis>/<emphasis remap='I'>hostname</emphasis>:<emphasis remap='I'>number</emphasis>.<emphasis remap='I'>screen_number</emphasis>

+</literallayout>

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>protocol</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a protocol family or an alias for a protocol family.  Supported 

+protocol families are implementation dependent.  The protocol entry is 

+optional.  If protocol is not specified, the / separating protocol and 

+hostname must also not be specified.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hostname</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the name of the host machine on which the display is physically

+attached.

+You follow the hostname with either a single colon (:) or a double colon (::).

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of the display server on that host machine.

+You may optionally follow this display number with a period (.).

+A single <acronym>CPU</acronym> can have more than one display.

+Multiple displays are usually numbered starting with zero.

+<indexterm><primary>Screen</primary></indexterm>

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the screen to be used on that server.

+Multiple screens can be controlled by a single X server.

+The screen_number sets an internal variable that can be accessed by

+using the 

+<function>DefaultScreen </function>

+macro or the 

+<function>XDefaultScreen</function>

+function if you are using languages other than C (see section 2.2.1).

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+For example, the following would specify screen 1 of display 0 on the 

+machine named ``dual-headed'':

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+dual-headed:0.1

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XOpenDisplay</function>

+function returns a 

+<function>Display </function>

+structure that serves as the

+connection to the X server and that contains all the information

+about that X server.

+<function>XOpenDisplay</function>

+connects your application to the X server through <acronym>TCP</acronym>

+or DECnet communications protocols,

+or through some local inter-process communication protocol.

+<indexterm><primary>Protocol</primary><secondary><acronym>TCP</acronym></secondary></indexterm>

+<indexterm><primary>Protocol</primary><secondary>DECnet</secondary></indexterm>

+If the protocol is specified as "tcp", "inet", or "inet6", or

+if no protocol is specified and the hostname is a host machine name and a single colon (:)

+separates the hostname and display number,

+<function>XOpenDisplay</function>

+connects using <acronym>TCP</acronym> streams.  (If the protocol is specified as "inet", <acronym>TCP</acronym> over

+IPv4 is used.  If the protocol is specified as "inet6", <acronym>TCP</acronym> over IPv6 is used.

+Otherwise, the implementation determines which <acronym>IP</acronym> version is used.)

+If the hostname and protocol are both not specified,

+Xlib uses whatever it believes is the fastest transport.

+If the hostname is a host machine name and a double colon (::)

+separates the hostname and display number,

+<function>XOpenDisplay</function>

+connects using DECnet.

+A single X server can support any or all of these transport mechanisms

+simultaneously.

+A particular Xlib implementation can support many more of these transport

+mechanisms.

+</para>

+<para>

+<!-- .LP -->

+<indexterm><primary>Display</primary></indexterm>

+If successful, 

+<function>XOpenDisplay </function>

+returns a pointer to a 

+<function>Display </function>

+structure,

+which is defined in 

+<!-- .hN X11/Xlib.h . -->

+If 

+<function>XOpenDisplay </function>

+does not succeed, it returns NULL.

+After a successful call to

+<function>XOpenDisplay</function>,

+all of the screens in the display can be used by the client.

+The screen number specified in the display_name argument is returned 

+by the 

+<function>DefaultScreen</function>

+macro (or the

+<function>XDefaultScreen</function>

+function).

+You can access elements of the

+<function>Display</function>

+and

+<function>Screen</function>

+structures only by using the information macros or functions.

+For information about using macros and functions to obtain information from 

+the

+<function>Display </function>

+structure,

+see section 2.2.1.

+</para>

+<para>

+<!-- .LP -->

+X servers may implement various types of access control mechanisms

+(see section 9.8).

+</para>

+</sect1>

+<sect1 id="Obtaining_Information_about_the_Display_Image_Formats_or_Screens">

+<title>Obtaining Information about the Display, Image Formats, or Screens</title>

+<!-- .XS -->

+<!-- (SN Obtaining Information about the Display, Image Formats, or Screens -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The Xlib library provides a number of useful macros 

+and corresponding functions that return data from the 

+<function>Display </function>

+structure.

+The macros are used for C programming, 

+and their corresponding function equivalents are for other language bindings.

+This section discusses the:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Display macros

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Image format functions and macros

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Screen information macros

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+<indexterm ><primary>Display</primary><secondary>data structure</secondary></indexterm>

+All other members of the 

+<function>Display </function>

+structure (that is, those for which no macros are defined) are private to Xlib 

+and must not be used.

+Applications must never directly modify or inspect these private members of the 

+<function>Display </function>

+structure.

+<!-- .NT Note -->

+The

+<function>XDisplayWidth</function>,

+<function>XDisplayHeight</function>,

+<function>XDisplayCells</function>,

+<function>XDisplayPlanes</function>,

+<function>XDisplayWidthMM</function>,

+and

+<function>XDisplayHeightMM</function>

+functions in the next sections are misnamed.

+These functions really should be named Screen<emphasis remap='I'>whatever</emphasis> 

+and XScreen<emphasis remap='I'>whatever</emphasis>, not Display<emphasis remap='I'>whatever</emphasis> or XDisplay<emphasis remap='I'>whatever</emphasis>.

+Our apologies for the resulting confusion.

+<!-- .NE -->

+</para>

+<sect2 id="Display_Macros_">

+<title>Display Macros </title>

+<!-- .XS -->

+<!-- (SN Display Macros -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Applications should not directly modify any part of the

+<function>Display</function>

+and

+<function>Screen</function>

+structures.

+The members should be considered read-only,

+although they may change as the result of other operations on the display.

+</para>

+<para>

+<!-- .LP  -->

+The following lists the C language macros,

+their corresponding function equivalents that are for other language bindings,

+and what data both can return.

+</para>

+<para>AllPlanes()</para>

+<para>XAllPlanes()</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>AllPlanes</primary></indexterm>

+<indexterm significance="preferred"><primary>XAllPlanes</primary></indexterm>

+Both return a value with all bits set to 1 suitable for use in a plane argument to

+a procedure.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+Both 

+<function>BlackPixel </function>

+and 

+<function>WhitePixel </function>

+can be used in implementing a monochrome application.

+These pixel values are for permanently allocated entries in the default

+colormap.

+The actual <acronym>RGB</acronym> (red, green, and blue) values are settable on some screens 

+and, in any case, may not actually be black or white.

+The names are intended to convey the expected relative intensity of the colors.

+<!-- .sM -->

+</para>

+<para>

+BlackPixel(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>unsigned long <function> XBlackPixel</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> screen_number</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate screen number on the host server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>BlackPixel</primary></indexterm>

+<indexterm significance="preferred"><primary>XBlackPixel</primary></indexterm>

+Both return the black pixel value for the specified screen.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+WhitePixel(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>unsigned long <function> XWhitePixel</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> screen_number</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate screen number on the host server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>WhitePixel</primary></indexterm>

+<indexterm significance="preferred"><primary>XWhitePixel</primary></indexterm>

+Both return the white pixel value for the specified screen. 

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+ConnectionNumber(<emphasis remap='I'>display</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XConnectionNumber</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>ConnectionNumber</primary></indexterm>

+<indexterm significance="preferred"><primary>XConnectionNumber</primary></indexterm>

+Both return a connection number for the specified display.

+On a <acronym>POSIX</acronym>-conformant system,

+this is the file descriptor of the connection.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+DefaultColormap(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Colormap <function> XDefaultColormap</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> screen_number</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate screen number on the host server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>DefaultColormap</primary></indexterm>

+<indexterm significance="preferred"><primary>XDefaultColormap</primary></indexterm>

+Both return the default colormap ID for allocation on the specified screen.

+Most routine allocations of color should be made out of this colormap.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+DefaultDepth(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XDefaultDepth</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> screen_number</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate screen number on the host server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>DefaultDepth</primary></indexterm>

+<indexterm significance="preferred"><primary>XDefaultDepth</primary></indexterm>

+Both return the depth (number of planes) of the default root window for the

+specified screen.

+Other depths may also be supported on this screen (see

+<function>XMatchVisualInfo</function>).

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<indexterm significance="preferred"><primary>XListDepths</primary></indexterm>

+To determine the number of depths that are available on a given screen, use

+<function>XListDepths</function>.

+<!-- .sM -->

+</para>

+<para>

+DefaultGC(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>GC <function> XDefaultGC</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> screen_number</parameter></paramdef>

+  <paramdef>int<parameter> *count_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate screen number on the host server.

+<!-- .ds Cn depths -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>count_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of (Cn.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XListDepths</function>

+function returns the array of depths 

+that are available on the specified screen.

+If the specified screen_number is valid and sufficient memory for the array

+can be allocated,

+<function>XListDepths</function>

+sets count_return to the number of available depths.

+Otherwise, it does not set count_return and returns NULL.

+To release the memory allocated for the array of depths, use

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+DefaultGC(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>GC <function> XDefaultGC</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> screen_number</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate screen number on the host server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>DefaultGC</primary></indexterm>

+<indexterm significance="preferred"><primary>XDefaultGC</primary></indexterm>

+Both return the default graphics context for the root window of the 

+specified screen.

+This GC is created for the convenience of simple applications

+and contains the default GC components with the foreground and

+background pixel values initialized to the black and white

+pixels for the screen, respectively.

+You can modify its contents freely because it is not used in any Xlib

+function.

+This GC should never be freed.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+DefaultRootWindow(<emphasis remap='I'>display</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Window <function> XDefaultRootWindow</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>DefaultRootWindow</primary></indexterm>

+<indexterm significance="preferred"><primary>XDefaultRootWindow</primary></indexterm>

+Both return the root window for the default screen.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+DefaultScreenOfDisplay(<emphasis remap='I'>display</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Screen *<function> XDefaultScreenOfDisplay</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>DefaultScreenOfDisplay</primary></indexterm>

+<indexterm significance="preferred"><primary>XDefaultScreenOfDisplay</primary></indexterm>

+Both return a pointer to the default screen.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+ScreenOfDisplay(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Screen *<function> XScreenOfDisplay</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> screen_number</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate screen number on the host server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>ScreenOfDisplay</primary></indexterm>

+<indexterm significance="preferred"><primary>XScreenOfDisplay</primary></indexterm>

+Both return a pointer to the indicated screen.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+DefaultScreen(<emphasis remap='I'>display</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XDefaultScreen</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>DefaultScreen</primary></indexterm>

+<indexterm significance="preferred"><primary>XDefaultScreen</primary></indexterm>

+Both return the default screen number referenced by the 

+<function>XOpenDisplay</function>

+function. 

+This macro or function should be used to retrieve the screen number 

+in applications that will use only a single screen.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+DefaultVisual(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Visual *<function> XDefaultVisual</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> screen_number</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate screen number on the host server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>DefaultVisual</primary></indexterm>

+<indexterm significance="preferred"><primary>XDefaultVisual</primary></indexterm>

+Both return the default visual type for the specified screen.

+For further information about visual types,

+see section 3.1.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+DisplayCells(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XDisplayCells</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> screen_number</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate screen number on the host server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>DisplayCells</primary></indexterm>

+<indexterm significance="preferred"><primary>XDisplayCells</primary></indexterm>

+Both return the number of entries in the default colormap.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+DisplayPlanes(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XDisplayPlanes</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> screen_number</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate screen number on the host server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>DisplayPlanes</primary></indexterm>

+<indexterm significance="preferred"><primary>XDisplayPlanes</primary></indexterm>

+Both return the depth of the root window of the specified screen.

+For an explanation of depth,

+see the glossary.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+DisplayString(<emphasis remap='I'>display</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char *<function> XDisplayString</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>DisplayString</primary></indexterm>

+<indexterm significance="preferred"><primary>XDisplayString</primary></indexterm>

+Both return the string that was passed to 

+<function>XOpenDisplay</function>

+when the current display was opened. 

+On <acronym>POSIX</acronym>-conformant systems,

+if the passed string was NULL, these return the value of

+the DISPLAY environment variable when the current display was opened.

+<indexterm><primary><acronym>POSIX</acronym> System Call</primary><secondary>fork</secondary></indexterm>

+These are useful to applications that invoke the 

+<function>fork</function>

+system call and want to open a new connection to the same display from the 

+child process as well as for printing error messages.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+LastKnownRequestProcessed(<emphasis remap='I'>display</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>unsigned long <function> XLastKnownRequestProcessed</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>XExtendedMaxRequestSize</primary></indexterm>

+The

+<function>XExtendedMaxRequestSize</function>

+function returns zero if the specified display does not support an

+extended-length protocol encoding; otherwise,

+it returns the maximum request size (in 4-byte units) supported

+by the server using the extended-length encoding.

+The Xlib functions

+<function>XDrawLines</function>,

+<function>XDrawArcs</function>,

+<function>XFillPolygon</function>,

+<function>XChangeProperty</function>,

+<function>XSetClipRectangles</function>,

+and

+<function>XSetRegion</function>

+will use the extended-length encoding as necessary, if supported

+by the server.  Use of the extended-length encoding in other Xlib

+functions (for example,

+<function>XDrawPoints</function>,

+<function>XDrawRectangles</function>,

+<function>XDrawSegments</function>,

+<function>XFillArcs</function>,

+<function>XFillRectangles</function>,

+<function>XPutImage</function>)

+is permitted but not required; an Xlib implementation may choose to

+split the data across multiple smaller requests instead.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+LastKnownRequestProcessed(<emphasis remap='I'>display</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>unsigned long <function> XLastKnownRequestProcessed</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>XMaxRequestSize</primary></indexterm>

+The

+<function>XMaxRequestSize</function>

+function returns the maximum request size (in 4-byte units) supported

+by the server without using an extended-length protocol encoding.

+Single protocol requests to the server can be no larger than this size

+unless an extended-length protocol encoding is supported by the server.

+The protocol guarantees the size to be no smaller than 4096 units

+(16384 bytes).

+Xlib automatically breaks data up into multiple protocol requests

+as necessary for the following functions:

+<function>XDrawPoints</function>,

+<function>XDrawRectangles</function>,

+<function>XDrawSegments</function>,

+<function>XFillArcs</function>,

+<function>XFillRectangles</function>,

+and 

+<function>XPutImage</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+LastKnownRequestProcessed(<emphasis remap='I'>display</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>unsigned long <function> XLastKnownRequestProcessed</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>LastKnownRequestProcessed</primary></indexterm>

+<indexterm significance="preferred"><primary>XLastKnownRequestProcessed</primary></indexterm>

+Both extract the full serial number of the last request known by Xlib

+to have been processed by the X server.

+Xlib automatically sets this number when replies, events, and errors

+are received.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+NextRequest(<emphasis remap='I'>display</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>unsigned long <function> XNextRequest</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>NextRequest</primary></indexterm>

+<indexterm significance="preferred"><primary>XNextRequest</primary></indexterm>

+Both extract the full serial number that is to be used for the next

+request.

+Serial numbers are maintained separately for each display connection.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+ProtocolVersion(<emphasis remap='I'>display</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XProtocolVersion</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>ProtocolVersion</primary></indexterm>

+<indexterm significance="preferred"><primary>XProtocolVersion</primary></indexterm>

+Both return the major version number (11) of the X protocol associated with 

+the connected display.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+ProtocolRevision(<emphasis remap='I'>display</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XProtocolRevision</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>ProtocolRevision</primary></indexterm>

+<indexterm significance="preferred"><primary>XProtocolRevision</primary></indexterm>

+Both return the minor protocol revision number of the X server.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+QLength(<emphasis remap='I'>display</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XQLength</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>QLength</primary></indexterm>

+<indexterm significance="preferred"><primary>XQLength</primary></indexterm>

+Both return the length of the event queue for the connected display.

+Note that there may be more events that have not been read into

+the queue yet (see

+<function>XEventsQueued</function>).

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+RootWindow(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Window <function> XRootWindow</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> screen_number</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate screen number on the host server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm><primary>Window</primary><secondary>RootWindow</secondary></indexterm>

+<indexterm significance="preferred"><primary>RootWindow</primary></indexterm>

+<indexterm><primary>Window</primary><secondary>XRootWindow</secondary></indexterm>

+<indexterm significance="preferred"><primary>XRootWindow</primary></indexterm>

+Both return the root window.

+These are useful with functions that need a drawable of a particular screen

+and for creating top-level windows.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+ScreenCount(<emphasis remap='I'>display</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XScreenCount</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>ScreenCount</primary></indexterm>

+<indexterm significance="preferred"><primary>XScreenCount</primary></indexterm>

+Both return the number of available screens.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+ServerVendor(<emphasis remap='I'>display</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char *<function> XServerVendor</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>ServerVendor</primary></indexterm>

+<indexterm significance="preferred"><primary>XServerVendor</primary></indexterm>

+Both return a pointer to a null-terminated string that provides

+some identification of the owner of the X server implementation.

+If the data returned by the server is in the Latin Portable Character Encoding,

+then the string is in the Host Portable Character Encoding.

+Otherwise, the contents of the string are implementation-dependent.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+VendorRelease(<emphasis remap='I'>display</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XVendorRelease</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>VendorRelease</primary></indexterm>

+<indexterm significance="preferred"><primary>XVendorRelease</primary></indexterm>

+Both return a number related to a vendor's release of the X server.

+</para>

+</sect2>

+<sect2 id="Image_Format_Functions_and_Macros">

+<title>Image Format Functions and Macros</title>

+<!-- .XS -->

+<!-- (SN Image Format Functions and Macros -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Applications are required to present data to the X server

+in a format that the server demands.

+To help simplify applications,

+most of the work required to convert the data is provided by Xlib

+(see sections 8.7 and 16.8).

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XPixmapFormatValues</function>

+structure provides an interface to the pixmap format information

+that is returned at the time of a connection setup.

+It contains:

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+	int depth;

+	int bits_per_pixel;

+	int scanline_pad;

+} XPixmapFormatValues;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To obtain the pixmap format information for a given display, use

+<function>XListPixmapFormats</function>.

+<indexterm significance="preferred"><primary>XListPixmapFormats</primary></indexterm>

+<!-- .sM -->

+</para>

+<para>

+ImageByteOrder(<emphasis remap='I'>display</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XImageByteOrder</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> *count_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Cn pixmap formats that are supported by the display -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>count_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of (Cn.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XListPixmapFormats</function>

+function returns an array of

+<function>XPixmapFormatValues</function>

+structures that describe the types of Z format images supported

+by the specified display.

+If insufficient memory is available,

+<function>XListPixmapFormats</function>

+returns NULL.

+To free the allocated storage for the

+<function>XPixmapFormatValues</function>

+structures, use

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP  -->

+The following lists the C language macros,

+their corresponding function equivalents that are for other language bindings,

+and what data they both return for the specified server and screen.

+These are often used by toolkits as well as by simple applications.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+ImageByteOrder(<emphasis remap='I'>display</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XImageByteOrder</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>ImageByteOrder</primary></indexterm>

+<indexterm significance="preferred"><primary>XImageByteOrder</primary></indexterm>

+Both specify the required byte order for images for each scanline unit in 

+XY format (bitmap) or for each pixel value in 

+Z format.

+The macro or function can return either

+<function>LSBFirst </function>

+or 

+<function>MSBFirst</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+BitmapUnit(<emphasis remap='I'>display</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XBitmapUnit</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>BitmapUnit</primary></indexterm>

+<indexterm significance="preferred"><primary>XBitmapUnit</primary></indexterm>

+Both return the size of a bitmap's scanline unit in bits.

+The scanline is calculated in multiples of this value.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+BitmapBitOrder(<emphasis remap='I'>display</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XBitmapBitOrder</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>BitmapBitOrder</primary></indexterm>

+<indexterm significance="preferred"><primary>XBitmapBitOrder</primary></indexterm>

+Within each bitmap unit, the left-most bit in the bitmap as displayed

+on the screen is either the least significant or most significant bit in the

+unit.

+This macro or function can return 

+<function>LSBFirst</function>

+or 

+<function>MSBFirst</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+BitmapPad(<emphasis remap='I'>display</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XBitmapPad</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>BitmapPad</primary></indexterm>

+<indexterm significance="preferred"><primary>XBitmapPad</primary></indexterm>

+Each scanline must be padded to a multiple of bits returned

+by this macro or function.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+DisplayHeight(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XDisplayHeight</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> screen_number</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate screen number on the host server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>DisplayHeight</primary></indexterm>

+<indexterm significance="preferred"><primary>XDisplayHeight</primary></indexterm>

+Both return an integer that describes the height of the screen

+in pixels.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+DisplayHeightMM(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XDisplayHeightMM</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> screen_number</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate screen number on the host server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>DisplayHeightMM</primary></indexterm>

+<indexterm significance="preferred"><primary>XDisplayHeightMM</primary></indexterm>

+Both return the height of the specified screen in millimeters.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+DisplayWidth(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XDisplayWidth</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> screen_number</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate screen number on the host server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>DisplayWidth</primary></indexterm>

+<indexterm significance="preferred"><primary>XDisplayWidth</primary></indexterm>

+Both return the width of the screen in pixels.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+DisplayWidthMM(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XDisplayWidthMM</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> screen_number</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate screen number on the host server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>DisplayWidthMM</primary></indexterm>

+<indexterm significance="preferred"><primary>XDisplayWidthMM</primary></indexterm>

+Both return the width of the specified screen in millimeters.

+</para>

+</sect2>

+<sect2 id="Screen_Information_Macros">

+<title>Screen Information Macros</title>

+<!-- .XS -->

+<!-- (SN Screen Information Macros -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The following lists the C language macros,

+their corresponding function equivalents that are for other language bindings,

+and what data they both can return.

+These macros or functions all take a pointer to the appropriate screen

+structure.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+BlackPixelOfScreen(<emphasis remap='I'>screen</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>unsigned long <function> XBlackPixelOfScreen</function></funcdef>

+  <paramdef>Screen<parameter> *screen</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate 

+<function>Screen</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>BlackPixelOfScreen</primary></indexterm>

+<indexterm significance="preferred"><primary>XBlackPixelOfScreen</primary></indexterm>

+Both return the black pixel value of the specified screen.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+WhitePixelOfScreen(<emphasis remap='I'>screen</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>unsigned long <function> XWhitePixelOfScreen</function></funcdef>

+  <paramdef>Screen<parameter> *screen</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate 

+<function>Screen</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>WhitePixelOfScreen</primary></indexterm>

+<indexterm significance="preferred"><primary>XWhitePixelOfScreen</primary></indexterm>

+Both return the white pixel value of the specified screen.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+CellsOfScreen(<emphasis remap='I'>screen</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XCellsOfScreen</function></funcdef>

+  <paramdef>Screen<parameter> *screen</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate 

+<function>Screen</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>CellsOfScreen</primary></indexterm>

+<indexterm significance="preferred"><primary>XCellsOfScreen</primary></indexterm>

+Both return the number of colormap cells in the default colormap 

+of the specified screen.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+DefaultColormapOfScreen(<emphasis remap='I'>screen</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Colormap <function> XDefaultColormapOfScreen</function></funcdef>

+  <paramdef>Screen<parameter> *screen</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate 

+<function>Screen</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>DefaultColormapOfScreen</primary></indexterm>

+<indexterm significance="preferred"><primary>XDefaultColormapOfScreen</primary></indexterm>

+Both return the default colormap of the specified screen.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+DefaultDepthOfScreen(<emphasis remap='I'>screen</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XDefaultDepthOfScreen</function></funcdef>

+  <paramdef>Screen<parameter> *screen</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate 

+<function>Screen</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>DefaultDepthOfScreen</primary></indexterm>

+<indexterm significance="preferred"><primary>XDefaultDepthOfScreen</primary></indexterm>

+Both return the depth of the root window.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+DefaultGCOfScreen(<emphasis remap='I'>screen</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>GC <function> XDefaultGCOfScreen</function></funcdef>

+  <paramdef>Screen<parameter> *screen</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate 

+<function>Screen</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>DefaultGCOfScreen</primary></indexterm>

+<indexterm significance="preferred"><primary>XDefaultGCOfScreen</primary></indexterm>

+Both return a default graphics context (GC) of the specified screen,

+which has the same depth as the root window of the screen.

+The GC must never be freed.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+DefaultVisualOfScreen(<emphasis remap='I'>screen</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Visual *<function> XDefaultVisualOfScreen</function></funcdef>

+  <paramdef>Screen<parameter> *screen</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate 

+<function>Screen</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>DefaultVisualOfScreen</primary></indexterm>

+<indexterm significance="preferred"><primary>XDefaultVisualOfScreen</primary></indexterm>

+Both return the default visual of the specified screen.

+For information on visual types,

+see section 3.1.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+DoesBackingStore(<emphasis remap='I'>screen</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XDoesBackingStore</function></funcdef>

+  <paramdef>Screen<parameter> *screen</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate 

+<function>Screen</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>DoesBackingStore</primary></indexterm>

+<indexterm significance="preferred"><primary>XDoesBackingStore</primary></indexterm>

+Both return a value indicating whether the screen supports backing

+stores.

+The value returned can be one of 

+<function>WhenMapped</function>,

+<function>NotUseful</function>,

+or

+<function>Always </function>

+(see section 3.2.4).

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+DoesSaveUnders(<emphasis remap='I'>screen</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool <function> XDoesSaveUnders</function></funcdef>

+  <paramdef>Screen<parameter> *screen</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate 

+<function>Screen</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>DoesSaveUnders</primary></indexterm>

+<indexterm significance="preferred"><primary>XDoesSaveUnders</primary></indexterm>

+Both return a Boolean value indicating whether the

+screen supports save unders.

+If

+<function>True</function>,

+the screen supports save unders.

+If

+<function>False</function>,

+the screen does not support save unders (see section 3.2.5).

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+DisplayOfScreen(<emphasis remap='I'>screen</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Display *<function> XDisplayOfScreen</function></funcdef>

+  <paramdef>Screen<parameter> *screen</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate 

+<function>Screen</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>DisplayOfScreen</primary></indexterm>

+<indexterm significance="preferred"><primary>XDisplayOfScreen</primary></indexterm>

+Both return the display of the specified screen.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+<indexterm significance="preferred"><primary>XScreenNumberOfScreen</primary></indexterm>

+</para>

+<para>

+EventMaskOfScreen(<emphasis remap='I'>screen</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>long <function> XEventMaskOfScreen</function></funcdef>

+  <paramdef>Screen<parameter> *screen</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate 

+<function>Screen</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XScreenNumberOfScreen</function>

+function returns the screen index number of the specified screen.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+EventMaskOfScreen(<emphasis remap='I'>screen</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>long <function> XEventMaskOfScreen</function></funcdef>

+  <paramdef>Screen<parameter> *screen</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate 

+<function>Screen</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>EventMaskOfScreen</primary></indexterm>

+<indexterm significance="preferred"><primary>XEventMaskOfScreen</primary></indexterm>

+Both return the event mask of the root window for the specified screen

+at connection setup time.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+WidthOfScreen(<emphasis remap='I'>screen</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XWidthOfScreen</function></funcdef>

+  <paramdef>Screen<parameter> *screen</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate 

+<function>Screen</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>WidthOfScreen</primary></indexterm>

+<indexterm significance="preferred"><primary>XWidthOfScreen</primary></indexterm>

+Both return the width of the specified screen in pixels.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+HeightOfScreen(<emphasis remap='I'>screen</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XHeightOfScreen</function></funcdef>

+  <paramdef>Screen<parameter> *screen</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate 

+<function>Screen</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>HeightOfScreen</primary></indexterm>

+<indexterm significance="preferred"><primary>XHeightOfScreen</primary></indexterm>

+Both return the height of the specified screen in pixels.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+WidthMMOfScreen(<emphasis remap='I'>screen</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XWidthMMOfScreen</function></funcdef>

+  <paramdef>Screen<parameter> *screen</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate 

+<function>Screen</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>WidthMMOfScreen</primary></indexterm>

+<indexterm significance="preferred"><primary>XWidthMMOfScreen</primary></indexterm>

+Both return the width of the specified screen in millimeters.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+HeightMMOfScreen(<emphasis remap='I'>screen</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XHeightMMOfScreen</function></funcdef>

+  <paramdef>Screen<parameter> *screen</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate 

+<function>Screen</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>HeightMMOfScreen</primary></indexterm>

+<indexterm significance="preferred"><primary>XHeightMMOfScreen</primary></indexterm>

+Both return the height of the specified screen in millimeters.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+MaxCmapsOfScreen(<emphasis remap='I'>screen</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XMaxCmapsOfScreen</function></funcdef>

+  <paramdef>Screen<parameter> *screen</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate 

+<function>Screen</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>MaxCmapsOfScreen</primary></indexterm>

+<indexterm significance="preferred"><primary>XMaxCmapsOfScreen</primary></indexterm>

+Both return the maximum number of installed colormaps supported 

+by the specified screen (see section 9.3).

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+MinCmapsOfScreen(<emphasis remap='I'>screen</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XMinCmapsOfScreen</function></funcdef>

+  <paramdef>Screen<parameter> *screen</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate 

+<function>Screen</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>MinCmapsOfScreen</primary></indexterm>

+<indexterm significance="preferred"><primary>XMinCmapsOfScreen</primary></indexterm>

+Both return the minimum number of installed colormaps supported 

+by the specified screen (see section 9.3).

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+PlanesOfScreen(<emphasis remap='I'>screen</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XPlanesOfScreen</function></funcdef>

+  <paramdef>Screen<parameter> *screen</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate 

+<function>Screen</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>PlanesOfScreen</primary></indexterm>

+<indexterm significance="preferred"><primary>XPlanesOfScreen</primary></indexterm>

+Both return the depth of the root window.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+</para>

+<para>

+RootWindowOfScreen(<emphasis remap='I'>screen</emphasis>)

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Window <function> XRootWindowOfScreen</function></funcdef>

+  <paramdef>Screen<parameter> *screen</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate 

+<function>Screen</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>RootWindowOfScreen</primary></indexterm>

+<indexterm significance="preferred"><primary>XRootWindowOfScreen</primary></indexterm>

+Both return the root window of the specified screen.

+</para>

+</sect2>

+</sect1>

+<sect1 id="Generating_a_NoOperation_Protocol_Request">

+<title>Generating a NoOperation Protocol Request</title>

+<!-- .XS -->

+<!-- (SN Generating a NoOperation Protocol Request -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To execute a 

+<function>NoOperation </function>

+protocol request, use

+<function>XNoOp</function>.

+<indexterm significance="preferred"><primary>XNoOp</primary></indexterm>

+<!-- .sM -->

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function>XNoOp</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<variablelist>

+  <varlistentry>

+    <term><emphasis remap='I'>display</emphasis></term>

+    <listitem>

+      <para>Specifies the connection to the X server.</para>

+    </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XNoOp</function>

+function sends a 

+<function>NoOperation </function>

+protocol request to the X server,

+thereby exercising the connection.

+</para>

+</sect1>

+<sect1 id="Freeing_Client_Created_Data">

+<title>Freeing Client-Created Data</title>

+<!-- .XS -->

+<!-- (SN Freeing Client-Created Data -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To free in-memory data that was created by an Xlib function, use

+<function>XFree</function>.

+<indexterm significance="preferred"><primary>XFree</primary></indexterm>

+<!-- .sM -->

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XFree</funcdef>

+  <paramdef>void<parameter> *data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the data that is to be freed.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XFree</function>

+function is a general-purpose Xlib routine that frees the specified data.

+You must use it to free any objects that were allocated by Xlib,

+unless an alternate function is explicitly specified for the object.

+A NULL pointer cannot be passed to this function.

+</para>

+</sect1>

+<sect1 id="Closing_the_Display">

+<title>Closing the Display</title>

+<!-- .XS -->

+<!-- (SN Closing the Display -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To close a display or disconnect from the X server, use

+<function>XCloseDisplay</function>.

+<indexterm significance="preferred"><primary>XCloseDisplay</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XCloseDisplay</funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCloseDisplay</function>

+function closes the connection to the X server for the display specified in the

+<function>Display</function>

+structure and destroys all windows, resource IDs

+(<function>Window</function>,

+<function>Font</function>,

+<function>Pixmap</function>,

+<function>Colormap</function>,

+<function>Cursor</function>,

+and

+<function>GContext</function>),

+or other resources that the client has created

+on this display, unless the close-down mode of the resource has been changed

+(see

+<function>XSetCloseDownMode</function>).

+Therefore, these windows, resource IDs, and other resources should never be 

+referenced again or an error will be generated.

+Before exiting, you should call

+<function>XCloseDisplay</function>

+explicitly so that any pending errors are reported as

+<function>XCloseDisplay</function>

+performs a final

+<function>XSync</function>

+operation.

+<indexterm><primary>Resource IDs</primary></indexterm>

+<indexterm><primary>XCloseDisplay</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<function>XCloseDisplay</function>

+can generate a

+<function>BadGC</function>

+error.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+Xlib provides a function to permit the resources owned by a client

+to survive after the client's connection is closed.

+To change a client's close-down mode, use

+<function>XSetCloseDownMode</function>.

+<indexterm significance="preferred"><primary>XSetCloseDownMode</primary></indexterm>

+<!-- .sM -->

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XSetCloseDownMode</funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> close_mode</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>close_mode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the client close-down mode.

+You can pass 

+<function>DestroyAll</function>,

+<function>RetainPermanent</function>,

+or

+<function>RetainTemporary</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetCloseDownMode</function>

+defines what will happen to the client's resources at connection close.

+A connection starts in

+<function>DestroyAll</function>

+mode.

+For information on what happens to the client's resources when the

+close_mode argument is

+<function>RetainPermanent</function>

+or

+<function>RetainTemporary</function>,

+see section 2.6.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetCloseDownMode</function>

+can generate a

+<function>BadValue </function>

+error.

+</para>

+</sect1>

+<sect1 id="Using_X_Server_Connection_Close_Operations_">

+<title>Using X Server Connection Close Operations </title>

+<!-- .XS -->

+<!-- (SN Using X Server Connection Close Operations -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+When the X server's connection to a client is closed

+either by an explicit call to

+<function>XCloseDisplay</function>

+or by a process that exits, the X server performs the following

+automatic operations:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+It disowns all selections owned by the client

+(see 

+<function>XSetSelectionOwner</function>).

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It performs an

+<function>XUngrabPointer</function>

+and

+<function>XUngrabKeyboard </function>

+if the client has actively grabbed the pointer 

+or the keyboard.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It performs an

+<function>XUngrabServer </function>

+if the client has grabbed the server.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It releases all passive grabs made by the client.  

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It marks all resources (including colormap entries) allocated 

+by the client either as permanent or temporary, 

+depending on whether the close-down mode is 

+<function>RetainPermanent</function>

+or

+<function>RetainTemporary</function>.

+However, this does not prevent other client applications from explicitly

+destroying the resources (see 

+<function>XSetCloseDownMode</function>).

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+When the close-down mode is

+<function>DestroyAll</function>,

+the X server destroys all of a client's resources as follows:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+It examines each window in the client's save-set to determine if it is an inferior

+(subwindow) of a window created by the client.

+(The save-set is a list of other clients' windows

+that are referred to as save-set windows.)

+If so, the X server reparents the save-set window to the closest ancestor so

+that the save-set window is not an inferior of a window created by the client.

+The reparenting leaves unchanged the absolute coordinates (with respect to

+the root window) of the upper-left outer corner of the save-set

+window.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It performs a

+<function>MapWindow</function>

+request on the save-set window if the save-set window is unmapped.

+The X server does this even if the save-set window was not an inferior of 

+a window created by the client.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It destroys all windows created by the client.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It performs the appropriate free request on each nonwindow resource created by

+the client in the server (for example, 

+<function>Font</function>,

+<function>Pixmap</function>,

+<function>Cursor</function>,

+<function>Colormap</function>,

+and 

+<function>GContext</function>).

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It frees all colors and colormap entries allocated by a client application.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+Additional processing occurs when the last connection to the X server closes.

+An X server goes through a cycle of having no connections and having some

+connections.

+When the last connection to the X server closes as a result of a connection

+closing with the close_mode of

+<function>DestroyAll</function>,

+the X server does the following: 

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+It resets its state as if it had just been

+started.  

+The X server begins by destroying all lingering resources from

+clients that have terminated in 

+<function>RetainPermanent</function>

+or

+<function>RetainTemporary</function>

+mode.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It deletes all but the predefined atom identifiers.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It deletes all properties on all root windows (see section 4.3).

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It resets all device maps and attributes 

+(for example, key click, bell volume, and acceleration) 

+as well as the access control list.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It restores the standard root tiles and cursors.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It restores the default font path.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It restores the input focus to state

+<function>PointerRoot</function>.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+However, the X server does not reset if you close a connection with a close-down

+mode set to

+<function>RetainPermanent</function>

+or

+<function>RetainTemporary</function>.

+</para>

+</sect1>

+<sect1 id="Using_Xlib_with_Threads">

+<title>Using Xlib with Threads</title>

+<!-- .XS -->

+<!-- (SN Using Xlib with Threads -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+On systems that have threads, support may be provided to permit

+multiple threads to use Xlib concurrently.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To initialize support for concurrent threads, use

+<function>XInitThreads</function>.

+<indexterm significance="preferred"><primary>XInitThreads</primary></indexterm>

+<!-- .sM -->

+</para>

+<para>Status XInitThreads();</para>

+<!-- .FN -->

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XInitThreads</function>

+function initializes Xlib support for concurrent threads.

+This function must be the first Xlib function a

+multi-threaded program calls, and it must complete

+before any other Xlib call is made.

+This function returns a nonzero status if initialization was

+successful; otherwise, it returns zero.

+On systems that do not support threads, this function always returns zero.

+</para>

+<para>

+<!-- .LP -->

+It is only necessary to call this function if multiple threads

+might use Xlib concurrently.  If all calls to Xlib functions

+are protected by some other access mechanism (for example,

+a mutual exclusion lock in a toolkit or through explicit client

+programming), Xlib thread initialization is not required.

+It is recommended that single-threaded programs not call this function.

+

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To lock a display across several Xlib calls, use

+<function>XLockDisplay</function>.

+<indexterm significance="preferred"><primary>XLockDisplay</primary></indexterm>

+<!-- .sM -->

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XLockDisplay</funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XLockDisplay</function>

+function locks out all other threads from using the specified display.

+Other threads attempting to use the display will block until

+the display is unlocked by this thread.

+Nested calls to

+<function>XLockDisplay</function>

+work correctly; the display will not actually be unlocked until

+<function>XUnlockDisplay</function>

+has been called the same number of times as

+<function>XLockDisplay</function>.

+This function has no effect unless Xlib was successfully initialized

+for threads using

+<function>XInitThreads</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To unlock a display, use

+<function>XUnlockDisplay</function>.

+<indexterm significance="preferred"><primary>XUnlockDisplay</primary></indexterm>

+<!-- .sM -->

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XUnlockDisplay</funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XUnlockDisplay</function>

+function allows other threads to use the specified display again.

+Any threads that have blocked on the display are allowed to continue.

+Nested locking works correctly; if

+<function>XLockDisplay</function>

+has been called multiple times by a thread, then

+<function>XUnlockDisplay</function>

+must be called an equal number of times before the display is

+actually unlocked.

+This function has no effect unless Xlib was successfully initialized

+for threads using

+<function>XInitThreads</function>.

+</para>

+</sect1>

+<sect1 id="Using_Internal_Connections">

+<title>Using Internal Connections</title>

+<!-- .XS -->

+<!-- (SN Using Internal Connections -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+In addition to the connection to the X server, an Xlib implementation

+may require connections to other kinds of servers (for example, to

+input method servers as described in chapter 13).  Toolkits and clients

+that use multiple displays, or that use displays in combination with

+other inputs, need to obtain these additional connections to correctly

+block until input is available and need to process that input

+when it is available.  Simple clients that use a single display and

+block for input in an Xlib event function do not need to use these

+facilities.

+</para>

+<para>

+<!-- .LP -->

+To track internal connections for a display, use

+<function>XAddConnectionWatch</function>.

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>type void XConnectionWatchProc</funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

+  <paramdef>int<parameter> fd</parameter></paramdef>

+  <paramdef>Bool<parameter> opening</parameter></paramdef>

+  <paramdef>XPointer<parameter> *watch_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status XAddConnectionWatch</funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XWatchProc<parameter> procedure</parameter></paramdef>

+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>procedure</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the procedure to be called.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>client_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the additional client data.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XAddConnectionWatch</function>

+function registers a procedure to be called each time Xlib opens or closes an

+internal connection for the specified display.  The procedure is passed the

+display, the specified client_data, the file descriptor for the connection,

+a Boolean indicating whether the connection is being opened or closed, and a

+pointer to a location for private watch data.  If opening is

+<function>True</function>,

+the procedure can store a pointer to private data in the location pointed

+to by watch_data;

+when the procedure is later called for this same connection and opening is

+<function>False</function>,

+the location pointed to by watch_data will hold this same private data pointer.

+</para>

+<para>

+<!-- .LP -->

+This function can be called at any time after a display is opened.

+If internal connections already exist, the registered procedure will

+immediately be called for each of them, before

+<function>XAddConnectionWatch</function>

+returns.

+<function>XAddConnectionWatch</function>

+returns a nonzero status if the procedure is successfully registered;

+otherwise, it returns zero.

+</para>

+<para>

+<!-- .LP -->

+The registered procedure should not call any Xlib functions.

+If the procedure directly or indirectly causes the state of internal

+connections or watch procedures to change, the result is not defined.

+If Xlib has been initialized for threads, the procedure is called with

+the display locked and the result of a call by the procedure to any

+Xlib function that locks the display is not defined unless the executing

+thread has externally locked the display using

+<function>XLockDisplay</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To stop tracking internal connections for a display, use

+<function>XRemoveConnectionWatch</function>.

+<indexterm significance="preferred"><primary>XRemoveConnectionWatch</primary></indexterm>

+<!-- .sM -->

+</para>

+<para>

+()

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XRemoveConnectionWatch </function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XWatchProc<parameter> procedure</parameter></paramdef>

+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>procedure</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the procedure to be called.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>client_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the additional client data.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XRemoveConnectionWatch</function>

+function removes a previously registered connection watch procedure.

+The client_data must match the client_data used when the procedure

+was initially registered.

+

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To process input on an internal connection, use

+<function>XProcessInternalConnection</function>.

+<indexterm significance="preferred"><primary>XProcessInternalConnection</primary></indexterm>

+<!-- .sM -->

+</para>

+<para>

+()

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function>XProcessInternalConnection</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> fd</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>fd</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the file descriptor.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XProcessInternalConnection</function>

+function processes input available on an internal connection.

+This function should be called for an internal connection only

+after an operating system facility (for example,

+<function>select</function>

+or

+<function>poll</function>)

+has indicated that input is available; otherwise,

+the effect is not defined.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain all of the current internal connections for a display, use

+<function>XInternalConnectionNumbers</function>.

+<indexterm significance="preferred"><primary>XInternalConnectionNumbers</primary></indexterm>

+<!-- .sM -->

+</para>

+<para>

+()

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XInternalConnectionNumbers </function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int **<parameter> fd</parameter></paramdef>

+  <paramdef>int *<parameter> count_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>fd_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the file descriptors.

+<!-- .ds Cn file descriptors -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>count_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of (Cn.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XInternalConnectionNumbers</function>

+function returns a list of the file descriptors for all internal

+connections currently open for the specified display.

+When the allocated list is no longer needed,

+free it by using

+<function>XFree</function>.

+This functions returns a nonzero status if the list is successfully allocated;

+otherwise, it returns zero.

+</para>

+</sect1>

+</chapter>

diff --git a/libX11/specs/libX11/CH03 b/libX11/specs/libX11/CH03
deleted file mode 100644
index f7eb2d4c0..000000000
--- a/libX11/specs/libX11/CH03
+++ /dev/null
@@ -1,3121 +0,0 @@
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-.\" OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" Except as contained in this notice, the name of the X Consortium shall
-.\" not be used in advertising or otherwise to promote the sale, use or
-.\" other dealings in this Software without prior written authorization
-.\" from the X Consortium.
-.\"
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
-.\" Digital Equipment Corporation
-.\"
-.\" Portions Copyright \(co 1990, 1991 by
-.\" Tektronix, Inc.
-.\"
-.\" Permission to use, copy, modify and distribute this documentation for
-.\" any purpose and without fee is hereby granted, provided that the above
-.\" copyright notice appears in all copies and that both that copyright notice
-.\" and this permission notice appear in all copies, and that the names of
-.\" Digital and Tektronix not be used in in advertising or publicity pertaining
-.\" to this documentation without specific, written prior permission.
-.\" Digital and Tektronix makes no representations about the suitability
-.\" of this documentation for any purpose.
-.\" It is provided ``as is'' without express or implied warranty.
-.\" 
-\&
-.sp 1
-.ce 3
-\s+1\fBChapter 3\fP\s-1
-
-\s+1\fBWindow Functions\fP\s-1
-.sp 2
-.nr H1 3
-.nr H2 0
-.nr H3 0
-.nr H4 0
-.nr H5 0
-.na
-.LP
-.XS
-Chapter 3: Window Functions
-.XE
-In the X Window System, 
-a window is a rectangular area on the screen that lets you
-view graphic output.
-Client applications
-can display overlapping and nested windows on one or more
-screens that are driven by X servers on one or more machines.
-Clients who want to create windows must first 
-connect their program to the X server
-by calling 
-.PN XOpenDisplay .
-This chapter begins with a discussion of 
-visual types and window attributes.
-The chapter continues with a discussion of the Xlib functions you can use to:
-.IP \(bu 5
-Create windows 
-.IP \(bu 5
-Destroy windows
-.IP \(bu 5
-Map windows
-.IP \(bu 5
-Unmap windows
-.IP \(bu 5
-Configure windows
-.IP \(bu 5
-Change window stacking order
-.IP \(bu 5
-Change window attributes
-.LP
-This chapter also identifies the window actions that may generate events.
-.LP
-Note that it is vital that your application conform to the
-established conventions for communicating with window managers
-for it to work well with the various window managers in use (see section 14.1).
-Toolkits generally adhere to these conventions for you,
-relieving you of the burden.
-Toolkits also often supersede many functions in this chapter
-with versions of their own.
-For more information,
-refer to the documentation for the toolkit that you are using.
-.NH 2
-Visual Types
-.XS
-\*(SN Visual Types
-.XE
-.LP
-.IN "Visual Type" "" "@DEF@"
-On some display hardware, 
-it may be possible to deal with color resources in more than one way.
-For example, you may be able to deal with a screen of either 12-bit depth
-with arbitrary mapping of pixel to color (pseudo-color) or 24-bit depth
-with 8 bits of the pixel dedicated to each of red, green, and blue.
-These different ways of dealing with the visual aspects of the screen
-are called visuals.
-For each screen of the display, there may be a list of valid visual types
-supported at different depths of the screen.
-Because default windows and visual types are defined for each screen,
-most simple applications need not deal with this complexity.
-Xlib provides macros and functions that return the default root window, 
-the default depth of the default root window, and the default visual type
-(see sections 2.2.1 and 16.7).
-.LP
-Xlib uses an opaque 
-.PN Visual 
-.IN "Visual" "" "@DEF@"
-structure that contains information about the possible color mapping.
-The visual utility functions (see section 16.7) use an
-.PN XVisualInfo
-structure to return this information to an application.
-The members of this structure pertinent to this discussion are class, red_mask,
-green_mask, blue_mask, bits_per_rgb, and colormap_size.
-The class member specifies one of the possible visual classes of the screen
-and can be 
-.IN "Visual Classes" "StaticGray"
-.IN "Visual Classes" "StaticColor"
-.IN "Visual Classes" "TrueColor"
-.IN "Visual Classes" "StaticColor"
-.IN "Visual Classes" "GrayScale"
-.IN "Visual Classes" "PseudoColor"
-.PN StaticGray ,
-.PN StaticColor ,
-.PN TrueColor ,
-.PN GrayScale ,
-.PN PseudoColor ,
-or
-.PN DirectColor .
-.LP
-The following concepts may serve to make the explanation of
-visual types clearer. 
-The screen can be color or grayscale,
-can have a colormap that is writable or read-only,
-and can also have a colormap whose indices are decomposed into separate 
-RGB pieces, provided one is not on a grayscale screen.
-This leads to the following diagram:
-.LP
-.DS
-.TS
-center;
-  c   c   s   c   s
-  c   c   c   c   c
-| c | c | c | c | c |.
-	Color	Gray-scale
-	R/O	R/W	R/O	R/W
-_
-Undecomposed	Static	Pseudo	Static	Gray
-Colormap	Color	Color	Gray	Scale
-_
-.T&
-| c | c | c |.
-Decomposed	True	Direct
-Colormap	Color	Color
-_	_	_
-.TE
-.DE
-.LP
-Conceptually, 
-as each pixel is read out of video memory for display on the screen,
-it goes through a look-up stage by indexing into a colormap.
-Colormaps can be manipulated arbitrarily on some hardware, 
-in limited ways on other hardware, and not at all on other hardware.  
-The visual types affect the colormap and 
-the RGB values in the following ways:
-.LP
-.IP \(bu 5
-For 
-.PN PseudoColor , 
-a pixel value indexes a colormap to produce
-independent RGB values, and the RGB values can be changed dynamically.
-.IP \(bu 5
-.PN GrayScale 
-is treated the same way as 
-.PN PseudoColor  
-except that the primary that drives the screen is undefined. 
-Thus, the client should always store the
-same value for red, green, and blue in the colormaps.  
-.IP \(bu 5
-For 
-.PN DirectColor ,
-a pixel value is decomposed into separate RGB subfields, and each
-subfield separately indexes the colormap for the corresponding value.
-The RGB values can be changed dynamically.  
-.IP \(bu 5
-.PN TrueColor
-is treated the same way as 
-.PN DirectColor 
-except that the colormap has predefined, read-only RGB values.
-These RGB values are server dependent but provide linear or near-linear
-ramps in each primary.  
-.IP \(bu 5
-.PN StaticColor
-is treated the same way as 
-.PN PseudoColor 
-except that the colormap has predefined, 
-read-only, server-dependent RGB values.
-.IP \(bu 5
-.PN StaticGray 
-is treated the same way as 
-.PN StaticColor 
-except that the RGB values are equal for any single pixel
-value, thus resulting in shades of gray.  
-.PN StaticGray 
-with a two-entry
-colormap can be thought of as monochrome.
-.LP
-The red_mask, green_mask, and blue_mask members are only defined for
-.PN DirectColor
-and 
-.PN TrueColor . 
-Each has one contiguous set of bits with no
-intersections.
-The bits_per_rgb member specifies the log base 2 of the
-number of distinct color values (individually) of red, green, and blue.
-Actual RGB values are unsigned 16-bit numbers.
-The colormap_size member defines the number of available colormap entries
-in a newly created colormap.  
-For 
-.PN DirectColor 
-and 
-.PN TrueColor , 
-this is the size of an individual pixel subfield.
-.sp
-.LP
-To obtain the visual ID from a 
-.PN Visual ,
-use
-.PN XVisualIDFromVisual .
-.IN "XVisualIDFromVisual" "" "@DEF@"
-.sM
-.FD 0
-VisualID XVisualIDFromVisual\^(\^\fIvisual\fP\^)
-.br
-       Visual *\^\fIvisual\fP\^;
-.FN
-.IP \fIvisual\fP 1i
-Specifies the visual type.
-.LP
-.eM
-The
-.PN XVisualIDFromVisual
-function returns the visual ID for the specified visual type.
-.NH 2
-Window Attributes
-.XS
-\*(SN Window Attributes
-.XE
-.LP
-.IN "Window"
-.IN "Window" "attributes"
-All 
-.PN InputOutput
-windows have a border width of zero or more pixels, an optional background, 
-an event suppression mask (which suppresses propagation of events from 
-children), and a property list (see section 4.3).
-The window border and background can be a solid color or a pattern, called
-a tile.
-All windows except the root have a parent and are clipped by their parent.
-If a window is stacked on top of another window, it obscures that other
-window for the purpose of input.
-If a window has a background (almost all do), it obscures the other
-window for purposes of output.
-Attempts to output to the obscured area do nothing, 
-and no input events (for example, pointer motion) are generated for the 
-obscured area.
-.LP
-Windows also have associated property lists (see section 4.3).
-.LP
-Both
-.PN InputOutput
-and
-.PN InputOnly
-windows have the following common attributes,
-which are the only attributes of an
-.PN InputOnly
-window:
-.IP \(bu 5
-win-gravity
-.IP \(bu 5
-event-mask
-.IP \(bu 5
-do-not-propagate-mask
-.IP \(bu 5
-override-redirect
-.IP \(bu 5
-cursor
-.LP
-If you specify any other attributes for an
-.PN InputOnly
-window,
-a
-.PN BadMatch
-error results.
-.LP
-.PN InputOnly
-windows are used for controlling input events in situations where
-.PN InputOutput
-windows are unnecessary.
-.PN InputOnly
-windows are invisible; can only be used to control such things as
-cursors, input event generation, and grabbing;
-and cannot be used in any graphics requests.
-Note that
-.PN InputOnly
-windows cannot have
-.PN InputOutput
-windows as inferiors.
-.LP
-Windows have borders of a programmable width and pattern
-as well as a background pattern or tile.
-.IN "Tile" "pixmaps"
-Pixel values can be used for solid colors.
-.IN "Resource IDs" "freeing"
-.IN "Freeing" "resources"
-The background and border pixmaps can be destroyed immediately after
-creating the window if no further explicit references to them
-are to be made.
-.IN "Tile" "mode" 
-The pattern can either be relative to the parent 
-or absolute.
-If
-.PN ParentRelative ,
-the parent's background is used.
-.LP
-When windows are first created, 
-they are not visible (not mapped) on the screen.
-Any output to a window that is not visible on the screen 
-and that does not have backing store will be discarded.
-.IN "Window" "mapping"
-An application may wish to create a window long before it is
-mapped to the screen.
-When a window is eventually mapped to the screen 
-(using
-.PN XMapWindow ),
-.IN "XMapWindow"
-the X server generates an 
-.PN Expose 
-event for the window if backing store has not been maintained.
-.LP
-A window manager can override your choice of size, 
-border width, and position for a top-level window.
-Your program must be prepared to use the actual size and position
-of the top window.
-It is not acceptable for a client application to resize itself
-unless in direct response to a human command to do so.
-Instead, either your program should use the space given to it,
-or if the space is too small for any useful work, your program
-might ask the user to resize the window.
-The border of your top-level window is considered fair game 
-for window managers.
-.LP
-To set an attribute of a window,
-set the appropriate member of the
-.PN XSetWindowAttributes
-structure and OR in the corresponding value bitmask in your subsequent calls to
-.PN XCreateWindow
-and
-.PN XChangeWindowAttributes ,
-or use one of the other convenience functions that set the appropriate 
-attribute.
-The symbols for the value mask bits and the
-.PN XSetWindowAttributes
-structure are:
-.sM
-.LP
-/* Window attribute value mask bits */
-.TS
-lw(.5i) lw(2.5i) lw(.8i).
-T{
-#define
-T}	T{
-.PN CWBackPixmap
-T}	T{
-(1L<<0)
-T}
-T{
-#define
-T}	T{
-.PN CWBackPixel
-T}	T{
-(1L<<1)
-T}
-T{
-#define
-T}	T{
-.PN CWBorderPixmap
-T}	T{
-(1L<<2)
-T}
-T{
-#define
-T}	T{
-.PN CWBorderPixel
-T}	T{
-(1L<<3)
-T}
-T{
-#define
-T}	T{
-.PN CWBitGravity
-T}	T{
-(1L<<4)
-T}
-T{
-#define
-T}	T{
-.PN CWWinGravity
-T}	T{
-(1L<<5)
-T}
-T{
-#define
-T}	T{
-.PN CWBackingStore
-T}	T{
-(1L<<6)
-T}
-T{
-#define
-T}	T{
-.PN CWBackingPlanes
-T}	T{
-(1L<<7)
-T}
-T{
-#define
-T}	T{
-.PN CWBackingPixel
-T}	T{
-(1L<<8)
-T}
-T{
-#define
-T}	T{
-.PN CWOverrideRedirect
-T}	T{
-(1L<<9)
-T}
-T{
-#define
-T}	T{
-.PN CWSaveUnder
-T}	T{
-(1L<<10)
-T}
-T{
-#define
-T}	T{
-.PN CWEventMask
-T}	T{
-(1L<<11)
-T}
-T{
-#define
-T}	T{
-.PN CWDontPropagate
-T}	T{
-(1L<<12)
-T}
-T{
-#define
-T}	T{
-.PN CWColormap
-T}	T{
-(1L<<13)
-T}
-T{
-#define
-T}	T{
-.PN CWCursor
-T}	T{
-(1L<<14)
-T}
-.TE
-.IN "XSetWindowAttributes" "" "@DEF@"
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-/* Values */
-
-typedef struct {
-	Pixmap background_pixmap;	/* background, None, or ParentRelative */
-	unsigned long background_pixel;	/* background pixel */
-	Pixmap border_pixmap;		/* border of the window or CopyFromParent */
-	unsigned long border_pixel;	/* border pixel value */
-	int bit_gravity;	/* one of bit gravity values */
-	int win_gravity;	/* one of the window gravity values */
-	int backing_store;	/* NotUseful, WhenMapped, Always */
-	unsigned long backing_planes;	/* planes to be preserved if possible */
-	unsigned long backing_pixel;	/* value to use in restoring planes */
-	Bool save_under;	/* should bits under be saved? (popups) */
-	long event_mask;	/* set of events that should be saved */
-	long do_not_propagate_mask;	/* set of events that should not propagate */
-	Bool override_redirect;	/* boolean value for override_redirect */
-	Colormap colormap;	/* color map to be associated with window */
-	Cursor cursor;		/* cursor to be displayed (or None) */
-} XSetWindowAttributes;
-.De
-.LP
-.eM
-The following lists the defaults for each window attribute and indicates
-whether the attribute is applicable to
-.PN InputOutput
-and
-.PN InputOnly
-windows:
-.TS H
-l l l l
-lw(1.4i) lw(1.3i) cw(.9i) cw(.8i).
-_
-.sp 6p
-T{
-.B Attribute
-T}	T{
-.B Default 
-T}	T{
-.PN InputOutput
-T}	T{
-.PN InputOnly
-T}
-.sp 6p
-_
-.sp 6p
-.TH
-.R
-T{
-background-pixmap
-T}	T{
-.PN None
-T}	T{
-Yes
-T}	T{
-No
-T}
-background-pixel	Undefined	Yes	No
-T{
-border-pixmap
-T}	T{
-.PN CopyFromParent
-T}	T{
-Yes
-T}	T{
-No
-T}
-border-pixel	Undefined	Yes	No
-T{
-bit-gravity
-T}	T{
-.PN ForgetGravity
-T}	T{
-Yes
-T}	T{
-No
-T}
-T{
-win-gravity
-T}	T{
-.PN NorthWestGravity
-T}	T{
-Yes
-T}	T{
-Yes
-T}
-T{
-backing-store
-T}	T{
-.PN NotUseful
-T}	T{
-Yes
-T}	T{
-No
-T}
-backing-planes	All ones	Yes	No
-backing-pixel	zero	Yes	No
-T{
-save-under
-T}	T{
-.PN False
-T}	T{
-Yes
-T}	T{
-No
-T}
-event-mask	empty set	Yes	Yes
-do-not-propagate-mask	empty set	Yes	Yes
-T{
-override-redirect
-T}	T{
-.PN False
-T}	T{
-Yes
-T}	T{
-Yes
-T}
-T{
-colormap
-T}	T{
-.PN CopyFromParent
-T}	T{
-Yes
-T}	T{
-No
-T}
-T{
-cursor
-T}	T{
-.PN None
-T}	T{
-Yes
-T}	T{
-Yes
-T}
-_
-.TE
-.NH 3
-Background Attribute
-.XS
-\*(SN Background Attribute
-.XE
-.LP
-Only
-.PN InputOutput
-windows can have a background.
-You can set the background of an
-.PN InputOutput
-window by using a pixel or a pixmap.
-.LP
-The background-pixmap attribute of a window specifies the pixmap to be used for 
-a window's background.
-This pixmap can be of any size, although some sizes may be faster than others.
-The background-pixel attribute of a window specifies a pixel value used to paint
-a window's background in a single color.
-.LP
-You can set the background-pixmap to a pixmap,  
-.PN None 
-(default), or 
-.PN ParentRelative .
-You can set the background-pixel of a window to any pixel value (no default).
-If you specify a background-pixel, 
-it overrides either the default background-pixmap
-or any value you may have set in the background-pixmap.
-A pixmap of an undefined size that is filled with the background-pixel is used 
-for the background.
-Range checking is not performed on the background pixel;
-it simply is truncated to the appropriate number of bits.
-.LP
-If you set the background-pixmap,
-it overrides the default.
-The background-pixmap and the window must have the same depth,
-or a
-.PN BadMatch
-error results.
-If you set background-pixmap to
-.PN None ,
-the window has no defined background.  
-If you set the background-pixmap to
-.PN ParentRelative :
-.IP \(bu 5
-The parent window's background-pixmap is used. 
-The child window, however, must have the same depth as 
-its parent,
-or a
-.PN BadMatch
-error results.
-.IP \(bu 5
-If the parent window has a background-pixmap of
-.PN None ,
-the window also has a background-pixmap of
-.PN None . 
-.IP \(bu 5
-A copy of the parent window's background-pixmap is not made.
-The parent's background-pixmap is examined each time the child window's 
-background-pixmap is required.  
-.IP \(bu 5
-The background tile origin always aligns with the parent window's
-background tile origin. 
-If the background-pixmap is not
-.PN ParentRelative ,
-the background tile origin is the child window's origin.
-.LP
-Setting a new background, whether by setting background-pixmap or
-background-pixel, overrides any previous background.
-The background-pixmap can be freed immediately if no further explicit reference
-is made to it (the X server will keep a copy to use when needed).
-If you later draw into the pixmap used for the background,
-what happens is undefined because the
-X implementation is free to make a copy of the pixmap or
-to use the same pixmap.
-.LP
-When no valid contents are available for regions of a window
-and either the regions are visible or the server is maintaining backing store,
-the server automatically tiles the regions with the window's background
-unless the window has a background of
-.PN None .
-If the background is
-.PN None ,
-the previous screen contents from other windows of the same depth as the window
-are simply left in place as long as the contents come from the parent of the
-window or an inferior of the parent.
-Otherwise, the initial contents of the exposed regions are undefined.
-.PN Expose 
-events are then generated for the regions, even if the background-pixmap
-is
-.PN None 
-(see section 10.9).
-.NH 3
-Border Attribute
-.XS
-\*(SN Border Attribute
-.XE
-.LP
-Only
-.PN InputOutput
-windows can have a border.
-You can set the border of an
-.PN InputOutput
-window by using a pixel or a pixmap.
-.LP
-The border-pixmap attribute of a window specifies the pixmap to be used 
-for a window's border.
-The border-pixel attribute of a window specifies a pixmap of undefined size 
-filled with that pixel be used for a window's border. 
-Range checking is not performed on the background pixel;
-it simply is truncated to the appropriate number of bits.
-The border tile origin is always the same as the background tile origin.
-.LP
-You can also set the border-pixmap to a pixmap of any size (some may be faster
-than others) or to
-.PN CopyFromParent 
-(default).
-You can set the border-pixel to any pixel value (no default).
-.LP
-If you set a border-pixmap, 
-it overrides the default.
-The border-pixmap and the window must have the same depth,
-or a
-.PN BadMatch
-error results.
-If you set the border-pixmap to 
-.PN CopyFromParent ,
-the parent window's border-pixmap is copied.
-Subsequent changes to the parent window's border attribute do not affect 
-the child window.
-However, the child window must have the same depth as the parent window,
-or a
-.PN BadMatch
-error results.
-.LP
-The border-pixmap can be freed immediately if no further explicit reference
-is made to it.
-If you later draw into the pixmap used for the border,
-what happens is undefined because the
-X implementation is free either to make a copy of the pixmap or
-to use the same pixmap.
-If you specify a border-pixel, 
-it overrides either the default border-pixmap
-or any value you may have set in the border-pixmap.
-All pixels in the window's border will be set to the border-pixel.
-Setting a new border, whether by setting border-pixel or by setting
-border-pixmap, overrides any previous border.
-.LP
-Output to a window is always clipped to the inside of the window. 
-Therefore, graphics operations never affect the window border.
-.NH 3
-Gravity Attributes
-.XS
-\*(SN Gravity Attributes
-.XE
-.LP
-The bit gravity of a window defines which region of the window should be 
-retained when an
-.PN InputOutput
-window is resized. 
-The default value for the bit-gravity attribute is 
-.PN ForgetGravity .
-The window gravity of a window allows you to define how the 
-.PN InputOutput
-or
-.PN InputOnly
-window should be repositioned if its parent is resized.  
-The default value for the win-gravity attribute is 
-.PN NorthWestGravity .
-.LP
-If the inside width or height of a window is not changed 
-and if the window is moved or its border is changed, 
-then the contents of the window are not lost but move with the window.
-Changing the inside width or height of the window causes its contents to be
-moved or lost (depending on the bit-gravity of the window) and causes
-children to be reconfigured (depending on their win-gravity).
-For a
-change of width and height, the (x, y) pairs are defined:
-.LP
-.TS
-l l
-l l.
-_
-.sp 6p
-.B
-Gravity Direction	Coordinates
-.sp 6p
-_
-.sp 6p
-.R
-T{
-.PN NorthWestGravity
-T}	T{
-(0, 0)
-T}
-T{
-.PN NorthGravity
-T}	T{
-(Width/2, 0)
-T}
-T{
-.PN NorthEastGravity
-T}	T{
-(Width, 0)
-T}
-T{
-.PN WestGravity
-T}	T{
-(0, Height/2)
-T}
-T{
-.PN CenterGravity
-T}	T{
-(Width/2, Height/2)
-T}
-T{
-.PN EastGravity
-T}	T{
-(Width, Height/2)
-T}
-T{
-.PN SouthWestGravity
-T}	T{
-(0, Height)
-T}
-T{
-.PN SouthGravity
-T}	T{
-(Width/2, Height)
-T}
-T{
-.PN SouthEastGravity
-T}	T{
-(Width, Height)
-T}
-.sp 6p
-_
-.TE
-.LP
-When a window with one of these bit-gravity values is resized, 
-the corresponding pair
-defines the change in position of each pixel in the window.
-When a window with one of these win-gravities has its parent window resized,
-the corresponding pair defines the change in position of the window 
-within the parent.
-When a window is so repositioned, a
-.PN GravityNotify
-event is generated (see section 10.10.5).
-.LP
-A bit-gravity of
-.PN StaticGravity 
-indicates that the contents or origin should not move relative to the 
-origin of the root window.
-If the change in size of the window is coupled with a change in position (x, y),
-then for bit-gravity the change in position of each pixel is (\-x, \-y), and for
-win-gravity the change in position of a child when its parent is so resized is
-(\-x, \-y).
-Note that
-.PN StaticGravity
-still only takes effect when the width or height of the window is changed, 
-not when the window is moved.
-.LP
-A bit-gravity of 
-.PN ForgetGravity 
-indicates that the window's contents are always discarded after a size change, 
-even if a backing store or save under has been requested.
-The window is tiled with its background
-and zero or more 
-.PN Expose 
-events are generated. 
-If no background is defined, the existing screen contents are not
-altered.
-Some X servers may also ignore the specified bit-gravity and 
-always generate 
-.PN Expose
-events.
-.LP
-The contents and borders of inferiors are not affected by their parent's
-bit-gravity.
-A server is permitted to ignore the specified bit-gravity and use
-.PN Forget
-instead.
-.LP
-A win-gravity of 
-.PN UnmapGravity 
-is like 
-.PN NorthWestGravity
-(the window is not moved),
-except the child is also
-unmapped when the parent is resized,
-and an 
-.PN UnmapNotify 
-event is
-generated.
-.NH 3
-Backing Store Attribute
-.XS
-\*(SN Backing Store Attribute
-.XE
-.LP
-Some implementations of the X server may choose to maintain the contents of 
-.PN InputOutput
-windows.
-If the X server maintains the contents of a window, 
-the off-screen saved pixels
-are known as backing store.
-The backing store advises the X server on what to do 
-with the contents of a window.
-The backing-store attribute can be set to
-.PN NotUseful 
-(default),
-.PN WhenMapped ,
-or
-.PN Always .
-.LP
-A backing-store attribute of 
-.PN NotUseful 
-advises the X server that 
-maintaining contents is unnecessary, 
-although some X implementations may
-still choose to maintain contents and, therefore, not generate 
-.PN Expose
-events.
-A backing-store attribute of 
-.PN WhenMapped 
-advises the X server that maintaining contents of 
-obscured regions when the window is mapped would be beneficial.
-In this case,
-the server may generate an 
-.PN Expose 
-event when the window is created.
-A backing-store attribute of 
-.PN Always 
-advises the X server that maintaining contents even when 
-the window is unmapped would be beneficial.  
-Even if the window is larger than its parent, 
-this is a request to the X server to maintain complete contents, 
-not just the region within the parent window boundaries.  
-While the X server maintains the window's contents, 
-.PN Expose 
-events normally are not generated, 
-but the X server may stop maintaining 
-contents at any time.  
-.LP
-When the contents of obscured regions of a window are being maintained,
-regions obscured by noninferior windows are included in the destination
-of graphics requests (and source, when the window is the source).
-However, regions obscured by inferior windows are not included.
-.NH 3
-Save Under Flag
-.XS
-\*(SN Save Under Flag
-.XE
-.IN "Save Unders"
-.LP
-Some server implementations may preserve contents of 
-.PN InputOutput
-windows under other 
-.PN InputOutput
-windows.
-This is not the same as preserving the contents of a window for you.
-You may get better visual
-appeal if transient windows (for example, pop-up menus) request that the system
-preserve the screen contents under them, 
-so the temporarily obscured applications do not have to repaint.
-.LP
-You can set the save-under flag to
-.PN True
-or
-.PN False 
-(default).
-If save-under is 
-.PN True , 
-the X server is advised that, when this window is mapped, 
-saving the contents of windows it obscures would be beneficial.
-.NH 3
-Backing Planes and Backing Pixel Attributes
-.XS
-\*(SN Backing Planes and Backing Pixel Attributes
-.XE
-.LP
-You can set backing planes to indicate (with bits set to 1) 
-which bit planes of an
-.PN InputOutput
-window hold dynamic data that must be preserved in backing store 
-and during save unders.
-The default value for the backing-planes attribute is all bits set to 1.
-You can set backing pixel to specify what bits to use in planes not 
-covered by backing planes.
-The default value for the backing-pixel attribute is all bits set to 0.
-The X server is free to save only the specified bit planes in the backing store
-or the save under and is free to regenerate the remaining planes with 
-the specified pixel value.
-Any extraneous bits in these values (that is, those bits beyond 
-the specified depth of the window) may be simply ignored.
-If you request backing store or save unders,
-you should use these members to minimize the amount of off-screen memory 
-required to store your window.
-.NH 3
-Event Mask and Do Not Propagate Mask Attributes
-.XS
-\*(SN Event Mask and Do Not Propagate Mask Attributes
-.XE
-.LP
-The event mask defines which events the client is interested in for this 
-.PN InputOutput
-or
-.PN InputOnly
-window (or, for some event types, inferiors of this window).
-The event mask is the bitwise inclusive OR of zero or more of the 
-valid event mask bits.
-You can specify that no maskable events are reported by setting 
-.PN NoEventMask 
-(default).
-.LP
-The do-not-propagate-mask attribute
-defines which events should not be propagated to 
-ancestor windows when no client has the event type selected in this 
-.PN InputOutput
-or
-.PN InputOnly
-window.
-The do-not-propagate-mask is the bitwise inclusive OR of zero or more
-of the following masks:
-.PN KeyPress , 
-.PN KeyRelease ,
-.PN ButtonPress , 
-.PN ButtonRelease ,
-.PN PointerMotion ,
-.PN Button1Motion , 
-.PN Button2Motion , 
-.PN Button3Motion ,
-.PN Button4Motion , 
-.PN Button5Motion , 
-and
-.PN ButtonMotion .
-You can specify that all events are propagated by setting 
-.PN NoEventMask 
-(default).
-.NH 3
-Override Redirect Flag
-.XS
-\*(SN Override Redirect Flag
-.XE
-.LP
-To control window placement or to add decoration,
-a window manager often needs to intercept (redirect) any map or configure
-request.
-Pop-up windows, however, often need to be mapped without a window manager
-getting in the way.
-To control whether an
-.PN InputOutput
-or
-.PN InputOnly
-window is to ignore these structure control facilities,
-use the override-redirect flag.
-.LP
-The override-redirect flag specifies whether map and configure requests 
-on this window should override a 
-.PN SubstructureRedirectMask 
-on the parent.
-You can set the override-redirect flag to
-.PN True
-or
-.PN False 
-(default).
-Window managers use this information to avoid tampering with pop-up windows
-(see also chapter 14).
-.NH 3
-Colormap Attribute
-.XS
-\*(SN Colormap Attribute
-.XE
-.LP
-The colormap attribute specifies which colormap best reflects the true
-colors of the 
-.PN InputOutput
-window.  
-The colormap must have the same visual type as the window,
-or a 
-.PN BadMatch 
-error results.  
-X servers capable of supporting multiple 
-hardware colormaps can use this information, 
-and window managers can use it for calls to
-.PN XInstallColormap .
-You can set the colormap attribute to a colormap or to
-.PN CopyFromParent
-(default).
-.LP
-If you set the colormap to
-.PN CopyFromParent ,
-the parent window's colormap is copied and used by its child.
-However, the child window must have the same visual type as the parent, 
-or a 
-.PN BadMatch 
-error results. 
-The parent window must not have a colormap of 
-.PN None ,
-or a 
-.PN BadMatch 
-error results.
-The colormap is copied by sharing the colormap object between the child 
-and parent, not by making a complete copy of the colormap contents.
-Subsequent changes to the parent window's colormap attribute do
-not affect the child window.
-.NH 3
-Cursor Attribute
-.XS
-\*(SN Cursor Attribute
-.XE
-.LP
-The cursor attribute specifies which cursor is to be used when the pointer is
-in the 
-.PN InputOutput
-or
-.PN InputOnly
-window.
-You can set the cursor to a cursor or
-.PN None
-(default).
-.LP
-If you set the cursor to
-.PN None ,
-the parent's cursor is used when the 
-pointer is in the 
-.PN InputOutput
-or
-.PN InputOnly
-window, and any change in the parent's cursor will cause an
-immediate change in the displayed cursor.
-By calling
-.PN XFreeCursor ,
-the cursor can be freed immediately as long as no further explicit reference 
-to it is made.
-.NH 2
-Creating Windows
-.XS
-\*(SN Creating Windows
-.XE
-.LP
-Xlib provides basic ways for creating windows,
-and toolkits often supply higher-level functions specifically for
-creating and placing top-level windows,
-which are discussed in the appropriate toolkit documentation.
-If you do not use a toolkit, however,
-you must provide some standard information or hints for the window
-manager by using the Xlib inter-client communication functions
-(see chapter 14).
-.LP
-If you use Xlib to create your own top-level windows
-(direct children of the root window),
-you must observe the following rules so that all applications interact
-reasonably across the different styles of window management:
-.IP \(bu 5
-You must never fight with the window manager for the size or
-placement of your top-level window.
-.IP \(bu 5
-You must be able to deal with whatever size window you get, 
-even if this means that your application just prints a message 
-like ``Please make me bigger'' in its window.
-.IP \(bu 5
-You should only attempt to resize or move top-level windows in
-direct response to a user request.
-If a request to change the size of a top-level window fails,
-you must be prepared to live with what you get.
-You are free to resize or move the children of top-level
-windows as necessary.
-(Toolkits often have facilities for automatic relayout.)
-.IP \(bu 5
-If you do not use a toolkit that automatically sets standard window properties,
-you should set these properties for top-level windows before mapping them.
-.LP
-For further information,
-see chapter 14 and the \fIInter-Client Communication Conventions Manual\fP.
-.LP
-.PN XCreateWindow
-is the more general function that allows you to set specific window attributes 
-when you create a window.
-.PN XCreateSimpleWindow 
-creates a window that inherits its attributes from its parent window.
-.LP
-.IN "Window" "InputOnly"
-The X server acts as if 
-.PN InputOnly 
-windows do not exist for
-the purposes of graphics requests, exposure processing, and
-.PN VisibilityNotify 
-events.
-An 
-.PN InputOnly 
-window cannot be used as a
-drawable (that is, as a source or destination for graphics requests).
-.PN InputOnly
-and 
-.PN InputOutput 
-windows act identically in other respects (properties,
-grabs, input control, and so on).
-Extension packages can define other classes of windows.
-.LP
-To create an unmapped window and set its window attributes, use
-.PN XCreateWindow .
-.IN "XCreateWindow" "" "@DEF@"
-.sM
-.FD 0
-Window XCreateWindow\^(\^\fIdisplay\fP, \fIparent\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIborder_width\fP\^, \fIdepth\fP\^, 
-.br
-                       \fIclass\fP\^, \fIvisual\fP\^, \fIvaluemask\fP\^, \fIattributes\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIparent\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^; 
-.br
-      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
-.br
-      unsigned int \fIborder_width\fP\^;
-.br
-      int \fIdepth\fP\^;
-.br
-      unsigned int \fIclass\fP\^;
-.br
-      Visual *\fIvisual\fP\^;
-.br
-      unsigned long \fIvaluemask\fP\^;
-.br
-      XSetWindowAttributes *\fIattributes\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIparent\fP 1i
-Specifies the parent window.
-.ds Xy , which are the top-left outside corner of the created window's \
-borders and are relative to the inside of the parent window's borders
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.ds Wh , which are the created window's inside dimensions \
-and do not include the created window's borders
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height\*(Wh.
-The dimensions must be nonzero,
-or a
-.PN BadValue
-error results.
-.IP \fIborder_width\fP 1i
-Specifies the width of the created window's border in pixels.
-.IP \fIdepth\fP 1i
-Specifies the window's depth.
-A depth of 
-.PN CopyFromParent
-means the depth is taken from the parent.
-.IP \fIclass\fP 1i
-Specifies the created window's class.
-You can pass
-.PN InputOutput , 
-.PN InputOnly , 
-or 
-.PN CopyFromParent .
-A class of 
-.PN CopyFromParent
-means the class
-is taken from the parent.
-.IP \fIvisual\fP 1i
-Specifies the visual type.
-A visual of 
-.PN CopyFromParent 
-means the visual type is taken from the 
-parent.
-.IP \fIvaluemask\fP 1i
-Specifies which window attributes are defined in the attributes
-argument.
-This mask is the bitwise inclusive OR of the valid attribute mask bits.
-If valuemask is zero,
-the attributes are ignored and are not referenced.
-.IP \fIattributes\fP 1i
-Specifies the structure from which the values (as specified by the value mask)
-are to be taken.
-The value mask should have the appropriate bits
-set to indicate which attributes have been set in the structure.
-.LP
-.eM
-The
-.PN XCreateWindow
-function creates an unmapped subwindow for a specified parent window, 
-returns the window ID of the created window, 
-and causes the X server to generate a
-.PN CreateNotify
-event.
-The created window is placed on top in the stacking order 
-with respect to siblings.
-.LP
-The coordinate system has the X axis horizontal and the Y axis vertical
-with the origin [0, 0] at the upper-left corner.
-Coordinates are integral,
-in terms of pixels,
-and coincide with pixel centers.
-Each window and pixmap has its own coordinate system.
-For a window, 
-the origin is inside the border at the inside, upper-left corner.
-.LP
-The border_width for an
-.PN InputOnly
-window must be zero, or a
-.PN BadMatch
-error results.
-For class
-.PN InputOutput ,
-the visual type and depth must be a combination supported for the screen,
-or a
-.PN BadMatch
-error results.
-The depth need not be the same as the parent,
-but the parent must not be a window of class 
-.PN InputOnly ,
-or a
-.PN BadMatch
-error results.
-For an
-.PN InputOnly
-window,
-the depth must be zero, and the visual must be one supported by the screen.
-If either condition is not met,
-a
-.PN BadMatch
-error results.
-The parent window, however, may have any depth and class.
-If you specify any invalid window attribute for a window, a
-.PN BadMatch
-error results.
-.LP
-The created window is not yet displayed (mapped) on the user's display.
-To display the window, call
-.PN XMapWindow .
-The new window initially uses the same cursor as
-its parent. 
-A new cursor can be defined for the new window by calling
-.PN XDefineCursor .
-.IN "Cursor" "Initial State"
-.IN "XDefineCursor" 
-The window will not be visible on the screen unless it and all of its
-ancestors are mapped and it is not obscured by any of its ancestors.
-.LP
-.PN XCreateWindow
-can generate
-.PN BadAlloc ,
-.PN BadColor ,
-.PN BadCursor ,
-.PN BadMatch ,
-.PN BadPixmap ,
-.PN BadValue ,
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To create an unmapped 
-.PN InputOutput
-subwindow of a given parent window, use
-.PN XCreateSimpleWindow .
-.IN "XCreateSimpleWindow" "" "@DEF@"
-.sM
-.FD 0
-Window XCreateSimpleWindow\^(\^\fIdisplay\fP, \fIparent\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIborder_width\fP\^, 
-.br
-                             \fIborder\fP\^, \fIbackground\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIparent\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.br
-      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
-.br
-      unsigned int \fIborder_width\fP\^;
-.br
-      unsigned long \fIborder\fP\^;
-.br
-      unsigned long \fIbackground\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIparent\fP 1i
-Specifies the parent window.
-.ds Xy , which are the top-left outside corner of the new window's borders \
-and are relative to the inside of the parent window's borders
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.ds Wh , which are the created window's inside dimensions \
-and do not include the created window's borders
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height\*(Wh.
-The dimensions must be nonzero,
-or a
-.PN BadValue
-error results.
-.IP \fIborder_width\fP 1i
-Specifies the width of the created window's border in pixels.
-.IP \fIborder\fP 1i
-Specifies the border pixel value of the window.
-.IP \fIbackground\fP 1i
-Specifies the background pixel value of the window.
-
-.LP
-.eM
-The
-.PN XCreateSimpleWindow
-function creates an unmapped
-.PN InputOutput
-subwindow for a specified parent window, returns the
-window ID of the created window, and causes the X server to generate a
-.PN CreateNotify
-event.
-The created window is placed on top in the stacking order with respect to 
-siblings.
-Any part of the window that extends outside its parent window is clipped.
-The border_width for an
-.PN InputOnly
-window must be zero, or a
-.PN BadMatch
-error results.
-.PN XCreateSimpleWindow
-inherits its depth, class, and visual from its parent.
-All other window attributes, except background and border, 
-have their default values.
-.LP
-.PN XCreateSimpleWindow
-can generate
-.PN BadAlloc ,
-.PN BadMatch ,
-.PN BadValue ,
-and
-.PN BadWindow 
-errors.
-.NH 2
-Destroying Windows
-.XS
-\*(SN Destroying Windows 
-.XE
-.LP
-Xlib provides functions that you can use to destroy a window or destroy all
-subwindows of a window.
-.LP
-.sp
-To destroy a window and all of its subwindows, use
-.PN XDestroyWindow .
-.IN "XDestroyWindow" "" "@DEF@"
-.sM
-.FD 0
-XDestroyWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.LP
-.eM
-The
-.PN XDestroyWindow
-function destroys the specified window as well as all of its subwindows and causes
-the X server to generate a
-.PN DestroyNotify
-event for each window.
-The window should never be referenced again.
-If the window specified by the w argument is mapped,
-it is unmapped automatically.
-The ordering of the
-.PN DestroyNotify
-events is such that for any given window being destroyed,
-.PN DestroyNotify
-is generated on any inferiors of the window before being generated on
-the window itself.
-The ordering among siblings and across subhierarchies is not otherwise
-constrained.
-If the window you specified is a root window, no windows are destroyed.
-Destroying a mapped window will generate 
-.PN Expose 
-events on other windows that were obscured by the window being destroyed.
-.LP
-.PN XDestroyWindow
-can generate a
-.PN BadWindow 
-error.
-.LP
-.sp
-To destroy all subwindows of a specified window, use 
-.PN XDestroySubwindows .
-.IN "XDestroySubwindows" "" "@DEF@"
-.sM
-.FD 0
-XDestroySubwindows\^(\^\fIdisplay\fP, \fIw\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.LP
-.eM
-The
-.PN XDestroySubwindows
-function destroys all inferior windows of the specified window, 
-in bottom-to-top stacking order.
-It causes the X server to generate a
-.PN DestroyNotify
-event for each window.
-If any mapped
-subwindows were actually destroyed,
-.PN XDestroySubwindows
-causes the X server to generate 
-.PN Expose 
-events on the specified window.
-This is much more efficient than deleting many windows
-one at a time because much of the work need be performed only once for all
-of the windows, rather than for each window.
-The subwindows should never be referenced again.  
-.LP
-.PN XDestroySubwindows
-can generate a
-.PN BadWindow 
-error.
-.NH 2
-Mapping Windows 
-.XS
-\*(SN Mapping Windows 
-.XE
-.LP
-A window is considered mapped if an 
-.PN XMapWindow
-call has been made on it.
-It may not be visible on the screen for one of the following reasons:
-.IP \(bu 5
-It is obscured by another opaque window.
-.IP \(bu 5
-One of its ancestors is not mapped.
-.IP \(bu 5
-It is entirely clipped by an ancestor.
-.LP
-.PN Expose 
-events are generated for the window when part or all of
-it becomes visible on the screen. 
-A client receives the
-.PN Expose 
-events only if it has asked for them.
-Windows retain their position in the stacking order when they are unmapped.
-.LP
-A window manager may want to control the placement of subwindows.
-If 
-.PN SubstructureRedirectMask 
-has been selected by a window manager
-on a parent window (usually a root window),
-a map request initiated by other clients on a child window is not performed,
-and the window manager is sent a 
-.PN MapRequest 
-event.
-However, if the override-redirect flag on the child had been set to
-.PN True
-(usually only on pop-up menus),
-the map request is performed.
-.LP
-A tiling window manager might decide to reposition and resize other clients' 
-windows and then decide to map the window to its final location.
-A window manager that wants to provide decoration might
-reparent the child into a frame first.
-For further information,
-see sections 3.2.8 and 10.10.
-Only a single client at a time can select for 
-.PN SubstructureRedirectMask .
-.LP
-Similarly, a single client can select for 
-.PN ResizeRedirectMask 
-on a parent window.
-Then, any attempt to resize the window by another client is suppressed, and
-the client receives a 
-.PN ResizeRequest 
-event.
-.LP
-.sp
-To map a given window, use 
-.PN XMapWindow .
-.IN "XMapWindow" "" "@DEF@"
-.sM
-.FD 0
-XMapWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.LP
-.eM
-The
-.PN XMapWindow
-function
-maps the window and all of its
-subwindows that have had map requests.
-Mapping a window that has an unmapped ancestor does not display the
-window but marks it as eligible for display when the ancestor becomes
-mapped.
-Such a window is called unviewable.
-When all its ancestors are mapped,
-the window becomes viewable
-and will be visible on the screen if it is not obscured by another window.
-This function has no effect if the window is already mapped.
-.LP
-If the override-redirect of the window is
-.PN False 
-and if some other client has selected
-.PN SubstructureRedirectMask
-on the parent window, then the X server generates a
-.PN MapRequest
-event, and the
-.PN XMapWindow
-function does not map the window.
-Otherwise, the window is mapped, and the X server generates a
-.PN MapNotify
-event.
-.LP
-If the window becomes viewable and no earlier contents for it are remembered,
-the X server tiles the window with its background.
-If the window's background is undefined,
-the existing screen contents are not
-altered, and the X server generates zero or more 
-.PN Expose
-events.
-If backing-store was maintained while the window was unmapped, no 
-.PN Expose
-events
-are generated.
-If backing-store will now be maintained, 
-a full-window exposure is always generated.
-Otherwise, only visible regions may be reported.
-Similar tiling and exposure take place for any newly viewable inferiors.
-.LP
-.IN "XMapWindow"
-If the window is an
-.PN InputOutput 
-window,
-.PN XMapWindow
-generates 
-.PN Expose 
-events on each 
-.PN InputOutput
-window that it causes to be displayed.
-If the client maps and paints the window 
-and if the client begins processing events, 
-the window is painted twice.
-To avoid this,
-first ask for 
-.PN Expose 
-events and then map the window,
-so the client processes input events as usual.
-The event list will include 
-.PN Expose 
-for each
-window that has appeared on the screen. 
-The client's normal response to
-an 
-.PN Expose 
-event should be to repaint the window.
-This method usually leads to simpler programs and to proper interaction
-with window managers.
-.LP
-.PN XMapWindow
-can generate a
-.PN BadWindow 
-error.
-.LP
-.sp
-To map and raise a window, use
-.PN XMapRaised .
-.IN "XMapRaised" "" "@DEF@"
-.sM
-.FD 0
-XMapRaised\^(\^\fIdisplay\fP, \fIw\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.LP
-.eM
-The
-.PN XMapRaised
-function
-essentially is similar to
-.PN XMapWindow
-in that it maps the window and all of its
-subwindows that have had map requests.
-However, it also raises the specified window to the top of the stack.
-For additional information,
-see 
-.PN XMapWindow .
-.LP
-.PN XMapRaised
-can generate multiple
-.PN BadWindow 
-errors.
-.LP
-.sp
-To map all subwindows for a specified window, use 
-.PN XMapSubwindows .
-.IN "XMapSubwindows" "" "@DEF@"
-.sM
-.FD 0
-XMapSubwindows\^(\^\fIdisplay\fP, \fIw\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.LP
-.eM
-The
-.PN XMapSubwindows
-.IN "XMapSubwindows"
-function maps all subwindows for a specified window in top-to-bottom stacking 
-order.
-The X server generates
-.PN Expose
-events on each newly displayed window.
-This may be much more efficient than mapping many windows
-one at a time because the server needs to perform much of the work
-only once, for all of the windows, rather than for each window.
-.LP
-.PN XMapSubwindows
-can generate a
-.PN BadWindow 
-error.
-.NH 2
-Unmapping Windows
-.XS
-\*(SN Unmapping Windows 
-.XE
-.LP
-Xlib provides functions that you can use to unmap a window or all subwindows.
-.LP
-.sp
-To unmap a window, use 
-.PN XUnmapWindow .
-.IN "XUnmapWindow" "" "@DEF@"
-.sM
-.FD 0
-XUnmapWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.LP
-.eM
-The
-.PN XUnmapWindow
-function unmaps the specified window and causes the X server to generate an
-.PN UnmapNotify
-.IN "UnmapNotify Event"
-.IN "XUnmapWindow"
-event.
-If the specified window is already unmapped, 
-.PN XUnmapWindow 
-has no effect.
-Normal exposure processing on formerly obscured windows is performed.
-Any child window will no longer be visible until another map call is
-made on the parent.
-In other words, the subwindows are still mapped but are not visible
-until the parent is mapped.
-Unmapping a window will generate 
-.PN Expose 
-events on windows that were formerly obscured by it.
-.LP
-.PN XUnmapWindow
-can generate a
-.PN BadWindow 
-error.
-.LP
-.sp
-To unmap all subwindows for a specified window, use 
-.PN XUnmapSubwindows .
-.IN "XUnmapSubwindows" "" "@DEF@"
-.sM
-.FD 0
-XUnmapSubwindows\^(\^\fIdisplay\fP, \fIw\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.LP
-.eM
-The
-.PN XUnmapSubwindows
-function unmaps all subwindows for the specified window in bottom-to-top
-stacking order.
-It causes the X server to generate an
-.PN UnmapNotify
-event on each subwindow and 
-.PN Expose 
-events on formerly obscured windows.
-.IN "UnmapNotify Event"
-Using this function is much more efficient than unmapping multiple windows
-one at a time because the server needs to perform much of the work
-only once, for all of the windows, rather than for each window.
-.LP
-.PN XUnmapSubwindows
-can generate a
-.PN BadWindow 
-error.
-.NH 2
-Configuring Windows
-.XS
-\*(SN Configuring Windows 
-.XE
-.LP
-.LP
-Xlib provides functions that you can use to
-move a window, resize a window, move and resize a window, or
-change a window's border width.
-To change one of these parameters,
-set the appropriate member of the
-.PN XWindowChanges
-structure and OR in the corresponding value mask in subsequent calls to
-.PN XConfigureWindow .
-The symbols for the value mask bits and the
-.PN XWindowChanges
-structure are:
-.sM
-.LP
-/* Configure window value mask bits */
-.TS
-lw(.5i) lw(2.5i) lw(.8i).
-T{
-#define
-T}	T{
-.PN CWX
-T}	T{
-(1<<0)
-T}
-T{
-#define
-T}	T{
-.PN CWY
-T}	T{
-(1<<1)
-T}
-T{
-#define
-T}	T{
-.PN CWWidth
-T}	T{
-(1<<2)
-T}
-T{
-#define
-T}	T{
-.PN CWHeight
-T}	T{
-(1<<3)
-T}
-T{
-#define
-T}	T{
-.PN CWBorderWidth
-T}	T{
-(1<<4)
-T}
-T{
-#define
-T}	T{
-.PN CWSibling
-T}	T{
-(1<<5)
-T}
-T{
-#define
-T}	T{
-.PN CWStackMode
-T}	T{
-(1<<6)
-T}
-.TE
-.IN "XWindowChanges" "" "@DEF@"
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-/* Values */
-
-typedef struct {
-	int x, y;
-	int width, height;
-	int border_width;
-	Window sibling;
-	int stack_mode;
-} XWindowChanges;
-.De
-.LP
-.eM
-The x and y members are used to set the window's x and y coordinates,
-which are relative to the parent's origin
-and indicate the position of the upper-left outer corner of the window.
-The width and height members are used to set the inside size of the window,
-not including the border, and must be nonzero, or a
-.PN BadValue
-error results.
-Attempts to configure a root window have no effect.
-.LP
-The border_width member is used to set the width of the border in pixels.
-Note that setting just the border width leaves the outer-left corner of the window
-in a fixed position but moves the absolute position of the window's origin.
-If you attempt to set the border-width attribute of an
-.PN InputOnly
-window nonzero, a
-.PN BadMatch
-error results. 
-.LP
-The sibling member is used to set the sibling window for stacking operations.
-The stack_mode member is used to set how the window is to be restacked 
-and can be set to
-.PN Above , 
-.PN Below , 
-.PN TopIf , 
-.PN BottomIf ,
-or 
-.PN Opposite .
-.LP
-If the override-redirect flag of the window is
-.PN False 
-and if some other client has selected
-.PN SubstructureRedirectMask
-on the parent, the X server generates a
-.PN ConfigureRequest
-event, and no further processing is performed.
-Otherwise, 
-if some other client has selected 
-.PN ResizeRedirectMask 
-on the window and the inside
-width or height of the window is being changed,
-a 
-.PN ResizeRequest
-event is generated, and the current inside width and height are
-used instead.
-Note that the override-redirect flag of the window has no effect
-on
-.PN ResizeRedirectMask 
-and that
-.PN SubstructureRedirectMask
-on the parent has precedence over
-.PN ResizeRedirectMask 
-on the window.
-.LP
-When the geometry of the window is changed as specified, 
-the window is restacked among siblings, and a
-.PN ConfigureNotify 
-event is generated if the state of the window actually changes.
-.PN GravityNotify
-events are generated after 
-.PN ConfigureNotify 
-events.
-If the inside width or height of the window has actually changed, 
-children of the window are affected as specified.
-.LP
-If a window's size actually changes,
-the window's subwindows move according to their window gravity.
-Depending on the window's bit gravity,
-the contents of the window also may be moved (see section 3.2.3).
-.LP
-If regions of the window were obscured but now are not,
-exposure processing is performed on these formerly obscured windows, 
-including the window itself and its inferiors. 
-As a result of increasing the width or height,
-exposure processing is also performed on any new regions of the window 
-and any regions where window contents are lost.
-.LP
-The restack check (specifically, the computation for 
-.PN BottomIf ,
-.PN TopIf ,
-and 
-.PN Opposite )
-is performed with respect to the window's final size and position (as
-controlled by the other arguments of the request), not its initial position.
-If a sibling is specified without a stack_mode,
-a
-.PN BadMatch
-error results.
-.LP
-If a sibling and a stack_mode are specified, 
-the window is restacked as follows:
-.TS
-lw(1i) lw(5i).
-T{
-.PN Above
-T}	T{
-The window is placed just above the sibling.
-T}
-.sp 6p
-T{
-.PN Below
-T}	T{
-The window is placed just below the sibling.
-T}
-.sp 6p
-T{
-.PN TopIf
-T}	T{
-If the sibling occludes the window, the window is placed
-at the top of the stack.
-T}
-.sp 6p
-T{
-.PN BottomIf
-T}	T{
-If the window occludes the sibling, the window is
-placed at the bottom of the stack.
-T}
-.sp 6p
-T{
-.PN Opposite
-T}	T{
-If the sibling occludes the window, the window 
-is placed at the top of the stack.
-If the window occludes the sibling, 
-the window is placed at the bottom of the stack.
-T}
-.TE
-.LP
-If a stack_mode is specified but no sibling is specified,
-the window is restacked as follows:
-.TS
-lw(1i) lw(5i).
-T{
-.PN Above
-T}	T{
-The window is placed at the top of the stack.
-T}
-.sp 6p
-T{
-.PN Below
-T}	T{
-The window is placed at the bottom of the stack.
-T}
-.sp 6p
-T{
-.PN TopIf
-T}	T{
-If any sibling occludes the window, the window is placed at
-the top of the stack.
-T}
-.sp 6p
-T{
-.PN BottomIf
-T}	T{
-If the window occludes any sibling, the window is placed at
-the bottom of the stack.
-T}
-.sp 6p
-T{
-.PN Opposite
-T}	T{
-If any sibling occludes the window, the window 
-is placed at the top of the stack. 
-If the window occludes any sibling, 
-the window is placed at the bottom of the stack.
-T}
-.TE
-.LP
-Attempts to configure a root window have no effect.
-.LP
-.sp
-To configure a window's size, location, stacking, or border, use
-.PN XConfigureWindow .
-.IN "XConfigureWindow" "" "@DEF@"
-.sM
-.FD 0
-XConfigureWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIvalue_mask\fP\^, \fIvalues\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      unsigned int \fIvalue_mask\fP\^;
-.br
-      XWindowChanges *\fIvalues\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Wi to be reconfigured
-.IP \fIw\fP 1i
-Specifies the window \*(Wi.
-.IP \fIvalue_mask\fP 1i
-Specifies which values are to be set using information in
-the values structure.
-This mask is the bitwise inclusive OR of the valid configure window values bits.
-.IP \fIvalues\fP 1i
-Specifies the 
-.PN XWindowChanges 
-structure.
-.LP
-.eM
-The
-.PN XConfigureWindow
-function uses the values specified in the
-.PN XWindowChanges
-structure to reconfigure a window's size, position, border, and stacking order.
-Values not specified are taken from the existing geometry of the window.
-.LP
-If a sibling is specified without a stack_mode or if the window
-is not actually a sibling,
-a
-.PN BadMatch
-error results. 
-Note that the computations for
-.PN BottomIf ,
-.PN TopIf ,
-and
-.PN Opposite
-are performed with respect to the window's final geometry (as controlled by the
-other arguments passed to
-.PN XConfigureWindow ),
-not its initial geometry.
-Any backing store contents of the window, its
-inferiors, and other newly visible windows are either discarded or
-changed to reflect the current screen contents 
-(depending on the implementation).
-.LP
-.PN XConfigureWindow
-can generate
-.PN BadMatch ,
-.PN BadValue ,
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To move a window without changing its size, use 
-.PN XMoveWindow .
-.IN "XMoveWindow" "" "@DEF@"
-.sM
-.FD 0 
-XMoveWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIx\fP\^, \fIy\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.FN	
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Wi to be moved
-.IP \fIw\fP 1i
-Specifies the window \*(Wi.
-.ds Xy , which define the new location of the top-left pixel \
-of the window's border or the window itself if it has no border
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.LP
-.eM
-The
-.PN XMoveWindow
-function moves the specified window to the specified x and y coordinates,
-but it does not change the window's size, raise the window, or
-change the mapping state of the window.
-Moving a mapped window may or may not lose the window's contents 
-depending on if the window is obscured by nonchildren 
-and if no backing store exists.
-If the contents of the window are lost, 
-the X server generates
-.PN Expose 
-events.
-Moving a mapped window generates
-.PN Expose 
-events on any formerly obscured windows. 
-.LP
-If the override-redirect flag of the window is 
-.PN False 
-and some
-other client has selected 
-.PN SubstructureRedirectMask 
-on the parent, the X server generates a
-.PN ConfigureRequest 
-event, and no further processing is
-performed.  
-Otherwise, the window is moved.
-.LP
-.PN XMoveWindow
-can generate a
-.PN BadWindow 
-error.
-.LP
-.sp
-To change a window's size without changing the upper-left coordinate, use 
-.PN XResizeWindow .
-.IN "XResizeWindow" "" "@DEF@"
-.sM
-.FD 0
-XResizeWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwidth\fP\^, \fIheight\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.ds Wh , which are the interior dimensions of the window \
-after the call completes
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height\*(Wh.
-.LP
-.eM
-The
-.PN XResizeWindow
-function changes the inside dimensions of the specified window, not including
-its borders.
-This function does not change the window's upper-left coordinate or
-the origin and does not restack the window.
-Changing the size of a mapped window may lose its contents and generate
-.PN Expose 
-events.
-If a mapped window is made smaller, 
-changing its size generates
-.PN Expose 
-events on windows that the mapped window formerly obscured.
-.LP
-If the override-redirect flag of the window is 
-.PN False 
-and some
-other client has selected 
-.PN SubstructureRedirectMask 
-on the parent, the X server generates a
-.PN ConfigureRequest 
-event, and no further processing is performed.  
-If either width or height is zero,
-a
-.PN BadValue
-error results.
-.LP
-.PN XResizeWindow
-can generate
-.PN BadValue
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To change the size and location of a window, use 
-.PN XMoveResizeWindow .
-.IN "XMoveResizeWindow" "" "@DEF@"
-.sM
-.FD 0
-XMoveResizeWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.br
-      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Wi to be reconfigured
-.IP \fIw\fP 1i
-Specifies the window \*(Wi.
-.ds Xy , which define the new position of the window relative to its parent
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.ds Wh , which define the interior size of the window
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height\*(Wh.
-.LP
-.eM
-The
-.PN XMoveResizeWindow
-function changes the size and location of the specified window 
-without raising it.
-Moving and resizing a mapped window may generate an
-.PN Expose 
-event on the window.
-Depending on the new size and location parameters,
-moving and resizing a window may generate 
-.PN Expose 
-events on windows that the window formerly obscured. 
-.LP
-If the override-redirect flag of the window is 
-.PN False 
-and some
-other client has selected 
-.PN SubstructureRedirectMask 
-on the parent, the X server generates a
-.PN ConfigureRequest 
-event, and no further processing is performed.  
-Otherwise, the window size and location are changed.
-.LP
-.PN XMoveResizeWindow
-can generate
-.PN BadValue 
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To change the border width of a given window, use
-.PN XSetWindowBorderWidth .
-.IN "XSetWindowBorderWidth" "" "@DEF@"
-.sM
-.FD 0
-XSetWindowBorderWidth\^(\^\fIdisplay\fP, \fIw\fP, \fIwidth\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      unsigned int \fIwidth\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIwidth\fP 1i
-Specifies the width of the window border.
-.LP
-.eM
-The
-.PN XSetWindowBorderWidth
-function sets the specified window's border width to the specified width.
-.LP
-.PN XSetWindowBorderWidth
-can generate a
-.PN BadWindow 
-error.
-.NH 2
-Changing Window Stacking Order
-.XS
-\*(SN Changing Window Stacking Order 
-.XE
-.LP
-.LP
-Xlib provides functions that you can use to raise, lower, circulate,
-or restack windows.
-.LP
-.sp
-To raise a window so that no sibling window obscures it, use 
-.PN XRaiseWindow .
-.IN "XRaiseWindow" "" "@DEF@"
-.sM
-.FD 0
-XRaiseWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.LP
-.eM
-The
-.PN XRaiseWindow
-function
-raises the specified window to the top of the stack so that no sibling window
-obscures it.
-If the windows are regarded as overlapping sheets of paper stacked 
-on a desk,
-then raising a window is analogous to moving the sheet to the top of
-the stack but leaving its x and y location on the desk constant.
-Raising a mapped window may generate 
-.PN Expose
-events for the window and any mapped subwindows that were formerly obscured.  
-.LP
-If the override-redirect attribute of the window is 
-.PN False 
-and some
-other client has selected 
-.PN SubstructureRedirectMask 
-on the parent, the X server generates a
-.PN ConfigureRequest 
-event, and no processing is performed.
-Otherwise, the window is raised.
-.LP
-.PN XRaiseWindow
-can generate a
-.PN BadWindow 
-error.
-.LP
-.sp
-To lower a window so that it does not obscure any sibling windows, use 
-.PN XLowerWindow .
-.IN "XLowerWindow" "" "@DEF@"
-.sM
-.FD 0
-XLowerWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.LP
-.eM
-The
-.PN XLowerWindow
-function lowers the specified window to the bottom of the stack
-so that it does not obscure any sibling
-windows.
-If the windows are regarded as overlapping sheets of paper
-stacked on a desk, then lowering a window is analogous to moving the
-sheet to the bottom of the stack but leaving its x and y location on
-the desk constant.
-Lowering a mapped window will generate 
-.PN Expose 
-events on any windows it formerly obscured.
-.LP
-If the override-redirect attribute of the window is 
-.PN False 
-and some
-other client has selected 
-.PN SubstructureRedirectMask 
-on the parent, the X server generates a
-.PN ConfigureRequest 
-event, and no processing is performed.  
-Otherwise, the window is lowered to the bottom of the
-stack.
-.LP
-.PN XLowerWindow
-can generate a
-.PN BadWindow 
-error.
-.LP
-.sp
-To circulate a subwindow up or down, use
-.PN XCirculateSubwindows .
-.IN "XCirculateSubwindows" "" "@DEF@"
-.sM
-.FD 0
-XCirculateSubwindows\^(\^\fIdisplay\fP, \fIw\fP\^, \fIdirection\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      int \fIdirection\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIdirection\fP 1i
-Specifies the direction (up or down) that you want to circulate
-the window. 
-You can pass 
-.PN RaiseLowest
-or
-.PN LowerHighest .
-.LP
-.eM
-The
-.PN XCirculateSubwindows
-function circulates children of the specified window in the specified 
-direction.
-If you specify
-.PN RaiseLowest ,
-.PN XCirculateSubwindows
-raises the lowest mapped child (if any) that is occluded 
-by another child to the top of the stack.
-If you specify
-.PN LowerHighest ,
-.PN XCirculateSubwindows
-lowers the highest mapped child (if any) that occludes another child
-to the bottom of the stack.
-Exposure processing is then performed on formerly obscured windows.
-If some other client has selected 
-.PN SubstructureRedirectMask 
-on the window, the X server generates a 
-.PN CirculateRequest 
-event, and no further processing is performed.
-If a child is actually restacked,
-the X server generates a
-.PN CirculateNotify
-event. 
-.LP
-.PN XCirculateSubwindows
-can generate
-.PN BadValue
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To raise the lowest mapped child of a window that is partially or completely
-occluded by another child, use
-.PN XCirculateSubwindowsUp .
-.IN "XCirculateSubwindowsUp" "" "@DEF@"
-.sM
-.FD 0
-XCirculateSubwindowsUp\^(\^\fIdisplay\fP, \fIw\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.LP
-.eM
-The
-.PN XCirculateSubwindowsUp
-function raises the lowest mapped child of the specified window that
-is partially
-or completely
-occluded by another child.
-Completely unobscured children are not affected.
-This is a convenience function equivalent to
-.PN XCirculateSubwindows
-with
-.PN RaiseLowest
-specified.
-.LP
-.PN XCirculateSubwindowsUp
-can generate a
-.PN BadWindow 
-error.
-.LP
-.sp
-To lower the highest mapped child of a window that partially or 
-completely occludes another child, use 
-.PN XCirculateSubwindowsDown .
-.IN "XCirculateSubwindowsDown" "" "@DEF@"
-.sM
-.FD 0
-XCirculateSubwindowsDown\^(\^\fIdisplay\fP, \fIw\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.LP
-.eM
-The
-.PN XCirculateSubwindowsDown
-function lowers the highest mapped child of the specified window that partially
-or completely occludes another child.
-Completely unobscured children are not affected.
-This is a convenience function equivalent to
-.PN XCirculateSubwindows
-with
-.PN LowerHighest
-specified.
-.LP
-.PN XCirculateSubwindowsDown
-can generate a
-.PN BadWindow 
-error.
-.LP
-.sp
-To restack a set of windows from top to bottom, use 
-.PN XRestackWindows .
-.IN "XRestackWindows" "" "@DEF@"
-.sM
-.FD 0
-XRestackWindows\^(\^\fIdisplay\fP, \fIwindows\fP\^, \^\fInwindows\fP\^);
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIwindows\fP\^[];
-.br
-      int \fInwindows\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIwindows\fP 1i
-Specifies an array containing the windows to be restacked.
-.IP \fInwindows\fP 1i
-Specifies the number of windows to be restacked.
-.LP
-.eM
-The
-.PN XRestackWindows
-function restacks the windows in the order specified,
-from top to bottom.
-The stacking order of the first window in the windows array is unaffected,
-but the other windows in the array are stacked underneath the first window,
-in the order of the array.
-The stacking order of the other windows is not affected.
-For each window in the window array that is not a child of the specified window,
-a
-.PN BadMatch
-error results.
-.LP
-If the override-redirect attribute of a window is 
-.PN False 
-and some
-other client has selected 
-.PN SubstructureRedirectMask 
-on the parent, the X server generates 
-.PN ConfigureRequest 
-events for each window whose override-redirect flag is not set, 
-and no further processing is performed.
-Otherwise, the windows will be restacked in top-to-bottom order.
-.LP
-.PN XRestackWindows
-can generate a
-.PN BadWindow 
-error.
-.NH 2
-Changing Window Attributes
-.XS
-\*(SN Changing Window Attributes 
-.XE
-.LP
-.LP
-Xlib provides functions that you can use to set window attributes.
-.PN XChangeWindowAttributes
-is the more general function that allows you to set one or more window
-attributes provided by the
-.PN XSetWindowAttributes
-structure.
-The other functions described in this section allow you to set one specific
-window attribute, such as a window's background.
-.LP
-.sp
-To change one or more attributes for a given window, use
-.PN XChangeWindowAttributes .
-.IN "XChangeWindowAttributes" "" "@DEF@"
-.sM
-.FD 0
-XChangeWindowAttributes\^(\^\fIdisplay\fP, \fIw\fP\^, \fIvaluemask\fP\^, \fIattributes\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      unsigned long \fIvaluemask\fP\^;
-.br
-      XSetWindowAttributes *\fIattributes\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIvaluemask\fP 1i
-Specifies which window attributes are defined in the attributes
-argument.
-This mask is the bitwise inclusive OR of the valid attribute mask bits.
-If valuemask is zero,
-the attributes are ignored and are not referenced.
-The values and restrictions are
-the same as for
-.PN XCreateWindow .
-.IP
-.IP \fIattributes\fP 1i
-Specifies the structure from which the values (as specified by the value mask)
-are to be taken.
-The value mask should have the appropriate bits
-set to indicate which attributes have been set in the structure 
-(see section 3.2).
-.LP
-.eM
-Depending on the valuemask,
-the
-.PN XChangeWindowAttributes
-function uses the window attributes in the
-.PN XSetWindowAttributes
-structure to change the specified window attributes.
-Changing the background does not cause the window contents to be
-changed.
-To repaint the window and its background, use 
-.PN XClearWindow .
-Setting the border or changing the background such that the
-border tile origin changes causes the border to be repainted.
-Changing the background of a root window to 
-.PN None 
-or 
-.PN ParentRelative
-restores the default background pixmap.
-Changing the border of a root window to
-.PN CopyFromParent
-restores the default border pixmap.
-Changing the win-gravity does not affect the current position of the
-window.
-Changing the backing-store of an obscured window to 
-.PN WhenMapped 
-or
-.PN Always , 
-or changing the backing-planes, backing-pixel, or
-save-under of a mapped window may have no immediate effect.
-Changing the colormap of a window (that is, defining a new map, not
-changing the contents of the existing map) generates a 
-.PN ColormapNotify
-event.
-Changing the colormap of a visible window may have no
-immediate effect on the screen because the map may not be installed
-(see
-.PN XInstallColormap ).
-Changing the cursor of a root window to 
-.PN None 
-restores the default
-cursor.
-Whenever possible, you are encouraged to share colormaps.
-.LP
-Multiple clients can select input on the same window. 
-Their event masks are maintained separately.
-When an event is generated, 
-it is reported to all interested clients. 
-However, only one client at a time can select for 
-.PN SubstructureRedirectMask , 
-.PN ResizeRedirectMask , 
-and
-.PN ButtonPressMask .
-If a client attempts to select any of these event masks 
-and some other client has already selected one, 
-a
-.PN BadAccess
-error results.
-There is only one do-not-propagate-mask for a window, 
-not one per client.
-.LP
-.PN XChangeWindowAttributes
-can generate
-.PN BadAccess ,
-.PN BadColor ,
-.PN BadCursor ,
-.PN BadMatch ,
-.PN BadPixmap ,
-.PN BadValue ,
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To set the background of a window to a given pixel, use 
-.PN XSetWindowBackground .
-.IN "XSetWindowBackground" "" "@DEF@"
-.sM
-.FD 0
-XSetWindowBackground\^(\^\fIdisplay\fP, \fIw\fP\^, \fIbackground_pixel\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      unsigned long \fIbackground_pixel\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIbackground_pixel\fP 1i
-Specifies the pixel that is to be used for the background.
-.LP
-.eM
-The
-.PN XSetWindowBackground
-function sets the background of the window to the specified pixel value.
-Changing the background does not cause the window contents to be changed.
-.PN XSetWindowBackground
-uses a pixmap of undefined size filled with the pixel value you passed.
-If you try to change the background of an 
-.PN InputOnly
-window, a
-.PN BadMatch
-error results.
-.LP
-.PN XSetWindowBackground
-can generate
-.PN BadMatch
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-.LP
-To set the background of a window to a given pixmap, use 
-.PN XSetWindowBackgroundPixmap .
-.IN "Window" "background"
-.IN "XSetWindowBackgroundPixmap" "" "@DEF@"
-.sM
-.FD 0
-XSetWindowBackgroundPixmap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIbackground_pixmap\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      Pixmap \fIbackground_pixmap\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIbackground_pixmap\fP 1i
-Specifies the background pixmap,
-.PN ParentRelative ,
-or
-.PN None .
-.LP
-.eM
-.IN "Resource IDs" "freeing"
-.IN "Freeing" "resources"
-The
-.PN XSetWindowBackgroundPixmap
-function sets the background pixmap of the window to the specified pixmap.
-The background pixmap can immediately be freed if no further explicit
-references to it are to be made.
-If 
-.PN ParentRelative
-is specified, 
-the background pixmap of the window's parent is used,
-or on the root window, the default background is restored.
-If you try to change the background of an 
-.PN InputOnly
-window, a
-.PN BadMatch
-error results.
-If the background is set to
-.PN None ,
-the window has no defined background.
-.LP
-.PN XSetWindowBackgroundPixmap
-can generate
-.PN BadMatch ,
-.PN BadPixmap ,
-and 
-.PN BadWindow 
-errors.
-.NT Note
-.PN XSetWindowBackground
-and
-.PN XSetWindowBackgroundPixmap
-do not change the current contents of the window.
-.NE
-.LP
-.sp
-To change and repaint a window's border to a given pixel, use 
-.PN XSetWindowBorder .
-.IN "XSetWindowBorder" "" "@DEF@"
-.sM
-.FD 0
-XSetWindowBorder\^(\^\fIdisplay\fP, \fIw\fP\^, \fIborder_pixel\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      unsigned long \fIborder_pixel\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIborder_pixel\fP 1i
-Specifies the entry in the colormap. 
-.LP
-.eM
-The
-.PN XSetWindowBorder
-function sets the border of the window to the pixel value you specify.
-If you attempt to perform this on an
-.PN InputOnly
-window, a
-.PN BadMatch
-error results.
-.LP
-.PN XSetWindowBorder
-can generate
-.PN BadMatch 
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To change and repaint the border tile of a given window, use 
-.PN XSetWindowBorderPixmap .
-.IN "XSetWindowBorderPixmap" "" "@DEF@"
-.sM
-.FD 0
-XSetWindowBorderPixmap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIborder_pixmap\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      Pixmap \fIborder_pixmap\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIborder_pixmap\fP 1i
-Specifies the border pixmap or
-.PN CopyFromParent .
-.LP
-.eM
-The
-.PN XSetWindowBorderPixmap
-function sets the border pixmap of the window to the pixmap you specify.
-The border pixmap can be freed immediately if no further explicit
-references to it are to be made.
-If you specify
-.PN CopyFromParent ,
-a copy of the parent window's border pixmap is used.
-If you attempt to perform this on an
-.PN InputOnly
-window, a
-.PN BadMatch
-error results.
-.IN "Resource IDs" "freeing"
-.IN "Freeing" "resources"
-.LP
-.PN XSetWindowBorderPixmap
-can generate
-.PN BadMatch ,
-.PN BadPixmap ,
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To set the colormap of a given window, use
-.PN XSetWindowColormap .
-.IN "XSetWindowColormap" "" "@DEF@"
-.sM
-.FD 0
-XSetWindowColormap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIcolormap\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.LP
-.eM
-The
-.PN XSetWindowColormap
-function sets the specified colormap of the specified window.
-The colormap must have the same visual type as the window,
-or a
-.PN BadMatch
-error results.
-.LP
-.PN XSetWindowColormap
-can generate
-.PN BadColor ,
-.PN BadMatch ,
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To define which cursor will be used in a window, use
-.PN XDefineCursor .
-.IN "Window" "defining the cursor"
-.IN "XDefineCursor" "" "@DEF@"
-.sM
-.FD 0
-XDefineCursor\^(\^\fIdisplay\fP, \fIw\fP\^, \fIcursor\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      Cursor \fIcursor\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIcursor\fP 1i
-Specifies the cursor that is to be displayed or
-.PN None .
-.LP
-.eM
-If a cursor is set, it will be used when the pointer is in the window.
-If the cursor is
-.PN None ,
-it is equivalent to
-.PN XUndefineCursor .
-.LP
-.PN XDefineCursor
-can generate
-.PN BadCursor
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To undefine the cursor in a given window, use
-.PN XUndefineCursor .
-.IN "Window" "undefining the cursor"
-.IN "XUndefineCursor" "" "@DEF@"
-.sM
-.FD 0
-XUndefineCursor\^(\^\fIdisplay\fP, \fIw\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.LP
-.eM
-The
-.PN XUndefineCursor
-function undoes the effect of a previous
-.PN XDefineCursor
-for this window.
-When the pointer is in the window,
-the parent's cursor will now be used.
-On the root window,
-the default cursor is restored.
-.LP
-.PN XUndefineCursor
-can generate a
-.PN BadWindow 
-error.
-.bp
diff --git a/libX11/specs/libX11/CH03.xml b/libX11/specs/libX11/CH03.xml
new file mode 100644
index 000000000..a90a06821
--- /dev/null
+++ b/libX11/specs/libX11/CH03.xml
@@ -0,0 +1,4162 @@
+<chapter id="window_functions"><title>Window Functions</title>

+<sect1 id="Visual_Types">

+<title>Visual Types</title>

+<!-- .XS -->

+<!-- (SN Visual Types -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>Visual Type</primary></indexterm>

+On some display hardware, 

+it may be possible to deal with color resources in more than one way.

+For example, you may be able to deal with a screen of either 12-bit depth

+with arbitrary mapping of pixel to color (pseudo-color) or 24-bit depth

+with 8 bits of the pixel dedicated to each of red, green, and blue.

+These different ways of dealing with the visual aspects of the screen

+are called visuals.

+For each screen of the display, there may be a list of valid visual types

+supported at different depths of the screen.

+Because default windows and visual types are defined for each screen,

+most simple applications need not deal with this complexity.

+Xlib provides macros and functions that return the default root window, 

+the default depth of the default root window, and the default visual type

+(see sections 2.2.1 and 16.7).

+</para>

+<para>

+<!-- .LP -->

+Xlib uses an opaque 

+<function>Visual </function>

+<indexterm significance="preferred"><primary>Visual</primary></indexterm>

+structure that contains information about the possible color mapping.

+The visual utility functions (see section 16.7) use an

+<function>XVisualInfo</function>

+structure to return this information to an application.

+The members of this structure pertinent to this discussion are class, red_mask,

+green_mask, blue_mask, bits_per_rgb, and colormap_size.

+The class member specifies one of the possible visual classes of the screen

+and can be 

+<indexterm><primary>Visual Classes</primary><secondary>StaticGray</secondary></indexterm>

+<indexterm><primary>Visual Classes</primary><secondary>StaticColor</secondary></indexterm>

+<indexterm><primary>Visual Classes</primary><secondary>TrueColor</secondary></indexterm>

+<indexterm><primary>Visual Classes</primary><secondary>StaticColor</secondary></indexterm>

+<indexterm><primary>Visual Classes</primary><secondary>GrayScale</secondary></indexterm>

+<indexterm><primary>Visual Classes</primary><secondary>PseudoColor</secondary></indexterm>

+<function>StaticGray</function>,

+<function>StaticColor</function>,

+<function>TrueColor</function>,

+<function>GrayScale</function>,

+<function>PseudoColor</function>,

+or

+<function>DirectColor</function>.

+</para>

+<para>

+<!-- .LP -->

+The following concepts may serve to make the explanation of

+visual types clearer. 

+The screen can be color or grayscale,

+can have a colormap that is writable or read-only,

+and can also have a colormap whose indices are decomposed into separate 

+<acronym>RGB</acronym> pieces, provided one is not on a grayscale screen.

+This leads to the following diagram:

+</para>

+

+<literallayout class="monospaced">

+                      Color        Gray-Scale

+                   R/O    R/W      R/O   R/W

+----------------------------------------------

+ Undecomposed    Static  Pseudo   Static  Gray

+   Colormap      Color   Color    Gray    Scale

+

+ Decomposed       True   Direct

+   Colormap       Color  Color

+----------------------------------------------

+</literallayout>

+

+<para>

+<!-- .LP -->

+Conceptually, 

+as each pixel is read out of video memory for display on the screen,

+it goes through a look-up stage by indexing into a colormap.

+Colormaps can be manipulated arbitrarily on some hardware, 

+in limited ways on other hardware, and not at all on other hardware.  

+The visual types affect the colormap and 

+the <acronym>RGB</acronym> values in the following ways:

+</para>

+<para>

+<!-- .LP -->

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+For 

+<function>PseudoColor</function>,

+a pixel value indexes a colormap to produce

+independent <acronym>RGB</acronym> values, and the <acronym>RGB</acronym> values can be changed dynamically.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>GrayScale </function>

+is treated the same way as 

+<function>PseudoColor  </function>

+except that the primary that drives the screen is undefined. 

+Thus, the client should always store the

+same value for red, green, and blue in the colormaps.  

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+For 

+<function>DirectColor</function>,

+a pixel value is decomposed into separate <acronym>RGB</acronym> subfields, and each

+subfield separately indexes the colormap for the corresponding value.

+The <acronym>RGB</acronym> values can be changed dynamically.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>TrueColor</function>

+is treated the same way as 

+<function>DirectColor </function>

+except that the colormap has predefined, read-only <acronym>RGB</acronym> values.

+These <acronym>RGB</acronym> values are server dependent but provide linear or near-linear

+ramps in each primary.  

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>StaticColor</function>

+is treated the same way as 

+<function>PseudoColor </function>

+except that the colormap has predefined, 

+read-only, server-dependent <acronym>RGB</acronym> values.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>StaticGray </function>

+is treated the same way as 

+<function>StaticColor </function>

+except that the <acronym>RGB</acronym> values are equal for any single pixel

+value, thus resulting in shades of gray.  

+<function>StaticGray </function>

+with a two-entry

+colormap can be thought of as monochrome.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+The red_mask, green_mask, and blue_mask members are only defined for

+<function>DirectColor</function>

+and 

+<function>TrueColor</function>.

+Each has one contiguous set of bits with no

+intersections.

+The bits_per_rgb member specifies the log base 2 of the

+number of distinct color values (individually) of red, green, and blue.

+Actual <acronym>RGB</acronym> values are unsigned 16-bit numbers.

+The colormap_size member defines the number of available colormap entries

+in a newly created colormap.  

+For 

+<function>DirectColor </function>

+and 

+<function>TrueColor</function>,

+this is the size of an individual pixel subfield.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To obtain the visual ID from a 

+<function>Visual</function>,

+use

+<function>XVisualIDFromVisual</function>.

+<indexterm significance="preferred"><primary>XVisualIDFromVisual</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>VisualID<function> XVisualIDFromVisual</function></funcdef>

+  <paramdef>Visual<parameter> *\^visual</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>visual</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the visual type.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XVisualIDFromVisual</function>

+function returns the visual ID for the specified visual type.

+</para>

+</sect1>

+<sect1 id="Window_Attributes">

+<title>Window Attributes</title>

+<!-- .XS -->

+<!-- (SN Window Attributes -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Window</primary></indexterm>

+<indexterm><primary>Window</primary><secondary>attributes</secondary></indexterm>

+All 

+<function>InputOutput</function>

+windows have a border width of zero or more pixels, an optional background, 

+an event suppression mask (which suppresses propagation of events from 

+children), and a property list (see section 4.3).

+The window border and background can be a solid color or a pattern, called

+a tile.

+All windows except the root have a parent and are clipped by their parent.

+If a window is stacked on top of another window, it obscures that other

+window for the purpose of input.

+If a window has a background (almost all do), it obscures the other

+window for purposes of output.

+Attempts to output to the obscured area do nothing, 

+and no input events (for example, pointer motion) are generated for the 

+obscured area.

+</para>

+<para>

+<!-- .LP -->

+Windows also have associated property lists (see section 4.3).

+</para>

+<para>

+<!-- .LP -->

+Both

+<function>InputOutput</function>

+and

+<function>InputOnly</function>

+windows have the following common attributes,

+which are the only attributes of an

+<function>InputOnly</function>

+window:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+win-gravity

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+event-mask

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+do-not-propagate-mask

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+override-redirect

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+cursor

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+If you specify any other attributes for an

+<function>InputOnly</function>

+window,

+a

+<function>BadMatch</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+<function>InputOnly</function>

+windows are used for controlling input events in situations where

+<function>InputOutput</function>

+windows are unnecessary.

+<function>InputOnly</function>

+windows are invisible; can only be used to control such things as

+cursors, input event generation, and grabbing;

+and cannot be used in any graphics requests.

+Note that

+<function>InputOnly</function>

+windows cannot have

+<function>InputOutput</function>

+windows as inferiors.

+</para>

+<para>

+<!-- .LP -->

+Windows have borders of a programmable width and pattern

+as well as a background pattern or tile.

+<indexterm><primary>Tile</primary><secondary>pixmaps</secondary></indexterm>

+Pixel values can be used for solid colors.

+<indexterm><primary>Resource IDs</primary><secondary>freeing</secondary></indexterm>

+<indexterm><primary>Freeing</primary><secondary>resources</secondary></indexterm>

+The background and border pixmaps can be destroyed immediately after

+creating the window if no further explicit references to them

+are to be made.

+<indexterm ><primary>Tile</primary><secondary>mode</secondary></indexterm>

+The pattern can either be relative to the parent 

+or absolute.

+If

+<function>ParentRelative</function>,

+the parent's background is used.

+</para>

+<para>

+<!-- .LP -->

+When windows are first created, 

+they are not visible (not mapped) on the screen.

+Any output to a window that is not visible on the screen 

+and that does not have backing store will be discarded.

+<indexterm><primary>Window</primary><secondary>mapping</secondary></indexterm>

+An application may wish to create a window long before it is

+mapped to the screen.

+When a window is eventually mapped to the screen 

+(using

+<function>XMapWindow</function>),

+<indexterm><primary>XMapWindow</primary></indexterm>

+the X server generates an 

+<function>Expose </function>

+event for the window if backing store has not been maintained.

+</para>

+<para>

+<!-- .LP -->

+A window manager can override your choice of size, 

+border width, and position for a top-level window.

+Your program must be prepared to use the actual size and position

+of the top window.

+It is not acceptable for a client application to resize itself

+unless in direct response to a human command to do so.

+Instead, either your program should use the space given to it,

+or if the space is too small for any useful work, your program

+might ask the user to resize the window.

+The border of your top-level window is considered fair game 

+for window managers.

+</para>

+<para>

+<!-- .LP -->

+To set an attribute of a window,

+set the appropriate member of the

+<function>XSetWindowAttributes</function>

+structure and OR in the corresponding value bitmask in your subsequent calls to

+<function>XCreateWindow</function>

+and

+<function>XChangeWindowAttributes</function>,

+or use one of the other convenience functions that set the appropriate 

+attribute.

+The symbols for the value mask bits and the

+<function>XSetWindowAttributes</function>

+structure are:

+<!-- .sM -->

+</para>

+<para>

+<!-- .LP -->

+/* Window attribute value mask bits */

+

+

+<literallayout class="monospaced">

+/* Window attribute value mask bits */

+#define    CWBackPixmap                    (1L&lt;&lt;0)

+#define    CWBackPixel                     (1L&lt;&lt;1)

+#define    CWBorderPixmap                  (1L&lt;&lt;2)

+#define    CWBorderPixel                   (1L&lt;&lt;3)

+#define    CWBitGravity                    (1L&lt;&lt;4)

+#define    CWWinGravity                    (1L&lt;&lt;5)

+#define    CWBackingStore                  (1L&lt;&lt;6)

+#define    CWBackingPlanes                 (1L&lt;&lt;7)

+#define    CWBackingPixel                  (1L&lt;&lt;8)

+#define    CWOverrideRedirect              (1L&lt;&lt;9)

+#define    CWSaveUnder                     (1L&lt;&lt;10)

+#define    CWEventMask                     (1L&lt;&lt;11)

+#define    CWDontPropagate                 (1L&lt;&lt;12)

+#define    CWColormap                      (1L&lt;&lt;13)

+#define    CWCursor                        (1L&lt;&lt;14)

+</literallayout>

+

+<indexterm significance="preferred"><primary>XSetWindowAttributes</primary></indexterm>

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+/* Values */

+

+typedef struct {

+     Pixmap background_pixmap;     /* background, None, or ParentRelative */

+     unsigned long background_pixel;     /* background pixel */

+     Pixmap border_pixmap;          /* border of the window or CopyFromParent */

+     unsigned long border_pixel;     /* border pixel value */

+     int bit_gravity;     /* one of bit gravity values */

+     int win_gravity;     /* one of the window gravity values */

+     int backing_store;     /* NotUseful, WhenMapped, Always */

+     unsigned long backing_planes;     /* planes to be preserved if possible */

+     unsigned long backing_pixel;     /* value to use in restoring planes */

+     Bool save_under;     /* should bits under be saved? (popups) */

+     long event_mask;     /* set of events that should be saved */

+     long do_not_propagate_mask;     /* set of events that should not propagate */

+     Bool override_redirect;     /* boolean value for override_redirect */

+     Colormap colormap;     /* color map to be associated with window */

+     Cursor cursor;          /* cursor to be displayed (or None) */

+} XSetWindowAttributes;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The following lists the defaults for each window attribute and indicates

+whether the attribute is applicable to

+<function>InputOutput</function>

+and

+<function>InputOnly</function>

+windows:

+</para>

+<informaltable>

+  <tgroup cols='4' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <colspec colname='c3'/>

+  <colspec colname='c4'/>

+  <thead>

+    <row>

+      <entry>Attribute</entry>

+      <entry>Default</entry>

+      <entry>InputOutput</entry>

+      <entry>nputOnly</entry>

+    </row>

+  </thead>

+  <tbody>

+    <row>

+      <entry>background-pixmap</entry>

+      <entry><function>None</function></entry>

+      <entry>Yes</entry>

+      <entry>No</entry>

+    </row>

+    <row>

+      <entry>background-pixel</entry>

+      <entry>Undefined</entry>

+      <entry>Yes</entry>

+      <entry>No</entry>

+    </row>

+    <row>

+      <entry>border-pixmap</entry>

+      <entry><function>CopyFromParent</function></entry>

+      <entry>Yes</entry>

+      <entry>No</entry>

+    </row>

+    <row>

+      <entry>border-pixel</entry>

+      <entry>Undefined</entry>

+      <entry>Yes</entry>

+      <entry>No</entry>

+    </row>

+    <row>

+      <entry>bit-gravity</entry>

+      <entry><function>ForgetGravity</function></entry>

+      <entry>Yes</entry>

+      <entry>No</entry>

+    </row>

+    <row>

+      <entry>win-gravity</entry>

+      <entry><function>NorthWestGravity</function></entry>

+      <entry>Yes</entry>

+      <entry>Yes</entry>

+    </row>

+    <row>

+      <entry>backing-store</entry>

+      <entry><function>NotUseful</function></entry>

+      <entry>Yes</entry>

+      <entry>No</entry>

+    </row>

+    <row>

+      <entry>backing-planes</entry>

+      <entry>All ones</entry>

+      <entry>Yes</entry>

+      <entry>No</entry>

+    </row>

+    <row>

+      <entry>backing-pixel</entry>

+      <entry>zero</entry>

+      <entry>Yes</entry>

+      <entry>No</entry>

+    </row>

+    <row>

+      <entry>save-under</entry>

+      <entry><function>False</function></entry>

+      <entry>Yes</entry>

+      <entry>No</entry>

+    </row>

+    <row>

+      <entry>event-mask</entry>

+      <entry>empty set</entry>

+      <entry>Yes</entry>

+      <entry>Yes</entry>

+    </row>

+    <row>

+      <entry>do-not-propagate-mask</entry>

+      <entry>empty set</entry>

+      <entry>Yes</entry>

+      <entry>Yes</entry>

+    </row>

+    <row>

+      <entry>override-redirect</entry>

+      <entry><function>False</function></entry>

+      <entry>Yes</entry>

+      <entry>Yes</entry>

+    </row>

+    <row>

+      <entry>colormap</entry>

+      <entry><function>CopyFromParent</function></entry>

+      <entry>Yes</entry>

+      <entry>No</entry>

+    </row>

+    <row>

+      <entry>cursor</entry>

+      <entry><function>None</function></entry>

+      <entry>Yes</entry>

+      <entry>Yes</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<sect2 id="Background_Attribute">

+<title>Background Attribute</title>

+<!-- .XS -->

+<!-- (SN Background Attribute -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Only

+<function>InputOutput</function>

+windows can have a background.

+You can set the background of an

+<function>InputOutput</function>

+window by using a pixel or a pixmap.

+</para>

+<para>

+<!-- .LP -->

+The background-pixmap attribute of a window specifies the pixmap to be used for 

+a window's background.

+This pixmap can be of any size, although some sizes may be faster than others.

+The background-pixel attribute of a window specifies a pixel value used to paint

+a window's background in a single color.

+</para>

+<para>

+<!-- .LP -->

+You can set the background-pixmap to a pixmap,  

+<function>None </function>

+(default), or 

+<function>ParentRelative</function>.

+You can set the background-pixel of a window to any pixel value (no default).

+If you specify a background-pixel, 

+it overrides either the default background-pixmap

+or any value you may have set in the background-pixmap.

+A pixmap of an undefined size that is filled with the background-pixel is used 

+for the background.

+Range checking is not performed on the background pixel;

+it simply is truncated to the appropriate number of bits.

+</para>

+<para>

+<!-- .LP -->

+If you set the background-pixmap,

+it overrides the default.

+The background-pixmap and the window must have the same depth,

+or a

+<function>BadMatch</function>

+error results.

+If you set background-pixmap to

+<function>None</function>,

+the window has no defined background.  

+If you set the background-pixmap to

+<function>ParentRelative :</function>

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+The parent window's background-pixmap is used. 

+The child window, however, must have the same depth as 

+its parent,

+or a

+<function>BadMatch</function>

+error results.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If the parent window has a background-pixmap of

+<function>None</function>,

+the window also has a background-pixmap of

+<function>None</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A copy of the parent window's background-pixmap is not made.

+The parent's background-pixmap is examined each time the child window's 

+background-pixmap is required.  

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The background tile origin always aligns with the parent window's

+background tile origin. 

+If the background-pixmap is not

+<function>ParentRelative</function>,

+the background tile origin is the child window's origin.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+Setting a new background, whether by setting background-pixmap or

+background-pixel, overrides any previous background.

+The background-pixmap can be freed immediately if no further explicit reference

+is made to it (the X server will keep a copy to use when needed).

+If you later draw into the pixmap used for the background,

+what happens is undefined because the

+X implementation is free to make a copy of the pixmap or

+to use the same pixmap.

+</para>

+<para>

+<!-- .LP -->

+When no valid contents are available for regions of a window

+and either the regions are visible or the server is maintaining backing store,

+the server automatically tiles the regions with the window's background

+unless the window has a background of

+<function>None</function>.

+If the background is

+<function>None</function>,

+the previous screen contents from other windows of the same depth as the window

+are simply left in place as long as the contents come from the parent of the

+window or an inferior of the parent.

+Otherwise, the initial contents of the exposed regions are undefined.

+<function>Expose </function>

+events are then generated for the regions, even if the background-pixmap

+is

+<function>None </function>

+(see section 10.9).

+</para>

+</sect2>

+<sect2 id="Border_Attribute">

+<title>Border Attribute</title>

+<!-- .XS -->

+<!-- (SN Border Attribute -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Only

+<function>InputOutput</function>

+windows can have a border.

+You can set the border of an

+<function>InputOutput</function>

+window by using a pixel or a pixmap.

+</para>

+<para>

+<!-- .LP -->

+The border-pixmap attribute of a window specifies the pixmap to be used 

+for a window's border.

+The border-pixel attribute of a window specifies a pixmap of undefined size 

+filled with that pixel be used for a window's border. 

+Range checking is not performed on the background pixel;

+it simply is truncated to the appropriate number of bits.

+The border tile origin is always the same as the background tile origin.

+</para>

+<para>

+<!-- .LP -->

+You can also set the border-pixmap to a pixmap of any size (some may be faster

+than others) or to

+<function>CopyFromParent </function>

+(default).

+You can set the border-pixel to any pixel value (no default).

+</para>

+<para>

+<!-- .LP -->

+If you set a border-pixmap, 

+it overrides the default.

+The border-pixmap and the window must have the same depth,

+or a

+<function>BadMatch</function>

+error results.

+If you set the border-pixmap to 

+<function>CopyFromParent</function>,

+the parent window's border-pixmap is copied.

+Subsequent changes to the parent window's border attribute do not affect 

+the child window.

+However, the child window must have the same depth as the parent window,

+or a

+<function>BadMatch</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+The border-pixmap can be freed immediately if no further explicit reference

+is made to it.

+If you later draw into the pixmap used for the border,

+what happens is undefined because the

+X implementation is free either to make a copy of the pixmap or

+to use the same pixmap.

+If you specify a border-pixel, 

+it overrides either the default border-pixmap

+or any value you may have set in the border-pixmap.

+All pixels in the window's border will be set to the border-pixel.

+Setting a new border, whether by setting border-pixel or by setting

+border-pixmap, overrides any previous border.

+</para>

+<para>

+<!-- .LP -->

+Output to a window is always clipped to the inside of the window. 

+Therefore, graphics operations never affect the window border.

+</para>

+</sect2>

+<sect2 id="Gravity_Attributes">

+<title>Gravity Attributes</title>

+<!-- .XS -->

+<!-- (SN Gravity Attributes -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The bit gravity of a window defines which region of the window should be 

+retained when an

+<function>InputOutput</function>

+window is resized. 

+The default value for the bit-gravity attribute is 

+<function>ForgetGravity</function>.

+The window gravity of a window allows you to define how the 

+<function>InputOutput</function>

+or

+<function>InputOnly</function>

+window should be repositioned if its parent is resized.  

+The default value for the win-gravity attribute is 

+<function>NorthWestGravity</function>.

+</para>

+<para>

+<!-- .LP -->

+If the inside width or height of a window is not changed 

+and if the window is moved or its border is changed, 

+then the contents of the window are not lost but move with the window.

+Changing the inside width or height of the window causes its contents to be

+moved or lost (depending on the bit-gravity of the window) and causes

+children to be reconfigured (depending on their win-gravity).

+For a

+change of width and height, the (x, y) pairs are defined:

+</para>

+<para>

+<!-- .LP -->

+<informaltable>

+  <tgroup cols='3' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <thead>

+    <row>

+      <entry>Gravity Direction</entry>

+      <entry>Coordinates</entry>

+    </row>

+  </thead>

+  <tbody>

+    <row>

+      <entry><function>NorthWestGravity</function></entry>

+      <entry>(0, 0)</entry>

+    </row>

+    <row>

+      <entry><function>NorthGravity</function></entry>

+      <entry>(Width/2, 0)</entry>

+    </row>

+    <row>

+      <entry><function>NorthEastGravity</function></entry>

+      <entry>(Width, 0)</entry>

+    </row>

+    <row>

+      <entry><function>WestGravity</function></entry>

+      <entry>(0, Height/2)</entry>

+    </row>

+    <row>

+      <entry><function>CenterGravity</function></entry>

+      <entry>(Width/2, Height/2)</entry>

+    </row>

+    <row>

+      <entry><function>EastGravity</function></entry>

+      <entry>(Width, Height/2)</entry>

+    </row>

+    <row>

+      <entry><function>SouthWestGravity</function></entry>

+      <entry>(0, Height)</entry>

+    </row>

+    <row>

+      <entry><function>SouthGravity</function></entry>

+      <entry>(Width/2, Height)</entry>

+    </row>

+    <row>

+      <entry><function>SouthEastGravity</function></entry>

+      <entry>(Width, Height)</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+</para>

+<para>

+<!-- .LP -->

+When a window with one of these bit-gravity values is resized, 

+the corresponding pair

+defines the change in position of each pixel in the window.

+When a window with one of these win-gravities has its parent window resized,

+the corresponding pair defines the change in position of the window 

+within the parent.

+When a window is so repositioned, a

+<function>GravityNotify</function>

+event is generated (see section 10.10.5).

+</para>

+<para>

+<!-- .LP -->

+A bit-gravity of

+<function>StaticGravity </function>

+indicates that the contents or origin should not move relative to the 

+origin of the root window.

+If the change in size of the window is coupled with a change in position (x, y),

+then for bit-gravity the change in position of each pixel is (\-x, \-y), and for

+win-gravity the change in position of a child when its parent is so resized is

+(\-x, \-y).

+Note that

+<function>StaticGravity</function>

+still only takes effect when the width or height of the window is changed, 

+not when the window is moved.

+</para>

+<para>

+<!-- .LP -->

+A bit-gravity of 

+<function>ForgetGravity </function>

+indicates that the window's contents are always discarded after a size change, 

+even if a backing store or save under has been requested.

+The window is tiled with its background

+and zero or more 

+<function>Expose </function>

+events are generated. 

+If no background is defined, the existing screen contents are not

+altered.

+Some X servers may also ignore the specified bit-gravity and 

+always generate 

+<function>Expose</function>

+events.

+</para>

+<para>

+<!-- .LP -->

+The contents and borders of inferiors are not affected by their parent's

+bit-gravity.

+A server is permitted to ignore the specified bit-gravity and use

+<function>Forget</function>

+instead.

+</para>

+<para>

+<!-- .LP -->

+A win-gravity of 

+<function>UnmapGravity </function>

+is like 

+<function>NorthWestGravity</function>

+(the window is not moved),

+except the child is also

+unmapped when the parent is resized,

+and an 

+<function>UnmapNotify </function>

+event is

+generated.

+</para>

+</sect2>

+<sect2 id="Backing_Store_Attribute">

+<title>Backing Store Attribute</title>

+<!-- .XS -->

+<!-- (SN Backing Store Attribute -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Some implementations of the X server may choose to maintain the contents of 

+<function>InputOutput</function>

+windows.

+If the X server maintains the contents of a window, 

+the off-screen saved pixels

+are known as backing store.

+The backing store advises the X server on what to do 

+with the contents of a window.

+The backing-store attribute can be set to

+<function>NotUseful </function>

+(default),

+<function>WhenMapped</function>,

+or

+<function>Always</function>.

+</para>

+<para>

+<!-- .LP -->

+A backing-store attribute of 

+<function>NotUseful </function>

+advises the X server that 

+maintaining contents is unnecessary, 

+although some X implementations may

+still choose to maintain contents and, therefore, not generate 

+<function>Expose</function>

+events.

+A backing-store attribute of 

+<function>WhenMapped </function>

+advises the X server that maintaining contents of 

+obscured regions when the window is mapped would be beneficial.

+In this case,

+the server may generate an 

+<function>Expose </function>

+event when the window is created.

+A backing-store attribute of 

+<function>Always </function>

+advises the X server that maintaining contents even when 

+the window is unmapped would be beneficial.  

+Even if the window is larger than its parent, 

+this is a request to the X server to maintain complete contents, 

+not just the region within the parent window boundaries.  

+While the X server maintains the window's contents, 

+<function>Expose </function>

+events normally are not generated, 

+but the X server may stop maintaining 

+contents at any time.  

+</para>

+<para>

+<!-- .LP -->

+When the contents of obscured regions of a window are being maintained,

+regions obscured by noninferior windows are included in the destination

+of graphics requests (and source, when the window is the source).

+However, regions obscured by inferior windows are not included.

+</para>

+</sect2>

+<sect2 id="Save_Under_Flag">

+<title>Save Under Flag</title>

+<!-- .XS -->

+<!-- (SN Save Under Flag -->

+<!-- .XE -->

+<indexterm><primary>Save Unders</primary></indexterm>

+<para>

+<!-- .LP -->

+Some server implementations may preserve contents of 

+<function>InputOutput</function>

+windows under other 

+<function>InputOutput</function>

+windows.

+This is not the same as preserving the contents of a window for you.

+You may get better visual

+appeal if transient windows (for example, pop-up menus) request that the system

+preserve the screen contents under them, 

+so the temporarily obscured applications do not have to repaint.

+</para>

+<para>

+<!-- .LP -->

+You can set the save-under flag to

+<function>True</function>

+or

+<function>False </function>

+(default).

+If save-under is 

+<function>True</function>,

+the X server is advised that, when this window is mapped, 

+saving the contents of windows it obscures would be beneficial.

+</para>

+</sect2>

+<sect2 id="Backing_Planes_and_Backing_Pixel_Attributes">

+<title>Backing Planes and Backing Pixel Attributes</title>

+<!-- .XS -->

+<!-- (SN Backing Planes and Backing Pixel Attributes -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+You can set backing planes to indicate (with bits set to 1) 

+which bit planes of an

+<function>InputOutput</function>

+window hold dynamic data that must be preserved in backing store 

+and during save unders.

+The default value for the backing-planes attribute is all bits set to 1.

+You can set backing pixel to specify what bits to use in planes not 

+covered by backing planes.

+The default value for the backing-pixel attribute is all bits set to 0.

+The X server is free to save only the specified bit planes in the backing store

+or the save under and is free to regenerate the remaining planes with 

+the specified pixel value.

+Any extraneous bits in these values (that is, those bits beyond 

+the specified depth of the window) may be simply ignored.

+If you request backing store or save unders,

+you should use these members to minimize the amount of off-screen memory 

+required to store your window.

+</para>

+</sect2>

+<sect2 id="Event_Mask_and_Do_Not_Propagate_Mask_Attributes">

+<title>Event Mask and Do Not Propagate Mask Attributes</title>

+<!-- .XS -->

+<!-- (SN Event Mask and Do Not Propagate Mask Attributes -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The event mask defines which events the client is interested in for this 

+<function>InputOutput</function>

+or

+<function>InputOnly</function>

+window (or, for some event types, inferiors of this window).

+The event mask is the bitwise inclusive OR of zero or more of the 

+valid event mask bits.

+You can specify that no maskable events are reported by setting 

+<function>NoEventMask </function>

+(default).

+</para>

+<para>

+<!-- .LP -->

+The do-not-propagate-mask attribute

+defines which events should not be propagated to 

+ancestor windows when no client has the event type selected in this 

+<function>InputOutput</function>

+or

+<function>InputOnly</function>

+window.

+The do-not-propagate-mask is the bitwise inclusive OR of zero or more

+of the following masks:

+<function>KeyPress</function>,

+<function>KeyRelease</function>,

+<function>ButtonPress</function>,

+<function>ButtonRelease</function>,

+<function>PointerMotion</function>,

+<function>Button1Motion</function>,

+<function>Button2Motion</function>,

+<function>Button3Motion</function>,

+<function>Button4Motion</function>,

+<function>Button5Motion</function>,

+and

+<function>ButtonMotion</function>.

+You can specify that all events are propagated by setting 

+<function>NoEventMask </function>

+(default).

+</para>

+</sect2>

+<sect2 id="Override_Redirect_Flag">

+<title>Override Redirect Flag</title>

+<!-- .XS -->

+<!-- (SN Override Redirect Flag -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To control window placement or to add decoration,

+a window manager often needs to intercept (redirect) any map or configure

+request.

+Pop-up windows, however, often need to be mapped without a window manager

+getting in the way.

+To control whether an

+<function>InputOutput</function>

+or

+<function>InputOnly</function>

+window is to ignore these structure control facilities,

+use the override-redirect flag.

+</para>

+<para>

+<!-- .LP -->

+The override-redirect flag specifies whether map and configure requests 

+on this window should override a 

+<function>SubstructureRedirectMask </function>

+on the parent.

+You can set the override-redirect flag to

+<function>True</function>

+or

+<function>False </function>

+(default).

+Window managers use this information to avoid tampering with pop-up windows

+(see also chapter 14).

+</para>

+</sect2>

+<sect2 id="Colormap_Attribute">

+<title>Colormap Attribute</title>

+<!-- .XS -->

+<!-- (SN Colormap Attribute -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The colormap attribute specifies which colormap best reflects the true

+colors of the 

+<function>InputOutput</function>

+window.  

+The colormap must have the same visual type as the window,

+or a 

+<function>BadMatch </function>

+error results.  

+X servers capable of supporting multiple 

+hardware colormaps can use this information, 

+and window managers can use it for calls to

+<function>XInstallColormap</function>.

+You can set the colormap attribute to a colormap or to

+<function>CopyFromParent</function>

+(default).

+</para>

+<para>

+<!-- .LP -->

+If you set the colormap to

+<function>CopyFromParent</function>,

+the parent window's colormap is copied and used by its child.

+However, the child window must have the same visual type as the parent, 

+or a 

+<function>BadMatch </function>

+error results. 

+The parent window must not have a colormap of 

+<function>None</function>,

+or a 

+<function>BadMatch </function>

+error results.

+The colormap is copied by sharing the colormap object between the child 

+and parent, not by making a complete copy of the colormap contents.

+Subsequent changes to the parent window's colormap attribute do

+not affect the child window.

+</para>

+</sect2>

+<sect2 id="Cursor_Attribute">

+<title>Cursor Attribute</title>

+<!-- .XS -->

+<!-- (SN Cursor Attribute -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The cursor attribute specifies which cursor is to be used when the pointer is

+in the 

+<function>InputOutput</function>

+or

+<function>InputOnly</function>

+window.

+You can set the cursor to a cursor or

+<function>None</function>

+(default).

+</para>

+<para>

+<!-- .LP -->

+If you set the cursor to

+<function>None</function>,

+the parent's cursor is used when the 

+pointer is in the 

+<function>InputOutput</function>

+or

+<function>InputOnly</function>

+window, and any change in the parent's cursor will cause an

+immediate change in the displayed cursor.

+By calling

+<function>XFreeCursor</function>,

+the cursor can be freed immediately as long as no further explicit reference 

+to it is made.

+</para>

+</sect2>

+</sect1>

+<sect1 id="Creating_Windows">

+<title>Creating Windows</title>

+<!-- .XS -->

+<!-- (SN Creating Windows -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides basic ways for creating windows,

+and toolkits often supply higher-level functions specifically for

+creating and placing top-level windows,

+which are discussed in the appropriate toolkit documentation.

+If you do not use a toolkit, however,

+you must provide some standard information or hints for the window

+manager by using the Xlib inter-client communication functions

+(see chapter 14).

+</para>

+<para>

+<!-- .LP -->

+If you use Xlib to create your own top-level windows

+(direct children of the root window),

+you must observe the following rules so that all applications interact

+reasonably across the different styles of window management:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+You must never fight with the window manager for the size or

+placement of your top-level window.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+You must be able to deal with whatever size window you get, 

+even if this means that your application just prints a message 

+like ``Please make me bigger'' in its window.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+You should only attempt to resize or move top-level windows in

+direct response to a user request.

+If a request to change the size of a top-level window fails,

+you must be prepared to live with what you get.

+You are free to resize or move the children of top-level

+windows as necessary.

+(Toolkits often have facilities for automatic relayout.)

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If you do not use a toolkit that automatically sets standard window properties,

+you should set these properties for top-level windows before mapping them.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+For further information,

+see chapter 14 and the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.

+</para>

+<para>

+<!-- .LP -->

+<function>XCreateWindow</function>

+is the more general function that allows you to set specific window attributes 

+when you create a window.

+<function>XCreateSimpleWindow </function>

+creates a window that inherits its attributes from its parent window.

+</para>

+<para>

+<!-- .LP -->

+<indexterm><primary>Window</primary><secondary>InputOnly</secondary></indexterm>

+The X server acts as if 

+<function>InputOnly </function>

+windows do not exist for

+the purposes of graphics requests, exposure processing, and

+<function>VisibilityNotify </function>

+events.

+An 

+<function>InputOnly </function>

+window cannot be used as a

+drawable (that is, as a source or destination for graphics requests).

+<function>InputOnly</function>

+and 

+<function>InputOutput </function>

+windows act identically in other respects (properties,

+grabs, input control, and so on).

+Extension packages can define other classes of windows.

+</para>

+<para>

+<!-- .LP -->

+To create an unmapped window and set its window attributes, use

+<function>XCreateWindow</function>.

+<indexterm significance="preferred"><primary>XCreateWindow</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Window<function> XCreateWindow</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> parent</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+  <paramdef>unsignedint<parameter> border_width</parameter></paramdef>

+  <paramdef>int<parameter> depth</parameter></paramdef>

+  <paramdef>unsignedint<parameter> class</parameter></paramdef>

+  <paramdef>Visual<parameter> *visual</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>

+  <paramdef>XSetWindowAttributes<parameter> *attributes</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>parent</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the parent window.

+<!-- .ds Xy , which are the top-left outside corner of the created window's \ -->

+borders and are relative to the inside of the parent window's borders

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+<!-- .ds Wh , which are the created window's inside dimensions \ -->

+and do not include the created window's borders

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height(Wh.

+The dimensions must be nonzero,

+or a

+<function>BadValue</function>

+error results.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>border_width</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the width of the created window's border in pixels.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>depth</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window's depth.

+A depth of 

+<function>CopyFromParent</function>

+means the depth is taken from the parent.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>class</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the created window's class.

+You can pass

+<function>InputOutput</function>,

+<function>InputOnly</function>,

+or 

+<function>CopyFromParent</function>.

+A class of 

+<function>CopyFromParent</function>

+means the class

+is taken from the parent.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>visual</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the visual type.

+A visual of 

+<function>CopyFromParent </function>

+means the visual type is taken from the 

+parent.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>valuemask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies which window attributes are defined in the attributes

+argument.

+This mask is the bitwise inclusive OR of the valid attribute mask bits.

+If valuemask is zero,

+the attributes are ignored and are not referenced.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>attributes</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the structure from which the values (as specified by the value mask)

+are to be taken.

+The value mask should have the appropriate bits

+set to indicate which attributes have been set in the structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCreateWindow</function>

+function creates an unmapped subwindow for a specified parent window, 

+returns the window ID of the created window, 

+and causes the X server to generate a

+<function>CreateNotify</function>

+event.

+The created window is placed on top in the stacking order 

+with respect to siblings.

+</para>

+<para>

+<!-- .LP -->

+The coordinate system has the X axis horizontal and the Y axis vertical

+with the origin [0, 0] at the upper-left corner.

+Coordinates are integral,

+in terms of pixels,

+and coincide with pixel centers.

+Each window and pixmap has its own coordinate system.

+For a window, 

+the origin is inside the border at the inside, upper-left corner.

+</para>

+<para>

+<!-- .LP -->

+The border_width for an

+<function>InputOnly</function>

+window must be zero, or a

+<function>BadMatch</function>

+error results.

+For class

+<function>InputOutput</function>,

+the visual type and depth must be a combination supported for the screen,

+or a

+<function>BadMatch</function>

+error results.

+The depth need not be the same as the parent,

+but the parent must not be a window of class 

+<function>InputOnly</function>,

+or a

+<function>BadMatch</function>

+error results.

+For an

+<function>InputOnly</function>

+window,

+the depth must be zero, and the visual must be one supported by the screen.

+If either condition is not met,

+a

+<function>BadMatch</function>

+error results.

+The parent window, however, may have any depth and class.

+If you specify any invalid window attribute for a window, a

+<function>BadMatch</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+The created window is not yet displayed (mapped) on the user's display.

+To display the window, call

+<function>XMapWindow</function>.

+The new window initially uses the same cursor as

+its parent. 

+A new cursor can be defined for the new window by calling

+<function>XDefineCursor</function>.

+<indexterm><primary>Cursor</primary><secondary>Initial State</secondary></indexterm>

+<indexterm><primary>XDefineCursor</primary></indexterm>

+The window will not be visible on the screen unless it and all of its

+ancestors are mapped and it is not obscured by any of its ancestors.

+</para>

+<para>

+<!-- .LP -->

+<function>XCreateWindow</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadColor</function>,

+<function>BadCursor</function>,

+<function>BadMatch</function>,

+<function>BadPixmap</function>,

+<function>BadValue</function>,

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To create an unmapped 

+<function>InputOutput</function>

+subwindow of a given parent window, use

+<function>XCreateSimpleWindow</function>.

+<indexterm significance="preferred"><primary>XCreateSimpleWindow</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Window<function> XCreateSimpleWindow</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> parent</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+  <paramdef>unsignedint<parameter> border_width</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> border</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> background</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>parent</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the parent window.

+<!-- .ds Xy , which are the top-left outside corner of the new window's borders \ -->

+and are relative to the inside of the parent window's borders

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+<!-- .ds Wh , which are the created window's inside dimensions \ -->

+and do not include the created window's borders

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height(Wh.

+The dimensions must be nonzero,

+or a

+<function>BadValue</function>

+error results.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>border_width</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the width of the created window's border in pixels.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>border</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the border pixel value of the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>background</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the background pixel value of the window.

+

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCreateSimpleWindow</function>

+function creates an unmapped

+<function>InputOutput</function>

+subwindow for a specified parent window, returns the

+window ID of the created window, and causes the X server to generate a

+<function>CreateNotify</function>

+event.

+The created window is placed on top in the stacking order with respect to 

+siblings.

+Any part of the window that extends outside its parent window is clipped.

+The border_width for an

+<function>InputOnly</function>

+window must be zero, or a

+<function>BadMatch</function>

+error results.

+<function>XCreateSimpleWindow</function>

+inherits its depth, class, and visual from its parent.

+All other window attributes, except background and border, 

+have their default values.

+</para>

+<para>

+<!-- .LP -->

+<function>XCreateSimpleWindow</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadMatch</function>,

+<function>BadValue</function>,

+and

+<function>BadWindow </function>

+errors.

+</para>

+</sect1>

+<sect1 id="Destroying_Windows">

+<title>Destroying Windows</title>

+<!-- .XS -->

+<!-- (SN Destroying Windows  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to destroy a window or destroy all

+subwindows of a window.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To destroy a window and all of its subwindows, use

+<function>XDestroyWindow</function>.

+<indexterm significance="preferred"><primary>XDestroyWindow</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDestroyWindow</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XDestroyWindow</function>

+function destroys the specified window as well as all of its subwindows and causes

+the X server to generate a

+<function>DestroyNotify</function>

+event for each window.

+The window should never be referenced again.

+If the window specified by the w argument is mapped,

+it is unmapped automatically.

+The ordering of the

+<function>DestroyNotify</function>

+events is such that for any given window being destroyed,

+<function>DestroyNotify</function>

+is generated on any inferiors of the window before being generated on

+the window itself.

+The ordering among siblings and across subhierarchies is not otherwise

+constrained.

+If the window you specified is a root window, no windows are destroyed.

+Destroying a mapped window will generate 

+<function>Expose </function>

+events on other windows that were obscured by the window being destroyed.

+</para>

+<para>

+<!-- .LP -->

+<function>XDestroyWindow</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To destroy all subwindows of a specified window, use 

+<function>XDestroySubwindows</function>.

+<indexterm significance="preferred"><primary>XDestroySubwindows</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDestroySubwindows</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XDestroySubwindows</function>

+function destroys all inferior windows of the specified window, 

+in bottom-to-top stacking order.

+It causes the X server to generate a

+<function>DestroyNotify</function>

+event for each window.

+If any mapped

+subwindows were actually destroyed,

+<function>XDestroySubwindows</function>

+causes the X server to generate 

+<function>Expose </function>

+events on the specified window.

+This is much more efficient than deleting many windows

+one at a time because much of the work need be performed only once for all

+of the windows, rather than for each window.

+The subwindows should never be referenced again.  

+</para>

+<para>

+<!-- .LP -->

+<function>XDestroySubwindows</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+</sect1>

+<sect1 id="Mapping_Windows_">

+<title>Mapping Windows </title>

+<!-- .XS -->

+<!-- (SN Mapping Windows  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+A window is considered mapped if an 

+<function>XMapWindow</function>

+call has been made on it.

+It may not be visible on the screen for one of the following reasons:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+It is obscured by another opaque window.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+One of its ancestors is not mapped.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It is entirely clipped by an ancestor.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+<function>Expose </function>

+events are generated for the window when part or all of

+it becomes visible on the screen. 

+A client receives the

+<function>Expose </function>

+events only if it has asked for them.

+Windows retain their position in the stacking order when they are unmapped.

+</para>

+<para>

+<!-- .LP -->

+A window manager may want to control the placement of subwindows.

+If 

+<function>SubstructureRedirectMask </function>

+has been selected by a window manager

+on a parent window (usually a root window),

+a map request initiated by other clients on a child window is not performed,

+and the window manager is sent a 

+<function>MapRequest </function>

+event.

+However, if the override-redirect flag on the child had been set to

+<function>True</function>

+(usually only on pop-up menus),

+the map request is performed.

+</para>

+<para>

+<!-- .LP -->

+A tiling window manager might decide to reposition and resize other clients' 

+windows and then decide to map the window to its final location.

+A window manager that wants to provide decoration might

+reparent the child into a frame first.

+For further information,

+see sections 3.2.8 and 10.10.

+Only a single client at a time can select for 

+<function>SubstructureRedirectMask</function>.

+</para>

+<para>

+<!-- .LP -->

+Similarly, a single client can select for 

+<function>ResizeRedirectMask </function>

+on a parent window.

+Then, any attempt to resize the window by another client is suppressed, and

+the client receives a 

+<function>ResizeRequest </function>

+event.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To map a given window, use 

+<function>XMapWindow</function>.

+<indexterm significance="preferred"><primary>XMapWindow</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XMapWindow</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XMapWindow</function>

+function

+maps the window and all of its

+subwindows that have had map requests.

+Mapping a window that has an unmapped ancestor does not display the

+window but marks it as eligible for display when the ancestor becomes

+mapped.

+Such a window is called unviewable.

+When all its ancestors are mapped,

+the window becomes viewable

+and will be visible on the screen if it is not obscured by another window.

+This function has no effect if the window is already mapped.

+</para>

+<para>

+<!-- .LP -->

+If the override-redirect of the window is

+<function>False </function>

+and if some other client has selected

+<function>SubstructureRedirectMask</function>

+on the parent window, then the X server generates a

+<function>MapRequest</function>

+event, and the

+<function>XMapWindow</function>

+function does not map the window.

+Otherwise, the window is mapped, and the X server generates a

+<function>MapNotify</function>

+event.

+</para>

+<para>

+<!-- .LP -->

+If the window becomes viewable and no earlier contents for it are remembered,

+the X server tiles the window with its background.

+If the window's background is undefined,

+the existing screen contents are not

+altered, and the X server generates zero or more 

+<function>Expose</function>

+events.

+If backing-store was maintained while the window was unmapped, no 

+<function>Expose</function>

+events

+are generated.

+If backing-store will now be maintained, 

+a full-window exposure is always generated.

+Otherwise, only visible regions may be reported.

+Similar tiling and exposure take place for any newly viewable inferiors.

+</para>

+<para>

+<!-- .LP -->

+<indexterm><primary>XMapWindow</primary></indexterm>

+If the window is an

+<function>InputOutput </function>

+window,

+<function>XMapWindow</function>

+generates 

+<function>Expose </function>

+events on each 

+<function>InputOutput</function>

+window that it causes to be displayed.

+If the client maps and paints the window 

+and if the client begins processing events, 

+the window is painted twice.

+To avoid this,

+first ask for 

+<function>Expose </function>

+events and then map the window,

+so the client processes input events as usual.

+The event list will include 

+<function>Expose </function>

+for each

+window that has appeared on the screen. 

+The client's normal response to

+an 

+<function>Expose </function>

+event should be to repaint the window.

+This method usually leads to simpler programs and to proper interaction

+with window managers.

+</para>

+<para>

+<!-- .LP -->

+<function>XMapWindow</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To map and raise a window, use

+<function>XMapRaised</function>.

+<indexterm significance="preferred"><primary>XMapRaised</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XMapRaised</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XMapRaised</function>

+function

+essentially is similar to

+<function>XMapWindow</function>

+in that it maps the window and all of its

+subwindows that have had map requests.

+However, it also raises the specified window to the top of the stack.

+For additional information,

+see 

+<function>XMapWindow</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XMapRaised</function>

+can generate multiple

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To map all subwindows for a specified window, use 

+<function>XMapSubwindows</function>.

+<indexterm significance="preferred"><primary>XMapSubwindows</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XMapSubwindows</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XMapSubwindows</function>

+<indexterm><primary>XMapSubwindows</primary></indexterm>

+function maps all subwindows for a specified window in top-to-bottom stacking 

+order.

+The X server generates

+<function>Expose</function>

+events on each newly displayed window.

+This may be much more efficient than mapping many windows

+one at a time because the server needs to perform much of the work

+only once, for all of the windows, rather than for each window.

+</para>

+<para>

+<!-- .LP -->

+<function>XMapSubwindows</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+</sect1>

+<sect1 id="Unmapping_Windows">

+<title>Unmapping Windows</title>

+<!-- .XS -->

+<!-- (SN Unmapping Windows  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to unmap a window or all subwindows.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To unmap a window, use 

+<function>XUnmapWindow</function>.

+<indexterm significance="preferred"><primary>XUnmapWindow</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XUnmapWindow</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XUnmapWindow</function>

+function unmaps the specified window and causes the X server to generate an

+<function>UnmapNotify</function>

+<indexterm><primary>UnmapNotify Event</primary></indexterm>

+<indexterm><primary>XUnmapWindow</primary></indexterm>

+event.

+If the specified window is already unmapped, 

+<function>XUnmapWindow </function>

+has no effect.

+Normal exposure processing on formerly obscured windows is performed.

+Any child window will no longer be visible until another map call is

+made on the parent.

+In other words, the subwindows are still mapped but are not visible

+until the parent is mapped.

+Unmapping a window will generate 

+<function>Expose </function>

+events on windows that were formerly obscured by it.

+</para>

+<para>

+<!-- .LP -->

+<function>XUnmapWindow</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To unmap all subwindows for a specified window, use 

+<function>XUnmapSubwindows</function>.

+<indexterm significance="preferred"><primary>XUnmapSubwindows</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XUnmapSubwindows</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XUnmapSubwindows</function>

+function unmaps all subwindows for the specified window in bottom-to-top

+stacking order.

+It causes the X server to generate an

+<function>UnmapNotify</function>

+event on each subwindow and 

+<function>Expose </function>

+events on formerly obscured windows.

+<indexterm><primary>UnmapNotify Event</primary></indexterm>

+Using this function is much more efficient than unmapping multiple windows

+one at a time because the server needs to perform much of the work

+only once, for all of the windows, rather than for each window.

+</para>

+<para>

+<!-- .LP -->

+<function>XUnmapSubwindows</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+</sect1>

+<sect1 id="Configuring_Windows">

+<title>Configuring Windows</title>

+<!-- .XS -->

+<!-- (SN Configuring Windows  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+</para>

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to

+move a window, resize a window, move and resize a window, or

+change a window's border width.

+To change one of these parameters,

+set the appropriate member of the

+<function>XWindowChanges</function>

+structure and OR in the corresponding value mask in subsequent calls to

+<function>XConfigureWindow</function>.

+The symbols for the value mask bits and the

+<function>XWindowChanges</function>

+structure are:

+<!-- .sM -->

+</para>

+<para>

+<!-- .LP -->

+

+<literallayout class="monospaced">

+/* Configure window value mask bits */

+#define      CWX              (1&lt;&lt;0)

+#define      CWY              (1&lt;&lt;1)

+#define      CWWidth          (1&lt;&lt;2)

+#define      CWHeight         (1&lt;&lt;3)

+#define      CWBorderWidth    (1&lt;&lt;4)

+#define      CWSibling        (1&lt;&lt;5)

+#define      CWStackMode      (1&lt;&lt;6)

+</literallayout>

+

+<indexterm significance="preferred"><primary>XWindowChanges</primary></indexterm>

+<literallayout class="monospaced">

+/* Values */

+

+typedef struct {

+     int x, y;

+     int width, height;

+     int border_width;

+     Window sibling;

+     int stack_mode;

+} XWindowChanges;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The x and y members are used to set the window's x and y coordinates,

+which are relative to the parent's origin

+and indicate the position of the upper-left outer corner of the window.

+The width and height members are used to set the inside size of the window,

+not including the border, and must be nonzero, or a

+<function>BadValue</function>

+error results.

+Attempts to configure a root window have no effect.

+</para>

+<para>

+<!-- .LP -->

+The border_width member is used to set the width of the border in pixels.

+Note that setting just the border width leaves the outer-left corner of the window

+in a fixed position but moves the absolute position of the window's origin.

+If you attempt to set the border-width attribute of an

+<function>InputOnly</function>

+window nonzero, a

+<function>BadMatch</function>

+error results. 

+</para>

+<para>

+<!-- .LP -->

+The sibling member is used to set the sibling window for stacking operations.

+The stack_mode member is used to set how the window is to be restacked 

+and can be set to

+<function>Above</function>,

+<function>Below</function>,

+<function>TopIf</function>,

+<function>BottomIf</function>,

+or 

+<function>Opposite</function>.

+</para>

+<para>

+<!-- .LP -->

+If the override-redirect flag of the window is

+<function>False </function>

+and if some other client has selected

+<function>SubstructureRedirectMask</function>

+on the parent, the X server generates a

+<function>ConfigureRequest</function>

+event, and no further processing is performed.

+Otherwise, 

+if some other client has selected 

+<function>ResizeRedirectMask </function>

+on the window and the inside

+width or height of the window is being changed,

+a 

+<function>ResizeRequest</function>

+event is generated, and the current inside width and height are

+used instead.

+Note that the override-redirect flag of the window has no effect

+on

+<function>ResizeRedirectMask </function>

+and that

+<function>SubstructureRedirectMask</function>

+on the parent has precedence over

+<function>ResizeRedirectMask </function>

+on the window.

+</para>

+<para>

+<!-- .LP -->

+When the geometry of the window is changed as specified, 

+the window is restacked among siblings, and a

+<function>ConfigureNotify </function>

+event is generated if the state of the window actually changes.

+<function>GravityNotify</function>

+events are generated after 

+<function>ConfigureNotify </function>

+events.

+If the inside width or height of the window has actually changed, 

+children of the window are affected as specified.

+</para>

+<para>

+<!-- .LP -->

+If a window's size actually changes,

+the window's subwindows move according to their window gravity.

+Depending on the window's bit gravity,

+the contents of the window also may be moved (see section 3.2.3).

+</para>

+<para>

+<!-- .LP -->

+If regions of the window were obscured but now are not,

+exposure processing is performed on these formerly obscured windows, 

+including the window itself and its inferiors. 

+As a result of increasing the width or height,

+exposure processing is also performed on any new regions of the window 

+and any regions where window contents are lost.

+</para>

+<para>

+<!-- .LP -->

+The restack check (specifically, the computation for 

+<function>BottomIf</function>,

+<function>TopIf</function>,

+and 

+<function>Opposite</function>)

+is performed with respect to the window's final size and position (as

+controlled by the other arguments of the request), not its initial position.

+If a sibling is specified without a stack_mode,

+a

+<function>BadMatch</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+If a sibling and a stack_mode are specified, 

+the window is restacked as follows:

+</para>

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <tbody>

+    <row>

+      <entry><function>Above</function></entry>

+      <entry>The window is placed just above the sibling.</entry>

+    </row>

+    <row>

+      <entry><function>Below</function></entry>

+      <entry>The window is placed just below the sibling.</entry>

+    </row>

+    <row>

+      <entry><function>TopIf</function></entry>

+      <entry>If the sibling occludes the window, the window is placed at the top of the stack.</entry>

+    </row>

+    <row>

+      <entry><function>BottomIf</function></entry>

+      <entry>If the window occludes the sibling, the window is placed at the bottom of the stack.</entry>

+    </row>

+    <row>

+      <entry><function>Opposite</function></entry>

+      <entry>

+If the sibling occludes the window, the window is placed at the top of the stack.

+If the window occludes the sibling,

+the window is placed at the bottom of the stack.

+      </entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<para>

+<!-- .LP -->

+If a stack_mode is specified but no sibling is specified,

+the window is restacked as follows:

+</para>

+

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <tbody>

+    <row>

+      <entry><function>Above</function></entry>

+      <entry>The window is placed at the top of the stack.</entry>

+    </row>

+    <row>

+      <entry><function>Below</function></entry>

+      <entry>The window is placed at the bottom of the stack.</entry>

+    </row>

+    <row>

+      <entry><function>TopIf</function></entry>

+      <entry>

+If any sibling occludes the window, the window is placed at

+the top of the stack.

+      </entry>

+    </row>

+    <row>

+      <entry>

+If the window occludes any sibling, the window is placed at

+the bottom of the stack.

+      </entry>

+    </row>

+    <row>

+      <entry><function>Opposite</function></entry>

+      <entry>

+If any sibling occludes the window, the window

+is placed at the top of the stack.

+If the window occludes any sibling,

+the window is placed at the bottom of the stack.

+      </entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<para>

+<!-- .LP -->

+Attempts to configure a root window have no effect.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To configure a window's size, location, stacking, or border, use

+<function>XConfigureWindow</function>.

+<indexterm significance="preferred"><primary>XConfigureWindow</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XConfigureWindow</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>unsignedint<parameter> value_mask</parameter></paramdef>

+  <paramdef>XWindowChanges<parameter> *values</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Wi to be reconfigured -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window (Wi.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>value_mask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies which values are to be set using information in

+the values structure.

+This mask is the bitwise inclusive OR of the valid configure window values bits.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>values</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the 

+<function>XWindowChanges </function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XConfigureWindow</function>

+function uses the values specified in the

+<function>XWindowChanges</function>

+structure to reconfigure a window's size, position, border, and stacking order.

+Values not specified are taken from the existing geometry of the window.

+</para>

+<para>

+<!-- .LP -->

+If a sibling is specified without a stack_mode or if the window

+is not actually a sibling,

+a

+<function>BadMatch</function>

+error results. 

+Note that the computations for

+<function>BottomIf</function>,

+<function>TopIf</function>,

+and

+<function>Opposite</function>

+are performed with respect to the window's final geometry (as controlled by the

+other arguments passed to

+<function>XConfigureWindow</function>),

+not its initial geometry.

+Any backing store contents of the window, its

+inferiors, and other newly visible windows are either discarded or

+changed to reflect the current screen contents 

+(depending on the implementation).

+</para>

+<para>

+<!-- .LP -->

+<function>XConfigureWindow</function>

+can generate

+<function>BadMatch</function>,

+<function>BadValue</function>,

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To move a window without changing its size, use 

+<function>XMoveWindow</function>.

+<indexterm significance="preferred"><primary>XMoveWindow</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XMoveWindow</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN      -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Wi to be moved -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window (Wi.

+<!-- .ds Xy , which define the new location of the top-left pixel \ -->

+of the window's border or the window itself if it has no border

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XMoveWindow</function>

+function moves the specified window to the specified x and y coordinates,

+but it does not change the window's size, raise the window, or

+change the mapping state of the window.

+Moving a mapped window may or may not lose the window's contents 

+depending on if the window is obscured by nonchildren 

+and if no backing store exists.

+If the contents of the window are lost, 

+the X server generates

+<function>Expose </function>

+events.

+Moving a mapped window generates

+<function>Expose </function>

+events on any formerly obscured windows. 

+</para>

+<para>

+<!-- .LP -->

+If the override-redirect flag of the window is 

+<function>False </function>

+and some

+other client has selected 

+<function>SubstructureRedirectMask </function>

+on the parent, the X server generates a

+<function>ConfigureRequest </function>

+event, and no further processing is

+performed.  

+Otherwise, the window is moved.

+</para>

+<para>

+<!-- .LP -->

+<function>XMoveWindow</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To change a window's size without changing the upper-left coordinate, use 

+<function>XResizeWindow</function>.

+<indexterm significance="preferred"><primary>XResizeWindow</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XResizeWindow</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+<!-- .ds Wh , which are the interior dimensions of the window \ -->

+after the call completes

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height(Wh.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XResizeWindow</function>

+function changes the inside dimensions of the specified window, not including

+its borders.

+This function does not change the window's upper-left coordinate or

+the origin and does not restack the window.

+Changing the size of a mapped window may lose its contents and generate

+<function>Expose </function>

+events.

+If a mapped window is made smaller, 

+changing its size generates

+<function>Expose </function>

+events on windows that the mapped window formerly obscured.

+</para>

+<para>

+<!-- .LP -->

+If the override-redirect flag of the window is 

+<function>False </function>

+and some

+other client has selected 

+<function>SubstructureRedirectMask </function>

+on the parent, the X server generates a

+<function>ConfigureRequest </function>

+event, and no further processing is performed.  

+If either width or height is zero,

+a

+<function>BadValue</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+<function>XResizeWindow</function>

+can generate

+<function>BadValue</function>

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To change the size and location of a window, use 

+<function>XMoveResizeWindow</function>.

+<indexterm significance="preferred"><primary>XMoveResizeWindow</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XMoveResizeWindow</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Wi to be reconfigured -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window (Wi.

+<!-- .ds Xy , which define the new position of the window relative to its parent -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+<!-- .ds Wh , which define the interior size of the window -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height(Wh.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XMoveResizeWindow</function>

+function changes the size and location of the specified window 

+without raising it.

+Moving and resizing a mapped window may generate an

+<function>Expose </function>

+event on the window.

+Depending on the new size and location parameters,

+moving and resizing a window may generate 

+<function>Expose </function>

+events on windows that the window formerly obscured. 

+</para>

+<para>

+<!-- .LP -->

+If the override-redirect flag of the window is 

+<function>False </function>

+and some

+other client has selected 

+<function>SubstructureRedirectMask </function>

+on the parent, the X server generates a

+<function>ConfigureRequest </function>

+event, and no further processing is performed.  

+Otherwise, the window size and location are changed.

+</para>

+<para>

+<!-- .LP -->

+<function>XMoveResizeWindow</function>

+can generate

+<function>BadValue </function>

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To change the border width of a given window, use

+<function>XSetWindowBorderWidth</function>.

+<indexterm significance="preferred"><primary>XSetWindowBorderWidth</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetWindowBorderWidth</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>unsignedint<parameter> width</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the width of the window border.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetWindowBorderWidth</function>

+function sets the specified window's border width to the specified width.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetWindowBorderWidth</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+</sect1>

+<sect1 id="Changing_Window_Stacking_Order">

+<title>Changing Window Stacking Order</title>

+<!-- .XS -->

+<!-- (SN Changing Window Stacking Order  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+</para>

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to raise, lower, circulate,

+or restack windows.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To raise a window so that no sibling window obscures it, use 

+<function>XRaiseWindow</function>.

+<indexterm significance="preferred"><primary>XRaiseWindow</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XRaiseWindow</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XRaiseWindow</function>

+function

+raises the specified window to the top of the stack so that no sibling window

+obscures it.

+If the windows are regarded as overlapping sheets of paper stacked 

+on a desk,

+then raising a window is analogous to moving the sheet to the top of

+the stack but leaving its x and y location on the desk constant.

+Raising a mapped window may generate 

+<function>Expose</function>

+events for the window and any mapped subwindows that were formerly obscured.  

+</para>

+<para>

+<!-- .LP -->

+If the override-redirect attribute of the window is 

+<function>False </function>

+and some

+other client has selected 

+<function>SubstructureRedirectMask </function>

+on the parent, the X server generates a

+<function>ConfigureRequest </function>

+event, and no processing is performed.

+Otherwise, the window is raised.

+</para>

+<para>

+<!-- .LP -->

+<function>XRaiseWindow</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To lower a window so that it does not obscure any sibling windows, use 

+<function>XLowerWindow</function>.

+<indexterm significance="preferred"><primary>XLowerWindow</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XLowerWindow</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XLowerWindow</function>

+function lowers the specified window to the bottom of the stack

+so that it does not obscure any sibling

+windows.

+If the windows are regarded as overlapping sheets of paper

+stacked on a desk, then lowering a window is analogous to moving the

+sheet to the bottom of the stack but leaving its x and y location on

+the desk constant.

+Lowering a mapped window will generate 

+<function>Expose </function>

+events on any windows it formerly obscured.

+</para>

+<para>

+<!-- .LP -->

+If the override-redirect attribute of the window is 

+<function>False </function>

+and some

+other client has selected 

+<function>SubstructureRedirectMask </function>

+on the parent, the X server generates a

+<function>ConfigureRequest </function>

+event, and no processing is performed.  

+Otherwise, the window is lowered to the bottom of the

+stack.

+</para>

+<para>

+<!-- .LP -->

+<function>XLowerWindow</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To circulate a subwindow up or down, use

+<function>XCirculateSubwindows</function>.

+<indexterm significance="preferred"><primary>XCirculateSubwindows</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XCirculateSubwindows</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>int<parameter> direction</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>direction</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the direction (up or down) that you want to circulate

+the window. 

+You can pass 

+<function>RaiseLowest</function>

+or

+<function>LowerHighest</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCirculateSubwindows</function>

+function circulates children of the specified window in the specified 

+direction.

+If you specify

+<function>RaiseLowest</function>,

+<function>XCirculateSubwindows</function>

+raises the lowest mapped child (if any) that is occluded 

+by another child to the top of the stack.

+If you specify

+<function>LowerHighest</function>,

+<function>XCirculateSubwindows</function>

+lowers the highest mapped child (if any) that occludes another child

+to the bottom of the stack.

+Exposure processing is then performed on formerly obscured windows.

+If some other client has selected 

+<function>SubstructureRedirectMask </function>

+on the window, the X server generates a 

+<function>CirculateRequest </function>

+event, and no further processing is performed.

+If a child is actually restacked,

+the X server generates a

+<function>CirculateNotify</function>

+event. 

+</para>

+<para>

+<!-- .LP -->

+<function>XCirculateSubwindows</function>

+can generate

+<function>BadValue</function>

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To raise the lowest mapped child of a window that is partially or completely

+occluded by another child, use

+<function>XCirculateSubwindowsUp</function>.

+<indexterm significance="preferred"><primary>XCirculateSubwindowsUp</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XCirculateSubwindowsUp</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCirculateSubwindowsUp</function>

+function raises the lowest mapped child of the specified window that

+is partially

+or completely

+occluded by another child.

+Completely unobscured children are not affected.

+This is a convenience function equivalent to

+<function>XCirculateSubwindows</function>

+with

+<function>RaiseLowest</function>

+specified.

+</para>

+<para>

+<!-- .LP -->

+<function>XCirculateSubwindowsUp</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To lower the highest mapped child of a window that partially or 

+completely occludes another child, use 

+<function>XCirculateSubwindowsDown</function>.

+<indexterm significance="preferred"><primary>XCirculateSubwindowsDown</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XCirculateSubwindowsDown</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCirculateSubwindowsDown</function>

+function lowers the highest mapped child of the specified window that partially

+or completely occludes another child.

+Completely unobscured children are not affected.

+This is a convenience function equivalent to

+<function>XCirculateSubwindows</function>

+with

+<function>LowerHighest</function>

+specified.

+</para>

+<para>

+<!-- .LP -->

+<function>XCirculateSubwindowsDown</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To restack a set of windows from top to bottom, use 

+<function>XRestackWindows</function>.

+<indexterm significance="preferred"><primary>XRestackWindows</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XRestackWindows</function></funcdef>

+  <paramdef>XRestackWindows\^(\^display,windows,<parameter> \^nwindows)</parameter></paramdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> windows[]</parameter></paramdef>

+  <paramdef>int<parameter> nwindows</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>windows</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array containing the windows to be restacked.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nwindows</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of windows to be restacked.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XRestackWindows</function>

+function restacks the windows in the order specified,

+from top to bottom.

+The stacking order of the first window in the windows array is unaffected,

+but the other windows in the array are stacked underneath the first window,

+in the order of the array.

+The stacking order of the other windows is not affected.

+For each window in the window array that is not a child of the specified window,

+a

+<function>BadMatch</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+If the override-redirect attribute of a window is 

+<function>False </function>

+and some

+other client has selected 

+<function>SubstructureRedirectMask </function>

+on the parent, the X server generates 

+<function>ConfigureRequest </function>

+events for each window whose override-redirect flag is not set, 

+and no further processing is performed.

+Otherwise, the windows will be restacked in top-to-bottom order.

+</para>

+<para>

+<!-- .LP -->

+<function>XRestackWindows</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+</sect1>

+<sect1 id="Changing_Window_Attributes">

+<title>Changing Window Attributes</title>

+<!-- .XS -->

+<!-- (SN Changing Window Attributes  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+</para>

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to set window attributes.

+<function>XChangeWindowAttributes</function>

+is the more general function that allows you to set one or more window

+attributes provided by the

+<function>XSetWindowAttributes</function>

+structure.

+The other functions described in this section allow you to set one specific

+window attribute, such as a window's background.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To change one or more attributes for a given window, use

+<function>XChangeWindowAttributes</function>.

+<indexterm significance="preferred"><primary>XChangeWindowAttributes</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XChangeWindowAttributes</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>

+  <paramdef>XSetWindowAttributes<parameter> *attributes</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>valuemask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies which window attributes are defined in the attributes

+argument.

+This mask is the bitwise inclusive OR of the valid attribute mask bits.

+If valuemask is zero,

+the attributes are ignored and are not referenced.

+The values and restrictions are

+the same as for

+<function>XCreateWindow</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      

+    </term>

+    <listitem>

+      <para>

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>attributes</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the structure from which the values (as specified by the value mask)

+are to be taken.

+The value mask should have the appropriate bits

+set to indicate which attributes have been set in the structure 

+(see section 3.2).

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Depending on the valuemask,

+the

+<function>XChangeWindowAttributes</function>

+function uses the window attributes in the

+<function>XSetWindowAttributes</function>

+structure to change the specified window attributes.

+Changing the background does not cause the window contents to be

+changed.

+To repaint the window and its background, use 

+<function>XClearWindow</function>.

+Setting the border or changing the background such that the

+border tile origin changes causes the border to be repainted.

+Changing the background of a root window to 

+<function>None </function>

+or 

+<function>ParentRelative</function>

+restores the default background pixmap.

+Changing the border of a root window to

+<function>CopyFromParent</function>

+restores the default border pixmap.

+Changing the win-gravity does not affect the current position of the

+window.

+Changing the backing-store of an obscured window to 

+<function>WhenMapped </function>

+or

+<function>Always</function>,

+or changing the backing-planes, backing-pixel, or

+save-under of a mapped window may have no immediate effect.

+Changing the colormap of a window (that is, defining a new map, not

+changing the contents of the existing map) generates a 

+<function>ColormapNotify</function>

+event.

+Changing the colormap of a visible window may have no

+immediate effect on the screen because the map may not be installed

+(see

+<function>XInstallColormap</function>).

+Changing the cursor of a root window to 

+<function>None </function>

+restores the default

+cursor.

+Whenever possible, you are encouraged to share colormaps.

+</para>

+<para>

+<!-- .LP -->

+Multiple clients can select input on the same window. 

+Their event masks are maintained separately.

+When an event is generated, 

+it is reported to all interested clients. 

+However, only one client at a time can select for 

+<function>SubstructureRedirectMask</function>,

+<function>ResizeRedirectMask</function>,

+and

+<function>ButtonPressMask</function>.

+If a client attempts to select any of these event masks 

+and some other client has already selected one, 

+a

+<function>BadAccess</function>

+error results.

+There is only one do-not-propagate-mask for a window, 

+not one per client.

+</para>

+<para>

+<!-- .LP -->

+<function>XChangeWindowAttributes</function>

+can generate

+<function>BadAccess</function>,

+<function>BadColor</function>,

+<function>BadCursor</function>,

+<function>BadMatch</function>,

+<function>BadPixmap</function>,

+<function>BadValue</function>,

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the background of a window to a given pixel, use 

+<function>XSetWindowBackground</function>.

+<indexterm significance="preferred"><primary>XSetWindowBackground</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetWindowBackground</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> background_pixel</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>background_pixel</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the pixel that is to be used for the background.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetWindowBackground</function>

+function sets the background of the window to the specified pixel value.

+Changing the background does not cause the window contents to be changed.

+<function>XSetWindowBackground</function>

+uses a pixmap of undefined size filled with the pixel value you passed.

+If you try to change the background of an 

+<function>InputOnly</function>

+window, a

+<function>BadMatch</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetWindowBackground</function>

+can generate

+<function>BadMatch</function>

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To set the background of a window to a given pixmap, use 

+<function>XSetWindowBackgroundPixmap</function>.

+<indexterm><primary>Window</primary><secondary>background</secondary></indexterm>

+<indexterm significance="preferred"><primary>XSetWindowBackgroundPixmap</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetWindowBackgroundPixmap</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>Pixmap<parameter> background_pixmap</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>background_pixmap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the background pixmap,

+<function>ParentRelative</function>,

+or

+<function>None</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm><primary>Resource IDs</primary><secondary>freeing</secondary></indexterm>

+<indexterm><primary>Freeing</primary><secondary>resources</secondary></indexterm>

+The

+<function>XSetWindowBackgroundPixmap</function>

+function sets the background pixmap of the window to the specified pixmap.

+The background pixmap can immediately be freed if no further explicit

+references to it are to be made.

+If 

+<function>ParentRelative</function>

+is specified, 

+the background pixmap of the window's parent is used,

+or on the root window, the default background is restored.

+If you try to change the background of an 

+<function>InputOnly</function>

+window, a

+<function>BadMatch</function>

+error results.

+If the background is set to

+<function>None</function>,

+the window has no defined background.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetWindowBackgroundPixmap</function>

+can generate

+<function>BadMatch</function>,

+<function>BadPixmap</function>,

+and 

+<function>BadWindow </function>

+errors.

+<!-- .NT Note -->

+<function>XSetWindowBackground</function>

+and

+<function>XSetWindowBackgroundPixmap</function>

+do not change the current contents of the window.

+<!-- .NE -->

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To change and repaint a window's border to a given pixel, use 

+<function>XSetWindowBorder</function>.

+<indexterm significance="preferred"><primary>XSetWindowBorder</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetWindowBorder</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> border_pixel</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>border_pixel</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the entry in the colormap. 

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetWindowBorder</function>

+function sets the border of the window to the pixel value you specify.

+If you attempt to perform this on an

+<function>InputOnly</function>

+window, a

+<function>BadMatch</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetWindowBorder</function>

+can generate

+<function>BadMatch </function>

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To change and repaint the border tile of a given window, use 

+<function>XSetWindowBorderPixmap</function>.

+<indexterm significance="preferred"><primary>XSetWindowBorderPixmap</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetWindowBorderPixmap</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>Pixmap<parameter> border_pixmap</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>border_pixmap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the border pixmap or

+<function>CopyFromParent</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetWindowBorderPixmap</function>

+function sets the border pixmap of the window to the pixmap you specify.

+The border pixmap can be freed immediately if no further explicit

+references to it are to be made.

+If you specify

+<function>CopyFromParent</function>,

+a copy of the parent window's border pixmap is used.

+If you attempt to perform this on an

+<function>InputOnly</function>

+window, a

+<function>BadMatch</function>

+error results.

+<indexterm><primary>Resource IDs</primary><secondary>freeing</secondary></indexterm>

+<indexterm><primary>Freeing</primary><secondary>resources</secondary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<function>XSetWindowBorderPixmap</function>

+can generate

+<function>BadMatch</function>,

+<function>BadPixmap</function>,

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the colormap of a given window, use

+<function>XSetWindowColormap</function>.

+<indexterm significance="preferred"><primary>XSetWindowColormap</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetWindowColormap</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetWindowColormap</function>

+function sets the specified colormap of the specified window.

+The colormap must have the same visual type as the window,

+or a

+<function>BadMatch</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetWindowColormap</function>

+can generate

+<function>BadColor</function>,

+<function>BadMatch</function>,

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To define which cursor will be used in a window, use

+<function>XDefineCursor</function>.

+<indexterm><primary>Window</primary><secondary>defining the cursor</secondary></indexterm>

+<indexterm significance="preferred"><primary>XDefineCursor</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDefineCursor</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>Cursor<parameter> cursor</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>cursor</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the cursor that is to be displayed or

+<function>None</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If a cursor is set, it will be used when the pointer is in the window.

+If the cursor is

+<function>None</function>,

+it is equivalent to

+<function>XUndefineCursor</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XDefineCursor</function>

+can generate

+<function>BadCursor</function>

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To undefine the cursor in a given window, use

+<function>XUndefineCursor</function>.

+<indexterm><primary>Window</primary><secondary>undefining the cursor</secondary></indexterm>

+<indexterm significance="preferred"><primary>XUndefineCursor</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XUndefineCursor</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XUndefineCursor</function>

+function undoes the effect of a previous

+<function>XDefineCursor</function>

+for this window.

+When the pointer is in the window,

+the parent's cursor will now be used.

+On the root window,

+the default cursor is restored.

+</para>

+<para>

+<!-- .LP -->

+<function>XUndefineCursor</function>

+can generate a

+<function>BadWindow </function>

+error.

+<!-- .bp -->

+

+</para>

+</sect1>

+</chapter>

diff --git a/libX11/specs/libX11/CH04 b/libX11/specs/libX11/CH04
deleted file mode 100644
index b964198c2..000000000
--- a/libX11/specs/libX11/CH04
+++ /dev/null
@@ -1,1595 +0,0 @@
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-.\" OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" Except as contained in this notice, the name of the X Consortium shall
-.\" not be used in advertising or otherwise to promote the sale, use or
-.\" other dealings in this Software without prior written authorization
-.\" from the X Consortium.
-.\"
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
-.\" Digital Equipment Corporation
-.\"
-.\" Portions Copyright \(co 1990, 1991 by
-.\" Tektronix, Inc.
-.\"
-.\" Permission to use, copy, modify and distribute this documentation for
-.\" any purpose and without fee is hereby granted, provided that the above
-.\" copyright notice appears in all copies and that both that copyright notice
-.\" and this permission notice appear in all copies, and that the names of
-.\" Digital and Tektronix not be used in in advertising or publicity pertaining
-.\" to this documentation without specific, written prior permission.
-.\" Digital and Tektronix makes no representations about the suitability
-.\" of this documentation for any purpose.
-.\" It is provided ``as is'' without express or implied warranty.
-.\" 
-\&
-.sp 1
-.ce 3
-\s+1\fBChapter 4\fP\s-1
-
-\s+1\fBWindow Information Functions\fP\s-1
-.sp 2
-.nr H1 4
-.nr H2 0
-.nr H3 0
-.nr H4 0
-.nr H5 0
-.na
-.LP
-.XS
-Chapter 4: Window Information Functions 
-.XE
-After you connect the display to the X server and create a window,
-you can use the Xlib window information functions to:
-.IP \(bu 5
-Obtain information about a window
-.IP \(bu 5
-Translate screen coordinates
-.IP \(bu 5
-Manipulate property lists
-.IP \(bu 5
-Obtain and change window properties
-.IP \(bu 5
-Manipulate selections
-.NH 2
-Obtaining Window Information
-.XS
-\*(SN Obtaining Window Information 
-.XE
-.LP
-Xlib provides functions that you can use to obtain information about 
-the window tree, the window's current attributes, 
-the window's current geometry, or the current pointer coordinates.
-Because they are most frequently used by window managers,
-these functions all return a status to indicate whether the window still
-exists.
-.LP
-.sp
-To obtain the parent, a list of children, and number of children for 
-a given window, use 
-.PN XQueryTree .
-.IN "Child Window"
-.IN "Parent Window"
-.IN "XQueryTree" "" "@DEF@"
-.sM
-.FD 0
-Status XQueryTree\^(\^\fIdisplay\fP, \fIw\fP\^, \fIroot_return\fP\^, \fIparent_return\fP\^, \fIchildren_return\fP\^, \fInchildren_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      Window *\fIroot_return\fP\^;
-.br
-      Window *\fIparent_return\fP\^;
-.br
-      Window **\fIchildren_return\fP\^;
-.br
-      unsigned int *\fInchildren_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Wi whose list of children, root, parent, and number of children \
-you want to obtain
-.IP \fIw\fP 1i
-Specifies the window \*(Wi.
-.IP \fIroot_return\fP 1i
-Returns the root window.
-.IP \fIparent_return\fP 1i
-Returns the parent window.
-.IP \fIchildren_return\fP 1i
-Returns the list of children.
-.IP \fInchildren_return\fP 1i
-Returns the number of children.
-.LP
-.eM
-The
-.PN XQueryTree
-function returns the root ID, the parent window ID, 
-a pointer to the list of children windows
-(NULL when there are no children), 
-and the number of children in the list for the specified window.
-The children are listed in current stacking order, from bottom-most 
-(first) to top-most (last).
-.PN XQueryTree
-returns zero if it fails and nonzero if it succeeds.
-To free a non-NULL children list when it is no longer needed, use 
-.PN XFree .
-.LP
-.PN XQueryTree
-can generate a
-.PN BadWindow
-error.
-.LP
-.sp
-To obtain the current attributes of a given window, use 
-.PN XGetWindowAttributes .
-.IN "XGetWindowAttributes" "" "@DEF@"
-.sM
-.FD 0
-Status XGetWindowAttributes\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwindow_attributes_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XWindowAttributes *\fIwindow_attributes_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Wi whose current attributes you want to obtain
-.IP \fIw\fP 1i
-Specifies the window \*(Wi.
-.IP \fIwindow_attributes_return\fP 1i
-Returns the specified window's attributes in the
-.PN XWindowAttributes
-structure.
-.LP
-.eM
-The
-.PN XGetWindowAttributes
-function returns the current attributes for the specified window to an
-.PN XWindowAttributes
-structure.
-.LP
-.IN "XWindowAttributes" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int x, y;	/* location of window */
-	int width, height;	/* width and height of window */
-	int border_width;	/* border width of window */
-	int depth;	/* depth of window */
-	Visual *visual;	/* the associated visual structure */
-	Window root;	/* root of screen containing window */
-	int class;	/* InputOutput, InputOnly*/
-	int bit_gravity;	/* one of the bit gravity values */
-	int win_gravity;	/* one of the window gravity values */
-	int backing_store;	/* NotUseful, WhenMapped, Always */
-	unsigned long backing_planes;	/* planes to be preserved if possible */
-	unsigned long backing_pixel;	/* value to be used when restoring planes */
-	Bool save_under;	/* boolean, should bits under be saved? */
-	Colormap colormap;	/* color map to be associated with window */
-	Bool map_installed;	/* boolean, is color map currently installed*/
-	int map_state;	/* IsUnmapped, IsUnviewable, IsViewable */
-	long all_event_masks;	/* set of events all people have interest in*/
-	long your_event_mask;	/* my event mask */
-	long do_not_propagate_mask;	/* set of events that should not propagate */
-	Bool override_redirect;	/* boolean value for override-redirect */
-	Screen *screen;	/* back pointer to correct screen */
-} XWindowAttributes;
-.De
-.LP
-.eM
-The x and y members are set to the upper-left outer
-corner relative to the parent window's origin.
-The width and height members are set to the inside size of the window, 
-not including the border.
-The border_width member is set to the window's border width in pixels.
-The depth member is set to the depth of the window 
-(that is, bits per pixel for the object).
-The visual member is a pointer to the screen's associated
-.PN Visual
-structure.
-The root member is set to the root window of the screen containing the window.
-The class member is set to the window's class and can be either
-.PN InputOutput
-or
-.PN InputOnly .
-.LP
-The bit_gravity member is set to the window's bit gravity
-and can be one of the following:
-.LP
-.TS
-lw(1.5i) lw(1.5i).
-T{
-.PN ForgetGravity
-T}	T{
-.PN EastGravity
-T}
-T{
-.PN NorthWestGravity
-T}	T{
-.PN SouthWestGravity
-T}
-T{
-.PN NorthGravity
-T}	T{
-.PN SouthGravity
-T}
-T{
-.PN NorthEastGravity
-T}	T{
-.PN SouthEastGravity
-T}
-T{
-.PN WestGravity
-T}	T{
-.PN StaticGravity
-T}
-.PN CenterGravity
-.TE
-.LP
-The win_gravity member is set to the window's window gravity
-and can be one of the following:
-.LP
-.TS
-lw(1.5i) lw(1.5i).
-T{
-.PN UnmapGravity
-T}	T{
-.PN EastGravity
-T}
-T{
-.PN NorthWestGravity
-T}	T{
-.PN SouthWestGravity
-T}
-T{
-.PN NorthGravity
-T}	T{
-.PN SouthGravity
-T}
-T{
-.PN NorthEastGravity
-T}	T{
-.PN SouthEastGravity
-T}
-T{
-.PN WestGravity
-T}	T{
-.PN StaticGravity
-T}
-.PN CenterGravity
-.TE
-.LP
-For additional information on gravity,
-see section 3.2.3.
-.LP
-The backing_store member is set to indicate how the X server should maintain
-the contents of a window 
-and can be 
-.PN WhenMapped ,
-.PN Always ,
-or
-.PN NotUseful .
-The backing_planes member is set to indicate (with bits set to 1) which bit 
-planes of the window hold dynamic data that must be preserved in backing_stores 
-and during save_unders.
-The backing_pixel member is set to indicate what values to use 
-for planes not set in backing_planes.
-.LP
-The save_under member is set to 
-.PN True
-or
-.PN False .
-The colormap member is set to the colormap for the specified window and can be
-a colormap ID or 
-.PN None .
-The map_installed member is set to indicate whether the colormap is 
-currently installed and can be 
-.PN True
-or
-.PN False .
-The map_state member is set to indicate the state of the window and can be
-.PN IsUnmapped ,
-.PN IsUnviewable ,
-or
-.PN IsViewable .
-.PN IsUnviewable
-is used if the window is mapped but some ancestor is unmapped.
-.LP
-The all_event_masks member is set to the bitwise inclusive OR of all event 
-masks selected on the window by all clients.
-The your_event_mask member is set to the bitwise inclusive OR of all event 
-masks selected by the querying client.
-The do_not_propagate_mask member is set to the bitwise inclusive OR of the 
-set of events that should not propagate.
-.LP
-The override_redirect member is set to indicate whether this window overrides
-structure control facilities and can be 
-.PN True
-or
-.PN False .
-Window manager clients should ignore the window if this member is
-.PN True .
-.LP
-The screen member is set to a screen pointer that gives you a back pointer 
-to the correct screen.
-This makes it easier to obtain the screen information without
-having to loop over the root window fields to see which field matches.
-.LP
-.PN XGetWindowAttributes
-can generate
-.PN BadDrawable
-and
-.PN BadWindow
-errors.
-.LP
-.sp
-To obtain the current geometry of a given drawable, use 
-.PN XGetGeometry .
-.IN "XGetGeometry" "" "@DEF@"
-.sM
-.FD 0
-Status XGetGeometry\^(\^\fIdisplay\fP, \fId\fP\^, \^\fIroot_return\fP\^, \fIx_return\fP\^, \fIy_return\fP\^, \fIwidth_return\fP\^, 
-.br
-                      \fIheight_return\fP\^, \fIborder_width_return\fP\^, \fIdepth_return\fP\^)
-.br
-        Display *\fIdisplay\fP\^;
-.br
-        Drawable \fId\fP\^;
-.br
-        Window *\fIroot_return\fP\^;
-.br
-        int *\fIx_return\fP\^, *\fIy_return\fP\^;
-.br
-        unsigned int *\fIwidth_return\fP\^, *\fIheight_return\fP\^;
-.br
-        unsigned int *\fIborder_width_return\fP\^;
-.br
-        unsigned int *\fIdepth_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Dr , which can be a window or a pixmap
-.IP \fId\fP 1i
-Specifies the drawable\*(Dr. 
-.IP \fIroot_return\fP 1i
-Returns the root window.
-.IP \fIx_return\fP 1i
-.br
-.ns
-.IP \fIy_return\fP 1i
-Return the x and y coordinates that define the location of the drawable.
-For a window, 
-these coordinates specify the upper-left outer corner relative to
-its parent's origin.
-For pixmaps, these coordinates are always zero.
-.IP \fIwidth_return\fP 1i
-.br
-.ns
-.IP \fIheight_return\fP 1i
-Return the drawable's dimensions (width and height).
-For a window, 
-these dimensions specify the inside size, not including the border.
-.IP \fIborder_width_return\fP 1i
-Returns the border width in pixels. 
-If the drawable is a pixmap, it returns zero.
-.IP \fIdepth_return\fP 1i
-Returns the depth of the drawable (bits per pixel for the object).
-.LP
-.eM
-The
-.PN XGetGeometry
-function returns the root window and the current geometry of the drawable.
-The geometry of the drawable includes the x and y coordinates, width and height,
-border width, and depth.
-These are described in the argument list.
-It is legal to pass to this function a window whose class is
-.PN InputOnly .
-.LP
-.PN XGetGeometry
-can generate a
-.PN BadDrawable
-error.
-.NH 2
-Translating Screen Coordinates
-.XS
-\*(SN Translating Screen Coordinates 
-.XE
-.LP
-Applications sometimes
-need to perform a coordinate transformation from the coordinate
-space of one window to another window or need to determine which
-window the pointing device is in.
-.PN XTranslateCoordinates
-and
-.PN XQueryPointer
-fulfill these needs (and avoid any race conditions) by
-asking the X server to perform these operations.
-.LP
-.sp
-To translate a coordinate in one window to the coordinate
-space of another window, use
-.PN XTranslateCoordinates .
-.IN "XTranslateCoordinates" "" "@DEF@"
-.sM
-.FD 0
-Bool XTranslateCoordinates\^(\^\fIdisplay\fP, \fIsrc_w\fP\^, \fIdest_w\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIdest_x_return\fP\^, 
-.br
-                            \fIdest_y_return\fP\^, \fIchild_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIsrc_w\fP\^, \fIdest_w\fP\^;
-.br
-      int \fIsrc_x\fP\^, \fIsrc_y\fP\^;
-.br
-      int *\fIdest_x_return\fP\^, *\fIdest_y_return\fP\^;
-.br
-      Window *\fIchild_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIsrc_w\fP 1i
-Specifies the source window.
-.IP \fIdest_w\fP 1i
-Specifies the destination window.
-.IP \fIsrc_x\fP 1i
-.br
-.ns
-.IP \fIsrc_y\fP 1i
-Specify the x and y coordinates within the source window.
-.IP \fIdest_x_return\fP 1i
-.br
-.ns
-.IP \fIdest_y_return\fP 1i
-Return the x and y coordinates within the destination window.
-.IP \fIchild_return\fP 1i
-Returns the child if the coordinates are contained in a mapped child of the
-destination window.
-.LP
-.eM
-If
-.PN XTranslateCoordinates
-returns
-.PN True ,
-it takes the src_x and src_y coordinates relative
-to the source window's origin and returns these coordinates to 
-dest_x_return and dest_y_return
-relative to the destination window's origin.
-If
-.PN XTranslateCoordinates
-returns 
-.PN False , 
-src_w and dest_w are on different screens,
-and dest_x_return and dest_y_return are zero.
-If the coordinates are contained in a mapped child of dest_w,
-that child is returned to child_return.
-Otherwise, child_return is set to
-.PN None .
-.LP
-.PN XTranslateCoordinates
-can generate a
-.PN BadWindow 
-error.
-.LP
-.sp
-To obtain the screen coordinates of the pointer
-or to determine the pointer coordinates relative to a specified window, use 
-.PN XQueryPointer .
-.IN "XQueryPointer" "" "@DEF@"
-.sM
-.FD 0
-Bool XQueryPointer\^(\^\fIdisplay\fP, \fIw\fP\^, \fIroot_return\fP\^, \fIchild_return\fP\^, \fIroot_x_return\fP\^, \fIroot_y_return\fP\^, 
-.br
-                     \fIwin_x_return\fP\^, \fIwin_y_return\fP\^, \fImask_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      Window *\fIroot_return\fP\^, *\fIchild_return\fP\^;
-.br
-      int *\fIroot_x_return\fP\^, *\fIroot_y_return\fP\^;
-.br
-      int *\fIwin_x_return\fP\^, *\fIwin_y_return\fP\^;
-.br
-      unsigned int *\fImask_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.ds Ro that the pointer is in
-.IP \fIroot_return\fP 1i
-Returns the root window \*(Ro.
-.IP \fIchild_return\fP 1i
-Returns the child window that the pointer is located in, if any.
-.IP \fIroot_x_return\fP 1i
-.br
-.ns
-.IP \fIroot_y_return\fP 1i
-Return the pointer coordinates relative to the root window's origin.
-.IP \fIwin_x_return\fP 1i
-.br
-.ns
-.IP \fIwin_y_return\fP 1i
-Return the pointer coordinates relative to the specified window.
-.IP \fImask_return\fP 1i
-Returns the current state of the modifier keys and pointer buttons.
-.LP
-.eM
-The
-.PN XQueryPointer
-function returns the root window the pointer is logically on and the pointer
-coordinates relative to the root window's origin.
-If
-.PN XQueryPointer
-returns 
-.PN False , 
-the pointer is not on the same screen as the specified window, and
-.PN XQueryPointer
-returns 
-.PN None
-to child_return and zero to win_x_return and win_y_return.
-If 
-.PN XQueryPointer
-returns 
-.PN True , 
-the pointer coordinates returned to win_x_return and win_y_return
-are relative to the origin of the specified window.
-In this case, 
-.PN XQueryPointer
-returns the child that contains the pointer, if any,
-or else
-.PN None
-to child_return.
-.LP
-.PN XQueryPointer
-returns the current logical state of the keyboard buttons 
-and the modifier keys in mask_return.
-It sets mask_return to the bitwise inclusive OR of one or more
-of the button or modifier key bitmasks to match 
-the current state of the mouse buttons and the modifier keys.
-.LP
-Note that the logical state of a device (as seen through Xlib)
-may lag the physical state if device event processing is frozen
-(see section 12.1).
-.LP
-.PN XQueryPointer
-can generate a
-.PN BadWindow 
-error.
-.NH 2
-Properties and Atoms
-.XS
-\*(SN Properties and Atoms 
-.XE
-.LP
-A property is a collection of named, typed data.
-The window system has a set of predefined properties
-.IN "Atom" "predefined"
-(for example, the name of a window, size hints, and so on), and users can
-define any other arbitrary information and associate it with windows.
-Each property has a name,
-which is an ISO Latin-1 string.
-For each named property,
-a unique identifier (atom) is associated with it. 
-A property also has a type, for example, string or integer.
-These types are also indicated using atoms, so arbitrary new
-types can be defined.
-Data of only one type may be associated with a single
-property name.
-Clients can store and retrieve properties associated with windows.
-For efficiency reasons,
-an atom is used rather than a character string.
-.PN XInternAtom
-can be used to obtain the atom for property names.
-.IN "Atom" 
-.LP
-A property is also stored in one of several possible formats.
-The X server can store the information as 8-bit quantities, 16-bit
-quantities, or 32-bit quantities.
-This permits the X server to present the data in the byte order that the
-client expects.
-.NT Note
-If you define further properties of complex type, 
-you must encode and decode them yourself.
-These functions must be carefully written if they are to be portable.
-For further information about how to write a library extension,
-see appendix C.
-.NE
-The type of a property is defined by an atom, which allows for
-arbitrary extension in this type scheme.
-.IN "Atom" 
-.LP
-Certain property names are
-predefined in the server for commonly used functions.
-The atoms for these properties are defined in 
-.hN X11/Xatom.h .
-To avoid name clashes with user symbols, the 
-.PN #define 
-name for each atom has the XA_ prefix.
-For an explanation of the functions that let you get and set
-much of the information stored in these predefined properties,
-see chapter 14.
-.LP
-The core protocol imposes no semantics on these property names,
-but semantics are specified in other X Consortium standards,
-such as the \fIInter-Client Communication Conventions Manual\fP
-and the \fIX Logical Font Description Conventions\fP.
-.LP
-You can use properties to communicate other information between
-applications.
-The functions described in this section let you define new properties 
-and get the unique atom IDs in your applications.
-.LP
-Although any particular atom can have some client interpretation 
-within each of the name spaces, 
-atoms occur in five distinct name spaces within the protocol: 
-.IP \(bu 5
-Selections
-.IP \(bu 5
-Property names
-.IP \(bu 5
-Property types
-.IP \(bu 5
-Font properties 
-.IP \(bu 5
-Type of a 
-.PN ClientMessage 
-event (none are built into the X server)
-.LP
-.LP
-The built-in selection property names are:
-.LP
-.Ds 0
-.TA .5i 1.5i 3i
-.ta .5i 1.5i 3i
-.R
-PRIMARY
-SECONDARY
-.De
-.LP
-The built-in property names are: 
-.TS
-lw(2i) lw(2i).
-.sp 6p
-CUT_BUFFER0	RESOURCE_MANAGER
-CUT_BUFFER1	WM_CLASS
-CUT_BUFFER2	WM_CLIENT_MACHINE
-CUT_BUFFER3	WM_COLORMAP_WINDOWS
-CUT_BUFFER4	WM_COMMAND
-CUT_BUFFER5	WM_HINTS
-CUT_BUFFER6	WM_ICON_NAME
-CUT_BUFFER7	WM_ICON_SIZE
-RGB_BEST_MAP	WM_NAME
-RGB_BLUE_MAP	WM_NORMAL_HINTS
-RGB_DEFAULT_MAP	WM_PROTOCOLS
-RGB_GRAY_MAP	WM_STATE
-RGB_GREEN_MAP	WM_TRANSIENT_FOR
-RGB_RED_MAP	WM_ZOOM_HINTS
-.sp 6p
-.TE
-.LP
-The built-in property types are: 
-.LP
-.TS
-lw(2i) lw(2i).
-.sp 6p
-ARC	POINT
-ATOM	RGB_COLOR_MAP
-BITMAP	RECTANGLE
-CARDINAL	STRING
-COLORMAP	VISUALID
-CURSOR	WINDOW
-DRAWABLE	WM_HINTS
-FONT	WM_SIZE_HINTS
-INTEGER	
-PIXMAP
-.sp 6p
-.TE
-.LP
-The built-in font property names are: 
-.TS
-lw(2i) lw(2i).
-.sp 6p
-MIN_SPACE	STRIKEOUT_DESCENT
-NORM_SPACE	STRIKEOUT_ASCENT
-MAX_SPACE	ITALIC_ANGLE
-END_SPACE	X_HEIGHT
-SUPERSCRIPT_X	QUAD_WIDTH
-SUPERSCRIPT_Y	WEIGHT
-SUBSCRIPT_X	POINT_SIZE
-SUBSCRIPT_Y	RESOLUTION
-UNDERLINE_POSITION	COPYRIGHT
-UNDERLINE_THICKNESS	NOTICE
-FONT_NAME	FAMILY_NAME
-FULL_NAME	CAP_HEIGHT
-.sp 6p
-.TE
-.LP
-For further information about font properties,
-see section 8.5.
-.LP
-.sp
-To return an atom for a given name, use 
-.PN XInternAtom .
-.IN "Atom" "interning"
-.IN "XInternAtom" "" "@DEF@"
-.sM
-.FD 0
-Atom XInternAtom\^(\^\fIdisplay\fP, \fIatom_name\fP\^, \fIonly_if_exists\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      char *\fIatom_name\fP\^;
-.br
-      Bool \fIonly_if_exists\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIatom_name\fP 1i
-Specifies the name associated with the atom you want returned.
-.IP \fIonly_if_exists\fP 1i
-Specifies a Boolean value that indicates whether the atom must be created.
-.LP
-.eM
-The
-.PN XInternAtom
-function returns the atom identifier associated with the specified atom_name
-string.
-If only_if_exists is 
-.PN False ,
-the atom is created if it does not exist.
-Therefore,
-.PN XInternAtom
-can return
-.PN None .
-If the atom name is not in the Host Portable Character Encoding, 
-the result is implementation-dependent.
-Uppercase and lowercase matter;
-the strings ``thing'', ``Thing'', and ``thinG'' 
-all designate different atoms.  
-The atom will remain defined even after the client's connection closes.
-It will become undefined only when the last connection to
-the X server closes.
-.LP
-.PN XInternAtom
-can generate
-.PN BadAlloc
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-To return atoms for an array of names, use 
-.PN XInternAtoms .
-.IN "Atom" "interning"
-.IN "XInternAtoms" "" "@DEF@"
-.sM
-.FD 0
-Status XInternAtoms\^(\^\fIdisplay\fP, \fInames\fP\^, \fIcount\fP\^, \fIonly_if_exists\fP, \fIatoms_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      char **\fInames\fP\^;
-.br
-      int \fIcount\fP\^;
-.br
-      Bool \fIonly_if_exists\fP\^;
-.br
-      Atom *\fIatoms_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fInames\fP 1i
-Specifies the array of atom names.
-.ds Cn atom names in the array
-.IP \fIcount\fP 1i
-Specifies the number of \*(Cn.
-.IP \fIonly_if_exists\fP 1i
-Specifies a Boolean value that indicates whether the atom must be created.
-.IP \fIatoms_return\fP 1i
-Returns the atoms.
-.LP
-.eM
-The
-.PN XInternAtoms
-function returns the atom identifiers associated with the specified names.
-The atoms are stored in the atoms_return array supplied by the caller.
-Calling this function is equivalent to calling
-.PN XInternAtom
-for each of the names in turn with the specified value of only_if_exists,
-but this function minimizes the number of round-trip protocol exchanges
-between the client and the X server.
-.LP
-This function returns a nonzero status if atoms are returned for
-all of the names;
-otherwise, it returns zero.
-.LP
-.PN XInternAtoms
-can generate
-.PN BadAlloc
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-To return a name for a given atom identifier, use 
-.PN XGetAtomName .
-.IN "Atom" "getting name"
-.IN "XGetAtomName" "" "@DEF@"
-.sM
-.FD 0
-char *XGetAtomName\^(\^\fIdisplay\fP, \fIatom\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Atom \fIatom\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIatom\fP 1i
-Specifies the atom for the property name you want returned.
-.LP
-.eM
-The
-.PN XGetAtomName
-function returns the name associated with the specified atom.
-If the data returned by the server is in the Latin Portable Character Encoding,
-then the returned string is in the Host Portable Character Encoding.
-Otherwise, the result is implementation-dependent.
-To free the resulting string,
-call
-.PN XFree .
-.LP
-.PN XGetAtomName
-can generate a
-.PN BadAtom 
-error.
-.LP
-.sp
-To return the names for an array of atom identifiers, use 
-.PN XGetAtomNames .
-.IN "Atom" "getting name"
-.IN "XGetAtomNames" "" "@DEF@"
-.sM
-.FD 0
-Status XGetAtomNames\^(\^\fIdisplay\fP, \fIatoms\fP, \fIcount\fP\^, \fInames_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Atom *\fIatoms\fP\^;
-.br
-      int \fIcount\fP\^;
-.br
-      char **\fInames_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIatoms\fP 1i
-Specifies the array of atoms.
-.ds Cn atoms in the array
-.IP \fIcount\fP 1i
-Specifies the number of \*(Cn.
-.IP \fInames_return\fP 1i
-Returns the atom names.
-.LP
-.eM
-The
-.PN XGetAtomNames
-function returns the names associated with the specified atoms.
-The names are stored in the names_return array supplied by the caller.
-Calling this function is equivalent to calling
-.PN XGetAtomName
-for each of the atoms in turn,
-but this function minimizes the number of round-trip protocol exchanges
-between the client and the X server.
-.LP
-This function returns a nonzero status if names are returned for
-all of the atoms;
-otherwise, it returns zero.
-.LP
-.PN XGetAtomNames
-can generate a
-.PN BadAtom 
-error.
-.NH 2
-Obtaining and Changing Window Properties
-.XS
-\*(SN Obtaining and Changing Window Properties 
-.XE
-.LP
-You can attach a property list to every window.
-Each property has a name, a type, and a value (see section 4.3).
-The value is an array of 8-bit, 16-bit, or 32-bit quantities,
-whose interpretation is left to the clients.  The type
-.PN char
-is used to represent 8-bit quantities, the type
-.PN short
-is used to represent 16-bit quantities, and the type
-.PN long
-is used to represent 32-bit quantities.
-.LP
-Xlib provides functions that you can use to obtain, 
-change, update, or interchange window properties.
-In addition, Xlib provides other utility functions for inter-client
-communication (see chapter 14).
-.LP
-.sp
-To obtain the type, format, and value of a property of a given window, use 
-.PN XGetWindowProperty .
-.IN "Property" "getting"
-.LP
-.IN "XGetWindowProperty" "" "@DEF@"
-.sM
-.FD 0
-int XGetWindowProperty\^(\^\fIdisplay\fP, \fIw\fP\^, \fIproperty\fP\^, \fIlong_offset\fP\^, \fIlong_length\fP\^, \fIdelete\fP\^, \fIreq_type\fP\^, 
-.br
-                        \fIactual_type_return\fP\^, \fIactual_format_return\fP\^, \fInitems_return\fP\^, \fIbytes_after_return\fP\^, 
-.br
-                        \fIprop_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      Atom \fIproperty\fP\^;
-.br
-      long \fIlong_offset\fP\^, \fIlong_length\fP\^;
-.br
-      Bool \fIdelete\fP\^;
-.br
-      Atom \fIreq_type\fP\^; 
-.br
-      Atom *\fIactual_type_return\fP\^;
-.br
-      int *\fIactual_format_return\fP\^;
-.br
-      unsigned long *\fInitems_return\fP\^;
-.br
-      unsigned long *\fIbytes_after_return\fP\^;
-.br
-      unsigned char **\fIprop_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Wi whose property you want to obtain
-.IP \fIw\fP 1i
-Specifies the window \*(Wi.
-.IP \fIproperty\fP 1i
-Specifies the property name.
-.IP \fIlong_offset\fP 1i
-Specifies the offset in the specified property (in 32-bit quantities) 
-where the data is to be retrieved.
-.IP \fIlong_length\fP 1i
-Specifies the length in 32-bit multiples of the data to be retrieved.
-.IP \fIdelete\fP 1i
-Specifies a Boolean value that determines whether the property is deleted.
-.IP \fIreq_type\fP 1i
-Specifies the atom identifier associated with the property type or
-.PN AnyPropertyType .
-.IP \fIactual_type_return\fP 1i
-Returns the atom identifier  that defines the actual type of the property.
-.IP \fIactual_format_return\fP 1i
-Returns the actual format of the property.
-.IP \fInitems_return\fP 1i
-Returns the actual number of 8-bit, 16-bit, or 32-bit items 
-stored in the prop_return data.
-.IP \fIbytes_after_return\fP 1i
-Returns the number of bytes remaining to be read in the property if 
-a partial read was performed.
-.IP \fIprop_return\fP 1i
-Returns the data in the specified format.
-.LP
-.eM
-The
-.PN XGetWindowProperty
-function returns the actual type of the property; the actual format of the property;
-the number of 8-bit, 16-bit, or 32-bit items transferred; the number of bytes remaining
-to be read in the property; and a pointer to the data actually returned.
-.PN XGetWindowProperty
-sets the return arguments as follows:
-.IP \(bu 5
-If the specified property does not exist for the specified window,
-.PN XGetWindowProperty 
-returns 
-.PN None
-to actual_type_return and the value zero to 
-actual_format_return and bytes_after_return.
-The nitems_return argument is empty.
-In this case, the delete argument is ignored.
-.IP \(bu 5
-If the specified property exists 
-but its type does not match the specified type,
-.PN XGetWindowProperty 
-returns the actual property type to actual_type_return, 
-the actual property format (never zero) to actual_format_return, 
-and the property length in bytes
-(even if the actual_format_return is 16 or 32) 
-to bytes_after_return.
-It also ignores the delete argument.
-The nitems_return argument is empty.
-.IP \(bu 5
-If the specified property exists and either you assign 
-.PN AnyPropertyType 
-to the req_type argument or the specified type matches the actual property type,
-.PN XGetWindowProperty 
-returns the actual property type to actual_type_return and the actual
-property format (never zero) to actual_format_return. 
-It also returns a value to bytes_after_return and nitems_return, by 
-defining the following
-values:
-.IP
-.nf
-	N = actual length of the stored property in bytes
-	     (even if the format is 16 or 32)
-	I = 4 * long_offset
-	T = N - I
-	L = MINIMUM(T, 4 * long_length)
-	A = N - (I + L)
-.fi
-.IP
-The returned value starts at byte index I in the property (indexing
-from zero), and its length in bytes is L.
-If the value for long_offset causes L to be negative,
-a
-.PN BadValue
-error results. 
-The value of bytes_after_return is A, 
-giving the number of trailing unread bytes in the stored property.
-.LP
-If the returned format is 8, the returned data is represented as a
-.PN char
-array.
-If the returned format is 16, the returned data is represented as a
-.PN short
-array and should be cast to that type to obtain the elements.
-If the returned format is 32, the returned data is represented as a
-.PN long
-array and should be cast to that type to obtain the elements.
-.LP
-.PN XGetWindowProperty
-always allocates one extra byte in prop_return 
-(even if the property is zero length) 
-and sets it to zero so that simple properties consisting of characters
-do not have to be copied into yet another string before use.
-.LP
-If delete is 
-.PN True 
-and bytes_after_return is zero, 
-.PN XGetWindowProperty
-deletes the property 
-from the window and generates a 
-.PN PropertyNotify 
-event on the window.
-.LP
-The function returns
-.PN Success
-if it executes successfully.
-To free the resulting data,
-use
-.PN XFree .
-.LP
-.PN XGetWindowProperty
-can generate
-.PN BadAtom ,
-.PN BadValue ,
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To obtain a given window's property list, use 
-.PN XListProperties .
-.IN "Property" "listing"
-.IN "XListProperties" "" "@DEF@"
-.sM
-.FD 0
-Atom *XListProperties\^(\^\fIdisplay\fP, \fIw\fP\^, \fInum_prop_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      int *\fInum_prop_return\fP\^; 
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Wi whose property list you want to obtain
-.IP \fIw\fP 1i
-Specifies the window \*(Wi.
-.IP \fInum_prop_return\fP 1i
-Returns the length of the properties array.
-.LP
-.eM
-The
-.PN XListProperties
-function returns a pointer to an array of atom properties that are defined for 
-the specified window or returns NULL if no properties were found.
-To free the memory allocated by this function, use
-.PN XFree .
-.LP
-.PN XListProperties
-can generate a
-.PN BadWindow 
-error.
-.LP
-.sp
-To change a property of a given window, use
-.PN XChangeProperty .
-.IN "Property" "changing"
-.IN "Property" "appending"
-.IN "Property" "prepending"
-.IN "Property" "replacing"
-.IN "Property" "format"
-.IN "Property" "type"
-.IN "XChangeProperty" "" "@DEF@"
-.sM
-.FD 0
-XChangeProperty\^(\^\fIdisplay\fP, \fIw\fP\^, \fIproperty\fP\^, \fItype\fP\^, \fIformat\fP\^, \fImode\fP\^, \fIdata\fP\^, \fInelements\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      Atom \fIproperty\fP\^, \fItype\fP\^;
-.br
-      int \fIformat\fP\^;
-.br
-      int \fImode\fP\^;
-.br
-      unsigned char *\fIdata\fP\^;
-.br
-      int \fInelements\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Wi whose property you want to change
-.IP \fIw\fP 1i
-Specifies the window \*(Wi.
-.IP \fIproperty\fP 1i
-Specifies the property name.
-.IP \fItype\fP 1i
-Specifies the type of the property.
-The X server does not interpret the type but simply
-passes it back to an application that later calls 
-.PN XGetWindowProperty .
-.IP \fIformat\fP 1i
-Specifies whether the data should be viewed as a list
-of 8-bit, 16-bit, or 32-bit quantities.
-Possible values are 8, 16, and 32.
-This information allows the X server to correctly perform
-byte-swap operations as necessary.
-If the format is 16-bit or 32-bit,
-you must explicitly cast your data pointer to an (unsigned char *) in the call
-to 
-.PN XChangeProperty .
-.\" Changed name of this file to prop_mode.a on 1/13/87
-.IP \fImode\fP 1i
-Specifies the mode of the operation.
-You can pass
-.PN PropModeReplace ,
-.PN PropModePrepend ,
-or
-.PN PropModeAppend .
-.IP \fIdata\fP 1i
-Specifies the property data.
-.IP \fInelements\fP 1i
-Specifies the number of elements of the specified data format.
-.LP
-.eM
-The
-.PN XChangeProperty
-function alters the property for the specified window and
-causes the X server to generate a
-.PN PropertyNotify
-event on that window.
-.PN XChangeProperty
-performs the following:
-.IP \(bu 5
-If mode is
-.PN PropModeReplace ,
-.PN XChangeProperty
-discards the previous property value and stores the new data.
-.IP \(bu 5
-If mode is
-.PN PropModePrepend
-or
-.PN PropModeAppend ,
-.PN XChangeProperty
-inserts the specified data before the beginning of the existing data
-or onto the end of the existing data, respectively.
-The type and format must match the existing property value,
-or a
-.PN BadMatch
-error results.
-If the property is undefined, 
-it is treated as defined with the correct type and
-format with zero-length data.
-.LP
-If the specified format is 8, the property data must be a
-.PN char
-array.
-If the specified format is 16, the property data must be a
-.PN short
-array.
-If the specified format is 32, the property data must be a
-.PN long
-array.
-.LP
-The lifetime of a property is not tied to the storing client.
-Properties remain until explicitly deleted, until the window is destroyed,
-or until the server resets.
-For a discussion of what happens when the connection to the X server is closed,
-see section 2.6. 
-The maximum size of a property is server dependent and can vary dynamically
-depending on the amount of memory the server has available.
-(If there is insufficient space, a
-.PN BadAlloc
-error results.)
-.LP
-.PN XChangeProperty
-can generate
-.PN BadAlloc ,
-.PN BadAtom ,
-.PN BadMatch ,
-.PN BadValue ,
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To rotate a window's property list, use
-.PN XRotateWindowProperties .
-.LP
-.IN "XRotateWindowProperties" "" "@DEF@"
-.sM
-.FD 0
-XRotateWindowProperties\^(\^\fIdisplay\fP, \fIw\fP, \fIproperties\fP, \fInum_prop\fP, \fInpositions\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      Atom \fIproperties\fP\^[]\^;
-.br
-      int \fInum_prop\fP\^;
-.br
-      int \fInpositions\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIproperties\fP 1i
-Specifies the array of properties that are to be rotated.
-.IP \fInum_prop\fP 1i
-Specifies the length of the properties array.
-.IP \fInpositions\fP 1i
-Specifies the rotation amount.
-.LP
-.eM
-The
-.PN XRotateWindowProperties
-function allows you to rotate properties on a window and causes
-the X server to generate
-.PN PropertyNotify
-events.
-If the property names in the properties array are viewed as being numbered 
-starting from zero and if there are num_prop property names in the list,
-then the value associated with property name I becomes the value associated 
-with property name (I + npositions) mod N for all I from zero to N \- 1.
-The effect is to rotate the states by npositions places around the virtual ring
-of property names (right for positive npositions, 
-left for negative npositions).
-If npositions mod N is nonzero,
-the X server generates a
-.PN PropertyNotify
-event for each property in the order that they are listed in the array.
-If an atom occurs more than once in the list or no property with that 
-name is defined for the window,
-a 
-.PN BadMatch 
-error results.
-If a 
-.PN BadAtom 
-or 
-.PN BadMatch 
-error results,
-no properties are changed.
-.LP
-.PN XRotateWindowProperties
-can generate
-.PN BadAtom ,
-.PN BadMatch ,
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To delete a property on a given window, use 
-.PN XDeleteProperty .
-.IN "Property" "deleting"
-.IN "XDeleteProperty" "" "@DEF@"
-.sM
-.FD 0
-XDeleteProperty\^(\^\fIdisplay\fP, \fIw\fP\^, \fIproperty\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      Atom \fIproperty\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Wi whose property you want to delete
-.IP \fIw\fP 1i
-Specifies the window \*(Wi.
-.IP \fIproperty\fP 1i
-Specifies the property name.
-.LP
-.eM
-The
-.PN XDeleteProperty
-function deletes the specified property only if the
-property was defined on the specified window
-and causes the X server to generate a
-.PN PropertyNotify
-event on the window unless the property does not exist.
-.LP
-.PN XDeleteProperty
-can generate
-.PN BadAtom
-and
-.PN BadWindow 
-errors.
-.NH 2
-Selections
-.XS
-\*(SN Selections
-.XE
-.LP
-.IN "Selection"
-Selections are one method used by applications to exchange data.
-By using the property mechanism,
-applications can exchange data of arbitrary types and can negotiate
-the type of the data.
-A selection can be thought of as an indirect property with a dynamic type.
-That is, rather than having the property stored in the X server,
-the property is maintained by some client (the owner).
-A selection is global in nature (considered to belong to the user 
-but be maintained by clients) rather than being private to a particular 
-window subhierarchy or a particular set of clients.
-.LP
-Xlib provides functions that you can use to set, get, or request conversion
-of selections.
-This allows applications to implement the notion of current selection,
-which requires that notification be sent to applications when they no 
-longer own the selection.
-Applications that support selection often highlight the current selection
-and so must be informed when another application has
-acquired the selection so that they can unhighlight the selection.
-.LP
-When a client asks for the contents of
-a selection, it specifies a selection target type.
-This target type
-can be used to control the transmitted representation of the contents.
-For example, if the selection is ``the last thing the user clicked on''
-and that is currently an image, then the target type might specify
-whether the contents of the image should be sent in XY format or Z format.
-.LP
-The target type can also be used to control the class of
-contents transmitted, for example, 
-asking for the ``looks'' (fonts, line
-spacing, indentation, and so forth) of a paragraph selection, not the
-text of the paragraph.
-The target type can also be used for other
-purposes.
-The protocol does not constrain the semantics.
-.LP
-.sp
-To set the selection owner, use 
-.PN XSetSelectionOwner .
-.IN "Selection" "setting the owner"
-.IN "XSetSelectionOwner" "" "@DEF@"
-.sM
-.FD 0
-XSetSelectionOwner\^(\^\fIdisplay\fP, \fIselection\fP\^, \fIowner\fP\^, \fItime\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Atom \fIselection\fP\^;
-.br
-      Window \fIowner\fP\^; 
-.br
-      Time \fItime\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIselection\fP 1i
-Specifies the selection atom.
-.IP \fIowner\fP 1i
-Specifies the owner of the specified selection atom.
-You can pass a window or
-.PN None .
-.IP \fItime\fP 1i
-Specifies the time.
-You can pass either a timestamp or
-.PN CurrentTime .
-.LP
-.eM
-The
-.PN XSetSelectionOwner
-function changes the owner and last-change time for the specified selection
-and has no effect if the specified time is earlier than the current
-last-change time of the specified selection 
-or is later than the current X server time.
-Otherwise, the last-change time is set to the specified time,
-with
-.PN CurrentTime
-replaced by the current server time.
-If the owner window is specified as
-.PN None ,
-then the owner of the selection becomes 
-.PN None
-(that is, no owner).
-Otherwise, the owner of the selection becomes the client executing
-the request.
-.LP 
-If the new owner (whether a client or
-.PN None )
-is not
-the same as the current owner of the selection and the current
-owner is not
-.PN None ,
-the current owner is sent a 
-.PN SelectionClear 
-event.
-If the client that is the owner of a selection is later
-terminated (that is, its connection is closed)
-or if the owner window it has specified in the request is later
-destroyed,
-the owner of the selection automatically
-reverts to
-.PN None ,
-but the last-change time is not affected.
-The selection atom is uninterpreted by the X server.
-.PN XGetSelectionOwner
-returns the owner window, which is reported in 
-.PN SelectionRequest
-and
-.PN SelectionClear
-events.
-Selections are global to the X server.
-.LP
-.PN XSetSelectionOwner
-can generate
-.PN BadAtom
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To return the selection owner, use 
-.PN XGetSelectionOwner .
-.IN "Selection" "getting the owner"
-.IN "XGetSelectionOwner" "" "@DEF@"
-.sM
-.FD 0
-Window XGetSelectionOwner\^(\^\fIdisplay\fP, \fIselection\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Atom \fIselection\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Se whose owner you want returned
-.IP \fIselection\fP 1i
-Specifies the selection atom \*(Se.
-.LP
-.eM
-The
-.PN XGetSelectionOwner
-function
-returns the window ID associated with the window that currently owns the
-specified selection.
-If no selection was specified, the function returns the constant
-.PN None .
-If
-.PN None
-is returned,
-there is no owner for the selection.
-.LP
-.PN XGetSelectionOwner
-can generate a
-.PN BadAtom 
-error.
-.LP
-.sp
-To request conversion of a selection, use 
-.PN XConvertSelection .
-.IN "Selection" "converting"
-.IN "XConvertSelection" "" "@DEF@"
-.sM
-.FD 0
-XConvertSelection\^(\^\fIdisplay\fP, \fIselection\fP\^, \fItarget\fP\^, \fIproperty\fP\^, \fIrequestor\fP\^, \fItime\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Atom \fIselection\fP\^, \fItarget\fP\^;
-.br
-      Atom \fIproperty\fP\^;
-.br
-      Window \fIrequestor\fP\^;
-.br
-      Time \fItime\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIselection\fP 1i
-Specifies the selection atom.
-.IP \fItarget\fP 1i
-Specifies the target atom.
-.IP \fIproperty\fP 1i
-Specifies the property name.
-You also can pass 
-.PN None .
-.IP \fIrequestor\fP 1i
-Specifies the requestor.
-.IP \fItime\fP 1i
-Specifies the time.
-You can pass either a timestamp or
-.PN CurrentTime .
-.LP
-.eM
-.PN XConvertSelection
-requests that the specified selection be converted to the specified target
-type:
-.IP \(bu 5
-If the specified selection has an owner, the X server sends a
-.PN SelectionRequest
-event to that owner.
-.IP \(bu 5
-If no owner for the specified
-selection exists, the X server generates a
-.PN SelectionNotify
-event to the
-requestor with property
-.PN None .
-.LP
-The arguments are passed on unchanged in either of the events.
-There are two predefined selection atoms: PRIMARY and SECONDARY.
-.LP
-.PN XConvertSelection
-can generate
-.PN BadAtom
-and
-.PN BadWindow 
-errors.
-.bp
diff --git a/libX11/specs/libX11/CH04.xml b/libX11/specs/libX11/CH04.xml
new file mode 100644
index 000000000..ed8bd2427
--- /dev/null
+++ b/libX11/specs/libX11/CH04.xml
@@ -0,0 +1,2647 @@
+<chapter id="window_information_functions">

+<title>Window Information Functions</title>

+

+<para>

+After you connect the display to the X server and create a window, you can use the Xlib window

+information functions to:

+</para>

+<itemizedlist>

+  <listitem><para>Obtain information about a window</para></listitem>

+  <listitem><para>Translate screen coordinates</para></listitem>

+  <listitem><para>Manipulate property lists</para></listitem>

+  <listitem><para>Obtain and change window properties</para></listitem>

+  <listitem><para>Manipulate selections</para></listitem>

+</itemizedlist>

+

+<sect1 id="Obtaining_Window_Information">

+<title>Obtaining Window Information</title>

+<!-- .XS -->

+<!-- (SN Obtaining Window Information  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to obtain information about 

+the window tree, the window's current attributes, 

+the window's current geometry, or the current pointer coordinates.

+Because they are most frequently used by window managers,

+these functions all return a status to indicate whether the window still

+exists.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the parent, a list of children, and number of children for 

+a given window, use 

+<function>XQueryTree</function>.

+<indexterm><primary>Child Window</primary></indexterm>

+<indexterm><primary>Parent Window</primary></indexterm>

+<indexterm significance="preferred"><primary>XQueryTree</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XQueryTree</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>Window<parameter> *root_return</parameter></paramdef>

+  <paramdef>Window<parameter> *parent_return</parameter></paramdef>

+  <paramdef>Window<parameter> **children_return</parameter></paramdef>

+  <paramdef>unsignedint<parameter> *nchildren_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Wi whose list of children, root, parent, and number of children \ -->

+you want to obtain

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window (Wi.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>root_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the root window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>parent_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the parent window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>children_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the list of children.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nchildren_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of children.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XQueryTree</function>

+function returns the root ID, the parent window ID, 

+a pointer to the list of children windows

+(NULL when there are no children), 

+and the number of children in the list for the specified window.

+The children are listed in current stacking order, from bottom-most 

+(first) to top-most (last).

+<function>XQueryTree</function>

+returns zero if it fails and nonzero if it succeeds.

+To free a non-NULL children list when it is no longer needed, use 

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XQueryTree</function>

+can generate a

+<function>BadWindow</function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the current attributes of a given window, use 

+<function>XGetWindowAttributes</function>.

+<indexterm significance="preferred"><primary>XGetWindowAttributes</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XGetWindowAttributes</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XWindowAttributes<parameter> *window_attributes_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Wi whose current attributes you want to obtain -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window (Wi.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>window_attributes_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the specified window's attributes in the

+<function>XWindowAttributes</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetWindowAttributes</function>

+function returns the current attributes for the specified window to an

+<function>XWindowAttributes</function>

+structure.

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XWindowAttributes</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int x, y;                     /* location of window */

+     int width, height;            /* width and height of window */

+     int border_width;             /* border width of window */

+     int depth;                    /* depth of window */

+     Visual *visual;               /* the associated visual structure */

+     Window root;                  /* root of screen containing window */

+     int class;                    /* InputOutput, InputOnly*/

+     int bit_gravity;              /* one of the bit gravity values */

+     int win_gravity;              /* one of the window gravity values */

+     int backing_store;            /* NotUseful, WhenMapped, Always */

+     unsigned long backing_planes; /* planes to be preserved if possible */

+     unsigned long backing_pixel;  /* value to be used when restoring planes */

+     Bool save_under;              /* boolean, should bits under be saved? */

+     Colormap colormap;            /* color map to be associated with window */

+     Bool map_installed;           /* boolean, is color map currently installed*/

+     int map_state;                /* IsUnmapped, IsUnviewable, IsViewable */

+     long all_event_masks;         /* set of events all people have interest in*/

+     long your_event_mask;         /* my event mask */

+     long do_not_propagate_mask;   /* set of events that should not propagate */

+     Bool override_redirect;       /* boolean value for override-redirect */

+     Screen *screen;               /* back pointer to correct screen */

+} XWindowAttributes;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The x and y members are set to the upper-left outer

+corner relative to the parent window's origin.

+The width and height members are set to the inside size of the window, 

+not including the border.

+The border_width member is set to the window's border width in pixels.

+The depth member is set to the depth of the window 

+(that is, bits per pixel for the object).

+The visual member is a pointer to the screen's associated

+<function>Visual</function>

+structure.

+The root member is set to the root window of the screen containing the window.

+The class member is set to the window's class and can be either

+<function>InputOutput</function>

+or

+<function>InputOnly</function>.

+</para>

+<para>

+<!-- .LP -->

+The bit_gravity member is set to the window's bit gravity

+and can be one of the following:

+</para>

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <tbody>

+    <row>

+      <entry><function>ForgetGravity</function></entry>

+      <entry><function>EastGravity</function></entry>

+    </row>

+    <row>

+      <entry><function>NorthWestGravity</function></entry>

+      <entry><function>SouthWestGravity</function></entry>

+    </row>

+    <row>

+      <entry><function>NorthGravity</function></entry>

+      <entry><function>SouthGravity</function></entry>

+    </row>

+    <row>

+      <entry><function>NorthEastGravity</function></entry>

+      <entry><function>SouthEastGravity</function></entry>

+    </row>

+    <row>

+      <entry><function>WestGravity</function></entry>

+      <entry><function>StaticGravity</function></entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+<para>

+<!-- .LP -->

+The win_gravity member is set to the window's window gravity

+and can be one of the following:

+</para>

+

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <tbody>

+    <row>

+      <entry><function>UnmapGravity</function></entry>

+      <entry><function>EastGravity</function></entry>

+    </row>

+    <row>

+      <entry><function>NorthWestGravity</function></entry>

+      <entry><function>SouthWestGravity</function></entry>

+    </row>

+    <row>

+      <entry><function>NorthGravity</function></entry>

+      <entry><function>SouthGravity</function></entry>

+    </row>

+    <row>

+      <entry><function>NorthEastGravity</function></entry>

+      <entry><function>SouthEastGravity</function></entry>

+    </row>

+    <row>

+      <entry><function>WestGravity</function></entry>

+      <entry><function>StaticGravity</function></entry>

+    </row>

+    <row>

+      <entry><function>CenterGravity</function></entry>

+      <entry></entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+<para>

+<!-- .LP -->

+For additional information on gravity,

+see section 3.2.3. <!-- xref -->

+</para>

+<para>

+<!-- .LP -->

+The backing_store member is set to indicate how the X server should maintain

+the contents of a window 

+and can be 

+<function>WhenMapped</function>,

+<function>Always</function>,

+or

+<function>NotUseful</function>.

+The backing_planes member is set to indicate (with bits set to 1) which bit 

+planes of the window hold dynamic data that must be preserved in backing_stores 

+and during save_unders.

+The backing_pixel member is set to indicate what values to use 

+for planes not set in backing_planes.

+</para>

+<para>

+<!-- .LP -->

+The save_under member is set to 

+<function>True</function>

+or

+<function>False</function>.

+The colormap member is set to the colormap for the specified window and can be

+a colormap ID or 

+<function>None</function>.

+The map_installed member is set to indicate whether the colormap is 

+currently installed and can be 

+<function>True</function>

+or

+<function>False</function>.

+The map_state member is set to indicate the state of the window and can be

+<function>IsUnmapped</function>,

+<function>IsUnviewable</function>,

+or

+<function>IsViewable</function>.

+<function>IsUnviewable</function>

+is used if the window is mapped but some ancestor is unmapped.

+</para>

+<para>

+<!-- .LP -->

+The all_event_masks member is set to the bitwise inclusive OR of all event 

+masks selected on the window by all clients.

+The your_event_mask member is set to the bitwise inclusive OR of all event 

+masks selected by the querying client.

+The do_not_propagate_mask member is set to the bitwise inclusive OR of the 

+set of events that should not propagate.

+</para>

+<para>

+<!-- .LP -->

+The override_redirect member is set to indicate whether this window overrides

+structure control facilities and can be 

+<function>True</function>

+or

+<function>False</function>.

+Window manager clients should ignore the window if this member is

+<function>True</function>.

+</para>

+<para>

+<!-- .LP -->

+The screen member is set to a screen pointer that gives you a back pointer 

+to the correct screen.

+This makes it easier to obtain the screen information without

+having to loop over the root window fields to see which field matches.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetWindowAttributes</function>

+can generate

+<function>BadDrawable</function>

+and

+<function>BadWindow</function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the current geometry of a given drawable, use 

+<function>XGetGeometry</function>.

+<indexterm significance="preferred"><primary>XGetGeometry</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XGetGeometry</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>Window<parameter> *root_return</parameter></paramdef>

+  <paramdef>int*x_return,<parameter> *y_return</parameter></paramdef>

+  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>

+  <paramdef>unsignedint<parameter> *border_width_return</parameter></paramdef>

+  <paramdef>unsignedint<parameter> *depth_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Dr , which can be a window or a pixmap -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable(Dr. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>root_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the root window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Return the x and y coordinates that define the location of the drawable.

+For a window, 

+these coordinates specify the upper-left outer corner relative to

+its parent's origin.

+For pixmaps, these coordinates are always zero.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Return the drawable's dimensions (width and height).

+For a window, 

+these dimensions specify the inside size, not including the border.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>border_width_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the border width in pixels. 

+If the drawable is a pixmap, it returns zero.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>depth_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the depth of the drawable (bits per pixel for the object).

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetGeometry</function>

+function returns the root window and the current geometry of the drawable.

+The geometry of the drawable includes the x and y coordinates, width and height,

+border width, and depth.

+These are described in the argument list.

+It is legal to pass to this function a window whose class is

+<function>InputOnly</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetGeometry</function>

+can generate a

+<function>BadDrawable</function>

+error.

+</para>

+</sect1>

+<sect1 id="Translating_Screen_Coordinates">

+<title>Translating Screen Coordinates</title>

+<!-- .XS -->

+<!-- (SN Translating Screen Coordinates  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Applications sometimes

+need to perform a coordinate transformation from the coordinate

+space of one window to another window or need to determine which

+window the pointing device is in.

+<function>XTranslateCoordinates</function>

+and

+<function>XQueryPointer</function>

+fulfill these needs (and avoid any race conditions) by

+asking the X server to perform these operations.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To translate a coordinate in one window to the coordinate

+space of another window, use

+<function>XTranslateCoordinates</function>.

+<indexterm significance="preferred"><primary>XTranslateCoordinates</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool<function> XTranslateCoordinates</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Windowsrc_w,<parameter> dest_w</parameter></paramdef>

+  <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>

+  <paramdef>int*dest_x_return,<parameter> *dest_y_return</parameter></paramdef>

+  <paramdef>Window<parameter> *child_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>src_w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the source window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dest_w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the destination window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>src_x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>src_y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates within the source window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dest_x_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dest_y_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Return the x and y coordinates within the destination window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>child_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the child if the coordinates are contained in a mapped child of the

+destination window.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If

+<function>XTranslateCoordinates</function>

+returns

+<function>True</function>,

+it takes the src_x and src_y coordinates relative

+to the source window's origin and returns these coordinates to 

+dest_x_return and dest_y_return

+relative to the destination window's origin.

+If

+<function>XTranslateCoordinates</function>

+returns 

+<function>False</function>,

+src_w and dest_w are on different screens,

+and dest_x_return and dest_y_return are zero.

+If the coordinates are contained in a mapped child of dest_w,

+that child is returned to child_return.

+Otherwise, child_return is set to

+<function>None</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XTranslateCoordinates</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the screen coordinates of the pointer

+or to determine the pointer coordinates relative to a specified window, use 

+<function>XQueryPointer</function>.

+<indexterm significance="preferred"><primary>XQueryPointer</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool<function> XQueryPointer</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>Window*root_return,<parameter> *child_return</parameter></paramdef>

+  <paramdef>int*root_x_return,<parameter> *root_y_return</parameter></paramdef>

+  <paramdef>int*win_x_return,<parameter> *win_y_return</parameter></paramdef>

+  <paramdef>unsignedint<parameter> *mask_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+<!-- .ds Ro that the pointer is in -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>root_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the root window (Ro.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>child_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the child window that the pointer is located in, if any.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>root_x_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>root_y_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Return the pointer coordinates relative to the root window's origin.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>win_x_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>win_y_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Return the pointer coordinates relative to the specified window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>mask_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the current state of the modifier keys and pointer buttons.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XQueryPointer</function>

+function returns the root window the pointer is logically on and the pointer

+coordinates relative to the root window's origin.

+If

+<function>XQueryPointer</function>

+returns 

+<function>False</function>,

+the pointer is not on the same screen as the specified window, and

+<function>XQueryPointer</function>

+returns 

+<function>None</function>

+to child_return and zero to win_x_return and win_y_return.

+If 

+<function>XQueryPointer</function>

+returns 

+<function>True</function>,

+the pointer coordinates returned to win_x_return and win_y_return

+are relative to the origin of the specified window.

+In this case, 

+<function>XQueryPointer</function>

+returns the child that contains the pointer, if any,

+or else

+<function>None</function>

+to child_return.

+</para>

+<para>

+<!-- .LP -->

+<function>XQueryPointer</function>

+returns the current logical state of the keyboard buttons 

+and the modifier keys in mask_return.

+It sets mask_return to the bitwise inclusive OR of one or more

+of the button or modifier key bitmasks to match 

+the current state of the mouse buttons and the modifier keys.

+</para>

+<para>

+<!-- .LP -->

+Note that the logical state of a device (as seen through Xlib)

+may lag the physical state if device event processing is frozen

+(see section 12.1). <!-- xref -->

+</para>

+<para>

+<!-- .LP -->

+<function>XQueryPointer</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+</sect1>

+<sect1 id="Properties_and_Atoms">

+<title>Properties and Atoms</title>

+<!-- .XS -->

+<!-- (SN Properties and Atoms  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+A property is a collection of named, typed data.

+The window system has a set of predefined properties

+<indexterm><primary>Atom</primary><secondary>predefined</secondary></indexterm>

+(for example, the name of a window, size hints, and so on), and users can

+define any other arbitrary information and associate it with windows.

+Each property has a name,

+which is an ISO Latin-1 string.

+For each named property,

+a unique identifier (atom) is associated with it. 

+A property also has a type, for example, string or integer.

+These types are also indicated using atoms, so arbitrary new

+types can be defined.

+Data of only one type may be associated with a single

+property name.

+Clients can store and retrieve properties associated with windows.

+For efficiency reasons,

+an atom is used rather than a character string.

+<function>XInternAtom</function>

+can be used to obtain the atom for property names.

+<indexterm><primary>Atom</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+A property is also stored in one of several possible formats.

+The X server can store the information as 8-bit quantities, 16-bit

+quantities, or 32-bit quantities.

+This permits the X server to present the data in the byte order that the

+client expects.

+<!-- .NT Note -->

+If you define further properties of complex type, 

+you must encode and decode them yourself.

+These functions must be carefully written if they are to be portable.

+For further information about how to write a library extension,

+see appendix C. <!-- xref -->

+<!-- .NE -->

+The type of a property is defined by an atom, which allows for

+arbitrary extension in this type scheme.

+<indexterm><primary>Atom</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+Certain property names are

+predefined in the server for commonly used functions.

+The atoms for these properties are defined in 

+<!-- .hN X11/Xatom.h . -->

+To avoid name clashes with user symbols, the 

+<function>#define </function>

+name for each atom has the XA_ prefix.

+For an explanation of the functions that let you get and set

+much of the information stored in these predefined properties,

+see chapter 14. <!-- xref -->

+</para>

+<para>

+<!-- .LP -->

+The core protocol imposes no semantics on these property names,

+but semantics are specified in other X Consortium standards,

+such as the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>

+and the <emphasis remap='I'>X Logical Font Description Conventions</emphasis>.

+</para>

+<para>

+<!-- .LP -->

+You can use properties to communicate other information between

+applications.

+The functions described in this section let you define new properties 

+and get the unique atom IDs in your applications.

+</para>

+<para>

+<!-- .LP -->

+Although any particular atom can have some client interpretation 

+within each of the name spaces, 

+atoms occur in five distinct name spaces within the protocol: 

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Selections

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Property names

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Property types

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Font properties 

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Type of a 

+<function>ClientMessage </function>

+event (none are built into the X server)

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+</para>

+<para>

+<!-- .LP -->

+The built-in selection property names are:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA .5i 1.5i 3i -->

+<!-- .ta .5i 1.5i 3i -->

+<!-- .R -->

+PRIMARY

+SECONDARY

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+The built-in property names are: 

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <tbody>

+    <row>

+      <entry>lw(2i) lw(2i).</entry>

+    </row>

+    <row>

+      <entry>CUT_BUFFER0</entry>

+      <entry>RESOURCE_MANAGER</entry>

+    </row>

+    <row>

+      <entry>CUT_BUFFER1</entry>

+      <entry>WM_CLASS</entry>

+    </row>

+    <row>

+      <entry>CUT_BUFFER2</entry>

+      <entry>WM_CLIENT_MACHINE</entry>

+    </row>

+    <row>

+      <entry>CUT_BUFFER3</entry>

+      <entry>WM_COLORMAP_WINDOWS</entry>

+    </row>

+    <row>

+      <entry>CUT_BUFFER4</entry>

+      <entry>WM_COMMAND</entry>

+    </row>

+    <row>

+      <entry>CUT_BUFFER5</entry>

+      <entry>WM_HINTS</entry>

+    </row>

+    <row>

+      <entry>CUT_BUFFER6</entry>

+      <entry>WM_ICON_NAME</entry>

+    </row>

+    <row>

+      <entry>CUT_BUFFER7</entry>

+      <entry>WM_ICON_SIZE</entry>

+    </row>

+    <row>

+      <entry>RGB_BEST_MAP</entry>

+      <entry>WM_NAME</entry>

+    </row>

+    <row>

+      <entry>RGB_BLUE_MAP</entry>

+      <entry>WM_NORMAL_HINTS</entry>

+    </row>

+    <row>

+      <entry>RGB_DEFAULT_MAP</entry>

+      <entry>WM_PROTOCOLS</entry>

+    </row>

+    <row>

+      <entry>RGB_GRAY_MAP</entry>

+      <entry>WM_STATE</entry>

+    </row>

+    <row>

+      <entry>RGB_GREEN_MAP</entry>

+      <entry>WM_TRANSIENT_FOR</entry>

+    </row>

+    <row>

+      <entry>RGB_RED_MAP</entry>

+      <entry>WM_ZOOM_HINTS</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+</para>

+<para>

+<!-- .LP -->

+The built-in property types are: 

+</para>

+<para>

+<!-- .LP -->

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <tbody>

+    <row>

+      <entry>lw(2i) lw(2i).</entry>

+    </row>

+    <row>

+      <entry>ARC</entry>

+      <entry>POINT</entry>

+    </row>

+    <row>

+      <entry>ATOM</entry>

+      <entry>RGB_COLOR_MAP</entry>

+    </row>

+    <row>

+      <entry>BITMAP</entry>

+      <entry>RECTANGLE</entry>

+    </row>

+    <row>

+      <entry>CARDINAL</entry>

+      <entry>STRING</entry>

+    </row>

+    <row>

+      <entry>COLORMAP</entry>

+      <entry>VISUALID</entry>

+    </row>

+    <row>

+      <entry>CURSOR</entry>

+      <entry>WINDOW</entry>

+    </row>

+    <row>

+      <entry>DRAWABLE</entry>

+      <entry>WM_HINTS</entry>

+    </row>

+    <row>

+      <entry>FONT</entry>

+      <entry>WM_SIZE_HINTS</entry>

+    </row>

+    <row>

+      <entry>INTEGER</entry>

+    </row>

+    <row>

+      <entry>PIXMAP</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+</para>

+<para>

+<!-- .LP -->

+The built-in font property names are: 

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <tbody>

+    <row>

+      <entry>lw(2i) lw(2i).</entry>

+    </row>

+    <row>

+      <entry>MIN_SPACE</entry>

+      <entry>STRIKEOUT_DESCENT</entry>

+    </row>

+    <row>

+      <entry>NORM_SPACE</entry>

+      <entry>STRIKEOUT_ASCENT</entry>

+    </row>

+    <row>

+      <entry>MAX_SPACE</entry>

+      <entry>ITALIC_ANGLE</entry>

+    </row>

+    <row>

+      <entry>END_SPACE</entry>

+      <entry>X_HEIGHT</entry>

+    </row>

+    <row>

+      <entry>SUPERSCRIPT_X</entry>

+      <entry>QUAD_WIDTH</entry>

+    </row>

+    <row>

+      <entry>SUPERSCRIPT_Y</entry>

+      <entry>WEIGHT</entry>

+    </row>

+    <row>

+      <entry>SUBSCRIPT_X</entry>

+      <entry>POINT_SIZE</entry>

+    </row>

+    <row>

+      <entry>SUBSCRIPT_Y</entry>

+      <entry>RESOLUTION</entry>

+    </row>

+    <row>

+      <entry>UNDERLINE_POSITION</entry>

+      <entry>COPYRIGHT</entry>

+    </row>

+    <row>

+      <entry>UNDERLINE_THICKNESS</entry>

+      <entry>NOTICE</entry>

+    </row>

+    <row>

+      <entry>FONT_NAME</entry>

+      <entry>FAMILY_NAME</entry>

+    </row>

+    <row>

+      <entry>FULL_NAME</entry>

+      <entry>CAP_HEIGHT</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+</para>

+<para>

+<!-- .LP -->

+For further information about font properties,

+see section 8.5. <!-- xref -->

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To return an atom for a given name, use 

+<function>XInternAtom</function>.

+<indexterm><primary>Atom</primary><secondary>interning</secondary></indexterm>

+<indexterm significance="preferred"><primary>XInternAtom</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Atom<function> XInternAtom</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>char<parameter> *atom_name</parameter></paramdef>

+  <paramdef>Bool<parameter> only_if_exists</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>atom_name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the name associated with the atom you want returned.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>only_if_exists</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a Boolean value that indicates whether the atom must be created.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XInternAtom</function>

+function returns the atom identifier associated with the specified atom_name

+string.

+If only_if_exists is 

+<function>False</function>,

+the atom is created if it does not exist.

+Therefore,

+<function>XInternAtom</function>

+can return

+<function>None</function>.

+If the atom name is not in the Host Portable Character Encoding, 

+the result is implementation-dependent.

+Uppercase and lowercase matter;

+the strings ``thing'', ``Thing'', and ``thinG'' 

+all designate different atoms.  

+The atom will remain defined even after the client's connection closes.

+It will become undefined only when the last connection to

+the X server closes.

+</para>

+<para>

+<!-- .LP -->

+<function>XInternAtom</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To return atoms for an array of names, use 

+<function>XInternAtoms</function>.

+<indexterm><primary>Atom</primary><secondary>interning</secondary></indexterm>

+<indexterm significance="preferred"><primary>XInternAtoms</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XInternAtoms</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>char<parameter> **names</parameter></paramdef>

+  <paramdef>int<parameter> count</parameter></paramdef>

+  <paramdef>Bool<parameter> only_if_exists</parameter></paramdef>

+  <paramdef>Atom<parameter> *atoms_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>names</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the array of atom names.

+<!-- .ds Cn atom names in the array -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>count</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of (Cn.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>only_if_exists</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a Boolean value that indicates whether the atom must be created.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>atoms_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the atoms.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XInternAtoms</function>

+function returns the atom identifiers associated with the specified names.

+The atoms are stored in the atoms_return array supplied by the caller.

+Calling this function is equivalent to calling

+<function>XInternAtom</function>

+for each of the names in turn with the specified value of only_if_exists,

+but this function minimizes the number of round-trip protocol exchanges

+between the client and the X server.

+</para>

+<para>

+<!-- .LP -->

+This function returns a nonzero status if atoms are returned for

+all of the names;

+otherwise, it returns zero.

+</para>

+<para>

+<!-- .LP -->

+<function>XInternAtoms</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To return a name for a given atom identifier, use 

+<function>XGetAtomName</function>.

+<indexterm><primary>Atom</primary><secondary>getting name</secondary></indexterm>

+<indexterm significance="preferred"><primary>XGetAtomName</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> *XGetAtomName</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Atom<parameter> atom</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>atom</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the atom for the property name you want returned.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetAtomName</function>

+function returns the name associated with the specified atom.

+If the data returned by the server is in the Latin Portable Character Encoding,

+then the returned string is in the Host Portable Character Encoding.

+Otherwise, the result is implementation-dependent.

+To free the resulting string,

+call

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetAtomName</function>

+can generate a

+<function>BadAtom </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To return the names for an array of atom identifiers, use 

+<function>XGetAtomNames</function>.

+<indexterm><primary>Atom</primary><secondary>getting name</secondary></indexterm>

+<indexterm significance="preferred"><primary>XGetAtomNames</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XGetAtomNames</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Atom<parameter> *atoms</parameter></paramdef>

+  <paramdef>int<parameter> count</parameter></paramdef>

+  <paramdef>char<parameter> **names_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>atoms</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the array of atoms.

+<!-- .ds Cn atoms in the array -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>count</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of (Cn.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>names_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the atom names.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetAtomNames</function>

+function returns the names associated with the specified atoms.

+The names are stored in the names_return array supplied by the caller.

+Calling this function is equivalent to calling

+<function>XGetAtomName</function>

+for each of the atoms in turn,

+but this function minimizes the number of round-trip protocol exchanges

+between the client and the X server.

+</para>

+<para>

+<!-- .LP -->

+This function returns a nonzero status if names are returned for

+all of the atoms;

+otherwise, it returns zero.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetAtomNames</function>

+can generate a

+<function>BadAtom </function>

+error.

+</para>

+</sect1>

+<sect1 id="Obtaining_and_Changing_Window_Properties">

+<title>Obtaining and Changing Window Properties</title>

+<!-- .XS -->

+<!-- (SN Obtaining and Changing Window Properties  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+You can attach a property list to every window.

+Each property has a name, a type, and a value (see section 4.3). <!-- xref -->

+The value is an array of 8-bit, 16-bit, or 32-bit quantities,

+whose interpretation is left to the clients.  The type

+<function>char</function>

+is used to represent 8-bit quantities, the type

+<function>short</function>

+is used to represent 16-bit quantities, and the type

+<function>long</function>

+is used to represent 32-bit quantities.

+</para>

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to obtain, 

+change, update, or interchange window properties.

+In addition, Xlib provides other utility functions for inter-client

+communication (see chapter 14). <!-- xref -->

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the type, format, and value of a property of a given window, use 

+<function>XGetWindowProperty</function>.

+<indexterm><primary>Property</primary><secondary>getting</secondary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XGetWindowProperty</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> XGetWindowProperty</function></funcdef>

+  <paramdef><parameter> \^display</parameter></paramdef>

+  <paramdef><parameter> w</parameter></paramdef>

+  <paramdef><parameter> property</parameter></paramdef>

+  <paramdef><parameter> long_offset</parameter></paramdef>

+  <paramdef><parameter> long_length</parameter></paramdef>

+  <paramdef><parameter> delete</parameter></paramdef>

+  <paramdef><parameter> req_type</parameter></paramdef>

+  <paramdef><parameter> actual_type_return</parameter></paramdef>

+  <paramdef><parameter> actual_format_return</parameter></paramdef>

+  <paramdef><parameter> nitems_return</parameter></paramdef>

+  <paramdef><parameter> bytes_after_return</parameter></paramdef>

+  <paramdef>.br<parameter> prop_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Wi whose property you want to obtain -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window (Wi.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>property</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the property name.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>long_offset</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the offset in the specified property (in 32-bit quantities) 

+where the data is to be retrieved.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>long_length</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the length in 32-bit multiples of the data to be retrieved.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>delete</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a Boolean value that determines whether the property is deleted.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>req_type</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the atom identifier associated with the property type or

+<function>AnyPropertyType</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>actual_type_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the atom identifier  that defines the actual type of the property.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>actual_format_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the actual format of the property.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nitems_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the actual number of 8-bit, 16-bit, or 32-bit items 

+stored in the prop_return data.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>bytes_after_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of bytes remaining to be read in the property if 

+a partial read was performed.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>prop_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the data in the specified format.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetWindowProperty</function>

+function returns the actual type of the property; the actual format of the property;

+the number of 8-bit, 16-bit, or 32-bit items transferred; the number of bytes remaining

+to be read in the property; and a pointer to the data actually returned.

+<function>XGetWindowProperty</function>

+sets the return arguments as follows:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+If the specified property does not exist for the specified window,

+<function>XGetWindowProperty </function>

+returns 

+<function>None</function>

+to actual_type_return and the value zero to 

+actual_format_return and bytes_after_return.

+The nitems_return argument is empty.

+In this case, the delete argument is ignored.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If the specified property exists 

+but its type does not match the specified type,

+<function>XGetWindowProperty </function>

+returns the actual property type to actual_type_return, 

+the actual property format (never zero) to actual_format_return, 

+and the property length in bytes

+(even if the actual_format_return is 16 or 32) 

+to bytes_after_return.

+It also ignores the delete argument.

+The nitems_return argument is empty.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If the specified property exists and either you assign 

+<function>AnyPropertyType </function>

+to the req_type argument or the specified type matches the actual property type,

+<function>XGetWindowProperty </function>

+returns the actual property type to actual_type_return and the actual

+property format (never zero) to actual_format_return. 

+It also returns a value to bytes_after_return and nitems_return, by 

+defining the following

+values:

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<!-- .nf -->

+     N = actual length of the stored property in bytes

+          (even if the format is 16 or 32)

+     I = 4 * long_offset

+     T = N - I

+     L = MINIMUM(T, 4 * long_length)

+     A = N - (I + L)

+<!-- .fi -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The returned value starts at byte index I in the property (indexing

+from zero), and its length in bytes is L.

+If the value for long_offset causes L to be negative,

+a

+<function>BadValue</function>

+error results. 

+The value of bytes_after_return is A, 

+giving the number of trailing unread bytes in the stored property.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+If the returned format is 8, the returned data is represented as a

+<function>char</function>

+array.

+If the returned format is 16, the returned data is represented as a

+<function>short</function>

+array and should be cast to that type to obtain the elements.

+If the returned format is 32, the returned data is represented as a

+<function>long</function>

+array and should be cast to that type to obtain the elements.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetWindowProperty</function>

+always allocates one extra byte in prop_return 

+(even if the property is zero length) 

+and sets it to zero so that simple properties consisting of characters

+do not have to be copied into yet another string before use.

+</para>

+<para>

+<!-- .LP -->

+If delete is 

+<function>True </function>

+and bytes_after_return is zero, 

+<function>XGetWindowProperty</function>

+deletes the property 

+from the window and generates a 

+<function>PropertyNotify </function>

+event on the window.

+</para>

+<para>

+<!-- .LP -->

+The function returns

+<function>Success</function>

+if it executes successfully.

+To free the resulting data,

+use

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetWindowProperty</function>

+can generate

+<function>BadAtom</function>,

+<function>BadValue</function>,

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain a given window's property list, use 

+<function>XListProperties</function>.

+<indexterm><primary>Property</primary><secondary>listing</secondary></indexterm>

+<indexterm significance="preferred"><primary>XListProperties</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Atom<function> *XListProperties</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>int<parameter> *num_prop_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Wi whose property list you want to obtain -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window (Wi.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>num_prop_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the length of the properties array.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XListProperties</function>

+function returns a pointer to an array of atom properties that are defined for 

+the specified window or returns NULL if no properties were found.

+To free the memory allocated by this function, use

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XListProperties</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To change a property of a given window, use

+<function>XChangeProperty</function>.

+<indexterm><primary>Property</primary><secondary>changing</secondary></indexterm>

+<indexterm><primary>Property</primary><secondary>appending</secondary></indexterm>

+<indexterm><primary>Property</primary><secondary>prepending</secondary></indexterm>

+<indexterm><primary>Property</primary><secondary>replacing</secondary></indexterm>

+<indexterm><primary>Property</primary><secondary>format</secondary></indexterm>

+<indexterm><primary>Property</primary><secondary>type</secondary></indexterm>

+<indexterm significance="preferred"><primary>XChangeProperty</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XChangeProperty</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>Atomproperty,<parameter> type</parameter></paramdef>

+  <paramdef>int<parameter> format</parameter></paramdef>

+  <paramdef>int<parameter> mode</parameter></paramdef>

+  <paramdef>unsignedchar<parameter> *data</parameter></paramdef>

+  <paramdef>int<parameter> nelements</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Wi whose property you want to change -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window (Wi.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>property</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the property name.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>type</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the type of the property.

+The X server does not interpret the type but simply

+passes it back to an application that later calls 

+<function>XGetWindowProperty</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>format</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies whether the data should be viewed as a list

+of 8-bit, 16-bit, or 32-bit quantities.

+Possible values are 8, 16, and 32.

+This information allows the X server to correctly perform

+byte-swap operations as necessary.

+If the format is 16-bit or 32-bit,

+you must explicitly cast your data pointer to an (unsigned char *) in the call

+to 

+<function>XChangeProperty</function>.

+<!-- .\" Changed name of this file to prop_mode.a on 1/13/87 -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>mode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the mode of the operation.

+You can pass

+<function>PropModeReplace</function>,

+<function>PropModePrepend</function>,

+or

+<function>PropModeAppend</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the property data.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nelements</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of elements of the specified data format.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XChangeProperty</function>

+function alters the property for the specified window and

+causes the X server to generate a

+<function>PropertyNotify</function>

+event on that window.

+<function>XChangeProperty</function>

+performs the following:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+If mode is

+<function>PropModeReplace</function>,

+<function>XChangeProperty</function>

+discards the previous property value and stores the new data.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If mode is

+<function>PropModePrepend</function>

+or

+<function>PropModeAppend</function>,

+<function>XChangeProperty</function>

+inserts the specified data before the beginning of the existing data

+or onto the end of the existing data, respectively.

+The type and format must match the existing property value,

+or a

+<function>BadMatch</function>

+error results.

+If the property is undefined, 

+it is treated as defined with the correct type and

+format with zero-length data.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+If the specified format is 8, the property data must be a

+<function>char</function>

+array.

+If the specified format is 16, the property data must be a

+<function>short</function>

+array.

+If the specified format is 32, the property data must be a

+<function>long</function>

+array.

+</para>

+<para>

+<!-- .LP -->

+The lifetime of a property is not tied to the storing client.

+Properties remain until explicitly deleted, until the window is destroyed,

+or until the server resets.

+For a discussion of what happens when the connection to the X server is closed,

+see section 2.6.  <!-- xref -->

+The maximum size of a property is server dependent and can vary dynamically

+depending on the amount of memory the server has available.

+(If there is insufficient space, a

+<function>BadAlloc</function>

+error results.)

+</para>

+<para>

+<!-- .LP -->

+<function>XChangeProperty</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadAtom</function>,

+<function>BadMatch</function>,

+<function>BadValue</function>,

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To rotate a window's property list, use

+<function>XRotateWindowProperties</function>.

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XRotateWindowProperties</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XRotateWindowProperties</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>Atom<parameter> properties[]\^</parameter></paramdef>

+  <paramdef>int<parameter> num_prop</parameter></paramdef>

+  <paramdef>int<parameter> npositions</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>properties</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the array of properties that are to be rotated.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>num_prop</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the length of the properties array.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>npositions</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the rotation amount.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XRotateWindowProperties</function>

+function allows you to rotate properties on a window and causes

+the X server to generate

+<function>PropertyNotify</function>

+events.

+If the property names in the properties array are viewed as being numbered 

+starting from zero and if there are num_prop property names in the list,

+then the value associated with property name I becomes the value associated 

+with property name (I + npositions) mod N for all I from zero to N \- 1.

+The effect is to rotate the states by npositions places around the virtual ring

+of property names (right for positive npositions, 

+left for negative npositions).

+If npositions mod N is nonzero,

+the X server generates a

+<function>PropertyNotify</function>

+event for each property in the order that they are listed in the array.

+If an atom occurs more than once in the list or no property with that 

+name is defined for the window,

+a 

+<function>BadMatch </function>

+error results.

+If a 

+<function>BadAtom </function>

+or 

+<function>BadMatch </function>

+error results,

+no properties are changed.

+</para>

+<para>

+<!-- .LP -->

+<function>XRotateWindowProperties</function>

+can generate

+<function>BadAtom</function>,

+<function>BadMatch</function>,

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To delete a property on a given window, use 

+<function>XDeleteProperty</function>.

+<indexterm><primary>Property</primary><secondary>deleting</secondary></indexterm>

+<indexterm significance="preferred"><primary>XDeleteProperty</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDeleteProperty</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>Atom<parameter> property</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Wi whose property you want to delete -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window (Wi.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>property</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the property name.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XDeleteProperty</function>

+function deletes the specified property only if the

+property was defined on the specified window

+and causes the X server to generate a

+<function>PropertyNotify</function>

+event on the window unless the property does not exist.

+</para>

+<para>

+<!-- .LP -->

+<function>XDeleteProperty</function>

+can generate

+<function>BadAtom</function>

+and

+<function>BadWindow </function>

+errors.

+</para>

+</sect1>

+<sect1 id="Selections">

+<title>Selections</title>

+<!-- .XS -->

+<!-- (SN Selections -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Selection</primary></indexterm>

+Selections are one method used by applications to exchange data.

+By using the property mechanism,

+applications can exchange data of arbitrary types and can negotiate

+the type of the data.

+A selection can be thought of as an indirect property with a dynamic type.

+That is, rather than having the property stored in the X server,

+the property is maintained by some client (the owner).

+A selection is global in nature (considered to belong to the user 

+but be maintained by clients) rather than being private to a particular 

+window subhierarchy or a particular set of clients.

+</para>

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to set, get, or request conversion

+of selections.

+This allows applications to implement the notion of current selection,

+which requires that notification be sent to applications when they no 

+longer own the selection.

+Applications that support selection often highlight the current selection

+and so must be informed when another application has

+acquired the selection so that they can unhighlight the selection.

+</para>

+<para>

+<!-- .LP -->

+When a client asks for the contents of

+a selection, it specifies a selection target type.

+This target type

+can be used to control the transmitted representation of the contents.

+For example, if the selection is ``the last thing the user clicked on''

+and that is currently an image, then the target type might specify

+whether the contents of the image should be sent in XY format or Z format.

+</para>

+<para>

+<!-- .LP -->

+The target type can also be used to control the class of

+contents transmitted, for example, 

+asking for the ``looks'' (fonts, line

+spacing, indentation, and so forth) of a paragraph selection, not the

+text of the paragraph.

+The target type can also be used for other

+purposes.

+The protocol does not constrain the semantics.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the selection owner, use 

+<function>XSetSelectionOwner</function>.

+<indexterm><primary>Selection</primary><secondary>setting the owner</secondary></indexterm>

+<indexterm significance="preferred"><primary>XSetSelectionOwner</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetSelectionOwner</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Atom<parameter> selection</parameter></paramdef>

+  <paramdef>Window<parameter> owner</parameter></paramdef>

+  <paramdef>Time<parameter> time</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>selection</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the selection atom.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>owner</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the owner of the specified selection atom.

+You can pass a window or

+<function>None</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>time</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the time.

+You can pass either a timestamp or

+<function>CurrentTime</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetSelectionOwner</function>

+function changes the owner and last-change time for the specified selection

+and has no effect if the specified time is earlier than the current

+last-change time of the specified selection 

+or is later than the current X server time.

+Otherwise, the last-change time is set to the specified time,

+with

+<function>CurrentTime</function>

+replaced by the current server time.

+If the owner window is specified as

+<function>None</function>,

+then the owner of the selection becomes 

+<function>None</function>

+(that is, no owner).

+Otherwise, the owner of the selection becomes the client executing

+the request.

+</para>

+<para>

+<!-- .LP  -->

+If the new owner (whether a client or

+<function>None</function>)

+is not

+the same as the current owner of the selection and the current

+owner is not

+<function>None</function>,

+the current owner is sent a 

+<function>SelectionClear </function>

+event.

+If the client that is the owner of a selection is later

+terminated (that is, its connection is closed)

+or if the owner window it has specified in the request is later

+destroyed,

+the owner of the selection automatically

+reverts to

+<function>None</function>,

+but the last-change time is not affected.

+The selection atom is uninterpreted by the X server.

+<function>XGetSelectionOwner</function>

+returns the owner window, which is reported in 

+<function>SelectionRequest</function>

+and

+<function>SelectionClear</function>

+events.

+Selections are global to the X server.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetSelectionOwner</function>

+can generate

+<function>BadAtom</function>

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To return the selection owner, use 

+<function>XGetSelectionOwner</function>.

+<indexterm><primary>Selection</primary><secondary>getting the owner</secondary></indexterm>

+<indexterm significance="preferred"><primary>XGetSelectionOwner</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Window<function> XGetSelectionOwner</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Atom<parameter> selection</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Se whose owner you want returned -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>selection</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the selection atom (Se.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetSelectionOwner</function>

+function

+returns the window ID associated with the window that currently owns the

+specified selection.

+If no selection was specified, the function returns the constant

+<function>None</function>.

+If

+<function>None</function>

+is returned,

+there is no owner for the selection.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetSelectionOwner</function>

+can generate a

+<function>BadAtom </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To request conversion of a selection, use 

+<function>XConvertSelection</function>.

+<indexterm><primary>Selection</primary><secondary>converting</secondary></indexterm>

+<indexterm significance="preferred"><primary>XConvertSelection</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XConvertSelection</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Atomselection,<parameter> target</parameter></paramdef>

+  <paramdef>Atom<parameter> property</parameter></paramdef>

+  <paramdef>Window<parameter> requestor</parameter></paramdef>

+  <paramdef>Time<parameter> time</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>selection</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the selection atom.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>target</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the target atom.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>property</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the property name.

+You also can pass 

+<function>None</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>requestor</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the requestor.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>time</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the time.

+You can pass either a timestamp or

+<function>CurrentTime</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<function>XConvertSelection</function>

+requests that the specified selection be converted to the specified target

+type:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+If the specified selection has an owner, the X server sends a

+<function>SelectionRequest</function>

+event to that owner.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If no owner for the specified

+selection exists, the X server generates a

+<function>SelectionNotify</function>

+event to the

+requestor with property

+<function>None</function>.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+The arguments are passed on unchanged in either of the events.

+There are two predefined selection atoms: PRIMARY and SECONDARY.

+</para>

+<para>

+<!-- .LP -->

+<function>XConvertSelection</function>

+can generate

+<function>BadAtom</function>

+and

+<function>BadWindow </function>

+errors.

+<!-- .bp -->

+

+

+</para>

+</sect1>

+</chapter>

diff --git a/libX11/specs/libX11/CH05 b/libX11/specs/libX11/CH05
deleted file mode 100644
index 6ea218378..000000000
--- a/libX11/specs/libX11/CH05
+++ /dev/null
@@ -1,518 +0,0 @@
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-.\" OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" Except as contained in this notice, the name of the X Consortium shall
-.\" not be used in advertising or otherwise to promote the sale, use or
-.\" other dealings in this Software without prior written authorization
-.\" from the X Consortium.
-.\"
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
-.\" Digital Equipment Corporation
-.\"
-.\" Portions Copyright \(co 1990, 1991 by
-.\" Tektronix, Inc.
-.\"
-.\" Permission to use, copy, modify and distribute this documentation for
-.\" any purpose and without fee is hereby granted, provided that the above
-.\" copyright notice appears in all copies and that both that copyright notice
-.\" and this permission notice appear in all copies, and that the names of
-.\" Digital and Tektronix not be used in in advertising or publicity pertaining
-.\" to this documentation without specific, written prior permission.
-.\" Digital and Tektronix makes no representations about the suitability
-.\" of this documentation for any purpose.
-.\" It is provided ``as is'' without express or implied warranty.
-.\" 
-\&
-.sp 1
-.ce 3
-\s+1\fBChapter 5\fP\s-1
-
-\s+1\fBPixmap and Cursor Functions\fP\s-1
-.sp 2
-.nr H1 5
-.nr H2 0
-.nr H3 0
-.nr H4 0
-.nr H5 0
-.na
-.LP
-.XS
-Chapter 5: Pixmap and Cursor Functions 
-.XE
-Once you have connected to an X server,
-you can use the Xlib functions to:
-.IP \(bu 5
-Create and free pixmaps
-.IP \(bu 5
-Create, recolor, and free cursors
-.NH 2
-Creating and Freeing Pixmaps
-.XS
-\*(SN Creating and Freeing Pixmaps
-.XE
-.LP
-Pixmaps can only be used on the screen on which they were created.
-Pixmaps are off-screen resources that are used for various operations,
-such as defining cursors as tiling patterns 
-or as the source for certain raster operations.
-Most graphics requests can operate either on a window or on a pixmap.
-A bitmap is a single bit-plane pixmap.
-.LP
-.sp
-To create a pixmap of a given size, use
-.PN XCreatePixmap .
-.IN "XCreatePixmap" "" "@DEF@"
-.sM
-.FD 0
-Pixmap XCreatePixmap\^(\^\fIdisplay\fP, \fId\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIdepth\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
-.br
-      unsigned int \fIdepth\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies which screen the pixmap is created on. 
-.ds Wh , which define the dimensions of the pixmap
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height\*(Wh.
-.IP \fIdepth\fP 1i
-Specifies the depth of the pixmap.
-.LP
-.eM 
-The
-.PN XCreatePixmap
-function creates a pixmap of the width, height, and depth you specified
-and returns a pixmap ID that identifies it.
-It is valid to pass an 
-.PN InputOnly
-window to the drawable argument.
-The width and height arguments must be nonzero,
-or a 
-.PN BadValue
-error results.
-The depth argument must be one of the depths supported by the screen
-of the specified drawable,
-or a
-.PN BadValue
-error results.
-.LP
-The server uses the specified drawable to determine on which screen
-to create the pixmap.
-The pixmap can be used only on this screen
-and only with other drawables of the same depth (see
-.PN XCopyPlane
-for an exception to this rule).
-The initial contents of the pixmap are undefined.
-.LP
-.PN XCreatePixmap
-can generate
-.PN BadAlloc ,
-.PN BadDrawable ,
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-To free all storage associated with a specified pixmap, use
-.PN XFreePixmap .
-.IN "XFreePixmap" "" "@DEF@"
-.sM
-.FD 0
-XFreePixmap\^(\^\fIdisplay\fP, \fIpixmap\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Pixmap \fIpixmap\fP\^;
-.FN	
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIpixmap\fP 1i
-Specifies the pixmap.
-.LP
-.eM 
-The
-.PN XFreePixmap
-function first deletes the association between the pixmap ID and the pixmap.
-Then, the X server frees the pixmap storage when there are no references to it.
-The pixmap should never be referenced again.
-.LP
-.PN XFreePixmap
-can generate a
-.PN BadPixmap 
-error.
-.NH 2
-Creating, Recoloring, and Freeing Cursors
-.XS
-\*(SN Creating, Recoloring, and Freeing Cursors 
-.XE
-.LP
-Each window can have a different cursor defined for it.
-Whenever the pointer is in a visible window, 
-it is set to the cursor defined for that window.
-If no cursor was defined for that window, 
-the cursor is the one defined for the parent window.
-.LP
-From X's perspective, 
-a cursor consists of a cursor source, mask, colors, and a hotspot. 
-The mask pixmap determines the shape of the cursor and must be a depth
-of one.
-The source pixmap must have a depth of one,
-and the colors determine the colors of the source.
-The hotspot defines the point on the cursor that is reported
-when a pointer event occurs.
-There may be limitations imposed by the hardware on
-cursors as to size and whether a mask is implemented. 
-.IN "XQueryBestCursor"
-.PN XQueryBestCursor
-can be used to find out what sizes are possible.
-There is a standard font for creating cursors, but
-Xlib provides functions that you can use to create cursors
-from an arbitrary font or from bitmaps.
-.LP
-.sp
-To create a cursor from the standard cursor font, use
-.PN XCreateFontCursor .
-.IN "XCreateFontCursor" "" "@DEF@"
-.sM
-.FD 0
-#include <X11/cursorfont.h>
-.sp 6p
-Cursor XCreateFontCursor\^(\^\fIdisplay\fP, \fIshape\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      unsigned int \fIshape\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIshape\fP 1i
-Specifies the shape of the cursor.
-.LP
-.eM
-X provides a set of standard cursor shapes in a special font named
-cursor.
-Applications are encouraged to use this interface for their cursors
-because the font can be customized for the individual display type.
-The shape argument specifies which glyph of the standard fonts
-to use.
-.LP
-The hotspot comes from the information stored in the cursor font.
-The initial colors of a cursor are a black foreground and a white
-background (see
-.PN XRecolorCursor ).
-For further information about cursor shapes,
-see appendix B.
-.LP
-.PN XCreateFontCursor
-can generate
-.PN BadAlloc
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-To create a cursor from font glyphs, use
-.PN XCreateGlyphCursor .
-.IN "XCreateGlyphCursor" "" "@DEF@"
-.sM
-.FD 0
-Cursor XCreateGlyphCursor\^(\^\fIdisplay\fP, \fIsource_font\fP\^, \fImask_font\fP\^, \fIsource_char\fP\^, \fImask_char\fP\^,
-.br
-                           \fIforeground_color\fP\^, \fIbackground_color\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Font \fIsource_font\fP\^, \fImask_font\fP\^;
-.br
-      unsigned int \fIsource_char\fP\^, \fImask_char\fP\^;
-.br
-      XColor *\fIforeground_color\fP\^;
-.br
-      XColor *\fIbackground_color\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIsource_font\fP 1i
-Specifies the font for the source glyph.
-.IP \fImask_font\fP 1i
-Specifies the font for the mask glyph or
-.PN None .
-.IP \fIsource_char\fP 1i
-Specifies the character glyph for the source.
-.IP \fImask_char\fP 1i
-Specifies the glyph character for the mask. 
-.IP \fIforeground_color\fP 1i
-Specifies the RGB values for the foreground of the source. 
-.IP \fIbackground_color\fP 1i
-Specifies the RGB values for the background of the source.
-.LP
-.eM
-The
-.PN XCreateGlyphCursor
-function is similar to
-.PN XCreatePixmapCursor
-except that the source and mask bitmaps are obtained from the specified 
-font glyphs.
-The source_char must be a defined glyph in source_font, 
-or a
-.PN BadValue
-error results.
-If mask_font is given, 
-mask_char must be a defined glyph in mask_font,
-or a
-.PN BadValue
-error results.
-The mask_font and character are optional.
-The origins of the source_char and mask_char (if defined) glyphs are
-positioned coincidently and define the hotspot. 
-The source_char and mask_char need not have the same bounding box metrics, 
-and there is no restriction on the placement of the hotspot relative to the bounding
-boxes. 
-If no mask_char is given, all pixels of the source are displayed.
-You can free the fonts immediately by calling
-.PN XFreeFont
-if no further explicit references to them are to be made. 
-.LP
-For 2-byte matrix fonts, 
-the 16-bit value should be formed with the byte1
-member in the most significant byte and the byte2 member in the 
-least significant byte.
-.LP
-.PN XCreateGlyphCursor
-can generate
-.PN BadAlloc ,
-.PN BadFont ,
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-To create a cursor from two bitmaps,
-use
-.PN XCreatePixmapCursor .
-.IN "XCreatePixmapCursor" "" "@DEF@"
-.sM
-.FD 0
-Cursor XCreatePixmapCursor\^(\^\fIdisplay\fP, \fIsource\fP\^, \fImask\fP\^, \fIforeground_color\fP\^, \fIbackground_color\fP\^, \fIx\fP\^, \fIy\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Pixmap \fIsource\fP\^;
-.br
-      Pixmap \fImask\fP\^;
-.br
-      XColor *\fIforeground_color\fP\^;
-.br
-      XColor *\fIbackground_color\fP\^;
-.br
-      unsigned int \fIx\fP\^, \fIy\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIsource\fP 1i
-Specifies the shape of the source cursor.
-.\" *** JIM: NEED TO CHECK THIS. ***
-.IP \fImask\fP 1i
-Specifies the cursor's source bits to be displayed or
-.PN None .
-.IP \fIforeground_color\fP 1i
-Specifies the RGB values for the foreground of the source. 
-.IP \fIbackground_color\fP 1i
-Specifies the RGB values for the background of the source.
-.ds Xy , which indicate the hotspot relative to the source's origin
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.LP
-.eM
-The
-.PN XCreatePixmapCursor
-function creates a cursor and returns the cursor ID associated with it.
-The foreground and background RGB values must be specified using
-foreground_color and background_color,
-even if the X server only has a
-.PN StaticGray
-or
-.PN GrayScale
-screen.
-The foreground color is used for the pixels set to 1 in the
-source, and the background color is used for the pixels set to 0.
-Both source and mask, if specified, must have depth one (or a 
-.PN BadMatch
-error results) but can have any root.
-The mask argument defines the shape of the cursor.
-The pixels set to 1 in the mask define which source pixels are displayed,
-and the pixels set to 0 define which pixels are ignored.
-If no mask is given, 
-all pixels of the source are displayed.
-The mask, if present, must be the same size as the pixmap defined by the 
-source argument, or a
-.PN BadMatch
-error results.
-The hotspot must be a point within the source,
-or a
-.PN BadMatch
-error results.
-.LP
-The components of the cursor can be transformed arbitrarily to meet
-display limitations.
-The pixmaps can be freed immediately if no further explicit references
-to them are to be made.
-Subsequent drawing in the source or mask pixmap has an undefined effect on the
-cursor.
-The X server might or might not make a copy of the pixmap.
-.LP
-.PN XCreatePixmapCursor
-can generate
-.PN BadAlloc
-and
-.PN BadPixmap
-errors.
-.LP
-.sp
-To determine useful cursor sizes, use
-.PN XQueryBestCursor .
-.IN "XQueryBestCursor" "" "@DEF@"
-.sM
-.FD 0
-Status XQueryBestCursor\^(\^\fIdisplay\fP, \fId\fP, \fIwidth\fP\^, \fIheight\fP\^, \fIwidth_return\fP\^, \fIheight_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
-.br
-      unsigned int *\fIwidth_return\fP\^, *\fIheight_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Dr , which indicates the screen
-.IP \fId\fP 1i
-Specifies the drawable\*(Dr. 
-.ds Wh \ of the cursor that you want the size information for
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height\*(Wh.
-.IP \fIwidth_return\fP 1i
-.br
-.ns
-.IP \fIheight_return\fP 1i
-Return the best width and height that is closest to the specified width 
-and height.
-.LP
-.eM
-Some displays allow larger cursors than other displays.
-The
-.PN XQueryBestCursor
-function provides a way to find out what size cursors are actually
-possible on the display.
-.IN "Cursor" "limitations" 
-It returns the largest size that can be displayed.
-Applications should be prepared to use smaller cursors on displays that
-cannot support large ones.
-.LP
-.PN XQueryBestCursor
-can generate a
-.PN BadDrawable 
-error.
-.LP
-.sp
-To change the color of a given cursor, use
-.PN XRecolorCursor .
-.IN "XRecolorCursor" "" "@DEF@"
-.sM
-.FD 0
-XRecolorCursor\^(\^\fIdisplay\fP, \fIcursor\fP\^, \fIforeground_color\fP\^, \fIbackground_color\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Cursor \fIcursor\fP\^;
-.br
-      XColor *\fIforeground_color\fP\^, *\fIbackground_color\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcursor\fP 1i
-Specifies the cursor. 
-.IP \fIforeground_color\fP 1i
-Specifies the RGB values for the foreground of the source. 
-.IP \fIbackground_color\fP 1i
-Specifies the RGB values for the background of the source.
-.LP
-.eM
-The
-.PN XRecolorCursor
-function changes the color of the specified cursor, and
-if the cursor is being displayed on a screen,
-the change is visible immediately.
-The pixel members of the
-.PN XColor
-structures are ignored; only the RGB values are used.
-.LP
-.PN XRecolorCursor
-can generate a
-.PN BadCursor 
-error.
-.LP
-.sp
-To free (destroy) a given cursor, use
-.PN XFreeCursor .
-.IN "XFreeCursor" "" "@DEF@"
-.sM
-.FD 0
-XFreeCursor\^(\^\fIdisplay\fP, \fIcursor\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Cursor \fIcursor\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcursor\fP 1i
-Specifies the cursor. 
-.LP
-.eM 
-The
-.PN XFreeCursor
-function deletes the association between the cursor resource ID 
-and the specified cursor.
-The cursor storage is freed when no other resource references it.
-The specified cursor ID should not be referred to again.
-.LP
-.PN XFreeCursor
-can generate a
-.PN BadCursor 
-error.
-.bp
diff --git a/libX11/specs/libX11/CH05.xml b/libX11/specs/libX11/CH05.xml
new file mode 100644
index 000000000..449272a19
--- /dev/null
+++ b/libX11/specs/libX11/CH05.xml
@@ -0,0 +1,815 @@
+<chapter id="pixmap_and_cursor_functions">

+<title>Pixmap and Cursor Functions</title>

+<sect1 id="Creating_and_Freeing_Pixmaps">

+<title>Creating and Freeing Pixmaps</title>

+<!-- .XS -->

+<!-- (SN Creating and Freeing Pixmaps -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Pixmaps can only be used on the screen on which they were created.

+Pixmaps are off-screen resources that are used for various operations,

+such as defining cursors as tiling patterns 

+or as the source for certain raster operations.

+Most graphics requests can operate either on a window or on a pixmap.

+A bitmap is a single bit-plane pixmap.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To create a pixmap of a given size, use

+<function>XCreatePixmap</function>.

+<indexterm significance="preferred"><primary>XCreatePixmap</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Pixmap<function> XCreatePixmap</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+  <paramdef>unsignedint<parameter> depth</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies which screen the pixmap is created on. 

+<!-- .ds Wh , which define the dimensions of the pixmap -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height(Wh.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>depth</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the depth of the pixmap.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XCreatePixmap</function>

+function creates a pixmap of the width, height, and depth you specified

+and returns a pixmap ID that identifies it.

+It is valid to pass an 

+<function>InputOnly</function>

+window to the drawable argument.

+The width and height arguments must be nonzero,

+or a 

+<function>BadValue</function>

+error results.

+The depth argument must be one of the depths supported by the screen

+of the specified drawable,

+or a

+<function>BadValue</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+The server uses the specified drawable to determine on which screen

+to create the pixmap.

+The pixmap can be used only on this screen

+and only with other drawables of the same depth (see

+<function>XCopyPlane</function>

+for an exception to this rule).

+The initial contents of the pixmap are undefined.

+</para>

+<para>

+<!-- .LP -->

+<function>XCreatePixmap</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadDrawable</function>,

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To free all storage associated with a specified pixmap, use

+<function>XFreePixmap</function>.

+<indexterm significance="preferred"><primary>XFreePixmap</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XFreePixmap</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Pixmap<parameter> pixmap</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN	 -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>pixmap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the pixmap.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XFreePixmap</function>

+function first deletes the association between the pixmap ID and the pixmap.

+Then, the X server frees the pixmap storage when there are no references to it.

+The pixmap should never be referenced again.

+</para>

+<para>

+<!-- .LP -->

+<function>XFreePixmap</function>

+can generate a

+<function>BadPixmap </function>

+error.

+</para>

+</sect1>

+<sect1 id="Creating_Recoloring_and_Freeing_Cursors">

+<title>Creating, Recoloring, and Freeing Cursors</title>

+<!-- .XS -->

+<!-- (SN Creating, Recoloring, and Freeing Cursors  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Each window can have a different cursor defined for it.

+Whenever the pointer is in a visible window, 

+it is set to the cursor defined for that window.

+If no cursor was defined for that window, 

+the cursor is the one defined for the parent window.

+</para>

+<para>

+<!-- .LP -->

+From X's perspective, 

+a cursor consists of a cursor source, mask, colors, and a hotspot. 

+The mask pixmap determines the shape of the cursor and must be a depth

+of one.

+The source pixmap must have a depth of one,

+and the colors determine the colors of the source.

+The hotspot defines the point on the cursor that is reported

+when a pointer event occurs.

+There may be limitations imposed by the hardware on

+cursors as to size and whether a mask is implemented. 

+<indexterm><primary>XQueryBestCursor</primary></indexterm>

+<function>XQueryBestCursor</function>

+can be used to find out what sizes are possible.

+There is a standard font for creating cursors, but

+Xlib provides functions that you can use to create cursors

+from an arbitrary font or from bitmaps.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To create a cursor from the standard cursor font, use

+<function>XCreateFontCursor</function>.

+</para>

+<para>

+#include &lt;X11/cursorfont.h&gt;

+</para>

+

+<indexterm significance="preferred"><primary>XCreateFontCursor</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Cursor<function> XCreateFontCursor</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>unsignedint<parameter> shape</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>shape</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the shape of the cursor.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+X provides a set of standard cursor shapes in a special font named

+cursor.

+Applications are encouraged to use this interface for their cursors

+because the font can be customized for the individual display type.

+The shape argument specifies which glyph of the standard fonts

+to use.

+</para>

+<para>

+<!-- .LP -->

+The hotspot comes from the information stored in the cursor font.

+The initial colors of a cursor are a black foreground and a white

+background (see

+<function>XRecolorCursor</function>).

+For further information about cursor shapes,

+see appendix B.

+</para>

+<para>

+<!-- .LP -->

+<function>XCreateFontCursor</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To create a cursor from font glyphs, use

+<function>XCreateGlyphCursor</function>.

+<indexterm significance="preferred"><primary>XCreateGlyphCursor</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Cursor<function> XCreateGlyphCursor</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Fontsource_font,<parameter> mask_font</parameter></paramdef>

+  <paramdef>unsignedintsource_char,<parameter> mask_char</parameter></paramdef>

+  <paramdef>XColor<parameter> *foreground_color</parameter></paramdef>

+  <paramdef>XColor<parameter> *background_color</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>source_font</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the font for the source glyph.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>mask_font</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the font for the mask glyph or

+<function>None</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>source_char</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the character glyph for the source.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>mask_char</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the glyph character for the mask. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>foreground_color</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the <acronym>RGB</acronym> values for the foreground of the source. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>background_color</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the <acronym>RGB</acronym> values for the background of the source.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCreateGlyphCursor</function>

+function is similar to

+<function>XCreatePixmapCursor</function>

+except that the source and mask bitmaps are obtained from the specified 

+font glyphs.

+The source_char must be a defined glyph in source_font, 

+or a

+<function>BadValue</function>

+error results.

+If mask_font is given, 

+mask_char must be a defined glyph in mask_font,

+or a

+<function>BadValue</function>

+error results.

+The mask_font and character are optional.

+The origins of the source_char and mask_char (if defined) glyphs are

+positioned coincidently and define the hotspot. 

+The source_char and mask_char need not have the same bounding box metrics, 

+and there is no restriction on the placement of the hotspot relative to the bounding

+boxes. 

+If no mask_char is given, all pixels of the source are displayed.

+You can free the fonts immediately by calling

+<function>XFreeFont</function>

+if no further explicit references to them are to be made. 

+</para>

+<para>

+<!-- .LP -->

+For 2-byte matrix fonts, 

+the 16-bit value should be formed with the byte1

+member in the most significant byte and the byte2 member in the 

+least significant byte.

+</para>

+<para>

+<!-- .LP -->

+<function>XCreateGlyphCursor</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadFont</function>,

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To create a cursor from two bitmaps,

+use

+<function>XCreatePixmapCursor</function>.

+<indexterm significance="preferred"><primary>XCreatePixmapCursor</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Cursor<function> XCreatePixmapCursor</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Pixmap<parameter> source</parameter></paramdef>

+  <paramdef>Pixmap<parameter> mask</parameter></paramdef>

+  <paramdef>XColor<parameter> *foreground_color</parameter></paramdef>

+  <paramdef>XColor<parameter> *background_color</parameter></paramdef>

+  <paramdef>unsignedintx,<parameter> y</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>source</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the shape of the source cursor.

+<!-- .\" *** JIM: NEED TO CHECK THIS. *** -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>mask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the cursor's source bits to be displayed or

+<function>None</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>foreground_color</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the <acronym>RGB</acronym> values for the foreground of the source. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>background_color</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the <acronym>RGB</acronym> values for the background of the source.

+<!-- .ds Xy , which indicate the hotspot relative to the source's origin -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCreatePixmapCursor</function>

+function creates a cursor and returns the cursor ID associated with it.

+The foreground and background <acronym>RGB</acronym> values must be specified using

+foreground_color and background_color,

+even if the X server only has a

+<function>StaticGray</function>

+or

+<function>GrayScale</function>

+screen.

+The foreground color is used for the pixels set to 1 in the

+source, and the background color is used for the pixels set to 0.

+Both source and mask, if specified, must have depth one (or a 

+<function>BadMatch</function>

+error results) but can have any root.

+The mask argument defines the shape of the cursor.

+The pixels set to 1 in the mask define which source pixels are displayed,

+and the pixels set to 0 define which pixels are ignored.

+If no mask is given, 

+all pixels of the source are displayed.

+The mask, if present, must be the same size as the pixmap defined by the 

+source argument, or a

+<function>BadMatch</function>

+error results.

+The hotspot must be a point within the source,

+or a

+<function>BadMatch</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+The components of the cursor can be transformed arbitrarily to meet

+display limitations.

+The pixmaps can be freed immediately if no further explicit references

+to them are to be made.

+Subsequent drawing in the source or mask pixmap has an undefined effect on the

+cursor.

+The X server might or might not make a copy of the pixmap.

+</para>

+<para>

+<!-- .LP -->

+<function>XCreatePixmapCursor</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadPixmap</function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To determine useful cursor sizes, use

+<function>XQueryBestCursor</function>.

+<indexterm significance="preferred"><primary>XQueryBestCursor</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XQueryBestCursor</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Dr , which indicates the screen -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable(Dr. 

+<!-- .ds Wh \ of the cursor that you want the size information for -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height(Wh.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Return the best width and height that is closest to the specified width 

+and height.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Some displays allow larger cursors than other displays.

+The

+<function>XQueryBestCursor</function>

+function provides a way to find out what size cursors are actually

+possible on the display.

+<indexterm ><primary>Cursor</primary><secondary>limitations</secondary></indexterm>

+It returns the largest size that can be displayed.

+Applications should be prepared to use smaller cursors on displays that

+cannot support large ones.

+</para>

+<para>

+<!-- .LP -->

+<function>XQueryBestCursor</function>

+can generate a

+<function>BadDrawable </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To change the color of a given cursor, use

+<function>XRecolorCursor</function>.

+<indexterm significance="preferred"><primary>XRecolorCursor</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XRecolorCursor</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Cursor<parameter> cursor</parameter></paramdef>

+  <paramdef>XColor*foreground_color,<parameter> *background_color</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>cursor</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the cursor. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>foreground_color</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the <acronym>RGB</acronym> values for the foreground of the source. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>background_color</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the <acronym>RGB</acronym> values for the background of the source.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XRecolorCursor</function>

+function changes the color of the specified cursor, and

+if the cursor is being displayed on a screen,

+the change is visible immediately.

+The pixel members of the

+<function>XColor</function>

+structures are ignored; only the <acronym>RGB</acronym> values are used.

+</para>

+<para>

+<!-- .LP -->

+<function>XRecolorCursor</function>

+can generate a

+<function>BadCursor </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To free (destroy) a given cursor, use

+<function>XFreeCursor</function>.

+<indexterm significance="preferred"><primary>XFreeCursor</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XFreeCursor</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Cursor<parameter> cursor</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>cursor</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the cursor. 

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XFreeCursor</function>

+function deletes the association between the cursor resource ID 

+and the specified cursor.

+The cursor storage is freed when no other resource references it.

+The specified cursor ID should not be referred to again.

+</para>

+<para>

+<!-- .LP -->

+<function>XFreeCursor</function>

+can generate a

+<function>BadCursor </function>

+error.

+<!-- .bp -->

+

+</para>

+</sect1>

+</chapter>

diff --git a/libX11/specs/libX11/CH06 b/libX11/specs/libX11/CH06
deleted file mode 100644
index 44824d324..000000000
--- a/libX11/specs/libX11/CH06
+++ /dev/null
@@ -1,4773 +0,0 @@
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-.\" OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" Except as contained in this notice, the name of the X Consortium shall
-.\" not be used in advertising or otherwise to promote the sale, use or
-.\" other dealings in this Software without prior written authorization
-.\" from the X Consortium.
-.\"
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
-.\" Digital Equipment Corporation
-.\"
-.\" Portions Copyright \(co 1990, 1991 by
-.\" Tektronix, Inc.
-.\"
-.\" Permission to use, copy, modify and distribute this documentation for
-.\" any purpose and without fee is hereby granted, provided that the above
-.\" copyright notice appears in all copies and that both that copyright notice
-.\" and this permission notice appear in all copies, and that the names of
-.\" Digital and Tektronix not be used in in advertising or publicity pertaining
-.\" to this documentation without specific, written prior permission.
-.\" Digital and Tektronix makes no representations about the suitability
-.\" of this documentation for any purpose.
-.\" It is provided ``as is'' without express or implied warranty.
-.\" 
-\&
-.sp 1
-.ce 3
-\s+1\fBChapter 6\fP\s-1
-
-\s+1\fBColor Management Functions\fP\s-1
-.sp 2
-.nr H1 6
-.nr H2 0
-.nr H3 0
-.nr H4 0
-.nr H5 0
-.na
-.LP
-.XS
-Chapter 6: Color Management Functions 
-.XE
-Each X window always has an associated colormap that
-provides a level of indirection between pixel values and colors displayed
-on the screen.
-Xlib provides functions that you can use to manipulate a colormap.
-The X protocol defines colors using values in the RGB color space.
-The RGB color space is device dependent;
-rendering an RGB value on differing output devices typically results
-in different colors.
-Xlib also provides a means for clients to specify color using
-device-independent color spaces for consistent results across devices.
-Xlib supports device-independent color spaces derivable from the CIE XYZ
-color space.
-This includes the CIE XYZ, xyY, L*u*v*, and L*a*b* color spaces as well as
-the TekHVC color space.
-.LP
-This chapter discusses how to:
-.IP \(bu 5
-Create, copy, and destroy a colormap
-.IP \(bu 5
-Specify colors by name or value
-.IP \(bu 5
-Allocate, modify, and free color cells
-.IP \(bu 5
-Read entries in a colormap
-.IP \(bu 5
-Convert between color spaces
-.IP \(bu 5
-Control aspects of color conversion
-.IP \(bu 5
-Query the color gamut of a screen
-.IP \(bu 5
-Add new color spaces
-.LP
-All functions, types, and symbols in this chapter with the prefix ``Xcms''
-are defined in
-.hN X11/Xcms.h .
-The remaining functions and types are defined in
-.hN X11/Xlib.h .
-.LP
-Functions in this chapter manipulate the representation of color on the
-screen.
-For each possible value that a pixel can take in a window,
-there is a color cell in the colormap.
-For example, 
-if a window is 4 bits deep, pixel values 0 through 15 are defined. 
-A colormap is a collection of color cells.
-A color cell consists of a triple of red, green, and blue (RGB) values.
-The hardware imposes limits on the number of significant
-bits in these values.
-As each pixel is read out of display memory, the pixel
-is looked up in a colormap.
-The RGB value of the cell determines what color is displayed on the screen.
-On a grayscale display with a black-and-white monitor, 
-the values are combined to determine the brightness on the screen.
-.LP
-Typically, an application allocates color cells or sets of color cells
-to obtain the desired colors.
-The client can allocate read-only cells.
-In which case, 
-the pixel values for these colors can be shared among multiple applications, 
-and the RGB value of the cell cannot be changed.
-If the client allocates read/write cells,
-they are exclusively owned by the client,
-and the color associated with the pixel value can be changed at will.
-Cells must be allocated (and, if read/write, initialized with an RGB value)
-by a client to obtain desired colors.
-The use of pixel value for an
-unallocated cell results in an undefined color.
-.LP
-Because colormaps are associated with windows, X supports displays
-with multiple colormaps and, indeed, different types of colormaps.
-If there are insufficient colormap resources in the display,
-some windows will display in their true colors, and others
-will display with incorrect colors.
-A window manager usually controls which windows are displayed
-in their true colors if more than one colormap is required for
-the color resources the applications are using.
-At any time, there is a set of installed colormaps for a screen.
-Windows using one of the installed colormaps display with true colors, and
-windows using other colormaps generally display with incorrect colors.
-You can control the set of installed colormaps by using
-.PN XInstallColormap
-and
-.PN XUninstallColormap .
-.LP
-Colormaps are local to a particular screen.
-Screens always have a default colormap,
-and programs typically allocate cells out of this colormap.
-Generally, you should not write applications that monopolize 
-color resources.
-Although some hardware supports multiple colormaps installed at one time,
-many of the hardware displays
-built today support only a single installed colormap, so the primitives
-are written to encourage sharing of colormap entries between applications.
-.LP
-The 
-.PN DefaultColormap 
-macro returns the default colormap.
-The 
-.PN DefaultVisual 
-macro
-returns the default visual type for the specified screen.
-.IN "Color map"
-Possible visual types are 
-.PN StaticGray , 
-.PN GrayScale , 
-.PN StaticColor ,
-.PN PseudoColor , 
-.PN TrueColor , 
-or 
-.PN DirectColor 
-(see section 3.1).
-.NH 2
-Color Structures
-.XS
-\*(SN Color Structures
-.XE
-.LP
-Functions that operate only on RGB color space values use an
-.PN XColor
-structure, which contains:
-.LP
-.IN "XColor" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	unsigned long pixel;	/* pixel value */
-	unsigned short red, green, blue;	/* rgb values */
-	char flags;	/* DoRed, DoGreen, DoBlue */	
-	char pad;
-} XColor;
-.De
-.LP
-.eM
-The red, green, and blue values are always in the range 0 to 65535
-inclusive, independent of the number of bits actually used in the
-display hardware.
-The server scales these values down to the range used by the hardware.
-Black is represented by (0,0,0), 
-and white is represented by (65535,65535,65535).
-.IN "Color"
-In some functions,
-the flags member controls which of the red, green, and blue members is used 
-and can be the inclusive OR of zero or more of
-.PN DoRed ,
-.PN DoGreen ,
-and 
-.PN DoBlue .
-.LP
-.sp
-Functions that operate on all color space values use an
-.PN XcmsColor
-structure.
-This structure contains a union of substructures,
-each supporting color specification encoding for a particular color space.
-Like the
-.PN XColor
-structure, the
-.PN XcmsColor
-structure contains pixel
-and color specification information (the spec member in the 
-.PN XcmsColor
-structure).
-.IN "XcmsColor" "" "@DEF@"
-.sM
-.LP
-.Ds 0
-.TA .5i 1i 2.5i
-.ta .5i 1i 2.5i
-typedef unsigned long XcmsColorFormat;			/* Color Specification Format */
-
-typedef struct {
-	union {
-		XcmsRGB RGB;
-		XcmsRGBi RGBi;
-		XcmsCIEXYZ CIEXYZ;
-		XcmsCIEuvY CIEuvY;
-		XcmsCIExyY CIExyY;
-		XcmsCIELab CIELab;
-		XcmsCIELuv CIELuv;
-		XcmsTekHVC TekHVC;
-		XcmsPad Pad;
-	} spec;
-	unsigned long pixel;
-	XcmsColorFormat format;
-} XcmsColor;			/* Xcms Color Structure */
-.De
-.LP
-.eM
-Because the color specification can be encoded for the various color spaces, 
-encoding for the spec member is identified by the format member,
-which is of type
-.PN XcmsColorFormat .
-The following macros define standard formats.
-.sM
-.TS
-lw(.5i) lw(1.6i) lw(1.4i) lw(1.5i).
-T{
-#define
-T}	T{
-.PN XcmsUndefinedFormat
-T}	T{
-0x00000000
-T}
-T{
-#define
-T}	T{
-.PN XcmsCIEXYZFormat
-T}	T{
-0x00000001
-T}	T{
-/* CIE XYZ */
-T}
-T{
-#define
-T}	T{
-.PN XcmsCIEuvYFormat
-T}	T{
-0x00000002
-T}	T{
-/* CIE u'v'Y */
-T}
-T{
-#define
-T}	T{
-.PN XcmsCIExyYFormat
-T}	T{
-0x00000003
-T}	T{
-/* CIE xyY */
-T}
-T{
-#define
-T}	T{
-.PN XcmsCIELabFormat
-T}	T{
-0x00000004
-T}	T{
-/* CIE L*a*b* */
-T}
-T{
-#define
-T}	T{
-.PN XcmsCIELuvFormat
-T}	T{
-0x00000005
-T}	T{
-/* CIE L*u*v* */
-T}
-T{
-#define
-T}	T{
-.PN XcmsTekHVCFormat
-T}	T{
-0x00000006
-T}	T{
-/* TekHVC */
-T}
-T{
-#define
-T}	T{
-.PN XcmsRGBFormat
-T}	T{
-0x80000000
-T}	T{
-/* RGB Device */
-T}
-T{
-#define
-T}	T{
-.PN XcmsRGBiFormat
-T}	T{
-0x80000001
-T}	T{
-/* RGB Intensity */
-T}
-.TE
-.LP
-.eM
-Formats for device-independent color spaces are
-distinguishable from those for device-dependent spaces by the 32nd bit.
-If this bit is set,
-it indicates that the color specification is in a device-dependent form;
-otherwise, it is in a device-independent form.
-If the 31st bit is set,
-this indicates that the color space has been added to Xlib at run time
-(see section 6.12.4).
-The format value for a color space added at run time may be different each
-time the program is executed.
-If references to such a color space must be made outside the client
-(for example, storing a color specification in a file),
-then reference should be made by color space string prefix
-(see 
-.PN XcmsFormatOfPrefix
-and
-.PN XcmsPrefixOfFormat ).
-.LP
-Data types that describe the color specification encoding for the various
-color spaces are defined as follows:
-.sM
-.IN "XcmsRGB" "" "@DEF@"
-.LP
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef double XcmsFloat;
-
-typedef struct {
-	unsigned short red;	/* 0x0000 to 0xffff */
-	unsigned short green;	/* 0x0000 to 0xffff */
-	unsigned short blue;	/* 0x0000 to 0xffff */
-} XcmsRGB;		/* RGB Device */
-.De
-.IN "XcmsRGBi" "" "@DEF@"
-.LP
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	XcmsFloat red;	/* 0.0 to 1.0 */
-	XcmsFloat green;	/* 0.0 to 1.0 */
-	XcmsFloat blue;	/* 0.0 to 1.0 */
-} XcmsRGBi;		/* RGB Intensity */
-.De
-.IN "XcmsCIEXYZ" "" "@DEF@"
-.LP
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	XcmsFloat X;
-	XcmsFloat Y;	/* 0.0 to 1.0 */
-	XcmsFloat Z;
-} XcmsCIEXYZ;		/* CIE XYZ */
-.De
-.IN "XcmsCIEuvY" "" "@DEF@"
-.LP
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	XcmsFloat u_prime;	/* 0.0 to ~0.6 */
-	XcmsFloat v_prime;	/* 0.0 to ~0.6 */
-	XcmsFloat Y; 	/* 0.0 to 1.0 */
-} XcmsCIEuvY;		/* CIE u'v'Y */
-.De
-.IN "XcmsCIExyY" "" "@DEF@"
-.LP
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	XcmsFloat x; 	/* 0.0 to ~.75 */
-	XcmsFloat y; 	/* 0.0 to ~.85 */
-	XcmsFloat Y; 	/* 0.0 to 1.0 */
-} XcmsCIExyY;		/* CIE xyY */
-.De
-.IN "XcmsCIELab" "" "@DEF@"
-.LP
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	XcmsFloat L_star; 	/* 0.0 to 100.0 */
-	XcmsFloat a_star;
-	XcmsFloat b_star;
-} XcmsCIELab;		/* CIE L*a*b* */
-.De
-.IN "XcmsCIELuv" "" "@DEF@"
-.LP
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	XcmsFloat L_star; 	/* 0.0 to 100.0 */
-	XcmsFloat u_star;
-	XcmsFloat v_star;
-} XcmsCIELuv;		/* CIE L*u*v* */
-.De
-.IN "XcmsTekHVC" "" "@DEF@"
-.LP
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	XcmsFloat H; 	/* 0.0 to 360.0 */
-	XcmsFloat V; 	/* 0.0 to 100.0 */
-	XcmsFloat C; 	/* 0.0 to 100.0 */
-} XcmsTekHVC;		/* TekHVC */
-.De
-.IN "XcmsPad" "" "@DEF@"
-.LP
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	XcmsFloat pad0;
-	XcmsFloat pad1;
-	XcmsFloat pad2;
-	XcmsFloat pad3;
-} XcmsPad;		/* four doubles */
-.De
-.LP
-.eM
-The device-dependent formats provided allow color specification in:
-.IP \(bu 5
-RGB Intensity
-.Pn ( XcmsRGBi )
-.IP
-Red, green, and blue linear intensity values,
-floating-point values from 0.0 to 1.0,
-where 1.0 indicates full intensity, 0.5 half intensity, and so on.
-.IP \(bu 5
-RGB Device
-.Pn ( XcmsRGB )
-.IP
-Red, green, and blue values appropriate for the specified output device.
-.PN XcmsRGB
-values are of type unsigned short,
-scaled from 0 to 65535 inclusive,
-and are interchangeable with the red, green, and blue values in an 
-.PN XColor
-structure. 
-.LP
-It is important to note that RGB Intensity values are not gamma corrected
-values.
-In contrast,
-RGB Device values generated as a result of converting color specifications 
-are always gamma corrected, and
-RGB Device values acquired as a result of querying a colormap
-or passed in by the client are assumed by Xlib to be gamma corrected.
-The term \fIRGB value\fP in this manual always refers to an RGB Device value.
-.NH 2
-Color Strings
-.XS
-\*(SN Color Strings
-.XE
-.LP
-Xlib provides a mechanism for using string names for colors.
-A color string may either contain an abstract color name
-or a numerical color specification.
-Color strings are case-insensitive.
-.LP
-Color strings are used in the following functions:
-.IP \(bu 5
-.PN XAllocNamedColor
-.IP \(bu 5
-.PN XcmsAllocNamedColor
-.IP \(bu 5
-.PN XLookupColor
-.IP \(bu 5
-.PN XcmsLookupColor
-.IP \(bu 5
-.PN XParseColor
-.IP \(bu 5
-.PN XStoreNamedColor
-.LP
-Xlib supports the use of abstract color names, for example, red or blue.
-A value for this abstract name is obtained by searching one or more color
-name databases.
-Xlib first searches zero or more client-side databases;
-the number, location, and content of these databases is
-implementation-dependent and might depend on the current locale.
-If the name is not found, Xlib then looks for the color in the
-X server's database.
-If the color name is not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-.LP
-A numerical color specification
-consists of a color space name and a set of values in the following syntax:
-.LP
-.sM
-.Ds 0
-\fI<color_space_name>\fP:\fI<value>/.../<value>\fP
-.De
-.LP
-.eM
-The following are examples of valid color strings.
-.LP
-.Ds 0
-"CIEXYZ:0.3227/0.28133/0.2493"
-"RGBi:1.0/0.0/0.0"
-"rgb:00/ff/00"
-"CIELuv:50.0/0.0/0.0"
-.De
-The syntax and semantics of numerical specifications are given
-for each standard color space in the following sections.
-.NH 3
-RGB Device String Specification
-.XS
-\*(SN RGB Device String Specification
-.XE
-.LP
-An RGB Device specification is identified by
-the prefix ``rgb:'' and conforms to the following syntax:
-.LP
-.\" Start marker code here
-.Ds 0
-rgb:\fI<red>/<green>/<blue>\fP
-
-    \fI<red>\fP, \fI<green>\fP, \fI<blue>\fP := \fIh\fP | \fIhh\fP | \fIhhh\fP | \fIhhhh\fP
-    \fIh\fP := single hexadecimal digits (case insignificant)
-.De
-.\" End marker code here
-.LP
-Note that \fIh\fP indicates the value scaled in 4 bits, 
-\fIhh\fP the value scaled in 8 bits,
-\fIhhh\fP the value scaled in 12 bits,
-and \fIhhhh\fP the value scaled in 16 bits, respectively.
-.LP
-Typical examples are the strings ``rgb:ea/75/52'' and ``rgb:ccc/320/320'',
-but mixed numbers of hexadecimal digit strings 
-(``rgb:ff/a5/0'' and ``rgb:ccc/32/0'')
-are also allowed.
-.LP
-For backward compatibility, an older syntax for RGB Device is
-supported, but its continued use is not encouraged.
-The syntax is an initial sharp sign character followed by
-a numeric specification, in one of the following formats:
-.LP
-.\" Start marker code here
-.Ds 0
-.TA 2i
-.ta 2i
-#RGB	(4 bits each)
-#RRGGBB	(8 bits each)
-#RRRGGGBBB	(12 bits each)
-#RRRRGGGGBBBB	(16 bits each)
-.De
-.\" End marker code here
-.LP
-The R, G, and B represent single hexadecimal digits.
-When fewer than 16 bits each are specified, 
-they represent the most significant bits of the value
-(unlike the ``rgb:'' syntax, in which values are scaled).
-For example, the string ``#3a7'' is the same as ``#3000a0007000''.
-.NH 3
-RGB Intensity String Specification
-.XS
-\*(SN RGB Intensity String Specification
-.XE
-.LP
-An RGB intensity specification is identified
-by the prefix ``rgbi:'' and conforms to the following syntax:
-.LP
-.\" Start marker code here
-.Ds 0
-rgbi:\fI<red>/<green>/<blue>\fP
-.De
-.\" End marker code here
-.LP
-Note that red, green, and blue are floating-point values
-between 0.0 and 1.0, inclusive.
-The input format for these values is an optional sign,
-a string of numbers possibly containing a decimal point,
-and an optional exponent field containing an E or e 
-followed by a possibly signed integer string.
-.NH 3
-Device-Independent String Specifications
-.XS
-\*(SN Device-Independent String Specifications
-.XE
-.LP
-The standard device-independent string specifications have
-the following syntax:
-.LP
-.\" Start marker code here
-.Ds 0
-CIEXYZ:\fI<X>/<Y>/<Z>\fP
-CIEuvY:\fI<u>/<v>/<Y>\fP
-CIExyY:\fI<x>/<y>/<Y>\fP
-CIELab:\fI<L>/<a>/<b>\fP
-CIELuv:\fI<L>/<u>/<v>\fP
-TekHVC:\fI<H>/<V>/<C>\fP
-.De
-.\" End marker code here
-.LP
-All of the values (C, H, V, X, Y, Z, a, b, u, v, y, x) are
-floating-point values.
-The syntax for these values is an optional plus or minus sign,
-a string of digits possibly containing a decimal point,
-and an optional exponent field consisting of an ``E'' or ``e''
-followed by an optional plus or minus followed by a string of digits.
-.NH 2
-Color Conversion Contexts and Gamut Mapping
-.XS
-\*(SN Color Conversion Contexts and Gamut Mapping
-.XE
-.LP
-When Xlib converts device-independent color specifications
-into device-dependent specifications and vice versa,
-it uses knowledge about the color limitations of the screen hardware.
-This information, typically called the device profile,
-.IN "Device profile"
-is available in a Color Conversion Context (CCC).
-.IN "Color Conversion Context"
-.IN "CCC"
-.LP
-Because a specified color may be outside the color gamut of the target screen
-and the white point associated with the color specification may differ
-from the white point inherent to the screen,
-Xlib applies gamut mapping when it encounters certain conditions:
-.IN "White point"
-.IP \(bu 5
-Gamut compression occurs when conversion of device-independent
-color specifications to device-dependent color specifications
-results in a color out of the target screen's gamut.
-.IP \(bu 5
-White adjustment occurs when the inherent white point of the screen
-differs from the white point assumed by the client.
-.LP
-Gamut handling methods are stored as callbacks in the CCC,
-which in turn are used by the color space conversion routines.
-Client data is also stored in the CCC for each callback.
-The CCC also contains the white point the client assumes to be
-associated with color specifications (that is, the Client White Point).
-.IN "Client White Point"
-.IN "Gamut compression"
-.IN "Gamut handling"
-.IN "White point adjustment"
-The client can specify the gamut handling callbacks and client data
-as well as the Client White Point.
-Xlib does not preclude the X client from performing other
-forms of gamut handling (for example, gamut expansion); 
-however, Xlib does not provide direct support for gamut handling
-other than white adjustment and gamut compression.
-.LP
-Associated with each colormap is an initial CCC transparently generated by
-Xlib.
-.IN "Color Conversion Context" "creation"
-Therefore,
-when you specify a colormap as an argument to an Xlib function,
-you are indirectly specifying a CCC.
-.IN "CCC" "of colormap"
-.IN "Color Conversion Context" "of colormap"
-There is a default CCC associated with each screen.
-Newly created CCCs inherit attributes from the default CCC,
-so the default CCC attributes can be modified to affect new CCCs.
-.IN "CCC" "default"
-.IN "Color Conversion Context" "default"
-.LP
-Xcms functions in which gamut mapping can occur return
-.PN Status 
-and have specific status values defined for them, 
-as follows:
-.IP \(bu 5
-.PN XcmsFailure
-indicates that the function failed.
-.IP \(bu 5
-.PN XcmsSuccess
-indicates that the function succeeded.
-In addition,
-if the function performed any color conversion,
-the colors did not need to be compressed.
-.IP \(bu 5
-.PN XcmsSuccessWithCompression
-indicates the function performed color conversion
-and at least one of the colors needed to be compressed.
-The gamut compression method is determined by the gamut compression
-procedure in the CCC that is specified directly as a function argument
-or in the CCC indirectly specified by means of the colormap argument.
-.NH 2
-Creating, Copying, and Destroying Colormaps
-.XS
-\*(SN Creating, Copying, and Destroying Colormaps
-.XE
-.LP
-To create a colormap for a screen, use
-.PN XCreateColormap .
-.IN "XCreateColormap" "" "@DEF@"
-.sM
-.FD 0
-Colormap XCreateColormap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIvisual\fP\^, \fIalloc\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      Visual *\fIvisual\fP\^;
-.br
-      int \fIalloc\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Wi on whose screen you want to create a colormap
-.IP \fIw\fP 1i
-Specifies the window \*(Wi.
-.IP \fIvisual\fP 1i
-Specifies a visual type supported on the screen.
-If the visual type is not one supported by the screen, 
-a
-.PN BadMatch
-error results.
-.IP \fIalloc\fP 1i
-Specifies the colormap entries to be allocated.
-You can pass 
-.PN AllocNone 
-or 
-.PN AllocAll .
-.LP
-.eM
-The
-.PN XCreateColormap
-function creates a colormap of the specified visual type for the screen 
-on which the specified window resides and returns the colormap ID 
-associated with it.
-Note that the specified window is only used to determine the screen.
-.LP
-The initial values of the colormap entries are undefined for the 
-visual classes
-.PN GrayScale ,
-.PN PseudoColor ,
-and
-.PN DirectColor .
-For
-.PN StaticGray ,
-.PN StaticColor ,
-and
-.PN TrueColor ,
-the entries have defined values,
-but those values are specific to the visual and are not defined by X.
-For
-.PN StaticGray ,
-.PN StaticColor ,
-and
-.PN TrueColor ,
-alloc must be
-.PN AllocNone ,
-or a
-.PN BadMatch
-error results.
-For the other visual classes,
-if alloc is
-.PN AllocNone ,
-the colormap initially has no allocated entries,
-and clients can allocate them.
-For information about the visual types,
-see section 3.1.
-.LP
-If alloc is
-.PN AllocAll ,
-the entire colormap is allocated writable.
-The initial values of all allocated entries are undefined.
-For
-.PN GrayScale
-and
-.PN PseudoColor ,
-the effect is as if an
-.PN XAllocColorCells
-call returned all pixel values from zero to N \- 1,
-where N is the colormap entries value in the specified visual.
-For
-.PN DirectColor ,
-the effect is as if an
-.PN XAllocColorPlanes
-call returned a pixel value of zero and red_mask, green_mask, 
-and blue_mask values containing the same bits as the corresponding
-masks in the specified visual.
-However, in all cases,
-none of these entries can be freed by using
-.PN XFreeColors .
-.LP
-.PN XCreateColormap
-can generate
-.PN BadAlloc ,
-.PN BadMatch ,
-.PN BadValue ,
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To create a new colormap when the allocation out of a previously
-shared colormap has failed because of resource exhaustion, use
-.PN XCopyColormapAndFree .
-.IN "XCopyColormapAndFree" "" "@DEF@"
-.sM
-.FD 0
-Colormap XCopyColormapAndFree\^(\^\fIdisplay\fP, \fIcolormap\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.LP
-.eM
-The
-.PN XCopyColormapAndFree
-function creates a colormap of the same visual type and for the same screen
-as the specified colormap and returns the new colormap ID.
-It also moves all of the client's existing allocation from the specified
-colormap to the new colormap with their color values intact 
-and their read-only or writable characteristics intact and frees those entries 
-in the specified colormap.
-Color values in other entries in the new colormap are undefined.
-If the specified colormap was created by the client with alloc set to
-.PN AllocAll ,
-the new colormap is also created with 
-.PN AllocAll ,
-all color values for all entries are copied from the specified colormap,
-and then all entries in the specified colormap are freed.
-If the specified colormap was not created by the client with
-.PN AllocAll ,
-the allocations to be moved are all those pixels and planes
-that have been allocated by the client using
-.PN XAllocColor ,
-.PN XAllocNamedColor ,
-.PN XAllocColorCells ,
-or
-.PN XAllocColorPlanes
-and that have not been freed since they were allocated.
-.LP
-.PN XCopyColormapAndFree
-can generate
-.PN BadAlloc
-and
-.PN BadColor 
-errors.
-.LP
-.sp
-To destroy a colormap, use 
-.PN XFreeColormap .
-.IN "XFreeColormap" "" "@DEF@"
-.sM
-.FD 0
-XFreeColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Cm that you want to destroy
-.IP \fIcolormap\fP 1i
-Specifies the colormap \*(Cm.
-.LP
-.eM
-The
-.PN XFreeColormap
-function deletes the association between the colormap resource ID 
-and the colormap and frees the colormap storage.
-However, this function has no effect on the default colormap for a screen.
-If the specified colormap is an installed map for a screen,
-it is uninstalled (see
-.PN XUninstallColormap ).
-If the specified colormap is defined as the colormap for a window (by
-.PN XCreateWindow ,
-.PN XSetWindowColormap ,
-or
-.PN XChangeWindowAttributes ),
-.PN XFreeColormap
-changes the colormap associated with the window to
-.PN None 
-and generates a
-.PN ColormapNotify
-event.
-X does not define the colors displayed for a window with a colormap of
-.PN None .
-.LP
-.PN XFreeColormap
-can generate a
-.PN BadColor 
-error.
-.NH 2
-Mapping Color Names to Values
-.XS
-\*(SN Mapping Color Names to Values
-.XE
-.LP
-.sp
-To map a color name to an RGB value, use
-.PN XLookupColor .
-.IN "Color" "naming"
-.IN "XLookupColor" "" "@DEF@"
-.sM
-.FD 0
-Status XLookupColor\^(\^\fIdisplay\fP, \fIcolormap\fP, \fIcolor_name\fP, \
-\fIexact_def_return\fP\^, \fIscreen_def_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.br
-      char *\fIcolor_name\fP\^;
-.br
-      XColor *\fIexact_def_return\fP\^, *\fIscreen_def_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.IP \fIcolor_name\fP 1i
-Specifies the color name string (for example, red) whose color 
-definition structure you want returned.
-.IP \fIexact_def_return\fP 1i
-Returns the exact RGB values.
-.IP \fIscreen_def_return\fP 1i
-Returns the closest RGB values provided by the hardware.
-.LP
-.eM
-The
-.PN XLookupColor
-function looks up the string name of a color with respect to the screen
-associated with the specified colormap.
-It returns both the exact color values and
-the closest values provided by the screen 
-with respect to the visual type of the specified colormap.
-If the color name is not in the Host Portable Character Encoding, 
-the result is implementation-dependent.
-Use of uppercase or lowercase does not matter.
-.PN XLookupColor
-returns nonzero if the name is resolved;
-otherwise, it returns zero.
-.LP
-.PN XLookupColor
-can generate a
-.PN BadColor 
-error.
-.LP
-.sp
-To map a color name to the exact RGB value, use
-.PN XParseColor .
-.IN "Color" "naming"
-.IN "XParseColor" "" "@DEF@"
-.sM
-.FD 0
-Status XParseColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \^\fIspec\fP\^, \fIexact_def_return\fP\^)
-.br
-        Display *\fIdisplay\fP\^;
-.br
-        Colormap \fIcolormap\fP\^;
-.br
-        char *\fIspec\fP\^;
-.br
-        XColor *\fIexact_def_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.IP \fIspec\fP 1i
-Specifies the color name string;
-case is ignored.
-.IP \fIexact_def_return\fP 1i
-Returns the exact color value for later use and sets the
-.PN DoRed ,
-.PN DoGreen ,
-and
-.PN DoBlue
-flags.
-.LP
-.eM 
-The
-.PN XParseColor
-function looks up the string name of a color with respect to the screen
-associated with the specified colormap.
-It returns the exact color value.
-If the color name is not in the Host Portable Character Encoding, 
-the result is implementation-dependent.
-Use of uppercase or lowercase does not matter.
-.PN XParseColor
-returns nonzero if the name is resolved;
-otherwise, it returns zero.
-.LP
-.PN XParseColor
-can generate a
-.PN BadColor 
-error.
-.LP
-.sp
-To map a color name to a value in an arbitrary color space, use
-.PN XcmsLookupColor .
-.IN "Color" "naming"
-.IN "XcmsLookupColor" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsLookupColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor_string\fP\^, \fIcolor_exact_return\fP\^, \fIcolor_screen_return\fP\^,
-.br
-			 \fIresult_format\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.br
-      char *\fIcolor_string\fP\^;
-.br
-      XcmsColor *\fIcolor_exact_return\fP\^, *\fIcolor_screen_return\fP\^;
-.br
-      XcmsColorFormat \fIresult_format\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.ds St
-.IP \fIcolor_string\fP 1i
-Specifies the color string\*(St.
-.IP \fIcolor_exact_return\fP 1i
-Returns the color specification parsed from the color string
-or parsed from the corresponding string found in a color-name database.
-.IP \fIcolor_screen_return\fP 1i
-Returns the color that can be reproduced on the screen.
-.IP \fIresult_format\fP 1i
-Specifies the color format for the returned color
-specifications (color_screen_return and color_exact_return arguments).
-If the format is
-.PN XcmsUndefinedFormat
-and the color string contains a
-numerical color specification,
-the specification is returned in the format used in that numerical
-color specification.
-If the format is
-.PN XcmsUndefinedFormat
-and the color string contains a color name,
-the specification is returned in the format used 
-to store the color in the database.
-.LP
-.eM
-The
-.PN XcmsLookupColor
-function looks up the string name of a color with respect to the screen
-associated with the specified colormap.
-It returns both the exact color values and
-the closest values provided by the screen 
-with respect to the visual type of the specified colormap.
-The values are returned in the format specified by result_format.
-If the color name is not in the Host Portable Character Encoding, 
-the result is implementation-dependent.
-Use of uppercase or lowercase does not matter.
-.PN XcmsLookupColor
-returns
-.PN XcmsSuccess
-or
-.PN XcmsSuccessWithCompression
-if the name is resolved; otherwise, it returns
-.PN XcmsFailure .
-If
-.PN XcmsSuccessWithCompression
-is returned, the color specification returned in 
-color_screen_return is the result of gamut compression.
-.NH 2
-Allocating and Freeing Color Cells
-.XS
-\*(SN Allocating and Freeing Color Cells
-.XE
-.LP
-There are two ways of allocating color cells: 
-explicitly as read-only entries, one pixel value at a time,
-or read/write,
-where you can allocate a number of color cells and planes simultaneously.
-.IN "Read-only colormap cells"
-A read-only cell has its RGB value set by the server.
-.IN "Read/write colormap cells"
-Read/write cells do not have defined colors initially;
-functions described in the next section must be used to store values into them.
-Although it is possible for any client to store values into a read/write
-cell allocated by another client,
-read/write cells normally should be considered private to the client
-that allocated them.
-.LP
-Read-only colormap cells are shared among clients.
-The server counts each allocation and freeing of the cell by clients.
-When the last client frees a shared cell, the cell is finally deallocated.
-If a single client allocates the same read-only cell multiple
-times, the server counts each such allocation, not just the first one.
-.LP
-.sp
-To allocate a read-only color cell with an RGB value, use
-.PN XAllocColor .
-.IN "Allocation" "read-only colormap cells"
-.IN "Read-only colormap cells" "allocating"
-.IN "Color" "allocation"
-.IN "XAllocColor" "" "@DEF@"
-.sM
-.FD 0
-Status XAllocColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIscreen_in_out\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.br
-      XColor *\fIscreen_in_out\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.IP \fIscreen_in_out\fP 1i
-Specifies and returns the values actually used in the colormap.
-.LP
-.eM
-The
-.PN XAllocColor
-function allocates a read-only colormap entry corresponding to the closest
-RGB value supported by the hardware.
-.PN XAllocColor
-returns the pixel value of the color closest to the specified
-RGB elements supported by the hardware
-and returns the RGB value actually used.
-The corresponding colormap cell is read-only.
-In addition,
-.PN XAllocColor
-returns nonzero if it succeeded or zero if it failed.
-.IN "Color map"
-.IN "Color" "allocation"
-.IN "Allocation" "colormap"
-.IN "read-only colormap cells"
-Multiple clients that request the same effective RGB value can be assigned
-the same read-only entry, thus allowing entries to be shared.
-When the last client deallocates a shared cell, it is deallocated.
-.PN XAllocColor
-does not use or affect the flags in the
-.PN XColor
-structure.
-.LP
-.PN XAllocColor
-can generate a
-.PN BadColor 
-error.
-.EQ
-delim %%
-.EN
-.LP
-.sp
-To allocate a read-only color cell with a color in arbitrary format, use
-.PN XcmsAllocColor .
-.IN "Allocation" "read-only colormap cells"
-.IN "Read-only colormap cells" "allocating"
-.IN "Color" "allocation"
-.IN "XcmsAllocColor" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsAllocColor\^(\^\fIdisplay\fP\^, \fIcolormap\fP\^, \fIcolor_in_out\fP\^, \fIresult_format\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.br
-      XcmsColor *\fIcolor_in_out\fP\^;
-.br
-      XcmsColorFormat \fIresult_format\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.IP \fIcolor_in_out\fP 1i
-Specifies the color to allocate and returns the pixel and color 
-that is actually used in the colormap.
-.IP \fIresult_format\fP 1i
-Specifies the color format for the returned color specification.
-.LP
-.eM
-The
-.PN XcmsAllocColor
-function is similar to
-.PN XAllocColor
-except the color can be specified in any format.
-The
-.PN XcmsAllocColor
-function ultimately calls 
-.PN XAllocColor
-to allocate a read-only color cell (colormap entry) with the specified color.
-.PN XcmsAllocColor
-first converts the color specified
-to an RGB value and then passes this to
-.PN XAllocColor .
-.PN XcmsAllocColor
-returns the pixel value of the color cell and the color specification
-actually allocated.
-This returned color specification is the result of converting the RGB value
-returned by 
-.PN XAllocColor 
-into the format specified with the result_format argument.
-If there is no interest in a returned color specification, 
-unnecessary computation can be bypassed if result_format is set to
-.PN XcmsRGBFormat .
-The corresponding colormap cell is read-only.
-If this routine returns 
-.PN XcmsFailure , 
-the color_in_out color specification is left unchanged.
-.LP
-.PN XcmsAllocColor
-can generate a
-.PN BadColor
-error.
-.LP
-.sp
-To allocate a read-only color cell using a color name and return the closest
-color supported by the hardware in RGB format, use
-.PN XAllocNamedColor .
-.IN "Allocation" "read-only colormap cells"
-.IN "Read-only colormap cells" "allocating"
-.IN "Color" "naming"
-.IN "Color" "allocation"
-.IN "XAllocNamedColor" "" "@DEF@"
-.sM
-.FD 0
-Status XAllocNamedColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \
-\fIcolor_name\fP\^, \fIscreen_def_return\fP\^, \fIexact_def_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.br
-      char *\fIcolor_name\fP\^;
-.br
-      XColor *\fIscreen_def_return\fP\^, *\fIexact_def_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.IP \fIcolor_name\fP 1i
-Specifies the color name string (for example, red) whose color 
-definition structure you want returned.
-.IP \fIscreen_def_return\fP 1i
-Returns the closest RGB values provided by the hardware.
-.IP \fIexact_def_return\fP 1i
-Returns the exact RGB values.
-.LP
-.eM 
-The
-.PN XAllocNamedColor
-function looks up the named color with respect to the screen that is
-associated with the specified colormap.
-It returns both the exact database definition and
-the closest color supported by the screen.
-The allocated color cell is read-only.
-The pixel value is returned in screen_def_return.
-If the color name is not in the Host Portable Character Encoding, 
-the result is implementation-dependent.
-Use of uppercase or lowercase does not matter.
-If screen_def_return and exact_def_return
-point to the same structure, the pixel field will be set correctly,
-but the color values are undefined.
-.PN XAllocNamedColor
-returns nonzero if a cell is allocated;
-otherwise, it returns zero.
-.LP
-.PN XAllocNamedColor
-can generate a
-.PN BadColor
-error. 
-.LP
-.sp
-To allocate a read-only color cell using a color name and return the closest
-color supported by the hardware in an arbitrary format, use
-.PN XcmsAllocNamedColor .
-.IN "Allocation" "read-only colormap cells"
-.IN "Read-only colormap cells" "allocating"
-.IN "Color" "naming"
-.IN "Color" "allocation"
-.IN "XcmsAllocNamedColor" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsAllocNamedColor\^(\^\fIdisplay\fP\^, \fIcolormap\fP\^, \fIcolor_string\fP\^, \fIcolor_screen_return\fP\^, \fIcolor_exact_return\fP\^,
-.br
-                            \fIresult_format\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.br
-      char *\fIcolor_string\fP\^;
-.br
-      XcmsColor *\fIcolor_screen_return\fP\^;
-.br
-      XcmsColor *\fIcolor_exact_return\fP\^;
-.br
-      XcmsColorFormat \fIresult_format\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.ds St \ whose color definition structure is to be returned
-.IP \fIcolor_string\fP 1i
-Specifies the color string\*(St.
-.IP \fIcolor_screen_return\fP 1i
-Returns the pixel value of the color cell and color specification 
-that actually is stored for that cell.
-.IP \fIcolor_exact_return\fP 1i
-Returns the color specification parsed from the color string
-or parsed from the corresponding string found in a color-name database.
-.IP \fIresult_format\fP 1i
-Specifies the color format for the returned color
-specifications (color_screen_return and color_exact_return arguments).
-If the format is
-.PN XcmsUndefinedFormat
-and the color string contains a
-numerical color specification,
-the specification is returned in the format used in that numerical
-color specification.
-If the format is
-.PN XcmsUndefinedFormat
-and the color string contains a color name,
-the specification is returned in the format used 
-to store the color in the database.
-.LP
-.eM
-The
-.PN XcmsAllocNamedColor
-function is similar to
-.PN XAllocNamedColor
-except that the color returned can be in any format specified.
-This function
-ultimately calls
-.PN XAllocColor
-to allocate a read-only color cell with
-the color specified by a color string.
-The color string is parsed into an
-.PN XcmsColor
-structure (see
-.PN XcmsLookupColor ),
-converted
-to an RGB value, and finally passed to
-.PN XAllocColor .
-If the color name is not in the Host Portable Character Encoding, 
-the result is implementation-dependent.
-Use of uppercase or lowercase does not matter.
-.LP
-This function returns both the color specification as a result
-of parsing (exact specification) and the actual color specification
-stored (screen specification).
-This screen specification is the result of converting the RGB value
-returned by
-.PN XAllocColor
-into the format specified in result_format.
-If there is no interest in a returned color specification,
-unnecessary computation can be bypassed if result_format is set to
-.PN XcmsRGBFormat .
-If color_screen_return and color_exact_return
-point to the same structure, the pixel field will be set correctly,
-but the color values are undefined.
-.LP
-.PN XcmsAllocNamedColor
-can generate a
-.PN BadColor
-error.
-.LP
-.sp
-To allocate read/write color cell and color plane combinations for a
-.PN PseudoColor
-model, use
-.PN XAllocColorCells .
-.IN "Read/write colormap cells" "allocating"
-.IN "Allocation" "read/write colormap cells"
-.IN "Color" "allocation"
-.IN "XAllocColorCells" "" "@DEF@"
-.sM
-.FD 0
-Status XAllocColorCells\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcontig\fP\^, \
-\fIplane_masks_return\fP\^, \fInplanes\fP\^, 
-.br
-                          \fIpixels_return\fP\^, \fInpixels\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.br
-      Bool \fIcontig\fP\^;
-.br
-      unsigned long \fIplane_masks_return\fP[\^]\^;
-.br
-      unsigned int \fInplanes\fP\^;
-.br
-      unsigned long \fIpixels_return\fP[\^]\^;
-.br
-      unsigned int \fInpixels\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.IP \fIcontig\fP 1i
-Specifies a Boolean value that indicates whether the planes must be contiguous.
-.IP \fIplane_mask_return\fP 1i
-Returns an array of plane masks.
-.\" *** JIM: NEED MORE INFO FOR THIS. ***
-.IP \fInplanes\fP 1i
-Specifies the number of plane masks that are to be returned in the plane masks 
-array. 
-.IP \fIpixels_return\fP 1i
-Returns an array of pixel values. 
-.IP \fInpixels\fP 1i
-Specifies the number of pixel values that are to be returned in the 
-pixels_return array. 
-.LP
-.eM
-.EQ
-delim %%
-.EN
-The
-.PN XAllocColorCells
-function allocates read/write color cells.
-The number of colors must be positive and the number of planes nonnegative,
-or a
-.PN BadValue
-error results.
-If ncolors and nplanes are requested, 
-then ncolors pixels
-and nplane plane masks are returned.
-No mask will have any bits set to 1 in common with
-any other mask or with any of the pixels.
-By ORing together each pixel with zero or more masks,
-ncolors * %2 sup nplanes% distinct pixels can be produced.
-All of these are
-allocated writable by the request.
-For 
-.PN GrayScale 
-or 
-.PN PseudoColor , 
-each mask has exactly one bit set to 1. 
-For 
-.PN DirectColor , 
-each has exactly three bits set to 1.
-If contig is 
-.PN True 
-and if all masks are ORed
-together, a single contiguous set of bits set to 1 will be formed for 
-.PN GrayScale
-or 
-.PN PseudoColor 
-and three contiguous sets of bits set to 1 (one within each
-pixel subfield) for 
-.PN DirectColor .
-The RGB values of the allocated
-entries are undefined.
-.PN XAllocColorCells
-returns nonzero if it succeeded or zero if it failed.
-.LP
-.PN XAllocColorCells
-can generate
-.PN BadColor
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-To allocate read/write color resources for a
-.PN DirectColor
-model, use
-.PN XAllocColorPlanes .
-.IN "Read/write colormap planes" "allocating"
-.IN "Allocation" "read/write colormap planes"
-.IN "Color" "allocation"
-.IN "XAllocColorPlanes" "" "@DEF@"
-.sM
-.FD 0
-Status XAllocColorPlanes\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcontig\fP\^, \fIpixels_return\fP\^, \fIncolors\fP\^, \fInreds\fP\^, \fIngreens\fP\^, 
-.br
-                           \fInblues\fP\^, \fIrmask_return\fP\^, \fIgmask_return\fP\^, \fIbmask_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.br
-      Bool \fIcontig\fP\^;
-.br
-      unsigned long \fIpixels_return\fP[\^]\^;
-.br
-      int \fIncolors\fP\^;
-.br
-      int \fInreds\fP\^, \fIngreens\fP\^, \fInblues\fP\^;
-.br
-      unsigned long *\fIrmask_return\fP\^, *\fIgmask_return\fP\^, *\fIbmask_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.IP \fIcontig\fP 1i
-Specifies a Boolean value that indicates whether the planes must be contiguous.
-.IP \fIpixels_return\fP 1i
-Returns an array of pixel values. 
-.PN XAllocColorPlanes
-returns the pixel values in this array.
-.IP \fIncolors\fP 1i
-Specifies the number of pixel values that are to be returned in the 
-pixels_return array. 
-.IP \fInreds\fP 1i
-.br
-.ns
-.IP \fIngreens\fP 1i
-.br
-.ns
-.IP \fInblues\fP 1i
-.br
-.ns
-Specify the number of red, green, and blue planes.
-The value you pass must be nonnegative. 
-.IP \fIrmask_return\fP 1i
-.br
-.ns
-.IP \fIgmask_return\fP 1i
-.br
-.ns
-.IP \fIbmask_return\fP 1i
-Return bit masks for the red, green, and blue planes.
-.LP
-.eM
-.EQ
-delim %%
-.EN
-The specified ncolors must be positive; 
-and nreds, ngreens, and nblues must be nonnegative,
-or a
-.PN BadValue
-error results.
-If ncolors colors, nreds reds, ngreens greens, and nblues blues are requested, 
-ncolors pixels are returned; and the masks have nreds, ngreens, and 
-nblues bits set to 1, respectively.
-If contig is 
-.PN True , 
-each mask will have
-a contiguous set of bits set to 1.
-No mask will have any bits set to 1 in common with
-any other mask or with any of the pixels.
-For 
-.PN DirectColor , 
-each mask
-will lie within the corresponding pixel subfield.
-By ORing together
-subsets of masks with each pixel value, 
-ncolors * %2 sup (nreds+ngreens+nblues)% distinct pixel values can be produced. 
-All of these are allocated by the request.
-However, in the
-colormap, there are only ncolors * %2 sup nreds% independent red entries, 
-ncolors * %2 sup ngreens% independent green entries, 
-and ncolors * %2 sup nblues% independent blue entries. 
-This is true even for 
-.PN PseudoColor .
-When the colormap entry of a pixel
-value is changed (using 
-.PN XStoreColors ,
-.PN XStoreColor ,
-or 
-.PN XStoreNamedColor ),
-the pixel is decomposed according to the masks, 
-and the corresponding independent entries are updated.
-.PN XAllocColorPlanes
-returns nonzero if it succeeded or zero if it failed.
-.LP
-.PN XAllocColorPlanes
-can generate
-.PN BadColor
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-.IN "Freeing" "colors"
-To free colormap cells, use
-.PN XFreeColors .
-.IN "XFreeColors" "" "@DEF@"
-.IN "Color" "deallocation"
-.sM
-.FD 0
-XFreeColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIpixels\fP\^, \fInpixels\fP\^, \fIplanes\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.br
-      unsigned long \fIpixels\fP\^[\^];
-.br
-      int \fInpixels\fP\^;
-.br
-      unsigned long \fIplanes\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.ds Pi that map to the cells in the specified colormap
-.IP \fIpixels\fP 1i
-Specifies an array of pixel values \*(Pi. 
-.IP \fInpixels\fP 1i
-Specifies the number of pixels. 
-.IP \fIplanes\fP 1i
-Specifies the planes you want to free.
-.LP
-.eM
-The
-.PN XFreeColors
-function frees the cells represented by pixels whose values are in the
-pixels array.
-The planes argument should not have any bits set to 1 in common with any of the
-pixels. 
-The set of all pixels is produced by ORing together subsets of
-the planes argument with the pixels.
-The request frees all of these pixels that
-were allocated by the client (using 
-.IN XAllocColor
-.IN XAllocNamedColor
-.IN XAllocColorCells
-.IN XAllocColorPlanes
-.PN XAllocColor , 
-.PN XAllocNamedColor ,
-.PN XAllocColorCells ,
-and 
-.PN XAllocColorPlanes ).
-Note that freeing an
-individual pixel obtained from 
-.PN XAllocColorPlanes 
-may not actually allow
-it to be reused until all of its related pixels are also freed.
-Similarly,
-a read-only entry is not actually freed until it has been freed by all clients,
-and if a client allocates the same read-only entry multiple times,
-it must free the entry that many times before the entry is actually freed.
-.LP
-All specified pixels that are allocated by the client in the colormap are
-freed, even if one or more pixels produce an error. 
-If a specified pixel is not a valid index into the colormap, a 
-.PN BadValue 
-error results.
-If a specified pixel is not allocated by the
-client (that is, is unallocated or is only allocated by another client)
-or if the colormap was created with all entries writable (by passing
-.PN AllocAll
-to
-.PN XCreateColormap ),
-a
-.PN BadAccess
-error results. 
-If more than one pixel is in error, 
-the one that gets reported is arbitrary.
-.LP
-.PN XFreeColors
-can generate
-.PN BadAccess ,
-.PN BadColor ,
-and
-.PN BadValue 
-errors.
-.NH 2
-Modifying and Querying Colormap Cells
-.XS
-\*(SN Modifying and Querying Colormap Cells 
-.XE
-.LP
-.sp
-To store an RGB value in a single colormap cell, use
-.PN XStoreColor .
-.IN "Color" "storing"
-.IN "XStoreColor" "" "@DEF@"
-.sM
-.FD 0
-XStoreColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.br
-      XColor *\fIcolor\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.IP \fIcolor\fP 1i
-Specifies the pixel and RGB values.
-.LP
-.eM
-The
-.PN XStoreColor
-function changes the colormap entry of the pixel value specified in the
-pixel member of the
-.PN XColor
-structure.
-You specified this value in the
-pixel member of the
-.PN XColor
-structure.
-This pixel value must be a read/write cell and a valid index into the colormap.
-If a specified pixel is not a valid index into the colormap,
-a
-.PN BadValue
-error results.
-.PN XStoreColor
-also changes the red, green, and/or blue color components.
-You specify which color components are to be changed by setting
-.PN DoRed ,
-.PN DoGreen ,
-and/or
-.PN DoBlue
-in the flags member of the
-.PN XColor
-structure.
-If the colormap is an installed map for its screen, 
-the changes are visible immediately.
-.LP
-.PN XStoreColor
-can generate
-.PN BadAccess ,
-.PN BadColor ,
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-To store multiple RGB values in multiple colormap cells, use
-.PN XStoreColors .
-.IN "Color" "storing"
-.IN "XStoreColors" "" "@DEF@"
-.sM
-.FD 0
-XStoreColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^, \fIncolors\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.br
-      XColor \fIcolor\fP\^[\^]\^;
-.br
-      int \fIncolors\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.IP \fIcolor\fP 1i
-Specifies an array of color definition structures to be stored.
-.IP \fIncolors\fP 1i
-.\"Specifies the number of color definition structures. 
-Specifies the number of 
-.PN XColor
-structures in the color definition array.
-.LP
-.eM
-The
-.PN XStoreColors
-function changes the colormap entries of the pixel values
-specified in the pixel members of the
-.PN XColor
-structures.
-You specify which color components are to be changed by setting 
-.PN DoRed ,
-.PN DoGreen ,
-and/or
-.PN DoBlue
-in the flags member of the
-.PN XColor
-structures.
-If the colormap is an installed map for its screen, the
-changes are visible immediately.
-.PN XStoreColors 
-changes the specified pixels if they are allocated writable in the colormap 
-by any client, even if one or more pixels generates an error.
-If a specified pixel is not a valid index into the colormap, a
-.PN BadValue
-error results.
-If a specified pixel either is unallocated or is allocated read-only, a
-.PN BadAccess
-error results.
-If more than one pixel is in error, 
-the one that gets reported is arbitrary.
-.LP
-.PN XStoreColors
-can generate
-.PN BadAccess ,
-.PN BadColor ,
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-To store a color of arbitrary format in a single colormap cell, use
-.PN XcmsStoreColor .
-.IN "Color" "storing"
-.IN "XcmsStoreColor" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsStoreColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.br
-      XcmsColor *\fIcolor\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.IP \fIcolor\fP 1i
-Specifies the color cell and the color to store.
-Values specified in this
-.PN XcmsColor
-structure remain unchanged on return.
-.LP
-.eM
-The
-.PN XcmsStoreColor
-function converts the color specified in the
-.PN XcmsColor
-structure into RGB values.
-It then uses this RGB specification in an
-.PN XColor
-structure, whose three flags 
-.Pn ( DoRed , 
-.PN DoGreen ,
-and
-.PN DoBlue )
-are set, in a call to
-.PN XStoreColor
-to change the color cell specified by the pixel member of the
-.PN XcmsColor
-structure.
-This pixel value must be a valid index for the specified colormap,
-and the color cell specified by the pixel value must be a read/write cell.
-If the pixel value is not a valid index, a
-.PN BadValue
-error results.
-If the color cell is unallocated or is allocated read-only, a
-.PN BadAccess
-error results.
-If the colormap is an installed map for its screen, 
-the changes are visible immediately.
-.LP
-Note that 
-.PN XStoreColor
-has no return value; therefore, an
-.PN XcmsSuccess
-return value from this function indicates that the conversion 
-to RGB succeeded and the call to
-.PN XStoreColor
-was made.
-To obtain the actual color stored, use
-.PN XcmsQueryColor .
-Because of the screen's hardware limitations or gamut compression,
-the color stored in the colormap may not be identical
-to the color specified.
-.LP
-.PN XcmsStoreColor
-can generate
-.PN BadAccess ,
-.PN BadColor ,
-and
-.PN BadValue
-errors.
-.LP
-.sp
-To store multiple colors of arbitrary format in multiple colormap cells, use
-.PN XcmsStoreColors .
-.IN "Color" "storing"
-.IN "XcmsStoreColors" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsStoreColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolors\fP\^, \fIncolors\fP\^, \fIcompression_flags_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.br
-      XcmsColor \fIcolors\fP\^[\^]\^;
-.br
-      int \fIncolors\fP\^;
-.br
-      Bool \fIcompression_flags_return\fP\^[\^]\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.IP \fIcolors\fP 1i
-Specifies the color specification array of
-.PN XcmsColor
-structures, each specifying a color cell and the color to store in that
-cell.
-Values specified in the array remain unchanged upon return.
-.IP \fIncolors\fP 1i
-Specifies the number of 
-.PN XcmsColor
-structures in the color-specification array.
-.IP \fIcompression_flags_return\fP 1i
-Returns an array of Boolean values indicating compression status.
-If a non-NULL pointer is supplied,
-each element of the array is set to
-.PN True
-if the corresponding color was compressed and
-.PN False
-otherwise.
-Pass NULL if the compression status is not useful.
-.LP
-.eM
-The
-.PN XcmsStoreColors
-function converts the colors specified in the array of
-.PN XcmsColor
-structures into RGB values and then uses these RGB specifications in
-.PN XColor
-structures, whose three flags 
-.Pn ( DoRed , 
-.PN DoGreen ,
-and
-.PN DoBlue )
-are set, in a call to
-.PN XStoreColors
-to change the color cells specified by the pixel member of the corresponding
-.PN XcmsColor
-structure.
-Each pixel value must be a valid index for the specified colormap,
-and the color cell specified by each pixel value must be a read/write cell.
-If a pixel value is not a valid index, a
-.PN BadValue
-error results.
-If a color cell is unallocated or is allocated read-only, a
-.PN BadAccess
-error results.
-If more than one pixel is in error,
-the one that gets reported is arbitrary.
-If the colormap is an installed map for its screen, 
-the changes are visible immediately.
-.LP
-Note that 
-.PN XStoreColors
-has no return value; therefore, an
-.PN XcmsSuccess
-return value from this function indicates that conversions 
-to RGB succeeded and the call to
-.PN XStoreColors
-was made.
-To obtain the actual colors stored, use
-.PN XcmsQueryColors .
-Because of the screen's hardware limitations or gamut compression,
-the colors stored in the colormap may not be identical
-to the colors specified.
-.LP
-.PN XcmsStoreColors
-can generate
-.PN BadAccess ,
-.PN BadColor ,
-and
-.PN BadValue
-errors.
-.LP
-.sp
-To store a color specified by name in a single colormap cell, use
-.PN XStoreNamedColor .
-.IN "Color" "storing"
-.IN "Color" "naming"
-.IN "XStoreNamedColor" "" "@DEF@"
-.sM
-.FD 0
-XStoreNamedColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^, \fIpixel\fP\^, \fIflags\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.br
-      char *\^\fIcolor\fP\^;
-.br
-      unsigned long \fIpixel\fP\^;
-.br
-      int \fIflags\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.IP \fIcolor\fP 1i
-Specifies the color name string (for example, red). 
-.IP \fIpixel\fP 1i
-Specifies the entry in the colormap. 
-.IP \fIflags\fP 1i
-Specifies which red, green, and blue components are set.
-.LP
-.eM 
-The
-.PN XStoreNamedColor
-function looks up the named color with respect to the screen associated with
-the colormap and stores the result in the specified colormap.
-The pixel argument determines the entry in the colormap.
-The flags argument determines which of the red, green, and blue components 
-are set. 
-You can set this member to the
-bitwise inclusive OR of the bits 
-.PN DoRed , 
-.PN DoGreen , 
-and 
-.PN DoBlue .
-If the color name is not in the Host Portable Character Encoding, 
-the result is implementation-dependent.
-Use of uppercase or lowercase does not matter.
-If the specified pixel is not a valid index into the colormap, a
-.PN BadValue
-error results.
-If the specified pixel either is unallocated or is allocated read-only, a
-.PN BadAccess
-error results.
-.LP
-.PN XStoreNamedColor
-can generate
-.PN BadAccess ,
-.PN BadColor ,
-.PN BadName ,
-and 
-.PN BadValue 
-errors.
-.LP
-The
-.PN XQueryColor
-and
-.PN XQueryColors
-functions take pixel values in the pixel member of
-.PN XColor
-structures and store in the structures the RGB values for those
-pixels from the specified colormap.
-The values returned for an unallocated entry are undefined.
-These functions also set the flags member in the
-.PN XColor
-structure to all three colors.
-If a pixel is not a valid index into the specified colormap, a
-.PN BadValue
-error results.
-If more than one pixel is in error,
-the one that gets reported is arbitrary.
-.LP
-.sp
-To query the RGB value of a single colormap cell, use
-.PN XQueryColor .
-.IN "Color" "querying"
-.IN "XQueryColor" "" "@DEF@"
-.sM
-.FD 0
-XQueryColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIdef_in_out\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.br
-      XColor *\fIdef_in_out\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.IP \fIdef_in_out\fP 1i
-Specifies and returns the RGB values for the pixel specified in the structure.
-.LP
-.eM
-The
-.PN XQueryColor
-function returns the current RGB value for the pixel in the
-.PN XColor
-structure and sets the
-.PN DoRed ,
-.PN DoGreen ,
-and
-.PN DoBlue
-flags.
-.LP
-.PN XQueryColor
-can generate
-.PN BadColor
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-To query the RGB values of multiple colormap cells, use
-.PN XQueryColors .
-.IN "Color" "querying"
-.IN "XQueryColors" "" "@DEF@"
-.sM
-.FD 0
-XQueryColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIdefs_in_out\fP\^, \fIncolors\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.br
-      XColor \fIdefs_in_out\fP[\^]\^;
-.br
-      int \fIncolors\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.IP \fIdefs_in_out\fP 1i
-Specifies and returns an array of color definition structures for the pixel
-specified in the structure.
-.IP \fIncolors\fP 1i
-.\"Specifies the number of color definition structures. 
-Specifies the number of 
-.PN XColor
-structures in the color definition array.
-.LP
-.eM
-The
-.PN XQueryColors
-function returns the RGB value for each pixel in each
-.PN XColor
-structure and sets the
-.PN DoRed ,
-.PN DoGreen ,
-and
-.PN DoBlue
-flags in each structure.
-
-.LP
-.PN XQueryColors
-can generate
-.PN BadColor
-and
-.PN BadValue 
-errors.
-.sp
-.LP
-To query the color of a single colormap cell in an arbitrary format, use
-.PN XcmsQueryColor .
-.IN "Color" "querying"
-.IN "XcmsQueryColor" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsQueryColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor_in_out\fP\^, \fIresult_format\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.br
-      XcmsColor *\fIcolor_in_out\fP\^;
-.br
-      XcmsColorFormat \fIresult_format\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.IP \fIcolor_in_out\fP 1i
-Specifies the pixel member that indicates the color cell to query.
-The color specification stored for the color cell is returned in this
-.PN XcmsColor
-structure.
-.IP \fIresult_format\fP 1i
-Specifies the color format for the returned color specification.
-.LP
-.eM
-The
-.PN XcmsQueryColor
-function obtains the RGB value
-for the pixel value in the pixel member of the specified
-.PN XcmsColor
-structure and then
-converts the value to the target format as
-specified by the result_format argument.
-If the pixel is not a valid index in the specified colormap, a
-.PN BadValue
-error results.
-.LP
-.PN XcmsQueryColor
-can generate
-.PN BadColor
-and
-.PN BadValue
-errors.
-.sp
-.LP
-To query the color of multiple colormap cells in an arbitrary format, use
-.PN XcmsQueryColors .
-.IN "Color" "querying"
-.IN "XcmsQueryColors" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsQueryColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fIresult_format\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.br
-      XcmsColor \fIcolors_in_out\fP\^[\^]\^;
-.br
-      unsigned int \fIncolors\fP\^;
-.br
-      XcmsColorFormat \fIresult_format\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.IP \fIcolors_in_out\fP 1i
-Specifies an array of
-.PN XcmsColor
-structures, each pixel member indicating the color cell to query.
-The color specifications for the color cells are returned in these structures.
-.IP \fIncolors\fP 1i
-Specifies the number of 
-.PN XcmsColor
-structures in the color-specification array.
-.IP \fIresult_format\fP 1i
-Specifies the color format for the returned color specification.
-.LP
-.eM
-The
-.PN XcmsQueryColors
-function obtains the RGB values
-for pixel values in the pixel members of
-.PN XcmsColor
-structures and then
-converts the values to the target format as
-specified by the result_format argument.
-If a pixel is not a valid index into the specified colormap, a
-.PN BadValue
-error results.
-If more than one pixel is in error,
-the one that gets reported is arbitrary.
-.LP
-.PN XcmsQueryColors
-can generate
-.PN BadColor
-and
-.PN BadValue
-errors.
-.NH 2
-Color Conversion Context Functions
-.XS
-\*(SN Color Conversion Context Functions
-.XE
-.LP
-This section describes functions to create, modify,
-and query Color Conversion Contexts (CCCs).
-.LP
-Associated with each colormap is an initial CCC transparently generated by
-Xlib.
-.IN "Color Conversion Context" "creation"
-Therefore, when you specify a colormap as an argument to a function,
-you are indirectly specifying a CCC.
-.IN "CCC" "of colormap"
-.IN "Color Conversion Context" "of colormap"
-The CCC attributes that can be modified by the X client are:
-.IP \(bu 5
-Client White Point
-.IP \(bu 5
-Gamut compression procedure and client data
-.IP \(bu 5
-White point adjustment procedure and client data
-.LP
-The initial values for these attributes are implementation specific.
-The CCC attributes for subsequently created CCCs can be defined
-by changing the CCC attributes of the default CCC.
-.IN "CCC" "default"
-.IN "Color Conversion Context" "default"
-There is a default CCC associated with each screen.
-.NH 3
-Getting and Setting the Color Conversion Context of a Colormap
-.XS
-\*(SN Getting and Setting the Color Conversion Context of a Colormap
-.XE
-.LP
-.sp
-To obtain the CCC associated with a colormap, use
-.PN XcmsCCCOfColormap .
-.IN "XcmsCCCOfColormap" "" "@DEF@"
-.IN "Colormap" "CCC of"
-.IN "CCC" "of colormap"
-.IN "Color Conversion Context" "of colormap"
-.sM
-.FD 0
-XcmsCCC XcmsCCCOfColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.LP
-.eM
-The
-.PN XcmsCCCOfColormap
-function returns the CCC associated with the specified colormap.
-Once obtained, 
-the CCC attributes can be queried or modified.
-Unless the CCC associated with the specified colormap is changed with
-.PN XcmsSetCCCOfColormap ,
-this CCC is used when the specified colormap is used as an argument 
-to color functions.
-.sp
-.LP
-To change the CCC associated with a colormap, use
-.PN XcmsSetCCCOfColormap .
-.IN "XcmsSetCCCOfColormap" "" "@DEF@"
-.IN "Colormap" "CCC of"
-.IN "CCC" "of colormap"
-.IN "Color Conversion Context" "of colormap"
-.sM
-.FD 0
-XcmsCCC XcmsSetCCCOfColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIccc\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.br
-      XcmsCCC \fIccc\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.IP \fIccc\fP 1i
-Specifies the CCC.
-.LP
-.eM
-The
-.PN XcmsSetCCCOfColormap
-function changes the CCC associated with the specified colormap.
-It returns the CCC previously associated with the colormap.
-If they are not used again in the application,
-CCCs should be freed by calling
-.PN XcmsFreeCCC .
-Several colormaps may share the same CCC without restriction; this
-includes the CCCs generated by Xlib with each colormap.  Xlib, however,
-creates a new CCC with each new colormap.
-.NH 3
-Obtaining the Default Color Conversion Context
-.XS
-\*(SN Obtaining the Default Color Conversion Context
-.XE
-.LP
-You can change the default CCC attributes for subsequently created CCCs
-by changing the CCC attributes of the default CCC.
-.IN "CCC" "default"
-.IN "Color Conversion Context" "default"
-A default CCC is associated with each screen.
-.sp
-.LP
-To obtain the default CCC for a screen, use
-.PN XcmsDefaultCCC .
-.IN "XcmsDefaultCCC" "" "@DEF@"
-.IN "Color Conversion Context" "default"
-.IN "CCC" "default"
-.sM
-.FD 0
-XcmsCCC XcmsDefaultCCC\^(\^\fIdisplay\fP, \fIscreen_number\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIscreen_number\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIscreen_number\fP 1i
-Specifies the appropriate screen number on the host server.
-.LP
-.eM
-The
-.PN XcmsDefaultCCC
-function returns the default CCC for the specified screen.
-Its visual is the default visual of the screen.
-Its initial gamut compression and white point
-adjustment procedures as well as the associated client data are implementation
-specific.
-.NH 3
-Color Conversion Context Macros
-.XS
-\*(SN Color Conversion Context Macros
-.XE
-.LP
-Applications should not directly modify any part of the
-.PN XcmsCCC .
-The following lists the C language macros, their corresponding function
-equivalents for other language bindings, and what data they both
-can return.
-.sp
-.LP
-.IN "DisplayOfCCC" "" "@DEF@"
-.IN "XcmsDisplayOfCCC" "" "@DEF@"
-.sM
-.FD 0
-DisplayOfCCC\^(\^\fIccc\fP\^)
-.br
-     XcmsCCC \fIccc\fP\^;
-.sp
-Display *XcmsDisplayOfCCC\^(\^\fIccc\fP\^)
-.br
-     XcmsCCC \fIccc\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-.LP
-.eM
-Both return the display associated with the specified CCC.
-.LP
-.sp
-.IN "VisualOfCCC" "" "@DEF@"
-.IN "XcmsVisualOfCCC" "" "@DEF@"
-.sM
-.FD 0
-VisualOfCCC\^(\^\fIccc\fP\^)
-.br
-     XcmsCCC \fIccc\fP\^;
-.sp
-Visual *XcmsVisualOfCCC\^(\^\fIccc\fP\^)
-.br
-     XcmsCCC \fIccc\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-.LP
-.eM
-Both return the visual associated with the specified CCC.
-.sp
-.LP
-.IN "ScreenNumberOfCCC" "" "@DEF@"
-.IN "XcmsScreenNumberOfCCC" "" "@DEF@"
-.sM
-.FD 0
-ScreenNumberOfCCC\^(\^\fIccc\fP\^)
-.br
-     XcmsCCC \fIccc\fP\^;
-.sp
-int XcmsScreenNumberOfCCC\^(\^\fIccc\fP\^)
-.br
-     XcmsCCC \fIccc\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-.LP
-.eM
-Both return the number of the screen associated with the specified CCC.
-.sp
-.LP
-.IN "ScreenWhitePointOfCCC" "" "@DEF@"
-.IN "XcmsScreenWhitePointOfCCC" "" "@DEF@"
-.sM
-.FD 0
-ScreenWhitePointOfCCC\^(\^\fIccc\fP\^)
-.br
-     XcmsCCC \fIccc\fP\^;
-.sp
-XcmsColor *XcmsScreenWhitePointOfCCC\^(\^\fIccc\fP\^)
-.br
-     XcmsCCC \fIccc\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-.LP
-.eM
-Both return the white point of the screen associated with the specified CCC.
-.sp
-.LP
-.IN "ClientWhitePointOfCCC" "" "@DEF@"
-.IN "XcmsClientWhitePointOfCCC" "" "@DEF@"
-.sM
-.FD 0
-ClientWhitePointOfCCC\^(\^\fIccc\fP\^)
-.br
-     XcmsCCC \fIccc\fP\^;
-.sp
-XcmsColor *XcmsClientWhitePointOfCCC\^(\^\fIccc\fP\^)
-.br
-     XcmsCCC \fIccc\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-.LP
-.eM
-Both return the Client White Point of the specified CCC.
-.NH 3
-Modifying Attributes of a Color Conversion Context
-.XS
-\*(SN Modifying Attributes of a Color Conversion Context
-.XE
-.LP
-To set the Client White Point in the CCC, use
-.PN XcmsSetWhitePoint .
-.IN "XcmsSetWhitePoint" "" "@DEF@"
-.IN "Client White Point" "of Color Conversion Context"
-.sM
-.FD 0
-Status XcmsSetWhitePoint\^(\^\fIccc\fP\^, \fIcolor\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsColor *\fIcolor\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-.ds Co new Client White Point
-.IP \fIcolor\fP 1i
-Specifies the \*(Co.
-.LP
-.eM
-The
-.PN XcmsSetWhitePoint
-function changes the Client White Point in the specified CCC.
-Note that the pixel member is ignored 
-and that the color specification is left unchanged upon return.
-The format for the new white point must be
-.PN XcmsCIEXYZFormat ,
-.PN XcmsCIEuvYFormat ,
-.PN XcmsCIExyYFormat ,
-or
-.PN XcmsUndefinedFormat .
-If the color argument is NULL, this function sets the format component of the
-Client White Point specification to
-.PN XcmsUndefinedFormat ,
-indicating that the Client White Point is assumed to be the same as the
-Screen White Point.
-.LP
-This function returns nonzero status
-if the format for the new white point is valid;
-otherwise, it returns zero.
-
-.sp
-.LP
-To set the gamut compression procedure and corresponding client data
-in a specified CCC, use
-.PN XcmsSetCompressionProc .
-.IN "XcmsSetCompressionProc" "" "@DEF@"
-.IN "Gamut compression" "setting in Color Conversion Context"
-.IN "Gamut compression" "procedure"
-.IN "Gamut compression" "client data"
-.sM
-.FD 0
-XcmsCompressionProc XcmsSetCompressionProc\^(\^\fIccc\fP\^, \fIcompression_proc\fP\^, \fIclient_data\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsCompressionProc \fIcompression_proc\fP\^;
-.br
-      XPointer \fIclient_data\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-.IP \fIcompression_proc\fP 1i
-Specifies the gamut compression procedure that is to be applied 
-when a color lies outside the screen's color gamut.
-If NULL is specified and a function using this CCC must convert
-a color specification to a device-dependent format and encounters a color
-that lies outside the screen's color gamut, 
-that function will return
-.PN XcmsFailure .
-.ds Cd the gamut compression procedure
-.IP \fIclient_data\fP 1i
-Specifies client data for \*(Cd or NULL.
-.LP
-.eM
-The
-.PN XcmsSetCompressionProc
-function first sets the gamut compression procedure and client data 
-in the specified CCC with the newly specified procedure and client data
-and then returns the old procedure.
-.sp
-.LP
-To set the white point adjustment procedure and corresponding client data
-in a specified CCC, use
-.PN XcmsSetWhiteAdjustProc .
-.IN "XcmsSetWhiteAdjustProc" "" "@DEF@"
-.IN "White point adjustment" "setting in Color Conversion Context"
-.IN "White point adjustment" "procedure"
-.IN "White point adjustment" "client data"
-.FD 0
-.sM
-XcmsWhiteAdjustProc XcmsSetWhiteAdjustProc\^(\^\fIccc\fP\^, \fIwhite_adjust_proc\fP\^, \fIclient_data\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsWhiteAdjustProc \fIwhite_adjust_proc\fP\^;
-.br
-      XPointer \fIclient_data\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-.IP \fIwhite_adjust_proc\fP 1i
-Specifies the white point adjustment procedure.
-.ds Cd the white point adjustment procedure
-.IP \fIclient_data\fP 1i
-Specifies client data for \*(Cd or NULL.
-.LP
-.eM
-The
-.PN XcmsSetWhiteAdjustProc
-function first sets the white point adjustment procedure and client data 
-in the specified CCC with the newly specified procedure and client data
-and then returns the old procedure.
-.NH 3
-Creating and Freeing a Color Conversion Context
-.XS
-\*(SN Creating and Freeing a Color Conversion Context
-.XE
-.LP
-You can explicitly create a CCC within your application by calling
-.PN XcmsCreateCCC .
-These created CCCs can then be used by those functions that explicitly
-call for a CCC argument.
-Old CCCs that will not be used by the application should be freed using
-.PN XcmsFreeCCC .
-.sp
-.LP
-To create a CCC, use
-.PN XcmsCreateCCC .
-.IN "XcmsCreateCCC" "" "@DEF@"
-.IN "Color Conversion Context" "creation"
-.IN "CCC" "creation"
-.sM
-.FD 0
-XcmsCCC XcmsCreateCCC\^(\^\fIdisplay\fP, \fIscreen_number\fP\^, \fIvisual\fP\^, \fIclient_white_point\fP\^, \fIcompression_proc\fP\^,
-.br
-                    \fIcompression_client_data\fP\^, \fIwhite_adjust_proc\fP\^, \fIwhite_adjust_client_data\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIscreen_number\fP\^;
-.br
-      Visual *\fIvisual\fP\^;
-.br
-      XcmsColor *\fIclient_white_point\fP\^;
-.br
-      XcmsCompressionProc \fIcompression_proc\fP\^;
-.br
-      XPointer \fIcompression_client_data\fP\^;
-.br
-      XcmsWhiteAdjustProc \fIwhite_adjust_proc\fP\^;
-.br
-      XPointer \fIwhite_adjust_client_data\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIscreen_number\fP 1i
-Specifies the appropriate screen number on the host server.
-.IP \fIvisual\fP 1i
-Specifies the visual type.
-.IP \fIclient_white_point\fP 1i
-Specifies the Client White Point.
-If NULL is specified, 
-the Client White Point is to be assumed to be the same as the
-Screen White Point.
-Note that the pixel member is ignored.
-.IP \fIcompression_proc\fP 1i
-Specifies the gamut compression procedure that is to be applied 
-when a color lies outside the screen's color gamut.
-If NULL is specified and a function using this CCC must convert
-a color specification to a device-dependent format and encounters a color
-that lies outside the screen's color gamut, 
-that function will return
-.PN XcmsFailure .
-.IP \fIcompression_client_data\fP 1i
-Specifies client data for use by the gamut compression procedure or NULL.
-.IP \fIwhite_adjust_proc\fP 1i
-Specifies the white adjustment procedure that is to be applied
-when the Client White Point differs from the Screen White Point.
-NULL indicates that no white point adjustment is desired.
-.IP \fIwhite_adjust_client_data\fP 1i
-Specifies client data for use with the white point adjustment procedure or NULL.
-.LP
-.eM
-The
-.PN XcmsCreateCCC
-function creates a CCC for the specified display, screen, and visual.
-.LP
-.sp
-To free a CCC, use
-.PN XcmsFreeCCC .
-.IN "XcmsFreeCCC" "" "@DEF@"
-.IN "Color Conversion Context" "freeing"
-.IN "CCC" "freeing"
-.sM
-.FD 0
-void XcmsFreeCCC\^(\^\fIccc\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-.LP
-.eM
-The
-.PN XcmsFreeCCC
-function frees the memory used for the specified CCC.
-Note that default CCCs and those currently associated with colormaps
-are ignored.
-.NH 2
-Converting between Color Spaces
-.XS
-\*(SN Converting between Color Spaces
-.XE
-.LP
-.sp
-To convert an array of color specifications in arbitrary color formats
-to a single destination format, use
-.PN XcmsConvertColors .
-.IN "Color conversion"
-.IN "Color" "conversion"
-.IN "XcmsConvertColors" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsConvertColors\^(\^\fIccc\fP\^, \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fItarget_format\fP\^, \fIcompression_flags_return\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsColor \fIcolors_in_out\fP\^[\^]\^;
-.br
-      unsigned int \fIncolors\fP\^;
-.br
-      XcmsColorFormat \fItarget_format\fP\^;
-.br
-      Bool \fIcompression_flags_return\fP\^[\^]\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-If conversion is between device-independent color spaces only
-(for example, TekHVC to CIELuv),
-the CCC is necessary only to specify the Client White Point.
-.IP \fIcolors_in_out\fP 1i
-Specifies an array of color specifications.
-Pixel members are ignored and remain unchanged upon return.
-.IP \fIncolors\fP 1i
-Specifies the number of 
-.PN XcmsColor
-structures in the color-specification array.
-.IP \fItarget_format\fP 1i
-Specifies the target color specification format.
-.IP \fIcompression_flags_return\fP 1i
-Returns an array of Boolean values indicating compression status.
-If a non-NULL pointer is supplied,
-each element of the array is set to
-.PN True
-if the corresponding color was compressed and
-.PN False
-otherwise.
-Pass NULL if the compression status is not useful.
-.LP
-.eM
-The
-.PN XcmsConvertColors
-function converts the color specifications in the specified array of
-.PN XcmsColor
-structures from their current format to a single target format,
-using the specified CCC.
-When the return value is
-.PN XcmsFailure ,
-the contents of the color specification array are left unchanged.
-.LP
-The array may contain a mixture of color specification formats
-(for example, 3 CIE XYZ, 2 CIE Luv, and so on).
-When the array contains both device-independent and
-device-dependent color specifications and the target_format argument specifies
-a device-dependent format (for example,
-.PN XcmsRGBiFormat ,
-.PN XcmsRGBFormat ),
-all specifications are converted to CIE XYZ format and then to the target
-device-dependent format.
-.NH 2
-Callback Functions
-.XS
-\*(SN Callback Functions
-.XE
-.LP
-This section describes the gamut compression and white point
-adjustment callbacks.
-.LP
-The gamut compression procedure specified in the CCC
-is called when an attempt to convert a color specification from
-.PN XcmsCIEXYZ
-to a device-dependent format (typically
-.PN XcmsRGBi )
-results in a color that lies outside the screen's color gamut.
-If the gamut compression procedure requires client data, this data is passed
-via the gamut compression client data in the CCC.
-.LP
-During color specification conversion between device-independent
-and device-dependent color spaces,
-if a white point adjustment procedure is specified in the CCC,
-it is triggered when the Client White Point and Screen White Point differ.
-If required, the client data is obtained from the CCC.
-.NH 3
-Prototype Gamut Compression Procedure
-.XS
-\*(SN Prototype Gamut Compression Procedure
-.XE
-.LP
-The gamut compression callback interface must adhere to the
-following:
-.IN "XcmsCompressionProc" "" "@DEF@"
-.sM
-.FD 0
-typedef Status (*\^XcmsCompressionProc\^)\^(\^\fIccc\fP\^, \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fIindex\fP\^, \fIcompression_flags_return\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsColor \fIcolors_in_out[]\fP\^;
-.br
-      unsigned int \fIncolors\fP\^;
-.br
-      unsigned int \fIindex\fP\^;
-.br
-      Bool \fIcompression_flags_return[]\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-.IP \fIcolors_in_out\fP 1i
-Specifies an array of color specifications.
-Pixel members should be ignored and must remain unchanged upon return.
-.IP \fIncolors\fP 1i
-Specifies the number of 
-.PN XcmsColor
-structures in the color-specification array.
-.IP \fIindex\fP 1i
-Specifies the index into the array of
-.PN XcmsColor
-structures for the encountered color specification that lies outside the 
-screen's color gamut.
-Valid values are 0 (for the first element) to ncolors \- 1.
-.IP \fIcompression_flags_return\fP 1i
-Returns an array of Boolean values for indicating compression status.
-If a non-NULL pointer is supplied
-and a color at a given index is compressed, then
-.PN True
-should be stored at the corresponding index in this array;
-otherwise, the array should not be modified.
-.LP
-.eM
-When implementing a gamut compression procedure, consider the following
-rules and assumptions:
-.IP \(bu 5
-The gamut compression procedure can attempt to compress one or multiple
-specifications at a time.
-.IP \(bu 5
-When called, elements 0 to index \- 1 in the color specification
-array can be assumed to fall within the screen's color gamut.
-In addition, these color specifications are already in some device-dependent
-format (typically
-.PN XcmsRGBi ).
-If any modifications are made to these color specifications,
-they must be in their initial device-dependent format upon return.
-.IP \(bu 5
-When called, the element in the color specification array specified
-by the index argument contains the color specification outside the 
-screen's color gamut encountered by the calling routine.
-In addition, this color specification can be assumed to be in
-.PN XcmsCIEXYZ .
-Upon return, this color specification must be in
-.PN XcmsCIEXYZ .
-.IP \(bu 5
-When called, elements from index to ncolors \- 1 
-in the color specification array may or may not fall within the
-screen's color gamut.
-In addition, these color specifications can be assumed to be in
-.PN XcmsCIEXYZ .
-If any modifications are made to these color specifications, 
-they must be in
-.PN XcmsCIEXYZ
-upon return.
-.IP \(bu 5
-The color specifications passed to the gamut compression procedure
-have already been adjusted to the Screen White Point.
-This means that at this point the color specification's white point
-is the Screen White Point.
-.IP \(bu 5
-If the gamut compression procedure uses a device-independent color space not
-initially accessible for use in the color management system, use 
-.PN XcmsAddColorSpace
-to ensure that it is added.
-.NH 3
-Supplied Gamut Compression Procedures
-.XS
-\*(SN Supplied Gamut Compression Procedures
-.XE
-.LP
-The following equations are useful in describing gamut compression
-functions:
-.EQ
-delim %%
-.EN
-.LP
-.Ds 0
-%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )%
-
-%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right ]%
-
-%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )%
-
-%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right ]%
-.De
-.LP
-The gamut compression callback procedures provided by Xlib are as follows:
-.IP \(bu 5
-.PN XcmsCIELabClipL
-.IP
-This brings the encountered out-of-gamut color specification into the 
-screen's color gamut by reducing or increasing CIE metric lightness (L*) 
-in the CIE L*a*b* color space until the color is within the gamut.
-If the Psychometric Chroma of the color specification 
-is beyond maximum for the Psychometric Hue Angle,
-then while maintaining the same Psychometric Hue Angle,
-the color will be clipped to the CIE L*a*b* coordinates of maximum
-Psychometric Chroma.
-See
-.PN XcmsCIELabQueryMaxC .
-No client data is necessary.
-.IP \(bu 5
-.PN XcmsCIELabClipab
-.IP
-This brings the encountered out-of-gamut color specification into the 
-screen's color gamut by reducing Psychometric Chroma,
-while maintaining Psychometric Hue Angle,
-until the color is within the gamut.
-No client data is necessary.
-.IP \(bu 5
-.PN XcmsCIELabClipLab
-.IP
-This brings the encountered out-of-gamut color specification into the
-screen's color gamut by replacing it with CIE L*a*b* coordinates
-that fall within the color gamut while maintaining the original
-Psychometric Hue
-Angle and whose vector to the original coordinates is the shortest attainable.
-No client data is necessary.
-.IP \(bu 5
-.PN XcmsCIELuvClipL
-.IP
-This brings the encountered out-of-gamut color specification into the 
-screen's color gamut by reducing or increasing CIE metric lightness (L*)
-in the CIE L*u*v* color space until the color is within the gamut.
-If the Psychometric Chroma of the color specification
-is beyond maximum for the Psychometric Hue Angle,
-then, while maintaining the same Psychometric Hue Angle,
-the color will be clipped to the CIE L*u*v* coordinates of maximum
-Psychometric Chroma.
-See
-.PN XcmsCIELuvQueryMaxC .
-No client data is necessary.
-.IP \(bu 5
-.PN XcmsCIELuvClipuv
-.IP
-This brings the encountered out-of-gamut color specification into the
-screen's color gamut by reducing
-Psychometric Chroma, while maintaining Psychometric Hue Angle,
-until the color is within the gamut.
-No client data is necessary.
-.IP \(bu 5
-.PN XcmsCIELuvClipLuv
-.IP
-This brings the encountered out-of-gamut color specification into the
-screen's color gamut by replacing it with CIE L*u*v* coordinates
-that fall within the color gamut while maintaining the original
-Psychometric Hue
-Angle and whose vector to the original coordinates is the shortest attainable.
-No client data is necessary.
-.IP \(bu 5
-.PN XcmsTekHVCClipV
-.IP
-This brings the encountered out-of-gamut color specification into the
-screen's color gamut by reducing or increasing the Value dimension
-in the TekHVC color space until the color is within the gamut.
-If Chroma of the color specification is beyond maximum for the particular Hue,
-then, while maintaining the same Hue,
-the color will be clipped to the Value and Chroma coordinates
-that represent maximum Chroma for that particular Hue.
-No client data is necessary.
-.IP \(bu 5
-.PN XcmsTekHVCClipC
-.IP
-This brings the encountered out-of-gamut color specification into the
-screen's color gamut by reducing the Chroma dimension
-in the TekHVC color space until the color is within the gamut.
-No client data is necessary.
-.IP \(bu 5
-.PN XcmsTekHVCClipVC
-.IP
-This brings the encountered out-of-gamut color specification into the
-screen's color gamut by replacing it with TekHVC coordinates
-that fall within the color gamut while maintaining the original Hue
-and whose vector to the original coordinates is the shortest attainable.
-No client data is necessary.
-.NH 3
-Prototype White Point Adjustment Procedure
-.XS
-\*(SN Prototype White Point Adjustment Procedure
-.XE
-.LP
-The white point adjustment procedure interface must adhere to the following:
-.IN "XcmsWhiteAdjustProc" "" "@DEF@"
-.sM
-.FD 0
-typedef Status (*\^XcmsWhiteAdjustProc\^)\^(\^\fIccc\fP\^, \fIinitial_white_point\fP\^, \fItarget_white_point\fP\^, \fItarget_format\fP\^,
-.br
-                \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fIcompression_flags_return\fP\^)
-.br
-       XcmsCCC \fIccc\fP\^;
-.br
-       XcmsColor *\fIinitial_white_point\fP\^;
-.br
-       XcmsColor *\fItarget_white_point\fP\^;
-.br
-       XcmsColorFormat \fItarget_format\fP\^;
-.br
-       XcmsColor \fIcolors_in_out[]\fP\^;
-.br
-       unsigned int \fIncolors\fP\^;
-.br
-       Bool \fIcompression_flags_return[]\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-.IP \fIinitial_white_point\fP 1i
-Specifies the initial white point.
-.IP \fItarget_white_point\fP 1i
-Specifies the target white point.
-.IP \fItarget_format\fP 1i
-Specifies the target color specification format.
-.IP \fIcolors_in_out\fP 1i
-Specifies an array of color specifications.
-Pixel members should be ignored and must remain unchanged upon return.
-.IP \fIncolors\fP 1i
-Specifies the number of 
-.PN XcmsColor
-structures in the color-specification array.
-.IP \fIcompression_flags_return\fP 1i
-Returns an array of Boolean values for indicating compression status.
-If a non-NULL pointer is supplied
-and a color at a given index is compressed, then
-.PN True
-should be stored at the corresponding index in this array;
-otherwise, the array should not be modified.
-.LP
-.eM
-.NH 3
-Supplied White Point Adjustment Procedures
-.XS
-\*(SN Supplied White Point Adjustment Procedures
-.XE
-.LP
-White point adjustment procedures provided by Xlib are as follows:
-.IP \(bu 5
-.PN XcmsCIELabWhiteShiftColors
-.IP
-This uses the CIE L*a*b* color space for adjusting the chromatic character
-of colors to compensate for the chromatic differences between the source
-and destination white points.
-This procedure simply converts the color specifications to 
-.PN XcmsCIELab
-using the source white point and then converts to the target specification
-format using the destination's white point.
-No client data is necessary.
-.IP \(bu 5
-.PN XcmsCIELuvWhiteShiftColors
-.IP
-This uses the CIE L*u*v* color space for adjusting the chromatic character
-of colors to compensate for the chromatic differences between the source
-and destination white points.
-This procedure simply converts the color specifications to 
-.PN XcmsCIELuv
-using the source white point and then converts to the target specification
-format using the destination's white point.
-No client data is necessary.
-.IP \(bu 5
-.PN XcmsTekHVCWhiteShiftColors
-.IP
-This uses the TekHVC color space for adjusting the chromatic character
-of colors to compensate for the chromatic differences between the source
-and destination white points.
-This procedure simply converts the color specifications to
-.PN XcmsTekHVC
-using the source white point and then converts to the target specification
-format using the destination's white point.
-An advantage of this procedure over those previously described
-is an attempt to minimize hue shift.
-No client data is necessary.
-.LP
-From an implementation point of view,
-these white point adjustment procedures convert the color specifications
-to a device-independent but white-point-dependent color space 
-(for example, CIE L*u*v*, CIE L*a*b*, TekHVC) using one white point
-and then converting those specifications to the target color space 
-using another white point.
-In other words,
-the specification goes in the color space with one white point 
-but comes out with another white point, 
-resulting in a chromatic shift based on the chromatic displacement
-between the initial white point and target white point.
-The CIE color spaces that are assumed to be white-point-independent
-are CIE u'v'Y, CIE XYZ, and CIE xyY.
-When developing a custom white point adjustment procedure that uses a
-device-independent color space not initially accessible for use in the
-color management system, use
-.PN XcmsAddColorSpace
-to ensure that it is added.
-.LP
-As an example, 
-if the CCC specifies a white point adjustment procedure
-and if the Client White Point and Screen White Point differ, the
-.PN XcmsAllocColor
-function will use the white point adjustment
-procedure twice: 
-.IP \(bu 5
-Once to convert to
-.PN XcmsRGB
-.IP \(bu  5
-A second time to convert from
-.PN XcmsRGB 
-.LP
-For example, assume the specification is in
-.PN XcmsCIEuvY
-and the adjustment procedure is
-.PN XcmsCIELuvWhiteShiftColors .
-During conversion to
-.PN XcmsRGB ,
-the call to 
-.PN XcmsAllocColor 
-results in the following series of color specification conversions:
-.\" Do these need to be font coded?
-.IP \(bu 5
-From 
-.PN XcmsCIEuvY
-to
-.PN XcmsCIELuv
-using the Client White Point
-.IP \(bu 5
-From 
-.PN XcmsCIELuv
-to
-.PN XcmsCIEuvY
-using the Screen White Point
-.IP \(bu 5
-From
-.PN XcmsCIEuvY
-to
-.PN XcmsCIEXYZ
-(CIE u'v'Y and XYZ are white-point-independent color spaces)
-.IP \(bu 5
-From 
-.PN XcmsCIEXYZ
-to 
-.PN XcmsRGBi
-.IP \(bu 5
-From 
-.PN XcmsRGBi
-to
-.PN XcmsRGB
-.LP
-The resulting RGB specification is passed to
-.PN XAllocColor ,
-and the RGB
-specification returned by
-.PN XAllocColor
-is converted back to 
-.PN XcmsCIEuvY
-by reversing the color conversion sequence.
-.NH 2
-Gamut Querying Functions
-.XS
-\*(SN Gamut Querying Functions
-.XE
-.LP
-This section describes the gamut querying functions that Xlib provides.
-These functions allow the client to query the boundary 
-of the screen's color gamut in terms of the CIE L*a*b*, CIE L*u*v*, 
-and TekHVC color spaces.
-.IN "Gamut querying"
-Functions are also provided that allow you to query 
-the color specification of:
-.IP \(bu 5
-White (full-intensity red, green, and blue)
-.IP \(bu 5
-Red (full-intensity red while green and blue are zero)
-.IP \(bu 5
-Green (full-intensity green while red and blue are zero)
-.IP \(bu 5
-Blue (full-intensity blue while red and green are zero)
-.IP \(bu 5
-Black (zero-intensity red, green, and blue)
-.LP
-The white point associated with color specifications passed to 
-and returned from these gamut querying
-functions is assumed to be the Screen White Point.
-.IN "Screen White Point"
-This is a reasonable assumption,
-because the client is trying to query the screen's color gamut.
-.LP
-The following naming convention is used for the Max and Min functions:
-.LP
-.Ds 0
-Xcms\fI<color_space>\fPQueryMax\fI<dimensions>\fP
-
-Xcms\fI<color_space>\fPQueryMin\fI<dimensions>\fP
-.De
-.LP
-The <dimensions> consists of a letter or letters 
-that identify the dimensions of the color space 
-that are not fixed.
-For example, 
-.PN XcmsTekHVCQueryMaxC
-is given a fixed Hue and Value for which maximum Chroma is found.
-.NH 3
-Red, Green, and Blue Queries
-.XS
-\*(SN Red, Green, and Blue Queries
-.XE
-.LP
-To obtain the color specification for black 
-(zero-intensity red, green, and blue), use
-.PN XcmsQueryBlack .
-.IN "XcmsQueryBlack" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsQueryBlack\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsColorFormat \fItarget_format\fP\^;
-.br
-      XcmsColor *\fIcolor_return\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-The CCC's Client White Point and white point adjustment procedures
-are ignored.
-.IP \fItarget_format\fP 1i
-Specifies the target color specification format.
-.ds Cs zero-intensity red, green, and blue
-.IP \fIcolor_return\fP 1i
-Returns the color specification in the specified target format
-for \*(Cs.
-The white point associated with the returned
-color specification is the Screen White Point.
-The value returned in the pixel member is undefined.
-.LP
-.eM 
-The
-.PN XcmsQueryBlack
-function returns the color specification in the specified target format
-for zero-intensity red, green, and blue.
-.sp
-.LP
-To obtain the color specification for blue 
-(full-intensity blue while red and green are zero), use
-.PN XcmsQueryBlue .
-.IN "XcmsQueryBlue" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsQueryBlue\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsColorFormat \fItarget_format\fP\^;
-.br
-      XcmsColor *\fIcolor_return\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-The CCC's Client White Point and white point adjustment procedures
-are ignored.
-.IP \fItarget_format\fP 1i
-Specifies the target color specification format.
-.ds Cs full-intensity blue while red and green are zero
-.IP \fIcolor_return\fP 1i
-Returns the color specification in the specified target format
-for \*(Cs.
-The white point associated with the returned
-color specification is the Screen White Point.
-The value returned in the pixel member is undefined.
-.LP
-.eM 
-The
-.PN XcmsQueryBlue
-function returns the color specification in the specified target format
-for full-intensity blue while red and green are zero.
-.sp
-.LP
-To obtain the color specification for green
-(full-intensity green while red and blue are zero), use
-.PN XcmsQueryGreen .
-.IN "XcmsQueryGreen" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsQueryGreen\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsColorFormat \fItarget_format\fP\^;
-.br
-      XcmsColor *\fIcolor_return\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-The CCC's Client White Point and white point adjustment procedures
-are ignored.
-.IP \fItarget_format\fP 1i
-Specifies the target color specification format.
-.ds Cs full-intensity green while red and blue are zero
-.IP \fIcolor_return\fP 1i
-Returns the color specification in the specified target format
-for \*(Cs.
-The white point associated with the returned
-color specification is the Screen White Point.
-The value returned in the pixel member is undefined.
-.LP
-.eM 
-The
-.PN XcmsQueryGreen
-function returns the color specification in the specified target format
-for full-intensity green while red and blue are zero.
-.sp
-.LP
-To obtain the color specification for red
-(full-intensity red while green and blue are zero), use
-.PN XcmsQueryRed .
-.IN "XcmsQueryRed" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsQueryRed\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsColorFormat \fItarget_format\fP\^;
-.br
-      XcmsColor *\fIcolor_return\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-The CCC's Client White Point and white point adjustment procedures
-are ignored.
-.IP \fItarget_format\fP 1i
-Specifies the target color specification format.
-.ds Cs full-intensity red while green and blue are zero
-.IP \fIcolor_return\fP 1i
-Returns the color specification in the specified target format
-for \*(Cs.
-The white point associated with the returned
-color specification is the Screen White Point.
-The value returned in the pixel member is undefined.
-.LP
-.eM 
-The
-.PN XcmsQueryRed
-function returns the color specification in the specified target format
-for full-intensity red while green and blue are zero.
-.LP
-.sp
-To obtain the color specification for white
-(full-intensity red, green, and blue), use
-.PN XcmsQueryWhite .
-.IN "XcmsQueryWhite" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsQueryWhite\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsColorFormat \fItarget_format\fP\^;
-.br
-      XcmsColor *\fIcolor_return\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-The CCC's Client White Point and white point adjustment procedures
-are ignored.
-.IP \fItarget_format\fP 1i
-Specifies the target color specification format.
-.ds Cs full-intensity red, green, and blue
-.IP \fIcolor_return\fP 1i
-Returns the color specification in the specified target format
-for \*(Cs.
-The white point associated with the returned
-color specification is the Screen White Point.
-The value returned in the pixel member is undefined.
-.LP
-.eM 
-The
-.PN XcmsQueryWhite
-function returns the color specification in the specified target format
-for full-intensity red, green, and blue.
-.NH 3
-CIELab Queries
-.XS
-\*(SN CIELab Queries
-.XE
-.LP
-The following equations are useful in describing the CIELab query functions:
-.EQ
-delim %%
-.EN
-.LP
-.IN "Psychometric Hue Angle"
-.IN "CIE metric lightness"
-.IN "Psychometric Chroma"
-.IN "Psychometric Chroma" "maximum"
-.Ds 0
-%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )%
-
-%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right ]%
-.De
-.sp
-To obtain the CIE L*a*b* coordinates of maximum Psychometric Chroma
-for a given Psychometric Hue Angle and CIE metric lightness (L*), use
-.PN XcmsCIELabQueryMaxC .
-.IN "XcmsCIELabQueryMaxC" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsCIELabQueryMaxC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIL_star\fP\^, \fIcolor_return\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsFloat \fIhue_angle\fP\^;
-.br
-      XcmsFloat \fIL_star\fP\^;
-.br
-      XcmsColor *\fIcolor_return\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-The CCC's Client White Point and white point adjustment procedures
-are ignored.
-.ds Ha maximum chroma
-.IP \fIhue_angle\fP 1i
-Specifies the hue angle (in degrees) at which to find \*(Ha.
-.ds Ls maximum chroma
-.IP \fIL_star\fP 1i
-Specifies the lightness (L*) at which to find \*(Ls.
-.ds Lc maximum chroma
-.ds lC hue angle and lightness
-.IP \fIcolor_return\fP 1i
-Returns the CIE L*a*b* coordinates of \*(Lc
-displayable by the screen for the given \*(lC.
-The white point associated with the returned
-color specification is the Screen White Point.
-The value returned in the pixel member is undefined.
-.LP
-.eM 
-The
-.PN XcmsCIELabQueryMaxC
-function, given a hue angle and lightness,
-finds the point of maximum chroma displayable by the screen.
-It returns this point in CIE L*a*b* coordinates.
-.LP
-.sp
-To obtain the CIE L*a*b* coordinates of maximum CIE metric lightness (L*)
-for a given Psychometric Hue Angle and Psychometric Chroma, use
-.PN XcmsCIELabQueryMaxL .
-.IN "Psychometric Hue Angle"
-.IN "CIE metric lightness"
-.IN "CIE metric lightness" "maximum"
-.IN "XcmsCIELabQueryMaxL" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsCIELabQueryMaxL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsFloat \fIhue_angle\fP\^;
-.br
-      XcmsFloat \fIchroma\fP\^;
-.br
-      XcmsColor *\fIcolor_return\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-The CCC's Client White Point and white point adjustment procedures
-are ignored.
-.ds Ha maximum lightness
-.IP \fIhue_angle\fP 1i
-Specifies the hue angle (in degrees) at which to find \*(Ha.
-.ds Ch maximum lightness
-.IP \fIchroma\fP 1i
-Specifies the chroma at which to find \*(Ch.
-.ds Lc maximum lightness
-.ds lC hue angle and chroma
-.IP \fIcolor_return\fP 1i
-Returns the CIE L*a*b* coordinates of \*(Lc
-displayable by the screen for the given \*(lC.
-The white point associated with the returned
-color specification is the Screen White Point.
-The value returned in the pixel member is undefined.
-.LP
-.eM 
-The
-.PN XcmsCIELabQueryMaxL
-function, given a hue angle and chroma,
-finds the point in CIE L*a*b* color space of maximum 
-lightness (L*) displayable by the screen.
-It returns this point in CIE L*a*b* coordinates.
-An 
-.PN XcmsFailure
-return value usually indicates that the given chroma
-is beyond maximum for the given hue angle.
-.sp
-.LP
-To obtain the CIE L*a*b* coordinates of maximum Psychometric Chroma
-for a given Psychometric Hue Angle, use
-.PN XcmsCIELabQueryMaxLC .
-.IN "Psychometric Hue Angle"
-.IN "Psychometric Chroma"
-.IN "CIE metric lightness"
-.IN "Psychometric Chroma" "maximum"
-.IN "CIE metric lightness" "maximum"
-.IN "XcmsCIELabQueryMaxLC" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsCIELabQueryMaxLC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIcolor_return\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsFloat \fIhue_angle\fP\^;
-.br
-      XcmsColor *\fIcolor_return\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-The CCC's Client White Point and white point adjustment procedures
-are ignored.
-.ds Ha maximum chroma
-.IP \fIhue_angle\fP 1i
-Specifies the hue angle (in degrees) at which to find \*(Ha.
-.ds Lc maximum chroma
-.ds lC hue angle
-.IP \fIcolor_return\fP 1i
-Returns the CIE L*a*b* coordinates of \*(Lc
-displayable by the screen for the given \*(lC.
-The white point associated with the returned
-color specification is the Screen White Point.
-The value returned in the pixel member is undefined.
-.LP
-.eM 
-The
-.PN XcmsCIELabQueryMaxLC
-function, given a hue angle,
-finds the point of maximum chroma displayable by the screen.
-It returns this point in CIE L*a*b* coordinates.
-.sp
-.LP
-To obtain the CIE L*a*b* coordinates of minimum CIE metric lightness (L*)
-for a given Psychometric Hue Angle and Psychometric Chroma, use
-.PN XcmsCIELabQueryMinL .
-.IN "Psychometric Hue Angle"
-.IN "CIE metric lightness"
-.IN "CIE metric lightness" "minimum"
-.IN "XcmsCIELabQueryMinL" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsCIELabQueryMinL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsFloat \fIhue_angle\fP\^;
-.br
-      XcmsFloat \fIchroma\fP\^;
-.br
-      XcmsColor *\fIcolor_return\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-The CCC's Client White Point and white point adjustment procedures
-are ignored.
-.ds Ha minimum lightness
-.IP \fIhue_angle\fP 1i
-Specifies the hue angle (in degrees) at which to find \*(Ha.
-.ds Ch minimum lightness
-.IP \fIchroma\fP 1i
-Specifies the chroma at which to find \*(Ch.
-.ds Lc minimum lightness
-.ds lC hue angle and chroma
-.IP \fIcolor_return\fP 1i
-Returns the CIE L*a*b* coordinates of \*(Lc
-displayable by the screen for the given \*(lC.
-The white point associated with the returned
-color specification is the Screen White Point.
-The value returned in the pixel member is undefined.
-.LP
-.eM 
-The
-.PN XcmsCIELabQueryMinL
-function, given a hue angle and chroma,
-finds the point of minimum lightness (L*) displayable by the screen.
-It returns this point in CIE L*a*b* coordinates.
-An 
-.PN XcmsFailure
-return value usually indicates that the given chroma
-is beyond maximum for the given hue angle.
-.NH 3
-CIELuv Queries
-.XS
-\*(SN CIELuv Queries
-.XE
-.LP
-The following equations are useful in describing the CIELuv query functions:
-.EQ
-delim %%
-.EN
-.LP
-.IN "Psychometric Hue Angle"
-.IN "CIE metric lightness"
-.IN "Psychometric Chroma"
-.IN "Psychometric Chroma" "maximum"
-.Ds 0
-%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )%
-
-%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right ]%
-.De
-.sp
-.LP
-To obtain the CIE L*u*v* coordinates of maximum Psychometric Chroma
-for a given Psychometric Hue Angle and CIE metric lightness (L*), use
-.PN XcmsCIELuvQueryMaxC .
-.IN "XcmsCIELuvQueryMaxC" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsCIELuvQueryMaxC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIL_star\fP\^, \fIcolor_return\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsFloat \fIhue_angle\fP\^;
-.br
-      XcmsFloat \fIL_star\fP\^;
-.br
-      XcmsColor *\fIcolor_return\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-The CCC's Client White Point and white point adjustment procedures
-are ignored.
-.ds Ha maximum chroma
-.IP \fIhue_angle\fP 1i
-Specifies the hue angle (in degrees) at which to find \*(Ha.
-.ds Ls maximum chroma
-.IP \fIL_star\fP 1i
-Specifies the lightness (L*) at which to find \*(Ls.
-.ds Lc maximum chroma
-.ds lC hue angle and lightness
-.IP \fIcolor_return\fP 1i
-Returns the CIE L*u*v* coordinates of \*(Lc
-displayable by the screen for the given \*(lC.
-The white point associated with the returned
-color specification is the Screen White Point.
-The value returned in the pixel member is undefined.
-.LP
-.eM 
-The
-.PN XcmsCIELuvQueryMaxC
-function, given a hue angle and lightness,
-finds the point of maximum chroma displayable by the screen.
-It returns this point in CIE L*u*v* coordinates.
-.sp
-.LP
-To obtain the CIE L*u*v* coordinates of maximum CIE metric lightness (L*)
-for a given Psychometric Hue Angle and Psychometric Chroma, use
-.PN XcmsCIELuvQueryMaxL .
-.IN "Psychometric Hue Angle"
-.IN "CIE metric lightness"
-.IN "CIE metric lightness" "maximum"
-.IN "XcmsCIELuvQueryMaxL" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsCIELuvQueryMaxL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsFloat \fIhue_angle\fP\^;
-.br
-      XcmsFloat \fIchroma\fP\^;
-.br
-      XcmsColor *\fIcolor_return\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-The CCC's Client White Point and white point adjustment procedures
-are ignored.
-.ds Ha maximum lightness
-.IP \fIhue_angle\fP 1i
-Specifies the hue angle (in degrees) at which to find \*(Ha.
-.ds Ls maximum lightness
-.IP \fIL_star\fP 1i
-Specifies the lightness (L*) at which to find \*(Ls.
-.ds Lc maximum lightness
-.ds lC hue angle and chroma
-.IP \fIcolor_return\fP 1i
-Returns the CIE L*u*v* coordinates of \*(Lc
-displayable by the screen for the given \*(lC.
-The white point associated with the returned
-color specification is the Screen White Point.
-The value returned in the pixel member is undefined.
-.LP
-.eM 
-The
-.PN XcmsCIELuvQueryMaxL
-function, given a hue angle and chroma,
-finds the point in CIE L*u*v* color space of maximum 
-lightness (L*) displayable by the screen.
-It returns this point in CIE L*u*v* coordinates.
-An 
-.PN XcmsFailure
-return value usually indicates that the given chroma
-is beyond maximum for the given hue angle.
-.sp
-.LP
-To obtain the CIE L*u*v* coordinates of maximum Psychometric Chroma
-for a given Psychometric Hue Angle, use
-.PN XcmsCIELuvQueryMaxLC .
-.IN "Psychometric Hue Angle"
-.IN "Psychometric Chroma"
-.IN "CIE metric lightness"
-.IN "Psychometric Chroma" "maximum"
-.IN "CIE metric lightness" "maximum"
-.IN "XcmsCIELuvQueryMaxLC" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsCIELuvQueryMaxLC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIcolor_return\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsFloat \fIhue_angle\fP\^;
-.br
-      XcmsColor *\fIcolor_return\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-The CCC's Client White Point and white point adjustment procedures
-are ignored.
-.ds Ha maximum chroma
-.IP \fIhue_angle\fP 1i
-Specifies the hue angle (in degrees) at which to find \*(Ha.
-.ds Lc maximum chroma
-.ds lC hue angle
-.IP \fIcolor_return\fP 1i
-Returns the CIE L*u*v* coordinates of \*(Lc
-displayable by the screen for the given \*(lC.
-The white point associated with the returned
-color specification is the Screen White Point.
-The value returned in the pixel member is undefined.
-.LP
-.eM 
-The
-.PN XcmsCIELuvQueryMaxLC
-function, given a hue angle,
-finds the point of maximum chroma displayable by the screen.
-It returns this point in CIE L*u*v* coordinates.
-.sp
-.LP
-To obtain the CIE L*u*v* coordinates of minimum CIE metric lightness (L*)
-for a given Psychometric Hue Angle and Psychometric Chroma, use
-.PN XcmsCIELuvQueryMinL .
-.IN "Psychometric Hue Angle"
-.IN "CIE metric lightness"
-.IN "CIE metric lightness" "minimum"
-.IN "XcmsCIELuvQueryMinL" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsCIELuvQueryMinL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsFloat \fIhue_angle\fP\^;
-.br
-      XcmsFloat \fIchroma\fP\^;
-.br
-      XcmsColor *\fIcolor_return\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-The CCC's Client White Point and white point adjustment procedures
-are ignored.
-.ds Ha minimum lightness
-.IP \fIhue_angle\fP 1i
-Specifies the hue angle (in degrees) at which to find \*(Ha.
-.ds Ch minimum lightness
-.IP \fIchroma\fP 1i
-Specifies the chroma at which to find \*(Ch.
-.ds Lc minimum lightness
-.ds lC hue angle and chroma
-.IP \fIcolor_return\fP 1i
-Returns the CIE L*u*v* coordinates of \*(Lc
-displayable by the screen for the given \*(lC.
-The white point associated with the returned
-color specification is the Screen White Point.
-The value returned in the pixel member is undefined.
-.LP
-.eM
-The
-.PN XcmsCIELuvQueryMinL
-function, given a hue angle and chroma,
-finds the point of minimum lightness (L*) displayable by the screen.
-It returns this point in CIE L*u*v* coordinates.
-An 
-.PN XcmsFailure
-return value usually indicates that the given chroma
-is beyond maximum for the given hue angle.
-.NH 3
-TekHVC Queries
-.XS
-\*(SN TekHVC Queries
-.XE
-.LP
-To obtain the maximum Chroma for a given Hue and Value, use
-.PN XcmsTekHVCQueryMaxC .
-.IN "Chroma"
-.IN "Chroma" "maximum"
-.IN "XcmsTekHVCQueryMaxC" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsTekHVCQueryMaxC\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIvalue\fP\^, \fIcolor_return\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsFloat \fIhue\fP\^;
-.br
-      XcmsFloat \fIvalue\fP\^;
-.br
-      XcmsColor *\fIcolor_return\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-The CCC's Client White Point and white point adjustment procedures
-are ignored.
-.ds Hu in which to find the maximum Chroma
-.IP \fIhue\fP 1i
-Specifies the Hue \*(Hu.
-.ds Va maximum Chroma
-.IP \fIvalue\fP 1i
-Specifies the Value in which to find the \*(Va.
-.ds Lc maximum Chroma along with the actual Hue and Value 
-.ds lC maximum Chroma
-.IP \fIcolor_return\fP 1i
-Returns the \*(Lc at which the \*(lC was found.
-The white point associated with the returned
-color specification is the Screen White Point.
-The value returned in the pixel member is undefined.
-.LP
-.eM 
-The
-.PN XcmsTekHVCQueryMaxC
-function, given a Hue and Value,
-determines the maximum Chroma in TekHVC color space
-displayable by the screen.
-It returns the maximum Chroma along with the actual Hue
-and Value at which the maximum Chroma was found.
-.sp
-.LP
-To obtain the maximum Value for a given Hue and Chroma, use
-.PN XcmsTekHVCQueryMaxV .
-.IN "Value"
-.IN "Value" "maximum"
-.IN "XcmsTekHVCQueryMaxV" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsTekHVCQueryMaxV\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsFloat \fIhue\fP\^;
-.br
-      XcmsFloat \fIchroma\fP\^;
-.br
-      XcmsColor *\fIcolor_return\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-The CCC's Client White Point and white point adjustment procedures
-are ignored.
-.ds Hu in which to find the maximum Value
-.IP \fIhue\fP 1i
-Specifies the Hue \*(Hu.
-.ds Ch maximum Value
-.IP \fIchroma\fP 1i
-Specifies the chroma at which to find \*(Ch.
-.ds Lc maximum Value along with the Hue and Chroma
-.ds lC maximum Value
-.IP \fIcolor_return\fP 1i
-Returns the \*(Lc at which the \*(lC was found.
-The white point associated with the returned
-color specification is the Screen White Point.
-The value returned in the pixel member is undefined.
-.LP
-.eM 
-The
-.PN XcmsTekHVCQueryMaxV
-function, given a Hue and Chroma,
-determines the maximum Value in TekHVC color space
-displayable by the screen.
-It returns the maximum Value and the actual Hue and Chroma
-at which the maximum Value was found.
-.sp
-.LP
-To obtain the maximum Chroma and Value at which it is reached
-for a specified Hue, use
-.PN XcmsTekHVCQueryMaxVC .
-.IN "Chroma"
-.IN "Value"
-.IN "Chroma"  "maximum"
-.IN "Value" "maximum"
-.IN "XcmsTekHVCQueryMaxVC" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsTekHVCQueryMaxVC\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIcolor_return\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsFloat \fIhue\fP\^;
-.br
-      XcmsColor *\fIcolor_return\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-The CCC's Client White Point and white point adjustment procedures
-are ignored.
-.ds Hu in which to find the maximum Chroma
-.IP \fIhue\fP 1i
-Specifies the Hue \*(Hu.
-.ds Lc color specification in \
-XcmsTekHVC for the maximum Chroma, the Value at which \
-that maximum Chroma is reached, and the actual Hue
-.ds lC maximum Chroma
-.IP \fIcolor_return\fP 1i
-Returns the \*(Lc at which the \*(lC was found.
-The white point associated with the returned
-color specification is the Screen White Point.
-The value returned in the pixel member is undefined.
-.LP
-.eM 
-The
-.PN XcmsTekHVCQueryMaxVC
-function, given a Hue,
-determines the maximum Chroma in TekHVC color space displayable by the screen
-and the Value at which that maximum Chroma is reached.
-It returns the maximum Chroma,
-the Value at which that maximum Chroma is reached,
-and the actual Hue for which the maximum Chroma was found.
-.sp
-.LP
-To obtain a specified number of TekHVC specifications such that they
-contain maximum Values for a specified Hue and the
-Chroma at which the maximum Values are reached, use
-.PN XcmsTekHVCQueryMaxVSamples .
-.IN "Chroma"
-.IN "Value"
-.IN "Chroma"  "maximum"
-.IN "Value" "maximum"
-.IN "XcmsTekHVCQueryMaxVSamples" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsTekHVCQueryMaxVSamples\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIcolors_return\fP\^, \fInsamples\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsFloat \fIhue\fP\^;
-.br
-      XcmsColor \fIcolors_return[]\fP\^;
-.br
-      unsigned int \fInsamples\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-The CCC's Client White Point and white point adjustment procedures
-are ignored.
-.ds Hu for maximum Chroma/Value samples
-.IP \fIhue\fP 1i
-Specifies the Hue \*(Hu.
-.IP \fInsamples\fP 1i
-Specifies the number of samples.
-.IP \fIcolors_return\fP 1i
-Returns nsamples of color specifications in XcmsTekHVC
-such that the Chroma is the maximum attainable for the Value and Hue.
-The white point associated with the returned
-color specification is the Screen White Point.
-The value returned in the pixel member is undefined.
-.LP
-.eM 
-The
-.PN XcmsTekHVCQueryMaxVSamples
-returns nsamples of maximum Value, the Chroma at which that maximum Value
-is reached, and the actual Hue for which the maximum Chroma was found.
-These sample points may then be used to plot the maximum Value/Chroma
-boundary of the screen's color gamut for the specified Hue in TekHVC color
-space.
-.sp
-.LP
-To obtain the minimum Value for a given Hue and Chroma, use
-.PN XcmsTekHVCQueryMinV .
-.IN "Value"
-.IN "Value" "minimum"
-.IN "XcmsTekHVCQueryMinV" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsTekHVCQueryMinV\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsFloat \fIhue\fP\^;
-.br
-      XcmsFloat \fIchroma\fP\^;
-.br
-      XcmsColor *\fIcolor_return\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-The CCC's Client White Point and white point adjustment procedures
-are ignored.
-.ds Hu in which to find the minimum Value
-.IP \fIhue\fP 1i
-Specifies the Hue \*(Hu.
-.ds Va minimum Value
-.IP \fIvalue\fP 1i
-Specifies the Value in which to find the \*(Va.
-.ds Lc minimum Value and the actual Hue and Chroma
-.ds lC minimum Value
-.IP \fIcolor_return\fP 1i
-Returns the \*(Lc at which the \*(lC was found.
-The white point associated with the returned
-color specification is the Screen White Point.
-The value returned in the pixel member is undefined.
-.LP
-.eM 
-The
-.PN XcmsTekHVCQueryMinV
-function, given a Hue and Chroma,
-determines the minimum Value in TekHVC color space displayable by the screen.
-It returns the minimum Value and the actual Hue and Chroma at which
-the minimum Value was found.
-.NH 2
-Color Management Extensions
-.XS
-\*(SN Color Management Extensions
-.XE
-.LP
-The Xlib color management facilities can be extended in two ways:
-.IP \(bu 5
-Device-Independent Color Spaces
-.IP
-Device-independent color spaces that are derivable to CIE XYZ
-space can be added using the
-.PN XcmsAddColorSpace
-function.
-.IP \(bu 5
-Color Characterization Function Set
-.IP
-A Color Characterization Function Set consists of
-device-dependent color spaces and their functions that
-convert between these color spaces and the CIE XYZ
-color space, bundled together for a specific class of output devices.
-A function set can be added using the
-.PN XcmsAddFunctionSet
-function.
-.NH 3
-Color Spaces
-.XS
-\*(SN Color Spaces
-.XE
-.LP
-The CIE XYZ color space serves as the hub for all
-conversions between device-independent and device-dependent color spaces.
-Therefore, the knowledge to convert an 
-.PN XcmsColor
-structure to and from CIE XYZ format is associated with each color space.
-For example, conversion from CIE L*u*v* to RGB requires the knowledge
-to convert from CIE L*u*v* to CIE XYZ and from CIE XYZ to RGB.
-This knowledge is stored as an array of functions that,
-when applied in series, will convert the 
-.PN XcmsColor
-structure to or from CIE XYZ format.
-This color specification conversion mechanism facilitates
-the addition of color spaces.
-.LP
-Of course, when converting between only device-independent color spaces
-or only device-dependent color spaces,
-shortcuts are taken whenever possible.
-For example, conversion from TekHVC to CIE L*u*v* is performed 
-by intermediate conversion to CIE u*v*Y and then to CIE L*u*v*, 
-thus bypassing conversion between CIE u*v*Y and CIE XYZ.
-.NH 3
-Adding Device-Independent Color Spaces
-.XS
-\*(SN Adding Device-Independent Color Spaces
-.XE
-.LP
-To add a device-independent color space, use
-.PN XcmsAddColorSpace .
-.IN  "XcmsAddColorSpace" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsAddColorSpace\^(\^\fIcolor_space\fP\^)
-.br
-      XcmsColorSpace *\fIcolor_space\fP\^;
-.FN
-.IP \fIcolor_space\fP 1i
-Specifies the device-independent color space to add.
-.LP
-.eM
-The
-.PN XcmsAddColorSpace
-function makes a device-independent color space (actually an
-.PN XcmsColorSpace
-structure) accessible by the color management system.
-Because format values for unregistered color spaces are assigned at run time,
-they should be treated as private to the client.
-If references to an unregistered color space must be made
-outside the client (for example, storing color specifications 
-in a file using the unregistered color space), 
-then reference should be made by color space prefix
-(see
-.PN XcmsFormatOfPrefix
-and
-.PN XcmsPrefixOfFormat ).
-.LP
-If the 
-.PN XcmsColorSpace
-structure is already accessible in the color management system, 
-.PN XcmsAddColorSpace
-returns 
-.PN XcmsSuccess .
-.LP
-Note that added 
-.PN XcmsColorSpaces
-must be retained for reference by Xlib.
-.NH 3
-Querying Color Space Format and Prefix
-.XS
-\*(SN Querying Color Space Format and Prefix
-.XE
-.LP
-To obtain the format associated with the color space
-associated with a specified color string prefix, use
-.PN XcmsFormatOfPrefix .
-.IN  "XcmsFormatOfPrefix" "" "@DEF@"
-.sM
-.FD 0
-XcmsColorFormat XcmsFormatOfPrefix\^(\^\fIprefix\fP\^)
-.br
-      char *\fIprefix\fP\^;
-.FN
-.IP \fIprefix\fP 1i
-Specifies the string that contains the color space prefix.
-.LP
-.eM
-The
-.PN XcmsFormatOfPrefix
-function returns the format for the specified color space prefix
-(for example, the string ``CIEXYZ'').
-The prefix is case-insensitive.
-If the color space is not accessible in the color management system,
-.PN XcmsFormatOfPrefix
-returns 
-.PN XcmsUndefinedFormat .
-.LP
-.sp
-To obtain the color string prefix associated with the color space
-specified by a color format, use
-.PN XcmsPrefixOfFormat .
-.IN  "XcmsPrefixOfFormat" "" "@DEF@"
-.sM
-.FD 0
-char *XcmsPrefixOfFormat\^(\^\fIformat\fP\^)
-.br
-      XcmsColorFormat \fIformat\fP\^;
-.FN
-.IP \fIformat\fP 1i
-Specifies the color specification format.
-.LP
-.eM
-The
-.PN XcmsPrefixOfFormat
-function returns the string prefix associated with the color specification
-encoding specified by the format argument.
-Otherwise, if no encoding is found, it returns NULL.
-The returned string must be treated as read-only.
-.NH 3
-Creating Additional Color Spaces
-.XS
-\*(SN Creating Additional Color Spaces
-.XE
-.LP
-Color space specific information necessary 
-for color space conversion and color string parsing is stored in an
-.PN XcmsColorSpace
-structure.
-Therefore, a new structure containing this information is required
-for each additional color space.
-In the case of device-independent color spaces,
-a handle to this new structure (that is, by means of a global variable)
-is usually made accessible to the client program for use with the
-.PN XcmsAddColorSpace
-function.
-.LP
-If a new 
-.PN XcmsColorSpace
-structure specifies a color space not registered with the X Consortium,
-they should be treated as private to the client
-because format values for unregistered color spaces are assigned at run time.
-If references to an unregistered color space must be made outside the
-client (for example, storing color specifications in a file using the
-unregistered color space), then reference should be made by color space prefix
-(see
-.PN XcmsFormatOfPrefix
-and
-.PN XcmsPrefixOfFormat ).
-.sM
-.LP
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef (*XcmsConversionProc)();
-typedef XcmsConversionProc *XcmsFuncListPtr;
-		/* A NULL terminated list of function pointers*/
-
-typedef struct _XcmsColorSpace {
-	char *prefix;
-	XcmsColorFormat format;
-	XcmsParseStringProc parseString;
-	XcmsFuncListPtr to_CIEXYZ;
-	XcmsFuncListPtr from_CIEXYZ;
-	int inverse_flag;
-} XcmsColorSpace;
-.De
-.LP
-.eM
-The prefix member specifies the prefix that indicates a color string 
-is in this color space's string format.
-For example, the strings ``ciexyz'' or ``CIEXYZ'' for CIE XYZ,
-and ``rgb'' or ``RGB'' for RGB.
-The prefix is case insensitive.
-The format member specifies the color specification format.
-Formats for unregistered color spaces are assigned at run time.
-The parseString member contains a pointer to the function 
-that can parse a color string into an 
-.PN XcmsColor
-structure.
-This function returns an integer (int): nonzero if it succeeded
-and zero otherwise.
-The to_CIEXYZ and from_CIEXYZ members contain pointers,
-each to a NULL terminated list of function pointers.
-When the list of functions is executed in series,
-it will convert the color specified in an 
-.PN XcmsColor
-structure from/to the current color space format to/from the CIE XYZ format.
-Each function returns an integer (int): nonzero if it succeeded
-and zero otherwise.
-The white point to be associated with the colors is specified
-explicitly, even though white points can be found in the CCC.
-The inverse_flag member, if nonzero, specifies that for each function listed 
-in to_CIEXYZ,
-its inverse function can be found in from_CIEXYZ such that:
-.LP
-.Ds 0
-Given:  n = number of functions in each list
-
-for each i, such that 0 <= i < n
-    from_CIEXYZ[n - i - 1] is the inverse of to_CIEXYZ[i].
-.De
-.LP
-This allows Xlib to use the shortest conversion path,
-thus bypassing CIE XYZ if possible (for example, TekHVC to CIE L*u*v*).
-.NH 3
-Parse String Callback
-.XS
-\*(SN Parse String Callback
-.XE
-.LP
-The callback in the
-.PN XcmsColorSpace
-structure for parsing a color string for the particular color space must
-adhere to the following software interface specification:
-.IN  "XcmsParseStringProc" "" "@DEF@"
-.sM
-.FD 0
-typedef int (*XcmsParseStringProc)\^(\^\fIcolor_string\fP, \fIcolor_return\fP\^)
-.br
-      char *\fIcolor_string\fP\^;
-.br
-      XcmsColor *\fIcolor_return\fP\^;
-.FN
-.IP \fIcolor_string\fP 1i
-Specifies the color string to parse.
-.IP \fIcolor_return\fP 1i
-Returns the color specification in the color space's format.
-.LP
-.eM
-.NH 3
-Color Specification Conversion Callback
-.XS
-\*(SN Color Specification Conversion Callback
-.XE
-.LP
-Callback functions in the
-.PN XcmsColorSpace
-structure for converting a color specification between device-independent
-spaces must adhere to the
-following software interface specification:
-.sM
-.FD 0
-Status ConversionProc\^(\^\fIccc\fP, \fIwhite_point\fP, \fIcolors_in_out\fP, \fIncolors\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsColor *\fIwhite_point\fP\^;
-.br
-      XcmsColor *\fIcolors_in_out\fP\^;
-.br
-      unsigned int \fIncolors\fP\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-.IP \fIwhite_point\fP 1i
-Specifies the white point associated with color specifications.
-The pixel member should be ignored,
-and the entire structure remain unchanged upon return.
-.IP \fIcolors_in_out\fP 1i
-Specifies an array of color specifications.
-Pixel members should be ignored and must remain unchanged upon return.
-.IP \fIncolors\fP 1i
-Specifies the number of 
-.PN XcmsColor
-structures in the color-specification array.
-.LP
-.eM
-.sp
-Callback functions in the
-.PN XcmsColorSpace
-structure for converting a color specification to or from a device-dependent
-space must adhere to the
-following software interface specification:
-.sM
-.FD 0
-Status ConversionProc\^(\^\fIccc\fP, \fIcolors_in_out\fP, \fIncolors\fP, \fIcompression_flags_return\fP\^)
-.br
-      XcmsCCC \fIccc\fP\^;
-.br
-      XcmsColor *\fIcolors_in_out\fP\^;
-.br
-      unsigned int \fIncolors\fP\^;
-.br
-      Bool \fIcompression_flags_return\fP\^[\^]\^;
-.FN
-.IP \fIccc\fP 1i
-Specifies the CCC.
-.IP \fIcolors_in_out\fP 1i
-Specifies an array of color specifications.
-Pixel members should be ignored and must remain unchanged upon return.
-.IP \fIncolors\fP 1i
-Specifies the number of 
-.PN XcmsColor
-structures in the color-specification array.
-.IP \fIcompression_flags_return\fP 1i
-Returns an array of Boolean values for indicating compression status.
-If a non-NULL pointer is supplied
-and a color at a given index is compressed, then
-.PN True
-should be stored at the corresponding index in this array;
-otherwise, the array should not be modified.
-.LP
-.eM
-Conversion functions are available globally for use by other color
-spaces.
-The conversion functions provided by Xlib are:
-.TS H
-lw(1.8i) lw(1.8i) lw(1.8i).
-_
-.sp 6p
-.B
-Function	Converts from	Converts to
-.sp 6p
-_
-.sp 6p
-.TH
-.R
-T{
-.PN XcmsCIELabToCIEXYZ
-T}	T{
-.PN XcmsCIELabFormat
-T}	T{
-.PN XcmsCIEXYZFormat
-T}
-T{
-.PN XcmsCIELuvToCIEuvY
-T}	T{
-.PN XcmsCIELuvFormat
-T}	T{
-.PN XcmsCIEuvYFormat
-T}
-T{
-.PN XcmsCIEXYZToCIELab
-T}	T{
-.PN XcmsCIEXYZFormat
-T}	T{
-.PN XcmsCIELabFormat
-T}
-T{
-.PN XcmsCIEXYZToCIEuvY
-T}	T{
-.PN XcmsCIEXYZFormat
-T}	T{
-.PN XcmsCIEuvYFormat
-T}
-T{
-.PN XcmsCIEXYZToCIExyY
-T}	T{
-.PN XcmsCIEXYZFormat
-T}	T{
-.PN XcmsCIExyYFormat
-T}
-T{
-.PN XcmsCIEXYZToRGBi
-T}	T{
-.PN XcmsCIEXYZFormat
-T}	T{
-.PN XcmsRGBiFormat
-T}
-T{
-.PN XcmsCIEuvYToCIELuv
-T}	T{
-.PN XcmsCIEuvYFormat
-T}	T{
-.PN XcmsCIELabFormat
-T}
-T{
-.PN XcmsCIEuvYToCIEXYZ
-T}	T{
-.PN XcmsCIEuvYFormat
-T}	T{
-.PN XcmsCIEXYZFormat
-T}
-T{
-.PN XcmsCIEuvYToTekHVC
-T}	T{
-.PN XcmsCIEuvYFormat
-T}	T{
-.PN XcmsTekHVCFormat
-T}
-T{
-.PN XcmsCIExyYToCIEXYZ
-T}	T{
-.PN XcmsCIExyYFormat
-T}	T{
-.PN XcmsCIEXYZFormat
-T}
-T{
-.PN XcmsRGBToRGBi
-T}	T{
-.PN XcmsRGBFormat
-T}	T{
-.PN XcmsRGBiFormat
-T}
-T{
-.PN XcmsRGBiToCIEXYZ
-T}	T{
-.PN XcmsRGBiFormat
-T}	T{
-.PN XcmsCIEXYZFormat
-T}
-T{
-.PN XcmsRGBiToRGB
-T}	T{
-.PN XcmsRGBiFormat
-T}	T{
-.PN XcmsRGBFormat
-T}
-T{
-.PN XcmsTekHVCToCIEuvY
-T}	T{
-.PN XcmsTekHVCFormat
-T}	T{
-.PN XcmsCIEuvYFormat
-T}
-.sp 6p
-_
-.TE
-.NH 3
-Function Sets
-.XS
-\*(SN Function Sets
-.XE
-.IN "Function set"
-.IN "Function set" "LINEAR_RGB"
-.LP
-Functions to convert between device-dependent color spaces
-and CIE XYZ may differ for different classes of output devices
-(for example, color versus gray monitors).
-Therefore, the notion of a Color Characterization Function Set
-has been developed.
-A function set consists of device-dependent color spaces
-and the functions that convert color specifications 
-between these device-dependent color spaces and the CIE XYZ color space
-appropriate for a particular class of output devices.
-The function set also contains a function that reads
-color characterization data off root window properties.
-It is this characterization data that will differ between devices within
-a class of output devices.
-.IN "Device Color Characterization"
-For details about how color characterization data is
-stored in root window properties,
-see the section on Device Color Characterization in the
-\fIInter-Client Communication Conventions Manual\fP.
-The LINEAR_RGB function set is provided by Xlib
-and will support most color monitors.
-Function sets may require data that differs
-from those needed for the LINEAR_RGB function set.
-In that case, 
-its corresponding data may be stored on different root window properties.
-.NH 3
-Adding Function Sets
-.XS
-\*(SN Adding Function Sets
-.XE
-.LP
-To add a function set, use
-.PN XcmsAddFunctionSet .
-.IN  "XcmsAddFunctionSet" "" "@DEF@"
-.sM
-.FD 0
-Status XcmsAddFunctionSet\^(\^\fIfunction_set\fP\^)
-.br
-      XcmsFunctionSet *\fIfunction_set\fP\^;
-.FN
-.IP \fIfunction_set\fP 1i
-Specifies the function set to add.
-.LP
-.eM
-The
-.PN XcmsAddFunctionSet
-function adds a function set to the color management system.
-If the function set uses device-dependent 
-.PN XcmsColorSpace
-structures not accessible in the color management system,
-.PN XcmsAddFunctionSet
-adds them.
-If an added
-.PN XcmsColorSpace
-structure is for a device-dependent color space not registered
-with the X Consortium,
-they should be treated as private to the client
-because format values for unregistered color spaces are assigned at run time.
-If references to an unregistered color space must be made outside the
-client (for example, storing color specifications in a file
-using the unregistered color space),
-then reference should be made by color space prefix
-(see 
-.PN XcmsFormatOfPrefix
-and
-.PN XcmsPrefixOfFormat ).
-.LP
-Additional function sets should be added before any calls to other
-Xlib routines are made.
-If not, the 
-.PN XcmsPerScrnInfo
-member of a previously created 
-.PN XcmsCCC
-does not have the opportunity to initialize
-with the added function set.
-.NH 3
-Creating Additional Function Sets
-.XS
-\*(SN Creating Additional Function Sets
-.XE
-.LP
-The creation of additional function sets should be
-required only when an output device does not conform to existing 
-function sets or when additional device-dependent color spaces are necessary.
-A function set consists primarily of a collection of device-dependent
-.PN XcmsColorSpace
-structures and a means to read and store a 
-screen's color characterization data.
-This data is stored in an
-.PN XcmsFunctionSet
-structure.
-A handle to this structure (that is, by means of global variable)
-is usually made accessible to the client program for use with
-.PN XcmsAddFunctionSet .
-.LP
-If a function set uses new device-dependent 
-.PN XcmsColorSpace
-structures,
-they will be transparently processed into the color management system.
-Function sets can share an 
-.PN XcmsColorSpace
-structure for a device-dependent color space.
-In addition, multiple 
-.PN XcmsColorSpace
-structures are allowed for a device-dependent color space;
-however, a function set can reference only one of them.
-These 
-.PN XcmsColorSpace
-structures will differ in the functions to convert to and from CIE XYZ,
-thus tailored for the specific function set.
-.sM
-.LP
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct _XcmsFunctionSet {
-	XcmsColorSpace **DDColorSpaces;
-	XcmsScreenInitProc screenInitProc;
-	XcmsScreenFreeProc screenFreeProc;
-} XcmsFunctionSet;
-.De
-.LP
-.eM
-The DDColorSpaces member is a pointer to a NULL terminated list
-of pointers to 
-.PN XcmsColorSpace
-structures for the device-dependent color spaces that are supported
-by the function set.
-The screenInitProc member is set to the callback procedure (see the following
-interface specification) that initializes the 
-.PN XcmsPerScrnInfo
-structure for a particular screen.
-.LP
-The screen initialization callback must adhere to the following software
-interface specification:
-.IN  "XcmsScreenInitProc" "" "@DEF@"
-.sM
-.FD 0
-typedef Status (*XcmsScreenInitProc)\^(\^\fIdisplay\fP, \fIscreen_number\fP, \fIscreen_info\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIscreen_number\fP\^;
-.br
-      XcmsPerScrnInfo *\fIscreen_info\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIscreen_number\fP 1i
-Specifies the appropriate screen number on the host server.
-.IP \fIscreen_info\fP 1i
-Specifies the 
-.PN XcmsPerScrnInfo 
-structure, which contains the per screen information.
-.LP
-.eM
-The screen initialization callback in the
-.PN XcmsFunctionSet
-structure fetches the color characterization data (device profile) for
-the specified screen,
-typically off properties on the 
-screen's root window.
-It then initializes the specified
-.PN XcmsPerScrnInfo
-structure.
-.IN "Device profile"
-.IN "Color Characterization Data"
-If successful, the procedure fills in the 
-.PN XcmsPerScrnInfo
-structure as follows:
-.IP \(bu 5
-It sets the screenData member to the address 
-of the created device profile data structure 
-(contents known only by the function set).
-.IP \(bu 5
-It next sets the screenWhitePoint member.
-.IP \(bu 5
-It next sets the functionSet member to the address of the
-.PN XcmsFunctionSet
-structure.
-.IP \(bu 5
-It then sets the state member to 
-.PN XcmsInitSuccess 
-and finally returns
-.PN XcmsSuccess .
-.LP
-If unsuccessful, the procedure sets the state member to 
-.PN XcmsInitFailure
-and returns
-.PN XcmsFailure .
-.LP
-The
-.PN XcmsPerScrnInfo
-structure contains:
-.sM
-.LP
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct _XcmsPerScrnInfo {
-	XcmsColor screenWhitePoint;
-	XPointer functionSet;
-	XPointer screenData;
-	unsigned char state;
-	char pad[3];
-} XcmsPerScrnInfo;
-.De
-.LP
-.eM
-The screenWhitePoint member specifies the white point inherent to
-the screen.
-The functionSet member specifies the appropriate function set.
-The screenData member specifies the device profile.
-The state member is set to one of the following:
-.IP \(bu 5
-.PN XcmsInitNone
-indicates initialization has not been previously attempted.
-.IP \(bu 5
-.PN XcmsInitFailure
-indicates initialization has been previously attempted but failed.
-.IP \(bu 5
-.PN XcmsInitSuccess
-indicates initialization has been previously attempted and succeeded.
-.LP
-The screen free callback must adhere to the following software
-interface specification:
-.IN  "XcmsScreenFreeProc" "" "@DEF@"
-.sM
-.FD 0
-typedef void (*XcmsScreenFreeProc)\^(\^\fIscreenData\fP\^)
-.br
-      XPointer \fIscreenData\fP\^;
-.FN
-.IP \fIscreenData\fP 1i
-Specifies the data to be freed.
-.LP
-.eM
-This function is called to free the screenData stored in an
-.PN XcmsPerScrnInfo
-structure.
-.bp
diff --git a/libX11/specs/libX11/CH06.xml b/libX11/specs/libX11/CH06.xml
new file mode 100644
index 000000000..9ca12db0c
--- /dev/null
+++ b/libX11/specs/libX11/CH06.xml
@@ -0,0 +1,7439 @@
+<chapter id="color_management_functions">

+<title>Color Management Functions</title>

+<!-- .sp 2 -->

+<!-- .nr H1 6 -->

+<!-- .nr H2 0 -->

+<!-- .nr H3 0 -->

+<!-- .nr H4 0 -->

+<!-- .nr H5 0 -->

+<!-- .na -->

+<para>

+<!-- .LP -->

+<!-- .XS -->

+<!-- Chapter 6: Color Management Functions  -->

+<!-- .XE -->

+Each X window always has an associated colormap that

+provides a level of indirection between pixel values and colors displayed

+on the screen.

+Xlib provides functions that you can use to manipulate a colormap.

+The X protocol defines colors using values in the <acronym>RGB</acronym> color space.

+The <acronym>RGB</acronym> color space is device dependent;

+rendering an <acronym>RGB</acronym> value on differing output devices typically results

+in different colors.

+Xlib also provides a means for clients to specify color using

+device-independent color spaces for consistent results across devices.

+Xlib supports device-independent color spaces derivable from the <acronym>CIE</acronym> XYZ

+color space.

+This includes the <acronym>CIE</acronym> XYZ, xyY, L*u*v*, and L*a*b* color spaces as well as

+the TekHVC color space.

+</para>

+<para>

+<!-- .LP -->

+This chapter discusses how to:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Create, copy, and destroy a colormap

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Specify colors by name or value

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Allocate, modify, and free color cells

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Read entries in a colormap

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Convert between color spaces

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Control aspects of color conversion

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Query the color gamut of a screen

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Add new color spaces

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+All functions, types, and symbols in this chapter with the prefix ``Xcms''

+are defined in

+<!-- .hN X11/Xcms.h . -->

+The remaining functions and types are defined in

+<!-- .hN X11/Xlib.h . -->

+</para>

+<para>

+<!-- .LP -->

+Functions in this chapter manipulate the representation of color on the

+screen.

+For each possible value that a pixel can take in a window,

+there is a color cell in the colormap.

+For example, 

+if a window is 4 bits deep, pixel values 0 through 15 are defined. 

+A colormap is a collection of color cells.

+A color cell consists of a triple of red, green, and blue (<acronym>RGB</acronym>) values.

+The hardware imposes limits on the number of significant

+bits in these values.

+As each pixel is read out of display memory, the pixel

+is looked up in a colormap.

+The <acronym>RGB</acronym> value of the cell determines what color is displayed on the screen.

+On a grayscale display with a black-and-white monitor, 

+the values are combined to determine the brightness on the screen.

+</para>

+<para>

+<!-- .LP -->

+Typically, an application allocates color cells or sets of color cells

+to obtain the desired colors.

+The client can allocate read-only cells.

+In which case, 

+the pixel values for these colors can be shared among multiple applications, 

+and the <acronym>RGB</acronym> value of the cell cannot be changed.

+If the client allocates read/write cells,

+they are exclusively owned by the client,

+and the color associated with the pixel value can be changed at will.

+Cells must be allocated (and, if read/write, initialized with an <acronym>RGB</acronym> value)

+by a client to obtain desired colors.

+The use of pixel value for an

+unallocated cell results in an undefined color.

+</para>

+<para>

+<!-- .LP -->

+Because colormaps are associated with windows, X supports displays

+with multiple colormaps and, indeed, different types of colormaps.

+If there are insufficient colormap resources in the display,

+some windows will display in their true colors, and others

+will display with incorrect colors.

+A window manager usually controls which windows are displayed

+in their true colors if more than one colormap is required for

+the color resources the applications are using.

+At any time, there is a set of installed colormaps for a screen.

+Windows using one of the installed colormaps display with true colors, and

+windows using other colormaps generally display with incorrect colors.

+You can control the set of installed colormaps by using

+<function>XInstallColormap</function>

+and

+<function>XUninstallColormap</function>.

+</para>

+<para>

+<!-- .LP -->

+Colormaps are local to a particular screen.

+Screens always have a default colormap,

+and programs typically allocate cells out of this colormap.

+Generally, you should not write applications that monopolize 

+color resources.

+Although some hardware supports multiple colormaps installed at one time,

+many of the hardware displays

+built today support only a single installed colormap, so the primitives

+are written to encourage sharing of colormap entries between applications.

+</para>

+<para>

+<!-- .LP -->

+The 

+<function>DefaultColormap </function>

+macro returns the default colormap.

+The 

+<function>DefaultVisual </function>

+macro

+returns the default visual type for the specified screen.

+<indexterm><primary>Color map</primary></indexterm>

+Possible visual types are 

+<function>StaticGray</function>,

+<function>GrayScale</function>,

+<function>StaticColor</function>,

+<function>PseudoColor</function>,

+<function>TrueColor</function>,

+or 

+<function>DirectColor </function>

+(see section 3.1).

+</para>

+<sect1 id="Color_Structures">

+<title>Color Structures</title>

+<!-- .XS -->

+<!-- (SN Color Structures -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Functions that operate only on <acronym>RGB</acronym> color space values use an

+<function>XColor</function>

+structure, which contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XColor</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct {

+	unsigned long pixel;	/* pixel value */

+	unsigned short red, green, blue;	/* rgb values */

+	char flags;	/* DoRed, DoGreen, DoBlue */	

+	char pad;

+} XColor;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The red, green, and blue values are always in the range 0 to 65535

+inclusive, independent of the number of bits actually used in the

+display hardware.

+The server scales these values down to the range used by the hardware.

+Black is represented by (0,0,0), 

+and white is represented by (65535,65535,65535).

+<indexterm><primary>Color</primary></indexterm>

+In some functions,

+the flags member controls which of the red, green, and blue members is used 

+and can be the inclusive OR of zero or more of

+<function>DoRed</function>,

+<function>DoGreen</function>,

+and 

+<function>DoBlue</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+Functions that operate on all color space values use an

+<function>XcmsColor</function>

+structure.

+This structure contains a union of substructures,

+each supporting color specification encoding for a particular color space.

+Like the

+<function>XColor</function>

+structure, the

+<function>XcmsColor</function>

+structure contains pixel

+and color specification information (the spec member in the 

+<function>XcmsColor</function>

+structure).

+<indexterm significance="preferred"><primary>XcmsColor</primary></indexterm>

+<!-- .sM -->

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA .5i 1i 2.5i -->

+<!-- .ta .5i 1i 2.5i -->

+typedef unsigned long XcmsColorFormat;			/* Color Specification Format */

+

+typedef struct {

+	union {

+		XcmsRGB RGB;

+		XcmsRGBi RGBi;

+		XcmsCIEXYZ CIEXYZ;

+		XcmsCIEuvY CIEuvY;

+		XcmsCIExyY CIExyY;

+		XcmsCIELab CIELab;

+		XcmsCIELuv CIELuv;

+		XcmsTekHVC TekHVC;

+		XcmsPad Pad;

+	} spec;

+	unsigned long pixel;

+	XcmsColorFormat format;

+} XcmsColor;			/* Xcms Color Structure */

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Because the color specification can be encoded for the various color spaces, 

+encoding for the spec member is identified by the format member,

+which is of type

+<function>XcmsColorFormat</function>.

+The following macros define standard formats.

+<!-- .sM -->

+</para>

+

+<literallayout class="monospaced">

+#define          XcmsUndefinedFormat    0x00000000  

+#define          XcmsCIEXYZFormat      0x00000001  /* CIE XYZ */

+#define          XcmsCIEuvYFormat      0x00000002  /* CIE u'v'Y */

+#define          XcmsCIExyYFormat      0x00000003  /* CIE xyY */

+#define          XcmsCIELabFormat      0x00000004  /* CIE L*a*b* */

+#define          XcmsCIELuvFormat      0x00000005  /* CIE L*u*v* */

+#define          XcmsTekHVCFormat      0x00000006  /* TekHVC */

+#define          XcmsRGBFormat         0x80000000  /* RGB Device */

+#define          XcmsRGBiFormat        0x80000001  /* RGB Intensity */

+</literallayout>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Formats for device-independent color spaces are

+distinguishable from those for device-dependent spaces by the 32nd bit.

+If this bit is set,

+it indicates that the color specification is in a device-dependent form;

+otherwise, it is in a device-independent form.

+If the 31st bit is set,

+this indicates that the color space has been added to Xlib at run time

+(see section 6.12.4).

+The format value for a color space added at run time may be different each

+time the program is executed.

+If references to such a color space must be made outside the client

+(for example, storing a color specification in a file),

+then reference should be made by color space string prefix

+(see 

+<function>XcmsFormatOfPrefix</function>

+and

+<function>XcmsPrefixOfFormat</function>).

+</para>

+<para>

+<!-- .LP -->

+Data types that describe the color specification encoding for the various

+color spaces are defined as follows:

+<!-- .sM -->

+<indexterm significance="preferred"><primary>XcmsRGB</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef double XcmsFloat;

+

+typedef struct {

+	unsigned short red;	/* 0x0000 to 0xffff */

+	unsigned short green;	/* 0x0000 to 0xffff */

+	unsigned short blue;	/* 0x0000 to 0xffff */

+} XcmsRGB;		/* RGB Device */

+</literallayout>

+<indexterm significance="preferred"><primary>XcmsRGBi</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct {

+	XcmsFloat red;	/* 0.0 to 1.0 */

+	XcmsFloat green;	/* 0.0 to 1.0 */

+	XcmsFloat blue;	/* 0.0 to 1.0 */

+} XcmsRGBi;		/* RGB Intensity */

+</literallayout>

+<indexterm significance="preferred"><primary>XcmsCIEXYZ</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct {

+	XcmsFloat X;

+	XcmsFloat Y;	/* 0.0 to 1.0 */

+	XcmsFloat Z;

+} XcmsCIEXYZ;		/* CIE XYZ */

+</literallayout>

+<indexterm significance="preferred"><primary>XcmsCIEuvY</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct {

+	XcmsFloat u_prime;	/* 0.0 to ~0.6 */

+	XcmsFloat v_prime;	/* 0.0 to ~0.6 */

+	XcmsFloat Y; 	/* 0.0 to 1.0 */

+} XcmsCIEuvY;		/* CIE u'v'Y */

+</literallayout>

+<indexterm significance="preferred"><primary>XcmsCIExyY</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct {

+	XcmsFloat x; 	/* 0.0 to ~.75 */

+	XcmsFloat y; 	/* 0.0 to ~.85 */

+	XcmsFloat Y; 	/* 0.0 to 1.0 */

+} XcmsCIExyY;		/* CIE xyY */

+</literallayout>

+<indexterm significance="preferred"><primary>XcmsCIELab</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct {

+	XcmsFloat L_star; 	/* 0.0 to 100.0 */

+	XcmsFloat a_star;

+	XcmsFloat b_star;

+} XcmsCIELab;		/* CIE L*a*b* */

+</literallayout>

+<indexterm significance="preferred"><primary>XcmsCIELuv</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct {

+	XcmsFloat L_star; 	/* 0.0 to 100.0 */

+	XcmsFloat u_star;

+	XcmsFloat v_star;

+} XcmsCIELuv;		/* CIE L*u*v* */

+</literallayout>

+<indexterm significance="preferred"><primary>XcmsTekHVC</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct {

+	XcmsFloat H; 	/* 0.0 to 360.0 */

+	XcmsFloat V; 	/* 0.0 to 100.0 */

+	XcmsFloat C; 	/* 0.0 to 100.0 */

+} XcmsTekHVC;		/* TekHVC */

+</literallayout>

+<indexterm significance="preferred"><primary>XcmsPad</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct {

+	XcmsFloat pad0;

+	XcmsFloat pad1;

+	XcmsFloat pad2;

+	XcmsFloat pad3;

+} XcmsPad;		/* four doubles */

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The device-dependent formats provided allow color specification in:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+<acronym>RGB</acronym> Intensity

+(<function>XcmsRGBi</function>)

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Red, green, and blue linear intensity values,

+floating-point values from 0.0 to 1.0,

+where 1.0 indicates full intensity, 0.5 half intensity, and so on.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<acronym>RGB</acronym> Device

+(<function>XcmsRGB</function>)

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Red, green, and blue values appropriate for the specified output device.

+<function>XcmsRGB</function>

+values are of type unsigned short,

+scaled from 0 to 65535 inclusive,

+and are interchangeable with the red, green, and blue values in an 

+<function>XColor</function>

+structure. 

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+It is important to note that <acronym>RGB</acronym> Intensity values are not gamma corrected

+values.

+In contrast,

+<acronym>RGB</acronym> Device values generated as a result of converting color specifications 

+are always gamma corrected, and

+<acronym>RGB</acronym> Device values acquired as a result of querying a colormap

+or passed in by the client are assumed by Xlib to be gamma corrected.

+The term <emphasis remap='I'><acronym>RGB</acronym> value</emphasis> in this manual always refers to an <acronym>RGB</acronym> Device value.

+</para>

+</sect1>

+<sect1 id="Color_Strings">

+<title>Color Strings</title>

+<!-- .XS -->

+<!-- (SN Color Strings -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides a mechanism for using string names for colors.

+A color string may either contain an abstract color name

+or a numerical color specification.

+Color strings are case-insensitive.

+</para>

+<para>

+<!-- .LP -->

+Color strings are used in the following functions:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+<function>XAllocNamedColor</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XcmsAllocNamedColor</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XLookupColor</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XcmsLookupColor</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XParseColor</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XStoreNamedColor</function>

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+Xlib supports the use of abstract color names, for example, red or blue.

+A value for this abstract name is obtained by searching one or more color

+name databases.

+Xlib first searches zero or more client-side databases;

+the number, location, and content of these databases is

+implementation-dependent and might depend on the current locale.

+If the name is not found, Xlib then looks for the color in the

+X server's database.

+If the color name is not in the Host Portable Character Encoding,

+the result is implementation-dependent.

+</para>

+<para>

+<!-- .LP -->

+A numerical color specification

+consists of a color space name and a set of values in the following syntax:

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+<emphasis remap='I'>&lt;color_space_name&gt;</emphasis>:<emphasis remap='I'>&lt;value&gt;/.../&lt;value&gt;</emphasis>

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The following are examples of valid color strings.

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+"CIEXYZ:0.3227/0.28133/0.2493"

+"RGBi:1.0/0.0/0.0"

+"rgb:00/ff/00"

+"CIELuv:50.0/0.0/0.0"

+</literallayout>

+The syntax and semantics of numerical specifications are given

+for each standard color space in the following sections.

+</para>

+<sect2 id="RGB_Device_String_Specification">

+<title><acronym>RGB</acronym> Device String Specification</title>

+<!-- .XS -->

+<!-- (SN <acronym>RGB</acronym> Device String Specification -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+An <acronym>RGB</acronym> Device specification is identified by

+the prefix ``rgb:'' and conforms to the following syntax:

+</para>

+<para>

+<!-- .LP -->

+<!-- .\" Start marker code here -->

+<literallayout class="monospaced">

+rgb:<emphasis remap='I'>&lt;red&gt;/&lt;green&gt;/&lt;blue&gt;</emphasis>

+

+    <emphasis remap='I'>&lt;red&gt;</emphasis>, <emphasis remap='I'>&lt;green&gt;</emphasis>, <emphasis remap='I'>&lt;blue&gt;</emphasis> := <emphasis remap='I'>h</emphasis> | <emphasis remap='I'>hh</emphasis> | <emphasis remap='I'>hhh</emphasis> | <emphasis remap='I'>hhhh</emphasis>

+    <emphasis remap='I'>h</emphasis> := single hexadecimal digits (case insignificant)

+</literallayout>

+<!-- .\" End marker code here -->

+</para>

+<para>

+<!-- .LP -->

+Note that <emphasis remap='I'>h</emphasis> indicates the value scaled in 4 bits, 

+<emphasis remap='I'>hh</emphasis> the value scaled in 8 bits,

+<emphasis remap='I'>hhh</emphasis> the value scaled in 12 bits,

+and <emphasis remap='I'>hhhh</emphasis> the value scaled in 16 bits, respectively.

+</para>

+<para>

+<!-- .LP -->

+Typical examples are the strings ``rgb:ea/75/52'' and ``rgb:ccc/320/320'',

+but mixed numbers of hexadecimal digit strings 

+(``rgb:ff/a5/0'' and ``rgb:ccc/32/0'')

+are also allowed.

+</para>

+<para>

+<!-- .LP -->

+For backward compatibility, an older syntax for <acronym>RGB</acronym> Device is

+supported, but its continued use is not encouraged.

+The syntax is an initial sharp sign character followed by

+a numeric specification, in one of the following formats:

+</para>

+<para>

+<!-- .LP -->

+<!-- .\" Start marker code here -->

+<literallayout class="monospaced">

+<!-- .TA 2i -->

+<!-- .ta 2i -->

+#RGB	(4 bits each)

+#RRGGBB	(8 bits each)

+#RRRGGGBBB	(12 bits each)

+#RRRRGGGGBBBB	(16 bits each)

+</literallayout>

+<!-- .\" End marker code here -->

+</para>

+<para>

+<!-- .LP -->

+The R, G, and B represent single hexadecimal digits.

+When fewer than 16 bits each are specified, 

+they represent the most significant bits of the value

+(unlike the ``rgb:'' syntax, in which values are scaled).

+For example, the string ``#3a7'' is the same as ``#3000a0007000''.

+</para>

+</sect2>

+<sect2 id="RGB_Intensity_String_Specification">

+<title><acronym>RGB</acronym> Intensity String Specification</title>

+<!-- .XS -->

+<!-- (SN RGB Intensity String Specification -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+An <acronym>RGB</acronym> intensity specification is identified

+by the prefix ``rgbi:'' and conforms to the following syntax:

+</para>

+<para>

+<!-- .LP -->

+<!-- .\" Start marker code here -->

+<literallayout class="monospaced">

+rgbi:<emphasis remap='I'>&lt;red&gt;/&lt;green&gt;/&lt;blue&gt;</emphasis>

+</literallayout>

+<!-- .\" End marker code here -->

+</para>

+<para>

+<!-- .LP -->

+Note that red, green, and blue are floating-point values

+between 0.0 and 1.0, inclusive.

+The input format for these values is an optional sign,

+a string of numbers possibly containing a decimal point,

+and an optional exponent field containing an E or e 

+followed by a possibly signed integer string.

+</para>

+</sect2>

+<sect2 id="Device_Independent_String_Specifications">

+<title>Device-Independent String Specifications</title>

+<!-- .XS -->

+<!-- (SN Device-Independent String Specifications -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The standard device-independent string specifications have

+the following syntax:

+</para>

+<para>

+<!-- .LP -->

+<!-- .\" Start marker code here -->

+<literallayout class="monospaced">

+CIEXYZ:<emphasis remap='I'>&lt;X&gt;/&lt;Y&gt;/&lt;Z&gt;</emphasis>

+CIEuvY:<emphasis remap='I'>&lt;u&gt;/&lt;v&gt;/&lt;Y&gt;</emphasis>

+CIExyY:<emphasis remap='I'>&lt;x&gt;/&lt;y&gt;/&lt;Y&gt;</emphasis>

+CIELab:<emphasis remap='I'>&lt;L&gt;/&lt;a&gt;/&lt;b&gt;</emphasis>

+CIELuv:<emphasis remap='I'>&lt;L&gt;/&lt;u&gt;/&lt;v&gt;</emphasis>

+TekHVC:<emphasis remap='I'>&lt;H&gt;/&lt;V&gt;/&lt;C&gt;</emphasis>

+</literallayout>

+<!-- .\" End marker code here -->

+</para>

+<para>

+<!-- .LP -->

+All of the values (C, H, V, X, Y, Z, a, b, u, v, y, x) are

+floating-point values.

+The syntax for these values is an optional plus or minus sign,

+a string of digits possibly containing a decimal point,

+and an optional exponent field consisting of an ``E'' or ``e''

+followed by an optional plus or minus followed by a string of digits.

+</para>

+</sect2>

+</sect1>

+<sect1 id="Color_Conversion_Contexts_and_Gamut_Mapping">

+<title>Color Conversion Contexts and Gamut Mapping</title>

+<!-- .XS -->

+<!-- (SN Color Conversion Contexts and Gamut Mapping -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+When Xlib converts device-independent color specifications

+into device-dependent specifications and vice versa,

+it uses knowledge about the color limitations of the screen hardware.

+This information, typically called the device profile,

+<indexterm><primary>Device profile</primary></indexterm>

+is available in a Color Conversion Context (CCC).

+<indexterm><primary>Color Conversion Context</primary></indexterm>

+<indexterm><primary>CCC</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+Because a specified color may be outside the color gamut of the target screen

+and the white point associated with the color specification may differ

+from the white point inherent to the screen,

+Xlib applies gamut mapping when it encounters certain conditions:

+<indexterm><primary>White point</primary></indexterm>

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Gamut compression occurs when conversion of device-independent

+color specifications to device-dependent color specifications

+results in a color out of the target screen's gamut.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+White adjustment occurs when the inherent white point of the screen

+differs from the white point assumed by the client.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+Gamut handling methods are stored as callbacks in the CCC,

+which in turn are used by the color space conversion routines.

+Client data is also stored in the CCC for each callback.

+The CCC also contains the white point the client assumes to be

+associated with color specifications (that is, the Client White Point).

+<indexterm><primary>Client White Point</primary></indexterm>

+<indexterm><primary>Gamut compression</primary></indexterm>

+<indexterm><primary>Gamut handling</primary></indexterm>

+<indexterm><primary>White point adjustment</primary></indexterm>

+The client can specify the gamut handling callbacks and client data

+as well as the Client White Point.

+Xlib does not preclude the X client from performing other

+forms of gamut handling (for example, gamut expansion); 

+however, Xlib does not provide direct support for gamut handling

+other than white adjustment and gamut compression.

+</para>

+<para>

+<!-- .LP -->

+Associated with each colormap is an initial CCC transparently generated by

+Xlib.

+<indexterm><primary>Color Conversion Context</primary><secondary>creation</secondary></indexterm>

+Therefore,

+when you specify a colormap as an argument to an Xlib function,

+you are indirectly specifying a CCC.

+<indexterm><primary>CCC</primary><secondary>of colormap</secondary></indexterm>

+<indexterm><primary>Color Conversion Context</primary><secondary>of colormap</secondary></indexterm>

+There is a default CCC associated with each screen.

+Newly created CCCs inherit attributes from the default CCC,

+so the default CCC attributes can be modified to affect new CCCs.

+<indexterm><primary>CCC</primary><secondary>default</secondary></indexterm>

+<indexterm><primary>Color Conversion Context</primary><secondary>default</secondary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+Xcms functions in which gamut mapping can occur return

+<function>Status</function>

+and have specific status values defined for them, 

+as follows:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+<function>XcmsFailure</function>

+indicates that the function failed.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XcmsSuccess</function>

+indicates that the function succeeded.

+In addition,

+if the function performed any color conversion,

+the colors did not need to be compressed.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XcmsSuccessWithCompression</function>

+indicates the function performed color conversion

+and at least one of the colors needed to be compressed.

+The gamut compression method is determined by the gamut compression

+procedure in the CCC that is specified directly as a function argument

+or in the CCC indirectly specified by means of the colormap argument.

+    </para>

+  </listitem>

+</itemizedlist>

+</sect1>

+<sect1 id="Creating_Copying_and_Destroying_Colormaps">

+<title>Creating, Copying, and Destroying Colormaps</title>

+<!-- .XS -->

+<!-- (SN Creating, Copying, and Destroying Colormaps -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To create a colormap for a screen, use

+<function>XCreateColormap</function>.</para>

+<indexterm significance="preferred"><primary>XCreateColormap</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Colormap<function> XCreateColormap</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>Visual<parameter> *visual</parameter></paramdef>

+  <paramdef>int<parameter> alloc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Wi on whose screen you want to create a colormap -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window (Wi.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>visual</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a visual type supported on the screen.

+If the visual type is not one supported by the screen, 

+a

+<function>BadMatch</function>

+error results.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>alloc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap entries to be allocated.

+You can pass 

+<function>AllocNone </function>

+or 

+<function>AllocAll</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCreateColormap</function>

+function creates a colormap of the specified visual type for the screen 

+on which the specified window resides and returns the colormap ID 

+associated with it.

+Note that the specified window is only used to determine the screen.

+</para>

+<para>

+<!-- .LP -->

+The initial values of the colormap entries are undefined for the 

+visual classes

+<function>GrayScale</function>,

+<function>PseudoColor</function>,

+and

+<function>DirectColor</function>.

+For

+<function>StaticGray</function>,

+<function>StaticColor</function>,

+and

+<function>TrueColor</function>,

+the entries have defined values,

+but those values are specific to the visual and are not defined by X.

+For

+<function>StaticGray</function>,

+<function>StaticColor</function>,

+and

+<function>TrueColor</function>,

+alloc must be

+<function>AllocNone</function>,

+or a

+<function>BadMatch</function>

+error results.

+For the other visual classes,

+if alloc is

+<function>AllocNone</function>,

+the colormap initially has no allocated entries,

+and clients can allocate them.

+For information about the visual types,

+see section 3.1.

+</para>

+<para>

+<!-- .LP -->

+If alloc is

+<function>AllocAll</function>,

+the entire colormap is allocated writable.

+The initial values of all allocated entries are undefined.

+For

+<function>GrayScale</function>

+and

+<function>PseudoColor</function>,

+the effect is as if an

+<function>XAllocColorCells</function>

+call returned all pixel values from zero to N - 1,

+where N is the colormap entries value in the specified visual.

+For

+<function>DirectColor</function>,

+the effect is as if an

+<function>XAllocColorPlanes</function>

+call returned a pixel value of zero and red_mask, green_mask, 

+and blue_mask values containing the same bits as the corresponding

+masks in the specified visual.

+However, in all cases,

+none of these entries can be freed by using

+<function>XFreeColors</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XCreateColormap</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadMatch</function>,

+<function>BadValue</function>,

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To create a new colormap when the allocation out of a previously

+shared colormap has failed because of resource exhaustion, use

+<function>XCopyColormapAndFree</function>.

+<indexterm significance="preferred"><primary>XCopyColormapAndFree</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Colormap<function>XCopyColormapAndFree </function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCopyColormapAndFree</function>

+function creates a colormap of the same visual type and for the same screen

+as the specified colormap and returns the new colormap ID.

+It also moves all of the client's existing allocation from the specified

+colormap to the new colormap with their color values intact 

+and their read-only or writable characteristics intact and frees those entries 

+in the specified colormap.

+Color values in other entries in the new colormap are undefined.

+If the specified colormap was created by the client with alloc set to

+<function>AllocAll</function>,

+the new colormap is also created with 

+<function>AllocAll</function>,

+all color values for all entries are copied from the specified colormap,

+and then all entries in the specified colormap are freed.

+If the specified colormap was not created by the client with

+<function>AllocAll</function>,

+the allocations to be moved are all those pixels and planes

+that have been allocated by the client using

+<function>XAllocColor</function>,

+<function>XAllocNamedColor</function>,

+<function>XAllocColorCells</function>,

+or

+<function>XAllocColorPlanes</function>

+and that have not been freed since they were allocated.

+</para>

+<para>

+<!-- .LP -->

+<function>XCopyColormapAndFree</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadColor </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To destroy a colormap, use 

+<function>XFreeColormap</function>.

+<indexterm significance="preferred"><primary>XFreeColormap</primary></indexterm>

+</para>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function>XFreeColormap</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Cm that you want to destroy -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap (Cm.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XFreeColormap</function>

+function deletes the association between the colormap resource ID 

+and the colormap and frees the colormap storage.

+However, this function has no effect on the default colormap for a screen.

+If the specified colormap is an installed map for a screen,

+it is uninstalled (see

+<function>XUninstallColormap</function>).

+If the specified colormap is defined as the colormap for a window (by

+<function>XCreateWindow</function>,

+<function>XSetWindowColormap</function>,

+or

+<function>XChangeWindowAttributes</function>),

+<function>XFreeColormap</function>

+changes the colormap associated with the window to

+<function>None </function>

+and generates a

+<function>ColormapNotify</function>

+event.

+X does not define the colors displayed for a window with a colormap of

+<function>None</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XFreeColormap</function>

+can generate a

+<function>BadColor </function>

+error.

+</para>

+</sect1>

+<sect1 id="Mapping_Color_Names_to_Values">

+<title>Mapping Color Names to Values</title>

+<!-- .XS -->

+<!-- (SN Mapping Color Names to Values -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To map a color name to an <acronym>RGB</acronym> value, use

+<function>XLookupColor</function>.

+<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>

+<indexterm significance="preferred"><primary>XLookupColor</primary></indexterm>

+<!-- .sM -->

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XLookupColor</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+  <paramdef>char<parameter> *color_name</parameter></paramdef>

+  <paramdef>XColor*exact_def_return,<parameter> *screen_def_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the color name string (for example, red) whose color 

+definition structure you want returned.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>exact_def_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the exact <acronym>RGB</acronym> values.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_def_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the closest <acronym>RGB</acronym> values provided by the hardware.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XLookupColor</function>

+function looks up the string name of a color with respect to the screen

+associated with the specified colormap.

+It returns both the exact color values and

+the closest values provided by the screen 

+with respect to the visual type of the specified colormap.

+If the color name is not in the Host Portable Character Encoding, 

+the result is implementation-dependent.

+Use of uppercase or lowercase does not matter.

+<function>XLookupColor</function>

+returns nonzero if the name is resolved;

+otherwise, it returns zero.

+</para>

+<para>

+<!-- .LP -->

+<function>XLookupColor</function>

+can generate a

+<function>BadColor </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To map a color name to the exact <acronym>RGB</acronym> value, use

+<function>XParseColor</function>.

+</para>

+<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>

+<indexterm significance="preferred"><primary>XParseColor</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XParseColor</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+  <paramdef>char<parameter> *spec</parameter></paramdef>

+  <paramdef>XColor<parameter> *exact_def_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>spec</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the color name string;

+case is ignored.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>exact_def_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the exact color value for later use and sets the

+<function>DoRed</function>,

+<function>DoGreen</function>,

+and

+<function>DoBlue</function>

+flags.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XParseColor</function>

+function looks up the string name of a color with respect to the screen

+associated with the specified colormap.

+It returns the exact color value.

+If the color name is not in the Host Portable Character Encoding, 

+the result is implementation-dependent.

+Use of uppercase or lowercase does not matter.

+<function>XParseColor</function>

+returns nonzero if the name is resolved;

+otherwise, it returns zero.

+</para>

+<para>

+<!-- .LP -->

+<function>XParseColor</function>

+can generate a

+<function>BadColor </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To map a color name to a value in an arbitrary color space, use

+<function>XcmsLookupColor</function>.

+</para>

+<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>

+<indexterm significance="preferred"><primary>XcmsLookupColor</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsLookupColor</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+  <paramdef>char<parameter> *color_string</parameter></paramdef>

+  <paramdef>XcmsColor*color_exact_return,<parameter> *color_screen_return</parameter></paramdef>

+  <paramdef>XcmsColorFormat<parameter> result_format</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+<!-- .ds St -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the color string(St.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_exact_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the color specification parsed from the color string

+or parsed from the corresponding string found in a color-name database.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_screen_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the color that can be reproduced on the screen.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>result_format</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the color format for the returned color

+specifications (color_screen_return and color_exact_return arguments).

+If the format is

+<function>XcmsUndefinedFormat</function>

+and the color string contains a

+numerical color specification,

+the specification is returned in the format used in that numerical

+color specification.

+If the format is

+<function>XcmsUndefinedFormat</function>

+and the color string contains a color name,

+the specification is returned in the format used 

+to store the color in the database.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XcmsLookupColor</function>

+function looks up the string name of a color with respect to the screen

+associated with the specified colormap.

+It returns both the exact color values and

+the closest values provided by the screen 

+with respect to the visual type of the specified colormap.

+The values are returned in the format specified by result_format.

+If the color name is not in the Host Portable Character Encoding, 

+the result is implementation-dependent.

+Use of uppercase or lowercase does not matter.

+<function>XcmsLookupColor</function>

+returns

+<function>XcmsSuccess</function>

+or

+<function>XcmsSuccessWithCompression</function>

+if the name is resolved; otherwise, it returns

+<function>XcmsFailure</function>.

+If

+<function>XcmsSuccessWithCompression</function>

+is returned, the color specification returned in 

+color_screen_return is the result of gamut compression.

+</para>

+</sect1>

+

+<sect1 id="Allocating_and_Freeing_Color_Cells">

+<title>Allocating and Freeing Color Cells</title>

+<!-- .XS -->

+<!-- (SN Allocating and Freeing Color Cells -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+There are two ways of allocating color cells: 

+explicitly as read-only entries, one pixel value at a time,

+or read/write,

+where you can allocate a number of color cells and planes simultaneously.

+<indexterm><primary>Read-only colormap cells</primary></indexterm>

+A read-only cell has its <acronym>RGB</acronym> value set by the server.

+<indexterm><primary>Read/write colormap cells</primary></indexterm>

+Read/write cells do not have defined colors initially;

+functions described in the next section must be used to store values into them.

+Although it is possible for any client to store values into a read/write

+cell allocated by another client,

+read/write cells normally should be considered private to the client

+that allocated them.

+</para>

+<para>

+<!-- .LP -->

+Read-only colormap cells are shared among clients.

+The server counts each allocation and freeing of the cell by clients.

+When the last client frees a shared cell, the cell is finally deallocated.

+If a single client allocates the same read-only cell multiple

+times, the server counts each such allocation, not just the first one.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To allocate a read-only color cell with an <acronym>RGB</acronym> value, use

+<function>XAllocColor</function>.

+</para>

+<indexterm><primary>Allocation</primary><secondary>read-only colormap cells</secondary></indexterm>

+<indexterm><primary>Read-only colormap cells</primary><secondary>allocating</secondary></indexterm>

+<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>

+<indexterm significance="preferred"><primary>XAllocColor</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XAllocColor</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+  <paramdef>XColor<parameter> *screen_in_out</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_in_out</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies and returns the values actually used in the colormap.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XAllocColor</function>

+function allocates a read-only colormap entry corresponding to the closest

+<acronym>RGB</acronym> value supported by the hardware.

+<function>XAllocColor</function>

+returns the pixel value of the color closest to the specified

+<acronym>RGB</acronym> elements supported by the hardware

+and returns the <acronym>RGB</acronym> value actually used.

+The corresponding colormap cell is read-only.

+In addition,

+<function>XAllocColor</function>

+returns nonzero if it succeeded or zero if it failed.

+<indexterm><primary>Color map</primary></indexterm>

+<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>

+<indexterm><primary>Allocation</primary><secondary>colormap</secondary></indexterm>

+<indexterm><primary>read-only colormap cells</primary></indexterm>

+Multiple clients that request the same effective <acronym>RGB</acronym> value can be assigned

+the same read-only entry, thus allowing entries to be shared.

+When the last client deallocates a shared cell, it is deallocated.

+<function>XAllocColor</function>

+does not use or affect the flags in the

+<function>XColor</function>

+structure.

+</para>

+<para>

+<!-- .LP -->

+<function>XAllocColor</function>

+can generate a

+<function>BadColor </function>

+error.

+<!-- .EQ -->

+delim %%

+<!-- .EN -->

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To allocate a read-only color cell with a color in arbitrary format, use

+<function>XcmsAllocColor</function>.

+</para>

+<indexterm><primary>Allocation</primary><secondary>read-only colormap cells</secondary></indexterm>

+<indexterm><primary>Read-only colormap cells</primary><secondary>allocating</secondary></indexterm>

+<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>

+<indexterm significance="preferred"><primary>XcmsAllocColor</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsAllocColor</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color_in_out</parameter></paramdef>

+  <paramdef>XcmsColorFormat<parameter> result_format</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_in_out</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the color to allocate and returns the pixel and color 

+that is actually used in the colormap.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>result_format</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the color format for the returned color specification.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XcmsAllocColor</function>

+function is similar to

+<function>XAllocColor</function>

+except the color can be specified in any format.

+The

+<function>XcmsAllocColor</function>

+function ultimately calls 

+<function>XAllocColor</function>

+to allocate a read-only color cell (colormap entry) with the specified color.

+<function>XcmsAllocColor</function>

+first converts the color specified

+to an <acronym>RGB</acronym> value and then passes this to

+<function>XAllocColor</function>.

+<function>XcmsAllocColor</function>

+returns the pixel value of the color cell and the color specification

+actually allocated.

+This returned color specification is the result of converting the <acronym>RGB</acronym> value

+returned by 

+<function>XAllocColor </function>

+into the format specified with the result_format argument.

+If there is no interest in a returned color specification, 

+unnecessary computation can be bypassed if result_format is set to

+<function>XcmsRGBFormat</function>.

+The corresponding colormap cell is read-only.

+If this routine returns 

+<function>XcmsFailure</function>,

+the color_in_out color specification is left unchanged.

+</para>

+<para>

+<!-- .LP -->

+<function>XcmsAllocColor</function>

+can generate a

+<function>BadColor</function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To allocate a read-only color cell using a color name and return the closest

+color supported by the hardware in <acronym>RGB</acronym> format, use

+<function>XAllocNamedColor</function>.

+</para>

+<indexterm><primary>Allocation</primary><secondary>read-only colormap cells</secondary></indexterm>

+<indexterm><primary>Read-only colormap cells</primary><secondary>allocating</secondary></indexterm>

+<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>

+<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>

+<indexterm significance="preferred"><primary>XAllocNamedColor</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XAllocNamedColor</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+  <paramdef>char<parameter> *color_name</parameter></paramdef>

+  <paramdef>XColor*screen_def_return,<parameter> *exact_def_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the color name string (for example, red) whose color 

+definition structure you want returned.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_def_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the closest <acronym>RGB</acronym> values provided by the hardware.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>exact_def_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the exact <acronym>RGB</acronym> values.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XAllocNamedColor</function>

+function looks up the named color with respect to the screen that is

+associated with the specified colormap.

+It returns both the exact database definition and

+the closest color supported by the screen.

+The allocated color cell is read-only.

+The pixel value is returned in screen_def_return.

+If the color name is not in the Host Portable Character Encoding, 

+the result is implementation-dependent.

+Use of uppercase or lowercase does not matter.

+If screen_def_return and exact_def_return

+point to the same structure, the pixel field will be set correctly,

+but the color values are undefined.

+<function>XAllocNamedColor</function>

+returns nonzero if a cell is allocated;

+otherwise, it returns zero.

+</para>

+<para>

+<!-- .LP -->

+<function>XAllocNamedColor</function>

+can generate a

+<function>BadColor</function>

+error. 

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To allocate a read-only color cell using a color name and return the closest

+color supported by the hardware in an arbitrary format, use

+<function>XcmsAllocNamedColor</function>.

+</para>

+<indexterm><primary>Allocation</primary><secondary>read-only colormap cells</secondary></indexterm>

+<indexterm><primary>Read-only colormap cells</primary><secondary>allocating</secondary></indexterm>

+<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>

+<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>

+<indexterm significance="preferred"><primary>XcmsAllocNamedColor</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsAllocNamedColor</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+  <paramdef>char<parameter> *color_string</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color_screen_return</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color_exact_return</parameter></paramdef>

+  <paramdef>XcmsColorFormat<parameter> result_format</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+<!-- .ds St \ whose color definition structure is to be returned -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the color string(St.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_screen_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the pixel value of the color cell and color specification 

+that actually is stored for that cell.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_exact_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the color specification parsed from the color string

+or parsed from the corresponding string found in a color-name database.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>result_format</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the color format for the returned color

+specifications (color_screen_return and color_exact_return arguments).

+If the format is

+<function>XcmsUndefinedFormat</function>

+and the color string contains a

+numerical color specification,

+the specification is returned in the format used in that numerical

+color specification.

+If the format is

+<function>XcmsUndefinedFormat</function>

+and the color string contains a color name,

+the specification is returned in the format used 

+to store the color in the database.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XcmsAllocNamedColor</function>

+function is similar to

+<function>XAllocNamedColor</function>

+except that the color returned can be in any format specified.

+This function

+ultimately calls

+<function>XAllocColor</function>

+to allocate a read-only color cell with

+the color specified by a color string.

+The color string is parsed into an

+<function>XcmsColor</function>

+structure (see

+<function>XcmsLookupColor</function>),

+converted

+to an <acronym>RGB</acronym> value, and finally passed to

+<function>XAllocColor</function>.

+If the color name is not in the Host Portable Character Encoding, 

+the result is implementation-dependent.

+Use of uppercase or lowercase does not matter.

+</para>

+<para>

+<!-- .LP -->

+This function returns both the color specification as a result

+of parsing (exact specification) and the actual color specification

+stored (screen specification).

+This screen specification is the result of converting the <acronym>RGB</acronym> value

+returned by

+<function>XAllocColor</function>

+into the format specified in result_format.

+If there is no interest in a returned color specification,

+unnecessary computation can be bypassed if result_format is set to

+<function>XcmsRGBFormat</function>.

+If color_screen_return and color_exact_return

+point to the same structure, the pixel field will be set correctly,

+but the color values are undefined.

+</para>

+<para>

+<!-- .LP -->

+<function>XcmsAllocNamedColor</function>

+can generate a

+<function>BadColor</function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To allocate read/write color cell and color plane combinations for a

+<function>PseudoColor</function>

+model, use

+<function>XAllocColorCells</function>.

+</para>

+<indexterm><primary>Read/write colormap cells</primary><secondary>allocating</secondary></indexterm>

+<indexterm><primary>Allocation</primary><secondary>read/write colormap cells</secondary></indexterm>

+<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>

+<indexterm significance="preferred"><primary>XAllocColorCells</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XAllocColorCells</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+  <paramdef>Bool<parameter> contig</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> plane_masks_return[]</parameter></paramdef>

+  <paramdef>unsignedint<parameter> nplanes</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> pixels_return[]</parameter></paramdef>

+  <paramdef>unsignedint<parameter> npixels</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>contig</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a Boolean value that indicates whether the planes must be contiguous.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>plane_mask_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns an array of plane masks.

+<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nplanes</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of plane masks that are to be returned in the plane masks 

+array. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>pixels_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns an array of pixel values. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>npixels</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of pixel values that are to be returned in the 

+pixels_return array. 

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .EQ -->

+delim %%

+<!-- .EN -->

+The

+<function>XAllocColorCells</function>

+function allocates read/write color cells.

+The number of colors must be positive and the number of planes nonnegative,

+or a

+<function>BadValue</function>

+error results.

+If ncolors and nplanes are requested, 

+then ncolors pixels

+and nplane plane masks are returned.

+No mask will have any bits set to 1 in common with

+any other mask or with any of the pixels.

+By ORing together each pixel with zero or more masks,

+ncolors * %2 sup nplanes% distinct pixels can be produced.

+All of these are

+allocated writable by the request.

+For 

+<function>GrayScale </function>

+or 

+<function>PseudoColor</function>,

+each mask has exactly one bit set to 1. 

+For 

+<function>DirectColor</function>,

+each has exactly three bits set to 1.

+If contig is 

+<function>True </function>

+and if all masks are ORed

+together, a single contiguous set of bits set to 1 will be formed for 

+<function>GrayScale</function>

+or 

+<function>PseudoColor </function>

+and three contiguous sets of bits set to 1 (one within each

+pixel subfield) for 

+<function>DirectColor</function>.

+The <acronym>RGB</acronym> values of the allocated

+entries are undefined.

+<function>XAllocColorCells</function>

+returns nonzero if it succeeded or zero if it failed.

+</para>

+<para>

+<!-- .LP -->

+<function>XAllocColorCells</function>

+can generate

+<function>BadColor</function>

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To allocate read/write color resources for a

+<function>DirectColor</function>

+model, use

+<function>XAllocColorPlanes</function>.

+</para>

+<indexterm><primary>Read/write colormap planes</primary><secondary>allocating</secondary></indexterm>

+<indexterm><primary>Allocation</primary><secondary>read/write colormap planes</secondary></indexterm>

+<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>

+<indexterm significance="preferred"><primary>XAllocColorPlanes</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XAllocColorPlanes</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+  <paramdef>Bool<parameter> contig</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> pixels_return[]</parameter></paramdef>

+  <paramdef>int<parameter> ncolors</parameter></paramdef>

+  <paramdef>intnreds,ngreens,<parameter> nblues</parameter></paramdef>

+  <paramdef>unsignedlong*rmask_return,*gmask_return,<parameter> *bmask_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>contig</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a Boolean value that indicates whether the planes must be contiguous.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>pixels_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns an array of pixel values. 

+<function>XAllocColorPlanes</function>

+returns the pixel values in this array.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ncolors</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of pixel values that are to be returned in the 

+pixels_return array. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nreds</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ngreens</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nblues</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+Specify the number of red, green, and blue planes.

+The value you pass must be nonnegative. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>rmask_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gmask_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>bmask_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Return bit masks for the red, green, and blue planes.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .EQ -->

+delim %%

+<!-- .EN -->

+The specified ncolors must be positive; 

+and nreds, ngreens, and nblues must be nonnegative,

+or a

+<function>BadValue</function>

+error results.

+If ncolors colors, nreds reds, ngreens greens, and nblues blues are requested, 

+ncolors pixels are returned; and the masks have nreds, ngreens, and 

+nblues bits set to 1, respectively.

+If contig is 

+<function>True</function>,

+each mask will have

+a contiguous set of bits set to 1.

+No mask will have any bits set to 1 in common with

+any other mask or with any of the pixels.

+For 

+<function>DirectColor</function>,

+each mask

+will lie within the corresponding pixel subfield.

+By ORing together

+subsets of masks with each pixel value, 

+ncolors * %2 sup (nreds+ngreens+nblues)% distinct pixel values can be produced. 

+All of these are allocated by the request.

+However, in the

+colormap, there are only ncolors * %2 sup nreds% independent red entries, 

+ncolors * %2 sup ngreens% independent green entries, 

+and ncolors * %2 sup nblues% independent blue entries. 

+This is true even for 

+<function>PseudoColor</function>.

+When the colormap entry of a pixel

+value is changed (using 

+<function>XStoreColors</function>,

+<function>XStoreColor</function>,

+or 

+<function>XStoreNamedColor</function>),

+the pixel is decomposed according to the masks, 

+and the corresponding independent entries are updated.

+<function>XAllocColorPlanes</function>

+returns nonzero if it succeeded or zero if it failed.

+</para>

+<para>

+<!-- .LP -->

+<function>XAllocColorPlanes</function>

+can generate

+<function>BadColor</function>

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<indexterm><primary>Freeing</primary><secondary>colors</secondary></indexterm>

+To free colormap cells, use

+<function>XFreeColors</function>.

+<indexterm significance="preferred"><primary>XFreeColors</primary></indexterm>

+<indexterm><primary>Color</primary><secondary>deallocation</secondary></indexterm>

+<!-- .sM -->

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function>XFreeColors</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> pixels[]</parameter></paramdef>

+  <paramdef>int<parameter> npixels</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> planes</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+<!-- .ds Pi that map to the cells in the specified colormap -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>pixels</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array of pixel values (Pi. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>npixels</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of pixels. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>planes</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the planes you want to free.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XFreeColors</function>

+function frees the cells represented by pixels whose values are in the

+pixels array.

+The planes argument should not have any bits set to 1 in common with any of the

+pixels. 

+The set of all pixels is produced by ORing together subsets of

+the planes argument with the pixels.

+The request frees all of these pixels that

+were allocated by the client (using 

+<indexterm><primary>XAllocColor</primary></indexterm>

+<indexterm><primary>XAllocNamedColor</primary></indexterm>

+<indexterm><primary>XAllocColorCells</primary></indexterm>

+<indexterm><primary>XAllocColorPlanes</primary></indexterm>

+<function>XAllocColor</function>,

+<function>XAllocNamedColor</function>,

+<function>XAllocColorCells</function>,

+and 

+<function>XAllocColorPlanes</function>).

+Note that freeing an

+individual pixel obtained from 

+<function>XAllocColorPlanes </function>

+may not actually allow

+it to be reused until all of its related pixels are also freed.

+Similarly,

+a read-only entry is not actually freed until it has been freed by all clients,

+and if a client allocates the same read-only entry multiple times,

+it must free the entry that many times before the entry is actually freed.

+</para>

+<para>

+<!-- .LP -->

+All specified pixels that are allocated by the client in the colormap are

+freed, even if one or more pixels produce an error. 

+If a specified pixel is not a valid index into the colormap, a 

+<function>BadValue </function>

+error results.

+If a specified pixel is not allocated by the

+client (that is, is unallocated or is only allocated by another client)

+or if the colormap was created with all entries writable (by passing

+<function>AllocAll</function>

+to

+<function>XCreateColormap</function>),

+a

+<function>BadAccess</function>

+error results. 

+If more than one pixel is in error, 

+the one that gets reported is arbitrary.

+</para>

+<para>

+<!-- .LP -->

+<function>XFreeColors</function>

+can generate

+<function>BadAccess</function>,

+<function>BadColor</function>,

+and

+<function>BadValue </function>

+errors.

+</para>

+</sect1>

+<sect1 id="Modifying_and_Querying_Colormap_Cells">

+<title>Modifying and Querying Colormap Cells</title>

+<!-- .XS -->

+<!-- (SN Modifying and Querying Colormap Cells  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To store an <acronym>RGB</acronym> value in a single colormap cell, use

+<function>XStoreColor</function>.

+</para>

+<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>

+<indexterm significance="preferred"><primary>XStoreColor</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function>XStoreColor</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+  <paramdef>XColor<parameter> *color</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the pixel and <acronym>RGB</acronym> values.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XStoreColor</function>

+function changes the colormap entry of the pixel value specified in the

+pixel member of the

+<function>XColor</function>

+structure.

+You specified this value in the

+pixel member of the

+<function>XColor</function>

+structure.

+This pixel value must be a read/write cell and a valid index into the colormap.

+If a specified pixel is not a valid index into the colormap,

+a

+<function>BadValue</function>

+error results.

+<function>XStoreColor</function>

+also changes the red, green, and/or blue color components.

+You specify which color components are to be changed by setting

+<function>DoRed</function>,

+<function>DoGreen</function>,

+and/or

+<function>DoBlue</function>

+in the flags member of the

+<function>XColor</function>

+structure.

+If the colormap is an installed map for its screen, 

+the changes are visible immediately.

+</para>

+<para>

+<!-- .LP -->

+<function>XStoreColor</function>

+can generate

+<function>BadAccess</function>,

+<function>BadColor</function>,

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To store multiple <acronym>RGB</acronym> values in multiple colormap cells, use

+<function>XStoreColors</function>.

+</para>

+<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>

+<indexterm significance="preferred"><primary>XStoreColors</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function>XStoreColors</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+  <paramdef>XColor<parameter> color[]</parameter></paramdef>

+  <paramdef>int<parameter> ncolors</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array of color definition structures to be stored.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ncolors</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .\"Specifies the number of color definition structures.  -->

+Specifies the number of 

+<function>XColor</function>

+structures in the color definition array.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XStoreColors</function>

+function changes the colormap entries of the pixel values

+specified in the pixel members of the

+<function>XColor</function>

+structures.

+You specify which color components are to be changed by setting 

+<function>DoRed</function>,

+<function>DoGreen</function>,

+and/or

+<function>DoBlue</function>

+in the flags member of the

+<function>XColor</function>

+structures.

+If the colormap is an installed map for its screen, the

+changes are visible immediately.

+<function>XStoreColors </function>

+changes the specified pixels if they are allocated writable in the colormap 

+by any client, even if one or more pixels generates an error.

+If a specified pixel is not a valid index into the colormap, a

+<function>BadValue</function>

+error results.

+If a specified pixel either is unallocated or is allocated read-only, a

+<function>BadAccess</function>

+error results.

+If more than one pixel is in error, 

+the one that gets reported is arbitrary.

+</para>

+<para>

+<!-- .LP -->

+<function>XStoreColors</function>

+can generate

+<function>BadAccess</function>,

+<function>BadColor</function>,

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To store a color of arbitrary format in a single colormap cell, use

+<function>XcmsStoreColor</function>.

+</para>

+<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>

+<indexterm significance="preferred"><primary>XcmsStoreColor</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsStoreColor</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the color cell and the color to store.

+Values specified in this

+<function>XcmsColor</function>

+structure remain unchanged on return.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XcmsStoreColor</function>

+function converts the color specified in the

+<function>XcmsColor</function>

+structure into <acronym>RGB</acronym> values.

+It then uses this <acronym>RGB</acronym> specification in an

+<function>XColor</function>

+structure, whose three flags 

+(<function>DoRed</function>,

+<function>DoGreen</function>,

+and

+<function>DoBlue</function>)

+are set, in a call to

+<function>XStoreColor</function>

+to change the color cell specified by the pixel member of the

+<function>XcmsColor</function>

+structure.

+This pixel value must be a valid index for the specified colormap,

+and the color cell specified by the pixel value must be a read/write cell.

+If the pixel value is not a valid index, a

+<function>BadValue</function>

+error results.

+If the color cell is unallocated or is allocated read-only, a

+<function>BadAccess</function>

+error results.

+If the colormap is an installed map for its screen, 

+the changes are visible immediately.

+</para>

+<para>

+<!-- .LP -->

+Note that 

+<function>XStoreColor</function>

+has no return value; therefore, an

+<function>XcmsSuccess</function>

+return value from this function indicates that the conversion 

+to <acronym>RGB</acronym> succeeded and the call to

+<function>XStoreColor</function>

+was made.

+To obtain the actual color stored, use

+<function>XcmsQueryColor</function>.

+Because of the screen's hardware limitations or gamut compression,

+the color stored in the colormap may not be identical

+to the color specified.

+</para>

+<para>

+<!-- .LP -->

+<function>XcmsStoreColor</function>

+can generate

+<function>BadAccess</function>,

+<function>BadColor</function>,

+and

+<function>BadValue</function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To store multiple colors of arbitrary format in multiple colormap cells, use

+<function>XcmsStoreColors</function>.

+</para>

+<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>

+<indexterm significance="preferred"><primary>XcmsStoreColors</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsStoreColors</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> colors[]</parameter></paramdef>

+  <paramdef>int<parameter> ncolors</parameter></paramdef>

+  <paramdef>Bool<parameter> compression_flags_return[]</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colors</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the color specification array of

+<function>XcmsColor</function>

+structures, each specifying a color cell and the color to store in that

+cell.

+Values specified in the array remain unchanged upon return.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ncolors</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of 

+<function>XcmsColor</function>

+structures in the color-specification array.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>compression_flags_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns an array of Boolean values indicating compression status.

+If a non-NULL pointer is supplied,

+each element of the array is set to

+<function>True</function>

+if the corresponding color was compressed and

+<function>False</function>

+otherwise.

+Pass NULL if the compression status is not useful.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XcmsStoreColors</function>

+function converts the colors specified in the array of

+<function>XcmsColor</function>

+structures into <acronym>RGB</acronym> values and then uses these <acronym>RGB</acronym> specifications in

+<function>XColor</function>

+structures, whose three flags 

+(<function>DoRed</function>,

+<function>DoGreen</function>,

+and

+<function>DoBlue</function>)

+are set, in a call to

+<function>XStoreColors</function>

+to change the color cells specified by the pixel member of the corresponding

+<function>XcmsColor</function>

+structure.

+Each pixel value must be a valid index for the specified colormap,

+and the color cell specified by each pixel value must be a read/write cell.

+If a pixel value is not a valid index, a

+<function>BadValue</function>

+error results.

+If a color cell is unallocated or is allocated read-only, a

+<function>BadAccess</function>

+error results.

+If more than one pixel is in error,

+the one that gets reported is arbitrary.

+If the colormap is an installed map for its screen, 

+the changes are visible immediately.

+</para>

+<para>

+<!-- .LP -->

+Note that 

+<function>XStoreColors</function>

+has no return value; therefore, an

+<function>XcmsSuccess</function>

+return value from this function indicates that conversions 

+to <acronym>RGB</acronym> succeeded and the call to

+<function>XStoreColors</function>

+was made.

+To obtain the actual colors stored, use

+<function>XcmsQueryColors</function>.

+Because of the screen's hardware limitations or gamut compression,

+the colors stored in the colormap may not be identical

+to the colors specified.

+</para>

+<para>

+<!-- .LP -->

+<function>XcmsStoreColors</function>

+can generate

+<function>BadAccess</function>,

+<function>BadColor</function>,

+and

+<function>BadValue</function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To store a color specified by name in a single colormap cell, use

+<function>XStoreNamedColor</function>.

+</para>

+<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>

+<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>

+<indexterm significance="preferred"><primary>XStoreNamedColor</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function>XStoreNamedColor</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+  <paramdef>char<parameter> *color</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> pixel</parameter></paramdef>

+  <paramdef>int<parameter> flags</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the color name string (for example, red). 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>pixel</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the entry in the colormap. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>flags</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies which red, green, and blue components are set.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XStoreNamedColor</function>

+function looks up the named color with respect to the screen associated with

+the colormap and stores the result in the specified colormap.

+The pixel argument determines the entry in the colormap.

+The flags argument determines which of the red, green, and blue components 

+are set. 

+You can set this member to the

+bitwise inclusive OR of the bits 

+<function>DoRed</function>,

+<function>DoGreen</function>,

+and 

+<function>DoBlue</function>.

+If the color name is not in the Host Portable Character Encoding, 

+the result is implementation-dependent.

+Use of uppercase or lowercase does not matter.

+If the specified pixel is not a valid index into the colormap, a

+<function>BadValue</function>

+error results.

+If the specified pixel either is unallocated or is allocated read-only, a

+<function>BadAccess</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+<function>XStoreNamedColor</function>

+can generate

+<function>BadAccess</function>,

+<function>BadColor</function>,

+<function>BadName</function>,

+and 

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XQueryColor</function>

+and

+<function>XQueryColors</function>

+functions take pixel values in the pixel member of

+<function>XColor</function>

+structures and store in the structures the <acronym>RGB</acronym> values for those

+pixels from the specified colormap.

+The values returned for an unallocated entry are undefined.

+These functions also set the flags member in the

+<function>XColor</function>

+structure to all three colors.

+If a pixel is not a valid index into the specified colormap, a

+<function>BadValue</function>

+error results.

+If more than one pixel is in error,

+the one that gets reported is arbitrary.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To query the <acronym>RGB</acronym> value of a single colormap cell, use

+<function>XQueryColor</function>.

+</para>

+<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>

+<indexterm significance="preferred"><primary>XQueryColor</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function>XQueryColor</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+  <paramdef>XColor<parameter> *def_in_out</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>def_in_out</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies and returns the <acronym>RGB</acronym> values for the pixel specified in the structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XQueryColor</function>

+function returns the current <acronym>RGB</acronym> value for the pixel in the

+<function>XColor</function>

+structure and sets the

+<function>DoRed</function>,

+<function>DoGreen</function>,

+and

+<function>DoBlue</function>

+flags.

+</para>

+<para>

+<!-- .LP -->

+<function>XQueryColor</function>

+can generate

+<function>BadColor</function>

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To query the <acronym>RGB</acronym> values of multiple colormap cells, use

+<function>XQueryColors</function>.

+</para>

+<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>

+<indexterm significance="preferred"><primary>XQueryColors</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function>XQueryColors</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+  <paramdef>XColor<parameter> defs_in_out[]</parameter></paramdef>

+  <paramdef>int<parameter> ncolors</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>defs_in_out</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies and returns an array of color definition structures for the pixel

+specified in the structure.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ncolors</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .\"Specifies the number of color definition structures.  -->

+Specifies the number of 

+<function>XColor</function>

+structures in the color definition array.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XQueryColors</function>

+function returns the <acronym>RGB</acronym> value for each pixel in each

+<function>XColor</function>

+structure and sets the

+<function>DoRed</function>,

+<function>DoGreen</function>,

+and

+<function>DoBlue</function>

+flags in each structure.

+

+</para>

+<para>

+<!-- .LP -->

+<function>XQueryColors</function>

+can generate

+<function>BadColor</function>

+and

+<function>BadValue </function>

+errors.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To query the color of a single colormap cell in an arbitrary format, use

+<function>XcmsQueryColor</function>.

+</para>

+<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>

+<indexterm significance="preferred"><primary>XcmsQueryColor</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsQueryColor</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color_in_out</parameter></paramdef>

+  <paramdef>XcmsColorFormat<parameter> result_format</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_in_out</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the pixel member that indicates the color cell to query.

+The color specification stored for the color cell is returned in this

+<function>XcmsColor</function>

+structure.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>result_format</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the color format for the returned color specification.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XcmsQueryColor</function>

+function obtains the <acronym>RGB</acronym> value

+for the pixel value in the pixel member of the specified

+<function>XcmsColor</function>

+structure and then

+converts the value to the target format as

+specified by the result_format argument.

+If the pixel is not a valid index in the specified colormap, a

+<function>BadValue</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+<function>XcmsQueryColor</function>

+can generate

+<function>BadColor</function>

+and

+<function>BadValue</function>

+errors.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To query the color of multiple colormap cells in an arbitrary format, use

+<function>XcmsQueryColors</function>.

+</para>

+<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>

+<indexterm significance="preferred"><primary>XcmsQueryColors</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsQueryColors</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> colors_in_out[]</parameter></paramdef>

+  <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>

+  <paramdef>XcmsColorFormat<parameter> result_format</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colors_in_out</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array of

+<function>XcmsColor</function>

+structures, each pixel member indicating the color cell to query.

+The color specifications for the color cells are returned in these structures.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ncolors</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of 

+<function>XcmsColor</function>

+structures in the color-specification array.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>result_format</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the color format for the returned color specification.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XcmsQueryColors</function>

+function obtains the <acronym>RGB</acronym> values

+for pixel values in the pixel members of

+<function>XcmsColor</function>

+structures and then

+converts the values to the target format as

+specified by the result_format argument.

+If a pixel is not a valid index into the specified colormap, a

+<function>BadValue</function>

+error results.

+If more than one pixel is in error,

+the one that gets reported is arbitrary.

+</para>

+<para>

+<!-- .LP -->

+<function>XcmsQueryColors</function>

+can generate

+<function>BadColor</function>

+and

+<function>BadValue</function>

+errors.

+</para>

+</sect1>

+<sect1 id="Color_Conversion_Context_Functions">

+<title>Color Conversion Context Functions</title>

+<!-- .XS -->

+<!-- (SN Color Conversion Context Functions -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+This section describes functions to create, modify,

+and query Color Conversion Contexts (CCCs).

+</para>

+<para>

+<!-- .LP -->

+Associated with each colormap is an initial CCC transparently generated by

+Xlib.

+<indexterm><primary>Color Conversion Context</primary><secondary>creation</secondary></indexterm>

+Therefore, when you specify a colormap as an argument to a function,

+you are indirectly specifying a CCC.

+<indexterm><primary>CCC</primary><secondary>of colormap</secondary></indexterm>

+<indexterm><primary>Color Conversion Context</primary><secondary>of colormap</secondary></indexterm>

+The CCC attributes that can be modified by the X client are:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Client White Point

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Gamut compression procedure and client data

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+White point adjustment procedure and client data

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+The initial values for these attributes are implementation specific.

+The CCC attributes for subsequently created CCCs can be defined

+by changing the CCC attributes of the default CCC.

+<indexterm><primary>CCC</primary><secondary>default</secondary></indexterm>

+<indexterm><primary>Color Conversion Context</primary><secondary>default</secondary></indexterm>

+There is a default CCC associated with each screen.

+</para>

+<sect2 id="Getting_and_Setting_the_Color_Conversion_Context_of_a_Colormap">

+<title>Getting and Setting the Color Conversion Context of a Colormap</title>

+<!-- .XS -->

+<!-- (SN Getting and Setting the Color Conversion Context of a Colormap -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the CCC associated with a colormap, use

+<function>XcmsCCCOfColormap</function>.

+</para>

+<indexterm significance="preferred"><primary>XcmsCCCOfColormap</primary></indexterm>

+<indexterm><primary>Colormap</primary><secondary>CCC of</secondary></indexterm>

+<indexterm><primary>CCC</primary><secondary>of colormap</secondary></indexterm>

+<indexterm><primary>Color Conversion Context</primary><secondary>of colormap</secondary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XcmsCCC <function>XcmsCCCOfColormap</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XcmsCCCOfColormap</function>

+function returns the CCC associated with the specified colormap.

+Once obtained, 

+the CCC attributes can be queried or modified.

+Unless the CCC associated with the specified colormap is changed with

+<function>XcmsSetCCCOfColormap</function>,

+this CCC is used when the specified colormap is used as an argument 

+to color functions.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To change the CCC associated with a colormap, use

+<function>XcmsSetCCCOfColormap</function>.

+</para>

+<indexterm significance="preferred"><primary>XcmsSetCCCOfColormap</primary></indexterm>

+<indexterm><primary>Colormap</primary><secondary>CCC of</secondary></indexterm>

+<indexterm><primary>CCC</primary><secondary>of colormap</secondary></indexterm>

+<indexterm><primary>Color Conversion Context</primary><secondary>of colormap</secondary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XcmsCCC <function>XcmsSetCCCOfColormap</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XcmsSetCCCOfColormap</function>

+function changes the CCC associated with the specified colormap.

+It returns the CCC previously associated with the colormap.

+If they are not used again in the application,

+CCCs should be freed by calling

+<function>XcmsFreeCCC</function>.

+Several colormaps may share the same CCC without restriction; this

+includes the CCCs generated by Xlib with each colormap.  Xlib, however,

+creates a new CCC with each new colormap.

+</para>

+</sect2>

+<sect2 id="Obtaining_the_Default_Color_Conversion_Context">

+<title>Obtaining the Default Color Conversion Context</title>

+<!-- .XS -->

+<!-- (SN Obtaining the Default Color Conversion Context -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+You can change the default CCC attributes for subsequently created CCCs

+by changing the CCC attributes of the default CCC.

+<indexterm><primary>CCC</primary><secondary>default</secondary></indexterm>

+<indexterm><primary>Color Conversion Context</primary><secondary>default</secondary></indexterm>

+A default CCC is associated with each screen.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To obtain the default CCC for a screen, use

+<function>XcmsDefaultCCC</function>.

+</para>

+<indexterm significance="preferred"><primary>XcmsDefaultCCC</primary></indexterm>

+<indexterm><primary>Color Conversion Context</primary><secondary>default</secondary></indexterm>

+<indexterm><primary>CCC</primary><secondary>default</secondary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XcmsCCC <function>XcmsDefaultCCC</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> screen_number</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate screen number on the host server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XcmsDefaultCCC</function>

+function returns the default CCC for the specified screen.

+Its visual is the default visual of the screen.

+Its initial gamut compression and white point

+adjustment procedures as well as the associated client data are implementation

+specific.

+</para>

+</sect2>

+<sect2 id="Color_Conversion_Context_Macros">

+<title>Color Conversion Context Macros</title>

+<!-- .XS -->

+<!-- (SN Color Conversion Context Macros -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Applications should not directly modify any part of the

+<function>XcmsCCC</function>.

+The following lists the C language macros, their corresponding function

+equivalents for other language bindings, and what data they both

+can return.

+<!-- .sp -->

+</para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>DisplayOfCCC</primary></indexterm>

+<indexterm significance="preferred"><primary>XcmsDisplayOfCCC</primary></indexterm>

+<!-- .sM -->

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function>DisplayOfCCC</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Display <function>*XcmsDisplayOfCCC</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Both return the display associated with the specified CCC.

+</para>

+<!-- .LP -->

+<!-- .sp -->

+<indexterm significance="preferred"><primary>VisualOfCCC</primary></indexterm>

+<indexterm significance="preferred"><primary>XcmsVisualOfCCC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function>VisualOfCCC</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Visual<function>*XcmsVisualOfCCC</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Both return the visual associated with the specified CCC.

+<!-- .sp -->

+</para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>ScreenNumberOfCCC</primary></indexterm>

+<indexterm significance="preferred"><primary>XcmsScreenNumberOfCCC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function>ScreenNumberOfCCC</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function>XcmsScreenNumberOfCCC</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Both return the number of the screen associated with the specified CCC.

+<!-- .sp -->

+</para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>ScreenWhitePointOfCCC</primary></indexterm>

+<indexterm significance="preferred"><primary>XcmsScreenWhitePointOfCCC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function>ScreenWhitePointOfCCC</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XcmsColor <function>XcmsScreenWhitePointOfCCC</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Both return the white point of the screen associated with the specified CCC.

+<!-- .sp -->

+</para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>ClientWhitePointOfCCC</primary></indexterm>

+<indexterm significance="preferred"><primary>XcmsClientWhitePointOfCCC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef> <function>ClientWhitePointOfCCC</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XcmsColor<function> *XcmsClientWhitePointOfCCC</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Both return the Client White Point of the specified CCC.

+</para>

+</sect2>

+

+<sect2 id="Modifying_Attributes_of_a_Color_Conversion_Context">

+<title>Modifying Attributes of a Color Conversion Context</title>

+<!-- .XS -->

+<!-- (SN Modifying Attributes of a Color Conversion Context -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To set the Client White Point in the CCC, use

+<function>XcmsSetWhitePoint</function>.

+</para>

+<indexterm significance="preferred"><primary>XcmsSetWhitePoint</primary></indexterm>

+<indexterm><primary>Client White Point</primary><secondary>of Color Conversion Context</secondary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function> XcmsSetWhitePoint</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+<!-- .ds Co new Client White Point -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the new Client White Point.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XcmsSetWhitePoint</function>

+function changes the Client White Point in the specified CCC.

+Note that the pixel member is ignored 

+and that the color specification is left unchanged upon return.

+The format for the new white point must be

+<function>XcmsCIEXYZFormat</function>,

+<function>XcmsCIEuvYFormat</function>,

+<function>XcmsCIExyYFormat</function>,

+or

+<function>XcmsUndefinedFormat</function>.

+If the color argument is NULL, this function sets the format component of the

+Client White Point specification to

+<function>XcmsUndefinedFormat</function>,

+indicating that the Client White Point is assumed to be the same as the

+Screen White Point.

+</para>

+<para>

+<!-- .LP -->

+This function returns nonzero status

+if the format for the new white point is valid;

+otherwise, it returns zero.

+

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To set the gamut compression procedure and corresponding client data

+in a specified CCC, use

+<function>XcmsSetCompressionProc</function>.

+</para>

+<indexterm significance="preferred"><primary>XcmsSetCompressionProc</primary></indexterm>

+<indexterm><primary>Gamut compression</primary><secondary>setting in Color Conversion Context</secondary></indexterm>

+<indexterm><primary>Gamut compression</primary><secondary>procedure</secondary></indexterm>

+<indexterm><primary>Gamut compression</primary><secondary>client data</secondary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XcmsCompressionProc <function>XcmsSetCompressionProc</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsCompressionProc<parameter> compression_proc</parameter></paramdef>

+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>compression_proc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the gamut compression procedure that is to be applied 

+when a color lies outside the screen's color gamut.

+If NULL is specified and a function using this CCC must convert

+a color specification to a device-dependent format and encounters a color

+that lies outside the screen's color gamut, 

+that function will return

+<function>XcmsFailure</function>.

+<!-- .ds Cd the gamut compression procedure -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>client_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies client data for gamut compression procedure or NULL.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XcmsSetCompressionProc</function>

+function first sets the gamut compression procedure and client data 

+in the specified CCC with the newly specified procedure and client data

+and then returns the old procedure.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To set the white point adjustment procedure and corresponding client data

+in a specified CCC, use

+<function>XcmsSetWhiteAdjustProc</function>.

+</para>

+<indexterm significance="preferred"><primary>XcmsSetWhiteAdjustProc</primary></indexterm>

+<indexterm><primary>White point adjustment</primary><secondary>setting in Color Conversion Context</secondary></indexterm>

+<indexterm><primary>White point adjustment</primary><secondary>procedure</secondary></indexterm>

+<indexterm><primary>White point adjustment</primary><secondary>client data</secondary></indexterm>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XcmsWhiteAdjustProc <function>XcmsSetWhiteAdjustProc</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsWhiteAdjustProc<parameter> white_adjust_proc</parameter></paramdef>

+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>white_adjust_proc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the white point adjustment procedure.

+<!-- .ds Cd the white point adjustment procedure -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>client_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies client data for white point adjustment procedure or NULL.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XcmsSetWhiteAdjustProc</function>

+function first sets the white point adjustment procedure and client data 

+in the specified CCC with the newly specified procedure and client data

+and then returns the old procedure.

+</para>

+</sect2>

+<sect2 id="Creating_and_Freeing_a_Color_Conversion_Context">

+<title>Creating and Freeing a Color Conversion Context</title>

+<!-- .XS -->

+<!-- (SN Creating and Freeing a Color Conversion Context -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+You can explicitly create a CCC within your application by calling

+<function>XcmsCreateCCC</function>.

+These created CCCs can then be used by those functions that explicitly

+call for a CCC argument.

+Old CCCs that will not be used by the application should be freed using

+<function>XcmsFreeCCC</function>.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To create a CCC, use

+<function>XcmsCreateCCC</function>.

+</para>

+<indexterm significance="preferred"><primary>XcmsCreateCCC</primary></indexterm>

+<indexterm><primary>Color Conversion Context</primary><secondary>creation</secondary></indexterm>

+<indexterm><primary>CCC</primary><secondary>creation</secondary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XcmsCCC <function>XcmsCreateCCC</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> screen_number</parameter></paramdef>

+  <paramdef>Visual<parameter> *visual</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *client_white_point</parameter></paramdef>

+  <paramdef>XcmsCompressionProc<parameter> compression_proc</parameter></paramdef>

+  <paramdef>XPointer<parameter> compression_client_data</parameter></paramdef>

+  <paramdef>XcmsWhiteAdjustProc<parameter> white_adjust_proc</parameter></paramdef>

+  <paramdef>XPointer<parameter> white_adjust_client_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate screen number on the host server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>visual</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the visual type.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>client_white_point</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the Client White Point.

+If NULL is specified, 

+the Client White Point is to be assumed to be the same as the

+Screen White Point.

+Note that the pixel member is ignored.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>compression_proc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the gamut compression procedure that is to be applied 

+when a color lies outside the screen's color gamut.

+If NULL is specified and a function using this CCC must convert

+a color specification to a device-dependent format and encounters a color

+that lies outside the screen's color gamut, 

+that function will return

+<function>XcmsFailure</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>compression_client_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies client data for use by the gamut compression procedure or NULL.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>white_adjust_proc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the white adjustment procedure that is to be applied

+when the Client White Point differs from the Screen White Point.

+NULL indicates that no white point adjustment is desired.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>white_adjust_client_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies client data for use with the white point adjustment procedure or NULL.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XcmsCreateCCC</function>

+function creates a CCC for the specified display, screen, and visual.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To free a CCC, use

+<function>XcmsFreeCCC</function>.

+</para>

+<indexterm significance="preferred"><primary>XcmsFreeCCC</primary></indexterm>

+<indexterm><primary>Color Conversion Context</primary><secondary>freeing</secondary></indexterm>

+<indexterm><primary>CCC</primary><secondary>freeing</secondary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function>XcmsFreeCCC</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XcmsFreeCCC</function>

+function frees the memory used for the specified CCC.

+Note that default CCCs and those currently associated with colormaps

+are ignored.

+</para>

+</sect2>

+</sect1>

+<sect1 id="Converting_between_Color_Spaces">

+<title>Converting between Color Spaces</title>

+<!-- .XS -->

+<!-- (SN Converting between Color Spaces -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To convert an array of color specifications in arbitrary color formats

+to a single destination format, use

+<function>XcmsConvertColors</function>.

+</para>

+<indexterm><primary>Color conversion</primary></indexterm>

+<indexterm><primary>Color</primary><secondary>conversion</secondary></indexterm>

+<indexterm significance="preferred"><primary>XcmsConvertColors</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsConvertColors</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> colors_in_out[]</parameter></paramdef>

+  <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>

+  <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>

+  <paramdef>Bool<parameter> compression_flags_return[]</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+If conversion is between device-independent color spaces only

+(for example, TekHVC to CIELuv),

+the CCC is necessary only to specify the Client White Point.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colors_in_out</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array of color specifications.

+Pixel members are ignored and remain unchanged upon return.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ncolors</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of 

+<function>XcmsColor</function>

+structures in the color-specification array.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>target_format</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the target color specification format.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>compression_flags_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns an array of Boolean values indicating compression status.

+If a non-NULL pointer is supplied,

+each element of the array is set to

+<function>True</function>

+if the corresponding color was compressed and

+<function>False</function>

+otherwise.

+Pass NULL if the compression status is not useful.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XcmsConvertColors</function>

+function converts the color specifications in the specified array of

+<function>XcmsColor</function>

+structures from their current format to a single target format,

+using the specified CCC.

+When the return value is

+<function>XcmsFailure</function>,

+the contents of the color specification array are left unchanged.

+</para>

+<para>

+<!-- .LP -->

+The array may contain a mixture of color specification formats

+(for example, 3 <acronym>CIE</acronym> XYZ, 2 <acronym>CIE</acronym> Luv, and so on).

+When the array contains both device-independent and

+device-dependent color specifications and the target_format argument specifies

+a device-dependent format (for example,

+<function>XcmsRGBiFormat</function>,

+<function>XcmsRGBFormat</function>),

+all specifications are converted to <acronym>CIE</acronym> XYZ format and then to the target

+device-dependent format.

+</para>

+</sect1>

+<sect1 id="Callback_Functions">

+<title>Callback Functions</title>

+<!-- .XS -->

+<!-- (SN Callback Functions -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+This section describes the gamut compression and white point

+adjustment callbacks.

+</para>

+<para>

+<!-- .LP -->

+The gamut compression procedure specified in the CCC

+is called when an attempt to convert a color specification from

+<function>XcmsCIEXYZ</function>

+to a device-dependent format (typically

+<function>XcmsRGBi</function>)

+results in a color that lies outside the screen's color gamut.

+If the gamut compression procedure requires client data, this data is passed

+via the gamut compression client data in the CCC.

+</para>

+<para>

+<!-- .LP -->

+During color specification conversion between device-independent

+and device-dependent color spaces,

+if a white point adjustment procedure is specified in the CCC,

+it is triggered when the Client White Point and Screen White Point differ.

+If required, the client data is obtained from the CCC.

+</para>

+<sect2 id="Prototype_Gamut_Compression_Procedure">

+<title>Prototype Gamut Compression Procedure</title>

+<!-- .XS -->

+<!-- (SN Prototype Gamut Compression Procedure -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The gamut compression callback interface must adhere to the

+following:

+</para>

+<indexterm significance="preferred"><primary>XcmsCompressionProc</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>typedef Status<function>(*XcmsCompressionProc</function>)</funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> colors_in_out[]</parameter></paramdef>

+  <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>

+  <paramdef>unsignedint<parameter> index</parameter></paramdef>

+  <paramdef>Bool<parameter> compression_flags_return[]</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colors_in_out</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array of color specifications.

+Pixel members should be ignored and must remain unchanged upon return.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ncolors</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of 

+<function>XcmsColor</function>

+structures in the color-specification array.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>index</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the index into the array of

+<function>XcmsColor</function>

+structures for the encountered color specification that lies outside the 

+screen's color gamut.

+Valid values are 0 (for the first element) to ncolors - 1.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>compression_flags_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns an array of Boolean values for indicating compression status.

+If a non-NULL pointer is supplied

+and a color at a given index is compressed, then

+<function>True</function>

+should be stored at the corresponding index in this array;

+otherwise, the array should not be modified.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+When implementing a gamut compression procedure, consider the following

+rules and assumptions:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+The gamut compression procedure can attempt to compress one or multiple

+specifications at a time.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+When called, elements 0 to index - 1 in the color specification

+array can be assumed to fall within the screen's color gamut.

+In addition, these color specifications are already in some device-dependent

+format (typically

+<function>XcmsRGBi</function>).

+If any modifications are made to these color specifications,

+they must be in their initial device-dependent format upon return.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+When called, the element in the color specification array specified

+by the index argument contains the color specification outside the 

+screen's color gamut encountered by the calling routine.

+In addition, this color specification can be assumed to be in

+<function>XcmsCIEXYZ</function>.

+Upon return, this color specification must be in

+<function>XcmsCIEXYZ</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+When called, elements from index to ncolors - 1 

+in the color specification array may or may not fall within the

+screen's color gamut.

+In addition, these color specifications can be assumed to be in

+<function>XcmsCIEXYZ</function>.

+If any modifications are made to these color specifications, 

+they must be in

+<function>XcmsCIEXYZ</function>

+upon return.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The color specifications passed to the gamut compression procedure

+have already been adjusted to the Screen White Point.

+This means that at this point the color specification's white point

+is the Screen White Point.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If the gamut compression procedure uses a device-independent color space not

+initially accessible for use in the color management system, use 

+<function>XcmsAddColorSpace</function>

+to ensure that it is added.

+    </para>

+  </listitem>

+</itemizedlist>

+</sect2>

+<sect2 id="Supplied_Gamut_Compression_Procedures">

+<title>Supplied Gamut Compression Procedures</title>

+<!-- .XS -->

+<!-- (SN Supplied Gamut Compression Procedures -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The following equations are useful in describing gamut compression

+functions:

+<!-- .EQ -->

+delim %%

+<!-- .EN -->

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )%

+

+%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right ]%

+

+%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )%

+

+%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right ]%

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+The gamut compression callback procedures provided by Xlib are as follows:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+<function>XcmsCIELabClipL</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+This brings the encountered out-of-gamut color specification into the 

+screen's color gamut by reducing or increasing <acronym>CIE</acronym> metric lightness (L*) 

+in the <acronym>CIE</acronym> L*a*b* color space until the color is within the gamut.

+If the Psychometric Chroma of the color specification 

+is beyond maximum for the Psychometric Hue Angle,

+then while maintaining the same Psychometric Hue Angle,

+the color will be clipped to the <acronym>CIE</acronym> L*a*b* coordinates of maximum

+Psychometric Chroma.

+See

+<function>XcmsCIELabQueryMaxC</function>.

+No client data is necessary.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XcmsCIELabClipab</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+This brings the encountered out-of-gamut color specification into the 

+screen's color gamut by reducing Psychometric Chroma,

+while maintaining Psychometric Hue Angle,

+until the color is within the gamut.

+No client data is necessary.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XcmsCIELabClipLab</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+This brings the encountered out-of-gamut color specification into the

+screen's color gamut by replacing it with <acronym>CIE</acronym> L*a*b* coordinates

+that fall within the color gamut while maintaining the original

+Psychometric Hue

+Angle and whose vector to the original coordinates is the shortest attainable.

+No client data is necessary.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XcmsCIELuvClipL</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+This brings the encountered out-of-gamut color specification into the 

+screen's color gamut by reducing or increasing <acronym>CIE</acronym> metric lightness (L*)

+in the <acronym>CIE</acronym> L*u*v* color space until the color is within the gamut.

+If the Psychometric Chroma of the color specification

+is beyond maximum for the Psychometric Hue Angle,

+then, while maintaining the same Psychometric Hue Angle,

+the color will be clipped to the <acronym>CIE</acronym> L*u*v* coordinates of maximum

+Psychometric Chroma.

+See

+<function>XcmsCIELuvQueryMaxC</function>.

+No client data is necessary.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XcmsCIELuvClipuv</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+This brings the encountered out-of-gamut color specification into the

+screen's color gamut by reducing

+Psychometric Chroma, while maintaining Psychometric Hue Angle,

+until the color is within the gamut.

+No client data is necessary.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XcmsCIELuvClipLuv</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+This brings the encountered out-of-gamut color specification into the

+screen's color gamut by replacing it with <acronym>CIE</acronym> L*u*v* coordinates

+that fall within the color gamut while maintaining the original

+Psychometric Hue

+Angle and whose vector to the original coordinates is the shortest attainable.

+No client data is necessary.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XcmsTekHVCClipV</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+This brings the encountered out-of-gamut color specification into the

+screen's color gamut by reducing or increasing the Value dimension

+in the TekHVC color space until the color is within the gamut.

+If Chroma of the color specification is beyond maximum for the particular Hue,

+then, while maintaining the same Hue,

+the color will be clipped to the Value and Chroma coordinates

+that represent maximum Chroma for that particular Hue.

+No client data is necessary.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XcmsTekHVCClipC</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+This brings the encountered out-of-gamut color specification into the

+screen's color gamut by reducing the Chroma dimension

+in the TekHVC color space until the color is within the gamut.

+No client data is necessary.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XcmsTekHVCClipVC</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+This brings the encountered out-of-gamut color specification into the

+screen's color gamut by replacing it with TekHVC coordinates

+that fall within the color gamut while maintaining the original Hue

+and whose vector to the original coordinates is the shortest attainable.

+No client data is necessary.

+    </para>

+  </listitem>

+</itemizedlist>

+</sect2>

+<sect2 id="Prototype_White_Point_Adjustment_Procedure">

+<title>Prototype White Point Adjustment Procedure</title>

+<!-- .XS -->

+<!-- (SN Prototype White Point Adjustment Procedure -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The white point adjustment procedure interface must adhere to the following:

+</para>

+<indexterm significance="preferred"><primary>XcmsWhiteAdjustProc</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>typedef Status <function>(*XcmsWhiteAdjustProc</function>)</funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *initial_white_point</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *target_white_point</parameter></paramdef>

+  <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> colors_in_out[]</parameter></paramdef>

+  <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>

+  <paramdef>Bool<parameter> compression_flags_return[]</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>initial_white_point</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the initial white point.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>target_white_point</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the target white point.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>target_format</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the target color specification format.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colors_in_out</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array of color specifications.

+Pixel members should be ignored and must remain unchanged upon return.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ncolors</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of 

+<function>XcmsColor</function>

+structures in the color-specification array.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>compression_flags_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns an array of Boolean values for indicating compression status.

+If a non-NULL pointer is supplied

+and a color at a given index is compressed, then

+<function>True</function>

+should be stored at the corresponding index in this array;

+otherwise, the array should not be modified.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+</para>

+</sect2>

+<sect2 id="Supplied_White_Point_Adjustment_Procedures">

+<title>Supplied White Point Adjustment Procedures</title>

+<!-- .XS -->

+<!-- (SN Supplied White Point Adjustment Procedures -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+White point adjustment procedures provided by Xlib are as follows:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+<function>XcmsCIELabWhiteShiftColors</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+This uses the <acronym>CIE</acronym> L*a*b* color space for adjusting the chromatic character

+of colors to compensate for the chromatic differences between the source

+and destination white points.

+This procedure simply converts the color specifications to 

+<function>XcmsCIELab</function>

+using the source white point and then converts to the target specification

+format using the destination's white point.

+No client data is necessary.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XcmsCIELuvWhiteShiftColors</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+This uses the <acronym>CIE</acronym> L*u*v* color space for adjusting the chromatic character

+of colors to compensate for the chromatic differences between the source

+and destination white points.

+This procedure simply converts the color specifications to 

+<function>XcmsCIELuv</function>

+using the source white point and then converts to the target specification

+format using the destination's white point.

+No client data is necessary.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XcmsTekHVCWhiteShiftColors</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+This uses the TekHVC color space for adjusting the chromatic character

+of colors to compensate for the chromatic differences between the source

+and destination white points.

+This procedure simply converts the color specifications to

+<function>XcmsTekHVC</function>

+using the source white point and then converts to the target specification

+format using the destination's white point.

+An advantage of this procedure over those previously described

+is an attempt to minimize hue shift.

+No client data is necessary.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+From an implementation point of view,

+these white point adjustment procedures convert the color specifications

+to a device-independent but white-point-dependent color space 

+(for example, <acronym>CIE</acronym> L*u*v*, <acronym>CIE</acronym> L*a*b*, TekHVC) using one white point

+and then converting those specifications to the target color space 

+using another white point.

+In other words,

+the specification goes in the color space with one white point 

+but comes out with another white point, 

+resulting in a chromatic shift based on the chromatic displacement

+between the initial white point and target white point.

+The <acronym>CIE</acronym> color spaces that are assumed to be white-point-independent

+are <acronym>CIE</acronym> u'v'Y, <acronym>CIE</acronym> XYZ, and <acronym>CIE</acronym> xyY.

+When developing a custom white point adjustment procedure that uses a

+device-independent color space not initially accessible for use in the

+color management system, use

+<function>XcmsAddColorSpace</function>

+to ensure that it is added.

+</para>

+<para>

+<!-- .LP -->

+As an example, 

+if the CCC specifies a white point adjustment procedure

+and if the Client White Point and Screen White Point differ, the

+<function>XcmsAllocColor</function>

+function will use the white point adjustment

+procedure twice: 

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Once to convert to

+<function>XcmsRGB</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A second time to convert from

+<function>XcmsRGB </function>

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+For example, assume the specification is in

+<function>XcmsCIEuvY</function>

+and the adjustment procedure is

+<function>XcmsCIELuvWhiteShiftColors</function>.

+During conversion to

+<function>XcmsRGB</function>,

+the call to 

+<function>XcmsAllocColor </function>

+results in the following series of color specification conversions:

+<!-- .\" Do these need to be font coded? -->

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+From 

+<function>XcmsCIEuvY</function>

+to

+<function>XcmsCIELuv</function>

+using the Client White Point

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+From 

+<function>XcmsCIELuv</function>

+to

+<function>XcmsCIEuvY</function>

+using the Screen White Point

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+From

+<function>XcmsCIEuvY</function>

+to

+<function>XcmsCIEXYZ</function>

+(<acronym>CIE</acronym> u'v'Y and XYZ are white-point-independent color spaces)

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+From 

+<function>XcmsCIEXYZ</function>

+to 

+<function>XcmsRGBi</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+From 

+<function>XcmsRGBi</function>

+to

+<function>XcmsRGB</function>

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+The resulting <acronym>RGB</acronym> specification is passed to

+<function>XAllocColor</function>,

+and the <acronym>RGB</acronym>

+specification returned by

+<function>XAllocColor</function>

+is converted back to 

+<function>XcmsCIEuvY</function>

+by reversing the color conversion sequence.

+</para>

+</sect2>

+</sect1>

+<sect1 id="Gamut_Querying_Functions">

+<title>Gamut Querying Functions</title>

+<!-- .XS -->

+<!-- (SN Gamut Querying Functions -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+This section describes the gamut querying functions that Xlib provides.

+These functions allow the client to query the boundary 

+of the screen's color gamut in terms of the <acronym>CIE</acronym> L*a*b*, <acronym>CIE</acronym> L*u*v*, 

+and TekHVC color spaces.

+<indexterm><primary>Gamut querying</primary></indexterm>

+Functions are also provided that allow you to query 

+the color specification of:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+White (full-intensity red, green, and blue)

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Red (full-intensity red while green and blue are zero)

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Green (full-intensity green while red and blue are zero)

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Blue (full-intensity blue while red and green are zero)

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Black (zero-intensity red, green, and blue)

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+The white point associated with color specifications passed to 

+and returned from these gamut querying

+functions is assumed to be the Screen White Point.

+<indexterm><primary>Screen White Point</primary></indexterm>

+This is a reasonable assumption,

+because the client is trying to query the screen's color gamut.

+</para>

+<para>

+<!-- .LP -->

+The following naming convention is used for the Max and Min functions:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+Xcms<emphasis remap='I'>&lt;color_space&gt;</emphasis>QueryMax<emphasis remap='I'>&lt;dimensions&gt;</emphasis>

+

+Xcms<emphasis remap='I'>&lt;color_space&gt;</emphasis>QueryMin<emphasis remap='I'>&lt;dimensions&gt;</emphasis>

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+The &lt;dimensions&gt; consists of a letter or letters 

+that identify the dimensions of the color space 

+that are not fixed.

+For example, 

+<function>XcmsTekHVCQueryMaxC</function>

+is given a fixed Hue and Value for which maximum Chroma is found.

+</para>

+<sect2 id="Red_Green_and_Blue_Queries">

+<title>Red, Green, and Blue Queries</title>

+<!-- .XS -->

+<!-- (SN Red, Green, and Blue Queries -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To obtain the color specification for black 

+(zero-intensity red, green, and blue), use

+<function>XcmsQueryBlack</function>.

+</para>

+<indexterm significance="preferred"><primary>XcmsQueryBlack</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsQueryBlack</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+The CCC's Client White Point and white point adjustment procedures

+are ignored.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>target_format</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the target color specification format.

+<!-- .ds Cs zero-intensity red, green, and blue -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the color specification in the specified target format

+for (Cs.

+The white point associated with the returned

+color specification is the Screen White Point.

+The value returned in the pixel member is undefined.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XcmsQueryBlack</function>

+function returns the color specification in the specified target format

+for zero-intensity red, green, and blue.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To obtain the color specification for blue 

+(full-intensity blue while red and green are zero), use

+<function>XcmsQueryBlue</function>.

+</para>

+<indexterm significance="preferred"><primary>XcmsQueryBlue</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsQueryBlue</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+The CCC's Client White Point and white point adjustment procedures

+are ignored.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>target_format</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the target color specification format.

+<!-- .ds Cs full-intensity blue while red and green are zero -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the color specification in the specified target format

+for (Cs.

+The white point associated with the returned

+color specification is the Screen White Point.

+The value returned in the pixel member is undefined.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XcmsQueryBlue</function>

+function returns the color specification in the specified target format

+for full-intensity blue while red and green are zero.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To obtain the color specification for green

+(full-intensity green while red and blue are zero), use

+<function>XcmsQueryGreen</function>.

+</para>

+<indexterm significance="preferred"><primary>XcmsQueryGreen</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsQueryGreen</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+The CCC's Client White Point and white point adjustment procedures

+are ignored.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>target_format</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the target color specification format.

+<!-- .ds Cs full-intensity green while red and blue are zero -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the color specification in the specified target format

+for (Cs.

+The white point associated with the returned

+color specification is the Screen White Point.

+The value returned in the pixel member is undefined.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XcmsQueryGreen</function>

+function returns the color specification in the specified target format

+for full-intensity green while red and blue are zero.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To obtain the color specification for red

+(full-intensity red while green and blue are zero), use

+<function>XcmsQueryRed</function>.

+</para>

+<indexterm significance="preferred"><primary>XcmsQueryRed</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsQueryRed</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+The CCC's Client White Point and white point adjustment procedures

+are ignored.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>target_format</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the target color specification format.

+<!-- .ds Cs full-intensity red while green and blue are zero -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the color specification in the specified target format

+for (Cs.

+The white point associated with the returned

+color specification is the Screen White Point.

+The value returned in the pixel member is undefined.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XcmsQueryRed</function>

+function returns the color specification in the specified target format

+for full-intensity red while green and blue are zero.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the color specification for white

+(full-intensity red, green, and blue), use

+<function>XcmsQueryWhite</function>.

+</para>

+<indexterm significance="preferred"><primary>XcmsQueryWhite</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsQueryWhite</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+The CCC's Client White Point and white point adjustment procedures

+are ignored.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>target_format</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the target color specification format.

+<!-- .ds Cs full-intensity red, green, and blue -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the color specification in the specified target format

+for (Cs.

+The white point associated with the returned

+color specification is the Screen White Point.

+The value returned in the pixel member is undefined.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XcmsQueryWhite</function>

+function returns the color specification in the specified target format

+for full-intensity red, green, and blue.

+</para>

+</sect2>

+<sect2 id="CIELab_Queries">

+<title>CIELab Queries</title>

+<!-- .XS -->

+<!-- (SN CIELab Queries -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The following equations are useful in describing the CIELab query functions:

+<!-- .EQ -->

+delim %%

+<!-- .EN -->

+</para>

+<para>

+<!-- .LP -->

+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>

+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>

+<indexterm><primary>Psychometric Chroma</primary></indexterm>

+<indexterm><primary>Psychometric Chroma</primary><secondary>maximum</secondary></indexterm>

+<literallayout class="monospaced">

+%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )%

+

+%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right ]%

+</literallayout>

+<!-- .sp -->

+To obtain the <acronym>CIE</acronym> L*a*b* coordinates of maximum Psychometric Chroma

+for a given Psychometric Hue Angle and <acronym>CIE</acronym> metric lightness (L*), use

+<function>XcmsCIELabQueryMaxC</function>.

+</para>

+<indexterm significance="preferred"><primary>XcmsCIELabQueryMaxC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsCIELabQueryMaxC</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>

+  <paramdef>XcmsFloat<parameter> L_star</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+The CCC's Client White Point and white point adjustment procedures

+are ignored.

+<!-- .ds Ha maximum chroma -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hue_angle</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the hue angle (in degrees) at which to find (Ha.

+<!-- .ds Ls maximum chroma -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>L_star</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the lightness (L*) at which to find (Ls.

+<!-- .ds Lc maximum chroma -->

+<!-- .ds lC hue angle and lightness -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the <acronym>CIE</acronym> L*a*b* coordinates of (Lc

+displayable by the screen for the given (lC.

+The white point associated with the returned

+color specification is the Screen White Point.

+The value returned in the pixel member is undefined.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XcmsCIELabQueryMaxC</function>

+function, given a hue angle and lightness,

+finds the point of maximum chroma displayable by the screen.

+It returns this point in <acronym>CIE</acronym> L*a*b* coordinates.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the <acronym>CIE</acronym> L*a*b* coordinates of maximum <acronym>CIE</acronym> metric lightness (L*)

+for a given Psychometric Hue Angle and Psychometric Chroma, use

+<function>XcmsCIELabQueryMaxL</function>.

+</para>

+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>

+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>

+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>maximum</secondary></indexterm>

+<indexterm significance="preferred"><primary>XcmsCIELabQueryMaxL</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsCIELabQueryMaxL</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>

+  <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+The CCC's Client White Point and white point adjustment procedures

+are ignored.

+<!-- .ds Ha maximum lightness -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hue_angle</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the hue angle (in degrees) at which to find (Ha.

+<!-- .ds Ch maximum lightness -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>chroma</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the chroma at which to find (Ch.

+<!-- .ds Lc maximum lightness -->

+<!-- .ds lC hue angle and chroma -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the <acronym>CIE</acronym> L*a*b* coordinates of (Lc

+displayable by the screen for the given (lC.

+The white point associated with the returned

+color specification is the Screen White Point.

+The value returned in the pixel member is undefined.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XcmsCIELabQueryMaxL</function>

+function, given a hue angle and chroma,

+finds the point in <acronym>CIE</acronym> L*a*b* color space of maximum 

+lightness (L*) displayable by the screen.

+It returns this point in <acronym>CIE</acronym> L*a*b* coordinates.

+An 

+<function>XcmsFailure</function>

+return value usually indicates that the given chroma

+is beyond maximum for the given hue angle.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To obtain the <acronym>CIE</acronym> L*a*b* coordinates of maximum Psychometric Chroma

+for a given Psychometric Hue Angle, use

+<function>XcmsCIELabQueryMaxLC</function>.

+</para>

+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>

+<indexterm><primary>Psychometric Chroma</primary></indexterm>

+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>

+<indexterm><primary>Psychometric Chroma</primary><secondary>maximum</secondary></indexterm>

+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>maximum</secondary></indexterm>

+<indexterm significance="preferred"><primary>XcmsCIELabQueryMaxLC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsCIELabQueryMaxLC</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+The CCC's Client White Point and white point adjustment procedures

+are ignored.

+<!-- .ds Ha maximum chroma -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hue_angle</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the hue angle (in degrees) at which to find (Ha.

+<!-- .ds Lc maximum chroma -->

+<!-- .ds lC hue angle -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the <acronym>CIE</acronym> L*a*b* coordinates of (Lc

+displayable by the screen for the given (lC.

+The white point associated with the returned

+color specification is the Screen White Point.

+The value returned in the pixel member is undefined.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XcmsCIELabQueryMaxLC</function>

+function, given a hue angle,

+finds the point of maximum chroma displayable by the screen.

+It returns this point in <acronym>CIE</acronym> L*a*b* coordinates.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To obtain the <acronym>CIE</acronym> L*a*b* coordinates of minimum <acronym>CIE</acronym> metric lightness (L*)

+for a given Psychometric Hue Angle and Psychometric Chroma, use

+<function>XcmsCIELabQueryMinL</function>.

+</para>

+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>

+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>

+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>minimum</secondary></indexterm>

+<indexterm significance="preferred"><primary>XcmsCIELabQueryMinL</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsCIELabQueryMinL</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>

+  <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+The CCC's Client White Point and white point adjustment procedures

+are ignored.

+<!-- .ds Ha minimum lightness -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hue_angle</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the hue angle (in degrees) at which to find (Ha.

+<!-- .ds Ch minimum lightness -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>chroma</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the chroma at which to find (Ch.

+<!-- .ds Lc minimum lightness -->

+<!-- .ds lC hue angle and chroma -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the <acronym>CIE</acronym> L*a*b* coordinates of (Lc

+displayable by the screen for the given (lC.

+The white point associated with the returned

+color specification is the Screen White Point.

+The value returned in the pixel member is undefined.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XcmsCIELabQueryMinL</function>

+function, given a hue angle and chroma,

+finds the point of minimum lightness (L*) displayable by the screen.

+It returns this point in <acronym>CIE</acronym> L*a*b* coordinates.

+An 

+<function>XcmsFailure</function>

+return value usually indicates that the given chroma

+is beyond maximum for the given hue angle.

+</para>

+</sect2>

+<sect2 id="CIELuv_Queries">

+<title>CIELuv Queries</title>

+<!-- .XS -->

+<!-- (SN CIELuv Queries -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The following equations are useful in describing the CIELuv query functions:

+<!-- .EQ -->

+delim %%

+<!-- .EN -->

+</para>

+<para>

+<!-- .LP -->

+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>

+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>

+<indexterm><primary>Psychometric Chroma</primary></indexterm>

+<indexterm><primary>Psychometric Chroma</primary><secondary>maximum</secondary></indexterm>

+<literallayout class="monospaced">

+%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )%

+

+%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right ]%

+</literallayout>

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To obtain the <acronym>CIE</acronym> L*u*v* coordinates of maximum Psychometric Chroma

+for a given Psychometric Hue Angle and <acronym>CIE</acronym> metric lightness (L*), use

+<function>XcmsCIELuvQueryMaxC</function>.

+</para>

+<indexterm significance="preferred"><primary>XcmsCIELuvQueryMaxC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsCIELuvQueryMaxC</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>

+  <paramdef>XcmsFloat<parameter> L_star</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+The CCC's Client White Point and white point adjustment procedures

+are ignored.

+<!-- .ds Ha maximum chroma -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hue_angle</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the hue angle (in degrees) at which to find (Ha.

+<!-- .ds Ls maximum chroma -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>L_star</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the lightness (L*) at which to find (Ls.

+<!-- .ds Lc maximum chroma -->

+<!-- .ds lC hue angle and lightness -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the <acronym>CIE</acronym> L*u*v* coordinates of (Lc

+displayable by the screen for the given (lC.

+The white point associated with the returned

+color specification is the Screen White Point.

+The value returned in the pixel member is undefined.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XcmsCIELuvQueryMaxC</function>

+function, given a hue angle and lightness,

+finds the point of maximum chroma displayable by the screen.

+It returns this point in <acronym>CIE</acronym> L*u*v* coordinates.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To obtain the <acronym>CIE</acronym> L*u*v* coordinates of maximum <acronym>CIE</acronym> metric lightness (L*)

+for a given Psychometric Hue Angle and Psychometric Chroma, use

+<function>XcmsCIELuvQueryMaxL</function>.

+</para>

+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>

+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>

+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>maximum</secondary></indexterm>

+<indexterm significance="preferred"><primary>XcmsCIELuvQueryMaxL</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsCIELuvQueryMaxL</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>

+  <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+The CCC's Client White Point and white point adjustment procedures

+are ignored.

+<!-- .ds Ha maximum lightness -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hue_angle</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the hue angle (in degrees) at which to find (Ha.

+<!-- .ds Ls maximum lightness -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>L_star</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the lightness (L*) at which to find (Ls.

+<!-- .ds Lc maximum lightness -->

+<!-- .ds lC hue angle and chroma -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the <acronym>CIE</acronym> L*u*v* coordinates of (Lc

+displayable by the screen for the given (lC.

+The white point associated with the returned

+color specification is the Screen White Point.

+The value returned in the pixel member is undefined.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XcmsCIELuvQueryMaxL</function>

+function, given a hue angle and chroma,

+finds the point in <acronym>CIE</acronym> L*u*v* color space of maximum 

+lightness (L*) displayable by the screen.

+It returns this point in <acronym>CIE</acronym> L*u*v* coordinates.

+An 

+<function>XcmsFailure</function>

+return value usually indicates that the given chroma

+is beyond maximum for the given hue angle.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To obtain the <acronym>CIE</acronym> L*u*v* coordinates of maximum Psychometric Chroma

+for a given Psychometric Hue Angle, use

+<function>XcmsCIELuvQueryMaxLC</function>.

+</para>

+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>

+<indexterm><primary>Psychometric Chroma</primary></indexterm>

+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>

+<indexterm><primary>Psychometric Chroma</primary><secondary>maximum</secondary></indexterm>

+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>maximum</secondary></indexterm>

+<indexterm significance="preferred"><primary>XcmsCIELuvQueryMaxLC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsCIELuvQueryMaxLC</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+The CCC's Client White Point and white point adjustment procedures

+are ignored.

+<!-- .ds Ha maximum chroma -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hue_angle</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the hue angle (in degrees) at which to find (Ha.

+<!-- .ds Lc maximum chroma -->

+<!-- .ds lC hue angle -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the <acronym>CIE</acronym> L*u*v* coordinates of (Lc

+displayable by the screen for the given (lC.

+The white point associated with the returned

+color specification is the Screen White Point.

+The value returned in the pixel member is undefined.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XcmsCIELuvQueryMaxLC</function>

+function, given a hue angle,

+finds the point of maximum chroma displayable by the screen.

+It returns this point in <acronym>CIE</acronym> L*u*v* coordinates.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To obtain the <acronym>CIE</acronym> L*u*v* coordinates of minimum <acronym>CIE</acronym> metric lightness (L*)

+for a given Psychometric Hue Angle and Psychometric Chroma, use

+<function>XcmsCIELuvQueryMinL</function>.

+</para>

+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>

+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>

+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>minimum</secondary></indexterm>

+<indexterm significance="preferred"><primary>XcmsCIELuvQueryMinL</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> </function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>

+  <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+The CCC's Client White Point and white point adjustment procedures

+are ignored.

+<!-- .ds Ha minimum lightness -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hue_angle</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the hue angle (in degrees) at which to find (Ha.

+<!-- .ds Ch minimum lightness -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>chroma</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the chroma at which to find (Ch.

+<!-- .ds Lc minimum lightness -->

+<!-- .ds lC hue angle and chroma -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the <acronym>CIE</acronym> L*u*v* coordinates of (Lc

+displayable by the screen for the given (lC.

+The white point associated with the returned

+color specification is the Screen White Point.

+The value returned in the pixel member is undefined.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XcmsCIELuvQueryMinL</function>

+function, given a hue angle and chroma,

+finds the point of minimum lightness (L*) displayable by the screen.

+It returns this point in <acronym>CIE</acronym> L*u*v* coordinates.

+An 

+<function>XcmsFailure</function>

+return value usually indicates that the given chroma

+is beyond maximum for the given hue angle.

+</para>

+</sect2>

+<sect2 id="TekHVC_Queries">

+<title>TekHVC Queries</title>

+<!-- .XS -->

+<!-- (SN TekHVC Queries -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To obtain the maximum Chroma for a given Hue and Value, use

+<function>XcmsTekHVCQueryMaxC</function>.

+</para>

+<indexterm><primary>Chroma</primary></indexterm>

+<indexterm><primary>Chroma</primary><secondary>maximum</secondary></indexterm>

+<indexterm significance="preferred"><primary>XcmsTekHVCQueryMaxC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsTekHVCQueryMaxC</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsFloat<parameter> hue</parameter></paramdef>

+  <paramdef>XcmsFloat<parameter> value</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+The CCC's Client White Point and white point adjustment procedures

+are ignored.

+<!-- .ds Hu in which to find the maximum Chroma -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hue</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the Hue (Hu.

+<!-- .ds Va maximum Chroma -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>value</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the Value in which to find the (Va.

+<!-- .ds Lc maximum Chroma along with the actual Hue and Value  -->

+<!-- .ds lC maximum Chroma -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the (Lc at which the (lC was found.

+The white point associated with the returned

+color specification is the Screen White Point.

+The value returned in the pixel member is undefined.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XcmsTekHVCQueryMaxC</function>

+function, given a Hue and Value,

+determines the maximum Chroma in TekHVC color space

+displayable by the screen.

+It returns the maximum Chroma along with the actual Hue

+and Value at which the maximum Chroma was found.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To obtain the maximum Value for a given Hue and Chroma, use

+<function>XcmsTekHVCQueryMaxV</function>.

+</para>

+<indexterm><primary>Value</primary></indexterm>

+<indexterm><primary>Value</primary><secondary>maximum</secondary></indexterm>

+<indexterm significance="preferred"><primary>XcmsTekHVCQueryMaxV</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsTekHVCQueryMaxV</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsFloat<parameter> hue</parameter></paramdef>

+  <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+The CCC's Client White Point and white point adjustment procedures

+are ignored.

+<!-- .ds Hu in which to find the maximum Value -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hue</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the Hue (Hu.

+<!-- .ds Ch maximum Value -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>chroma</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the chroma at which to find (Ch.

+<!-- .ds Lc maximum Value along with the Hue and Chroma -->

+<!-- .ds lC maximum Value -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the (Lc at which the (lC was found.

+The white point associated with the returned

+color specification is the Screen White Point.

+The value returned in the pixel member is undefined.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XcmsTekHVCQueryMaxV</function>

+function, given a Hue and Chroma,

+determines the maximum Value in TekHVC color space

+displayable by the screen.

+It returns the maximum Value and the actual Hue and Chroma

+at which the maximum Value was found.

+<!-- .sp -->

+</para>

+

+<para>

+<!-- .LP -->

+To obtain the maximum Chroma and Value at which it is reached

+for a specified Hue, use

+<function>XcmsTekHVCQueryMaxVC</function>.

+</para>

+<indexterm><primary>Chroma</primary></indexterm>

+<indexterm><primary>Value</primary></indexterm>

+<indexterm><primary>Chroma</primary><secondary>maximum</secondary></indexterm>

+<indexterm><primary>Value</primary><secondary>maximum</secondary></indexterm>

+<indexterm significance="preferred"><primary>XcmsTekHVCQueryMaxVC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsTekHVCQueryMaxVC</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsFloat<parameter> hue</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+The CCC's Client White Point and white point adjustment procedures

+are ignored.

+<!-- .ds Hu in which to find the maximum Chroma -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hue</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the Hue (Hu.

+<!-- .ds Lc color specification in \ -->

+XcmsTekHVC for the maximum Chroma, the Value at which \

+that maximum Chroma is reached, and the actual Hue

+<!-- .ds lC maximum Chroma -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the (Lc at which the (lC was found.

+The white point associated with the returned

+color specification is the Screen White Point.

+The value returned in the pixel member is undefined.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XcmsTekHVCQueryMaxVC</function>

+function, given a Hue,

+determines the maximum Chroma in TekHVC color space displayable by the screen

+and the Value at which that maximum Chroma is reached.

+It returns the maximum Chroma,

+the Value at which that maximum Chroma is reached,

+and the actual Hue for which the maximum Chroma was found.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To obtain a specified number of TekHVC specifications such that they

+contain maximum Values for a specified Hue and the

+Chroma at which the maximum Values are reached, use

+<function>XcmsTekHVCQueryMaxVSamples</function>.

+</para>

+<indexterm><primary>Chroma</primary></indexterm>

+<indexterm><primary>Value</primary></indexterm>

+<indexterm><primary>Chroma</primary><secondary>maximum</secondary></indexterm>

+<indexterm><primary>Value</primary><secondary>maximum</secondary></indexterm>

+<indexterm significance="preferred"><primary>XcmsTekHVCQueryMaxVSamples</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsTekHVCQueryMaxVSamples</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsFloat<parameter> hue</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> colors_return[]</parameter></paramdef>

+  <paramdef>unsignedint<parameter> nsamples</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+The CCC's Client White Point and white point adjustment procedures

+are ignored.

+<!-- .ds Hu for maximum Chroma/Value samples -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hue</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the Hue (Hu.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nsamples</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of samples.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colors_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns nsamples of color specifications in XcmsTekHVC

+such that the Chroma is the maximum attainable for the Value and Hue.

+The white point associated with the returned

+color specification is the Screen White Point.

+The value returned in the pixel member is undefined.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XcmsTekHVCQueryMaxVSamples</function>

+returns nsamples of maximum Value, the Chroma at which that maximum Value

+is reached, and the actual Hue for which the maximum Chroma was found.

+These sample points may then be used to plot the maximum Value/Chroma

+boundary of the screen's color gamut for the specified Hue in TekHVC color

+space.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To obtain the minimum Value for a given Hue and Chroma, use

+<function>XcmsTekHVCQueryMinV</function>.

+</para>

+<indexterm><primary>Value</primary></indexterm>

+<indexterm><primary>Value</primary><secondary>minimum</secondary></indexterm>

+<indexterm significance="preferred"><primary>XcmsTekHVCQueryMinV</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsTekHVCQueryMinV</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsFloat<parameter> hue</parameter></paramdef>

+  <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+The CCC's Client White Point and white point adjustment procedures

+are ignored.

+<!-- .ds Hu in which to find the minimum Value -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hue</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the Hue (Hu.

+<!-- .ds Va minimum Value -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>value</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the Value in which to find the (Va.

+<!-- .ds Lc minimum Value and the actual Hue and Chroma -->

+<!-- .ds lC minimum Value -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the (Lc at which the (lC was found.

+The white point associated with the returned

+color specification is the Screen White Point.

+The value returned in the pixel member is undefined.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XcmsTekHVCQueryMinV</function>

+function, given a Hue and Chroma,

+determines the minimum Value in TekHVC color space displayable by the screen.

+It returns the minimum Value and the actual Hue and Chroma at which

+the minimum Value was found.

+</para>

+

+</sect2>

+</sect1>

+<sect1 id="Color_Management_Extensions">

+<title>Color Management Extensions</title>

+<!-- .XS -->

+<!-- (SN Color Management Extensions -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The Xlib color management facilities can be extended in two ways:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Device-Independent Color Spaces

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Device-independent color spaces that are derivable to <acronym>CIE</acronym> XYZ

+space can be added using the

+<function>XcmsAddColorSpace</function>

+function.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Color Characterization Function Set

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A Color Characterization Function Set consists of

+device-dependent color spaces and their functions that

+convert between these color spaces and the <acronym>CIE</acronym> XYZ

+color space, bundled together for a specific class of output devices.

+A function set can be added using the

+<function>XcmsAddFunctionSet</function>

+function.

+    </para>

+  </listitem>

+</itemizedlist>

+<sect2 id="Color_Spaces">

+<title>Color Spaces</title>

+<!-- .XS -->

+<!-- (SN Color Spaces -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The <acronym>CIE</acronym> XYZ color space serves as the hub for all

+conversions between device-independent and device-dependent color spaces.

+Therefore, the knowledge to convert an 

+<function>XcmsColor</function>

+structure to and from <acronym>CIE</acronym> XYZ format is associated with each color space.

+For example, conversion from <acronym>CIE</acronym> L*u*v* to <acronym>RGB</acronym> requires the knowledge

+to convert from <acronym>CIE</acronym> L*u*v* to <acronym>CIE</acronym> XYZ and from <acronym>CIE</acronym> XYZ to <acronym>RGB</acronym>.

+This knowledge is stored as an array of functions that,

+when applied in series, will convert the 

+<function>XcmsColor</function>

+structure to or from <acronym>CIE</acronym> XYZ format.

+This color specification conversion mechanism facilitates

+the addition of color spaces.

+</para>

+<para>

+<!-- .LP -->

+Of course, when converting between only device-independent color spaces

+or only device-dependent color spaces,

+shortcuts are taken whenever possible.

+For example, conversion from TekHVC to <acronym>CIE</acronym> L*u*v* is performed 

+by intermediate conversion to <acronym>CIE</acronym> u*v*Y and then to <acronym>CIE</acronym> L*u*v*, 

+thus bypassing conversion between <acronym>CIE</acronym> u*v*Y and <acronym>CIE</acronym> XYZ.

+</para>

+</sect2>

+<sect2 id="Adding_Device_Independent_Color_Spaces">

+<title>Adding Device-Independent Color Spaces</title>

+<!-- .XS -->

+<!-- (SN Adding Device-Independent Color Spaces -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To add a device-independent color space, use

+<function>XcmsAddColorSpace</function>.

+</para>

+<indexterm significance="preferred"><primary>XcmsAddColorSpace</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsAddColorSpace</function></funcdef>

+  <paramdef>XcmsColorSpace<parameter> *color_space</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_space</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the device-independent color space to add.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XcmsAddColorSpace</function>

+function makes a device-independent color space (actually an

+<function>XcmsColorSpace</function>

+structure) accessible by the color management system.

+Because format values for unregistered color spaces are assigned at run time,

+they should be treated as private to the client.

+If references to an unregistered color space must be made

+outside the client (for example, storing color specifications 

+in a file using the unregistered color space), 

+then reference should be made by color space prefix

+(see

+<function>XcmsFormatOfPrefix</function>

+and

+<function>XcmsPrefixOfFormat</function>).

+</para>

+<para>

+<!-- .LP -->

+If the 

+<function>XcmsColorSpace</function>

+structure is already accessible in the color management system, 

+<function>XcmsAddColorSpace</function>

+returns 

+<function>XcmsSuccess</function>.

+</para>

+<para>

+<!-- .LP -->

+Note that added 

+<function>XcmsColorSpaces</function>

+must be retained for reference by Xlib.

+</para>

+</sect2>

+<sect2 id="Querying_Color_Space_Format_and_Prefix">

+<title>Querying Color Space Format and Prefix</title>

+<!-- .XS -->

+<!-- (SN Querying Color Space Format and Prefix -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To obtain the format associated with the color space

+associated with a specified color string prefix, use

+<function>XcmsFormatOfPrefix</function>.

+</para>

+<indexterm significance="preferred"><primary>XcmsFormatOfPrefix</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XcmsColorFormat<function>XcmsFormatOfPrefix</function></funcdef>

+  <paramdef>char<parameter> *prefix</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>prefix</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the string that contains the color space prefix.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XcmsFormatOfPrefix</function>

+function returns the format for the specified color space prefix

+(for example, the string ``CIEXYZ'').

+The prefix is case-insensitive.

+If the color space is not accessible in the color management system,

+<function>XcmsFormatOfPrefix</function>

+returns 

+<function>XcmsUndefinedFormat</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the color string prefix associated with the color space

+specified by a color format, use

+<function>XcmsPrefixOfFormat</function>.

+</para>

+<indexterm significance="preferred"><primary>XcmsPrefixOfFormat</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char <function>*XcmsPrefixOfFormat</function></funcdef>

+  <paramdef>XcmsColorFormat<parameter> format</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>format</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the color specification format.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XcmsPrefixOfFormat</function>

+function returns the string prefix associated with the color specification

+encoding specified by the format argument.

+Otherwise, if no encoding is found, it returns NULL.

+The returned string must be treated as read-only.

+</para>

+</sect2>

+<sect2 id="Creating_Additional_Color_Spaces">

+<title>Creating Additional Color Spaces</title>

+<!-- .XS -->

+<!-- (SN Creating Additional Color Spaces -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Color space specific information necessary 

+for color space conversion and color string parsing is stored in an

+<function>XcmsColorSpace</function>

+structure.

+Therefore, a new structure containing this information is required

+for each additional color space.

+In the case of device-independent color spaces,

+a handle to this new structure (that is, by means of a global variable)

+is usually made accessible to the client program for use with the

+<function>XcmsAddColorSpace</function>

+function.

+</para>

+<para>

+<!-- .LP -->

+If a new 

+<function>XcmsColorSpace</function>

+structure specifies a color space not registered with the X Consortium,

+they should be treated as private to the client

+because format values for unregistered color spaces are assigned at run time.

+If references to an unregistered color space must be made outside the

+client (for example, storing color specifications in a file using the

+unregistered color space), then reference should be made by color space prefix

+(see

+<function>XcmsFormatOfPrefix</function>

+and

+<function>XcmsPrefixOfFormat</function>).

+<!-- .sM -->

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef (*XcmsConversionProc)();

+typedef XcmsConversionProc *XcmsFuncListPtr;

+		/* A NULL terminated list of function pointers*/

+

+typedef struct _XcmsColorSpace {

+	char *prefix;

+	XcmsColorFormat format;

+	XcmsParseStringProc parseString;

+	XcmsFuncListPtr to_CIEXYZ;

+	XcmsFuncListPtr from_CIEXYZ;

+	int inverse_flag;

+} XcmsColorSpace;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The prefix member specifies the prefix that indicates a color string 

+is in this color space's string format.

+For example, the strings ``ciexyz'' or ``CIEXYZ'' for <acronym>CIE</acronym> XYZ,

+and ``rgb'' or ``<acronym>RGB</acronym>'' for <acronym>RGB</acronym>.

+The prefix is case insensitive.

+The format member specifies the color specification format.

+Formats for unregistered color spaces are assigned at run time.

+The parseString member contains a pointer to the function 

+that can parse a color string into an 

+<function>XcmsColor</function>

+structure.

+This function returns an integer (int): nonzero if it succeeded

+and zero otherwise.

+The to_CIEXYZ and from_CIEXYZ members contain pointers,

+each to a NULL terminated list of function pointers.

+When the list of functions is executed in series,

+it will convert the color specified in an 

+<function>XcmsColor</function>

+structure from/to the current color space format to/from the <acronym>CIE</acronym> XYZ format.

+Each function returns an integer (int): nonzero if it succeeded

+and zero otherwise.

+The white point to be associated with the colors is specified

+explicitly, even though white points can be found in the CCC.

+The inverse_flag member, if nonzero, specifies that for each function listed 

+in to_CIEXYZ,

+its inverse function can be found in from_CIEXYZ such that:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+Given:  n = number of functions in each list

+

+for each i, such that 0 &lt;= i &lt; n

+    from_CIEXYZ[n - i - 1] is the inverse of to_CIEXYZ[i].

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+This allows Xlib to use the shortest conversion path,

+thus bypassing <acronym>CIE</acronym> XYZ if possible (for example, TekHVC to <acronym>CIE</acronym> L*u*v*).

+</para>

+</sect2>

+<sect2 id="Parse_String_Callback">

+<title>Parse String Callback</title>

+<!-- .XS -->

+<!-- (SN Parse String Callback -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The callback in the

+<function>XcmsColorSpace</function>

+structure for parsing a color string for the particular color space must

+adhere to the following software interface specification:

+</para>

+<indexterm significance="preferred"><primary>XcmsParseStringProc</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsParseStringProc</function></funcdef>

+  <paramdef>char<parameter> *color_string</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the color string to parse.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>color_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the color specification in the color space's format.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+</para>

+</sect2>

+<sect2 id="Color_Specification_Conversion_Callback">

+<title>Color Specification Conversion Callback</title>

+<!-- .XS -->

+<!-- (SN Color Specification Conversion Callback -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Callback functions in the

+<function>XcmsColorSpace</function>

+structure for converting a color specification between device-independent

+spaces must adhere to the

+following software interface specification:

+</para>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>ConversionProc</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *white_point</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *colors_in_out</parameter></paramdef>

+  <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>white_point</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the white point associated with color specifications.

+The pixel member should be ignored,

+and the entire structure remain unchanged upon return.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colors_in_out</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array of color specifications.

+Pixel members should be ignored and must remain unchanged upon return.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ncolors</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of 

+<function>XcmsColor</function>

+structures in the color-specification array.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+Callback functions in the

+<function>XcmsColorSpace</function>

+structure for converting a color specification to or from a device-dependent

+space must adhere to the

+following software interface specification:

+</para>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>ConversionProc</function></funcdef>

+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

+  <paramdef>XcmsColor<parameter> *colors_in_out</parameter></paramdef>

+  <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>

+  <paramdef>Bool<parameter> compression_flags_return[]</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ccc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the CCC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colors_in_out</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array of color specifications.

+Pixel members should be ignored and must remain unchanged upon return.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ncolors</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of 

+<function>XcmsColor</function>

+structures in the color-specification array.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>compression_flags_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns an array of Boolean values for indicating compression status.

+If a non-NULL pointer is supplied

+and a color at a given index is compressed, then

+<function>True</function>

+should be stored at the corresponding index in this array;

+otherwise, the array should not be modified.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Conversion functions are available globally for use by other color

+spaces.

+The conversion functions provided by Xlib are:

+</para>

+<informaltable>

+  <tgroup cols='3' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <colspec colname='c3'/>

+  <thead>

+    <row>

+      <entry>Function</entry>

+      <entry>Converts from</entry>

+      <entry>Converts to</entry>

+    </row>

+  </thead>

+  <tbody>

+    <row>

+      <entry><function>XcmsCIELabToCIEXYZ</function></entry>

+      <entry><function>XcmsCIELabFormat</function></entry>

+      <entry><function>XcmsCIEXYZFormat</function></entry>

+    </row>

+    <row>

+      <entry><function>XcmsCIELuvToCIEuvY</function></entry>

+      <entry><function>XcmsCIELuvFormat</function></entry>

+      <entry><function>XcmsCIEuvYFormat</function></entry>

+    </row>

+    <row>

+      <entry><function>XcmsCIEXYZToCIELab</function></entry>

+      <entry><function>XcmsCIEXYZFormat</function></entry>

+      <entry><function>XcmsCIELabFormat</function></entry>

+    </row>

+    <row>

+      <entry><function>XcmsCIEXYZToCIEuvY</function></entry>

+      <entry><function>XcmsCIEXYZFormat</function></entry>

+      <entry><function>XcmsCIEuvYFormat</function></entry>

+    </row>

+    <row>

+      <entry><function>XcmsCIEXYZToCIExyY</function></entry>

+      <entry><function>XcmsCIEXYZFormat</function></entry>

+      <entry><function>XcmsCIExyYFormat</function></entry>

+    </row>

+    <row>

+      <entry><function>XcmsCIEXYZToRGBi</function></entry>

+      <entry><function>XcmsCIEXYZFormat</function></entry>

+      <entry><function>XcmsRGBiFormat</function></entry>

+    </row>

+    <row>

+      <entry><function>XcmsCIEuvYToCIELuv</function></entry>

+      <entry><function>XcmsCIEuvYFormat</function></entry>

+      <entry><function>XcmsCIELabFormat</function></entry>

+    </row>

+    <row>

+      <entry><function>XcmsCIEuvYToCIEXYZ</function></entry>

+      <entry><function>XcmsCIEuvYFormat</function></entry>

+      <entry><function>XcmsCIEXYZFormat</function></entry>

+    </row>

+    <row>

+      <entry><function>XcmsCIEuvYToTekHVC</function></entry>

+      <entry><function>XcmsCIEuvYFormat</function></entry>

+      <entry><function>XcmsTekHVCFormat</function></entry>

+    </row>

+    <row>

+      <entry><function>XcmsCIExyYToCIEXYZ</function></entry>

+      <entry><function>XcmsCIExyYFormat</function></entry>

+      <entry><function>XcmsCIEXYZFormat</function></entry>

+    </row>

+    <row>

+      <entry><function>XcmsRGBToRGBi</function></entry>

+      <entry><function>XcmsRGBFormat</function></entry>

+      <entry><function>XcmsRGBiFormat</function></entry>

+    </row>

+    <row>

+      <entry><function>XcmsRGBiToCIEXYZ</function></entry>

+      <entry><function>XcmsRGBiFormat</function></entry>

+      <entry><function>XcmsCIEXYZFormat</function></entry>

+    </row>

+    <row>

+      <entry><function>XcmsRGBiToRGB</function></entry>

+      <entry><function>XcmsRGBiFormat</function></entry>

+      <entry><function>XcmsRGBFormat</function></entry>

+    </row>

+    <row>

+      <entry><function>XcmsTekHVCToCIEuvY</function></entry>

+      <entry><function>XcmsTekHVCFormat</function></entry>

+      <entry><function>XcmsCIEuvYFormat</function></entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+</sect2>

+<sect2 id="Function_Sets">

+<title>Function Sets</title>

+<!-- .XS -->

+<!-- (SN Function Sets -->

+<!-- .XE -->

+<indexterm><primary>Function set</primary></indexterm>

+<indexterm><primary>Function set</primary><secondary>LINEAR_RGB</secondary></indexterm>

+<para>

+<!-- .LP -->

+Functions to convert between device-dependent color spaces

+and <acronym>CIE</acronym> XYZ may differ for different classes of output devices

+(for example, color versus gray monitors).

+Therefore, the notion of a Color Characterization Function Set

+has been developed.

+A function set consists of device-dependent color spaces

+and the functions that convert color specifications 

+between these device-dependent color spaces and the <acronym>CIE</acronym> XYZ color space

+appropriate for a particular class of output devices.

+The function set also contains a function that reads

+color characterization data off root window properties.

+It is this characterization data that will differ between devices within

+a class of output devices.

+<indexterm><primary>Device Color Characterization</primary></indexterm>

+For details about how color characterization data is

+stored in root window properties,

+see the section on Device Color Characterization in the

+<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.

+The LINEAR_RGB function set is provided by Xlib

+and will support most color monitors.

+Function sets may require data that differs

+from those needed for the LINEAR_RGB function set.

+In that case, 

+its corresponding data may be stored on different root window properties.

+</para>

+</sect2>

+<sect2 id="Adding_Function_Sets">

+<title>Adding Function Sets</title>

+<!-- .XS -->

+<!-- (SN Adding Function Sets -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To add a function set, use

+<function>XcmsAddFunctionSet</function>.

+</para>

+<indexterm significance="preferred"><primary>XcmsAddFunctionSet</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XcmsAddFunctionSet</function></funcdef>

+  <paramdef>XcmsFunctionSet<parameter> *function_set</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>function_set</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the function set to add.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XcmsAddFunctionSet</function>

+function adds a function set to the color management system.

+If the function set uses device-dependent 

+<function>XcmsColorSpace</function>

+structures not accessible in the color management system,

+<function>XcmsAddFunctionSet</function>

+adds them.

+If an added

+<function>XcmsColorSpace</function>

+structure is for a device-dependent color space not registered

+with the X Consortium,

+they should be treated as private to the client

+because format values for unregistered color spaces are assigned at run time.

+If references to an unregistered color space must be made outside the

+client (for example, storing color specifications in a file

+using the unregistered color space),

+then reference should be made by color space prefix

+(see 

+<function>XcmsFormatOfPrefix</function>

+and

+<function>XcmsPrefixOfFormat</function>).

+</para>

+<para>

+<!-- .LP -->

+Additional function sets should be added before any calls to other

+Xlib routines are made.

+If not, the 

+<function>XcmsPerScrnInfo</function>

+member of a previously created 

+<function>XcmsCCC</function>

+does not have the opportunity to initialize

+with the added function set.

+</para>

+</sect2>

+<sect2 id="Creating_Additional_Function_Sets">

+<title>Creating Additional Function Sets</title>

+<!-- .XS -->

+<!-- (SN Creating Additional Function Sets -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The creation of additional function sets should be

+required only when an output device does not conform to existing 

+function sets or when additional device-dependent color spaces are necessary.

+A function set consists primarily of a collection of device-dependent

+<function>XcmsColorSpace</function>

+structures and a means to read and store a 

+screen's color characterization data.

+This data is stored in an

+<function>XcmsFunctionSet</function>

+structure.

+A handle to this structure (that is, by means of global variable)

+is usually made accessible to the client program for use with

+<function>XcmsAddFunctionSet</function>.

+</para>

+<para>

+<!-- .LP -->

+If a function set uses new device-dependent 

+<function>XcmsColorSpace</function>

+structures,

+they will be transparently processed into the color management system.

+Function sets can share an 

+<function>XcmsColorSpace</function>

+structure for a device-dependent color space.

+In addition, multiple 

+<function>XcmsColorSpace</function>

+structures are allowed for a device-dependent color space;

+however, a function set can reference only one of them.

+These 

+<function>XcmsColorSpace</function>

+structures will differ in the functions to convert to and from <acronym>CIE</acronym> XYZ,

+thus tailored for the specific function set.

+<!-- .sM -->

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct _XcmsFunctionSet {

+	XcmsColorSpace **DDColorSpaces;

+	XcmsScreenInitProc screenInitProc;

+	XcmsScreenFreeProc screenFreeProc;

+} XcmsFunctionSet;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The DDColorSpaces member is a pointer to a NULL terminated list

+of pointers to 

+<function>XcmsColorSpace</function>

+structures for the device-dependent color spaces that are supported

+by the function set.

+The screenInitProc member is set to the callback procedure (see the following

+interface specification) that initializes the 

+<function>XcmsPerScrnInfo</function>

+structure for a particular screen.

+</para>

+<para>

+<!-- .LP -->

+The screen initialization callback must adhere to the following software

+interface specification:

+<indexterm significance="preferred"><primary>XcmsScreenInitProc</primary></indexterm>

+<!-- .sM -->

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>typedef Status <function>(*XcmsScreenInitProc</function>)</funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> screen_number</parameter></paramdef>

+  <paramdef>ScmsPerScrnInfo<parameter> *screen_info</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate screen number on the host server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_info</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the 

+<function>XcmsPerScrnInfo </function>

+structure, which contains the per screen information.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The screen initialization callback in the

+<function>XcmsFunctionSet</function>

+structure fetches the color characterization data (device profile) for

+the specified screen,

+typically off properties on the 

+screen's root window.

+It then initializes the specified

+<function>XcmsPerScrnInfo</function>

+structure.

+<indexterm><primary>Device profile</primary></indexterm>

+<indexterm><primary>Color Characterization Data</primary></indexterm>

+If successful, the procedure fills in the 

+<function>XcmsPerScrnInfo</function>

+structure as follows:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+It sets the screenData member to the address 

+of the created device profile data structure 

+(contents known only by the function set).

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It next sets the screenWhitePoint member.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It next sets the functionSet member to the address of the

+<function>XcmsFunctionSet</function>

+structure.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It then sets the state member to 

+<function>XcmsInitSuccess </function>

+and finally returns

+<function>XcmsSuccess</function>.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+If unsuccessful, the procedure sets the state member to 

+<function>XcmsInitFailure</function>

+and returns

+<function>XcmsFailure</function>.

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XcmsPerScrnInfo</function>

+structure contains:

+<!-- .sM -->

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct _XcmsPerScrnInfo {

+	XcmsColor screenWhitePoint;

+	XPointer functionSet;

+	XPointer screenData;

+	unsigned char state;

+	char pad[3];

+} XcmsPerScrnInfo;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The screenWhitePoint member specifies the white point inherent to

+the screen.

+The functionSet member specifies the appropriate function set.

+The screenData member specifies the device profile.

+The state member is set to one of the following:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+<function>XcmsInitNone</function>

+indicates initialization has not been previously attempted.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XcmsInitFailure</function>

+indicates initialization has been previously attempted but failed.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XcmsInitSuccess</function>

+indicates initialization has been previously attempted and succeeded.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+The screen free callback must adhere to the following software

+interface specification:

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>typedef void (*XcmsScreenFreeProc)</funcdef>

+  <paramdef>XPointer<parameter> screenData</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screenData</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the data to be freed.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+This function is called to free the screenData stored in an

+<function>XcmsPerScrnInfo</function>

+structure.

+<!-- .bp -->

+

+</para>

+</sect2>

+</sect1>

+</chapter>

diff --git a/libX11/specs/libX11/CH07 b/libX11/specs/libX11/CH07
deleted file mode 100644
index d6f672289..000000000
--- a/libX11/specs/libX11/CH07
+++ /dev/null
@@ -1,2357 +0,0 @@
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-.\" OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" Except as contained in this notice, the name of the X Consortium shall
-.\" not be used in advertising or otherwise to promote the sale, use or
-.\" other dealings in this Software without prior written authorization
-.\" from the X Consortium.
-.\"
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
-.\" Digital Equipment Corporation
-.\"
-.\" Portions Copyright \(co 1990, 1991 by
-.\" Tektronix, Inc.
-.\"
-.\" Permission to use, copy, modify and distribute this documentation for
-.\" any purpose and without fee is hereby granted, provided that the above
-.\" copyright notice appears in all copies and that both that copyright notice
-.\" and this permission notice appear in all copies, and that the names of
-.\" Digital and Tektronix not be used in in advertising or publicity pertaining
-.\" to this documentation without specific, written prior permission.
-.\" Digital and Tektronix makes no representations about the suitability
-.\" of this documentation for any purpose.
-.\" It is provided ``as is'' without express or implied warranty.
-.\" 
-\&
-.sp 1
-.ce 3
-\s+1\fBChapter 7\fP\s-1
-
-\s+1\fBGraphics Context Functions\fP\s-1
-.sp 2
-.nr H1 7
-.nr H2 0
-.nr H3 0
-.nr H4 0
-.nr H5 0
-.na
-.LP
-.XS
-Chapter 7: Graphics Context Functions 
-.XE
-A number of resources are used when performing graphics operations in X.
-Most information about performing graphics (for example, foreground
-color, background color, line style, and so on) is stored in
-resources called graphics contexts (GCs).
-.IN "Graphics context"
-Most graphics operations (see chapter 8) take a 
-GC as an argument.
-Although in theory the X protocol permits sharing of GCs between applications, 
-it is expected that applications will use their own
-GCs when performing operations. 
-Sharing of GCs is highly discouraged because the library may cache GC state.
-.LP
-Graphics operations can be performed to either windows or pixmaps, 
-which collectively are called drawables.
-.IN "Root"
-Each drawable exists on a single screen.
-A GC is created for a specific screen and drawable depth
-and can only be used with drawables of matching
-screen and depth.
-.LP
-This chapter discusses how to:
-.IP \(bu 5
-Manipulate graphics context/state
-.IP \(bu 5
-Use graphics context convenience functions
-.NH 2
-Manipulating Graphics Context/State
-.XS
-\*(SN Manipulating Graphics Context/State 
-.XE
-.LP
-Most attributes of graphics operations are stored in GCs.
-These include line width, line style, plane mask, foreground, background,
-tile, stipple, clipping region, end style, join style, and so on.
-Graphics operations (for example, drawing lines) use these values
-to determine the actual drawing operation.
-Extensions to X may add additional components to GCs.
-The contents of a GC are private to Xlib.
-.LP
-Xlib implements a write-back cache for all elements of a GC that are not
-resource IDs to allow Xlib to implement the transparent coalescing of changes 
-to GCs.
-For example,
-a call to
-.PN XSetForeground
-of a GC followed by a call to
-.PN XSetLineAttributes
-results in only a single-change GC protocol request to the server.
-GCs are neither expected nor encouraged to be shared between client 
-applications, so this write-back caching should present no problems.
-Applications cannot share GCs without external synchronization.
-Therefore,
-sharing GCs between applications is highly discouraged. 
-.LP
-To set an attribute of a GC,
-set the appropriate member of the
-.PN XGCValues
-structure and OR in the corresponding value bitmask in your subsequent calls to
-.PN XCreateGC .
-The symbols for the value mask bits and the
-.PN XGCValues
-structure are:
-.sM
-.LP
-/* GC attribute value mask bits */
-.TS
-lw(.5i) lw(2.5i) lw(.75i).
-#define\
-	T{
-.PN GCFunction
-T}	T{
-(1L<<0)
-T}
-#define\
-	T{
-.PN GCPlaneMask
-T}	T{
-(1L<<1)
-T}
-#define\
-	T{
-.PN GCForeground
-T}	T{
-(1L<<2)
-T}
-#define\
-	T{
-.PN GCBackground
-T}	T{
-(1L<<3)
-T}
-#define\
-	T{
-.PN GCLineWidth
-T}	T{
-(1L<<4)
-T}
-#define\
-	T{
-.PN GCLineStyle
-T}	T{
-(1L<<5)
-T}
-#define\
-	T{
-.PN GCCapStyle
-T}	T{
-(1L<<6)
-T}
-#define\
-	T{
-.PN GCJoinStyle
-T}	T{
-(1L<<7)
-T}
-#define\
-	T{
-.PN GCFillStyle
-T}	T{
-(1L<<8)
-T}
-#define\
-	T{
-.PN GCFillRule
-T}	T{
-(1L<<9)
-T}
-#define\
-	T{
-.PN GCTile
-T}	T{
-(1L<<10)
-T}
-#define\
-	T{
-.PN GCStipple
-T}	T{
-(1L<<11)
-T}
-#define\
-	T{
-.PN GCTileStipXOrigin
-T}	T{
-(1L<<12)
-T}
-#define\
-	T{
-.PN GCTileStipYOrigin
-T}	T{
-(1L<<13)
-T}
-#define\
-	T{
-.PN GCFont
-T}	T{
-(1L<<14)
-T}
-#define\
-	T{
-.PN GCSubwindowMode
-T}	T{
-(1L<<15)
-T}
-#define\
-	T{
-.PN GCGraphicsExposures
-T}	T{
-(1L<<16)
-T}
-#define\
-	T{
-.PN GCClipXOrigin
-T}	T{
-(1L<<17)
-T}
-#define\
-	T{
-.PN GCClipYOrigin
-T}	T{
-(1L<<18)
-T}
-#define\
-	T{
-.PN GCClipMask
-T}	T{
-(1L<<19)
-T}
-#define\
-	T{
-.PN GCDashOffset
-T}	T{
-(1L<<20)
-T}
-#define\
-	T{
-.PN GCDashList
-T}	T{
-(1L<<21)
-T}
-#define\
-	T{
-.PN GCArcMode
-T}	T{
-(1L<<22)
-T}
-.TE
-.IN "XGCValues" "" "@DEF@"
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-/* Values */
-
-typedef struct {
-	int function;	/* logical operation */
-	unsigned long plane_mask;	/* plane mask */
-	unsigned long foreground;	/* foreground pixel */
-	unsigned long background;	/* background pixel */
-	int line_width;	/* line width (in pixels) */
-	int line_style;	/* LineSolid, LineOnOffDash, LineDoubleDash */
-	int cap_style;	/* CapNotLast, CapButt, CapRound, CapProjecting */
-	int join_style;	/* JoinMiter, JoinRound, JoinBevel */
-	int fill_style;	/* FillSolid, FillTiled, FillStippled FillOpaqueStippled*/
-	int fill_rule;	/* EvenOddRule, WindingRule */
-	int arc_mode;	/* ArcChord, ArcPieSlice */
-	Pixmap tile;	/* tile pixmap for tiling operations */
-	Pixmap stipple;	/* stipple 1 plane pixmap for stippling */
-	int ts_x_origin;	/* offset for tile or stipple operations */
-	int ts_y_origin;
-	Font font;	/* default text font for text operations */
-	int subwindow_mode;	/* ClipByChildren, IncludeInferiors */
-	Bool graphics_exposures;	/* boolean, should exposures be generated */
-	int clip_x_origin;	/* origin for clipping */
-	int clip_y_origin;
-	Pixmap clip_mask;	/* bitmap clipping; other calls for rects */
-	int dash_offset;	/* patterned/dashed line information */
-	char dashes;
-} XGCValues;
-.De
-.LP
-.eM 
-The default GC values are:
-.TS H
-l l.
-_
-.sp 6p
-.B
-Component	Default
-.sp 6p
-_
-.sp 6p
-.TH
-.R
-T{
-function
-T}	T{
-.PN GXcopy
-T}
-plane_mask	All ones
-foreground	0
-background	1
-line_width	0
-T{
-line_style
-T}	T{
-.PN LineSolid
-T}
-T{
-cap_style
-T}	T{
-.PN CapButt
-T}
-T{
-join_style
-T}	T{
-.PN JoinMiter
-T}
-T{
-fill_style
-T}	T{
-.PN FillSolid
-T}
-T{
-fill_rule
-T}	T{
-.PN EvenOddRule
-T}
-T{
-arc_mode
-T}	T{
-.PN ArcPieSlice
-T}
-tile	Pixmap of unspecified size filled with foreground pixel
-	(that is, client specified pixel if any, else 0)
-	(subsequent changes to foreground do not affect this pixmap)
-stipple	Pixmap of unspecified size filled with ones
-ts_x_origin	0
-ts_y_origin	0
-font	<implementation dependent>
-T{
-subwindow_mode
-T}	T{
-.PN ClipByChildren
-T}
-T{
-graphics_exposures
-T}	T{
-.PN True
-T}
-clip_x_origin	0
-clip_y_origin	0
-T{
-clip_mask
-T}	T{
-.PN None
-T}
-dash_offset	0
-dashes	4 (that is, the list [4, 4])
-.sp 6p
-_
-.TE
-.LP
-Note that foreground and background are not set to any values likely
-to be useful in a window.
-.LP
-.IN "Display Functions" "" "@DEF@"
-.IN "Source" "" "@DEF@"
-.IN "Destination" "" "@DEF@"
-The function attributes of a GC are used when you update a section of
-a drawable (the destination) with bits from somewhere else (the source).  
-The function in a GC defines how the new destination bits are to be
-computed from the source bits and the old destination bits.
-.PN GXcopy
-is typically the most useful because it will work on a color display,
-but special applications may use other functions,
-particularly in concert with particular planes of a color display.
-The 16 GC functions, defined in 
-.hN X11/X.h ,
-are:
-.\" are listed in Table 5-1 along with the 
-.\"the associated hexadecimal code
-.\" and operation.
-.\".CP T 1
-.\"Display Functions
-.TS H
-lw(1.5i) cw(.5i) lw(2i).
-_
-.sp 6p
-.B
-Function Name	Value	Operation
-.sp 6p
-_
-.sp 6p
-.TH
-T{
-.PN GXclear
-T}	T{
-0x0
-T}	T{
-0
-T}
-T{
-.PN GXand
-T}	T{
-0x1
-T}	T{
-src AND dst
-T}
-T{
-.PN GXandReverse
-T}	T{
-0x2
-T}	T{
-src AND NOT dst
-T}
-T{
-.PN GXcopy
-T}	T{
-0x3
-T}	T{
-src
-T}
-T{
-.PN GXandInverted
-T}	T{
-0x4
-T}	T{
-(NOT src) AND dst
-T}
-T{
-.PN GXnoop
-T}	T{
-0x5
-T}	T{
-dst
-T}
-T{
-.PN GXxor
-T}	T{
-0x6
-T}	T{
-src XOR dst
-T}
-T{
-.PN GXor
-T}	T{
-0x7
-T}	T{
-src OR dst
-T}
-T{
-.PN GXnor
-T}	T{
-0x8
-T}	T{
-(NOT src) AND (NOT dst)
-T}
-T{
-.PN GXequiv
-T}	T{
-0x9
-T}	T{
-(NOT src) XOR dst
-T}
-T{
-.PN GXinvert
-T}	T{
-0xa
-T}	T{
-NOT dst
-T}
-T{
-.PN GXorReverse
-T}	T{
-0xb
-T}	T{
-src OR (NOT dst)
-T}
-T{
-.PN GXcopyInverted
-T}	T{
-0xc
-T}	T{
-NOT src
-T}
-T{
-.PN GXorInverted
-T}	T{
-0xd
-T}	T{
-(NOT src) OR dst
-T}
-T{
-.PN GXnand
-T}	T{
-0xe
-T}	T{
-(NOT src) OR (NOT dst)
-T}
-T{
-.PN GXset
-T}	T{
-0xf
-T}	T{
-1
-T}
-.sp 6p
-_
-.TE
-.LP
-Many graphics operations depend on either pixel values or planes in a GC.
-.IN "Pixel value"
-The planes attribute is of type long, and it specifies which planes of the
-destination are to be modified, one bit per plane.
-.IN "Plane" "mask"
-A monochrome display has only one plane and
-will be the least significant bit of the word.
-As planes are added to the display hardware, they will occupy more
-significant bits in the plane mask.
-.LP
-In graphics operations, given a source and destination pixel, 
-the result is computed bitwise on corresponding bits of the pixels.
-That is, a Boolean operation is performed in each bit plane.  
-The plane_mask restricts the operation to a subset of planes.
-A macro constant
-.PN AllPlanes
-can be used to refer to all planes of the screen simultaneously.
-The result is computed by the following:
-.LP
-.Ds 
-((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask))
-.De
-.LP
-Range checking is not performed on the values for foreground,
-background, or plane_mask.
-They are simply truncated to the appropriate
-number of bits.
-The line-width is measured in pixels and either can be greater than or equal to
-one (wide line) or can be the special value zero (thin line).
-.LP
-Wide lines are drawn centered on the path described by the graphics request.
-Unless otherwise specified by the join-style or cap-style,
-the bounding box of a wide line with endpoints [x1, y1], [x2, y2] and
-width w is a rectangle with vertices at the following real coordinates:
-.LP
-.Ds
-.TA .5i 2.5i
-.ta .5i 2.5i
-[x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)],
-[x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)]
-.De
-.LP
-Here sn is the sine of the angle of the line,
-and cs is the cosine of the angle of the line.
-A pixel is part of the line and so is drawn
-if the center of the pixel is fully inside the bounding box
-(which is viewed as having infinitely thin edges).
-If the center of the pixel is exactly on the bounding box,
-it is part of the line if and only if the interior is immediately to its right
-(x increasing direction).
-Pixels with centers on a horizontal edge are a special case and are part of
-the line if and only if the interior or the boundary is immediately below 
-(y increasing direction) and the interior or the boundary is immediately
-to the right (x increasing direction).
-.LP
-Thin lines (zero line-width) are one-pixel-wide lines drawn using an
-unspecified, device-dependent algorithm.
-There are only two constraints on this algorithm. 
-.IP 1. 5
-If a line is drawn unclipped from [x1,y1] to [x2,y2] and
-if another line is drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy],
-a point [x,y] is touched by drawing the first line 
-if and only if the point [x+dx,y+dy] is touched by drawing the second line.
-.IP 2. 5
-The effective set of points comprising a line cannot be affected by clipping.
-That is, a point is touched in a clipped line if and only if the point 
-lies inside the clipping region and the point would be touched
-by the line when drawn unclipped.
-.LP
-A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels 
-as a wide line drawn from [x2,y2] to [x1,y1], not counting cap-style 
-and join-style.
-It is recommended that this property be true for thin lines, 
-but this is not required.
-A line-width of zero may differ from a line-width of one in which pixels are
-drawn.
-This permits the use of many manufacturers' line drawing hardware,
-which may run many times faster than the more precisely specified
-wide lines.
-.LP
-In general, 
-drawing a thin line will be faster than drawing a wide line of width one.
-However, because of their different drawing algorithms,
-thin lines may not mix well aesthetically with wide lines.
-If it is desirable to obtain precise and uniform results across all displays,
-a client should always use a line-width of one rather than a line-width of zero.
-.LP
-The line-style defines which sections of a line are drawn:
-.TS
-lw(1.3i) lw(4.5i).
-T{
-.PN LineSolid
-T}	T{
-The full path of the line is drawn.
-T}
-.sp 6p
-T{
-.PN LineDoubleDash
-T}	T{
-The full path of the line is drawn, 
-but the even dashes are filled differently 
-from the odd dashes (see fill-style) with
-.PN CapButt 
-style used where even and odd dashes meet.
-T}
-.sp 6p
-T{
-.PN LineOnOffDash
-T}	T{
-Only the even dashes are drawn,
-and cap-style applies to 
-all internal ends of the individual dashes,
-except 
-.PN CapNotLast
-is treated as 
-.PN CapButt . 
-T}
-.TE
-.LP
-The cap-style defines how the endpoints of a path are drawn:
-.IN "Graphics context" "path"
-.TS
-lw(1.3i) lw(4.5i).
-T{
-.PN CapNotLast
-T}	T{
-This is equivalent to 
-.PN CapButt  
-except that for a line-width of zero the final endpoint is not drawn.
-T}
-.sp 6p
-T{
-.PN CapButt
-T}	T{
-The line is square at the endpoint (perpendicular to the slope of the line)
-with no projection beyond.
-T}
-.sp 6p
-T{
-.PN CapRound
-T}	T{
-The line has a circular arc with the diameter equal to the line-width,
-centered on the endpoint.
-(This is equivalent to 
-.PN CapButt 
-for line-width of zero).
-T}
-.sp 6p
-T{
-.PN CapProjecting
-T}	T{
-The line is square at the end, but the path continues beyond the endpoint 
-for a distance equal to half the line-width.
-(This is equivalent to 
-.PN CapButt 
-for line-width of zero).
-T}
-.TE
-.LP
-The join-style defines how corners are drawn for wide lines:
-.TS
-lw(1.3i) lw(4.5i).
-T{
-.PN JoinMiter
-T}	T{
-The outer edges of two lines extend to meet at an angle.
-However, if the angle is less than 11 degrees,
-then a
-.PN JoinBevel
-join-style is used instead.
-T}
-.sp 6p
-T{
-.PN JoinRound
-T}	T{
-The corner is a circular arc with the diameter equal to the line-width, 
-centered on the joinpoint.
-T}
-.sp 6p
-T{
-.PN JoinBevel
-T}	T{
-The corner has
-.PN CapButt 
-endpoint styles with the triangular notch filled.
-T}
-.TE
-.LP
-For a line with coincident endpoints (x1=x2, y1=y2), 
-when the cap-style is applied to both endpoints, 
-the semantics depends on the line-width and the cap-style:
-.TS
-lw(1.3i) lw(.5i) lw(4i).
-T{
-.PN CapNotLast
-T}	T{
-thin
-T}	T{
-The results are device dependent, 
-but the desired effect is that nothing is drawn.
-T}
-.sp 6p
-T{
-.PN CapButt
-T}	T{
-thin
-T}	T{
-The results are device dependent, 
-but the desired effect is that a single pixel is drawn.
-T}
-.sp 6p
-T{
-.PN CapRound
-T}	T{
-thin
-T}	T{
-The results are the same as for
-.PN CapButt /thin.
-T}
-.sp 6p
-T{
-.PN CapProjecting
-T}	T{
-thin
-T}	T{
-The results are the same as for
-.PN CapButt /thin.
-T}
-.sp 6p
-T{
-.PN CapButt
-T}	T{
-wide
-T}	T{
-Nothing is drawn.
-T}
-.sp 6p
-T{
-.PN CapRound
-T}	T{
-wide
-T}	T{
-The closed path is a circle, centered at the endpoint, and
-with the diameter equal to the line-width.
-T}
-.sp 6p
-T{
-.PN CapProjecting
-T}	T{
-wide
-T}	T{
-The closed path is a square, aligned with the coordinate axes, centered at the
-endpoint, and with the sides equal to the line-width.
-T}
-.TE
-.LP
-For a line with coincident endpoints (x1=x2, y1=y2), 
-when the join-style is applied at one or both endpoints, 
-the effect is as if the line was removed from the overall path.
-However, if the total path consists of or is reduced to a single point joined
-with itself, the effect is the same as when the cap-style is applied at both
-endpoints.
-.LP
-The tile/stipple represents an infinite two-dimensional plane,
-with the tile/stipple replicated in all dimensions.
-When that plane is superimposed on the drawable
-for use in a graphics operation, the upper-left corner
-of some instance of the tile/stipple is at the coordinates within
-the drawable specified by the tile/stipple origin.
-The tile/stipple and clip origins are interpreted relative to the
-origin of whatever destination drawable is specified in a graphics
-request.
-The tile pixmap must have the same root and depth as the GC,
-or a
-.PN BadMatch 
-error results.
-The stipple pixmap must have depth one and must have the same root as the
-GC, or a 
-.PN BadMatch 
-error results.  
-For stipple operations where the fill-style is
-.PN FillStippled
-but not 
-.PN FillOpaqueStippled ,
-the stipple pattern is tiled in a
-single plane and acts as an additional clip mask to be ANDed with the clip-mask.
-Although some sizes may be faster to use than others,
-any size pixmap can be used for tiling or stippling.
-.LP
-The fill-style defines the contents of the source for line, text, and
-fill requests.  
-For all text and fill requests (for example,
-.PN XDrawText , 
-.PN XDrawText16 ,
-.PN XFillRectangle , 
-.PN XFillPolygon , 
-and
-.PN XFillArc );
-for line requests 
-with line-style 
-.PN LineSolid 
-(for example,
-.PN XDrawLine ,
-.PN XDrawSegments , 
-.PN XDrawRectangle ,
-.PN XDrawArc );
-and for the even dashes for line requests with line-style 
-.PN LineOnOffDash 
-or 
-.PN LineDoubleDash ,
-the following apply:
-.TS
-lw(1.8i) lw(4i).
-T{
-.PN FillSolid
-T}	T{
-Foreground
-T}
-.sp 6p
-T{
-.PN FillTiled
-T}	T{
-Tile
-T}
-.sp 6p
-T{
-.PN FillOpaqueStippled
-T}	T{
-A tile with the same width and height as stipple,
-but with background everywhere stipple has a zero
-and with foreground everywhere stipple has a one
-T}
-.sp 6p
-T{
-.PN FillStippled
-T}	T{
-Foreground masked by stipple
-T}
-.TE
-.LP
-When drawing lines with line-style
-.PN LineDoubleDash ,
-the odd dashes are controlled by the fill-style in the following manner:
-.TS
-lw(1.8i) lw(4i).
-T{
-.PN FillSolid
-T}	T{
-Background
-T}
-.sp 6p
-T{
-.PN FillTiled
-T}	T{
-Same as for even dashes
-T}
-.sp 6p
-T{
-.PN FillOpaqueStippled
-T}	T{
-Same as for even dashes
-T}
-.sp 6p
-T{
-.PN FillStippled
-T}	T{
-Background masked by stipple
-T}
-.TE
-.LP
-Storing a pixmap in a GC might or might not result in a copy
-being made.
-If the pixmap is later used as the destination for a graphics request,
-the change might or might not be reflected in the GC.
-If the pixmap is used simultaneously in a graphics request both as
-a destination and as a tile or stipple,
-the results are undefined.
-.LP
-For optimum performance,
-you should draw as much as possible with the same GC 
-(without changing its components).
-The costs of changing GC components relative to using different GCs
-depend on the display hardware and the server implementation.
-It is quite likely that some amount of GC information will be
-cached in display hardware and that such hardware can only cache a small number
-of GCs.
-.LP
-The dashes value is actually a simplified form of the
-more general patterns that can be set with 
-.PN XSetDashes .  
-Specifying a
-value of N is equivalent to specifying the two-element list [N, N] in 
-.PN XSetDashes . 
-The value must be nonzero,
-or a
-.PN BadValue
-error results.
-.LP
-The clip-mask restricts writes to the destination drawable.  
-If the clip-mask is set to a pixmap,
-it must have depth one and have the same root as the GC,
-or a
-.PN BadMatch 
-error results.
-If clip-mask is set to
-.PN None ,
-the pixels are always drawn regardless of the clip origin.
-The clip-mask also can be set by calling the
-.PN XSetClipRectangles
-or
-.PN XSetRegion
-functions.
-Only pixels where the clip-mask has a bit set to 1 are drawn.  
-Pixels are not drawn outside the area covered by the clip-mask 
-or where the clip-mask has a bit set to 0.
-The clip-mask affects all graphics requests.
-The clip-mask does not clip sources.
-The clip-mask origin is interpreted relative to the origin of whatever
-destination drawable is specified in a graphics request.
-.LP
-You can set the subwindow-mode to
-.PN ClipByChildren
-or
-.PN IncludeInferiors .
-For 
-.PN ClipByChildren , 
-both source and destination windows are
-additionally clipped by all viewable 
-.PN InputOutput
-children.  
-For 
-.PN IncludeInferiors ,
-neither source nor destination window is clipped by inferiors. 
-This will result in including subwindow contents in the source
-and drawing through subwindow boundaries of the destination.
-The use of 
-.PN IncludeInferiors 
-on a window of one depth with mapped
-inferiors of differing depth is not illegal, but the semantics are
-undefined by the core protocol.
-.LP
-The fill-rule defines what pixels are inside (drawn) for
-paths given in 
-.PN XFillPolygon 
-requests and can be set to 
-.PN EvenOddRule 
-or
-.PN WindingRule .
-For
-.PN EvenOddRule ,
-a point is inside if
-an infinite ray with the point as origin crosses the path an odd number
-of times.  
-For 
-.PN WindingRule , 
-a point is inside if an infinite ray with the
-point as origin crosses an unequal number of clockwise and
-counterclockwise directed path segments.
-A clockwise directed path segment is one that crosses the ray from left to
-right as observed from the point.
-A counterclockwise segment is one that crosses the ray from right to left
-as observed from the point.
-The case where a directed line segment is coincident with the ray is
-uninteresting because you can simply choose a different ray that is not
-coincident with a segment.
-.LP
-For both 
-.PN EvenOddRule
-and
-.PN WindingRule ,
-a point is infinitely small, 
-and the path is an infinitely thin line.  
-A pixel is inside if the center point of the pixel is inside
-and the center point is not on the boundary.  
-If the center point is on the boundary,
-the pixel is inside if and only if the polygon interior is immediately to
-its right (x increasing direction).  
-Pixels with centers on a horizontal edge are a special case 
-and are inside if and only if the polygon interior is immediately below 
-(y increasing direction).
-.LP
-The arc-mode controls filling in the 
-.PN XFillArcs
-function and can be set to
-.PN ArcPieSlice
-or
-.PN ArcChord .
-For
-.PN ArcPieSlice ,
-the arcs are pie-slice filled.
-For
-.PN ArcChord ,
-the arcs are chord filled.
-.LP
-The graphics-exposure flag controls 
-.PN GraphicsExpose 
-event generation
-for 
-.PN XCopyArea 
-and 
-.PN XCopyPlane
-requests (and any similar requests defined by extensions).
-.LP
-.sp
-To create a new GC that is usable on a given screen with a 
-depth of drawable, use
-.PN XCreateGC .
-.IN "Graphics context" "initializing"
-.IN "XCreateGC" "" "@DEF@"
-.sM
-.FD 0
-GC XCreateGC\^(\^\fIdisplay\fP, \fId\fP\^, \fIvaluemask\fP\^, \fIvalues\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      unsigned long \fIvaluemask\fP\^;
-.br
-      XGCValues *\^\fIvalues\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.ds Vm set using the information in the specified values structure
-.IP \fIvaluemask\fP 1i
-Specifies which components in the GC are to be \*(Vm. 
-This argument is the bitwise inclusive OR of zero or more of the valid
-GC component mask bits.
-.IP \fIvalues\fP 1i
-Specifies any values as specified by the valuemask.
-.LP
-.eM
-The
-.PN XCreateGC
-function creates a graphics context and returns a GC.
-The GC can be used with any destination drawable having the same root
-and depth as the specified drawable.
-Use with other drawables results in a
-.PN BadMatch
-error.
-.LP
-.PN XCreateGC
-can generate
-.PN BadAlloc ,
-.PN BadDrawable ,
-.PN BadFont ,
-.PN BadMatch ,
-.PN BadPixmap ,
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-To copy components from a source GC to a destination GC, use
-.PN XCopyGC .
-.IN "XCopyGC" "" "@DEF@"
-.sM
-.FD 0
-XCopyGC\^(\^\fIdisplay\fP, \fIsrc\fP\^, \fIvaluemask\fP\^, \fIdest\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIsrc\fP\^, \fIdest\fP\^;
-.br
-      unsigned long \fIvaluemask\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIsrc\fP 1i
-Specifies the components of the source GC.
-.ds Vm copied to the destination GC
-.IP \fIvaluemask\fP 1i
-Specifies which components in the GC are to be \*(Vm. 
-This argument is the bitwise inclusive OR of zero or more of the valid
-GC component mask bits.
-.IP \fIdest\fP 1i
-Specifies the destination GC.
-.LP
-.eM 
-The
-.PN XCopyGC
-function copies the specified components from the source GC
-to the destination GC.
-The source and destination GCs must have the same root and depth,
-or a
-.PN BadMatch
-error results.
-The valuemask specifies which component to copy, as for
-.PN XCreateGC .
-.LP
-.PN XCopyGC
-can generate
-.PN BadAlloc , 
-.PN BadGC ,
-and
-.PN BadMatch
-errors.
-.LP
-.sp
-To change the components in a given GC, use
-.PN XChangeGC .
-.IN "XChangeGC" "" "@DEF@"
-.sM
-.FD 0
-XChangeGC\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIvaluemask\fP\^, \fIvalues\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      unsigned long \fIvaluemask\fP\^;
-.br
-      XGCValues *\^\fIvalues\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.ds Vm changed using information in the specified values structure
-.IP \fIvaluemask\fP 1i
-Specifies which components in the GC are to be \*(Vm. 
-This argument is the bitwise inclusive OR of zero or more of the valid
-GC component mask bits.
-.IP \fIvalues\fP 1i
-Specifies any values as specified by the valuemask.
-.LP
-.eM
-The
-.PN XChangeGC
-function changes the components specified by valuemask for
-the specified GC.
-The values argument contains the values to be set.
-The values and restrictions are the same as for 
-.PN XCreateGC .
-Changing the clip-mask overrides any previous 
-.PN XSetClipRectangles
-request on the context. 
-Changing the dash-offset or dash-list
-overrides any previous 
-.PN XSetDashes
-request on the context.
-The order in which components are verified and altered is server dependent.
-If an error is generated, a subset of the components may have been altered.
-.LP
-.PN XChangeGC
-can generate
-.PN BadAlloc ,
-.PN BadFont ,
-.PN BadGC ,
-.PN BadMatch ,
-.PN BadPixmap ,
-and
-.PN BadValue
-errors.
-.LP
-.sp
-To obtain components of a given GC, use
-.PN XGetGCValues .
-.IN "XGetGCValues" "" "@DEF@"
-.sM
-.FD 0
-Status XGetGCValues\^(\^\fIdisplay\fP, \fIgc\fP, \fIvaluemask\fP, \
-\fIvalues_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      unsigned long \fIvaluemask\fP\^;
-.br
-      XGCValues *\fIvalues_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.ds Vm returned in the values_return argument
-.IP \fIvaluemask\fP 1i
-Specifies which components in the GC are to be \*(Vm. 
-This argument is the bitwise inclusive OR of zero or more of the valid
-GC component mask bits.
-.IP \fIvalues_return\fP 1i
-Returns the GC values in the specified
-.PN XGCValues 
-structure.
-.LP
-.eM
-The
-.PN XGetGCValues
-function returns the components specified by valuemask for the specified GC.
-If the valuemask contains a valid set of GC mask bits
-.Pn ( GCFunction ,
-.PN GCPlaneMask ,
-.PN GCForeground ,
-.PN GCBackground ,
-.PN GCLineWidth ,
-.PN GCLineStyle ,
-.PN GCCapStyle ,
-.PN GCJoinStyle ,
-.PN GCFillStyle ,
-.PN GCFillRule ,
-.PN GCTile ,
-.PN GCStipple ,
-.PN GCTileStipXOrigin ,
-.PN GCTileStipYOrigin ,
-.PN GCFont ,
-.PN GCSubwindowMode ,
-.PN GCGraphicsExposures ,
-.PN GCClipXOrigin ,
-.PN GCCLipYOrigin ,
-.PN GCDashOffset ,
-or
-.PN GCArcMode )
-and no error occurs,
-.PN XGetGCValues
-sets the requested components in values_return and returns a nonzero status.
-Otherwise, it returns a zero status.
-Note that the clip-mask and dash-list (represented by the
-.PN GCClipMask
-and 
-.PN GCDashList
-bits, respectively, in the valuemask)
-cannot be requested.
-Also note that an invalid resource ID (with one or more of the three
-most significant bits set to 1) will be returned for
-.PN GCFont ,
-.PN GCTile ,
-and
-.PN GCStipple
-if the component has never been explicitly set by the client.
-.LP
-.sp
-To free a given GC, use
-.PN XFreeGC .
-.IN "XFreeGC" "" "@DEF@"
-.sM
-.FD 0
-XFreeGC\^(\^\fIdisplay\fP, \fIgc\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.LP
-.eM
-The
-.PN XFreeGC
-function destroys the specified GC as well as all the associated storage.
-.LP
-.PN XFreeGC
-can generate a
-.PN BadGC 
-error.
-.LP
-.sp
-To obtain the 
-.PN GContext 
-resource ID for a given GC, use 
-.PN XGContextFromGC .
-.IN "XGContextFromGC" "" "@DEF@"
-.sM
-.FD 0
-GContext XGContextFromGC\^(\^\fIgc\fP\^)
-.br
-      GC \fIgc\fP\^;
-.FN
-.ds Gc for which you want the resource ID
-.IP \fIgc\fP 1i
-Specifies the GC \*(Gc.
-.LP
-.eM
-.sp
-Xlib usually defers sending changes to the components of a GC to the server
-until a graphics function is actually called with that GC.
-This permits batching of component changes into a single server request.
-In some circumstances, however, it may be necessary for the client
-to explicitly force sending the changes to the server.
-An example might be when a protocol extension uses the GC indirectly,
-in such a way that the extension interface cannot know what GC will be used.
-To force sending GC component changes, use
-.PN XFlushGC .
-.IN "XFlushGC" "" "@DEF@"
-.sM
-.FD 0
-void XFlushGC\^(\^\fIdisplay\fP, \fIgc\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.LP
-.eM
-.NH 2
-Using Graphics Context Convenience Routines
-.XS
-\*(SN Using Graphics Context Convenience Routines 
-.XE
-.LP
-This section discusses how to set the:
-.IP \(bu 5
-Foreground, background, plane mask, or function components
-.IP \(bu 5
-Line attributes and dashes components
-.IP \(bu 5
-Fill style and fill rule components
-.IP \(bu 5
-Fill tile and stipple components
-.IP \(bu 5
-Font component
-.IP \(bu 5
-Clip region component
-.IP \(bu 5
-Arc mode, subwindow mode, and graphics exposure components
-.NH 3
-Setting the Foreground, Background, Function, or Plane Mask
-.XS
-\*(SN Setting the Foreground, Background, Function, or Plane Mask
-.XE
-.LP
-To set the foreground, background, plane mask, and function components
-for a given GC, use
-.PN XSetState .
-.IN "XSetState" "" "@DEF@"
-.sM
-.FD 0
-XSetState\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIforeground\fP\^, \fIbackground\fP\^, \fIfunction\fP\^, \fIplane_mask\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      unsigned long \fIforeground\fP\^, \fIbackground\fP\^;
-.br
-      int \fIfunction\fP\^;
-.br
-      unsigned long \fIplane_mask\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIforeground\fP 1i
-Specifies the foreground you want to set for the specified GC.
-.IP \fIbackground\fP 1i
-Specifies the background you want to set for the specified GC.
-.IP \fIfunction\fP 1i
-Specifies the function you want to set for the specified GC.
-.IP \fIplane_mask\fP 1i
-Specifies the plane mask.
-.\" *** JIM: NEED MORE INFO FOR THIS. ***
-.LP
-.eM
-.PN XSetState
-can generate
-.PN BadAlloc ,
-.PN BadGC ,
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-To set the foreground of a given GC, use
-.PN XSetForeground .
-.IN "XSetForeground" "" "@DEF@"
-.sM
-.FD 0
-XSetForeground\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIforeground\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      unsigned long \fIforeground\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIforeground\fP 1i
-Specifies the foreground you want to set for the specified GC.
-.LP
-.eM
-.PN XSetForeground
-can generate
-.PN BadAlloc
-and
-.PN BadGC 
-errors.
-.LP
-.sp
-To set the background of a given GC, use
-.PN XSetBackground .
-.IN "XSetBackground" "" "@DEF@"
-.sM
-.FD 0
-XSetBackground\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIbackground\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      unsigned long \fIbackground\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIbackground\fP 1i
-Specifies the background you want to set for the specified GC.
-.LP
-.eM
-.PN XSetBackground
-can generate
-.PN BadAlloc
-and
-.PN BadGC 
-errors.
-.LP
-.sp
-To set the display function in a given GC, use
-.PN XSetFunction .
-.IN "XSetFunction" "" "@DEF@"
-.sM
-.FD 0
-XSetFunction\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfunction\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIfunction\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIfunction\fP 1i
-Specifies the function you want to set for the specified GC.
-.LP
-.eM
-.PN XSetFunction
-can generate
-.PN BadAlloc ,
-.PN BadGC ,
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-To set the plane mask of a given GC, use
-.PN XSetPlaneMask .
-.IN "XSetPlaneMask" "" "@DEF@"
-.sM
-.FD 0
-XSetPlaneMask\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIplane_mask\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      unsigned long \fIplane_mask\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIplane_mask\fP 1i
-Specifies the plane mask.
-.\" *** JIM: NEED MORE INFO FOR THIS. ***
-.LP
-.eM
-.PN XSetPlaneMask
-can generate
-.PN BadAlloc
-and
-.PN BadGC 
-errors.
-.NH 3
-Setting the Line Attributes and Dashes
-.XS
-\*(SN Setting the Line Attributes and Dashes 
-.XE
-.LP
-To set the line drawing components of a given GC, use
-.PN XSetLineAttributes .
-.IN "XSetLineAttributes" "" "@DEF@"
-.sM
-.FD 0
-XSetLineAttributes\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIline_width\fP\^, \fIline_style\fP\^, \fIcap_style\fP\^, \fIjoin_style\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      unsigned int \fIline_width\fP\^;
-.br
-      int \fIline_style\fP\^;
-.br
-      int \fIcap_style\fP\^;
-.br
-      int \fIjoin_style\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIline_width\fP 1i
-Specifies the line-width you want to set for the specified GC.
-.IP \fIline_style\fP 1i
-Specifies the line-style you want to set for the specified GC.
-You can pass
-.PN LineSolid ,
-.PN LineOnOffDash ,
-or
-.PN LineDoubleDash .
-.IP \fIcap_style\fP 1i
-Specifies the line-style and cap-style you want to set for the specified GC.
-You can pass
-.PN CapNotLast ,
-.PN CapButt ,
-.PN CapRound ,
-or
-.PN CapProjecting .
-.IP \fIjoin_style\fP 1i
-Specifies the line join-style you want to set for the specified GC.
-You can pass
-.PN JoinMiter ,
-.PN JoinRound ,
-or
-.PN JoinBevel .
-.LP
-.eM
-.PN XSetLineAttributes
-can generate
-.PN BadAlloc ,
-.PN BadGC ,
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-To set the dash-offset and dash-list for dashed line styles of a given GC, use
-.PN XSetDashes .
-.IN "XSetDashes" "" "@DEF@"
-.sM
-.FD 0
-XSetDashes\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIdash_offset\fP\^, \fIdash_list\fP\^, \fIn\fP\^)
-.br
-        Display *\fIdisplay\fP\^;
-.br
-        GC \fIgc\fP\^;
-.br
-        int \fIdash_offset\fP\^;
-.br
-        char \fIdash_list\fP[]\^;
-.br
-        int \fIn\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIdash_offset\fP 1i
-Specifies the phase of the pattern for the dashed line-style you want to set
-for the specified GC. 
-.IP \fIdash_list\fP 1i
-Specifies the dash-list for the dashed line-style
-you want to set for the specified GC. 
-.IP \fIn\fP 1i
-Specifies the number of elements in dash_list. 
-.LP
-.eM 
-The
-.PN XSetDashes
-function sets the dash-offset and dash-list attributes for dashed line styles
-in the specified GC.
-There must be at least one element in the specified dash_list,
-or a
-.PN BadValue
-error results. 
-The initial and alternating elements (second, fourth, and so on) 
-of the dash_list are the even dashes, and
-the others are the odd dashes.
-Each element specifies a dash length in pixels.
-All of the elements must be nonzero,
-or a
-.PN BadValue
-error results.
-Specifying an odd-length list is equivalent to specifying the same list
-concatenated with itself to produce an even-length list.
-.LP
-The dash-offset defines the phase of the pattern,
-specifying how many pixels into the dash-list the pattern
-should actually begin in any single graphics request.
-Dashing is continuous through path elements combined with a join-style
-but is reset to the dash-offset between each sequence of joined lines.
-.LP
-The unit of measure for dashes is the same for the ordinary coordinate system.
-Ideally, a dash length is measured along the slope of the line, but implementations
-are only required to match this ideal for horizontal and vertical lines.
-Failing the ideal semantics, it is suggested that the length be measured along the
-major axis of the line.
-The major axis is defined as the x axis for lines drawn at an angle of between
-\-45 and +45 degrees or between 135 and 225 degrees from the x axis.
-For all other lines, the major axis is the y axis.
-.LP
-.PN XSetDashes
-can generate
-.PN BadAlloc ,
-.PN BadGC ,
-and
-.PN BadValue 
-errors.
-.NH 3
-Setting the Fill Style and Fill Rule 
-.XS
-\*(SN Setting the Fill Style and Fill Rule 
-.XE
-.LP
-To set the fill-style of a given GC, use
-.PN XSetFillStyle .
-.IN "XSetFillStyle" "" "@DEF@"
-.sM
-.FD 0
-XSetFillStyle\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfill_style\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIfill_style\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIfill_style\fP 1i
-Specifies the fill-style you want to set for the specified GC.
-You can pass
-.PN FillSolid ,
-.PN FillTiled ,
-.PN FillStippled ,
-or
-.PN FillOpaqueStippled .
-.LP
-.eM
-.PN XSetFillStyle
-can generate
-.PN BadAlloc ,
-.PN BadGC ,
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-To set the fill-rule of a given GC, use
-.PN XSetFillRule .
-.IN "XSetFillRule" "" "@DEF@"
-.sM
-.FD 0
-XSetFillRule\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfill_rule\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIfill_rule\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIfill_rule\fP 1i
-Specifies the fill-rule you want to set for the specified GC.
-You can pass 
-.PN EvenOddRule
-or
-.PN WindingRule .
-.LP
-.eM
-.PN XSetFillRule
-can generate
-.PN BadAlloc ,
-.PN BadGC ,
-and
-.PN BadValue 
-errors.
-.NH 3
-Setting the Fill Tile and Stipple 
-.XS
-\*(SN Setting the Fill Tile and Stipple 
-.XE
-.LP
-Some displays have hardware support for tiling or
-stippling with patterns of specific sizes.
-Tiling and stippling operations that restrict themselves to those specific
-sizes run much faster than such operations with arbitrary size patterns.
-Xlib provides functions that you can use to determine the best size, 
-tile, or stipple for the display
-as well as to set the tile or stipple shape and the tile or stipple origin.
-.LP
-.sp
-To obtain the best size of a tile, stipple, or cursor, use
-.PN XQueryBestSize .
-.IN "XQueryBestSize" "" "@DEF@"
-.sM
-.FD 0
-Status XQueryBestSize\^(\^\fIdisplay\fP, \fIclass\fP, \fIwhich_screen\fP, \fIwidth\fP, \fIheight\fP, \fIwidth_return\fP, \fIheight_return\fP\^) 
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIclass\fP\^;
-.br
-      Drawable \fIwhich_screen\fP\^;
-.br
-      unsigned int \fIwidth\fP, \fIheight\fP\^;
-.br
-      unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIclass\fP 1i
-Specifies the class that you are interested in.
-You can pass 
-.PN TileShape , 
-.PN CursorShape , 
-or 
-.PN StippleShape .
-.IP \fIwhich_screen\fP 1i
-Specifies any drawable on the screen.
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height.
-.IP \fIwidth_return\fP 1i
-.br
-.ns
-.IP \fIheight_return\fP 1i
-Return the width and height of the object best supported 
-by the display hardware.
-.LP
-.eM
-The
-.PN XQueryBestSize
-function returns the best or closest size to the specified size.
-For 
-.PN CursorShape ,
-this is the largest size that can be fully displayed on the screen specified by
-which_screen.
-For 
-.PN TileShape ,
-this is the size that can be tiled fastest.
-For 
-.PN StippleShape ,
-this is the size that can be stippled fastest.
-For 
-.PN CursorShape ,
-the drawable indicates the desired screen.
-For 
-.PN TileShape 
-and 
-.PN StippleShape ,
-the drawable indicates the screen and possibly the window class and depth.
-An 
-.PN InputOnly 
-window cannot be used as the drawable for 
-.PN TileShape
-or 
-.PN StippleShape ,
-or a
-.PN BadMatch 
-error results.
-.LP
-.PN XQueryBestSize
-can generate
-.PN BadDrawable ,
-.PN BadMatch ,
-and 
-.PN BadValue 
-errors.
-.LP
-.sp
-To obtain the best fill tile shape, use
-.PN XQueryBestTile .
-.IN "XQueryBestTile" "" "@DEF@"
-.sM
-.FD 0
-Status XQueryBestTile\^(\^\fIdisplay\fP, \fIwhich_screen\fP, \fIwidth\fP, \fIheight\fP, \fIwidth_return\fP, \fIheight_return\fP\^) 
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fIwhich_screen\fP\^;
-.br
-      unsigned int \fIwidth\fP, \fIheight\fP\^;
-.br
-      unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIwhich_screen\fP 1i
-Specifies any drawable on the screen.
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height.
-.IP \fIwidth_return\fP 1i
-.br
-.ns
-.IP \fIheight_return\fP 1i
-Return the width and height of the object best supported 
-by the display hardware.
-.LP
-.eM
-The
-.PN XQueryBestTile
-function returns the best or closest size, that is, the size that can be
-tiled fastest on the screen specified by which_screen.
-The drawable indicates the screen and possibly the window class and depth.
-If an 
-.PN InputOnly 
-window is used as the drawable, a 
-.PN BadMatch 
-error results.
-.LP
-.PN XQueryBestTile
-can generate
-.PN BadDrawable
-and
-.PN BadMatch 
-errors.
-.LP
-.sp
-To obtain the best stipple shape, use
-.PN XQueryBestStipple .
-.IN "XQueryBestStipple" "" "@DEF@"
-.sM
-.FD 0
-Status XQueryBestStipple\^(\^\fIdisplay\fP, \fIwhich_screen\fP, \fIwidth\fP, \fIheight\fP, \fIwidth_return\fP, \fIheight_return\fP\^) 
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fIwhich_screen\fP\^;
-.br
-      unsigned int \fIwidth\fP, \fIheight\fP\^;
-.br
-      unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIwhich_screen\fP 1i
-Specifies any drawable on the screen.
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height.
-.IP \fIwidth_return\fP 1i
-.br
-.ns
-.IP \fIheight_return\fP 1i
-Return the width and height of the object best supported 
-by the display hardware.
-.LP
-.eM
-The
-.PN XQueryBestStipple
-function returns the best or closest size, that is, the size that can be
-stippled fastest on the screen specified by which_screen.
-The drawable indicates the screen and possibly the window class and depth.
-If an
-.PN InputOnly
-window is used as the drawable, a
-.PN BadMatch
-error results.
-.LP
-.PN XQueryBestStipple
-can generate
-.PN BadDrawable
-and
-.PN BadMatch 
-errors.
-.LP
-.sp
-To set the fill tile of a given GC, use
-.PN XSetTile .
-.IN "XSetTile" "" "@DEF@"
-.sM
-.FD 0
-XSetTile\^(\^\fIdisplay\fP, \fIgc\fP\^, \fItile\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      Pixmap \fItile\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fItile\fP 1i
-Specifies the fill tile you want to set for the specified GC. 
-.LP
-.eM
-The tile and GC must have the same depth,
-or a
-.PN BadMatch
-error results.
-.LP
-.PN XSetTile
-can generate
-.PN BadAlloc ,
-.PN BadGC ,
-.PN BadMatch ,
-and
-.PN BadPixmap 
-errors.
-.LP
-.sp
-To set the stipple of a given GC, use
-.PN XSetStipple .
-.IN "XSetStipple" "" "@DEF@"
-.sM
-.FD 0
-XSetStipple\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIstipple\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      Pixmap \fIstipple\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIstipple\fP 1i
-Specifies the stipple you want to set for the specified GC.
-.LP
-.eM
-The stipple must have a depth of one,
-or a
-.PN BadMatch
-error results.
-.LP
-.PN XSetStipple
-can generate
-.PN BadAlloc ,
-.PN BadGC ,
-.PN BadMatch ,
-and
-.PN BadPixmap 
-errors.
-.LP
-.sp
-To set the tile or stipple origin of a given GC, use
-.PN XSetTSOrigin .
-.IN "XSetTSOrigin" "" "@DEF@"
-.sM
-.FD 0
-XSetTSOrigin\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIts_x_origin\fP\^, \fIts_y_origin\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIts_x_origin\fP\^, \fIts_y_origin\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIts_x_origin\fP 1i
-.br
-.ns
-.IP \fIts_y_origin\fP 1i
-Specify the x and y coordinates of the tile and stipple origin.
-.LP
-.eM
-When graphics requests call for tiling or stippling,
-the parent's origin will be interpreted relative to whatever destination 
-drawable is specified in the graphics request.
-.LP
-.PN XSetTSOrigin
-can generate
-.PN BadAlloc
-and
-.PN BadGC 
-errors.
-.NH 3
-Setting the Current Font 
-.XS
-\*(SN Setting the Current Font 
-.XE
-.LP
-To set the current font of a given GC, use
-.PN XSetFont .
-.IN "XSetFont" "" "@DEF@"
-.sM
-.FD 0
-XSetFont\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfont\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      Font \fIfont\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIfont\fP 1i
-Specifies the font.
-.LP
-.eM
-.PN XSetFont
-can generate
-.PN BadAlloc ,
-.PN BadFont ,
-and 
-.PN BadGC 
-errors.
-.NH 3
-Setting the Clip Region
-.XS
-\*(SN Setting the Clip Region 
-.XE
-.LP
-Xlib provides functions that you can use to set the clip-origin 
-and the clip-mask or set the clip-mask to a list of rectangles.
-.LP
-.sp
-To set the clip-origin of a given GC, use
-.PN XSetClipOrigin .
-.IN "XSetClipOrigin" "" "@DEF@"
-.sM
-.FD 0
-XSetClipOrigin\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIclip_x_origin\fP 1i
-.br
-.ns
-.IP \fIclip_y_origin\fP 1i
-Specify the x and y coordinates of the clip-mask origin.
-.LP
-.eM
-The clip-mask origin is interpreted relative to the origin of whatever 
-destination drawable is specified in the graphics request.
-.LP
-.PN XSetClipOrigin
-can generate
-.PN BadAlloc
-and
-.PN BadGC 
-errors.
-.LP
-.sp
-To set the clip-mask of a given GC to the specified pixmap, use
-.PN XSetClipMask .
-.IN "XSetClipMask" "" "@DEF@"
-.sM
-.FD 0
-XSetClipMask\^(\^\fIdisplay\fP, \fIgc\fP, \fIpixmap\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      Pixmap \fIpixmap\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIpixmap\fP 1i
-Specifies the pixmap or
-.PN None .
-.LP
-.eM
-If the clip-mask is set to
-.PN None ,
-the pixels are always drawn (regardless of the clip-origin).
-.LP
-.PN XSetClipMask
-can generate
-.PN BadAlloc ,
-.PN BadGC ,
-.PN BadMatch ,
-and
-.PN BadPixmap 
-errors.
-.LP
-.sp
-To set the clip-mask of a given GC to the specified list of rectangles, use
-.PN XSetClipRectangles .
-.IN "XSetClipRectangles" "" "@DEF@"
-.sM
-.FD 0
-XSetClipRectangles\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^, \fIrectangles\fP\^, \fIn\fP\^, \fIordering\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^;
-.br
-      XRectangle \fIrectangles\fP[]\^;
-.br
-      int \fIn\fP\^;
-.br
-      int \fIordering\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIclip_x_origin\fP 1i
-.br
-.ns
-.IP \fIclip_y_origin\fP 1i
-Specify the x and y coordinates of the clip-mask origin.
-.IP \fIrectangles\fP 1i
-Specifies an array of rectangles that define the clip-mask.
-.IP \fIn\fP 1i
-Specifies the number of rectangles. 
-.IP \fIordering\fP 1i
-Specifies the ordering relations on the rectangles.
-You can pass
-.PN Unsorted ,
-.PN YSorted ,
-.PN YXSorted ,
-or
-.PN YXBanded .
-.LP
-.eM
-The
-.PN XSetClipRectangles
-function changes the clip-mask in the specified GC 
-to the specified list of rectangles and sets the clip origin.
-The output is clipped to remain contained within the
-rectangles.
-The clip-origin is interpreted relative to the origin of
-whatever destination drawable is specified in a graphics request.  
-The rectangle coordinates are interpreted relative to the clip-origin.  
-The rectangles should be nonintersecting, or the graphics results will be
-undefined.
-Note that the list of rectangles can be empty, 
-which effectively disables output.
-This is the opposite of passing
-.PN None
-as the clip-mask in
-.PN XCreateGC ,
-.PN XChangeGC ,
-and
-.PN XSetClipMask .
-.LP
-If known by the client, ordering relations on the rectangles can be
-specified with the ordering argument. 
-This may provide faster operation
-by the server. 
-If an incorrect ordering is specified, the X server may generate a
-.PN BadMatch
-error, but it is not required to do so.
-If no error is generated, the graphics
-results are undefined.
-.PN Unsorted 
-means the rectangles are in arbitrary order.
-.PN YSorted 
-means that the rectangles are nondecreasing in their Y origin.
-.PN YXSorted 
-additionally constrains 
-.PN YSorted 
-order in that all
-rectangles with an equal Y origin are nondecreasing in their X
-origin.  
-.PN YXBanded 
-additionally constrains 
-.PN YXSorted 
-by requiring that,
-for every possible Y scanline, all rectangles that include that
-scanline have an identical Y origins and Y extents.
-.LP
-.PN XSetClipRectangles
-can generate
-.PN BadAlloc , 
-.PN BadGC ,
-.PN BadMatch ,
-and
-.PN BadValue 
-errors.
-.LP
-Xlib provides a set of basic functions for performing
-region arithmetic.
-For information about these functions,
-see section 16.5.
-.NH 3
-Setting the Arc Mode, Subwindow Mode, and Graphics Exposure 
-.XS
-\*(SN Setting the Arc Mode, Subwindow Mode, and Graphics Exposure 
-.XE
-.LP
-To set the arc mode of a given GC, use
-.PN XSetArcMode .
-.IN "XSetArcMode" "" "@DEF@"
-.sM
-.FD 0
-XSetArcMode\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIarc_mode\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIarc_mode\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIarc_mode\fP 1i
-Specifies the arc mode.
-You can pass
-.PN ArcChord
-or
-.PN ArcPieSlice .
-.LP
-.eM
-.PN XSetArcMode
-can generate
-.PN BadAlloc ,
-.PN BadGC ,
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-To set the subwindow mode of a given GC, use
-.PN XSetSubwindowMode .
-.IN "XSetSubwindowMode" "" "@DEF@"
-.sM
-.FD 0
-XSetSubwindowMode\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIsubwindow_mode\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIsubwindow_mode\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIsubwindow_mode\fP 1i
-Specifies the subwindow mode.
-You can pass
-.PN ClipByChildren
-or
-.PN IncludeInferiors .
-.LP
-.eM
-.PN XSetSubwindowMode
-can generate
-.PN BadAlloc ,
-.PN BadGC ,
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-To set the graphics-exposures flag of a given GC, use
-.PN XSetGraphicsExposures .
-.IN "XSetGraphicsExposures" "" "@DEF@"
-.sM
-.FD 0
-XSetGraphicsExposures\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIgraphics_exposures\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      Bool \fIgraphics_exposures\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIgraphics_exposures\fP 1i
-Specifies a Boolean value that indicates whether you want
-.PN GraphicsExpose
-and
-.PN NoExpose
-events to be reported when calling
-.PN XCopyArea
-and
-.PN XCopyPlane
-with this GC.
-.LP
-.eM
-.PN XSetGraphicsExposures
-can generate
-.PN BadAlloc ,
-.PN BadGC ,
-and
-.PN BadValue 
-errors.
-.bp
diff --git a/libX11/specs/libX11/CH07.xml b/libX11/specs/libX11/CH07.xml
new file mode 100644
index 000000000..6e8894080
--- /dev/null
+++ b/libX11/specs/libX11/CH07.xml
@@ -0,0 +1,3401 @@
+<chapter id="graphics_context_functions">

+<title>Graphics Context Functions</title>

+

+<para>

+A number of resources are used when performing graphics operations in X. Most information

+about performing graphics (for example, foreground color, background color, line style, and so

+on) is stored in resources called graphics contexts (GCs). Most graphics operations (see chapter

+8) take a GC as an argument. Although in theory the X protocol permits sharing of GCs between

+applications, it is expected that applications will use their own GCs when performing operations.

+Sharing of GCs is highly discouraged because the library may cache GC state.

+</para>

+<para>

+Graphics operations can be performed to either windows or pixmaps, which collectively are

+called drawables. Each drawable exists on a single screen. A GC is created for a specific screen

+and drawable depth and can only be used with drawables of matching screen and depth.

+</para>

+<para>

+This chapter discusses how to:

+</para>

+<itemizedlist>

+  <listitem><para>Manipulate graphics context/state</para></listitem>

+  <listitem><para>Use graphics context convenience functions</para></listitem>

+</itemizedlist>

+

+<sect1 id="Manipulating_Graphics_Context_State">

+<title>Manipulating Graphics Context/State</title>

+<!-- .XS -->

+<!-- (SN Manipulating Graphics Context/State  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Most attributes of graphics operations are stored in GCs.

+These include line width, line style, plane mask, foreground, background,

+tile, stipple, clipping region, end style, join style, and so on.

+Graphics operations (for example, drawing lines) use these values

+to determine the actual drawing operation.

+Extensions to X may add additional components to GCs.

+The contents of a GC are private to Xlib.

+</para>

+<para>

+<!-- .LP -->

+Xlib implements a write-back cache for all elements of a GC that are not

+resource IDs to allow Xlib to implement the transparent coalescing of changes 

+to GCs.

+For example,

+a call to

+<function>XSetForeground</function>

+of a GC followed by a call to

+<function>XSetLineAttributes</function>

+results in only a single-change GC protocol request to the server.

+GCs are neither expected nor encouraged to be shared between client 

+applications, so this write-back caching should present no problems.

+Applications cannot share GCs without external synchronization.

+Therefore,

+sharing GCs between applications is highly discouraged. 

+</para>

+<para>

+<!-- .LP -->

+To set an attribute of a GC,

+set the appropriate member of the

+<function>XGCValues</function>

+structure and OR in the corresponding value bitmask in your subsequent calls to

+<function>XCreateGC</function>.

+The symbols for the value mask bits and the

+<function>XGCValues</function>

+structure are:

+<!-- .sM -->

+</para>

+

+

+<literallayout class="monospaced">

+/* GC attribute value mask bits */

+

+#define     GCFunction              (1L&lt;&lt;0)

+#define     GCPlaneMask             (1L&lt;&lt;1)

+#define     GCForeground            (1L&lt;&lt;2)

+#define     GCBackground            (1L&lt;&lt;3)

+#define     GCLineWidth             (1L&lt;&lt;4)

+#define     GCLineStyle             (1L&lt;&lt;5)

+#define     GCCapStyle              (1L&lt;&lt;6)

+#define     GCJoinStyle             (1L&lt;&lt;7)

+#define     GCFillStyle             (1L&lt;&lt;8)

+#define     GCFillRule              (1L&lt;&lt;9)

+#define     GCTile                  (1L&lt;&lt;10)

+#define     GCStipple               (1L&lt;&lt;11)

+#define     GCTileStipXOrigin       (1L&lt;&lt;12)

+#define     GCTileStipYOrigin       (1L&lt;&lt;13)

+#define     GCFont                  (1L&lt;&lt;14)

+#define     GCSubwindowMode         (1L&lt;&lt;15)

+#define     GCGraphicsExposures     (1L&lt;&lt;16)

+#define     GCClipXOrigin           (1L&lt;&lt;17)

+#define     GCClipYOrigin           (1L&lt;&lt;18)

+#define     GCClipMask              (1L&lt;&lt;19)

+#define     GCDashOffset            (1L&lt;&lt;20)

+#define     GCDashList              (1L&lt;&lt;21)

+#define     GCArcMode               (1L&lt;&lt;22)

+</literallayout>

+

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+/* Values */

+

+typedef struct {

+     int function;                 /* logical operation */

+     unsigned long plane_mask;     /* plane mask */

+     unsigned long foreground;     /* foreground pixel */

+     unsigned long background;     /* background pixel */

+     int line_width;               /* line width (in pixels) */

+     int line_style;               /* LineSolid, LineOnOffDash, LineDoubleDash */

+     int cap_style;                /* CapNotLast, CapButt, CapRound, CapProjecting */

+     int join_style;               /* JoinMiter, JoinRound, JoinBevel */

+     int fill_style;               /* FillSolid, FillTiled, FillStippled FillOpaqueStippled*/

+     int fill_rule;                /* EvenOddRule, WindingRule */

+     int arc_mode;                 /* ArcChord, ArcPieSlice */

+     Pixmap tile;                  /* tile pixmap for tiling operations */

+     Pixmap stipple;               /* stipple 1 plane pixmap for stippling */

+     int ts_x_origin;              /* offset for tile or stipple operations */

+     int ts_y_origin

+     Font font;                    /* default text font for text operations */

+     int subwindow_mode;           /* ClipByChildren, IncludeInferiors */

+     Bool graphics_exposures;      /* boolean, should exposures be generated */

+     int clip_x_origin;            /* origin for clipping */

+     int clip_y_origin;

+     Pixmap clip_mask;             /* bitmap clipping; other calls for rects */

+     int dash_offset;              /* patterned/dashed line information */

+     char dashes;

+} XGCValues;

+</literallayout>

+

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The default GC values are:

+</para>

+<informaltable>

+  <tgroup cols='3' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <colspec colname='c3'/>

+  <thead>

+    <row>

+      <entry>Component</entry>

+      <entry>Default</entry>

+    </row>

+  </thead>

+  <tbody>

+    <row>

+      <entry>function</entry>

+      <entry><function>GXcopy</function></entry>

+    </row>

+    <row>

+      <entry>plane_mask</entry>

+      <entry>All ones</entry>

+    </row>

+    <row>

+      <entry>foreground</entry>

+      <entry>0</entry>

+    </row>

+    <row>

+      <entry>background</entry>

+      <entry>1</entry>

+    </row>

+    <row>

+      <entry>line_width</entry>

+      <entry>0</entry>

+    </row>

+    <row>

+      <entry>line_style</entry>

+      <entry><function>LineSolid</function></entry>

+    </row>

+    <row>

+      <entry>cap_style</entry>

+      <entry><function>CapButt</function></entry>

+    </row>

+    <row>

+      <entry>join_style</entry>

+      <entry><function>JoinMiter</function></entry>

+    </row>

+    <row>

+      <entry>fill_style</entry>

+      <entry><function>FillSolid</function></entry>

+    </row>

+    <row>

+      <entry>fill_rule</entry>

+      <entry><function>EvenOddRule</function></entry>

+    </row>

+    <row>

+      <entry>arc_mode</entry>

+      <entry><function>ArcPieSlice</function></entry>

+    </row>

+    <row>

+      <entry>tile</entry>

+      <entry>Pixmap of unspecified size filled with foreground pixel</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>(that is, client specified pixel if any, else 0)</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>(subsequent changes to foreground do not affect this pixmap)</entry>

+    </row>

+    <row>

+      <entry>stipple</entry>

+      <entry>Pixmap of unspecified size filled with ones</entry>

+    </row>

+    <row>

+      <entry>ts_x_origin</entry>

+      <entry>0</entry>

+    </row>

+    <row>

+      <entry>ts_y_origin</entry>

+      <entry>0</entry>

+    </row>

+    <row>

+      <entry>font</entry>

+      <entry>&lt;implementation dependent&gt;</entry>

+    </row>

+    <row>

+      <entry>subwindow_mode</entry>

+      <entry><function>ClipByChildren</function></entry>

+    </row>

+    <row>

+      <entry>graphics_exposures</entry>

+      <entry><function>True</function></entry>

+    </row>

+    <row>

+      <entry>clip_x_origin</entry>

+      <entry>0</entry>

+    </row>

+    <row>

+      <entry>clip_y_origin</entry>

+      <entry>0</entry>

+    </row>

+    <row>

+      <entry>clip_mask</entry>

+      <entry><function>None</function></entry>

+    </row>

+    <row>

+      <entry>dash_offset</entry>

+      <entry>0</entry>

+    </row>

+    <row>

+      <entry>dashes</entry>

+      <entry>4 (that is, the list [4, 4])</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<para>

+<!-- .LP -->

+Note that foreground and background are not set to any values likely

+to be useful in a window.

+</para>

+

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>Display Functions</primary></indexterm>

+<indexterm significance="preferred"><primary>Source</primary></indexterm>

+<indexterm significance="preferred"><primary>Destination</primary></indexterm>

+The function attributes of a GC are used when you update a section of

+a drawable (the destination) with bits from somewhere else (the source).  

+The function in a GC defines how the new destination bits are to be

+computed from the source bits and the old destination bits.

+<function>GXcopy</function>

+is typically the most useful because it will work on a color display,

+but special applications may use other functions,

+particularly in concert with particular planes of a color display.

+The 16 GC functions, defined in 

+<!-- .hN X11/X.h , -->

+are:

+</para>

+<!-- .\" are listed in Table 5-1 along with the  -->

+<!-- .\"the associated hexadecimal code -->

+<!-- .\" and operation. -->

+<!-- .\".CP T 1 -->

+<!-- .\"Display Functions -->

+<informaltable>

+  <tgroup cols='3' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <colspec colname='c3'/>

+  <thead>

+    <row>

+      <entry>Function Name</entry>

+      <entry>Value</entry>

+      <entry>Operation</entry>

+    </row>

+  </thead>

+  <tbody>

+    <row>

+      <entry><function>GXclear</function></entry>

+      <entry>0x0</entry>

+      <entry>0</entry>

+    </row>

+    <row>

+      <entry><function>GXand</function></entry>

+      <entry>0x1</entry>

+      <entry>src AND dst</entry>

+    </row>

+    <row>

+      <entry><function>GXandReverse</function></entry>

+      <entry>0x2</entry>

+      <entry>src AND NOT dst</entry>

+    </row>

+    <row>

+      <entry><function>GXcopy</function></entry>

+      <entry>0x3</entry>

+      <entry>src</entry>

+    </row>

+    <row>

+      <entry><function>GXandInverted</function></entry>

+      <entry>0x4</entry>

+      <entry>(NOT src) AND dst</entry>

+    </row>

+    <row>

+      <entry><function>GXnoop</function></entry>

+      <entry>0x5</entry>

+      <entry>dst</entry>

+    </row>

+    <row>

+      <entry><function>GXxor</function></entry>

+      <entry>0x6</entry>

+      <entry>src XOR dst</entry>

+    </row>

+    <row>

+      <entry><function>GXor</function></entry>

+      <entry>0x7</entry>

+      <entry>src OR dst</entry>

+    </row>

+    <row>

+      <entry><function>GXnor</function></entry>

+      <entry>0x8</entry>

+      <entry>(NOT src) AND (NOT dst)</entry>

+    </row>

+    <row>

+      <entry><function>GXequiv</function></entry>

+      <entry>0x9</entry>

+      <entry>(NOT src) XOR dst</entry>

+    </row>

+    <row>

+      <entry><function>GXinvert</function></entry>

+      <entry>0xa</entry>

+      <entry>NOT dst</entry>

+    </row>

+    <row>

+      <entry><function>GXorReverse</function></entry>

+      <entry>0xb</entry>

+      <entry>src OR (NOT dst)</entry>

+    </row>

+    <row>

+      <entry><function>GXcopyInverted</function></entry>

+      <entry>0xc</entry>

+      <entry>NOT src</entry>

+    </row>

+    <row>

+      <entry><function>GXorInverted</function></entry>

+      <entry>0xd</entry>

+      <entry>(NOT src) OR dst</entry>

+    </row>

+    <row>

+      <entry><function>GXnand</function></entry>

+      <entry>0xe</entry>

+      <entry>(NOT src) OR (NOT dst)</entry>

+    </row>

+    <row>

+      <entry><function>GXset</function></entry>

+      <entry>0xf</entry>

+      <entry>1</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<para>

+<!-- .LP -->

+Many graphics operations depend on either pixel values or planes in a GC.

+<indexterm><primary>Pixel value</primary></indexterm>

+The planes attribute is of type long, and it specifies which planes of the

+destination are to be modified, one bit per plane.

+<indexterm><primary>Plane</primary><secondary>mask</secondary></indexterm>

+A monochrome display has only one plane and

+will be the least significant bit of the word.

+As planes are added to the display hardware, they will occupy more

+significant bits in the plane mask.

+</para>

+<para>

+<!-- .LP -->

+In graphics operations, given a source and destination pixel, 

+the result is computed bitwise on corresponding bits of the pixels.

+That is, a Boolean operation is performed in each bit plane.  

+The plane_mask restricts the operation to a subset of planes.

+A macro constant

+<function>AllPlanes</function>

+can be used to refer to all planes of the screen simultaneously.

+The result is computed by the following:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask))

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+Range checking is not performed on the values for foreground,

+background, or plane_mask.

+They are simply truncated to the appropriate

+number of bits.

+The line-width is measured in pixels and either can be greater than or equal to

+one (wide line) or can be the special value zero (thin line).

+</para>

+<para>

+<!-- .LP -->

+Wide lines are drawn centered on the path described by the graphics request.

+Unless otherwise specified by the join-style or cap-style,

+the bounding box of a wide line with endpoints [x1, y1], [x2, y2] and

+width w is a rectangle with vertices at the following real coordinates:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+[x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)],

+[x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)]

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+Here sn is the sine of the angle of the line,

+and cs is the cosine of the angle of the line.

+A pixel is part of the line and so is drawn

+if the center of the pixel is fully inside the bounding box

+(which is viewed as having infinitely thin edges).

+If the center of the pixel is exactly on the bounding box,

+it is part of the line if and only if the interior is immediately to its right

+(x increasing direction).

+Pixels with centers on a horizontal edge are a special case and are part of

+the line if and only if the interior or the boundary is immediately below 

+(y increasing direction) and the interior or the boundary is immediately

+to the right (x increasing direction).

+</para>

+<para>

+<!-- .LP -->

+Thin lines (zero line-width) are one-pixel-wide lines drawn using an

+unspecified, device-dependent algorithm.

+There are only two constraints on this algorithm. 

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+If a line is drawn unclipped from [x1,y1] to [x2,y2] and

+if another line is drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy],

+a point [x,y] is touched by drawing the first line 

+if and only if the point [x+dx,y+dy] is touched by drawing the second line.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The effective set of points comprising a line cannot be affected by clipping.

+That is, a point is touched in a clipped line if and only if the point 

+lies inside the clipping region and the point would be touched

+by the line when drawn unclipped.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels 

+as a wide line drawn from [x2,y2] to [x1,y1], not counting cap-style 

+and join-style.

+It is recommended that this property be true for thin lines, 

+but this is not required.

+A line-width of zero may differ from a line-width of one in which pixels are

+drawn.

+This permits the use of many manufacturers' line drawing hardware,

+which may run many times faster than the more precisely specified

+wide lines.

+</para>

+<para>

+<!-- .LP -->

+In general, 

+drawing a thin line will be faster than drawing a wide line of width one.

+However, because of their different drawing algorithms,

+thin lines may not mix well aesthetically with wide lines.

+If it is desirable to obtain precise and uniform results across all displays,

+a client should always use a line-width of one rather than a line-width of zero.

+</para>

+<para>

+<!-- .LP -->

+The line-style defines which sections of a line are drawn:

+</para>

+

+<variablelist>

+  <varlistentry>

+    <term><function>LineSolid</function></term>

+    <listitem>

+      <para>The full path of the line is drawn.</para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term><function>LineDoubleDash</function></term>

+    <listitem>

+      <para>

+The full path of the line is drawn,

+but the even dashes are filled differently

+from the odd dashes (see fill-style) with <!-- xref -->

+<function>CapButt </function>

+style used where even and odd dashes meet.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term><function>LineOnOffDash</function></term>

+    <listitem>

+      <para>

+Only the even dashes are drawn,

+and cap-style applies to 

+all internal ends of the individual dashes,

+except

+<function>CapNotLast</function>

+is treated as

+<function>CapButt</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+The cap-style defines how the endpoints of a path are drawn:

+</para>

+

+<variablelist>

+  <varlistentry>

+    <term><function>CapNotLast</function></term>

+    <listitem>

+      <para>

+This is equivalent to

+<function>CapButt</function>

+except that for a line-width of zero the final endpoint is not drawn.

+     </para>

+    </listitem>

+  </varlistentry>

+

+  <varlistentry>

+    <term><function>CapButt</function></term>

+    <listitem>

+      <para>

+The line is square at the endpoint (perpendicular to the slope of the line)

+with no projection beyond.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term><function>CapRound</function></term>

+    <listitem>

+      <para>

+The line has a circular arc with the diameter equal to the line-width,

+centered on the endpoint.

+(This is equivalent to 

+<function>CapButt </function>

+for line-width of zero).

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term><function>CapProjecting</function></term>

+    <listitem>

+      <para>

+The line is square at the end, but the path continues beyond the endpoint

+for a distance equal to half the line-width.

+(This is equivalent to

+<function>CapButt </function>

+for line-width of zero).

+      </para>

+    </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+The join-style defines how corners are drawn for wide lines:

+</para>

+

+<variablelist>

+  <varlistentry>

+    <term><function>JoinMiter</function></term>

+    <listitem>

+      <para>

+The outer edges of two lines extend to meet at an angle.

+However, if the angle is less than 11 degrees,

+then a

+<function>JoinBevel</function>

+join-style is used instead.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term><function>JoinRound</function></term>

+    <listitem>

+      <para>

+The corner is a circular arc with the diameter equal to the line-width,

+centered on the joinpoint.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term><function>JoinBevel</function></term>

+    <listitem>

+      <para>

+The corner has

+<function>CapButt </function>

+endpoint styles with the triangular notch filled.

+      </para>

+    </listitem>

+  </varlistentry>

+</variablelist>

+

+

+<para>

+<!-- .LP -->

+For a line with coincident endpoints (x1=x2, y1=y2), 

+when the cap-style is applied to both endpoints, 

+the semantics depends on the line-width and the cap-style:

+</para>

+

+<informaltable>

+  <tgroup cols='3' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <colspec colname='c3'/>

+  <tbody>

+    <row>

+      <entry><function>CapNotLast</function></entry>

+      <entry>thin</entry>

+      <entry>The results are device dependent,

+      but the desired effect is that nothing is drawn.</entry>

+    </row>

+    <row>

+      <entry><function>CapButt</function></entry>

+      <entry>thin</entry>

+      <entry>The results are device dependent,

+      but the desired effect is that a single pixel is drawn.</entry>

+    </row>

+    <row>

+      <entry><function>CapRound</function></entry>

+      <entry>thin</entry>

+      <entry>The results are the same as for

+      <function>CapButt /thin</function>.</entry>

+    </row>

+    <row>

+      <entry><function>CapProjecting</function></entry>

+      <entry>thin</entry>

+      <entry>The results are the same as for

+      <function>CapButt /thin</function>.</entry>

+    </row>

+    <row>

+      <entry><function>CapButt</function></entry>

+      <entry>wide</entry>

+      <entry>Nothing is drawn.</entry>

+    </row>

+    <row>

+      <entry><function>CapRound</function></entry>

+      <entry>wide</entry>

+      <entry>The closed path is a circle, centered at the endpoint, and

+      with the diameter equal to the line-width.</entry>

+    </row>

+    <row>

+      <entry><function>CapProjecting</function></entry>

+      <entry>wide</entry>

+      <entry>The closed path is a square, aligned with the coordinate axes, centered at the

+      endpoint, and with the sides equal to the line-width.</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<para>

+<!-- .LP -->

+For a line with coincident endpoints (x1=x2, y1=y2), 

+when the join-style is applied at one or both endpoints, 

+the effect is as if the line was removed from the overall path.

+However, if the total path consists of or is reduced to a single point joined

+with itself, the effect is the same as when the cap-style is applied at both

+endpoints.

+</para>

+<para>

+<!-- .LP -->

+The tile/stipple represents an infinite two-dimensional plane,

+with the tile/stipple replicated in all dimensions.

+When that plane is superimposed on the drawable

+for use in a graphics operation, the upper-left corner

+of some instance of the tile/stipple is at the coordinates within

+the drawable specified by the tile/stipple origin.

+The tile/stipple and clip origins are interpreted relative to the

+origin of whatever destination drawable is specified in a graphics

+request.

+The tile pixmap must have the same root and depth as the GC,

+or a

+<function>BadMatch </function>

+error results.

+The stipple pixmap must have depth one and must have the same root as the

+GC, or a 

+<function>BadMatch </function>

+error results.  

+For stipple operations where the fill-style is

+<function>FillStippled</function>

+but not 

+<function>FillOpaqueStippled</function>,

+the stipple pattern is tiled in a

+single plane and acts as an additional clip mask to be ANDed with the clip-mask.

+Although some sizes may be faster to use than others,

+any size pixmap can be used for tiling or stippling.

+</para>

+

+<para>

+<!-- .LP -->

+The fill-style defines the contents of the source for line, text, and

+fill requests.  

+For all text and fill requests (for example,

+<function>XDrawText</function>,

+<function>XDrawText16</function>,

+<function>XFillRectangle</function>,

+<function>XFillPolygon</function>,

+and

+<function>XFillArc</function>);

+for line requests 

+with line-style 

+<function>LineSolid </function>

+(for example,

+<function>XDrawLine</function>,

+<function>XDrawSegments</function>,

+<function>XDrawRectangle</function>,

+<function>XDrawArc</function>);

+and for the even dashes for line requests with line-style 

+<function>LineOnOffDash </function>

+or 

+<function>LineDoubleDash</function>,

+the following apply:

+</para>

+

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <tbody>

+    <row>

+      <entry><function>FillSolid</function></entry>

+      <entry>Foreground</entry>

+    </row>

+    <row>

+      <entry><function>FillTiled</function></entry>

+      <entry>Tile</entry>

+    </row>

+    <row>

+      <entry><function>FillOpaqueStippled</function></entry>

+      <entry>A tile with the same width and height as stipple,

+      but with background everywhere stipple has a zero

+      and with foreground everywhere stipple has a one</entry>

+    </row>

+    <row>

+      <entry><function>FillStippled</function></entry>

+      <entry>Foreground masked by stipple</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<para>

+<!-- .LP -->

+When drawing lines with line-style

+<function>LineDoubleDash</function>,

+the odd dashes are controlled by the fill-style in the following manner:

+</para>

+

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <tbody>

+    <row>

+      <entry><function>FillSolid</function></entry>

+      <entry>Background</entry>

+    </row>

+    <row>

+      <entry><function>FillTiled</function></entry>

+      <entry>Same as for even dashes</entry>

+    </row>

+    <row>

+      <entry><function>FillOpaqueStippled</function></entry>

+      <entry>Same as for even dashes</entry>

+    </row>

+    <row>

+      <entry><function>FillStippled</function></entry>

+      <entry>Background masked by stipple</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<para>

+<!-- .LP -->

+Storing a pixmap in a GC might or might not result in a copy

+being made.

+If the pixmap is later used as the destination for a graphics request,

+the change might or might not be reflected in the GC.

+If the pixmap is used simultaneously in a graphics request both as

+a destination and as a tile or stipple,

+the results are undefined.

+</para>

+<para>

+<!-- .LP -->

+For optimum performance,

+you should draw as much as possible with the same GC 

+(without changing its components).

+The costs of changing GC components relative to using different GCs

+depend on the display hardware and the server implementation.

+It is quite likely that some amount of GC information will be

+cached in display hardware and that such hardware can only cache a small number

+of GCs.

+</para>

+<para>

+<!-- .LP -->

+The dashes value is actually a simplified form of the

+more general patterns that can be set with 

+<function>XSetDashes</function>.

+Specifying a

+value of N is equivalent to specifying the two-element list [N, N] in 

+<function>XSetDashes</function>.

+The value must be nonzero,

+or a

+<function>BadValue</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+The clip-mask restricts writes to the destination drawable.  

+If the clip-mask is set to a pixmap,

+it must have depth one and have the same root as the GC,

+or a

+<function>BadMatch </function>

+error results.

+If clip-mask is set to

+<function>None</function>,

+the pixels are always drawn regardless of the clip origin.

+The clip-mask also can be set by calling the

+<function>XSetClipRectangles</function>

+or

+<function>XSetRegion</function>

+functions.

+Only pixels where the clip-mask has a bit set to 1 are drawn.  

+Pixels are not drawn outside the area covered by the clip-mask 

+or where the clip-mask has a bit set to 0.

+The clip-mask affects all graphics requests.

+The clip-mask does not clip sources.

+The clip-mask origin is interpreted relative to the origin of whatever

+destination drawable is specified in a graphics request.

+</para>

+<para>

+<!-- .LP -->

+You can set the subwindow-mode to

+<function>ClipByChildren</function>

+or

+<function>IncludeInferiors</function>.

+For 

+<function>ClipByChildren</function>,

+both source and destination windows are

+additionally clipped by all viewable 

+<function>InputOutput</function>

+children.  

+For 

+<function>IncludeInferiors</function>,

+neither source nor destination window is clipped by inferiors. 

+This will result in including subwindow contents in the source

+and drawing through subwindow boundaries of the destination.

+The use of 

+<function>IncludeInferiors </function>

+on a window of one depth with mapped

+inferiors of differing depth is not illegal, but the semantics are

+undefined by the core protocol.

+</para>

+<para>

+<!-- .LP -->

+The fill-rule defines what pixels are inside (drawn) for

+paths given in 

+<function>XFillPolygon </function>

+requests and can be set to 

+<function>EvenOddRule </function>

+or

+<function>WindingRule</function>.

+For

+<function>EvenOddRule</function>,

+a point is inside if

+an infinite ray with the point as origin crosses the path an odd number

+of times.  

+For 

+<function>WindingRule</function>,

+a point is inside if an infinite ray with the

+point as origin crosses an unequal number of clockwise and

+counterclockwise directed path segments.

+A clockwise directed path segment is one that crosses the ray from left to

+right as observed from the point.

+A counterclockwise segment is one that crosses the ray from right to left

+as observed from the point.

+The case where a directed line segment is coincident with the ray is

+uninteresting because you can simply choose a different ray that is not

+coincident with a segment.

+</para>

+<para>

+<!-- .LP -->

+For both 

+<function>EvenOddRule</function>

+and

+<function>WindingRule</function>,

+a point is infinitely small, 

+and the path is an infinitely thin line.  

+A pixel is inside if the center point of the pixel is inside

+and the center point is not on the boundary.  

+If the center point is on the boundary,

+the pixel is inside if and only if the polygon interior is immediately to

+its right (x increasing direction).  

+Pixels with centers on a horizontal edge are a special case 

+and are inside if and only if the polygon interior is immediately below 

+(y increasing direction).

+</para>

+<para>

+<!-- .LP -->

+The arc-mode controls filling in the 

+<function>XFillArcs</function>

+function and can be set to

+<function>ArcPieSlice</function>

+or

+<function>ArcChord</function>.

+For

+<function>ArcPieSlice</function>,

+the arcs are pie-slice filled.

+For

+<function>ArcChord</function>,

+the arcs are chord filled.

+</para>

+<para>

+<!-- .LP -->

+The graphics-exposure flag controls 

+<function>GraphicsExpose </function>

+event generation

+for 

+<function>XCopyArea </function>

+and 

+<function>XCopyPlane</function>

+requests (and any similar requests defined by extensions).

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To create a new GC that is usable on a given screen with a 

+depth of drawable, use

+<function>XCreateGC</function>.

+<indexterm><primary>Graphics context</primary><secondary>initializing</secondary></indexterm>

+<indexterm significance="preferred"><primary>XCreateGC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>GC<function> XCreateGC</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>

+  <paramdef>XGCValues<parameter> *\^values</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+<!-- .ds Vm set using the information in the specified values structure -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>valuemask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies which components in the GC are to be (Vm. 

+This argument is the bitwise inclusive OR of zero or more of the valid

+GC component mask bits.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>values</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies any values as specified by the valuemask.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCreateGC</function>

+function creates a graphics context and returns a GC.

+The GC can be used with any destination drawable having the same root

+and depth as the specified drawable.

+Use with other drawables results in a

+<function>BadMatch</function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<function>XCreateGC</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadDrawable</function>,

+<function>BadFont</function>,

+<function>BadMatch</function>,

+<function>BadPixmap</function>,

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To copy components from a source GC to a destination GC, use

+<function>XCopyGC</function>.

+<indexterm significance="preferred"><primary>XCopyGC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XCopyGC</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GCsrc,<parameter> dest</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>src</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the components of the source GC.

+<!-- .ds Vm copied to the destination GC -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>valuemask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies which components in the GC are to be (Vm. 

+This argument is the bitwise inclusive OR of zero or more of the valid

+GC component mask bits.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dest</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the destination GC.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XCopyGC</function>

+function copies the specified components from the source GC

+to the destination GC.

+The source and destination GCs must have the same root and depth,

+or a

+<function>BadMatch</function>

+error results.

+The valuemask specifies which component to copy, as for

+<function>XCreateGC</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XCopyGC</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadGC</function>,

+and

+<function>BadMatch</function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To change the components in a given GC, use

+<function>XChangeGC</function>.

+<indexterm significance="preferred"><primary>XChangeGC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XChangeGC</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>

+  <paramdef>XGCValues<parameter> *\^values</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+<!-- .ds Vm changed using information in the specified values structure -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>valuemask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies which components in the GC are to be (Vm. 

+This argument is the bitwise inclusive OR of zero or more of the valid

+GC component mask bits.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>values</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies any values as specified by the valuemask.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XChangeGC</function>

+function changes the components specified by valuemask for

+the specified GC.

+The values argument contains the values to be set.

+The values and restrictions are the same as for 

+<function>XCreateGC</function>.

+Changing the clip-mask overrides any previous 

+<function>XSetClipRectangles</function>

+request on the context. 

+Changing the dash-offset or dash-list

+overrides any previous 

+<function>XSetDashes</function>

+request on the context.

+The order in which components are verified and altered is server dependent.

+If an error is generated, a subset of the components may have been altered.

+</para>

+<para>

+<!-- .LP -->

+<function>XChangeGC</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadFont</function>,

+<function>BadGC</function>,

+<function>BadMatch</function>,

+<function>BadPixmap</function>,

+and

+<function>BadValue</function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain components of a given GC, use

+<function>XGetGCValues</function>.

+<indexterm significance="preferred"><primary>XGetGCValues</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XGetGCValues</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>

+  <paramdef>XGCValues<parameter> *values_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+<!-- .ds Vm returned in the values_return argument -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>valuemask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies which components in the GC are to be (Vm. 

+This argument is the bitwise inclusive OR of zero or more of the valid

+GC component mask bits.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>values_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the GC values in the specified

+<function>XGCValues </function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetGCValues</function>

+function returns the components specified by valuemask for the specified GC.

+If the valuemask contains a valid set of GC mask bits

+(<function>GCFunction</function>,

+<function>GCPlaneMask</function>,

+<function>GCForeground</function>,

+<function>GCBackground</function>,

+<function>GCLineWidth</function>,

+<function>GCLineStyle</function>,

+<function>GCCapStyle</function>,

+<function>GCJoinStyle</function>,

+<function>GCFillStyle</function>,

+<function>GCFillRule</function>,

+<function>GCTile</function>,

+<function>GCStipple</function>,

+<function>GCTileStipXOrigin</function>,

+<function>GCTileStipYOrigin</function>,

+<function>GCFont</function>,

+<function>GCSubwindowMode</function>,

+<function>GCGraphicsExposures</function>,

+<function>GCClipXOrigin</function>,

+<function>GCCLipYOrigin</function>,

+<function>GCDashOffset</function>,

+or

+<function>GCArcMode</function>)

+and no error occurs,

+<function>XGetGCValues</function>

+sets the requested components in values_return and returns a nonzero status.

+Otherwise, it returns a zero status.

+Note that the clip-mask and dash-list (represented by the

+<function>GCClipMask</function>

+and 

+<function>GCDashList</function>

+bits, respectively, in the valuemask)

+cannot be requested.

+Also note that an invalid resource ID (with one or more of the three

+most significant bits set to 1) will be returned for

+<function>GCFont</function>,

+<function>GCTile</function>,

+and

+<function>GCStipple</function>

+if the component has never been explicitly set by the client.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To free a given GC, use

+<function>XFreeGC</function>.

+<indexterm significance="preferred"><primary>XFreeGC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XFreeGC</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XFreeGC</function>

+function destroys the specified GC as well as all the associated storage.

+</para>

+<para>

+<!-- .LP -->

+<function>XFreeGC</function>

+can generate a

+<function>BadGC </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the 

+<function>GContext </function>

+resource ID for a given GC, use 

+<function>XGContextFromGC</function>.

+<indexterm significance="preferred"><primary>XGContextFromGC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>GContext<function> XGContextFromGC</function></funcdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<!-- .ds Gc for which you want the resource ID -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC (Gc.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+Xlib usually defers sending changes to the components of a GC to the server

+until a graphics function is actually called with that GC.

+This permits batching of component changes into a single server request.

+In some circumstances, however, it may be necessary for the client

+to explicitly force sending the changes to the server.

+An example might be when a protocol extension uses the GC indirectly,

+in such a way that the extension interface cannot know what GC will be used.

+To force sending GC component changes, use

+<function>XFlushGC</function>.

+<indexterm significance="preferred"><primary>XFlushGC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XFlushGC</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+</para>

+</sect1>

+<sect1 id="Using_Graphics_Context_Convenience_Routines">

+<title>Using Graphics Context Convenience Routines</title>

+<!-- .XS -->

+<!-- (SN Using Graphics Context Convenience Routines  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+This section discusses how to set the:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Foreground, background, plane mask, or function components

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Line attributes and dashes components

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Fill style and fill rule components

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Fill tile and stipple components

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Font component

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Clip region component

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Arc mode, subwindow mode, and graphics exposure components

+    </para>

+  </listitem>

+</itemizedlist>

+<sect2 id="Setting_the_Foreground_Background_Function_or_Plane_Mask">

+<title>Setting the Foreground, Background, Function, or Plane Mask</title>

+<!-- .XS -->

+<!-- (SN Setting the Foreground, Background, Function, or Plane Mask -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To set the foreground, background, plane mask, and function components

+for a given GC, use

+<function>XSetState</function>.

+<indexterm significance="preferred"><primary>XSetState</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetState</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>unsignedlongforeground,<parameter> background</parameter></paramdef>

+  <paramdef>int<parameter> function</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> plane_mask</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>foreground</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the foreground you want to set for the specified GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>background</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the background you want to set for the specified GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>function</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the function you want to set for the specified GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>plane_mask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the plane mask.

+<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<function>XSetState</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadGC</function>,

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the foreground of a given GC, use

+<function>XSetForeground</function>.

+<indexterm significance="preferred"><primary>XSetForeground</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetForeground</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> foreground</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>foreground</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the foreground you want to set for the specified GC.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<function>XSetForeground</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadGC </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the background of a given GC, use

+<function>XSetBackground</function>.

+<indexterm significance="preferred"><primary>XSetBackground</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetBackground</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> background</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>background</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the background you want to set for the specified GC.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<function>XSetBackground</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadGC </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the display function in a given GC, use

+<function>XSetFunction</function>.

+<indexterm significance="preferred"><primary>XSetFunction</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetFunction</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>int<parameter> function</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>function</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the function you want to set for the specified GC.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<function>XSetFunction</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadGC</function>,

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the plane mask of a given GC, use

+<function>XSetPlaneMask</function>.

+<indexterm significance="preferred"><primary>XSetPlaneMask</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetPlaneMask</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> plane_mask</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>plane_mask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the plane mask.

+<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<function>XSetPlaneMask</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadGC </function>

+errors.

+</para>

+</sect2>

+<sect2 id="Setting_the_Line_Attributes_and_Dashes">

+<title>Setting the Line Attributes and Dashes</title>

+<!-- .XS -->

+<!-- (SN Setting the Line Attributes and Dashes  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To set the line drawing components of a given GC, use

+<function>XSetLineAttributes</function>.

+<indexterm significance="preferred"><primary>XSetLineAttributes</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetLineAttributes</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>unsignedint<parameter> line_width</parameter></paramdef>

+  <paramdef>int<parameter> line_style</parameter></paramdef>

+  <paramdef>int<parameter> cap_style</parameter></paramdef>

+  <paramdef>int<parameter> join_style</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>line_width</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the line-width you want to set for the specified GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>line_style</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the line-style you want to set for the specified GC.

+You can pass

+<function>LineSolid</function>,

+<function>LineOnOffDash</function>,

+or

+<function>LineDoubleDash</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>cap_style</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the line-style and cap-style you want to set for the specified GC.

+You can pass

+<function>CapNotLast</function>,

+<function>CapButt</function>,

+<function>CapRound</function>,

+or

+<function>CapProjecting</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>join_style</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the line join-style you want to set for the specified GC.

+You can pass

+<function>JoinMiter</function>,

+<function>JoinRound</function>,

+or

+<function>JoinBevel</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<function>XSetLineAttributes</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadGC</function>,

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the dash-offset and dash-list for dashed line styles of a given GC, use

+<function>XSetDashes</function>.

+<indexterm significance="preferred"><primary>XSetDashes</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetDashes</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>int<parameter> dash_offset</parameter></paramdef>

+  <paramdef>char<parameter> dash_list[]\^</parameter></paramdef>

+  <paramdef>int<parameter> n</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dash_offset</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the phase of the pattern for the dashed line-style you want to set

+for the specified GC. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dash_list</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the dash-list for the dashed line-style

+you want to set for the specified GC. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>n</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of elements in dash_list. 

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XSetDashes</function>

+function sets the dash-offset and dash-list attributes for dashed line styles

+in the specified GC.

+There must be at least one element in the specified dash_list,

+or a

+<function>BadValue</function>

+error results. 

+The initial and alternating elements (second, fourth, and so on) 

+of the dash_list are the even dashes, and

+the others are the odd dashes.

+Each element specifies a dash length in pixels.

+All of the elements must be nonzero,

+or a

+<function>BadValue</function>

+error results.

+Specifying an odd-length list is equivalent to specifying the same list

+concatenated with itself to produce an even-length list.

+</para>

+<para>

+<!-- .LP -->

+The dash-offset defines the phase of the pattern,

+specifying how many pixels into the dash-list the pattern

+should actually begin in any single graphics request.

+Dashing is continuous through path elements combined with a join-style

+but is reset to the dash-offset between each sequence of joined lines.

+</para>

+<para>

+<!-- .LP -->

+The unit of measure for dashes is the same for the ordinary coordinate system.

+Ideally, a dash length is measured along the slope of the line, but implementations

+are only required to match this ideal for horizontal and vertical lines.

+Failing the ideal semantics, it is suggested that the length be measured along the

+major axis of the line.

+The major axis is defined as the x axis for lines drawn at an angle of between

+\-45 and +45 degrees or between 135 and 225 degrees from the x axis.

+For all other lines, the major axis is the y axis.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetDashes</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadGC</function>,

+and

+<function>BadValue </function>

+errors.

+</para>

+</sect2>

+<sect2 id="Setting_the_Fill_Style_and_Fill_Rule_">

+<title>Setting the Fill Style and Fill Rule </title>

+<!-- .XS -->

+<!-- (SN Setting the Fill Style and Fill Rule  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To set the fill-style of a given GC, use

+<function>XSetFillStyle</function>.

+<indexterm significance="preferred"><primary>XSetFillStyle</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetFillStyle</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>int<parameter> fill_style</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>fill_style</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the fill-style you want to set for the specified GC.

+You can pass

+<function>FillSolid</function>,

+<function>FillTiled</function>,

+<function>FillStippled</function>,

+or

+<function>FillOpaqueStippled</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<function>XSetFillStyle</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadGC</function>,

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the fill-rule of a given GC, use

+<function>XSetFillRule</function>.

+<indexterm significance="preferred"><primary>XSetFillRule</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetFillRule</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>int<parameter> fill_rule</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>fill_rule</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the fill-rule you want to set for the specified GC.

+You can pass 

+<function>EvenOddRule</function>

+or

+<function>WindingRule</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<function>XSetFillRule</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadGC</function>,

+and

+<function>BadValue </function>

+errors.

+</para>

+</sect2>

+<sect2 id="Setting_the_Fill_Tile_and_Stipple_">

+<title>Setting the Fill Tile and Stipple </title>

+<!-- .XS -->

+<!-- (SN Setting the Fill Tile and Stipple  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Some displays have hardware support for tiling or

+stippling with patterns of specific sizes.

+Tiling and stippling operations that restrict themselves to those specific

+sizes run much faster than such operations with arbitrary size patterns.

+Xlib provides functions that you can use to determine the best size, 

+tile, or stipple for the display

+as well as to set the tile or stipple shape and the tile or stipple origin.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the best size of a tile, stipple, or cursor, use

+<function>XQueryBestSize</function>.

+<indexterm significance="preferred"><primary>XQueryBestSize</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XQueryBestSize</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> class</parameter></paramdef>

+  <paramdef>Drawable<parameter> which_screen</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>class</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the class that you are interested in.

+You can pass 

+<function>TileShape</function>,

+<function>CursorShape</function>,

+or 

+<function>StippleShape</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>which_screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies any drawable on the screen.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Return the width and height of the object best supported 

+by the display hardware.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XQueryBestSize</function>

+function returns the best or closest size to the specified size.

+For 

+<function>CursorShape</function>,

+this is the largest size that can be fully displayed on the screen specified by

+which_screen.

+For 

+<function>TileShape</function>,

+this is the size that can be tiled fastest.

+For 

+<function>StippleShape</function>,

+this is the size that can be stippled fastest.

+For 

+<function>CursorShape</function>,

+the drawable indicates the desired screen.

+For 

+<function>TileShape </function>

+and 

+<function>StippleShape</function>,

+the drawable indicates the screen and possibly the window class and depth.

+An 

+<function>InputOnly </function>

+window cannot be used as the drawable for 

+<function>TileShape</function>

+or 

+<function>StippleShape</function>,

+or a

+<function>BadMatch </function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+<function>XQueryBestSize</function>

+can generate

+<function>BadDrawable</function>,

+<function>BadMatch</function>,

+and 

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the best fill tile shape, use

+<function>XQueryBestTile</function>.

+<indexterm significance="preferred"><primary>XQueryBestTile</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XQueryBestTile</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> which_screen</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>which_screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies any drawable on the screen.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Return the width and height of the object best supported 

+by the display hardware.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XQueryBestTile</function>

+function returns the best or closest size, that is, the size that can be

+tiled fastest on the screen specified by which_screen.

+The drawable indicates the screen and possibly the window class and depth.

+If an 

+<function>InputOnly </function>

+window is used as the drawable, a 

+<function>BadMatch </function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+<function>XQueryBestTile</function>

+can generate

+<function>BadDrawable</function>

+and

+<function>BadMatch </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the best stipple shape, use

+<function>XQueryBestStipple</function>.

+<indexterm significance="preferred"><primary>XQueryBestStipple</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XQueryBestStipple</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> which_screen</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>which_screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies any drawable on the screen.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Return the width and height of the object best supported 

+by the display hardware.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XQueryBestStipple</function>

+function returns the best or closest size, that is, the size that can be

+stippled fastest on the screen specified by which_screen.

+The drawable indicates the screen and possibly the window class and depth.

+If an

+<function>InputOnly</function>

+window is used as the drawable, a

+<function>BadMatch</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+<function>XQueryBestStipple</function>

+can generate

+<function>BadDrawable</function>

+and

+<function>BadMatch </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the fill tile of a given GC, use

+<function>XSetTile</function>.

+<indexterm significance="preferred"><primary>XSetTile</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetTile</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>Pixmap<parameter> tile</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>tile</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the fill tile you want to set for the specified GC. 

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The tile and GC must have the same depth,

+or a

+<function>BadMatch</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetTile</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadGC</function>,

+<function>BadMatch</function>,

+and

+<function>BadPixmap </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the stipple of a given GC, use

+<function>XSetStipple</function>.

+<indexterm significance="preferred"><primary>XSetStipple</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetStipple</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>Pixmap<parameter> stipple</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>stipple</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the stipple you want to set for the specified GC.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The stipple must have a depth of one,

+or a

+<function>BadMatch</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetStipple</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadGC</function>,

+<function>BadMatch</function>,

+and

+<function>BadPixmap </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the tile or stipple origin of a given GC, use

+<function>XSetTSOrigin</function>.

+<indexterm significance="preferred"><primary>XSetTSOrigin</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetTSOrigin</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intts_x_origin,<parameter> ts_y_origin</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ts_x_origin</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ts_y_origin</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates of the tile and stipple origin.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+When graphics requests call for tiling or stippling,

+the parent's origin will be interpreted relative to whatever destination 

+drawable is specified in the graphics request.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetTSOrigin</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadGC </function>

+errors.

+</para>

+</sect2>

+<sect2 id="Setting_the_Current_Font_">

+<title>Setting the Current Font </title>

+<!-- .XS -->

+<!-- (SN Setting the Current Font  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To set the current font of a given GC, use

+<function>XSetFont</function>.

+<indexterm significance="preferred"><primary>XSetFont</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetFont</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>Font<parameter> font</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the font.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<function>XSetFont</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadFont</function>,

+and 

+<function>BadGC </function>

+errors.

+</para>

+</sect2>

+<sect2 id="Setting_the_Clip_Region">

+<title>Setting the Clip Region</title>

+<!-- .XS -->

+<!-- (SN Setting the Clip Region  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to set the clip-origin 

+and the clip-mask or set the clip-mask to a list of rectangles.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the clip-origin of a given GC, use

+<function>XSetClipOrigin</function>.

+<indexterm significance="preferred"><primary>XSetClipOrigin</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetClipOrigin</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intclip_x_origin,<parameter> clip_y_origin</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>clip_x_origin</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>clip_y_origin</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates of the clip-mask origin.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The clip-mask origin is interpreted relative to the origin of whatever 

+destination drawable is specified in the graphics request.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetClipOrigin</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadGC </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the clip-mask of a given GC to the specified pixmap, use

+<function>XSetClipMask</function>.

+<indexterm significance="preferred"><primary>XSetClipMask</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetClipMask</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>Pixmap<parameter> pixmap</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>pixmap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the pixmap or

+<function>None</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If the clip-mask is set to

+<function>None</function>,

+the pixels are always drawn (regardless of the clip-origin).

+</para>

+<para>

+<!-- .LP -->

+<function>XSetClipMask</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadGC</function>,

+<function>BadMatch</function>,

+and

+<function>BadPixmap </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the clip-mask of a given GC to the specified list of rectangles, use

+<function>XSetClipRectangles</function>.

+<indexterm significance="preferred"><primary>XSetClipRectangles</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetClipRectangles</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intclip_x_origin,<parameter> clip_y_origin</parameter></paramdef>

+  <paramdef>XRectangle<parameter> rectangles[]\^</parameter></paramdef>

+  <paramdef>int<parameter> n</parameter></paramdef>

+  <paramdef>int<parameter> ordering</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>clip_x_origin</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>clip_y_origin</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates of the clip-mask origin.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>rectangles</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array of rectangles that define the clip-mask.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>n</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of rectangles. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ordering</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the ordering relations on the rectangles.

+You can pass

+<function>Unsorted</function>,

+<function>YSorted</function>,

+<function>YXSorted</function>,

+or

+<function>YXBanded</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetClipRectangles</function>

+function changes the clip-mask in the specified GC 

+to the specified list of rectangles and sets the clip origin.

+The output is clipped to remain contained within the

+rectangles.

+The clip-origin is interpreted relative to the origin of

+whatever destination drawable is specified in a graphics request.  

+The rectangle coordinates are interpreted relative to the clip-origin.  

+The rectangles should be nonintersecting, or the graphics results will be

+undefined.

+Note that the list of rectangles can be empty, 

+which effectively disables output.

+This is the opposite of passing

+<function>None</function>

+as the clip-mask in

+<function>XCreateGC</function>,

+<function>XChangeGC</function>,

+and

+<function>XSetClipMask</function>.

+</para>

+<para>

+<!-- .LP -->

+If known by the client, ordering relations on the rectangles can be

+specified with the ordering argument. 

+This may provide faster operation

+by the server. 

+If an incorrect ordering is specified, the X server may generate a

+<function>BadMatch</function>

+error, but it is not required to do so.

+If no error is generated, the graphics

+results are undefined.

+<function>Unsorted </function>

+means the rectangles are in arbitrary order.

+<function>YSorted </function>

+means that the rectangles are nondecreasing in their Y origin.

+<function>YXSorted </function>

+additionally constrains 

+<function>YSorted </function>

+order in that all

+rectangles with an equal Y origin are nondecreasing in their X

+origin.  

+<function>YXBanded </function>

+additionally constrains 

+<function>YXSorted </function>

+by requiring that,

+for every possible Y scanline, all rectangles that include that

+scanline have an identical Y origins and Y extents.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetClipRectangles</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadGC</function>,

+<function>BadMatch</function>,

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+Xlib provides a set of basic functions for performing

+region arithmetic.

+For information about these functions,

+see section 16.5.

+</para>

+</sect2>

+<sect2 id="Setting_the_Arc_Mode_Subwindow_Mode_and_Graphics_Exposure_">

+<title>Setting the Arc Mode, Subwindow Mode, and Graphics Exposure </title>

+<!-- .XS -->

+<!-- (SN Setting the Arc Mode, Subwindow Mode, and Graphics Exposure  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To set the arc mode of a given GC, use

+<function>XSetArcMode</function>.

+<indexterm significance="preferred"><primary>XSetArcMode</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetArcMode</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>int<parameter> arc_mode</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>arc_mode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the arc mode.

+You can pass

+<function>ArcChord</function>

+or

+<function>ArcPieSlice</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<function>XSetArcMode</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadGC</function>,

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the subwindow mode of a given GC, use

+<function>XSetSubwindowMode</function>.

+<indexterm significance="preferred"><primary>XSetSubwindowMode</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetSubwindowMode</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>int<parameter> subwindow_mode</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>subwindow_mode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the subwindow mode.

+You can pass

+<function>ClipByChildren</function>

+or

+<function>IncludeInferiors</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<function>XSetSubwindowMode</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadGC</function>,

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the graphics-exposures flag of a given GC, use

+<function>XSetGraphicsExposures</function>.

+<indexterm significance="preferred"><primary>XSetGraphicsExposures</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetGraphicsExposures</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>Bool<parameter> graphics_exposures</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>graphics_exposures</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a Boolean value that indicates whether you want

+<function>GraphicsExpose</function>

+and

+<function>NoExpose</function>

+events to be reported when calling

+<function>XCopyArea</function>

+and

+<function>XCopyPlane</function>

+with this GC.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<function>XSetGraphicsExposures</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadGC</function>,

+and

+<function>BadValue </function>

+errors.

+<!-- .bp -->

+

+</para>

+</sect2>

+</sect1>

+</chapter>

diff --git a/libX11/specs/libX11/CH08 b/libX11/specs/libX11/CH08
deleted file mode 100644
index 3d2161fb2..000000000
--- a/libX11/specs/libX11/CH08
+++ /dev/null
@@ -1,3468 +0,0 @@
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-.\" OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" Except as contained in this notice, the name of the X Consortium shall
-.\" not be used in advertising or otherwise to promote the sale, use or
-.\" other dealings in this Software without prior written authorization
-.\" from the X Consortium.
-.\"
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
-.\" Digital Equipment Corporation
-.\"
-.\" Portions Copyright \(co 1990, 1991 by
-.\" Tektronix, Inc.
-.\"
-.\" Permission to use, copy, modify and distribute this documentation for
-.\" any purpose and without fee is hereby granted, provided that the above
-.\" copyright notice appears in all copies and that both that copyright notice
-.\" and this permission notice appear in all copies, and that the names of
-.\" Digital and Tektronix not be used in in advertising or publicity pertaining
-.\" to this documentation without specific, written prior permission.
-.\" Digital and Tektronix makes no representations about the suitability
-.\" of this documentation for any purpose.
-.\" It is provided ``as is'' without express or implied warranty.
-.\" 
-\&
-.sp 1
-.ce 3
-\s+1\fBChapter 8\fP\s-1
-
-\s+1\fBGraphics Functions\fP\s-1
-.sp 2
-.nr H1 8
-.nr H2 0
-.nr H3 0
-.nr H4 0
-.nr H5 0
-.na
-.LP
-.XS
-Chapter 8: Graphics Functions 
-.XE
-Once you have established a connection to a display,
-you can use the Xlib graphics functions to:
-.IP \(bu 5
-Clear and copy areas
-.IP \(bu 5
-Draw points, lines, rectangles, and arcs
-.IP \(bu 5
-Fill areas
-.IP \(bu 5
-Manipulate fonts
-.IP \(bu 5
-Draw text
-.IP \(bu 5
-Transfer images between clients and the server
-.LP
-If the same drawable and GC is used for each call,
-Xlib batches back-to-back calls to
-.PN XDrawPoint ,
-.PN XDrawLine ,
-.PN XDrawRectangle ,
-.PN XFillArc ,
-and
-.PN XFillRectangle .
-Note that this reduces the total number of requests sent to the server.
-.NH 2
-Clearing Areas
-.XS
-\*(SN Clearing Areas 
-.XE
-.LP
-Xlib provides functions that you can use to clear an area or the entire window.
-Because pixmaps do not have defined backgrounds, 
-they cannot be filled by using the functions described in this section.
-Instead, to accomplish an analogous operation on a pixmap,
-you should use 
-.PN XFillRectangle ,
-which sets the pixmap to a known value.
-.LP
-.sp
-To clear a rectangular area of a given window, use
-.PN XClearArea .
-.IN "Areas" "clearing"
-.IN "Clearing" "areas"
-.IN "XClearArea" "" "@DEF@"
-.sM
-.FD 0
-XClearArea\^(\^\fIdisplay\fP, \fIw\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIexposures\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.br
-      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
-.br
-      Bool \fIexposures\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.ds Xy , which are relative to the origin of the window \
-and specify the upper-left corner of the rectangle
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.ds Wh , which are the dimensions of the rectangle
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height\*(Wh.
-.IP \fIexposures\fP 1i
-Specifies a Boolean value that indicates if
-.PN Expose
-events are to be generated.
-.LP
-.eM
-The
-.PN XClearArea
-function paints a rectangular area in the specified window according to the
-specified dimensions with the window's background pixel or pixmap.
-The subwindow-mode effectively is
-.PN ClipByChildren . 
-If width is zero, it
-is replaced with the current width of the window minus x.
-If height is
-zero, it is replaced with the current height of the window minus y.
-If the window has a defined background tile, 
-the rectangle clipped by any children is filled with this tile.
-If the window has
-background 
-.PN None , 
-the contents of the window are not changed.  
-In either
-case, if exposures is 
-.PN True , 
-one or more 
-.PN Expose 
-events are generated for regions of the rectangle that are either visible or are
-being retained in a backing store.
-If you specify a window whose class is
-.PN InputOnly ,
-a
-.PN BadMatch
-error results.
-.LP
-.PN XClearArea
-can generate
-.PN BadMatch ,
-.PN BadValue ,
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To clear the entire area in a given window, use
-.PN XClearWindow .
-.IN "Window" "clearing"
-.IN "Clearing" "windows"
-.IN "XClearWindow" "" "@DEF@"
-.sM
-.FD 0
-XClearWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.LP
-.eM
-The
-.PN XClearWindow
-function clears the entire area in the specified window and is
-equivalent to
-.PN XClearArea
-(display, w, 0, 0, 0, 0, 
-.PN False ).
-If the window has a defined background tile, the rectangle is tiled with a
-plane-mask of all ones and 
-.PN GXcopy
-function.
-If the window has
-background 
-.PN None , 
-the contents of the window are not changed.  
-If you specify a window whose class is
-.PN InputOnly ,
-a
-.PN BadMatch
-error results. 
-.LP
-.PN XClearWindow
-can generate
-.PN BadMatch
-and
-.PN BadWindow 
-errors.
-.NH 2
-Copying Areas
-.XS
-\*(SN Copying Areas 
-.XE
-.LP
-Xlib provides functions that you can use to copy an area or a bit plane.
-.LP
-.sp
-To copy an area between drawables of the same
-root and depth, use
-.PN XCopyArea .
-.IN "Areas" "copying"
-.IN "Copying" "areas"
-.IN "XCopyArea" "" "@DEF@"
-.sM
-.FD 0
-XCopyArea\^(\^\fIdisplay\fP, \fIsrc\fP\^, \fIdest\fP\^, \fIgc\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIwidth\fP\^, \fIheight\fP\^,  \fIdest_x\fP\^, \fIdest_y\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fIsrc\fP\^, \fIdest\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIsrc_x\fP\^, \fIsrc_y\fP\^;
-.br
-      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
-.br
-      int \fIdest_x\fP\^, \fIdest_y\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIsrc\fP 1i
-.br
-.ns
-.IP \fIdest\fP 1i
-Specify the source and destination rectangles to be combined. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIsrc_x\fP 1i
-.br
-.ns
-.IP \fIsrc_y\fP 1i
-Specify the x and y coordinates, 
-which are relative to the origin of the source rectangle
-and specify its upper-left corner.
-.ds Wh , which are the dimensions of both the source \
-and destination rectangles
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height\*(Wh.
-.ds Dx , which are relative to the origin of the destination rectangle \
-and specify its upper-left corner
-.IP \fIdest_x\fP 1i
-.br
-.ns
-.IP \fIdest_y\fP 1i
-Specify the x and y coordinates\*(Dx. 
-.LP
-.eM
-The
-.PN XCopyArea
-function combines the specified rectangle of src with the specified rectangle 
-of dest.
-The drawables must have the same root and depth,
-or a
-.PN BadMatch
-error results.
-.LP
-If regions of the source rectangle are obscured and have not been
-retained in backing store 
-or if regions outside the boundaries of the source drawable are specified, 
-those regions are not copied. 
-Instead, the 
-following occurs on all corresponding destination regions that are either
-visible or are retained in backing store.  
-If the destination is a window with a background other than 
-.PN None , 
-corresponding regions
-of the destination are tiled with that background
-(with plane-mask of all ones and
-.PN GXcopy 
-function).
-Regardless of tiling or whether the destination is a window or a pixmap,
-if graphics-exposures is 
-.PN True ,
-then
-.PN GraphicsExpose
-events for all corresponding destination regions are generated.
-If graphics-exposures is 
-.PN True 
-but no
-.PN GraphicsExpose
-events are generated, a
-.PN NoExpose 
-event is generated.
-Note that by default graphics-exposures is
-.PN True
-in new GCs.
-.LP
-This function uses these GC components: function, plane-mask, 
-subwindow-mode, graphics-exposures, clip-x-origin,
-clip-y-origin, and clip-mask.
-.LP
-.PN XCopyArea
-can generate
-.PN BadDrawable ,
-.PN BadGC ,
-and
-.PN BadMatch 
-errors.
-.sp
-.LP
-To copy a single bit plane of a given drawable, use
-.PN XCopyPlane .
-.IN "Plane" "copying"
-.IN "Copying" "planes"
-.IN "XCopyPlane" "" "@DEF@"
-.sM
-.FD 0
-XCopyPlane\^(\^\fIdisplay\fP, \fIsrc\fP\^, \fIdest\fP\^, \fIgc\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIdest_x\fP\^, \fIdest_y\fP\^, \fIplane\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fIsrc\fP\^, \fIdest\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIsrc_x\fP\^, \fIsrc_y\fP\^;
-.br
-      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
-.br
-      int \fIdest_x\fP\^, \fIdest_y\fP\^;
-.br
-      unsigned long \fIplane\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIsrc\fP 1i
-.br
-.ns
-.IP \fIdest\fP 1i
-Specify the source and destination rectangles to be combined. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIsrc_x\fP 1i
-.br
-.ns
-.IP \fIsrc_y\fP 1i
-Specify the x and y coordinates, 
-which are relative to the origin of the source rectangle
-and specify its upper-left corner.
-.ds Wh , which are the dimensions of both the source and destination rectangles
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height\*(Wh.
-.ds Dx , which are relative to the origin of the destination rectangle \
-and specify its upper-left corner
-.IP \fIdest_x\fP 1i
-.br
-.ns
-.IP \fIdest_y\fP 1i
-Specify the x and y coordinates\*(Dx. 
-.IP \fIplane\fP 1i
-Specifies the bit plane.
-You must set exactly one bit to 1.
-.LP
-.eM
-The
-.PN XCopyPlane
-function uses a single bit plane of the specified source rectangle
-combined with the specified GC to modify the specified rectangle of dest.
-The drawables must have the same root but need not have the same depth.
-If the drawables do not have the same root, a
-.PN BadMatch
-error results.
-If plane does not have exactly one bit set to 1 and the value of plane
-is not less than %2 sup n%, where \fIn\fP is the depth of src, a
-.PN BadValue
-error results.
-.LP
-Effectively, 
-.PN XCopyPlane
-forms a pixmap of the same depth as the rectangle of dest and with a
-size specified by the source region. 
-It uses the foreground/background pixels in the GC (foreground
-everywhere the bit plane in src contains a bit set to 1,
-background everywhere the bit plane in src contains a bit set to 0)
-and the equivalent of a 
-.PN CopyArea
-protocol request is performed with all the same exposure semantics.
-This can also be thought of as using the specified region of the source 
-bit plane as a stipple with a fill-style of
-.PN FillOpaqueStippled
-for filling a rectangular area of the destination.
-.LP
-This function uses these GC components: function, plane-mask, foreground,
-background, subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin,
-and clip-mask.
-.LP
-.PN XCopyPlane
-can generate
-.PN BadDrawable ,
-.PN BadGC ,
-.PN BadMatch ,
-and 
-.PN BadValue 
-errors.
-.NH 2
-Drawing Points, Lines, Rectangles, and Arcs
-.XS
-\*(SN Drawing Points, Lines, Rectangles, and Arcs 
-.XE
-.LP
-Xlib provides functions that you can use to draw:
-.IP \(bu 5
-A single point or multiple points
-.IP \(bu 5
-A single line or multiple lines
-.IP \(bu 5
-A single rectangle or multiple rectangles
-.IP \(bu 5
-A single arc or multiple arcs
-.LP
-Some of the functions described in the following sections
-use these structures:
-.LP
-.IN "XSegment" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i
-.ta .5i
-typedef struct {
-	short x1, y1, x2, y2;
-} XSegment;
-.De
-.LP
-.eM
-.IN "XPoint" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i
-.ta .5i
-typedef struct {
-	short x, y;
-} XPoint;
-.De
-.LP
-.eM
-.IN "XRectangle" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i
-.ta .5i
-typedef struct {
-	short x, y;
-	unsigned short width, height;
-} XRectangle;
-.De
-.LP
-.eM
-.IN "XArc" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	short x, y;
-	unsigned short width, height;
-	short angle1, angle2;             /* Degrees * 64 */
-} XArc;
-.De
-.LP
-.eM
-All x and y members are signed integers.
-The width and height members are 16-bit unsigned integers.
-You should be careful not to generate coordinates and sizes
-out of the 16-bit ranges, because the protocol only has 16-bit fields
-for these values.
-.NH 3
-Drawing Single and Multiple Points
-.XS
-\*(SN Drawing Single and Multiple Points 
-.XE
-.LP
-.IN "Points" "drawing"
-.IN "Drawing" "points"
-.IN "XDrawPoints"
-.IN "XDrawPoint"
-.LP
-To draw a single point in a given drawable, use
-.PN XDrawPoint .
-.IN "XDrawPoint" "" "@DEF@"
-.sM
-.FD 0
-XDrawPoint\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates where you want the point drawn.
-.LP
-.eM
-.sp
-To draw multiple points in a given drawable, use
-.PN XDrawPoints .
-.IN "XDrawPoints" "" "@DEF@"
-.sM
-.FD 0
-XDrawPoints\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIpoints\fP\^, \fInpoints\fP\^, \fImode\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      XPoint *\fIpoints\fP\^;
-.br
-      int \fInpoints\fP\^;
-.br
-      int \fImode\fP\^; 
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIpoints\fP 1i
-Specifies an array of points.
-.IP \fInpoints\fP 1i
-Specifies the number of points in the array.
-.IP \fImode\fP 1i
-Specifies the coordinate mode. 
-You can pass
-.PN CoordModeOrigin
-or
-.PN CoordModePrevious .
-.LP
-.eM
-The
-.PN XDrawPoint
-function uses the foreground pixel and function components of the
-GC to draw a single point into the specified drawable; 
-.PN XDrawPoints
-draws multiple points this way.
-.PN CoordModeOrigin
-treats all coordinates as relative to the origin,
-and
-.PN CoordModePrevious
-treats all coordinates after the first as relative to the previous point.
-.PN XDrawPoints
-draws the points in the order listed in the array.
-.LP
-Both functions use these GC components: function, plane-mask,
-foreground, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
-.LP
-.PN XDrawPoint
-can generate
-.PN BadDrawable ,
-.PN BadGC ,
-and 
-.PN BadMatch 
-errors.
-.PN XDrawPoints
-can generate
-.PN BadDrawable ,
-.PN BadGC ,
-.PN BadMatch ,
-and
-.PN BadValue 
-errors.
-.NH 3
-Drawing Single and Multiple Lines
-.XS
-\*(SN Drawing Single and Multiple Lines
-.XE
-.LP
-.IN "Lines" "drawing"
-.IN "Drawing" "lines"
-.IN "XDrawLine"
-.IN "XDrawLines"
-.IN "Polygons" "drawing"
-.IN "Drawing" "polygons"
-.IN "XDrawSegments"
-.LP
-To draw a single line between two points in a given drawable, use
-.PN XDrawLine .
-.IN "XDrawLine" "" "@DEF@"
-.sM
-.FD 0
-XDrawLine\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx1\fP\^, \fIy1\fP\^, \fIx2\fP\^, \fIy2\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIx1\fP\^, \fIy1\fP\^, \fIx2\fP\^, \fIy2\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIx1\fP 1i
-.br
-.ns
-.IP \fIy1\fP 1i
-.br
-.ns
-.IP \fIx2\fP 1i
-.br
-.ns
-.IP \fIy2\fP 1i
-Specify the points (x1, y1) and (x2, y2) to be connected.
-.LP
-.eM
-.sp
-To draw multiple lines in a given drawable, use
-.PN XDrawLines .
-.IN "XDrawLines" "" "@DEF@"
-.sM
-.FD 0
-XDrawLines\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIpoints\fP\^, \fInpoints\fP\^, \fImode\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      XPoint *\fIpoints\fP\^;
-.br
-      int \fInpoints\fP\^;
-.br
-      int \fImode\fP\^; 
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIpoints\fP 1i
-Specifies an array of points.
-.IP \fInpoints\fP 1i
-Specifies the number of points in the array.
-.IP \fImode\fP 1i
-Specifies the coordinate mode. 
-You can pass
-.PN CoordModeOrigin
-or
-.PN CoordModePrevious .
-.LP
-.eM
-.sp
-To draw multiple, unconnected lines in a given drawable,
-use
-.PN XDrawSegments .
-.IN "XDrawSegments" "" "@DEF@"
-.sM
-.FD 0
-XDrawSegments\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIsegments\fP\^, \fInsegments\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      XSegment *\fIsegments\fP\^;
-.br
-      int \fInsegments\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIsegments\fP 1i
-Specifies an array of segments.
-.IP \fInsegments\fP 1i
-Specifies the number of segments in the array.
-.LP
-.eM
-The
-.PN XDrawLine
-function uses the components of the specified GC to
-draw a line between the specified set of points (x1, y1) and (x2, y2).
-It does not perform joining at coincident endpoints.
-For any given line, 
-.PN XDrawLine 
-does not draw a pixel more than once.
-If lines intersect, the intersecting pixels are drawn multiple times.  
-.LP
-The
-.PN XDrawLines
-function uses the components of the specified GC to draw 
-npoints\-1 lines between each pair of points (point[i], point[i+1]) 
-in the array of
-.PN XPoint
-structures.
-It draws the lines in the order listed in the array.
-The lines join correctly at all intermediate points, and if the first and last
-points coincide, the first and last lines also join correctly.
-For any given line, 
-.PN XDrawLines
-does not draw a pixel more than once.
-If thin (zero line-width) lines intersect, 
-the intersecting pixels are drawn multiple times.
-If wide lines intersect, the intersecting pixels are drawn only once, as though
-the entire 
-.PN PolyLine 
-protocol request were a single, filled shape.
-.PN CoordModeOrigin
-treats all coordinates as relative to the origin,
-and
-.PN CoordModePrevious
-treats all coordinates after the first as relative to the previous point.
-.LP
-The
-.PN XDrawSegments 
-function draws multiple, unconnected lines. 
-For each segment, 
-.PN XDrawSegments 
-draws a
-line between (x1, y1) and (x2, y2).
-It draws the lines in the order listed in the array of
-.PN XSegment
-structures and does not perform joining at coincident endpoints.
-For any given line, 
-.PN XDrawSegments
-does not draw a pixel more than once.  
-If lines intersect, the intersecting pixels are drawn multiple times.  
-.LP
-All three functions use these GC components:
-function, plane-mask, line-width,
-line-style, cap-style, fill-style, subwindow-mode,
-clip-x-origin, clip-y-origin, and clip-mask.
-The
-.PN XDrawLines
-function also uses the join-style GC component.
-All three functions also use these GC mode-dependent components:
-foreground, background, tile, stipple, tile-stipple-x-origin, 
-tile-stipple-y-origin, dash-offset, and dash-list.
-.LP
-.PN XDrawLine ,
-.PN XDrawLines ,
-and
-.PN XDrawSegments
-can generate
-.PN BadDrawable ,
-.PN BadGC ,
-and
-.PN BadMatch 
-errors.
-.PN XDrawLines
-also can generate
-.PN BadValue 
-errors.
-.NH 3
-Drawing Single and Multiple Rectangles 
-.XS
-\*(SN Drawing Single and Multiple Rectangles 
-.XE
-.LP
-.IN "Rectangles" "drawing"
-.IN "Drawing" "rectangles"
-.IN "XDrawRectangle"
-.IN "XDrawRectangles"
-.LP
-To draw the outline of a single rectangle in a given drawable, use
-.PN XDrawRectangle .
-.IN "XDrawRectangle" "" "@DEF@"
-.sM
-.FD 0
-XDrawRectangle\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.br
-      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.ds Xy , which specify the upper-left corner of the rectangle
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.ds Wh , which specify the dimensions of the rectangle
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height\*(Wh.
-.LP
-.eM
-.sp
-To draw the outline of multiple rectangles
-in a given drawable, use
-.PN XDrawRectangles .
-.IN "XDrawRectangles" "" "@DEF@"
-.sM
-.FD 0
-XDrawRectangles\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIrectangles\fP\^, \fInrectangles\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      XRectangle \fIrectangles\fP\^[\^]\^;
-.br
-      int \fInrectangles\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIrectangles\fP 1i
-Specifies an array of rectangles.
-.IP \fInrectangles\fP 1i
-Specifies the number of rectangles in the array.
-.LP
-.eM
-The
-.PN XDrawRectangle
-and
-.PN XDrawRectangles
-functions draw the outlines of the specified rectangle or rectangles as
-if a five-point 
-.PN PolyLine 
-protocol request were specified for each rectangle:
-.IP
-[x,y] [x+width,y] [x+width,y+height] [x,y+height] [x,y]
-.LP 
-For the specified rectangle or rectangles, 
-these functions do not draw a pixel more than once.
-.PN XDrawRectangles
-draws the rectangles in the order listed in the array.
-If rectangles intersect,
-the intersecting pixels are drawn multiple times.
-.LP
-Both functions use these GC components: 
-function, plane-mask, line-width,
-line-style, cap-style, join-style, fill-style, 
-subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
-They also use these GC mode-dependent components: 
-foreground, background, tile, stipple, tile-stipple-x-origin, 
-tile-stipple-y-origin, dash-offset, and dash-list.
-.LP
-.PN XDrawRectangle
-and
-.PN XDrawRectangles
-can generate
-.PN BadDrawable ,
-.PN BadGC ,
-and
-.PN BadMatch 
-errors.
-.NH 3
-Drawing Single and Multiple Arcs
-.XS
-\*(SN Drawing Single and Multiple Arcs 
-.XE
-.LP
-.IN "Drawing" "arcs"
-.IN "XDrawArc"
-.IN "Arcs" "drawing"
-.IN "XDrawArcs"
-.LP
-.sp
-To draw a single arc in a given drawable, use
-.PN XDrawArc .
-.IN "XDrawArc" "" "@DEF@"
-.sM
-.FD 0
-XDrawArc\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIangle1\fP\^, \fIangle2\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.br
-      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
-.br
-      int \fIangle1\fP\^, \fIangle2\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.ds Xy , which are relative to the origin of the drawable \
-and specify the upper-left corner of the bounding rectangle
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.ds Wh , which are the major and minor axes of the arc
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height\*(Wh.
-.IP \fIangle1\fP 1i
-Specifies the start of the arc relative to the three-o'clock position
-from the center, in units of degrees * 64.
-.IP \fIangle2\fP 1i
-Specifies the path and extent of the arc relative to the start of the
-arc, in units of degrees * 64.
-.LP
-.eM
-.sp
-To draw multiple arcs in a given drawable, use
-.PN XDrawArcs .
-.IN "XDrawArcs" "" "@DEF@"
-.sM
-.FD 0
-XDrawArcs\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIarcs\fP\^, \fInarcs\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      XArc *\fIarcs\fP\^;
-.br
-      int \fInarcs\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIarcs\fP 1i
-Specifies an array of arcs.
-.IP \fInarcs\fP 1i
-Specifies the number of arcs in the array.
-.LP
-.eM
-.EQ
-delim %%
-.EN
-.PN XDrawArc
-draws a single circular or elliptical arc, and 
-.PN XDrawArcs
-draws multiple circular or elliptical arcs.
-Each arc is specified by a rectangle and two angles.  
-The center of the circle or ellipse is the center of the
-rectangle, and the major and minor axes are specified by the width and height.
-Positive angles indicate counterclockwise motion, 
-and negative angles indicate clockwise motion.  
-If the magnitude of angle2 is greater than 360 degrees, 
-.PN XDrawArc
-or 
-.PN XDrawArcs
-truncates it to 360 degrees.
-.LP
-For an arc specified as %[ ~x, ~y, ~width , ~height, ~angle1, ~angle2 ]%, 
-the origin of the major and minor axes is at 
-% [ x +^ {width over 2} , ~y +^ {height over 2}  ]%, 
-and the infinitely thin path describing the entire circle or ellipse 
-intersects the horizontal axis at % [ x, ~y +^ {height over 2}  ]% and 
-% [ x +^ width , ~y +^ { height over 2 }] %
-and intersects the vertical axis at % [ x +^ { width over 2 } , ~y ]% and 
-% [ x +^ { width over 2 }, ~y +^ height ]%.
-These coordinates can be fractional
-and so are not truncated to discrete coordinates.
-The path should be defined by the ideal mathematical path.  
-For a wide line with line-width lw, 
-the bounding outlines for filling are given        
-by the two infinitely thin paths consisting of all points whose perpendicular
-distance from the path of the circle/ellipse is equal to lw/2
-(which may be a fractional value).
-The cap-style and join-style are applied the same as for a line
-corresponding to the tangent of the circle/ellipse at the endpoint.
-.LP
-For an arc specified as % [ ~x, ~y, ~width, ~height, ~angle1, ~angle2  ]%,
-the angles must be specified
-in the effectively skewed coordinate system of the ellipse (for a
-circle, the angles and coordinate systems are identical).  The
-relationship between these angles and angles expressed in the normal
-coordinate system of the screen (as measured with a protractor) is as
-follows:
-.LP
-.Ds
-% roman "skewed-angle" ~ = ~ atan left ( tan ( roman "normal-angle" )
- * width over height right ) +^ adjust%
-.De
-.LP
-The skewed-angle and normal-angle are expressed in radians (rather
-than in degrees scaled by 64) in the range % [ 0 , ~2 pi  ]% and where atan
-returns a value in the range % [ - pi over 2 , ~pi over 2  ] %
-and adjust is:
-.LP
-.Ds
-.TA 1i 2i
-.ta 1i 2i
-%0%	for normal-angle in the range % [ 0 , ~pi over 2  ]%
-%pi%	for normal-angle in the range % [ pi over 2 , ~{3 pi} over 2  ]%
-%2 pi%	for normal-angle in the range % [ {3 pi} over 2 , ~2 pi  ]%
-.De
-.LP
-For any given arc, 
-.PN XDrawArc
-and
-.PN XDrawArcs
-do not draw a pixel more than once.  
-If two arcs join correctly and if the line-width is greater than zero 
-and the arcs intersect, 
-.PN XDrawArc
-and
-.PN XDrawArcs
-do not draw a pixel more than once.
-Otherwise, 
-the intersecting pixels of intersecting arcs are drawn multiple times.
-Specifying an arc with one endpoint and a clockwise extent draws the same pixels
-as specifying the other endpoint and an equivalent counterclockwise extent,
-except as it affects joins.
-.LP
-If the last point in one arc coincides with the first point in the following 
-arc, the two arcs will join correctly.  
-If the first point in the first arc coincides with the last point in the last 
-arc, the two arcs will join correctly.
-By specifying one axis to be zero, a horizontal or vertical line can be
-drawn.
-Angles are computed based solely on the coordinate system and ignore the
-aspect ratio.
-.LP
-Both functions use these GC components: 
-function, plane-mask, line-width, line-style, cap-style, join-style, 
-fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
-They also use these GC mode-dependent components: 
-foreground, background, tile, stipple, tile-stipple-x-origin, 
-tile-stipple-y-origin, dash-offset, and dash-list.
-.LP
-.PN XDrawArc
-and
-.PN XDrawArcs
-can generate
-.PN BadDrawable ,
-.PN BadGC ,
-and
-.PN BadMatch 
-errors.
-.NH 2
-Filling Areas
-.XS
-\*(SN Filling Areas 
-.XE
-.LP
-Xlib provides functions that you can use to fill:
-.IP \(bu 5
-A single rectangle or multiple rectangles
-.IP \(bu 5
-A single polygon
-.IP \(bu 5
-A single arc or multiple arcs
-.NH 3
-Filling Single and Multiple Rectangles
-.XS
-\*(SN Filling Single and Multiple Rectangles 
-.XE
-.LP
-.IN "Filling" "rectangles"
-.IN "XFillRectangle"
-.IN "Rectangle" "filling"
-.IN "XFillRectangles"
-.LP
-.sp
-To fill a single rectangular area in a given drawable, use
-.PN XFillRectangle .
-.IN "XFillRectangle" "" "@DEF@"
-.sM
-.FD 0 
-XFillRectangle\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.br
-      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.ds Xy , which are relative to the origin of the drawable \
-and specify the upper-left corner of the rectangle
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.ds Wh , which are the dimensions of the rectangle to be filled
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height\*(Wh.
-.LP
-.eM
-.sp
-To fill multiple rectangular areas in a given drawable, use
-.PN XFillRectangles .
-.IN "XFillRectangles" "" "@DEF@"
-.sM
-.FD 0 
-XFillRectangles\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIrectangles\fP\^, \fInrectangles\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      XRectangle *\fIrectangles\fP\^;
-.br
-      int \fInrectangles\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIrectangles\fP 1i
-Specifies an array of rectangles.
-.IP \fInrectangles\fP 1i
-Specifies the number of rectangles in the array.
-.LP
-.eM
-The
-.PN XFillRectangle
-and
-.PN XFillRectangles
-functions fill the specified rectangle or rectangles
-as if a four-point 
-.PN FillPolygon
-protocol request were specified for each rectangle:
-.LP
-.Ds
-[x,y] [x+width,y] [x+width,y+height] [x,y+height]
-.De
-.LP
-Each function uses the x and y coordinates,
-width and height dimensions, and GC you specify.
-.LP
-.PN XFillRectangles
-fills the rectangles in the order listed in the array.  
-For any given rectangle,
-.PN XFillRectangle
-and
-.PN XFillRectangles
-do not draw a pixel more than once.  
-If rectangles intersect, the intersecting pixels are
-drawn multiple times.
-.LP
-Both functions use these GC components: 
-function, plane-mask, fill-style, subwindow-mode, 
-clip-x-origin, clip-y-origin, and clip-mask.
-They also use these GC mode-dependent components: 
-foreground, background, tile, stipple, tile-stipple-x-origin, 
-and tile-stipple-y-origin.
-.LP
-.PN XFillRectangle
-and
-.PN XFillRectangles
-can generate
-.PN BadDrawable ,
-.PN BadGC ,
-and
-.PN BadMatch 
-errors.
-.NH 3
-Filling a Single Polygon
-.XS
-\*(SN Filling a Single Polygon 
-.XE
-.LP
-.sp
-To fill a polygon area in a given drawable, use
-.PN XFillPolygon .
-.IN "Polygons" "filling"
-.IN "Filling" "polygon"
-.IN "XFillPolygon" "" "@DEF@"
-.sM
-.FD 0 
-XFillPolygon\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIpoints\fP\^, \fInpoints\fP\^, \fIshape\fP\^, \fImode\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      XPoint *\fIpoints\fP\^;
-.br
-      int \fInpoints\fP\^;
-.br
-      int \fIshape\fP\^; 
-.br
-      int \fImode\fP\^; 
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIpoints\fP 1i
-Specifies an array of points.
-.IP \fInpoints\fP 1i
-Specifies the number of points in the array.
-.IP \fIshape\fP 1i
-Specifies a shape that helps the server to improve performance.
-You can pass 
-.PN Complex , 
-.PN Convex , 
-or 
-.PN Nonconvex .
-.IP \fImode\fP 1i
-Specifies the coordinate mode. 
-You can pass
-.PN CoordModeOrigin
-or
-.PN CoordModePrevious .
-.LP
-.eM
-.PN XFillPolygon 
-fills the region closed by the specified path.
-The path is closed
-automatically if the last point in the list does not coincide with the
-first point.
-.PN XFillPolygon
-does not draw a pixel of the region more than once.
-.PN CoordModeOrigin
-treats all coordinates as relative to the origin,
-and
-.PN CoordModePrevious
-treats all coordinates after the first as relative to the previous point.
-.LP
-Depending on the specified shape, the following occurs: 
-.IP \(bu 5
-If shape is
-.PN Complex , 
-the path may self-intersect. 
-Note that contiguous coincident points in the path are not treated 
-as self-intersection.
-.IP \(bu 5
-If shape is
-.PN Convex , 
-for every pair of points inside the polygon,
-the line segment connecting them does not intersect the path.
-If known by the client,
-specifying 
-.PN Convex 
-can improve performance.  
-If you specify
-.PN Convex 
-for a path that is not convex, 
-the graphics results are undefined.
-.IP \(bu 5
-If shape is
-.PN Nonconvex , 
-the path does not self-intersect, but the shape is not
-wholly convex. 
-If known by the client, 
-specifying 
-.PN Nonconvex 
-instead of
-.PN Complex 
-may improve performance.  
-If you specify
-.PN Nonconvex 
-for a self-intersecting path, the graphics results are undefined.
-.LP
-The fill-rule of the GC controls the filling behavior of 
-self-intersecting polygons.
-.LP
-This function uses these GC components: 
-function, plane-mask, fill-style, fill-rule, subwindow-mode, clip-x-origin, 
-clip-y-origin, and clip-mask.
-It also uses these GC mode-dependent components: 
-foreground, background, tile, stipple, tile-stipple-x-origin, 
-and tile-stipple-y-origin.
-.LP
-.PN XFillPolygon
-can generate
-.PN BadDrawable ,
-.PN BadGC ,
-.PN BadMatch ,
-and
-.PN BadValue 
-errors.
-.NH 3
-Filling Single and Multiple Arcs
-.XS
-\*(SN Filling Single and Multiple Arcs 
-.XE
-.LP
-.IN "XFillArc"
-.IN "Arcs" "filling"
-.IN "Filling" "arcs"
-To fill a single arc in a given drawable, use
-.PN XFillArc .
-.IN "XFillArc" "" "@DEF@"
-.sM
-.FD 0
-XFillArc\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^,  \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIangle1\fP\^, \fIangle2\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.br
-      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
-.br
-      int \fIangle1\fP\^, \fIangle2\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.ds Xy , which are relative to the origin of the drawable \
-and specify the upper-left corner of the bounding rectangle
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.ds Wh , which are the major and minor axes of the arc
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height\*(Wh.
-.IP \fIangle1\fP 1i
-Specifies the start of the arc relative to the three-o'clock position
-from the center, in units of degrees * 64.
-.IP \fIangle2\fP 1i
-Specifies the path and extent of the arc relative to the start of the
-arc, in units of degrees * 64.
-.LP
-.eM
-.sp
-To fill multiple arcs in a given drawable, use
-.PN XFillArcs .
-.IN "XFillArcs" "" "@DEF@"
-.sM
-.FD 0
-XFillArcs\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIarcs\fP\^, \fInarcs\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      XArc *\fIarcs\fP\^;
-.br
-      int \fInarcs\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIarcs\fP 1i
-Specifies an array of arcs.
-.IP \fInarcs\fP 1i
-Specifies the number of arcs in the array.
-.LP
-.eM
-For each arc, 
-.PN XFillArc
-or
-.PN XFillArcs
-fills the region closed by the infinitely thin path
-described by the specified arc and, depending on the 
-arc-mode specified in the GC, one or two line segments. 
-For 
-.PN ArcChord , 
-the single line segment joining the endpoints of the arc is used.  
-For 
-.PN ArcPieSlice ,
-the two line segments joining the endpoints of the arc with the center
-point are used.  
-.PN XFillArcs
-fills the arcs in the order listed in the array.  
-For any given arc,  
-.PN XFillArc
-and
-.PN XFillArcs
-do not draw a pixel more than once.  
-If regions intersect, 
-the intersecting pixels are drawn multiple times.
-.LP
-Both functions use these GC components: 
-function, plane-mask, fill-style, arc-mode, subwindow-mode, clip-x-origin, 
-clip-y-origin, and clip-mask.
-They also use these GC mode-dependent components: 
-foreground, background, tile, stipple, tile-stipple-x-origin, 
-and tile-stipple-y-origin.
-.LP
-.PN XFillArc
-and
-.PN XFillArcs
-can generate
-.PN BadDrawable ,
-.PN BadGC ,
-and
-.PN BadMatch 
-errors.
-.NH 2
-Font Metrics
-.XS
-\*(SN Font Metrics 
-.XE
-.LP
-.IN "Font"
-A font is a graphical description of a set of characters that are used to 
-increase efficiency whenever a set of small, similar sized patterns are 
-repeatedly used.
-.LP
-This section discusses how to:
-.IP \(bu 5
-Load and free fonts
-.IP \(bu 5
-Obtain and free font names
-.IP \(bu 5
-Compute character string sizes
-.IP \(bu 5
-Compute logical extents
-.IP \(bu 5
-Query character string sizes
-.LP
-The X server loads fonts whenever a program requests a new font.
-The server can cache fonts for quick lookup.
-Fonts are global across all screens in a server.
-Several levels are possible when dealing with fonts.
-Most applications simply use 
-.PN XLoadQueryFont
-to load a font and query the font metrics.
-.LP
-Characters in fonts are regarded as masks.
-Except for image text requests,
-the only pixels modified are those in which bits are set to 1 in the character.
-This means that it makes sense to draw text using stipples or tiles
-(for example, many menus gray-out unusable entries).
-.LP
-.sM
-The
-.PN XFontStruct
-structure contains all of the information for the font
-and consists of the font-specific information as well as
-a pointer to an array of
-.PN XCharStruct
-structures for the
-characters contained in the font.
-The
-.PN XFontStruct ,
-.PN XFontProp ,
-and
-.PN XCharStruct
-structures contain:
-.LP
-.IN "XCharStruct" "" "@DEF@"
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	short lbearing;	/* origin to left edge of raster */
-	short rbearing;	/* origin to right edge of raster */
-	short width;	/* advance to next char's origin */
-	short ascent;	/* baseline to top edge of raster */
-	short descent;	/* baseline to bottom edge of raster */
-	unsigned short attributes;	/* per char flags (not predefined) */
-} XCharStruct;
-.De
-.LP
-.IN "XFontProp" "" "@DEF@"
-.Ds 0
-.TA .5i 1i 3i
-.ta .5i 1i 3i
-typedef struct {
-	Atom	name;
-	unsigned long card32;
-} XFontProp;
-.De
-.LP
-.IN "XChar2b" "" "@DEF@"
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {	/* normal 16 bit characters are two bytes */
-    unsigned char byte1;
-    unsigned char byte2;
-} XChar2b;
-.De
-.LP
-.IN "XFontStruct" "" "@DEF@"
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	XExtData *ext_data;	/* hook for extension to hang data */
-	Font fid;	/* Font id for this font */
-	unsigned direction;	/* hint about the direction font is painted */
-	unsigned min_char_or_byte2;	/* first character */
-	unsigned max_char_or_byte2;	/* last character */
-	unsigned min_byte1;	/* first row that exists */
-	unsigned max_byte1;	/* last row that exists */
-	Bool all_chars_exist;	/* flag if all characters have nonzero size */
-	unsigned default_char;	/* char to print for undefined character */
-	int n_properties;	/* how many properties there are */
-	XFontProp *properties;	/* pointer to array of additional properties */
-	XCharStruct min_bounds;	/* minimum bounds over all existing char */
-	XCharStruct max_bounds;	/* maximum bounds over all existing char */
-	XCharStruct *per_char;	/* first_char to last_char information */
-	int ascent;	/* logical extent above baseline for spacing */
-	int descent;	/* logical descent below baseline for spacing */
-} XFontStruct;
-.De
-.LP
-.eM
-X supports single byte/character, two bytes/character matrix,
-and 16-bit character text operations.
-Note that any of these forms can be used with a font, but a
-single byte/character text request can only specify a single byte
-(that is, the first row of a 2-byte font).
-You should view 2-byte fonts as a two-dimensional matrix of defined
-characters: byte1 specifies the range of defined rows and
-byte2 defines the range of defined columns of the font.
-Single byte/character fonts have one row defined, and the byte2 range
-specified in the structure defines a range of characters.
-.LP
-The bounding box of a character is defined by the 
-.PN XCharStruct 
-of that character.
-When characters are absent from a font,
-the default_char is used.
-When fonts have all characters of the same size,
-only the information in the
-.PN XFontStruct
-min and max bounds are used.
-.LP
-The members of the 
-.PN XFontStruct 
-have the following semantics:
-.IP \(bu 5
-The direction member can be either 
-.PN FontLeftToRight 
-or 
-.PN FontRightToLeft . 
-It is just a hint as to whether most 
-.PN XCharStruct 
-elements 
-have a positive 
-.Pn ( FontLeftToRight ) 
-or a negative 
-.Pn ( FontRightToLeft )
-character width 
-metric.
-The core protocol defines no support for vertical text.
-.IP \(bu 5
-If the min_byte1 and max_byte1 members are both zero, min_char_or_byte2
-specifies the linear character index corresponding to the first element
-of the per_char array, and max_char_or_byte2 specifies the linear character
-index of the last element.
-.IP
-If either min_byte1 or max_byte1 are nonzero, both
-min_char_or_byte2 and max_char_or_byte2 are less than 256, 
-and the 2-byte character index values corresponding to the
-per_char array element N (counting from 0) are:
-.IP
-.nf
-	byte1 = N/D + min_byte1
-.br
-	byte2 = N\\D + min_char_or_byte2
-.IP
-.fi
-where:
-.IP
-.nf
-        D = max_char_or_byte2 \- min_char_or_byte2 + 1
-        / = integer division
-        \\ = integer modulus
-.fi
-.IP \(bu 5
-If the per_char pointer is NULL, 
-all glyphs between the first and last character indexes
-inclusive have the same information,
-as given by both min_bounds and max_bounds.
-.IP \(bu 5
-If all_chars_exist is 
-.PN True ,
-all characters in the per_char array have nonzero bounding boxes.
-.IP \(bu 5
-The default_char member specifies the character that will be used when an
-undefined or nonexistent character is printed.  
-The default_char is a 16-bit character (not a 2-byte character).
-For a font using 2-byte matrix format, 
-the default_char has byte1 in the most-significant byte
-and byte2 in the least significant byte.
-If the default_char itself specifies an undefined or nonexistent character, 
-no printing is performed for an undefined or nonexistent character.
-.IP \(bu 5
-The min_bounds and max_bounds members contain the most extreme values of
-each individual 
-.PN XCharStruct 
-component over all elements of this array
-(and ignore nonexistent characters).
-The bounding box of the font (the smallest
-rectangle enclosing the shape obtained by superimposing all of the
-characters at the same origin [x,y]) has its upper-left coordinate at:
-.Ds
-	[x + min_bounds.lbearing, y \- max_bounds.ascent]
-.De
-.IP
-Its width is:
-.Ds
-	max_bounds.rbearing \- min_bounds.lbearing
-.De
-.IP
-Its height is:
-.Ds
-	max_bounds.ascent + max_bounds.descent
-.De
-.IP \(bu 5
-The ascent member is the logical extent of the font above the baseline that is
-used for determining line spacing.
-Specific characters may extend beyond
-this.
-.IP \(bu 5
-The descent member is the logical extent of the font at or below the
-baseline that is used for determining line spacing.
-Specific characters may extend beyond this.
-.IP \(bu 5
-If the baseline is at Y-coordinate y,
-the logical extent of the font is inclusive between the Y-coordinate 
-values (y \- font.ascent) and (y + font.descent \- 1).
-Typically,
-the minimum interline spacing between rows of text is given
-by ascent + descent.
-.LP
-For a character origin at [x,y],
-the bounding box of a character (that is, 
-the smallest rectangle that encloses the character's shape)
-described in terms of 
-.PN XCharStruct 
-components is a rectangle with its upper-left corner at:
-.LP
-.Ds
-[x + lbearing, y \- ascent]
-.De
-.LP
-Its width is:
-.LP
-.Ds
-rbearing \- lbearing
-.De
-.LP
-Its height is:
-.LP
-.Ds
-ascent + descent
-.De
-.LP
-The origin for the next character is defined to be:
-.LP
-.Ds
-[x + width, y]
-.De
-.LP
-The lbearing member defines the extent of the left edge of the character ink
-from the origin.
-The rbearing member defines the extent of the right edge of the character ink
-from the origin.
-The ascent member defines the extent of the top edge of the character ink
-from the origin.
-The descent member defines the extent of the bottom edge of the character ink
-from the origin.
-The width member defines the logical width of the character.
-.LP
-Note that the baseline (the y position of the character origin) 
-is logically viewed as being the scanline just below nondescending characters. 
-When descent is zero,
-only pixels with Y-coordinates less than y are drawn,
-and the origin is logically viewed as being coincident with the left edge of
-a nonkerned character. 
-When lbearing is zero,
-no pixels with X-coordinate less than x are drawn.
-Any of the
-.PN XCharStruct
-metric members could be negative.
-If the width is negative,
-the next character will be placed to the left of the current origin.
-.LP
-The X protocol does not define the interpretation of the attributes member 
-in the
-.PN XCharStruct
-structure.
-A nonexistent character is represented with all members of its
-.PN XCharStruct
-set to zero.
-.LP
-A font is not guaranteed to have any properties.
-The interpretation of the property value (for example, long or unsigned long)
-must be derived from \fIa priori\fP knowledge of the property. 
-A basic set of font properties is specified in the X Consortium standard
-\fIX Logical Font Description Conventions\fP.
-.NH 3
-Loading and Freeing Fonts
-.XS
-\*(SN Loading and Freeing Fonts 
-.XE
-.LP
-Xlib provides functions that you can use to load fonts, get font information,
-unload fonts, and free font information.
-.IN "Fonts" "getting information"
-.IN "Fonts" "unloading"
-.IN "Fonts" "freeing font information"
-A few font functions use a 
-.PN GContext 
-resource ID or a font ID interchangeably.
-.LP
-.sp
-To load a given font, use
-.PN XLoadFont .
-.IN "XLoadFont" "" "@DEF@"
-.sM
-.FD 0
-Font XLoadFont\^(\^\fIdisplay\fP, \fIname\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      char *\fIname\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIname\fP 1i
-Specifies the name of the font,
-which is a null-terminated string.
-.LP
-.eM
-The
-.PN XLoadFont
-function loads the specified font and returns its associated font ID.
-If the font name is not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-Use of uppercase or lowercase does not matter.
-When the characters ``?'' and ``*'' are used in a font name, a
-pattern match is performed and any matching font is used.
-In the pattern, 
-the ``?'' character will match any single character, 
-and the ``*'' character will match any number of characters.
-A structured format for font names is specified in the X Consortium standard 
-\fIX Logical Font Description Conventions\fP.
-If 
-.PN XLoadFont
-was unsuccessful at loading the specified font, 
-a 
-.PN BadName 
-error results.
-Fonts are not associated with a particular screen 
-and can be stored as a component
-of any GC.
-When the font is no longer needed, call 
-.PN XUnloadFont .
-.LP
-.PN XLoadFont
-can generate
-.PN BadAlloc
-and
-.PN BadName 
-errors.
-.LP
-.sp
-To return information about an available font, use
-.PN XQueryFont .
-.IN "XQueryFont" "" "@DEF@"
-.sM
-.FD 0
-XFontStruct *XQueryFont\^(\^\fIdisplay\fP, \fIfont_ID\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XID \fIfont_ID\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIfont_ID\fP 1i
-Specifies the font ID or the 
-.PN GContext
-ID.
-.LP
-.eM
-The
-.PN XQueryFont
-function returns a pointer to the
-.PN XFontStruct
-structure, which contains information associated with the font.
-You can query a font or the font stored in a GC.
-The font ID stored in the 
-.PN XFontStruct
-structure will be the 
-.PN GContext 
-ID, and you need to be careful when using this ID in other functions
-(see
-.PN XGContextFromGC ).
-If the font does not exist,
-.PN XQueryFont
-returns NULL.
-To free this data, use
-.PN XFreeFontInfo .
-.LP
-.sp
-To perform a
-.PN XLoadFont
-and
-.PN XQueryFont
-in a single operation, use
-.PN XLoadQueryFont .
-.IN "XLoadQueryFont" "" "@DEF@"
-.sM
-.FD 0
-XFontStruct *XLoadQueryFont\^(\^\fIdisplay\fP, \fIname\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      char *\fIname\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIname\fP 1i
-Specifies the name of the font,
-which is a null-terminated string.
-.LP
-.eM
-The
-.PN XLoadQueryFont
-function provides the most common way for accessing a font.
-.PN XLoadQueryFont
-both opens (loads) the specified font and returns a pointer to the
-appropriate
-.PN XFontStruct
-structure.
-If the font name is not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-If the font does not exist,
-.PN XLoadQueryFont
-returns NULL.
-.LP
-.PN XLoadQueryFont
-can generate a
-.PN BadAlloc 
-error.
-.LP
-.sp
-To unload the font and free the storage used by the font structure
-that was allocated by
-.PN XQueryFont
-or
-.PN XLoadQueryFont ,
-use
-.PN XFreeFont .
-.IN "XFreeFont" "" "@DEF@"
-.sM
-.FD 0
-XFreeFont\^(\^\fIdisplay\fP, \fIfont_struct\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XFontStruct *\fIfont_struct\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIfont_struct\fP 1i
-Specifies the storage associated with the font.
-.LP
-.eM 
-The
-.PN XFreeFont
-function deletes the association between the font resource ID and the specified 
-font and frees the
-.PN XFontStruct
-structure.
-The font itself will be freed when no other resource references it.
-The data and the font should not be referenced again.
-.LP
-.PN XFreeFont
-can generate a
-.PN BadFont 
-error.
-.LP
-.sp
-To return a given font property, use
-.PN XGetFontProperty .
-.IN "XGetFontProperty" "" "@DEF@"
-.sM
-.FD 0
-Bool XGetFontProperty\^(\^\fIfont_struct\fP\^, \^\fIatom\fP\^, \^\fIvalue_return\fP\^)
-.br
-      XFontStruct *\fIfont_struct\fP\^;
-.br
-      Atom \fIatom\fP\^;
-.br
-      unsigned long *\fIvalue_return\fP\^;
-.FN
-.IP \fIfont_struct\fP 1i
-Specifies the storage associated with the font.
-.IP \fIatom\fP 1i
-Specifies the atom for the property name you want returned.
-.IP \fIvalue_return\fP 1i
-Returns the value of the font property.
-.LP
-.eM
-Given the atom for that property,
-the
-.PN XGetFontProperty
-function returns the value of the specified font property. 
-.PN XGetFontProperty
-also returns 
-.PN False
-if the property was not defined or 
-.PN True
-if it was defined.
-A set of predefined atoms exists for font properties,
-which can be found in
-.hN X11/Xatom.h .
-This set contains the standard properties associated with
-a font.
-Although it is not guaranteed,
-it is likely that the predefined font properties will be present.
-.LP
-.sp
-To unload a font that was loaded by
-.PN XLoadFont , 
-use
-.PN XUnloadFont .
-.IN "XUnloadFont" "" "@DEF@"
-.sM
-.FD 0
-XUnloadFont\^(\^\fIdisplay\fP, \fIfont\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Font \fIfont\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIfont\fP 1i
-Specifies the font.
-.LP
-.eM
-The
-.PN XUnloadFont
-function deletes the association between the font resource ID and the specified font.
-The font itself will be freed when no other resource references it.
-The font should not be referenced again.
-.LP
-.PN XUnloadFont
-can generate a
-.PN BadFont 
-error.
-.NH 3
-Obtaining and Freeing Font Names and Information
-.XS
-\*(SN Obtaining and Freeing Font Names and Information
-.XE
-.LP
-You obtain font names and information by matching a wildcard specification
-when querying a font type for a list of available sizes and so on.
-.LP
-.sp
-To return a list of the available font names, use
-.PN XListFonts .
-.IN "XListFonts" "" "@DEF@"
-.sM
-.FD 0
-char **XListFonts\^(\^\fIdisplay\fP, \fIpattern\fP\^, \fImaxnames\fP, \fIactual_count_return\fP\^)
-.br
-      Display *\^\fIdisplay\fP\^;
-.br
-      char *\^\fIpattern\fP\^;
-.br
-      int \fImaxnames\fP\^;
-.br
-      int *\^\fIactual_count_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIpattern\fP 1i
-Specifies the null-terminated pattern string that can contain wildcard 
-characters.
-.IP \fImaxnames\fP 1i
-Specifies the maximum number of names to be returned.
-.IP \fIactual_count_return\fP 1i
-Returns the actual number of font names.
-.LP
-.eM
-The
-.PN XListFonts
-function returns an array of available font names 
-(as controlled by the font search path; see
-.PN XSetFontPath )
-that match the string you passed to the pattern argument.
-The pattern string can contain any characters,
-but each asterisk (*) is a wildcard for any number of characters,
-and each question mark (?) is a wildcard for a single character.
-If the pattern string is not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-Use of uppercase or lowercase does not matter.
-Each returned string is null-terminated.
-If the data returned by the server is in the Latin Portable Character Encoding,
-then the returned strings are in the Host Portable Character Encoding.
-Otherwise, the result is implementation-dependent.
-If there are no matching font names,
-.PN XListFonts
-returns NULL.
-The client should call
-.PN XFreeFontNames
-when finished with the result to free the memory.
-.LP
-.sp
-To free a font name array, use
-.PN XFreeFontNames .
-.IN "XFreeFontNames" "" "@DEF@"
-.sM
-.FD 0
-XFreeFontNames\^(\^\fIlist\fP\^)
-.br
-      char *\fIlist\fP\^[\^]\^;
-.FN
-.IP \fIlist\fP 1i
-Specifies the array of strings you want to free.
-.LP
-.eM
-The
-.PN XFreeFontNames
-function frees the array and strings returned by
-.PN XListFonts 
-or
-.PN XListFontsWithInfo .
-.LP
-.sp
-To obtain the names and information about available fonts, use
-.PN XListFontsWithInfo .
-.IN "XListFontsWithInfo" "" "@DEF@"
-.sM
-.FD 0
-char **XListFontsWithInfo\^(\^\fIdisplay\fP, \fIpattern\fP, \fImaxnames\fP, \fIcount_return\fP, \fIinfo_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      char *\fIpattern\fP\^;
-.br
-      int \fImaxnames\fP\^;
-.br
-      int *\fIcount_return\fP\^;
-.br
-      XFontStruct **\fIinfo_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIpattern\fP 1i
-Specifies the null-terminated pattern string that can contain wildcard 
-characters.
-.IP \fImaxnames\fP 1i
-Specifies the maximum number of names to be returned.
-.IP \fIcount_return\fP 1i
-Returns the actual number of matched font names.
-.IP \fIinfo_return\fP 1i
-Returns the font information.
-.LP
-.eM
-The
-.PN XListFontsWithInfo
-function returns a list of font names that match the specified pattern and their
-associated font information.
-The list of names is limited to size specified by maxnames.
-The information returned for each font is identical to what
-.PN XLoadQueryFont
-would return except that the per-character metrics are not returned.
-The pattern string can contain any characters,
-but each asterisk (*) is a wildcard for any number of characters,
-and each question mark (?) is a wildcard for a single character.
-If the pattern string is not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-Use of uppercase or lowercase does not matter.
-Each returned string is null-terminated.
-If the data returned by the server is in the Latin Portable Character Encoding,
-then the returned strings are in the Host Portable Character Encoding.
-Otherwise, the result is implementation-dependent.
-If there are no matching font names,
-.PN XListFontsWithInfo
-returns NULL.
-.LP
-To free only the allocated name array,
-the client should call
-.PN XFreeFontNames .
-To free both the name array and the font information array
-or to free just the font information array,
-the client should call
-.PN XFreeFontInfo .
-.LP
-.sp
-To free font structures and font names, use
-.PN XFreeFontInfo .
-.IN "XFreeFontInfo" "" "@DEF@"
-.sM
-.FD 0
-XFreeFontInfo(\^\fInames\fP, \fIfree_info\fP, \fIactual_count\fP\^)
-.br
-      char **\fInames\fP\^;
-.br
-      XFontStruct *\fIfree_info\fP;
-.br
-      int \fIactual_count\fP\^;
-.FN
-.IP \fInames\fP 1i
-Specifies the list of font names.
-
-.IP \fIfree_info\fP 1i
-Specifies the font information.
-
-.IP \fIactual_count\fP 1i
-Specifies the actual number of font names.
-
-.LP
-.eM
-The
-.PN XFreeFontInfo
-function frees a font structure or an array of font structures
-and optionally an array of font names.
-If NULL is passed for names, no font names are freed.
-If a font structure for an open font (returned by
-.PN XLoadQueryFont )
-is passed, the structure is freed,
-but the font is not closed; use
-.PN XUnloadFont
-to close the font.
-.NH 3
-Computing Character String Sizes
-.XS
-\*(SN Computing Character String Sizes 
-.XE
-.LP
-Xlib provides functions that you can use to compute the width,
-the logical extents, 
-and the server information about 8-bit and 2-byte text strings.
-.IN "XTextWidth"
-.IN "XTextWidth16"
-The width is computed by adding the character widths of all the characters.
-It does not matter if the font is an 8-bit or 2-byte font.
-These functions return the sum of the character metrics in pixels.
-.LP
-.sp
-To determine the width of an 8-bit character string, use
-.PN XTextWidth .
-.IN "XTextWidth" "" "@DEF@"
-.sM
-.FD 0
-int XTextWidth\^(\^\fIfont_struct\fP\^, \fIstring\fP, \fIcount\fP\^)
-.br
-      XFontStruct *\fIfont_struct\fP\^;
-.br
-      char *\fIstring\fP\^;
-.br
-      int \fIcount\fP\^;
-.FN
-.IP \fIfont_struct\fP 1i
-Specifies the font used for the width computation.
-.IP \fIstring\fP 1i
-Specifies the character string.
-.IP \fIcount\fP 1i
-Specifies the character count in the specified string.
-.LP
-.eM
-.sp
-To determine the width of a 2-byte character string, use
-.PN XTextWidth16 .
-.IN "XTextWidth16" "" "@DEF@"
-.sM
-.FD 0
-int XTextWidth16\^(\^\fIfont_struct\fP\^, \fIstring\fP, \fIcount\fP\^)
-.br
-      XFontStruct *\fIfont_struct\fP\^;
-.br
-      XChar2b *\fIstring\fP\^;
-.br
-      int \fIcount\fP\^;
-.FN
-.IP \fIfont_struct\fP 1i
-Specifies the font used for the width computation.
-.IP \fIstring\fP 1i
-Specifies the character string.
-.IP \fIcount\fP 1i
-Specifies the character count in the specified string.
-.LP
-.eM
-.NH 3
-Computing Logical Extents
-.XS
-\*(SN Computing Logical Extents 
-.XE
-.LP
-To compute the bounding box of an 8-bit character string in a given font, use
-.PN XTextExtents .
-.IN "XTextExtents" "" "@DEF@"
-.sM
-.FD 0
-XTextExtents\^(\^\fIfont_struct\fP\^, \fIstring\fP\^, \fInchars\fP\^, \
-\fIdirection_return\fP, \fIfont_ascent_return\fP,
-.br
-              \fIfont_descent_return\fP, \fIoverall_return\fP\^)
-.br
-      XFontStruct *\fIfont_struct\fP\^;
-.br
-      char *\fIstring\fP\^;
-.br
-      int \fInchars\fP\^;
-.br
-      int *\fIdirection_return\fP\^;
-.br
-      int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^;
-.br
-      XCharStruct *\fIoverall_return\fP\^;
-
-.FN
-.IP \fIfont_struct\fP 1i
-Specifies the 
-.PN XFontStruct 
-structure.
-.IP \fIstring\fP 1i
-Specifies the character string.
-.IP \fInchars\fP 1i
-Specifies the number of characters in the character string.
-.IP \fIdirection_return\fP 1i
-Returns the value of the direction hint
-.Pn ( FontLeftToRight
-or
-.PN FontRightToLeft ).
-.IP \fIfont_ascent_return\fP 1i
-Returns the font ascent.
-.IP \fIfont_descent_return\fP 1i
-Returns the font descent.
-.IP \fIoverall_return\fP 1i
-Returns the overall size in the specified
-.PN XCharStruct 
-structure.
-.LP
-.eM
-.sp
-To compute the bounding box of a 2-byte character string in a given font, use
-.PN XTextExtents16 .
-.IN "XTextExtents16" "" "@DEF@"
-.sM
-.FD 0
-XTextExtents16\^(\^\fIfont_struct\fP\^, \fIstring\fP\^, \fInchars\fP\^, \
-\fIdirection_return\fP, \fIfont_ascent_return\fP, 
-.br
-                \fIfont_descent_return\fP, \fIoverall_return\fP\^)
-.br
-      XFontStruct *\fIfont_struct\fP\^;
-.br
-      XChar2b *\fIstring\fP\^;
-.br
-      int \fInchars\fP\^;
-.br
-      int *\fIdirection_return\fP\^;
-.br
-      int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^;
-.br
-      XCharStruct *\fIoverall_return\fP\^;
-
-.FN
-.IP \fIfont_struct\fP 1i
-Specifies the 
-.PN XFontStruct 
-structure.
-.IP \fIstring\fP 1i
-Specifies the character string.
-.IP \fInchars\fP 1i
-Specifies the number of characters in the character string.
-.IP \fIdirection_return\fP 1i
-Returns the value of the direction hint
-.Pn ( FontLeftToRight
-or
-.PN FontRightToLeft ).
-.IP \fIfont_ascent_return\fP 1i
-Returns the font ascent.
-.IP \fIfont_descent_return\fP 1i
-Returns the font descent.
-.IP \fIoverall_return\fP 1i
-Returns the overall size in the specified
-.PN XCharStruct 
-structure.
-.LP
-.eM
-The
-.PN XTextExtents
-and
-.PN XTextExtents16
-functions 
-perform the size computation locally and, thereby,
-avoid the round-trip overhead of
-.PN XQueryTextExtents 
-and
-.PN XQueryTextExtents16 .
-Both functions return an
-.PN XCharStruct
-structure, whose members are set to the values as follows.
-.LP
-The ascent member is set to the maximum of the ascent metrics of all
-characters in the string.
-The descent member is set to the maximum of the descent metrics.
-The width member is set to the sum of the character-width metrics of all
-characters in the string.
-For each character in the string,
-let W be the sum of the character-width metrics of all characters preceding 
-it in the string.
-Let L be the left-side-bearing metric of the character plus W.
-Let R be the right-side-bearing metric of the character plus W.
-The lbearing member is set to the minimum L of all characters in the string.
-The rbearing member is set to the maximum R.
-.LP
-For fonts defined with linear indexing rather than 2-byte matrix indexing,
-each 
-.PN XChar2b 
-structure is interpreted as a 16-bit number with byte1 as the 
-most significant byte.
-If the font has no defined default character,
-undefined characters in the string are taken to have all zero metrics.
-.NH 3
-Querying Character String Sizes
-.XS
-\*(SN Querying Character String Sizes 
-.XE
-.LP
-To query the server for the bounding box of an 8-bit character string in a 
-given font, use 
-.PN XQueryTextExtents .
-.IN "XQueryTextExtents" "" "@DEF@"
-.sM
-.FD 0
-XQueryTextExtents\^(\^\fIdisplay\fP, \fIfont_ID\fP, \fIstring\fP, \
-\fInchars\fP, \fIdirection_return\fP, \fIfont_ascent_return\fP, 
-.br
-                    \fIfont_descent_return\fP, \fIoverall_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XID \fIfont_ID\fP\^;
-.br
-      char *\fIstring\fP\^;
-.br
-      int \fInchars\fP\^;
-.br
-      int *\fIdirection_return\fP\^;
-.br
-      int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^;
-.br
-      XCharStruct *\fIoverall_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIfont_ID\fP 1i
-Specifies either the font ID or the 
-.PN GContext
-ID that contains the font.
-.IP \fIstring\fP 1i
-Specifies the character string.
-.IP \fInchars\fP 1i
-Specifies the number of characters in the character string.
-.IP \fIdirection_return\fP 1i
-Returns the value of the direction hint
-.Pn ( FontLeftToRight
-or
-.PN FontRightToLeft ).
-.IP \fIfont_ascent_return\fP 1i
-Returns the font ascent.
-.IP \fIfont_descent_return\fP 1i
-Returns the font descent.
-.IP \fIoverall_return\fP 1i
-Returns the overall size in the specified
-.PN XCharStruct 
-structure.
-.LP
-.eM
-.sp
-To query the server for the bounding box of a 2-byte character string
-in a given font, use
-.PN XQueryTextExtents16 .
-.IN "XQueryTextExtents16" "" "@DEF@"
-.sM
-.FD 0
-XQueryTextExtents16\^(\^\fIdisplay\fP, \fIfont_ID\fP, \fIstring\fP, \
-\fInchars\fP, \fIdirection_return\fP, \fIfont_ascent_return\fP, 
-.br
-                        \fIfont_descent_return\fP, \fIoverall_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XID \fIfont_ID\fP\^;
-.br
-      XChar2b *\fIstring\fP\^;
-.br
-      int \fInchars\fP\^;
-.br
-      int *\fIdirection_return\fP\^;
-.br
-      int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^;
-.br
-      XCharStruct *\fIoverall_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIfont_ID\fP 1i
-Specifies either the font ID or the 
-.PN GContext
-ID that contains the font.
-.IP \fIstring\fP 1i
-Specifies the character string.
-.IP \fInchars\fP 1i
-Specifies the number of characters in the character string.
-.IP \fIdirection_return\fP 1i
-Returns the value of the direction hint
-.Pn ( FontLeftToRight
-or
-.PN FontRightToLeft ).
-.IP \fIfont_ascent_return\fP 1i
-Returns the font ascent.
-.IP \fIfont_descent_return\fP 1i
-Returns the font descent.
-.IP \fIoverall_return\fP 1i
-Returns the overall size in the specified
-.PN XCharStruct 
-structure.
-.LP
-.eM
-The
-.PN XQueryTextExtents
-and
-.PN XQueryTextExtents16
-functions return the bounding box of the specified 8-bit and 16-bit
-character string in the specified font or the font contained in the
-specified GC.
-These functions query the X server and, therefore, suffer the round-trip
-overhead that is avoided by
-.PN XTextExtents
-and 
-.PN XTextExtents16 .
-Both functions return a
-.PN XCharStruct 
-structure, whose members are set to the values as follows.
-.LP
-The ascent member is set to the maximum of the ascent metrics 
-of all characters in the string.
-The descent member is set to the maximum of the descent metrics.
-The width member is set to the sum of the character-width metrics 
-of all characters in the string.
-For each character in the string,
-let W be the sum of the character-width metrics of all characters preceding
-it in the string.
-Let L be the left-side-bearing metric of the character plus W.
-Let R be the right-side-bearing metric of the character plus W.
-The lbearing member is set to the minimum L of all characters in the string.
-The rbearing member is set to the maximum R.
-.LP
-For fonts defined with linear indexing rather than 2-byte matrix indexing,
-each 
-.PN XChar2b 
-structure is interpreted as a 16-bit number with byte1 as the 
-most significant byte.
-If the font has no defined default character,
-undefined characters in the string are taken to have all zero metrics.
-.LP
-Characters with all zero metrics are ignored.
-If the font has no defined default_char,
-the undefined characters in the string are also ignored.
-.LP
-.PN XQueryTextExtents
-and
-.PN XQueryTextExtents16
-can generate
-.PN BadFont
-and
-.PN BadGC 
-errors.
-.NH 2
-Drawing Text
-.XS
-\*(SN Drawing Text
-.XE
-.LP
-This section discusses how to draw:
-.IP \(bu 5
-Complex text 
-.IP \(bu 5
-Text characters
-.IP \(bu 5
-Image text characters
-.LP
-The fundamental text functions
-.PN XDrawText
-and
-.PN XDrawText16
-use the following structures:
-.LP
-.IN "XTextItem" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	char *chars;	/* pointer to string */
-	int nchars;	/* number of characters */
-	int delta;	/* delta between strings */
-	Font font;	/* Font to print it in, None don't change */
-} XTextItem;
-.De
-.LP
-.IN "XTextItem16" "" "@DEF@"
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	XChar2b *chars;	/* pointer to two-byte characters */
-	int nchars;	/* number of characters */
-	int delta;	/* delta between strings */
-	Font font;	/* font to print it in, None don't change */
-} XTextItem16;
-.De
-.LP
-.eM
-If the font member is not
-.PN None ,
-the font is changed before printing and also is stored in the GC.
-If an error was generated during text drawing,
-the previous items may have been drawn.
-The baseline of the characters are drawn starting at the x and y
-coordinates that you pass in the text drawing functions.
-.LP
-For example, consider the background rectangle drawn by
-.PN XDrawImageString .
-If you want the upper-left corner of the background rectangle
-to be at pixel coordinate (x,y), pass the (x,y + ascent)
-as the baseline origin coordinates to the text functions.
-The ascent is the font ascent, as given in the
-.PN XFontStruct
-structure.
-If you want the lower-left corner of the background rectangle
-to be at pixel coordinate (x,y), pass the (x,y \- descent + 1)
-as the baseline origin coordinates to the text functions.
-The descent is the font descent, as given in the
-.PN XFontStruct
-structure.
-.NH 3
-Drawing Complex Text
-.XS
-\*(SN Drawing Complex Text 
-.XE
-.LP
-.IN "Text" "drawing"
-.IN "Drawing" "text items"
-.LP
-To draw 8-bit characters in a given drawable, use
-.PN XDrawText .
-.IN "XDrawText" "" "@DEF@"
-.sM
-.FD 0
-XDrawText\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.br
-      XTextItem *\fIitems\fP\^;
-.br
-      int \fInitems\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.ds Xy , which are relative to the origin of the specified drawable \
-and define the origin of the first character
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.IP \fIitems\fP 1i
-Specifies an array of text items.
-.IP \fInitems\fP 1i
-Specifies the number of text items in the array.
-.LP
-.eM
-.sp
-To draw 2-byte characters in a given drawable, use
-.PN XDrawText16 .
-.IN "XDrawText16" "" "@DEF@"
-.sM
-.FD 0
-XDrawText16\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.br
-      XTextItem16 *\fIitems\fP\^;
-.br
-      int \fInitems\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.ds Xy , which are relative to the origin of the specified drawable \
-and define the origin of the first character
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.IP \fIitems\fP 1i
-Specifies an array of text items.
-.IP \fInitems\fP 1i
-Specifies the number of text items in the array.
-.LP
-.eM
-The
-.PN XDrawText16
-function is similar to
-.PN XDrawText 
-except that it uses 2-byte or 16-bit characters.
-Both functions allow complex spacing and font shifts between counted strings.
-.LP
-Each text item is processed in turn.
-A font member other than 
-.PN None
-in an item causes the font to be stored in the GC
-and used for subsequent text.  
-A text element delta specifies an additional change
-in the position along the x axis before the string is drawn. 
-The delta is always added to the character origin
-and is not dependent on any characteristics of the font.
-Each character image, as defined by the font in the GC, is treated as an
-additional mask for a fill operation on the drawable.
-The drawable is modified only where the font character has a bit set to 1.
-If a text item generates a
-.PN BadFont
-error, the previous text items may have been drawn.
-.LP
-For fonts defined with linear indexing rather than 2-byte matrix indexing,
-each 
-.PN XChar2b
-structure is interpreted as a 16-bit number with byte1 as the 
-most significant byte.
-.LP
-Both functions use these GC components:
-function, plane-mask, fill-style, font, subwindow-mode, 
-clip-x-origin, clip-y-origin, and clip-mask.
-They also use these GC mode-dependent components: 
-foreground, background, tile, stipple, tile-stipple-x-origin, 
-and tile-stipple-y-origin.
-.LP
-.PN XDrawText
-and
-.PN XDrawText16
-can generate
-.PN BadDrawable ,
-.PN BadFont ,
-.PN BadGC ,
-and
-.PN BadMatch 
-errors.
-.NH 3
-Drawing Text Characters
-.XS
-\*(SN Drawing Text Characters 
-.XE
-.LP
-.IN "Strings" "drawing"
-.IN "Drawing" "strings"
-To draw 8-bit characters in a given drawable, use
-.PN XDrawString .
-.IN "XDrawString" "" "@DEF@"
-.sM
-.FD 0
-XDrawString\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.br
-      char *\fIstring\fP\^;
-.br
-      int \fIlength\fP\^; 
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.ds Xy , which are relative to the origin of the specified drawable \
-and define the origin of the first character
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.IP \fIstring\fP 1i
-Specifies the character string.
-.IP \fIlength\fP 1i
-Specifies the number of characters in the string argument.
-.LP
-.eM
-.sp
-To draw 2-byte characters in a given drawable, use
-.PN XDrawString16 .
-.IN "XDrawString16" "" "@DEF@"
-.sM
-.FD 0
-XDrawString16\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.br
-      XChar2b *\fIstring\fP\^;
-.br
-      int \fIlength\fP\^; 
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.ds Xy , which are relative to the origin of the specified drawable \
-and define the origin of the first character
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.IP \fIstring\fP 1i
-Specifies the character string.
-.IP \fIlength\fP 1i
-Specifies the number of characters in the string argument.
-.LP
-.eM
-Each character image, as defined by the font in the GC, is treated as an
-additional mask for a fill operation on the drawable.
-The drawable is modified only where the font character has a bit set to 1.
-For fonts defined with 2-byte matrix indexing
-and used with
-.PN XDrawString16 ,
-each byte is used as a byte2 with a byte1 of zero.
-.LP
-Both functions use these GC components: 
-function, plane-mask, fill-style, font, subwindow-mode, clip-x-origin, 
-clip-y-origin, and clip-mask.
-They also use these GC mode-dependent components: 
-foreground, background, tile, stipple, tile-stipple-x-origin, 
-and tile-stipple-y-origin.
-.LP
-.PN XDrawString
-and
-.PN XDrawString16
-can generate
-.PN BadDrawable ,
-.PN BadGC ,
-and
-.PN BadMatch 
-errors.
-.NH 3
-Drawing Image Text Characters
-.XS
-\*(SN Drawing Image Text Characters 
-.XE
-.LP
-.IN "Image text" "drawing"
-.IN "Drawing" "image text"
-Some applications, in particular terminal emulators, need to
-print image text in which both the foreground and background bits of
-each character are painted.
-This prevents annoying flicker on many displays.
-.IN "XDrawImageString"
-.IN "XDrawImageString16"
-.LP
-.sp
-To draw 8-bit image text characters in a given drawable, use
-.PN XDrawImageString .
-.IN "XDrawImageString" "" "@DEF@"
-.sM
-.FD 0
-XDrawImageString\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.br
-      char *\fIstring\fP\^;
-.br
-      int \fIlength\fP\^; 
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.ds Xy , which are relative to the origin of the specified drawable \
-and define the origin of the first character
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.IP \fIstring\fP 1i
-Specifies the character string.
-.IP \fIlength\fP 1i
-Specifies the number of characters in the string argument.
-.LP
-.eM
-.sp
-To draw 2-byte image text characters in a given drawable, use
-.PN XDrawImageString16 .
-.IN "XDrawImageString16" "" "@DEF@"
-.sM
-.FD 0
-XDrawImageString16\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.br
-      XChar2b *\fIstring\fP\^;
-.br
-      int \fIlength\fP\^; 
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.ds Xy , which are relative to the origin of the specified drawable \
-and define the origin of the first character
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.IP \fIstring\fP 1i
-Specifies the character string.
-.IP \fIlength\fP 1i
-Specifies the number of characters in the string argument.
-.LP
-.eM
-The
-.PN XDrawImageString16
-function is similar to
-.PN XDrawImageString 
-except that it uses 2-byte or 16-bit characters.
-Both functions also use both the foreground and background pixels 
-of the GC in the destination.
-.LP
-The effect is first to fill a
-destination rectangle with the background pixel defined in the GC and then
-to paint the text with the foreground pixel.
-The upper-left corner of the filled rectangle is at:
-.LP
-.Ds
-[x, y \- font-ascent]
-.De
-.LP
-The width is:
-.LP
-.Ds
-overall-width
-.De
-.LP
-The height is:
-.LP
-.Ds
-font-ascent + font-descent
-.De
-.LP
-The overall-width, font-ascent, and font-descent
-are as would be returned by 
-.PN XQueryTextExtents 
-using gc and string.
-The function and fill-style defined in the GC are ignored for these functions. 
-The effective function is 
-.PN GXcopy ,
-and the effective fill-style is
-.PN FillSolid .
-.LP
-For fonts defined with 2-byte matrix indexing
-and used with
-.PN XDrawImageString ,
-each byte is used as a byte2 with a byte1 of zero.
-.LP
-Both functions use these GC components: 
-plane-mask, foreground, background, font, subwindow-mode, clip-x-origin, 
-clip-y-origin, and clip-mask.
-.LP
-.PN XDrawImageString
-and
-.PN XDrawImageString16
-can generate
-.PN BadDrawable ,
-.PN BadGC ,
-and
-.PN BadMatch 
-errors.
-.LP
-.NH 2
-Transferring Images between Client and Server
-.XS
-\*(SN Transferring Images between Client and Server 
-.XE
-.LP
-Xlib provides functions that you can use to transfer images between a client 
-and the server.
-Because the server may require diverse data formats, 
-Xlib provides an image object that fully describes the data in memory 
-and that provides for basic operations on that data.  
-You should reference the data 
-through the image object rather than referencing the data directly.
-However, some implementations of the Xlib library may efficiently deal with 
-frequently used data formats by replacing
-functions in the procedure vector with special case functions.
-Supported operations include destroying the image, getting a pixel,
-storing a pixel, extracting a subimage of an image, and adding a constant
-to an image (see section 16.8).
-.LP
-All the image manipulation functions discussed in this section make use of 
-the 
-.PN XImage 
-structure,
-which describes an image as it exists in the client's memory.
-.LP
-.IN "XImage" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 1i 3i
-.ta .5i 1i 3i
-typedef struct _XImage {
-	int width, height;		/* size of image */
-	int xoffset;		/* number of pixels offset in X direction */
-	int format;		/* XYBitmap, XYPixmap, ZPixmap */
-	char *data;		/* pointer to image data */
-	int byte_order;		/* data byte order, LSBFirst, MSBFirst */
-	int bitmap_unit;		/* quant. of scanline 8, 16, 32 */
-	int bitmap_bit_order;		/* LSBFirst, MSBFirst */
-	int bitmap_pad;		/* 8, 16, 32 either XY or ZPixmap */
-	int depth;		/* depth of image */
-	int bytes_per_line;		/* accelerator to next scanline */
-	int bits_per_pixel;		/* bits per pixel (ZPixmap) */
-	unsigned long red_mask;		/* bits in z arrangement */
-	unsigned long green_mask;
-	unsigned long blue_mask;
-	XPointer obdata;	/* hook for the object routines to hang on */
-	struct funcs {		/* image manipulation routines */
-		struct _XImage *(*create_image)();
-		int (*destroy_image)();
-		unsigned long (*get_pixel)();
-		int (*put_pixel)();
-		struct _XImage *(*sub_image)();
-		int (*add_pixel)();
-	} f;
-} XImage;
-.De
-.LP
-.eM
-.sp
-To initialize the image manipulation routines of an image structure, use
-.PN XInitImage .
-.IN "XInitImage" "" "@DEF@"
-.sM
-.FD 0
-Status XInitImage\^(\^\fIimage\fP\^)
-.br
-      XImage *\fIimage\fP\^;
-.FN
-.IP \fIximage\fP 1i
-Specifies the image.
-.LP
-.eM
-The
-.PN XInitImage
-function initializes the internal image manipulation routines of an
-image structure, based on the values of the various structure members.
-All fields other than the manipulation routines must already be initialized.
-If the bytes_per_line member is zero,
-.PN XInitImage
-will assume the image data is contiguous in memory and set the
-bytes_per_line member to an appropriate value based on the other
-members; otherwise, the value of bytes_per_line is not changed.
-All of the manipulation routines are initialized to functions
-that other Xlib image manipulation functions need to operate on the
-type of image specified by the rest of the structure.
-.LP
-This function must be called for any image constructed by the client
-before passing it to any other Xlib function.
-Image structures created or returned by Xlib do not need to be
-initialized in this fashion.
-.LP
-This function returns a nonzero status if initialization of the
-structure is successful.  It returns zero if it detected some error
-or inconsistency in the structure, in which case the image is not changed.
-.LP
-.sp
-To combine an image with a rectangle of a drawable on the display,
-use
-.PN XPutImage .
-.IN "XPutImage" "" "@DEF@"
-.sM
-.FD 0
-XPutImage\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIimage\fP\^, \fIsrc_x\fP, \fIsrc_y\fP, \fIdest_x\fP\^, \fIdest_y\fP\^, \fIwidth\fP\^, \fIheight\fP\^)
-.br
-        Display *\fIdisplay\fP\^;
-.br
-        Drawable \fId\fP\^;
-.br
-        GC \fIgc\fP\^;
-.br
-        XImage *\fIimage\fP\^;
-.br
-        int \fIsrc_x\fP\^, \fIsrc_y\fP\^;
-.br
-        int \fIdest_x\fP\^, \fIdest_y\fP\^;
-.br
-        unsigned int \fIwidth\fP\^, \fIheight\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIimage\fP 1i
-Specifies the image you want combined with the rectangle. 
-.IP \fIsrc_x\fP 1i
-Specifies the offset in X from the left edge of the image defined
-by the 
-.PN XImage 
-structure.
-.IP \fIsrc_y\fP 1i
-Specifies the offset in Y from the top edge of the image defined
-by the 
-.PN XImage 
-structure.
-.ds Dx , which are relative to the origin of the drawable \
-and are the coordinates of the subimage
-.IP \fIdest_x\fP 1i
-.br
-.ns
-.IP \fIdest_y\fP 1i
-Specify the x and y coordinates\*(Dx. 
-.ds Wh \ of the subimage, which define the dimensions of the rectangle
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height\*(Wh.
-.LP
-.eM
-The
-.PN XPutImage
-function
-combines an image with a rectangle of the specified drawable.
-The section of the image defined by the src_x, src_y, width, and height 
-arguments is drawn on the specified part of the drawable.
-If 
-.PN XYBitmap 
-format is used, the depth of the image must be one,
-or a
-.PN BadMatch 
-error results.
-The foreground pixel in the GC defines the source for the one bits in the image,
-and the background pixel defines the source for the zero bits.
-For 
-.PN XYPixmap 
-and 
-.PN ZPixmap , 
-the depth of the image must match the depth of the drawable,
-or a
-.PN BadMatch
-error results.
-.LP
-If the characteristics of the image (for example, byte_order and bitmap_unit)
-differ from what the server requires,
-.PN XPutImage 
-automatically makes the appropriate
-conversions.
-.LP
-This function uses these GC components: 
-function, plane-mask, subwindow-mode, clip-x-origin, clip-y-origin, 
-and clip-mask.
-It also uses these GC mode-dependent components:
-foreground and background.
-.LP
-.PN XPutImage
-can generate
-.PN BadDrawable ,
-.PN BadGC ,
-.PN BadMatch ,
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-To return the contents of a rectangle in a given drawable on the display,
-use
-.PN XGetImage .
-This function specifically supports rudimentary screen dumps.
-.IN "XGetImage" "" "@DEF@"
-.sM
-.FD 0
-XImage *XGetImage\^(\^\fIdisplay\fP, \fId\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIplane_mask\fP, \fIformat\fP\^)
-.br
-        Display *\fIdisplay\fP\^;
-.br
-        Drawable \fId\fP\^;
-.br
-        int \fIx\fP\^, \fIy\fP\^;
-.br
-        unsigned int \fIwidth\fP\^, \fIheight\fP\^;
-.br
-        unsigned long \fIplane_mask\fP\^;
-.br
-        int \fIformat\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.ds Xy , which are relative to the origin of the drawable \
-and define the upper-left corner of the rectangle
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.ds Wh \ of the subimage, which define the dimensions of the rectangle
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height\*(Wh.
-.IP \fIplane_mask\fP 1i
-Specifies the plane mask.
-.\" *** JIM: NEED MORE INFO FOR THIS. ***
-.IP \fIformat\fP 1i
-Specifies the format for the image.
-You can pass
-.PN XYPixmap
-or 
-.PN ZPixmap .
-.LP
-.eM
-The
-.PN XGetImage
-function returns a pointer to an
-.PN XImage
-structure.
-This structure provides you with the contents of the specified rectangle of
-the drawable in the format you specify.
-If the format argument is 
-.PN XYPixmap ,
-the image contains only the bit planes you passed to the plane_mask argument.
-If the plane_mask argument only requests a subset of the planes of the
-display, the depth of the returned image will be the number of planes
-requested.
-If the format argument is 
-.PN ZPixmap ,
-.PN XGetImage
-returns as zero the bits in all planes not 
-specified in the plane_mask argument.
-The function performs no range checking on the values in plane_mask and ignores
-extraneous bits.
-.LP
-.PN XGetImage
-returns the depth of the image to the depth member of the
-.PN XImage
-structure.
-The depth of the image is as specified when the drawable was created,
-except when getting a subset of the planes in 
-.PN XYPixmap
-format, when the depth is given by the number of bits set to 1 in plane_mask.
-.LP
-If the drawable is a pixmap, 
-the given rectangle must be wholly contained within the pixmap, 
-or a
-.PN BadMatch
-error results.
-If the drawable is a window, 
-the window must be viewable, 
-and it must be the case that if there were no inferiors or overlapping windows,
-the specified rectangle of the window would be fully visible on the screen
-and wholly contained within the outside edges of the window,
-or a
-.PN BadMatch
-error results.
-Note that the borders of the window can be included and read with
-this request.
-If the window has backing-store, the backing-store contents are
-returned for regions of the window that are obscured by noninferior
-windows. 
-If the window does not have backing-store,
-the returned contents of such obscured regions are undefined.
-The returned contents of visible regions of inferiors
-of a different depth than the specified window's depth are also undefined.
-The pointer cursor image is not included in the returned contents.
-If a problem occurs,
-.PN XGetImage
-returns NULL.
-.LP
-.PN XGetImage
-can generate
-.PN BadDrawable ,
-.PN BadMatch ,
-and
-.PN BadValue 
-errors.
-.sp
-.LP
-To copy the contents of a rectangle on the display
-to a location within a preexisting image structure, use
-.PN XGetSubImage .
-.IN "XGetSubImage" "" "@DEF@"
-.sM
-.FD 0
-XImage *XGetSubImage\^(\^\fIdisplay\fP, \fId\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIplane_mask\fP, \fIformat\fP\^, \fIdest_image\fP\^, \fIdest_x\fP\^, 
-.br
-                     \fIdest_y\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.br
-      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
-.br
-      unsigned long \fIplane_mask\fP\^;
-.br
-      int \fIformat\fP\^;
-.br
-      XImage *\fIdest_image\fP\^;
-.br
-      int \fIdest_x\fP\^, \fIdest_y\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.ds Xy , which are relative to the origin of the drawable \
-and define the upper-left corner of the rectangle
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.ds Wh \ of the subimage, which define the dimensions of the rectangle
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height\*(Wh.
-.IP \fIplane_mask\fP 1i
-Specifies the plane mask.
-.\" *** JIM: NEED MORE INFO FOR THIS. ***
-.IP \fIformat\fP 1i
-Specifies the format for the image.
-You can pass
-.PN XYPixmap
-or 
-.PN ZPixmap .
-.IP \fIdest_image\fP 1i
-Specifies the destination image.
-.ds Dx , which are relative to the origin of the destination rectangle, \
-specify its upper-left corner, and determine where the subimage \
-is placed in the destination image
-.IP \fIdest_x\fP 1i
-.br
-.ns
-.IP \fIdest_y\fP 1i
-Specify the x and y coordinates\*(Dx. 
-.LP
-.eM
-The 
-.PN XGetSubImage 
-function updates dest_image with the specified subimage in the same manner as 
-.PN XGetImage . 
-If the format argument is 
-.PN XYPixmap ,
-the image contains only the bit planes you passed to the plane_mask argument.
-If the format argument is 
-.PN ZPixmap ,
-.PN XGetSubImage
-returns as zero the bits in all planes not 
-specified in the plane_mask argument.
-The function performs no range checking on the values in plane_mask and ignores
-extraneous bits.
-As a convenience,
-.PN XGetSubImage
-returns a pointer to the same
-.PN XImage
-structure specified by dest_image.
-.LP
-The depth of the destination
-.PN XImage
-structure must be the same as that of the drawable.
-If the specified subimage does not fit at the specified location
-on the destination image, the right and bottom edges are clipped.
-If the drawable is a pixmap,
-the given rectangle must be wholly contained within the pixmap,
-or a
-.PN BadMatch
-error results.
-If the drawable is a window, 
-the window must be viewable, 
-and it must be the case that if there were no inferiors or overlapping windows,
-the specified rectangle of the window would be fully visible on the screen
-and wholly contained within the outside edges of the window,
-or a
-.PN BadMatch
-error results.
-If the window has backing-store, 
-then the backing-store contents are returned for regions of the window 
-that are obscured by noninferior windows. 
-If the window does not have backing-store, 
-the returned contents of such obscured regions are undefined.
-The returned contents of visible regions of inferiors
-of a different depth than the specified window's depth are also undefined.
-If a problem occurs,
-.PN XGetSubImage
-returns NULL.
-.LP
-.PN XGetSubImage
-can generate
-.PN BadDrawable ,
-.PN BadGC ,
-.PN BadMatch ,
-and
-.PN BadValue 
-errors.
-.bp
diff --git a/libX11/specs/libX11/CH08.xml b/libX11/specs/libX11/CH08.xml
new file mode 100644
index 000000000..5f08f93f3
--- /dev/null
+++ b/libX11/specs/libX11/CH08.xml
@@ -0,0 +1,5960 @@
+<chapter id="graphics_functions">

+<title>Graphics Functions</title>

+<para>

+Once you have established a connection to a display, you can use the Xlib graphics functions to:

+</para>

+<itemizedlist>

+  <listitem><para>Clear and copy areas</para></listitem>

+  <listitem><para>Draw points, lines, rectangles, and arcs</para></listitem>

+  <listitem><para>Fill areas</para></listitem>

+  <listitem><para>Manipulate fonts</para></listitem>

+  <listitem><para>Draw text</para></listitem>

+  <listitem><para>Transfer images between clients and the server</para></listitem>

+</itemizedlist>

+<para>

+If the same drawable and GC is used for each call, Xlib batches back-to-back calls to XDraw-

+Point, XDrawLine, XDrawRectangle, XFillArc, and XFillRectangle. Note that this reduces

+the total number of requests sent to the server.

+</para>

+<sect1 id="Clearing_Areas">

+<title>Clearing Areas</title>

+<!-- .XS -->

+<!-- (SN Clearing Areas  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to clear an area or the entire window.

+Because pixmaps do not have defined backgrounds, 

+they cannot be filled by using the functions described in this section.

+Instead, to accomplish an analogous operation on a pixmap,

+you should use 

+<function>XFillRectangle</function>,

+which sets the pixmap to a known value.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To clear a rectangular area of a given window, use

+<function>XClearArea</function>.

+<indexterm><primary>Areas</primary><secondary>clearing</secondary></indexterm>

+<indexterm><primary>Clearing</primary><secondary>areas</secondary></indexterm>

+<indexterm significance="preferred"><primary>XClearArea</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XClearArea</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+  <paramdef>Bool<parameter> exposures</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+<!-- .ds Xy , which are relative to the origin of the window \ -->

+and specify the upper-left corner of the rectangle

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+<!-- .ds Wh , which are the dimensions of the rectangle -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height(Wh.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>exposures</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a Boolean value that indicates if

+<function>Expose</function>

+events are to be generated.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XClearArea</function>

+function paints a rectangular area in the specified window according to the

+specified dimensions with the window's background pixel or pixmap.

+The subwindow-mode effectively is

+<function>ClipByChildren</function>.

+If width is zero, it

+is replaced with the current width of the window minus x.

+If height is

+zero, it is replaced with the current height of the window minus y.

+If the window has a defined background tile, 

+the rectangle clipped by any children is filled with this tile.

+If the window has

+background 

+<function>None</function>,

+the contents of the window are not changed.  

+In either

+case, if exposures is 

+<function>True</function>,

+one or more 

+<function>Expose </function>

+events are generated for regions of the rectangle that are either visible or are

+being retained in a backing store.

+If you specify a window whose class is

+<function>InputOnly</function>,

+a

+<function>BadMatch</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+<function>XClearArea</function>

+can generate

+<function>BadMatch</function>,

+<function>BadValue</function>,

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To clear the entire area in a given window, use

+<function>XClearWindow</function>.

+<indexterm><primary>Window</primary><secondary>clearing</secondary></indexterm>

+<indexterm><primary>Clearing</primary><secondary>windows</secondary></indexterm>

+<indexterm significance="preferred"><primary>XClearWindow</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XClearWindow</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XClearWindow</function>

+function clears the entire area in the specified window and is

+equivalent to

+<function>XClearArea</function>

+(display, w, 0, 0, 0, 0, 

+<function>False</function>).

+If the window has a defined background tile, the rectangle is tiled with a

+plane-mask of all ones and 

+<function>GXcopy</function>

+function.

+If the window has

+background 

+<function>None</function>,

+the contents of the window are not changed.  

+If you specify a window whose class is

+<function>InputOnly</function>,

+a

+<function>BadMatch</function>

+error results. 

+</para>

+<para>

+<!-- .LP -->

+<function>XClearWindow</function>

+can generate

+<function>BadMatch</function>

+and

+<function>BadWindow </function>

+errors.

+</para>

+</sect1>

+<sect1 id="Copying_Areas">

+<title>Copying Areas</title>

+<!-- .XS -->

+<!-- (SN Copying Areas  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to copy an area or a bit plane.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To copy an area between drawables of the same

+root and depth, use

+<function>XCopyArea</function>.

+<indexterm><primary>Areas</primary><secondary>copying</secondary></indexterm>

+<indexterm><primary>Copying</primary><secondary>areas</secondary></indexterm>

+<indexterm significance="preferred"><primary>XCopyArea</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XCopyArea</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawablesrc,<parameter> dest</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+  <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>src</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dest</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the source and destination rectangles to be combined. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>src_x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>src_y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates, 

+which are relative to the origin of the source rectangle

+and specify its upper-left corner.

+<!-- .ds Wh , which are the dimensions of both the source \ -->

+and destination rectangles

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height(Wh.

+<!-- .ds Dx , which are relative to the origin of the destination rectangle \ -->

+and specify its upper-left corner

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dest_x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dest_y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Dx. 

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCopyArea</function>

+function combines the specified rectangle of src with the specified rectangle 

+of dest.

+The drawables must have the same root and depth,

+or a

+<function>BadMatch</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+If regions of the source rectangle are obscured and have not been

+retained in backing store 

+or if regions outside the boundaries of the source drawable are specified, 

+those regions are not copied. 

+Instead, the 

+following occurs on all corresponding destination regions that are either

+visible or are retained in backing store.  

+If the destination is a window with a background other than 

+<function>None</function>,

+corresponding regions

+of the destination are tiled with that background

+(with plane-mask of all ones and

+<function>GXcopy </function>

+function).

+Regardless of tiling or whether the destination is a window or a pixmap,

+if graphics-exposures is 

+<function>True</function>,

+then

+<function>GraphicsExpose</function>

+events for all corresponding destination regions are generated.

+If graphics-exposures is 

+<function>True </function>

+but no

+<function>GraphicsExpose</function>

+events are generated, a

+<function>NoExpose </function>

+event is generated.

+Note that by default graphics-exposures is

+<function>True</function>

+in new GCs.

+</para>

+<para>

+<!-- .LP -->

+This function uses these GC components: function, plane-mask, 

+subwindow-mode, graphics-exposures, clip-x-origin,

+clip-y-origin, and clip-mask.

+</para>

+<para>

+<!-- .LP -->

+<function>XCopyArea</function>

+can generate

+<function>BadDrawable</function>,

+<function>BadGC</function>,

+and

+<function>BadMatch </function>

+errors.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To copy a single bit plane of a given drawable, use

+<function>XCopyPlane</function>.

+<indexterm><primary>Plane</primary><secondary>copying</secondary></indexterm>

+<indexterm><primary>Copying</primary><secondary>planes</secondary></indexterm>

+<indexterm significance="preferred"><primary>XCopyPlane</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XCopyPlane</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawablesrc,<parameter> dest</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+  <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> plane</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>src</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dest</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the source and destination rectangles to be combined. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>src_x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>src_y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates, 

+which are relative to the origin of the source rectangle

+and specify its upper-left corner.

+<!-- .ds Wh , which are the dimensions of both the source and destination rectangles -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height(Wh.

+<!-- .ds Dx , which are relative to the origin of the destination rectangle \ -->

+and specify its upper-left corner

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dest_x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dest_y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Dx. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>plane</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the bit plane.

+You must set exactly one bit to 1.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCopyPlane</function>

+function uses a single bit plane of the specified source rectangle

+combined with the specified GC to modify the specified rectangle of dest.

+The drawables must have the same root but need not have the same depth.

+If the drawables do not have the same root, a

+<function>BadMatch</function>

+error results.

+If plane does not have exactly one bit set to 1 and the value of plane

+is not less than %2 sup n%, where <emphasis remap='I'>n</emphasis> is the depth of src, a

+<function>BadValue</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+Effectively, 

+<function>XCopyPlane</function>

+forms a pixmap of the same depth as the rectangle of dest and with a

+size specified by the source region. 

+It uses the foreground/background pixels in the GC (foreground

+everywhere the bit plane in src contains a bit set to 1,

+background everywhere the bit plane in src contains a bit set to 0)

+and the equivalent of a 

+<function>CopyArea</function>

+protocol request is performed with all the same exposure semantics.

+This can also be thought of as using the specified region of the source 

+bit plane as a stipple with a fill-style of

+<function>FillOpaqueStippled</function>

+for filling a rectangular area of the destination.

+</para>

+<para>

+<!-- .LP -->

+This function uses these GC components: function, plane-mask, foreground,

+background, subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin,

+and clip-mask.

+</para>

+<para>

+<!-- .LP -->

+<function>XCopyPlane</function>

+can generate

+<function>BadDrawable</function>,

+<function>BadGC</function>,

+<function>BadMatch</function>,

+and 

+<function>BadValue </function>

+errors.

+</para>

+</sect1>

+<sect1 id="Drawing_Points_Lines_Rectangles_and_Arcs">

+<title>Drawing Points, Lines, Rectangles, and Arcs</title>

+<!-- .XS -->

+<!-- (SN Drawing Points, Lines, Rectangles, and Arcs  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to draw:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+A single point or multiple points

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A single line or multiple lines

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A single rectangle or multiple rectangles

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A single arc or multiple arcs

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+Some of the functions described in the following sections

+use these structures:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XSegment</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i -->

+<!-- .ta .5i -->

+typedef struct {

+     short x1, y1, x2, y2;

+} XSegment;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>XPoint</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i -->

+<!-- .ta .5i -->

+typedef struct {

+     short x, y;

+} XPoint;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>XRectangle</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i -->

+<!-- .ta .5i -->

+typedef struct {

+     short x, y;

+     unsigned short width, height;

+} XRectangle;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>XArc</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     short x, y;

+     unsigned short width, height;

+     short angle1, angle2;             /* Degrees * 64 */

+} XArc;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+All x and y members are signed integers.

+The width and height members are 16-bit unsigned integers.

+You should be careful not to generate coordinates and sizes

+out of the 16-bit ranges, because the protocol only has 16-bit fields

+for these values.

+</para>

+<sect2 id="Drawing_Single_and_Multiple_Points">

+<title>Drawing Single and Multiple Points</title>

+<!-- .XS -->

+<!-- (SN Drawing Single and Multiple Points  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Points</primary><secondary>drawing</secondary></indexterm>

+<indexterm><primary>Drawing</primary><secondary>points</secondary></indexterm>

+<indexterm><primary>XDrawPoints</primary></indexterm>

+<indexterm><primary>XDrawPoint</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+To draw a single point in a given drawable, use

+<function>XDrawPoint</function>.

+<indexterm significance="preferred"><primary>XDrawPoint</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDrawPoint</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates where you want the point drawn.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To draw multiple points in a given drawable, use

+<function>XDrawPoints</function>.

+<indexterm significance="preferred"><primary>XDrawPoints</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDrawPoints</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>XPoint<parameter> *points</parameter></paramdef>

+  <paramdef>int<parameter> npoints</parameter></paramdef>

+  <paramdef>int<parameter> mode</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>points</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array of points.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>npoints</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of points in the array.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>mode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the coordinate mode. 

+You can pass

+<function>CoordModeOrigin</function>

+or

+<function>CoordModePrevious</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XDrawPoint</function>

+function uses the foreground pixel and function components of the

+GC to draw a single point into the specified drawable; 

+<function>XDrawPoints</function>

+draws multiple points this way.

+<function>CoordModeOrigin</function>

+treats all coordinates as relative to the origin,

+and

+<function>CoordModePrevious</function>

+treats all coordinates after the first as relative to the previous point.

+<function>XDrawPoints</function>

+draws the points in the order listed in the array.

+</para>

+<para>

+<!-- .LP -->

+Both functions use these GC components: function, plane-mask,

+foreground, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.

+</para>

+<para>

+<!-- .LP -->

+<function>XDrawPoint</function>

+can generate

+<function>BadDrawable</function>,

+<function>BadGC</function>,

+and 

+<function>BadMatch </function>

+errors.

+<function>XDrawPoints</function>

+can generate

+<function>BadDrawable</function>,

+<function>BadGC</function>,

+<function>BadMatch</function>,

+and

+<function>BadValue </function>

+errors.

+</para>

+</sect2>

+<sect2 id="Drawing_Single_and_Multiple_Lines">

+<title>Drawing Single and Multiple Lines</title>

+<!-- .XS -->

+<!-- (SN Drawing Single and Multiple Lines -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Lines</primary><secondary>drawing</secondary></indexterm>

+<indexterm><primary>Drawing</primary><secondary>lines</secondary></indexterm>

+<indexterm><primary>XDrawLine</primary></indexterm>

+<indexterm><primary>XDrawLines</primary></indexterm>

+<indexterm><primary>Polygons</primary><secondary>drawing</secondary></indexterm>

+<indexterm><primary>Drawing</primary><secondary>polygons</secondary></indexterm>

+<indexterm><primary>XDrawSegments</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+To draw a single line between two points in a given drawable, use

+<function>XDrawLine</function>.

+<indexterm significance="preferred"><primary>XDrawLine</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDrawLine</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intx1,y1,x2,<parameter> y2</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x1</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y1</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x2</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y2</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the points (x1, y1) and (x2, y2) to be connected.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To draw multiple lines in a given drawable, use

+<function>XDrawLines</function>.

+<indexterm significance="preferred"><primary>XDrawLines</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDrawLines</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>XPoint<parameter> *points</parameter></paramdef>

+  <paramdef>int<parameter> npoints</parameter></paramdef>

+  <paramdef>int<parameter> mode</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>points</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array of points.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>npoints</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of points in the array.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>mode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the coordinate mode. 

+You can pass

+<function>CoordModeOrigin</function>

+or

+<function>CoordModePrevious</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To draw multiple, unconnected lines in a given drawable,

+use

+<function>XDrawSegments</function>.

+<indexterm significance="preferred"><primary>XDrawSegments</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDrawSegments</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>XSegment<parameter> *segments</parameter></paramdef>

+  <paramdef>int<parameter> nsegments</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>segments</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array of segments.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nsegments</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of segments in the array.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XDrawLine</function>

+function uses the components of the specified GC to

+draw a line between the specified set of points (x1, y1) and (x2, y2).

+It does not perform joining at coincident endpoints.

+For any given line, 

+<function>XDrawLine </function>

+does not draw a pixel more than once.

+If lines intersect, the intersecting pixels are drawn multiple times.  

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XDrawLines</function>

+function uses the components of the specified GC to draw 

+npoints-1 lines between each pair of points (point[i], point[i+1]) 

+in the array of

+<function>XPoint</function>

+structures.

+It draws the lines in the order listed in the array.

+The lines join correctly at all intermediate points, and if the first and last

+points coincide, the first and last lines also join correctly.

+For any given line, 

+<function>XDrawLines</function>

+does not draw a pixel more than once.

+If thin (zero line-width) lines intersect, 

+the intersecting pixels are drawn multiple times.

+If wide lines intersect, the intersecting pixels are drawn only once, as though

+the entire 

+<function>PolyLine </function>

+protocol request were a single, filled shape.

+<function>CoordModeOrigin</function>

+treats all coordinates as relative to the origin,

+and

+<function>CoordModePrevious</function>

+treats all coordinates after the first as relative to the previous point.

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XDrawSegments </function>

+function draws multiple, unconnected lines. 

+For each segment, 

+<function>XDrawSegments </function>

+draws a

+line between (x1, y1) and (x2, y2).

+It draws the lines in the order listed in the array of

+<function>XSegment</function>

+structures and does not perform joining at coincident endpoints.

+For any given line, 

+<function>XDrawSegments</function>

+does not draw a pixel more than once.  

+If lines intersect, the intersecting pixels are drawn multiple times.  

+</para>

+<para>

+<!-- .LP -->

+All three functions use these GC components:

+function, plane-mask, line-width,

+line-style, cap-style, fill-style, subwindow-mode,

+clip-x-origin, clip-y-origin, and clip-mask.

+The

+<function>XDrawLines</function>

+function also uses the join-style GC component.

+All three functions also use these GC mode-dependent components:

+foreground, background, tile, stipple, tile-stipple-x-origin, 

+tile-stipple-y-origin, dash-offset, and dash-list.

+</para>

+<para>

+<!-- .LP -->

+<function>XDrawLine</function>,

+<function>XDrawLines</function>,

+and

+<function>XDrawSegments</function>

+can generate

+<function>BadDrawable</function>,

+<function>BadGC</function>,

+and

+<function>BadMatch </function>

+errors.

+<function>XDrawLines</function>

+also can generate

+<function>BadValue </function>

+errors.

+</para>

+</sect2>

+<sect2 id="Drawing_Single_and_Multiple_Rectangles_">

+<title>Drawing Single and Multiple Rectangles </title>

+<!-- .XS -->

+<!-- (SN Drawing Single and Multiple Rectangles  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Rectangles</primary><secondary>drawing</secondary></indexterm>

+<indexterm><primary>Drawing</primary><secondary>rectangles</secondary></indexterm>

+<indexterm><primary>XDrawRectangle</primary></indexterm>

+<indexterm><primary>XDrawRectangles</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+To draw the outline of a single rectangle in a given drawable, use

+<function>XDrawRectangle</function>.

+<indexterm significance="preferred"><primary>XDrawRectangle</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDrawRectangle</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+<!-- .ds Xy , which specify the upper-left corner of the rectangle -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+<!-- .ds Wh , which specify the dimensions of the rectangle -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height(Wh.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To draw the outline of multiple rectangles

+in a given drawable, use

+<function>XDrawRectangles</function>.

+<indexterm significance="preferred"><primary>XDrawRectangles</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDrawRectangles</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>XRectangle<parameter> rectangles[]</parameter></paramdef>

+  <paramdef>int<parameter> nrectangles</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>rectangles</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array of rectangles.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nrectangles</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of rectangles in the array.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XDrawRectangle</function>

+and

+<function>XDrawRectangles</function>

+functions draw the outlines of the specified rectangle or rectangles as

+if a five-point 

+<function>PolyLine </function>

+protocol request were specified for each rectangle:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+[x,y] [x+width,y] [x+width,y+height] [x,y+height] [x,y]

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP  -->

+For the specified rectangle or rectangles, 

+these functions do not draw a pixel more than once.

+<function>XDrawRectangles</function>

+draws the rectangles in the order listed in the array.

+If rectangles intersect,

+the intersecting pixels are drawn multiple times.

+</para>

+<para>

+<!-- .LP -->

+Both functions use these GC components: 

+function, plane-mask, line-width,

+line-style, cap-style, join-style, fill-style, 

+subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.

+They also use these GC mode-dependent components: 

+foreground, background, tile, stipple, tile-stipple-x-origin, 

+tile-stipple-y-origin, dash-offset, and dash-list.

+</para>

+<para>

+<!-- .LP -->

+<function>XDrawRectangle</function>

+and

+<function>XDrawRectangles</function>

+can generate

+<function>BadDrawable</function>,

+<function>BadGC</function>,

+and

+<function>BadMatch </function>

+errors.

+</para>

+</sect2>

+<sect2 id="Drawing_Single_and_Multiple_Arcs">

+<title>Drawing Single and Multiple Arcs</title>

+<!-- .XS -->

+<!-- (SN Drawing Single and Multiple Arcs  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Drawing</primary><secondary>arcs</secondary></indexterm>

+<indexterm><primary>XDrawArc</primary></indexterm>

+<indexterm><primary>Arcs</primary><secondary>drawing</secondary></indexterm>

+<indexterm><primary>XDrawArcs</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To draw a single arc in a given drawable, use

+<function>XDrawArc</function>.

+<indexterm significance="preferred"><primary>XDrawArc</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDrawArc</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+  <paramdef>intangle1,<parameter> angle2</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+<!-- .ds Xy , which are relative to the origin of the drawable \ -->

+and specify the upper-left corner of the bounding rectangle

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+<!-- .ds Wh , which are the major and minor axes of the arc -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height(Wh.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>angle1</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the start of the arc relative to the three-o'clock position

+from the center, in units of degrees * 64.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>angle2</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the path and extent of the arc relative to the start of the

+arc, in units of degrees * 64.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To draw multiple arcs in a given drawable, use

+<function>XDrawArcs</function>.

+<indexterm significance="preferred"><primary>XDrawArcs</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDrawArcs</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>XArc<parameter> *arcs</parameter></paramdef>

+  <paramdef>int<parameter> narcs</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>arcs</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array of arcs.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>narcs</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of arcs in the array.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .EQ -->

+delim %%

+<!-- .EN -->

+<function>XDrawArc</function>

+draws a single circular or elliptical arc, and 

+<function>XDrawArcs</function>

+draws multiple circular or elliptical arcs.

+Each arc is specified by a rectangle and two angles.  

+The center of the circle or ellipse is the center of the

+rectangle, and the major and minor axes are specified by the width and height.

+Positive angles indicate counterclockwise motion, 

+and negative angles indicate clockwise motion.  

+If the magnitude of angle2 is greater than 360 degrees, 

+<function>XDrawArc</function>

+or 

+<function>XDrawArcs</function>

+truncates it to 360 degrees.

+</para>

+<para>

+<!-- .LP -->

+For an arc specified as %[ ~x, ~y, ~width , ~height, ~angle1, ~angle2 ]%, 

+the origin of the major and minor axes is at 

+% [ x +^ {width over 2} , ~y +^ {height over 2}  ]%, 

+and the infinitely thin path describing the entire circle or ellipse 

+intersects the horizontal axis at % [ x, ~y +^ {height over 2}  ]% and 

+% [ x +^ width , ~y +^ { height over 2 }] %

+and intersects the vertical axis at % [ x +^ { width over 2 } , ~y ]% and 

+% [ x +^ { width over 2 }, ~y +^ height ]%.

+These coordinates can be fractional

+and so are not truncated to discrete coordinates.

+The path should be defined by the ideal mathematical path.  

+For a wide line with line-width lw, 

+the bounding outlines for filling are given        

+by the two infinitely thin paths consisting of all points whose perpendicular

+distance from the path of the circle/ellipse is equal to lw/2

+(which may be a fractional value).

+The cap-style and join-style are applied the same as for a line

+corresponding to the tangent of the circle/ellipse at the endpoint.

+</para>

+<para>

+<!-- .LP -->

+For an arc specified as % [ ~x, ~y, ~width, ~height, ~angle1, ~angle2  ]%,

+the angles must be specified

+in the effectively skewed coordinate system of the ellipse (for a

+circle, the angles and coordinate systems are identical).  The

+relationship between these angles and angles expressed in the normal

+coordinate system of the screen (as measured with a protractor) is as

+follows:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+% roman "skewed-angle" ~ = ~ atan left ( tan ( roman "normal-angle" )

+ * width over height right ) +^ adjust%

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+The skewed-angle and normal-angle are expressed in radians (rather

+than in degrees scaled by 64) in the range % [ 0 , ~2 pi  ]% and where atan

+returns a value in the range % [ - pi over 2 , ~pi over 2  ] %

+and adjust is:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA 1i 2i -->

+<!-- .ta 1i 2i -->

+%0%     for normal-angle in the range % [ 0 , ~pi over 2  ]%

+%pi%     for normal-angle in the range % [ pi over 2 , ~{3 pi} over 2  ]%

+%2 pi%     for normal-angle in the range % [ {3 pi} over 2 , ~2 pi  ]%

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+For any given arc, 

+<function>XDrawArc</function>

+and

+<function>XDrawArcs</function>

+do not draw a pixel more than once.  

+If two arcs join correctly and if the line-width is greater than zero 

+and the arcs intersect, 

+<function>XDrawArc</function>

+and

+<function>XDrawArcs</function>

+do not draw a pixel more than once.

+Otherwise, 

+the intersecting pixels of intersecting arcs are drawn multiple times.

+Specifying an arc with one endpoint and a clockwise extent draws the same pixels

+as specifying the other endpoint and an equivalent counterclockwise extent,

+except as it affects joins.

+</para>

+<para>

+<!-- .LP -->

+If the last point in one arc coincides with the first point in the following 

+arc, the two arcs will join correctly.  

+If the first point in the first arc coincides with the last point in the last 

+arc, the two arcs will join correctly.

+By specifying one axis to be zero, a horizontal or vertical line can be

+drawn.

+Angles are computed based solely on the coordinate system and ignore the

+aspect ratio.

+</para>

+<para>

+<!-- .LP -->

+Both functions use these GC components: 

+function, plane-mask, line-width, line-style, cap-style, join-style, 

+fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.

+They also use these GC mode-dependent components: 

+foreground, background, tile, stipple, tile-stipple-x-origin, 

+tile-stipple-y-origin, dash-offset, and dash-list.

+</para>

+<para>

+<!-- .LP -->

+<function>XDrawArc</function>

+and

+<function>XDrawArcs</function>

+can generate

+<function>BadDrawable</function>,

+<function>BadGC</function>,

+and

+<function>BadMatch </function>

+errors.

+</para>

+</sect2>

+</sect1>

+<sect1 id="Filling_Areas">

+<title>Filling Areas</title>

+<!-- .XS -->

+<!-- (SN Filling Areas  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to fill:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+A single rectangle or multiple rectangles

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A single polygon

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A single arc or multiple arcs

+    </para>

+  </listitem>

+</itemizedlist>

+<sect2 id="Filling_Single_and_Multiple_Rectangles">

+<title>Filling Single and Multiple Rectangles</title>

+<!-- .XS -->

+<!-- (SN Filling Single and Multiple Rectangles  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Filling</primary><secondary>rectangles</secondary></indexterm>

+<indexterm><primary>XFillRectangle</primary></indexterm>

+<indexterm><primary>Rectangle</primary><secondary>filling</secondary></indexterm>

+<indexterm><primary>XFillRectangles</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To fill a single rectangular area in a given drawable, use

+<function>XFillRectangle</function>.

+<indexterm significance="preferred"><primary>XFillRectangle</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XFillRectangle</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+<!-- .ds Xy , which are relative to the origin of the drawable \ -->

+and specify the upper-left corner of the rectangle

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+<!-- .ds Wh , which are the dimensions of the rectangle to be filled -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height(Wh.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To fill multiple rectangular areas in a given drawable, use

+<function>XFillRectangles</function>.

+<indexterm significance="preferred"><primary>XFillRectangles</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XFillRectangles</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>XRectangle<parameter> *rectangles</parameter></paramdef>

+  <paramdef>int<parameter> nrectangles</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>rectangles</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array of rectangles.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nrectangles</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of rectangles in the array.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XFillRectangle</function>

+and

+<function>XFillRectangles</function>

+functions fill the specified rectangle or rectangles

+as if a four-point 

+<function>FillPolygon</function>

+protocol request were specified for each rectangle:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+[x,y] [x+width,y] [x+width,y+height] [x,y+height]

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+Each function uses the x and y coordinates,

+width and height dimensions, and GC you specify.

+</para>

+<para>

+<!-- .LP -->

+<function>XFillRectangles</function>

+fills the rectangles in the order listed in the array.  

+For any given rectangle,

+<function>XFillRectangle</function>

+and

+<function>XFillRectangles</function>

+do not draw a pixel more than once.  

+If rectangles intersect, the intersecting pixels are

+drawn multiple times.

+</para>

+<para>

+<!-- .LP -->

+Both functions use these GC components: 

+function, plane-mask, fill-style, subwindow-mode, 

+clip-x-origin, clip-y-origin, and clip-mask.

+They also use these GC mode-dependent components: 

+foreground, background, tile, stipple, tile-stipple-x-origin, 

+and tile-stipple-y-origin.

+</para>

+<para>

+<!-- .LP -->

+<function>XFillRectangle</function>

+and

+<function>XFillRectangles</function>

+can generate

+<function>BadDrawable</function>,

+<function>BadGC</function>,

+and

+<function>BadMatch </function>

+errors.

+</para>

+</sect2>

+<sect2 id="Filling_a_Single_Polygon">

+<title>Filling a Single Polygon</title>

+<!-- .XS -->

+<!-- (SN Filling a Single Polygon  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To fill a polygon area in a given drawable, use

+<function>XFillPolygon</function>.

+<indexterm><primary>Polygons</primary><secondary>filling</secondary></indexterm>

+<indexterm><primary>Filling</primary><secondary>polygon</secondary></indexterm>

+<indexterm significance="preferred"><primary>XFillPolygon</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XFillPolygon</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>XPoint<parameter> *points</parameter></paramdef>

+  <paramdef>int<parameter> npoints</parameter></paramdef>

+  <paramdef>int<parameter> shape</parameter></paramdef>

+  <paramdef>int<parameter> mode</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>points</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array of points.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>npoints</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of points in the array.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>shape</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a shape that helps the server to improve performance.

+You can pass 

+<function>Complex</function>,

+<function>Convex</function>,

+or 

+<function>Nonconvex</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>mode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the coordinate mode. 

+You can pass

+<function>CoordModeOrigin</function>

+or

+<function>CoordModePrevious</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<function>XFillPolygon </function>

+fills the region closed by the specified path.

+The path is closed

+automatically if the last point in the list does not coincide with the

+first point.

+<function>XFillPolygon</function>

+does not draw a pixel of the region more than once.

+<function>CoordModeOrigin</function>

+treats all coordinates as relative to the origin,

+and

+<function>CoordModePrevious</function>

+treats all coordinates after the first as relative to the previous point.

+</para>

+<para>

+<!-- .LP -->

+Depending on the specified shape, the following occurs: 

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+If shape is

+<function>Complex</function>,

+the path may self-intersect. 

+Note that contiguous coincident points in the path are not treated 

+as self-intersection.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If shape is

+<function>Convex</function>,

+for every pair of points inside the polygon,

+the line segment connecting them does not intersect the path.

+If known by the client,

+specifying 

+<function>Convex </function>

+can improve performance.  

+If you specify

+<function>Convex </function>

+for a path that is not convex, 

+the graphics results are undefined.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If shape is

+<function>Nonconvex</function>,

+the path does not self-intersect, but the shape is not

+wholly convex. 

+If known by the client, 

+specifying 

+<function>Nonconvex </function>

+instead of

+<function>Complex </function>

+may improve performance.  

+If you specify

+<function>Nonconvex </function>

+for a self-intersecting path, the graphics results are undefined.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+The fill-rule of the GC controls the filling behavior of 

+self-intersecting polygons.

+</para>

+<para>

+<!-- .LP -->

+This function uses these GC components: 

+function, plane-mask, fill-style, fill-rule, subwindow-mode, clip-x-origin, 

+clip-y-origin, and clip-mask.

+It also uses these GC mode-dependent components: 

+foreground, background, tile, stipple, tile-stipple-x-origin, 

+and tile-stipple-y-origin.

+</para>

+<para>

+<!-- .LP -->

+<function>XFillPolygon</function>

+can generate

+<function>BadDrawable</function>,

+<function>BadGC</function>,

+<function>BadMatch</function>,

+and

+<function>BadValue </function>

+errors.

+</para>

+</sect2>

+<sect2 id="Filling_Single_and_Multiple_Arcs">

+<title>Filling Single and Multiple Arcs</title>

+<!-- .XS -->

+<!-- (SN Filling Single and Multiple Arcs  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>XFillArc</primary></indexterm>

+<indexterm><primary>Arcs</primary><secondary>filling</secondary></indexterm>

+<indexterm><primary>Filling</primary><secondary>arcs</secondary></indexterm>

+To fill a single arc in a given drawable, use

+<function>XFillArc</function>.

+<indexterm significance="preferred"><primary>XFillArc</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XFillArc</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+  <paramdef>intangle1,<parameter> angle2</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+<!-- .ds Xy , which are relative to the origin of the drawable \ -->

+and specify the upper-left corner of the bounding rectangle

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+<!-- .ds Wh , which are the major and minor axes of the arc -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height(Wh.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>angle1</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the start of the arc relative to the three-o'clock position

+from the center, in units of degrees * 64.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>angle2</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the path and extent of the arc relative to the start of the

+arc, in units of degrees * 64.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To fill multiple arcs in a given drawable, use

+<function>XFillArcs</function>.

+<indexterm significance="preferred"><primary>XFillArcs</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XFillArcs</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>XArc<parameter> *arcs</parameter></paramdef>

+  <paramdef>int<parameter> narcs</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>arcs</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array of arcs.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>narcs</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of arcs in the array.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+For each arc, 

+<function>XFillArc</function>

+or

+<function>XFillArcs</function>

+fills the region closed by the infinitely thin path

+described by the specified arc and, depending on the 

+arc-mode specified in the GC, one or two line segments. 

+For 

+<function>ArcChord</function>,

+the single line segment joining the endpoints of the arc is used.  

+For 

+<function>ArcPieSlice</function>,

+the two line segments joining the endpoints of the arc with the center

+point are used.  

+<function>XFillArcs</function>

+fills the arcs in the order listed in the array.  

+For any given arc,  

+<function>XFillArc</function>

+and

+<function>XFillArcs</function>

+do not draw a pixel more than once.  

+If regions intersect, 

+the intersecting pixels are drawn multiple times.

+</para>

+<para>

+<!-- .LP -->

+Both functions use these GC components: 

+function, plane-mask, fill-style, arc-mode, subwindow-mode, clip-x-origin, 

+clip-y-origin, and clip-mask.

+They also use these GC mode-dependent components: 

+foreground, background, tile, stipple, tile-stipple-x-origin, 

+and tile-stipple-y-origin.

+</para>

+<para>

+<!-- .LP -->

+<function>XFillArc</function>

+and

+<function>XFillArcs</function>

+can generate

+<function>BadDrawable</function>,

+<function>BadGC</function>,

+and

+<function>BadMatch </function>

+errors.

+</para>

+</sect2>

+</sect1>

+<sect1 id="Font_Metrics">

+<title>Font Metrics</title>

+<!-- .XS -->

+<!-- (SN Font Metrics  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Font</primary></indexterm>

+A font is a graphical description of a set of characters that are used to 

+increase efficiency whenever a set of small, similar sized patterns are 

+repeatedly used.

+</para>

+<para>

+<!-- .LP -->

+This section discusses how to:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Load and free fonts

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Obtain and free font names

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Compute character string sizes

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Compute logical extents

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Query character string sizes

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+The X server loads fonts whenever a program requests a new font.

+The server can cache fonts for quick lookup.

+Fonts are global across all screens in a server.

+Several levels are possible when dealing with fonts.

+Most applications simply use 

+<function>XLoadQueryFont</function>

+to load a font and query the font metrics.

+</para>

+<para>

+<!-- .LP -->

+Characters in fonts are regarded as masks.

+Except for image text requests,

+the only pixels modified are those in which bits are set to 1 in the character.

+This means that it makes sense to draw text using stipples or tiles

+(for example, many menus gray-out unusable entries).

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+The

+<function>XFontStruct</function>

+structure contains all of the information for the font

+and consists of the font-specific information as well as

+a pointer to an array of

+<function>XCharStruct</function>

+structures for the

+characters contained in the font.

+The

+<function>XFontStruct</function>,

+<function>XFontProp</function>,

+and

+<function>XCharStruct</function>

+structures contain:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XCharStruct</primary></indexterm>

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     short lbearing;               /* origin to left edge of raster */

+     short rbearing;               /* origin to right edge of raster */

+     short width;                  /* advance to next char's origin */

+     short ascent;                 /* baseline to top edge of raster */

+     short descent;                /* baseline to bottom edge of raster */

+     unsigned short attributes;    /* per char flags (not predefined) */

+} XCharStruct;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XFontProp</primary></indexterm>

+<literallayout class="monospaced">

+<!-- .TA .5i 1i 3i -->

+<!-- .ta .5i 1i 3i -->

+typedef struct {

+     Atom     name;

+     unsigned long card32;

+} XFontProp;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XChar2b</primary></indexterm>

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {     /* normal 16 bit characters are two bytes */

+    unsigned char byte1;

+    unsigned char byte2;

+} XChar2b;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XFontStruct</primary></indexterm>

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     XExtData *ext_data;               /* hook for extension to hang data */

+     Font fid;                         /* Font id for this font */

+     unsigned direction;               /* hint about the direction font is painted */

+     unsigned min_char_or_byte2;       /* first character */

+     unsigned max_char_or_byte2;       /* last character */

+     unsigned min_byte1;               /* first row that exists */

+     unsigned max_byte1;               /* last row that exists */

+     Bool all_chars_exist;             /* flag if all characters have nonzero size */

+     unsigned default_char;            /* char to print for undefined character */

+     int n_properties;                 /* how many properties there are */

+     XFontProp *properties;            /* pointer to array of additional properties */

+     XCharStruct min_bounds;           /* minimum bounds over all existing char */

+     XCharStruct max_bounds;           /* maximum bounds over all existing char */

+     XCharStruct *per_char;            /* first_char to last_char information */

+     int ascent;                       /* logical extent above baseline for spacing */

+     int descent;                      /* logical descent below baseline for spacing */

+} XFontStruct;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+X supports single byte/character, two bytes/character matrix,

+and 16-bit character text operations.

+Note that any of these forms can be used with a font, but a

+single byte/character text request can only specify a single byte

+(that is, the first row of a 2-byte font).

+You should view 2-byte fonts as a two-dimensional matrix of defined

+characters: byte1 specifies the range of defined rows and

+byte2 defines the range of defined columns of the font.

+Single byte/character fonts have one row defined, and the byte2 range

+specified in the structure defines a range of characters.

+</para>

+<para>

+<!-- .LP -->

+The bounding box of a character is defined by the 

+<function>XCharStruct </function>

+of that character.

+When characters are absent from a font,

+the default_char is used.

+When fonts have all characters of the same size,

+only the information in the

+<function>XFontStruct</function>

+min and max bounds are used.

+</para>

+<para>

+<!-- .LP -->

+The members of the 

+<function>XFontStruct </function>

+have the following semantics:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+The direction member can be either 

+<function>FontLeftToRight </function>

+or 

+<function>FontRightToLeft</function>.

+It is just a hint as to whether most 

+<function>XCharStruct </function>

+elements 

+have a positive 

+(<function>FontLeftToRight</function>)

+or a negative 

+(<function>FontRightToLeft</function>)

+character width 

+metric.

+The core protocol defines no support for vertical text.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If the min_byte1 and max_byte1 members are both zero, min_char_or_byte2

+specifies the linear character index corresponding to the first element

+of the per_char array, and max_char_or_byte2 specifies the linear character

+index of the last element.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If either min_byte1 or max_byte1 are nonzero, both

+min_char_or_byte2 and max_char_or_byte2 are less than 256, 

+and the 2-byte character index values corresponding to the

+per_char array element N (counting from 0) are:

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<!-- .nf -->

+     byte1 = N/D + min_byte1

+<!-- .br -->

+     byte2 = N\\D + min_char_or_byte2

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<!-- .fi -->

+where:

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<!-- .nf -->

+        D = max_char_or_byte2 - min_char_or_byte2 + 1

+        / = integer division

+        \\ = integer modulus

+<!-- .fi -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If the per_char pointer is NULL, 

+all glyphs between the first and last character indexes

+inclusive have the same information,

+as given by both min_bounds and max_bounds.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If all_chars_exist is 

+<function>True</function>,

+all characters in the per_char array have nonzero bounding boxes.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The default_char member specifies the character that will be used when an

+undefined or nonexistent character is printed.  

+The default_char is a 16-bit character (not a 2-byte character).

+For a font using 2-byte matrix format, 

+the default_char has byte1 in the most-significant byte

+and byte2 in the least significant byte.

+If the default_char itself specifies an undefined or nonexistent character, 

+no printing is performed for an undefined or nonexistent character.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The min_bounds and max_bounds members contain the most extreme values of

+each individual 

+<function>XCharStruct </function>

+component over all elements of this array

+(and ignore nonexistent characters).

+The bounding box of the font (the smallest

+rectangle enclosing the shape obtained by superimposing all of the

+characters at the same origin [x,y]) has its upper-left coordinate at:

+<literallayout class="monospaced">

+     [x + min_bounds.lbearing, y - max_bounds.ascent]

+</literallayout>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Its width is:

+<literallayout class="monospaced">

+     max_bounds.rbearing - min_bounds.lbearing

+</literallayout>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Its height is:

+<literallayout class="monospaced">

+     max_bounds.ascent + max_bounds.descent

+</literallayout>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The ascent member is the logical extent of the font above the baseline that is

+used for determining line spacing.

+Specific characters may extend beyond

+this.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The descent member is the logical extent of the font at or below the

+baseline that is used for determining line spacing.

+Specific characters may extend beyond this.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If the baseline is at Y-coordinate y,

+the logical extent of the font is inclusive between the Y-coordinate 

+values (y - font.ascent) and (y + font.descent - 1).

+Typically,

+the minimum interline spacing between rows of text is given

+by ascent + descent.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+For a character origin at [x,y],

+the bounding box of a character (that is, 

+the smallest rectangle that encloses the character's shape)

+described in terms of 

+<function>XCharStruct </function>

+components is a rectangle with its upper-left corner at:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+[x + lbearing, y - ascent]

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+Its width is:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+rbearing - lbearing

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+Its height is:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+ascent + descent

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+The origin for the next character is defined to be:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+[x + width, y]

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+The lbearing member defines the extent of the left edge of the character ink

+from the origin.

+The rbearing member defines the extent of the right edge of the character ink

+from the origin.

+The ascent member defines the extent of the top edge of the character ink

+from the origin.

+The descent member defines the extent of the bottom edge of the character ink

+from the origin.

+The width member defines the logical width of the character.

+</para>

+<para>

+<!-- .LP -->

+Note that the baseline (the y position of the character origin) 

+is logically viewed as being the scanline just below nondescending characters. 

+When descent is zero,

+only pixels with Y-coordinates less than y are drawn,

+and the origin is logically viewed as being coincident with the left edge of

+a nonkerned character. 

+When lbearing is zero,

+no pixels with X-coordinate less than x are drawn.

+Any of the

+<function>XCharStruct</function>

+metric members could be negative.

+If the width is negative,

+the next character will be placed to the left of the current origin.

+</para>

+<para>

+<!-- .LP -->

+The X protocol does not define the interpretation of the attributes member 

+in the

+<function>XCharStruct</function>

+structure.

+A nonexistent character is represented with all members of its

+<function>XCharStruct</function>

+set to zero.

+</para>

+<para>

+<!-- .LP -->

+A font is not guaranteed to have any properties.

+The interpretation of the property value (for example, long or unsigned long)

+must be derived from <emphasis remap='I'>a priori</emphasis> knowledge of the property. 

+A basic set of font properties is specified in the X Consortium standard

+<emphasis remap='I'>X Logical Font Description Conventions</emphasis>.

+</para>

+<sect2 id="Loading_and_Freeing_Fonts">

+<title>Loading and Freeing Fonts</title>

+<!-- .XS -->

+<!-- (SN Loading and Freeing Fonts  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to load fonts, get font information,

+unload fonts, and free font information.

+<indexterm><primary>Fonts</primary><secondary>getting information</secondary></indexterm>

+<indexterm><primary>Fonts</primary><secondary>unloading</secondary></indexterm>

+<indexterm><primary>Fonts</primary><secondary>freeing font information</secondary></indexterm>

+A few font functions use a 

+<function>GContext </function>

+resource ID or a font ID interchangeably.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To load a given font, use

+<function>XLoadFont</function>.

+<indexterm significance="preferred"><primary>XLoadFont</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Font<function> XLoadFont</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>char<parameter> *name</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the name of the font,

+which is a null-terminated string.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XLoadFont</function>

+function loads the specified font and returns its associated font ID.

+If the font name is not in the Host Portable Character Encoding,

+the result is implementation-dependent.

+Use of uppercase or lowercase does not matter.

+When the characters ``?'' and ``*'' are used in a font name, a

+pattern match is performed and any matching font is used.

+In the pattern, 

+the ``?'' character will match any single character, 

+and the ``*'' character will match any number of characters.

+A structured format for font names is specified in the X Consortium standard 

+<emphasis remap='I'>X Logical Font Description Conventions</emphasis>.

+If 

+<function>XLoadFont</function>

+was unsuccessful at loading the specified font, 

+a 

+<function>BadName </function>

+error results.

+Fonts are not associated with a particular screen 

+and can be stored as a component

+of any GC.

+When the font is no longer needed, call 

+<function>XUnloadFont</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XLoadFont</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadName </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To return information about an available font, use

+<function>XQueryFont</function>.

+<indexterm significance="preferred"><primary>XQueryFont</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XFontStruct<function> *XQueryFont</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XID<parameter> font_ID</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_ID</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the font ID or the 

+<function>GContext</function>

+ID.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XQueryFont</function>

+function returns a pointer to the

+<function>XFontStruct</function>

+structure, which contains information associated with the font.

+You can query a font or the font stored in a GC.

+The font ID stored in the 

+<function>XFontStruct</function>

+structure will be the 

+<function>GContext </function>

+ID, and you need to be careful when using this ID in other functions

+(see

+<function>XGContextFromGC</function>).

+If the font does not exist,

+<function>XQueryFont</function>

+returns NULL.

+To free this data, use

+<function>XFreeFontInfo</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To perform a

+<function>XLoadFont</function>

+and

+<function>XQueryFont</function>

+in a single operation, use

+<function>XLoadQueryFont</function>.

+<indexterm significance="preferred"><primary>XLoadQueryFont</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XFontStruct<function> *XLoadQueryFont</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>char<parameter> *name</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the name of the font,

+which is a null-terminated string.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XLoadQueryFont</function>

+function provides the most common way for accessing a font.

+<function>XLoadQueryFont</function>

+both opens (loads) the specified font and returns a pointer to the

+appropriate

+<function>XFontStruct</function>

+structure.

+If the font name is not in the Host Portable Character Encoding,

+the result is implementation-dependent.

+If the font does not exist,

+<function>XLoadQueryFont</function>

+returns NULL.

+</para>

+<para>

+<!-- .LP -->

+<function>XLoadQueryFont</function>

+can generate a

+<function>BadAlloc </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To unload the font and free the storage used by the font structure

+that was allocated by

+<function>XQueryFont</function>

+or

+<function>XLoadQueryFont</function>,

+use

+<function>XFreeFont</function>.

+<indexterm significance="preferred"><primary>XFreeFont</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XFreeFont</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_struct</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the storage associated with the font.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XFreeFont</function>

+function deletes the association between the font resource ID and the specified 

+font and frees the

+<function>XFontStruct</function>

+structure.

+The font itself will be freed when no other resource references it.

+The data and the font should not be referenced again.

+</para>

+<para>

+<!-- .LP -->

+<function>XFreeFont</function>

+can generate a

+<function>BadFont </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To return a given font property, use

+<function>XGetFontProperty</function>.

+<indexterm significance="preferred"><primary>XGetFontProperty</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool<function> XGetFontProperty</function></funcdef>

+  <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>

+  <paramdef>Atom<parameter> atom</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> *value_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_struct</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the storage associated with the font.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>atom</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the atom for the property name you want returned.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>value_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the value of the font property.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Given the atom for that property,

+the

+<function>XGetFontProperty</function>

+function returns the value of the specified font property. 

+<function>XGetFontProperty</function>

+also returns 

+<function>False</function>

+if the property was not defined or 

+<function>True</function>

+if it was defined.

+A set of predefined atoms exists for font properties,

+which can be found in

+<!-- .hN X11/Xatom.h . -->

+This set contains the standard properties associated with

+a font.

+Although it is not guaranteed,

+it is likely that the predefined font properties will be present.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To unload a font that was loaded by

+<function>XLoadFont</function>,

+use

+<function>XUnloadFont</function>.

+<indexterm significance="preferred"><primary>XUnloadFont</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XUnloadFont</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Font<parameter> font</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the font.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XUnloadFont</function>

+function deletes the association between the font resource ID and the specified font.

+The font itself will be freed when no other resource references it.

+The font should not be referenced again.

+</para>

+<para>

+<!-- .LP -->

+<function>XUnloadFont</function>

+can generate a

+<function>BadFont </function>

+error.

+</para>

+</sect2>

+<sect2 id="Obtaining_and_Freeing_Font_Names_and_Information">

+<title>Obtaining and Freeing Font Names and Information</title>

+<!-- .XS -->

+<!-- (SN Obtaining and Freeing Font Names and Information -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+You obtain font names and information by matching a wildcard specification

+when querying a font type for a list of available sizes and so on.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To return a list of the available font names, use

+<function>XListFonts</function>.

+<indexterm significance="preferred"><primary>XListFonts</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> **XListFonts</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>char<parameter> *pattern</parameter></paramdef>

+  <paramdef>int<parameter> maxnames</parameter></paramdef>

+  <paramdef>int<parameter> *actual_count_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>pattern</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the null-terminated pattern string that can contain wildcard 

+characters.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>maxnames</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the maximum number of names to be returned.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>actual_count_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the actual number of font names.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XListFonts</function>

+function returns an array of available font names 

+(as controlled by the font search path; see

+<function>XSetFontPath</function>)

+that match the string you passed to the pattern argument.

+The pattern string can contain any characters,

+but each asterisk (*) is a wildcard for any number of characters,

+and each question mark (?) is a wildcard for a single character.

+If the pattern string is not in the Host Portable Character Encoding,

+the result is implementation-dependent.

+Use of uppercase or lowercase does not matter.

+Each returned string is null-terminated.

+If the data returned by the server is in the Latin Portable Character Encoding,

+then the returned strings are in the Host Portable Character Encoding.

+Otherwise, the result is implementation-dependent.

+If there are no matching font names,

+<function>XListFonts</function>

+returns NULL.

+The client should call

+<function>XFreeFontNames</function>

+when finished with the result to free the memory.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To free a font name array, use

+<function>XFreeFontNames</function>.

+<indexterm significance="preferred"><primary>XFreeFontNames</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XFreeFontNames</function></funcdef>

+  <paramdef>char<parameter> *list[]</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>list</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the array of strings you want to free.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XFreeFontNames</function>

+function frees the array and strings returned by

+<function>XListFonts </function>

+or

+<function>XListFontsWithInfo</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the names and information about available fonts, use

+<function>XListFontsWithInfo</function>.

+<indexterm significance="preferred"><primary>XListFontsWithInfo</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> **XListFontsWithInfo</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>char<parameter> *pattern</parameter></paramdef>

+  <paramdef>int<parameter> maxnames</parameter></paramdef>

+  <paramdef>int<parameter> *count_return</parameter></paramdef>

+  <paramdef>XFontStruct<parameter> **info_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>pattern</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the null-terminated pattern string that can contain wildcard 

+characters.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>maxnames</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the maximum number of names to be returned.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>count_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the actual number of matched font names.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>info_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the font information.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XListFontsWithInfo</function>

+function returns a list of font names that match the specified pattern and their

+associated font information.

+The list of names is limited to size specified by maxnames.

+The information returned for each font is identical to what

+<function>XLoadQueryFont</function>

+would return except that the per-character metrics are not returned.

+The pattern string can contain any characters,

+but each asterisk (*) is a wildcard for any number of characters,

+and each question mark (?) is a wildcard for a single character.

+If the pattern string is not in the Host Portable Character Encoding,

+the result is implementation-dependent.

+Use of uppercase or lowercase does not matter.

+Each returned string is null-terminated.

+If the data returned by the server is in the Latin Portable Character Encoding,

+then the returned strings are in the Host Portable Character Encoding.

+Otherwise, the result is implementation-dependent.

+If there are no matching font names,

+<function>XListFontsWithInfo</function>

+returns NULL.

+</para>

+<para>

+<!-- .LP -->

+To free only the allocated name array,

+the client should call

+<function>XFreeFontNames</function>.

+To free both the name array and the font information array

+or to free just the font information array,

+the client should call

+<function>XFreeFontInfo</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To free font structures and font names, use

+<function>XFreeFontInfo</function>.

+<indexterm significance="preferred"><primary>XFreeFontInfo</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XFreeFontInfo</function></funcdef>

+  <paramdef>char<parameter> **names</parameter></paramdef>

+  <paramdef>XFontStruct<parameter> *free_info</parameter></paramdef>

+  <paramdef>int<parameter> actual_count</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>names</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the list of font names.

+

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>free_info</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the font information.

+

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>actual_count</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the actual number of font names.

+

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XFreeFontInfo</function>

+function frees a font structure or an array of font structures

+and optionally an array of font names.

+If NULL is passed for names, no font names are freed.

+If a font structure for an open font (returned by

+<function>XLoadQueryFont</function>)

+is passed, the structure is freed,

+but the font is not closed; use

+<function>XUnloadFont</function>

+to close the font.

+</para>

+</sect2>

+<sect2 id="Computing_Character_String_Sizes">

+<title>Computing Character String Sizes</title>

+<!-- .XS -->

+<!-- (SN Computing Character String Sizes  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to compute the width,

+the logical extents, 

+and the server information about 8-bit and 2-byte text strings.

+<indexterm><primary>XTextWidth</primary></indexterm>

+<indexterm><primary>XTextWidth16</primary></indexterm>

+The width is computed by adding the character widths of all the characters.

+It does not matter if the font is an 8-bit or 2-byte font.

+These functions return the sum of the character metrics in pixels.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To determine the width of an 8-bit character string, use

+<function>XTextWidth</function>.

+<indexterm significance="preferred"><primary>XTextWidth</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> XTextWidth</function></funcdef>

+  <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>

+  <paramdef>char<parameter> *string</parameter></paramdef>

+  <paramdef>int<parameter> count</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_struct</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the font used for the width computation.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the character string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>count</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the character count in the specified string.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To determine the width of a 2-byte character string, use

+<function>XTextWidth16</function>.

+<indexterm significance="preferred"><primary>XTextWidth16</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> XTextWidth16</function></funcdef>

+  <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>

+  <paramdef>XChar2b<parameter> *string</parameter></paramdef>

+  <paramdef>int<parameter> count</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_struct</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the font used for the width computation.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the character string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>count</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the character count in the specified string.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+</para>

+</sect2>

+<sect2 id="Computing_Logical_Extents">

+<title>Computing Logical Extents</title>

+<!-- .XS -->

+<!-- (SN Computing Logical Extents  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To compute the bounding box of an 8-bit character string in a given font, use

+<function>XTextExtents</function>.

+<indexterm significance="preferred"><primary>XTextExtents</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XTextExtents</function></funcdef>

+  <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>

+  <paramdef>char<parameter> *string</parameter></paramdef>

+  <paramdef>int<parameter> nchars</parameter></paramdef>

+  <paramdef>int<parameter> *direction_return</parameter></paramdef>

+  <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef>

+  <paramdef>XCharStruct<parameter> *overall_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_struct</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the 

+<function>XFontStruct </function>

+structure.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the character string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nchars</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of characters in the character string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>direction_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the value of the direction hint

+(<function>FontLeftToRight</function>

+or

+<function>FontRightToLeft</function>).

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_ascent_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the font ascent.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_descent_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the font descent.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>overall_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the overall size in the specified

+<function>XCharStruct </function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To compute the bounding box of a 2-byte character string in a given font, use

+<function>XTextExtents16</function>.

+<indexterm significance="preferred"><primary>XTextExtents16</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XTextExtents16</function></funcdef>

+  <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>

+  <paramdef>XChar2b<parameter> *string</parameter></paramdef>

+  <paramdef>int<parameter> nchars</parameter></paramdef>

+  <paramdef>int<parameter> *direction_return</parameter></paramdef>

+  <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef>

+  <paramdef>XCharStruct<parameter> *overall_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_struct</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the 

+<function>XFontStruct </function>

+structure.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the character string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nchars</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of characters in the character string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>direction_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the value of the direction hint

+(<function>FontLeftToRight</function>

+or

+<function>FontRightToLeft</function>).

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_ascent_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the font ascent.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_descent_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the font descent.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>overall_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the overall size in the specified

+<function>XCharStruct </function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XTextExtents</function>

+and

+<function>XTextExtents16</function>

+functions 

+perform the size computation locally and, thereby,

+avoid the round-trip overhead of

+<function>XQueryTextExtents </function>

+and

+<function>XQueryTextExtents16</function>.

+Both functions return an

+<function>XCharStruct</function>

+structure, whose members are set to the values as follows.

+</para>

+<para>

+<!-- .LP -->

+The ascent member is set to the maximum of the ascent metrics of all

+characters in the string.

+The descent member is set to the maximum of the descent metrics.

+The width member is set to the sum of the character-width metrics of all

+characters in the string.

+For each character in the string,

+let W be the sum of the character-width metrics of all characters preceding 

+it in the string.

+Let L be the left-side-bearing metric of the character plus W.

+Let R be the right-side-bearing metric of the character plus W.

+The lbearing member is set to the minimum L of all characters in the string.

+The rbearing member is set to the maximum R.

+</para>

+<para>

+<!-- .LP -->

+For fonts defined with linear indexing rather than 2-byte matrix indexing,

+each 

+<function>XChar2b </function>

+structure is interpreted as a 16-bit number with byte1 as the 

+most significant byte.

+If the font has no defined default character,

+undefined characters in the string are taken to have all zero metrics.

+</para>

+</sect2>

+<sect2 id="Querying_Character_String_Sizes">

+<title>Querying Character String Sizes</title>

+<!-- .XS -->

+<!-- (SN Querying Character String Sizes  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To query the server for the bounding box of an 8-bit character string in a 

+given font, use 

+<function>XQueryTextExtents</function>.

+<indexterm significance="preferred"><primary>XQueryTextExtents</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XQueryTextExtents</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XID<parameter> font_ID</parameter></paramdef>

+  <paramdef>char<parameter> *string</parameter></paramdef>

+  <paramdef>int<parameter> nchars</parameter></paramdef>

+  <paramdef>int<parameter> *direction_return</parameter></paramdef>

+  <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef>

+  <paramdef>XCharStruct<parameter> *overall_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_ID</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies either the font ID or the 

+<function>GContext</function>

+ID that contains the font.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the character string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nchars</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of characters in the character string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>direction_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the value of the direction hint

+(<function>FontLeftToRight</function>

+or

+<function>FontRightToLeft</function>).

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_ascent_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the font ascent.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_descent_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the font descent.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>overall_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the overall size in the specified

+<function>XCharStruct </function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To query the server for the bounding box of a 2-byte character string

+in a given font, use

+<function>XQueryTextExtents16</function>.

+<indexterm significance="preferred"><primary>XQueryTextExtents16</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XQueryTextExtents16</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XID<parameter> font_ID</parameter></paramdef>

+  <paramdef>XChar2b<parameter> *string</parameter></paramdef>

+  <paramdef>int<parameter> nchars</parameter></paramdef>

+  <paramdef>int<parameter> *direction_return</parameter></paramdef>

+  <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef>

+  <paramdef>XCharStruct<parameter> *overall_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_ID</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies either the font ID or the 

+<function>GContext</function>

+ID that contains the font.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the character string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nchars</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of characters in the character string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>direction_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the value of the direction hint

+(<function>FontLeftToRight</function>

+or

+<function>FontRightToLeft</function>).

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_ascent_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the font ascent.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_descent_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the font descent.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>overall_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the overall size in the specified

+<function>XCharStruct </function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XQueryTextExtents</function>

+and

+<function>XQueryTextExtents16</function>

+functions return the bounding box of the specified 8-bit and 16-bit

+character string in the specified font or the font contained in the

+specified GC.

+These functions query the X server and, therefore, suffer the round-trip

+overhead that is avoided by

+<function>XTextExtents</function>

+and 

+<function>XTextExtents16</function>.

+Both functions return a

+<function>XCharStruct </function>

+structure, whose members are set to the values as follows.

+</para>

+<para>

+<!-- .LP -->

+The ascent member is set to the maximum of the ascent metrics 

+of all characters in the string.

+The descent member is set to the maximum of the descent metrics.

+The width member is set to the sum of the character-width metrics 

+of all characters in the string.

+For each character in the string,

+let W be the sum of the character-width metrics of all characters preceding

+it in the string.

+Let L be the left-side-bearing metric of the character plus W.

+Let R be the right-side-bearing metric of the character plus W.

+The lbearing member is set to the minimum L of all characters in the string.

+The rbearing member is set to the maximum R.

+</para>

+<para>

+<!-- .LP -->

+For fonts defined with linear indexing rather than 2-byte matrix indexing,

+each 

+<function>XChar2b </function>

+structure is interpreted as a 16-bit number with byte1 as the 

+most significant byte.

+If the font has no defined default character,

+undefined characters in the string are taken to have all zero metrics.

+</para>

+<para>

+<!-- .LP -->

+Characters with all zero metrics are ignored.

+If the font has no defined default_char,

+the undefined characters in the string are also ignored.

+</para>

+<para>

+<!-- .LP -->

+<function>XQueryTextExtents</function>

+and

+<function>XQueryTextExtents16</function>

+can generate

+<function>BadFont</function>

+and

+<function>BadGC </function>

+errors.

+</para>

+</sect2>

+</sect1>

+<sect1 id="Drawing_Text">

+<title>Drawing Text</title>

+<!-- .XS -->

+<!-- (SN Drawing Text -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+This section discusses how to draw:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Complex text 

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Text characters

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Image text characters

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+The fundamental text functions

+<function>XDrawText</function>

+and

+<function>XDrawText16</function>

+use the following structures:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XTextItem</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     char *chars;     /* pointer to string */

+     int nchars;      /* number of characters */

+     int delta;       /* delta between strings */

+     Font font;       /* Font to print it in, None don't change */

+} XTextItem;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XTextItem16</primary></indexterm>

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     XChar2b *chars;     /* pointer to two-byte characters */

+     int nchars;         /* number of characters */

+     int delta;         /* delta between strings */

+     Font font;         /* font to print it in, None don't change */

+} XTextItem16;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If the font member is not

+<function>None</function>,

+the font is changed before printing and also is stored in the GC.

+If an error was generated during text drawing,

+the previous items may have been drawn.

+The baseline of the characters are drawn starting at the x and y

+coordinates that you pass in the text drawing functions.

+</para>

+<para>

+<!-- .LP -->

+For example, consider the background rectangle drawn by

+<function>XDrawImageString</function>.

+If you want the upper-left corner of the background rectangle

+to be at pixel coordinate (x,y), pass the (x,y + ascent)

+as the baseline origin coordinates to the text functions.

+The ascent is the font ascent, as given in the

+<function>XFontStruct</function>

+structure.

+If you want the lower-left corner of the background rectangle

+to be at pixel coordinate (x,y), pass the (x,y - descent + 1)

+as the baseline origin coordinates to the text functions.

+The descent is the font descent, as given in the

+<function>XFontStruct</function>

+structure.

+</para>

+<sect2 id="Drawing_Complex_Text">

+<title>Drawing Complex Text</title>

+<!-- .XS -->

+<!-- (SN Drawing Complex Text  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Text</primary><secondary>drawing</secondary></indexterm>

+<indexterm><primary>Drawing</primary><secondary>text items</secondary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+To draw 8-bit characters in a given drawable, use

+<function>XDrawText</function>.

+<indexterm significance="preferred"><primary>XDrawText</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDrawText</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>XTextItem<parameter> *items</parameter></paramdef>

+  <paramdef>int<parameter> nitems</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->

+and define the origin of the first character

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>items</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array of text items.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nitems</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of text items in the array.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To draw 2-byte characters in a given drawable, use

+<function>XDrawText16</function>.

+<indexterm significance="preferred"><primary>XDrawText16</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDrawText16</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>XTextItem16<parameter> *items</parameter></paramdef>

+  <paramdef>int<parameter> nitems</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->

+and define the origin of the first character

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>items</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array of text items.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nitems</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of text items in the array.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XDrawText16</function>

+function is similar to

+<function>XDrawText </function>

+except that it uses 2-byte or 16-bit characters.

+Both functions allow complex spacing and font shifts between counted strings.

+</para>

+<para>

+<!-- .LP -->

+Each text item is processed in turn.

+A font member other than 

+<function>None</function>

+in an item causes the font to be stored in the GC

+and used for subsequent text.  

+A text element delta specifies an additional change

+in the position along the x axis before the string is drawn. 

+The delta is always added to the character origin

+and is not dependent on any characteristics of the font.

+Each character image, as defined by the font in the GC, is treated as an

+additional mask for a fill operation on the drawable.

+The drawable is modified only where the font character has a bit set to 1.

+If a text item generates a

+<function>BadFont</function>

+error, the previous text items may have been drawn.

+</para>

+<para>

+<!-- .LP -->

+For fonts defined with linear indexing rather than 2-byte matrix indexing,

+each 

+<function>XChar2b</function>

+structure is interpreted as a 16-bit number with byte1 as the 

+most significant byte.

+</para>

+<para>

+<!-- .LP -->

+Both functions use these GC components:

+function, plane-mask, fill-style, font, subwindow-mode, 

+clip-x-origin, clip-y-origin, and clip-mask.

+They also use these GC mode-dependent components: 

+foreground, background, tile, stipple, tile-stipple-x-origin, 

+and tile-stipple-y-origin.

+</para>

+<para>

+<!-- .LP -->

+<function>XDrawText</function>

+and

+<function>XDrawText16</function>

+can generate

+<function>BadDrawable</function>,

+<function>BadFont</function>,

+<function>BadGC</function>,

+and

+<function>BadMatch </function>

+errors.

+</para>

+</sect2>

+<sect2 id="Drawing_Text_Characters">

+<title>Drawing Text Characters</title>

+<!-- .XS -->

+<!-- (SN Drawing Text Characters  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Strings</primary><secondary>drawing</secondary></indexterm>

+<indexterm><primary>Drawing</primary><secondary>strings</secondary></indexterm>

+To draw 8-bit characters in a given drawable, use

+<function>XDrawString</function>.

+<indexterm significance="preferred"><primary>XDrawString</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDrawString</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>char<parameter> *string</parameter></paramdef>

+  <paramdef>int<parameter> length</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->

+and define the origin of the first character

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the character string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>length</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of characters in the string argument.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To draw 2-byte characters in a given drawable, use

+<function>XDrawString16</function>.

+<indexterm significance="preferred"><primary>XDrawString16</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDrawString16</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>XChar2b<parameter> *string</parameter></paramdef>

+  <paramdef>int<parameter> length</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->

+and define the origin of the first character

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the character string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>length</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of characters in the string argument.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Each character image, as defined by the font in the GC, is treated as an

+additional mask for a fill operation on the drawable.

+The drawable is modified only where the font character has a bit set to 1.

+For fonts defined with 2-byte matrix indexing

+and used with

+<function>XDrawString16</function>,

+each byte is used as a byte2 with a byte1 of zero.

+</para>

+<para>

+<!-- .LP -->

+Both functions use these GC components: 

+function, plane-mask, fill-style, font, subwindow-mode, clip-x-origin, 

+clip-y-origin, and clip-mask.

+They also use these GC mode-dependent components: 

+foreground, background, tile, stipple, tile-stipple-x-origin, 

+and tile-stipple-y-origin.

+</para>

+<para>

+<!-- .LP -->

+<function>XDrawString</function>

+and

+<function>XDrawString16</function>

+can generate

+<function>BadDrawable</function>,

+<function>BadGC</function>,

+and

+<function>BadMatch </function>

+errors.

+</para>

+</sect2>

+<sect2 id="Drawing_Image_Text_Characters">

+<title>Drawing Image Text Characters</title>

+<!-- .XS -->

+<!-- (SN Drawing Image Text Characters  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Image text</primary><secondary>drawing</secondary></indexterm>

+<indexterm><primary>Drawing</primary><secondary>image text</secondary></indexterm>

+Some applications, in particular terminal emulators, need to

+print image text in which both the foreground and background bits of

+each character are painted.

+This prevents annoying flicker on many displays.

+<indexterm><primary>XDrawImageString</primary></indexterm>

+<indexterm><primary>XDrawImageString16</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To draw 8-bit image text characters in a given drawable, use

+<function>XDrawImageString</function>.

+<indexterm significance="preferred"><primary>XDrawImageString</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDrawImageString</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>char<parameter> *string</parameter></paramdef>

+  <paramdef>int<parameter> length</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->

+and define the origin of the first character

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the character string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>length</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of characters in the string argument.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To draw 2-byte image text characters in a given drawable, use

+<function>XDrawImageString16</function>.

+<indexterm significance="preferred"><primary>XDrawImageString16</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDrawImageString16</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>XChar2b<parameter> *string</parameter></paramdef>

+  <paramdef>int<parameter> length</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->

+and define the origin of the first character

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the character string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>length</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of characters in the string argument.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XDrawImageString16</function>

+function is similar to

+<function>XDrawImageString </function>

+except that it uses 2-byte or 16-bit characters.

+Both functions also use both the foreground and background pixels 

+of the GC in the destination.

+</para>

+<para>

+<!-- .LP -->

+The effect is first to fill a

+destination rectangle with the background pixel defined in the GC and then

+to paint the text with the foreground pixel.

+The upper-left corner of the filled rectangle is at:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+[x, y - font-ascent]

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+The width is:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+overall-width

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+The height is:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+font-ascent + font-descent

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+The overall-width, font-ascent, and font-descent

+are as would be returned by 

+<function>XQueryTextExtents </function>

+using gc and string.

+The function and fill-style defined in the GC are ignored for these functions. 

+The effective function is 

+<function>GXcopy</function>,

+and the effective fill-style is

+<function>FillSolid</function>.

+</para>

+<para>

+<!-- .LP -->

+For fonts defined with 2-byte matrix indexing

+and used with

+<function>XDrawImageString</function>,

+each byte is used as a byte2 with a byte1 of zero.

+</para>

+<para>

+<!-- .LP -->

+Both functions use these GC components: 

+plane-mask, foreground, background, font, subwindow-mode, clip-x-origin, 

+clip-y-origin, and clip-mask.

+</para>

+<para>

+<!-- .LP -->

+<function>XDrawImageString</function>

+and

+<function>XDrawImageString16</function>

+can generate

+<function>BadDrawable</function>,

+<function>BadGC</function>,

+and

+<function>BadMatch </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+</para>

+</sect2>

+</sect1>

+<sect1 id="Transferring_Images_between_Client_and_Server">

+<title>Transferring Images between Client and Server</title>

+<!-- .XS -->

+<!-- (SN Transferring Images between Client and Server  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to transfer images between a client 

+and the server.

+Because the server may require diverse data formats, 

+Xlib provides an image object that fully describes the data in memory 

+and that provides for basic operations on that data.  

+You should reference the data 

+through the image object rather than referencing the data directly.

+However, some implementations of the Xlib library may efficiently deal with 

+frequently used data formats by replacing

+functions in the procedure vector with special case functions.

+Supported operations include destroying the image, getting a pixel,

+storing a pixel, extracting a subimage of an image, and adding a constant

+to an image (see section 16.8).

+</para>

+<para>

+<!-- .LP -->

+All the image manipulation functions discussed in this section make use of 

+the 

+<function>XImage </function>

+structure,

+which describes an image as it exists in the client's memory.

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XImage</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 1i 3i -->

+<!-- .ta .5i 1i 3i -->

+typedef struct _XImage {

+     int width, height;         /* size of image */

+     int xoffset;               /* number of pixels offset in X direction */

+     int format;                /* XYBitmap, XYPixmap, ZPixmap */

+     char *data;                /* pointer to image data */

+     int byte_order;            /* data byte order, LSBFirst, MSBFirst */

+     int bitmap_unit;           /* quant. of scanline 8, 16, 32 */

+     int bitmap_bit_order;      /* LSBFirst, MSBFirst */

+     int bitmap_pad;            /* 8, 16, 32 either XY or ZPixmap */

+     int depth;                 /* depth of image */

+     int bytes_per_line;        /* accelerator to next scanline */

+     int bits_per_pixel;        /* bits per pixel (ZPixmap) */

+     unsigned long red_mask;    /* bits in z arrangement */

+     unsigned long green_mask;

+     unsigned long blue_mask;

+     XPointer obdata;           /* hook for the object routines to hang on */

+     struct funcs {             /* image manipulation routines */

+          struct _XImage *(*create_image)();

+          int             (*destroy_image)();

+          unsigned long   (*get_pixel)();

+          int             (*put_pixel)();

+          struct _XImage  *(*sub_image)();

+          int            (*add_pixel)();

+     } f;

+} XImage;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To initialize the image manipulation routines of an image structure, use

+<function>XInitImage</function>.

+<indexterm significance="preferred"><primary>XInitImage</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XInitImage</function></funcdef>

+  <paramdef>XImage<parameter> *image</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ximage</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the image.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XInitImage</function>

+function initializes the internal image manipulation routines of an

+image structure, based on the values of the various structure members.

+All fields other than the manipulation routines must already be initialized.

+If the bytes_per_line member is zero,

+<function>XInitImage</function>

+will assume the image data is contiguous in memory and set the

+bytes_per_line member to an appropriate value based on the other

+members; otherwise, the value of bytes_per_line is not changed.

+All of the manipulation routines are initialized to functions

+that other Xlib image manipulation functions need to operate on the

+type of image specified by the rest of the structure.

+</para>

+<para>

+<!-- .LP -->

+This function must be called for any image constructed by the client

+before passing it to any other Xlib function.

+Image structures created or returned by Xlib do not need to be

+initialized in this fashion.

+</para>

+<para>

+<!-- .LP -->

+This function returns a nonzero status if initialization of the

+structure is successful.  It returns zero if it detected some error

+or inconsistency in the structure, in which case the image is not changed.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To combine an image with a rectangle of a drawable on the display,

+use

+<function>XPutImage</function>.

+<indexterm significance="preferred"><primary>XPutImage</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XPutImage</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>XImage<parameter> *image</parameter></paramdef>

+  <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>

+  <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>image</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the image you want combined with the rectangle. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>src_x</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the offset in X from the left edge of the image defined

+by the 

+<function>XImage </function>

+structure.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>src_y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the offset in Y from the top edge of the image defined

+by the 

+<function>XImage </function>

+structure.

+<!-- .ds Dx , which are relative to the origin of the drawable \ -->

+and are the coordinates of the subimage

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dest_x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dest_y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Dx. 

+<!-- .ds Wh \ of the subimage, which define the dimensions of the rectangle -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height(Wh.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XPutImage</function>

+function

+combines an image with a rectangle of the specified drawable.

+The section of the image defined by the src_x, src_y, width, and height 

+arguments is drawn on the specified part of the drawable.

+If 

+<function>XYBitmap </function>

+format is used, the depth of the image must be one,

+or a

+<function>BadMatch </function>

+error results.

+The foreground pixel in the GC defines the source for the one bits in the image,

+and the background pixel defines the source for the zero bits.

+For 

+<function>XYPixmap </function>

+and 

+<function>ZPixmap</function>,

+the depth of the image must match the depth of the drawable,

+or a

+<function>BadMatch</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+If the characteristics of the image (for example, byte_order and bitmap_unit)

+differ from what the server requires,

+<function>XPutImage </function>

+automatically makes the appropriate

+conversions.

+</para>

+<para>

+<!-- .LP -->

+This function uses these GC components: 

+function, plane-mask, subwindow-mode, clip-x-origin, clip-y-origin, 

+and clip-mask.

+It also uses these GC mode-dependent components:

+foreground and background.

+</para>

+<para>

+<!-- .LP -->

+<function>XPutImage</function>

+can generate

+<function>BadDrawable</function>,

+<function>BadGC</function>,

+<function>BadMatch</function>,

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To return the contents of a rectangle in a given drawable on the display,

+use

+<function>XGetImage</function>.

+This function specifically supports rudimentary screen dumps.

+<indexterm significance="preferred"><primary>XGetImage</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XImage<function> *XGetImage</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> plane_mask</parameter></paramdef>

+  <paramdef>int<parameter> format</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+<!-- .ds Xy , which are relative to the origin of the drawable \ -->

+and define the upper-left corner of the rectangle

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+<!-- .ds Wh \ of the subimage, which define the dimensions of the rectangle -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height(Wh.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>plane_mask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the plane mask.

+<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>format</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the format for the image.

+You can pass

+<function>XYPixmap</function>

+or 

+<function>ZPixmap</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetImage</function>

+function returns a pointer to an

+<function>XImage</function>

+structure.

+This structure provides you with the contents of the specified rectangle of

+the drawable in the format you specify.

+If the format argument is 

+<function>XYPixmap</function>,

+the image contains only the bit planes you passed to the plane_mask argument.

+If the plane_mask argument only requests a subset of the planes of the

+display, the depth of the returned image will be the number of planes

+requested.

+If the format argument is 

+<function>ZPixmap</function>,

+<function>XGetImage</function>

+returns as zero the bits in all planes not 

+specified in the plane_mask argument.

+The function performs no range checking on the values in plane_mask and ignores

+extraneous bits.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetImage</function>

+returns the depth of the image to the depth member of the

+<function>XImage</function>

+structure.

+The depth of the image is as specified when the drawable was created,

+except when getting a subset of the planes in 

+<function>XYPixmap</function>

+format, when the depth is given by the number of bits set to 1 in plane_mask.

+</para>

+<para>

+<!-- .LP -->

+If the drawable is a pixmap, 

+the given rectangle must be wholly contained within the pixmap, 

+or a

+<function>BadMatch</function>

+error results.

+If the drawable is a window, 

+the window must be viewable, 

+and it must be the case that if there were no inferiors or overlapping windows,

+the specified rectangle of the window would be fully visible on the screen

+and wholly contained within the outside edges of the window,

+or a

+<function>BadMatch</function>

+error results.

+Note that the borders of the window can be included and read with

+this request.

+If the window has backing-store, the backing-store contents are

+returned for regions of the window that are obscured by noninferior

+windows. 

+If the window does not have backing-store,

+the returned contents of such obscured regions are undefined.

+The returned contents of visible regions of inferiors

+of a different depth than the specified window's depth are also undefined.

+The pointer cursor image is not included in the returned contents.

+If a problem occurs,

+<function>XGetImage</function>

+returns NULL.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetImage</function>

+can generate

+<function>BadDrawable</function>,

+<function>BadMatch</function>,

+and

+<function>BadValue </function>

+errors.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To copy the contents of a rectangle on the display

+to a location within a preexisting image structure, use

+<function>XGetSubImage</function>.

+<indexterm significance="preferred"><primary>XGetSubImage</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XImage<function> *XGetSubImage</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> plane_mask</parameter></paramdef>

+  <paramdef>int<parameter> format</parameter></paramdef>

+  <paramdef>XImage<parameter> *dest_image</parameter></paramdef>

+  <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+<!-- .ds Xy , which are relative to the origin of the drawable \ -->

+and define the upper-left corner of the rectangle

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+<!-- .ds Wh \ of the subimage, which define the dimensions of the rectangle -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height(Wh.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>plane_mask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the plane mask.

+<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>format</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the format for the image.

+You can pass

+<function>XYPixmap</function>

+or 

+<function>ZPixmap</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dest_image</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the destination image.

+<!-- .ds Dx , which are relative to the origin of the destination rectangle, \ -->

+specify its upper-left corner, and determine where the subimage \

+is placed in the destination image

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dest_x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dest_y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Dx. 

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XGetSubImage </function>

+function updates dest_image with the specified subimage in the same manner as 

+<function>XGetImage</function>.

+If the format argument is 

+<function>XYPixmap</function>,

+the image contains only the bit planes you passed to the plane_mask argument.

+If the format argument is 

+<function>ZPixmap</function>,

+<function>XGetSubImage</function>

+returns as zero the bits in all planes not 

+specified in the plane_mask argument.

+The function performs no range checking on the values in plane_mask and ignores

+extraneous bits.

+As a convenience,

+<function>XGetSubImage</function>

+returns a pointer to the same

+<function>XImage</function>

+structure specified by dest_image.

+</para>

+<para>

+<!-- .LP -->

+The depth of the destination

+<function>XImage</function>

+structure must be the same as that of the drawable.

+If the specified subimage does not fit at the specified location

+on the destination image, the right and bottom edges are clipped.

+If the drawable is a pixmap,

+the given rectangle must be wholly contained within the pixmap,

+or a

+<function>BadMatch</function>

+error results.

+If the drawable is a window, 

+the window must be viewable, 

+and it must be the case that if there were no inferiors or overlapping windows,

+the specified rectangle of the window would be fully visible on the screen

+and wholly contained within the outside edges of the window,

+or a

+<function>BadMatch</function>

+error results.

+If the window has backing-store, 

+then the backing-store contents are returned for regions of the window 

+that are obscured by noninferior windows. 

+If the window does not have backing-store, 

+the returned contents of such obscured regions are undefined.

+The returned contents of visible regions of inferiors

+of a different depth than the specified window's depth are also undefined.

+If a problem occurs,

+<function>XGetSubImage</function>

+returns NULL.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetSubImage</function>

+can generate

+<function>BadDrawable</function>,

+<function>BadGC</function>,

+<function>BadMatch</function>,

+and

+<function>BadValue </function>

+errors.

+<!-- .bp -->

+

+

+</para>

+</sect1>

+</chapter>

diff --git a/libX11/specs/libX11/CH09 b/libX11/specs/libX11/CH09
deleted file mode 100644
index 2b79d3880..000000000
--- a/libX11/specs/libX11/CH09
+++ /dev/null
@@ -1,1290 +0,0 @@
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996, 2002 The Open Group
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-.\" OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" Except as contained in this notice, the name of The Open Group shall
-.\" not be used in advertising or otherwise to promote the sale, use or
-.\" other dealings in this Software without prior written authorization
-.\" from The Open Group.
-.\"
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
-.\" Digital Equipment Corporation
-.\"
-.\" Portions Copyright \(co 1990, 1991 by
-.\" Tektronix, Inc.
-.\"
-.\" Permission to use, copy, modify and distribute this documentation for
-.\" any purpose and without fee is hereby granted, provided that the above
-.\" copyright notice appears in all copies and that both that copyright notice
-.\" and this permission notice appear in all copies, and that the names of
-.\" Digital and Tektronix not be used in in advertising or publicity pertaining
-.\" to this documentation without specific, written prior permission.
-.\" Digital and Tektronix makes no representations about the suitability
-.\" of this documentation for any purpose.
-.\" It is provided ``as is'' without express or implied warranty.
-.\" 
-\&
-.sp 1
-.ce 3
-\s+1\fBChapter 9\fP\s-1
-
-\s+1\fBWindow and Session Manager Functions\fP\s-1
-.sp 2
-.nr H1 9
-.nr H2 0
-.nr H3 0
-.nr H4 0
-.nr H5 0
-.na
-.LP
-.XS
-Chapter 9: Window and Session Manager Functions 
-.XE
-Although it is difficult to categorize functions as exclusively
-for an application, a window manager, or a session manager,
-the functions in this chapter are most often used by window managers
-and session managers.
-It is not expected that these functions will be used by most 
-application programs.
-Xlib provides management functions to:
-.IP \(bu 5
-Change the parent of a window
-.IP \(bu 5
-Control the lifetime of a window
-.IP \(bu 5
-Manage installed colormaps
-.IP \(bu 5
-Set and retrieve the font search path
-.IP \(bu 5
-Grab the server
-.IP \(bu 5
-Kill a client
-.IP \(bu 5
-Control the screen saver
-.IP \(bu 5
-Control host access
-.NH 2
-Changing the Parent of a Window
-.XS
-\*(SN Changing the Parent of a Window 
-.XE
-.LP
-To change a window's parent to another window on the same screen, use
-.PN XReparentWindow .
-There is no way to move a window between screens.
-.IN "XReparentWindow" "" "@DEF@"
-.sM
-.FD 0
-XReparentWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIparent\fP\^, \fIx\fP\^, \fIy\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      Window \fIparent\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIparent\fP 1i
-Specifies the parent window.
-.ds Xy \ of the position in the new parent window
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.LP
-.eM
-If the specified window is mapped,
-.PN XReparentWindow
-automatically performs an
-.PN UnmapWindow
-request on it, removes it from its current position in the hierarchy,
-and inserts it as the child of the specified parent.
-The window is placed in the stacking order on top with respect to
-sibling windows.
-.LP
-After reparenting the specified window,
-.PN XReparentWindow
-causes the X server to generate a
-.PN ReparentNotify
-event.
-The override_redirect member returned in this event is
-set to the window's corresponding attribute.
-Window manager clients usually should ignore this window if this member
-is set to
-.PN True .
-Finally, if the specified window was originally mapped,
-the X server automatically performs a
-.PN MapWindow
-request on it.
-.LP
-The X server performs normal exposure processing on formerly obscured
-windows.
-The X server might not generate 
-.PN Expose 
-events for regions from the initial
-.PN UnmapWindow
-request that are immediately obscured by the final
-.PN MapWindow
-request.
-A
-.PN BadMatch
-error results if:
-.IP \(bu 5
-The new parent window is not on the same screen as
-the old parent window.
-.IP \(bu 5
-The new parent window is the specified window or an inferior of the
-specified window.
-.IP \(bu 5
-The new parent is
-.PN InputOnly ,
-and the window is not.
-.IP \(bu 5
-The specified window has a
-.PN ParentRelative
-background, and the new parent window is not the same depth as the
-specified window.
-.LP
-.PN XReparentWindow
-can generate
-.PN BadMatch
-and
-.PN BadWindow 
-errors.
-.NH 2
-Controlling the Lifetime of a Window
-.XS
-\*(SN Controlling the Lifetime of a Window 
-.XE
-.LP
-The save-set of a client is a list of other clients' windows that,
-if they are inferiors of one of the client's windows at connection close,
-should not be destroyed and should be remapped if they are unmapped.
-For further information about close-connection processing,
-see section 2.6.
-To allow an application's window to survive when a window manager that
-has reparented a window fails,
-Xlib provides the save-set functions that you can 
-use to control the longevity of subwindows
-that are normally destroyed when the parent is destroyed.
-For example, a window manager that wants to add decoration
-to a window by adding a frame might reparent an application's
-window. 
-When the frame is destroyed,
-the application's window should not be destroyed 
-but be returned to its previous place in the window hierarchy.
-.LP
-The X server automatically removes windows from the save-set
-when they are destroyed.
-.LP
-.sp
-To add or remove a window from the client's save-set, use
-.PN XChangeSaveSet .
-.IN "XChangeSaveSet" "" "@DEF@"
-.sM
-.FD 0
-XChangeSaveSet\^(\^\fIdisplay\fP, \fIw\fP\^, \fIchange_mode\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      int \fIchange_mode\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Wi that you want to add to or delete from the client's save-set
-.IP \fIw\fP 1i
-Specifies the window \*(Wi.
-.IP \fIchange_mode\fP 1i
-Specifies the mode.
-You can pass
-.PN SetModeInsert 
-or
-.PN SetModeDelete .
-.LP
-.eM
-Depending on the specified mode,
-.PN XChangeSaveSet
-either inserts or deletes the specified window from the client's save-set. 
-The specified window must have been created by some other client,
-or a
-.PN BadMatch
-error results.
-.LP
-.PN XChangeSaveSet
-can generate
-.PN BadMatch ,
-.PN BadValue ,
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To add a window to the client's save-set, use
-.PN XAddToSaveSet .
-.IN "XAddToSaveSet" "" "@DEF@"
-.sM
-.FD 0
-XAddToSaveSet\^(\^\fIdisplay\fP, \fIw\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Wi that you want to add to the client's save-set
-.IP \fIw\fP 1i
-Specifies the window \*(Wi.
-.LP
-.eM
-The
-.PN XAddToSaveSet
-function adds the specified window to the client's save-set.
-The specified window must have been created by some other client,
-or a
-.PN BadMatch
-error results.
-.LP
-.PN XAddToSaveSet
-can generate
-.PN BadMatch
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To remove a window from the client's save-set, use
-.PN XRemoveFromSaveSet .
-.IN "XRemoveFromSaveSet" "" "@DEF@"
-.sM
-.FD 0
-XRemoveFromSaveSet\^(\^\fIdisplay\fP, \fIw\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Wi that you want to delete from the client's save-set
-.IP \fIw\fP 1i
-Specifies the window \*(Wi.
-.LP
-.eM
-The
-.PN XRemoveFromSaveSet
-function removes the specified window from the client's save-set.
-The specified window must have been created by some other client,
-or a
-.PN BadMatch
-error results.
-.LP
-.PN XRemoveFromSaveSet
-can generate
-.PN BadMatch 
-and
-.PN BadWindow 
-errors.
-.NH 2
-Managing Installed Colormaps
-.XS
-\*(SN Managing Installed Colormaps
-.XE
-.LP
-The X server maintains a list of installed colormaps.
-Windows using these colormaps are guaranteed to display with
-correct colors; windows using other colormaps may or may not display
-with correct colors.
-Xlib provides functions that you can use to install a colormap, 
-uninstall a colormap, and obtain a list of installed colormaps.
-.LP
-At any time,
-there is a subset of the installed maps that is viewed as an ordered list
-and is called the required list.
-The length of the required list is at most M,
-where M is the minimum number of installed colormaps specified for the screen
-in the connection setup.
-The required list is maintained as follows.
-When a colormap is specified to
-.PN XInstallColormap ,
-it is added to the head of the list;
-the list is truncated at the tail, if necessary, to keep its length to 
-at most M.
-When a colormap is specified to
-.PN XUninstallColormap
-and it is in the required list,
-it is removed from the list.
-A colormap is not added to the required list when it is implicitly installed
-by the X server,
-and the X server cannot implicitly uninstall a colormap that is in the
-required list.
-.LP
-.sp
-To install a colormap, use
-.PN XInstallColormap .
-.IN "XInstallColormap" "" "@DEF@"
-.sM
-.FD 0
-XInstallColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.LP
-.eM
-The
-.PN XInstallColormap
-function installs the specified colormap for its associated screen.
-All windows associated with this colormap immediately display with
-true colors.
-You associated the windows with this colormap when you created them by calling
-.PN XCreateWindow ,
-.PN XCreateSimpleWindow ,
-.PN XChangeWindowAttributes ,
-or
-.PN XSetWindowColormap .
-.LP
-If the specified colormap is not already an installed colormap, 
-the X server generates a
-.PN ColormapNotify
-event on each window that has that colormap.
-In addition, for every other colormap that is installed as 
-a result of a call to
-.PN XInstallColormap ,
-the X server generates a
-.PN ColormapNotify
-event on each window that has that colormap.
-.LP
-.PN XInstallColormap
-can generate a
-.PN BadColor 
-error.
-.LP
-.sp
-To uninstall a colormap, use
-.PN XUninstallColormap .
-.IN "XUninstallColormap" "" "@DEF@"
-.sM
-.FD 0
-XUninstallColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Colormap \fIcolormap\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcolormap\fP 1i
-Specifies the colormap.
-.LP
-.eM
-The
-.PN XUninstallColormap
-function removes the specified colormap from the required
-list for its screen.
-As a result,
-the specified colormap might be uninstalled, 
-and the X server might implicitly install or uninstall additional colormaps.
-Which colormaps get installed or uninstalled is server dependent
-except that the required list must remain installed.
-.LP
-If the specified colormap becomes uninstalled, 
-the X server generates a
-.PN ColormapNotify
-event on each window that has that colormap.
-In addition, for every other colormap that is installed or uninstalled as a 
-result of a call to 
-.PN XUninstallColormap ,
-the X server generates a
-.PN ColormapNotify
-event on each window that has that colormap.
-.LP
-.PN XUninstallColormap
-can generate a
-.PN BadColor 
-error.
-.LP
-.sp
-To obtain a list of the currently installed colormaps for a given screen, use
-.PN XListInstalledColormaps .
-.IN "XListInstalledColormaps" "" "@DEF@"
-.sM
-.FD 0
-Colormap *XListInstalledColormaps\^(\^\fIdisplay\fP, \fIw\fP, \fInum_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      int *\fInum_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Wi that determines the screen
-.IP \fIw\fP 1i
-Specifies the window \*(Wi.
-.IP \fInum_return\fP 1i
-Returns the number of currently installed colormaps.
-.LP
-.eM
-The
-.PN XListInstalledColormaps
-function returns a list of the currently installed colormaps for the screen 
-of the specified window.
-The order of the colormaps in the list is not significant
-and is no explicit indication of the required list.
-When the allocated list is no longer needed,
-free it by using
-.PN XFree .
-.LP
-.PN XListInstalledColormaps
-can generate a
-.PN BadWindow 
-error.
-.NH 2
-Setting and Retrieving the Font Search Path
-.XS
-\*(SN Setting and Retrieving the Font Search Path 
-.XE
-.LP
-The set of fonts available from a server depends on a font
-search path.  Xlib provides functions to set and retrieve the
-search path for a server.
-.LP
-.sp
-To set the font search path, use
-.PN XSetFontPath .
-.IN "XSetFontPath" "" "@DEF@"
-.sM
-.FD 0
-XSetFontPath\^(\^\fIdisplay\fP, \fIdirectories\fP\^, \fIndirs\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      char **\fIdirectories\fP\^;
-.br
-      int \fIndirs\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIdirectories\fP 1i
-Specifies the directory path used to look for a font.
-Setting the path to the empty list restores the default path defined
-for the X server.
-.IP \fIndirs\fP 1i
-Specifies the number of directories in the path.
-.LP
-.eM
-The
-.PN XSetFontPath
-function defines the directory search path for font lookup.
-There is only one search path per X server, not one per client.
-The encoding and interpretation of the strings are implementation-dependent,
-but typically they specify directories or font servers to be searched 
-in the order listed.
-An X server is permitted to cache font information internally;
-for example, it might cache an entire font from a file and not
-check on subsequent opens of that font to see if the underlying
-font file has changed.
-However,
-when the font path is changed,
-the X server is guaranteed to flush all cached information about fonts 
-for which there currently are no explicit resource IDs allocated.
-The meaning of an error from this request is implementation-dependent.
-.LP
-.PN XSetFontPath
-can generate a
-.PN BadValue 
-error.
-.LP
-.sp
-To get the current font search path, use
-.PN XGetFontPath .
-.IN "XGetFontPath" "" "@DEF@"
-.sM
-.FD 0
-char **XGetFontPath\^(\^\fIdisplay\fP, \fInpaths_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int *\fInpaths_return\fP\^;
-
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fInpaths_return\fP 1i
-Returns the number of strings in the font path array.
-.LP
-.eM
-The
-.PN XGetFontPath
-function allocates and returns an array of strings containing the search path.
-The contents of these strings are implementation-dependent
-and are not intended to be interpreted by client applications.
-When it is no longer needed,
-the data in the font path should be freed by using
-.PN XFreeFontPath .
-.LP
-.sp
-To free data returned by
-.PN XGetFontPath ,
-use
-.PN XFreeFontPath .
-.IN "XFreeFontPath" "" "@DEF@"
-.sM
-.FD 0
-XFreeFontPath\^(\^\fIlist\fP\^)
-.br
-      char **\fIlist\fP\^;
-
-.FN
-.IP \fIlist\fP 1i
-Specifies the array of strings you want to free.
-.LP
-.eM
-The
-.PN XFreeFontPath
-function
-frees the data allocated by
-.PN XGetFontPath .
-.NH 2
-Grabbing the Server 
-.XS
-\*(SN Grabbing the Server 
-.XE
-.LP
-Xlib provides functions that you can use to grab and ungrab the server.
-These functions can be used to control processing of output on other
-connections by the window system server.
-While the server is grabbed,
-no processing of requests or close downs on any other connection will occur.
-A client closing its connection automatically ungrabs the server.
-.IN "Menus"
-.IN "Window" "managers"
-Although grabbing the server is highly discouraged, it is sometimes necessary.
-.LP
-.sp
-To grab the server, use
-.PN XGrabServer .
-.IN "Server" "grabbing"
-.IN "Grabbing" "server"
-.IN "XGrabServer" "" "@DEF@"
-.sM
-.FD 0
-XGrabServer\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-The
-.PN XGrabServer
-function disables processing of requests and close downs on all other 
-connections than the one this request arrived on.
-You should not grab the X server any more than is absolutely necessary.
-.LP
-.sp
-To ungrab the server, use
-.PN XUngrabServer .
-.IN "XUngrabServer" "" "@DEF@"
-.sM
-.FD 0
-XUngrabServer\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-The
-.PN XUngrabServer
-function restarts processing of requests and close downs on other connections.
-You should avoid grabbing the X server as much as possible.
-.NH 2
-Killing Clients
-.XS
-\*(SN Killing Clients 
-.XE
-.LP
-Xlib provides a function to cause the connection to
-a client to be closed and its resources to be destroyed.
-To destroy a client, use
-.PN XKillClient .
-.IN "XKillClient" "" "@DEF@"
-.sM
-.FD 0
-XKillClient\^(\^\fIdisplay\fP, \fIresource\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XID \fIresource\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIresource\fP 1i
-Specifies any resource associated with the client that you want to destroy or
-.PN AllTemporary .
-.LP
-.eM
-The
-.PN XKillClient
-function
-forces a close down of the client
-that created the resource
-if a valid resource is specified.
-If the client has already terminated in
-either 
-.PN RetainPermanent 
-or 
-.PN RetainTemporary 
-mode, all of the client's
-resources are destroyed.
-If 
-.PN AllTemporary 
-is specified, the resources of all clients that have terminated in
-.PN RetainTemporary 
-are destroyed (see section 2.5).
-This permits implementation of window manager facilities that aid debugging.
-A client can set its close-down mode to
-.PN RetainTemporary .
-If the client then crashes,
-its windows would not be destroyed. 
-The programmer can then inspect the application's window tree 
-and use the window manager to destroy the zombie windows.
-.LP
-.PN XKillClient
-can generate a
-.PN BadValue 
-error.
-.NH 2
-Controlling the Screen Saver 
-.XS
-\*(SN Controlling the Screen Saver 
-.XE
-.LP
-Xlib provides functions that you can use to set or reset the mode 
-of the screen saver, to force or activate the screen saver,
-or to obtain the current screen saver values.
-.LP
-.sp
-To set the screen saver mode, use
-.PN XSetScreenSaver .
-.IN "XSetScreenSaver" "" "@DEF@"
-.sM
-.FD 0
-XSetScreenSaver\^(\^\fIdisplay\fP, \fItimeout\fP\^, \fIinterval\fP\^, \fIprefer_blanking\fP\^, \fIallow_exposures\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fItimeout\fP\^, \fIinterval\fP\^;
-.br
-      int \fIprefer_blanking\fP\^; 
-.br
-      int \fIallow_exposures\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fItimeout\fP 1i
-Specifies the timeout, in seconds, until the screen saver turns on.
-.IP \fIinterval\fP 1i
-Specifies the interval, in seconds, between screen saver alterations.
-.IP \fIprefer_blanking\fP 1i
-Specifies how to enable screen blanking.
-You can pass
-.PN DontPreferBlanking ,
-.PN PreferBlanking ,
-or
-.PN DefaultBlanking .
-.IP \fIallow_exposures\fP 1i
-Specifies the screen save control values.
-You can pass
-.PN DontAllowExposures ,
-.PN AllowExposures ,
-or
-.PN DefaultExposures .
-.LP
-.eM
-Timeout and interval are specified in seconds. 
-A timeout of 0 disables the screen saver 
-(but an activated screen saver is not deactivated),
-and a timeout of \-1 restores the default.
-Other negative values generate a
-.PN BadValue
-error.
-If the timeout value is nonzero, 
-.PN XSetScreenSaver
-enables the screen saver.
-An interval of 0 disables the random-pattern motion.
-If no input from devices (keyboard, mouse, and so on) is generated 
-for the specified number of timeout seconds once the screen saver is enabled,
-the screen saver is activated.
-.LP
-For each screen, 
-if blanking is preferred and the hardware supports video blanking, 
-the screen simply goes blank.  
-Otherwise, if either exposures are allowed or the screen can be regenerated 
-without sending 
-.PN Expose 
-events to clients, 
-the screen is tiled with the root window background tile randomly 
-re-origined each interval seconds.
-Otherwise, the screens' state do not change, 
-and the screen saver is not activated.
-The screen saver is deactivated,
-and all screen states are restored at the next
-keyboard or pointer input or at the next call to
-.PN XForceScreenSaver
-with mode
-.PN ScreenSaverReset .  
-.LP
-If the server-dependent screen saver method supports periodic change,
-the interval argument serves as a hint about how long the change period
-should be, and zero hints that no periodic change should be made.
-Examples of ways to change the screen include scrambling the colormap
-periodically, moving an icon image around the screen periodically, or tiling
-the screen with the root window background tile, randomly re-origined
-periodically.
-.LP
-.PN XSetScreenSaver
-can generate a
-.PN BadValue 
-error.
-.LP
-.sp
-To force the screen saver on or off, use
-.PN XForceScreenSaver .
-.IN "XForceScreenSaver" "" "@DEF@"
-.sM
-.FD 0
-XForceScreenSaver\^(\^\fIdisplay\fP\^, \fImode\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fImode\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fImode\fP 1i
-Specifies the mode that is to be applied.
-You can pass
-.PN ScreenSaverActive
-or
-.PN ScreenSaverReset .
-.LP
-.eM
-If the specified mode is 
-.PN ScreenSaverActive 
-and the screen saver currently is deactivated,
-.PN XForceScreenSaver
-activates the screen saver even if the screen saver had been disabled
-with a timeout of zero.
-If the specified mode is 
-.PN ScreenSaverReset 
-and the screen saver currently is enabled,
-.PN XForceScreenSaver
-deactivates the screen saver if it was activated,
-and the activation timer is reset to its initial state 
-(as if device input had been received).
-.LP
-.PN XForceScreenSaver
-can generate a
-.PN BadValue 
-error.
-.LP
-.sp
-To activate the screen saver, use
-.PN XActivateScreenSaver .
-.IN "XActivateScreenSaver" "" "@DEF@"
-.sM
-.FD 0
-XActivateScreenSaver\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-.sp
-To reset the screen saver, use
-.PN XResetScreenSaver .
-.IN "XResetScreenSaver" "" "@DEF@"
-.sM
-.FD 0
-XResetScreenSaver\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-.sp
-To get the current screen saver values, use
-.PN XGetScreenSaver .
-.IN "XGetScreenSaver" "" "@DEF@"
-.sM
-.FD 0
-XGetScreenSaver\^(\^\fIdisplay\fP, \fItimeout_return\fP\^, \fIinterval_return\fP\^, \fIprefer_blanking_return\fP\^, 
-.br
-                  \fIallow_exposures_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int *\fItimeout_return\fP\^, *\fIinterval_return\fP\^;
-.br
-      int *\fIprefer_blanking_return\fP\^;
-.br
-      int *\fIallow_exposures_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fItimeout_return\fP 1i
-Returns the timeout, in seconds, until the screen saver turns on.
-.IP \fIinterval_return\fP 1i
-Returns the interval between screen saver invocations.
-.IP \fIprefer_blanking_return\fP 1i
-Returns the current screen blanking preference
-.Pn ( DontPreferBlanking ,
-.PN PreferBlanking ,
-or
-.PN DefaultBlanking ).
-.IP \fIallow_exposures_return\fP 1i
-Returns the current screen save control value
-.Pn ( DontAllowExposures ,
-.PN AllowExposures ,
-or
-.PN DefaultExposures ).
-.LP
-.eM
-.NH 2
-Controlling Host Access
-.XS
-\*(SN Controlling Host Access 
-.XE
-.LP
-This section discusses how to:
-.IP \(bu 5
-Add, get, or remove hosts from the access control list
-.IP \(bu 5
-Change, enable, or disable access
-.LP
-.IN "Access control list"
-.IN "Authentication"
-X does not provide any protection on a per-window basis.
-If you find out the resource ID of a resource, you can manipulate it.
-To provide some minimal level of protection, however,
-connections are permitted only from machines you trust.
-This is adequate on single-user workstations but obviously
-breaks down on timesharing machines.
-Although provisions exist in the X protocol for proper connection
-authentication, the lack of a standard authentication server
-leaves host-level access control as the only common mechanism.
-.LP
-.IN "Default Protection"
-The initial set of hosts allowed to open connections typically consists of:
-.IP \(bu 5
-The host the window system is running on.
-.IP \(bu 5
-On POSIX-conformant systems, each host listed in the
-.PN /etc/X?.hosts 
-file.
-The ? indicates the number of the
-display.
-.IN "Files" "/etc/X?.hosts"
-This file should consist of host names separated by newlines.
-DECnet nodes must terminate in :: to distinguish them from Internet hosts.
-.LP
-If a host is not in the access control list when the access control 
-mechanism is enabled and if the host attempts to establish a connection,
-the server refuses the connection.
-To change the access list,
-the client must reside on the same host as the server and/or must
-have been granted permission in the initial authorization at connection
-setup.
-.LP
-Servers also can implement other access control policies in addition to
-or in place of this host access facility.
-For further information about other access control implementations,
-see ``X Window System Protocol.''
-.NH 3
-Adding, Getting, or Removing Hosts
-.XS
-\*(SN Adding, Getting, or Removing Hosts 
-.XE
-.LP
-Xlib provides functions that you can use to add, get, or remove hosts
-from the access control list.
-All the host access control functions use the 
-.PN XHostAddress 
-structure, which contains:
-.LP
-.IN "XHostAddress" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int family;	/* for example FamilyInternet */
-	int length;	/* length of address, in bytes */
-	char *address;	/* pointer to where to find the address */
-} XHostAddress;
-.De
-.LP
-.eM
-The family member specifies which protocol address family to use 
-(for example, TCP/IP or DECnet) and can be
-.PN FamilyInternet ,
-.PN FamilyInternet6 ,
-.PN FamilyServerInterpreted ,
-.PN FamilyDECnet ,
-or
-.PN FamilyChaos .
-The length member specifies the length of the address in bytes.
-The address member specifies a pointer to the address.
-.LP
-For TCP/IP, the address should be in network byte order.
-For IP version 4 addresses, the family should be FamilyInternet
-and the length should be 4 bytes.  For IP version 6 addresses, the
-family should be FamilyInternet6 and the length should be 16 bytes.
-.LP
-For the DECnet family, 
-the server performs no automatic swapping on the address bytes.
-A Phase IV address is 2 bytes long.
-The first byte contains the least significant 8 bits of the node number.
-The second byte contains the most significant 2 bits of the
-node number in the least significant 2 bits of the byte
-and the area in the most significant 6 bits of the byte.
-.LP
-For the ServerInterpreted family, the length is ignored and the address 
-member is a pointer to a 
-.PN XServerInterpretedAddress
-structure, which contains:
-.LP
-.IN "XServerInterpretedAddress" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int typelength;	/* length of type string, in bytes */
-	int valuelength;/* length of value string, in bytes */
-	char *type;	/* pointer to where to find the type string */
-	char *value;	/* pointer to where to find the address */
-} XServerInterpretedAddress;
-.De
-.LP
-.eM
-The type and value members point to strings representing the type and value of
-the server interpreted entry.  These strings may not be NULL-terminated so care
-should be used when accessing them.  The typelength and valuelength members
-specify the length in byte of the type and value strings.
-.LP
-.sp
-To add a single host, use
-.PN XAddHost .
-.IN "XAddHost" "" "@DEF@"
-.sM
-.FD 0
-XAddHost\^(\^\fIdisplay\fP, \fIhost\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XHostAddress *\fIhost\fP\^;	
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Ho added
-.IP \fIhost\fP 1i
-Specifies the host that is to be \*(Ho.
-.LP
-.eM
-The
-.PN XAddHost
-function adds the specified host to the access control list for that display.
-The server must be on the same host as the client issuing the command, or a
-.PN BadAccess
-error results.
-.LP
-.PN XAddHost
-can generate
-.PN BadAccess
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-To add multiple hosts at one time, use
-.PN XAddHosts .
-.IN "XAddHosts" "" "@DEF@"
-.sM
-.FD 0
-XAddHosts\^(\^\fIdisplay\fP, \fIhosts\fP, \fInum_hosts\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XHostAddress *\fIhosts\fP\^;
-.br
-      int \fInum_hosts\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Ho added
-.IP \fIhosts\fP 1i
-Specifies each host that is to be \*(Ho.
-.IP \fInum_hosts\fP 1i
-Specifies the number of hosts.
-.LP
-.eM
-The
-.PN XAddHosts
-function adds each specified host to the access control list for that display.
-The server must be on the same host as the client issuing the command, or a
-.PN BadAccess
-error results.
-.LP
-.PN XAddHosts
-can generate
-.PN BadAccess
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-To obtain a host list, use
-.PN XListHosts .
-.IN "XListHosts" "" "@DEF@"
-.sM
-.FD 0
-XHostAddress *XListHosts\^(\^\fIdisplay\fP, \fInhosts_return\fP, \fIstate_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int *\fInhosts_return\fP\^;
-.br
-      Bool *\fIstate_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fInhosts_return\fP 1i
-Returns the number of hosts currently in the access control list.
-.IP \fIstate_return\fP 1i
-Returns the state of the access control.
-.LP
-.eM
-The
-.PN XListHosts
-function returns the current access control list as well as whether the use 
-of the list at connection setup was enabled or disabled.
-.PN XListHosts
-allows a program to find out what machines can make connections.
-It also returns a pointer to a list of host structures that
-were allocated by the function. 
-When no longer needed,
-this memory should be freed by calling
-.PN XFree .
-.LP
-.sp
-To remove a single host, use
-.PN XRemoveHost .
-.IN "XRemoveHost" "" "@DEF@"
-.sM
-.FD 0
-XRemoveHost\^(\^\fIdisplay\fP, \fIhost\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XHostAddress *\fIhost\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Ho removed
-.IP \fIhost\fP 1i
-Specifies the host that is to be \*(Ho.
-.LP
-.eM
-The
-.PN XRemoveHost
-function removes the specified host from the access control list 
-for that display.
-The server must be on the same host as the client process, or a
-.PN BadAccess
-error results.
-If you remove your machine from the access list,
-you can no longer connect to that server,
-and this operation cannot be reversed unless you reset the server.
-.LP
-.PN XRemoveHost
-can generate
-.PN BadAccess
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-To remove multiple hosts at one time, use
-.PN XRemoveHosts .
-.IN "XRemoveHosts" "" "@DEF@"
-.sM
-.FD 0
-XRemoveHosts\^(\^\fIdisplay\fP, \fIhosts\fP, \fInum_hosts\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XHostAddress *\fIhosts\fP\^;
-.br
-      int \fInum_hosts\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Ho removed
-.IP \fIhosts\fP 1i
-Specifies each host that is to be \*(Ho.
-.IP \fInum_hosts\fP 1i
-Specifies the number of hosts.
-.LP
-.eM
-The
-.PN XRemoveHosts
-function removes each specified host from the access control list for that 
-display.  
-The X server must be on the same host as the client process, or a
-.PN BadAccess
-error results.
-If you remove your machine from the access list, 
-you can no longer connect to that server,
-and this operation cannot be reversed unless you reset the server.
-.LP
-.PN XRemoveHosts
-can generate
-.PN BadAccess
-and
-.PN BadValue 
-errors.
-.NH 3
-Changing, Enabling, or Disabling Access Control
-.XS
-\*(SN Changing, Enabling, or Disabling Access Control 
-.XE
-.LP
-Xlib provides functions that you can use to enable, disable, 
-or change access control.
-.LP
-For these functions to execute successfully,
-the client application must reside on the same host as the X server
-and/or have been given permission in the initial authorization
-at connection setup.
-.LP
-.sp
-To change access control, use
-.PN XSetAccessControl .
-.IN "XSetAccessControl" "" "@DEF@"
-.sM
-.FD 0
-XSetAccessControl\^(\^\fIdisplay\fP, \fImode\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fImode\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fImode\fP 1i
-Specifies the mode.
-You can pass
-.PN EnableAccess
-or
-.PN DisableAccess .
-.LP
-.eM
-The
-.PN XSetAccessControl
-function either enables or disables the use of the access control list 
-at each connection setup.
-.LP
-.PN XSetAccessControl
-can generate
-.PN BadAccess
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-To enable access control, use
-.PN XEnableAccessControl .
-.IN "XEnableAccessControl" "" "@DEF@"
-.sM
-.FD 0
-XEnableAccessControl\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-The
-.PN XEnableAccessControl
-function enables the use of the access control list at each connection setup.
-.LP
-.PN XEnableAccessControl
-can generate a
-.PN BadAccess 
-error.
-.LP
-.sp
-To disable access control, use
-.PN XDisableAccessControl .
-.IN "XDisableAccessControl" "" "@DEF@"
-.sM
-.FD 0
-XDisableAccessControl\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-The
-.PN XDisableAccessControl
-function disables the use of the access control list at each connection setup.
-.LP
-.PN XDisableAccessControl
-can generate a
-.PN BadAccess 
-error.
-.bp
diff --git a/libX11/specs/libX11/CH09.xml b/libX11/specs/libX11/CH09.xml
new file mode 100644
index 000000000..20b2e99bc
--- /dev/null
+++ b/libX11/specs/libX11/CH09.xml
@@ -0,0 +1,2012 @@
+<chapter id="window_and_session_manager_functions">

+<title>Window and Session Manager Functions</title>

+

+<para>

+Although it is difficult to categorize functions as exclusively for an application, a window man-

+ager, or a session manager, the functions in this chapter are most often used by window managers

+and session managers. It is not expected that these functions will be used by most application

+programs. Xlib provides management functions to:

+</para>

+

+<itemizedlist>

+  <listitem><para>Change the parent of a window</para></listitem>

+  <listitem><para>Control the lifetime of a window</para></listitem>

+  <listitem><para>Manage installed colormaps</para></listitem>

+  <listitem><para>Set and retrieve the font search path</para></listitem>

+  <listitem><para>Grab the server</para></listitem>

+  <listitem><para>Kill a client</para></listitem>

+  <listitem><para>Control the screen saver</para></listitem>

+  <listitem><para>Control host access</para></listitem>

+</itemizedlist>

+

+<sect1 id="Changing_the_Parent_of_a_Window">

+<title>Changing the Parent of a Window</title>

+<!-- .XS -->

+<!-- (SN Changing the Parent of a Window  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To change a window's parent to another window on the same screen, use

+<function>XReparentWindow</function>.

+There is no way to move a window between screens.

+<indexterm significance="preferred"><primary>XReparentWindow</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XReparentWindow</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>Window<parameter> parent</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>parent</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the parent window.

+<!-- .ds Xy \ of the position in the new parent window -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If the specified window is mapped,

+<function>XReparentWindow</function>

+automatically performs an

+<function>UnmapWindow</function>

+request on it, removes it from its current position in the hierarchy,

+and inserts it as the child of the specified parent.

+The window is placed in the stacking order on top with respect to

+sibling windows.

+</para>

+<para>

+<!-- .LP -->

+After reparenting the specified window,

+<function>XReparentWindow</function>

+causes the X server to generate a

+<function>ReparentNotify</function>

+event.

+The override_redirect member returned in this event is

+set to the window's corresponding attribute.

+Window manager clients usually should ignore this window if this member

+is set to

+<function>True</function>.

+Finally, if the specified window was originally mapped,

+the X server automatically performs a

+<function>MapWindow</function>

+request on it.

+</para>

+<para>

+<!-- .LP -->

+The X server performs normal exposure processing on formerly obscured

+windows.

+The X server might not generate 

+<function>Expose </function>

+events for regions from the initial

+<function>UnmapWindow</function>

+request that are immediately obscured by the final

+<function>MapWindow</function>

+request.

+A

+<function>BadMatch</function>

+error results if:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+The new parent window is not on the same screen as

+the old parent window.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The new parent window is the specified window or an inferior of the

+specified window.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The new parent is

+<function>InputOnly</function>,

+and the window is not.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The specified window has a

+<function>ParentRelative</function>

+background, and the new parent window is not the same depth as the

+specified window.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+<function>XReparentWindow</function>

+can generate

+<function>BadMatch</function>

+and

+<function>BadWindow </function>

+errors.

+</para>

+</sect1>

+<sect1 id="Controlling_the_Lifetime_of_a_Window">

+<title>Controlling the Lifetime of a Window</title>

+<!-- .XS -->

+<!-- (SN Controlling the Lifetime of a Window  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The save-set of a client is a list of other clients' windows that,

+if they are inferiors of one of the client's windows at connection close,

+should not be destroyed and should be remapped if they are unmapped.

+For further information about close-connection processing,

+see section 2.6.

+To allow an application's window to survive when a window manager that

+has reparented a window fails,

+Xlib provides the save-set functions that you can 

+use to control the longevity of subwindows

+that are normally destroyed when the parent is destroyed.

+For example, a window manager that wants to add decoration

+to a window by adding a frame might reparent an application's

+window. 

+When the frame is destroyed,

+the application's window should not be destroyed 

+but be returned to its previous place in the window hierarchy.

+</para>

+<para>

+<!-- .LP -->

+The X server automatically removes windows from the save-set

+when they are destroyed.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To add or remove a window from the client's save-set, use

+<function>XChangeSaveSet</function>.

+<indexterm significance="preferred"><primary>XChangeSaveSet</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XChangeSaveSet</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>int<parameter> change_mode</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Wi that you want to add to or delete from the client's save-set -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window (Wi.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>change_mode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the mode.

+You can pass

+<function>SetModeInsert </function>

+or

+<function>SetModeDelete</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Depending on the specified mode,

+<function>XChangeSaveSet</function>

+either inserts or deletes the specified window from the client's save-set. 

+The specified window must have been created by some other client,

+or a

+<function>BadMatch</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+<function>XChangeSaveSet</function>

+can generate

+<function>BadMatch</function>,

+<function>BadValue</function>,

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To add a window to the client's save-set, use

+<function>XAddToSaveSet</function>.

+<indexterm significance="preferred"><primary>XAddToSaveSet</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XAddToSaveSet</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Wi that you want to add to the client's save-set -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window (Wi.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XAddToSaveSet</function>

+function adds the specified window to the client's save-set.

+The specified window must have been created by some other client,

+or a

+<function>BadMatch</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+<function>XAddToSaveSet</function>

+can generate

+<function>BadMatch</function>

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To remove a window from the client's save-set, use

+<function>XRemoveFromSaveSet</function>.

+<indexterm significance="preferred"><primary>XRemoveFromSaveSet</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XRemoveFromSaveSet</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Wi that you want to delete from the client's save-set -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window (Wi.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XRemoveFromSaveSet</function>

+function removes the specified window from the client's save-set.

+The specified window must have been created by some other client,

+or a

+<function>BadMatch</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+<function>XRemoveFromSaveSet</function>

+can generate

+<function>BadMatch </function>

+and

+<function>BadWindow </function>

+errors.

+</para>

+</sect1>

+<sect1 id="Managing_Installed_Colormaps">

+<title>Managing Installed Colormaps</title>

+<!-- .XS -->

+<!-- (SN Managing Installed Colormaps -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The X server maintains a list of installed colormaps.

+Windows using these colormaps are guaranteed to display with

+correct colors; windows using other colormaps may or may not display

+with correct colors.

+Xlib provides functions that you can use to install a colormap, 

+uninstall a colormap, and obtain a list of installed colormaps.

+</para>

+<para>

+<!-- .LP -->

+At any time,

+there is a subset of the installed maps that is viewed as an ordered list

+and is called the required list.

+The length of the required list is at most M,

+where M is the minimum number of installed colormaps specified for the screen

+in the connection setup.

+The required list is maintained as follows.

+When a colormap is specified to

+<function>XInstallColormap</function>,

+it is added to the head of the list;

+the list is truncated at the tail, if necessary, to keep its length to 

+at most M.

+When a colormap is specified to

+<function>XUninstallColormap</function>

+and it is in the required list,

+it is removed from the list.

+A colormap is not added to the required list when it is implicitly installed

+by the X server,

+and the X server cannot implicitly uninstall a colormap that is in the

+required list.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To install a colormap, use

+<function>XInstallColormap</function>.

+<indexterm significance="preferred"><primary>XInstallColormap</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XInstallColormap</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XInstallColormap</function>

+function installs the specified colormap for its associated screen.

+All windows associated with this colormap immediately display with

+true colors.

+You associated the windows with this colormap when you created them by calling

+<function>XCreateWindow</function>,

+<function>XCreateSimpleWindow</function>,

+<function>XChangeWindowAttributes</function>,

+or

+<function>XSetWindowColormap</function>.

+</para>

+<para>

+<!-- .LP -->

+If the specified colormap is not already an installed colormap, 

+the X server generates a

+<function>ColormapNotify</function>

+event on each window that has that colormap.

+In addition, for every other colormap that is installed as 

+a result of a call to

+<function>XInstallColormap</function>,

+the X server generates a

+<function>ColormapNotify</function>

+event on each window that has that colormap.

+</para>

+<para>

+<!-- .LP -->

+<function>XInstallColormap</function>

+can generate a

+<function>BadColor </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To uninstall a colormap, use

+<function>XUninstallColormap</function>.

+<indexterm significance="preferred"><primary>XUninstallColormap</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XUninstallColormap</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the colormap.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XUninstallColormap</function>

+function removes the specified colormap from the required

+list for its screen.

+As a result,

+the specified colormap might be uninstalled, 

+and the X server might implicitly install or uninstall additional colormaps.

+Which colormaps get installed or uninstalled is server dependent

+except that the required list must remain installed.

+</para>

+<para>

+<!-- .LP -->

+If the specified colormap becomes uninstalled, 

+the X server generates a

+<function>ColormapNotify</function>

+event on each window that has that colormap.

+In addition, for every other colormap that is installed or uninstalled as a 

+result of a call to 

+<function>XUninstallColormap</function>,

+the X server generates a

+<function>ColormapNotify</function>

+event on each window that has that colormap.

+</para>

+<para>

+<!-- .LP -->

+<function>XUninstallColormap</function>

+can generate a

+<function>BadColor </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain a list of the currently installed colormaps for a given screen, use

+<function>XListInstalledColormaps</function>.

+<indexterm significance="preferred"><primary>XListInstalledColormaps</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Colormap<function> *XListInstalledColormaps</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>int<parameter> *num_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Wi that determines the screen -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window (Wi.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>num_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of currently installed colormaps.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XListInstalledColormaps</function>

+function returns a list of the currently installed colormaps for the screen 

+of the specified window.

+The order of the colormaps in the list is not significant

+and is no explicit indication of the required list.

+When the allocated list is no longer needed,

+free it by using

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XListInstalledColormaps</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+</sect1>

+<sect1 id="Setting_and_Retrieving_the_Font_Search_Path">

+<title>Setting and Retrieving the Font Search Path</title>

+<!-- .XS -->

+<!-- (SN Setting and Retrieving the Font Search Path  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The set of fonts available from a server depends on a font

+search path.  Xlib provides functions to set and retrieve the

+search path for a server.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the font search path, use

+<function>XSetFontPath</function>.

+<indexterm significance="preferred"><primary>XSetFontPath</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetFontPath</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>char<parameter> **directories</parameter></paramdef>

+  <paramdef>int<parameter> ndirs</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>directories</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the directory path used to look for a font.

+Setting the path to the empty list restores the default path defined

+for the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ndirs</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of directories in the path.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetFontPath</function>

+function defines the directory search path for font lookup.

+There is only one search path per X server, not one per client.

+The encoding and interpretation of the strings are implementation-dependent,

+but typically they specify directories or font servers to be searched 

+in the order listed.

+An X server is permitted to cache font information internally;

+for example, it might cache an entire font from a file and not

+check on subsequent opens of that font to see if the underlying

+font file has changed.

+However,

+when the font path is changed,

+the X server is guaranteed to flush all cached information about fonts 

+for which there currently are no explicit resource IDs allocated.

+The meaning of an error from this request is implementation-dependent.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetFontPath</function>

+can generate a

+<function>BadValue </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To get the current font search path, use

+<function>XGetFontPath</function>.

+<indexterm significance="preferred"><primary>XGetFontPath</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> **XGetFontPath</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> *npaths_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>npaths_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of strings in the font path array.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetFontPath</function>

+function allocates and returns an array of strings containing the search path.

+The contents of these strings are implementation-dependent

+and are not intended to be interpreted by client applications.

+When it is no longer needed,

+the data in the font path should be freed by using

+<function>XFreeFontPath</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To free data returned by

+<function>XGetFontPath</function>,

+use

+<function>XFreeFontPath</function>.

+<indexterm significance="preferred"><primary>XFreeFontPath</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XFreeFontPath</function></funcdef>

+  <paramdef>char<parameter> **list</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>list</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the array of strings you want to free.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XFreeFontPath</function>

+function

+frees the data allocated by

+<function>XGetFontPath</function>.

+</para>

+</sect1>

+<sect1 id="Grabbing_the_Server_">

+<title>Grabbing the Server </title>

+<!-- .XS -->

+<!-- (SN Grabbing the Server  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to grab and ungrab the server.

+These functions can be used to control processing of output on other

+connections by the window system server.

+While the server is grabbed,

+no processing of requests or close downs on any other connection will occur.

+A client closing its connection automatically ungrabs the server.

+<indexterm><primary>Menus</primary></indexterm>

+<indexterm><primary>Window</primary><secondary>managers</secondary></indexterm>

+Although grabbing the server is highly discouraged, it is sometimes necessary.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To grab the server, use

+<function>XGrabServer</function>.

+<indexterm><primary>Server</primary><secondary>grabbing</secondary></indexterm>

+<indexterm><primary>Grabbing</primary><secondary>server</secondary></indexterm>

+<indexterm significance="preferred"><primary>XGrabServer</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XGrabServer</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGrabServer</function>

+function disables processing of requests and close downs on all other 

+connections than the one this request arrived on.

+You should not grab the X server any more than is absolutely necessary.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To ungrab the server, use

+<function>XUngrabServer</function>.

+<indexterm significance="preferred"><primary>XUngrabServer</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XUngrabServer</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XUngrabServer</function>

+function restarts processing of requests and close downs on other connections.

+You should avoid grabbing the X server as much as possible.

+</para>

+</sect1>

+<sect1 id="Killing_Clients">

+<title>Killing Clients</title>

+<!-- .XS -->

+<!-- (SN Killing Clients  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides a function to cause the connection to

+a client to be closed and its resources to be destroyed.

+To destroy a client, use

+<function>XKillClient</function>.

+<indexterm significance="preferred"><primary>XKillClient</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XKillClient</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XID<parameter> resource</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>resource</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies any resource associated with the client that you want to destroy or

+<function>AllTemporary</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XKillClient</function>

+function

+forces a close down of the client

+that created the resource

+if a valid resource is specified.

+If the client has already terminated in

+either 

+<function>RetainPermanent </function>

+or 

+<function>RetainTemporary </function>

+mode, all of the client's

+resources are destroyed.

+If 

+<function>AllTemporary </function>

+is specified, the resources of all clients that have terminated in

+<function>RetainTemporary </function>

+are destroyed (see section 2.5).

+This permits implementation of window manager facilities that aid debugging.

+A client can set its close-down mode to

+<function>RetainTemporary</function>.

+If the client then crashes,

+its windows would not be destroyed. 

+The programmer can then inspect the application's window tree 

+and use the window manager to destroy the zombie windows.

+</para>

+<para>

+<!-- .LP -->

+<function>XKillClient</function>

+can generate a

+<function>BadValue </function>

+error.

+</para>

+</sect1>

+<sect1 id="Controlling_the_Screen_Saver_">

+<title>Controlling the Screen Saver </title>

+<!-- .XS -->

+<!-- (SN Controlling the Screen Saver  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to set or reset the mode 

+of the screen saver, to force or activate the screen saver,

+or to obtain the current screen saver values.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the screen saver mode, use

+<function>XSetScreenSaver</function>.

+<indexterm significance="preferred"><primary>XSetScreenSaver</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetScreenSaver</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>inttimeout,<parameter> interval</parameter></paramdef>

+  <paramdef>int<parameter> prefer_blanking</parameter></paramdef>

+  <paramdef>int<parameter> allow_exposures</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>timeout</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the timeout, in seconds, until the screen saver turns on.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>interval</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the interval, in seconds, between screen saver alterations.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>prefer_blanking</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies how to enable screen blanking.

+You can pass

+<function>DontPreferBlanking</function>,

+<function>PreferBlanking</function>,

+or

+<function>DefaultBlanking</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>allow_exposures</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the screen save control values.

+You can pass

+<function>DontAllowExposures</function>,

+<function>AllowExposures</function>,

+or

+<function>DefaultExposures</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Timeout and interval are specified in seconds. 

+A timeout of 0 disables the screen saver 

+(but an activated screen saver is not deactivated),

+and a timeout of \-1 restores the default.

+Other negative values generate a

+<function>BadValue</function>

+error.

+If the timeout value is nonzero, 

+<function>XSetScreenSaver</function>

+enables the screen saver.

+An interval of 0 disables the random-pattern motion.

+If no input from devices (keyboard, mouse, and so on) is generated 

+for the specified number of timeout seconds once the screen saver is enabled,

+the screen saver is activated.

+</para>

+<para>

+<!-- .LP -->

+For each screen, 

+if blanking is preferred and the hardware supports video blanking, 

+the screen simply goes blank.  

+Otherwise, if either exposures are allowed or the screen can be regenerated 

+without sending 

+<function>Expose </function>

+events to clients, 

+the screen is tiled with the root window background tile randomly 

+re-origined each interval seconds.

+Otherwise, the screens' state do not change, 

+and the screen saver is not activated.

+The screen saver is deactivated,

+and all screen states are restored at the next

+keyboard or pointer input or at the next call to

+<function>XForceScreenSaver</function>

+with mode

+<function>ScreenSaverReset</function>.

+</para>

+<para>

+<!-- .LP -->

+If the server-dependent screen saver method supports periodic change,

+the interval argument serves as a hint about how long the change period

+should be, and zero hints that no periodic change should be made.

+Examples of ways to change the screen include scrambling the colormap

+periodically, moving an icon image around the screen periodically, or tiling

+the screen with the root window background tile, randomly re-origined

+periodically.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetScreenSaver</function>

+can generate a

+<function>BadValue </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To force the screen saver on or off, use

+<function>XForceScreenSaver</function>.

+<indexterm significance="preferred"><primary>XForceScreenSaver</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XForceScreenSaver</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> mode</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>mode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the mode that is to be applied.

+You can pass

+<function>ScreenSaverActive</function>

+or

+<function>ScreenSaverReset</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If the specified mode is 

+<function>ScreenSaverActive </function>

+and the screen saver currently is deactivated,

+<function>XForceScreenSaver</function>

+activates the screen saver even if the screen saver had been disabled

+with a timeout of zero.

+If the specified mode is 

+<function>ScreenSaverReset </function>

+and the screen saver currently is enabled,

+<function>XForceScreenSaver</function>

+deactivates the screen saver if it was activated,

+and the activation timer is reset to its initial state 

+(as if device input had been received).

+</para>

+<para>

+<!-- .LP -->

+<function>XForceScreenSaver</function>

+can generate a

+<function>BadValue </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To activate the screen saver, use

+<function>XActivateScreenSaver</function>.

+<indexterm significance="preferred"><primary>XActivateScreenSaver</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XActivateScreenSaver</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To reset the screen saver, use

+<function>XResetScreenSaver</function>.

+<indexterm significance="preferred"><primary>XResetScreenSaver</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XResetScreenSaver</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To get the current screen saver values, use

+<function>XGetScreenSaver</function>.

+<indexterm significance="preferred"><primary>XGetScreenSaver</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XGetScreenSaver</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int*timeout_return,<parameter> *interval_return</parameter></paramdef>

+  <paramdef>int<parameter> *prefer_blanking_return</parameter></paramdef>

+  <paramdef>int<parameter> *allow_exposures_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>timeout_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the timeout, in seconds, until the screen saver turns on.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>interval_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the interval between screen saver invocations.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>prefer_blanking_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the current screen blanking preference

+(<function>DontPreferBlanking</function>,

+<function>PreferBlanking</function>,

+or

+<function>DefaultBlanking</function>).

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>allow_exposures_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the current screen save control value

+(<function>DontAllowExposures</function>,

+<function>AllowExposures</function>,

+or

+<function>DefaultExposures</function>).

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+</para>

+</sect1>

+<sect1 id="Controlling_Host_Access">

+<title>Controlling Host Access</title>

+<!-- .XS -->

+<!-- (SN Controlling Host Access  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+This section discusses how to:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Add, get, or remove hosts from the access control list

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Change, enable, or disable access

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+<indexterm><primary>Access control list</primary></indexterm>

+<indexterm><primary>Authentication</primary></indexterm>

+X does not provide any protection on a per-window basis.

+If you find out the resource ID of a resource, you can manipulate it.

+To provide some minimal level of protection, however,

+connections are permitted only from machines you trust.

+This is adequate on single-user workstations but obviously

+breaks down on timesharing machines.

+Although provisions exist in the X protocol for proper connection

+authentication, the lack of a standard authentication server

+leaves host-level access control as the only common mechanism.

+</para>

+<para>

+<!-- .LP -->

+<indexterm><primary>Default Protection</primary></indexterm>

+The initial set of hosts allowed to open connections typically consists of:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+The host the window system is running on.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+On <acronym>POSIX</acronym>-conformant systems, each host listed in the

+<function>/etc/X?.hosts </function>

+file.

+The ? indicates the number of the

+display.

+<indexterm><primary>Files</primary><secondary>/etc/X?.hosts</secondary></indexterm>

+This file should consist of host names separated by newlines.

+DECnet nodes must terminate in :: to distinguish them from Internet hosts.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+If a host is not in the access control list when the access control 

+mechanism is enabled and if the host attempts to establish a connection,

+the server refuses the connection.

+To change the access list,

+the client must reside on the same host as the server and/or must

+have been granted permission in the initial authorization at connection

+setup.

+</para>

+<para>

+<!-- .LP -->

+Servers also can implement other access control policies in addition to

+or in place of this host access facility.

+For further information about other access control implementations,

+see ``X Window System Protocol.''

+</para>

+<sect2 id="Adding_Getting_or_Removing_Hosts">

+<title>Adding, Getting, or Removing Hosts</title>

+<!-- .XS -->

+<!-- (SN Adding, Getting, or Removing Hosts  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to add, get, or remove hosts

+from the access control list.

+All the host access control functions use the 

+<function>XHostAddress </function>

+structure, which contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XHostAddress</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int family;        /* for example FamilyInternet */

+     int length;        /* length of address, in bytes */

+     char *address;     /* pointer to where to find the address */

+} XHostAddress;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The family member specifies which protocol address family to use 

+(for example, <acronym>TCP</acronym>/<acronym>IP</acronym> or DECnet) and can be

+<function>FamilyInternet</function>,

+<function>FamilyInternet6</function>,

+<function>FamilyServerInterpreted</function>,

+<function>FamilyDECnet</function>,

+or

+<function>FamilyChaos</function>.

+The length member specifies the length of the address in bytes.

+The address member specifies a pointer to the address.

+</para>

+<para>

+<!-- .LP -->

+For <acronym>TCP</acronym>/<acronym>IP</acronym>, the address should be in network byte order.

+For <acronym>IP</acronym> version 4 addresses, the family should be FamilyInternet

+and the length should be 4 bytes.  For <acronym>IP</acronym> version 6 addresses, the

+family should be FamilyInternet6 and the length should be 16 bytes.

+</para>

+<para>

+<!-- .LP -->

+For the DECnet family, 

+the server performs no automatic swapping on the address bytes.

+A Phase IV address is 2 bytes long.

+The first byte contains the least significant 8 bits of the node number.

+The second byte contains the most significant 2 bits of the

+node number in the least significant 2 bits of the byte

+and the area in the most significant 6 bits of the byte.

+</para>

+<para>

+<!-- .LP -->

+For the ServerInterpreted family, the length is ignored and the address 

+member is a pointer to a 

+<function>XServerInterpretedAddress</function>

+structure, which contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XServerInterpretedAddress</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int typelength;     /* length of type string, in bytes */

+     int valuelength;    /* length of value string, in bytes */

+     char *type;         /* pointer to where to find the type string */

+     char *value;        /* pointer to where to find the address */

+} XServerInterpretedAddress;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The type and value members point to strings representing the type and value of

+the server interpreted entry.  These strings may not be NULL-terminated so care

+should be used when accessing them.  The typelength and valuelength members

+specify the length in byte of the type and value strings.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To add a single host, use

+<function>XAddHost</function>.

+<indexterm significance="preferred"><primary>XAddHost</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XAddHost</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XHostAddress<parameter> *host</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Ho added -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>host</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the host that is to be (Ho.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XAddHost</function>

+function adds the specified host to the access control list for that display.

+The server must be on the same host as the client issuing the command, or a

+<function>BadAccess</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+<function>XAddHost</function>

+can generate

+<function>BadAccess</function>

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To add multiple hosts at one time, use

+<function>XAddHosts</function>.

+<indexterm significance="preferred"><primary>XAddHosts</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XAddHosts</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XHostAddress<parameter> *hosts</parameter></paramdef>

+  <paramdef>int<parameter> num_hosts</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Ho added -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hosts</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies each host that is to be (Ho.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>num_hosts</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of hosts.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XAddHosts</function>

+function adds each specified host to the access control list for that display.

+The server must be on the same host as the client issuing the command, or a

+<function>BadAccess</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+<function>XAddHosts</function>

+can generate

+<function>BadAccess</function>

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain a host list, use

+<function>XListHosts</function>.

+<indexterm significance="preferred"><primary>XListHosts</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XHostAddress<function> *XListHosts</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> *nhosts_return</parameter></paramdef>

+  <paramdef>Bool<parameter> *state_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nhosts_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of hosts currently in the access control list.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>state_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the state of the access control.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XListHosts</function>

+function returns the current access control list as well as whether the use 

+of the list at connection setup was enabled or disabled.

+<function>XListHosts</function>

+allows a program to find out what machines can make connections.

+It also returns a pointer to a list of host structures that

+were allocated by the function. 

+When no longer needed,

+this memory should be freed by calling

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To remove a single host, use

+<function>XRemoveHost</function>.

+<indexterm significance="preferred"><primary>XRemoveHost</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XRemoveHost</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XHostAddress<parameter> *host</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Ho removed -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>host</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the host that is to be (Ho.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XRemoveHost</function>

+function removes the specified host from the access control list 

+for that display.

+The server must be on the same host as the client process, or a

+<function>BadAccess</function>

+error results.

+If you remove your machine from the access list,

+you can no longer connect to that server,

+and this operation cannot be reversed unless you reset the server.

+</para>

+<para>

+<!-- .LP -->

+<function>XRemoveHost</function>

+can generate

+<function>BadAccess</function>

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To remove multiple hosts at one time, use

+<function>XRemoveHosts</function>.

+<indexterm significance="preferred"><primary>XRemoveHosts</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XRemoveHosts</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XHostAddress<parameter> *hosts</parameter></paramdef>

+  <paramdef>int<parameter> num_hosts</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Ho removed -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hosts</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies each host that is to be (Ho.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>num_hosts</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of hosts.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XRemoveHosts</function>

+function removes each specified host from the access control list for that 

+display.  

+The X server must be on the same host as the client process, or a

+<function>BadAccess</function>

+error results.

+If you remove your machine from the access list, 

+you can no longer connect to that server,

+and this operation cannot be reversed unless you reset the server.

+</para>

+<para>

+<!-- .LP -->

+<function>XRemoveHosts</function>

+can generate

+<function>BadAccess</function>

+and

+<function>BadValue </function>

+errors.

+</para>

+</sect2>

+<sect2 id="Changing_Enabling_or_Disabling_Access_Control">

+<title>Changing, Enabling, or Disabling Access Control</title>

+<!-- .XS -->

+<!-- (SN Changing, Enabling, or Disabling Access Control  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to enable, disable, 

+or change access control.

+</para>

+<para>

+<!-- .LP -->

+For these functions to execute successfully,

+the client application must reside on the same host as the X server

+and/or have been given permission in the initial authorization

+at connection setup.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To change access control, use

+<function>XSetAccessControl</function>.

+<indexterm significance="preferred"><primary>XSetAccessControl</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetAccessControl</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> mode</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>mode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the mode.

+You can pass

+<function>EnableAccess</function>

+or

+<function>DisableAccess</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetAccessControl</function>

+function either enables or disables the use of the access control list 

+at each connection setup.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetAccessControl</function>

+can generate

+<function>BadAccess</function>

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To enable access control, use

+<function>XEnableAccessControl</function>.

+<indexterm significance="preferred"><primary>XEnableAccessControl</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XEnableAccessControl</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XEnableAccessControl</function>

+function enables the use of the access control list at each connection setup.

+</para>

+<para>

+<!-- .LP -->

+<function>XEnableAccessControl</function>

+can generate a

+<function>BadAccess </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To disable access control, use

+<function>XDisableAccessControl</function>.

+<indexterm significance="preferred"><primary>XDisableAccessControl</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDisableAccessControl</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XDisableAccessControl</function>

+function disables the use of the access control list at each connection setup.

+</para>

+<para>

+<!-- .LP -->

+<function>XDisableAccessControl</function>

+can generate a

+<function>BadAccess </function>

+error.

+<!-- .bp -->

+

+</para>

+</sect2>

+</sect1>

+</chapter>

diff --git a/libX11/specs/libX11/CH10 b/libX11/specs/libX11/CH10
deleted file mode 100644
index 76502fb9e..000000000
--- a/libX11/specs/libX11/CH10
+++ /dev/null
@@ -1,3886 +0,0 @@
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-.\" OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" Except as contained in this notice, the name of the X Consortium shall
-.\" not be used in advertising or otherwise to promote the sale, use or
-.\" other dealings in this Software without prior written authorization
-.\" from the X Consortium.
-.\"
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
-.\" Digital Equipment Corporation
-.\"
-.\" Portions Copyright \(co 1990, 1991 by
-.\" Tektronix, Inc.
-.\"
-.\" Permission to use, copy, modify and distribute this documentation for
-.\" any purpose and without fee is hereby granted, provided that the above
-.\" copyright notice appears in all copies and that both that copyright notice
-.\" and this permission notice appear in all copies, and that the names of
-.\" Digital and Tektronix not be used in in advertising or publicity pertaining
-.\" to this documentation without specific, written prior permission.
-.\" Digital and Tektronix makes no representations about the suitability
-.\" of this documentation for any purpose.
-.\" It is provided ``as is'' without express or implied warranty.
-.\" 
-\&
-.sp 1
-.ce 3
-\s+1\fBChapter 10\fP\s-1
-
-\s+1\fBEvents\fP\s-1
-.sp 2
-.nr H1 10
-.nr H2 0
-.nr H3 0
-.nr H4 0
-.nr H5 0
-.na
-.LP
-.XS
-Chapter 10: Events
-.XE
-A client application communicates with the X server through the connection you
-establish with the 
-.PN XOpenDisplay 
-.IN "XOpenDisplay"
-function.
-A client application sends requests to the X server over this connection.
-.IN "Requests" "" "@DEF@"
-These requests are made by the Xlib functions that are 
-called in the client application.
-Many Xlib functions cause the X server to generate events,
-and the user's typing or moving the pointer can generate events asynchronously.
-The X server returns events to the client on the same connection.
-.LP
-This chapter discusses the following topics associated with events:
-.IP \(bu 5
-Event types
-.IP \(bu 5
-Event structures
-.IP \(bu 5
-Event masks
-.IP \(bu 5
-Event processing
-.LP
-Functions for handling events are dealt with in the next chapter.
-.NH 2
-Event Types
-.XS
-\*(SN Event Types 
-.XE
-.LP
-.IN "Event" "types"
-An event is data generated asynchronously by the X server as a result of some 
-device activity or as side effects of a request sent by an Xlib function.
-.IN "Event" 
-Device-related events propagate from the source window to ancestor windows
-until some client application has selected that event type 
-or until the event is explicitly discarded.
-The X server generally sends an event to a client application
-only if the client has specifically asked to be informed of that event type, 
-typically by setting the event-mask attribute of the window.
-The mask can also be set when you create a window
-or by changing the window's
-event-mask.
-You can also mask out events that would propagate to ancestor windows
-by manipulating the
-do-not-propagate mask of the window's attributes.
-However,
-.PN MappingNotify
-events are always sent to all clients.
-.IN "Input Control"
-.IN "Output Control"
-.LP
-An event type describes a specific event generated by the X server.
-For each event type, 
-a corresponding constant name is defined in
-.hN X11/X.h ,
-which is used when referring to an event type.
-.IN "Event" "categories"
-The following table lists the event category 
-and its associated event type or types. 
-The processing associated with these events is discussed in section 10.5.
-.LP
-.\".CP T 1
-.\"Event Categories and Event Types
-.LP
-.TS H
-lw(2.25i) lw(3.5i).
-_
-.sp 6p
-.B
-Event Category	Event Type
-.sp 6p
-_
-.sp 6p
-.TH
-.R
-T{
-Keyboard events
-T}	T{
-.PN KeyPress ,
-.PN KeyRelease
-T}
-.sp 6p
-T{
-Pointer events
-T}	T{
-.PN ButtonPress , 
-.PN ButtonRelease  ,
-.PN MotionNotify
-T}
-.sp 6p
-T{
-Window crossing events
-T}	T{
-.PN EnterNotify , 
-.PN LeaveNotify
-T}
-.sp 6p
-T{
-Input focus events
-T}	T{
-.PN FocusIn , 
-.PN FocusOut
-T}
-.sp 6p
-T{
-Keymap state notification event
-T}	T{
-.PN KeymapNotify
-T}
-.sp 6p
-T{
-Exposure events	
-T}	T{
-.PN Expose , 
-.PN GraphicsExpose , 
-.PN NoExpose
-T}
-.sp 6p
-T{
-Structure control events
-T}	T{
-.PN CirculateRequest , 
-.PN ConfigureRequest , 
-.PN MapRequest ,
-.PN ResizeRequest
-T}
-.sp 6p
-T{
-Window state notification events
-T}	T{
-.PN CirculateNotify , 
-.PN ConfigureNotify , 
-.PN CreateNotify , 
-.PN DestroyNotify , 
-.PN GravityNotify , 
-.PN MapNotify ,
-.PN MappingNotify , 
-.PN ReparentNotify , 
-.PN UnmapNotify , 
-.br
-.PN VisibilityNotify
-T}
-.sp 6p
-T{
-Colormap state notification event
-T}	T{
-.PN ColormapNotify
-T}
-.sp 6p
-T{
-Client communication events
-T}	T{
-.PN ClientMessage , 
-.PN PropertyNotify , 
-.PN SelectionClear , 
-.PN SelectionNotify , 
-.PN SelectionRequest
-T}
-.sp 6p
-_
-.TE
-.\".LP
-.\"Table 8-1 lists the event types and the Xlib functions that could cause
-.\"the X server to generate that event type.
-.\"The event types are listed alphabetically.
-.\"Note that the error event is not listed in this table.
-.\"For a list of the constants associated with an error event, see the Handling
-.\"Errors section in this chapter.
-.\".LP
-.\".so eventtable
-.NH 2
-Event Structures
-.XS
-\*(SN Event Structures 
-.XE
-.LP
-For each event type,
-a corresponding structure is declared in
-.hN X11/Xlib.h .
-All the event structures have the following common members:
-.LP
-.IN "XAnyEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window window;
-} XAnyEvent;
-.De
-.LP
-.eM
-The type member is set to the event type constant name that uniquely identifies
-it.
-For example, when the X server reports a
-.PN GraphicsExpose
-event to a client application, it sends an
-.PN XGraphicsExposeEvent
-structure with the type member set to
-.PN GraphicsExpose .
-The display member is set to a pointer to the display the event was read on.
-The send_event member is set to
-.PN True
-if the event came from a
-.PN SendEvent
-protocol request.
-The serial member is set from the serial number reported in the protocol
-but expanded from the 16-bit least-significant bits to a full 32-bit value.
-The window member is set to the window that is most useful to toolkit
-dispatchers.
-.LP
-The X server can send events at any time in the input stream. 
-Xlib stores any events received while waiting for a reply in an event queue 
-for later use.
-Xlib also provides functions that allow you to check events 
-in the event queue (see section 11.3).
-.LP
-In addition to the individual structures declared for each event type, the
-.PN XEvent
-structure is a union of the individual structures declared for each event type.
-Depending on the type,
-you should access members of each event by using the 
-.PN XEvent
-union.
-.LP
-.IN "XEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef union _XEvent {
-	int type;	/* must not be changed */
-	XAnyEvent xany;
-	XKeyEvent xkey;
-	XButtonEvent xbutton;
-	XMotionEvent xmotion;
-	XCrossingEvent xcrossing;
-	XFocusChangeEvent xfocus;
-	XExposeEvent xexpose;
-	XGraphicsExposeEvent xgraphicsexpose;
-	XNoExposeEvent xnoexpose;
-	XVisibilityEvent xvisibility;
-	XCreateWindowEvent xcreatewindow;
-	XDestroyWindowEvent xdestroywindow;
-	XUnmapEvent xunmap;
-	XMapEvent xmap;
-	XMapRequestEvent xmaprequest;
-	XReparentEvent xreparent;
-	XConfigureEvent xconfigure;
-	XGravityEvent xgravity;
-	XResizeRequestEvent xresizerequest;
-	XConfigureRequestEvent xconfigurerequest;
-	XCirculateEvent xcirculate;
-	XCirculateRequestEvent xcirculaterequest;
-	XPropertyEvent xproperty;
-	XSelectionClearEvent xselectionclear;
-	XSelectionRequestEvent xselectionrequest;
-	XSelectionEvent xselection;
-	XColormapEvent xcolormap;
-	XClientMessageEvent xclient;
-	XMappingEvent xmapping;
-	XErrorEvent xerror;
-	XKeymapEvent xkeymap;
-	long pad[24];
-} XEvent;
-.De
-.LP
-.eM
-An
-.PN XEvent
-structure's first entry always is the type member,
-which is set to the event type.
-The second member always is the serial number of the protocol request
-that generated the event.
-The third member always is send_event,
-which is a
-.PN Bool
-that indicates if the event was sent by a different client.
-The fourth member always is a display,
-which is the display that the event was read from.
-Except for keymap events,
-the fifth member always is a window,
-which has been carefully selected to be useful to toolkit dispatchers.
-To avoid breaking toolkits,
-the order of these first five entries is not to change.
-Most events also contain a time member,
-which is the time at which an event occurred.
-In addition, a pointer to the generic event must be cast before it
-is used to access any other information in the structure.
-.NH 2
-Event Masks
-.XS
-\*(SN Event Masks
-.XE
-.LP
-.IN "Event mask" "" "@DEF@"
-Clients select event reporting of most events relative to a window.
-To do this, pass an event mask to an Xlib event-handling
-function that takes an event_mask argument.
-The bits of the event mask are defined in
-.hN X11/X.h .
-Each bit in the event mask maps to an event mask name,
-which describes the event or events you want the X server to
-return to a client application.
-.LP
-Unless the client has specifically asked for them,
-most events are not reported to clients when they are generated. 
-Unless the client suppresses them by setting graphics-exposures in the GC to
-.PN False ,
-.PN GraphicsExpose 
-and 
-.PN NoExpose 
-are reported by default as a result of
-.PN XCopyPlane
-and
-.PN XCopyArea .
-.PN SelectionClear ,
-.PN SelectionRequest ,
-.PN SelectionNotify ,
-or
-.PN ClientMessage
-cannot be masked.
-Selection-related events are only sent to clients cooperating
-with selections (see section 4.5).
-When the keyboard or pointer mapping is changed,
-.PN MappingNotify
-is always sent to clients.
-.LP
-.\"Table 8-2 
-The following table 
-lists the event mask constants you can pass to
-the event_mask argument and
-the circumstances in which you would want to specify the
-event mask:
-.LP
-.\" .CP T 2
-.\"Event Mask Definitions
-.TS H
-lw(2i) lw(3.5i).
-_
-.sp 6p
-.B
-Event Mask	Circumstances
-.sp 6p
-_
-.sp 6p
-.TH
-.R
-T{
-.PN NoEventMask
-T}	T{
-No events wanted
-T}
-T{
-.PN KeyPressMask
-T}	T{
-Keyboard down events wanted
-T}
-T{
-.PN KeyReleaseMask
-T}	T{
-Keyboard up events wanted
-T}
-T{
-.PN ButtonPressMask
-T}	T{
-Pointer button down events wanted
-T}
-T{
-.PN ButtonReleaseMask
-T}	T{
-Pointer button up events wanted
-T}
-T{
-.PN EnterWindowMask
-T}	T{
-Pointer window entry events wanted
-T}
-T{
-.PN LeaveWindowMask
-T}	T{
-Pointer window leave events wanted
-T}
-T{
-.PN PointerMotionMask
-T}	T{
-Pointer motion events wanted
-T}
-T{
-.PN PointerMotionHintMask
-T}	T{
-Pointer motion hints wanted
-T}
-T{
-.PN Button1MotionMask
-T}	T{
-Pointer motion while button 1 down
-T}
-T{
-.PN Button2MotionMask
-T}	T{
-Pointer motion while button 2 down
-T}
-T{
-.PN Button3MotionMask
-T}	T{
-Pointer motion while button 3 down
-T}
-T{
-.PN Button4MotionMask
-T}	T{
-Pointer motion while button 4 down
-T}
-T{
-.PN Button5MotionMask
-T}	T{
-Pointer motion while button 5 down
-T}
-T{
-.PN ButtonMotionMask
-T}	T{
-Pointer motion while any button down
-T}
-T{
-.PN KeymapStateMask
-T}	T{
-Keyboard state wanted at window entry and focus in
-T}
-T{
-.PN ExposureMask
-T}	T{
-Any exposure wanted
-T}
-T{
-.PN VisibilityChangeMask
-T}	T{
-Any change in visibility wanted
-T}
-T{
-.PN StructureNotifyMask
-T}	T{
-Any change in window structure wanted
-T}
-T{
-.PN ResizeRedirectMask
-T}	T{
-Redirect resize of this window
-T}
-T{
-.PN SubstructureNotifyMask
-T}	T{
-Substructure notification wanted
-T}
-T{
-.PN SubstructureRedirectMask
-T}	T{
-Redirect structure requests on children
-T}
-T{
-.PN FocusChangeMask
-T}	T{
-Any change in input focus wanted
-T}
-T{
-.PN PropertyChangeMask
-T}	T{
-Any change in property wanted
-T}
-T{
-.PN ColormapChangeMask
-T}	T{
-Any change in colormap wanted
-T}
-T{
-.PN OwnerGrabButtonMask
-T}	T{
-Automatic grabs should activate with owner_events set to 
-.PN True
-T}
-.sp 6p
-_
-.TE
-.LP
-.NH 2
-Event Processing Overview
-.XS
-\*(SN Event Processing Overview
-.XE
-.LP
-The event reported to a client application during event processing
-depends on which event masks you provide as the event-mask attribute 
-for a window.
-For some event masks, there is a one-to-one correspondence between
-the event mask constant and the event type constant.
-For example, if you pass the event mask
-.PN ButtonPressMask ,
-the X server sends back only
-.PN ButtonPress
-events.
-.IN "CurrentTime"
-Most events contain a time member,
-which is the time at which an event occurred.
-.LP
-In other cases, one event mask constant can map to several event type constants.
-For example, if you pass the event mask
-.PN SubstructureNotifyMask ,
-the X server can send back
-.PN CirculateNotify ,
-.PN ConfigureNotify ,
-.PN CreateNotify ,
-.PN DestroyNotify ,
-.PN GravityNotify ,
-.PN MapNotify ,
-.PN ReparentNotify ,
-or
-.PN UnmapNotify
-events.
-.LP
-In another case, 
-two event masks can map to one event type.
-For example, 
-if you pass either
-.PN PointerMotionMask 
-or
-.PN ButtonMotionMask ,
-the X server sends back
-a
-.PN MotionNotify
-event.
-.LP
-The following table 
-lists the event mask, 
-its associated event type or types, 
-and the structure name associated with the event type.
-Some of these structures actually are typedefs to a generic structure
-that is shared between two event types.
-Note that N.A. appears in columns for which the information is not applicable.
-.LP
-.ps 9
-.nr PS 9
-.TS H
-lw(1.5i) lw(1i) lw(1.5i) lw(1.5i).
-_
-.sp 6p
-.B
-Event Mask	Event Type	Structure	Generic Structure
-.sp 6p
-_
-.sp 6p
-.TH
-.R
-ButtonMotionMask	MotionNotify	XPointerMovedEvent	XMotionEvent
-Button1MotionMask		
-Button2MotionMask		
-Button3MotionMask		
-Button4MotionMask		
-Button5MotionMask		
-.sp 6p
-ButtonPressMask	ButtonPress	XButtonPressedEvent	XButtonEvent
-.sp 6p
-ButtonReleaseMask	ButtonRelease	XButtonReleasedEvent	XButtonEvent
-.sp 6p
-ColormapChangeMask	ColormapNotify	XColormapEvent
-.sp 6p
-EnterWindowMask	EnterNotify	XEnterWindowEvent	XCrossingEvent
-.sp 6p
-LeaveWindowMask	LeaveNotify	XLeaveWindowEvent	XCrossingEvent
-.sp 6p
-ExposureMask	Expose	XExposeEvent 
-GCGraphicsExposures in GC	GraphicsExpose	XGraphicsExposeEvent
-	NoExpose	XNoExposeEvent
-.sp 6p
-FocusChangeMask	FocusIn	XFocusInEvent	XFocusChangeEvent
-	FocusOut	XFocusOutEvent	XFocusChangeEvent
-.sp 6p
-KeymapStateMask	KeymapNotify	XKeymapEvent
-.sp 6p
-KeyPressMask	KeyPress	XKeyPressedEvent	XKeyEvent
-KeyReleaseMask	KeyRelease	XKeyReleasedEvent	XKeyEvent
-.sp 6p
-OwnerGrabButtonMask	N.A.	N.A.
-.sp 6p
-PointerMotionMask	MotionNotify	XPointerMovedEvent	XMotionEvent
-PointerMotionHintMask	N.A.	N.A.
-.sp 6p
-PropertyChangeMask	PropertyNotify	XPropertyEvent
-.sp 6p
-ResizeRedirectMask	ResizeRequest	XResizeRequestEvent
-.sp 6p
-StructureNotifyMask	CirculateNotify	XCirculateEvent
-	ConfigureNotify	XConfigureEvent
-	DestroyNotify	XDestroyWindowEvent
-	GravityNotify	XGravityEvent
-	MapNotify	XMapEvent
-	ReparentNotify	XReparentEvent
-	UnmapNotify	XUnmapEvent
-.sp 6p
-SubstructureNotifyMask	CirculateNotify	XCirculateEvent
-	ConfigureNotify	XConfigureEvent
-	CreateNotify	XCreateWindowEvent
-	DestroyNotify	XDestroyWindowEvent
-	GravityNotify	XGravityEvent
-	MapNotify	XMapEvent
-	ReparentNotify	XReparentEvent
-	UnmapNotify	XUnmapEvent
-.sp 6p
-SubstructureRedirectMask	CirculateRequest	XCirculateRequestEvent
-	ConfigureRequest	XConfigureRequestEvent
-	MapRequest	XMapRequestEvent
-.sp 6p
-N.A.	ClientMessage	XClientMessageEvent
-.sp 6p
-N.A.	MappingNotify	XMappingEvent
-.sp 6p
-N.A.	SelectionClear	XSelectionClearEvent
-.sp 6p
-N.A.	SelectionNotify	XSelectionEvent
-.sp 6p
-N.A.	SelectionRequest	XSelectionRequestEvent
-.sp 6p
-VisibilityChangeMask	VisibilityNotify	XVisibilityEvent
-.sp 6p
-_
-.TE
-.ps 11
-.nr PS 11
-.LP
-The sections that follow describe the processing that occurs 
-when you select the different event masks.
-The sections are organized according to these processing categories:
-.IP \(bu 5
-Keyboard and pointer events
-.IP \(bu 5
-Window crossing events
-.IP \(bu 5
-Input focus events
-.IP \(bu 5
-Keymap state notification events
-.IP \(bu 5
-Exposure events
-.IP \(bu 5
-Window state notification events
-.IP \(bu 5
-Structure control events
-.IP \(bu 5
-Colormap state notification events
-.IP \(bu 5
-Client communication events
-.NH 2
-Keyboard and Pointer Events
-.XS
-\*(SN Keyboard and Pointer Events
-.XE
-.LP
-This section discusses:
-.IP \(bu 5
-Pointer button events
-.IP \(bu 5
-Keyboard and pointer events
-.NH 3
-Pointer Button Events
-.XS
-\*(SN Pointer Button Events
-.XE
-.LP
-The following describes the event processing that occurs when a pointer button 
-press is processed with the pointer in some window w and 
-when no active pointer grab is in progress.
-.LP
-The X server searches the ancestors of w from the root down,
-looking for a passive grab to activate.
-If no matching passive grab on the button exists,
-the X server automatically starts an active grab for the client receiving
-the event and sets the last-pointer-grab time to the current server time.
-The effect is essentially equivalent to an
-.PN XGrabButton
-with these client passed arguments:
-.TS H
-lw(1.5i) lw(3.5i).
-_
-.sp 6p
-.B
-Argument	Value
-.sp 6p
-_
-.sp 6p
-.TH
-.R
-T{
-\fIw\fP
-T}	T{
-The event window 
-T}
-T{
-\fIevent_mask\fP
-T}	T{
-The client's selected pointer events on the event window
-T}
-T{
-\fIpointer_mode\fP
-T}	T{
-.PN GrabModeAsync
-T}
-T{
-\fIkeyboard_mode\fP
-T}	T{
-.PN GrabModeAsync 
-T}
-T{
-\fIowner_events\fP
-T}	T{
-.PN True ,
-if the client has selected
-.PN OwnerGrabButtonMask
-on the event window,
-otherwise
-.PN False 
-T}
-T{
-\fIconfine_to\fP
-T}	T{
-.PN None 
-T}
-T{
-\fIcursor\fP
-T}	T{
-.PN None 
-T}
-.sp 6p
-_
-.TE
-.LP
-The active grab is automatically terminated when 
-the logical state of the pointer has all buttons released.
-Clients can modify the active grab by calling
-.PN XUngrabPointer
-and
-.PN XChangeActivePointerGrab .
-.NH 3
-Keyboard and Pointer Events
-.XS
-\*(SN Keyboard and Pointer Events
-.XE
-.LP
-.IN "Events" "ButtonPress"
-.IN "Events" "ButtonRelease"
-.IN "Events" "KeyPress"
-.IN "Events" "KeyRelease"
-.IN "Events" "MotionNotify"
-This section discusses the processing that occurs for the
-keyboard events
-.PN KeyPress
-and 
-.PN KeyRelease 
-and the pointer events
-.PN ButtonPress ,
-.PN ButtonRelease ,
-and
-.PN MotionNotify .
-For information about the keyboard event-handling utilities,
-see chapter 11.
-.LP
-.IN "KeyPress" "" "@DEF@"
-.IN "KeyRelease" "" "@DEF@"
-The X server reports
-.PN KeyPress
-or
-.PN KeyRelease
-events to clients wanting information about keys that logically change state.
-Note that these events are generated for all keys, 
-even those mapped to modifier bits.
-.IN "ButtonPress" "" "@DEF@"
-.IN "ButtonRelease" "" "@DEF@"
-The X server reports
-.PN ButtonPress
-or
-.PN ButtonRelease
-events to clients wanting information about buttons that logically change state.
-.LP
-.IN "MotionNotify" "" "@DEF@"
-The X server reports
-.PN MotionNotify
-events to clients wanting information about when the pointer logically moves.
-The X server generates this event whenever the pointer is moved 
-and the pointer motion begins and ends in the window.
-The granularity of
-.PN MotionNotify
-events is not guaranteed, 
-but a client that selects this event type is guaranteed
-to receive at least one event when the pointer moves and then rests.
-.LP
-The generation of the logical changes lags the physical changes 
-if device event processing is frozen.
-.LP
-To receive
-.PN KeyPress ,
-.PN KeyRelease ,
-.PN ButtonPress ,
-and
-.PN ButtonRelease 
-events, set 
-.PN KeyPressMask ,
-.PN KeyReleaseMask ,
-.PN ButtonPressMask ,
-and
-.PN ButtonReleaseMask 
-bits in the event-mask attribute of the window.
-.LP
-To receive 
-.PN MotionNotify
-events, set one or more of the following event 
-masks bits in the event-mask attribute of the window.
-.IP \(bu 5
-.PN Button1MotionMask \ \-
-.PN Button5MotionMask
-.IP
-The client application receives
-.PN MotionNotify
-events only when one or more of the specified buttons is pressed.
-.IP \(bu 5
-.PN ButtonMotionMask
-.IP
-The client application receives
-.PN MotionNotify
-events only when at least one button is pressed.
-.IP \(bu 5
-.PN PointerMotionMask
-.IP
-The client application receives 
-.PN MotionNotify
-events independent of the state of
-the pointer buttons.
-.IP \(bu 5
-.PN PointerMotionHintMask
-.IP
-If
-.PN PointerMotionHintMask
-is selected in combination with one or more of the above masks, 
-the X server is free to send only one
-.PN MotionNotify
-event (with the is_hint member  of the
-.PN XPointerMovedEvent
-structure set to
-.PN NotifyHint )
-to the client for the event window, 
-until either the key or button state changes,
-the pointer leaves the event window, or the client calls
-.PN XQueryPointer
-or
-.PN XGetMotionEvents .
-The server still may send
-.PN MotionNotify
-events without is_hint set to
-.PN NotifyHint .
-.LP
-The source of the event is the viewable window that the pointer is in.
-The window used by the X server to report these events depends on 
-the window's position in the window hierarchy 
-and whether any intervening window prohibits the generation of these events.
-Starting with the source window, 
-the X server searches up the window hierarchy until it locates the first 
-window specified by a client as having an interest in these events.
-If one of the intervening windows has its do-not-propagate-mask
-set to prohibit generation of the event type,
-the events of those types will be suppressed.
-Clients can modify the actual window used for reporting by performing
-active grabs and, in the case of keyboard events, by using the focus window.
-.LP
-The structures for these event types contain:
-.LP
-.IN "XButtonEvent" "" "@DEF@"
-.IN "XButtonPressedEvent" "" "@DEF@"
-.IN "XButtonReleasedEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* ButtonPress or ButtonRelease */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window window;	/* ``event'' window it is reported relative to */
-	Window root;	/* root window that the event occurred on */
-	Window subwindow;	/* child window */
-	Time time;	/* milliseconds */
-	int x, y;	/* pointer x, y coordinates in event window */
-	int x_root, y_root;	/* coordinates relative to root */
-	unsigned int state;	/* key or button mask */
-	unsigned int button;	/* detail */
-	Bool same_screen;	/* same screen flag */
-} XButtonEvent;
-typedef XButtonEvent XButtonPressedEvent;
-typedef XButtonEvent XButtonReleasedEvent;
-.De
-.LP
-.IN "XKeyEvent" "" "@DEF@"
-.IN "XKeyPressedEvent" "" "@DEF@"
-.IN "XKeyReleasedEvent" "" "@DEF@"
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* KeyPress or KeyRelease */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window window;	/* ``event'' window it is reported relative to */
-	Window root;	/* root window that the event occurred on */
-	Window subwindow;	/* child window */
-	Time time;	/* milliseconds */
-	int x, y;	/* pointer x, y coordinates in event window */
-	int x_root, y_root;	/* coordinates relative to root */
-	unsigned int state;	/* key or button mask */
-	unsigned int keycode;	/* detail */
-	Bool same_screen;	/* same screen flag */
-} XKeyEvent;
-typedef XKeyEvent XKeyPressedEvent;
-typedef XKeyEvent XKeyReleasedEvent;
-.De
-.LP
-.IN "XMotionEvent" "" "@DEF@"
-.IN "XPointerMovedEvent" "" "@DEF@"
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* MotionNotify */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window window;	/* ``event'' window reported relative to */
-	Window root;	/* root window that the event occurred on */
-	Window subwindow;	/* child window */
-	Time time;	/* milliseconds */
-	int x, y;	/* pointer x, y coordinates in event window */
-	int x_root, y_root;	/* coordinates relative to root */
-	unsigned int state;	/* key or button mask */
-	char is_hint;	/* detail */
-	Bool same_screen;	/* same screen flag */
-} XMotionEvent;
-typedef XMotionEvent XPointerMovedEvent;
-.De
-.LP
-.eM
-These structures have the following common members:
-window, root, subwindow, time, x, y, x_root, y_root, state, and same_screen.
-The window member is set to the window on which the
-event was generated and is referred to as the event window. 
-As long as the conditions previously discussed are met,
-this is the window used by the X server to report the event.
-The root member is set to the source window's root window.
-The x_root and y_root members are set to the pointer's coordinates
-relative to the root window's origin at the time of the event.
-.LP
-The same_screen member is set to indicate whether the event 
-window is on the same screen
-as the root window and can be either
-.PN True 
-or
-.PN False .
-If
-.PN True ,
-the event and root windows are on the same screen.
-If
-.PN False ,
-the event and root windows are not on the same screen.
-.LP
-If the source window is an inferior of the event window, 
-the subwindow member of the structure is set to the child of the event window
-that is the source window or the child of the event window that is
-an ancestor of the source window.
-Otherwise, the X server sets the subwindow member to
-.PN None .
-The time member is set to the time when the event was generated 
-and is expressed in milliseconds.
-.LP
-If the event window is on the same screen as the root window, 
-the x and y members
-are set to the coordinates relative to the event window's origin.
-Otherwise, these members are set to zero.
-.LP
-The state member is set to indicate the logical state of the pointer buttons 
-and modifier keys just prior to the event,
-which is the bitwise inclusive OR of one or more of the
-button or modifier key masks:
-.PN Button1Mask ,
-.PN Button2Mask ,
-.PN Button3Mask ,
-.PN Button4Mask ,
-.PN Button5Mask ,
-.PN ShiftMask ,
-.PN LockMask ,
-.PN ControlMask ,
-.PN Mod1Mask ,
-.PN Mod2Mask ,
-.PN Mod3Mask ,
-.PN Mod4Mask ,
-and
-.PN Mod5Mask .
-.LP
-Each of these structures also has a member that indicates the detail.
-For the
-.PN XKeyPressedEvent
-and
-.PN XKeyReleasedEvent
-structures, this member is called a keycode.
-It is set to a number that represents a physical key on the keyboard.
-The keycode is an arbitrary representation for any key on the keyboard
-(see sections 12.7 and 16.1).
-.LP
-For the
-.PN XButtonPressedEvent
-and
-.PN XButtonReleasedEvent
-structures, this member is called button.
-It represents the pointer button that changed state and can be the
-.PN Button1 ,
-.PN Button2 ,
-.PN Button3 ,
-.PN Button4 ,
-or
-.PN Button5 
-value.
-For the
-.PN XPointerMovedEvent
-structure, this member is called is_hint.
-It can be set to 
-.PN NotifyNormal
-or
-.PN NotifyHint .
-.LP
-Some of the symbols mentioned in this section have fixed values, as
-follows:
-.TS H
-lw(2i) lw(3.5i).
-_
-.sp 6p
-.B
-Symbol	Value
-.sp 6p
-_
-.sp 6p
-.TH
-.R
-T{
-.PN Button1MotionMask
-T}	T{
-(1L<<8)
-T}
-T{
-.PN Button2MotionMask
-T}	T{
-(1L<<9)
-T}
-T{
-.PN Button3MotionMask
-T}	T{
-(1L<<10)
-T}
-T{
-.PN Button4MotionMask
-T}	T{
-(1L<<11)
-T}
-T{
-.PN Button5MotionMask
-T}	T{
-(1L<<12)
-T}
-T{
-.PN Button1Mask
-T}	T{
-(1<<8)
-T}
-T{
-.PN Button2Mask
-T}	T{
-(1<<9)
-T}
-T{
-.PN Button3Mask
-T}	T{
-(1<<10)
-T}
-T{
-.PN Button4Mask
-T}	T{
-(1<<11)
-T}
-T{
-.PN Button5Mask
-T}	T{
-(1<<12)
-T}
-T{
-.PN ShiftMask
-T}	T{
-(1<<0)
-T}
-T{
-.PN LockMask
-T}	T{
-(1<<1)
-T}
-T{
-.PN ControlMask
-T}	T{
-(1<<2)
-T}
-T{
-.PN Mod1Mask
-T}	T{
-(1<<3)
-T}
-T{
-.PN Mod2Mask
-T}	T{
-(1<<4)
-T}
-T{
-.PN Mod3Mask
-T}	T{
-(1<<5)
-T}
-T{
-.PN Mod4Mask
-T}	T{
-(1<<6)
-T}
-T{
-.PN Mod5Mask
-T}	T{
-(1<<7)
-T}
-T{
-.PN Button1
-T}	T{
-1
-T}
-T{
-.PN Button2
-T}	T{
-2
-T}
-T{
-.PN Button3
-T}	T{
-3
-T}
-T{
-.PN Button4
-T}	T{
-4
-T}
-T{
-.PN Button5
-T}	T{
-5
-T}
-.sp 6p
-_
-.TE
-.NH 2
-Window Entry/Exit Events
-.XS
-\*(SN Window Entry/Exit Events
-.XE
-.LP
-.IN "Events" "EnterNotify"
-.IN "Events" "LeaveNotify"
-This section describes the processing that 
-occurs for the window crossing events
-.PN EnterNotify
-and
-.PN LeaveNotify .
-.IN "EnterNotify" "" "@DEF@"
-.IN "LeaveNotify" "" "@DEF@"
-If a pointer motion or a window hierarchy change causes the
-pointer to be in a different window than before, the X server reports
-.PN EnterNotify
-or
-.PN LeaveNotify
-events to clients who have selected for these events.
-All 
-.PN EnterNotify
-and 
-.PN LeaveNotify
-events caused by a hierarchy change are
-generated after any hierarchy event
-.Pn ( UnmapNotify ,
-.PN MapNotify ,
-.PN ConfigureNotify ,
-.PN GravityNotify ,
-.PN CirculateNotify )
-caused by that change;
-however, the X protocol does not constrain the ordering of 
-.PN EnterNotify 
-and 
-.PN LeaveNotify 
-events with respect to
-.PN FocusOut , 
-.PN VisibilityNotify ,
-and 
-.PN Expose 
-events.
-.LP
-This contrasts with
-.PN MotionNotify
-events, which are also generated when the pointer moves
-but only when the pointer motion begins and ends in a single window.
-An
-.PN EnterNotify
-or
-.PN LeaveNotify
-event also can be generated when some client application calls
-.PN XGrabPointer
-and
-.PN XUngrabPointer .
-.LP
-To receive
-.PN EnterNotify
-or
-.PN LeaveNotify
-events, set the
-.PN EnterWindowMask
-or
-.PN LeaveWindowMask
-bits of the event-mask attribute of the window.
-.LP
-The structure for these event types contains:
-.LP
-.IN "XCrossingEvent" "" "@DEF@"
-.IN "XEnterWindowEvent" "" "@DEF@"
-.IN "XLeaveWindowEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* EnterNotify or LeaveNotify */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window window;	/* ``event'' window reported relative to */
-	Window root;	/* root window that the event occurred on */
-	Window subwindow;	/* child window */
-	Time time;	/* milliseconds */
-	int x, y;	/* pointer x, y coordinates in event window */
-	int x_root, y_root;	/* coordinates relative to root */
-	int mode;	/* NotifyNormal, NotifyGrab, NotifyUngrab */
-	int detail;
-		/*
-	 	* NotifyAncestor, NotifyVirtual, NotifyInferior, 
-	 	* NotifyNonlinear,NotifyNonlinearVirtual
-	 	*/
-	Bool same_screen;	/* same screen flag */
-	Bool focus;	/* boolean focus */
-	unsigned int state;	/* key or button mask */
-} XCrossingEvent;
-typedef XCrossingEvent XEnterWindowEvent;
-typedef XCrossingEvent XLeaveWindowEvent;
-.De
-.LP
-.eM
-The window member is set to the window on which the
-.PN EnterNotify
-or
-.PN LeaveNotify
-event was generated and is referred to as the event window. 
-This is the window used by the X server to report the event, 
-and is relative to the root
-window on which the event occurred. 
-The root member is set to the root window of the screen
-on which the event occurred.
-.LP
-For a
-.PN LeaveNotify 
-event,
-if a child of the event window contains the initial position of the pointer,
-the subwindow component is set to that child.
-Otherwise, the X server sets the subwindow member to
-.PN None .
-For an
-.PN EnterNotify 
-event, if a child of the event window contains the final pointer position, 
-the subwindow component is set to that child or
-.PN None .
-.LP
-The time member is set to the time when the event was generated
-and is expressed in milliseconds.
-The x and y members are set to the coordinates of the pointer position in 
-the event window.
-This position is always the pointer's final position,
-not its initial position.
-If the event window is on the same
-screen as the root window, x and y are the pointer coordinates
-relative to the event window's origin. 
-Otherwise, x and y are set to zero.
-The x_root and y_root members are set to the pointer's coordinates relative to the
-root window's origin at the time of the event.
-.LP
-The same_screen member is set to indicate whether the event window is on the same screen
-as the root window and can be either
-.PN True 
-or
-.PN False .
-If
-.PN True ,
-the event and root windows are on the same screen.
-If
-.PN False ,
-the event and root windows are not on the same screen.
-.LP
-The focus member is set to indicate whether the event window is the focus window or an
-inferior of the focus window.
-The X server can set this member to either
-.PN True 
-or
-.PN False .
-If
-.PN True ,
-the event window is the focus window or an inferior of the focus window.
-If
-.PN False ,
-the event window is not the focus window or an inferior of the focus window.
-.LP
-The state member is set to indicate the state of the pointer buttons and
-modifier keys just prior to the
-event.
-The X server can set this member to the bitwise inclusive OR of one 
-or more of the button or modifier key masks:
-.PN Button1Mask ,
-.PN Button2Mask ,
-.PN Button3Mask ,
-.PN Button4Mask ,
-.PN Button5Mask ,
-.PN ShiftMask ,
-.PN LockMask ,
-.PN ControlMask ,
-.PN Mod1Mask ,
-.PN Mod2Mask ,
-.PN Mod3Mask ,
-.PN Mod4Mask ,
-.PN Mod5Mask .
-.LP
-The mode member is set to indicate whether the events are normal events, 
-pseudo-motion events
-when a grab activates, or pseudo-motion events when a grab deactivates.
-The X server can set this member to 
-.PN NotifyNormal ,
-.PN NotifyGrab ,
-or
-.PN NotifyUngrab .
-.LP
-The detail member is set to indicate the notify detail and can be
-.PN NotifyAncestor ,
-.PN NotifyVirtual ,
-.PN NotifyInferior ,
-.PN NotifyNonlinear ,
-or
-.PN NotifyNonlinearVirtual .
-.NH 3 
-Normal Entry/Exit Events
-.XS
-\*(SN Normal Entry/Exit Events
-.XE
-.LP
-.PN EnterNotify
-and
-.PN LeaveNotify
-events are generated when the pointer moves from
-one window to another window.
-Normal events are identified by
-.PN XEnterWindowEvent
-or
-.PN XLeaveWindowEvent
-structures whose mode member is set to
-.PN NotifyNormal .
-.IP \(bu 5
-When the pointer moves from window A to window B and A is an inferior of B, 
-the X server does the following:
-.RS
-.IP \- 5
-It generates a
-.PN LeaveNotify
-event on window A, with the detail member of the
-.PN XLeaveWindowEvent
-structure set to
-.PN NotifyAncestor .
-.IP \- 5
-It generates a
-.PN LeaveNotify
-event on each window between window A and window B, exclusive,
-with the detail member of each
-.PN XLeaveWindowEvent
-structure set to
-.PN NotifyVirtual .
-.IP \- 5
-It generates an
-.PN EnterNotify
-event on window B, with the detail member of the 
-.PN XEnterWindowEvent
-structure set to
-.PN NotifyInferior .
-.RE
-.IP \(bu 5
-When the pointer moves from window A to window B and B is an inferior of A,
-the X server does the following:
-.RS
-.IP \- 5
-It generates a
-.PN LeaveNotify
-event on window A,
-with the detail member of the
-.PN XLeaveWindowEvent
-structure set to
-.PN NotifyInferior .
-.IP \- 5
-It generates an
-.PN EnterNotify
-event on each window between window A and window B, exclusive, with the 
-detail member of each 
-.PN XEnterWindowEvent
-structure set to
-.PN NotifyVirtual . 
-.IP \- 5
-It generates an
-.PN EnterNotify
-event on window B, with the detail member of the 
-.PN XEnterWindowEvent
-structure set to
-.PN NotifyAncestor .
-.RE
-.IP \(bu 5
-When the pointer moves from window A to window B 
-and window C is their least common ancestor, 
-the X server does the following:
-.RS
-.IP \- 5
-It generates a
-.PN LeaveNotify
-event on window A,
-with the detail member of the
-.PN XLeaveWindowEvent
-structure set to 
-.PN NotifyNonlinear .
-.IP \- 5
-It generates a
-.PN LeaveNotify
-event on each window between window A and window C, exclusive,
-with the detail member of each
-.PN XLeaveWindowEvent
-structure set to
-.PN NotifyNonlinearVirtual .
-.IP \- 5
-It generates an
-.PN EnterNotify
-event on each window between window C and window B, exclusive, 
-with the detail member of each
-.PN XEnterWindowEvent
-structure set to
-.PN NotifyNonlinearVirtual .
-.IP \- 5
-It generates an
-.PN EnterNotify
-event on window B, with the detail member of the 
-.PN XEnterWindowEvent
-structure set to 
-.PN NotifyNonlinear .
-.RE
-.IP \(bu 5
-When the pointer moves from window A to window B on different screens, 
-the X server does the following:
-.RS
-.IP \- 5
-It generates a
-.PN LeaveNotify
-event on window A,
-with the detail member of the
-.PN XLeaveWindowEvent
-structure set to 
-.PN NotifyNonlinear .
-.IP \- 5
-If window A is not a root window,
-it generates a
-.PN LeaveNotify
-event on each window above window A up to and including its root,
-with the detail member of each
-.PN XLeaveWindowEvent
-structure set to 
-.PN NotifyNonlinearVirtual .
-.IP \- 5
-If window B is not a root window,
-it generates an
-.PN EnterNotify
-event on each window from window B's root down to but not including
-window B, with the detail member of each
-.PN XEnterWindowEvent
-structure set to 
-.PN NotifyNonlinearVirtual .
-.IP \- 5
-It generates an
-.PN EnterNotify
-event on window B, with the detail member of the
-.PN XEnterWindowEvent
-structure set to 
-.PN NotifyNonlinear .
-.RE
-.\".SH 3
-.NH 3 
-Grab and Ungrab Entry/Exit Events
-.XS
-\*(SN Grab and Ungrab Entry/Exit Events
-.XE
-.LP
-Pseudo-motion mode
-.PN EnterNotify
-and
-.PN LeaveNotify
-events are generated when a pointer grab activates or deactivates.
-Events in which the pointer grab activates
-are identified by
-.PN XEnterWindowEvent
-or
-.PN XLeaveWindowEvent
-structures whose mode member is set to 
-.PN NotifyGrab .
-Events in which the pointer grab deactivates
-are identified by
-.PN XEnterWindowEvent
-or
-.PN XLeaveWindowEvent
-structures whose mode member is set to 
-.PN NotifyUngrab
-(see
-.PN XGrabPointer ).
-.IP \(bu 5
-When a pointer grab activates after any initial warp into a confine_to
-window and before generating any actual
-.PN ButtonPress
-event that activates the grab, 
-G is the grab_window for the grab, 
-and P is the window the pointer is in, 
-the X server does the following:
-.RS
-.IP \- 5
-It generates
-.PN EnterNotify
-and
-.PN LeaveNotify
-events (see section 10.6.1)
-with the mode members of the 
-.PN XEnterWindowEvent
-and
-.PN XLeaveWindowEvent
-structures set to 
-.PN NotifyGrab .
-These events are generated
-as if the pointer were to suddenly warp from
-its current position in P to some position in G.
-However, the pointer does not warp, and the X server uses the pointer position 
-as both the initial and final positions for the events.
-.RE
-.IP \(bu 5
-When a pointer grab deactivates after generating any actual
-.PN ButtonRelease
-event that deactivates the grab, 
-G is the grab_window for the grab,
-and P is the window the pointer is in, 
-the X server does the following:
-.RS
-.IP \- 5
-It generates
-.PN EnterNotify
-and
-.PN LeaveNotify
-events (see section 10.6.1)
-with the mode members of the
-.PN XEnterWindowEvent
-and
-.PN XLeaveWindowEvent
-structures set to 
-.PN NotifyUngrab .
-These events are generated as if the pointer were to suddenly warp from
-some position in G to its current position in P.
-However, the pointer does not warp, and the X server uses the
-current pointer position as both the
-initial and final positions for the events.
-.RE
-.NH 2
-Input Focus Events
-.XS
-\*(SN Input Focus Events 
-.XE
-.LP
-.IN "Events" "FocusIn"
-.IN "Events" "FocusOut"
-This section describes the processing that occurs for the input focus events
-.PN FocusIn
-and
-.PN FocusOut .
-.IN "FocusIn" "" "@DEF@"
-.IN "FocusOut" "" "@DEF@"
-The X server can report
-.PN FocusIn
-or
-.PN FocusOut
-events to clients wanting information about when the input focus changes.
-The keyboard is always attached to some window 
-(typically, the root window or a top-level window), 
-which is called the focus window.
-The focus window and the position of the pointer determine the window that
-receives keyboard input.
-Clients may need to know when the input focus changes
-to control highlighting of areas on the screen.
-.LP
-To receive
-.PN FocusIn
-or
-.PN FocusOut
-events, set the
-.PN FocusChangeMask
-bit in the event-mask attribute of the window. 
-.LP
-The structure for these event types contains:
-.LP
-.IN "XFocusChangeEvent" "" "@DEF@"
-.IN "XFocusInEvent" "" "@DEF@"
-.IN "XFocusOutEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* FocusIn or FocusOut */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window window;	/* window of event */
-	int mode;	/* NotifyNormal, NotifyGrab, NotifyUngrab */
-	int detail;
-		/*
-	 	* NotifyAncestor, NotifyVirtual, NotifyInferior, 
-	 	* NotifyNonlinear,NotifyNonlinearVirtual, NotifyPointer,
-	 	* NotifyPointerRoot, NotifyDetailNone 
-	 	*/
-} XFocusChangeEvent;
-typedef XFocusChangeEvent XFocusInEvent;
-typedef XFocusChangeEvent XFocusOutEvent;
-.De
-.LP
-.eM
-The window member is set to the window on which the
-.PN FocusIn
-or
-.PN FocusOut
-event was generated.
-This is the window used by the X server to report the event. 
-The mode member is set to indicate whether the focus events 
-are normal focus events, 
-focus events while grabbed,
-focus events
-when a grab activates, or focus events when a grab deactivates.
-The X server can set the mode member to 
-.PN NotifyNormal ,
-.PN NotifyWhileGrabbed ,
-.PN NotifyGrab ,
-or
-.PN NotifyUngrab .
-.LP
-All 
-.PN FocusOut
-events caused by a window unmap are generated after any
-.PN UnmapNotify
-event; however, the X protocol does not constrain the ordering of 
-.PN FocusOut
-events with respect to
-generated 
-.PN EnterNotify ,
-.PN LeaveNotify ,
-.PN VisibilityNotify ,
-and
-.PN Expose
-events.
-.LP
-Depending on the event mode,
-the detail member is set to indicate the notify detail and can be
-.PN NotifyAncestor ,
-.PN NotifyVirtual ,
-.PN NotifyInferior ,
-.PN NotifyNonlinear ,
-.PN NotifyNonlinearVirtual ,
-.PN NotifyPointer ,
-.PN NotifyPointerRoot ,
-or
-.PN NotifyDetailNone .
-.NH 3 
-Normal Focus Events and Focus Events While Grabbed 
-.XS
-\*(SN Normal Focus Events and Focus Events While Grabbed 
-.XE
-.LP
-Normal focus events are identified by
-.PN XFocusInEvent
-or
-.PN XFocusOutEvent
-structures whose mode member is set to 
-.PN NotifyNormal .
-Focus events while grabbed are identified by
-.PN XFocusInEvent
-or
-.PN XFocusOutEvent
-structures whose mode member is set to 
-.PN NotifyWhileGrabbed .
-The X server processes normal focus and focus events while grabbed according to 
-the following:
-.IP \(bu 5
-When the focus moves from window A to window B, A is an inferior of B, 
-and the pointer is in window P, 
-the X server does the following:
-.RS
-.IP \- 5
-It generates a
-.PN FocusOut
-event on window A, with the detail member of the
-.PN XFocusOutEvent
-structure set to 
-.PN NotifyAncestor . 
-.IP \- 5
-It generates a
-.PN FocusOut
-event on each window between window A and window B, exclusive,
-with the detail member of each
-.PN XFocusOutEvent
-structure set to 
-.PN NotifyVirtual .
-.IP \- 5
-It generates a
-.PN FocusIn
-event on window B, with the detail member of the 
-.PN XFocusOutEvent
-structure set to 
-.PN NotifyInferior .
-.IP \- 5
-If window P is an inferior of window B
-but window P is not window A or an inferior or ancestor of window A,
-it generates a
-.PN FocusIn
-event on each window below window B, down to and including window P, 
-with the detail member of each 
-.PN XFocusInEvent
-structure set to 
-.PN NotifyPointer .
-.RE
-.IP \(bu 5
-When the focus moves from window A to window B, B is an inferior of A, 
-and the pointer is in window P, 
-the X server does the following:
-.RS
-.IP \- 5
-If window P is an inferior of window A
-but P is not an inferior of window B or an ancestor of B,
-it generates a
-.PN FocusOut
-event on each window from window P up to but not including window A,
-with the detail member of each 
-.PN XFocusOutEvent
-structure set to  
-.PN NotifyPointer .
-.IP \- 5
-It generates a
-.PN FocusOut
-event on window A,
-with the detail member of the
-.PN XFocusOutEvent
-structure set to  
-.PN NotifyInferior . 
-.IP \- 5
-It generates a
-.PN FocusIn
-event on each window between window A and window B, exclusive, with the 
-detail member of each 
-.PN XFocusInEvent
-structure set to  
-.PN NotifyVirtual . 
-.IP \- 5
-It generates a
-.PN FocusIn
-event on window B, with the detail member of the 
-.PN XFocusInEvent
-structure set to  
-.PN NotifyAncestor .
-.RE
-.IP \(bu 5
-When the focus moves from window A to window B, 
-window C is their least common ancestor, 
-and the pointer is in window P, 
-the X server does the following:
-.RS
-.IP \- 5
-If window P is an inferior of window A,
-it generates a
-.PN FocusOut
-event on each window from window P up to but not including window A, 
-with the detail member of the 
-.PN XFocusOutEvent
-structure set to  
-.PN NotifyPointer .
-.IP \- 5
-It generates a
-.PN FocusOut
-event on window A,
-with the detail member of the
-.PN XFocusOutEvent
-structure set to  
-.PN NotifyNonlinear .
-.IP \- 5
-It generates a
-.PN FocusOut
-event on each window between window A and window C, exclusive,
-with the detail member of each
-.PN XFocusOutEvent
-structure set to  
-.PN NotifyNonlinearVirtual .
-.IP \- 5
-It generates a
-.PN FocusIn
-event on each window between C and B, exclusive,
-with the detail member of each
-.PN XFocusInEvent
-structure set to  
-.PN NotifyNonlinearVirtual .
-.IP \- 5
-It generates a
-.PN FocusIn
-event on window B, with the detail member of the 
-.PN XFocusInEvent
-structure set to  
-.PN NotifyNonlinear .
-.IP \- 5
-If window P is an inferior of window B, it generates a
-.PN FocusIn
-event on each window below window B down to and including window P, 
-with the detail member of the 
-.PN XFocusInEvent
-structure set to  
-.PN NotifyPointer .
-.RE
-.IP \(bu 5
-When the focus moves from window A to window B on different screens 
-and the pointer is in window P, 
-the X server does the following:
-.RS
-.IP \- 5
-If window P is an inferior of window A, it generates a
-.PN FocusOut
-event on each window from window P up to but not including window A, 
-with the detail member of each 
-.PN XFocusOutEvent
-structure set to  
-.PN NotifyPointer .
-.IP \- 5
-It generates a
-.PN FocusOut
-event on window A,
-with the detail member of the
-.PN XFocusOutEvent
-structure set to  
-.PN NotifyNonlinear .
-.IP \- 5
-If window A is not a root window,
-it generates a
-.PN FocusOut
-event on each window above window A up to and including its root, 
-with the detail member of each
-.PN XFocusOutEvent
-structure set to  
-.PN NotifyNonlinearVirtual .
-.IP \- 5
-If window B is not a root window,
-it generates a
-.PN FocusIn
-event on each window from window B's root down to but not including
-window B, with the detail member of each
-.PN XFocusInEvent
-structure set to  
-.PN NotifyNonlinearVirtual .
-.IP \- 5
-It generates a
-.PN FocusIn
-event on window B, with the detail member of each 
-.PN XFocusInEvent
-structure set to  
-.PN NotifyNonlinear .
-.IP \- 5
-If window P is an inferior of window B, it generates a
-.PN FocusIn
-event on each window below window B down to and including window P, 
-with the detail member of each 
-.PN XFocusInEvent
-structure set to  
-.PN NotifyPointer .
-.RE
-.IP \(bu 5
-When the focus moves from window A to 
-.PN PointerRoot
-(events sent to the window under the pointer)
-or
-.PN None 
-(discard), and the pointer is in window P,
-the X server does the following:
-.RS
-.IP \- 5
-If window P is an inferior of window A, it generates a
-.PN FocusOut
-event on each window from window P up to but not including window A, 
-with the detail member of each 
-.PN XFocusOutEvent
-structure set to  
-.PN NotifyPointer .
-.IP \- 5
-It generates a
-.PN FocusOut
-event on window A, with the detail member of the
-.PN XFocusOutEvent
-structure set to
-.PN NotifyNonlinear .
-.IP \- 5
-If window A is not a root window,
-it generates a
-.PN FocusOut
-event on each window above window A up to and including its root, 
-with the detail member of each
-.PN XFocusOutEvent
-structure set to
-.PN NotifyNonlinearVirtual .
-.IP \- 5
-It generates a
-.PN FocusIn
-event on the root window of all screens, with the detail member of each
-.PN XFocusInEvent
-structure set to
-.PN NotifyPointerRoot
-(or
-.PN NotifyDetailNone ).
-.IP \- 5
-If the new focus is
-.PN PointerRoot ,
-it generates a
-.PN FocusIn
-event on each window from window P's root down to and including window P, 
-with the detail member of each
-.PN XFocusInEvent
-structure set to
-.PN NotifyPointer .
-.RE
-.IP \(bu 5
-When the focus moves from 
-.PN PointerRoot
-(events sent to the window under the pointer)
-or
-.PN None 
-to window A, and the pointer is in window P, 
-the X server does the following: 
-.RS
-.IP \- 5
-If the old focus is
-.PN PointerRoot ,
-it generates a
-.PN FocusOut
-event on each window from window P up to and including window P's root, 
-with the detail member of each
-.PN XFocusOutEvent
-structure set to
-.PN NotifyPointer .
-.IP \- 5
-It generates a
-.PN FocusOut
-event on all root windows,
-with the detail member of each
-.PN XFocusOutEvent
-structure set to
-.PN NotifyPointerRoot
-(or
-.PN NotifyDetailNone ).
-.IP \- 5
-If window A is not a root window,
-it generates a
-.PN FocusIn
-event on each window from window A's root down to but not including window A,
-with the detail member of each
-.PN XFocusInEvent
-structure set to
-.PN NotifyNonlinearVirtual .
-.IP \- 5
-It generates a
-.PN FocusIn
-event on window A,
-with the detail member of the 
-.PN XFocusInEvent
-structure set to  
-.PN NotifyNonlinear .
-.IP \- 5
-If window P is an inferior of window A, it generates a
-.PN FocusIn
-event on each window below window A down to and including window P, 
-with the detail member of each 
-.PN XFocusInEvent
-structure set to  
-.PN NotifyPointer .
-.RE
-.IP \(bu 5
-When the focus moves from 
-.PN PointerRoot
-(events sent to the window under the pointer)
-to
-.PN None
-(or vice versa), and the pointer is in window P, 
-the X server does the following:
-.RS
-.IP \- 5
-If the old focus is
-.PN PointerRoot ,
-it generates a
-.PN FocusOut
-event on each window from window P up to and including window P's root, 
-with the detail member of each
-.PN XFocusOutEvent
-structure set to
-.PN NotifyPointer .
-.IP \- 5
-It generates a
-.PN FocusOut
-event on all root windows,
-with the detail member of each 
-.PN XFocusOutEvent
-structure set to either
-.PN NotifyPointerRoot
-or
-.PN NotifyDetailNone . 
-.IP \- 5
-It generates a
-.PN FocusIn
-event on all root windows,
-with the detail member of each
-.PN XFocusInEvent
-structure set to
-.PN NotifyDetailNone 
-or
-.PN NotifyPointerRoot .
-.IP \- 5
-If the new focus is
-.PN PointerRoot ,
-it generates a
-.PN FocusIn
-event on each window from window P's root down to and including window P, 
-with the detail member of each
-.PN XFocusInEvent
-structure set to
-.PN NotifyPointer .
-.RE
-.\".SH 3
-.NH 3 
-Focus Events Generated by Grabs
-.XS
-\*(SN Focus Events Generated by Grabs 
-.XE
-.LP
-Focus events in which the keyboard grab activates
-are identified by
-.PN XFocusInEvent
-or
-.PN XFocusOutEvent
-structures whose mode member is set to 
-.PN NotifyGrab .
-Focus events in which the keyboard grab deactivates
-are identified by
-.PN XFocusInEvent
-or
-.PN XFocusOutEvent
-structures whose mode member is set to 
-.PN NotifyUngrab 
-(see 
-.PN XGrabKeyboard ).
-.IP \(bu 5
-When a keyboard grab activates before generating any actual 
-.PN KeyPress
-event that activates the grab,
-G is the grab_window, and F is the current focus, 
-the X server does the following:
-.RS
-.IP \- 5
-It generates 
-.PN FocusIn
-and
-.PN FocusOut
-events, with the mode members of the 
-.PN XFocusInEvent
-and
-.PN XFocusOutEvent
-structures set to 
-.PN NotifyGrab .
-These events are generated
-as if the focus were to change from
-F to G.
-.RE
-.IP \(bu 5
-When a keyboard grab deactivates after generating any actual
-.PN KeyRelease
-event that deactivates the grab,
-G is the grab_window, and F is the current focus,
-the X server does the following:
-.RS
-.IP \- 5
-It generates 
-.PN FocusIn
-and
-.PN FocusOut
-events, with the mode members of the 
-.PN XFocusInEvent
-and
-.PN XFocusOutEvent
-structures set to
-.PN NotifyUngrab .
-These events are generated
-as if the focus were to change from
-G to F.
-.RE
-.NH 2
-Key Map State Notification Events
-.XS
-\*(SN Key Map State Notification Events
-.XE
-.LP
-.IN "Events" "KeymapNotify"
-.IN "KeymapNotify" "" "@DEF@"
-The X server can report
-.PN KeymapNotify
-events to clients that want information about changes in their keyboard state.
-.LP
-To receive
-.PN KeymapNotify
-events, set the
-.PN KeymapStateMask
-bit in the event-mask attribute of the window. 
-The X server generates this event immediately after every
-.PN EnterNotify
-and
-.PN FocusIn
-event.
-.LP
-The structure for this event type contains:
-.LP
-.IN "XKeymapEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-/* generated on EnterWindow and FocusIn when KeymapState selected */
-typedef struct {
-	int type;	/* KeymapNotify */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window window;
-	char key_vector[32];
-} XKeymapEvent;	
-.De
-.LP
-.eM
-The window member is not used but is present to aid some toolkits.
-The key_vector member is set to the bit vector of the keyboard.
-Each bit set to 1 indicates that the corresponding key 
-is currently pressed.
-The vector is represented as 32 bytes.
-Byte N (from 0) contains the bits for keys 8N to 8N + 7 
-with the least significant bit in the byte representing key 8N.
-.NH 2
-Exposure Events
-.XS
-\*(SN Exposure Events
-.XE
-.LP
-The X protocol does not guarantee to preserve the contents of window 
-regions when
-the windows are obscured or reconfigured.
-Some implementations may preserve the contents of windows.
-Other implementations are free to destroy the contents of windows
-when exposed.
-X expects client applications to assume the responsibility for
-restoring the contents of an exposed window region. 
-(An exposed window region describes a formerly obscured window whose 
-region becomes visible.) 
-Therefore, the X server sends 
-.PN Expose 
-events describing the window and the region of the window that has been exposed.
-A naive client application usually redraws the entire window. 
-A more sophisticated client application redraws only the exposed region.
-.NH 3
-Expose Events
-.XS
-\*(SN Expose Events
-.XE
-.LP
-.IN "Events" "Expose"
-.IN "Expose" "" "@DEF@"
-The X server can report
-.PN Expose
-events to clients wanting information about when the contents of window regions
-have been lost.
-The circumstances in which the X server generates
-.PN Expose
-events are not as definite as those for other events.
-However, the X server never generates
-.PN Expose
-events on windows whose class you specified as
-.PN InputOnly .
-The X server can generate
-.PN Expose
-events when no valid contents are available for regions of a window
-and either the regions are visible, 
-the regions are viewable and the server is (perhaps newly) maintaining 
-backing store on the window,
-or the window is not viewable but the server is (perhaps newly) honoring the
-window's backing-store attribute of
-.PN Always
-or
-.PN WhenMapped .
-The regions decompose into an (arbitrary) set of rectangles,
-and an
-.PN Expose
-event is generated for each rectangle.
-For any given window,
-the X server guarantees to report contiguously 
-all of the regions exposed by some action that causes 
-.PN Expose 
-events, such as raising a window.
-.LP
-To receive
-.PN Expose
-events, set the
-.PN ExposureMask
-bit in the event-mask attribute of the window. 
-.LP
-The structure for this event type contains:
-.LP
-.IN "XExposeEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* Expose */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window window;
-	int x, y;
-	int width, height;
-	int count;	/* if nonzero, at least this many more */
-} XExposeEvent;
-.De
-.LP
-.eM
-The window member is set to the exposed (damaged) window.
-The x and y members are set to the coordinates relative to the window's origin
-and indicate the upper-left corner of the rectangle.
-The width and height members are set to the size (extent) of the rectangle.
-The count member is set to the number of
-.PN Expose
-events that are to follow.
-If count is zero, no more
-.PN Expose
-events follow for this window.
-However, if count is nonzero, at least that number of 
-.PN Expose 
-events (and possibly more) follow for this window.
-Simple applications that do not want to optimize redisplay by distinguishing
-between subareas of its window can just ignore all
-.PN Expose
-events with nonzero counts and perform full redisplays
-on events with zero counts.
-.NH 3
-GraphicsExpose and NoExpose Events
-.XS
-\*(SN GraphicsExpose and NoExpose Events
-.XE
-.LP
-.IN "Events" "GraphicsExpose"
-.IN "Events" "NoExpose"
-.IN "GraphicsExpose" "" "@DEF@"
-The X server can report
-.PN GraphicsExpose
-events to clients wanting information about when a destination region could not
-be computed during certain graphics requests:
-.PN XCopyArea
-or
-.PN XCopyPlane .
-The X server generates this event whenever a destination region could not be
-computed because of an obscured or out-of-bounds source region.
-In addition, the X server guarantees to report contiguously all of the regions exposed by
-some graphics request 
-(for example, copying an area of a drawable to a destination
-drawable).
-.LP
-.IN "NoExpose" "" "@DEF@"
-The X server generates a
-.PN NoExpose
-event whenever a graphics request that might
-produce a
-.PN GraphicsExpose
-event does not produce any.
-In other words, the client is really asking for a
-.PN GraphicsExpose
-event but instead receives a
-.PN NoExpose
-event.
-.LP
-To receive
-.PN GraphicsExpose
-or
-.PN NoExpose
-events, you must first set the graphics-exposure 
-attribute of the graphics context to
-.PN True .
-You also can set the graphics-expose attribute when creating a graphics
-context using
-.PN XCreateGC 
-or by calling
-.PN XSetGraphicsExposures .
-.LP
-The structures for these event types contain:
-.LP
-.IN "XGraphicsExposeEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* GraphicsExpose */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Drawable drawable;
-	int x, y;
-	int width, height;
-	int count;	/* if nonzero, at least this many more */
-	int major_code;	/* core is CopyArea or CopyPlane */
-	int minor_code;	/* not defined in the core */
-} XGraphicsExposeEvent;
-.De
-.LP
-.IN "XNoExposeEvent" "" "@DEF@"
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* NoExpose */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Drawable drawable;
-	int major_code;	/* core is CopyArea or CopyPlane */
-	int minor_code;	/* not defined in the core */
-} XNoExposeEvent;
-.De
-.LP
-.eM
-Both structures have these common members: drawable, major_code, and minor_code.
-The drawable member is set to the drawable of the destination region on 
-which the graphics request was to be performed.
-The major_code member is set to the graphics request initiated by the client
-and can be either
-.PN X_CopyArea
-or
-.PN X_CopyPlane .
-If it is
-.PN X_CopyArea ,
-a call to
-.PN XCopyArea
-initiated the request.
-If it is
-.PN X_CopyPlane ,
-a call to
-.PN XCopyPlane
-initiated the request.
-These constants are defined in 
-.hN X11/Xproto.h .
-The minor_code member,
-like the major_code member, 
-indicates which graphics request was initiated by
-the client. 
-However, the minor_code member is not defined by the core
-X protocol and will be zero in these cases, 
-although it may be used by an extension.
-.LP
-The 
-.PN XGraphicsExposeEvent
-structure has these additional members: x, y, width, height, and count. 
-The x and y members are set to the coordinates relative to the drawable's origin
-and indicate the upper-left corner of the rectangle.
-The width and height members are set to the size (extent) of the rectangle.
-The count member is set to the number of
-.PN GraphicsExpose
-events to follow.
-If count is zero, no more
-.PN GraphicsExpose
-events follow for this window.
-However, if count is nonzero, at least that number of
-.PN GraphicsExpose
-events (and possibly more) are to follow for this window.
-.NH 2
-Window State Change Events 
-.XS
-\*(SN Window State Change Events
-.XE
-.LP
-The following sections discuss:
-.IP \(bu 5
-.PN CirculateNotify
-events
-.IP \(bu 5
-.PN ConfigureNotify
-events
-.IP \(bu 5
-.PN CreateNotify 
-events
-.IP \(bu 5
-.PN DestroyNotify
-events
-.IP \(bu 5
-.PN GravityNotify
-events
-.IP \(bu 5
-.PN MapNotify
-events
-.IP \(bu 5
-.PN MappingNotify
-events
-.IP \(bu 5
-.PN ReparentNotify 
-events
-.IP \(bu 5
-.PN UnmapNotify
-events
-.IP \(bu 5
-.PN VisibilityNotify
-events
-.\" .SH 3
-.NH 3
-CirculateNotify Events
-.XS
-\*(SN CirculateNotify Events
-.XE
-.LP
-.IN "Events" "CirculateNotify"
-.IN "CirculateNotify" "" "@DEF@"
-The X server can report
-.PN CirculateNotify
-events to clients wanting information about when a window changes 
-its position in the stack.
-The X server generates this event type whenever a window is actually restacked 
-as a result of a client application calling
-.PN XCirculateSubwindows ,
-.PN XCirculateSubwindowsUp ,
-or
-.PN XCirculateSubwindowsDown .
-.LP
-To receive 
-.PN CirculateNotify
-events, set the
-.PN StructureNotifyMask
-bit in the event-mask attribute of the window
-or the
-.PN SubstructureNotifyMask
-bit in the event-mask attribute of the parent window
-(in which case, circulating any child generates an event).
-.LP
-The structure for this event type contains:
-.LP
-.IN "XCirculateEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* CirculateNotify */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window event;
-	Window window;
-	int place;	/* PlaceOnTop, PlaceOnBottom */
-} XCirculateEvent;
-.De
-.LP
-.eM
-The event member is set either to the restacked window or to its parent,
-depending on whether
-.PN StructureNotify
-or
-.PN SubstructureNotify
-was selected.
-The window member is set to the window that was restacked.
-The place member is set to the window's position after the restack occurs and
-is either
-.PN PlaceOnTop
-or
-.PN PlaceOnBottom .
-If it is
-.PN PlaceOnTop ,
-the window is now on top of all siblings.
-If it is
-.PN PlaceOnBottom ,
-the window is now below all siblings.
-.NH 3
-ConfigureNotify Events
-.XS
-\*(SN ConfigureNotify Events
-.XE
-.LP
-.IN "Events" "ConfigureNotify"
-.IN "ConfigureNotify" "" "@DEF@"
-The X server can report
-.PN ConfigureNotify
-events to clients wanting information about actual changes to a window's
-state, such as size, position, border, and stacking order.
-The X server generates this event type whenever one of the following configure 
-window requests made by a client application actually completes:
-.IP \(bu 5
-A window's size, position, border, and/or stacking order is reconfigured 
-by calling
-.PN XConfigureWindow .
-.IP \(bu 5
-The window's position in the stacking order is changed by calling
-.PN XLowerWindow ,
-.PN XRaiseWindow ,
-or
-.PN XRestackWindows .
-.IP \(bu 5
-A window is moved by calling
-.PN XMoveWindow .
-.IP \(bu 5
-A window's size is changed by calling
-.PN XResizeWindow .
-.IP \(bu 5
-A window's size and location is changed by calling
-.PN XMoveResizeWindow .
-.IP \(bu 5
-A window is mapped and its position in the stacking order is changed
-by calling
-.PN XMapRaised .
-.IP \(bu 5
-A window's border width is changed by calling
-.PN XSetWindowBorderWidth .
-.LP
-To receive 
-.PN ConfigureNotify
-events, set the
-.PN StructureNotifyMask
-bit in the event-mask attribute of the window or the
-.PN SubstructureNotifyMask
-bit in the event-mask attribute of the parent window
-(in which case, configuring any child generates an event).
-.LP
-The structure for this event type contains:
-.LP
-.IN "XConfigureEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* ConfigureNotify */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window event;
-	Window window;
-	int x, y;
-	int width, height;
-	int border_width;
-	Window above;
-	Bool override_redirect;
-} XConfigureEvent;
-.De
-.LP
-.eM
-The event member is set either to the reconfigured window or to its parent,
-depending on whether
-.PN StructureNotify
-or
-.PN SubstructureNotify
-was selected.
-The window member is set to the window whose size, position, 
-border, and/or stacking
-order was changed.
-.LP
-The x and y members are set to the coordinates relative to the parent window's 
-origin and indicate the position of the upper-left outside corner of the window.
-The width and height members are set to the inside size of the window, 
-not including
-the border.
-The border_width member is set to the width of the window's border, in pixels.
-.LP
-The above member is set to the sibling window and is used 
-for stacking operations.
-If the X server sets this member to
-.PN None ,
-the window whose state was changed is on the bottom of the stack
-with respect to sibling windows.
-However, if this member is set to a sibling window, 
-the window whose state was changed is placed on top of this sibling window.
-.LP
-The override_redirect member is set to the override-redirect attribute of the
-window.
-Window manager clients normally should ignore this window if the 
-override_redirect member
-is
-.PN True .
-.NH 3
-CreateNotify Events
-.XS
-\*(SN CreateNotify Events
-.XE
-.LP
-.IN "Events" "CreateNotify"
-.IN "CreateNotify" "" "@DEF@"
-The X server can report
-.PN CreateNotify
-events to clients wanting information about creation of windows.
-The X server generates this event whenever a client
-application creates a window by calling
-.PN XCreateWindow
-or
-.PN XCreateSimpleWindow .
-.LP
-To receive 
-.PN CreateNotify
-events, set the
-.PN SubstructureNotifyMask
-bit in the event-mask attribute of the window.
-Creating any children then generates an event.
-.LP
-The structure for the event type contains:
-.LP
-.IN "XCreateWindowEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* CreateNotify */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window parent;	/* parent of the window */
-	Window window;	/* window id of window created */
-	int x, y;	/* window location */
-	int width, height;	/* size of window */
-	int border_width;	/* border width */
-	Bool override_redirect;	/* creation should be overridden */
-} XCreateWindowEvent;
-.De
-.LP
-.eM
-The parent member is set to the created window's parent.
-The window member specifies the created window.
-The x and y members are set to the created window's coordinates relative 
-to the parent window's origin and indicate the position of the upper-left 
-outside corner of the created window.
-The width and height members are set to the inside size of the created window 
-(not including the border) and are always nonzero.
-The border_width member is set to the width of the created window's border, in pixels.
-The override_redirect member is set to the override-redirect attribute of the
-window.
-Window manager clients normally should ignore this window 
-if the override_redirect member is
-.PN True .
-.NH 3
-DestroyNotify Events
-.XS
-\*(SN DestroyNotify Events
-.XE
-.LP
-.IN "Events" "DestroyNotify"
-.IN "DestroyNotify" "" "@DEF@"
-The X server can report
-.PN DestroyNotify
-events to clients wanting information about which windows are destroyed.
-The X server generates this event whenever a client application destroys a 
-window by calling
-.PN XDestroyWindow
-or
-.PN XDestroySubwindows .
-.LP
-The ordering of the 
-.PN DestroyNotify 
-events is such that for any given window, 
-.PN DestroyNotify
-is generated on all inferiors of the window
-before being generated on the window itself.  
-The X protocol does not constrain the ordering among
-siblings and across subhierarchies.
-.LP
-To receive 
-.PN DestroyNotify
-events, set the
-.PN StructureNotifyMask
-bit in the event-mask attribute of the window or the
-.PN SubstructureNotifyMask
-bit in the event-mask attribute of the parent window
-(in which case, destroying any child generates an event).
-.LP
-The structure for this event type contains:
-.LP
-.IN "XDestroyWindowEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* DestroyNotify */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window event;
-	Window window;
-} XDestroyWindowEvent;
-.De
-.LP
-.eM
-The event member is set either to the destroyed window or to its parent,
-depending on whether
-.PN StructureNotify
-or 
-.PN SubstructureNotify
-was selected.
-The window member is set to the window that is destroyed.
-.NH 3
-GravityNotify Events
-.XS
-\*(SN GravityNotify Events
-.XE
-.LP
-.IN "Events" "GravityNotify"
-.IN "GravityNotify" "" "@DEF@"
-The X server can report
-.PN GravityNotify
-events to clients wanting information about when a window is moved because of a
-change in the size of its parent.
-The X server generates this event whenever a client
-application actually moves a child window as a result of resizing its parent by calling
-.PN XConfigureWindow ,
-.PN XMoveResizeWindow ,
-or
-.PN XResizeWindow . 
-.LP
-To receive 
-.PN GravityNotify
-events, set the
-.PN StructureNotifyMask
-bit in the event-mask attribute of the window or the
-.PN SubstructureNotifyMask
-bit in the event-mask attribute of the parent window
-(in which case, any child that is moved because its parent has been resized
-generates an event).
-.LP
-The structure for this event type contains:
-.LP
-.IN "XGravityEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* GravityNotify */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window event;
-	Window window;
-	int x, y;
-} XGravityEvent;
-.De
-.LP
-.eM
-The event member is set either to the window that was moved or to its parent,
-depending on whether
-.PN StructureNotify
-or
-.PN SubstructureNotify
-was selected.
-The window member is set to the child window that was moved.
-The x and y members are set to the coordinates relative to the 
-new parent window's origin
-and indicate the position of the upper-left outside corner of the 
-window.
-.NH 3
-MapNotify Events
-.XS
-\*(SN MapNotify Events
-.XE
-.LP
-.IN "Events" "MapNotify"
-.IN "MapNotify" "" "@DEF@"
-The X server can report
-.PN MapNotify
-events to clients wanting information about which windows are mapped.
-The X server generates this event type whenever a client application changes the
-window's state from unmapped to mapped by calling
-.PN XMapWindow ,
-.PN XMapRaised ,
-.PN XMapSubwindows ,
-.PN XReparentWindow ,
-or as a result of save-set processing.
-.LP
-To receive 
-.PN MapNotify
-events, set the
-.PN StructureNotifyMask
-bit in the event-mask attribute of the window or the
-.PN SubstructureNotifyMask
-bit in the event-mask attribute of the parent window
-(in which case, mapping any child generates an event).
-.LP
-The structure for this event type contains:
-.LP
-.IN "XMapEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* MapNotify */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window event;
-	Window window;
-	Bool override_redirect;	/* boolean, is override set... */
-} XMapEvent;
-.De
-.LP
-.eM
-The event member is set either to the window that was mapped or to its parent,
-depending on whether
-.PN StructureNotify
-or
-.PN SubstructureNotify
-was selected.
-The window member is set to the window that was mapped.
-The override_redirect member is set to the override-redirect attribute
-of the window.
-Window manager clients normally should ignore this window 
-if the override-redirect attribute is
-.PN True ,
-because these events usually are generated from pop-ups,
-which override structure control.
-.NH 3
-MappingNotify Events
-.XS
-\*(SN MappingNotify Events
-.XE
-.LP
-.IN "Events" "MappingNotify"
-.IN "MappingNotify" "" "@DEF@"
-The X server reports
-.PN MappingNotify
-events to all clients.
-There is no mechanism to express disinterest in this event.
-The X server generates this event type whenever a client application 
-successfully calls:
-.IP \(bu 5
-.PN XSetModifierMapping
-to indicate which KeyCodes are to be used as modifiers
-.IP \(bu 5
-.PN XChangeKeyboardMapping
-to change the keyboard mapping
-.IP \(bu 5
-.PN XSetPointerMapping
-to set the pointer mapping
-.LP
-The structure for this event type contains:
-.LP
-.IN "XMappingEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* MappingNotify */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window window;	/* unused */
-	int request;	/* one of MappingModifier, MappingKeyboard,
-		   MappingPointer */
-	int first_keycode;	/* first keycode */
-	int count;	/* defines range of change w. first_keycode*/
-} XMappingEvent;
-.De
-.LP
-.eM
-The request member is set to indicate the kind of mapping change that occurred
-and can be
-.PN MappingModifier ,
-.PN MappingKeyboard ,
-or
-.PN MappingPointer .
-If it is
-.PN MappingModifier ,
-the modifier mapping was changed.
-If it is
-.PN MappingKeyboard ,
-the keyboard mapping was changed.
-If it is
-.PN MappingPointer ,
-the pointer button mapping was changed. 
-The first_keycode and count members are set only 
-if the request member was set to
-.PN MappingKeyboard .
-The number in first_keycode represents the first number in the range 
-of the altered mapping, 
-and count represents the number of keycodes altered.
-.LP
-To update the client application's knowledge of the keyboard,
-you should call
-.PN XRefreshKeyboardMapping . 
-.NH 3
-ReparentNotify Events
-.XS
-\*(SN ReparentNotify Events
-.XE
-.LP
-.IN "Events" "ReparentNotify"
-.IN "ReparentNotify" "" "@DEF@"
-The X server can report
-.PN ReparentNotify
-events to clients wanting information about changing a window's parent.
-The X server generates this event whenever a client
-application calls
-.PN XReparentWindow 
-and the window is actually reparented.
-.LP
-To receive 
-.PN ReparentNotify
-events, set the
-.PN StructureNotifyMask
-bit in the event-mask attribute of the window or the
-.PN SubstructureNotifyMask
-bit in the event-mask attribute of either the old or the new parent window
-(in which case, reparenting any child generates an event).
-.LP
-The structure for this event type contains:
-.LP
-.IN "XReparentEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* ReparentNotify */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window event;
-	Window window;
-	Window parent;
-	int x, y;
-	Bool override_redirect;
-} XReparentEvent;
-.De
-.LP
-.eM
-The event member is set either to the reparented window
-or to the old or the new parent, depending on whether
-.PN StructureNotify
-or
-.PN SubstructureNotify
-was selected. 
-The window member is set to the window that was reparented.
-The parent member is set to the new parent window.
-The x and y members are set to the reparented window's coordinates relative 
-to the new parent window's
-origin and define the upper-left outer corner of the reparented window.
-The override_redirect member is set to the override-redirect attribute of the
-window specified by the window member.
-Window manager clients normally should ignore this window 
-if the override_redirect member is
-.PN True .
-.NH 3
-UnmapNotify Events
-.XS
-\*(SN UnmapNotify Events
-.XE
-.LP
-.IN "Events" "UnmapNotify"
-.IN "UnmapNotify" "" "@DEF@"
-The X server can report
-.PN UnmapNotify
-events to clients wanting information about which windows are unmapped.
-The X server generates this event type whenever a client application changes the
-window's state from mapped to unmapped.
-.LP
-To receive 
-.PN UnmapNotify
-events, set the
-.PN StructureNotifyMask
-bit in the event-mask attribute of the window or the
-.PN SubstructureNotifyMask
-bit in the event-mask attribute of the parent window
-(in which case, unmapping any child window generates an event).
-.LP
-The structure for this event type contains:
-.LP
-.IN "XUnmapEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* UnmapNotify */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window event;
-	Window window;
-	Bool from_configure;
-} XUnmapEvent;
-.De
-.LP
-.eM
-The event member is set either to the unmapped window or to its parent,
-depending on whether
-.PN StructureNotify
-or
-.PN SubstructureNotify
-was selected.
-This is the window used by the X server to report the event.
-The window member is set to the window that was unmapped.
-The from_configure member is set to
-.PN True 
-if the event was generated as a result of a resizing of the window's parent when
-the window itself had a win_gravity of
-.PN UnmapGravity .
-.NH 3
-VisibilityNotify Events
-.XS
-\*(SN VisibilityNotify Events
-.XE
-.LP
-.IN "Events" "VisibilityNotify"
-.IN "VisibilityNotify" "" "@DEF@"
-The X server can report
-.PN VisibilityNotify
-events to clients wanting any change in the visibility of the specified window.
-A region of a window is visible if someone looking at the screen can
-actually see it.
-The X server generates this event whenever the visibility changes state. 
-However, this event is never generated for windows whose class is
-.PN InputOnly .
-.LP
-All 
-.PN VisibilityNotify
-events caused by a hierarchy change are generated
-after any hierarchy event
-.Pn ( UnmapNotify , 
-.PN MapNotify , 
-.PN ConfigureNotify ,
-.PN GravityNotify ,
-.PN CirculateNotify )
-caused by that change.  Any
-.PN VisibilityNotify
-event on a given window is generated before any
-.PN Expose 
-events on that window, but it is not required that all
-.PN VisibilityNotify
-events on all windows be generated before all 
-.PN Expose
-events on all windows.  
-The X protocol does not constrain the ordering of 
-.PN VisibilityNotify
-events with
-respect to 
-.PN FocusOut , 
-.PN EnterNotify ,
-and 
-.PN LeaveNotify
-events.
-.LP
-To receive 
-.PN VisibilityNotify
-events, set the
-.PN VisibilityChangeMask
-bit in the event-mask attribute of the window. 
-.LP
-The structure for this event type contains:
-.LP
-.IN "XVisibilityEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* VisibilityNotify */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window window;
-	int state;
-} XVisibilityEvent;
-.De
-.LP
-.eM
-The window member is set to the window whose visibility state changes.
-The state member is set to the state of the window's visibility and can be
-.PN VisibilityUnobscured ,
-.PN VisibilityPartiallyObscured ,
-or
-.PN VisibilityFullyObscured .
-The X server ignores all of a window's subwindows
-when determining the visibility state of the window and processes 
-.PN VisibilityNotify
-events according to the following:
-.IP \(bu 5
-When the window changes state from partially obscured, fully obscured,
-or not viewable to viewable and completely unobscured,
-the X server generates the event with the state member of the
-.PN XVisibilityEvent
-structure set to
-.PN VisibilityUnobscured .
-.IP \(bu 5
-When the window changes state from viewable and completely unobscured or 
-not viewable to viewable and partially obscured,
-the X server generates the event with the state member of the
-.PN XVisibilityEvent
-structure set to
-.PN VisibilityPartiallyObscured .
-.IP \(bu 5
-When the window changes state from viewable and completely unobscured, 
-viewable and partially obscured, or not viewable to viewable and 
-fully obscured,
-the X server generates the event with the state member of the
-.PN XVisibilityEvent
-structure set to
-.PN VisibilityFullyObscured .
-.NH 2
-Structure Control Events
-.XS
-\*(SN Structure Control Events
-.XE
-.LP
-This section discusses:
-.IP \(bu 5
-.PN CirculateRequest
-events
-.IP \(bu 5
-.PN ConfigureRequest
-events
-.IP \(bu 5
-.PN MapRequest 
-events
-.IP \(bu 5
-.PN ResizeRequest 
-events
-.NH 3 
-CirculateRequest Events
-.XS
-\*(SN CirculateRequest Events
-.XE
-.LP
-.IN "Events" "CirculateRequest"
-.IN "CirculateRequest" "" "@DEF@"
-The X server can report
-.PN CirculateRequest
-events to clients wanting information about 
-when another client initiates a circulate window request 
-on a specified window.
-The X server generates this event type whenever a client initiates a circulate
-window request on a window and a subwindow actually needs to be restacked. 
-The client initiates a circulate window request on the window by calling
-.PN XCirculateSubwindows ,
-.PN XCirculateSubwindowsUp ,
-or
-.PN XCirculateSubwindowsDown .
-.LP
-To receive
-.PN CirculateRequest
-events, set the
-.PN SubstructureRedirectMask
-in the event-mask attribute of the window. 
-Then, in the future,
-the circulate window request for the specified window is not executed,
-and thus, any subwindow's position in the stack is not changed.
-For example, suppose a client application calls
-.PN XCirculateSubwindowsUp
-to raise a subwindow to the top of the stack.
-If you had selected
-.PN SubstructureRedirectMask
-on the window, the X server reports to you a
-.PN CirculateRequest
-event and does not raise the subwindow to the top of the stack.
-.LP
-The structure for this event type contains:
-.LP
-.IN "XCirculateRequestEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* CirculateRequest */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window parent;
-	Window window;
-	int place;	/* PlaceOnTop, PlaceOnBottom */
-} XCirculateRequestEvent;
-.De
-.LP
-.eM
-The parent member is set to the parent window.
-The window member is set to the subwindow to be restacked.
-The place member is set to what the new position in the stacking order should be
-and is either
-.PN PlaceOnTop
-or
-.PN PlaceOnBottom .
-If it is
-.PN PlaceOnTop ,
-the subwindow should be on top of all siblings.
-If it is
-.PN PlaceOnBottom ,
-the subwindow should be below all siblings.
-.NH 3
-ConfigureRequest Events
-.XS
-\*(SN ConfigureRequest Events
-.XE
-.LP
-.IN "Events" "ConfigureRequest"
-.IN "ConfigureRequest" "" "@DEF@"
-The X server can report
-.PN ConfigureRequest
-events to clients wanting information about when a different client initiates 
-a configure window request on any child of a specified window. 
-The configure window request attempts to 
-reconfigure a window's size, position, border, and stacking order.
-The X server generates this event whenever a different client initiates
-a configure window request on a window by calling
-.PN XConfigureWindow ,
-.PN XLowerWindow ,
-.PN XRaiseWindow ,
-.PN XMapRaised ,
-.PN XMoveResizeWindow ,
-.PN XMoveWindow ,
-.PN XResizeWindow ,
-.PN XRestackWindows ,
-or
-.PN XSetWindowBorderWidth .
-.LP
-To receive
-.PN ConfigureRequest
-events, set the
-.PN SubstructureRedirectMask
-bit in the event-mask attribute of the window. 
-.PN ConfigureRequest
-events are generated when a
-.PN ConfigureWindow
-protocol request is issued on a child window by another client.
-For example, suppose a client application calls
-.PN XLowerWindow
-to lower a window.
-If you had selected
-.PN SubstructureRedirectMask 
-on the parent window and if the override-redirect attribute 
-of the window is set to
-.PN False ,
-the X server reports a
-.PN ConfigureRequest
-event to you and does not lower the specified window.
-.LP
-The structure for this event type contains:
-.LP
-.IN "XConfigureRequestEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* ConfigureRequest */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window parent;
-	Window window;
-	int x, y;
-	int width, height;
-	int border_width;
-	Window above;
-	int detail;	/* Above, Below, TopIf, BottomIf, Opposite */
-	unsigned long value_mask;
-} XConfigureRequestEvent;
-.De
-.LP
-.eM
-The parent member is set to the parent window.
-The window member is set to the window whose size, position, border width, 
-and/or stacking order is to be reconfigured.
-The value_mask member indicates which components were specified in the
-.PN ConfigureWindow 
-protocol request.
-The corresponding values are reported as given in the request.
-The remaining values are filled in from the current geometry of the window,
-except in the case of above (sibling) and detail (stack-mode),
-which are reported as
-.PN None
-and
-.PN Above ,
-respectively, if they are not given in the request.
-.NH 3
-MapRequest Events
-.XS
-\*(SN MapRequest Events
-.XE
-.LP
-.IN "Events" "MapRequest"
-.IN "MapRequest" "" "@DEF@"
-The X server can report
-.PN MapRequest
-events to clients wanting information about a different client's desire 
-to map windows.
-A window is considered mapped when a map window request completes.
-The X server generates this event whenever a different client initiates 
-a map window request on an unmapped window whose override_redirect member 
-is set to
-.PN False .
-Clients initiate map window requests by calling
-.PN XMapWindow ,
-.PN XMapRaised ,
-or
-.PN XMapSubwindows .
-.LP
-To receive
-.PN MapRequest
-events, set the
-.PN SubstructureRedirectMask
-bit in the event-mask attribute of the window. 
-This means another client's attempts to map a child window by calling one of
-the map window request functions is intercepted, and you are sent a 
-.PN MapRequest
-instead.
-For example, suppose a client application calls
-.PN XMapWindow
-to map a window.
-If you (usually a window manager) had selected
-.PN SubstructureRedirectMask 
-on the parent window and if the override-redirect attribute 
-of the window is set to
-.PN False ,
-the X server reports a
-.PN MapRequest
-event to you 
-and does not map the specified window.
-Thus, this event gives your window manager client the ability 
-to control the placement of subwindows.
-.LP
-The structure for this event type contains:
-.LP
-.IN "XMapRequestEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* MapRequest */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window parent;
-	Window window;
-} XMapRequestEvent;
-.De
-.LP
-.eM
-The parent member is set to the parent window.
-The window member is set to the window to be mapped.
-.NH 3
-ResizeRequest Events
-.XS
-\*(SN ResizeRequest Events
-.XE
-.LP
-.IN "Events" "ResizeRequest"
-.IN "ResizeRequest" "" "@DEF@"
-The X server can report
-.PN ResizeRequest
-events to clients wanting information about another client's attempts to change the
-size of a window.
-The X server generates this event whenever some other client attempts to change
-the size of the specified window by calling
-.PN XConfigureWindow ,
-.PN XResizeWindow ,
-or
-.PN XMoveResizeWindow .
-.LP
-To receive
-.PN ResizeRequest
-events, set the
-.PN ResizeRedirect
-bit in the event-mask attribute of the window. 
-Any attempts to change the size by other clients are then redirected.
-.LP
-The structure for this event type contains:
-.LP
-.IN "XResizeRequestEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* ResizeRequest */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window window;
-	int width, height;
-} XResizeRequestEvent;
-.De
-.LP
-.eM
-The window member is set to the window whose size another 
-client attempted to change.
-The width and height members are set to the inside size of the window, 
-excluding the border.
-.NH 2
-Colormap State Change Events
-.XS
-\*(SN Colormap State Change Events
-.XE
-.LP
-.IN "Events" "ColormapNotify"
-.IN "ColormapNotify" "" "@DEF@"
-The X server can report
-.PN ColormapNotify
-events to clients wanting information about when the colormap changes 
-and when a colormap is installed or uninstalled. 
-The X server generates this event type whenever a client application:
-.IP \(bu 5
-Changes the colormap member of the
-.PN XSetWindowAttributes
-structure by 
-calling
-.PN XChangeWindowAttributes ,
-.PN XFreeColormap ,
-or
-.PN XSetWindowColormap 
-.IP \(bu 5
-Installs or uninstalls the colormap by calling
-.PN XInstallColormap
-or
-.PN XUninstallColormap 
-.LP
-To receive 
-.PN ColormapNotify 
-events, set the
-.PN ColormapChangeMask
-bit in the event-mask attribute of the window. 
-.LP
-The structure for this event type contains:
-.LP
-.IN "XColormapEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* ColormapNotify */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window window;
-	Colormap colormap;	/* colormap or None */
-	Bool new;
-	int state;	/* ColormapInstalled, ColormapUninstalled */
-} XColormapEvent;
-.De
-.LP
-.eM
-The window member is set to the window whose associated 
-colormap is changed, installed, or uninstalled.
-For a colormap that is changed, installed, or uninstalled,
-the colormap member is set to the colormap associated with the window. 
-For a colormap that is changed by a call to
-.PN XFreeColormap ,
-the colormap member is set to
-.PN None .
-The new member is set to indicate whether the colormap 
-for the specified window was changed or installed or uninstalled
-and can be 
-.PN True
-or
-.PN False .
-If it is
-.PN True ,
-the colormap was changed.
-If it is
-.PN False ,
-the colormap was installed or uninstalled.
-The state member is always set to indicate whether the colormap is installed or
-uninstalled and can be 
-.PN ColormapInstalled
-or
-.PN ColormapUninstalled .
-.NH 2
-Client Communication Events
-.XS
-\*(SN Client Communication Events
-.XE
-.LP
-This section discusses:
-.IP \(bu 5
-.PN ClientMessage 
-events
-.IP \(bu 5
-.PN PropertyNotify
-events
-.IP \(bu 5
-.PN SelectionClear
-events
-.IP \(bu 5
-.PN SelectionNotify
-events
-.IP \(bu 5
-.PN SelectionRequest
-events
-.NH 3
-ClientMessage Events
-.XS
-\*(SN ClientMessage Events
-.XE
-.LP
-.IN "Events" "ClientMessage"
-.IN "ClientMessage" "" "@DEF@"
-The X server generates
-.PN ClientMessage
-events only when a client calls the function
-.PN XSendEvent .
-.LP
-The structure for this event type contains:
-.LP
-.IN "XClientMessageEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 1i 3i
-.ta .5i 1i 3i
-typedef struct {
-	int type;	/* ClientMessage */
-	unsigned long serial;		/* # of last request processed by server */
-	Bool send_event;		/* true if this came from a SendEvent request */
-	Display *display;		/* Display the event was read from */
-	Window window;
-	Atom message_type;
-	int format;
-	union {
-		char b[20];
-		short s[10];
-		long l[5];
-	        } data;
-} XClientMessageEvent;
-.De
-.LP
-.eM
-The message_type member is set to an atom that indicates how the data 
-should be interpreted by the receiving client.
-The format member is set to 8, 16, or 32 and specifies whether the data
-should be viewed as a list of bytes, shorts, or longs.
-The data member is a union that contains the members b, s, and l.
-The b, s, and l members represent data of twenty 8-bit values, 
-ten 16-bit values, and five 32-bit values.
-Particular message types might not make use of all these values.
-The X server places no interpretation on the values in the window,
-message_type, or data members.
-.NH 3
-PropertyNotify Events
-.XS
-\*(SN PropertyNotify Events
-.XE
-.LP
-.IN "Events" "PropertyNotify"
-.IN "PropertyNotify" "" "@DEF@"
-The X server can report
-.PN PropertyNotify
-events to clients wanting information about property changes 
-for a specified window.
-.LP
-To receive
-.PN PropertyNotify
-events, set the
-.PN PropertyChangeMask
-bit in the event-mask attribute of the window. 
-.LP
-The structure for this event type contains:
-.LP
-.IN "XPropertyEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* PropertyNotify */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window window;
-	Atom atom;
-	Time time;
-	int state;	/* PropertyNewValue or PropertyDelete */
-} XPropertyEvent;
-.De
-.LP
-.eM
-The window member is set to the window whose associated 
-property was changed.
-The atom member is set to the property's atom and indicates which
-property was changed or desired.
-The time member is set to the server time when the property was changed.
-The state member is set to indicate whether the property was changed 
-to a new value or deleted and can be
-.PN PropertyNewValue
-or
-.PN PropertyDelete .
-The state member is set to
-.PN PropertyNewValue
-when a property of the window is changed using
-.PN XChangeProperty
-or
-.PN XRotateWindowProperties
-(even when adding zero-length data using
-.PN XChangeProperty )
-and when replacing all or part of a property with identical data using
-.PN XChangeProperty
-or 
-.PN XRotateWindowProperties .
-The state member is set to
-.PN PropertyDelete
-when a property of the window is deleted using
-.PN XDeleteProperty
-or, if the delete argument is 
-.PN True ,
-.PN XGetWindowProperty .
-.NH 3
-SelectionClear Events
-.XS
-\*(SN SelectionClear Events
-.XE
-.LP
-.IN "Events" "SelectionClear" 
-.IN "SelectionClear" "" "@DEF@"
-The X server reports
-.PN SelectionClear
-events to the client losing ownership of a selection.
-The X server generates this event type when another client
-asserts ownership of the selection by calling
-.PN XSetSelectionOwner .
-.LP
-The structure for this event type contains:
-.LP
-.IN "XSelectionClearEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* SelectionClear */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window window;
-	Atom selection;
-	Time time;
-} XSelectionClearEvent;
-.De
-.LP
-.eM
-The selection member is set to the selection atom.
-The time member is set to the last change time recorded for the 
-selection.
-The window member is the window that was specified by the current owner
-(the owner losing the selection) in its
-.PN XSetSelectionOwner
-call.
-.NH 3
-SelectionRequest Events
-.XS
-\*(SN SelectionRequest Events
-.XE
-.LP
-.IN "Events" "SelectionRequest"
-.IN "SelectionRequest" "" "@DEF@"
-The X server reports
-.PN SelectionRequest
-events to the owner of a selection.
-The X server generates this event whenever a client 
-requests a selection conversion by calling 
-.PN XConvertSelection 
-for the owned selection.
-.LP
-The structure for this event type contains:
-.LP
-.IN "XSelectionRequestEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* SelectionRequest */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window owner;
-	Window requestor;
-	Atom selection;
-	Atom target;
-	Atom property;
-	Time time;
-} XSelectionRequestEvent;
-.De
-.LP
-.eM
-The owner member is set to the window
-that was specified by the current owner in its
-.PN XSetSelectionOwner
-call.
-The requestor member is set to the window requesting the selection.
-The selection member is set to the atom that names the selection.
-For example, PRIMARY is used to indicate the primary selection.
-The target member is set to the atom that indicates the type
-the selection is desired in.
-The property member can be a property name or 
-.PN None .
-The time member is set to the timestamp or 
-.PN CurrentTime 
-value from the
-.PN ConvertSelection
-request.
-.LP
-The owner should convert the selection based on the specified target type
-and send a
-.PN SelectionNotify
-event back to the requestor.
-A complete specification for using selections is given in the X Consortium
-standard \fIInter-Client Communication Conventions Manual\fP.
-.NH 3
-SelectionNotify Events
-.XS
-\*(SN SelectionNotify Events
-.XE
-.LP
-.IN "Events" "SelectionNotify"
-.IN "SelectionNotify" "" "@DEF@"
-This event is generated by the X server in response to a
-.PN ConvertSelection 
-protocol request when there is no owner for the selection.
-When there is an owner, it should be generated by the owner
-of the selection by using
-.PN XSendEvent .
-The owner of a selection should send this event to a requestor when a selection
-has been converted and stored as a property
-or when a selection conversion could
-not be performed (which is indicated by setting the property member to
-.PN None ).
-.LP
-If
-.PN None
-is specified as the property in the 
-.PN ConvertSelection
-protocol request, the owner should choose a property name,
-store the result as that property on the requestor window,
-and then send a 
-.PN SelectionNotify
-giving that actual property name.
-.LP
-The structure for this event type contains:
-.LP
-.IN "XSelectionEvent" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	int type;	/* SelectionNotify */
-	unsigned long serial;	/* # of last request processed by server */
-	Bool send_event;	/* true if this came from a SendEvent request */
-	Display *display;	/* Display the event was read from */
-	Window requestor;
-	Atom selection;
-	Atom target;
-	Atom property;	/* atom or None */
-	Time time;
-} XSelectionEvent;
-.De
-.LP
-.eM
-The requestor member is set to the window associated with
-the requestor of the selection.
-The selection member is set to the atom that indicates the selection.
-For example, PRIMARY is used for the primary selection.
-The target member is set to the atom that indicates the converted type.
-For example, PIXMAP is used for a pixmap.
-The property member is set to the atom that indicates which
-property the result was stored on.
-If the conversion failed, 
-the property member is set to
-.PN None .
-The time member is set to the time the conversion took place and
-can be a timestamp or
-.PN CurrentTime .
-.bp
diff --git a/libX11/specs/libX11/CH10.xml b/libX11/specs/libX11/CH10.xml
new file mode 100644
index 000000000..68a5f98f4
--- /dev/null
+++ b/libX11/specs/libX11/CH10.xml
@@ -0,0 +1,4725 @@
+<chapter id="events">

+<title>Events</title>

+

+<para>

+A client application communicates with the X server through the connection you establish with

+the XOpenDisplay function. A client application sends requests to the X server over this con-

+nection. These requests are made by the Xlib functions that are called in the client application.

+Many Xlib functions cause the X server to generate events, and the user’s typing or moving the

+pointer can generate events asynchronously. The X server returns events to the client on the same

+connection.

+</para>

+<para>

+This chapter discusses the following topics associated with events:

+</para>

+

+<itemizedlist>

+  <listitem><para>Event types</para></listitem>

+  <listitem><para>Event structures</para></listitem>

+  <listitem><para>Event masks</para></listitem>

+  <listitem><para>Event processing</para></listitem>

+</itemizedlist>

+

+<para>

+Functions for handling events are dealt with in the next chapter.

+</para>

+

+<sect1 id="Event_Types">

+<title>Event Types</title>

+<!-- .XS -->

+<!-- (SN Event Types  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Event</primary><secondary>types</secondary></indexterm>

+An event is data generated asynchronously by the X server as a result of some 

+device activity or as side effects of a request sent by an Xlib function.

+<indexterm><primary>Event</primary></indexterm>

+Device-related events propagate from the source window to ancestor windows

+until some client application has selected that event type 

+or until the event is explicitly discarded.

+The X server generally sends an event to a client application

+only if the client has specifically asked to be informed of that event type, 

+typically by setting the event-mask attribute of the window.

+The mask can also be set when you create a window

+or by changing the window's

+event-mask.

+You can also mask out events that would propagate to ancestor windows

+by manipulating the

+do-not-propagate mask of the window's attributes.

+However,

+<function>MappingNotify</function>

+events are always sent to all clients.

+<indexterm><primary>Input Control</primary></indexterm>

+<indexterm><primary>Output Control</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+An event type describes a specific event generated by the X server.

+For each event type, 

+a corresponding constant name is defined in

+<!-- .hN X11/X.h , -->

+which is used when referring to an event type.

+<indexterm><primary>Event</primary><secondary>categories</secondary></indexterm>

+The following table lists the event category 

+and its associated event type or types. 

+The processing associated with these events is discussed in section 10.5.

+</para>

+<para>

+<!-- .LP -->

+<!-- .\".CP T 1 -->

+<!-- .\"Event Categories and Event Types -->

+</para>

+<para>

+<!-- .LP -->

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <thead>

+    <row>

+      <entry>Event Category</entry>

+      <entry>Event Type</entry>

+    </row>

+  </thead>

+  <tbody>

+    <row>

+      <entry>Keyboard events</entry>

+      <entry><function>KeyPress</function>,

+      <function>KeyRelease</function></entry>

+    </row>

+    <row>

+      <entry>Pointer events</entry>

+      <entry><function>ButtonPress</function>,

+      <function>ButtonRelease</function>,

+      <function>MotionNotify</function></entry>

+    </row>

+    <row>

+      <entry>Window crossing events</entry>

+      <entry><function>EnterNotify</function>,

+      <function>LeaveNotify</function></entry>

+    </row>

+    <row>

+      <entry>Input focus events</entry>

+      <entry><function>FocusIn</function>,

+      <function>FocusOut</function></entry>

+    </row>

+    <row>

+      <entry>Keymap state notification event</entry>

+      <entry><function>KeymapNotify</function></entry>

+    </row>

+    <row>

+      <entry>Exposure events</entry>

+      <entry><function>Expose</function>,

+      <function>GraphicsExpose</function>,

+      <function>NoExpose</function></entry>

+    </row>

+    <row>

+      <entry>Structure control events</entry>

+      <entry><function>CirculateRequest</function>,

+      <function>ConfigureRequest</function>,

+      <function>MapRequest</function>,

+      <function>ResizeRequest</function></entry>

+    </row>

+    <row>

+      <entry>Window state notification events</entry>

+      <entry>

+      <function>CirculateNotify</function>,

+      <function>ConfigureNotify</function>,

+      <function>CreateNotify</function>,

+      <function>DestroyNotify</function>,

+      <function>GravityNotify</function>,

+      <function>MapNotify</function>,

+      <function>MappingNotify</function>,

+      <function>ReparentNotify</function>,

+      <function>UnmapNotify</function>,

+      <function>VisibilityNotify</function></entry>

+    </row>

+    <row>

+      <entry>Colormap state notification event</entry>

+      <entry><function>ColormapNotify</function></entry>

+    </row>

+    <row>

+      <entry>Client communication events</entry>

+      <entry><function>ClientMessage</function>,

+      <function>PropertyNotify</function>,

+      <function>SelectionClear</function>,

+      <function>SelectionNotify</function>,

+      <function>SelectionRequest</function></entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<!-- .\".LP -->

+<!-- .\"Table 8-1 lists the event types and the Xlib functions that could cause -->

+<!-- .\"the X server to generate that event type. -->

+<!-- .\"The event types are listed alphabetically. -->

+<!-- .\"Note that the error event is not listed in this table. -->

+<!-- .\"For a list of the constants associated with an error event, see the Handling -->

+<!-- .\"Errors section in this chapter. -->

+<!-- .\".LP -->

+<!-- .\".so eventtable -->

+</para>

+</sect1>

+<sect1 id="Event_Structures">

+<title>Event Structures</title>

+<!-- .XS -->

+<!-- (SN Event Structures  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+For each event type,

+a corresponding structure is declared in

+<!-- .hN X11/Xlib.h . -->

+All the event structures have the following common members:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XAnyEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;

+     unsigned long serial;     /* # of last request processed by server */

+     Bool          send_event; /* true if this came from a SendEvent request */

+     Display       *display;   /* Display the event was read from */

+     Window        window;

+} XAnyEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The type member is set to the event type constant name that uniquely identifies

+it.

+For example, when the X server reports a

+<function>GraphicsExpose</function>

+event to a client application, it sends an

+<function>XGraphicsExposeEvent</function>

+structure with the type member set to

+<function>GraphicsExpose</function>.

+The display member is set to a pointer to the display the event was read on.

+The send_event member is set to

+<function>True</function>

+if the event came from a

+<function>SendEvent</function>

+protocol request.

+The serial member is set from the serial number reported in the protocol

+but expanded from the 16-bit least-significant bits to a full 32-bit value.

+The window member is set to the window that is most useful to toolkit

+dispatchers.

+</para>

+<para>

+<!-- .LP -->

+The X server can send events at any time in the input stream. 

+Xlib stores any events received while waiting for a reply in an event queue 

+for later use.

+Xlib also provides functions that allow you to check events 

+in the event queue (see section 11.3).

+</para>

+<para>

+<!-- .LP -->

+In addition to the individual structures declared for each event type, the

+<function>XEvent</function>

+structure is a union of the individual structures declared for each event type.

+Depending on the type,

+you should access members of each event by using the 

+<function>XEvent</function>

+union.

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XEvent</primary></indexterm>

+<!-- .sM -->

+</para>

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef union _XEvent {

+     int                            type;          /* must not be changed */

+     XAnyEvent                      xany;

+     XKeyEvent                      xkey;

+     XButtonEvent                   xbutton;

+     XMotionEvent                   xmotion;

+     XCrossingEvent                 xcrossing;

+     XFocusChangeEvent              xfocus;

+     XExposeEvent                   xexpose;

+     XGraphicsExposeEvent           xgraphicsexpose;

+     XNoExposeEvent                 xnoexpose;

+     XVisibilityEvent               xvisibility;

+     XCreateWindowEvent             xcreatewindow;

+     XDestroyWindowEvent            xdestroywindow;

+     XUnmapEvent                    xunmap;

+     XMapEvent                      xmap;

+     XMapRequestEvent               xmaprequest;

+     XReparentEvent                 xreparent;

+     XConfigureEvent                xconfigure;

+     XGravityEvent                  xgravity;

+     XResizeRequestEvent            xresizerequest;

+     XConfigureRequestEvent         xconfigurerequest;

+     XCirculateEvent                xcirculate;

+     XCirculateRequestEvent         xcirculaterequest;

+     XPropertyEvent                 xproperty;

+     XSelectionClearEvent           xselectionclear;

+     XSelectionRequestEvent         xselectionrequest;

+     XSelectionEvent                xselection;

+     XColormapEvent                 xcolormap;

+     XClientMessageEvent            xclient;

+     XMappingEvent                  xmapping;

+     XErrorEvent                    xerror;

+     XKeymapEvent                   xkeymap;

+     long                           pad[24];

+} XEvent;

+</literallayout>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+An

+<function>XEvent</function>

+structure's first entry always is the type member,

+which is set to the event type.

+The second member always is the serial number of the protocol request

+that generated the event.

+The third member always is send_event,

+which is a

+<function>Bool</function>

+that indicates if the event was sent by a different client.

+The fourth member always is a display,

+which is the display that the event was read from.

+Except for keymap events,

+the fifth member always is a window,

+which has been carefully selected to be useful to toolkit dispatchers.

+To avoid breaking toolkits,

+the order of these first five entries is not to change.

+Most events also contain a time member,

+which is the time at which an event occurred.

+In addition, a pointer to the generic event must be cast before it

+is used to access any other information in the structure.

+</para>

+</sect1>

+<sect1 id="Event_Masks">

+<title>Event Masks</title>

+<!-- .XS -->

+<!-- (SN Event Masks -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>Event mask</primary></indexterm>

+Clients select event reporting of most events relative to a window.

+To do this, pass an event mask to an Xlib event-handling

+function that takes an event_mask argument.

+The bits of the event mask are defined in

+<!-- .hN X11/X.h . -->

+Each bit in the event mask maps to an event mask name,

+which describes the event or events you want the X server to

+return to a client application.

+</para>

+<para>

+<!-- .LP -->

+Unless the client has specifically asked for them,

+most events are not reported to clients when they are generated. 

+Unless the client suppresses them by setting graphics-exposures in the GC to

+<function>False</function>,

+<function>GraphicsExpose </function>

+and 

+<function>NoExpose </function>

+are reported by default as a result of

+<function>XCopyPlane</function>

+and

+<function>XCopyArea</function>.

+<function>SelectionClear</function>,

+<function>SelectionRequest</function>,

+<function>SelectionNotify</function>,

+or

+<function>ClientMessage</function>

+cannot be masked.

+Selection-related events are only sent to clients cooperating

+with selections (see section 4.5).

+When the keyboard or pointer mapping is changed,

+<function>MappingNotify</function>

+is always sent to clients.

+</para>

+<para>

+<!-- .LP -->

+<!-- .\"Table 8-2  -->

+The following table 

+lists the event mask constants you can pass to

+the event_mask argument and

+the circumstances in which you would want to specify the

+event mask:

+</para>

+<!-- .LP -->

+<!-- .\" .CP T 2 -->

+<!-- .\"Event Mask Definitions -->

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <thead>

+    <row>

+      <entry>Event Mask</entry>

+      <entry>Circumstances</entry>

+    </row>

+  </thead>

+  <tbody>

+    <row>

+      <entry><function>NoEventMask</function></entry>

+      <entry>No events wanted</entry>

+    </row>

+    <row>

+      <entry><function>KeyPressMask</function></entry>

+      <entry>Keyboard down events wanted</entry>

+    </row>

+    <row>

+      <entry><function>KeyReleaseMask</function></entry>

+      <entry>Keyboard up events wanted</entry>

+    </row>

+    <row>

+      <entry><function>ButtonPressMask</function></entry>

+      <entry>Pointer button down events wanted</entry>

+    </row>

+    <row>

+      <entry><function>ButtonReleaseMask</function></entry>

+      <entry>Pointer button up events wanted</entry>

+    </row>

+    <row>

+      <entry><function>EnterWindowMask</function></entry>

+      <entry>Pointer window entry events wanted</entry>

+    </row>

+    <row>

+      <entry><function>LeaveWindowMask</function></entry>

+      <entry>Pointer window leave events wanted</entry>

+    </row>

+    <row>

+      <entry><function>PointerMotionMask</function></entry>

+      <entry>Pointer motion events wanted</entry>

+    </row>

+    <row>

+      <entry><function>PointerMotionHintMask</function></entry>

+      <entry>Pointer motion hints wanted</entry>

+    </row>

+    <row>

+      <entry><function>Button1MotionMask</function></entry>

+      <entry>Pointer motion while button 1 down</entry>

+    </row>

+    <row>

+      <entry><function>Button2MotionMask</function></entry>

+      <entry>Pointer motion while button 2 down</entry>

+    </row>

+    <row>

+      <entry><function>Button3MotionMask</function></entry>

+      <entry>Pointer motion while button 3 down</entry>

+    </row>

+    <row>

+      <entry><function>Button4MotionMask</function></entry>

+      <entry>Pointer motion while button 4 down</entry>

+    </row>

+    <row>

+      <entry><function>Button5MotionMask</function></entry>

+      <entry>Pointer motion while button 5 down</entry>

+    </row>

+    <row>

+      <entry><function>ButtonMotionMask</function></entry>

+      <entry>Pointer motion while any button down</entry>

+    </row>

+    <row>

+      <entry><function>KeymapStateMask</function></entry>

+      <entry>Keyboard state wanted at window entry and focus in</entry>

+    </row>

+    <row>

+      <entry><function>ExposureMask</function></entry>

+      <entry>Any exposure wanted</entry>

+    </row>

+    <row>

+      <entry><function>VisibilityChangeMask</function></entry>

+      <entry>Any change in visibility wanted</entry>

+    </row>

+    <row>

+      <entry><function>StructureNotifyMask</function></entry>

+      <entry>Any change in window structure wanted</entry>

+    </row>

+    <row>

+      <entry><function>ResizeRedirectMask</function></entry>

+      <entry>Redirect resize of this window</entry>

+    </row>

+    <row>

+      <entry><function>SubstructureNotifyMask</function></entry>

+      <entry>Substructure notification wanted</entry>

+    </row>

+    <row>

+      <entry><function>SubstructureRedirectMask</function></entry>

+      <entry>Redirect structure requests on children</entry>

+    </row>

+    <row>

+      <entry><function>FocusChangeMask</function></entry>

+      <entry>Any change in input focus wanted</entry>

+    </row>

+    <row>

+      <entry><function>PropertyChangeMask</function></entry>

+      <entry>Any change in property wanted</entry>

+    </row>

+    <row>

+      <entry><function>ColormapChangeMask</function></entry>

+      <entry>Any change in colormap wanted</entry>

+    </row>

+    <row>

+      <entry><function>OwnerGrabButtonMask</function></entry>

+      <entry>Automatic grabs should activate with owner_events set to True</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<para>

+<!-- .LP -->

+</para>

+</sect1>

+<sect1 id="Event_Processing_Overview">

+<title>Event Processing Overview</title>

+<!-- .XS -->

+<!-- (SN Event Processing Overview -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The event reported to a client application during event processing

+depends on which event masks you provide as the event-mask attribute 

+for a window.

+For some event masks, there is a one-to-one correspondence between

+the event mask constant and the event type constant.

+For example, if you pass the event mask

+<function>ButtonPressMask</function>,

+the X server sends back only

+<function>ButtonPress</function>

+events.

+<indexterm><primary>CurrentTime</primary></indexterm>

+Most events contain a time member,

+which is the time at which an event occurred.

+</para>

+<para>

+<!-- .LP -->

+In other cases, one event mask constant can map to several event type constants.

+For example, if you pass the event mask

+<function>SubstructureNotifyMask</function>,

+the X server can send back

+<function>CirculateNotify</function>,

+<function>ConfigureNotify</function>,

+<function>CreateNotify</function>,

+<function>DestroyNotify</function>,

+<function>GravityNotify</function>,

+<function>MapNotify</function>,

+<function>ReparentNotify</function>,

+or

+<function>UnmapNotify</function>

+events.

+</para>

+<para>

+<!-- .LP -->

+In another case, 

+two event masks can map to one event type.

+For example, 

+if you pass either

+<function>PointerMotionMask </function>

+or

+<function>ButtonMotionMask</function>,

+the X server sends back

+a

+<function>MotionNotify</function>

+event.

+</para>

+<para>

+<!-- .LP -->

+The following table 

+lists the event mask, 

+its associated event type or types, 

+and the structure name associated with the event type.

+Some of these structures actually are typedefs to a generic structure

+that is shared between two event types.

+Note that N.A. appears in columns for which the information is not applicable.

+</para>

+<!-- .LP -->

+<!-- .ps 9 -->

+<!-- .nr PS 9 -->

+<informaltable>

+  <tgroup cols='4' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <colspec colname='c3'/>

+  <colspec colname='c4'/>

+  <thead>

+    <row>

+      <entry>Event Mask</entry>

+      <entry>Event Type</entry>

+      <entry>Structure</entry>

+      <entry>Generic Structure</entry>

+    </row>

+  </thead>

+  <tbody>

+    <row>

+      <entry>ButtonMotionMask</entry>

+      <entry>MotionNotify</entry>

+      <entry>XPointerMovedEvent</entry>

+      <entry>XMotionEvent</entry>

+    </row>

+    <row>

+      <entry>Button1MotionMask</entry>

+    </row>

+    <row>

+      <entry>Button2MotionMask</entry>

+    </row>

+    <row>

+      <entry>Button3MotionMask</entry>

+    </row>

+    <row>

+      <entry>Button4MotionMask</entry>

+    </row>

+    <row>

+      <entry>Button5MotionMask</entry>

+    </row>

+    <row>

+      <entry>ButtonPressMask</entry>

+      <entry>ButtonPress</entry>

+      <entry>XButtonPressedEvent</entry>

+      <entry>XButtonEvent</entry>

+    </row>

+    <row>

+      <entry>ButtonReleaseMask</entry>

+      <entry>ButtonRelease</entry>

+      <entry>XButtonReleasedEvent</entry>

+      <entry>XButtonEvent</entry>

+    </row>

+    <row>

+      <entry>ColormapChangeMask</entry>

+      <entry>ColormapNotify</entry>

+      <entry>XColormapEvent</entry>

+    </row>

+    <row>

+      <entry>EnterWindowMask</entry>

+      <entry>EnterNotify</entry>

+      <entry>XEnterWindowEvent</entry>

+      <entry>XCrossingEvent</entry>

+    </row>

+    <row>

+      <entry>LeaveWindowMask</entry>

+      <entry>LeaveNotify</entry>

+      <entry>XLeaveWindowEvent</entry>

+      <entry>XCrossingEvent</entry>

+    </row>

+    <row>

+      <entry>ExposureMask</entry>

+      <entry>Expose</entry>

+      <entry>XExposeEvent </entry>

+    </row>

+    <row>

+      <entry>GCGraphicsExposures in GC</entry>

+      <entry>GraphicsExpose</entry>

+      <entry>XGraphicsExposeEvent</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>NoExpose</entry>

+      <entry>XNoExposeEvent</entry>

+    </row>

+    <row>

+      <entry>FocusChangeMask</entry>

+      <entry>FocusIn</entry>

+      <entry>XFocusInEvent</entry>

+      <entry>XFocusChangeEvent</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>FocusOut</entry>

+      <entry>XFocusOutEvent</entry>

+      <entry>XFocusChangeEvent</entry>

+    </row>

+    <row>

+      <entry>KeymapStateMask</entry>

+      <entry>KeymapNotify</entry>

+      <entry>XKeymapEvent</entry>

+    </row>

+    <row>

+      <entry>KeyPressMask</entry>

+      <entry>KeyPress</entry>

+      <entry>XKeyPressedEvent</entry>

+      <entry>XKeyEvent</entry>

+    </row>

+    <row>

+      <entry>KeyReleaseMask</entry>

+      <entry>KeyRelease</entry>

+      <entry>XKeyReleasedEvent</entry>

+      <entry>XKeyEvent</entry>

+    </row>

+    <row>

+      <entry>OwnerGrabButtonMask</entry>

+      <entry>N.A.</entry>

+      <entry>N.A.</entry>

+    </row>

+    <row>

+      <entry>PointerMotionMask</entry>

+      <entry>MotionNotify</entry>

+      <entry>XPointerMovedEvent</entry>

+      <entry>XMotionEvent</entry>

+    </row>

+    <row>

+      <entry>PointerMotionHintMask</entry>

+      <entry>N.A.</entry>

+      <entry>N.A.</entry>

+    </row>

+    <row>

+      <entry>PropertyChangeMask</entry>

+      <entry>PropertyNotify</entry>

+      <entry>XPropertyEvent</entry>

+    </row>

+    <row>

+      <entry>ResizeRedirectMask</entry>

+      <entry>ResizeRequest</entry>

+      <entry>XResizeRequestEvent</entry>

+    </row>

+    <row>

+      <entry>StructureNotifyMask</entry>

+      <entry>CirculateNotify</entry>

+      <entry>XCirculateEvent</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>ConfigureNotify</entry>

+      <entry>XConfigureEvent</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>DestroyNotify</entry>

+      <entry>XDestroyWindowEvent</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>GravityNotify</entry>

+      <entry>XGravityEvent</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>MapNotify</entry>

+      <entry>XMapEvent</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>ReparentNotify</entry>

+      <entry>XReparentEvent</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>UnmapNotify</entry>

+      <entry>XUnmapEvent</entry>

+    </row>

+    <row>

+      <entry>SubstructureNotifyMask</entry>

+      <entry>CirculateNotify</entry>

+      <entry>XCirculateEvent</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>ConfigureNotify</entry>

+      <entry>XConfigureEvent</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>CreateNotify</entry>

+      <entry>XCreateWindowEvent</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>DestroyNotify</entry>

+      <entry>XDestroyWindowEvent</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>GravityNotify</entry>

+      <entry>XGravityEvent</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>MapNotify</entry>

+      <entry>XMapEvent</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>ReparentNotify</entry>

+      <entry>XReparentEvent</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>UnmapNotify</entry>

+      <entry>XUnmapEvent</entry>

+    </row>

+    <row>

+      <entry>SubstructureRedirectMask</entry>

+      <entry>CirculateRequest</entry>

+      <entry>XCirculateRequestEvent</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>ConfigureRequest</entry>

+      <entry>XConfigureRequestEvent</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>MapRequest</entry>

+      <entry>XMapRequestEvent</entry>

+    </row>

+    <row>

+      <entry>N.A.</entry>

+      <entry>ClientMessage</entry>

+      <entry>XClientMessageEvent</entry>

+    </row>

+    <row>

+      <entry>N.A.</entry>

+      <entry>MappingNotify</entry>

+      <entry>XMappingEvent</entry>

+    </row>

+    <row>

+      <entry>N.A.</entry>

+      <entry>SelectionClear</entry>

+      <entry>XSelectionClearEvent</entry>

+    </row>

+    <row>

+      <entry>N.A.</entry>

+      <entry>SelectionNotify</entry>

+      <entry>XSelectionEvent</entry>

+    </row>

+    <row>

+      <entry>N.A.</entry>

+      <entry>SelectionRequest</entry>

+      <entry>XSelectionRequestEvent</entry>

+    </row>

+    <row>

+      <entry>VisibilityChangeMask</entry>

+      <entry>VisibilityNotify</entry>

+      <entry>XVisibilityEvent</entry>

+    </row>

+    <row>

+      <entry>_</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<para>

+<!-- .LP -->

+The sections that follow describe the processing that occurs 

+when you select the different event masks.

+The sections are organized according to these processing categories:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Keyboard and pointer events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Window crossing events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Input focus events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Keymap state notification events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Exposure events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Window state notification events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Structure control events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Colormap state notification events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Client communication events

+    </para>

+  </listitem>

+</itemizedlist>

+

+</sect1>

+

+<sect1 id="Keyboard_and_Pointer_Events">

+<title>Keyboard and Pointer Events</title>

+<!-- .XS -->

+<!-- (SN Keyboard and Pointer Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+This section discusses:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Pointer button events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Keyboard and pointer events

+    </para>

+  </listitem>

+</itemizedlist>

+<sect2 id="Pointer_Button_Events">

+<title>Pointer Button Events</title>

+<!-- .XS -->

+<!-- (SN Pointer Button Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The following describes the event processing that occurs when a pointer button 

+press is processed with the pointer in some window w and 

+when no active pointer grab is in progress.

+</para>

+<para>

+<!-- .LP -->

+The X server searches the ancestors of w from the root down,

+looking for a passive grab to activate.

+If no matching passive grab on the button exists,

+the X server automatically starts an active grab for the client receiving

+the event and sets the last-pointer-grab time to the current server time.

+The effect is essentially equivalent to an

+<function>XGrabButton</function>

+with these client passed arguments:

+</para>

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <thead>

+    <row>

+      <entry>Argument</entry>

+      <entry>Value</entry>

+    </row>

+  </thead>

+  <tbody>

+    <row>

+      <entry><emphasis remap='I'>w</emphasis></entry>

+      <entry>The event window </entry>

+    </row>

+    <row>

+      <entry><emphasis remap='I'>event_mask</emphasis></entry>

+      <entry>The client's selected pointer events on the event window</entry>

+    </row>

+    <row>

+      <entry><emphasis remap='I'>pointer_mode</emphasis></entry>

+      <entry><function>GrabModeAsync</function></entry>

+    </row>

+    <row>

+      <entry><emphasis remap='I'>keyboard_mode</emphasis></entry>

+      <entry><function>GrabModeAsync </function></entry>

+    </row>

+    <row>

+      <entry><emphasis remap='I'>owner_events</emphasis></entry>

+      <entry><function>True</function>,

+      if the client has selected

+      <function>OwnerGrabButtonMask</function>

+      on the event window,

+      otherwise

+      <function>False </function></entry>

+    </row>

+    <row>

+      <entry><emphasis remap='I'>confine_to</emphasis></entry>

+      <entry><function>None </function></entry>

+    </row>

+    <row>

+      <entry><emphasis remap='I'>cursor</emphasis></entry>

+      <entry><function>None </function></entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<para>

+<!-- .LP -->

+The active grab is automatically terminated when 

+the logical state of the pointer has all buttons released.

+Clients can modify the active grab by calling

+<function>XUngrabPointer</function>

+and

+<function>XChangeActivePointerGrab</function>.

+</para>

+</sect2>

+

+<sect2 id="Keyboard_and_Pointer_Events_b">

+<title>Keyboard and Pointer Events</title>

+<!-- .XS -->

+<!-- (SN Keyboard and Pointer Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>ButtonPress</secondary></indexterm>

+<indexterm><primary>Events</primary><secondary>ButtonRelease</secondary></indexterm>

+<indexterm><primary>Events</primary><secondary>KeyPress</secondary></indexterm>

+<indexterm><primary>Events</primary><secondary>KeyRelease</secondary></indexterm>

+<indexterm><primary>Events</primary><secondary>MotionNotify</secondary></indexterm>

+This section discusses the processing that occurs for the

+keyboard events

+<function>KeyPress</function>

+and 

+<function>KeyRelease </function>

+and the pointer events

+<function>ButtonPress</function>,

+<function>ButtonRelease</function>,

+and

+<function>MotionNotify</function>.

+For information about the keyboard event-handling utilities,

+see chapter 11.

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>KeyPress</primary></indexterm>

+<indexterm significance="preferred"><primary>KeyRelease</primary></indexterm>

+The X server reports

+<function>KeyPress</function>

+or

+<function>KeyRelease</function>

+events to clients wanting information about keys that logically change state.

+Note that these events are generated for all keys, 

+even those mapped to modifier bits.

+<indexterm significance="preferred"><primary>ButtonPress</primary></indexterm>

+<indexterm significance="preferred"><primary>ButtonRelease</primary></indexterm>

+The X server reports

+<function>ButtonPress</function>

+or

+<function>ButtonRelease</function>

+events to clients wanting information about buttons that logically change state.

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>MotionNotify</primary></indexterm>

+The X server reports

+<function>MotionNotify</function>

+events to clients wanting information about when the pointer logically moves.

+The X server generates this event whenever the pointer is moved 

+and the pointer motion begins and ends in the window.

+The granularity of

+<function>MotionNotify</function>

+events is not guaranteed, 

+but a client that selects this event type is guaranteed

+to receive at least one event when the pointer moves and then rests.

+</para>

+<para>

+<!-- .LP -->

+The generation of the logical changes lags the physical changes 

+if device event processing is frozen.

+</para>

+<para>

+<!-- .LP -->

+To receive

+<function>KeyPress</function>,

+<function>KeyRelease</function>,

+<function>ButtonPress</function>,

+and

+<function>ButtonRelease </function>

+events, set 

+<function>KeyPressMask</function>,

+<function>KeyReleaseMask</function>,

+<function>ButtonPressMask</function>,

+and

+<function>ButtonReleaseMask </function>

+bits in the event-mask attribute of the window.

+</para>

+<para>

+<!-- .LP -->

+To receive 

+<function>MotionNotify</function>

+events, set one or more of the following event 

+masks bits in the event-mask attribute of the window.

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+<function>Button1MotionMask \ \-</function>

+<function>Button5MotionMask</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The client application receives

+<function>MotionNotify</function>

+events only when one or more of the specified buttons is pressed.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>ButtonMotionMask</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The client application receives

+<function>MotionNotify</function>

+events only when at least one button is pressed.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>PointerMotionMask</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The client application receives 

+<function>MotionNotify</function>

+events independent of the state of

+the pointer buttons.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>PointerMotionHintMask</function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If

+<function>PointerMotionHintMask</function>

+is selected in combination with one or more of the above masks, 

+the X server is free to send only one

+<function>MotionNotify</function>

+event (with the is_hint member  of the

+<function>XPointerMovedEvent</function>

+structure set to

+<function>NotifyHint</function>)

+to the client for the event window, 

+until either the key or button state changes,

+the pointer leaves the event window, or the client calls

+<function>XQueryPointer</function>

+or

+<function>XGetMotionEvents</function>.

+The server still may send

+<function>MotionNotify</function>

+events without is_hint set to

+<function>NotifyHint</function>.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+The source of the event is the viewable window that the pointer is in.

+The window used by the X server to report these events depends on 

+the window's position in the window hierarchy 

+and whether any intervening window prohibits the generation of these events.

+Starting with the source window, 

+the X server searches up the window hierarchy until it locates the first 

+window specified by a client as having an interest in these events.

+If one of the intervening windows has its do-not-propagate-mask

+set to prohibit generation of the event type,

+the events of those types will be suppressed.

+Clients can modify the actual window used for reporting by performing

+active grabs and, in the case of keyboard events, by using the focus window.

+</para>

+<para>

+<!-- .LP -->

+The structures for these event types contain:

+</para>

+<literallayout class="monospaced">

+typedef struct {

+     int            type;            /* ButtonPress or ButtonRelease */

+     unsigned long  serial;          /* # of last request processed by server */

+     Bool           send_event;      /* true if this came from a SendEvent request */

+     Display        *display;        /* Display the event was read from */

+     Window         window;          /* ``event'' window it is reported relative to */

+     Window         root;            /* root window that the event occurred on */

+     Window         subwindow;       /* child window */

+     Time           time;            /* milliseconds */

+     int            x, y;            /* pointer x, y coordinates in event window */

+     int            x_root, y_root;  /* coordinates relative to root */

+     unsigned int   state;           /* key or button mask */

+     unsigned int   button;          /* detail */

+     Bool           same_screen;     /* same screen flag */

+} XButtonEvent;

+typedef XButtonEvent XButtonPressedEvent;

+typedef XButtonEvent XButtonReleasedEvent;

+</literallayout>

+

+<literallayout class="monospaced">

+typedef struct {

+     int            type;            /* KeyPress or KeyRelease */

+     unsigned long  serial;          /* # of last request processed by server */

+     Bool           send_event;      /* true if this came from a SendEvent request */

+     Display        *display;        /* Display the event was read from */

+     Window         window;          /* ``event'' window it is reported relative to */

+     Window         root;            /* root window that the event occurred on */

+     Window         subwindow;       /* child window */

+     Time           time;            /* milliseconds */

+     int            x, y;            /* pointer x, y coordinates in event window */

+     int            x_root, y_root;  /* coordinates relative to root */

+     unsigned int   state;           /* key or button mask */

+     unsigned int   keycode;         /* detail */

+     Bool           same_screen;     /* same screen flag */

+} XKeyEvent;

+typedef XKeyEvent XKeyPressedEvent;

+typedef XKeyEvent XKeyReleasedEvent;

+</literallayout>

+

+<literallayout class="monospaced">

+typedef struct {

+     int            type;              /* MotionNotify */

+     unsigned long  serial;            /* # of last request processed by server */

+     Bool           send_event;        /* true if this came from a SendEvent request */

+     Display        *display;          /* Display the event was read from */

+     Window         window;            /* ``event'' window reported relative to */

+     Window         root;              /* root window that the event occurred on */

+     Window         subwindow;         /* child window */

+     Time           time;              /* milliseconds */

+     int            x, y;              /* pointer x, y coordinates in event window */

+     int            x_root, y_root;    /* coordinates relative to root */

+     unsigned int   state;             /* key or button mask */

+     char           is_hint;           /* detail */

+     Bool           same_screen;       /* same screen flag */

+} XMotionEvent;

+typedef XMotionEvent XPointerMovedEvent;

+</literallayout>

+

+<para>

+These structures have the following common members:

+window, root, subwindow, time, x, y, x_root, y_root, state, and same_screen.

+The window member is set to the window on which the

+event was generated and is referred to as the event window. 

+As long as the conditions previously discussed are met,

+this is the window used by the X server to report the event.

+The root member is set to the source window's root window.

+The x_root and y_root members are set to the pointer's coordinates

+relative to the root window's origin at the time of the event.

+</para>

+

+<para>

+<!-- .LP -->

+The same_screen member is set to indicate whether the event 

+window is on the same screen

+as the root window and can be either

+<function>True </function>

+or

+<function>False</function>.

+If

+<function>True</function>,

+the event and root windows are on the same screen.

+If

+<function>False</function>,

+the event and root windows are not on the same screen.

+</para>

+<para>

+<!-- .LP -->

+If the source window is an inferior of the event window, 

+the subwindow member of the structure is set to the child of the event window

+that is the source window or the child of the event window that is

+an ancestor of the source window.

+Otherwise, the X server sets the subwindow member to

+<function>None</function>.

+The time member is set to the time when the event was generated 

+and is expressed in milliseconds.

+</para>

+<para>

+<!-- .LP -->

+If the event window is on the same screen as the root window, 

+the x and y members

+are set to the coordinates relative to the event window's origin.

+Otherwise, these members are set to zero.

+</para>

+<para>

+<!-- .LP -->

+The state member is set to indicate the logical state of the pointer buttons 

+and modifier keys just prior to the event,

+which is the bitwise inclusive OR of one or more of the

+button or modifier key masks:

+<function>Button1Mask</function>,

+<function>Button2Mask</function>,

+<function>Button3Mask</function>,

+<function>Button4Mask</function>,

+<function>Button5Mask</function>,

+<function>ShiftMask</function>,

+<function>LockMask</function>,

+<function>ControlMask</function>,

+<function>Mod1Mask</function>,

+<function>Mod2Mask</function>,

+<function>Mod3Mask</function>,

+<function>Mod4Mask</function>,

+and

+<function>Mod5Mask</function>.

+</para>

+<para>

+<!-- .LP -->

+Each of these structures also has a member that indicates the detail.

+For the

+<function>XKeyPressedEvent</function>

+and

+<function>XKeyReleasedEvent</function>

+structures, this member is called a keycode.

+It is set to a number that represents a physical key on the keyboard.

+The keycode is an arbitrary representation for any key on the keyboard

+(see sections 12.7 and 16.1).

+</para>

+<para>

+<!-- .LP -->

+For the

+<function>XButtonPressedEvent</function>

+and

+<function>XButtonReleasedEvent</function>

+structures, this member is called button.

+It represents the pointer button that changed state and can be the

+<function>Button1</function>,

+<function>Button2</function>,

+<function>Button3</function>,

+<function>Button4</function>,

+or

+<function>Button5 </function>

+value.

+For the

+<function>XPointerMovedEvent</function>

+structure, this member is called is_hint.

+It can be set to 

+<function>NotifyNormal</function>

+or

+<function>NotifyHint</function>.

+</para>

+<para>

+<!-- .LP -->

+Some of the symbols mentioned in this section have fixed values, as

+follows:

+</para>

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <thead>

+    <row>

+      <entry>Symbol</entry>

+      <entry>Value</entry>

+    </row>

+  </thead>

+  <tbody>

+    <row>

+      <entry><function>Button1MotionMask</function></entry>

+      <entry>(1L&lt;&lt;8)</entry>

+    </row>

+    <row>

+      <entry><function>Button2MotionMask</function></entry>

+      <entry>(1L&lt;&lt;9)</entry>

+    </row>

+    <row>

+      <entry><function>Button3MotionMask</function></entry>

+      <entry>(1L&lt;&lt;10)</entry>

+    </row>

+    <row>

+      <entry><function>Button4MotionMask</function></entry>

+      <entry>(1L&lt;&lt;11)</entry>

+    </row>

+    <row>

+      <entry><function>Button5MotionMask</function></entry>

+      <entry>(1L&lt;&lt;12)</entry>

+    </row>

+    <row>

+      <entry><function>Button1Mask</function></entry>

+      <entry>(1&lt;&lt;8)</entry>

+    </row>

+    <row>

+      <entry><function>Button2Mask</function></entry>

+      <entry>(1&lt;&lt;9)</entry>

+    </row>

+    <row>

+      <entry><function>Button3Mask</function></entry>

+      <entry>(1&lt;&lt;10)</entry>

+    </row>

+    <row>

+      <entry><function>Button4Mask</function></entry>

+      <entry>(1&lt;&lt;11)</entry>

+    </row>

+    <row>

+      <entry><function>Button5Mask</function></entry>

+      <entry>(1&lt;&lt;12)</entry>

+    </row>

+    <row>

+      <entry><function>ShiftMask</function></entry>

+      <entry>(1&lt;&lt;0)</entry>

+    </row>

+    <row>

+      <entry><function>LockMask</function></entry>

+      <entry>(1&lt;&lt;1)</entry>

+    </row>

+    <row>

+      <entry><function>ControlMask</function></entry>

+      <entry>(1&lt;&lt;2)</entry>

+    </row>

+    <row>

+      <entry><function>Mod1Mask</function></entry>

+      <entry>(1&lt;&lt;3)</entry>

+    </row>

+    <row>

+      <entry><function>Mod2Mask</function></entry>

+      <entry>(1&lt;&lt;4)</entry>

+    </row>

+    <row>

+      <entry><function>Mod3Mask</function></entry>

+      <entry>(1&lt;&lt;5)</entry>

+    </row>

+    <row>

+      <entry><function>Mod4Mask</function></entry>

+      <entry>(1&lt;&lt;6)</entry>

+    </row>

+    <row>

+      <entry><function>Mod5Mask</function></entry>

+      <entry>(1&lt;&lt;7)</entry>

+    </row>

+    <row>

+      <entry><function>Button1</function></entry>

+      <entry>1</entry>

+    </row>

+    <row>

+      <entry><function>Button2</function></entry>

+      <entry>2</entry>

+    </row>

+    <row>

+      <entry><function>Button3</function></entry>

+      <entry>3</entry>

+    </row>

+    <row>

+      <entry><function>Button4</function></entry>

+      <entry>4</entry>

+    </row>

+    <row>

+      <entry><function>Button5</function></entry>

+      <entry>5</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+</sect2>

+</sect1>

+<sect1 id="Window_Entry_Exit_Events">

+<title>Window Entry/Exit Events</title>

+<!-- .XS -->

+<!-- (SN Window Entry/Exit Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>EnterNotify</secondary></indexterm>

+<indexterm><primary>Events</primary><secondary>LeaveNotify</secondary></indexterm>

+This section describes the processing that 

+occurs for the window crossing events

+<function>EnterNotify</function>

+and

+<function>LeaveNotify</function>.

+<indexterm significance="preferred"><primary>EnterNotify</primary></indexterm>

+<indexterm significance="preferred"><primary>LeaveNotify</primary></indexterm>

+If a pointer motion or a window hierarchy change causes the

+pointer to be in a different window than before, the X server reports

+<function>EnterNotify</function>

+or

+<function>LeaveNotify</function>

+events to clients who have selected for these events.

+All 

+<function>EnterNotify</function>

+and 

+<function>LeaveNotify</function>

+events caused by a hierarchy change are

+generated after any hierarchy event

+(<function>UnmapNotify</function>,

+<function>MapNotify</function>,

+<function>ConfigureNotify</function>,

+<function>GravityNotify</function>,

+<function>CirculateNotify</function>)

+caused by that change;

+however, the X protocol does not constrain the ordering of 

+<function>EnterNotify </function>

+and 

+<function>LeaveNotify </function>

+events with respect to

+<function>FocusOut</function>,

+<function>VisibilityNotify</function>,

+and 

+<function>Expose </function>

+events.

+</para>

+<para>

+<!-- .LP -->

+This contrasts with

+<function>MotionNotify</function>

+events, which are also generated when the pointer moves

+but only when the pointer motion begins and ends in a single window.

+An

+<function>EnterNotify</function>

+or

+<function>LeaveNotify</function>

+event also can be generated when some client application calls

+<function>XGrabPointer</function>

+and

+<function>XUngrabPointer</function>.

+</para>

+<para>

+<!-- .LP -->

+To receive

+<function>EnterNotify</function>

+or

+<function>LeaveNotify</function>

+events, set the

+<function>EnterWindowMask</function>

+or

+<function>LeaveWindowMask</function>

+bits of the event-mask attribute of the window.

+</para>

+<para>

+<!-- .LP -->

+The structure for these event types contains:

+</para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XCrossingEvent</primary></indexterm>

+<indexterm significance="preferred"><primary>XEnterWindowEvent</primary></indexterm>

+<indexterm significance="preferred"><primary>XLeaveWindowEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;           /* EnterNotify or LeaveNotify */

+     unsigned long serial;         /* # of last request processed by server */

+     Bool          send_event;     /* true if this came from a SendEvent request */

+     Display       *display;       /* Display the event was read from */

+     Window        window;         /* ``event'' window reported relative to */

+     Window        root;           /* root window that the event occurred on */

+     Window        subwindow;      /* child window */

+     Time          time;           /* milliseconds */

+     int           x, y;           /* pointer x, y coordinates in event window */

+     int           x_root, y_root; /* coordinates relative to root */

+     int           mode;           /* NotifyNormal, NotifyGrab, NotifyUngrab */

+     int           detail;

+                   /*

+                    * NotifyAncestor, NotifyVirtual, NotifyInferior, 

+                    * NotifyNonlinear,NotifyNonlinearVirtual

+                    */

+     Bool          same_screen;    /* same screen flag */

+     Bool          focus;          /* boolean focus */

+     unsigned int  state;          /* key or button mask */

+} XCrossingEvent;

+typedef XCrossingEvent XEnterWindowEvent;

+typedef XCrossingEvent XLeaveWindowEvent;

+</literallayout>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The window member is set to the window on which the

+<function>EnterNotify</function>

+or

+<function>LeaveNotify</function>

+event was generated and is referred to as the event window. 

+This is the window used by the X server to report the event, 

+and is relative to the root

+window on which the event occurred. 

+The root member is set to the root window of the screen

+on which the event occurred.

+</para>

+<para>

+<!-- .LP -->

+For a

+<function>LeaveNotify </function>

+event,

+if a child of the event window contains the initial position of the pointer,

+the subwindow component is set to that child.

+Otherwise, the X server sets the subwindow member to

+<function>None</function>.

+For an

+<function>EnterNotify </function>

+event, if a child of the event window contains the final pointer position, 

+the subwindow component is set to that child or

+<function>None</function>.

+</para>

+<para>

+<!-- .LP -->

+The time member is set to the time when the event was generated

+and is expressed in milliseconds.

+The x and y members are set to the coordinates of the pointer position in 

+the event window.

+This position is always the pointer's final position,

+not its initial position.

+If the event window is on the same

+screen as the root window, x and y are the pointer coordinates

+relative to the event window's origin. 

+Otherwise, x and y are set to zero.

+The x_root and y_root members are set to the pointer's coordinates relative to the

+root window's origin at the time of the event.

+</para>

+<para>

+<!-- .LP -->

+The same_screen member is set to indicate whether the event window is on the same screen

+as the root window and can be either

+<function>True </function>

+or

+<function>False</function>.

+If

+<function>True</function>,

+the event and root windows are on the same screen.

+If

+<function>False</function>,

+the event and root windows are not on the same screen.

+</para>

+<para>

+<!-- .LP -->

+The focus member is set to indicate whether the event window is the focus window or an

+inferior of the focus window.

+The X server can set this member to either

+<function>True </function>

+or

+<function>False</function>.

+If

+<function>True</function>,

+the event window is the focus window or an inferior of the focus window.

+If

+<function>False</function>,

+the event window is not the focus window or an inferior of the focus window.

+</para>

+<para>

+<!-- .LP -->

+The state member is set to indicate the state of the pointer buttons and

+modifier keys just prior to the

+event.

+The X server can set this member to the bitwise inclusive OR of one 

+or more of the button or modifier key masks:

+<function>Button1Mask</function>,

+<function>Button2Mask</function>,

+<function>Button3Mask</function>,

+<function>Button4Mask</function>,

+<function>Button5Mask</function>,

+<function>ShiftMask</function>,

+<function>LockMask</function>,

+<function>ControlMask</function>,

+<function>Mod1Mask</function>,

+<function>Mod2Mask</function>,

+<function>Mod3Mask</function>,

+<function>Mod4Mask</function>,

+<function>Mod5Mask</function>.

+</para>

+<para>

+<!-- .LP -->

+The mode member is set to indicate whether the events are normal events, 

+pseudo-motion events

+when a grab activates, or pseudo-motion events when a grab deactivates.

+The X server can set this member to 

+<function>NotifyNormal</function>,

+<function>NotifyGrab</function>,

+or

+<function>NotifyUngrab</function>.

+</para>

+<para>

+<!-- .LP -->

+The detail member is set to indicate the notify detail and can be

+<function>NotifyAncestor</function>,

+<function>NotifyVirtual</function>,

+<function>NotifyInferior</function>,

+<function>NotifyNonlinear</function>,

+or

+<function>NotifyNonlinearVirtual</function>.

+</para>

+<sect2 id="Normal_Entry_Exit_Events">

+<title>Normal Entry/Exit Events</title>

+<!-- .XS -->

+<!-- (SN Normal Entry/Exit Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<function>EnterNotify</function>

+and

+<function>LeaveNotify</function>

+events are generated when the pointer moves from

+one window to another window.

+Normal events are identified by

+<function>XEnterWindowEvent</function>

+or

+<function>XLeaveWindowEvent</function>

+structures whose mode member is set to

+<function>NotifyNormal</function>.

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+When the pointer moves from window A to window B and A is an inferior of B, 

+the X server does the following:

+<!-- .RS -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>LeaveNotify</function>

+event on window A, with the detail member of the

+<function>XLeaveWindowEvent</function>

+structure set to

+<function>NotifyAncestor</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>LeaveNotify</function>

+event on each window between window A and window B, exclusive,

+with the detail member of each

+<function>XLeaveWindowEvent</function>

+structure set to

+<function>NotifyVirtual</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates an

+<function>EnterNotify</function>

+event on window B, with the detail member of the 

+<function>XEnterWindowEvent</function>

+structure set to

+<function>NotifyInferior</function>.

+<!-- .RE -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+When the pointer moves from window A to window B and B is an inferior of A,

+the X server does the following:

+<!-- .RS -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>LeaveNotify</function>

+event on window A,

+with the detail member of the

+<function>XLeaveWindowEvent</function>

+structure set to

+<function>NotifyInferior</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates an

+<function>EnterNotify</function>

+event on each window between window A and window B, exclusive, with the 

+detail member of each 

+<function>XEnterWindowEvent</function>

+structure set to

+<function>NotifyVirtual</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates an

+<function>EnterNotify</function>

+event on window B, with the detail member of the 

+<function>XEnterWindowEvent</function>

+structure set to

+<function>NotifyAncestor</function>.

+<!-- .RE -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+When the pointer moves from window A to window B 

+and window C is their least common ancestor, 

+the X server does the following:

+<!-- .RS -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>LeaveNotify</function>

+event on window A,

+with the detail member of the

+<function>XLeaveWindowEvent</function>

+structure set to 

+<function>NotifyNonlinear</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>LeaveNotify</function>

+event on each window between window A and window C, exclusive,

+with the detail member of each

+<function>XLeaveWindowEvent</function>

+structure set to

+<function>NotifyNonlinearVirtual</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates an

+<function>EnterNotify</function>

+event on each window between window C and window B, exclusive, 

+with the detail member of each

+<function>XEnterWindowEvent</function>

+structure set to

+<function>NotifyNonlinearVirtual</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates an

+<function>EnterNotify</function>

+event on window B, with the detail member of the 

+<function>XEnterWindowEvent</function>

+structure set to 

+<function>NotifyNonlinear</function>.

+<!-- .RE -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+When the pointer moves from window A to window B on different screens, 

+the X server does the following:

+<!-- .RS -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>LeaveNotify</function>

+event on window A,

+with the detail member of the

+<function>XLeaveWindowEvent</function>

+structure set to 

+<function>NotifyNonlinear</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If window A is not a root window,

+it generates a

+<function>LeaveNotify</function>

+event on each window above window A up to and including its root,

+with the detail member of each

+<function>XLeaveWindowEvent</function>

+structure set to 

+<function>NotifyNonlinearVirtual</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If window B is not a root window,

+it generates an

+<function>EnterNotify</function>

+event on each window from window B's root down to but not including

+window B, with the detail member of each

+<function>XEnterWindowEvent</function>

+structure set to 

+<function>NotifyNonlinearVirtual</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates an

+<function>EnterNotify</function>

+event on window B, with the detail member of the

+<function>XEnterWindowEvent</function>

+structure set to 

+<function>NotifyNonlinear</function>.

+<!-- .RE -->

+<!-- .\".SH 3 -->

+    </para>

+  </listitem>

+</itemizedlist>

+</sect2>

+<sect2 id="Grab_and_Ungrab_Entry_Exit_Events">

+<title>Grab and Ungrab Entry/Exit Events</title>

+<!-- .XS -->

+<!-- (SN Grab and Ungrab Entry/Exit Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Pseudo-motion mode

+<function>EnterNotify</function>

+and

+<function>LeaveNotify</function>

+events are generated when a pointer grab activates or deactivates.

+Events in which the pointer grab activates

+are identified by

+<function>XEnterWindowEvent</function>

+or

+<function>XLeaveWindowEvent</function>

+structures whose mode member is set to 

+<function>NotifyGrab</function>.

+Events in which the pointer grab deactivates

+are identified by

+<function>XEnterWindowEvent</function>

+or

+<function>XLeaveWindowEvent</function>

+structures whose mode member is set to 

+<function>NotifyUngrab</function>

+(see

+<function>XGrabPointer</function>).

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+When a pointer grab activates after any initial warp into a confine_to

+window and before generating any actual

+<function>ButtonPress</function>

+event that activates the grab, 

+G is the grab_window for the grab, 

+and P is the window the pointer is in, 

+the X server does the following:

+<!-- .RS -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates

+<function>EnterNotify</function>

+and

+<function>LeaveNotify</function>

+events (see section 10.6.1)

+with the mode members of the 

+<function>XEnterWindowEvent</function>

+and

+<function>XLeaveWindowEvent</function>

+structures set to 

+<function>NotifyGrab</function>.

+These events are generated

+as if the pointer were to suddenly warp from

+its current position in P to some position in G.

+However, the pointer does not warp, and the X server uses the pointer position 

+as both the initial and final positions for the events.

+<!-- .RE -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+When a pointer grab deactivates after generating any actual

+<function>ButtonRelease</function>

+event that deactivates the grab, 

+G is the grab_window for the grab,

+and P is the window the pointer is in, 

+the X server does the following:

+<!-- .RS -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates

+<function>EnterNotify</function>

+and

+<function>LeaveNotify</function>

+events (see section 10.6.1)

+with the mode members of the

+<function>XEnterWindowEvent</function>

+and

+<function>XLeaveWindowEvent</function>

+structures set to 

+<function>NotifyUngrab</function>.

+These events are generated as if the pointer were to suddenly warp from

+some position in G to its current position in P.

+However, the pointer does not warp, and the X server uses the

+current pointer position as both the

+initial and final positions for the events.

+<!-- .RE -->

+    </para>

+  </listitem>

+</itemizedlist>

+</sect2>

+</sect1>

+<sect1 id="Input_Focus_Events">

+<title>Input Focus Events</title>

+<!-- .XS -->

+<!-- (SN Input Focus Events  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>FocusIn</secondary></indexterm>

+<indexterm><primary>Events</primary><secondary>FocusOut</secondary></indexterm>

+This section describes the processing that occurs for the input focus events

+<function>FocusIn</function>

+and

+<function>FocusOut</function>.

+<indexterm significance="preferred"><primary>FocusIn</primary></indexterm>

+<indexterm significance="preferred"><primary>FocusOut</primary></indexterm>

+The X server can report

+<function>FocusIn</function>

+or

+<function>FocusOut</function>

+events to clients wanting information about when the input focus changes.

+The keyboard is always attached to some window 

+(typically, the root window or a top-level window), 

+which is called the focus window.

+The focus window and the position of the pointer determine the window that

+receives keyboard input.

+Clients may need to know when the input focus changes

+to control highlighting of areas on the screen.

+</para>

+<para>

+<!-- .LP -->

+To receive

+<function>FocusIn</function>

+or

+<function>FocusOut</function>

+events, set the

+<function>FocusChangeMask</function>

+bit in the event-mask attribute of the window. 

+</para>

+<para>

+<!-- .LP -->

+The structure for these event types contains:

+</para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XFocusChangeEvent</primary></indexterm>

+<indexterm significance="preferred"><primary>XFocusInEvent</primary></indexterm>

+<indexterm significance="preferred"><primary>XFocusOutEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;       /* FocusIn or FocusOut */

+     unsigned long serial;     /* # of last request processed by server */

+     Bool          send_event; /* true if this came from a SendEvent request */

+     Display       *display;   /* Display the event was read from */

+     Window        window;     /* window of event */

+     int           mode;       /* NotifyNormal, NotifyGrab, NotifyUngrab */

+     int           detail;

+                   /*

+                    * NotifyAncestor, NotifyVirtual, NotifyInferior, 

+                    * NotifyNonlinear,NotifyNonlinearVirtual, NotifyPointer,

+                    * NotifyPointerRoot, NotifyDetailNone 

+                    */

+} XFocusChangeEvent;

+typedef XFocusChangeEvent XFocusInEvent;

+typedef XFocusChangeEvent XFocusOutEvent;

+</literallayout>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The window member is set to the window on which the

+<function>FocusIn</function>

+or

+<function>FocusOut</function>

+event was generated.

+This is the window used by the X server to report the event. 

+The mode member is set to indicate whether the focus events 

+are normal focus events, 

+focus events while grabbed,

+focus events

+when a grab activates, or focus events when a grab deactivates.

+The X server can set the mode member to 

+<function>NotifyNormal</function>,

+<function>NotifyWhileGrabbed</function>,

+<function>NotifyGrab</function>,

+or

+<function>NotifyUngrab</function>.

+</para>

+<para>

+<!-- .LP -->

+All 

+<function>FocusOut</function>

+events caused by a window unmap are generated after any

+<function>UnmapNotify</function>

+event; however, the X protocol does not constrain the ordering of 

+<function>FocusOut</function>

+events with respect to

+generated 

+<function>EnterNotify</function>,

+<function>LeaveNotify</function>,

+<function>VisibilityNotify</function>,

+and

+<function>Expose</function>

+events.

+</para>

+<para>

+<!-- .LP -->

+Depending on the event mode,

+the detail member is set to indicate the notify detail and can be

+<function>NotifyAncestor</function>,

+<function>NotifyVirtual</function>,

+<function>NotifyInferior</function>,

+<function>NotifyNonlinear</function>,

+<function>NotifyNonlinearVirtual</function>,

+<function>NotifyPointer</function>,

+<function>NotifyPointerRoot</function>,

+or

+<function>NotifyDetailNone</function>.

+</para>

+<sect2 id="Normal_Focus_Events_and_Focus_Events_While_Grabbed_">

+<title>Normal Focus Events and Focus Events While Grabbed </title>

+<!-- .XS -->

+<!-- (SN Normal Focus Events and Focus Events While Grabbed  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Normal focus events are identified by

+<function>XFocusInEvent</function>

+or

+<function>XFocusOutEvent</function>

+structures whose mode member is set to 

+<function>NotifyNormal</function>.

+Focus events while grabbed are identified by

+<function>XFocusInEvent</function>

+or

+<function>XFocusOutEvent</function>

+structures whose mode member is set to 

+<function>NotifyWhileGrabbed</function>.

+The X server processes normal focus and focus events while grabbed according to 

+the following:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+When the focus moves from window A to window B, A is an inferior of B, 

+and the pointer is in window P, 

+the X server does the following:

+<!-- .RS -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>FocusOut</function>

+event on window A, with the detail member of the

+<function>XFocusOutEvent</function>

+structure set to 

+<function>NotifyAncestor</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>FocusOut</function>

+event on each window between window A and window B, exclusive,

+with the detail member of each

+<function>XFocusOutEvent</function>

+structure set to 

+<function>NotifyVirtual</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>FocusIn</function>

+event on window B, with the detail member of the 

+<function>XFocusOutEvent</function>

+structure set to 

+<function>NotifyInferior</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If window P is an inferior of window B

+but window P is not window A or an inferior or ancestor of window A,

+it generates a

+<function>FocusIn</function>

+event on each window below window B, down to and including window P, 

+with the detail member of each 

+<function>XFocusInEvent</function>

+structure set to 

+<function>NotifyPointer</function>.

+<!-- .RE -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+When the focus moves from window A to window B, B is an inferior of A, 

+and the pointer is in window P, 

+the X server does the following:

+<!-- .RS -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If window P is an inferior of window A

+but P is not an inferior of window B or an ancestor of B,

+it generates a

+<function>FocusOut</function>

+event on each window from window P up to but not including window A,

+with the detail member of each 

+<function>XFocusOutEvent</function>

+structure set to  

+<function>NotifyPointer</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>FocusOut</function>

+event on window A,

+with the detail member of the

+<function>XFocusOutEvent</function>

+structure set to  

+<function>NotifyInferior</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>FocusIn</function>

+event on each window between window A and window B, exclusive, with the 

+detail member of each 

+<function>XFocusInEvent</function>

+structure set to  

+<function>NotifyVirtual</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>FocusIn</function>

+event on window B, with the detail member of the 

+<function>XFocusInEvent</function>

+structure set to  

+<function>NotifyAncestor</function>.

+<!-- .RE -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+When the focus moves from window A to window B, 

+window C is their least common ancestor, 

+and the pointer is in window P, 

+the X server does the following:

+<!-- .RS -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If window P is an inferior of window A,

+it generates a

+<function>FocusOut</function>

+event on each window from window P up to but not including window A, 

+with the detail member of the 

+<function>XFocusOutEvent</function>

+structure set to  

+<function>NotifyPointer</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>FocusOut</function>

+event on window A,

+with the detail member of the

+<function>XFocusOutEvent</function>

+structure set to  

+<function>NotifyNonlinear</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>FocusOut</function>

+event on each window between window A and window C, exclusive,

+with the detail member of each

+<function>XFocusOutEvent</function>

+structure set to  

+<function>NotifyNonlinearVirtual</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>FocusIn</function>

+event on each window between C and B, exclusive,

+with the detail member of each

+<function>XFocusInEvent</function>

+structure set to  

+<function>NotifyNonlinearVirtual</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>FocusIn</function>

+event on window B, with the detail member of the 

+<function>XFocusInEvent</function>

+structure set to  

+<function>NotifyNonlinear</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If window P is an inferior of window B, it generates a

+<function>FocusIn</function>

+event on each window below window B down to and including window P, 

+with the detail member of the 

+<function>XFocusInEvent</function>

+structure set to  

+<function>NotifyPointer</function>.

+<!-- .RE -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+When the focus moves from window A to window B on different screens 

+and the pointer is in window P, 

+the X server does the following:

+<!-- .RS -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If window P is an inferior of window A, it generates a

+<function>FocusOut</function>

+event on each window from window P up to but not including window A, 

+with the detail member of each 

+<function>XFocusOutEvent</function>

+structure set to  

+<function>NotifyPointer</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>FocusOut</function>

+event on window A,

+with the detail member of the

+<function>XFocusOutEvent</function>

+structure set to  

+<function>NotifyNonlinear</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If window A is not a root window,

+it generates a

+<function>FocusOut</function>

+event on each window above window A up to and including its root, 

+with the detail member of each

+<function>XFocusOutEvent</function>

+structure set to  

+<function>NotifyNonlinearVirtual</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If window B is not a root window,

+it generates a

+<function>FocusIn</function>

+event on each window from window B's root down to but not including

+window B, with the detail member of each

+<function>XFocusInEvent</function>

+structure set to  

+<function>NotifyNonlinearVirtual</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>FocusIn</function>

+event on window B, with the detail member of each 

+<function>XFocusInEvent</function>

+structure set to  

+<function>NotifyNonlinear</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If window P is an inferior of window B, it generates a

+<function>FocusIn</function>

+event on each window below window B down to and including window P, 

+with the detail member of each 

+<function>XFocusInEvent</function>

+structure set to  

+<function>NotifyPointer</function>.

+<!-- .RE -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+When the focus moves from window A to 

+<function>PointerRoot</function>

+(events sent to the window under the pointer)

+or

+<function>None </function>

+(discard), and the pointer is in window P,

+the X server does the following:

+<!-- .RS -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If window P is an inferior of window A, it generates a

+<function>FocusOut</function>

+event on each window from window P up to but not including window A, 

+with the detail member of each 

+<function>XFocusOutEvent</function>

+structure set to  

+<function>NotifyPointer</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>FocusOut</function>

+event on window A, with the detail member of the

+<function>XFocusOutEvent</function>

+structure set to

+<function>NotifyNonlinear</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If window A is not a root window,

+it generates a

+<function>FocusOut</function>

+event on each window above window A up to and including its root, 

+with the detail member of each

+<function>XFocusOutEvent</function>

+structure set to

+<function>NotifyNonlinearVirtual</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>FocusIn</function>

+event on the root window of all screens, with the detail member of each

+<function>XFocusInEvent</function>

+structure set to

+<function>NotifyPointerRoot</function>

+(or

+<function>NotifyDetailNone</function>).

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If the new focus is

+<function>PointerRoot</function>,

+it generates a

+<function>FocusIn</function>

+event on each window from window P's root down to and including window P, 

+with the detail member of each

+<function>XFocusInEvent</function>

+structure set to

+<function>NotifyPointer</function>.

+<!-- .RE -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+When the focus moves from 

+<function>PointerRoot</function>

+(events sent to the window under the pointer)

+or

+<function>None </function>

+to window A, and the pointer is in window P, 

+the X server does the following: 

+<!-- .RS -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If the old focus is

+<function>PointerRoot</function>,

+it generates a

+<function>FocusOut</function>

+event on each window from window P up to and including window P's root, 

+with the detail member of each

+<function>XFocusOutEvent</function>

+structure set to

+<function>NotifyPointer</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>FocusOut</function>

+event on all root windows,

+with the detail member of each

+<function>XFocusOutEvent</function>

+structure set to

+<function>NotifyPointerRoot</function>

+(or

+<function>NotifyDetailNone</function>).

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If window A is not a root window,

+it generates a

+<function>FocusIn</function>

+event on each window from window A's root down to but not including window A,

+with the detail member of each

+<function>XFocusInEvent</function>

+structure set to

+<function>NotifyNonlinearVirtual</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>FocusIn</function>

+event on window A,

+with the detail member of the 

+<function>XFocusInEvent</function>

+structure set to  

+<function>NotifyNonlinear</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If window P is an inferior of window A, it generates a

+<function>FocusIn</function>

+event on each window below window A down to and including window P, 

+with the detail member of each 

+<function>XFocusInEvent</function>

+structure set to  

+<function>NotifyPointer</function>.

+<!-- .RE -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+When the focus moves from 

+<function>PointerRoot</function>

+(events sent to the window under the pointer)

+to

+<function>None</function>

+(or vice versa), and the pointer is in window P, 

+the X server does the following:

+<!-- .RS -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If the old focus is

+<function>PointerRoot</function>,

+it generates a

+<function>FocusOut</function>

+event on each window from window P up to and including window P's root, 

+with the detail member of each

+<function>XFocusOutEvent</function>

+structure set to

+<function>NotifyPointer</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>FocusOut</function>

+event on all root windows,

+with the detail member of each 

+<function>XFocusOutEvent</function>

+structure set to either

+<function>NotifyPointerRoot</function>

+or

+<function>NotifyDetailNone</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates a

+<function>FocusIn</function>

+event on all root windows,

+with the detail member of each

+<function>XFocusInEvent</function>

+structure set to

+<function>NotifyDetailNone </function>

+or

+<function>NotifyPointerRoot</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If the new focus is

+<function>PointerRoot</function>,

+it generates a

+<function>FocusIn</function>

+event on each window from window P's root down to and including window P, 

+with the detail member of each

+<function>XFocusInEvent</function>

+structure set to

+<function>NotifyPointer</function>.

+<!-- .RE -->

+<!-- .\".SH 3 -->

+    </para>

+  </listitem>

+</itemizedlist>

+</sect2>

+<sect2 id="Focus_Events_Generated_by_Grabs">

+<title>Focus Events Generated by Grabs</title>

+<!-- .XS -->

+<!-- (SN Focus Events Generated by Grabs  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Focus events in which the keyboard grab activates

+are identified by

+<function>XFocusInEvent</function>

+or

+<function>XFocusOutEvent</function>

+structures whose mode member is set to 

+<function>NotifyGrab</function>.

+Focus events in which the keyboard grab deactivates

+are identified by

+<function>XFocusInEvent</function>

+or

+<function>XFocusOutEvent</function>

+structures whose mode member is set to 

+<function>NotifyUngrab </function>

+(see 

+<function>XGrabKeyboard</function>).

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+When a keyboard grab activates before generating any actual 

+<function>KeyPress</function>

+event that activates the grab,

+G is the grab_window, and F is the current focus, 

+the X server does the following:

+<!-- .RS -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates 

+<function>FocusIn</function>

+and

+<function>FocusOut</function>

+events, with the mode members of the 

+<function>XFocusInEvent</function>

+and

+<function>XFocusOutEvent</function>

+structures set to 

+<function>NotifyGrab</function>.

+These events are generated

+as if the focus were to change from

+F to G.

+<!-- .RE -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+When a keyboard grab deactivates after generating any actual

+<function>KeyRelease</function>

+event that deactivates the grab,

+G is the grab_window, and F is the current focus,

+the X server does the following:

+<!-- .RS -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It generates 

+<function>FocusIn</function>

+and

+<function>FocusOut</function>

+events, with the mode members of the 

+<function>XFocusInEvent</function>

+and

+<function>XFocusOutEvent</function>

+structures set to

+<function>NotifyUngrab</function>.

+These events are generated

+as if the focus were to change from

+G to F.

+<!-- .RE -->

+    </para>

+  </listitem>

+</itemizedlist>

+</sect2>

+</sect1>

+<sect1 id="Key_Map_State_Notification_Events">

+<title>Key Map State Notification Events</title>

+<!-- .XS -->

+<!-- (SN Key Map State Notification Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>KeymapNotify</secondary></indexterm>

+<indexterm significance="preferred"><primary>KeymapNotify</primary></indexterm>

+The X server can report

+<function>KeymapNotify</function>

+events to clients that want information about changes in their keyboard state.

+</para>

+<para>

+<!-- .LP -->

+To receive

+<function>KeymapNotify</function>

+events, set the

+<function>KeymapStateMask</function>

+bit in the event-mask attribute of the window. 

+The X server generates this event immediately after every

+<function>EnterNotify</function>

+and

+<function>FocusIn</function>

+event.

+</para>

+<para>

+<!-- .LP -->

+The structure for this event type contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XKeymapEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+/* generated on EnterWindow and FocusIn when KeymapState selected */

+typedef struct {

+     int            type;           /* KeymapNotify */

+     unsigned long  serial;         /* # of last request processed by server */

+     Bool           send_event;     /* true if this came from a SendEvent request */

+     Display        *display;       /* Display the event was read from */

+     Window         window;

+     char           key_vector[32];

+} XKeymapEvent;     

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The window member is not used but is present to aid some toolkits.

+The key_vector member is set to the bit vector of the keyboard.

+Each bit set to 1 indicates that the corresponding key 

+is currently pressed.

+The vector is represented as 32 bytes.

+Byte N (from 0) contains the bits for keys 8N to 8N + 7 

+with the least significant bit in the byte representing key 8N.

+</para>

+</sect1>

+<sect1 id="Exposure_Events">

+<title>Exposure Events</title>

+<!-- .XS -->

+<!-- (SN Exposure Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The X protocol does not guarantee to preserve the contents of window 

+regions when

+the windows are obscured or reconfigured.

+Some implementations may preserve the contents of windows.

+Other implementations are free to destroy the contents of windows

+when exposed.

+X expects client applications to assume the responsibility for

+restoring the contents of an exposed window region. 

+(An exposed window region describes a formerly obscured window whose 

+region becomes visible.) 

+Therefore, the X server sends 

+<function>Expose </function>

+events describing the window and the region of the window that has been exposed.

+A naive client application usually redraws the entire window. 

+A more sophisticated client application redraws only the exposed region.

+</para>

+<sect2 id="Expose_Events">

+<title>Expose Events</title>

+<!-- .XS -->

+<!-- (SN Expose Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>Expose</secondary></indexterm>

+<indexterm significance="preferred"><primary>Expose</primary></indexterm>

+The X server can report

+<function>Expose</function>

+events to clients wanting information about when the contents of window regions

+have been lost.

+The circumstances in which the X server generates

+<function>Expose</function>

+events are not as definite as those for other events.

+However, the X server never generates

+<function>Expose</function>

+events on windows whose class you specified as

+<function>InputOnly</function>.

+The X server can generate

+<function>Expose</function>

+events when no valid contents are available for regions of a window

+and either the regions are visible, 

+the regions are viewable and the server is (perhaps newly) maintaining 

+backing store on the window,

+or the window is not viewable but the server is (perhaps newly) honoring the

+window's backing-store attribute of

+<function>Always</function>

+or

+<function>WhenMapped</function>.

+The regions decompose into an (arbitrary) set of rectangles,

+and an

+<function>Expose</function>

+event is generated for each rectangle.

+For any given window,

+the X server guarantees to report contiguously 

+all of the regions exposed by some action that causes 

+<function>Expose </function>

+events, such as raising a window.

+</para>

+<para>

+<!-- .LP -->

+To receive

+<function>Expose</function>

+events, set the

+<function>ExposureMask</function>

+bit in the event-mask attribute of the window. 

+</para>

+<para>

+<!-- .LP -->

+The structure for this event type contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XExposeEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;           /* Expose */

+     unsigned long serial;         /* # of last request processed by server */

+     Bool          send_event;     /* true if this came from a SendEvent request */

+     Display       *display;       /* Display the event was read from */

+     Window        window;

+     int           x, y;

+     int           width, height;

+     int           count;          /* if nonzero, at least this many more */

+} XExposeEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The window member is set to the exposed (damaged) window.

+The x and y members are set to the coordinates relative to the window's origin

+and indicate the upper-left corner of the rectangle.

+The width and height members are set to the size (extent) of the rectangle.

+The count member is set to the number of

+<function>Expose</function>

+events that are to follow.

+If count is zero, no more

+<function>Expose</function>

+events follow for this window.

+However, if count is nonzero, at least that number of 

+<function>Expose </function>

+events (and possibly more) follow for this window.

+Simple applications that do not want to optimize redisplay by distinguishing

+between subareas of its window can just ignore all

+<function>Expose</function>

+events with nonzero counts and perform full redisplays

+on events with zero counts.

+</para>

+</sect2>

+<sect2 id="GraphicsExpose_and_NoExpose_Events">

+<title>GraphicsExpose and NoExpose Events</title>

+<!-- .XS -->

+<!-- (SN GraphicsExpose and NoExpose Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>GraphicsExpose</secondary></indexterm>

+<indexterm><primary>Events</primary><secondary>NoExpose</secondary></indexterm>

+<indexterm significance="preferred"><primary>GraphicsExpose</primary></indexterm>

+The X server can report

+<function>GraphicsExpose</function>

+events to clients wanting information about when a destination region could not

+be computed during certain graphics requests:

+<function>XCopyArea</function>

+or

+<function>XCopyPlane</function>.

+The X server generates this event whenever a destination region could not be

+computed because of an obscured or out-of-bounds source region.

+In addition, the X server guarantees to report contiguously all of the regions exposed by

+some graphics request 

+(for example, copying an area of a drawable to a destination

+drawable).

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>NoExpose</primary></indexterm>

+The X server generates a

+<function>NoExpose</function>

+event whenever a graphics request that might

+produce a

+<function>GraphicsExpose</function>

+event does not produce any.

+In other words, the client is really asking for a

+<function>GraphicsExpose</function>

+event but instead receives a

+<function>NoExpose</function>

+event.

+</para>

+<para>

+<!-- .LP -->

+To receive

+<function>GraphicsExpose</function>

+or

+<function>NoExpose</function>

+events, you must first set the graphics-exposure 

+attribute of the graphics context to

+<function>True</function>.

+You also can set the graphics-expose attribute when creating a graphics

+context using

+<function>XCreateGC </function>

+or by calling

+<function>XSetGraphicsExposures</function>.

+</para>

+<para>

+<!-- .LP -->

+The structures for these event types contain:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XGraphicsExposeEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int            type;           /* GraphicsExpose */

+     unsigned long  serial;         /* # of last request processed by server */

+     Bool           send_event;     /* true if this came from a SendEvent request */

+     Display        *display;       /* Display the event was read from */

+     Drawable       drawable;

+     int            x, y;

+     int            width, height;

+     int            count;          /* if nonzero, at least this many more */

+     int            major_code;     /* core is CopyArea or CopyPlane */

+     int            minor_code;     /* not defined in the core */

+} XGraphicsExposeEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XNoExposeEvent</primary></indexterm>

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;         /* NoExpose */

+     unsigned long serial;       /* # of last request processed by server */

+     Bool          send_event;   /* true if this came from a SendEvent request */

+     Display       *display;     /* Display the event was read from */

+     Drawable      drawable;

+     int           major_code;   /* core is CopyArea or CopyPlane */

+     int           minor_code;   /* not defined in the core */

+} XNoExposeEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Both structures have these common members: drawable, major_code, and minor_code.

+The drawable member is set to the drawable of the destination region on 

+which the graphics request was to be performed.

+The major_code member is set to the graphics request initiated by the client

+and can be either

+<function>X_CopyArea</function>

+or

+<function>X_CopyPlane</function>.

+If it is

+<function>X_CopyArea</function>,

+a call to

+<function>XCopyArea</function>

+initiated the request.

+If it is

+<function>X_CopyPlane</function>,

+a call to

+<function>XCopyPlane</function>

+initiated the request.

+These constants are defined in 

+<!-- .hN X11/Xproto.h . -->

+The minor_code member,

+like the major_code member, 

+indicates which graphics request was initiated by

+the client. 

+However, the minor_code member is not defined by the core

+X protocol and will be zero in these cases, 

+although it may be used by an extension.

+</para>

+<para>

+<!-- .LP -->

+The 

+<function>XGraphicsExposeEvent</function>

+structure has these additional members: x, y, width, height, and count. 

+The x and y members are set to the coordinates relative to the drawable's origin

+and indicate the upper-left corner of the rectangle.

+The width and height members are set to the size (extent) of the rectangle.

+The count member is set to the number of

+<function>GraphicsExpose</function>

+events to follow.

+If count is zero, no more

+<function>GraphicsExpose</function>

+events follow for this window.

+However, if count is nonzero, at least that number of

+<function>GraphicsExpose</function>

+events (and possibly more) are to follow for this window.

+</para>

+</sect2>

+</sect1>

+<sect1 id="Window_State_Change_Events_">

+<title>Window State Change Events </title>

+<!-- .XS -->

+<!-- (SN Window State Change Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The following sections discuss:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+<function>CirculateNotify</function>

+events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>ConfigureNotify</function>

+events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>CreateNotify </function>

+events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>DestroyNotify</function>

+events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>GravityNotify</function>

+events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>MapNotify</function>

+events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>MappingNotify</function>

+events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>ReparentNotify </function>

+events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>UnmapNotify</function>

+events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>VisibilityNotify</function>

+events

+<!-- .\" .SH 3 -->

+    </para>

+  </listitem>

+</itemizedlist>

+<sect2 id="CirculateNotify_Events">

+<title>CirculateNotify Events</title>

+<!-- .XS -->

+<!-- (SN CirculateNotify Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>CirculateNotify</secondary></indexterm>

+<indexterm significance="preferred"><primary>CirculateNotify</primary></indexterm>

+The X server can report

+<function>CirculateNotify</function>

+events to clients wanting information about when a window changes 

+its position in the stack.

+The X server generates this event type whenever a window is actually restacked 

+as a result of a client application calling

+<function>XCirculateSubwindows</function>,

+<function>XCirculateSubwindowsUp</function>,

+or

+<function>XCirculateSubwindowsDown</function>.

+</para>

+<para>

+<!-- .LP -->

+To receive 

+<function>CirculateNotify</function>

+events, set the

+<function>StructureNotifyMask</function>

+bit in the event-mask attribute of the window

+or the

+<function>SubstructureNotifyMask</function>

+bit in the event-mask attribute of the parent window

+(in which case, circulating any child generates an event).

+</para>

+<para>

+<!-- .LP -->

+The structure for this event type contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XCirculateEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int type;     /* CirculateNotify */

+     unsigned long serial;     /* # of last request processed by server */

+     Bool send_event;     /* true if this came from a SendEvent request */

+     Display *display;     /* Display the event was read from */

+     Window event;

+     Window window;

+     int place;     /* PlaceOnTop, PlaceOnBottom */

+} XCirculateEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The event member is set either to the restacked window or to its parent,

+depending on whether

+<function>StructureNotify</function>

+or

+<function>SubstructureNotify</function>

+was selected.

+The window member is set to the window that was restacked.

+The place member is set to the window's position after the restack occurs and

+is either

+<function>PlaceOnTop</function>

+or

+<function>PlaceOnBottom</function>.

+If it is

+<function>PlaceOnTop</function>,

+the window is now on top of all siblings.

+If it is

+<function>PlaceOnBottom</function>,

+the window is now below all siblings.

+</para>

+</sect2>

+<sect2 id="ConfigureNotify_Events">

+<title>ConfigureNotify Events</title>

+<!-- .XS -->

+<!-- (SN ConfigureNotify Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>ConfigureNotify</secondary></indexterm>

+<indexterm significance="preferred"><primary>ConfigureNotify</primary></indexterm>

+The X server can report

+<function>ConfigureNotify</function>

+events to clients wanting information about actual changes to a window's

+state, such as size, position, border, and stacking order.

+The X server generates this event type whenever one of the following configure 

+window requests made by a client application actually completes:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+A window's size, position, border, and/or stacking order is reconfigured 

+by calling

+<function>XConfigureWindow</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The window's position in the stacking order is changed by calling

+<function>XLowerWindow</function>,

+<function>XRaiseWindow</function>,

+or

+<function>XRestackWindows</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A window is moved by calling

+<function>XMoveWindow</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A window's size is changed by calling

+<function>XResizeWindow</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A window's size and location is changed by calling

+<function>XMoveResizeWindow</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A window is mapped and its position in the stacking order is changed

+by calling

+<function>XMapRaised</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A window's border width is changed by calling

+<function>XSetWindowBorderWidth</function>.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+To receive 

+<function>ConfigureNotify</function>

+events, set the

+<function>StructureNotifyMask</function>

+bit in the event-mask attribute of the window or the

+<function>SubstructureNotifyMask</function>

+bit in the event-mask attribute of the parent window

+(in which case, configuring any child generates an event).

+</para>

+<para>

+<!-- .LP -->

+The structure for this event type contains:

+</para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XConfigureEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;       /* ConfigureNotify */

+     unsigned long serial;     /* # of last request processed by server */

+     Bool          send_event; /* true if this came from a SendEvent request */

+     Display       *display;   /* Display the event was read from */

+     Window        event;

+     Window        window;

+     int           x, y;

+     int           width, height;

+     int           border_width;

+     Window        above;

+     Bool          override_redirect;

+} XConfigureEvent;

+</literallayout>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The event member is set either to the reconfigured window or to its parent,

+depending on whether

+<function>StructureNotify</function>

+or

+<function>SubstructureNotify</function>

+was selected.

+The window member is set to the window whose size, position, 

+border, and/or stacking

+order was changed.

+</para>

+<para>

+<!-- .LP -->

+The x and y members are set to the coordinates relative to the parent window's 

+origin and indicate the position of the upper-left outside corner of the window.

+The width and height members are set to the inside size of the window, 

+not including

+the border.

+The border_width member is set to the width of the window's border, in pixels.

+</para>

+<para>

+<!-- .LP -->

+The above member is set to the sibling window and is used 

+for stacking operations.

+If the X server sets this member to

+<function>None</function>,

+the window whose state was changed is on the bottom of the stack

+with respect to sibling windows.

+However, if this member is set to a sibling window, 

+the window whose state was changed is placed on top of this sibling window.

+</para>

+<para>

+<!-- .LP -->

+The override_redirect member is set to the override-redirect attribute of the

+window.

+Window manager clients normally should ignore this window if the 

+override_redirect member

+is

+<function>True</function>.

+</para>

+</sect2>

+<sect2 id="CreateNotify_Events">

+<title>CreateNotify Events</title>

+<!-- .XS -->

+<!-- (SN CreateNotify Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>CreateNotify</secondary></indexterm>

+<indexterm significance="preferred"><primary>CreateNotify</primary></indexterm>

+The X server can report

+<function>CreateNotify</function>

+events to clients wanting information about creation of windows.

+The X server generates this event whenever a client

+application creates a window by calling

+<function>XCreateWindow</function>

+or

+<function>XCreateSimpleWindow</function>.

+</para>

+<para>

+<!-- .LP -->

+To receive 

+<function>CreateNotify</function>

+events, set the

+<function>SubstructureNotifyMask</function>

+bit in the event-mask attribute of the window.

+Creating any children then generates an event.

+</para>

+<para>

+<!-- .LP -->

+The structure for the event type contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XCreateWindowEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;               /* CreateNotify */

+     unsigned long serial;             /* # of last request processed by server */

+     Bool          send_event;         /* true if this came from a SendEvent request */

+     Display       *display;           /* Display the event was read from */

+     Window        parent;             /* parent of the window */

+     Window        window;             /* window id of window created */

+     int           x, y;               /* window location */

+     int           width, height;      /* size of window */

+     int           border_width;       /* border width */

+     Bool          override_redirect;  /* creation should be overridden */

+} XCreateWindowEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The parent member is set to the created window's parent.

+The window member specifies the created window.

+The x and y members are set to the created window's coordinates relative 

+to the parent window's origin and indicate the position of the upper-left 

+outside corner of the created window.

+The width and height members are set to the inside size of the created window 

+(not including the border) and are always nonzero.

+The border_width member is set to the width of the created window's border, in pixels.

+The override_redirect member is set to the override-redirect attribute of the

+window.

+Window manager clients normally should ignore this window 

+if the override_redirect member is

+<function>True</function>.

+</para>

+</sect2>

+<sect2 id="DestroyNotify_Events">

+<title>DestroyNotify Events</title>

+<!-- .XS -->

+<!-- (SN DestroyNotify Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>DestroyNotify</secondary></indexterm>

+<indexterm significance="preferred"><primary>DestroyNotify</primary></indexterm>

+The X server can report

+<function>DestroyNotify</function>

+events to clients wanting information about which windows are destroyed.

+The X server generates this event whenever a client application destroys a 

+window by calling

+<function>XDestroyWindow</function>

+or

+<function>XDestroySubwindows</function>.

+</para>

+<para>

+<!-- .LP -->

+The ordering of the 

+<function>DestroyNotify </function>

+events is such that for any given window, 

+<function>DestroyNotify</function>

+is generated on all inferiors of the window

+before being generated on the window itself.  

+The X protocol does not constrain the ordering among

+siblings and across subhierarchies.

+</para>

+<para>

+<!-- .LP -->

+To receive 

+<function>DestroyNotify</function>

+events, set the

+<function>StructureNotifyMask</function>

+bit in the event-mask attribute of the window or the

+<function>SubstructureNotifyMask</function>

+bit in the event-mask attribute of the parent window

+(in which case, destroying any child generates an event).

+</para>

+<para>

+<!-- .LP -->

+The structure for this event type contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XDestroyWindowEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;       /* DestroyNotify */

+     unsigned long serial;     /* # of last request processed by server */

+     Bool          send_event; /* true if this came from a SendEvent request */

+     Display       *display;   /* Display the event was read from */

+     Window        event;

+     Window        window;

+} XDestroyWindowEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The event member is set either to the destroyed window or to its parent,

+depending on whether

+<function>StructureNotify</function>

+or 

+<function>SubstructureNotify</function>

+was selected.

+The window member is set to the window that is destroyed.

+</para>

+</sect2>

+<sect2 id="GravityNotify_Events">

+<title>GravityNotify Events</title>

+<!-- .XS -->

+<!-- (SN GravityNotify Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>GravityNotify</secondary></indexterm>

+<indexterm significance="preferred"><primary>GravityNotify</primary></indexterm>

+The X server can report

+<function>GravityNotify</function>

+events to clients wanting information about when a window is moved because of a

+change in the size of its parent.

+The X server generates this event whenever a client

+application actually moves a child window as a result of resizing its parent by calling

+<function>XConfigureWindow</function>,

+<function>XMoveResizeWindow</function>,

+or

+<function>XResizeWindow</function>.

+</para>

+<para>

+<!-- .LP -->

+To receive 

+<function>GravityNotify</function>

+events, set the

+<function>StructureNotifyMask</function>

+bit in the event-mask attribute of the window or the

+<function>SubstructureNotifyMask</function>

+bit in the event-mask attribute of the parent window

+(in which case, any child that is moved because its parent has been resized

+generates an event).

+</para>

+<para>

+<!-- .LP -->

+The structure for this event type contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XGravityEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;       /* GravityNotify */

+     unsigned long serial;     /* # of last request processed by server */

+     Bool          send_event; /* true if this came from a SendEvent request */

+     Display       *display;   /* Display the event was read from */

+     Window        event;

+     Window        window;

+     int           x, y;

+} XGravityEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The event member is set either to the window that was moved or to its parent,

+depending on whether

+<function>StructureNotify</function>

+or

+<function>SubstructureNotify</function>

+was selected.

+The window member is set to the child window that was moved.

+The x and y members are set to the coordinates relative to the 

+new parent window's origin

+and indicate the position of the upper-left outside corner of the 

+window.

+</para>

+</sect2>

+<sect2 id="MapNotify_Events">

+<title>MapNotify Events</title>

+<!-- .XS -->

+<!-- (SN MapNotify Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>MapNotify</secondary></indexterm>

+<indexterm significance="preferred"><primary>MapNotify</primary></indexterm>

+The X server can report

+<function>MapNotify</function>

+events to clients wanting information about which windows are mapped.

+The X server generates this event type whenever a client application changes the

+window's state from unmapped to mapped by calling

+<function>XMapWindow</function>,

+<function>XMapRaised</function>,

+<function>XMapSubwindows</function>,

+<function>XReparentWindow</function>,

+or as a result of save-set processing.

+</para>

+<para>

+<!-- .LP -->

+To receive 

+<function>MapNotify</function>

+events, set the

+<function>StructureNotifyMask</function>

+bit in the event-mask attribute of the window or the

+<function>SubstructureNotifyMask</function>

+bit in the event-mask attribute of the parent window

+(in which case, mapping any child generates an event).

+</para>

+<para>

+<!-- .LP -->

+The structure for this event type contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XMapEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;                  /* MapNotify */

+     unsigned long serial;                /* # of last request processed by server */

+     Bool          send_event;            /* true if this came from a SendEvent request */

+     Display       *display;              /* Display the event was read from */

+     Window        event;

+     Window        window;

+     Bool          override_redirect;     /* boolean, is override set... */

+} XMapEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The event member is set either to the window that was mapped or to its parent,

+depending on whether

+<function>StructureNotify</function>

+or

+<function>SubstructureNotify</function>

+was selected.

+The window member is set to the window that was mapped.

+The override_redirect member is set to the override-redirect attribute

+of the window.

+Window manager clients normally should ignore this window 

+if the override-redirect attribute is

+<function>True</function>,

+because these events usually are generated from pop-ups,

+which override structure control.

+</para>

+</sect2>

+<sect2 id="MappingNotify_Events">

+<title>MappingNotify Events</title>

+<!-- .XS -->

+<!-- (SN MappingNotify Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>MappingNotify</secondary></indexterm>

+<indexterm significance="preferred"><primary>MappingNotify</primary></indexterm>

+The X server reports

+<function>MappingNotify</function>

+events to all clients.

+There is no mechanism to express disinterest in this event.

+The X server generates this event type whenever a client application 

+successfully calls:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+<function>XSetModifierMapping</function>

+to indicate which KeyCodes are to be used as modifiers

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XChangeKeyboardMapping</function>

+to change the keyboard mapping

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XSetPointerMapping</function>

+to set the pointer mapping

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+The structure for this event type contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XMappingEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;           /* MappingNotify */

+     unsigned long serial;         /* # of last request processed by server */

+     Bool          send_event;     /* true if this came from a SendEvent request */

+     Display       *display;       /* Display the event was read from */

+     Window        window;         /* unused */

+     int           request;        /* one of MappingModifier, MappingKeyboard,

+                   MappingPointer  */

+     int           first_keycode;  /* first keycode */

+     int           count;          /* defines range of change w. first_keycode*/

+} XMappingEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The request member is set to indicate the kind of mapping change that occurred

+and can be

+<function>MappingModifier</function>,

+<function>MappingKeyboard</function>,

+or

+<function>MappingPointer</function>.

+If it is

+<function>MappingModifier</function>,

+the modifier mapping was changed.

+If it is

+<function>MappingKeyboard</function>,

+the keyboard mapping was changed.

+If it is

+<function>MappingPointer</function>,

+the pointer button mapping was changed. 

+The first_keycode and count members are set only 

+if the request member was set to

+<function>MappingKeyboard</function>.

+The number in first_keycode represents the first number in the range 

+of the altered mapping, 

+and count represents the number of keycodes altered.

+</para>

+<para>

+<!-- .LP -->

+To update the client application's knowledge of the keyboard,

+you should call

+<function>XRefreshKeyboardMapping</function>.

+</para>

+</sect2>

+<sect2 id="ReparentNotify_Events">

+<title>ReparentNotify Events</title>

+<!-- .XS -->

+<!-- (SN ReparentNotify Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>ReparentNotify</secondary></indexterm>

+<indexterm significance="preferred"><primary>ReparentNotify</primary></indexterm>

+The X server can report

+<function>ReparentNotify</function>

+events to clients wanting information about changing a window's parent.

+The X server generates this event whenever a client

+application calls

+<function>XReparentWindow </function>

+and the window is actually reparented.

+</para>

+<para>

+<!-- .LP -->

+To receive 

+<function>ReparentNotify</function>

+events, set the

+<function>StructureNotifyMask</function>

+bit in the event-mask attribute of the window or the

+<function>SubstructureNotifyMask</function>

+bit in the event-mask attribute of either the old or the new parent window

+(in which case, reparenting any child generates an event).

+</para>

+<para>

+<!-- .LP -->

+The structure for this event type contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XReparentEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;       /* ReparentNotify */

+     unsigned long serial;     /* # of last request processed by server */

+     Bool          send_event; /* true if this came from a SendEvent request */

+     Display       *display;   /* Display the event was read from */

+     Window        event;

+     Window        window;

+     Window        parent;

+     int           x, y;

+     Bool          override_redirect;

+} XReparentEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The event member is set either to the reparented window

+or to the old or the new parent, depending on whether

+<function>StructureNotify</function>

+or

+<function>SubstructureNotify</function>

+was selected. 

+The window member is set to the window that was reparented.

+The parent member is set to the new parent window.

+The x and y members are set to the reparented window's coordinates relative 

+to the new parent window's

+origin and define the upper-left outer corner of the reparented window.

+The override_redirect member is set to the override-redirect attribute of the

+window specified by the window member.

+Window manager clients normally should ignore this window 

+if the override_redirect member is

+<function>True</function>.

+</para>

+</sect2>

+<sect2 id="UnmapNotify_Events">

+<title>UnmapNotify Events</title>

+<!-- .XS -->

+<!-- (SN UnmapNotify Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>UnmapNotify</secondary></indexterm>

+<indexterm significance="preferred"><primary>UnmapNotify</primary></indexterm>

+The X server can report

+<function>UnmapNotify</function>

+events to clients wanting information about which windows are unmapped.

+The X server generates this event type whenever a client application changes the

+window's state from mapped to unmapped.

+</para>

+<para>

+<!-- .LP -->

+To receive 

+<function>UnmapNotify</function>

+events, set the

+<function>StructureNotifyMask</function>

+bit in the event-mask attribute of the window or the

+<function>SubstructureNotifyMask</function>

+bit in the event-mask attribute of the parent window

+(in which case, unmapping any child window generates an event).

+</para>

+<para>

+<!-- .LP -->

+The structure for this event type contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XUnmapEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;       /* UnmapNotify */

+     unsigned long serial;     /* # of last request processed by server */

+     Bool          send_event; /* true if this came from a SendEvent request */

+     Display       *display;   /* Display the event was read from */

+     Window        event;

+     Window        window;

+     Bool          from_configure;

+} XUnmapEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The event member is set either to the unmapped window or to its parent,

+depending on whether

+<function>StructureNotify</function>

+or

+<function>SubstructureNotify</function>

+was selected.

+This is the window used by the X server to report the event.

+The window member is set to the window that was unmapped.

+The from_configure member is set to

+<function>True </function>

+if the event was generated as a result of a resizing of the window's parent when

+the window itself had a win_gravity of

+<function>UnmapGravity</function>.

+</para>

+</sect2>

+<sect2 id="VisibilityNotify_Events">

+<title>VisibilityNotify Events</title>

+<!-- .XS -->

+<!-- (SN VisibilityNotify Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>VisibilityNotify</secondary></indexterm>

+<indexterm significance="preferred"><primary>VisibilityNotify</primary></indexterm>

+The X server can report

+<function>VisibilityNotify</function>

+events to clients wanting any change in the visibility of the specified window.

+A region of a window is visible if someone looking at the screen can

+actually see it.

+The X server generates this event whenever the visibility changes state. 

+However, this event is never generated for windows whose class is

+<function>InputOnly</function>.

+</para>

+<para>

+<!-- .LP -->

+All 

+<function>VisibilityNotify</function>

+events caused by a hierarchy change are generated

+after any hierarchy event

+(<function>UnmapNotify</function>,

+<function>MapNotify</function>,

+<function>ConfigureNotify</function>,

+<function>GravityNotify</function>,

+<function>CirculateNotify</function>)

+caused by that change.  Any

+<function>VisibilityNotify</function>

+event on a given window is generated before any

+<function>Expose </function>

+events on that window, but it is not required that all

+<function>VisibilityNotify</function>

+events on all windows be generated before all 

+<function>Expose</function>

+events on all windows.  

+The X protocol does not constrain the ordering of 

+<function>VisibilityNotify</function>

+events with

+respect to 

+<function>FocusOut</function>,

+<function>EnterNotify</function>,

+and 

+<function>LeaveNotify</function>

+events.

+</para>

+<para>

+<!-- .LP -->

+To receive 

+<function>VisibilityNotify</function>

+events, set the

+<function>VisibilityChangeMask</function>

+bit in the event-mask attribute of the window. 

+</para>

+<para>

+<!-- .LP -->

+The structure for this event type contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XVisibilityEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;       /* VisibilityNotify */

+     unsigned long serial;     /* # of last request processed by server */

+     Bool          send_event; /* true if this came from a SendEvent request */

+     Display       *display;   /* Display the event was read from */

+     Window        window;

+     int           state;

+} XVisibilityEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The window member is set to the window whose visibility state changes.

+The state member is set to the state of the window's visibility and can be

+<function>VisibilityUnobscured</function>,

+<function>VisibilityPartiallyObscured</function>,

+or

+<function>VisibilityFullyObscured</function>.

+The X server ignores all of a window's subwindows

+when determining the visibility state of the window and processes 

+<function>VisibilityNotify</function>

+events according to the following:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+When the window changes state from partially obscured, fully obscured,

+or not viewable to viewable and completely unobscured,

+the X server generates the event with the state member of the

+<function>XVisibilityEvent</function>

+structure set to

+<function>VisibilityUnobscured</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+When the window changes state from viewable and completely unobscured or 

+not viewable to viewable and partially obscured,

+the X server generates the event with the state member of the

+<function>XVisibilityEvent</function>

+structure set to

+<function>VisibilityPartiallyObscured</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+When the window changes state from viewable and completely unobscured, 

+viewable and partially obscured, or not viewable to viewable and 

+fully obscured,

+the X server generates the event with the state member of the

+<function>XVisibilityEvent</function>

+structure set to

+<function>VisibilityFullyObscured</function>.

+    </para>

+  </listitem>

+</itemizedlist>

+</sect2>

+</sect1>

+<sect1 id="Structure_Control_Events">

+<title>Structure Control Events</title>

+<!-- .XS -->

+<!-- (SN Structure Control Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+This section discusses:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+<function>CirculateRequest</function>

+events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>ConfigureRequest</function>

+events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>MapRequest </function>

+events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>ResizeRequest </function>

+events

+    </para>

+  </listitem>

+</itemizedlist>

+<sect2 id="CirculateRequest_Events">

+<title>CirculateRequest Events</title>

+<!-- .XS -->

+<!-- (SN CirculateRequest Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>CirculateRequest</secondary></indexterm>

+<indexterm significance="preferred"><primary>CirculateRequest</primary></indexterm>

+The X server can report

+<function>CirculateRequest</function>

+events to clients wanting information about 

+when another client initiates a circulate window request 

+on a specified window.

+The X server generates this event type whenever a client initiates a circulate

+window request on a window and a subwindow actually needs to be restacked. 

+The client initiates a circulate window request on the window by calling

+<function>XCirculateSubwindows</function>,

+<function>XCirculateSubwindowsUp</function>,

+or

+<function>XCirculateSubwindowsDown</function>.

+</para>

+<para>

+<!-- .LP -->

+To receive

+<function>CirculateRequest</function>

+events, set the

+<function>SubstructureRedirectMask</function>

+in the event-mask attribute of the window. 

+Then, in the future,

+the circulate window request for the specified window is not executed,

+and thus, any subwindow's position in the stack is not changed.

+For example, suppose a client application calls

+<function>XCirculateSubwindowsUp</function>

+to raise a subwindow to the top of the stack.

+If you had selected

+<function>SubstructureRedirectMask</function>

+on the window, the X server reports to you a

+<function>CirculateRequest</function>

+event and does not raise the subwindow to the top of the stack.

+</para>

+<para>

+<!-- .LP -->

+The structure for this event type contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XCirculateRequestEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;       /* CirculateRequest */

+     unsigned long serial;     /* # of last request processed by server */

+     Bool          send_event; /* true if this came from a SendEvent request */

+     Display       *display;   /* Display the event was read from */

+     Window        parent;

+     Window        window;

+     int place;                /* PlaceOnTop, PlaceOnBottom */

+} XCirculateRequestEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The parent member is set to the parent window.

+The window member is set to the subwindow to be restacked.

+The place member is set to what the new position in the stacking order should be

+and is either

+<function>PlaceOnTop</function>

+or

+<function>PlaceOnBottom</function>.

+If it is

+<function>PlaceOnTop</function>,

+the subwindow should be on top of all siblings.

+If it is

+<function>PlaceOnBottom</function>,

+the subwindow should be below all siblings.

+</para>

+</sect2>

+<sect2 id="ConfigureRequest_Events">

+<title>ConfigureRequest Events</title>

+<!-- .XS -->

+<!-- (SN ConfigureRequest Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>ConfigureRequest</secondary></indexterm>

+<indexterm significance="preferred"><primary>ConfigureRequest</primary></indexterm>

+The X server can report

+<function>ConfigureRequest</function>

+events to clients wanting information about when a different client initiates 

+a configure window request on any child of a specified window. 

+The configure window request attempts to 

+reconfigure a window's size, position, border, and stacking order.

+The X server generates this event whenever a different client initiates

+a configure window request on a window by calling

+<function>XConfigureWindow</function>,

+<function>XLowerWindow</function>,

+<function>XRaiseWindow</function>,

+<function>XMapRaised</function>,

+<function>XMoveResizeWindow</function>,

+<function>XMoveWindow</function>,

+<function>XResizeWindow</function>,

+<function>XRestackWindows</function>,

+or

+<function>XSetWindowBorderWidth</function>.

+</para>

+<para>

+<!-- .LP -->

+To receive

+<function>ConfigureRequest</function>

+events, set the

+<function>SubstructureRedirectMask</function>

+bit in the event-mask attribute of the window. 

+<function>ConfigureRequest</function>

+events are generated when a

+<function>ConfigureWindow</function>

+protocol request is issued on a child window by another client.

+For example, suppose a client application calls

+<function>XLowerWindow</function>

+to lower a window.

+If you had selected

+<function>SubstructureRedirectMask </function>

+on the parent window and if the override-redirect attribute 

+of the window is set to

+<function>False</function>,

+the X server reports a

+<function>ConfigureRequest</function>

+event to you and does not lower the specified window.

+</para>

+<para>

+<!-- .LP -->

+The structure for this event type contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XConfigureRequestEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;         /* ConfigureRequest */

+     unsigned long serial;       /* # of last request processed by server */

+     Bool          send_event;   /* true if this came from a SendEvent request */

+     Display       *display;     /* Display the event was read from */

+     Window        parent;

+     Window        window;

+     int           x, y;

+     int           width, height;

+     int           border_width;

+     Window        above;

+     int           detail;       /* Above, Below, TopIf, BottomIf, Opposite */

+     unsigned long value_mask;

+} XConfigureRequestEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The parent member is set to the parent window.

+The window member is set to the window whose size, position, border width, 

+and/or stacking order is to be reconfigured.

+The value_mask member indicates which components were specified in the

+<function>ConfigureWindow </function>

+protocol request.

+The corresponding values are reported as given in the request.

+The remaining values are filled in from the current geometry of the window,

+except in the case of above (sibling) and detail (stack-mode),

+which are reported as

+<function>None</function>

+and

+<function>Above</function>,

+respectively, if they are not given in the request.

+</para>

+</sect2>

+<sect2 id="MapRequest_Events">

+<title>MapRequest Events</title>

+<!-- .XS -->

+<!-- (SN MapRequest Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>MapRequest</secondary></indexterm>

+<indexterm significance="preferred"><primary>MapRequest</primary></indexterm>

+The X server can report

+<function>MapRequest</function>

+events to clients wanting information about a different client's desire 

+to map windows.

+A window is considered mapped when a map window request completes.

+The X server generates this event whenever a different client initiates 

+a map window request on an unmapped window whose override_redirect member 

+is set to

+<function>False</function>.

+Clients initiate map window requests by calling

+<function>XMapWindow</function>,

+<function>XMapRaised</function>,

+or

+<function>XMapSubwindows</function>.

+</para>

+<para>

+<!-- .LP -->

+To receive

+<function>MapRequest</function>

+events, set the

+<function>SubstructureRedirectMask</function>

+bit in the event-mask attribute of the window. 

+This means another client's attempts to map a child window by calling one of

+the map window request functions is intercepted, and you are sent a 

+<function>MapRequest</function>

+instead.

+For example, suppose a client application calls

+<function>XMapWindow</function>

+to map a window.

+If you (usually a window manager) had selected

+<function>SubstructureRedirectMask </function>

+on the parent window and if the override-redirect attribute 

+of the window is set to

+<function>False</function>,

+the X server reports a

+<function>MapRequest</function>

+event to you 

+and does not map the specified window.

+Thus, this event gives your window manager client the ability 

+to control the placement of subwindows.

+</para>

+<para>

+<!-- .LP -->

+The structure for this event type contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XMapRequestEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;       /* MapRequest */

+     unsigned long serial;     /* # of last request processed by server */

+     Bool          send_event; /* true if this came from a SendEvent request */

+     Display       *display;   /* Display the event was read from */

+     Window        parent;

+     Window        window;

+} XMapRequestEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The parent member is set to the parent window.

+The window member is set to the window to be mapped.

+</para>

+</sect2>

+<sect2 id="ResizeRequest_Events">

+<title>ResizeRequest Events</title>

+<!-- .XS -->

+<!-- (SN ResizeRequest Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>ResizeRequest</secondary></indexterm>

+<indexterm significance="preferred"><primary>ResizeRequest</primary></indexterm>

+The X server can report

+<function>ResizeRequest</function>

+events to clients wanting information about another client's attempts to change the

+size of a window.

+The X server generates this event whenever some other client attempts to change

+the size of the specified window by calling

+<function>XConfigureWindow</function>,

+<function>XResizeWindow</function>,

+or

+<function>XMoveResizeWindow</function>.

+</para>

+<para>

+<!-- .LP -->

+To receive

+<function>ResizeRequest</function>

+events, set the

+<function>ResizeRedirect</function>

+bit in the event-mask attribute of the window. 

+Any attempts to change the size by other clients are then redirected.

+</para>

+<para>

+<!-- .LP -->

+The structure for this event type contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XResizeRequestEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;        /* ResizeRequest */

+     unsigned long serial;      /* # of last request processed by server */

+     Bool          send_event;  /* true if this came from a SendEvent request */

+     Display       *display;    /* Display the event was read from */

+     Window        window;

+     int           width, height;

+} XResizeRequestEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The window member is set to the window whose size another 

+client attempted to change.

+The width and height members are set to the inside size of the window, 

+excluding the border.

+</para>

+</sect2>

+</sect1>

+<sect1 id="Colormap_State_Change_Events">

+<title>Colormap State Change Events</title>

+<!-- .XS -->

+<!-- (SN Colormap State Change Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>ColormapNotify</secondary></indexterm>

+<indexterm significance="preferred"><primary>ColormapNotify</primary></indexterm>

+The X server can report

+<function>ColormapNotify</function>

+events to clients wanting information about when the colormap changes 

+and when a colormap is installed or uninstalled. 

+The X server generates this event type whenever a client application:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Changes the colormap member of the

+<function>XSetWindowAttributes</function>

+structure by 

+calling

+<function>XChangeWindowAttributes</function>,

+<function>XFreeColormap</function>,

+or

+<function>XSetWindowColormap </function>

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Installs or uninstalls the colormap by calling

+<function>XInstallColormap</function>

+or

+<function>XUninstallColormap </function>

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+To receive 

+<function>ColormapNotify </function>

+events, set the

+<function>ColormapChangeMask</function>

+bit in the event-mask attribute of the window. 

+</para>

+<para>

+<!-- .LP -->

+The structure for this event type contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XColormapEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;       /* ColormapNotify */

+     unsigned long serial;     /* # of last request processed by server */

+     Bool          send_event; /* true if this came from a SendEvent request */

+     Display       *display;   /* Display the event was read from */

+     Window        window;

+     Colormap      colormap;   /* colormap or None */

+     Bool          new;

+     int           state;      /* ColormapInstalled, ColormapUninstalled */

+} XColormapEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The window member is set to the window whose associated 

+colormap is changed, installed, or uninstalled.

+For a colormap that is changed, installed, or uninstalled,

+the colormap member is set to the colormap associated with the window. 

+For a colormap that is changed by a call to

+<function>XFreeColormap</function>,

+the colormap member is set to

+<function>None</function>.

+The new member is set to indicate whether the colormap 

+for the specified window was changed or installed or uninstalled

+and can be 

+<function>True</function>

+or

+<function>False</function>.

+If it is

+<function>True</function>,

+the colormap was changed.

+If it is

+<function>False</function>,

+the colormap was installed or uninstalled.

+The state member is always set to indicate whether the colormap is installed or

+uninstalled and can be 

+<function>ColormapInstalled</function>

+or

+<function>ColormapUninstalled</function>.

+</para>

+</sect1>

+<sect1 id="Client_Communication_Events">

+<title>Client Communication Events</title>

+<!-- .XS -->

+<!-- (SN Client Communication Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+This section discusses:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+<function>ClientMessage </function>

+events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>PropertyNotify</function>

+events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>SelectionClear</function>

+events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>SelectionNotify</function>

+events

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>SelectionRequest</function>

+events

+    </para>

+  </listitem>

+</itemizedlist>

+<sect2 id="ClientMessage_Events">

+<title>ClientMessage Events</title>

+<!-- .XS -->

+<!-- (SN ClientMessage Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>ClientMessage</secondary></indexterm>

+<indexterm significance="preferred"><primary>ClientMessage</primary></indexterm>

+The X server generates

+<function>ClientMessage</function>

+events only when a client calls the function

+<function>XSendEvent</function>.

+</para>

+<para>

+<!-- .LP -->

+The structure for this event type contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XClientMessageEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 1i 3i -->

+<!-- .ta .5i 1i 3i -->

+typedef struct {

+     int           type;           /* ClientMessage */

+     unsigned long serial;         /* # of last request processed by server */

+     Bool          send_event;     /* true if this came from a SendEvent request */

+     Display       *display;       /* Display the event was read from */

+     Window        window;

+     Atom          message_type;

+     int           format;

+     union         {

+                     char  b[20];

+                     short s[10];

+                     long  l[5];

+                   } data;

+} XClientMessageEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The message_type member is set to an atom that indicates how the data 

+should be interpreted by the receiving client.

+The format member is set to 8, 16, or 32 and specifies whether the data

+should be viewed as a list of bytes, shorts, or longs.

+The data member is a union that contains the members b, s, and l.

+The b, s, and l members represent data of twenty 8-bit values, 

+ten 16-bit values, and five 32-bit values.

+Particular message types might not make use of all these values.

+The X server places no interpretation on the values in the window,

+message_type, or data members.

+</para>

+</sect2>

+<sect2 id="PropertyNotify_Events">

+<title>PropertyNotify Events</title>

+<!-- .XS -->

+<!-- (SN PropertyNotify Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>PropertyNotify</secondary></indexterm>

+<indexterm significance="preferred"><primary>PropertyNotify</primary></indexterm>

+The X server can report

+<function>PropertyNotify</function>

+events to clients wanting information about property changes 

+for a specified window.

+</para>

+<para>

+<!-- .LP -->

+To receive

+<function>PropertyNotify</function>

+events, set the

+<function>PropertyChangeMask</function>

+bit in the event-mask attribute of the window. 

+</para>

+<para>

+<!-- .LP -->

+The structure for this event type contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XPropertyEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;       /* PropertyNotify */

+     unsigned long serial;     /* # of last request processed by server */

+     Bool          send_event; /* true if this came from a SendEvent request */

+     Display       *display;   /* Display the event was read from */

+     Window        window;

+     Atom atom;

+     Time time;

+     int state;                /* PropertyNewValue or PropertyDelete */

+} XPropertyEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The window member is set to the window whose associated 

+property was changed.

+The atom member is set to the property's atom and indicates which

+property was changed or desired.

+The time member is set to the server time when the property was changed.

+The state member is set to indicate whether the property was changed 

+to a new value or deleted and can be

+<function>PropertyNewValue</function>

+or

+<function>PropertyDelete</function>.

+The state member is set to

+<function>PropertyNewValue</function>

+when a property of the window is changed using

+<function>XChangeProperty</function>

+or

+<function>XRotateWindowProperties</function>

+(even when adding zero-length data using

+<function>XChangeProperty</function>)

+and when replacing all or part of a property with identical data using

+<function>XChangeProperty</function>

+or 

+<function>XRotateWindowProperties</function>.

+The state member is set to

+<function>PropertyDelete</function>

+when a property of the window is deleted using

+<function>XDeleteProperty</function>

+or, if the delete argument is 

+<function>True</function>,

+<function>XGetWindowProperty</function>.

+</para>

+</sect2>

+<sect2 id="SelectionClear_Events">

+<title>SelectionClear Events</title>

+<!-- .XS -->

+<!-- (SN SelectionClear Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm ><primary>Events</primary><secondary>SelectionClear</secondary></indexterm>

+<indexterm significance="preferred"><primary>SelectionClear</primary></indexterm>

+The X server reports

+<function>SelectionClear</function>

+events to the client losing ownership of a selection.

+The X server generates this event type when another client

+asserts ownership of the selection by calling

+<function>XSetSelectionOwner</function>.

+</para>

+<para>

+<!-- .LP -->

+The structure for this event type contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XSelectionClearEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;       /* SelectionClear */

+     unsigned long serial;     /* # of last request processed by server */

+     Bool          send_event; /* true if this came from a SendEvent request */

+     Display       *display;   /* Display the event was read from */

+     Window        window;

+     Atom          selection;

+     Time          time;

+} XSelectionClearEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The selection member is set to the selection atom.

+The time member is set to the last change time recorded for the 

+selection.

+The window member is the window that was specified by the current owner

+(the owner losing the selection) in its

+<function>XSetSelectionOwner</function>

+call.

+</para>

+</sect2>

+<sect2 id="SelectionRequest_Events">

+<title>SelectionRequest Events</title>

+<!-- .XS -->

+<!-- (SN SelectionRequest Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>SelectionRequest</secondary></indexterm>

+<indexterm significance="preferred"><primary>SelectionRequest</primary></indexterm>

+The X server reports

+<function>SelectionRequest</function>

+events to the owner of a selection.

+The X server generates this event whenever a client 

+requests a selection conversion by calling 

+<function>XConvertSelection </function>

+for the owned selection.

+</para>

+<para>

+<!-- .LP -->

+The structure for this event type contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XSelectionRequestEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;       /* SelectionRequest */

+     unsigned long serial;     /* # of last request processed by server */

+     Bool          send_event; /* true if this came from a SendEvent request */

+     Display       *display;   /* Display the event was read from */

+     Window        owner;

+     Window        requestor;

+     Atom          selection;

+     Atom          target;

+     Atom          property;

+     Time          time;

+} XSelectionRequestEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The owner member is set to the window

+that was specified by the current owner in its

+<function>XSetSelectionOwner</function>

+call.

+The requestor member is set to the window requesting the selection.

+The selection member is set to the atom that names the selection.

+For example, PRIMARY is used to indicate the primary selection.

+The target member is set to the atom that indicates the type

+the selection is desired in.

+The property member can be a property name or 

+<function>None</function>.

+The time member is set to the timestamp or 

+<function>CurrentTime </function>

+value from the

+<function>ConvertSelection</function>

+request.

+</para>

+<para>

+<!-- .LP -->

+The owner should convert the selection based on the specified target type

+and send a

+<function>SelectionNotify</function>

+event back to the requestor.

+A complete specification for using selections is given in the X Consortium

+standard <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.

+</para>

+</sect2>

+<sect2 id="SelectionNotify_Events">

+<title>SelectionNotify Events</title>

+<!-- .XS -->

+<!-- (SN SelectionNotify Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Events</primary><secondary>SelectionNotify</secondary></indexterm>

+<indexterm significance="preferred"><primary>SelectionNotify</primary></indexterm>

+This event is generated by the X server in response to a

+<function>ConvertSelection </function>

+protocol request when there is no owner for the selection.

+When there is an owner, it should be generated by the owner

+of the selection by using

+<function>XSendEvent</function>.

+The owner of a selection should send this event to a requestor when a selection

+has been converted and stored as a property

+or when a selection conversion could

+not be performed (which is indicated by setting the property member to

+<function>None</function>).

+</para>

+<para>

+<!-- .LP -->

+If

+<function>None</function>

+is specified as the property in the 

+<function>ConvertSelection</function>

+protocol request, the owner should choose a property name,

+store the result as that property on the requestor window,

+and then send a 

+<function>SelectionNotify</function>

+giving that actual property name.

+</para>

+<para>

+<!-- .LP -->

+The structure for this event type contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XSelectionEvent</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     int           type;       /* SelectionNotify */

+     unsigned long serial;     /* # of last request processed by server */

+     Bool          send_event; /* true if this came from a SendEvent request */

+     Display       *display;   /* Display the event was read from */

+     Window        requestor;

+     Atom          selection;

+     Atom          target;

+     Atom          property;   /* atom or None */

+     Time          time;

+} XSelectionEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The requestor member is set to the window associated with

+the requestor of the selection.

+The selection member is set to the atom that indicates the selection.

+For example, PRIMARY is used for the primary selection.

+The target member is set to the atom that indicates the converted type.

+For example, PIXMAP is used for a pixmap.

+The property member is set to the atom that indicates which

+property the result was stored on.

+If the conversion failed, 

+the property member is set to

+<function>None</function>.

+The time member is set to the time the conversion took place and

+can be a timestamp or

+<function>CurrentTime</function>.

+<!-- .bp -->

+

+

+</para>

+</sect2>

+</sect1>

+</chapter>

diff --git a/libX11/specs/libX11/CH11 b/libX11/specs/libX11/CH11
deleted file mode 100644
index 09d845d35..000000000
--- a/libX11/specs/libX11/CH11
+++ /dev/null
@@ -1,1664 +0,0 @@
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-.\" OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" Except as contained in this notice, the name of the X Consortium shall
-.\" not be used in advertising or otherwise to promote the sale, use or
-.\" other dealings in this Software without prior written authorization
-.\" from the X Consortium.
-.\"
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
-.\" Digital Equipment Corporation
-.\"
-.\" Portions Copyright \(co 1990, 1991 by
-.\" Tektronix, Inc.
-.\"
-.\" Permission to use, copy, modify and distribute this documentation for
-.\" any purpose and without fee is hereby granted, provided that the above
-.\" copyright notice appears in all copies and that both that copyright notice
-.\" and this permission notice appear in all copies, and that the names of
-.\" Digital and Tektronix not be used in in advertising or publicity pertaining
-.\" to this documentation without specific, written prior permission.
-.\" Digital and Tektronix makes no representations about the suitability
-.\" of this documentation for any purpose.
-.\" It is provided ``as is'' without express or implied warranty.
-.\" 
-\&
-.sp 1
-.ce 3
-\s+1\fBChapter 11\fP\s-1
-
-\s+1\fBEvent Handling Functions\fP\s-1
-.sp 2
-.nr H1 11
-.nr H2 0
-.nr H3 0
-.nr H4 0
-.nr H5 0
-.na
-.LP
-.XS
-Chapter 11: Event Handling Functions 
-.XE
-This chapter discusses the Xlib functions you can use to:
-.IP \(bu 5
-Select events
-.IP \(bu 5
-Handle the output buffer and the event queue
-.IP \(bu 5
-Select events from the event queue 
-.IP \(bu 5
-Send and get events
-.IP \(bu 5
-Handle protocol errors
-.NT Note
-Some toolkits use their own event-handling functions
-and do not allow you to interchange these event-handling functions
-with those in Xlib.
-For further information, 
-see the documentation supplied with the toolkit.
-.NE
-.LP
-Most applications simply are event loops:
-they wait for an event, decide what to do with it,
-execute some amount of code that results in changes to the display,
-and then wait for the next event.
-.NH 2
-Selecting Events
-.XS
-\*(SN Selecting Events 
-.XE
-.LP
-There are two ways to select the events you want reported to your client
-application.
-One way is to set the event_mask member of the
-.PN XSetWindowAttributes
-structure when you call
-.PN XCreateWindow
-and
-.PN XChangeWindowAttributes .
-Another way is to use
-.PN XSelectInput . 
-.IN "XSelectInput" "" "@DEF@"
-.sM
-.FD 0
-XSelectInput\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_mask\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      long \fIevent_mask\fP\^;
-.FN	
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Wi whose events you are interested in
-.IP \fIw\fP 1i
-Specifies the window \*(Wi.
-.IP \fIevent_mask\fP 1i
-Specifies the event mask.
-.LP
-.eM 
-The
-.PN XSelectInput
-function requests that the X server report the events associated with the 
-specified event mask.
-Initially, X will not report any of these events.
-Events are reported relative to a window.
-If a window is not interested in a device event, it usually propagates to
-the closest ancestor that is interested,
-unless the do_not_propagate mask prohibits it.
-.IN "Event" "propagation"
-.LP
-Setting the event-mask attribute of a window overrides any previous call
-for the same window but not for other clients.
-Multiple clients can select for the same events on the same window
-with the following restrictions:
-.IP \(bu 5
-Multiple clients can select events on the same window because their event masks
-are disjoint.
-When the X server generates an event, it reports it
-to all interested clients.
-.IP \(bu 5
-Only one client at a time can select
-.PN CirculateRequest ,
-.PN ConfigureRequest ,
-or
-.PN MapRequest
-events, which are associated with
-the event mask
-.PN SubstructureRedirectMask . 
-.IP \(bu 5
-Only one client at a time can select
-a
-.PN ResizeRequest
-event, which is associated with
-the event mask
-.PN ResizeRedirectMask . 
-.IP \(bu 5
-Only one client at a time can select a 
-.PN ButtonPress 
-event, which is associated with
-the event mask
-.PN ButtonPressMask .
-.LP
-The server reports the event to all interested clients.
-.LP
-.PN XSelectInput
-can generate a
-.PN BadWindow 
-error.
-.NH 2
-Handling the Output Buffer
-.XS
-\*(SN Handling the Output Buffer
-.XE
-.LP
-The output buffer is an area used by Xlib to store requests.
-The functions described in this section flush the output buffer
-if the function would block or not return an event.
-That is, all requests residing in the output buffer that
-have not yet been sent are transmitted to the X server.
-These functions differ in the additional tasks they might perform.
-.LP
-.sp
-To flush the output buffer, use 
-.PN XFlush .
-.IN "XFlush" "" "@DEF@"
-.sM
-.FD 0
-XFlush\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-The
-.PN XFlush
-function
-flushes the output buffer.
-Most client applications need not use this function because the output
-buffer is automatically flushed as needed by calls to
-.PN XPending ,
-.PN XNextEvent ,
-and
-.PN XWindowEvent .
-.IN "XPending"
-.IN "XNextEvent"
-.IN "XWindowEvent"
-Events generated by the server may be enqueued into the library's event queue.
-.LP
-.sp
-To flush the output buffer and then wait until all requests have been processed,
-use 
-.PN XSync .
-.IN "XSync" "" "@DEF@"
-.sM
-.FD 0
-XSync\^(\^\fIdisplay\fP, \fIdiscard\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Bool \fIdiscard\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIdiscard\fP 1i
-Specifies a Boolean value that indicates whether 
-.PN XSync
-discards all events on the event queue.
-.LP
-.eM
-The
-.PN XSync
-function
-flushes the output buffer and then waits until all requests have been received
-and processed by the X server.
-Any errors generated must be handled by the error handler.
-For each protocol error received by Xlib,
-.PN XSync
-calls the client application's error handling routine (see section 11.8.2).
-Any events generated by the server are enqueued into the library's 
-event queue.
-.LP
-Finally, if you passed 
-.PN False ,
-.PN XSync
-does not discard the events in the queue.
-If you passed 
-.PN True ,
-.PN XSync 
-discards all events in the queue,
-including those events that were on the queue before
-.PN XSync
-was called.
-Client applications seldom need to call
-.PN XSync .
-.NH 2
-Event Queue Management
-.XS
-\*(SN Event Queue Management
-.XE
-.LP
-Xlib maintains an event queue.
-However, the operating system also may be buffering data 
-in its network connection that is not yet read into the event queue.
-.LP
-.sp
-To check the number of events in the event queue, use
-.PN XEventsQueued .
-.IN "XEventsQueued" "" "@DEF@"
-.sM
-.FD 0
-int XEventsQueued\^(\^\fIdisplay\fP, \fImode\fP\^)
-.br
-     Display *\fIdisplay\fP\^;
-.br
-     int \fImode\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fImode\fP 1i
-Specifies the mode.
-You can pass
-.PN QueuedAlready ,
-.PN QueuedAfterFlush ,
-or
-.PN QueuedAfterReading .
-.LP
-.eM
-If mode is 
-.PN QueuedAlready ,
-.PN XEventsQueued 
-returns the number of events
-already in the event queue (and never performs a system call).
-If mode is 
-.PN QueuedAfterFlush , 
-.PN XEventsQueued
-returns the number of events already in the queue if the number is nonzero.
-If there are no events in the queue, 
-.PN XEventsQueued
-flushes the output buffer, 
-attempts to read more events out of the application's connection,
-and returns the number read.
-If mode is 
-.PN QueuedAfterReading , 
-.PN XEventsQueued
-returns the number of events already in the queue if the number is nonzero. 
-If there are no events in the queue, 
-.PN XEventsQueued
-attempts to read more events out of the application's connection 
-without flushing the output buffer and returns the number read.
-.LP
-.PN XEventsQueued
-always returns immediately without I/O if there are events already in the
-queue.
-.PN XEventsQueued
-with mode 
-.PN QueuedAfterFlush
-is identical in behavior to
-.PN XPending .
-.PN XEventsQueued
-with mode
-.PN QueuedAlready
-is identical to the
-.PN XQLength
-function.
-.LP
-.sp
-To return the number of events that are pending, use 
-.PN XPending .
-.IN "XPending" "" "@DEF@"
-.sM
-.FD 0
-int XPending\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN	
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-The
-.PN XPending
-function returns the number of events that have been received from the
-X server but have not been removed from the event queue.
-.PN XPending
-is identical to
-.PN XEventsQueued
-with the mode
-.PN QueuedAfterFlush
-specified.
-.NH 2
-Manipulating the Event Queue
-.XS
-\*(SN Manipulating the Event Queue 
-.XE
-.LP
-Xlib provides functions that let you manipulate the event queue.
-This section discusses how to:
-.IP \(bu 5
-Obtain events, in order, and remove them from the queue
-.IP \(bu 5
-Peek at events in the queue without removing them
-.IP \(bu 5
-Obtain events that match the event mask or the arbitrary
-predicate procedures that you provide
-.NH 3
-Returning the Next Event
-.XS
-\*(SN Returning the Next Event
-.XE
-.LP
-To get the next event and remove it from the queue, use
-.PN XNextEvent .
-.IN "XNextEvent" "" "@DEF@"
-.sM
-.FD 0
-XNextEvent\^(\^\fIdisplay\fP, \fIevent_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XEvent *\fIevent_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIevent_return\fP 1i
-Returns the next event in the queue.
-.LP
-.eM
-The
-.PN XNextEvent
-function copies the first event from the event queue into the specified
-.PN XEvent
-structure and then removes it from the queue.
-If the event queue is empty,
-.PN XNextEvent
-flushes the output buffer and blocks until an event is received.
-.LP
-.sp
-To peek at the event queue, use
-.PN XPeekEvent .
-.IN "XPeekEvent" "" "@DEF@"
-.sM
-.FD 0
-XPeekEvent\^(\^\fIdisplay\fP, \fIevent_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XEvent *\fIevent_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIevent_return\fP 1i
-Returns a copy of the matched event's associated structure.
-.LP
-.eM
-The
-.PN XPeekEvent
-function returns the first event from the event queue,
-but it does not remove the event from the queue.
-If the queue is empty,
-.PN XPeekEvent
-flushes the output buffer and blocks until an event is received.
-It then copies the event into the client-supplied
-.PN XEvent
-structure without removing it from the event queue.
-.NH 3
-Selecting Events Using a Predicate Procedure
-.XS
-\*(SN Selecting Events Using a Predicate Procedure
-.XE
-.LP
-Each of the functions discussed in this section requires you to
-pass a predicate procedure that determines if an event matches 
-what you want.
-Your predicate procedure must decide if the event is useful
-without calling any Xlib functions.
-If the predicate directly or indirectly causes the state of the event queue
-to change, the result is not defined.
-If Xlib has been initialized for threads, the predicate is called with
-the display locked and the result of a call by the predicate to any
-Xlib function that locks the display is not defined unless the caller
-has first called
-.PN XLockDisplay .
-.LP
-The predicate procedure and its associated arguments are:
-.sM
-.FD 0
-Bool (\^*\fIpredicate\fP\^)\^(\^\fIdisplay\fP, \fIevent\fP, \fIarg\fP\^)
-.br
-     Display *\fIdisplay\fP\^;
-.br
-     XEvent *\fIevent\fP\^;
-.br
-     XPointer \fIarg\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIevent\fP 1i
-Specifies the
-.PN XEvent
-structure.
-.IP \fIarg\fP 1i
-Specifies the argument passed in from the 
-.PN XIfEvent ,
-.PN XCheckIfEvent ,
-or
-.PN XPeekIfEvent 
-function.
-.LP
-.eM
-The predicate procedure is called once for each
-event in the queue until it finds a match. 
-After finding a match, the predicate procedure must return 
-.PN True .
-If it did not find a match, it must return
-.PN False .
-.LP
-.sp
-To check the event queue for a matching event
-and, if found, remove the event from the queue, use
-.PN XIfEvent .
-.IN "XIfEvent" "" "@DEF@"
-.sM
-.FD 0
-XIfEvent\^(\^\fIdisplay\fP, \fIevent_return\fP, \fIpredicate\fP, \fIarg\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XEvent *\fIevent_return\fP\^;
-.br
-      Bool (\^*\fIpredicate\fP\^)\^(\^)\^;
-.br
-      XPointer \fIarg\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIevent_return\fP 1i
-Returns the matched event's associated structure.
-.IP \fIpredicate\fP 1i
-Specifies the procedure that is to be called to determine
-if the next event in the queue matches what you want.
-.IP \fIarg\fP 1i
-Specifies the user-supplied argument that will be passed to the predicate procedure.
-.LP
-.eM
-The
-.PN XIfEvent
-function completes only when the specified predicate
-procedure returns 
-.PN True 
-for an event, 
-which indicates an event in the queue matches.
-.PN XIfEvent
-flushes the output buffer if it blocks waiting for additional events.
-.PN XIfEvent
-removes the matching event from the queue 
-and copies the structure into the client-supplied
-.PN XEvent
-structure.
-.LP
-.sp
-To check the event queue for a matching event without blocking, use
-.PN XCheckIfEvent .
-.IN "XCheckIfEvent" "" "@DEF@"
-.sM
-.FD 0
-Bool XCheckIfEvent\^(\^\fIdisplay\fP, \fIevent_return\fP, \fIpredicate\fP, \fIarg\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XEvent *\fIevent_return\fP\^;
-.br
-      Bool (\^*\fIpredicate\fP\^)\^(\^)\^;
-.br
-      XPointer \fIarg\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIevent_return\fP 1i
-Returns a copy of the matched event's associated structure.
-.IP \fIpredicate\fP 1i
-Specifies the procedure that is to be called to determine
-if the next event in the queue matches what you want.
-.IP \fIarg\fP 1i
-Specifies the user-supplied argument that will be passed to the predicate procedure.
-.LP
-.eM
-When the predicate procedure finds a match,
-.PN XCheckIfEvent
-copies the matched event into the client-supplied
-.PN XEvent
-structure and returns 
-.PN True .
-(This event is removed from the queue.)
-If the predicate procedure finds no match,
-.PN XCheckIfEvent
-returns
-.PN False ,
-and the output buffer will have been flushed.
-All earlier events stored in the queue are not discarded.
-.LP
-.sp
-To check the event queue for a matching event
-without removing the event from the queue, use
-.PN XPeekIfEvent .
-.IN "XPeekIfEvent" "" "@DEF@"
-.sM
-.FD 0
-XPeekIfEvent\^(\^\fIdisplay\fP, \fIevent_return\fP, \fIpredicate\fP, \fIarg\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XEvent *\fIevent_return\fP\^;
-.br
-      Bool (\^*\fIpredicate\fP\^)\^(\^)\^;
-.br
-      XPointer \fIarg\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIevent_return\fP 1i
-Returns a copy of the matched event's associated structure.
-.IP \fIpredicate\fP 1i
-Specifies the procedure that is to be called to determine
-if the next event in the queue matches what you want.
-.IP \fIarg\fP 1i
-Specifies the user-supplied argument that will be passed to the predicate procedure.
-.LP
-.eM
-The
-.PN XPeekIfEvent
-function returns only when the specified predicate
-procedure returns 
-.PN True
-for an event.
-After the predicate procedure finds a match,
-.PN XPeekIfEvent
-copies the matched event into the client-supplied
-.PN XEvent
-structure without removing the event from the queue.
-.PN XPeekIfEvent
-flushes the output buffer if it blocks waiting for additional events.
-.NH 3
-Selecting Events Using a Window or Event Mask
-.XS
-\*(SN Selecting Events Using a Window or Event Mask
-.XE
-.LP
-The functions discussed in this section let you select events by window 
-or event types, allowing you to process events out of order.
-.LP
-.sp
-To remove the next event that matches both a window and an event mask, use
-.PN XWindowEvent .
-.IN "XWindowEvent" "" "@DEF@"
-.sM
-.FD 0
-XWindowEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_mask\fP\^, \fIevent_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      long \fIevent_mask\fP\^;
-.br
-      XEvent *\fIevent_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Wi whose events you are interested in
-.IP \fIw\fP 1i
-Specifies the window \*(Wi.
-.IP \fIevent_mask\fP 1i
-Specifies the event mask.
-.IP \fIevent_return\fP 1i
-Returns the matched event's associated structure.
-.LP
-.eM
-The
-.PN XWindowEvent
-function searches the event queue for an event that matches both the specified
-window and event mask.
-When it finds a match,
-.PN XWindowEvent
-removes that event from the queue and copies it into the specified
-.PN XEvent
-structure.
-The other events stored in the queue are not discarded.
-If a matching event is not in the queue,
-.PN XWindowEvent
-flushes the output buffer and blocks until one is received.
-.LP
-.sp
-To remove the next event that matches both a window and an event mask (if any),
-use
-.PN XCheckWindowEvent .
-.IN "XCheckWindowEvent"
-This function is similar to
-.PN XWindowEvent 
-except that it never blocks and it returns a 
-.PN Bool 
-indicating if the event was returned.
-.IN "XCheckWindowEvent" "" "@DEF@"
-.sM
-.FD 0
-Bool XCheckWindowEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_mask\fP\^, \fIevent_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      long \fIevent_mask\fP\^;
-.br
-      XEvent *\fIevent_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Wi whose events you are interested in
-.IP \fIw\fP 1i
-Specifies the window \*(Wi.
-.IP \fIevent_mask\fP 1i
-Specifies the event mask.
-.IP \fIevent_return\fP 1i
-Returns the matched event's associated structure.
-.LP
-.eM
-The
-.PN XCheckWindowEvent
-function searches the event queue and then the events available 
-on the server connection for the first event that matches the specified window
-and event mask.
-If it finds a match,
-.PN XCheckWindowEvent
-removes that event, copies it into the specified
-.PN XEvent
-structure, and returns
-.PN True .
-The other events stored in the queue are not discarded.
-If the event you requested is not available,
-.PN XCheckWindowEvent
-returns
-.PN False ,
-and the output buffer will have been flushed.
-.LP
-.sp
-To remove the next event that matches an event mask, use
-.PN XMaskEvent .
-.IN "XMaskEvent" "" "@DEF@"
-.sM
-.FD 0
-XMaskEvent\^(\^\fIdisplay\fP, \fIevent_mask\fP\^, \fIevent_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      long \fIevent_mask\fP\^;
-.br
-      XEvent *\fIevent_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIevent_mask\fP 1i
-Specifies the event mask.
-.IP \fIevent_return\fP 1i
-Returns the matched event's associated structure.
-.LP
-.eM
-The
-.PN XMaskEvent
-function searches the event queue for the events associated with the 
-specified mask.
-When it finds a match,
-.PN XMaskEvent
-removes that event and copies it into the specified
-.PN XEvent
-structure.
-The other events stored in the queue are not discarded.
-If the event you requested is not in the queue,
-.PN XMaskEvent
-flushes the output buffer and blocks until one is received.
-.LP
-.sp
-To return and remove the next event that matches an event mask (if any), use
-.PN XCheckMaskEvent .
-This function is similar to 
-.PN XMaskEvent 
-except that it never blocks and it returns a 
-.PN Bool 
-indicating if the event was returned.
-.IN "XCheckMaskEvent" "" "@DEF@"
-.sM
-.FD 0
-Bool XCheckMaskEvent\^(\^\fIdisplay\fP, \fIevent_mask\fP\^, \fIevent_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      long \fIevent_mask\fP\^;
-.br
-      XEvent *\fIevent_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIevent_mask\fP 1i
-Specifies the event mask.
-.IP \fIevent_return\fP 1i
-Returns the matched event's associated structure.
-.LP
-.eM
-The
-.PN XCheckMaskEvent
-function searches the event queue and then any events available on the
-server connection for the first event that matches the specified mask.
-If it finds a match,
-.PN XCheckMaskEvent
-removes that event, copies it into the specified
-.PN XEvent
-structure, and returns
-.PN True .
-The other events stored in the queue are not discarded.
-If the event you requested is not available,
-.PN XCheckMaskEvent
-returns
-.PN False ,
-and the output buffer will have been flushed.
-.LP
-.sp 
-To return and remove the next event in the queue that matches an event type, use
-.PN XCheckTypedEvent .
-.IN "XCheckTypedEvent" "" "@DEF@"
-.sM
-.FD 0
-Bool XCheckTypedEvent\^(\^\fIdisplay\fP, \fIevent_type\fP\^, \fIevent_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIevent_type\fP\^;
-.br
-      XEvent *\fIevent_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIevent_type\fP 1i
-Specifies the event type to be compared.
-
-.IP \fIevent_return\fP 1i
-Returns the matched event's associated structure.
-.LP
-.eM
-The
-.PN XCheckTypedEvent
-function searches the event queue and then any events available  
-on the server connection for the first event that matches the specified type.
-If it finds a match,
-.PN XCheckTypedEvent
-removes that event, copies it into the specified
-.PN XEvent
-structure, and returns
-.PN True .
-The other events in the queue are not discarded.
-If the event is not available,
-.PN XCheckTypedEvent
-returns
-.PN False ,
-and the output buffer will have been flushed.
-.LP
-.sp
-To return and remove the next event in the queue that matches an event type 
-and a window, use
-.PN XCheckTypedWindowEvent .
-.IN "XCheckTypedWindowEvent" "" "@DEF@"
-.sM
-.FD 0
-Bool XCheckTypedWindowEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_type\fP\^, \fIevent_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      int \fIevent_type\fP\^;
-.br
-      XEvent *\fIevent_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIevent_type\fP 1i
-Specifies the event type to be compared.
-
-.IP \fIevent_return\fP 1i
-Returns the matched event's associated structure.
-.LP
-.eM
-The
-.PN XCheckTypedWindowEvent
-function searches the event queue and then any events available  
-on the server connection for the first event that matches the specified
-type and window.
-If it finds a match,
-.PN XCheckTypedWindowEvent
-removes the event from the queue, copies it into the specified
-.PN XEvent
-structure, and returns
-.PN True .
-The other events in the queue are not discarded.
-If the event is not available,
-.PN XCheckTypedWindowEvent
-returns
-.PN False ,
-and the output buffer will have been flushed.
-.NH 2
-Putting an Event Back into the Queue
-.XS
-\*(SN Putting an Event Back into the Queue 
-.XE
-.LP
-To push an event back into the event queue, use
-.PN XPutBackEvent .
-.IN "XPutBackEvent" "" "@DEF@"
-.sM
-.FD 0
-XPutBackEvent\^(\^\fIdisplay\fP, \fIevent\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XEvent *\fIevent\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIevent\fP 1i
-Specifies the event.
-.LP
-.eM 
-The
-.PN XPutBackEvent
-function pushes an event back onto the head of the display's event queue
-by copying the event into the queue.
-This can be useful if you read an event and then decide that you
-would rather deal with it later.
-There is no limit to the number of times in succession that you can call
-.PN XPutBackEvent .
-.NH 2
-Sending Events to Other Applications
-.XS
-\*(SN Sending Events to Other Applications
-.XE
-.LP
-To send an event to a specified window, use
-.PN XSendEvent .
-.IN "XSendEvent"
-This function is often used in selection processing.
-For example, the owner of a selection should use
-.PN XSendEvent
-to send a
-.PN SelectionNotify
-event to a requestor when a selection has been converted 
-and stored as a property.
-.IN "XSendEvent" "" "@DEF@"
-.sM
-.FD 0
-Status XSendEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIpropagate\fP\^, \fIevent_mask\fP\^, \fIevent_send\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      Bool \fIpropagate\fP\^;
-.br
-      long \fIevent_mask\fP\^;
-.br
-      XEvent *\fIevent_send\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window the event is to be sent to, or
-.PN PointerWindow ,
-or
-.PN InputFocus .
-.IP \fIpropagate\fP 1i
-Specifies a Boolean value.
-.IP \fIevent_mask\fP 1i
-Specifies the event mask.
-.IP \fIevent_send\fP 1i
-Specifies the event that is to be sent.
-.LP
-.eM
-The
-.PN XSendEvent
-function identifies the destination window, 
-determines which clients should receive the specified events, 
-and ignores any active grabs.
-This function requires you to pass an event mask.
-For a discussion of the valid event mask names,
-see section 10.3.
-This function uses the w argument to identify the destination window as follows:
-.IP \(bu 5
-If w is
-.PN PointerWindow ,
-the destination window is the window that contains the pointer.
-.IP \(bu 5
-If w is
-.PN InputFocus 
-and if the focus window contains the pointer, 
-the destination window is the window that contains the pointer; 
-otherwise, the destination window is the focus window.
-.LP
-To determine which clients should receive the specified events,
-.PN XSendEvent
-uses the propagate argument as follows:
-.IP \(bu 5
-If event_mask is the empty set,
-the event is sent to the client that created the destination window.
-If that client no longer exists,
-no event is sent.
-.IP \(bu 5
-If propagate is 
-.PN False ,
-the event is sent to every client selecting on destination any of the event
-types in the event_mask argument.
-.IP \(bu 5
-If propagate is 
-.PN True 
-and no clients have selected on destination any of
-the event types in event-mask, the destination is replaced with the
-closest ancestor of destination for which some client has selected a
-type in event-mask and for which no intervening window has that type in its
-do-not-propagate-mask. 
-If no such window exists or if the window is
-an ancestor of the focus window and 
-.PN InputFocus 
-was originally specified
-as the destination, the event is not sent to any clients.
-Otherwise, the event is reported to every client selecting on the final
-destination any of the types specified in event_mask.
-.LP
-The event in the
-.PN XEvent
-structure must be one of the core events or one of the events
-defined by an extension (or a 
-.PN BadValue
-error results) so that the X server can correctly byte-swap 
-the contents as necessary.  
-The contents of the event are
-otherwise unaltered and unchecked by the X server except to force send_event to
-.PN True
-in the forwarded event and to set the serial number in the event correctly;
-therefore these fields
-and the display field are ignored by
-.PN XSendEvent .
-.LP
-.PN XSendEvent
-returns zero if the conversion to wire protocol format failed
-and returns nonzero otherwise.
-.LP
-.PN XSendEvent
-can generate
-.PN BadValue
-and 
-.PN BadWindow 
-errors.
-.NH 2
-Getting Pointer Motion History
-.XS
-\*(SN Getting Pointer Motion History
-.XE
-.LP
-Some X server implementations will maintain a more complete
-history of pointer motion than is reported by event notification.
-The pointer position at each pointer hardware interrupt may be
-stored in a buffer for later retrieval.
-This buffer is called the motion history buffer.
-For example, a few applications, such as paint programs,
-want to have a precise history of where the pointer
-traveled. 
-However, this historical information is highly excessive for most applications.
-.LP
-.sp
-To determine the approximate maximum number of elements in the motion buffer, 
-use
-.PN XDisplayMotionBufferSize .
-.IN "XDisplayMotionBufferSize" "" "@DEF@"
-.sM
-.FD 0
-unsigned long XDisplayMotionBufferSize\^(\^\fIdisplay\fP\^)
-.br
-        Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-The server may retain the recent history of the pointer motion
-and do so to a finer granularity than is reported by
-.PN MotionNotify
-events.
-The
-.PN XGetMotionEvents
-function makes this history available.
-.LP
-.sp
-To get the motion history for a specified window and time, use
-.PN XGetMotionEvents .
-.IN "XGetMotionEvents" "" "@DEF@"
-.sM
-.FD 0
-XTimeCoord *XGetMotionEvents\^(\^\fIdisplay\fP, \fIw\fP\^, \fIstart\fP\^, \fIstop\fP\^, \fInevents_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      Time \fIstart\fP\^, \fIstop\fP\^;	
-.br
-      int *\fInevents_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIstart\fP 1i
-.br
-.ns
-.IP \fIstop\fP 1i
-Specify the time interval in which the events are returned from the motion
-history buffer.
-You can pass a timestamp or
-.PN CurrentTime .
-.IP \fInevents_return\fP 1i
-Returns the number of events from the motion history buffer.
-.LP
-.eM
-The
-.PN XGetMotionEvents
-function returns all events in the motion history buffer that fall between the
-specified start and stop times, inclusive, and that have coordinates
-that lie within the specified window (including its borders) at its present
-placement.
-If the server does not support motion history, 
-if the start time is later than the stop time,
-or if the start time is in the future, 
-no events are returned;
-.PN XGetMotionEvents
-returns NULL.
-If the stop time is in the future, it is equivalent to specifying
-.PN CurrentTime .
-The return type for this function is a structure defined as follows:
-.LP
-.IN "XTimeCoord" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i
-.ta .5i
-typedef struct {
-	Time time;
-	short x, y;
-} XTimeCoord;
-.De
-.LP
-.eM
-The time member is set to the time, in milliseconds. 
-The x and y members are set to the coordinates of the pointer and
-are reported relative to the origin
-of the specified window.
-To free the data returned from this call, use
-.PN XFree .
-.LP
-.PN XGetMotionEvents
-can generate a
-.PN BadWindow 
-error.
-.NH 2
-Handling Protocol Errors
-.XS
-\*(SN Handling Protocol Errors
-.XE
-.LP
-Xlib provides functions that you can use to enable or disable synchronization
-and to use the default error handlers.
-.NH 3
-Enabling or Disabling Synchronization
-.XS
-\*(SN Enabling or Disabling Synchronization 
-.XE
-.LP
-When debugging X applications, 
-it often is very convenient to require Xlib to behave synchronously
-so that errors are reported as they occur.
-The following function lets you disable or enable synchronous behavior.
-Note that graphics may occur 30 or more times more slowly when 
-synchronization is enabled.
-.IN "_Xdebug"
-On POSIX-conformant systems,
-there is also a global variable 
-.PN _Xdebug 
-that, if set to nonzero before starting a program under a debugger, will force
-synchronous library behavior.
-.LP
-After completing their work,
-all Xlib functions that generate protocol requests call what is known as
-an after function.
-.PN XSetAfterFunction
-sets which function is to be called.
-.IN "XSetAfterFunction" "" "@DEF@"
-.sM
-.FD 0
-int (*XSetAfterFunction\^(\^\fIdisplay\fP, \fIprocedure\fP\^))()
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int (\^*\^\fIprocedure\fP\^)\^();
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIprocedure\fP 1i
-Specifies the procedure to be called.
-.LP
-.eM
-The specified procedure is called with only a display pointer.
-.PN XSetAfterFunction
-returns the previous after function.
-.LP
-To enable or disable synchronization, use 
-.PN XSynchronize .
-.IN "Debugging" "synchronous mode"
-.IN "XSynchronize" "" "@DEF@"
-.sM
-.FD 0
-int (*XSynchronize\^(\^\fIdisplay\fP, \fIonoff\fP\^)\^)()
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Bool \fIonoff\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIonoff\fP 1i
-Specifies a Boolean value that indicates whether to enable 
-or disable synchronization.
-.LP
-.eM
-The
-.PN XSynchronize
-function returns 
-the previous after function.
-If onoff is 
-.PN True , 
-.PN XSynchronize
-turns on synchronous behavior.
-If onoff is
-.PN False ,
-.PN XSynchronize 
-turns off synchronous behavior.
-.NH 3
-Using the Default Error Handlers
-.XS
-\*(SN Using the Default Error Handlers 
-.XE
-.LP
-.IN "Debugging" "error handlers"
-.IN "Error" "handlers"
-There are two default error handlers in Xlib: 
-one to handle typically fatal conditions (for example, 
-the connection to a display server dying because a machine crashed) 
-and one to handle protocol errors from the X server.
-These error handlers can be changed to user-supplied routines if you
-prefer your own error handling and can be changed as often as you like.
-If either function is passed a NULL pointer, it will
-reinvoke the default handler.
-The action of the default handlers is to print an explanatory
-message and exit.
-.LP
-.sp
-To set the error handler, use
-.PN XSetErrorHandler .
-.IN "XSetErrorHandler" "" "@DEF@"
-.sM
-.FD 0
-int (*XSetErrorHandler\^(\^\fIhandler\fP\^)\^)\^(\^)
-.br
-      int (\^*\^\fIhandler\fP\^)\^(Display *, XErrorEvent *)
-.FN
-.IP \fIhandler\fP 1i
-Specifies the program's supplied error handler.
-.LP
-.eM 
-Xlib generally calls the program's
-supplied error handler whenever an error is received.
-It is not called on
-.PN BadName
-errors from
-.PN OpenFont ,
-.PN LookupColor ,
-or
-.PN AllocNamedColor
-protocol requests or on
-.PN BadFont
-errors from a
-.PN QueryFont
-protocol request.
-These errors generally are reflected back to the program through the
-procedural interface.
-Because this condition is not assumed to be fatal, 
-it is acceptable for your error handler to return;
-the returned value is ignored.
-However, the error handler should not
-call any functions (directly or indirectly) on the display
-that will generate protocol requests or that will look for input events.
-The previous error handler is returned.
-.LP
-The 
-.PN XErrorEvent
-structure contains:
-.IN "Debugging" "error event"
-.LP
-.IN "XErrorEvent" "" "@DEF"
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	int type;
-	Display *display;	/* Display the event was read from */
-	unsigned long serial;		/* serial number of failed request */
-	unsigned char error_code;	/* error code of failed request */
-	unsigned char request_code;	/* Major op-code of failed request */
-	unsigned char minor_code;	/* Minor op-code of failed request */
-	XID resourceid;		/* resource id */
-} XErrorEvent;
-.De
-.LP
-.IN "Serial Number"
-The serial member is the number of requests, starting from one, 
-sent over the network connection since it was opened. 
-It is the number that was the value of 
-.PN NextRequest 
-immediately before the failing call was made.  
-The request_code member is a protocol request
-of the procedure that failed, as defined in 
-.hN X11/Xproto.h .
-The following error codes can be returned by the functions described in this
-chapter:
-.br
-.ne 13
-.IN "Debugging" "error numbers"
-.IN "Error" "codes"
-.\".CP T 3
-.\"Error Codes
-.IN "BadAccess" "" "@DEF@"
-.IN "BadAlloc" "" "@DEF@"
-.IN "BadAtom" "" "@DEF@"
-.IN "BadColor" "" "@DEF@"
-.IN "BadCursor" "" "@DEF@"
-.IN "BadDrawable" "" "@DEF@"
-.IN "BadFont" "" "@DEF@"
-.IN "BadGC" "" "@DEF@"
-.IN "BadIDChoice" "" "@DEF@"
-.TS H
-l c
-lw(1.75i) lw(4i).
-_
-.sp 6p
-.B
-Error Code	Description
-.sp 6p
-_
-.sp 6p
-.TH
-.R
-T{
-.PN BadAccess
-T}	T{
-A client attempts to grab a key/button combination already grabbed 
-by another client.
-.sp 3p
-A client attempts to free a colormap entry that it had not already allocated
-or to free an entry in a colormap that was created with all entries writable.
-.sp 3p
-A client attempts to store into a read-only or unallocated colormap entry.
-.sp 3p
-A client attempts to modify the access control list from other than the local 
-(or otherwise authorized) host.
-.sp 3p
-A client attempts to select an event type that another client 
-has already selected.
-T}
-.sp 3p
-T{
-.PN BadAlloc
-T}	T{
-The server fails to allocate the requested resource.
-Note that the explicit listing of
-.PN BadAlloc
-errors in requests only covers allocation errors at a very coarse level
-and is not intended to (nor can it in practice hope to) cover all cases of
-a server running out of allocation space in the middle of service.
-The semantics when a server runs out of allocation space are left unspecified,
-but a server may generate a
-.PN BadAlloc
-error on any request for this reason,
-and clients should be prepared to receive such errors and handle or discard
-them.
-T}
-.sp 3p
-T{
-.PN BadAtom
-T}	T{
-A value for an atom argument does not name a defined atom.
-T}
-.sp 3p
-T{
-.PN BadColor
-T}	T{
-A value for a colormap argument does not name a defined colormap.
-T}
-.sp 3p
-T{
-.PN BadCursor
-T}	T{
-A value for a cursor argument does not name a defined cursor.
-T}
-.sp 3p
-T{
-.PN BadDrawable
-T}	T{
-A value for a drawable argument does not name a defined window or pixmap.
-T}
-.sp 3p
-T{
-.PN BadFont
-T}	T{
-A value for a font argument does not name a defined font (or, in some cases, 
-.PN GContext ).
-T}
-.sp 3p
-T{
-.PN BadGC
-T}	T{
-A value for a 
-.PN GContext 
-argument does not name a defined 
-.PN GContext .
-T}
-.sp 3p
-T{
-.PN BadIDChoice
-T}	T{
-The value chosen for a resource identifier either is not included in the 
-range assigned to the client or is already in use.
-Under normal circumstances,
-this cannot occur and should be considered a server or Xlib error.
-T}
-.sp 3p
-T{
-.PN BadImplementation
-T}	T{
-The server does not implement some aspect of the request.
-A server that generates this error for a core request is deficient.
-As such, this error is not listed for any of the requests,
-but clients should be prepared to receive such errors 
-and handle or discard them.
-T}
-.sp 3p
-T{
-.PN BadLength
-T}	T{
-The length of a request is shorter or longer than that required to 
-contain the arguments.
-This is an internal Xlib or server error.
-.sp 3p
-The length of a request exceeds the maximum length accepted by the server.
-T}
-.sp 3p
-T{
-.PN BadMatch
-T}	T{
-In a graphics request,
-the root and depth of the graphics context do not match those of the drawable.
-.sp 3p
-An 
-.PN InputOnly 
-window is used as a drawable.
-.sp 3p
-Some argument or pair of arguments has the correct type and range,
-but it fails to match in some other way required by the request.
-.sp 3p
-An 
-.PN InputOnly 
-window lacks this attribute.
-T}
-.sp 3p
-T{
-.PN BadName
-T}	T{
-A font or color of the specified name does not exist.
-T}
-.sp 3p
-T{
-.PN BadPixmap
-T}	T{
-A value for a pixmap argument does not name a defined pixmap.
-T}
-.sp 3p
-T{
-.PN BadRequest
-T}	T{
-The major or minor opcode does not specify a valid request.
-This usually is an Xlib or server error.
-T}
-.sp 3p
-T{
-.PN BadValue
-T}	T{
-Some numeric value falls outside of the range of values accepted 
-by the request.  
-Unless a specific range is specified for an argument,
-the full range defined by the argument's type is accepted.
-Any argument defined as a set of alternatives typically can generate
-this error (due to the encoding).
-T}
-.sp 3p
-T{
-.PN BadWindow
-T}	T{
-A value for a window argument does not name a defined window.
-T}
-.sp 6p
-_
-.TE
-.IN "BadImplementation" "" "@DEF@"
-.IN "BadLength" "" "@DEF@"
-.IN "BadMatch" "" "@DEF@"
-.IN "BadName" "" "@DEF@"
-.IN "BadPixmap" "" "@DEF@"
-.IN "BadRequest" "" "@DEF@"
-.IN "BadValue" "" "@DEF@"
-.IN "BadWindow" "" "@DEF@"
-.NT Note
-The 
-.PN BadAtom , 
-.PN BadColor , 
-.PN BadCursor , 
-.PN BadDrawable , 
-.PN BadFont , 
-.PN BadGC , 
-.PN BadPixmap , 
-and 
-.PN BadWindow
-errors are also used when the argument type is extended by a set of
-fixed alternatives.
-.NE
-.sp
-.LP
-To obtain textual descriptions of the specified error code, use 
-.PN XGetErrorText .
-.IN "XGetErrorText" "" "@DEF@"
-.IN "Debugging" "error message strings"
-.sM
-.FD 0
-XGetErrorText\^(\^\fIdisplay\fP, \fIcode\fP, \fIbuffer_return\fP, \fIlength\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIcode\fP\^;
-.br
-      char *\fIbuffer_return\fP\^;
-.br
-      int \fIlength\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIcode\fP 1i
-Specifies the error code for which you want to obtain a description.
-.IP \fIbuffer_return\fP 1i
-Returns the error description.
-.IP \fIlength\fP 1i
-Specifies the size of the buffer.
-.LP
-.eM 
-The
-.PN XGetErrorText
-function copies a null-terminated string describing the specified error code
-into the specified buffer.
-The returned text is in the encoding of the current locale.
-It is recommended that you use this function to obtain an error description
-because extensions to Xlib may define their own error codes
-and error strings.
-.LP
-.sp
-To obtain error messages from the error database, use
-.PN XGetErrorDatabaseText .
-.IN "XGetErrorDatabaseText" "" "@DEF@"
-.sM
-.FD 0
-XGetErrorDatabaseText\^(\^\fIdisplay\fP, \fIname\fP, \fImessage\fP, \fIdefault_string\fP, \fIbuffer_return\fP, \fIlength\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      char *\fIname\fP, *\fImessage\fP\^;
-.br
-      char *\fIdefault_string\fP\^;
-.br
-      char *\fIbuffer_return\fP\^;
-.br
-      int \fIlength\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIname\fP 1i
-Specifies the name of the application.
-.IP \fImessage\fP 1i
-Specifies the type of the error message.
-.IP \fIdefault_string\fP 1i
-Specifies the default error message if none is found in the database.
-.IP \fIbuffer_return\fP 1i
-Returns the error description.
-.IP \fIlength\fP 1i
-Specifies the size of the buffer.
-.LP
-.eM
-The
-.PN XGetErrorDatabaseText
-function returns a null-terminated message
-(or the default message) from the error message
-database.
-Xlib uses this function internally to look up its error messages.
-The text in the default_string argument is assumed
-to be in the encoding of the current locale,
-and the text stored in the buffer_return argument
-is in the encoding of the current locale.
-.LP
-The name argument should generally be the name of your application.
-The message argument should indicate which type of error message you want.
-If the name and message are not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-Xlib uses three predefined ``application names'' to report errors.
-In these names,
-uppercase and lowercase matter.
-.IP XProtoError 1i
-The protocol error number is used as a string for the message argument.
-.IP XlibMessage 1i
-These are the message strings that are used internally by the library.
-.IP XRequest 1i
-For a core protocol request,
-the major request protocol number is used for the message argument.
-For an extension request,
-the extension name (as given by
-.PN InitExtension )
-followed by a period (\.) and the minor request protocol number 
-is used for the message argument.
-If no string is found in the error database,
-the default_string is returned to the buffer argument.
-.LP
-.sp
-To report an error to the user when the requested display does not exist, use
-.PN XDisplayName .
-.IN "XDisplayName" "" "@DEF@"
-.sM
-.FD 0
-char *XDisplayName\^(\^\fIstring\fP\^)
-.br
-      char *\fIstring\fP\^;
-.FN
-.IP \fIstring\fP 1i
-Specifies the character string.
-.LP
-.eM
-The
-.PN XDisplayName
-function returns the name of the display that 
-.PN XOpenDisplay
-would attempt to use.
-If a NULL string is specified,
-.PN XDisplayName
-looks in the environment for the display and returns the display name that
-.PN XOpenDisplay
-would attempt to use.
-This makes it easier to report to the user precisely which display the
-program attempted to open when the initial connection attempt failed.
-.LP
-.sp
-To handle fatal I/O errors, use
-.PN XSetIOErrorHandler .
-.IN "XSetIOErrorHandler" "" "@DEF@"
-.sM
-.FD 0
-int (*XSetIOErrorHandler\^(\^\fIhandler\fP\^)\^)\^(\^)
-.br
-      int (\^*\^\fIhandler\fP\^)(Display *);
-.FN
-.IP \fIhandler\fP 1i
-Specifies the program's supplied error handler.
-.LP
-.eM
-The
-.PN XSetIOErrorHandler
-sets the fatal I/O error handler.
-Xlib calls the program's supplied error handler if any sort of system call
-error occurs (for example, the connection to the server was lost).
-This is assumed to be a fatal condition,
-and the called routine should not return.
-If the I/O error handler does return,
-the client process exits.
-.LP
-Note that the previous error handler is returned.
-.bp
diff --git a/libX11/specs/libX11/CH11.xml b/libX11/specs/libX11/CH11.xml
new file mode 100644
index 000000000..1a9bfc139
--- /dev/null
+++ b/libX11/specs/libX11/CH11.xml
@@ -0,0 +1,2539 @@
+<chapter id="event_handling_functions">

+<title>Event Handling Functions</title>

+

+<para>

+This chapter discusses the Xlib functions you can use to:

+</para>

+<itemizedlist>

+  <listitem><para>Select events</para></listitem>

+  <listitem><para>Handle the output buffer and the event queue</para></listitem>

+  <listitem><para>Select events from the event queue</para></listitem>

+  <listitem><para>Send and get events</para></listitem>

+  <listitem><para>Handle protocol errors</para></listitem>

+</itemizedlist>

+<note><para>

+Some toolkits use their own event-handling functions and do not allow you to

+interchange these event-handling functions with those in Xlib. For further

+information, see the documentation supplied with the toolkit.

+</para></note>

+

+<para>

+Most applications simply are event loops: they wait for an event, decide what to do with it,

+execute some amount of code that results in changes to the display, and then wait for the next

+event.

+</para>

+

+<sect1 id="Selecting_Events">

+<title>Selecting Events</title>

+<!-- .XS -->

+<!-- (SN Selecting Events  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+There are two ways to select the events you want reported to your client

+application.

+One way is to set the event_mask member of the

+<function>XSetWindowAttributes</function>

+structure when you call

+<function>XCreateWindow</function>

+and

+<function>XChangeWindowAttributes</function>.

+Another way is to use

+<function>XSelectInput</function>.

+<indexterm significance="preferred"><primary>XSelectInput</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSelectInput</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>long<parameter> event_mask</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN	 -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Wi whose events you are interested in -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window (Wi.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_mask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the event mask.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XSelectInput</function>

+function requests that the X server report the events associated with the 

+specified event mask.

+Initially, X will not report any of these events.

+Events are reported relative to a window.

+If a window is not interested in a device event, it usually propagates to

+the closest ancestor that is interested,

+unless the do_not_propagate mask prohibits it.

+<indexterm><primary>Event</primary><secondary>propagation</secondary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+Setting the event-mask attribute of a window overrides any previous call

+for the same window but not for other clients.

+Multiple clients can select for the same events on the same window

+with the following restrictions:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Multiple clients can select events on the same window because their event masks

+are disjoint.

+When the X server generates an event, it reports it

+to all interested clients.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Only one client at a time can select

+<function>CirculateRequest</function>,

+<function>ConfigureRequest</function>,

+or

+<function>MapRequest</function>

+events, which are associated with

+the event mask

+<function>SubstructureRedirectMask</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Only one client at a time can select

+a

+<function>ResizeRequest</function>

+event, which is associated with

+the event mask

+<function>ResizeRedirectMask</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Only one client at a time can select a 

+<function>ButtonPress </function>

+event, which is associated with

+the event mask

+<function>ButtonPressMask</function>.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+The server reports the event to all interested clients.

+</para>

+<para>

+<!-- .LP -->

+<function>XSelectInput</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+</sect1>

+<sect1 id="Handling_the_Output_Buffer">

+<title>Handling the Output Buffer</title>

+<!-- .XS -->

+<!-- (SN Handling the Output Buffer -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The output buffer is an area used by Xlib to store requests.

+The functions described in this section flush the output buffer

+if the function would block or not return an event.

+That is, all requests residing in the output buffer that

+have not yet been sent are transmitted to the X server.

+These functions differ in the additional tasks they might perform.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To flush the output buffer, use 

+<function>XFlush</function>.

+<indexterm significance="preferred"><primary>XFlush</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XFlush</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XFlush</function>

+function

+flushes the output buffer.

+Most client applications need not use this function because the output

+buffer is automatically flushed as needed by calls to

+<function>XPending</function>,

+<function>XNextEvent</function>,

+and

+<function>XWindowEvent</function>.

+<indexterm><primary>XPending</primary></indexterm>

+<indexterm><primary>XNextEvent</primary></indexterm>

+<indexterm><primary>XWindowEvent</primary></indexterm>

+Events generated by the server may be enqueued into the library's event queue.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To flush the output buffer and then wait until all requests have been processed,

+use 

+<function>XSync</function>.

+<indexterm significance="preferred"><primary>XSync</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSync</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Bool<parameter> discard</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>discard</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a Boolean value that indicates whether 

+<function>XSync</function>

+discards all events on the event queue.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSync</function>

+function

+flushes the output buffer and then waits until all requests have been received

+and processed by the X server.

+Any errors generated must be handled by the error handler.

+For each protocol error received by Xlib,

+<function>XSync</function>

+calls the client application's error handling routine (see section 11.8.2).

+Any events generated by the server are enqueued into the library's 

+event queue.

+</para>

+<para>

+<!-- .LP -->

+Finally, if you passed 

+<function>False</function>,

+<function>XSync</function>

+does not discard the events in the queue.

+If you passed 

+<function>True</function>,

+<function>XSync </function>

+discards all events in the queue,

+including those events that were on the queue before

+<function>XSync</function>

+was called.

+Client applications seldom need to call

+<function>XSync</function>.

+</para>

+</sect1>

+<sect1 id="Event_Queue_Management">

+<title>Event Queue Management</title>

+<!-- .XS -->

+<!-- (SN Event Queue Management -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib maintains an event queue.

+However, the operating system also may be buffering data 

+in its network connection that is not yet read into the event queue.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To check the number of events in the event queue, use

+<function>XEventsQueued</function>.

+<indexterm significance="preferred"><primary>XEventsQueued</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> XEventsQueued</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> mode</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>mode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the mode.

+You can pass

+<function>QueuedAlready</function>,

+<function>QueuedAfterFlush</function>,

+or

+<function>QueuedAfterReading</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If mode is 

+<function>QueuedAlready</function>,

+<function>XEventsQueued </function>

+returns the number of events

+already in the event queue (and never performs a system call).

+If mode is 

+<function>QueuedAfterFlush</function>,

+<function>XEventsQueued</function>

+returns the number of events already in the queue if the number is nonzero.

+If there are no events in the queue, 

+<function>XEventsQueued</function>

+flushes the output buffer, 

+attempts to read more events out of the application's connection,

+and returns the number read.

+If mode is 

+<function>QueuedAfterReading</function>,

+<function>XEventsQueued</function>

+returns the number of events already in the queue if the number is nonzero. 

+If there are no events in the queue, 

+<function>XEventsQueued</function>

+attempts to read more events out of the application's connection 

+without flushing the output buffer and returns the number read.

+</para>

+<para>

+<!-- .LP -->

+<function>XEventsQueued</function>

+always returns immediately without I/O if there are events already in the

+queue.

+<function>XEventsQueued</function>

+with mode 

+<function>QueuedAfterFlush</function>

+is identical in behavior to

+<function>XPending</function>.

+<function>XEventsQueued</function>

+with mode

+<function>QueuedAlready</function>

+is identical to the

+<function>XQLength</function>

+function.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To return the number of events that are pending, use 

+<function>XPending</function>.

+<indexterm significance="preferred"><primary>XPending</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> XPending</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN	 -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XPending</function>

+function returns the number of events that have been received from the

+X server but have not been removed from the event queue.

+<function>XPending</function>

+is identical to

+<function>XEventsQueued</function>

+with the mode

+<function>QueuedAfterFlush</function>

+specified.

+</para>

+</sect1>

+<sect1 id="Manipulating_the_Event_Queue">

+<title>Manipulating the Event Queue</title>

+<!-- .XS -->

+<!-- (SN Manipulating the Event Queue  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that let you manipulate the event queue.

+This section discusses how to:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Obtain events, in order, and remove them from the queue

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Peek at events in the queue without removing them

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Obtain events that match the event mask or the arbitrary

+predicate procedures that you provide

+    </para>

+  </listitem>

+</itemizedlist>

+<sect2 id="Returning_the_Next_Event">

+<title>Returning the Next Event</title>

+<!-- .XS -->

+<!-- (SN Returning the Next Event -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To get the next event and remove it from the queue, use

+<function>XNextEvent</function>.

+<indexterm significance="preferred"><primary>XNextEvent</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XNextEvent</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the next event in the queue.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XNextEvent</function>

+function copies the first event from the event queue into the specified

+<function>XEvent</function>

+structure and then removes it from the queue.

+If the event queue is empty,

+<function>XNextEvent</function>

+flushes the output buffer and blocks until an event is received.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To peek at the event queue, use

+<function>XPeekEvent</function>.

+<indexterm significance="preferred"><primary>XPeekEvent</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XPeekEvent</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns a copy of the matched event's associated structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XPeekEvent</function>

+function returns the first event from the event queue,

+but it does not remove the event from the queue.

+If the queue is empty,

+<function>XPeekEvent</function>

+flushes the output buffer and blocks until an event is received.

+It then copies the event into the client-supplied

+<function>XEvent</function>

+structure without removing it from the event queue.

+</para>

+</sect2>

+<sect2 id="Selecting_Events_Using_a_Predicate_Procedure">

+<title>Selecting Events Using a Predicate Procedure</title>

+<!-- .XS -->

+<!-- (SN Selecting Events Using a Predicate Procedure -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Each of the functions discussed in this section requires you to

+pass a predicate procedure that determines if an event matches 

+what you want.

+Your predicate procedure must decide if the event is useful

+without calling any Xlib functions.

+If the predicate directly or indirectly causes the state of the event queue

+to change, the result is not defined.

+If Xlib has been initialized for threads, the predicate is called with

+the display locked and the result of a call by the predicate to any

+Xlib function that locks the display is not defined unless the caller

+has first called

+<function>XLockDisplay</function>.

+</para>

+<para>

+<!-- .LP -->

+The predicate procedure and its associated arguments are:

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> Bool</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XEvent<parameter> *event</parameter></paramdef>

+  <paramdef>XPointer<parameter> arg</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the

+<function>XEvent</function>

+structure.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>arg</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the argument passed in from the 

+<function>XIfEvent</function>,

+<function>XCheckIfEvent</function>,

+or

+<function>XPeekIfEvent </function>

+function.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The predicate procedure is called once for each

+event in the queue until it finds a match. 

+After finding a match, the predicate procedure must return 

+<function>True</function>.

+If it did not find a match, it must return

+<function>False</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To check the event queue for a matching event

+and, if found, remove the event from the queue, use

+<function>XIfEvent</function>.

+<indexterm significance="preferred"><primary>XIfEvent</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XIfEvent</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

+  <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>

+  <paramdef>XPointer<parameter> arg</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the matched event's associated structure.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>predicate</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the procedure that is to be called to determine

+if the next event in the queue matches what you want.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>arg</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the user-supplied argument that will be passed to the predicate procedure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XIfEvent</function>

+function completes only when the specified predicate

+procedure returns 

+<function>True </function>

+for an event, 

+which indicates an event in the queue matches.

+<function>XIfEvent</function>

+flushes the output buffer if it blocks waiting for additional events.

+<function>XIfEvent</function>

+removes the matching event from the queue 

+and copies the structure into the client-supplied

+<function>XEvent</function>

+structure.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To check the event queue for a matching event without blocking, use

+<function>XCheckIfEvent</function>.

+<indexterm significance="preferred"><primary>XCheckIfEvent</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool<function> XCheckIfEvent</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

+  <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>

+  <paramdef>XPointer<parameter> arg</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns a copy of the matched event's associated structure.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>predicate</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the procedure that is to be called to determine

+if the next event in the queue matches what you want.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>arg</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the user-supplied argument that will be passed to the predicate procedure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+When the predicate procedure finds a match,

+<function>XCheckIfEvent</function>

+copies the matched event into the client-supplied

+<function>XEvent</function>

+structure and returns 

+<function>True</function>.

+(This event is removed from the queue.)

+If the predicate procedure finds no match,

+<function>XCheckIfEvent</function>

+returns

+<function>False</function>,

+and the output buffer will have been flushed.

+All earlier events stored in the queue are not discarded.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To check the event queue for a matching event

+without removing the event from the queue, use

+<function>XPeekIfEvent</function>.

+<indexterm significance="preferred"><primary>XPeekIfEvent</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XPeekIfEvent</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

+  <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>

+  <paramdef>XPointer<parameter> arg</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns a copy of the matched event's associated structure.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>predicate</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the procedure that is to be called to determine

+if the next event in the queue matches what you want.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>arg</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the user-supplied argument that will be passed to the predicate procedure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XPeekIfEvent</function>

+function returns only when the specified predicate

+procedure returns 

+<function>True</function>

+for an event.

+After the predicate procedure finds a match,

+<function>XPeekIfEvent</function>

+copies the matched event into the client-supplied

+<function>XEvent</function>

+structure without removing the event from the queue.

+<function>XPeekIfEvent</function>

+flushes the output buffer if it blocks waiting for additional events.

+</para>

+</sect2>

+<sect2 id="Selecting_Events_Using_a_Window_or_Event_Mask">

+<title>Selecting Events Using a Window or Event Mask</title>

+<!-- .XS -->

+<!-- (SN Selecting Events Using a Window or Event Mask -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The functions discussed in this section let you select events by window 

+or event types, allowing you to process events out of order.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To remove the next event that matches both a window and an event mask, use

+<function>XWindowEvent</function>.

+<indexterm significance="preferred"><primary>XWindowEvent</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XWindowEvent</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>long<parameter> event_mask</parameter></paramdef>

+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Wi whose events you are interested in -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window (Wi.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_mask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the event mask.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the matched event's associated structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XWindowEvent</function>

+function searches the event queue for an event that matches both the specified

+window and event mask.

+When it finds a match,

+<function>XWindowEvent</function>

+removes that event from the queue and copies it into the specified

+<function>XEvent</function>

+structure.

+The other events stored in the queue are not discarded.

+If a matching event is not in the queue,

+<function>XWindowEvent</function>

+flushes the output buffer and blocks until one is received.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To remove the next event that matches both a window and an event mask (if any),

+use

+<function>XCheckWindowEvent</function>.

+<indexterm><primary>XCheckWindowEvent</primary></indexterm>

+This function is similar to

+<function>XWindowEvent </function>

+except that it never blocks and it returns a 

+<function>Bool </function>

+indicating if the event was returned.

+<indexterm significance="preferred"><primary>XCheckWindowEvent</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool<function> XCheckWindowEvent</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>long<parameter> event_mask</parameter></paramdef>

+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Wi whose events you are interested in -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window (Wi.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_mask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the event mask.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the matched event's associated structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCheckWindowEvent</function>

+function searches the event queue and then the events available 

+on the server connection for the first event that matches the specified window

+and event mask.

+If it finds a match,

+<function>XCheckWindowEvent</function>

+removes that event, copies it into the specified

+<function>XEvent</function>

+structure, and returns

+<function>True</function>.

+The other events stored in the queue are not discarded.

+If the event you requested is not available,

+<function>XCheckWindowEvent</function>

+returns

+<function>False</function>,

+and the output buffer will have been flushed.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To remove the next event that matches an event mask, use

+<function>XMaskEvent</function>.

+<indexterm significance="preferred"><primary>XMaskEvent</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XMaskEvent</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>long<parameter> event_mask</parameter></paramdef>

+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_mask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the event mask.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the matched event's associated structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XMaskEvent</function>

+function searches the event queue for the events associated with the 

+specified mask.

+When it finds a match,

+<function>XMaskEvent</function>

+removes that event and copies it into the specified

+<function>XEvent</function>

+structure.

+The other events stored in the queue are not discarded.

+If the event you requested is not in the queue,

+<function>XMaskEvent</function>

+flushes the output buffer and blocks until one is received.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To return and remove the next event that matches an event mask (if any), use

+<function>XCheckMaskEvent</function>.

+This function is similar to 

+<function>XMaskEvent </function>

+except that it never blocks and it returns a 

+<function>Bool </function>

+indicating if the event was returned.

+<indexterm significance="preferred"><primary>XCheckMaskEvent</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool<function> XCheckMaskEvent</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>long<parameter> event_mask</parameter></paramdef>

+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_mask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the event mask.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the matched event's associated structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCheckMaskEvent</function>

+function searches the event queue and then any events available on the

+server connection for the first event that matches the specified mask.

+If it finds a match,

+<function>XCheckMaskEvent</function>

+removes that event, copies it into the specified

+<function>XEvent</function>

+structure, and returns

+<function>True</function>.

+The other events stored in the queue are not discarded.

+If the event you requested is not available,

+<function>XCheckMaskEvent</function>

+returns

+<function>False</function>,

+and the output buffer will have been flushed.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp  -->

+To return and remove the next event in the queue that matches an event type, use

+<function>XCheckTypedEvent</function>.

+<indexterm significance="preferred"><primary>XCheckTypedEvent</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool<function> XCheckTypedEvent</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> event_type</parameter></paramdef>

+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_type</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the event type to be compared.

+

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the matched event's associated structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCheckTypedEvent</function>

+function searches the event queue and then any events available  

+on the server connection for the first event that matches the specified type.

+If it finds a match,

+<function>XCheckTypedEvent</function>

+removes that event, copies it into the specified

+<function>XEvent</function>

+structure, and returns

+<function>True</function>.

+The other events in the queue are not discarded.

+If the event is not available,

+<function>XCheckTypedEvent</function>

+returns

+<function>False</function>,

+and the output buffer will have been flushed.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To return and remove the next event in the queue that matches an event type 

+and a window, use

+<function>XCheckTypedWindowEvent</function>.

+<indexterm significance="preferred"><primary>XCheckTypedWindowEvent</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool<function> XCheckTypedWindowEvent</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>int<parameter> event_type</parameter></paramdef>

+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_type</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the event type to be compared.

+

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the matched event's associated structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCheckTypedWindowEvent</function>

+function searches the event queue and then any events available  

+on the server connection for the first event that matches the specified

+type and window.

+If it finds a match,

+<function>XCheckTypedWindowEvent</function>

+removes the event from the queue, copies it into the specified

+<function>XEvent</function>

+structure, and returns

+<function>True</function>.

+The other events in the queue are not discarded.

+If the event is not available,

+<function>XCheckTypedWindowEvent</function>

+returns

+<function>False</function>,

+and the output buffer will have been flushed.

+</para>

+</sect2>

+</sect1>

+<sect1 id="Putting_an_Event_Back_into_the_Queue">

+<title>Putting an Event Back into the Queue</title>

+<!-- .XS -->

+<!-- (SN Putting an Event Back into the Queue  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To push an event back into the event queue, use

+<function>XPutBackEvent</function>.

+<indexterm significance="preferred"><primary>XPutBackEvent</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XPutBackEvent</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XEvent<parameter> *event</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the event.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XPutBackEvent</function>

+function pushes an event back onto the head of the display's event queue

+by copying the event into the queue.

+This can be useful if you read an event and then decide that you

+would rather deal with it later.

+There is no limit to the number of times in succession that you can call

+<function>XPutBackEvent</function>.

+</para>

+</sect1>

+<sect1 id="Sending_Events_to_Other_Applications">

+<title>Sending Events to Other Applications</title>

+<!-- .XS -->

+<!-- (SN Sending Events to Other Applications -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To send an event to a specified window, use

+<function>XSendEvent</function>.

+<indexterm><primary>XSendEvent</primary></indexterm>

+This function is often used in selection processing.

+For example, the owner of a selection should use

+<function>XSendEvent</function>

+to send a

+<function>SelectionNotify</function>

+event to a requestor when a selection has been converted 

+and stored as a property.

+<indexterm significance="preferred"><primary>XSendEvent</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XSendEvent</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>Bool<parameter> propagate</parameter></paramdef>

+  <paramdef>long<parameter> event_mask</parameter></paramdef>

+  <paramdef>XEvent<parameter> *event_send</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window the event is to be sent to, or

+<function>PointerWindow</function>,

+or

+<function>InputFocus</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>propagate</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a Boolean value.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_mask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the event mask.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_send</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the event that is to be sent.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSendEvent</function>

+function identifies the destination window, 

+determines which clients should receive the specified events, 

+and ignores any active grabs.

+This function requires you to pass an event mask.

+For a discussion of the valid event mask names,

+see section 10.3.

+This function uses the w argument to identify the destination window as follows:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+If w is

+<function>PointerWindow</function>,

+the destination window is the window that contains the pointer.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If w is

+<function>InputFocus </function>

+and if the focus window contains the pointer, 

+the destination window is the window that contains the pointer; 

+otherwise, the destination window is the focus window.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+To determine which clients should receive the specified events,

+<function>XSendEvent</function>

+uses the propagate argument as follows:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+If event_mask is the empty set,

+the event is sent to the client that created the destination window.

+If that client no longer exists,

+no event is sent.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If propagate is 

+<function>False</function>,

+the event is sent to every client selecting on destination any of the event

+types in the event_mask argument.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If propagate is 

+<function>True </function>

+and no clients have selected on destination any of

+the event types in event-mask, the destination is replaced with the

+closest ancestor of destination for which some client has selected a

+type in event-mask and for which no intervening window has that type in its

+do-not-propagate-mask. 

+If no such window exists or if the window is

+an ancestor of the focus window and 

+<function>InputFocus </function>

+was originally specified

+as the destination, the event is not sent to any clients.

+Otherwise, the event is reported to every client selecting on the final

+destination any of the types specified in event_mask.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+The event in the

+<function>XEvent</function>

+structure must be one of the core events or one of the events

+defined by an extension (or a 

+<function>BadValue</function>

+error results) so that the X server can correctly byte-swap 

+the contents as necessary.  

+The contents of the event are

+otherwise unaltered and unchecked by the X server except to force send_event to

+<function>True</function>

+in the forwarded event and to set the serial number in the event correctly;

+therefore these fields

+and the display field are ignored by

+<function>XSendEvent</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XSendEvent</function>

+returns zero if the conversion to wire protocol format failed

+and returns nonzero otherwise.

+</para>

+<para>

+<!-- .LP -->

+<function>XSendEvent</function>

+can generate

+<function>BadValue</function>

+and 

+<function>BadWindow </function>

+errors.

+</para>

+</sect1>

+<sect1 id="Getting_Pointer_Motion_History">

+<title>Getting Pointer Motion History</title>

+<!-- .XS -->

+<!-- (SN Getting Pointer Motion History -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Some X server implementations will maintain a more complete

+history of pointer motion than is reported by event notification.

+The pointer position at each pointer hardware interrupt may be

+stored in a buffer for later retrieval.

+This buffer is called the motion history buffer.

+For example, a few applications, such as paint programs,

+want to have a precise history of where the pointer

+traveled. 

+However, this historical information is highly excessive for most applications.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To determine the approximate maximum number of elements in the motion buffer, 

+use

+<function>XDisplayMotionBufferSize</function>.

+<indexterm significance="preferred"><primary>XDisplayMotionBufferSize</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>unsigned<function> long</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The server may retain the recent history of the pointer motion

+and do so to a finer granularity than is reported by

+<function>MotionNotify</function>

+events.

+The

+<function>XGetMotionEvents</function>

+function makes this history available.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To get the motion history for a specified window and time, use

+<function>XGetMotionEvents</function>.

+<indexterm significance="preferred"><primary>XGetMotionEvents</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XTimeCoord<function> *XGetMotionEvents</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>Timestart,<parameter> stop</parameter></paramdef>

+  <paramdef>int<parameter> *nevents_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>start</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>stop</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the time interval in which the events are returned from the motion

+history buffer.

+You can pass a timestamp or

+<function>CurrentTime</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nevents_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of events from the motion history buffer.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetMotionEvents</function>

+function returns all events in the motion history buffer that fall between the

+specified start and stop times, inclusive, and that have coordinates

+that lie within the specified window (including its borders) at its present

+placement.

+If the server does not support motion history, 

+if the start time is later than the stop time,

+or if the start time is in the future, 

+no events are returned;

+<function>XGetMotionEvents</function>

+returns NULL.

+If the stop time is in the future, it is equivalent to specifying

+<function>CurrentTime</function>.

+The return type for this function is a structure defined as follows:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XTimeCoord</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i -->

+<!-- .ta .5i -->

+typedef struct {

+	Time time;

+	short x, y;

+} XTimeCoord;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The time member is set to the time, in milliseconds. 

+The x and y members are set to the coordinates of the pointer and

+are reported relative to the origin

+of the specified window.

+To free the data returned from this call, use

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetMotionEvents</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+</sect1>

+<sect1 id="Handling_Protocol_Errors">

+<title>Handling Protocol Errors</title>

+<!-- .XS -->

+<!-- (SN Handling Protocol Errors -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to enable or disable synchronization

+and to use the default error handlers.

+</para>

+<sect2 id="Enabling_or_Disabling_Synchronization">

+<title>Enabling or Disabling Synchronization</title>

+<!-- .XS -->

+<!-- (SN Enabling or Disabling Synchronization  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+When debugging X applications, 

+it often is very convenient to require Xlib to behave synchronously

+so that errors are reported as they occur.

+The following function lets you disable or enable synchronous behavior.

+Note that graphics may occur 30 or more times more slowly when 

+synchronization is enabled.

+<indexterm><primary>_Xdebug</primary></indexterm>

+On <acronym>POSIX</acronym>-conformant systems,

+there is also a global variable 

+<function>_Xdebug </function>

+that, if set to nonzero before starting a program under a debugger, will force

+synchronous library behavior.

+</para>

+<para>

+<!-- .LP -->

+After completing their work,

+all Xlib functions that generate protocol requests call what is known as

+an after function.

+<function>XSetAfterFunction</function>

+sets which function is to be called.

+<indexterm significance="preferred"><primary>XSetAfterFunction</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> int</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> (*procedure)()</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>procedure</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the procedure to be called.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The specified procedure is called with only a display pointer.

+<function>XSetAfterFunction</function>

+returns the previous after function.

+</para>

+<para>

+<!-- .LP -->

+To enable or disable synchronization, use 

+<function>XSynchronize</function>.

+<indexterm><primary>Debugging</primary><secondary>synchronous mode</secondary></indexterm>

+<indexterm significance="preferred"><primary>XSynchronize</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> int</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Bool<parameter> onoff</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>onoff</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a Boolean value that indicates whether to enable 

+or disable synchronization.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSynchronize</function>

+function returns 

+the previous after function.

+If onoff is 

+<function>True</function>,

+<function>XSynchronize</function>

+turns on synchronous behavior.

+If onoff is

+<function>False</function>,

+<function>XSynchronize </function>

+turns off synchronous behavior.

+</para>

+</sect2>

+<sect2 id="Using_the_Default_Error_Handlers">

+<title>Using the Default Error Handlers</title>

+<!-- .XS -->

+<!-- (SN Using the Default Error Handlers  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Debugging</primary><secondary>error handlers</secondary></indexterm>

+<indexterm><primary>Error</primary><secondary>handlers</secondary></indexterm>

+There are two default error handlers in Xlib: 

+one to handle typically fatal conditions (for example, 

+the connection to a display server dying because a machine crashed) 

+and one to handle protocol errors from the X server.

+These error handlers can be changed to user-supplied routines if you

+prefer your own error handling and can be changed as often as you like.

+If either function is passed a NULL pointer, it will

+reinvoke the default handler.

+The action of the default handlers is to print an explanatory

+message and exit.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the error handler, use

+<function>XSetErrorHandler</function>.

+<indexterm significance="preferred"><primary>XSetErrorHandler</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> *XSetErrorHandler</function></funcdef>

+  <paramdef>int <parameter> *handler</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>handler</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the program's supplied error handler.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+Xlib generally calls the program's

+supplied error handler whenever an error is received.

+It is not called on

+<function>BadName</function>

+errors from

+<function>OpenFont</function>,

+<function>LookupColor</function>,

+or

+<function>AllocNamedColor</function>

+protocol requests or on

+<function>BadFont</function>

+errors from a

+<function>QueryFont</function>

+protocol request.

+These errors generally are reflected back to the program through the

+procedural interface.

+Because this condition is not assumed to be fatal, 

+it is acceptable for your error handler to return;

+the returned value is ignored.

+However, the error handler should not

+call any functions (directly or indirectly) on the display

+that will generate protocol requests or that will look for input events.

+The previous error handler is returned.

+</para>

+<para>

+<!-- .LP -->

+The 

+<function>XErrorEvent</function>

+structure contains:

+<indexterm><primary>Debugging</primary><secondary>error event</secondary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XErrorEvent</primary></indexterm>

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct {

+	int type;

+	Display *display;	/* Display the event was read from */

+	unsigned long serial;		/* serial number of failed request */

+	unsigned char error_code;	/* error code of failed request */

+	unsigned char request_code;	/* Major op-code of failed request */

+	unsigned char minor_code;	/* Minor op-code of failed request */

+	XID resourceid;		/* resource id */

+} XErrorEvent;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<indexterm><primary>Serial Number</primary></indexterm>

+The serial member is the number of requests, starting from one, 

+sent over the network connection since it was opened. 

+It is the number that was the value of 

+<function>NextRequest </function>

+immediately before the failing call was made.  

+The request_code member is a protocol request

+of the procedure that failed, as defined in 

+&lt; X11/Xproto.h .&gt;

+The following error codes can be returned by the functions described in this

+chapter:

+</para>

+<!-- .br -->

+<!-- .ne 13 -->

+<indexterm><primary>Debugging</primary><secondary>error numbers</secondary></indexterm>

+<indexterm><primary>Error</primary><secondary>codes</secondary></indexterm>

+<!-- .\".CP T 3 -->

+<!-- .\"Error Codes -->

+<indexterm significance="preferred"><primary>BadAccess</primary></indexterm>

+<indexterm significance="preferred"><primary>BadAlloc</primary></indexterm>

+<indexterm significance="preferred"><primary>BadAtom</primary></indexterm>

+<indexterm significance="preferred"><primary>BadColor</primary></indexterm>

+<indexterm significance="preferred"><primary>BadCursor</primary></indexterm>

+<indexterm significance="preferred"><primary>BadDrawable</primary></indexterm>

+<indexterm significance="preferred"><primary>BadFont</primary></indexterm>

+<indexterm significance="preferred"><primary>BadGC</primary></indexterm>

+<indexterm significance="preferred"><primary>BadIDChoice</primary></indexterm>

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <thead>

+    <row>

+      <entry>Error Code</entry>

+      <entry>Description</entry>

+    </row>

+  </thead>

+  <tbody>

+    <row>

+      <entry><function>BadAccess</function></entry>

+      <entry>A client attempts to grab a key/button combination already grabbed

+      by another client.</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>A client attempts to free a colormap entry that it had not already allocated

+      or to free an entry in a colormap that was created with all entries writable.</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>A client attempts to store into a read-only or unallocated colormap entry.</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>A client attempts to modify the access control list from other than the local

+      (or otherwise authorized) host.</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>A client attempts to select an event type that another client

+      has already selected.</entry>

+    </row>

+    <row>

+      <entry><function>BadAlloc</function></entry>

+      <entry>The server fails to allocate the requested resource.

+      Note that the explicit listing of

+      <function>BadAlloc</function>

+      errors in requests only covers allocation errors at a very coarse level

+      and is not intended to (nor can it in practice hope to) cover all cases of

+      a server running out of allocation space in the middle of service.

+      The semantics when a server runs out of allocation space are left unspecified,

+      but a server may generate a

+      <function>BadAlloc</function>

+      error on any request for this reason,

+      and clients should be prepared to receive such errors and handle or discard

+      them.</entry>

+    </row>

+    <row>

+      <entry><function>BadAtom</function></entry>

+      <entry>A value for an atom argument does not name a defined atom.</entry>

+    </row>

+    <row>

+      <entry><function>BadColor</function></entry>

+      <entry>A value for a colormap argument does not name a defined colormap.</entry>

+    </row>

+    <row>

+      <entry><function>BadCursor</function></entry>

+      <entry>A value for a cursor argument does not name a defined cursor.</entry>

+    </row>

+    <row>

+      <entry><function>BadDrawable</function></entry>

+      <entry>A value for a drawable argument does not name a defined window or pixmap.</entry>

+    </row>

+    <row>

+      <entry><function>BadFont</function></entry>

+      <entry>A value for a font argument does not name a defined font (or, in some cases,

+      <function>GContext</function>).</entry>

+    </row>

+    <row>

+      <entry><function>BadGC</function></entry>

+      <entry>A value for a

+      <function>GContext </function>

+      argument does not name a defined 

+      <function>GContext</function>.</entry>

+    </row>

+    <row>

+      <entry><function>BadIDChoice</function></entry>

+      <entry>The value chosen for a resource identifier either is not included in the

+      range assigned to the client or is already in use.

+      Under normal circumstances,

+      this cannot occur and should be considered a server or Xlib error.</entry>

+    </row>

+    <row>

+      <entry><function>BadImplementation</function></entry>

+      <entry>The server does not implement some aspect of the request.

+      A server that generates this error for a core request is deficient.

+      As such, this error is not listed for any of the requests,

+      but clients should be prepared to receive such errors

+      and handle or discard them.</entry>

+    </row>

+    <row>

+      <entry><function>BadLength</function></entry>

+      <entry>The length of a request is shorter or longer than that required to

+      contain the arguments.

+      This is an internal Xlib or server error.</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>

+      The length of a request exceeds the maximum length accepted by the server.</entry>

+    </row>

+    <row>

+      <entry><function>BadMatch</function></entry>

+      <entry>In a graphics request,

+      the root and depth of the graphics context do not match those of the drawable.</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>An <function>InputOnly </function> window is used as a drawable.</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>

+      Some argument or pair of arguments has the correct type and range,

+      but it fails to match in some other way required by the request.</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>An <function>InputOnly </function>

+      window lacks this attribute.</entry>

+    </row>

+    <row>

+      <entry><function>BadName</function></entry>

+      <entry>A font or color of the specified name does not exist.</entry>

+    </row>

+    <row>

+      <entry><function>BadPixmap</function></entry>

+      <entry>A value for a pixmap argument does not name a defined pixmap.</entry>

+    </row>

+    <row>

+      <entry><function>BadRequest</function></entry>

+      <entry>The major or minor opcode does not specify a valid request.

+      This usually is an Xlib or server error.</entry>

+    </row>

+    <row>

+      <entry><function>BadValue</function></entry>

+      <entry>Some numeric value falls outside of the range of values accepted

+      by the request.

+      Unless a specific range is specified for an argument,

+      the full range defined by the argument's type is accepted.

+      Any argument defined as a set of alternatives typically can generate

+      this error (due to the encoding).</entry>

+    </row>

+    <row>

+      <entry><function>BadWindow</function></entry>

+      <entry>A value for a window argument does not name a defined window.</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<indexterm significance="preferred"><primary>BadImplementation</primary></indexterm>

+<indexterm significance="preferred"><primary>BadLength</primary></indexterm>

+<indexterm significance="preferred"><primary>BadMatch</primary></indexterm>

+<indexterm significance="preferred"><primary>BadName</primary></indexterm>

+<indexterm significance="preferred"><primary>BadPixmap</primary></indexterm>

+<indexterm significance="preferred"><primary>BadRequest</primary></indexterm>

+<indexterm significance="preferred"><primary>BadValue</primary></indexterm>

+<indexterm significance="preferred"><primary>BadWindow</primary></indexterm>

+<!-- .NT Note -->

+

+<note>

+<para>

+The 

+<function>BadAtom</function>,

+<function>BadColor</function>,

+<function>BadCursor</function>,

+<function>BadDrawable</function>,

+<function>BadFont</function>,

+<function>BadGC</function>,

+<function>BadPixmap</function>,

+and 

+<function>BadWindow</function>

+errors are also used when the argument type is extended by a set of

+fixed alternatives.

+</para>

+</note>

+

+<!-- .NE -->

+<!-- .sp -->

+<para>

+<!-- .LP -->

+To obtain textual descriptions of the specified error code, use 

+<function>XGetErrorText</function>.

+<indexterm significance="preferred"><primary>XGetErrorText</primary></indexterm>

+<indexterm><primary>Debugging</primary><secondary>error message strings</secondary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XGetErrorText</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> code</parameter></paramdef>

+  <paramdef>char<parameter> *buffer_return</parameter></paramdef>

+  <paramdef>int<parameter> length</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>code</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the error code for which you want to obtain a description.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>buffer_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the error description.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>length</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the size of the buffer.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XGetErrorText</function>

+function copies a null-terminated string describing the specified error code

+into the specified buffer.

+The returned text is in the encoding of the current locale.

+It is recommended that you use this function to obtain an error description

+because extensions to Xlib may define their own error codes

+and error strings.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain error messages from the error database, use

+<function>XGetErrorDatabaseText</function>.

+<indexterm significance="preferred"><primary>XGetErrorDatabaseText</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XGetErrorDatabaseText</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>char*name,<parameter> *message</parameter></paramdef>

+  <paramdef>char<parameter> *default_string</parameter></paramdef>

+  <paramdef>char<parameter> *buffer_return</parameter></paramdef>

+  <paramdef>int<parameter> length</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the name of the application.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>message</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the type of the error message.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>default_string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the default error message if none is found in the database.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>buffer_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the error description.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>length</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the size of the buffer.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetErrorDatabaseText</function>

+function returns a null-terminated message

+(or the default message) from the error message

+database.

+Xlib uses this function internally to look up its error messages.

+The text in the default_string argument is assumed

+to be in the encoding of the current locale,

+and the text stored in the buffer_return argument

+is in the encoding of the current locale.

+</para>

+<para>

+<!-- .LP -->

+The name argument should generally be the name of your application.

+The message argument should indicate which type of error message you want.

+If the name and message are not in the Host Portable Character Encoding,

+the result is implementation-dependent.

+Xlib uses three predefined ``application names'' to report errors.

+In these names,

+uppercase and lowercase matter.

+<variablelist>

+  <varlistentry>

+    <term>

+      XProtoError

+    </term>

+    <listitem>

+      <para>

+The protocol error number is used as a string for the message argument.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      XlibMessage

+    </term>

+    <listitem>

+      <para>

+These are the message strings that are used internally by the library.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      XRequest

+    </term>

+    <listitem>

+      <para>

+For a core protocol request,

+the major request protocol number is used for the message argument.

+For an extension request,

+the extension name (as given by

+<function>InitExtension</function>)

+followed by a period (\.) and the minor request protocol number 

+is used for the message argument.

+If no string is found in the error database,

+the default_string is returned to the buffer argument.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To report an error to the user when the requested display does not exist, use

+<function>XDisplayName</function>.

+<indexterm significance="preferred"><primary>XDisplayName</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> *XDisplayName</function></funcdef>

+  <paramdef>char<parameter> *string</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the character string.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XDisplayName</function>

+function returns the name of the display that 

+<function>XOpenDisplay</function>

+would attempt to use.

+If a NULL string is specified,

+<function>XDisplayName</function>

+looks in the environment for the display and returns the display name that

+<function>XOpenDisplay</function>

+would attempt to use.

+This makes it easier to report to the user precisely which display the

+program attempted to open when the initial connection attempt failed.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To handle fatal I/O errors, use

+<function>XSetIOErrorHandler</function>.

+<indexterm significance="preferred"><primary>XSetIOErrorHandler</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> int</function></funcdef>

+  <paramdef>int(*handler)(Display<parameter> *)</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>handler</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the program's supplied error handler.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetIOErrorHandler</function>

+sets the fatal I/O error handler.

+Xlib calls the program's supplied error handler if any sort of system call

+error occurs (for example, the connection to the server was lost).

+This is assumed to be a fatal condition,

+and the called routine should not return.

+If the I/O error handler does return,

+the client process exits.

+</para>

+<para>

+<!-- .LP -->

+Note that the previous error handler is returned.

+<!-- .bp -->

+

+</para>

+</sect2>

+</sect1>

+</chapter>

diff --git a/libX11/specs/libX11/CH12 b/libX11/specs/libX11/CH12
deleted file mode 100644
index 08b9ba93a..000000000
--- a/libX11/specs/libX11/CH12
+++ /dev/null
@@ -1,2680 +0,0 @@
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-.\" OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" Except as contained in this notice, the name of the X Consortium shall
-.\" not be used in advertising or otherwise to promote the sale, use or
-.\" other dealings in this Software without prior written authorization
-.\" from the X Consortium.
-.\"
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
-.\" Digital Equipment Corporation
-.\"
-.\" Portions Copyright \(co 1990, 1991 by
-.\" Tektronix, Inc.
-.\"
-.\" Permission to use, copy, modify and distribute this documentation for
-.\" any purpose and without fee is hereby granted, provided that the above
-.\" copyright notice appears in all copies and that both that copyright notice
-.\" and this permission notice appear in all copies, and that the names of
-.\" Digital and Tektronix not be used in in advertising or publicity pertaining
-.\" to this documentation without specific, written prior permission.
-.\" Digital and Tektronix makes no representations about the suitability
-.\" of this documentation for any purpose.
-.\" It is provided ``as is'' without express or implied warranty.
-.\" 
-\&
-.sp 1
-.ce 3
-\s+1\fBChapter 12\fP\s-1
-
-\s+1\fBInput Device Functions\fP\s-1
-.sp 2
-.nr H1 12
-.nr H2 0
-.nr H3 0
-.nr H4 0
-.nr H5 0
-.na
-.LP
-.XS
-Chapter 12: Input Device Functions
-.XE
-You can use the Xlib input device functions to:
-.IP \(bu 5
-Grab the pointer and individual buttons on the pointer
-.IP \(bu 5
-Grab the keyboard and individual keys on the keyboard
-.IP \(bu 5
-Resume event processing
-.IP \(bu 5
-Move the pointer
-.IP \(bu 5
-Set the input focus
-.IP \(bu 5
-Manipulate the keyboard and pointer settings
-.IP \(bu 5
-Manipulate the keyboard encoding
-.NH 2
-Pointer Grabbing 
-.XS
-\*(SN Pointer Grabbing  
-.XE
-.LP
-Xlib provides functions that you can use to control input from the pointer,
-which usually is a mouse.
-Usually, as soon as keyboard and mouse events occur,
-the X server delivers them to the appropriate client,
-which is determined by the window and input focus.
-The X server provides sufficient control over event delivery to
-allow window managers to support mouse ahead and various other
-styles of user interface.
-Many of these user interfaces depend on synchronous delivery of events.
-The delivery of  pointer and keyboard events can be controlled
-independently.
-.LP
-When mouse buttons or keyboard keys are grabbed, events
-will be sent to the grabbing client rather than the normal
-client who would have received the event.
-If the keyboard or pointer is in asynchronous mode,
-further mouse and keyboard events will continue to be processed.
-If the keyboard or pointer is in synchronous mode, no
-further events are processed until the grabbing client
-allows them (see
-.PN XAllowEvents ).
-The keyboard or pointer is considered frozen during this
-interval.
-The event that triggered the grab can also be replayed.
-.LP
-Note that the logical state of a device (as seen by client applications)
-may lag the physical state if device event processing is frozen.
-.LP
-.IN "Active grab" "" "@DEF@"
-There are two kinds of grabs:
-active and passive.
-An active grab occurs when a single client grabs the keyboard and/or pointer
-explicitly (see
-.PN XGrabPointer
-and
-.PN XGrabKeyboard ).
-.IN "Passive grab"
-A passive grab occurs when clients grab a particular keyboard key 
-or pointer button in a window,
-and the grab will activate when the key or button is actually pressed.
-Passive grabs are convenient for implementing reliable pop-up menus.
-For example, you can guarantee that the pop-up is mapped 
-before the up pointer button event occurs by
-grabbing a button requesting synchronous behavior.
-The down event will trigger the grab and freeze further
-processing of pointer events until you have the chance to
-map the pop-up window.
-You can then allow further event processing.
-The up event will then be correctly processed relative to the
-pop-up window.
-.LP
-For many operations,
-there are functions that take a time argument.
-The X server includes a timestamp in various events.
-One special time, called
-.IN "CurrentTime" "" "@DEF@"
-.IN "Time" "" "@DEF@"
-.PN CurrentTime ,
-represents the current server time.
-The X server maintains the time when the input focus was last changed,
-when the keyboard was last grabbed,
-when the pointer was last grabbed,
-or when a selection was last changed.
-Your
-application may be slow reacting to an event.
-You often need some way to specify that your
-request should not occur if another application has in the meanwhile
-taken control of the keyboard, pointer, or selection.
-By providing the timestamp from the event in the request, 
-you can arrange that the operation not take effect
-if someone else has performed an operation in the meanwhile.
-.LP
-A timestamp is a time value, expressed in milliseconds. 
-It typically is the time since the last server reset.
-Timestamp values wrap around (after about 49.7 days).
-The server, given its current time is represented by timestamp T, 
-always interprets timestamps from clients by treating half of the timestamp 
-space as being later in time than T.
-One timestamp value, named
-.PN CurrentTime ,
-is never generated by the server.
-This value is reserved for use in requests to represent the current server time.
-.LP
-For many functions in this section,
-you pass pointer event mask bits.
-The valid pointer event mask bits are:
-.PN ButtonPressMask ,
-.PN ButtonReleaseMask ,
-.PN EnterWindowMask ,
-.PN LeaveWindowMask ,
-.PN PointerMotionMask ,
-.PN PointerMotionHintMask ,
-.PN Button1MotionMask ,
-.PN Button2MotionMask ,
-.PN Button3MotionMask ,
-.PN Button4MotionMask ,
-.PN Button5MotionMask ,
-.PN ButtonMotionMask ,
-and
-.PN KeyMapStateMask .
-For other functions in this section,
-you pass keymask bits.
-The valid keymask bits are:
-.PN ShiftMask ,
-.PN LockMask ,
-.PN ControlMask ,
-.PN Mod1Mask ,
-.PN Mod2Mask ,
-.PN Mod3Mask ,
-.PN Mod4Mask ,
-and
-.PN Mod5Mask .
-.LP
-.sp
-To grab the pointer, use
-.PN XGrabPointer .
-.IN "Grabbing" "pointer"
-.IN "Pointer" "grabbing"
-.IN "XGrabPointer" "" "@DEF@"
-.sM
-.FD 0
-int XGrabPointer\^(\^\fIdisplay\fP, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIevent_mask\fP\^, \fIpointer_mode\fP\^,
-               \fIkeyboard_mode\fP\^, \fIconfine_to\fP\^, \fIcursor\fP\^, \fItime\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIgrab_window\fP\^;
-.br
-      Bool \fIowner_events\fP\^;
-.br
-      unsigned int \fIevent_mask\fP\^;	
-.br
-      int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^; 
-.br
-      Window \fIconfine_to\fP\^; 
-.br
-      Cursor \fIcursor\fP\^; 
-.br
-      Time \fItime\fP\^; 
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgrab_window\fP 1i
-Specifies the grab window.
-.IP \fIowner_events\fP 1i
-Specifies a Boolean value that indicates whether the pointer 
-events are to be reported as usual or reported with respect to the grab window 
-if selected by the event mask.
-.IP \fIevent_mask\fP 1i
-Specifies which pointer events are reported to the client.
-The mask is the bitwise inclusive OR of the valid pointer event mask bits.
-.IP \fIpointer_mode\fP 1i
-Specifies further processing of pointer events.
-You can pass 
-.PN GrabModeSync 
-or
-.PN GrabModeAsync .
-.IP \fIkeyboard_mode\fP 1i
-Specifies further processing of keyboard events.
-You can pass 
-.PN GrabModeSync 
-or
-.PN GrabModeAsync .
-.IP \fIconfine_to\fP 1i
-Specifies the window to confine the pointer in or
-.PN None .
-.IP \fIcursor\fP 1i
-Specifies the cursor that is to be displayed during the grab or
-.PN None . 
-.IP \fItime\fP 1i
-Specifies the time.
-You can pass either a timestamp or
-.PN CurrentTime .
-.LP
-.eM
-The
-.PN XGrabPointer
-function actively grabs control of the pointer and returns
-.PN GrabSuccess
-if the grab was successful.
-Further pointer events are reported only to the grabbing client.
-.PN XGrabPointer
-overrides any active pointer grab by this client.
-If owner_events is 
-.PN False , 
-all generated pointer events
-are reported with respect to grab_window and are reported only if
-selected by event_mask.
-If owner_events is 
-.PN True
-and if a generated
-pointer event would normally be reported to this client, 
-it is reported as usual. 
-Otherwise, the event is reported with respect to the
-grab_window and is reported only if selected by event_mask.
-For either value of owner_events, unreported events are discarded.
-.LP
-If the pointer_mode is 
-.PN GrabModeAsync , 
-pointer event processing continues as usual.
-If the pointer is currently frozen by this client, 
-the processing of events for the pointer is resumed.
-If the pointer_mode is 
-.PN GrabModeSync , 
-the state of the pointer, as seen by
-client applications,
-appears to freeze, and the X server generates no further pointer events
-until the grabbing client calls 
-.PN XAllowEvents
-or until the pointer grab is released.
-Actual pointer changes are not lost while the pointer is frozen;
-they are simply queued in the server for later processing.
-.LP
-If the keyboard_mode is 
-.PN GrabModeAsync , 
-keyboard event processing is unaffected by activation of the grab.
-If the keyboard_mode is 
-.PN GrabModeSync , 
-the state of the keyboard, as seen by
-client applications,
-appears to freeze, and the X server generates no further keyboard events
-until the grabbing client calls 
-.PN XAllowEvents
-or until the pointer grab is released.
-Actual keyboard changes are not lost while the pointer is frozen;
-they are simply queued in the server for later processing.
-.LP
-If a cursor is specified, it is displayed regardless of what
-window the pointer is in.  
-If 
-.PN None
-is specified,
-the normal cursor for that window is displayed
-when the pointer is in grab_window or one of its subwindows;
-otherwise, the cursor for grab_window is displayed.
-.LP
-If a confine_to window is specified,
-the pointer is restricted to stay contained in that window.
-The confine_to window need have no relationship to the grab_window.
-If the pointer is not initially in the confine_to window, 
-it is warped automatically to the closest edge 
-just before the grab activates and enter/leave events are generated as usual. 
-If the confine_to window is subsequently reconfigured, 
-the pointer is warped automatically, as necessary, 
-to keep it contained in the window.
-.LP
-The time argument allows you to avoid certain circumstances that come up
-if applications take a long time to respond or if there are long network
-delays.
-Consider a situation where you have two applications, both
-of which normally grab the pointer when clicked on.
-If both applications specify the timestamp from the event, 
-the second application may wake up faster and successfully grab the pointer
-before the first application. 
-The first application then will get an indication that the other application 
-grabbed the pointer before its request was processed.
-.LP
-.PN XGrabPointer 
-generates
-.PN EnterNotify 
-and
-.PN LeaveNotify 
-events.
-.LP
-Either if grab_window or confine_to window is not viewable
-or if the confine_to window lies completely outside the boundaries of the root
-window,
-.PN XGrabPointer
-fails and returns
-.PN GrabNotViewable .
-If the pointer is actively grabbed by some other client,
-it fails and returns
-.PN AlreadyGrabbed .
-If the pointer is frozen by an active grab of another client,
-it fails and returns
-.PN GrabFrozen .
-If the specified time is earlier than the last-pointer-grab time or later 
-than the current X server time, it fails and returns
-.PN GrabInvalidTime .
-Otherwise, the last-pointer-grab time is set to the specified time
-.Pn ( CurrentTime 
-is replaced by the current X server time).
-.LP
-.PN XGrabPointer
-can generate
-.PN BadCursor ,
-.PN BadValue ,
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To ungrab the pointer, use
-.PN XUngrabPointer .
-.IN "Ungrabbing" "pointer"
-.IN "Pointer" "ungrabbing"
-.IN "XUngrabPointer" "" "@DEF@"
-.sM
-.FD 0
-XUngrabPointer\^(\^\fIdisplay\fP, \fItime\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Time \fItime\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fItime\fP 1i
-Specifies the time.
-You can pass either a timestamp or
-.PN CurrentTime .
-.LP
-.eM
-The
-.PN XUngrabPointer
-function releases the pointer and any queued events
-if this client has actively grabbed the pointer from
-.PN XGrabPointer ,
-.PN XGrabButton ,
-or from a normal button press.
-.PN XUngrabPointer
-does not release the pointer if the specified
-time is earlier than the last-pointer-grab time or is later than the
-current X server time.
-It also generates 
-.PN EnterNotify 
-and 
-.PN LeaveNotify 
-events.
-The X server performs an 
-.PN UngrabPointer 
-request automatically if the event window or confine_to window 
-for an active pointer grab becomes not viewable
-or if window reconfiguration causes the confine_to window to lie completely
-outside the boundaries of the root window.
-.LP
-.sp
-To change an active pointer grab, use
-.PN XChangeActivePointerGrab .
-.IN "Pointer" "grabbing"
-.IN "Changing" "pointer grab" 
-.IN "XChangeActivePointerGrab" "" "@DEF@"
-.sM
-.FD 0
-XChangeActivePointerGrab\^(\^\fIdisplay\fP, \fIevent_mask\fP\^, \fIcursor\fP\^, \fItime\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      unsigned int \fIevent_mask\fP\^;
-.br
-      Cursor \fIcursor\fP\^;
-.br
-      Time \fItime\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIevent_mask\fP 1i
-Specifies which pointer events are reported to the client.
-The mask is the bitwise inclusive OR of the valid pointer event mask bits.
-.IP \fIcursor\fP 1i
-Specifies the cursor that is to be displayed or
-.PN None .
-.IP \fItime\fP 1i
-Specifies the time.
-You can pass either a timestamp or
-.PN CurrentTime .
-.LP
-.eM
-The
-.PN XChangeActivePointerGrab
-function changes the specified dynamic parameters if the pointer is actively
-grabbed by the client and if the specified time is no earlier than the
-last-pointer-grab time and no later than the current X server time.
-This function has no effect on the passive parameters of an
-.PN XGrabButton .
-The interpretation of event_mask and cursor is the same as described in
-.PN XGrabPointer .
-.LP
-.PN XChangeActivePointerGrab
-can generate
-.PN BadCursor 
-and
-.PN BadValue
-errors.
-.LP
-.sp
-To grab a pointer button, use
-.PN XGrabButton .
-.IN "Grabbing" "buttons"
-.IN "Button" "grabbing"
-.IN "XGrabButton" "" "@DEF@"
-.sM
-.FD 0
-XGrabButton\^(\^\fIdisplay\fP, \fIbutton\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIevent_mask\fP\^, 
-.br
-                \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^, \fIconfine_to\fP\^, \fIcursor\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      unsigned int \fIbutton\fP\^;
-.br
-      unsigned int \fImodifiers\fP\^;
-.br
-      Window \fIgrab_window\fP\^;
-.br
-      Bool \fIowner_events\fP\^;
-.br
-      unsigned int \fIevent_mask\fP\^;	
-.br
-      int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^;
-.br
-      Window \fIconfine_to\fP\^; 
-.br
-      Cursor \fIcursor\fP\^; 
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Bu grabbed
-.IP \fIbutton\fP 1i
-Specifies the pointer button that is to be \*(Bu or
-.PN AnyButton .
-.IP \fImodifiers\fP 1i
-Specifies the set of keymasks or
-.PN AnyModifier .
-The mask is the bitwise inclusive OR of the valid keymask bits.
-.IP \fIgrab_window\fP 1i
-Specifies the grab window.
-.IP \fIowner_events\fP 1i
-Specifies a Boolean value that indicates whether the pointer 
-events are to be reported as usual or reported with respect to the grab window 
-if selected by the event mask.
-.IP \fIevent_mask\fP 1i
-Specifies which pointer events are reported to the client.
-The mask is the bitwise inclusive OR of the valid pointer event mask bits.
-.IP \fIpointer_mode\fP 1i
-Specifies further processing of pointer events.
-You can pass 
-.PN GrabModeSync 
-or
-.PN GrabModeAsync .
-.IP \fIkeyboard_mode\fP 1i
-Specifies further processing of keyboard events.
-You can pass 
-.PN GrabModeSync 
-or
-.PN GrabModeAsync .
-.IP \fIconfine_to\fP 1i
-Specifies the window to confine the pointer in or
-.PN None .
-.IP \fIcursor\fP 1i
-Specifies the cursor that is to be displayed or
-.PN None .
-.LP
-.eM
-The
-.PN XGrabButton
-function establishes a passive grab.
-In the future,
-the pointer is actively grabbed (as for
-.PN XGrabPointer ),
-the last-pointer-grab time is set to the time at which the button was pressed
-(as transmitted in the
-.PN ButtonPress
-event), and the
-.PN ButtonPress
-event is reported if all of the following conditions are true:
-.IP \(bu 5
-The pointer is not grabbed, and the specified button is logically pressed
-when the specified modifier keys are logically down,
-and no other buttons or modifier keys are logically down.
-.IP \(bu 5
-The grab_window contains the pointer.
-.IP \(bu 5
-The confine_to window (if any) is viewable.
-.IP \(bu 5
-A passive grab on the same button/key combination does not exist
-on any ancestor of grab_window.
-.LP
-The interpretation of the remaining arguments is as for
-.PN XGrabPointer .
-The active grab is terminated automatically when the logical state of the
-pointer has all buttons released
-(independent of the state of the logical modifier keys).
-.LP
-Note that the logical state of a device (as seen by client applications)
-may lag the physical state if device event processing is frozen.
-.LP
-This request overrides all previous grabs by the same client on the same
-button/key combinations on the same window.
-A modifiers of 
-.PN AnyModifier 
-is equivalent to issuing the grab request for all
-possible modifier combinations (including the combination of no modifiers).  
-It is not required that all modifiers specified have currently assigned 
-KeyCodes.
-A button of 
-.PN AnyButton 
-is equivalent to
-issuing the request for all possible buttons.
-Otherwise, it is not required that the specified button currently be assigned
-to a physical button.
-.LP
-If some other client has already issued an
-.PN XGrabButton
-with the same button/key combination on the same window, a
-.PN BadAccess 
-error results.
-When using 
-.PN AnyModifier 
-or 
-.PN AnyButton , 
-the request fails completely,
-and a
-.PN BadAccess
-error results (no grabs are
-established) if there is a conflicting grab for any combination.
-.PN XGrabButton
-has no effect on an active grab.
-.LP
-.PN XGrabButton
-can generate
-.PN BadCursor ,
-.PN BadValue ,
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To ungrab a pointer button, use
-.PN XUngrabButton .
-.IN "Ungrabbing" "buttons"
-.IN "Button" "ungrabbing"
-.IN "XUngrabButton" "" "@DEF@"
-.sM
-.FD 0
-XUngrabButton\^(\^\fIdisplay\fP, \fIbutton\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      unsigned int \fIbutton\fP\^;
-.br
-      unsigned int \fImodifiers\fP\^;
-.br
-      Window \fIgrab_window\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Bu released
-.IP \fIbutton\fP 1i
-Specifies the pointer button that is to be \*(Bu or
-.PN AnyButton .
-.IP \fImodifiers\fP 1i
-Specifies the set of keymasks or
-.PN AnyModifier .
-The mask is the bitwise inclusive OR of the valid keymask bits.
-.IP \fIgrab_window\fP 1i
-Specifies the grab window.
-.LP
-.eM
-The
-.PN XUngrabButton
-function releases the passive button/key combination on the specified window if
-it was grabbed by this client.
-A modifiers of 
-.PN AnyModifier 
-is
-equivalent to issuing 
-the ungrab request for all possible modifier combinations, including 
-the combination of no modifiers.
-A button of 
-.PN AnyButton 
-is equivalent to issuing the
-request for all possible buttons.
-.PN XUngrabButton
-has no effect on an active grab.
-.LP
-.PN XUngrabButton
-can generate
-.PN BadValue
-and
-.PN BadWindow 
-errors.
-.NH 2
-Keyboard Grabbing 
-.XS
-\*(SN Keyboard Grabbing 
-.XE
-.LP
-Xlib provides functions that you can use to grab or ungrab the keyboard
-as well as allow events.
-.LP
-For many functions in this section,
-you pass keymask bits.
-The valid keymask bits are:
-.PN ShiftMask ,
-.PN LockMask ,
-.PN ControlMask ,
-.PN Mod1Mask ,
-.PN Mod2Mask ,
-.PN Mod3Mask ,
-.PN Mod4Mask ,
-and
-.PN Mod5Mask .
-.LP
-.sp
-To grab the keyboard, use
-.PN XGrabKeyboard .
-.IN "Keyboard" "grabbing"
-.IN "Grabbing" "keyboard"
-.IN "XGrabKeyboard" "" "@DEF@"
-.sM
-.FD 0
-int XGrabKeyboard\^(\^\fIdisplay\fP, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^, \fItime\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIgrab_window\fP\^;
-.br
-      Bool \fIowner_events\fP\^;
-.br
-      int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^;
-.br
-      Time \fItime\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgrab_window\fP 1i
-Specifies the grab window.
-.IP \fIowner_events\fP 1i
-Specifies a Boolean value that indicates whether the keyboard events 
-are to be reported as usual.
-.IP \fIpointer_mode\fP 1i
-Specifies further processing of pointer events.
-You can pass 
-.PN GrabModeSync 
-or
-.PN GrabModeAsync .
-.IP \fIkeyboard_mode\fP 1i
-Specifies further processing of keyboard events.
-You can pass 
-.PN GrabModeSync 
-or
-.PN GrabModeAsync .
-.IP \fItime\fP 1i
-Specifies the time.
-You can pass either a timestamp or
-.PN CurrentTime .
-.LP
-.eM
-The
-.PN XGrabKeyboard
-function actively grabs control of the keyboard and generates
-.PN FocusIn
-and
-.PN FocusOut
-events.
-Further key events are reported only to the
-grabbing client.
-.PN XGrabKeyboard
-overrides any active keyboard grab by this client.
-If owner_events is 
-.PN False , 
-all generated key events are reported with
-respect to grab_window.  
-If owner_events is 
-.PN True  
-and if a generated
-key event would normally be reported to this client, it is reported
-normally; otherwise, the event is reported with respect to the
-grab_window.  
-Both 
-.PN KeyPress 
-and 
-.PN KeyRelease 
-events are always reported,
-independent of any event selection made by the client.
-.LP
-If the keyboard_mode argument is 
-.PN GrabModeAsync ,
-keyboard event processing continues
-as usual. 
-If the keyboard is currently frozen by this client, 
-then processing of keyboard events is resumed.
-If the keyboard_mode  argument is
-.PN GrabModeSync ,
-the state of the keyboard (as seen by client applications) appears to freeze,
-and the X server generates no further keyboard events until the
-grabbing client issues a releasing 
-.PN XAllowEvents 
-call or until the keyboard grab is released.
-Actual keyboard changes are not lost while the keyboard is frozen; 
-they are simply queued in the server for later processing.
-.LP
-If pointer_mode is 
-.PN GrabModeAsync ,
-pointer event processing is unaffected
-by activation of the grab.  
-If pointer_mode is 
-.PN GrabModeSync ,
-the state of the pointer (as seen by client applications) appears to freeze, 
-and the X server generates no further pointer events 
-until the grabbing client issues a releasing 
-.PN XAllowEvents 
-call or until the keyboard grab is released.
-Actual pointer changes are not lost while the pointer is frozen; 
-they are simply queued in the server for later processing.
-.LP
-If the keyboard is actively grabbed by some other client,
-.PN XGrabKeyboard
-fails and returns
-.PN AlreadyGrabbed .
-If grab_window is not viewable,
-it fails and returns
-.PN GrabNotViewable .
-If the keyboard is frozen by an active grab of another client,
-it fails and returns
-.PN GrabFrozen .
-If the specified time is earlier than the last-keyboard-grab time 
-or later than the current X server time,
-it fails and returns
-.PN GrabInvalidTime .
-Otherwise, the last-keyboard-grab time is set to the specified time
-.Pn ( CurrentTime 
-is replaced by the current X server time).
-.LP
-.PN XGrabKeyboard
-can generate
-.PN BadValue
-and 
-.PN BadWindow 
-errors.
-.LP
-.sp
-To ungrab the keyboard, use
-.PN XUngrabKeyboard .
-.IN "Keyboard" "ungrabbing"
-.IN "Ungrabbing" "keyboard"
-.IN "XUngrabKeyboard" "" "@DEF@"
-.sM
-.FD 0
-XUngrabKeyboard\^(\^\fIdisplay\fP, \fItime\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Time \fItime\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fItime\fP 1i
-Specifies the time.
-You can pass either a timestamp or
-.PN CurrentTime .
-.LP
-.eM
-The
-.PN XUngrabKeyboard
-function
-releases the keyboard and any queued events if this client has it actively grabbed from
-either
-.PN XGrabKeyboard
-or
-.PN XGrabKey .
-.PN XUngrabKeyboard
-does not release the keyboard and any queued events
-if the specified time is earlier than
-the last-keyboard-grab time or is later than the current X server time.
-It also generates
-.PN FocusIn 
-and 
-.PN FocusOut 
-events.
-The X server automatically performs an 
-.PN UngrabKeyboard 
-request if the event window for an
-active keyboard grab becomes not viewable.
-.LP
-.sp
-To passively grab a single key of the keyboard, use
-.PN XGrabKey .
-.IN "Key" "grabbing"
-.IN "Grabbing" "keys"
-.IN "XGrabKey" "" "@DEF@"
-.sM
-.FD 0
-XGrabKey\^(\^\fIdisplay\fP, \fIkeycode\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIpointer_mode\fP\^, 
-.br
-             \fIkeyboard_mode\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIkeycode\fP\^;
-.br
-      unsigned int \fImodifiers\fP\^;
-.br
-      Window \fIgrab_window\fP\^;
-.br
-      Bool \fIowner_events\fP\^;
-.br
-      int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIkeycode\fP 1i
-Specifies the KeyCode or
-.PN AnyKey .
-.IP \fImodifiers\fP 1i
-Specifies the set of keymasks or
-.PN AnyModifier .
-The mask is the bitwise inclusive OR of the valid keymask bits.
-.IP \fIgrab_window\fP 1i
-Specifies the grab window.
-.IP \fIowner_events\fP 1i
-Specifies a Boolean value that indicates whether the keyboard events 
-are to be reported as usual.
-.IP \fIpointer_mode\fP 1i
-Specifies further processing of pointer events.
-You can pass 
-.PN GrabModeSync 
-or
-.PN GrabModeAsync .
-.IP \fIkeyboard_mode\fP 1i
-Specifies further processing of keyboard events.
-You can pass 
-.PN GrabModeSync 
-or
-.PN GrabModeAsync .
-.LP
-.eM
-The
-.PN XGrabKey
-function establishes a passive grab on the keyboard.
-In the future,
-the keyboard is actively grabbed (as for
-.PN XGrabKeyboard ),
-the last-keyboard-grab time is set to the time at which the key was pressed
-(as transmitted in the
-.PN KeyPress
-event), and the
-.PN KeyPress
-event is reported if all of the following conditions are true:
-.IP \(bu 5
-The keyboard is not grabbed and the specified key
-(which can itself be a modifier key) is logically pressed
-when the specified modifier keys are logically down,
-and no other modifier keys are logically down.
-.IP \(bu 5
-Either the grab_window is an ancestor of (or is) the focus window,
-or the grab_window is a descendant of the focus window and contains the pointer.
-.IP \(bu 5
-A passive grab on the same key combination does not exist
-on any ancestor of grab_window.
-.LP
-The interpretation of the remaining arguments is as for 
-.PN XGrabKeyboard .
-The active grab is terminated automatically when the logical state of the
-keyboard has the specified key released
-(independent of the logical state of the modifier keys).
-.LP
-Note that the logical state of a device (as seen by client applications)
-may lag the physical state if device event processing is frozen.
-.LP
-A modifiers argument of 
-.PN AnyModifier
-is equivalent to issuing the request for all
-possible modifier combinations (including the combination of no
-modifiers).  
-It is not required that all modifiers specified have
-currently assigned KeyCodes.
-A keycode argument of 
-.PN AnyKey
-is equivalent to issuing
-the request for all possible KeyCodes.
-Otherwise, the specified keycode must be in
-the range specified by min_keycode and max_keycode in the connection
-setup, 
-or a
-.PN BadValue
-error results.
-.LP
-If some other client has issued a 
-.PN XGrabKey
-with the same key combination on the same window, a 
-.PN BadAccess 
-error results.
-When using
-.PN AnyModifier
-or 
-.PN AnyKey ,
-the request fails completely,
-and a
-.PN BadAccess 
-error results (no grabs are established) 
-if there is a conflicting grab for any combination.
-.LP
-.PN XGrabKey
-can generate
-.PN BadAccess ,
-.PN BadValue , 
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To ungrab a key, use
-.PN XUngrabKey .
-.IN "Key" "ungrabbing"
-.IN "Ungrabbing" "keys"
-.IN "XUngrabKey" "" "@DEF@"
-.sM
-.FD 0
-XUngrabKey\^(\^\fIdisplay\fP, \fIkeycode\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIkeycode\fP\^;
-.br
-      unsigned int \fImodifiers\fP\^;
-.br
-      Window \fIgrab_window\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIkeycode\fP 1i
-Specifies the KeyCode or
-.PN AnyKey .
-.IP \fImodifiers\fP 1i
-Specifies the set of keymasks or
-.PN AnyModifier .
-The mask is the bitwise inclusive OR of the valid keymask bits.
-.IP \fIgrab_window\fP 1i
-Specifies the grab window.
-.LP
-.eM
-The
-.PN XUngrabKey
-function releases the key combination on the specified window if it was grabbed
-by this client.
-It has no effect on an active grab.
-A modifiers of
-.PN AnyModifier
-is equivalent to issuing
-the request for all possible modifier combinations
-(including the combination of no modifiers).
-A keycode argument of
-.PN AnyKey
-is equivalent to issuing the request for all possible key codes.
-.LP
-.PN XUngrabKey
-can generate
-.PN BadValue
-and
-.PN BadWindow 
-errors.
-.NH 2
-Resuming Event Processing
-.XS
-\*(SN Resuming Event Processing
-.XE
-.LP
-The previous sections discussed grab mechanisms with which processing
-of events by the server can be temporarily suspended.  This section
-describes the mechanism for resuming event processing.
-.LP
-.sp
-To allow further events to be processed when the device has been frozen, use
-.PN XAllowEvents .
-.IN "XAllowEvents" "" "@DEF@"
-.sM
-.FD 0
-XAllowEvents\^(\^\fIdisplay\fP, \fIevent_mode\fP\^, \fItime\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIevent_mode\fP\^; 
-.br
-      Time \fItime\fP\^; 
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIevent_mode\fP 1i
-Specifies the event mode.
-You can pass 
-.PN AsyncPointer , 
-.PN SyncPointer , 
-.PN AsyncKeyboard , 
-.PN SyncKeyboard ,
-.PN ReplayPointer , 
-.PN ReplayKeyboard ,
-.PN AsyncBoth ,
-or
-.PN SyncBoth .
-.IP \fItime\fP 1i
-Specifies the time.
-You can pass either a timestamp or
-.PN CurrentTime .
-.LP
-.eM
-The
-.PN XAllowEvents
-function releases some queued events if the client has caused a device 
-to freeze.
-It has no effect if the specified time is earlier than the last-grab
-time of the most recent active grab for the client or if the specified time
-is later than the current X server time.
-Depending on the event_mode argument, the following occurs:
-.TS
-lw(1.25i) lw(4.5i).
-T{
-.PN AsyncPointer
-T}	T{
-If the pointer is frozen by the client,
-pointer event processing continues as usual.
-If the pointer is frozen twice by the client on behalf of two separate grabs,
-.PN AsyncPointer 
-thaws for both.
-.PN AsyncPointer
-has no effect if the pointer is not frozen by the client,
-but the pointer need not be grabbed by the client.
-T}
-.sp 6p
-T{
-.PN SyncPointer 
-T}	T{
-If the pointer is frozen and actively grabbed by the client,
-pointer event processing continues as usual until the next 
-.PN ButtonPress 
-or 
-.PN ButtonRelease 
-event is reported to the client.
-At this time, 
-the pointer again appears to freeze.
-However, if the reported event causes the pointer grab to be released,
-the pointer does not freeze.
-.PN SyncPointer 
-has no effect if the pointer is not frozen by the client
-or if the pointer is not grabbed by the client.
-T}
-.sp 6p
-T{
-.PN ReplayPointer
-T}	T{
-If the pointer is actively grabbed by the client and is frozen as the result of
-an event having been sent to the client (either from the activation of an 
-.PN XGrabButton 
-or from a previous 
-.PN XAllowEvents 
-with mode 
-.PN SyncPointer
-but not from an 
-.PN XGrabPointer ),
-the pointer grab is released and that event is completely reprocessed.
-This time, however, the function ignores any passive grabs at or above 
-(toward the root of) the grab_window of the grab just released.
-The request has no effect if the pointer is not grabbed by the client
-or if the pointer is not frozen as the result of an event.
-T}
-.sp 6p
-T{
-.PN AsyncKeyboard 
-T}	T{
-If the keyboard is frozen by the client,
-keyboard event processing continues as usual.
-If the keyboard is frozen twice by the client on behalf of two separate grabs,
-.PN AsyncKeyboard 
-thaws for both.
-.PN AsyncKeyboard 
-has no effect if the keyboard is not frozen by the client,
-but the keyboard need not be grabbed by the client.
-T}
-.sp 6p
-T{
-.PN SyncKeyboard
-T}	T{
-If the keyboard is frozen and actively grabbed by the client,
-keyboard event processing continues as usual until the next 
-.PN KeyPress 
-or 
-.PN KeyRelease 
-event is reported to the client.
-At this time,
-the keyboard again appears to freeze.
-However, if the reported event causes the keyboard grab to be released,
-the keyboard does not freeze.
-.PN SyncKeyboard 
-has no effect if the keyboard is not frozen by the client
-or if the keyboard is not grabbed by the client.
-T}
-.sp 6p
-T{
-.PN ReplayKeyboard
-T}	T{
-If the keyboard is actively grabbed by the client and is frozen 
-as the result of an event having been sent to the client (either from the
-activation of an 
-.PN XGrabKey 
-or from a previous 
-.PN XAllowEvents 
-with mode 
-.PN SyncKeyboard 
-but not from an 
-.PN XGrabKeyboard ),
-the keyboard grab is released and that event is completely reprocessed.
-This time, however, the function ignores any passive grabs at or above 
-(toward the root of)
-the grab_window of the grab just released.
-The request has no effect if the keyboard is not grabbed by the client
-or if the keyboard is not frozen as the result of an event.
-T}
-.sp 6p
-T{
-.PN SyncBoth
-T}	T{
-If both pointer and keyboard are frozen by the client,
-event processing for both devices continues as usual until the next
-.PN ButtonPress , 
-.PN ButtonRelease , 
-.PN KeyPress , 
-or 
-.PN KeyRelease 
-event is reported to the client for a grabbed device 
-(button event for the pointer, key event for the keyboard), 
-at which time the devices again appear to freeze.  
-However, if the reported event causes the grab to be released,
-then the devices do not freeze (but if the other device is still
-grabbed, then a subsequent event for it will still cause both devices
-to freeze).  
-.PN SyncBoth
-has no effect unless both pointer and keyboard
-are frozen by the client.
-If the pointer or keyboard is frozen twice
-by the client on behalf of two separate grabs, 
-.PN SyncBoth 
-thaws for both (but a subsequent freeze for 
-.PN SyncBoth 
-will only freeze each device once).
-T}
-.sp 6p
-T{
-.PN AsyncBoth
-T}	T{
-If the pointer and the keyboard are frozen by the
-client, event processing for both devices continues as usual.
-If a device is frozen twice by the client on behalf of two separate grabs,
-.PN AsyncBoth 
-thaws for both.
-.PN AsyncBoth 
-has no effect unless both
-pointer and keyboard are frozen by the client.
-T}
-.TE
-.LP
-.PN AsyncPointer , 
-.PN SyncPointer , 
-and 
-.PN ReplayPointer 
-have no effect on the
-processing of keyboard events.
-.PN AsyncKeyboard , 
-.PN SyncKeyboard , 
-and 
-.PN ReplayKeyboard 
-have no effect on the
-processing of pointer events.
-It is possible for both a pointer grab and a keyboard grab (by the same 
-or different clients) to be active simultaneously.
-If a device is frozen on behalf of either grab,
-no event processing is performed for the device.
-It is possible for a single device to be frozen because of both grabs.
-In this case,
-the freeze must be released on behalf of both grabs before events can 
-again be processed.
-If a device is frozen twice by a single client,
-then a single
-.PN AllowEvents
-releases both.
-.LP
-.PN XAllowEvents
-can generate a
-.PN BadValue 
-error.
-.NH 2
-Moving the Pointer
-.XS
-\*(SN Moving the Pointer
-.XE
-.LP
-Although movement of the pointer normally should be left to the
-control of the end user, sometimes it is necessary to move the
-pointer to a new position under program control.
-.LP
-.sp
-To move the pointer to an arbitrary point in a window, use
-.PN XWarpPointer .
-.IN "XWarpPointer" "" "@DEF@"
-.sM
-.FD 0
-XWarpPointer\^(\^\fIdisplay\fP, \fIsrc_w\fP\^, \fIdest_w\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIsrc_width\fP\^, \fIsrc_height\fP\^, \fIdest_x\fP\^, 
-.br
-                \fIdest_y\fP\^)
-.br
-        Display *\fIdisplay\fP\^;
-.br
-        Window \fIsrc_w\fP\^, \fIdest_w\fP\^;
-.br
-        int \fIsrc_x\fP\^, \fIsrc_y\fP\^;
-.br
-        unsigned int \fIsrc_width\fP\^, \fIsrc_height\fP\^;
-.br
-        int \fIdest_x\fP\^, \fIdest_y\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIsrc_w\fP 1i
-Specifies the source window or
-.PN None .
-.IP \fIdest_w\fP 1i
-Specifies the destination window or
-.PN None .
-.IP \fIsrc_x\fP 1i
-.br
-.ns
-.IP \fIsrc_y\fP 1i
-.br
-.ns
-.IP \fIsrc_width\fP 1i
-.br
-.ns
-.IP \fIsrc_height\fP 1i
-Specify a rectangle in the source window.
-.IP \fIdest_x\fP 1i
-.br
-.ns
-.IP \fIdest_y\fP 1i
-Specify the x and y coordinates within the destination window.
-.LP
-.eM
-If dest_w is
-.PN None ,
-.PN XWarpPointer
-moves the pointer by the offsets (dest_x, dest_y) relative to the current
-position of the pointer.
-If dest_w is a window,
-.PN XWarpPointer
-moves the pointer to the offsets (dest_x, dest_y) relative to the origin of
-dest_w.
-However, if src_w is a window,
-the move only takes place if the window src_w contains the pointer 
-and if the specified rectangle of src_w contains the pointer.
-.LP
-The src_x and src_y coordinates are relative to the origin of src_w.
-If src_height is zero,
-it is replaced with the current height of src_w minus src_y.
-If src_width is zero,
-it is replaced with the current width of src_w minus src_x.
-.LP
-There is seldom any reason for calling this function. 
-The pointer should normally be left to the user.
-If you do use this function, however, it generates events just as if the user
-had instantaneously moved the pointer from one position to another.
-Note that you cannot use
-.PN XWarpPointer
-to move the pointer outside the confine_to window of an active pointer grab.
-An attempt to do so will only move the pointer as far as the closest edge of the
-confine_to window. 
-.LP
-.PN XWarpPointer
-can generate a
-.PN BadWindow 
-error.
-.NH 2
-Controlling Input Focus
-.XS
-\*(SN Controlling Input Focus 
-.XE
-.LP
-Xlib provides functions that you can use to set and get the input focus.
-The input focus is a shared resource, and cooperation among clients is
-required for correct interaction.  See the
-\fIInter-Client Communication Conventions Manual\fP 
-for input focus policy.
-.LP
-.sp
-To set the input focus, use
-.PN XSetInputFocus .
-.IN "XSetInputFocus" "" "@DEF@"
-.sM
-.FD 0
-XSetInputFocus\^(\^\fIdisplay\fP, \fIfocus\fP\^, \fIrevert_to\fP\^, \fItime\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIfocus\fP\^;
-.br
-      int \fIrevert_to\fP\^; 
-.br
-      Time \fItime\fP\^; 
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIfocus\fP 1i
-Specifies the window,
-.PN PointerRoot ,
-or
-.PN None .
-.IP \fIrevert_to\fP 1i
-Specifies where the input focus reverts to if the window becomes not
-viewable.
-You can pass 
-.PN RevertToParent , 
-.PN RevertToPointerRoot , 
-or 
-.PN RevertToNone .
-.IP \fItime\fP 1i
-Specifies the time.
-You can pass either a timestamp or
-.PN CurrentTime .
-.LP
-.eM
-The
-.PN XSetInputFocus
-function changes the input focus and the last-focus-change time.
-It has no effect if the specified time is earlier than the current
-last-focus-change time or is later than the current X server time.
-Otherwise, the last-focus-change time is set to the specified time
-.Pn ( CurrentTime 
-is replaced by the current X server time).
-.PN XSetInputFocus
-causes the X server to generate
-.PN FocusIn 
-and 
-.PN FocusOut 
-events.
-.LP
-Depending on the focus argument,
-the following occurs: 
-.IP \(bu 5
-If focus is
-.PN None ,
-all keyboard events are discarded until a new focus window is set,
-and the revert_to argument is ignored.
-.IP \(bu 5
-If focus is a window, 
-it becomes the keyboard's focus window.
-If a generated keyboard event would normally be reported to this window
-or one of its inferiors, the event is reported as usual. 
-Otherwise, the event is reported relative to the focus window.
-.IP \(bu 5
-If focus is
-.PN PointerRoot ,
-the focus window is dynamically taken to be the root window of whatever screen 
-the pointer is on at each keyboard event.  
-In this case, the revert_to argument is ignored.
-.LP
-The specified focus window must be viewable at the time 
-.PN XSetInputFocus
-is called,
-or a
-.PN BadMatch
-error results.
-If the focus window later becomes not viewable, 
-the X server
-evaluates the revert_to argument to determine the new focus window as follows: 
-.IP \(bu 5
-If revert_to is
-.PN RevertToParent ,
-the focus reverts to the parent (or the closest viewable ancestor), 
-and the new revert_to value is taken to be
-.PN RevertToNone .  
-.IP \(bu 5
-If revert_to is
-.PN RevertToPointerRoot 
-or 
-.PN RevertToNone ,
-the focus reverts to
-.PN PointerRoot
-or
-.PN None ,
-respectively.
-When the focus reverts,
-the X server generates
-.PN FocusIn
-and
-.PN FocusOut
-events, but the last-focus-change time is not affected.
-.LP
-.PN XSetInputFocus
-can generate
-.PN BadMatch ,
-.PN BadValue ,
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To obtain the current input focus, use
-.PN XGetInputFocus .
-.IN "XGetInputFocus" "" "@DEF@"
-.sM
-.FD 0
-XGetInputFocus\^(\^\fIdisplay\fP, \fIfocus_return\fP\^, \fIrevert_to_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window *\fIfocus_return\fP\^;
-.br
-      int *\fIrevert_to_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIfocus_return\fP 1i
-Returns the focus window,
-.PN PointerRoot ,
-or 
-.PN None .
-.IP \fIrevert_to_return\fP 1i
-Returns the current focus state
-.Pn ( RevertToParent , 
-.PN RevertToPointerRoot , 
-or 
-.PN RevertToNone ).
-.LP
-.eM
-The
-.PN XGetInputFocus
-function returns the focus window and the current focus state.
-.NH 2
-Manipulating the Keyboard and Pointer Settings
-.XS
-\*(SN Manipulating the Keyboard and Pointer Settings 
-.XE
-.LP
-Xlib provides functions that you can use to
-change the keyboard control, obtain a list of the auto-repeat keys,
-turn keyboard auto-repeat on or off, ring the bell, 
-set or obtain the pointer button or keyboard mapping, 
-and obtain a bit vector for the keyboard.
-.LP
-.IN "Keyboard" "bell volume"
-.IN "Keyboard" "keyclick volume"
-.IN "Keyboard" "bit vector"
-.IN "Mouse" "programming"
-This section discusses 
-the user-preference options of bell, key click,
-pointer behavior, and so on.
-The default values for many of these options are server dependent.
-Not all implementations will actually be able to control all of these
-parameters.
-.LP
-The
-.PN XChangeKeyboardControl
-function changes control of a keyboard and operates on a
-.PN XKeyboardControl
-structure:
-.sM
-.LP
-/* Mask bits for ChangeKeyboardControl */
-.TS
-lw(.5i) lw(2.5i) lw(.8i).
-T{
-#define
-T}	T{
-.PN KBKeyClickPercent
-T}	T{
-(1L<<0)
-T}
-T{
-#define
-T}	T{
-.PN KBBellPercent
-T}	T{
-(1L<<1)
-T}
-T{
-#define
-T}	T{
-.PN KBBellPitch
-T}	T{
-(1L<<2)
-T}
-T{
-#define
-T}	T{
-.PN KBBellDuration
-T}	T{
-(1L<<3)
-T}
-T{
-#define
-T}	T{
-.PN KBLed
-T}	T{
-(1L<<4)
-T}
-T{
-#define
-T}	T{
-.PN KBLedMode
-T}	T{
-(1L<<5)
-T}
-T{
-#define
-T}	T{
-.PN KBKey
-T}	T{
-(1L<<6)
-T}
-T{
-#define
-T}	T{
-.PN KBAutoRepeatMode
-T}	T{
-(1L<<7)
-T}
-.TE
-.IN "XKeyboardControl" "" "@DEF@"
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-/* Values */
-
-typedef struct {
-	int key_click_percent;
-	int bell_percent;
-	int bell_pitch;
-	int bell_duration;
-	int led;
-	int led_mode;	/* LedModeOn, LedModeOff */
-	int key;
-	int auto_repeat_mode;	/* AutoRepeatModeOff, AutoRepeatModeOn, 
-                            	AutoRepeatModeDefault */
-} XKeyboardControl;
-.De
-.LP
-.eM
-The key_click_percent member sets the volume for key clicks between 0 (off) 
-and 100 (loud) inclusive, if possible.  
-A setting of \-1 restores the default.
-Other negative values generate a
-.PN BadValue
-error.
-.LP
-The bell_percent sets the base volume for the bell between 0 (off) and 100
-(loud) inclusive, if possible.  
-A setting of \-1 restores the default.
-Other negative values generate a
-.PN BadValue
-error.
-The bell_pitch member sets the pitch (specified in Hz) of the bell, if possible.
-A setting of \-1 restores the default.
-Other negative values generate a
-.PN BadValue
-error.
-The bell_duration member sets the duration of the
-bell specified in milliseconds, if possible.  
-A setting of \-1 restores the default.
-Other negative values generate a
-.PN BadValue
-error.
-.LP
-If both the led_mode and led members are specified,
-the state of that LED is changed, if possible.  
-The led_mode member can be set to
-.PN LedModeOn
-or
-.PN LedModeOff .
-If only led_mode is specified, the state of
-all LEDs are changed, if possible.  
-At most 32 LEDs numbered from one are supported. 
-No standard interpretation of LEDs is defined.
-If led is specified without led_mode, a
-.PN BadMatch
-error results. 
-.LP
-If both the auto_repeat_mode and key members are specified, 
-the auto_repeat_mode of that key is changed (according to
-.PN AutoRepeatModeOn ,
-.PN AutoRepeatModeOff ,
-or
-.PN AutoRepeatModeDefault ),
-if possible.
-If only auto_repeat_mode is
-specified, the global auto_repeat_mode for the entire keyboard is
-changed, if possible, and does not affect the per-key settings.
-If a key is specified without an auto_repeat_mode, a
-.PN BadMatch
-error results.
-Each key has an individual mode of whether or not it should auto-repeat
-and a default setting for the mode.
-In addition,
-there is a global mode of whether auto-repeat should be enabled or not
-and a default setting for that mode.
-When global mode is
-.PN AutoRepeatModeOn ,
-keys should obey their individual auto-repeat modes.
-When global mode is
-.PN AutoRepeatModeOff ,
-no keys should auto-repeat.
-An auto-repeating key generates alternating
-.PN KeyPress
-and
-.PN KeyRelease
-events.
-When a key is used as a modifier,
-it is desirable for the key not to auto-repeat,
-regardless of its auto-repeat setting.
-.LP
-A bell generator connected with the console but not directly on a
-keyboard is treated as if it were part of the keyboard.
-The order in which controls are verified and altered is server-dependent.
-If an error is generated, a subset of the controls may have been altered.
-.LP
-.sp
-.IN "XChangeKeyboardControl" "" "@DEF@"
-.sM
-.FD 0
-XChangeKeyboardControl\^(\^\fIdisplay\fP, \fIvalue_mask\fP\^, \fIvalues\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      unsigned long \fIvalue_mask\fP\^;
-.br
-      XKeyboardControl *\fIvalues\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIvalue_mask\fP 1i
-Specifies which controls to change.
-This mask is the bitwise inclusive OR of the valid control mask bits.
-.IP \fIvalues\fP 1i
-Specifies one value for each bit set to 1 in the mask.
-.LP
-.eM
-The
-.PN XChangeKeyboardControl
-function controls the keyboard characteristics defined by the
-.PN XKeyboardControl
-structure.
-The value_mask argument specifies which values are to be changed.
-.LP
-.PN XChangeKeyboardControl
-can generate
-.PN BadMatch
-and
-.PN BadValue 
-errors.
-.LP
-.sp
-To obtain the current control values for the keyboard, use
-.PN XGetKeyboardControl .
-.IN "XGetKeyboardControl" "" "@DEF@"
-.sM
-.FD 0
-XGetKeyboardControl\^(\^\fIdisplay\fP, \fIvalues_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XKeyboardState *\fIvalues_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIvalues_return\fP 1i
-Returns the current keyboard controls in the specified
-.PN XKeyboardState 
-structure.
-.LP
-.eM
-The
-.PN XGetKeyboardControl
-function returns the current control values for the keyboard to the
-.PN XKeyboardState
-structure.
-.LP
-.IN "XGetKeyboardControl"
-.IN "XKeyboardState" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 
-.ta .5i
-typedef struct {
-	int key_click_percent;
-	int bell_percent;
-	unsigned int bell_pitch, bell_duration;
-	unsigned long led_mask;
-	int global_auto_repeat;
-	char auto_repeats[32];
-} XKeyboardState;
-.De
-.LP
-.eM
-For the LEDs, 
-the least significant bit of led_mask corresponds to LED one,
-and each bit set to 1 in led_mask indicates an LED that is lit.
-The global_auto_repeat member can be set to
-.PN AutoRepeatModeOn
-or
-.PN AutoRepeatModeOff .
-The auto_repeats member is a bit vector.
-Each bit set to 1 indicates that auto-repeat is enabled 
-for the corresponding key.
-The vector is represented as 32 bytes.  
-Byte N (from 0) contains the bits for keys 8N to 8N + 7
-with the least significant bit in the byte representing key 8N.
-.LP
-.sp
-To turn on keyboard auto-repeat, use
-.PN XAutoRepeatOn .
-.IN "XAutoRepeatOn" "" "@DEF@"
-.sM
-.FD 0
-XAutoRepeatOn\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-The
-.PN XAutoRepeatOn
-function turns on auto-repeat for the keyboard on the specified display.
-.LP
-.sp
-To turn off keyboard auto-repeat, use
-.PN XAutoRepeatOff .
-.IN "XAutoRepeatOff" "" "@DEF@"
-.sM
-.FD 0
-XAutoRepeatOff\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-The
-.PN XAutoRepeatOff
-function turns off auto-repeat for the keyboard on the specified display.
-.LP
-.sp
-To ring the bell, use
-.PN XBell .
-.IN "XBell" "" "@DEF@"
-.sM
-.FD 0
-XBell\^(\^\fIdisplay\fP, \fIpercent\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIpercent\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIpercent\fP 1i
-Specifies the volume for the bell,
-which can range from \-100 to 100 inclusive. 
-.LP
-.eM
-The
-.PN XBell
-function rings the bell on the keyboard on the specified display, if possible.
-The specified volume is relative to the base volume for the keyboard.
-If the value for the percent argument is not in the range \-100 to 100
-inclusive, a
-.PN BadValue
-error results.
-The volume at which the bell rings
-when the percent argument is nonnegative is:
-.IP
-base \- [(base * percent) / 100] + percent
-.LP
-The volume at which the bell rings
-when the percent argument is negative is:
-.IP
-base + [(base * percent) / 100]
-.LP
-To change the base volume of the bell, use
-.PN XChangeKeyboardControl .
-.LP
-.PN XBell
-can generate a
-.PN BadValue 
-error.
-.LP
-.sp
-To obtain a bit vector that describes the state of the keyboard, use
-.PN XQueryKeymap .
-.IN "XQueryKeymap" "" "@DEF@"
-.sM
-.FD 0
-XQueryKeymap\^(\^\fIdisplay\fP, \fIkeys_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      char \fIkeys_return\fP[32]\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIkeys_return\fP 1i
-Returns an array of bytes that identifies which keys are pressed down.
-Each bit represents one key of the keyboard.
-.LP
-.eM
-The
-.PN XQueryKeymap
-function returns a bit vector for the logical state of the keyboard, 
-where each bit set to 1 indicates that the corresponding key is currently 
-pressed down.
-The vector is represented as 32 bytes.
-Byte N (from 0) contains the bits for keys 8N to 8N + 7 
-with the least significant bit in the byte representing key 8N.
-.LP
-Note that the logical state of a device (as seen by client applications)
-may lag the physical state if device event processing is frozen.
-.LP
-.sp
-To set the mapping of the pointer buttons, use
-.PN XSetPointerMapping .
-.IN "XSetPointerMapping" "" "@DEF@"
-.sM
-.FD 0
-int XSetPointerMapping\^(\^\fIdisplay\fP, \fImap\fP, \fInmap\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      unsigned char \fImap\fP\^[]\^;
-.br
-      int \fInmap\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fImap\fP 1i
-Specifies the mapping list.
-.IP \fInmap\fP 1i
-Specifies the number of items in the mapping list.
-.LP
-.eM
-The
-.PN XSetPointerMapping
-function sets the mapping of the pointer.
-If it succeeds, the X server generates a
-.PN MappingNotify
-event, and
-.PN XSetPointerMapping
-returns
-.PN MappingSuccess .
-Element map[i] defines the logical button number for the physical button
-i+1.
-The length of the list must be the same as
-.PN XGetPointerMapping
-would return,
-or a
-.PN BadValue
-error results.
-A zero element disables a button, and elements are not restricted in
-value by the number of physical buttons.
-However, no two elements can have the same nonzero value,
-or a
-.PN BadValue
-error results.
-If any of the buttons to be altered are logically in the down state,
-.PN XSetPointerMapping
-returns
-.PN MappingBusy ,
-and the mapping is not changed.
-.LP
-.PN XSetPointerMapping
-can generate a
-.PN BadValue 
-error.
-.LP
-.sp
-To get the pointer mapping, use
-.PN XGetPointerMapping .
-.IN "XGetPointerMapping" "" "@DEF@"
-.sM
-.FD 0
-int XGetPointerMapping\^(\^\fIdisplay\fP, \fImap_return\fP, \fInmap\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      unsigned char \fImap_return\fP\^[]\^;
-.br
-      int \fInmap\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fImap_return\fP 1i
-Returns the mapping list.
-.IP \fInmap\fP 1i
-Specifies the number of items in the mapping list.
-.LP
-.eM
-The
-.PN XGetPointerMapping
-function returns the current mapping of the pointer.
-Pointer buttons are numbered starting from one.
-.PN XGetPointerMapping
-returns the number of physical buttons actually on the pointer.
-The nominal mapping for a pointer is map[i]=i+1.
-The nmap argument specifies the length of the array where the pointer
-mapping is returned, and only the first nmap elements are returned 
-in map_return.
-.LP
-.sp
-To control the pointer's interactive feel, use
-.PN XChangePointerControl .
-.IN "XChangePointerControl" "" "@DEF@"
-.sM
-.FD 0
-XChangePointerControl\^(\^\fIdisplay\fP, \fIdo_accel\fP\^, \fIdo_threshold\fP\^, \fIaccel_numerator\fP\^, 
-.br
-                        \fIaccel_denominator\fP\^, \fIthreshold\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Bool \fIdo_accel\fP\^, \fIdo_threshold\fP\^;
-.br
-      int \fIaccel_numerator\fP\^, \fIaccel_denominator\fP\^;
-.br
-      int \fIthreshold\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIdo_accel\fP 1i
-Specifies a Boolean value that controls whether the values for 
-the accel_numerator or accel_denominator are used.
-.IP \fIdo_threshold\fP 1i
-Specifies a Boolean value that controls whether the value for the 
-threshold is used.
-.IP \fIaccel_numerator\fP 1i
-Specifies the numerator for the acceleration multiplier.
-.IP \fIaccel_denominator\fP 1i
-Specifies the denominator for the acceleration multiplier.
-.IP \fIthreshold\fP 1i
-Specifies the acceleration threshold.
-.LP
-.eM
-The
-.PN XChangePointerControl
-function defines how the pointing device moves.
-The acceleration, expressed as a fraction, is a
-multiplier for movement. 
-For example,
-specifying 3/1 means the pointer moves three times as fast as normal.
-The fraction may be rounded arbitrarily by the X server.  
-Acceleration
-only takes effect if the pointer moves more than threshold pixels at
-once and only applies to the amount beyond the value in the threshold argument.
-Setting a value to \-1 restores the default.
-The values of the do_accel and do_threshold arguments must be 
-.PN True 
-for the pointer values to be set,
-or the parameters are unchanged.
-Negative values (other than \-1) generate a
-.PN BadValue
-error, as does a zero value
-for the accel_denominator argument.
-.LP
-.PN XChangePointerControl
-can generate a
-.PN BadValue 
-error.
-.LP
-.sp
-To get the current pointer parameters, use
-.PN XGetPointerControl .
-.IN "XGetPointerControl" "" "@DEF@"
-.sM
-.FD 0
-XGetPointerControl\^(\^\fIdisplay\fP, \fIaccel_numerator_return\fP\^, \fIaccel_denominator_return\fP\^, 
-.br
-                       \fIthreshold_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int *\fIaccel_numerator_return\fP\^, *\fIaccel_denominator_return\fP\^;
-.br
-      int *\fIthreshold_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIaccel_numerator_return\fP 1i
-Returns the numerator for the acceleration multiplier.
-.IP \fIaccel_denominator_return\fP 1i
-Returns the denominator for the acceleration multiplier.
-.IP \fIthreshold_return\fP 1i
-Returns the acceleration threshold.
-.LP
-.eM
-The
-.PN XGetPointerControl
-function returns the pointer's current acceleration multiplier
-and acceleration threshold.
-.NH 2
-Manipulating the Keyboard Encoding
-.XS
-\*(SN Manipulating the Keyboard Encoding 
-.XE
-.LP
-A KeyCode represents a physical (or logical) key.  
-KeyCodes lie in the inclusive range [8,255].  
-A KeyCode value carries no intrinsic information,
-although server implementors may attempt to encode geometry 
-(for example, matrix) information in some fashion so that it can
-be interpreted in a server-dependent fashion.
-The mapping between keys and KeyCodes cannot be changed.
-.LP
-A KeySym is an encoding of a symbol on the cap of a key.  
-The set of defined KeySyms includes the ISO Latin character sets (1\-4), 
-Katakana, Arabic, Cyrillic, Greek, Technical,
-Special, Publishing, APL, Hebrew, Thai, Korean
-and a miscellany of keys found
-on keyboards (Return, Help, Tab, and so on).  
-To the extent possible, these sets are derived from international
-standards. 
-In areas where no standards exist,
-some of these sets are derived from Digital Equipment Corporation standards.
-The list of defined symbols can be found in
-.hN X11/keysymdef.h .
-Unfortunately, some C preprocessors have
-limits on the number of defined symbols.
-If you must use KeySyms not
-in the Latin 1\-4, Greek, and miscellaneous classes,
-you may have to define a symbol for those sets.
-Most applications usually only include 
-.hN X11/keysym.h ,
-which defines symbols for ISO Latin 1\-4, Greek, and miscellaneous.
-.LP
-A list of KeySyms is associated with each KeyCode.
-The list is intended to convey the set of symbols on the corresponding key.
-If the list (ignoring trailing
-.PN NoSymbol
-entries) is 
-a single KeySym ``\fIK\fP'',
-then the list is treated as if it were the list 
-``\fIK\fP NoSymbol \fIK\fP NoSymbol''.
-If the list (ignoring trailing
-.PN NoSymbol
-entries) is a pair of KeySyms ``\fIK1 K2\fP'',
-then the list is treated as if it were the list ``\fIK1 K2 K1 K2\fP''.
-If the list (ignoring trailing
-.PN NoSymbol
-entries) is a triple of KeySyms ``\fIK1 K2 K3\fP'',
-then the list is treated as if it were the list ``\fIK1 K2 K3\fP NoSymbol''.
-When an explicit ``void'' element is desired in the list,
-the value
-.PN VoidSymbol
-can be used.
-.LP
-The first four elements of the list are split into two groups of KeySyms.
-Group 1 contains the first and second KeySyms;
-Group 2 contains the third and fourth KeySyms.
-Within each group,
-if the second element of the group is
-.PN NoSymbol ,
-then the group should be treated as if the second element were 
-the same as the first element,
-except when the first element is an alphabetic KeySym ``\fIK\fP'' 
-for which both lowercase and uppercase forms are defined.
-In that case,
-the group should be treated as if the first element were 
-the lowercase form of ``\fIK\fP'' and the second element were 
-the uppercase form of ``\fIK\fP''.
-.LP
-The standard rules for obtaining a KeySym from a
-.PN KeyPress
-event make use of only the Group 1 and Group 2 KeySyms;
-no interpretation of other KeySyms in the list is given.
-Which group to use is determined by the modifier state.
-Switching between groups is controlled by the KeySym named MODE SWITCH,
-by attaching that KeySym to some KeyCode and attaching 
-that KeyCode to any one of the modifiers
-.PN Mod1
-through
-.PN Mod5 .
-This modifier is called the \fIgroup modifier\fP\^.
-For any KeyCode,
-Group 1 is used when the group modifier is off,
-and Group 2 is used when the group modifier is on.
-.LP
-The
-.PN Lock
-modifier is interpreted as CapsLock when the KeySym named XK_Caps_Lock
-is attached to some KeyCode and that KeyCode is attached to the
-.PN Lock
-modifier.  The
-.PN Lock
-modifier is interpreted as ShiftLock when the KeySym named XK_Shift_Lock
-is attached to some KeyCode and that KeyCode is attached to the
-.PN Lock 
-modifier.  If the
-.PN Lock 
-modifier could be interpreted as both
-CapsLock and ShiftLock, the CapsLock interpretation is used.
-.LP
-The operation of keypad keys is controlled by the KeySym named XK_Num_Lock,
-by attaching that KeySym to some KeyCode and attaching that KeyCode to any
-one of the modifiers
-.PN Mod1 
-through
-.PN Mod5 . 
-This modifier is called the
-\fInumlock modifier\fP\^.  The standard KeySyms with the prefix ``XK_KP_''
-in their
-name are called keypad KeySyms; these are KeySyms with numeric value in
-the hexadecimal range 0xFF80 to 0xFFBD inclusive.  In addition,
-vendor-specific KeySyms in the hexadecimal range 0x11000000 to 0x1100FFFF
-are also keypad KeySyms.
-.LP
-Within a group, the choice of KeySym is determined by applying the first
-rule that is satisfied from the following list:
-.IP \(bu 5
-The numlock modifier is on and the second KeySym is a keypad KeySym.  In
-this case, if the
-.PN Shift 
-modifier is on, or if the
-.PN Lock 
-modifier is on and
-is interpreted as ShiftLock, then the first KeySym is used, otherwise the
-second KeySym is used.
-.IP \(bu 5
-The
-.PN Shift 
-and
-.PN Lock 
-modifiers are both off.  In this case, the first
-KeySym is used.
-.IP \(bu 5
-The
-.PN Shift 
-modifier is off, and the
-.PN Lock 
-modifier is on and is
-interpreted as CapsLock.  In this case, the first KeySym is used, but if
-that KeySym is lowercase alphabetic, then the corresponding uppercase
-KeySym is used instead.
-.IP \(bu 5
-The
-.PN Shift 
-modifier is on, and the
-.PN Lock 
-modifier is on and is interpreted
-as CapsLock.  In this case, the second KeySym is used, but if that KeySym
-is lowercase alphabetic, then the corresponding uppercase KeySym is used
-instead.
-.IP \(bu 5
-The
-.PN Shift 
-modifier is on, or the
-.PN Lock 
-modifier is on and is interpreted
-as ShiftLock, or both.  In this case, the second KeySym is used.
-.LP
-No spatial geometry of the symbols on the key is defined by
-their order in the KeySym list, 
-although a geometry might be defined on a
-server-specific basis.
-The X server does not use the mapping between KeyCodes and KeySyms.
-Rather, it merely stores it for reading and writing by clients.
-.sp
-.LP
-To obtain the legal KeyCodes for a display, use
-.PN XDisplayKeycodes .
-.IN "XDisplayKeycodes" "" "@DEF@"
-.sM
-.FD 0
-XDisplayKeycodes\^(\^\fIdisplay\fP\^, \fImin_keycodes_return\fP\^, \
-\fImax_keycodes_return\fP\^)
-.br
-        Display *\^\fIdisplay\fP\^;
-.br
-        int *\^\fImin_keycodes_return\fP\^, *\^\fImax_keycodes_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fImin_keycodes_return\fP 1i
-Returns the minimum number of KeyCodes.
-.IP \fImax_keycodes_return\fP 1i
-Returns the maximum number of KeyCodes.
-.LP
-.eM
-The
-.PN XDisplayKeycodes
-function returns the min-keycodes and max-keycodes supported by the
-specified display.
-The minimum number of KeyCodes returned is never less than 8,
-and the maximum number of KeyCodes returned is never greater than 255.
-Not all KeyCodes in this range are required to have corresponding keys.
-.sp
-.LP
-To obtain the symbols for the specified KeyCodes, use
-.PN XGetKeyboardMapping .
-.IN "XGetKeyboardMapping" "" "@DEF@"
-.sM
-.FD 0
-KeySym *XGetKeyboardMapping(\^\fIdisplay\fP, \fIfirst_keycode\fP, \fIkeycode_count\fP, 
-.br
-                            \fIkeysyms_per_keycode_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      KeyCode \fIfirst_keycode\fP\^;
-.br
-      int \fIkeycode_count\fP\^;
-.br
-      int *\fIkeysyms_per_keycode_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Kc returned
-.IP \fIfirst_keycode\fP 1i
-Specifies the first KeyCode that is to be \*(Kc.
-.IP \fIkeycode_count\fP 1i
-Specifies the number of KeyCodes that are to be returned.
-.IP \fIkeysyms_per_keycode_return\fP 1i
-Returns the number of KeySyms per KeyCode.
-.LP
-.eM
-The
-.PN XGetKeyboardMapping
-function returns the symbols for the specified number of KeyCodes
-starting with first_keycode.
-The value specified in first_keycode must be greater than 
-or equal to min_keycode as returned by
-.PN XDisplayKeycodes ,
-or a
-.PN BadValue 
-error results.
-In addition, the following expression must be less than or equal 
-to max_keycode as returned by
-.PN XDisplayKeycodes :
-.LP
-.Ds 
-first_keycode + keycode_count \- 1
-.De
-.LP
-If this is not the case, a 
-.PN BadValue 
-error results. 
-The number of elements in the KeySyms list is:
-.LP
-.Ds 
-keycode_count * keysyms_per_keycode_return
-.De
-.LP
-KeySym number N, counting from zero, for KeyCode K has the following index
-in the list, counting from zero: 
-.Ds
-(K \- first_code) * keysyms_per_code_return + N
-.De
-.LP
-The X server arbitrarily chooses the keysyms_per_keycode_return value 
-to be large enough to report all requested symbols. 
-A special KeySym value of 
-.PN NoSymbol 
-is used to fill in unused elements for
-individual KeyCodes.
-To free the storage returned by 
-.PN XGetKeyboardMapping ,
-use
-.PN XFree .
-.LP
-.PN XGetKeyboardMapping
-can generate a
-.PN BadValue 
-error.
-.LP
-.sp
-To change the keyboard mapping, use
-.PN XChangeKeyboardMapping .
-.IN "XChangeKeyboardMapping" "" "@DEF@"
-.sM
-.FD 0
-XChangeKeyboardMapping(\^\fIdisplay\fP, \fIfirst_keycode\fP, \fIkeysyms_per_keycode\fP, \fIkeysyms\fP, \fInum_codes\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIfirst_keycode\fP\^;
-.br
-      int \fIkeysyms_per_keycode\fP\^;
-.br
-      KeySym *\fIkeysyms\fP\^;
-.br
-      int \fInum_codes\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Kc changed
-.IP \fIfirst_keycode\fP 1i
-Specifies the first KeyCode that is to be \*(Kc.
-.IP \fIkeysyms_per_keycode\fP 1i
-Specifies the number of KeySyms per KeyCode.
-.IP \fIkeysyms\fP 1i
-Specifies an array of KeySyms.
-.IP \fInum_codes\fP 1i
-Specifies the number of KeyCodes that are to be changed.
-.LP
-.eM
-The
-.PN XChangeKeyboardMapping
-function defines the symbols for the specified number of KeyCodes
-starting with first_keycode.
-The symbols for KeyCodes outside this range remain unchanged.  
-The number of elements in keysyms must be:
-.LP
-.Ds
-num_codes * keysyms_per_keycode
-.De
-.LP
-The specified first_keycode must be greater than or equal to min_keycode 
-returned by
-.PN XDisplayKeycodes ,
-or a 
-.PN BadValue 
-error results.
-In addition, the following expression must be less than or equal to 
-max_keycode as returned by
-.PN XDisplayKeycodes ,
-or a
-.PN BadValue 
-error results:
-.LP
-.Ds
-first_keycode + num_codes \- 1
-.De
-.LP
-KeySym number N, counting from zero, for KeyCode K has the following index
-in keysyms, counting from zero: 
-.LP
-.Ds 
-(K \- first_keycode) * keysyms_per_keycode + N
-.De
-.LP
-The specified keysyms_per_keycode can be chosen arbitrarily by the client
-to be large enough to hold all desired symbols. 
-A special KeySym value of 
-.PN NoSymbol 
-should be used to fill in unused elements 
-for individual KeyCodes.  
-It is legal for 
-.PN NoSymbol 
-to appear in nontrailing positions
-of the effective list for a KeyCode.
-.PN XChangeKeyboardMapping
-generates a 
-.PN MappingNotify 
-event.
-.LP
-There is no requirement that the X server interpret this mapping. 
-It is merely stored for reading and writing by clients.
-.LP
-.PN XChangeKeyboardMapping
-can generate
-.PN BadAlloc 
-and
-.PN BadValue 
-errors.
-.LP
-The next six functions make use of the 
-.PN XModifierKeymap
-data structure, which contains:
-.LP
-.IN "XModifierKeymap" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	int max_keypermod;	/* This server's max number of keys per modifier */
-	KeyCode *modifiermap;	/* An 8 by max_keypermod array of the modifiers */
-} XModifierKeymap;
-.De
-.LP
-.eM
-To create an
-.PN XModifierKeymap
-structure, use
-.PN XNewModifiermap .
-.IN "XNewModifiermap" "" "@DEF@"
-.sM
-.FD 0
-XModifierKeymap *XNewModifiermap(\^\fImax_keys_per_mod\fP\^)
-.br
-        int \fImax_keys_per_mod\fP\^;
-.FN
-.IP \fImax_keys_per_mod\fP 1i
-Specifies the number of KeyCode entries preallocated to the modifiers
-in the map.
-.LP
-.eM
-The
-.PN XNewModifiermap
-function returns a pointer to
-.PN XModifierKeymap
-structure for later use.
-.LP
-.sp
-To add a new entry to an 
-.PN XModifierKeymap
-structure, use
-.PN XInsertModifiermapEntry .
-.IN "XInsertModifiermapEntry" "" "@DEF@"
-.sM
-.FD 0
-XModifierKeymap *XInsertModifiermapEntry\^(\^\fImodmap\fP, \
-\fIkeycode_entry\fP, \fImodifier\fP\^)
-.br
-     XModifierKeymap *\fImodmap\fP\^;
-.br
-     KeyCode \fIkeycode_entry\fP\^;
-.br
-     int \fImodifier\fP\^;
-.FN
-.IP \fImodmap\fP 1i
-Specifies the 
-.PN XModifierKeymap
-structure.
-.IP \fIkeycode_entry\fP 1i
-Specifies the KeyCode. 
-.IP \fImodifier\fP 1i
-Specifies the modifier.
-.LP
-.eM
-The
-.PN XInsertModifiermapEntry
-function adds the specified KeyCode to the set that controls the specified
-modifier and returns the resulting
-.PN XModifierKeymap
-structure (expanded as needed).
-.LP
-.sp
-To delete an entry from an 
-.PN XModifierKeymap
-structure, use
-.PN XDeleteModifiermapEntry .
-.IN "XDeleteModifiermapEntry" "" "@DEF@"
-.sM
-.FD 0
-XModifierKeymap *XDeleteModifiermapEntry\^(\^\fImodmap\fP, \
-\fIkeycode_entry\fP, \fImodifier\fP\^)
-.br
-     XModifierKeymap *\fImodmap\fP\^;
-.br
-     KeyCode \fIkeycode_entry\fP\^;
-.br
-     int \fImodifier\fP\^;
-.FN
-.IP \fImodmap\fP 1i
-Specifies the 
-.PN XModifierKeymap
-structure.
-.IP \fIkeycode_entry\fP 1i
-Specifies the KeyCode. 
-.IP \fImodifier\fP 1i
-Specifies the modifier.
-.LP
-.eM
-The
-.PN XDeleteModifiermapEntry
-function deletes the specified KeyCode from the set that controls the
-specified modifier and returns a pointer to the resulting
-.PN XModifierKeymap
-structure.
-.LP
-.sp
-To destroy an
-.PN XModifierKeymap
-structure, use
-.PN XFreeModifiermap .
-.IN "XFreeModifiermap" "" "@DEF@"
-.sM
-.FD 0
-XFreeModifiermap(\^\fImodmap\fP\^)
-.br
-        XModifierKeymap *\fImodmap\fP;
-.FN
-.IP \fImodmap\fP 1i
-Specifies the 
-.PN XModifierKeymap
-structure.
-.LP
-.eM
-The
-.PN XFreeModifiermap
-function frees the specified
-.PN XModifierKeymap
-structure.
-.LP
-.sp
-To set the KeyCodes to be used as modifiers, use
-.PN XSetModifierMapping .
-.IN "XSetModifierMapping" "" "@DEF@"
-.sM
-.FD 0
-int XSetModifierMapping(\^\fIdisplay\fP, \fImodmap\fP\^)
-.br
-        Display *\fIdisplay\fP\^;
-.br
-        XModifierKeymap *\fImodmap\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fImodmap\fP 1i
-Specifies the 
-.PN XModifierKeymap
-structure.
-.LP
-.eM
-The
-.PN XSetModifierMapping
-function specifies the KeyCodes of the keys (if any) that are to be used 
-as modifiers.
-If it succeeds,
-the X server generates a
-.PN MappingNotify
-event, and
-.PN XSetModifierMapping
-returns
-.PN MappingSuccess .
-X permits at most 8 modifier keys.
-If more than 8 are specified in the
-.PN XModifierKeymap
-structure, a
-.PN BadLength
-error results.
-.LP
-The modifiermap member of the 
-.PN XModifierKeymap
-structure contains 8 sets of max_keypermod KeyCodes, 
-one for each modifier in the order 
-.PN Shift , 
-.PN Lock , 
-.PN Control , 
-.PN Mod1 , 
-.PN Mod2 , 
-.PN Mod3 , 
-.PN Mod4 , 
-and 
-.PN Mod5 .
-Only nonzero KeyCodes have meaning in each set, 
-and zero KeyCodes are ignored.
-In addition, all of the nonzero KeyCodes must be in the range specified by 
-min_keycode and max_keycode in the 
-.PN Display 
-structure,
-or a 
-.PN BadValue 
-error results.
-.LP
-An X server can impose restrictions on how modifiers can be changed, 
-for example,
-if certain keys do not generate up transitions in hardware,
-if auto-repeat cannot be disabled on certain keys,
-or if multiple modifier keys are not supported.  
-If some such restriction is violated, 
-the status reply is
-.PN MappingFailed ,
-and none of the modifiers are changed.
-If the new KeyCodes specified for a modifier differ from those
-currently defined and any (current or new) keys for that modifier are
-in the logically down state, 
-.PN XSetModifierMapping
-returns
-.PN MappingBusy , 
-and none of the modifiers is changed.
-.LP
-.PN XSetModifierMapping
-can generate
-.PN BadAlloc
-and 
-.PN BadValue 
-errors.
-.LP
-.sp
-To obtain the KeyCodes used as modifiers, use
-.PN XGetModifierMapping .
-.IN "XGetModifierMapping" "" "@DEF@"
-.sM
-.FD 0
-XModifierKeymap *XGetModifierMapping(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-The
-.PN XGetModifierMapping
-function returns a pointer to a newly created
-.PN XModifierKeymap
-structure that contains the keys being used as modifiers.
-The structure should be freed after use by calling
-.PN XFreeModifiermap .
-If only zero values appear in the set for any modifier, 
-that modifier is disabled.
-.bp
diff --git a/libX11/specs/libX11/CH12.xml b/libX11/specs/libX11/CH12.xml
new file mode 100644
index 000000000..210a2be9f
--- /dev/null
+++ b/libX11/specs/libX11/CH12.xml
@@ -0,0 +1,3928 @@
+<chapter id="input_device_functions">

+<title>Input Device Functions</title>

+

+<para>

+You can use the Xlib input device functions to:

+</para>

+

+<itemizedlist>

+  <listitem><para>Grab the pointer and individual buttons on the pointer</para></listitem>

+  <listitem><para>Grab the keyboard and individual keys on the keyboard</para></listitem>

+  <listitem><para>Resume event processing</para></listitem>

+  <listitem><para>Move the pointer</para></listitem>

+  <listitem><para>Set the input focus</para></listitem>

+  <listitem><para>Manipulate the keyboard and pointer settings</para></listitem>

+  <listitem><para>Manipulate the keyboard encoding</para></listitem>

+</itemizedlist>

+

+<sect1 id="Pointer_Grabbing_">

+<title>Pointer Grabbing </title>

+<!-- .XS -->

+<!-- (SN Pointer Grabbing   -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to control input from the pointer,

+which usually is a mouse.

+Usually, as soon as keyboard and mouse events occur,

+the X server delivers them to the appropriate client,

+which is determined by the window and input focus.

+The X server provides sufficient control over event delivery to

+allow window managers to support mouse ahead and various other

+styles of user interface.

+Many of these user interfaces depend on synchronous delivery of events.

+The delivery of  pointer and keyboard events can be controlled

+independently.

+</para>

+<para>

+<!-- .LP -->

+When mouse buttons or keyboard keys are grabbed, events

+will be sent to the grabbing client rather than the normal

+client who would have received the event.

+If the keyboard or pointer is in asynchronous mode,

+further mouse and keyboard events will continue to be processed.

+If the keyboard or pointer is in synchronous mode, no

+further events are processed until the grabbing client

+allows them (see

+<function>XAllowEvents</function>).

+The keyboard or pointer is considered frozen during this

+interval.

+The event that triggered the grab can also be replayed.

+</para>

+<para>

+<!-- .LP -->

+Note that the logical state of a device (as seen by client applications)

+may lag the physical state if device event processing is frozen.

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>Active grab</primary></indexterm>

+There are two kinds of grabs:

+active and passive.

+An active grab occurs when a single client grabs the keyboard and/or pointer

+explicitly (see

+<function>XGrabPointer</function>

+and

+<function>XGrabKeyboard</function>).

+<indexterm><primary>Passive grab</primary></indexterm>

+A passive grab occurs when clients grab a particular keyboard key 

+or pointer button in a window,

+and the grab will activate when the key or button is actually pressed.

+Passive grabs are convenient for implementing reliable pop-up menus.

+For example, you can guarantee that the pop-up is mapped 

+before the up pointer button event occurs by

+grabbing a button requesting synchronous behavior.

+The down event will trigger the grab and freeze further

+processing of pointer events until you have the chance to

+map the pop-up window.

+You can then allow further event processing.

+The up event will then be correctly processed relative to the

+pop-up window.

+</para>

+<para>

+<!-- .LP -->

+For many operations,

+there are functions that take a time argument.

+The X server includes a timestamp in various events.

+One special time, called

+<indexterm significance="preferred"><primary>CurrentTime</primary></indexterm>

+<indexterm significance="preferred"><primary>Time</primary></indexterm>

+<function>CurrentTime</function>,

+represents the current server time.

+The X server maintains the time when the input focus was last changed,

+when the keyboard was last grabbed,

+when the pointer was last grabbed,

+or when a selection was last changed.

+Your

+application may be slow reacting to an event.

+You often need some way to specify that your

+request should not occur if another application has in the meanwhile

+taken control of the keyboard, pointer, or selection.

+By providing the timestamp from the event in the request, 

+you can arrange that the operation not take effect

+if someone else has performed an operation in the meanwhile.

+</para>

+<para>

+<!-- .LP -->

+A timestamp is a time value, expressed in milliseconds. 

+It typically is the time since the last server reset.

+Timestamp values wrap around (after about 49.7 days).

+The server, given its current time is represented by timestamp T, 

+always interprets timestamps from clients by treating half of the timestamp 

+space as being later in time than T.

+One timestamp value, named

+<function>CurrentTime</function>,

+is never generated by the server.

+This value is reserved for use in requests to represent the current server time.

+</para>

+<para>

+<!-- .LP -->

+For many functions in this section,

+you pass pointer event mask bits.

+The valid pointer event mask bits are:

+<function>ButtonPressMask</function>,

+<function>ButtonReleaseMask</function>,

+<function>EnterWindowMask</function>,

+<function>LeaveWindowMask</function>,

+<function>PointerMotionMask</function>,

+<function>PointerMotionHintMask</function>,

+<function>Button1MotionMask</function>,

+<function>Button2MotionMask</function>,

+<function>Button3MotionMask</function>,

+<function>Button4MotionMask</function>,

+<function>Button5MotionMask</function>,

+<function>ButtonMotionMask</function>,

+and

+<function>KeyMapStateMask</function>.

+For other functions in this section,

+you pass keymask bits.

+The valid keymask bits are:

+<function>ShiftMask</function>,

+<function>LockMask</function>,

+<function>ControlMask</function>,

+<function>Mod1Mask</function>,

+<function>Mod2Mask</function>,

+<function>Mod3Mask</function>,

+<function>Mod4Mask</function>,

+and

+<function>Mod5Mask</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To grab the pointer, use

+<function>XGrabPointer</function>.

+<indexterm><primary>Grabbing</primary><secondary>pointer</secondary></indexterm>

+<indexterm><primary>Pointer</primary><secondary>grabbing</secondary></indexterm>

+<indexterm significance="preferred"><primary>XGrabPointer</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> XGrabPointer</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> grab_window</parameter></paramdef>

+  <paramdef>Bool<parameter> owner_events</parameter></paramdef>

+  <paramdef>unsignedint<parameter> event_mask</parameter></paramdef>

+  <paramdef>intpointer_mode,<parameter> keyboard_mode</parameter></paramdef>

+  <paramdef>Window<parameter> confine_to</parameter></paramdef>

+  <paramdef>Cursor<parameter> cursor</parameter></paramdef>

+  <paramdef>Time<parameter> time</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>grab_window</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the grab window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>owner_events</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a Boolean value that indicates whether the pointer 

+events are to be reported as usual or reported with respect to the grab window 

+if selected by the event mask.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_mask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies which pointer events are reported to the client.

+The mask is the bitwise inclusive OR of the valid pointer event mask bits.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>pointer_mode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies further processing of pointer events.

+You can pass 

+<function>GrabModeSync </function>

+or

+<function>GrabModeAsync</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keyboard_mode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies further processing of keyboard events.

+You can pass 

+<function>GrabModeSync </function>

+or

+<function>GrabModeAsync</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>confine_to</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window to confine the pointer in or

+<function>None</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>cursor</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the cursor that is to be displayed during the grab or

+<function>None</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>time</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the time.

+You can pass either a timestamp or

+<function>CurrentTime</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGrabPointer</function>

+function actively grabs control of the pointer and returns

+<function>GrabSuccess</function>

+if the grab was successful.

+Further pointer events are reported only to the grabbing client.

+<function>XGrabPointer</function>

+overrides any active pointer grab by this client.

+If owner_events is 

+<function>False</function>,

+all generated pointer events

+are reported with respect to grab_window and are reported only if

+selected by event_mask.

+If owner_events is 

+<function>True</function>

+and if a generated

+pointer event would normally be reported to this client, 

+it is reported as usual. 

+Otherwise, the event is reported with respect to the

+grab_window and is reported only if selected by event_mask.

+For either value of owner_events, unreported events are discarded.

+</para>

+<para>

+<!-- .LP -->

+If the pointer_mode is 

+<function>GrabModeAsync</function>,

+pointer event processing continues as usual.

+If the pointer is currently frozen by this client, 

+the processing of events for the pointer is resumed.

+If the pointer_mode is 

+<function>GrabModeSync</function>,

+the state of the pointer, as seen by

+client applications,

+appears to freeze, and the X server generates no further pointer events

+until the grabbing client calls 

+<function>XAllowEvents</function>

+or until the pointer grab is released.

+Actual pointer changes are not lost while the pointer is frozen;

+they are simply queued in the server for later processing.

+</para>

+<para>

+<!-- .LP -->

+If the keyboard_mode is 

+<function>GrabModeAsync</function>,

+keyboard event processing is unaffected by activation of the grab.

+If the keyboard_mode is 

+<function>GrabModeSync</function>,

+the state of the keyboard, as seen by

+client applications,

+appears to freeze, and the X server generates no further keyboard events

+until the grabbing client calls 

+<function>XAllowEvents</function>

+or until the pointer grab is released.

+Actual keyboard changes are not lost while the pointer is frozen;

+they are simply queued in the server for later processing.

+</para>

+<para>

+<!-- .LP -->

+If a cursor is specified, it is displayed regardless of what

+window the pointer is in.  

+If 

+<function>None</function>

+is specified,

+the normal cursor for that window is displayed

+when the pointer is in grab_window or one of its subwindows;

+otherwise, the cursor for grab_window is displayed.

+</para>

+<para>

+<!-- .LP -->

+If a confine_to window is specified,

+the pointer is restricted to stay contained in that window.

+The confine_to window need have no relationship to the grab_window.

+If the pointer is not initially in the confine_to window, 

+it is warped automatically to the closest edge 

+just before the grab activates and enter/leave events are generated as usual. 

+If the confine_to window is subsequently reconfigured, 

+the pointer is warped automatically, as necessary, 

+to keep it contained in the window.

+</para>

+<para>

+<!-- .LP -->

+The time argument allows you to avoid certain circumstances that come up

+if applications take a long time to respond or if there are long network

+delays.

+Consider a situation where you have two applications, both

+of which normally grab the pointer when clicked on.

+If both applications specify the timestamp from the event, 

+the second application may wake up faster and successfully grab the pointer

+before the first application. 

+The first application then will get an indication that the other application 

+grabbed the pointer before its request was processed.

+</para>

+<para>

+<!-- .LP -->

+<function>XGrabPointer </function>

+generates

+<function>EnterNotify </function>

+and

+<function>LeaveNotify </function>

+events.

+</para>

+<para>

+<!-- .LP -->

+Either if grab_window or confine_to window is not viewable

+or if the confine_to window lies completely outside the boundaries of the root

+window,

+<function>XGrabPointer</function>

+fails and returns

+<function>GrabNotViewable</function>.

+If the pointer is actively grabbed by some other client,

+it fails and returns

+<function>AlreadyGrabbed</function>.

+If the pointer is frozen by an active grab of another client,

+it fails and returns

+<function>GrabFrozen</function>.

+If the specified time is earlier than the last-pointer-grab time or later 

+than the current X server time, it fails and returns

+<function>GrabInvalidTime</function>.

+Otherwise, the last-pointer-grab time is set to the specified time

+(<function>CurrentTime </function>

+is replaced by the current X server time).

+</para>

+<para>

+<!-- .LP -->

+<function>XGrabPointer</function>

+can generate

+<function>BadCursor</function>,

+<function>BadValue</function>,

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To ungrab the pointer, use

+<function>XUngrabPointer</function>.

+<indexterm><primary>Ungrabbing</primary><secondary>pointer</secondary></indexterm>

+<indexterm><primary>Pointer</primary><secondary>ungrabbing</secondary></indexterm>

+<indexterm significance="preferred"><primary>XUngrabPointer</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XUngrabPointer</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Time<parameter> time</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>time</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the time.

+You can pass either a timestamp or

+<function>CurrentTime</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XUngrabPointer</function>

+function releases the pointer and any queued events

+if this client has actively grabbed the pointer from

+<function>XGrabPointer</function>,

+<function>XGrabButton</function>,

+or from a normal button press.

+<function>XUngrabPointer</function>

+does not release the pointer if the specified

+time is earlier than the last-pointer-grab time or is later than the

+current X server time.

+It also generates 

+<function>EnterNotify </function>

+and 

+<function>LeaveNotify </function>

+events.

+The X server performs an 

+<function>UngrabPointer </function>

+request automatically if the event window or confine_to window 

+for an active pointer grab becomes not viewable

+or if window reconfiguration causes the confine_to window to lie completely

+outside the boundaries of the root window.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To change an active pointer grab, use

+<function>XChangeActivePointerGrab</function>.

+<indexterm><primary>Pointer</primary><secondary>grabbing</secondary></indexterm>

+<indexterm ><primary>Changing</primary><secondary>pointer grab</secondary></indexterm>

+<indexterm significance="preferred"><primary>XChangeActivePointerGrab</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XChangeActivePointerGrab</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>unsignedint<parameter> event_mask</parameter></paramdef>

+  <paramdef>Cursor<parameter> cursor</parameter></paramdef>

+  <paramdef>Time<parameter> time</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_mask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies which pointer events are reported to the client.

+The mask is the bitwise inclusive OR of the valid pointer event mask bits.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>cursor</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the cursor that is to be displayed or

+<function>None</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>time</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the time.

+You can pass either a timestamp or

+<function>CurrentTime</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XChangeActivePointerGrab</function>

+function changes the specified dynamic parameters if the pointer is actively

+grabbed by the client and if the specified time is no earlier than the

+last-pointer-grab time and no later than the current X server time.

+This function has no effect on the passive parameters of an

+<function>XGrabButton</function>.

+The interpretation of event_mask and cursor is the same as described in

+<function>XGrabPointer</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XChangeActivePointerGrab</function>

+can generate

+<function>BadCursor </function>

+and

+<function>BadValue</function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To grab a pointer button, use

+<function>XGrabButton</function>.

+<indexterm><primary>Grabbing</primary><secondary>buttons</secondary></indexterm>

+<indexterm><primary>Button</primary><secondary>grabbing</secondary></indexterm>

+<indexterm significance="preferred"><primary>XGrabButton</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XGrabButton</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>unsignedint<parameter> button</parameter></paramdef>

+  <paramdef>unsignedint<parameter> modifiers</parameter></paramdef>

+  <paramdef>Window<parameter> grab_window</parameter></paramdef>

+  <paramdef>Bool<parameter> owner_events</parameter></paramdef>

+  <paramdef>unsignedint<parameter> event_mask</parameter></paramdef>

+  <paramdef>intpointer_mode,<parameter> keyboard_mode</parameter></paramdef>

+  <paramdef>Window<parameter> confine_to</parameter></paramdef>

+  <paramdef>Cursor<parameter> cursor</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Bu grabbed -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>button</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the pointer button that is to be (Bu or

+<function>AnyButton</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>modifiers</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the set of keymasks or

+<function>AnyModifier</function>.

+The mask is the bitwise inclusive OR of the valid keymask bits.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>grab_window</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the grab window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>owner_events</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a Boolean value that indicates whether the pointer 

+events are to be reported as usual or reported with respect to the grab window 

+if selected by the event mask.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_mask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies which pointer events are reported to the client.

+The mask is the bitwise inclusive OR of the valid pointer event mask bits.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>pointer_mode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies further processing of pointer events.

+You can pass 

+<function>GrabModeSync </function>

+or

+<function>GrabModeAsync</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keyboard_mode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies further processing of keyboard events.

+You can pass 

+<function>GrabModeSync </function>

+or

+<function>GrabModeAsync</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>confine_to</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window to confine the pointer in or

+<function>None</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>cursor</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the cursor that is to be displayed or

+<function>None</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGrabButton</function>

+function establishes a passive grab.

+In the future,

+the pointer is actively grabbed (as for

+<function>XGrabPointer</function>),

+the last-pointer-grab time is set to the time at which the button was pressed

+(as transmitted in the

+<function>ButtonPress</function>

+event), and the

+<function>ButtonPress</function>

+event is reported if all of the following conditions are true:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+The pointer is not grabbed, and the specified button is logically pressed

+when the specified modifier keys are logically down,

+and no other buttons or modifier keys are logically down.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The grab_window contains the pointer.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The confine_to window (if any) is viewable.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A passive grab on the same button/key combination does not exist

+on any ancestor of grab_window.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+The interpretation of the remaining arguments is as for

+<function>XGrabPointer</function>.

+The active grab is terminated automatically when the logical state of the

+pointer has all buttons released

+(independent of the state of the logical modifier keys).

+</para>

+<para>

+<!-- .LP -->

+Note that the logical state of a device (as seen by client applications)

+may lag the physical state if device event processing is frozen.

+</para>

+<para>

+<!-- .LP -->

+This request overrides all previous grabs by the same client on the same

+button/key combinations on the same window.

+A modifiers of 

+<function>AnyModifier </function>

+is equivalent to issuing the grab request for all

+possible modifier combinations (including the combination of no modifiers).  

+It is not required that all modifiers specified have currently assigned 

+KeyCodes.

+A button of 

+<function>AnyButton </function>

+is equivalent to

+issuing the request for all possible buttons.

+Otherwise, it is not required that the specified button currently be assigned

+to a physical button.

+</para>

+<para>

+<!-- .LP -->

+If some other client has already issued an

+<function>XGrabButton</function>

+with the same button/key combination on the same window, a

+<function>BadAccess </function>

+error results.

+When using 

+<function>AnyModifier </function>

+or 

+<function>AnyButton</function>,

+the request fails completely,

+and a

+<function>BadAccess</function>

+error results (no grabs are

+established) if there is a conflicting grab for any combination.

+<function>XGrabButton</function>

+has no effect on an active grab.

+</para>

+<para>

+<!-- .LP -->

+<function>XGrabButton</function>

+can generate

+<function>BadCursor</function>,

+<function>BadValue</function>,

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To ungrab a pointer button, use

+<function>XUngrabButton</function>.

+<indexterm><primary>Ungrabbing</primary><secondary>buttons</secondary></indexterm>

+<indexterm><primary>Button</primary><secondary>ungrabbing</secondary></indexterm>

+<indexterm significance="preferred"><primary>XUngrabButton</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XUngrabButton</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>unsignedint<parameter> button</parameter></paramdef>

+  <paramdef>unsignedint<parameter> modifiers</parameter></paramdef>

+  <paramdef>Window<parameter> grab_window</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Bu released -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>button</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the pointer button that is to be (Bu or

+<function>AnyButton</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>modifiers</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the set of keymasks or

+<function>AnyModifier</function>.

+The mask is the bitwise inclusive OR of the valid keymask bits.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>grab_window</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the grab window.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XUngrabButton</function>

+function releases the passive button/key combination on the specified window if

+it was grabbed by this client.

+A modifiers of 

+<function>AnyModifier </function>

+is

+equivalent to issuing 

+the ungrab request for all possible modifier combinations, including 

+the combination of no modifiers.

+A button of 

+<function>AnyButton </function>

+is equivalent to issuing the

+request for all possible buttons.

+<function>XUngrabButton</function>

+has no effect on an active grab.

+</para>

+<para>

+<!-- .LP -->

+<function>XUngrabButton</function>

+can generate

+<function>BadValue</function>

+and

+<function>BadWindow </function>

+errors.

+</para>

+</sect1>

+<sect1 id="Keyboard_Grabbing_">

+<title>Keyboard Grabbing </title>

+<!-- .XS -->

+<!-- (SN Keyboard Grabbing  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to grab or ungrab the keyboard

+as well as allow events.

+</para>

+<para>

+<!-- .LP -->

+For many functions in this section,

+you pass keymask bits.

+The valid keymask bits are:

+<function>ShiftMask</function>,

+<function>LockMask</function>,

+<function>ControlMask</function>,

+<function>Mod1Mask</function>,

+<function>Mod2Mask</function>,

+<function>Mod3Mask</function>,

+<function>Mod4Mask</function>,

+and

+<function>Mod5Mask</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To grab the keyboard, use

+<function>XGrabKeyboard</function>.

+<indexterm><primary>Keyboard</primary><secondary>grabbing</secondary></indexterm>

+<indexterm><primary>Grabbing</primary><secondary>keyboard</secondary></indexterm>

+<indexterm significance="preferred"><primary>XGrabKeyboard</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> XGrabKeyboard</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> grab_window</parameter></paramdef>

+  <paramdef>Bool<parameter> owner_events</parameter></paramdef>

+  <paramdef>intpointer_mode,<parameter> keyboard_mode</parameter></paramdef>

+  <paramdef>Time<parameter> time</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>grab_window</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the grab window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>owner_events</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a Boolean value that indicates whether the keyboard events 

+are to be reported as usual.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>pointer_mode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies further processing of pointer events.

+You can pass 

+<function>GrabModeSync </function>

+or

+<function>GrabModeAsync</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keyboard_mode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies further processing of keyboard events.

+You can pass 

+<function>GrabModeSync </function>

+or

+<function>GrabModeAsync</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>time</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the time.

+You can pass either a timestamp or

+<function>CurrentTime</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGrabKeyboard</function>

+function actively grabs control of the keyboard and generates

+<function>FocusIn</function>

+and

+<function>FocusOut</function>

+events.

+Further key events are reported only to the

+grabbing client.

+<function>XGrabKeyboard</function>

+overrides any active keyboard grab by this client.

+If owner_events is 

+<function>False</function>,

+all generated key events are reported with

+respect to grab_window.  

+If owner_events is 

+<function>True  </function>

+and if a generated

+key event would normally be reported to this client, it is reported

+normally; otherwise, the event is reported with respect to the

+grab_window.  

+Both 

+<function>KeyPress </function>

+and 

+<function>KeyRelease </function>

+events are always reported,

+independent of any event selection made by the client.

+</para>

+<para>

+<!-- .LP -->

+If the keyboard_mode argument is 

+<function>GrabModeAsync</function>,

+keyboard event processing continues

+as usual. 

+If the keyboard is currently frozen by this client, 

+then processing of keyboard events is resumed.

+If the keyboard_mode  argument is

+<function>GrabModeSync</function>,

+the state of the keyboard (as seen by client applications) appears to freeze,

+and the X server generates no further keyboard events until the

+grabbing client issues a releasing 

+<function>XAllowEvents </function>

+call or until the keyboard grab is released.

+Actual keyboard changes are not lost while the keyboard is frozen; 

+they are simply queued in the server for later processing.

+</para>

+<para>

+<!-- .LP -->

+If pointer_mode is 

+<function>GrabModeAsync</function>,

+pointer event processing is unaffected

+by activation of the grab.  

+If pointer_mode is 

+<function>GrabModeSync</function>,

+the state of the pointer (as seen by client applications) appears to freeze, 

+and the X server generates no further pointer events 

+until the grabbing client issues a releasing 

+<function>XAllowEvents </function>

+call or until the keyboard grab is released.

+Actual pointer changes are not lost while the pointer is frozen; 

+they are simply queued in the server for later processing.

+</para>

+<para>

+<!-- .LP -->

+If the keyboard is actively grabbed by some other client,

+<function>XGrabKeyboard</function>

+fails and returns

+<function>AlreadyGrabbed</function>.

+If grab_window is not viewable,

+it fails and returns

+<function>GrabNotViewable</function>.

+If the keyboard is frozen by an active grab of another client,

+it fails and returns

+<function>GrabFrozen</function>.

+If the specified time is earlier than the last-keyboard-grab time 

+or later than the current X server time,

+it fails and returns

+<function>GrabInvalidTime</function>.

+Otherwise, the last-keyboard-grab time is set to the specified time

+(<function>CurrentTime </function>

+is replaced by the current X server time).

+</para>

+<para>

+<!-- .LP -->

+<function>XGrabKeyboard</function>

+can generate

+<function>BadValue</function>

+and 

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To ungrab the keyboard, use

+<function>XUngrabKeyboard</function>.

+<indexterm><primary>Keyboard</primary><secondary>ungrabbing</secondary></indexterm>

+<indexterm><primary>Ungrabbing</primary><secondary>keyboard</secondary></indexterm>

+<indexterm significance="preferred"><primary>XUngrabKeyboard</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XUngrabKeyboard</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Time<parameter> time</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>time</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the time.

+You can pass either a timestamp or

+<function>CurrentTime</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XUngrabKeyboard</function>

+function

+releases the keyboard and any queued events if this client has it actively grabbed from

+either

+<function>XGrabKeyboard</function>

+or

+<function>XGrabKey</function>.

+<function>XUngrabKeyboard</function>

+does not release the keyboard and any queued events

+if the specified time is earlier than

+the last-keyboard-grab time or is later than the current X server time.

+It also generates

+<function>FocusIn </function>

+and 

+<function>FocusOut </function>

+events.

+The X server automatically performs an 

+<function>UngrabKeyboard </function>

+request if the event window for an

+active keyboard grab becomes not viewable.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To passively grab a single key of the keyboard, use

+<function>XGrabKey</function>.

+<indexterm><primary>Key</primary><secondary>grabbing</secondary></indexterm>

+<indexterm><primary>Grabbing</primary><secondary>keys</secondary></indexterm>

+<indexterm significance="preferred"><primary>XGrabKey</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XGrabKey</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> keycode</parameter></paramdef>

+  <paramdef>unsignedint<parameter> modifiers</parameter></paramdef>

+  <paramdef>Window<parameter> grab_window</parameter></paramdef>

+  <paramdef>Bool<parameter> owner_events</parameter></paramdef>

+  <paramdef>intpointer_mode,<parameter> keyboard_mode</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keycode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the KeyCode or

+<function>AnyKey</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>modifiers</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the set of keymasks or

+<function>AnyModifier</function>.

+The mask is the bitwise inclusive OR of the valid keymask bits.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>grab_window</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the grab window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>owner_events</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a Boolean value that indicates whether the keyboard events 

+are to be reported as usual.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>pointer_mode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies further processing of pointer events.

+You can pass 

+<function>GrabModeSync </function>

+or

+<function>GrabModeAsync</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keyboard_mode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies further processing of keyboard events.

+You can pass 

+<function>GrabModeSync </function>

+or

+<function>GrabModeAsync</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGrabKey</function>

+function establishes a passive grab on the keyboard.

+In the future,

+the keyboard is actively grabbed (as for

+<function>XGrabKeyboard</function>),

+the last-keyboard-grab time is set to the time at which the key was pressed

+(as transmitted in the

+<function>KeyPress</function>

+event), and the

+<function>KeyPress</function>

+event is reported if all of the following conditions are true:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+The keyboard is not grabbed and the specified key

+(which can itself be a modifier key) is logically pressed

+when the specified modifier keys are logically down,

+and no other modifier keys are logically down.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Either the grab_window is an ancestor of (or is) the focus window,

+or the grab_window is a descendant of the focus window and contains the pointer.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A passive grab on the same key combination does not exist

+on any ancestor of grab_window.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+The interpretation of the remaining arguments is as for 

+<function>XGrabKeyboard</function>.

+The active grab is terminated automatically when the logical state of the

+keyboard has the specified key released

+(independent of the logical state of the modifier keys).

+</para>

+<para>

+<!-- .LP -->

+Note that the logical state of a device (as seen by client applications)

+may lag the physical state if device event processing is frozen.

+</para>

+<para>

+<!-- .LP -->

+A modifiers argument of 

+<function>AnyModifier</function>

+is equivalent to issuing the request for all

+possible modifier combinations (including the combination of no

+modifiers).  

+It is not required that all modifiers specified have

+currently assigned KeyCodes.

+A keycode argument of 

+<function>AnyKey</function>

+is equivalent to issuing

+the request for all possible KeyCodes.

+Otherwise, the specified keycode must be in

+the range specified by min_keycode and max_keycode in the connection

+setup, 

+or a

+<function>BadValue</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+If some other client has issued a 

+<function>XGrabKey</function>

+with the same key combination on the same window, a 

+<function>BadAccess </function>

+error results.

+When using

+<function>AnyModifier</function>

+or 

+<function>AnyKey</function>,

+the request fails completely,

+and a

+<function>BadAccess </function>

+error results (no grabs are established) 

+if there is a conflicting grab for any combination.

+</para>

+<para>

+<!-- .LP -->

+<function>XGrabKey</function>

+can generate

+<function>BadAccess</function>,

+<function>BadValue</function>,

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To ungrab a key, use

+<function>XUngrabKey</function>.

+<indexterm><primary>Key</primary><secondary>ungrabbing</secondary></indexterm>

+<indexterm><primary>Ungrabbing</primary><secondary>keys</secondary></indexterm>

+<indexterm significance="preferred"><primary>XUngrabKey</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XUngrabKey</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> keycode</parameter></paramdef>

+  <paramdef>unsignedint<parameter> modifiers</parameter></paramdef>

+  <paramdef>Window<parameter> grab_window</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keycode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the KeyCode or

+<function>AnyKey</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>modifiers</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the set of keymasks or

+<function>AnyModifier</function>.

+The mask is the bitwise inclusive OR of the valid keymask bits.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>grab_window</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the grab window.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XUngrabKey</function>

+function releases the key combination on the specified window if it was grabbed

+by this client.

+It has no effect on an active grab.

+A modifiers of

+<function>AnyModifier</function>

+is equivalent to issuing

+the request for all possible modifier combinations

+(including the combination of no modifiers).

+A keycode argument of

+<function>AnyKey</function>

+is equivalent to issuing the request for all possible key codes.

+</para>

+<para>

+<!-- .LP -->

+<function>XUngrabKey</function>

+can generate

+<function>BadValue</function>

+and

+<function>BadWindow </function>

+errors.

+</para>

+</sect1>

+<sect1 id="Resuming_Event_Processing">

+<title>Resuming Event Processing</title>

+<!-- .XS -->

+<!-- (SN Resuming Event Processing -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The previous sections discussed grab mechanisms with which processing

+of events by the server can be temporarily suspended.  This section

+describes the mechanism for resuming event processing.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To allow further events to be processed when the device has been frozen, use

+<function>XAllowEvents</function>.

+<indexterm significance="preferred"><primary>XAllowEvents</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XAllowEvents</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> event_mode</parameter></paramdef>

+  <paramdef>Time<parameter> time</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_mode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the event mode.

+You can pass 

+<function>AsyncPointer</function>,

+<function>SyncPointer</function>,

+<function>AsyncKeyboard</function>,

+<function>SyncKeyboard</function>,

+<function>ReplayPointer</function>,

+<function>ReplayKeyboard</function>,

+<function>AsyncBoth</function>,

+or

+<function>SyncBoth</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>time</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the time.

+You can pass either a timestamp or

+<function>CurrentTime</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XAllowEvents</function>

+function releases some queued events if the client has caused a device 

+to freeze.

+It has no effect if the specified time is earlier than the last-grab

+time of the most recent active grab for the client or if the specified time

+is later than the current X server time.

+Depending on the event_mode argument, the following occurs:

+</para>

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <tbody>

+    <row>

+      <entry><function>AsyncPointer</function></entry>

+      <entry>If the pointer is frozen by the client,

+      pointer event processing continues as usual.

+      If the pointer is frozen twice by the client on behalf of two separate grabs,

+      <function>AsyncPointer </function>

+      thaws for both.

+      <function>AsyncPointer</function>

+      has no effect if the pointer is not frozen by the client,

+      but the pointer need not be grabbed by the client.</entry>

+    </row>

+    <row>

+      <entry><function>SyncPointer </function></entry>

+      <entry>If the pointer is frozen and actively grabbed by the client,

+      pointer event processing continues as usual until the next

+      <function>ButtonPress </function>

+      or

+      <function>ButtonRelease </function>

+      event is reported to the client.

+      At this time,

+      the pointer again appears to freeze.

+      However, if the reported event causes the pointer grab to be released,

+      the pointer does not freeze.

+      <function>SyncPointer </function>

+      has no effect if the pointer is not frozen by the client

+      or if the pointer is not grabbed by the client.</entry>

+    </row>

+    <row>

+      <entry><function>ReplayPointer</function></entry>

+      <entry>If the pointer is actively grabbed by the client and is frozen as the result of

+      an event having been sent to the client (either from the activation of an

+      <function>XGrabButton </function>

+      or from a previous

+      <function>XAllowEvents </function>

+      with mode

+      <function>SyncPointer</function>

+      but not from an 

+      <function>XGrabPointer</function>),

+      the pointer grab is released and that event is completely reprocessed.

+      This time, however, the function ignores any passive grabs at or above 

+      (toward the root of) the grab_window of the grab just released.

+      The request has no effect if the pointer is not grabbed by the client

+      or if the pointer is not frozen as the result of an event.</entry>

+    </row>

+    <row>

+      <entry><function>AsyncKeyboard </function></entry>

+      <entry>If the keyboard is frozen by the client,

+      keyboard event processing continues as usual.

+      If the keyboard is frozen twice by the client on behalf of two separate grabs,

+      <function>AsyncKeyboard </function>

+      thaws for both.

+      <function>AsyncKeyboard </function>

+      has no effect if the keyboard is not frozen by the client,

+      but the keyboard need not be grabbed by the client.</entry>

+    </row>

+    <row>

+      <entry><function>SyncKeyboard</function></entry>

+      <entry>If the keyboard is frozen and actively grabbed by the client,

+      keyboard event processing continues as usual until the next

+      <function>KeyPress </function>

+      or

+      <function>KeyRelease </function>

+      event is reported to the client.

+      At this time,

+      the keyboard again appears to freeze.

+      However, if the reported event causes the keyboard grab to be released,

+      the keyboard does not freeze.

+      <function>SyncKeyboard </function>

+      has no effect if the keyboard is not frozen by the client

+      or if the keyboard is not grabbed by the client.</entry>

+    </row>

+    <row>

+      <entry><function>ReplayKeyboard</function></entry>

+      <entry>If the keyboard is actively grabbed by the client and is frozen

+      as the result of an event having been sent to the client (either from the

+      activation of an

+      <function>XGrabKey </function>

+      or from a previous

+      <function>XAllowEvents </function>

+      with mode

+      <function>SyncKeyboard </function>

+      but not from an 

+      <function>XGrabKeyboard</function>),

+      the keyboard grab is released and that event is completely reprocessed.

+      This time, however, the function ignores any passive grabs at or above

+      (toward the root of)

+      the grab_window of the grab just released.

+      The request has no effect if the keyboard is not grabbed by the client

+      or if the keyboard is not frozen as the result of an event.</entry>

+    </row>

+    <row>

+      <entry><function>SyncBoth</function></entry>

+      <entry>If both pointer and keyboard are frozen by the client,

+      event processing for both devices continues as usual until the next

+      <function>ButtonPress</function>,

+      <function>ButtonRelease</function>,

+      <function>KeyPress</function>,

+      or 

+      <function>KeyRelease </function>

+      event is reported to the client for a grabbed device 

+      (button event for the pointer, key event for the keyboard), 

+      at which time the devices again appear to freeze.  

+      However, if the reported event causes the grab to be released,

+      then the devices do not freeze (but if the other device is still

+      grabbed, then a subsequent event for it will still cause both devices

+      to freeze).  

+      <function>SyncBoth</function>

+      has no effect unless both pointer and keyboard

+      are frozen by the client.

+      If the pointer or keyboard is frozen twice

+      by the client on behalf of two separate grabs, 

+      <function>SyncBoth </function>

+      thaws for both (but a subsequent freeze for 

+      <function>SyncBoth </function>

+      will only freeze each device once).</entry>

+    </row>

+    <row>

+      <entry><function>AsyncBoth</function></entry>

+      <entry>If the pointer and the keyboard are frozen by the

+      client, event processing for both devices continues as usual.

+      If a device is frozen twice by the client on behalf of two separate grabs,

+      <function>AsyncBoth </function>

+      thaws for both.

+      <function>AsyncBoth </function>

+      has no effect unless both

+      pointer and keyboard are frozen by the client.</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<para>

+<!-- .LP -->

+<function>AsyncPointer</function>,

+<function>SyncPointer</function>,

+and 

+<function>ReplayPointer </function>

+have no effect on the

+processing of keyboard events.

+<function>AsyncKeyboard</function>,

+<function>SyncKeyboard</function>,

+and 

+<function>ReplayKeyboard </function>

+have no effect on the

+processing of pointer events.

+It is possible for both a pointer grab and a keyboard grab (by the same 

+or different clients) to be active simultaneously.

+If a device is frozen on behalf of either grab,

+no event processing is performed for the device.

+It is possible for a single device to be frozen because of both grabs.

+In this case,

+the freeze must be released on behalf of both grabs before events can 

+again be processed.

+If a device is frozen twice by a single client,

+then a single

+<function>AllowEvents</function>

+releases both.

+</para>

+<para>

+<!-- .LP -->

+<function>XAllowEvents</function>

+can generate a

+<function>BadValue </function>

+error.

+</para>

+</sect1>

+<sect1 id="Moving_the_Pointer">

+<title>Moving the Pointer</title>

+<!-- .XS -->

+<!-- (SN Moving the Pointer -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Although movement of the pointer normally should be left to the

+control of the end user, sometimes it is necessary to move the

+pointer to a new position under program control.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To move the pointer to an arbitrary point in a window, use

+<function>XWarpPointer</function>.

+<indexterm significance="preferred"><primary>XWarpPointer</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XWarpPointer</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Windowsrc_w,<parameter> dest_w</parameter></paramdef>

+  <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>

+  <paramdef>unsignedintsrc_width,<parameter> src_height</parameter></paramdef>

+  <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>src_w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the source window or

+<function>None</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dest_w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the destination window or

+<function>None</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>src_x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>src_y</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>src_width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>src_height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify a rectangle in the source window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dest_x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dest_y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates within the destination window.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If dest_w is

+<function>None</function>,

+<function>XWarpPointer</function>

+moves the pointer by the offsets (dest_x, dest_y) relative to the current

+position of the pointer.

+If dest_w is a window,

+<function>XWarpPointer</function>

+moves the pointer to the offsets (dest_x, dest_y) relative to the origin of

+dest_w.

+However, if src_w is a window,

+the move only takes place if the window src_w contains the pointer 

+and if the specified rectangle of src_w contains the pointer.

+</para>

+<para>

+<!-- .LP -->

+The src_x and src_y coordinates are relative to the origin of src_w.

+If src_height is zero,

+it is replaced with the current height of src_w minus src_y.

+If src_width is zero,

+it is replaced with the current width of src_w minus src_x.

+</para>

+<para>

+<!-- .LP -->

+There is seldom any reason for calling this function. 

+The pointer should normally be left to the user.

+If you do use this function, however, it generates events just as if the user

+had instantaneously moved the pointer from one position to another.

+Note that you cannot use

+<function>XWarpPointer</function>

+to move the pointer outside the confine_to window of an active pointer grab.

+An attempt to do so will only move the pointer as far as the closest edge of the

+confine_to window. 

+</para>

+<para>

+<!-- .LP -->

+<function>XWarpPointer</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+</sect1>

+<sect1 id="Controlling_Input_Focus">

+<title>Controlling Input Focus</title>

+<!-- .XS -->

+<!-- (SN Controlling Input Focus  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to set and get the input focus.

+The input focus is a shared resource, and cooperation among clients is

+required for correct interaction.  See the

+<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis> 

+for input focus policy.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the input focus, use

+<function>XSetInputFocus</function>.

+<indexterm significance="preferred"><primary>XSetInputFocus</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetInputFocus</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> focus</parameter></paramdef>

+  <paramdef>int<parameter> revert_to</parameter></paramdef>

+  <paramdef>Time<parameter> time</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>focus</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window,

+<function>PointerRoot</function>,

+or

+<function>None</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>revert_to</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies where the input focus reverts to if the window becomes not

+viewable.

+You can pass 

+<function>RevertToParent</function>,

+<function>RevertToPointerRoot</function>,

+or 

+<function>RevertToNone</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>time</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the time.

+You can pass either a timestamp or

+<function>CurrentTime</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetInputFocus</function>

+function changes the input focus and the last-focus-change time.

+It has no effect if the specified time is earlier than the current

+last-focus-change time or is later than the current X server time.

+Otherwise, the last-focus-change time is set to the specified time

+(<function>CurrentTime </function>

+is replaced by the current X server time).

+<function>XSetInputFocus</function>

+causes the X server to generate

+<function>FocusIn </function>

+and 

+<function>FocusOut </function>

+events.

+</para>

+<para>

+<!-- .LP -->

+Depending on the focus argument,

+the following occurs: 

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+If focus is

+<function>None</function>,

+all keyboard events are discarded until a new focus window is set,

+and the revert_to argument is ignored.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If focus is a window, 

+it becomes the keyboard's focus window.

+If a generated keyboard event would normally be reported to this window

+or one of its inferiors, the event is reported as usual. 

+Otherwise, the event is reported relative to the focus window.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If focus is

+<function>PointerRoot</function>,

+the focus window is dynamically taken to be the root window of whatever screen 

+the pointer is on at each keyboard event.  

+In this case, the revert_to argument is ignored.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+The specified focus window must be viewable at the time 

+<function>XSetInputFocus</function>

+is called,

+or a

+<function>BadMatch</function>

+error results.

+If the focus window later becomes not viewable, 

+the X server

+evaluates the revert_to argument to determine the new focus window as follows: 

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+If revert_to is

+<function>RevertToParent</function>,

+the focus reverts to the parent (or the closest viewable ancestor), 

+and the new revert_to value is taken to be

+<function>RevertToNone</function>.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If revert_to is

+<function>RevertToPointerRoot </function>

+or 

+<function>RevertToNone</function>,

+the focus reverts to

+<function>PointerRoot</function>

+or

+<function>None</function>,

+respectively.

+When the focus reverts,

+the X server generates

+<function>FocusIn</function>

+and

+<function>FocusOut</function>

+events, but the last-focus-change time is not affected.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+<function>XSetInputFocus</function>

+can generate

+<function>BadMatch</function>,

+<function>BadValue</function>,

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the current input focus, use

+<function>XGetInputFocus</function>.

+<indexterm significance="preferred"><primary>XGetInputFocus</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XGetInputFocus</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> *focus_return</parameter></paramdef>

+  <paramdef>int<parameter> *revert_to_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>focus_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the focus window,

+<function>PointerRoot</function>,

+or 

+<function>None</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>revert_to_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the current focus state

+(<function>RevertToParent</function>,

+<function>RevertToPointerRoot</function>,

+or 

+<function>RevertToNone</function>).

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetInputFocus</function>

+function returns the focus window and the current focus state.

+</para>

+</sect1>

+<sect1 id="Manipulating_the_Keyboard_and_Pointer_Settings">

+<title>Manipulating the Keyboard and Pointer Settings</title>

+<!-- .XS -->

+<!-- (SN Manipulating the Keyboard and Pointer Settings  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to

+change the keyboard control, obtain a list of the auto-repeat keys,

+turn keyboard auto-repeat on or off, ring the bell, 

+set or obtain the pointer button or keyboard mapping, 

+and obtain a bit vector for the keyboard.

+</para>

+<para>

+<!-- .LP -->

+<indexterm><primary>Keyboard</primary><secondary>bell volume</secondary></indexterm>

+<indexterm><primary>Keyboard</primary><secondary>keyclick volume</secondary></indexterm>

+<indexterm><primary>Keyboard</primary><secondary>bit vector</secondary></indexterm>

+<indexterm><primary>Mouse</primary><secondary>programming</secondary></indexterm>

+This section discusses 

+the user-preference options of bell, key click,

+pointer behavior, and so on.

+The default values for many of these options are server dependent.

+Not all implementations will actually be able to control all of these

+parameters.

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XChangeKeyboardControl</function>

+function changes control of a keyboard and operates on a

+<function>XKeyboardControl</function>

+structure:

+<!-- .sM -->

+</para>

+

+<literallayout class="monospaced">

+/* Mask bits for ChangeKeyboardControl */

+

+

+#define     KBBellPercent           (1L&lt;&lt;0)

+#define     KBBellPitch             (1L&lt;&lt;1)

+#define     KBBellDuration          (1L&lt;&lt;2)

+#define     KBLed                   (1L&lt;&lt;3)

+#define     KBLedMode               (1L&lt;&lt;4)

+#define     KBKey                   (1L&lt;&lt;5)

+#define     KBAutoRepeatMode        (1L&lt;&lt;6)

+

+

+/* Values */

+

+typedef struct {

+int key_click_percent;

+int bell_percent;

+int bell_pitch;

+int bell_duration;

+int led;

+int led_mode;                /* LedModeOn, LedModeOff */

+int key;

+int auto_repeat_mode;        /* AutoRepeatModeOff, AutoRepeatModeOn,

+                                AutoRepeatModeDefault */

+} XKeyboardControl;

+

+</literallayout>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The key_click_percent member sets the volume for key clicks between 0 (off) 

+and 100 (loud) inclusive, if possible.  

+A setting of -1 restores the default.

+Other negative values generate a

+<function>BadValue</function>

+error.

+</para>

+<para>

+<!-- .LP -->

+The bell_percent sets the base volume for the bell between 0 (off) and 100

+(loud) inclusive, if possible.  

+A setting of -1 restores the default.

+Other negative values generate a

+<function>BadValue</function>

+error.

+The bell_pitch member sets the pitch (specified in Hz) of the bell, if possible.

+A setting of -1 restores the default.

+Other negative values generate a

+<function>BadValue</function>

+error.

+The bell_duration member sets the duration of the

+bell specified in milliseconds, if possible.  

+A setting of -1 restores the default.

+Other negative values generate a

+<function>BadValue</function>

+error.

+</para>

+<para>

+<!-- .LP -->

+If both the led_mode and led members are specified,

+the state of that <acronym>LED</acronym> is changed, if possible.  

+The led_mode member can be set to

+<function>LedModeOn</function>

+or

+<function>LedModeOff</function>.

+If only led_mode is specified, the state of

+all LEDs are changed, if possible.  

+At most 32 LEDs numbered from one are supported. 

+No standard interpretation of LEDs is defined.

+If led is specified without led_mode, a

+<function>BadMatch</function>

+error results. 

+</para>

+<para>

+<!-- .LP -->

+If both the auto_repeat_mode and key members are specified, 

+the auto_repeat_mode of that key is changed (according to

+<function>AutoRepeatModeOn</function>,

+<function>AutoRepeatModeOff</function>,

+or

+<function>AutoRepeatModeDefault</function>),

+if possible.

+If only auto_repeat_mode is

+specified, the global auto_repeat_mode for the entire keyboard is

+changed, if possible, and does not affect the per-key settings.

+If a key is specified without an auto_repeat_mode, a

+<function>BadMatch</function>

+error results.

+Each key has an individual mode of whether or not it should auto-repeat

+and a default setting for the mode.

+In addition,

+there is a global mode of whether auto-repeat should be enabled or not

+and a default setting for that mode.

+When global mode is

+<function>AutoRepeatModeOn</function>,

+keys should obey their individual auto-repeat modes.

+When global mode is

+<function>AutoRepeatModeOff</function>,

+no keys should auto-repeat.

+An auto-repeating key generates alternating

+<function>KeyPress</function>

+and

+<function>KeyRelease</function>

+events.

+When a key is used as a modifier,

+it is desirable for the key not to auto-repeat,

+regardless of its auto-repeat setting.

+</para>

+<para>

+<!-- .LP -->

+A bell generator connected with the console but not directly on a

+keyboard is treated as if it were part of the keyboard.

+The order in which controls are verified and altered is server-dependent.

+If an error is generated, a subset of the controls may have been altered.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<indexterm significance="preferred"><primary>XChangeKeyboardControl</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XChangeKeyboardControl</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> value_mask</parameter></paramdef>

+  <paramdef>XKeyboardControl<parameter> *values</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>value_mask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies which controls to change.

+This mask is the bitwise inclusive OR of the valid control mask bits.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>values</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies one value for each bit set to 1 in the mask.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XChangeKeyboardControl</function>

+function controls the keyboard characteristics defined by the

+<function>XKeyboardControl</function>

+structure.

+The value_mask argument specifies which values are to be changed.

+</para>

+<para>

+<!-- .LP -->

+<function>XChangeKeyboardControl</function>

+can generate

+<function>BadMatch</function>

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the current control values for the keyboard, use

+<function>XGetKeyboardControl</function>.

+<indexterm significance="preferred"><primary>XGetKeyboardControl</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XGetKeyboardControl</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XKeyboardState<parameter> *values_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>values_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the current keyboard controls in the specified

+<function>XKeyboardState </function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetKeyboardControl</function>

+function returns the current control values for the keyboard to the

+<function>XKeyboardState</function>

+structure.

+</para>

+<para>

+<!-- .LP -->

+<indexterm><primary>XGetKeyboardControl</primary></indexterm>

+<indexterm significance="preferred"><primary>XKeyboardState</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i  -->

+<!-- .ta .5i -->

+typedef struct {

+	int key_click_percent;

+	int bell_percent;

+	unsigned int bell_pitch, bell_duration;

+	unsigned long led_mask;

+	int global_auto_repeat;

+	char auto_repeats[32];

+} XKeyboardState;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+For the LEDs, 

+the least significant bit of led_mask corresponds to <acronym>LED</acronym> one,

+and each bit set to 1 in led_mask indicates an <acronym>LED</acronym> that is lit.

+The global_auto_repeat member can be set to

+<function>AutoRepeatModeOn</function>

+or

+<function>AutoRepeatModeOff</function>.

+The auto_repeats member is a bit vector.

+Each bit set to 1 indicates that auto-repeat is enabled 

+for the corresponding key.

+The vector is represented as 32 bytes.  

+Byte N (from 0) contains the bits for keys 8N to 8N + 7

+with the least significant bit in the byte representing key 8N.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To turn on keyboard auto-repeat, use

+<function>XAutoRepeatOn</function>.

+<indexterm significance="preferred"><primary>XAutoRepeatOn</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XAutoRepeatOn</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XAutoRepeatOn</function>

+function turns on auto-repeat for the keyboard on the specified display.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To turn off keyboard auto-repeat, use

+<function>XAutoRepeatOff</function>.

+<indexterm significance="preferred"><primary>XAutoRepeatOff</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XAutoRepeatOff</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XAutoRepeatOff</function>

+function turns off auto-repeat for the keyboard on the specified display.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To ring the bell, use

+<function>XBell</function>.

+<indexterm significance="preferred"><primary>XBell</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XBell</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> percent</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>percent</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the volume for the bell,

+which can range from -100 to 100 inclusive. 

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XBell</function>

+function rings the bell on the keyboard on the specified display, if possible.

+The specified volume is relative to the base volume for the keyboard.

+If the value for the percent argument is not in the range -100 to 100

+inclusive, a

+<function>BadValue</function>

+error results.

+The volume at which the bell rings

+when the percent argument is nonnegative is:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+base - [(base * percent) / 100] + percent

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+The volume at which the bell rings

+when the percent argument is negative is:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+base + [(base * percent) / 100]

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+To change the base volume of the bell, use

+<function>XChangeKeyboardControl</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XBell</function>

+can generate a

+<function>BadValue </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain a bit vector that describes the state of the keyboard, use

+<function>XQueryKeymap</function>.

+<indexterm significance="preferred"><primary>XQueryKeymap</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XQueryKeymap</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>char<parameter> keys_return[32]</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keys_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns an array of bytes that identifies which keys are pressed down.

+Each bit represents one key of the keyboard.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XQueryKeymap</function>

+function returns a bit vector for the logical state of the keyboard, 

+where each bit set to 1 indicates that the corresponding key is currently 

+pressed down.

+The vector is represented as 32 bytes.

+Byte N (from 0) contains the bits for keys 8N to 8N + 7 

+with the least significant bit in the byte representing key 8N.

+</para>

+<para>

+<!-- .LP -->

+Note that the logical state of a device (as seen by client applications)

+may lag the physical state if device event processing is frozen.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the mapping of the pointer buttons, use

+<function>XSetPointerMapping</function>.

+<indexterm significance="preferred"><primary>XSetPointerMapping</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> XSetPointerMapping</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>unsignedchar<parameter> map[]</parameter></paramdef>

+  <paramdef>int<parameter> nmap</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>map</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the mapping list.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nmap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of items in the mapping list.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetPointerMapping</function>

+function sets the mapping of the pointer.

+If it succeeds, the X server generates a

+<function>MappingNotify</function>

+event, and

+<function>XSetPointerMapping</function>

+returns

+<function>MappingSuccess</function>.

+Element map[i] defines the logical button number for the physical button

+i+1.

+The length of the list must be the same as

+<function>XGetPointerMapping</function>

+would return,

+or a

+<function>BadValue</function>

+error results.

+A zero element disables a button, and elements are not restricted in

+value by the number of physical buttons.

+However, no two elements can have the same nonzero value,

+or a

+<function>BadValue</function>

+error results.

+If any of the buttons to be altered are logically in the down state,

+<function>XSetPointerMapping</function>

+returns

+<function>MappingBusy</function>,

+and the mapping is not changed.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetPointerMapping</function>

+can generate a

+<function>BadValue </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To get the pointer mapping, use

+<function>XGetPointerMapping</function>.

+<indexterm significance="preferred"><primary>XGetPointerMapping</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> XGetPointerMapping</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>unsignedchar<parameter> map_return[]</parameter></paramdef>

+  <paramdef>int<parameter> nmap</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>map_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the mapping list.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nmap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of items in the mapping list.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetPointerMapping</function>

+function returns the current mapping of the pointer.

+Pointer buttons are numbered starting from one.

+<function>XGetPointerMapping</function>

+returns the number of physical buttons actually on the pointer.

+The nominal mapping for a pointer is map[i]=i+1.

+The nmap argument specifies the length of the array where the pointer

+mapping is returned, and only the first nmap elements are returned 

+in map_return.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To control the pointer's interactive feel, use

+<function>XChangePointerControl</function>.

+<indexterm significance="preferred"><primary>XChangePointerControl</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XChangePointerControl</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Booldo_accel,<parameter> do_threshold</parameter></paramdef>

+  <paramdef>intaccel_numerator,<parameter> accel_denominator</parameter></paramdef>

+  <paramdef>int<parameter> threshold</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>do_accel</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a Boolean value that controls whether the values for 

+the accel_numerator or accel_denominator are used.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>do_threshold</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a Boolean value that controls whether the value for the 

+threshold is used.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>accel_numerator</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the numerator for the acceleration multiplier.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>accel_denominator</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the denominator for the acceleration multiplier.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>threshold</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the acceleration threshold.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XChangePointerControl</function>

+function defines how the pointing device moves.

+The acceleration, expressed as a fraction, is a

+multiplier for movement. 

+For example,

+specifying 3/1 means the pointer moves three times as fast as normal.

+The fraction may be rounded arbitrarily by the X server.  

+Acceleration

+only takes effect if the pointer moves more than threshold pixels at

+once and only applies to the amount beyond the value in the threshold argument.

+Setting a value to -1 restores the default.

+The values of the do_accel and do_threshold arguments must be 

+<function>True </function>

+for the pointer values to be set,

+or the parameters are unchanged.

+Negative values (other than -1) generate a

+<function>BadValue</function>

+error, as does a zero value

+for the accel_denominator argument.

+</para>

+<para>

+<!-- .LP -->

+<function>XChangePointerControl</function>

+can generate a

+<function>BadValue </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To get the current pointer parameters, use

+<function>XGetPointerControl</function>.

+<indexterm significance="preferred"><primary>XGetPointerControl</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XGetPointerControl</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int*accel_numerator_return,<parameter> *accel_denominator_return</parameter></paramdef>

+  <paramdef>int<parameter> *threshold_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>accel_numerator_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the numerator for the acceleration multiplier.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>accel_denominator_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the denominator for the acceleration multiplier.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>threshold_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the acceleration threshold.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetPointerControl</function>

+function returns the pointer's current acceleration multiplier

+and acceleration threshold.

+</para>

+</sect1>

+<sect1 id="Manipulating_the_Keyboard_Encoding">

+<title>Manipulating the Keyboard Encoding</title>

+<!-- .XS -->

+<!-- (SN Manipulating the Keyboard Encoding  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+A KeyCode represents a physical (or logical) key.  

+KeyCodes lie in the inclusive range [8,255].  

+A KeyCode value carries no intrinsic information,

+although server implementors may attempt to encode geometry 

+(for example, matrix) information in some fashion so that it can

+be interpreted in a server-dependent fashion.

+The mapping between keys and KeyCodes cannot be changed.

+</para>

+<para>

+<!-- .LP -->

+A KeySym is an encoding of a symbol on the cap of a key.  

+The set of defined KeySyms includes the ISO Latin character sets (1-4), 

+Katakana, Arabic, Cyrillic, Greek, Technical,

+Special, Publishing, APL, Hebrew, Thai, Korean

+and a miscellany of keys found

+on keyboards (Return, Help, Tab, and so on).  

+To the extent possible, these sets are derived from international

+standards. 

+In areas where no standards exist,

+some of these sets are derived from Digital Equipment Corporation standards.

+The list of defined symbols can be found in

+<!-- .hN X11/keysymdef.h . -->

+Unfortunately, some C preprocessors have

+limits on the number of defined symbols.

+If you must use KeySyms not

+in the Latin 1-4, Greek, and miscellaneous classes,

+you may have to define a symbol for those sets.

+Most applications usually only include 

+<!-- .hN X11/keysym.h , -->

+which defines symbols for ISO Latin 1-4, Greek, and miscellaneous.

+</para>

+<para>

+<!-- .LP -->

+A list of KeySyms is associated with each KeyCode.

+The list is intended to convey the set of symbols on the corresponding key.

+If the list (ignoring trailing

+<function>NoSymbol</function>

+entries) is 

+a single KeySym ``<emphasis remap='I'>K</emphasis>'',

+then the list is treated as if it were the list 

+``<emphasis remap='I'>K</emphasis> NoSymbol <emphasis remap='I'>K</emphasis> NoSymbol''.

+If the list (ignoring trailing

+<function>NoSymbol</function>

+entries) is a pair of KeySyms ``<emphasis remap='I'>K1 K2</emphasis>'',

+then the list is treated as if it were the list ``<emphasis remap='I'>K1 K2 K1 K2</emphasis>''.

+If the list (ignoring trailing

+<function>NoSymbol</function>

+entries) is a triple of KeySyms ``<emphasis remap='I'>K1 K2 K3</emphasis>'',

+then the list is treated as if it were the list ``<emphasis remap='I'>K1 K2 K3</emphasis> NoSymbol''.

+When an explicit ``void'' element is desired in the list,

+the value

+<function>VoidSymbol</function>

+can be used.

+</para>

+<para>

+<!-- .LP -->

+The first four elements of the list are split into two groups of KeySyms.

+Group 1 contains the first and second KeySyms;

+Group 2 contains the third and fourth KeySyms.

+Within each group,

+if the second element of the group is

+<function>NoSymbol</function>,

+then the group should be treated as if the second element were 

+the same as the first element,

+except when the first element is an alphabetic KeySym ``<emphasis remap='I'>K</emphasis>'' 

+for which both lowercase and uppercase forms are defined.

+In that case,

+the group should be treated as if the first element were 

+the lowercase form of ``<emphasis remap='I'>K</emphasis>'' and the second element were 

+the uppercase form of ``<emphasis remap='I'>K</emphasis>''.

+</para>

+<para>

+<!-- .LP -->

+The standard rules for obtaining a KeySym from a

+<function>KeyPress</function>

+event make use of only the Group 1 and Group 2 KeySyms;

+no interpretation of other KeySyms in the list is given.

+Which group to use is determined by the modifier state.

+Switching between groups is controlled by the KeySym named MODE SWITCH,

+by attaching that KeySym to some KeyCode and attaching 

+that KeyCode to any one of the modifiers

+<function>Mod1</function>

+through

+<function>Mod5</function>.

+This modifier is called the <emphasis remap='I'>group modifier</emphasis>.

+For any KeyCode,

+Group 1 is used when the group modifier is off,

+and Group 2 is used when the group modifier is on.

+</para>

+<para>

+<!-- .LP -->

+The

+<function>Lock</function>

+modifier is interpreted as CapsLock when the KeySym named XK_Caps_Lock

+is attached to some KeyCode and that KeyCode is attached to the

+<function>Lock</function>

+modifier.  The

+<function>Lock</function>

+modifier is interpreted as ShiftLock when the KeySym named XK_Shift_Lock

+is attached to some KeyCode and that KeyCode is attached to the

+<function>Lock </function>

+modifier.  If the

+<function>Lock </function>

+modifier could be interpreted as both

+CapsLock and ShiftLock, the CapsLock interpretation is used.

+</para>

+<para>

+<!-- .LP -->

+The operation of keypad keys is controlled by the KeySym named XK_Num_Lock,

+by attaching that KeySym to some KeyCode and attaching that KeyCode to any

+one of the modifiers

+<function>Mod1 </function>

+through

+<function>Mod5</function>.

+This modifier is called the

+<emphasis remap='I'>numlock modifier</emphasis>.  The standard KeySyms with the prefix ``XK_KP_''

+in their

+name are called keypad KeySyms; these are KeySyms with numeric value in

+the hexadecimal range 0xFF80 to 0xFFBD inclusive.  In addition,

+vendor-specific KeySyms in the hexadecimal range 0x11000000 to 0x1100FFFF

+are also keypad KeySyms.

+</para>

+<para>

+<!-- .LP -->

+Within a group, the choice of KeySym is determined by applying the first

+rule that is satisfied from the following list:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+The numlock modifier is on and the second KeySym is a keypad KeySym.  In

+this case, if the

+<function>Shift </function>

+modifier is on, or if the

+<function>Lock </function>

+modifier is on and

+is interpreted as ShiftLock, then the first KeySym is used, otherwise the

+second KeySym is used.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The

+<function>Shift </function>

+and

+<function>Lock </function>

+modifiers are both off.  In this case, the first

+KeySym is used.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The

+<function>Shift </function>

+modifier is off, and the

+<function>Lock </function>

+modifier is on and is

+interpreted as CapsLock.  In this case, the first KeySym is used, but if

+that KeySym is lowercase alphabetic, then the corresponding uppercase

+KeySym is used instead.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The

+<function>Shift </function>

+modifier is on, and the

+<function>Lock </function>

+modifier is on and is interpreted

+as CapsLock.  In this case, the second KeySym is used, but if that KeySym

+is lowercase alphabetic, then the corresponding uppercase KeySym is used

+instead.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The

+<function>Shift </function>

+modifier is on, or the

+<function>Lock </function>

+modifier is on and is interpreted

+as ShiftLock, or both.  In this case, the second KeySym is used.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+No spatial geometry of the symbols on the key is defined by

+their order in the KeySym list, 

+although a geometry might be defined on a

+server-specific basis.

+The X server does not use the mapping between KeyCodes and KeySyms.

+Rather, it merely stores it for reading and writing by clients.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To obtain the legal KeyCodes for a display, use

+<function>XDisplayKeycodes</function>.

+<indexterm significance="preferred"><primary>XDisplayKeycodes</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDisplayKeycodes</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int*min_keycodes_return,<parameter> *max_keycodes_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>min_keycodes_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the minimum number of KeyCodes.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>max_keycodes_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the maximum number of KeyCodes.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XDisplayKeycodes</function>

+function returns the min-keycodes and max-keycodes supported by the

+specified display.

+The minimum number of KeyCodes returned is never less than 8,

+and the maximum number of KeyCodes returned is never greater than 255.

+Not all KeyCodes in this range are required to have corresponding keys.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To obtain the symbols for the specified KeyCodes, use

+<function>XGetKeyboardMapping</function>.

+<indexterm significance="preferred"><primary>XGetKeyboardMapping</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>KeySym<function> *XGetKeyboardMapping</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>KeyCode<parameter> first_keycode</parameter></paramdef>

+  <paramdef>int<parameter> keycode_count</parameter></paramdef>

+  <paramdef>int<parameter> *keysyms_per_keycode_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Kc returned -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>first_keycode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the first KeyCode that is to be (Kc.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keycode_count</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of KeyCodes that are to be returned.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keysyms_per_keycode_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of KeySyms per KeyCode.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetKeyboardMapping</function>

+function returns the symbols for the specified number of KeyCodes

+starting with first_keycode.

+The value specified in first_keycode must be greater than 

+or equal to min_keycode as returned by

+<function>XDisplayKeycodes</function>,

+or a

+<function>BadValue </function>

+error results.

+In addition, the following expression must be less than or equal 

+to max_keycode as returned by

+<function>XDisplayKeycodes :</function>

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+first_keycode + keycode_count - 1

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+If this is not the case, a 

+<function>BadValue </function>

+error results. 

+The number of elements in the KeySyms list is:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+keycode_count * keysyms_per_keycode_return

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+KeySym number N, counting from zero, for KeyCode K has the following index

+in the list, counting from zero: 

+<literallayout class="monospaced">

+(K - first_code) * keysyms_per_code_return + N

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+The X server arbitrarily chooses the keysyms_per_keycode_return value 

+to be large enough to report all requested symbols. 

+A special KeySym value of 

+<function>NoSymbol </function>

+is used to fill in unused elements for

+individual KeyCodes.

+To free the storage returned by 

+<function>XGetKeyboardMapping</function>,

+use

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetKeyboardMapping</function>

+can generate a

+<function>BadValue </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To change the keyboard mapping, use

+<function>XChangeKeyboardMapping</function>.

+<indexterm significance="preferred"><primary>XChangeKeyboardMapping</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XChangeKeyboardMapping</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> first_keycode</parameter></paramdef>

+  <paramdef>int<parameter> keysyms_per_keycode</parameter></paramdef>

+  <paramdef>KeySym<parameter> *keysyms</parameter></paramdef>

+  <paramdef>int<parameter> num_codes</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Kc changed -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>first_keycode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the first KeyCode that is to be (Kc.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keysyms_per_keycode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of KeySyms per KeyCode.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keysyms</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array of KeySyms.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>num_codes</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of KeyCodes that are to be changed.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XChangeKeyboardMapping</function>

+function defines the symbols for the specified number of KeyCodes

+starting with first_keycode.

+The symbols for KeyCodes outside this range remain unchanged.  

+The number of elements in keysyms must be:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+num_codes * keysyms_per_keycode

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+The specified first_keycode must be greater than or equal to min_keycode 

+returned by

+<function>XDisplayKeycodes</function>,

+or a 

+<function>BadValue </function>

+error results.

+In addition, the following expression must be less than or equal to 

+max_keycode as returned by

+<function>XDisplayKeycodes</function>,

+or a

+<function>BadValue </function>

+error results:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+first_keycode + num_codes - 1

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+KeySym number N, counting from zero, for KeyCode K has the following index

+in keysyms, counting from zero: 

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+(K - first_keycode) * keysyms_per_keycode + N

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+The specified keysyms_per_keycode can be chosen arbitrarily by the client

+to be large enough to hold all desired symbols. 

+A special KeySym value of 

+<function>NoSymbol </function>

+should be used to fill in unused elements 

+for individual KeyCodes.  

+It is legal for 

+<function>NoSymbol </function>

+to appear in nontrailing positions

+of the effective list for a KeyCode.

+<function>XChangeKeyboardMapping</function>

+generates a 

+<function>MappingNotify </function>

+event.

+</para>

+<para>

+<!-- .LP -->

+There is no requirement that the X server interpret this mapping. 

+It is merely stored for reading and writing by clients.

+</para>

+<para>

+<!-- .LP -->

+<function>XChangeKeyboardMapping</function>

+can generate

+<function>BadAlloc </function>

+and

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+The next six functions make use of the 

+<function>XModifierKeymap</function>

+data structure, which contains:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XModifierKeymap</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct {

+	int max_keypermod;	/* This server's max number of keys per modifier */

+	KeyCode *modifiermap;	/* An 8 by max_keypermod array of the modifiers */

+} XModifierKeymap;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+To create an

+<function>XModifierKeymap</function>

+structure, use

+<function>XNewModifiermap</function>.

+<indexterm significance="preferred"><primary>XNewModifiermap</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XModifierKeymap<function> *XNewModifiermap</function></funcdef>

+  <paramdef>int<parameter> max_keys_per_mod</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>max_keys_per_mod</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of KeyCode entries preallocated to the modifiers

+in the map.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XNewModifiermap</function>

+function returns a pointer to

+<function>XModifierKeymap</function>

+structure for later use.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To add a new entry to an 

+<function>XModifierKeymap</function>

+structure, use

+<function>XInsertModifiermapEntry</function>.

+<indexterm significance="preferred"><primary>XInsertModifiermapEntry</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XModifierKeymap<function> *XInsertModifiermapEntry</function></funcdef>

+  <paramdef>XModifierKeymap<parameter> *modmap</parameter></paramdef>

+  <paramdef>KeyCode<parameter> keycode_entry</parameter></paramdef>

+  <paramdef>int<parameter> modifier</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>modmap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the 

+<function>XModifierKeymap</function>

+structure.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keycode_entry</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the KeyCode. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>modifier</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the modifier.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XInsertModifiermapEntry</function>

+function adds the specified KeyCode to the set that controls the specified

+modifier and returns the resulting

+<function>XModifierKeymap</function>

+structure (expanded as needed).

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To delete an entry from an 

+<function>XModifierKeymap</function>

+structure, use

+<function>XDeleteModifiermapEntry</function>.

+<indexterm significance="preferred"><primary>XDeleteModifiermapEntry</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XModifierKeymap<function> *XDeleteModifiermapEntry</function></funcdef>

+  <paramdef>XModifierKeymap<parameter> *modmap</parameter></paramdef>

+  <paramdef>KeyCode<parameter> keycode_entry</parameter></paramdef>

+  <paramdef>int<parameter> modifier</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>modmap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the 

+<function>XModifierKeymap</function>

+structure.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keycode_entry</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the KeyCode. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>modifier</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the modifier.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XDeleteModifiermapEntry</function>

+function deletes the specified KeyCode from the set that controls the

+specified modifier and returns a pointer to the resulting

+<function>XModifierKeymap</function>

+structure.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To destroy an

+<function>XModifierKeymap</function>

+structure, use

+<function>XFreeModifiermap</function>.

+<indexterm significance="preferred"><primary>XFreeModifiermap</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XFreeModifiermap</function></funcdef>

+  <paramdef>XModifierKeymap<parameter> *modmap</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>modmap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the 

+<function>XModifierKeymap</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XFreeModifiermap</function>

+function frees the specified

+<function>XModifierKeymap</function>

+structure.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the KeyCodes to be used as modifiers, use

+<function>XSetModifierMapping</function>.

+<indexterm significance="preferred"><primary>XSetModifierMapping</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> XSetModifierMapping</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XModifierKeymap<parameter> *modmap</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>modmap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the 

+<function>XModifierKeymap</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetModifierMapping</function>

+function specifies the KeyCodes of the keys (if any) that are to be used 

+as modifiers.

+If it succeeds,

+the X server generates a

+<function>MappingNotify</function>

+event, and

+<function>XSetModifierMapping</function>

+returns

+<function>MappingSuccess</function>.

+X permits at most 8 modifier keys.

+If more than 8 are specified in the

+<function>XModifierKeymap</function>

+structure, a

+<function>BadLength</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+The modifiermap member of the 

+<function>XModifierKeymap</function>

+structure contains 8 sets of max_keypermod KeyCodes, 

+one for each modifier in the order 

+<function>Shift</function>,

+<function>Lock</function>,

+<function>Control</function>,

+<function>Mod1</function>,

+<function>Mod2</function>,

+<function>Mod3</function>,

+<function>Mod4</function>,

+and 

+<function>Mod5</function>.

+Only nonzero KeyCodes have meaning in each set, 

+and zero KeyCodes are ignored.

+In addition, all of the nonzero KeyCodes must be in the range specified by 

+min_keycode and max_keycode in the 

+<function>Display </function>

+structure,

+or a 

+<function>BadValue </function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+An X server can impose restrictions on how modifiers can be changed, 

+for example,

+if certain keys do not generate up transitions in hardware,

+if auto-repeat cannot be disabled on certain keys,

+or if multiple modifier keys are not supported.  

+If some such restriction is violated, 

+the status reply is

+<function>MappingFailed</function>,

+and none of the modifiers are changed.

+If the new KeyCodes specified for a modifier differ from those

+currently defined and any (current or new) keys for that modifier are

+in the logically down state, 

+<function>XSetModifierMapping</function>

+returns

+<function>MappingBusy</function>,

+and none of the modifiers is changed.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetModifierMapping</function>

+can generate

+<function>BadAlloc</function>

+and 

+<function>BadValue </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the KeyCodes used as modifiers, use

+<function>XGetModifierMapping</function>.

+<indexterm significance="preferred"><primary>XGetModifierMapping</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XModifierKeymap<function> *XGetModifierMapping</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetModifierMapping</function>

+function returns a pointer to a newly created

+<function>XModifierKeymap</function>

+structure that contains the keys being used as modifiers.

+The structure should be freed after use by calling

+<function>XFreeModifiermap</function>.

+If only zero values appear in the set for any modifier, 

+that modifier is disabled.

+<!-- .bp -->

+

+

+</para>

+</sect1>

+</chapter>

diff --git a/libX11/specs/libX11/CH13 b/libX11/specs/libX11/CH13
deleted file mode 100644
index ed143c690..000000000
--- a/libX11/specs/libX11/CH13
+++ /dev/null
@@ -1,7673 +0,0 @@
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-.\" OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" Except as contained in this notice, the name of the X Consortium shall
-.\" not be used in advertising or otherwise to promote the sale, use or
-.\" other dealings in this Software without prior written authorization
-.\" from the X Consortium.
-.\"
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
-.\" Digital Equipment Corporation
-.\"
-.\" Portions Copyright \(co 1990, 1991 by
-.\" Tektronix, Inc.
-.\"
-.\" Permission to use, copy, modify and distribute this documentation for
-.\" any purpose and without fee is hereby granted, provided that the above
-.\" copyright notice appears in all copies and that both that copyright notice
-.\" and this permission notice appear in all copies, and that the names of
-.\" Digital and Tektronix not be used in in advertising or publicity pertaining
-.\" to this documentation without specific, written prior permission.
-.\" Digital and Tektronix makes no representations about the suitability
-.\" of this documentation for any purpose.
-.\" It is provided ``as is'' without express or implied warranty.
-.\" 
-\&
-.sp 1
-.ce 3
-\s+1\fBChapter 13\fP\s-1
-
-\s+1\fBLocales and Internationalized Text Functions\fP\s-1
-.sp 2
-.nr H1 13
-.nr H2 0
-.nr H3 0
-.nr H4 0
-.nr H5 0
-.na
-.LP
-.XS
-Chapter 13: Locales and Internationalized Text Functions
-.XE
-An internationalized application is one that is adaptable to the requirements
-of different native languages, local customs, and character string encodings.
-The process of adapting the operation to a particular native language,
-local custom, or string encoding is called \fIlocalization\fP\^.
-A goal of internationalization is to permit localization
-without program source modifications or recompilation.
-.LP
-As one of the localization mechanisms,
-Xlib provides an X Input Method
-.Pn ( XIM )
-functional interface for internationalized text input
-and an X Output Method
-.Pn ( XOM )
-functional interface for internationalized text output.
-.LP
-Internationalization in X is based on the concept of a \fIlocale\fP.
-A locale defines the localized behavior of a program at run time.
-Locales affect Xlib in its:
-.IP \(bu 5
-Encoding and processing of input method text
-.IP \(bu 5
-Encoding of resource files and values
-.IP \(bu 5
-Encoding and imaging of text strings
-.IP \(bu 5
-Encoding and decoding for inter-client text communication
-.LP
-Characters from various languages are represented in a computer
-using an encoding.
-Different languages have different encodings,
-and there are even different encodings for the same characters
-in the same language.
-.LP
-This chapter defines support for localized text imaging and text input
-and describes the locale mechanism that controls all locale-dependent
-Xlib functions.
-Sets of functions are provided for multibyte (char *) text as well as
-wide character (wchar_t) text in the form supported 
-by the host C language environment.
-The multibyte and wide character functions
-are equivalent except for the form of the text argument.
-.LP
-The Xlib internationalization functions are not meant to provide
-support for multilingual applications (mixing multiple languages
-within a single piece of text), but they make it possible to
-implement applications that work in limited fashion with more than
-one language in independent contexts.
-.LP
-The remainder of this chapter discusses:
-.IP \(bu 5
-X locale management
-.IP \(bu 5
-Locale and modifier dependencies
-.IP \(bu 5
-Variable argument lists
-.IP \(bu 5
-Output methods
-.IP \(bu 5
-Input methods
-.IP \(bu 5
-String constants
-.NH 2
-X Locale Management
-.XS
-\*(SN X Locale Management
-.XE
-.LP
-X supports one or more of the locales defined by the host environment.
-On implementations that conform to the ANSI C library,
-the locale announcement method is
-.PN setlocale .
-This function configures the locale operation of both
-the host C library and Xlib.
-The operation of Xlib is governed by the LC_CTYPE category;
-this is called the \fIcurrent locale\fP.
-An implementation is permitted to provide implementation-dependent
-mechanisms for announcing the locale in addition to
-.PN setlocale .
-.LP
-On implementations that do not conform to the ANSI C library, 
-the locale announcement method is Xlib implementation-dependent.
-.LP
-The mechanism by which the semantic operation of Xlib is defined
-for a specific locale is implementation-dependent.
-.LP
-.sp
-X is not required to support all the locales supported by the host.
-To determine if the current locale is supported by X, use
-.PN XSupportsLocale .
-.IN "XSupportsLocale" "" "@DEF@"
-.sM
-.FD 0
-Bool XSupportsLocale\^(\|)
-.FN
-.LP
-.eM
-The 
-.PN XSupportsLocale
-function returns 
-.PN True
-if Xlib functions are capable of operating under the current locale.
-If it returns 
-.PN False ,
-Xlib locale-dependent functions for which the 
-.PN XLocaleNotSupported 
-return status is defined will return 
-.PN XLocaleNotSupported .
-Other Xlib locale-dependent routines will operate in the ``C'' locale.
-.LP
-The client is responsible for selecting its locale and X modifiers.
-Clients should provide a means for the user to override the clients'
-locale selection at client invocation.
-Most single-display X clients operate in a single locale 
-for both X and the host processing environment.
-They will configure the locale by calling three functions: 
-the host locale configuration function,
-.PN XSupportsLocale ,
-and 
-.PN XSetLocaleModifiers .
-.LP
-The semantics of certain categories of X internationalization capabilities
-can be configured by setting modifiers.
-Modifiers are named by implementation-dependent and locale-specific strings.
-The only standard use for this capability at present
-is selecting one of several styles of keyboard input method.
-.LP
-.sp
-To configure Xlib locale modifiers for the current locale, use
-.PN XSetLocaleModifiers .
-.IN "XSetLocaleModifiers" "" "@DEF@"
-.sM
-.FD 0
-char *XSetLocaleModifiers\^(\^\fImodifier_list\fP\^)
-.br
-      char *\fImodifier_list\fP\^;
-.FN
-.IP \fImodifier_list\fP 1i
-Specifies the modifiers.
-.LP
-.eM
-The
-.PN XSetLocaleModifiers
-function sets the X modifiers for the current locale setting.
-The modifier_list argument is a null-terminated string of the form
-``{@\^\fIcategory\fP\^=\^\fIvalue\fP\^}'', that is,
-having zero or more concatenated ``@\^\fIcategory\fP\^=\^\fIvalue\fP\^''
-entries, where \fIcategory\fP is a category name 
-and \fIvalue\fP is the (possibly empty) setting for that category.
-The values are encoded in the current locale.
-Category names are restricted to the POSIX Portable Filename Character Set.
-.LP
-The local host X locale modifiers announcer (on POSIX-compliant systems,
-the XMODIFIERS environment variable) is appended to the modifier_list to
-provide default values on the local host.
-If a given category appears more than once in the list,
-the first setting in the list is used.
-If a given category is not included in the full modifier list,
-the category is set to an implementation-dependent default
-for the current locale.
-An empty value for a category explicitly specifies the
-implementation-dependent default.
-.LP
-If the function is successful, it returns a pointer to a string.
-The contents of the string are such that a subsequent call with that string
-(in the same locale) will restore the modifiers to the same settings.
-If modifier_list is a NULL pointer,
-.PN XSetLocaleModifiers
-also returns a pointer to such a string,
-and the current locale modifiers are not changed.
-.LP
-If invalid values are given for one or more modifier categories supported by
-the locale, a NULL pointer is returned, and none of the
-current modifiers are changed.
-.LP
-At program startup,
-the modifiers that are in effect are unspecified until
-the first successful call to set them.  Whenever the locale is changed, the
-modifiers that are in effect become unspecified until the next successful call
-to set them.
-Clients should always call
-.PN XSetLocaleModifiers
-with a non-NULL modifier_list after setting the locale
-before they call any locale-dependent Xlib routine.
-.LP
-The only standard modifier category currently defined is ``im'',
-which identifies the desired input method.
-The values for input method are not standardized.
-A single locale may use multiple input methods,
-switching input method under user control.
-The modifier may specify the initial input method in effect
-or an ordered list of input methods.
-Multiple input methods may be specified in a single im value string
-in an implementation-dependent manner.
-.LP
-The returned modifiers string is owned by Xlib and should not be modified or
-freed by the client.
-It may be freed by Xlib after the current locale or modifiers are changed.
-Until freed, it will not be modified by Xlib.
-.LP
-The recommended procedure for clients initializing their locale and modifiers
-is to obtain locale and modifier announcers separately from
-one of the following prioritized sources:
-.IP \(bu 5
-A command line option
-.IP \(bu 5
-A resource
-.IP \(bu 5
-The empty string ("\^")
-.LP
-The first of these that is defined should be used.
-Note that when a locale command line option or locale resource is defined,
-the effect should be to set all categories to the specified locale,
-overriding any category-specific settings in the local host environment.
-.NH 2
-Locale and Modifier Dependencies
-.XS
-\*(SN Locale and Modifier Dependencies
-.XE
-.LP
-The internationalized Xlib functions operate in the current locale
-configured by the host environment and X locale modifiers set by
-.PN XSetLocaleModifiers
-or in the locale and modifiers configured at the time
-some object supplied to the function was created.
-For each locale-dependent function,
-the following table describes the locale (and modifiers) dependency:
-.TS H
-lw(1.25i) lw(2.5i) lw(2i).
-_
-.sp 6p
-.B
-Locale from	Affects the Function	In
-.sp 6p
-_
-.sp 6p
-.TH
-.R
-	Locale Query/Configuration:
-.sp 6p
-T{
-.PN setlocale
-T}	T{
-.PN XSupportsLocale
-T}	T{
-Locale queried
-T}
-	T{
-.PN XSetLocaleModifiers
-T}	T{
-Locale modified
-T}
-.sp
-	Resources:
-.sp 6p
-T{
-.PN setlocale
-T}	T{
-.PN XrmGetFileDatabase
-T}	T{
-Locale of 
-.PN XrmDatabase
-T}
-	T{
-.PN XrmGetStringDatabase
-T}
-T{
-.PN XrmDatabase
-T}	T{
-.PN XrmPutFileDatabase
-T}	T{
-Locale of 
-.PN XrmDatabase
-T}
-	T{
-.PN XrmLocaleOfDatabase
-T}
-.sp
-	Setting Standard Properties:
-.sp 6p
-T{
-.PN setlocale
-T}	T{
-.PN XmbSetWMProperties
-T}	T{
-Encoding of supplied/returned
-T}
-		text (some WM_ property
-		text in environment locale)
-.sp 6p
-T{
-.PN setlocale
-T}	T{
-.PN XmbTextPropertyToTextList
-T}	T{
-Encoding of supplied/returned text
-T}
-	T{
-.PN XwcTextPropertyToTextList
-T}
-	T{
-.PN XmbTextListToTextProperty
-T}
-	T{
-.PN XwcTextListToTextProperty
-T}
-.sp
-	Text Input:
-.sp 6p
-T{
-.PN setlocale
-T}	T{
-.PN XOpenIM
-T}	T{
-XIM input method selection
-T}
-	T{
-.PN XRegisterIMInstantiateCallback
-T}	T{
-XIM selection
-T}
-	T{
-.PN XUnregisterIMInstantiateCallback
-T}	T{
-XIM selection
-T}
-T{
-.PN XIM
-T}	T{
-.PN XCreateIC
-T}	T{
-XIC input method configuration
-T}
-	T{
-.PN XLocaleOfIM , 
-and so on
-T}	T{
-Queried locale
-T}
-T{
-.PN XIC
-T}	T{
-.PN XmbLookupString
-T}	T{
-Keyboard layout
-T}
-	T{
-.PN XwcLookupString
-T}	T{
-Encoding of returned text
-T}
-.sp
-	Text Drawing:
-.sp 6p
-T{
-.PN setlocale
-T}	T{
-.PN XOpenOM
-T}	T{
-XOM output method selection
-T}
-	T{
-.PN XCreateFontSet
-T}	T{
-Charsets of fonts in 
-.PN XFontSet
-T}
-T{
-.PN XOM
-T}	T{
-.PN XCreateOC
-T}	T{
-XOC output method configuration
-T}
-	T{
-.PN XLocaleOfOM , 
-and so on
-T}	T{
-Queried locale
-T}
-T{
-.PN XFontSet
-T}	T{
-.PN XmbDrawText ,
-T}	T{
-Locale of supplied text
-T}
-	T{
-.PN XwcDrawText ,
-and so on
-T}	T{
-Locale of supplied text
-T}
-	T{
-.PN XExtentsOfFontSet ,
-and so on
-T}	T{
-Locale-dependent metrics
-T}
-	T{
-.PN XmbTextExtents ,
-T}
-	T{
-.PN XwcTextExtents , 
-and so on
-T}
-.sp
-	Xlib Errors:
-.sp 6p
-T{
-.PN setlocale
-T}	T{
-.PN XGetErrorDatabaseText
-T}	T{
-Locale of error message
-T}
-	T{
-.PN XGetErrorText
-T}
-.sp 6p
-_
-.TE
-.LP
-Clients may assume that a locale-encoded text string returned 
-by an X function can be passed to a C library routine, or vice versa,
-if the locale is the same at the two calls.
-.LP
-All text strings processed by internationalized Xlib functions are assumed
-to begin in the initial state of the encoding of the locale, if the encoding
-is state-dependent.
-.LP
-All Xlib functions behave as if they do not change the current locale
-or X modifier setting.
-(This means that if they do change locale or call 
-.PN XSetLocaleModifiers
-with a non-NULL argument, they must save and restore the current state on
-entry and exit.)
-Also, Xlib functions on implementations that conform to the ANSI C library do
-not alter the global state associated with the ANSI C functions 
-.PN mblen , 
-.PN mbtowc , 
-.PN wctomb ,
-and 
-.PN strtok .
-.NH 2
-Variable Argument Lists
-.XS
-\*(SN Variable Argument Lists
-.XE
-.LP
-Various functions in this chapter have arguments that conform
-to the ANSI C variable argument list calling convention.
-Each function denoted with an argument of the form ``...'' takes 
-a variable-length list of name and value pairs,
-where each name is a string and each value is of type 
-.PN XPointer .
-A name argument that is NULL identifies the end of the list. 
-.LP
-A variable-length argument list may contain a nested list.
-If the name 
-.PN XNVaNestedList
-is specified in place of an argument name,
-then the following value is interpreted as an 
-.PN XVaNestedList
-value that specifies a list of values logically inserted into the
-original list at the point of declaration.
-A NULL identifies the end of a nested list.
-.LP
-.sp
-To allocate a nested variable argument list dynamically, use
-.PN XVaCreateNestedList .
-.IN "XVaCreateNestedList" "" @DEF@"
-.sM
-.FD 0
-typedef void * XVaNestedList;
-
-XVaNestedList XVaCreateNestedList\^(\^\fIdummy\fP\^, ...)
-.br
-      int \fIdummy\fP\^; 
-.FN
-.IP \fIdummy\fP 1i
-Specifies an unused argument (required by ANSI C).
-.ds Al
-.IP ... 1i
-Specifies the variable length argument list\*(Al.
-.LP
-.eM
-The
-.PN XVaCreateNestedList
-function allocates memory and copies its arguments into
-a single list pointer,
-which may be used as a value for arguments requiring a list value.
-Any entries are copied as specified.
-Data passed by reference is not copied;
-the caller must ensure data remains valid for the lifetime
-of the nested list.
-The list should be freed using
-.PN XFree
-when it is no longer needed.
-.NH 2
-Output Methods
-.XS
-\*(SN Output Methods
-.XE
-.LP
-This section provides discussions of the following X Output Method
-(XOM) topics:
-.IP \(bu 5
-Output method overview
-.IP \(bu 5
-Output method functions
-.IP \(bu 5
-Output method values
-.IP \(bu 5
-Output context functions
-.IP \(bu 5
-Output context values
-.IP \(bu 5
-Creating and freeing a font set
-.IP \(bu 5
-Obtaining font set metrics
-.IP \(bu 5
-Drawing text using font sets
-.NH 3
-Output Method Overview
-.XS
-\*(SN Output Method Overview
-.XE
-.LP
-Locale-dependent text may include one or more text components, each of
-which may require different fonts and character set encodings.
-In some languages, each component might have a different
-drawing direction, and some components might contain
-context-dependent characters that change shape based on
-relationships with neighboring characters.
-.LP
-When drawing such locale-dependent text, some locale-specific
-knowledge is required;
-for example, what fonts are required to draw the text,
-how the text can be separated into components, and which
-fonts are selected to draw each component.
-Further, when bidirectional text must be drawn,
-the internal representation order of the text must be changed
-into the visual representation order to be drawn.
-.LP
-An X Output Method provides a functional interface so that clients
-do not have to deal directly with such locale-dependent details.
-Output methods provide the following capabilities:
-.IP \(bu 5
-Creating a set of fonts required to draw locale-dependent text.
-.IP \(bu 5
-Drawing locale-dependent text with a font set without the caller
-needing to be aware of locale dependencies.
-.IP \(bu 5
-Obtaining the escapement and extents in pixels of locale-dependent text.
-.IP \(bu 5
-Determining if bidirectional or context-dependent drawing is required
-in a specific locale with a specific font set.
-.LP
-Two different abstractions are used in the representation of
-the output method for clients.
-.LP
-The abstraction used to communicate with an output method
-is an opaque data structure represented by the 
-.PN XOM
-data type.
-The abstraction for representing the state of a particular output thread
-is called an \fIoutput context\fP.
-The Xlib representation of an output context is an 
-.PN XOC ,
-which is compatible with 
-.PN XFontSet
-in terms of its functional interface, but is 
-a broader, more generalized abstraction.
-.NH 3 
-Output Method Functions
-.XS
-\*(SN Output Method Functions
-.XE
-.LP
-To open an output method, use
-.PN XOpenOM .
-.IN "XOpenOM" "" "@DEF@"
-.sM
-.FD 0
-XOM XOpenOM\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XrmDatabase \fIdb\fP\^;
-.br
-      char *\fIres_name\fP\^;
-.br
-      char *\fIres_class\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIdb\fP 1i
-Specifies a pointer to the resource database.
-.IP \fIres_name\fP 1i
-Specifies the full resource name of the application.
-.IP \fIres_class\fP 1i
-Specifies the full class name of the application.
-.LP
-.eM
-The
-.PN XOpenOM
-function opens an output method
-matching the current locale and modifiers specification.
-The current locale and modifiers are bound to the output method
-when
-.PN XOpenOM
-is called.
-The locale associated with an output method cannot be changed.
-.LP
-The specific output method to which this call will be routed
-is identified on the basis of the current locale and modifiers.
-.PN XOpenOM
-will identify a default output method corresponding to the
-current locale.
-That default can be modified using 
-.PN XSetLocaleModifiers
-to set the output method modifier.
-.LP
-The db argument is the resource database to be used by the output method
-for looking up resources that are private to the output method.
-It is not intended that this database be used to look
-up values that can be set as OC values in an output context.
-If db is NULL,
-no database is passed to the output method.
-.LP
-The res_name and res_class arguments specify the resource name 
-and class of the application. 
-They are intended to be used as prefixes by the output method
-when looking up resources that are common to all output contexts
-that may be created for this output method.
-The characters used for resource names and classes must be in the
-X Portable Character Set.
-The resources looked up are not fully specified
-if res_name or res_class is NULL.
-.LP
-The res_name and res_class arguments are not assumed to exist beyond
-the call to
-.PN XOpenOM .
-The specified resource database is assumed to exist for the lifetime
-of the output method.
-.LP
-.PN XOpenOM
-returns NULL if no output method could be opened.
-.LP
-.sp
-To close an output method, use
-.PN XCloseOM .
-.IN "XCloseOM" "" "@DEF@"
-.sM
-.FD 0
-Status XCloseOM\^(\^\fIom\fP\^)
-.br
-      XOM \fIom\fP\^;
-.FN
-.IP \fIom\fP 1i
-Specifies the output method.
-.LP
-.eM
-The
-.PN XCloseOM
-function closes the specified output method.
-.LP
-.sp
-To set output method attributes, use 
-.PN XSetOMValues .
-.IN "XSetOMValues" "" "@DEF@"
-.sM
-.FD 0
-char * XSetOMValues\^(\^\fIom\fP\^, ...)
-.br
-      XOM \fIom\fP\^; 
-.FN
-.IP \fIom\fP 1i
-Specifies the output method.
-.ds Al \ to set XOM values
-.IP ... 1i
-Specifies the variable-length argument list\*(Al.
-.LP
-.eM
-The
-.PN XSetOMValues
-function presents a variable argument list programming interface
-for setting properties or features of the specified output method.
-This function returns NULL if it succeeds;
-otherwise,
-it returns the name of the first argument that could not be obtained.
-.LP
-No standard arguments are currently defined by Xlib.
-.LP
-.sp
-To query an output method, use 
-.PN XGetOMValues .
-.IN "XGetOMValues" "" "@DEF@"
-.sM
-.FD 0
-char * XGetOMValues\^(\^\fIom\fP\^, ...)
-.br
-      XOM \fIom\fP\^; 
-.FN
-.IP \fIom\fP 1i
-Specifies the output method.
-.ds Al \ to get XOM values
-.IP ... 1i
-Specifies the variable-length argument list\*(Al.
-.LP
-.eM
-The
-.PN XGetOMValues
-function presents a variable argument list programming interface
-for querying properties or features of the specified output method.
-This function returns NULL if it succeeds;
-otherwise,
-it returns the name of the first argument that could not be obtained.
-.LP
-To obtain the display associated with an output method, use
-.PN XDisplayOfOM .
-.IN "XDisplayOfOM" "" "@DEF@"
-.sM
-.FD 0
-Display * XDisplayOfOM\^(\^\fIom\fP\^)
-.br
-	XOM \fIom\fP\^;
-.FN
-.IP \fIom\fP 1i
-Specifies the output method.
-.LP
-.eM
-The
-.PN XDisplayOfOM
-function returns the display associated with the specified output method.
-.LP
-.sp
-To get the locale associated with an output method, use
-.PN XLocaleOfOM .
-.IN "XLocaleOfOM" "" "@DEF@"
-.sM
-.FD 0
-char * XLocaleOfOM\^(\^\fIom\fP\^)
-.br
-      XOM \fIom\fP\^; 
-.FN
-.IP \fIom\fP 1i
-Specifies the output method.
-.LP
-.eM
-The
-.PN XLocaleOfOM
-returns the locale associated with the specified output method.
-.NH 3
-X Output Method Values
-.XS
-\*(SN X Output Method Values
-.XE
-.LP
-The following table describes how XOM values are interpreted by an
-output method.
-The first column lists the XOM values.  The second column indicates
-how each of the XOM values are treated by a particular output style.
-.LP
-.LP
-The following key applies to this table.
-.TS H
-lw(1i) lw(4.75i).
-_
-.sp 6p
-.B
-Key	Explanation
-.sp 6p
-_
-.sp 6p
-.TH
-.R
-G	T{
-This value may be read using 
-.PN XGetOMValues .
-T}
-.sp 6p
-_
-.TE
-.LP
-.TS H
-lw(2.25i) c
-lw(2.25i) c.
-_
-.sp 6p
-.B
-XOM Value	Key
-.sp 6p
-_
-.sp 6p
-.TH
-.R
-T{
-.PN XNRequiredCharSet
-T}	T{
-G
-T}
-T{
-.PN XNQueryOrientation
-T}	T{
-G
-T}
-T{
-.PN XNDirectionalDependentDrawing
-T}	T{
-G
-T}
-T{
-.PN XNContextualDrawing
-T}	T{
-G
-T}
-.sp 6p
-_
-.TE
-.LP
-.NH 4
-Required Char Set
-.XS
-\*(SN Required Char Set
-.XE
-.LP
-The
-.PN XNRequiredCharSet
-argument returns the list of charsets that are required for loading the fonts
-needed for the locale.
-The value of the argument is a pointer to a structure of type
-.PN XOMCharSetList .
-.LP
-The
-.PN XOMCharSetList
-structure is defined as follows:
-.IN "XOMCharSetList" "" "@DEF@"
-.sM
-.LP
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	int charset_count;
-	char **charset_list;
-} XOMCharSetList;
-.De
-.LP
-.eM
-The charset_list member is a list of one or more null-terminated
-charset names, and the charset_count member is the number of
-charset names.
-.LP
-The required charset list is owned by Xlib and should not be modified or
-freed by the client.
-It will be freed by a call to 
-.PN XCloseOM
-with the associated 
-.PN XOM .
-Until freed, its contents will not be modified by Xlib.
-.LP
-.NH 4
-Query Orientation
-.XS
-\*(SN Query Orientation
-.XE
-.LP
-The
-.PN XNQueryOrientation
-argument returns the global orientation of text when drawn.
-Other than
-.PN XOMOrientation_LTR_TTB ,
-the set of orientations supported is locale-dependent.
-The value of the argument is a pointer to a structure of type
-.PN XOMOrientation .
-Clients are responsible for freeing the
-.PN XOMOrientation
-structure by using
-.PN XFree ;
-this also frees the contents of the structure.
-.LP
-.sM
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	int num_orientation;
-	XOrientation *orientation;	/* Input Text description */
-} XOMOrientation;
-
-typedef enum {
-	XOMOrientation_LTR_TTB,
-	XOMOrientation_RTL_TTB,	
-	XOMOrientation_TTB_LTR,
-	XOMOrientation_TTB_RTL,
-	XOMOrientation_Context
-} XOrientation;
-.De
-.LP
-.eM
-The possible value for XOrientation may be:
-.IP \(bu 5
-.PN XOMOrientation_LTR_TTB  
-left-to-right, top-to-bottom global orientation
-.IP \(bu 5
-.PN XOMOrientation_RTL_TTB  
-right-to-left, top-to-bottom global orientation
-.IP \(bu 5
-.PN XOMOrientation_TTB_LTR  
-top-to-bottom, left-to-right global orientation
-.IP \(bu 5
-.PN XOMOrientation_TTB_RTL  
-top-to-bottom, right-to-left global orientation
-.IP \(bu 5
-.PN XOMOrientation_Context  
-contextual global orientation
-.LP
-.NH 4
-Directional Dependent Drawing
-.XS
-\*(SN Directional Dependent Drawing
-.XE
-.LP
-The
-.PN XNDirectionalDependentDrawing
-argument indicates whether the text rendering functions
-implement implicit handling of directional text.  If this value
-is
-.PN True ,
-the output method has knowledge of directional
-dependencies and reorders text as necessary when
-rendering text.  If this value is
-.PN False ,
-the output method does not implement any directional text
-handling, and all character directions are assumed to be left-to-right.
-.LP
-Regardless of the rendering order of characters,
-the origins of all characters are on the primary draw direction side
-of the drawing origin.
-.LP
-This OM value presents functionality identical to the
-.PN XDirectionalDependentDrawing
-function.
-.NH 4
-Context Dependent Drawing
-.XS
-\*(SN Context Dependent Drawing
-.XE
-.LP
-The
-.PN XNContextualDrawing
-argument indicates whether the text rendering functions
-implement implicit context-dependent drawing.  If this value is
-.PN True ,
-the output method has knowledge of context dependencies and
-performs character shape editing, combining glyphs to present
-a single character as necessary.  The actual shape editing is
-dependent on the locale implementation and the font set used.
-.LP
-This OM value presents functionality identical to the
-.PN XContextualDrawing
-function.
-.NH 3
-Output Context Functions
-.XS
-\*(SN Output Context Functions
-.XE
-.LP
-An output context is an abstraction that contains both the data
-required by an output method and the information required
-to display that data.
-There can be multiple output contexts for one output method.
-The programming interfaces for creating, reading, or modifying
-an output context use a variable argument list.
-The name elements of the argument lists are referred to as XOC values.
-It is intended that output methods be controlled by these XOC values.
-As new XOC values are created,
-they should be registered with the X Consortium.
-An
-.PN XOC
-can be used anywhere an
-.PN XFontSet
-can be used, and vice versa;
-.PN XFontSet
-is retained for compatibility with previous releases.
-The concepts of output methods and output contexts include broader,
-more generalized abstraction than font set,
-supporting complex and more intelligent text display, and dealing not only
-with multiple fonts but also with context dependencies.
-However,
-.PN XFontSet
-is widely used in several interfaces, so
-.PN XOC
-is defined as an upward compatible type of
-.PN XFontSet .
-.LP
-.sp
-To create an output context, use
-.PN XCreateOC .
-.IN "XCreateOC" "" "@DEF@"
-.sM
-.FD 0
-XOC XCreateOC\^(\^\fIom\fP\^, ...)
-.br
-      XOM \fIom\fP\^;
-.FN
-.IP \fIom\fP 1i
-Specifies the output method.
-.ds Al \ to set XOC values
-.IP ... 1i
-Specifies the variable-length argument list\*(Al.
-.LP
-.eM
-The
-.PN XCreateOC 
-function creates an output context within the specified output method.
-.LP
-The base font names argument is mandatory at creation time, and
-the output context will not be created unless it is provided.
-All other output context values can be set later.
-.LP
-.PN XCreateOC
-returns NULL if no output context could be created.
-NULL can be returned for any of the following reasons:
-.IP \(bu 5
-A required argument was not set.
-.IP \(bu 5
-A read-only argument was set.
-.IP \(bu 5
-An argument name is not recognized.
-.IP \(bu 5
-The output method encountered an output method implementation-dependent error.
-.LP
-.PN XCreateOC
-can generate a
-.PN BadAtom
-error.
-.LP
-.sp
-To destroy an output context, use
-.PN XDestroyOC .
-.IN "XDestroyOC" "" "@DEF@"
-.sM
-.FD 0
-void XDestroyOC\^(\^\fIoc\fP\^)
-.br
-      XOC \fIoc\fP\^;
-.FN
-.IP \fIoc\fP 1i
-Specifies the output context.
-.LP
-.eM
-The
-.PN XDestroyOC
-function destroys the specified output context.
-.LP
-.sp
-To get the output method associated with an output context, use
-.PN XOMOfOC .
-.IN "XOMOfOC" "" "@DEF@"
-.sM
-.FD 0
-XOM XOMOfOC\^(\^\fIoc\fP\^)
-.br
-      XOC \fIoc\fP\^; 
-.FN
-.IP \fIoc\fP 1i
-Specifies the output context.
-.LP
-.eM
-The
-.PN XOMOfOC
-function returns the output method associated with the
-specified output context.
-.LP
-.sp
-Xlib provides two functions for setting and reading output context values,
-respectively,
-.PN XSetOCValues
-and
-.PN XGetOCValues .
-Both functions have a variable-length argument list.
-In that argument list, any XOC value's name must be denoted
-with a character string using the X Portable Character Set.
-.LP
-.sp
-To set XOC values, use
-.PN XSetOCValues .
-.IN "XSetOCValues" "" "@DEF@"
-.sM
-.FD 0
-char * XSetOCValues\^(\^\fIoc\fP\^, ...)
-.br
-      XOC \fIoc\fP\^;
-.FN
-.IP \fIoc\fP 1i
-Specifies the output context.
-.ds Al \ to set XOC values
-.IP ... 1i
-Specifies the variable-length argument list\*(Al.
-.LP
-.eM
-The
-.PN XSetOCValues
-function returns NULL if no error occurred; 
-otherwise,
-it returns the name of the first argument that could not be set.
-An argument might not be set for any of the following reasons:
-.IP \(bu 5
-The argument is read-only.
-.IP \(bu 5
-The argument name is not recognized.
-.IP \(bu 5
-An implementation-dependent error occurs.
-.LP
-Each value to be set must be an appropriate datum,
-matching the data type imposed by the semantics of the argument.
-.LP
-.PN XSetOCValues
-can generate a
-.PN BadAtom 
-error.
-.LP
-.sp
-To obtain XOC values, use
-.PN XGetOCValues .
-.IN "XGetOCValues" "" "@DEF@"
-.sM
-.FD 0
-char * XGetOCValues\^(\^\fIoc\fP\^, ...)
-.br
-      XOC \fIoc\fP\^;
-.FN
-.IP \fIoc\fP 1i
-Specifies the output context.
-.ds Al \ to get XOC values
-.IP ... 1i
-Specifies the variable-length argument list\*(Al.
-.LP
-.eM
-The
-.PN XGetOCValues
-function returns NULL if no error occurred; otherwise,
-it returns the name of the first argument that could not be obtained.
-An argument might not be obtained for any of the following reasons:
-.IP \(bu 5
-The argument name is not recognized.
-.IP \(bu 5
-An implementation-dependent error occurs.
-.LP
-Each argument value
-following a name must point to a location where the value is to be stored.
-.NH 3 
-Output Context Values
-.XS
-\*(SN Output Context Values
-.XE
-.LP
-The following table describes how XOC values are interpreted
-by an output method.
-The first column lists the XOC values.
-The second column indicates the alternative interfaces that function
-identically and are provided for compatibility with previous releases.
-The third column indicates how each of the XOC values is treated.
-.LP
-The following keys apply to this table.
-.TS H
-lw(1i) lw(4.75i).
-_
-.sp 6p
-.B
-Key	Explanation
-.sp 6p
-_
-.TH
-.R
-C	T{
-This value must be set with
-.PN XCreateOC .
-T}
-D	T{
-This value may be set using 
-.PN XCreateOC .
-If it is not set,
-.br
-a default is provided.
-T}
-G	T{
-This value may be read using 
-.PN XGetOCValues .
-T}
-S	T{
-This value must be set using
-.PN XSetOCValues .
-T}
-.sp 6p
-_
-.TE
-.LP
-.TS H
-l c c
-l c c.
-_
-.sp 6p
-.B
-XOC Value	Alternative Interface	Key
-.sp 6p
-_
-.sp 6p
-.TH
-.R
-T{
-BaseFontName
-T}	T{
-.PN XCreateFontSet
-T}	T{
-C-G
-T}
-T{
-MissingCharSet
-T}	T{
-.PN XCreateFontSet
-T}	T{
-G
-T}
-T{
-DefaultString
-T}	T{
-.PN XCreateFontSet
-T}	T{
-G
-T}
-T{
-Orientation
-T}	T{
-\-
-T}	T{
-D-S-G
-T}
-T{
-ResourceName
-T}	T{
-\-
-T}	T{
-S-G
-T}
-T{
-ResourceClass
-T}	T{
-\-
-T}	T{
-S-G
-T}
-T{
-FontInfo
-T}	T{
-.PN XFontsOfFontSet
-T}	T{
-G
-T}
-T{
-OMAutomatic
-T}	T{
-\-
-T}	T{
-G
-T}
-.sp 6p
-_
-.TE
-.LP
-.NH 4
-Base Font Name
-.XS
-\*(SN Base Font Name
-.XE
-.LP
-The
-.PN XNBaseFontName
-argument is a list of base font names that Xlib uses
-to load the fonts needed for the locale.
-The base font names are a comma-separated list.  The string is null-terminated
-and is assumed to be in the Host Portable Character Encoding;
-otherwise, the result is implementation-dependent.
-White space immediately on either side of a separating comma is ignored.
-.LP
-Use of XLFD font names permits Xlib to obtain the fonts needed for a
-variety of locales from a single locale-independent base font name.
-The single base font name should name a family of fonts whose members
-are encoded in the various charsets needed by the locales of interest.
-.LP
-An XLFD base font name can explicitly name a charset needed for the locale.
-This allows the user to specify an exact font for use with a charset required
-by a locale, fully controlling the font selection.
-.LP
-If a base font name is not an XLFD name,
-Xlib will attempt to obtain an XLFD name from the font properties
-for the font.
-If Xlib is successful, the
-.PN XGetOCValues
-function will return this XLFD name instead of the client-supplied name.
-.LP
-This argument must be set at creation time
-and cannot be changed.
-If no fonts exist for any of the required charsets,
-or if the locale definition in Xlib requires that a font exist
-for a particular charset and a font is not found for that charset,
-.PN XCreateOC
-returns NULL.
-.LP
-When querying for the
-.PN XNBaseFontName
-XOC value,
-.PN XGetOCValues
-returns a null-terminated string identifying the base font names that
-Xlib used to load the fonts needed for the locale.
-This string is owned by Xlib and should not be modified or freed by
-the client.
-The string will be freed by a call to
-.PN XDestroyOC
-with the associated
-.PN XOC .
-Until freed, the string contents will not be modified by Xlib.
-.NH 4
-Missing CharSet
-.XS
-\*(SN Missing CharSet
-.XE
-.LP
-The
-.PN XNMissingCharSet
-argument returns the list of required charsets that are missing from the
-font set.
-The value of the argument is a pointer to a structure of type
-.PN XOMCharSetList .
-.LP
-If fonts exist for all of the charsets required by the current locale,
-charset_list is set to NULL and charset_count is set to zero.
-If no fonts exist for one or more of the required charsets,
-charset_list is set to a list of one or more null-terminated charset names
-for which no fonts exist, and charset_count is set to the number of
-missing charsets.
-The charsets are from the list of the required charsets for
-the encoding of the locale and do not include any charsets to which Xlib
-may be able to remap a required charset.
-.LP
-The missing charset list is owned by Xlib and should not be modified or
-freed by the client.
-It will be freed by a call to 
-.PN XDestroyOC
-with the associated
-.PN XOC .
-Until freed, its contents will not be modified by Xlib.
-.NH 4
-Default String
-.XS
-\*(SN Default String
-.XE
-.LP
-When a drawing or measuring function is called with an
-.PN XOC
-that has missing charsets, some characters in the locale will not be
-drawable.
-The
-.PN XNDefaultString
-argument returns a pointer to a string that represents the glyphs
-that are drawn with this
-.PN XOC
-when the charsets of the available fonts do not include all glyphs
-required to draw a character.
-The string does not necessarily consist of valid characters
-in the current locale and is not necessarily drawn with
-the fonts loaded for the font set,
-but the client can draw or measure the default glyphs
-by including this string in a string being drawn or measured with the
-.PN XOC .
-.LP
-If the
-.PN XNDefaultString
-argument returned the empty string ("\^"),
-no glyphs are drawn and the escapement is zero.
-The returned string is null-terminated.
-It is owned by Xlib and should not be modified or freed by the client.
-It will be freed by a call to
-.PN XDestroyOC
-with the associated
-.PN XOC .
-Until freed, its contents will not be modified by Xlib.
-.NH 4
-Orientation
-.XS
-\*(SN Orientation
-.XE
-.LP
-The
-.PN XNOrientation
-argument specifies the current orientation of text when drawn.  The value of
-this argument is one of the values returned by the
-.PN XGetOMValues
-function with the
-.PN XNQueryOrientation
-argument specified in the
-.PN XOrientation
-list.
-The value of the argument is of type
-.PN XOrientation .
-When
-.PN XNOrientation
-is queried, the value specifies the current orientation.  
-When
-.PN XNOrientation
-is set, a value is used to set the current orientation.
-.LP
-When 
-.PN XOMOrientation_Context
-is set, the text orientation of the 
-text is determined according to an implementation-defined method
-(for example, ISO 6429 control sequences), and the initial text orientation for
-locale-dependent Xlib functions is assumed to 
-be
-.PN XOMOrientation_LTR_TTB .
-.LP
-The
-.PN XNOrientation
-value does not change the prime drawing direction 
-for Xlib drawing functions.  
-.NH 4
-Resource Name and Class
-.XS
-\*(SN Resource Name and Class
-.XE
-.LP
-The
-.PN XNResourceName
-and
-.PN XNResourceClass
-arguments are strings that specify the full name and class
-used by the client to obtain resources for the display of the output context.
-These values should be used as prefixes for name and class
-when looking up resources that may vary according to the output context.
-If these values are not set,
-the resources will not be fully specified.
-.LP
-It is not intended that values that can be set as XOM values be
-set as resources.
-.LP
-When querying for the
-.PN XNResourceName
-or
-.PN XNResourceClass
-XOC value,
-.PN XGetOCValues
-returns a null-terminated string.
-This string is owned by Xlib and should not be modified or freed by
-the client.
-The string will be freed by a call to
-.PN XDestroyOC
-with the associated
-.PN XOC
-or when the associated value is changed via
-.PN XSetOCValues .
-Until freed, the string contents will not be modified by Xlib.
-.NH 4
-Font Info
-.XS
-\*(SN Font Info
-.XE
-.LP
-The
-.PN XNFontInfo
-argument specifies a list of one or more 
-.PN XFontStruct
-structures
-and font names for the fonts used for drawing by the given output context.
-The value of the argument is a pointer to a structure of type
-.PN XOMFontInfo .
-.LP
-.sM
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	int num_font;
-	XFontStruct **font_struct_list;
-	char **font_name_list;
-} XOMFontInfo;
-.De
-.LP
-.eM
-A list of pointers to the
-.PN XFontStruct
-structures is returned to font_struct_list.
-A list of pointers to null-terminated, fully-specified font name strings
-in the locale of the output context is returned to font_name_list.
-The font_name_list order corresponds to the font_struct_list order.
-The number of
-.PN XFontStruct
-structures and font names is returned to num_font.
-.LP
-Because it is not guaranteed that a given character will be imaged using a
-single font glyph,
-there is no provision for mapping a character or default string 
-to the font properties, font ID, or direction hint for the font 
-for the character.
-The client may access the 
-.PN XFontStruct
-list to obtain these values for all the fonts currently in use.
-.LP
-Xlib does not guarantee that fonts are loaded from the server
-at the creation of an 
-.PN XOC .
-Xlib may choose to cache font data, loading it only as needed to draw text 
-or compute text dimensions.
-Therefore, existence of the per_char metrics in the 
-.PN XFontStruct
-structures in the
-.PN XFontStructSet
-is undefined.
-Also, note that all properties in the 
-.PN XFontStruct
-structures are in the STRING encoding.
-.LP
-The client must not free the 
-.PN XOMFontInfo
-struct itself; it will be freed when the
-.PN XOC
-is closed.
-.NH 4
-OM Automatic
-.XS
-\*(SN OM Automatic
-.XE
-.LP
-The
-.PN XNOMAutomatic
-argument returns whether the associated output context was created by
-.PN XCreateFontSet
-or not.  Because the
-.PN XFreeFontSet
-function not only destroys the output context but also closes the implicit
-output method associated with it,
-.PN XFreeFontSet
-should be used with any output context created by 
-.PN XCreateFontSet .
-However, it is possible that a client does not know how the output context
-was created.
-Before a client destroys the output context,
-it can query whether
-.PN XNOMAutomatic
-is set to determine whether 
-.PN XFreeFontSet 
-or 
-.PN XDestroyOC
-should be used to destroy the output context.
-.NH 3
-Creating and Freeing a Font Set
-.XS
-\*(SN Creating and Freeing a Font Set
-.XE
-.LP
-Xlib international text drawing is done using a set of one or more fonts,
-as needed for the locale of the text.
-Fonts are loaded according to a list of base font names 
-supplied by the client and the charsets required by the locale.
-The
-.PN XFontSet
-is an opaque type representing the state of a particular output thread
-and is equivalent to the type
-.PN XOC .
-.LP
-.sp
-The 
-.PN XCreateFontSet
-function is a convenience function for creating an output context using
-only default values.  The returned
-.PN XFontSet
-has an implicitly created
-.PN XOM .
-This
-.PN XOM
-has an OM value
-.PN XNOMAutomatic
-automatically set to
-.PN True
-so that the output context self indicates whether it was created by
-.PN XCreateOC
-or
-.PN XCreateFontSet .
-.IN "XCreateFontSet" "" "@DEF@"
-.sM
-.FD 0
-XFontSet XCreateFontSet\^(\^\fIdisplay\fP\^, \fIbase_font_name_list\fP\^, \fImissing_charset_list_return\fP\^,
-.br
-               \fImissing_charset_count_return\fP\^, \fIdef_string_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      char *\fIbase_font_name_list\fP\^;
-.br
-      char ***\fImissing_charset_list_return\fP\^;
-.br
-      int *\fImissing_charset_count_return\fP\^;
-.br
-      char **\fIdef_string_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIbase_font_name_list\fP 1i
-Specifies the base font names.
-.IP \fImissing_charset_list_return\fP 1i
-Returns the missing charsets.
-.IP \fImissing_charset_count_return\fP 1i
-Returns the number of missing charsets.
-.IP \fIdef_string_return\fP 1i
-Returns the string drawn for missing charsets.
-.LP
-.eM
-The 
-.PN XCreateFontSet
-function creates a font set for the specified display.
-The font set is bound to the current locale when 
-.PN XCreateFontSet
-is called.
-The font set may be used in subsequent calls to obtain font
-and character information and to image text in the locale of the font set.
-.LP
-The base_font_name_list argument is a list of base font names
-that Xlib uses to load the fonts needed for the locale.
-The base font names are a comma-separated list.
-The string is null-terminated
-and is assumed to be in the Host Portable Character Encoding; 
-otherwise, the result is implementation-dependent.
-White space immediately on either side of a separating comma is ignored.
-.LP
-Use of XLFD font names permits Xlib to obtain the fonts needed for a
-variety of locales from a single locale-independent base font name.
-The single base font name should name a family of fonts whose members
-are encoded in the various charsets needed by the locales of interest.
-.LP
-An XLFD base font name can explicitly name a charset needed for the locale.
-This allows the user to specify an exact font for use with a charset required
-by a locale, fully controlling the font selection.
-.LP
-If a base font name is not an XLFD name,
-Xlib will attempt to obtain an XLFD name from the font properties
-for the font.
-If this action is successful in obtaining an XLFD name, the
-.PN XBaseFontNameListOfFontSet
-function will return this XLFD name instead of the client-supplied name.
-.LP
-Xlib uses the following algorithm to select the fonts
-that will be used to display text with the 
-.PN XFontSet .
-.LP
-For each font charset required by the locale,
-the base font name list is searched for the first appearance of one 
-of the following cases that names a set of fonts that exist at the server:
-.IP \(bu 5
-The first XLFD-conforming base font name that specifies the required
-charset or a superset of the required charset in its 
-.PN CharSetRegistry
-and 
-.PN CharSetEncoding
-fields.
-The implementation may use a base font name whose specified charset
-is a superset of the required charset, for example,
-an ISO8859-1 font for an ASCII charset.
-.IP \(bu 5
-The first set of one or more XLFD-conforming base font names
-that specify one or more charsets that can be remapped to support the
-required charset.
-The Xlib implementation may recognize various mappings 
-from a required charset to one or more other charsets
-and use the fonts for those charsets.
-For example, JIS Roman is ASCII with tilde and backslash replaced 
-by yen and overbar;
-Xlib may load an ISO8859-1 font to support this character set
-if a JIS Roman font is not available.
-.IP \(bu 5
-The first XLFD-conforming font name or the first non-XLFD font name
-for which an XLFD font name can be obtained, combined with the
-required charset (replacing the 
-.PN CharSetRegistry
-and
-.PN CharSetEncoding
-fields in the XLFD font name).
-As in case 1,
-the implementation may use a charset that is a superset
-of the required charset.
-.IP \(bu 5
-The first font name that can be mapped in some implementation-dependent
-manner to one or more fonts that support imaging text in the charset.
-.LP
-For example, assume that a locale required the charsets:
-.LP
-.Ds 0
-ISO8859-1
-JISX0208.1983
-JISX0201.1976
-GB2312-1980.0
-.De
-.LP
-The user could supply a base_font_name_list that explicitly specifies the
-charsets, ensuring that specific fonts are used if they exist.
-For example:
-.LP
-.Ds 0
-"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\\
--JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\\
--GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\\
--Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1"
-.De
-.LP
-Alternatively, the user could supply a base_font_name_list
-that omits the charsets,
-letting Xlib select font charsets required for the locale.
-For example:
-.LP
-.Ds 0
-"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\
--JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\\
--GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\
--Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150"
-.De
-.LP
-Alternatively, the user could simply supply a single base font name
-that allows Xlib to select from all available fonts
-that meet certain minimum XLFD property requirements.
-For example:
-.LP
-.Ds 0
-"-*-*-*-R-Normal--*-180-100-100-*-*"
-.De
-.LP
-If 
-.PN XCreateFontSet
-is unable to create the font set, 
-either because there is insufficient memory or because the current locale
-is not supported,
-.PN XCreateFontSet
-returns NULL, missing_charset_list_return is set to NULL,
-and missing_charset_count_return
-is set to zero.
-If fonts exist for all of the charsets required by the current locale,
-.PN XCreateFontSet
-returns a valid
-.PN XFontSet ,
-missing_charset_list_return is set to NULL,
-and missing_charset_count_return is set to zero.
-.LP
-If no font exists for one or more of the required charsets,
-.PN XCreateFontSet
-sets missing_charset_list_return to a
-list of one or more null-terminated charset names for which no font exists
-and sets missing_charset_count_return to the number of missing fonts.
-The charsets are from the list of the required charsets for
-the encoding of the locale and do not include any charsets to which Xlib
-may be able to remap a required charset.
-.LP
-If no font exists for any of the required charsets
-or if the locale definition in Xlib requires that a font exist
-for a particular charset and a font is not found for that charset, 
-.PN XCreateFontSet
-returns NULL.
-Otherwise, 
-.PN XCreateFontSet
-returns a valid 
-.PN XFontSet
-to font_set.
-.LP
-When an Xmb/wc drawing or measuring function is called with an
-.PN XFontSet
-that has missing charsets, some characters in the locale will not be
-drawable.
-If def_string_return is non-NULL,
-.PN XCreateFontSet
-returns a pointer to a string that represents the glyphs
-that are drawn with this 
-.PN XFontSet
-when the charsets of the available fonts do not include all font glyphs
-required to draw a codepoint.
-The string does not necessarily consist of valid characters 
-in the current locale and is not necessarily drawn with
-the fonts loaded for the font set,
-but the client can draw and measure the default glyphs
-by including this string in a string being drawn or measured with the 
-.PN XFontSet .
-.LP
-If the string returned to def_string_return is the empty string ("\^"),
-no glyphs are drawn, and the escapement is zero.
-The returned string is null-terminated.
-It is owned by Xlib and should not be modified or freed by the client.
-It will be freed by a call to 
-.PN XFreeFontSet
-with the associated 
-.PN XFontSet .
-Until freed, its contents will not be modified by Xlib.
-.LP
-The client is responsible for constructing an error message from the
-missing charset and default string information and may choose to continue
-operation in the case that some fonts did not exist.
-.LP
-The returned 
-.PN XFontSet
-and missing charset list should be freed with 
-.PN XFreeFontSet
-and
-.PN XFreeStringList ,
-respectively.
-The client-supplied base_font_name_list may be freed 
-by the client after calling 
-.PN XCreateFontSet .
-.LP
-.sp
-To obtain a list of 
-.PN XFontStruct
-structures and full font names given an 
-.PN XFontSet ,
-use
-.PN XFontsOfFontSet .
-.IN "XFontsOfFontSet" "" "@DEF@"
-.sM
-.FD 0
-int XFontsOfFontSet\^(\^\fIfont_set\fP\^, \fIfont_struct_list_return\fP\^, \fIfont_name_list_return\fP\^)
-.br
-       XFontSet \fIfont_set\fP\^;
-.br
-       XFontStruct ***\fIfont_struct_list_return\fP\^;
-.br
-       char ***\fIfont_name_list_return\fP\^;
-.FN
-.IP \fIfont_set\fP 1i
-Specifies the font set.
-.IP \fIfont_struct_list_return\fP 1i
-Returns the list of font structs.
-.IP \fIfont_name_list_return\fP 1i
-Returns the list of font names.
-.LP
-.eM
-The
-.PN XFontsOfFontSet
-function returns a list of one or more 
-.PN XFontStructs
-and font names for the fonts used by the Xmb and Xwc layers
-for the given font set.
-A list of pointers to the
-.PN XFontStruct
-structures is returned to font_struct_list_return.
-A list of pointers to null-terminated, fully specified font name strings
-in the locale of the font set is returned to font_name_list_return.
-The font_name_list order corresponds to the font_struct_list order.
-The number of
-.PN XFontStruct
-structures and font names is returned as the value of the function.
-.LP
-Because it is not guaranteed that a given character will be imaged using a
-single font glyph,
-there is no provision for mapping a character or default string 
-to the font properties, font ID, or direction hint for the font 
-for the character.
-The client may access the 
-.PN XFontStruct
-list to obtain these values for all the fonts currently in use.
-.LP
-Xlib does not guarantee that fonts are loaded from the server
-at the creation of an 
-.PN XFontSet .
-Xlib may choose to cache font data, loading it only as needed to draw text 
-or compute text dimensions.
-Therefore, existence of the per_char metrics in the 
-.PN XFontStruct
-structures in the
-.PN XFontStructSet
-is undefined.
-Also, note that all properties in the 
-.PN XFontStruct
-structures are in the STRING encoding.
-.LP
-The 
-.PN XFontStruct
-and font name lists are owned by Xlib 
-and should not be modified or freed by the client.
-They will be freed by a call to
-.PN XFreeFontSet
-with the associated
-.PN XFontSet .
-Until freed, their contents will not be modified by Xlib.
-.LP
-.sp
-To obtain the base font name list and the selected font name list given an
-.PN XFontSet ,
-use
-.PN XBaseFontNameListOfFontSet .
-.IN "XBaseFontNameListOfFontSet" "" "@DEF@"
-.sM
-.FD 0
-char *XBaseFontNameListOfFontSet\^(\^\fIfont_set\fP\^)
-.br
-      XFontSet \fIfont_set\fP\^;
-.FN
-.IP \fIfont_set\fP 1i
-Specifies the font set.
-.LP
-.eM
-The
-.PN XBaseFontNameListOfFontSet
-function returns the original base font name list supplied
-by the client when the 
-.PN XFontSet
-was created.
-A null-terminated string containing a list of
-comma-separated font names is returned
-as the value of the function.
-White space may appear immediately on either side of separating commas.
-.LP
-If 
-.PN XCreateFontSet
-obtained an XLFD name from the font properties for the font specified
-by a non-XLFD base name, the
-.PN XBaseFontNameListOfFontSet
-function will return the XLFD name instead of the non-XLFD base name.
-.LP
-The base font name list is owned by Xlib and should not be modified or
-freed by the client.
-It will be freed by a call to 
-.PN XFreeFontSet
-with the associated 
-.PN XFontSet .
-Until freed, its contents will not be modified by Xlib.
-.LP
-.sp
-To obtain the locale name given an 
-.PN XFontSet ,
-use
-.PN XLocaleOfFontSet .
-.IN "XLocaleOfFontSet" "" "@DEF@"
-.sM
-.FD 0
-char *XLocaleOfFontSet\^(\^\fIfont_set\fP\^)
-.br
-      XFontSet \fIfont_set\fP\^;
-.FN
-.IP \fIfont_set\fP 1i
-Specifies the font set.
-.LP
-.eM
-The
-.PN XLocaleOfFontSet
-function
-returns the name of the locale bound to the specified
-.PN XFontSet ,
-as a null-terminated string.
-.LP
-The returned locale name string is owned by Xlib
-and should not be modified or freed by the client.
-It may be freed by a call to
-.PN XFreeFontSet
-with the associated 
-.PN XFontSet .
-Until freed, it will not be modified by Xlib.
-.LP
-.sp
-The 
-.PN XFreeFontSet
-function is a convenience function for freeing an output context.
-.PN XFreeFontSet 
-also frees its associated 
-.PN XOM
-if the output context was created by
-.PN XCreateFontSet .
-.IN "XFreeFontSet" "" "@DEF@"
-.sM
-.FD 0
-void XFreeFontSet\^(\^\fIdisplay\fP\^, \fIfont_set\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XFontSet \fIfont_set\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIfont_set\fP 1i
-Specifies the font set.
-.LP
-.eM
-The
-.PN XFreeFontSet
-function frees the specified font set.
-The associated base font name list, font name list, 
-.PN XFontStruct
-list, and 
-.PN XFontSetExtents , 
-if any, are freed.
-.NH 3
-Obtaining Font Set Metrics
-.XS
-\*(SN Obtaining Font Set Metrics
-.XE
-.LP
-Metrics for the internationalized text drawing functions 
-are defined in terms of a primary draw direction, 
-which is the default direction in which the character origin advances
-for each succeeding character in the string.
-The Xlib interface is currently defined to support only a left-to-right
-primary draw direction.
-The drawing origin is the position passed to the drawing function 
-when the text is drawn.
-The baseline is a line drawn through the drawing origin parallel
-to the primary draw direction.
-Character ink is the pixels painted in the foreground color 
-and does not include interline or intercharacter spacing 
-or image text background pixels.
-.LP
-The drawing functions are allowed to implement implicit text
-directionality control, reversing the order in which characters are
-rendered along the primary draw direction in response to locale-specific
-lexical analysis of the string.
-.LP
-Regardless of the character rendering order,
-the origins of all characters are on the primary draw direction side
-of the drawing origin.
-The screen location of a particular character image may be determined with
-.PN XmbTextPerCharExtents
-or
-.PN XwcTextPerCharExtents .
-.LP
-The drawing functions are allowed to implement context-dependent
-rendering, where the glyphs drawn for a string are not simply a
-concatenation of the glyphs that represent each individual character.
-A string of two characters drawn with 
-.PN XmbDrawString
-may render differently than if the two characters 
-were drawn with separate calls to
-.PN XmbDrawString .
-If the client appends or inserts a character 
-in a previously drawn string,
-the client may need to redraw some adjacent characters 
-to obtain proper rendering.
-.LP
-.sp
-To find out about direction-dependent rendering, use
-.PN XDirectionalDependentDrawing .
-.IN "XDirectionalDependentDrawing" "" "@DEF@"
-.sM
-.FD 0
-Bool XDirectionalDependentDrawing\^(\^\fIfont_set\fP\^)
-.br
-      XFontSet \fIfont_set\fP\^;
-.FN
-.IP \fIfont_set\fP 1i
-Specifies the font set.
-.LP
-.eM
-The
-.PN XDirectionalDependentDrawing
-function returns
-.PN True
-if the drawing functions implement implicit text directionality;
-otherwise, it returns
-.PN False .
-.LP
-.sp
-To find out about context-dependent rendering, use
-.PN XContextualDrawing .
-.IN "XContextualDrawing" "" "@DEF@"
-.sM
-.FD 0
-Bool XContextualDrawing\^(\^\fIfont_set\fP\^)
-.br
-      XFontSet \fIfont_set\fP\^;
-.FN
-.IP \fIfont_set\fP 1i
-Specifies the font set.
-.LP
-.eM
-The
-.PN XContextualDrawing
-function returns
-.PN True
-if text drawn with the font set might include context-dependent drawing;
-otherwise, it returns
-.PN False .
-.LP
-.sp
-To find out about context-dependent or direction-dependent rendering, use
-.PN XContextDependentDrawing .
-.IN "XContextDependentDrawing" "" "@DEF@"
-.sM
-.FD 0
-Bool XContextDependentDrawing\^(\^\fIfont_set\fP\^)
-.br
-      XFontSet \fIfont_set\fP\^;
-.FN
-.IP \fIfont_set\fP 1i
-Specifies the font set.
-.LP
-.eM
-The
-.PN XContextDependentDrawing
-function returns
-.PN True
-if the drawing functions implement implicit text directionality or
-if text drawn with the font_set might include context-dependent drawing;
-otherwise, it returns
-.PN False .
-.LP
-The drawing functions do not interpret newline, tab, or other control
-characters.
-The behavior when nonprinting characters other than space are drawn
-is implementation-dependent.
-It is the client's responsibility to interpret control characters
-in a text stream.
-.LP
-The maximum character extents for the fonts that are used by the text
-drawing layers can be accessed by the 
-.PN XFontSetExtents
-structure:
-.IN "XFontSetExtents" "" "@DEF@"
-.LP
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	XRectangle max_ink_extent;	/* over all drawable characters */
-	XRectangle max_logical_extent;	/* over all drawable characters */
-} XFontSetExtents;
-.De
-.LP
-The 
-.PN XRectangle
-structures used to return font set metrics are the usual Xlib screen-oriented 
-rectangles
-with x, y giving the upper left corner, and width and height always positive.
-.LP
-The max_ink_extent member gives the maximum extent, over all drawable characters, of
-the rectangles that bound the character glyph image drawn in the
-foreground color, relative to a constant origin.
-See 
-.PN XmbTextExtents
-and
-.PN XwcTextExtents
-for detailed semantics.
-.LP
-The max_logical_extent member gives the maximum extent,
-over all drawable characters, of the rectangles 
-that specify minimum spacing to other graphical features,
-relative to a constant origin.
-Other graphical features drawn by the client, for example,
-a border surrounding the text, should not intersect this rectangle.
-The max_logical_extent member should be used to compute minimum 
-interline spacing and the minimum area that must be allowed
-in a text field to draw a given number of arbitrary characters.
-.LP
-Due to context-dependent rendering,
-appending a given character to a string may change 
-the string's extent by an amount other than that character's
-individual extent.
-.LP
-The rectangles for a given character in a string can be obtained from
-.PN XmbPerCharExtents
-or
-.PN XwcPerCharExtents .
-.LP
-.sp
-To obtain the maximum extents structure given an
-.PN XFontSet ,
-use
-.PN XExtentsOfFontSet .
-.IN "XExtentsOfFontSet" "" "@DEF@"
-.sM
-.FD 0
-XFontSetExtents *XExtentsOfFontSet\^(\^\fIfont_set\fP\^)
-.br
-       XFontSet \fIfont_set\fP\^;
-.FN
-.IP \fIfont_set\fP 1i
-Specifies the font set.
-.LP
-.eM
-The
-.PN XExtentsOfFontSet
-function returns an
-.PN XFontSetExtents
-structure for the fonts used by the Xmb and Xwc layers
-for the given font set.
-.LP
-The 
-.PN XFontSetExtents
-structure is owned by Xlib and should not be modified
-or freed by the client.
-It will be freed by a call to 
-.PN XFreeFontSet
-with the associated 
-.PN XFontSet .
-Until freed, its contents will not be modified by Xlib.
-.LP
-.sp
-To obtain the escapement in pixels of the specified text as a value,
-use
-.PN XmbTextEscapement
-or 
-.PN XwcTextEscapement .
-.IN "XmbTextEscapement" "" "@DEF@"
-.IN "XwcTextEscapement" "" "@DEF@"
-.sM
-.FD 0
-int XmbTextEscapement\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^)
-.br
-      XFontSet \fIfont_set\fP\^;
-.br
-      char *\fIstring\fP\^;
-.br
-      int \fInum_bytes\fP\^;
-.FN
-.FD 0
-int XwcTextEscapement\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^)
-.br
-      XFontSet \fIfont_set\fP\^;
-.br
-      wchar_t *\fIstring\fP\^;
-.br
-      int \fInum_wchars\fP\^;
-.FN
-.IP \fIfont_set\fP 1i
-Specifies the font set.
-.IP \fIstring\fP 1i
-Specifies the character string.
-.IP \fInum_bytes\fP 1i
-Specifies the number of bytes in the string argument.
-.IP \fInum_wchars\fP 1i
-Specifies the number of characters in the string argument.
-.LP
-.eM
-The
-.PN XmbTextEscapement
-and
-.PN XwcTextEscapement
-functions return the escapement in pixels of the specified string as a value,
-using the fonts loaded for the specified font set.
-The escapement is the distance in pixels in the primary draw
-direction from the drawing origin to the origin of the next character to
-be drawn, assuming that the rendering of the next character is not
-dependent on the supplied string.
-.LP
-Regardless of the character rendering order,
-the escapement is always positive.
-.LP
-.sp
-To obtain the overall_ink_return and overall_logical_return arguments,
-the overall bounding box of the string's image, and a logical bounding box,
-use
-.PN XmbTextExtents
- or
-.PN XwcTextExtents .
-.IN "XmbTextExtents" "" "@DEF@"
-.IN "XwcTextExtents" "" "@DEF@"
-.sM
-.FD 0
-int XmbTextExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^, \fIoverall_ink_return\fP\^, \fIoverall_logical_return\fP\^)
-.br
-      XFontSet \fIfont_set\fP\^;
-.br
-      char *\fIstring\fP\^;
-.br
-      int \fInum_bytes\fP\^;
-.br
-      XRectangle *\fIoverall_ink_return\fP\^;
-.br
-      XRectangle *\fIoverall_logical_return\fP\^;
-.FN
-.FD 0
-int XwcTextExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^, 
-\fIoverall_ink_return\fP\^, \fIoverall_logical_return\fP\^)
-.br
-      XFontSet \fIfont_set\fP\^;
-.br
-      wchar_t *\fIstring\fP\^;
-.br
-      int \fInum_wchars\fP\^;
-.br
-      XRectangle *\fIoverall_ink_return\fP\^;
-.br
-      XRectangle *\fIoverall_logical_return\fP\^;
-.FN
-.IP \fIfont_set\fP 1i
-Specifies the font set.
-.IP \fIstring\fP 1i
-Specifies the character string.
-.IP \fInum_bytes\fP 1i
-Specifies the number of bytes in the string argument.
-.IP \fInum_wchars\fP 1i
-Specifies the number of characters in the string argument.
-.ds Ov dimensions
-.IP \fIoverall_ink_return\fP 1i
-Returns the overall ink \*(Ov.
-.IP \fIoverall_logical_return\fP 1i
-Returns the overall logical \*(Ov.
-.LP
-.eM
-The
-.PN XmbTextExtents
-and
-.PN XwcTextExtents
-functions set the components of the specified overall_ink_return and
-overall_logical_return
-arguments to the overall bounding box of the string's image
-and a logical bounding box for spacing purposes, respectively.
-They return the value returned by 
-.PN XmbTextEscapement
-or
-.PN XwcTextEscapement .
-These metrics are relative to the drawing origin of the string,
-using the fonts loaded for the specified font set.
-.LP
-If the overall_ink_return argument is non-NULL,
-it is set to the bounding box of the string's character ink.
-The overall_ink_return for a nondescending, horizontally drawn
-Latin character is conventionally entirely above the baseline;
-that is, overall_ink_return.height <= \-overall_ink_return.y.
-The overall_ink_return for a nonkerned character
-is entirely at, and to the right of, the origin;
-that is, overall_ink_return.x >= 0.
-A character consisting of a single pixel at the origin would set
-overall_ink_return fields y = 0, x = 0, width = 1, and height = 1.
-.LP
-If the overall_logical_return argument is non-NULL,
-it is set to the bounding box that provides minimum spacing
-to other graphical features for the string.
-Other graphical features, for example, a border surrounding the text,
-should not intersect this rectangle.
-.LP
-When the 
-.PN XFontSet
-has missing charsets,
-metrics for each unavailable character are taken 
-from the default string returned by 
-.PN XCreateFontSet 
-so that the metrics represent the text as it will actually be drawn.
-The behavior for an invalid codepoint is undefined.
-.LP
-To determine the effective drawing origin for a character in a drawn string,
-the client should call 
-.PN XmbTextPerCharExtents
-on the entire string, then on the character,
-and subtract the x values of the returned 
-rectangles for the character.
-This is useful to redraw portions of a line of text
-or to justify words, but for context-dependent rendering,
-the client should not assume that it can redraw the character by itself
-and get the same rendering.
-.LP
-.sp
-To obtain per-character information for a text string,
-use
-.PN XmbTextPerCharExtents
-or
-.PN XwcTextPerCharExtents .
-.IN "XmbTextPerCharExtents" "" "@DEF@"
-.IN "XwcTextPerCharExtents" "" "@DEF@"
-.sM
-.FD 0
-Status XmbTextPerCharExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^, \fIink_array_return\fP\^,
-.br
-           \fIlogical_array_return\fP\^, \fIarray_size\fP\^, \fInum_chars_return\fP\^, \fIoverall_ink_return\fP\^, \fIoverall_logical_return\fP\^)
-.br
-      XFontSet \fIfont_set\fP\^;
-.br
-      char *\fIstring\fP\^;
-.br
-      int \fInum_bytes\fP\^;
-.br
-      XRectangle *\fIink_array_return\fP\^;
-.br
-      XRectangle *\fIlogical_array_return\fP\^;
-.br
-      int \fIarray_size\fP\^;
-.br
-      int *\fInum_chars_return\fP\^;
-.br
-      XRectangle *\fIoverall_ink_return\fP\^;
-.br
-      XRectangle *\fIoverall_logical_return\fP\^;
-.FN
-.FD 0
-Status XwcTextPerCharExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^, \fIink_array_return\fP\^,
-.br
-          \fIlogical_array_return\fP\^, \fIarray_size\fP\^, \fInum_chars_return\fP\^, \fIoverall_ink_return\fP\^, \fIoverall_ink_return\fP\^)
-.br
-      XFontSet \fIfont_set\fP\^;
-.br
-      wchar_t *\fIstring\fP\^;
-.br
-      int \fInum_wchars\fP\^;
-.br
-      XRectangle *\fIink_array_return\fP\^;
-.br
-      XRectangle *\fIlogical_array_return\fP;
-.br
-      int \fIarray_size\fP\^;
-.br
-      int *\fInum_chars_return\fP\^;
-.br
-      XRectangle *\fIoverall_ink_return\fP\^;
-.br
-      XRectangle *\fIoverall_logical_return\fP\^;
-.FN
-.IP \fIfont_set\fP 1i
-Specifies the font set.
-.IP \fIstring\fP 1i
-Specifies the character string.
-.IP \fInum_bytes\fP 1i
-Specifies the number of bytes in the string argument.
-.IP \fInum_wchars\fP 1i
-Specifies the number of characters in the string argument.
-.IP \fIink_array_return\fP 1i
-Returns the ink dimensions for each character.
-.IP \fIlogical_array_return\fP 1i
-Returns the logical dimensions for each character.
-.IP \fIarray_size\fP 1i
-Specifies the size of ink_array_return and logical_array_return.
-The caller must pass in arrays of this size.
-.IP \fInum_chars_return\fP 1i
-Returns the number of characters in the string argument.
-.ds Ov extents of the entire string
-.IP \fIoverall_ink_return\fP 1i
-Returns the overall ink \*(Ov.
-.IP \fIoverall_logical_return\fP 1i
-Returns the overall logical \*(Ov.
-.LP
-.eM
-The
-.PN XmbTextPerCharExtents
-and
-.PN XwcTextPerCharExtents
-functions return the text dimensions of each character of the specified text,
-using the fonts loaded for the specified font set.
-Each successive element of ink_array_return and logical_array_return
-is set to the successive character's drawn metrics,
-relative to the drawing origin of the string and one 
-rectangle
-for each character in the supplied text string.
-The number of elements of ink_array_return and logical_array_return
-that have been set is returned to num_chars_return.
-.LP
-Each element of ink_array_return is set to the bounding box 
-of the corresponding character's drawn foreground color.
-Each element of logical_array_return is set to the bounding box 
-that provides minimum spacing to other graphical features
-for the corresponding character.
-Other graphical features should not intersect any of the
-logical_array_return rectangles.
-.LP
-Note that an 
-.PN XRectangle
-represents the effective drawing dimensions of the character,
-regardless of the number of font glyphs that are used to draw
-the character or the direction in which the character is drawn.
-If multiple characters map to a single character glyph,
-the dimensions of all the 
-.PN XRectangles
-of those characters are the same.
-.LP
-When the 
-.PN XFontSet
-has missing charsets, metrics for each unavailable
-character are taken from the default string returned by 
-.PN XCreateFontSet
-so that the metrics represent the text as it will actually be drawn.
-The behavior for an invalid codepoint is undefined.
-.LP
-If the array_size is too small for the number of characters in the
-supplied text, the functions return zero
-and num_chars_return is set to the number of rectangles required.
-Otherwise, the functions return a nonzero value.
-.LP
-If the overall_ink_return or overall_logical_return argument is non-NULL,
-.PN XmbTextPerCharExtents
-and 
-.PN XwcTextPerCharExtents
-return the maximum extent of the string's metrics to overall_ink_return
-or overall_logical_return, as returned by 
-.PN XmbTextExtents
-or 
-.PN XwcTextExtents .
-.NH 3
-Drawing Text Using Font Sets
-.XS
-\*(SN Drawing Text Using Font Sets
-.XE
-.LP
-The functions defined in this section
-draw text at a specified location in a drawable.
-They are similar to the functions
-.PN XDrawText ,
-.PN XDrawString ,
-and
-.PN XDrawImageString
-except that they work with font sets instead of single fonts
-and interpret the text based on the locale of the font set
-instead of treating the bytes of the string as direct font indexes.
-See section 8.6 for details of the use of Graphics Contexts (GCs)
-and possible protocol errors.
-If a 
-.PN BadFont
-error is generated,
-characters prior to the offending character may have been drawn.
-.LP
-The text is drawn using the fonts loaded for the specified font set;
-the font in the GC is ignored and may be modified by the functions.
-No validation that all fonts conform to some width rule is performed.
-.LP
-The text functions
-.PN XmbDrawText
-and
-.PN XwcDrawText
-use the following structures:
-.LP
-.IN "XmbTextItem" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	char *chars;	/* pointer to string */
-	int nchars;	/* number of bytes */
-	int delta;	/* pixel delta between strings */
-	XFontSet font_set; 	/* fonts, None means don't change */
-} XmbTextItem;
-.De
-.LP
-.IN "XwcTextItem" "" "@DEF@"
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	wchar_t *chars;	/* pointer to wide char string */
-	int nchars;	/* number of wide characters */
-	int delta;	/* pixel delta between strings */
-	XFontSet font_set;	/* fonts, None means don't change */
-} XwcTextItem;
-.De
-.LP
-.eM
-.sp
-To draw text using multiple font sets in a given drawable, use
-.PN XmbDrawText
-or
-.PN XwcDrawText .
-.IN "XmbDrawText" "" "@DEF@"
-.IN "XwcDrawText" "" "@DEF@"
-.sM
-.FD 0
-void XmbDrawText\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.br
-      XmbTextItem *\fIitems\fP\^;
-.br
-      int \fInitems\fP\^;
-.FN
-.FD 0
-void XwcDrawText\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.br
-      XwcTextItem *\fIitems\fP\^;
-.br
-      int \fInitems\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIgc\fP 1i
-Specifies the GC.
-.ds Xy
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.IP \fIitems\fP 1i
-Specifies an array of text items.
-.IP \fInitems\fP 1i
-Specifies the number of text items in the array.
-.LP
-.eM
-The
-.PN XmbDrawText
-and 
-.PN XwcDrawText 
-functions allow complex spacing and font set shifts between text strings.
-Each text item is processed in turn, with the origin of a text
-element advanced in the primary draw direction by the escapement of the
-previous text item.
-A text item delta specifies an additional escapement of the text item
-drawing origin in the primary draw direction.
-A font_set member other than 
-.PN None
-in an item causes the font set to be used for this and subsequent text items
-in the text_items list.
-Leading text items with a font_set member set to
-.PN None
-will not be drawn.
-.LP
-.PN XmbDrawText
-and
-.PN XwcDrawText
-do not perform any context-dependent rendering between text segments.
-Clients may compute the drawing metrics by passing each text segment to
-.PN XmbTextExtents
-and
-.PN XwcTextExtents
-or 
-.PN XmbTextPerCharExtents
-and
-.PN XwcTextPerCharExtents .
-When the 
-.PN XFontSet
-has missing charsets, each unavailable character is drawn 
-with the default string returned by 
-.PN XCreateFontSet .
-The behavior for an invalid codepoint is undefined.
-.LP
-.sp
-To draw text using a single font set in a given drawable, use
-.PN XmbDrawString
-or
-.PN XwcDrawString .
-.IN "XmbDrawString" "" "@DEF@"
-.IN "XwcDrawString" "" "@DEF@"
-.sM
-.FD 0
-void XmbDrawString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      XFontSet \fIfont_set\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.br
-      char *\fIstring\fP\^;
-.br
-      int \fInum_bytes\fP\^;
-.FN
-.FD 0
-void XwcDrawString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      XFontSet \fIfont_set\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.br
-      wchar_t *\fIstring\fP\^;
-.br
-      int \fInum_wchars\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIfont_set\fP 1i
-Specifies the font set.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.ds Xy
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.IP \fIstring\fP 1i
-Specifies the character string.
-.IP \fInum_bytes\fP 1i
-Specifies the number of bytes in the string argument.
-.IP \fInum_wchars\fP 1i
-Specifies the number of characters in the string argument.
-.LP
-.eM
-The
-.PN XmbDrawString
-and
-.PN XwcDrawString
-functions draw the specified text with the foreground pixel.
-When the 
-.PN XFontSet
-has missing charsets, each unavailable character is drawn 
-with the default string returned by 
-.PN XCreateFontSet .
-The behavior for an invalid codepoint is undefined.
-.LP
-.sp
-To draw image text using a single font set in a given drawable, use
-.PN XmbDrawImageString
-or
-.PN XwcDrawImageString .
-.IN "XmbDrawImageString" "" "@DEF@"
-.IN "XwcDrawImageString" "" "@DEF@"
-.sM
-.FD 0
-void XmbDrawImageString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      XFontSet \fIfont_set\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.br
-      char *\fIstring\fP\^;
-.br
-      int \fInum_bytes\fP\^;
-.FN
-.FD 0
-void XwcDrawImageString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      XFontSet \fIfont_set\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.br
-      wchar_t *\fIstring\fP\^;
-.br
-      int \fInum_wchars\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fId\fP 1i
-Specifies the drawable. 
-.IP \fIfont_set\fP 1i
-Specifies the font set.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.ds Xy
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.IP \fIstring\fP 1i
-Specifies the character string.
-.IP \fInum_bytes\fP 1i
-Specifies the number of bytes in the string argument.
-.IP \fInum_wchars\fP 1i
-Specifies the number of characters in the string argument.
-.LP
-.eM
-The
-.PN XmbDrawImageString
-and
-.PN XwcDrawImageString
-functions fill a destination rectangle with the background pixel defined
-in the GC and then paint the text with the foreground pixel.
-The filled rectangle is the rectangle returned to overall_logical_return by
-.PN XmbTextExtents
-or 
-.PN XwcTextExtents
-for the same text and 
-.PN XFontSet .
-.LP
-When the 
-.PN XFontSet
-has missing charsets, each unavailable character is drawn 
-with the default string returned by 
-.PN XCreateFontSet .
-The behavior for an invalid codepoint is undefined.
-.NH 2
-Input Methods
-.XS
-\*(SN Input Methods
-.XE
-.LP
-This section provides discussions of the following X Input Method
-(XIM) topics:
-.IP \(bu 5
-Input method overview
-.IP \(bu 5
-Input method management
-.IP \(bu 5
-Input method functions
-.IP \(bu 5
-Input method values
-.IP \(bu 5
-Input context functions
-.IP \(bu 5
-Input context values
-.IP \(bu 5
-Input method callback semantics
-.IP \(bu 5
-Event filtering
-.IP \(bu 5
-Getting keyboard input
-.IP \(bu 5
-Input method conventions
-.NH 3
-Input Method Overview
-.XS
-\*(SN Input Method Overview
-.XE
-.LP
-This section provides definitions for terms and concepts used
-for internationalized text input and a brief overview of the
-intended use of the mechanisms provided by Xlib.
-.LP
-A large number of languages in the world use alphabets
-consisting of a small set of symbols (letters) to form words.
-To enter text into a computer in an alphabetic language,
-a user usually has a keyboard on which there exist key symbols corresponding
-to the alphabet.
-Sometimes, a few characters of an alphabetic language are missing
-on the keyboard.
-Many computer users who speak a Latin-alphabet-based language 
-only have an English-based keyboard.
-They need to hit a combination of keystrokes
-to enter a character that does not exist directly on the keyboard.
-A number of algorithms have been developed for entering such characters.
-These are known as European input methods, compose input methods, 
-or dead-key input methods.
-.LP
-Japanese is an example of a language with a phonetic symbol set,
-where each symbol represents a specific sound.
-There are two phonetic symbol sets in Japanese:  Katakana and Hiragana.
-In general,
-Katakana is used for words that are of foreign origin,
-and Hiragana is used for writing native Japanese words.
-Collectively, the two systems are called Kana.
-Each set consists of 48 characters.
-.LP
-Korean also has a phonetic symbol set, called Hangul.
-Each of the 24 basic phonetic symbols (14 consonants and 10 vowels)
-represents a specific sound.
-A syllable is composed of two or three parts: 
-the initial consonants, the vowels, and the optional last consonants.
-With Hangul,
-syllables can be treated as the basic units on which text processing is done.
-For example,
-a delete operation may work on a phonetic symbol or a syllable.
-Korean code sets include several thousands of these syllables.
-A user types the phonetic symbols that make up the syllables of the words
-to be entered.
-The display may change as each phonetic symbol is entered.
-For example,
-when the second phonetic symbol of a syllable is entered,
-the first phonetic symbol may change its shape and size.
-Likewise, when the third phonetic symbol is entered,
-the first two phonetic symbols may change their shape and size.
-.LP
-Not all languages rely solely on alphabetic or phonetic systems.
-Some languages, including Japanese and Korean, employ an
-ideographic writing system.
-In an ideographic system, rather than taking a small set of
-symbols and combining them in different ways to create words,
-each word consists of one unique symbol (or, occasionally, several symbols).
-The number of symbols can be very large: 
-approximately 50,000 have been identified in Hanzi,
-the Chinese ideographic system.
-.LP
-Two major aspects of ideographic systems impact their use with computers.
-First, the standard computer character sets in Japan, China, and Korea
-include roughly 8,000 characters,
-while sets in Taiwan have between 15,000 and 30,000 characters.
-This makes it necessary to use more than one byte to represent a character.
-Second, it obviously is impractical to have a keyboard that includes
-all of a given language's ideographic symbols.
-Therefore, a mechanism is required for entering characters
-so that a keyboard with a reasonable number of keys can be used.
-Those input methods are usually based on phonetics,
-but there also exist methods based on the graphical properties of
-characters.
-.LP
-In Japan, both Kana and the ideographic system Kanji are used.
-In Korea, Hangul and sometimes the ideographic system Hanja are used.
-Now consider entering ideographs in Japan, Korea, China, and Taiwan.
-.LP
-In Japan, either Kana or English characters are typed and then a region
-is selected (sometimes automatically) for conversion to Kanji.
-Several Kanji characters may have the same phonetic representation.
-If that is the case with the string entered,
-a menu of characters is presented and
-the user must choose the appropriate one.
-If no choice is necessary or a preference has been established,
-the input method does the substitution directly.
-When Latin characters are converted to Kana or Kanji,
-it is called a romaji conversion.
-.LP
-In Korea, it is usually acceptable to keep Korean text in Hangul form,
-but some people may choose to write Hanja-originated words in Hanja
-rather than in Hangul.
-To change Hangul to Hanja,
-the user selects a region for conversion
-and then follows the same basic method as that described for Japanese.
-.LP
-Probably because there are well-accepted phonetic writing systems
-for Japanese and Korean,
-computer input methods in these countries for entering ideographs 
-are fairly standard.
-Keyboard keys have both English characters and phonetic symbols
-engraved on them, and the user can switch between the two sets.
-.LP
-The situation is different for Chinese.
-While there is a phonetic system called Pinyin promoted by authorities,
-there is no consensus for entering Chinese text.
-Some vendors use a phonetic decomposition (Pinyin or another),
-others use ideographic decomposition of Chinese words,
-with various implementations and keyboard layouts. 
-There are about 16 known methods, none of which is a clear standard. 
-.LP
-Also, there are actually two ideographic sets used:
-Traditional Chinese (the original written Chinese)
-and Simplified Chinese.
-Several years ago,
-the People's Republic of China launched a campaign to simplify
-some ideographic characters and eliminate redundancies altogether.
-Under the plan, 
-characters would be streamlined every five years.
-Characters have been revised several times now, 
-resulting in the smaller, simpler set that makes up Simplified Chinese.
-.NH 4
-Input Method Architecture
-.XS
-\*(SN Input Method Architecture
-.XE
-.LP
-As shown in the previous section,
-there are many different input methods in use today,
-each varying with language, culture, and history. 
-A common feature of many input methods is that the user may type
-multiple keystrokes to compose a single character (or set
-of characters).
-The process of composing characters from keystrokes is called
-\fIpreediting\fP.
-It may require complex algorithms and large dictionaries 
-involving substantial computer resources.
-.LP
-Input methods may require one or more areas in which to show the
-feedback of the actual keystrokes, to propose disambiguation to the
-user, to list dictionaries, and so on.
-The input method areas of concern are as follows:
-.IP \(bu 5
-The \fIstatus\fP area is a logical extension of the
-LEDs that exist on the physical keyboard.
-It is a window that is intended to present the internal state
-of the input method that is critical to the user.
-The status area may consist of text data and bitmaps or some combination.
-.IP \(bu 5
-The \fIpreedit\fP area displays the
-intermediate text for those languages that are composing prior to 
-the client handling the data.   
-.IP \(bu 5
-The \fIauxiliary\fP area is used for pop-up menus and customizing
-dialogs that may be required for an input method.
-There may be multiple auxiliary areas for an input method.
-Auxiliary areas are managed by the input method independent of the client.
-Auxiliary areas are assumed to be separate dialogs,
-which are maintained by the input method.
-.LP
-There are various user interaction styles used for preediting.
-The ones supported by Xlib are as follows:
-.IP \(bu 5
-For \fIon-the-spot\fP input methods,
-preediting data will be displayed directly in the application window.
-Application data is moved to allow preedit data to appear
-at the point of insertion.
-.IP \(bu 5
-\fIOver-the-spot\fP preediting means that the data is displayed in
-a preedit window that is placed over the point of insertion.
-.IP \(bu 5
-\fIOff-the-spot\fP preediting means that the preedit window is
-inside the application window but not at the point of insertion.
-Often, this type of window is placed at the bottom of the application window.
-.IP \(bu 5
-\fIRoot-window\fP preediting refers to input methods that use a preedit
-window that is the child of 
-.PN RootWindow .
-.LP
-It would require a lot of computing resources if portable applications
-had to include input methods for all the languages in the world.
-To avoid this,
-a goal of the Xlib design is to allow an application 
-to communicate with an input method placed in a separate process.
-Such a process is called an \fIinput server\fP.
-The server to which the application should connect is dependent on
-the environment when the application is started up,
-that is, the user language and the actual encoding to be used for it.
-The input method connection is said to be \fIlocale-dependent\fP.
-It is also user-dependent.
-For a given language, the user can choose, to some extent,
-the user interface style of input method (if choice is possible among
-several).
-.LP
-Using an input server implies communication overhead,
-but applications can be migrated without relinking.
-Input methods can be implemented either as a
-stub communicating to an input server or as a local library.
-.LP
-An input method may be based on a \fIfront-end\fP or a \fIback-end\fP
-architecture.
-In a front-end architecture,
-there are two separate connections to the X server:
-keystrokes go directly from the X server to the input method on
-one connection and other events to the regular client connection.
-The input method is then acting as a filter and sends composed strings
-to the client.
-A front-end architecture requires synchronization between the
-two connections to avoid lost key events or locking issues.
-.LP
-In a back-end architecture,
-a single X server connection is used.
-A dispatching mechanism must decide on this channel to delegate appropriate
-keystrokes to the input method.
-For instance,
-it may retain a Help keystroke for its own purpose.
-In the case where the input method is a separate process (that is, a server),
-there must be a special communication protocol between the back-end client
-and the input server.
-.LP
-A front-end architecture introduces synchronization issues
-and a filtering mechanism for noncharacter keystrokes
-(Function keys, Help, and so on).
-A back-end architecture sometimes implies more communication overhead
-and more process switching.
-If all three processes (X server, input server, client)
-are running on a single workstation, 
-there are two process switches for each keystroke in a back-end
-architecture,
-but there is only one in a front-end architecture.
-.LP
-The abstraction used by a client to communicate with an input method
-is an opaque data structure represented by the 
-.PN XIM
-data type.
-This data structure is returned by the 
-.PN XOpenIM
-function, which opens an input method on a given display.
-Subsequent operations on this data structure encapsulate all communication
-between client and input method.
-There is no need for an X client to use any networking library 
-or natural language package to use an input method.
-.LP
-A single input server may be used for one or more languages,
-supporting one or more encoding schemes.
-But the strings returned from an input method will always be encoded
-in the (single) locale associated with the
-.PN XIM
-object.
-.NH 4
-Input Contexts
-.XS
-\*(SN Input Contexts
-.XE
-.LP
-Xlib provides the ability to manage a multi-threaded state for text input.
-A client may be using multiple windows,
-each window with multiple text entry areas,
-and the user possibly switching among them at any time.
-The abstraction for representing the state of a particular input thread
-is called an \fIinput context\fP.
-The Xlib representation of an input context is an 
-.PN XIC .
-.LP
-An input context is the abstraction retaining the state, properties,
-and semantics of communication between a client and an input method.
-An input context is a combination of an input method, a locale
-specifying the encoding of the character strings to be returned,
-a client window, internal state information,
-and various layout or appearance characteristics.
-The input context concept somewhat matches for input the graphics context
-abstraction defined for graphics output.
-.LP
-One input context belongs to exactly one input method.
-Different input contexts may be associated with the same input method,
-possibly with the same client window.
-An 
-.PN XIC
-is created with the
-.PN XCreateIC
-function, providing an 
-.PN XIM
-argument and affiliating the input context to the input method
-for its lifetime. 
-When an input method is closed with 
-.PN XCloseIM ,
-all of its affiliated input contexts should not be used any more
-(and should preferably be destroyed before closing the input method).
-.LP
-Considering the example of a client window with multiple text entry areas,
-the application programmer could, for example, choose to implement as follows:
-.IP \(bu 5
-As many input contexts are created as text entry areas, and the client
-will get the input accumulated on each context each time it looks up
-in that context.
-.IP \(bu 5
-A single context is created for a top-level window in the application.
-If such a window contains several text entry areas, 
-each time the user moves to another text entry area,
-the client has to indicate changes in the context.
-.LP
-A range of choices can be made by application designers to use
-either a single or multiple input contexts,
-according to the needs of their application.
-.NH 4
-Getting Keyboard Input
-.XS
-\*(SN Getting Keyboard Input
-.XE
-.LP
-To obtain characters from an input method,
-a client must call the function
-.PN XmbLookupString
-or 
-.PN XwcLookupString
-with an input context created from that input method.
-Both a locale and display are bound to an input method when it is opened,
-and an input context inherits this locale and display.
-Any strings returned by 
-.PN XmbLookupString
-or
-.PN XwcLookupString
-will be encoded in that locale. 
-.NH 4 
-Focus Management
-.XS
-\*(SN Focus Management
-.XE
-.LP
-For each text entry area in which the
-.PN XmbLookupString
-or
-.PN XwcLookupString
-functions are used,
-there will be an associated input context.
-.LP
-When the application focus moves to a text entry area,
-the application must set the input context focus to the
-input context associated with that area.
-The input context focus is set by calling 
-.PN XSetICFocus
-with the appropriate input context.
-.LP
-Also, when the application focus moves out of a text entry area, the
-application should unset the focus for the associated input context
-by calling
-.PN XUnsetICFocus .
-As an optimization, if
-.PN XSetICFocus
-is called successively on two different input contexts,
-setting the focus on the second 
-will automatically unset the focus on the first.
-.LP
-To set and unset the input context focus correctly,
-it is necessary to track application-level focus changes.
-Such focus changes do not necessarily correspond to X server focus changes.
-.LP
-If a single input context
-is being used to do input for
-multiple text entry areas, it will also be necessary
-to set the focus window of the
-input context whenever the focus window changes
-(see section 13.5.6.3).
-.NH 4 
-Geometry Management
-.XS
-\*(SN Geometry Management
-.XE
-.LP
-In most input method architectures 
-(on-the-spot being the notable exception),
-the input method will perform the display of its own data.
-To provide better visual locality,
-it is often desirable to have the input method areas embedded within a client.
-To do this,
-the client may need to allocate space for an input method.
-Xlib provides support that allows the size and position of input method
-areas to be provided by a client.
-The input method areas that are supported for geometry management
-are the status area and the preedit area.
-.LP
-The fundamental concept on which geometry management for input method windows
-is based is the proper division of responsibilities between the
-client (or toolkit) and the input method.
-The division of responsibilities is as follows:
-.IP \(bu 5
-The client is responsible for the geometry of the input method window.
-.IP \(bu 5
-The input method is responsible for the contents of the input method window.
-.LP
-An input method is able to suggest a size to the client,
-but it cannot suggest a placement.
-Also the input method can only suggest a size.
-It does not determine the size,
-and it must accept the size it is given.
-.LP
-Before a client provides geometry management for an input method,
-it must determine if geometry management is needed.
-The input method indicates the need for geometry management 
-by setting 
-.PN XIMPreeditArea
-or 
-.PN XIMStatusArea
-in its 
-.PN XIMStyles
-value returned by 
-.PN XGetIMValues .
-When a client has decided that it will provide geometry management
-for an input method, 
-it indicates that decision by setting the
-.PN XNInputStyle
-value in the 
-.PN XIC .
-.LP
-After a client has established with the input method
-that it will do geometry management,
-the client must negotiate the geometry with the input method.
-The geometry is negotiated by the following steps:
-.IP \(bu 5
-The client suggests an area to the input method by setting the
-.PN XNAreaNeeded
-value for that area.
-If the client has no constraints for the input method,
-it either will not suggest an area or will set the width and height to zero.
-Otherwise, it will set one of the values.
-.IP \(bu 5
-The client will get the XIC value 
-.PN XNAreaNeeded .
-The input method will return its suggested size in this value.
-The input method should pay attention to any constraints suggested
-by the client.
-.IP \(bu 5
-The client sets the XIC value
-.PN XNArea
-to inform the input method of the geometry of its window.  
-The client should try to honor the geometry requested by the input method.
-The input method must accept this geometry.
-.LP
-Clients doing geometry management must be aware that setting other
-XIC values may affect the geometry desired by an input method.
-For example, 
-.PN XNFontSet
-and
-.PN XNLineSpacing
-may change the geometry desired by the input method.  
-.LP
-The table of XIC values (see section 13.5.6)
-indicates the values that can cause the desired geometry to change
-when they are set.
-It is the responsibility of the client to renegotiate the geometry
-of the input method window when it is needed.
-.LP
-In addition,
-a geometry management callback is provided
-by which an input method can initiate a geometry change.
-.NH 4
-Event Filtering
-.XS
-\*(SN Event Filtering
-.XE
-.LP
-A filtering mechanism is provided to allow input methods
-to capture X events transparently to clients.
-It is expected that toolkits (or clients) using
-.PN XmbLookupString
-or
-.PN XwcLookupString 
-will call this filter at some point in the event processing mechanism
-to make sure that events needed by an input method can be filtered
-by that input method.
-.LP
-If there were no filter,
-a client could receive and discard events that are necessary
-for the proper functioning of an input method.
-The following provides a few examples of such events:
-.IP \(bu 5
-Expose events on preedit window in local mode.
-.IP \(bu 5
-Events may be used by an input method to communicate with an input server.
-Such input server protocol-related events have to be intercepted
-if one does not want to disturb client code.
-.IP \(bu 5
-Key events can be sent to a filter before they are bound
-to translations such as those the X Toolkit Intrinsics library provides.
-.LP
-Clients are expected to get the XIC value 
-.PN XNFilterEvents
-and augment the event mask for the client window with that event mask.
-This mask may be zero.
-.NH 4
-Callbacks
-.XS
-\*(SN Callbacks
-.XE
-.LP
-When an on-the-spot input method is implemented,
-only the client can insert or delete preedit data in place
-and possibly scroll existing text.
-This means that the echo of the keystrokes has to be achieved 
-by the client itself, tightly coupled with the input method logic.
-.LP
-When the user enters a keystroke,
-the client calls
-.PN XmbLookupString
-or
-.PN XwcLookupString .
-At this point, in the on-the-spot case,
-the echo of the keystroke in the preedit has not yet been done.
-Before returning to the client logic that handles the input characters,
-the look-up function
-must call the echoing logic to insert the new keystroke.
-If the keystrokes entered so far make up a character,
-the keystrokes entered need to be deleted,
-and the composed character will be returned.
-Hence, what happens is that, while being called by client code,
-the input method logic has to call back to the client before it returns.
-The client code, that is, a callback procedure,
-is called from the input method logic.
-.LP
-There are a number of cases where the input method logic has to
-call back the client.
-Each of those cases is associated with a well-defined callback action.
-It is possible for the client to specify, for each input context,
-what callback is to be called for each action.
-.LP
-There are also callbacks provided for feedback of status information
-and a callback to initiate a geometry request for an input method.
-.NH 4
-Visible Position Feedback Masks
-.XS
-\*(SN Visible Position Feedback Masks
-.XE
-.LP
-In the on-the-spot input style, there is a problem when
-attempting to draw preedit strings that are longer than the
-available space.  Once the display area is exceeded, it is not
-clear how best to display the preedit string.
-The visible position feedback masks of
-.PN XIMText
-help resolve this problem by allowing the input method to specify hints that
-indicate the essential portions of the preedit string.
-For example, such hints can help developers implement
-scrolling of a long preedit string within a short preedit display area.
-.NH 4
-Preedit String Management
-.XS
-\*(SN Preedit String Management
-.XE
-.LP
-As highlighted before, the input method architecture provides
-preediting, which supports a type of preprocessor input composition.
-In this case, composition consists of interpreting a sequence
-of key events and returning a committed string via 
-.PN XmbLookupString
-or
-.PN XwcLookupString .
-This provides the basics for input methods.
-.LP
-In addition to preediting based on key events, a general framework
-is provided to give a client that desires it more advanced preediting based
-on the text within the client.  This framework is called 
-\fIstring conversion\fP and is provided using XIC values. 
-The fundamental concept of string conversion
-is to allow the input method to manipulate the client's
-text independent of any user preediting operation.
-.LP
-The need for string conversion is based on 
-language needs and input method capabilities.
-The following are some examples of string conversion:
-.IP \(bu 5
-Transliteration conversion provides language-specific conversions
-within the input method.
-In the case of Korean input, users wish to convert a Hangul string 
-into a Hanja string while in preediting, after preediting,
-or in other situations (for example, on a selected string).
-The conversion is triggered when the user
-presses a Hangul-to-Hanja key sequence (which may be input method specific).
-Sometimes the user may want to invoke the conversion after finishing
-preediting or on a user-selected string.  
-Thus, the string to be converted is in an application buffer, not in 
-the preedit area of the input method.  The string conversion services
-allow the client to request this transliteration conversion from the 
-input method.
-There are many other transliteration conversions defined for 
-various languages, for example, Kana-to-Kanji conversion in Japanese.
-.sp
-The key to remember is that transliteration conversions are triggered
-at the request of the user and returned to the client 
-immediately without affecting the preedit area of the input method.
-.IP \(bu 5
-Reconversion of a previously committed string or 
-a selected string is supported by many input methods as a 
-convenience to the user.
-For example, a user tends to mistype the commit key while
-preediting.  In that case, some input methods provide a special
-key sequence to request a ``reconvert'' operation on the 
-committed string, similiar to the undo facility provided by most
-text editors.
-Another example is where the user is proofreading a document 
-that has some misconversions from preediting and wants to correct
-the misconverted text.  Such reconversion is again triggered
-by the user invoking some special action, but reconversions should
-not affect the state of the preedit area.  
-.IP \(bu 5
-Context-sensitive conversion is required for some languages
-and input methods that need to retrieve text that surrounds the
-current spot location (cursor position) of the client's buffer.
-Such text is needed when the preediting operation depends on 
-some surrounding characters (usually preceding the spot location).
-For example, 
-in Thai language input, certain character sequences may be invalid and
-the input method may want to check whether characters constitute a
-valid word.  Input methods that do such context-dependent
-checking need to retrieve the characters surrounding the current
-cursor position to obtain complete words.
-.sp
-Unlike other conversions, this conversion is not explicitly 
-requested by the user.
-Input methods that provide such context-sensitive conversion 
-continuously need to request context from the client, and any change
-in the context of the spot location may affect such conversions.
-The client's context would be needed if the user moves the cursor
-and starts editing again.
-.sp
-For this reason, an input method supporting this type of conversion
-should take notice of when the client calls
-.PN XmbResetIC
-or
-.PN XwcResetIC ,
-which is usually an indication of a context change.  
-.LP
-Context-sensitive conversions just need a copy of the client's text,
-while other conversions replace the client's text with new text
-to achieve the reconversion or transliteration.   Yet in all
-cases the result of a conversion, either immediately or via preediting,
-is returned by the
-.PN XmbLookupString
-and
-.PN XwcLookupString
-functions.
-.LP
-String conversion support is dependent on the availability of the 
-.PN XNStringConversion
-or 
-.PN XNStringConversionCallback 
-XIC values.
-Because the input method may not support string conversions,
-clients have to query the availability of string conversion
-operations by checking the supported XIC values list by calling
-.PN XGetIMValues
-with the
-.PN XNQueryICValuesList
-IM value.
-.LP
-The difference between these two values is whether the
-conversion is invoked by the client or the input method.  
-The 
-.PN XNStringConversion
-XIC value is used by clients to request 
-a string conversion from the input method.  The client
-is responsible for determining which events are used 
-to trigger the string conversion and whether the string to be
-converted should be copied or deleted.  The type of conversion
-is determined by the input method; the client can only 
-pass the string to be converted.  The client is guaranteed that
-no
-.PN XNStringConversionCallback
-will be issued when this value is set; thus, the client need
-only set one of these values.
-.LP
-The
-.PN XNStringConversionCallback
-XIC value is used by the client to notify the input method that
-it will accept requests from the input method for string conversion.
-If this value is set,
-it is the input method's responsibility to determine which
-events are used to trigger the string conversion.
-When such events occur, the input method issues a call to the
-client-supplied procedure to retrieve the string to be converted.  The client's
-callback procedure is notified whether to copy or delete the string and 
-is provided with hints as to the amount of text needed.
-The
-.PN XIMStringConversionCallbackStruct
-specifies which text should be passed back to the input method.
-.LP
-Finally, the input method may call the client's 
-.PN XNStringConversionCallback
-procedure multiple times if the string returned from the callback is
-not sufficient to perform a successful conversion.   The arguments
-to the client's procedure allow the input method to define a
-position (in character units) relative to the client's cursor position 
-and the size of the text needed.  By varying the position and size of
-the desired text in subsequent callbacks, the input method can retrieve 
-additional text.
-.LP
-.NH 3
-Input Method Management
-.XS
-\*(SN Input Method Management
-.XE
-.LP
-The interface to input methods might appear to be simply creating
-an input method
-.Pn ( XOpenIM )
-and freeing an input method
-.Pn ( XCloseIM ).
-However, input methods may 
-require complex communication with input method servers (IM servers),
-for example:
-.IP \(bu 5
-If the X server, IM server, and X clients are started asynchronously,
-some clients may attempt to connect to the IM server before it is
-fully operational, and fail.
-Therefore, some mechanism is needed to allow clients to detect when an IM 
-server has started.
-.LP
-It is up to clients to decide what should be done when an IM server is 
-not available (for example, wait, or use some other IM server).
-.LP
-.IP \(bu 5
-Some input methods may allow the underlying IM server to be switched. 
-Such customization may be desired without restarting the entire client.
-.LP
-To support management of input methods in these cases, the following 
-functions are provided:
-.TS
-lw(2.4i) lw(3.3i).
-T{
-.PN XRegisterIMInstantiateCallback
-T}	T{
-This function allows clients to register a callback procedure
-to be called when Xlib detects that an IM server is up and available.
-T}
-T{
-.PN XOpenIM
-T}	T{
-A client calls this function as a result of the callback procedure
-being called.
-T}
-T{
-.PN XSetIMValue ,
-.PN XSetICValue
-T}	T{
-These functions use the XIM and XIC values,
-.PN XNDestroyCallback ,
-to allow a client 
-to register a callback procedure to be called when Xlib detects that
-an IM server that was associated with an opened 
-input method is no longer available.
-.sp 4p
-In addition, this function can be used to switch IM servers for those input 
-methods that support such functionality.  The IM value for switching IM 
-servers is implementation-dependent; see the description below about
-switching IM servers.
-T}
-T{
-.PN XUnregisterIMInstantiateCallback
-T}	T{
-This function removes a callback procedure registered by the client.
-T}
-.TE
-.LP
-Input methods that support switching of IM servers may exhibit some
-side-effects:
-.IP \(bu 5
-The input method will ensure that any new IM server supports any of the 
-input styles being used by input contexts already associated with the
-input method.
-However, the list of supported input styles may be different.
-.LP
-.IP \(bu 5
-Geometry management requests on previously created input contexts
-may be initiated by the new IM server.
-.LP
-.NH 4
-Hot Keys
-.XS
-\*(SN Hot Keys
-.XE
-.LP
-Some clients need to guarantee which keys can be used to escape from the
-input method, regardless of the input method state;
-for example, the client-specific Help key or the keys to move the
-input focus.
-The HotKey mechanism allows clients 
-to specify a set of keys for this purpose.  However, the input 
-method might not allow clients to specify hot keys.
-Therefore, clients have to query support of hot keys by checking the
-supported XIC values list by calling
-.PN XGetIMValues
-with the
-.PN XNQueryICValuesList
-IM value.
-When the hot keys specified conflict with the key bindings of the 
-input method, hot keys take precedence over the key bindings of the input 
-method.
-.LP
-.NH 4
-Preedit State Operation
-.XS
-\*(SN Preedit State Operation
-.XE
-.LP
-An input method may have several internal states, depending on its
-implementation and the locale.  However, one state that is
-independent of locale and implementation is whether the input method
-is currently performing a preediting operation.
-Xlib provides the ability for an application to manage the preedit state
-programmatically.  Two methods are provided for
-retrieving the preedit state of an input context.
-One method is to query the state by calling
-.PN XGetICValues
-with the
-.PN XNPreeditState
-XIC value.
-Another method is to receive notification whenever
-the preedit state is changed.  To receive such notification,
-an application needs to register a callback by calling
-.PN XSetICValues
-with the
-.PN XNPreeditStateNotifyCallback
-XIC value. 
-In order to change the preedit state programmatically, an application 
-needs to call 
-.PN XSetICValues
-with
-.PN XNPreeditState.
-.LP
-Availability of the preedit state is input method dependent.  The input 
-method may not provide the ability to set the state or to
-retrieve the state programmatically.  Therefore, clients have to 
-query availability of preedit state operations by checking the 
-supported XIC values list by calling
-.PN XGetIMValues
-with the
-.PN XNQueryICValuesList
-IM value.
-.NH 3 
-Input Method Functions
-.XS
-\*(SN Input Method Functions
-.XE
-.LP
-To open a connection, use
-.PN XOpenIM .
-.IN "XOpenIM" "" "@DEF@"
-.sM
-.FD 0
-XIM XOpenIM\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XrmDatabase \fIdb\fP\^;
-.br
-      char *\fIres_name\fP\^;
-.br
-      char *\fIres_class\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIdb\fP 1i
-Specifies a pointer to the resource database.
-.IP \fIres_name\fP 1i
-Specifies the full resource name of the application.
-.IP \fIres_class\fP 1i
-Specifies the full class name of the application.
-.LP
-.eM
-The
-.PN XOpenIM
-function opens an input method, 
-matching the current locale and modifiers specification.
-Current locale and modifiers are bound to the input method at opening time.
-The locale associated with an input method cannot be changed dynamically.
-This implies that the strings returned by
-.PN XmbLookupString
-or
-.PN XwcLookupString ,
-for any input context affiliated with a given input method,
-will be encoded in the locale current at the time the input method is opened.
-.LP
-The specific input method to which this call will be routed
-is identified on the basis of the current locale. 
-.PN XOpenIM
-will identify a default input method corresponding to the
-current locale.
-That default can be modified using 
-.PN XSetLocaleModifiers
-for the input method modifier.
-.LP
-The db argument is the resource database to be used by the input method
-for looking up resources that are private to the input method.
-It is not intended that this database be used to look
-up values that can be set as IC values in an input context.
-If db is NULL,
-no database is passed to the input method.
-.LP
-The res_name and res_class arguments specify the resource name 
-and class of the application. 
-They are intended to be used as prefixes by the input method
-when looking up resources that are common to all input contexts
-that may be created for this input method.
-The characters used for resource names and classes must be in the
-X Portable Character Set.
-The resources looked up are not fully specified
-if res_name or res_class is NULL.
-.LP
-The res_name and res_class arguments are not assumed to exist beyond
-the call to
-.PN XOpenIM .
-The specified resource database is assumed to exist for the lifetime
-of the input method.
-.LP
-.PN XOpenIM
-returns NULL if no input method could be opened.
-.LP
-.sp
-To close a connection, use
-.PN XCloseIM .
-.IN "XCloseIM" "" "@DEF@"
-.sM
-.FD 0
-Status XCloseIM\^(\^\fIim\fP\^)
-.br
-      XIM \fIim\fP\^;
-.FN
-.IP \fIim\fP 1i
-Specifies the input method.
-.LP
-.eM
-The
-.PN XCloseIM
-function closes the specified input method.
-.LP
-.sp
-To set input method attributes, use
-.PN XSetIMValues .
-.IN "XSetIMValues" "" "@DEF@"
-.sM
-.FD 0
-char * XSetIMValues\^(\^\fIim\fP\^, ...)
-.br
-      XIM \fIim\fP\^; 
-.FN
-.IP \fIim\fP 1i
-Specifies the input method.
-.ds Al \ to set XIM values
-.IP ... 1i
-Specifies the variable-length argument list\*(Al.
-.LP
-.eM
-The
-.PN XSetIMValues
-function presents a variable argument list programming interface
-for setting attributes of the specified input method.
-It returns NULL if it succeeds;
-otherwise,
-it returns the name of the first argument that could not be set.
-Xlib does not attempt to set arguments from the supplied list that
-follow the failed argument;
-all arguments in the list preceding the failed argument have been set
-correctly.
-.LP
-.sp
-To query an input method, use 
-.PN XGetIMValues .
-.IN "XGetIMValues" "" "@DEF@"
-.sM
-.FD 0
-char * XGetIMValues\^(\^\fIim\fP\^, ...)
-.br
-      XIM \fIim\fP\^; 
-.FN
-.IP \fIim\fP 1i
-Specifies the input method.
-.ds Al \ to get XIM values
-.IP ... 1i
-Specifies the variable length argument list\*(Al.
-.LP
-.eM
-The
-.PN XGetIMValues
-function presents a variable argument list programming interface
-for querying properties or features of the specified input method.
-This function returns NULL if it succeeds;
-otherwise,
-it returns the name of the first argument that could not be obtained.
-.LP
-Each XIM value argument (following a name) must point to
-a location where the XIM value is to be stored.
-That is, if the XIM value is of type T,
-the argument must be of type T*.
-If T itself is a pointer type,
-then
-.PN XGetIMValues
-allocates memory to store the actual data,
-and the client is responsible for freeing this data by calling
-.PN XFree
-with the returned pointer.
-.LP
-.sp
-To obtain the display associated with an input method, use
-.PN XDisplayOfIM .
-.IN "XDisplayOfIM" "" "@DEF@"
-.sM
-.FD 0
-Display * XDisplayOfIM\^(\^\fIim\fP\^)
-.br
-	XIM \fIim\fP\^;
-.FN
-.IP \fIim\fP 1i
-Specifies the input method.
-.LP
-.eM
-The
-.PN XDisplayOfIM
-function returns the display associated with the specified input method.
-.LP
-.sp
-To get the locale associated with an input method, use
-.PN XLocaleOfIM .
-.IN "XLocaleOfIM" "" "@DEF@"
-.sM
-.FD 0
-char * XLocaleOfIM\^(\^\fIim\fP\^)
-.br
-      XIM \fIim\fP\^; 
-.FN
-.IP \fIim\fP 1i
-Specifies the input method.
-.LP
-.eM
-The
-.PN XLocaleOfIM
-function returns the locale associated with the specified input method.
-.LP
-.sp
-To register an input method instantiate callback, use
-.PN XRegisterIMInstantiateCallback .
-.IN "XRegisterIMInstantiateCallback" "" "@DEF@"
-.sM
-.FD 0
-Bool XRegisterIMInstantiateCallback\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^, \fIcallback\fP\^, \fIclient_data\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XrmDatabase \fIdb\fP\^;
-.br
-      char *\fIres_name\fP\^;
-.br
-      char *\fIres_class\fP\^;
-.br
-      XIMProc  \fIcallback\fP\^;
-.br
-      XPointer *\fIclient_data\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIdb\fP 1i
-Specifies a pointer to the resource database.
-.IP \fIres_name\fP 1i
-Specifies the full resource name of the application.
-.IP \fIres_class\fP 1i
-Specifies the full class name of the application.
-.IP \fIcallback\fP 1i
-Specifies a pointer to the input method instantiate callback.
-.IP \fIclient_data\fP 1i
-Specifies the additional client data.
-.LP
-.eM
-The
-.PN XRegisterIMInstantiateCallback
-function registers a callback to be invoked whenever a new input method
-becomes available for the specified display that matches the current
-locale and modifiers.
-.LP
-The function returns 
-.PN True
- if it succeeds; otherwise, it returns 
-.PN False .
-.LP
-The generic prototype is as follows:
-.IN "IMInstantiateCallback" "" "@DEF@"
-.sM
-.FD 0
-void IMInstantiateCallback\^(\^\fIdisplay\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XPointer \fIclient_data\fP\^;	
-.br
-      XPointer \fIcall_data\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIclient_data\fP 1i
-Specifies the additional client data.
-.IP \fIcall_data\fP 1i
-Not used for this callback and always passed as NULL.
-.LP
-.eM
-To unregister an input method instantiation callback, use
-.PN XUnregisterIMInstantiateCallback .
-.IN "XUnregisterIMInstantiateCallback" "" "@DEF@"
-.sM
-.FD 0
-Bool XUnregisterIMInstantiateCallback\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^, \fIcallback\fP\^, \fIclient_data\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XrmDatabase \fIdb\fP\^;
-.br
-      char *\fIres_name\fP\^;
-.br
-      char *\fIres_class\fP\^;
-.br
-      XIMProc  \fIcallback\fP\^;
-.br
-      XPointer *\fIclient_data\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIdb\fP 1i
-Specifies a pointer to the resource database.
-.IP \fIres_name\fP 1i
-Specifies the full resource name of the application.
-.IP \fIres_class\fP 1i
-Specifies the full class name of the application.
-.IP \fIcallback\fP 1i
-Specifies a pointer to the input method instantiate callback.
-.IP \fIclient_data\fP 1i
-Specifies the additional client data.
-.LP
-.eM
-The
-.PN XUnregisterIMInstantiateCallback
-function removes an input method instantiation callback previously
-registered.
-The function returns
-.PN True
-if it succeeds; otherwise, it returns 
-.PN False .
-.NH 3 
-Input Method Values
-.XS
-\*(SN Input Method Values
-.XE
-.LP
-The following table describes how XIM values are interpreted
-by an input method.
-The first column lists the XIM values.
-The second column indicates how each of the XIM values 
-are treated by that input style.
-.LP
-.LP
-The following keys apply to this table.
-.TS H
-lw(1i) lw(4.75i).
-_
-.sp 6p
-.B
-Key	Explanation
-.sp 6p
-_
-.TH
-.R
-D	T{
-This value may be set using 
-.PN XSetIMValues .
-If it is not set,
-.br
-a default is provided.
-T}
-S	T{
-This value may be set using 
-.PN XSetIMValues .
-T}
-G	T{
-This value may be read using 
-.PN XGetIMValues .
-T}
-.sp 6p
-_
-.TE
-.LP
-.TS H
-lw(2.25i) c
-lw(2.25i) c.
-_
-.sp 6p
-.B
-XIM Value	Key
-.sp 6p
-_
-.sp 6p
-.TH
-.R
-T{
-.PN XNQueryInputStyle
-T}	T{
-G
-T}
-T{
-.PN XNResourceName
-T}	T{
-D-S-G
-T}
-T{
-.PN XNResourceClass
-T}	T{
-D-S-G
-T}
-T{
-.PN XNDestroyCallback
-T}	T{
-D-S-G
-T}
-T{
-.PN XNQueryIMValuesList
-T}	T{
-G
-T}
-T{
-.PN XNQueryICValuesList
-T}	T{
-G
-T}
-T{
-.PN XNVisiblePosition
-T}	T{
-G
-T}
-T{
-.PN XNR6PreeditCallbackBehavior
-T}	T{
-D-S-G
-T}
-.sp 6p
-_
-.TE
-.LP
-.PN XNR6PreeditCallbackBehavior
-is obsolete and its use is not recommended (see section 13.5.4.6).
-.LP
-.NH 4
-Query Input Style
-.XS
-\*(SN Query Input Style
-.XE
-.LP
-A client should always query the input method to determine which input 
-styles are supported.
-The client should then find an input style it is capable of supporting.
-.LP
-If the client cannot find an input style that it can support,
-it should negotiate with the user the continuation of the program
-(exit, choose another input method, and so on).
-.LP
-The argument value must be a pointer to a location
-where the returned value will be stored.
-The returned value is a pointer to a structure of type
-.PN XIMStyles .
-Clients are responsible for freeing the 
-.PN XIMStyles
-structure.
-To do so, use
-.PN XFree .
-.LP
-The
-.PN XIMStyles
-structure is defined as follows:
-.LP
-.IN "XIMStyle" "" "@DEF@"
-.IN "XIMPreeditArea" "" "@DEF@"
-.IN "XIMPreeditCallbacks" "" "@DEF@"
-.IN "XIMPreeditPosition" "" "@DEF@"
-.IN "XIMPreeditNothing" "" "@DEF@"
-.IN "XIMPreeditNone" "" "@DEF@"
-.IN "XIMStatusArea" "" "@DEF@"
-.IN "XIMStatusCallbacks" "" "@DEF@"
-.IN "XIMStatusNothing" "" "@DEF@"
-.IN "XIMStatusNone" "" "@DEF@"
-.IN "XIMStyles" "" "@DEF@"
-.sM
-.Ds 0
-typedef unsigned long XIMStyle;
-.De
-.TS
-lw(.5i) lw(2i) lw(2.5i).
-T{
-#define
-T}	T{
-.PN XIMPreeditArea
-T}	T{
-0x0001L
-T}
-T{
-#define
-T}	T{
-.PN XIMPreeditCallbacks
-T}	T{
-0x0002L
-T}
-T{
-#define
-T}	T{
-.PN XIMPreeditPosition
-T}	T{
-0x0004L
-T}
-T{
-#define
-T}	T{
-.PN XIMPreeditNothing
-T}	T{
-0x0008L
-T}
-T{
-#define
-T}	T{
-.PN XIMPreeditNone
-T}	T{
-0x0010L
-T}
-.sp
-T{
-#define
-T}	T{
-.PN XIMStatusArea
-T}	T{
-0x0100L
-T}
-T{
-#define
-T}	T{
-.PN XIMStatusCallbacks
-T}	T{
-0x0200L
-T}
-T{
-#define
-T}	T{
-.PN XIMStatusNothing
-T}	T{
-0x0400L
-T}
-T{
-#define
-T}	T{
-.PN XIMStatusNone
-T}	T{
-0x0800L
-T}
-.TE
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	unsigned short count_styles;
-	XIMStyle * supported_styles;
-} XIMStyles;
-.De
-.LP
-.eM
-An 
-.PN XIMStyles
-structure contains the number of input styles supported
-in its count_styles field.
-This is also the size of the supported_styles array.
-.LP
-The supported styles is a list of bitmask combinations,
-which indicate the combination of styles for each of the areas supported.
-These areas are described later.
-Each element in the list should select one of the bitmask values for
-each area.
-The list describes the complete set of combinations supported.
-Only these combinations are supported by the input method.
-.LP
-The preedit category defines what type of support is provided
-by the input method for preedit information.
-.IN "XIMPreeditArea" "" "@DEF@"
-.IN "XIMPreeditPosition" "" "@DEF@"
-.IN "XIMPreeditCallbacks" "" "@DEF@"
-.IN "XIMPreeditNothing" "" "@DEF@"
-.IN "XIMPreeditNone" "" "@DEF@"
-.TS
-lw(1.5i) lw(4.25i).
-T{
-.PN XIMPreeditArea 
-T}	T{
-If chosen,
-the input method would require the client to provide some area values
-for it to do its preediting.
-Refer to XIC values 
-.PN XNArea
-and
-.PN XNAreaNeeded .
-T}
-T{
-.PN XIMPreeditPosition
-T}	T{
-If chosen,
-the input method would require the client to provide positional values. 
-Refer to XIC values 
-.PN XNSpotLocation
-and
-.PN XNFocusWindow .
-T}
-T{
-.PN XIMPreeditCallbacks
-T}	T{
-If chosen,
-the input method would require the client to define the set of preedit callbacks.
-Refer to XIC values 
-.PN XNPreeditStartCallback ,
-.PN XNPreeditDoneCallback , 
-.PN XNPreeditDrawCallback ,
-and
-.PN XNPreeditCaretCallback .
-T}
-T{
-.PN XIMPreeditNothing
-T}	T{
-If chosen, the input method can function without any preedit values.
-T}
-T{
-.PN XIMPreeditNone
-T}	T{
-The input method does not provide any preedit feedback.
-Any preedit value is ignored.
-This style is mutually exclusive with the other preedit styles.
-T}
-.TE
-.LP
-The status category defines what type of support is provided
-by the input method for status information.
-.IN "XIMStatusArea" "" "@DEF@"
-.IN "XIMStatusCallbacks" "" "@DEF@"
-.IN "XIMStatusNothing" "" "@DEF@"
-.IN "XIMStatusNone" "" "@DEF@"
-.TS
-lw(1.5i) lw(4.25i).
-T{
-.PN XIMStatusArea
-T}	T{
-The input method requires the client to provide
-some area values for it to do its status feedback.
-See
-.PN XNArea
-and
-.PN XNAreaNeeded .
-T}
-T{
-.PN XIMStatusCallbacks
-T}	T{
-The input method requires the client to define the set of status callbacks,
-.PN XNStatusStartCallback , 
-.PN XNStatusDoneCallback ,
-and
-.PN XNStatusDrawCallback .
-T}
-T{
-.PN XIMStatusNothing
-T}	T{
-The input method can function without any status values.
-T}
-T{
-.PN XIMStatusNone
-T}	T{
-The input method does not provide any status feedback.
-If chosen, any status value is ignored.
-This style is mutually exclusive with the other status styles.
-T}
-.TE
-.NH 4
-Resource Name and Class
-.XS
-\*(SN Resource Name and Class
-.XE
-.LP
-The
-.PN XNResourceName
-and
-.PN XNResourceClass
-arguments are strings that specify the full name and class
-used by the input method.
-These values should be used as prefixes for the name and class
-when looking up resources that may vary according to the input method.
-If these values are not set,
-the resources will not be fully specified.
-.LP
-It is not intended that values that can be set as XIM values be
-set as resources.
-.LP
-.NH 4
-Destroy Callback
-.XS
-\*(SN Destroy Callback
-.XE
-.LP
-The 
-.PN XNDestroyCallback 
-argument is a pointer to a structure of type
-.PN XIMCallback .
-.PN XNDestroyCallback
-is triggered when an input method stops its service for any reason. 
-After the callback is invoked, the input method is closed and the
-associated input context(s) are destroyed by Xlib.
-Therefore, the client should not call
-.PN XCloseIM
-or
-.PN XDestroyIC .
-.LP
-The generic prototype of this callback function is as follows:
-.IN "DestroyCallback" "" "@DEF@"
-.sM
-.FD 0
-void DestroyCallback\^(\^\fIim\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
-.br
-      XIM \fIim\fP\^;
-.br
-      XPointer \fIclient_data\fP\^;
-.br
-      XPointer \fIcall_data\fP\^;
-.FN
-.IP \fIim\fP 1i
-Specifies the input method.
-.IP \fIclient_data\fP 1i
-Specifies the additional client data.
-.IP \fIcall_data\fP 1i
-Not used for this callback and always passed as NULL.
-.LP
-.eM
-A DestroyCallback is always called with a NULL call_data argument.
-.LP
-.NH 4
-Query IM/IC Values List
-.XS
-\*(SN Query IM/IC Values List
-.XE
-.LP
-.PN XNQueryIMValuesList
-and
-.PN XNQueryICValuesList
-are used to query about XIM and XIC values supported by the input method.
-.LP
-The argument value must be a pointer to a location where the returned
-value will be stored.  The returned value is a pointer to a structure
-of type
-.PN XIMValuesList .
-Clients are responsible for freeing the 
-.PN XIMValuesList
-structure.
-To do so, use
-.PN XFree .
-.LP
-The
-.PN XIMValuesList
-structure is defined as follows:
-.sM
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	unsigned short count_values;
-	char **supported_values;
-} XIMValuesList;
-.De
-.LP
-.eM
-.NH 4
-Visible Position
-.XS
-\*(SN Visible Position
-.XE
-.LP
-The 
-.PN XNVisiblePosition
-argument indicates whether the visible position masks of 
-.PN XIMFeedback
-in
-.PN XIMText
-are available.
-.LP
-The argument value must be a pointer to a location where the returned
-value will be stored.  The returned value is of type
-.PN Bool .
-If the returned value is
-.PN True ,
-the input method uses the visible position masks of
-.PN XIMFeedback
-in
-.PN XIMText ;
-otherwise, the input method does not use the masks.
-.LP
-Because this XIM value is optional, a client should call
-.PN XGetIMValues
-with argument
-.PN XNQueryIMValues
-before using this argument.
-If the 
-.PN XNVisiblePosition
-does not exist in the IM values list returned from 
-.PN XNQueryIMValues ,
-the visible position masks of
-.PN XIMFeedback
-in
-.PN XIMText
-are not used to indicate the visible position.
-.LP
-.NH 4
-Preedit Callback Behavior
-.XS
-\*(SN Preedit Callback Behavior
-.XE
-.LP
-The
-.PN XNR6PreeditCallbackBehavior
-argument originally included in the X11R6 specification has been
-deprecated.\(dg
-.\" If XNR6PreeditCallbackBehavior is not deprecated, then its type
-.\" should be changed from *Bool to Bool.
-.FS \(dg
-During formulation of the X11R6 specification, the behavior of
-the R6 PreeditDrawCallbacks was going to differ significantly from
-that of the R5 callbacks.
-Late changes to the specification converged the R5 and R6 behaviors,
-eliminating the need for
-.PN XNR6PreeditCallbackBehavior .
-Unfortunately, this argument was not removed from the R6 specification
-before it was published.
-.FE
-.LP
-The 
-.PN XNR6PreeditCallbackBehavior
-argument indicates whether the behavior of preedit callbacks regarding
-.PN XIMPreeditDrawCallbackStruct
-values follows Release 5 or Release 6 semantics.
-.LP
-The value is of type
-.PN Bool .
-When querying for
-.PN XNR6PreeditCallbackBehavior ,
-if the returned value is
-.PN True ,
-the input method uses the Release 6 behavior;
-otherwise, it uses the Release 5 behavior.
-The default value is
-.PN False .
-In order to use Release 6 semantics, the value of
-.PN XNR6PreeditCallbackBehavior
-must be set to
-.PN True .
-.LP
-Because this XIM value is optional, a client should call
-.PN XGetIMValues
-with argument
-.PN XNQueryIMValues
-before using this argument.
-If the
-.PN XNR6PreeditCallbackBehavior
-does not exist in the IM values list returned from
-.PN XNQueryIMValues ,
-the PreeditCallback behavior is Release 5 semantics.
-.LP
-.NH 3
-Input Context Functions
-.XS
-\*(SN Input Context Functions
-.XE
-.LP
-An input context is an abstraction that is used to contain both the data
-required (if any) by an input method and the information required
-to display that data.
-There may be multiple input contexts for one input method.
-The programming interfaces for creating, reading, or modifying
-an input context use a variable argument list.
-The name elements of the argument lists are referred to as XIC values.
-It is intended that input methods be controlled by these XIC values.
-As new XIC values are created,
-they should be registered with the X Consortium.
-.LP
-.sp
-To create an input context, use
-.PN XCreateIC .
-.IN "XCreateIC" "" "@DEF@"
-.sM
-.FD 0
-XIC XCreateIC\^(\^\fIim\fP\^, ...)
-.br
-      XIM \fIim\fP\^;
-.FN
-.IP \fIim\fP 1i
-Specifies the input method.
-.ds Al \ to set XIC values
-.IP ... 1i
-Specifies the variable length argument list\*(Al.
-.LP
-.eM
-The
-.PN XCreateIC 
-function creates a context within the specified input method.
-.LP
-Some of the arguments are mandatory at creation time, and
-the input context will not be created if those arguments are not provided.
-The mandatory arguments are the input style and the set of text callbacks
-(if the input style selected requires callbacks).
-All other input context values can be set later.
-.LP
-.PN XCreateIC
-returns a NULL value if no input context could be created.
-A NULL value could be returned for any of the following reasons:
-.IP \(bu 5
-A required argument was not set.
-.IP \(bu 5
-A read-only argument was set (for example,
-.PN XNFilterEvents ).
-.IP \(bu 5
-The argument name is not recognized.
-.IP \(bu 5
-The input method encountered an input method implementation-dependent error.
-.LP
-.PN XCreateIC
-can generate
-.PN BadAtom ,
-.PN BadColor ,
-.PN BadPixmap ,
-and
-.PN BadWindow
-errors.
-.LP
-.sp
-To destroy an input context, use
-.PN XDestroyIC .
-.IN "XDestroyIC" "" "@DEF@"
-.sM
-.FD 0
-void XDestroyIC\^(\^\fIic\fP\^)
-.br
-      XIC \fIic\fP\^;
-.FN
-.IP \fIic\fP 1i
-Specifies the input context.
-.LP
-.eM
-.PN XDestroyIC
-destroys the specified input context.
-.LP
-.sp
-To communicate to and synchronize with input method
-for any changes in keyboard focus from the client side,
-use 
-.PN XSetICFocus
-and
-.PN XUnsetICFocus .
-.IN "XSetICFocus" "" "@DEF@"
-.sM
-.FD 0
-void XSetICFocus\^(\^\fIic\fP\^)
-.br
-      XIC \fIic\fP\^; 
-.FN
-.IP \fIic\fP 1i
-Specifies the input context.
-.LP
-.eM
-The
-.PN XSetICFocus
-function allows a client to notify an input method that the focus window
-attached to the specified input context has received keyboard focus.
-The input method should take action to provide appropriate feedback.
-Complete feedback specification is a matter of user interface policy.
-.LP
-Calling
-.PN XSetICFocus
-does not affect the focus window value.
-.LP
-.sp
-.IN "XUnsetICFocus" "" "@DEF@"
-.sM
-.FD 0
-void XUnsetICFocus\^(\^\fIic\fP\^)
-.br
-      XIC \fIic\fP\^;
-.FN
-.IP \fIic\fP 1i
-Specifies the input context.
-.LP
-.eM
-The
-.PN XUnsetICFocus
-function allows a client to notify an input method that the specified input context
-has lost the keyboard focus and that no more input is expected on the focus window
-attached to that input context.
-The input method should take action to provide appropriate feedback.
-Complete feedback specification is a matter of user interface policy.
-.LP
-Calling
-.PN XUnsetICFocus
-does not affect the focus window value;
-the client may still receive 
-events from the input method that are directed to the focus window.
-.LP
-.sp
-To reset the state of an input context to its initial state, use
-.PN XmbResetIC
-or
-.PN XwcResetIC .
-.IN "XmbResetIC" "" "@DEF@"
-.IN "XwcResetIC" "" "@DE@"
-.sM
-.FD 0
-char * XmbResetIC\^(\^\fIic\fP\^)
-.br
-      XIC \fIic\fP\^;
-.FN
-.FD 0
-wchar_t * XwcResetIC\^(\^\fIic\fP\^)
-.br
-      XIC \fIic\fP\^; 
-.FN
-.IP \fIic\fP 1i
-Specifies the input context.
-.LP
-.eM
-When
-.PN XNResetState
-is set to
-.PN XIMInitialState ,
-.PN XmbResetIC
-and
-.PN XwcResetIC
-reset an input context to its initial state;
-when
-.PN XNResetState
-is set to
-.PN XIMPreserveState ,
-the current input context state is preserved.
-In both cases, any input pending on that context is deleted.
-The input method is required to clear the preedit area, if any,
-and update the status accordingly.
-Calling 
-.PN XmbResetIC
-or
-.PN XwcResetIC
-does not change the focus.
-.LP
-The return value of
-.PN XmbResetIC
-is its current preedit string as a multibyte string.
-If there is any preedit text drawn or visible to the user,
-then these procedures must return a non-NULL string.
-If there is no visible preedit text, 
-then it is input method implementation-dependent 
-whether these procedures return a non-NULL string or NULL.
-.LP
-The client should free the returned string by calling
-.PN XFree .
-.LP
-.sp
-To get the input method associated with an input context, use
-.PN XIMOfIC .
-.IN "XIMOfIC" "" "@DEF@"
-.sM
-.FD 0
-XIM XIMOfIC\^(\^\fIic\fP\^)
-.br
-      XIC \fIic\fP\^; 
-.FN
-.IP \fIic\fP 1i
-Specifies the input context.
-.LP
-.eM
-The
-.PN XIMOfIC
-function returns the input method associated with the specified input context.
-.LP
-.sp
-Xlib provides two functions for setting and reading XIC values, respectively,
-.PN XSetICValues
-and
-.PN XGetICValues .
-Both functions have a variable-length argument list.
-In that argument list, any XIC value's name must be denoted
-with a character string using the X Portable Character Set.
-.LP
-.sp
-To set XIC values, use
-.PN XSetICValues .
-.IN "XSetICValues" "" "@DEF@"
-.sM
-.FD 0
-char * XSetICValues\^(\^\fIic\fP\^, ...)
-.br
-      XIC \fIic\fP\^;
-.FN
-.IP \fIic\fP 1i
-Specifies the input context.
-.ds Al \ to set XIC values
-.IP ... 1i
-Specifies the variable length argument list\*(Al.
-.LP
-.eM
-The
-.PN XSetICValues
-function returns NULL if no error occurred; 
-otherwise,
-it returns the name of the first argument that could not be set.
-An argument might not be set for any of the following reasons:
-.IP \(bu 5
-The argument is read-only (for example,
-.PN XNFilterEvents ).
-.IP \(bu 5
-The argument name is not recognized.
-.IP \(bu 5
-An implementation-dependent error occurs.
-.LP
-Each value to be set must be an appropriate datum,
-matching the data type imposed by the semantics of the argument.
-.LP
-.PN XSetICValues
-can generate
-.PN BadAtom ,
-.PN BadColor ,
-.PN BadCursor ,
-.PN BadPixmap ,
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To obtain XIC values, use
-.PN XGetICValues .
-.IN "XGetICValues" "" "@DEF@"
-.sM
-.FD 0
-char * XGetICValues\^(\^\fIic\fP\^, ...)
-.br
-      XIC \fIic\fP\^;
-.FN
-.IP \fIic\fP 1i
-Specifies the input context.
-.ds Al \ to get XIC values
-.IP ... 1i
-Specifies the variable length argument list\*(Al.
-.LP
-.eM
-The
-.PN XGetICValues
-function returns NULL if no error occurred; otherwise,
-it returns the name of the first argument that could not be obtained.
-An argument could not be obtained for any of the following reasons:
-.IP \(bu 5
-The argument name is not recognized.
-.IP \(bu 5
-The input method encountered an implementation-dependent error.
-.LP
-Each IC attribute value argument (following a name) must point to
-a location where the IC value is to be stored.
-That is, if the IC value is of type T,
-the argument must be of type T*.
-If T itself is a pointer type,
-then
-.PN XGetICValues
-allocates memory to store the actual data,
-and the client is responsible for freeing this data by calling
-.PN XFree
-with the returned pointer.
-The exception to this rule is for an IC value of type
-.PN XVaNestedList
-(for preedit and status attributes).
-In this case,  the argument must also be of type
-.PN XVaNestedList .
-Then, the rule of changing type T to T* and freeing the allocated data
-applies to each element of the nested list.
-.NH 3 
-Input Context Values
-.XS
-\*(SN Input Context Values
-.XE
-.LP
-The following tables describe how XIC values are interpreted
-by an input method depending on the input style chosen by the 
-user.
-.LP
-The first column lists the XIC values.
-The second column indicates which values are involved in affecting,
-negotiating, and setting the geometry of the input method windows.
-The subentries under the third column indicate the different
-input styles that are supported.
-Each of these columns indicates how each of the XIC values 
-are treated by that input style.
-.LP
-The following keys apply to these tables.
-.TS H
-lw(1i) lw(4.75i).
-_
-.sp 6p
-.B
-Key	Explanation
-.sp 6p
-_
-.TH
-.R
-C	T{
-This value must be set with 
-.PN XCreateIC .
-T}
-D	T{
-This value may be set using 
-.PN XCreateIC .
-If it is not set,
-a default is provided.
-T}
-G	T{
-This value may be read using 
-.PN XGetICValues .
-T}
-GN	T{
-This value may cause geometry negotiation when its value is set by means of
-.PN XCreateIC
-or
-.PN XSetICValues .
-T}
-GR	T{
-This value will be the response of the input method when any 
-GN value is changed.
-T}
-GS	T{
-This value will cause the geometry of the input method window to be set.
-T}
-O	T{
-This value must be set once and only once.
-It need not be set at create time.
-T}
-S	T{
-This value may be set with
-.PN XSetICValues .
-T}
-Ignored	T{
-This value is ignored by the input method for the given input style.
-T}
-.sp 6p
-_
-.TE
-.LP
-.TS H
-c c c s s s s
-l c c c c c c
-c c c c c c c
-l c c c c c c.
-_
-.sp 6p
-.B
-		Input Style			
-XIC Value	Geometry	Preedit	Preedit	Preedit	Preedit	Preedit
-	Management	Callback	Position	Area	Nothing	None
-.sp 6p
-_
-.sp 6p
-.TH
-.R
-Input Style		C-G	C-G	C-G	C-G	C-G
-Client Window		O-G	O-G	O-G	O-G	Ignored
-Focus Window	GN	D-S-G	D-S-G	D-S-G	D-S-G	Ignored
-Resource Name		Ignored	D-S-G	D-S-G	D-S-G	Ignored
-Resource Class		Ignored	D-S-G	D-S-G	D-S-G	Ignored
-Geometry Callback		Ignored	Ignored	D-S-G	Ignored	Ignored
-Filter Events		G	G	G	G	Ignored
-Destroy Callback		D-S-G	D-S-G	D-S-G	D-S-G	D-S-G
-String Conversion Callback		S-G	S-G	S-G	S-G	S-G
-String Conversion		D-S-G	D-S-G	D-S-G	D-S-G	D-S-G
-Reset State		D-S-G	D-S-G	D-S-G	D-S-G	Ignored
-HotKey		S-G	S-G	S-G	S-G	Ignored
-HotKeyState		D-S-G	D-S-G	D-S-G	D-S-G	Ignored
-.sp 6p
-\fBPreedit\fP
-Area	GS	Ignored	D-S-G	D-S-G	Ignored	Ignored
-Area Needed	GN-GR	Ignored	Ignored	S-G	Ignored	Ignored
-Spot Location		Ignored	D-S-G	Ignored	Ignored	Ignored
-Colormap		Ignored	D-S-G	D-S-G	D-S-G	Ignored
-Foreground		Ignored	D-S-G	D-S-G	D-S-G	Ignored
-Background		Ignored	D-S-G	D-S-G	D-S-G	Ignored
-Background Pixmap		Ignored	D-S-G	D-S-G	D-S-G	Ignored
-Font Set	GN	Ignored	D-S-G	D-S-G	D-S-G	Ignored
-Line Spacing	GN	Ignored	D-S-G	D-S-G	D-S-G	Ignored
-Cursor		Ignored	D-S-G	D-S-G	D-S-G	Ignored
-Preedit State		D-S-G	D-S-G	D-S-G	D-S-G	Ignored
-Preedit State Notify Callback		S-G	S-G	S-G	S-G	Ignored
-Preedit Callbacks		C-S-G	Ignored	Ignored	Ignored	Ignored
-.sp 6p
-_
-.TE
-.LP
-.TS H
-c c c s s s
-l c c c c c
-c c c c c c 
-l c c c c c.
-_
-.sp 6p
-.B
-		Input Style			
-XIC Value	Geometry	Status	Status	Status	Status
-	Management	Callback	Area	Nothing	None
-.sp 6p
-_
-.sp 6p
-.TH
-.R
-Input Style		C-G	C-G	C-G	C-G
-Client Window		O-G	O-G	O-G	Ignored
-Focus Window	GN	D-S-G	D-S-G	D-S-G	Ignored
-Resource Name		Ignored	D-S-G	D-S-G	Ignored
-Resource Class		Ignored	D-S-G	D-S-G	Ignored
-Geometry Callback		Ignored	D-S-G	Ignored	Ignored
-Filter Events		G	G	G	G
-.sp 6p
-\fBStatus\fP					
-Area	GS	Ignored	D-S-G	Ignored	Ignored
-Area Needed	GN-GR	Ignored	S-G	Ignored	Ignored
-Colormap		Ignored	D-S-G	D-S-G	Ignored
-Foreground		Ignored	D-S-G	D-S-G	Ignored
-Background		Ignored	D-S-G	D-S-G	Ignored
-Background Pixmap		Ignored	D-S-G	D-S-G	Ignored
-Font Set	GN	Ignored	D-S-G	D-S-G	Ignored
-Line Spacing	GN	Ignored	D-S-G	D-S-G	Ignored
-Cursor		Ignored	D-S-G	D-S-G	Ignored
-Status Callbacks		C-S-G	Ignored	Ignored	Ignored
-.sp 6p
-_
-.TE
-.NH 4 
-Input Style
-.XS
-\*(SN Input Style
-.XE
-.LP
-The
-.PN XNInputStyle
-argument specifies the input style to be used.
-The value of this argument must be one of the values returned by the
-.PN XGetIMValues
-function with the
-.PN XNQueryInputStyle
-argument specified in the supported_styles list.
-.LP
-Note that this argument must be set at creation time
-and cannot be changed.
-.NH 4 
-Client Window
-.XS
-\*(SN Client Window
-.XE
-.LP
-.IN "XNClientWindow" "" "@DEF@"
-The
-.PN XNClientWindow
-argument specifies to the input method the client window in
-which the input method
-can display data or create subwindows.
-Geometry values for input method areas are given with respect to the client
-window.
-Dynamic change of client window is not supported.
-This argument may be set only once and
-should be set before any input is done using this input context.
-If it is not set,
-the input method may not operate correctly.
-.LP
-If an attempt is made to set this value a second time with
-.PN XSetICValues ,
-the string
-.PN XNClientWindow
-will be returned by
-.PN XSetICValues ,
-and the client window will not be changed.
-.LP
-If the client window is not a valid window ID on the display
-attached to the input method,
-a 
-.PN BadWindow 
-error can be generated when this value is used by the input method.
-.NH 4 
-Focus Window
-.XS
-\*(SN Focus Window
-.XE
-.LP
-.IN "XNFocusWindow" "" "@DEF@"
-The
-.PN XNFocusWindow
-argument specifies the focus window.
-The primary purpose of the 
-.PN XNFocusWindow
-is to identify the window that will receive the key event when input
-is composed.
-In addition, the input method may possibly affect the focus window
-as follows:
-.IP \(bu 5
-Select events on it
-.IP \(bu 5
-Send events to it
-.IP \(bu 5
-Modify its properties
-.IP \(bu 5
-Grab the keyboard within that window  
-.LP
-The associated value must be of type 
-.PN Window .
-If the focus window is not a valid window ID on the display 
-attached to the input method,
-a 
-.PN BadWindow
-error can be generated when this value is used by the input method.
-.LP
-When this XIC value is left unspecified,
-the input method will use the client window as the default focus window.
-.NH 4
-Resource Name and Class
-.XS
-\*(SN Resource Name and Class
-.XE
-.LP
-.IN "XNResourceName" "" "@DEF@"
-.IN "XNResourceClass" "" "@DEF@"
-The
-.PN XNResourceName
-and
-.PN XNResourceClass
-arguments are strings that specify the full name and class
-used by the client to obtain resources for the client window. 
-These values should be used as prefixes for name and class
-when looking up resources that may vary according to the input context.
-If these values are not set,
-the resources will not be fully specified.
-.LP
-It is not intended that values that can be set as XIC values be
-set as resources.
-.NH 4
-Geometry Callback
-.XS
-\*(SN Geometry Callback
-.XE
-.LP
-.IN "XNGeometryCallback" "" "@DEF@"
-The 
-.PN XNGeometryCallback
-argument is a structure of type 
-.PN XIMCallback 
-(see section 13.5.6.13.12).
-.LP
-The 
-.PN XNGeometryCallback
-argument specifies the geometry callback that a client can set.
-This callback is not required for correct operation of either 
-an input method or a client.
-It can be set for a client whose user interface policy permits
-an input method to request the dynamic change of that input 
-method's window.
-An input method that does dynamic change will need to filter any
-events that it uses to initiate the change.
-.NH 4
-Filter Events
-.XS
-\*(SN Filter Events
-.XE
-.LP
-.IN "XNFilterEvents" "" "@DEF@"
-The 
-.PN XNFilterEvents
-argument returns the event mask that an input method needs
-to have selected for.
-The client is expected to augment its own event mask 
-for the client window with this one.
-.LP
-This argument is read-only, is set by the input method at create time,
-and is never changed.
-.LP
-The type of this argument is 
-.PN unsigned
-.PN long .
-Setting this value will cause an error.
-.NH 4
-Destroy Callback
-.XS
-\*(SN Destroy Callback 
-.XE
-.LP
-The 
-.PN XNDestroyCallback 
-argument is a pointer to a structure of type
-.PN XIMCallback 
-(see section 13.5.6.13.12).  This callback is triggered when the input method 
-stops its service for any reason; for example, when a connection to an IM
-server is broken.  After the destroy callback is called, 
-the input context is destroyed and the input method is closed.
-Therefore, the client should not call 
-.PN XDestroyIC
-and
-.PN XCloseIM .
-.LP
-.NH 4
-String Conversion Callback
-.XS
-\*(SN String Conversion Callback
-.XE
-.LP
-The
-.PN XNStringConversionCallback
-argument is a structure of type
-.PN XIMCallback 
-(see section 13.5.6.13.12).
-.LP
-The
-.PN XNStringConversionCallback
-argument specifies a string conversion callback.  This callback
-is not required for correct operation of
-either the input method or the client.  It can be set by a client
-to support string conversions that may be requested
-by the input method.  An input method that does string conversions
-will filter any events that it uses to initiate the conversion.
-.LP
-Because this XIC value is optional, a client should call
-.PN XGetIMValues
-with argument
-.PN XNQueryICValuesList
-before using this argument.
-.LP
-.NH 4
-String Conversion 
-.XS
-\*(SN String Conversion
-.XE
-.LP
-The
-.PN XNStringConversion
-argument is a structure of type
-.PN XIMStringConversionText .
-.LP
-The
-.PN XNStringConversion
-argument specifies the string to be converted by an input method.
-This argument is not required for correct operation of either
-the input method or the client.
-.LP
-String conversion facilitates the manipulation of text independent
-of preediting.
-It is essential for some input methods and clients to manipulate
-text by performing context-sensitive conversion,
-reconversion, or transliteration conversion on it.
-.LP
-Because this XIC value is optional, a client should call
-.PN XGetIMValues
-with argument
-.PN XNQueryICValuesList
-before using this argument.
-.LP
-The
-.PN XIMStringConversionText
-structure is defined as follows:
-.LP
-.sM
-.Ds 0
-
-typedef struct _XIMStringConversionText {
-	unsigned short length;
-	XIMStringConversionFeedback *feedback;
-	Bool encoding_is_wchar;
-	union {
-		char	*mbs;
-		wchar_t *wcs;
-	} string;
-} XIMStringConversionText;
-
-typedef unsigned long XIMStringConversionFeedback;
-.De
-.LP
-.eM
-The feedback member is reserved for future use.  The text to be
-converted is defined by the string and length members.  The length
-is indicated in characters.  To prevent the library from freeing memory
-pointed to by an uninitialized pointer, the client should set the feedback
-element to NULL.
-.LP
-.NH 4
-Reset State
-.XS
-\*(SN Reset State
-.XE
-.LP
-The
-.PN XNResetState
-argument specifies the state the input context will return to after calling
-.PN XmbResetIC
-or
-.PN XwcResetIC .
-.LP
-The XIC state may be set to its initial state, as specified by the
-.PN XNPreeditState
-value when
-.PN XCreateIC
-was called, or it may be set to preserve the current state.
-.LP
-The valid masks for
-.PN XIMResetState
-are as follows:
-.LP
-.IN "XIMInitialState" "" "@DEF@"
-.IN "XINPreserveState" "" "@DEF@"
-.sM
-.LP
-.Ds 0
-typedef unsigned long XIMResetState;
-.De
-.TS
-lw(.5i) lw(2i) lw(2i).
-T{
-#define
-T}	T{
-.PN XIMInitialState
-T}	T{
-(1L)
-T}
-T{
-#define
-T}	T{
-.PN XIMPreserveState
-T}	T{
-(1L<<1)
-T}
-.TE
-.LP
-.eM
-If
-.PN XIMInitialState
-is set, then
-.PN XmbResetIC
-and
-.PN XwcResetIC
-will return to the initial
-.PN XNPreeditState
-state of the XIC.
-.LP
-If
-.PN XIMPreserveState
-is set, then 
-.PN XmbResetIC
-and
-.PN XwcResetIC
-will preserve the current state of the XIC.
-.LP
-If
-.PN XNResetState
-is left unspecified, the default is
-.PN XIMInitialState .
-.LP
-.PN XIMResetState
-values other than those specified above will default to
-.PN XIMInitialState .
-.LP
-Because this XIC value is optional, a client should call
-.PN XGetIMValues
-with argument
-.PN XNQueryICValuesList
-before using this argument.
-.LP
-.NH 4
-Hot Keys
-.XS
-\*(SN Hot Keys
-.XE
-.LP
-The
-.PN XNHotKey
-argument specifies the hot key list to the XIC.
-The hot key list is a pointer to the structure of type
-.PN XIMHotKeyTriggers ,
-which specifies the key events that must be received
-without any interruption of the input method.
-For the hot key list set with this argument to be utilized, the client
-must also set
-.PN XNHotKeyState
-to
-.PN XIMHotKeyStateON .
-.LP
-Because this XIC value is optional, a client should call
-.PN XGetIMValues
-with argument
-.PN XNQueryICValuesList
-before using this functionality.
-.LP
-The value of the argument is a pointer to a structure of type
-.PN XIMHotKeyTriggers .
-.LP
-If an event for a key in the hot key list is found, then the process will
-receive the event and it will be processed inside the client.
-.LP
-.sM
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	KeySym keysym;
-	unsigned int modifier;
-	unsigned int modifier_mask;
-} XIMHotKeyTrigger;
-
-typedef struct {
-	int num_hot_key;
-	XIMHotKeyTrigger *key;
-} XIMHotKeyTriggers;
-.De
-.LP
-.eM
-.LP
-The combination of modifier and modifier_mask are used to represent one of
-three states for each modifier:
-either the modifier must be on, or the modifier must be off, or the modifier
-is a ``don't care'' \- it may be on or off.
-When a modifier_mask bit is set to 0, the state of the associated modifier
-is ignored when evaluating whether the key is hot or not.
-.TS H
-lw(1i) lw(1i) lw(3i).
-_
-.sp 6p
-.B
-Modifier Bit	Mask Bit	Meaning
-.sp 6p
-_
-.sp 6p
-.TH
-.R
-T{
-0
-T}	T{
-1
-T}	T{
-The modifier must be off.
-T}
-T{
-1
-T}	T{
-1
-T}	T{
-The modifier must be on.
-T}
-T{
-n/a
-T}	T{
-0
-T}	T{
-Do not care if the modifier is on or off.
-T}
-.sp 6p
-_
-.TE
-.NH 4
-Hot Key State
-.XS
-\*(SN Hot Key State
-.XE
-.LP
-The
-.PN XNHotKeyState
-argument specifies the hot key state of the input method.
-This is usually used to switch the input method between hot key
-operation and normal input processing.
-.LP
-The value of the argument is a pointer to a structure of type
-XIMHotKeyState .
-.LP
-.sM
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef unsigned long XIMHotKeyState;
-.De
-.TS
-lw(.5i) lw(3i) lw(2i).
-T{
-#define
-T}	T{
-.PN XIMHotKeyStateON
-T}	T{
-(0x0001L)
-T}
-T{
-#define
-T}	T{
-.PN XIMHotKeyStateOFF
-T}	T{
-(0x0002L)
-T}
-.TE
-.LP
-.eM
-.LP
-If not specified, the default is
-.PN XIMHotKeyStateOFF .
-.LP
-.NH 4
-Preedit and Status Attributes
-.XS
-\*(SN Preedit and Status Attributes
-.XE
-.LP
-.IN "XNPreeditAttributes" "" "@DEF@"
-.IN "XNStatusAttributes" "" "@DEF@"
-The
-.PN XNPreeditAttributes
-and
-.PN XNStatusAttributes
-arguments specify to an input method the attributes to be used for the 
-preedit and status areas,
-if any.
-Those attributes are passed to 
-.PN XSetICValues
-or
-.PN XGetICValues
-as a nested variable-length list.
-The names to be used in these lists are described in the following sections.
-.NH 5 
-Area
-.XS
-\*(SN Area
-.XE
-.LP
-.IN "XNArea" "" "@DEF@"
-The value of the
-.PN XNArea
-argument must be a pointer to a structure of type
-.PN XRectangle.
-The interpretation of the
-.PN XNArea
-argument is dependent on the input method style that has been set.
-.LP
-If the input method style is 
-.PN XIMPreeditPosition ,
-.PN XNArea
-specifies the clipping region within which preediting will take place.
-If the focus window has been set,
-the coordinates are assumed to be relative to the focus window.
-Otherwise, the coordinates are assumed to be relative to the client window.
-If neither has been set,
-the results are undefined.
-.LP
-If 
-.PN XNArea
-is not specified, is set to NULL, or is invalid,
-the input method will default the clipping region
-to the geometry of the
-.PN XNFocusWindow .
-If the area specified is NULL or invalid,
-the results are undefined.
-.LP
-If the input style is 
-.PN XIMPreeditArea
-or 
-.PN XIMStatusArea ,
-.PN XNArea
-specifies the geometry provided by the client to the input method.
-The input method may use this area to display its data,
-either preedit or status depending on the area designated.
-The input method may create a window as a child of the client window
-with dimensions that fit the
-.PN XNArea .
-The coordinates are relative to the client window.
-If the client window has not been set yet,
-the input method should save these values 
-and apply them when the client window is set.
-If 
-.PN XNArea
-is not specified, is set to NULL, or is invalid,
-the results are undefined.
-.NH 5
-Area Needed
-.XS
-\*(SN Area Needed
-.XE
-.LP
-.IN "XNAreaNeeded" "" "@DEF@"
-When set, the
-.PN XNAreaNeeded
-argument specifies the geometry suggested by the client for this area
-(preedit or status).
-The value associated with the argument must be a pointer to a 
-structure of type 
-.PN XRectangle .
-Note that the x, y values are not used
-and that nonzero values for width or height are the constraints 
-that the client wishes the input method to respect.
-.LP
-When read, the
-.PN XNAreaNeeded
-argument specifies the preferred geometry desired by the input method
-for the area.
-.LP
-This argument is only valid if the input style is 
-.PN XIMPreeditArea
-or 
-.PN XIMStatusArea .
-It is used for geometry negotiation between the client and the input method
-and has no other effect on the input method 
-(see section 13.5.1.5).
-.NH 5 
-Spot Location
-.XS
-\*(SN Spot Location
-.XE
-.LP
-.IN "XNSpotLocation" "" "@DEF@"
-The
-.PN XNSpotLocation
-argument specifies to the input method the coordinates of the spot
-to be used by an input method executing with 
-.PN XNInputStyle 
-set to 
-.PN XIMPreeditPosition .
-When specified to any input method other than 
-.PN XIMPreeditPosition ,
-this XIC value is ignored.
-.LP
-The x coordinate specifies the position where the next character
-would be inserted.
-The y coordinate is the position of the baseline used
-by the current text line in the focus window.
-The x and y coordinates are relative to the focus window, if it has been set;
-otherwise, they are relative to the client window.
-If neither the focus window nor the client window has been set,
-the results are undefined.
-.LP
-The value of the argument is a pointer to a structure of type
-.PN XPoint .
-.NH 5
-Colormap
-.XS
-\*(SN Colormap
-.XE
-.LP
-Two different arguments can be used to indicate what colormap the input method
-should use to allocate colors, a colormap ID, or a standard colormap name.
-.LP
-.IN "XNColormap" "" "@DEF@"
-The
-.PN XNColormap
-argument is used to specify a colormap ID.
-The argument value is of type
-.PN Colormap .
-An invalid argument may generate a 
-.PN BadColor
-error when it is used by the input method.
-.LP
-.IN "XNStdColormap" "" "@DEF@"
-The
-.PN XNStdColormap
-argument is used to indicate the name of the standard colormap
-in which the input method should allocate colors.
-The argument value is an 
-.PN Atom
-that should be a valid atom for calling
-.PN XGetRGBColormaps .
-An invalid argument may generate a
-.PN BadAtom
-error when it is used by the input method.
-.LP
-If the colormap is left unspecified,
-the client window colormap becomes the default.
-.NH 5
-Foreground and Background
-.XS
-\*(SN Foreground and Background
-.XE
-.LP
-.IN "XNForeground" "" "@DEF@"
-.IN "XNBackground" "" "@DEF@"
-The
-.PN XNForeground
-and
-.PN XNBackground
-arguments specify the foreground and background pixel, respectively.
-The argument value is of type
-.PN unsigned
-.PN long .
-It must be a valid pixel in the input method colormap.
-.LP
-If these values are left unspecified,
-the default is determined by the input method.
-.NH 5
-Background Pixmap
-.XS
-\*(SN Background Pixmap
-.XE
-.LP
-The
-.PN XNBackgroundPixmap
-argument specifies a background pixmap to be used as the background of the
-window.
-The value must be of type 
-.PN Pixmap .
-An invalid argument may generate a
-.PN BadPixmap
-error when it is used by the input method.
-.LP
-If this value is left unspecified,
-the default is determined by the input method.
-.NH 5
-Font Set
-.XS
-\*(SN Font Set
-.XE
-.LP
-.IN "XNFontSet" "" "@DEF@"
-The
-.PN XNFontSet
-argument specifies to the input method what font set is to be used.
-The argument value is of type
-.PN XFontSet .
-.LP
-If this value is left unspecified,
-the default is determined by the input method.
-.NH 5
-Line Spacing
-.XS
-\*(SN Line Spacing
-.XE
-.LP
-The
-.PN XNLineSpace
-argument specifies to the input method what line spacing is to be used
-in the preedit window if more than one line is to be used.
-This argument is of type
-.PN int .
-.LP
-If this value is left unspecified,
-the default is determined by the input method.
-.NH 5
-Cursor
-.XS
-\*(SN Cursor
-.XE
-.LP
-.IN "XNCursor" "" "DEF@"
-The
-.PN XNCursor
-argument specifies to the input method what cursor is to be used
-in the specified window.
-This argument is of type 
-.PN Cursor .
-.LP
-An invalid argument may generate a
-.PN BadCursor
-error when it is used by the input method.
-If this value is left unspecified,
-the default is determined by the input method.
-.NH 5 
-Preedit State
-.XS
-\*(SN Preedit State
-.XE
-.LP
-The
-.PN XNPreeditState
-argument specifies the state of input preediting for the input method.
-Input preediting can be on or off.
-.LP
-The valid mask names for
-.PN XNPreeditState
-are as follows:
-.LP
-.IN "XIMPreeditUnknown" "" "@DEV@"
-.IN "XIMPreeditEnable" "" "@DEF@"
-.IN "XIMPreeditDisable" "" "@DEV@"
-.sM
-.LP
-.Ds 0
-typedef unsigned long XIMPreeditState;
-.De
-.TS
-lw(.5i) lw(2i) lw(2i).
-T{
-#define
-T}	T{
-.PN XIMPreeditUnknown
-T}	T{
-0L
-T}
-T{
-#define
-T}	T{
-.PN XIMPreeditEnable
-T}	T{
-1L
-T}
-T{
-#define
-T}	T{
-.PN XIMPreeditDisable
-T}	T{
-(1L<<1)
-T}
-.TE
-.LP
-.eM
-If a value of
-.PN XIMPreeditEnable
-is set, then input preediting is turned on by the input method.
-.LP
-If a value of
-.PN XIMPreeditDisable
-is set, then input preediting is turned off by the input method.
-.LP
-If
-.PN XNPreeditState
-is left unspecified, then the state will be implementation-dependent.
-.LP
-When
-.PN XNResetState
-is set to
-.PN XIMInitialState ,
-the
-.PN XNPreeditState
-value specified at the creation time will be reflected as the initial state for
-.PN XmbResetIC
-and
-.PN XwcResetIC .
-.LP
-Because this XIC value is optional, a client should call
-.PN XGetIMValues
-with argument
-.PN XNQueryICValuesList
-before using this argument.
-.NH 5
-Preedit State Notify Callback
-.XS
-\*(SN Preedit State Notify Callback
-.XE
-.LP
-The preedit state notify callback is triggered by the input method
-when the preediting state has changed.
-The value of the
-.PN XNPreeditStateNotifyCallback
-argument is a pointer to a structure of type
-.PN XIMCallback .
-The generic prototype is as follows:
-.IN "PreeditStateNotifyCallback" "" "@DEF@"
-.sM
-.FD 0
-void PreeditStateNotifyCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
-.br
-      XIC \fIic\fP\^;
-.br
-      XPointer \fIclient_data\fP\^;
-.br
-      XIMPreeditStateNotifyCallbackStruct *\fIcall_data\fP\^;
-.FN
-.IP \fIic\fP 1i
-Specifies the input context.
-.IP \fIclient_data\fP 1i
-Specifies the additional client data.
-.IP \fIcall_data\fP 1i
-Specifies the current preedit state.
-.LP
-.eM
-The
-.PN XIMPreeditStateNotifyCallbackStruct
-structure is defined as follows:
-.LP
-.IN "XIMPreeditStateNotifyCallbackStruct" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct _XIMPreeditStateNotifyCallbackStruct {
-	XIMPreeditState state;
-} XIMPreeditStateNotifyCallbackStruct;
-.De
-.LP
-.eM
-.LP
-Because this XIC value is optional, a client should call
-.PN XGetIMValues
-with argument
-.PN XNQueryICValuesList
-before using this argument.
-.NH 5
-Preedit and Status Callbacks
-.XS
-\*(SN Preedit and Status Callbacks
-.XE
-.LP
-A client that wants to support the input style
-.PN XIMPreeditCallbacks
-must provide a set of preedit callbacks to the input method.
-The set of preedit callbacks is as follows:
-.IN "XNPreeditStartCallback" "" "@DEF@"
-.IN "XNPreeditDoneCallback" "" "@DEF@"
-.IN "XNPreeditDrawCallback" "" "@DEF@"
-.IN "XNPreeditCaretCallback" "" "@DEF@"
-.TS
-lw(1.75i) lw(4i).
-T{
-.PN XNPreeditStartCallback
-T}	T{
-This is called when the input method starts preedit.
-T}
-T{
-.PN XNPreeditDoneCallback
-T}	T{
-This is called when the input method stops preedit.
-T}
-T{
-.PN XNPreeditDrawCallback
-T}	T{
-This is called when a number of preedit keystrokes should be echoed.
-T}
-T{
-.PN XNPreeditCaretCallback
-T}	T{
-This is called to move the text insertion point within the preedit string.
-T}
-.TE
-.LP
-A client that wants to support the input style
-.PN XIMStatusCallbacks
-must provide a set of status callbacks to the input method.
-The set of status callbacks is as follows:
-.IN "XNStatusStartCallback" "" "@DEF@"
-.IN "XNStatusDoneCallback" "" "@DEF@"
-.IN "XNStatusDrawCallback" "" "@DEF@"
-.TS
-lw(1.75i) lw(4i).
-T{
-.PN XNStatusStartCallback
-T}	T{
-This is called when the input method initializes the status area.
-T}
-T{
-.PN XNStatusDoneCallback
-T}	T{
-This is called when the input method no longer needs the status area.
-T}
-T{
-.PN XNStatusDrawCallback
-T}	T{
-This is called when updating of the status area is required.
-T}
-.TE
-.LP
-The value of any status or preedit argument is a pointer
-to a structure of type
-.PN XIMCallback .
-.IN "XIMProc" "" "@DEF@"
-.IN "XIMCallback" "" "@DEF@"
-.sM
-.LP
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef void (*XIMProc)();
-
-typedef struct {
-	XPointer client_data;
-	XIMProc callback;
-} XIMCallback;
-.De
-.LP
-.eM
-Each callback has some particular semantics and will carry the data
-that expresses the environment necessary to the client 
-into a specific data structure.
-This paragraph only describes the arguments to be used to set
-the callback.
-.LP
-Setting any of these values while doing preedit
-may cause unexpected results.
-.NH 3
-Input Method Callback Semantics
-.XS
-\*(SN Input Method Callback Semantics
-.XE
-.LP
-XIM callbacks are procedures defined by clients or text drawing packages
-that are to be called from the input method when selected events occur.
-Most clients will use a text editing package or a toolkit
-and, hence, will not need to define such callbacks.
-This section defines the callback semantics, when they are triggered,
-and what their arguments are.
-This information is mostly useful for X toolkit implementors.
-.LP
-Callbacks are mostly provided so that clients (or text editing
-packages) can implement on-the-spot preediting in their own window.
-In that case,
-the input method needs to communicate and synchronize with the client.
-The input method needs to communicate changes in the preedit window 
-when it is under control of the client.
-Those callbacks allow the client to initialize the preedit area,
-display a new preedit string,
-move the text insertion point during preedit,
-terminate preedit, or update the status area.
-.LP
-All callback procedures follow the generic prototype:
-.IN "CallbackPrototype" "" "@DEF@"
-.sM
-.FD 0
-void CallbackPrototype\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
-.br
-      XIC \fIic\fP\^;
-.br
-      XPointer \fIclient_data\fP\^;	
-.br
-      SomeType \fIcall_data\fP\^;
-.FN
-.IP \fIic\fP 1i
-Specifies the input context.
-.IP \fIclient_data\fP 1i
-Specifies the additional client data.
-.IP \fIcall_data\fP 1i
-Specifies data specific to the callback.
-.LP
-.eM
-The call_data argument is a structure that expresses the arguments needed
-to achieve the semantics;
-that is,
-it is a specific data structure appropriate to the callback.
-In cases where no data is needed in the callback,
-this call_data argument is NULL.
-The client_data argument is a closure that has been initially specified
-by the client when specifying the callback and passed back.
-It may serve, for example, to inherit application context in the callback.
-.LP
-The following paragraphs describe the programming semantics
-and specific data structure associated with the different reasons.
-.NH 4
-Geometry Callback
-.XS
-\*(SN Geometry Callback
-.XE
-.LP
-The geometry callback is triggered by the input method 
-to indicate that it wants the client to negotiate geometry.
-The generic prototype is as follows:
-.IN "GeometryCallback" "" "@DEF@"
-.sM
-.FD 0
-void GeometryCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
-.br
-      XIC \fIic\fP\^;
-.br
-      XPointer \fIclient_data\fP\^;
-.br
-      XPointer \fIcall_data\fP\^;
-.FN
-.IP \fIic\fP 1i
-Specifies the input context.
-.IP \fIclient_data\fP 1i
-Specifies the additional client data.
-.IP \fIcall_data\fP 1i
-Not used for this callback and always passed as NULL.
-.LP
-.eM
-The callback is called with a NULL call_data argument.
-.NH 4
-Destroy Callback
-.XS
-\*(SN Destroy Callback
-.XE
-.LP
-The destroy callback is triggered by the input method 
-when it stops service for any reason.
-After the callback is invoked, the input context will be freed by Xlib.
-The generic prototype is as follows:
-.IN "DestroyCallback" "" "@DEF@"
-.sM
-.FD 0
-void DestroyCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
-.br
-      XIC \fIic\fP\^;
-.br
-      XPointer \fIclient_data\fP\^;
-.br
-      XPointer \fIcall_data\fP\^;
-.FN
-.IP \fIic\fP 1i
-Specifies the input context.
-.IP \fIclient_data\fP 1i
-Specifies the additional client data.
-.IP \fIcall_data\fP 1i
-Not used for this callback and always passed as NULL.
-.LP
-.eM
-The callback is called with a NULL call_data argument.
-.NH 4
-String Conversion Callback
-.XS
-\*(SN String Conversion Callback
-.XE
-.LP
-The string conversion callback is triggered by the input method 
-to request the client to return the string to be converted.  The
-returned string may be either a multibyte or wide character string,
-with an encoding matching the locale bound to the input context.
-The callback prototype is as follows:
-.IN "StringConversionCallback" "" "@DEF@"
-.sM
-.FD 0
-void StringConversionCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
-.br
-      XIC \fIic\fP\^;
-.br
-      XPointer \fIclient_data\fP\^;
-.br
-      XIMStringConversionCallbackStruct *\fIcall_data\fP\^;
-.FN
-.IP \fIic\fP 1i
-Specifies the input method.
-.IP \fIclient_data\fP 1i
-Specifies the additional client data.
-.IP \fIcall_data\fP 1i
-Specifies the amount of the string to be converted.
-.LP
-.eM
-The callback is passed an
-.PN XIMStringConversionCallbackStruct
-structure in the call_data argument.
-The text member is an
-.PN XIMStringConversionText
-structure (see section 13.5.6.9) to be filled in by the client
-and describes the text to be sent to the input method.
-The data pointed to by the 
-string and feedback elements of the
-.PN XIMStringConversionText
-structure will be freed using
-.PN XFree
-by the input method
-after the callback returns.  So the client should not point to 
-internal buffers that are critical to the client.
-Similarly, because the feedback element is currently reserved for future
-use, the client should set feedback to NULL to prevent the library from
-freeing memory at some random location due to an uninitialized pointer.
-.LP
-The 
-.PN XIMStringConversionCallbackStruct
-structure is defined as follows:
-.LP
-.IN "XIMStringConversionCallbackStruct" "" "@DEF@"
-.sM
-.LP
-.Ds 0
-typedef struct _XIMStringConversionCallbackStruct {
-	XIMStringConversionPosition position;		
-	XIMCaretDirection direction;
-	short factor;
-	XIMStringConversionOperation operation;
-	XIMStringConversionText *text;
-} XIMStringConversionCallbackStruct;
-
-typedef short XIMStringConversionPosition;
-
-typedef unsigned short XIMStringConversionOperation;
-
-.De
-.LP
-.TS
-lw(.5i) lw(3i) lw(2i).
-T{
-#define
-T}	T{
-.PN XIMStringConversionSubstitution
-T}	T{
-(0x0001)
-T}
-T{
-#define
-T}	T{
-.PN XIMStringConversionRetrieval
-T}	T{
-(0x0002)
-T}
-.TE
-.LP
-.eM
-.PN XIMStringConversionPosition
-specifies the starting position of the string to be returned
-in the
-.PN XIMStringConversionText
-structure.  The value identifies a position, in units of characters,
-relative to the client's cursor position in the client's buffer.
-.LP
-The ending position of the text buffer is determined by
-the direction and factor members.  Specifically, it is the character position 
-relative to the starting point as defined by the
-.PN XIMCaretDirection .
-The factor member of 
-.PN XIMStringConversionCallbackStruct 
-specifies the number of
-.PN XIMCaretDirection 
-positions to be applied.  For example, if the direction specifies
-.PN XIMLineEnd
-and factor is 1, then all characters from the starting position to 
-the end of the current display line are returned.  If the direction
-specifies
-.PN XIMForwardChar
-or
-.PN XIMBackwardChar ,
-then the factor specifies a relative position, indicated in characters, 
-from the starting position.
-.LP
-.PN XIMStringConversionOperation
-specifies whether the string to be converted should be 
-deleted (substitution) or copied (retrieval) from the client's
-buffer.  When the
-.PN XIMStringConversionOperation
-is
-.PN XIMStringConversionSubstitution ,
-the client must delete the string to be converted from its own buffer.
-When the
-.PN XIMStringConversionOperation
-is
-.PN XIMStringConversionRetrieval ,
-the client must not delete the string to be converted from its buffer.
-The substitute operation is typically used for reconversion and
-transliteration conversion,
-while the retrieval operation is typically used for context-sensitive 
-conversion.
-.NH 4
-Preedit State Callbacks
-.XS
-\*(SN Preedit State Callbacks
-.XE
-.LP
-When the input method turns preediting on or off, a
-.PN PreeditStartCallback
-or
-.PN PreeditDoneCallback
-callback is triggered to let the toolkit do the setup
-or the cleanup for the preedit region.
-.IN "PreeditStartCallback" "" "@DEF@"
-.sM
-.FD 0
-int PreeditStartCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
-.br
-      XIC \fIic\fP\^;
-.br
-      XPointer \fIclient_data\fP\^;
-.br
-      XPointer \fIcall_data\fP\^;
-.FN
-.IP \fIic\fP 1i
-Specifies the input context.
-.IP \fIclient_data\fP 1i
-Specifies the additional client data.
-.IP \fIcall_data\fP 1i
-Not used for this callback and always passed as NULL.
-.LP
-.eM
-When preedit starts on the specified input context,
-the callback is called with a NULL call_data argument.
-.PN PreeditStartCallback
-will return the maximum size of the preedit string.
-A positive number indicates the maximum number of bytes allowed
-in the preedit string, 
-and a value of \-1 indicates there is no limit.
-.IN "PreeditDoneCallback" "" "@DEF@"
-.sM
-.FD 0
-void PreeditDoneCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
-.br
-      XIC \fIic\fP\^;
-.br
-      XPointer \fIclient_data\fP\^;
-.br
-      XPointer \fIcall_data\fP\^;
-.FN
-.IP \fIic\fP 1i
-Specifies the input context.
-.IP \fIclient_data\fP 1i
-Specifies the additional client data.
-.IP \fIcall_data\fP 1i
-Not used for this callback and always passed as NULL.
-.LP
-.eM
-When preedit stops on the specified input context,
-the callback is called with a NULL call_data argument.
-The client can release the data allocated by
-.PN PreeditStartCallback .
-.LP
-.PN PreeditStartCallback
-should initialize appropriate data needed for
-displaying preedit information and for handling further 
-.PN PreeditDrawCallback
-calls.
-Once
-.PN PreeditStartCallback
-is called, it will not be called again before
-.PN PreeditDoneCallback
-has been called.
-.NH 4
-Preedit Draw Callback
-.XS
-\*(SN Preedit Draw Callback
-.XE
-.LP
-This callback is triggered to draw and insert, delete or replace,
-preedit text in the preedit region.
-The preedit text may include unconverted input text such as Japanese Kana,
-converted text such as Japanese Kanji characters, or characters of both kinds.
-That string is either a multibyte or wide character string, 
-whose encoding matches the locale bound to the input context.
-The callback prototype
-is as follows:
-.IN "PreeditDrawCallback" "" "@DEF@"
-.sM
-.FD 0
-void PreeditDrawCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
-.br
-      XIC \fIic\fP\^;
-.br
-      XPointer \fIclient_data\fP\^;
-.br
-      XIMPreeditDrawCallbackStruct *\fIcall_data\fP\^;
-.FN
-.IP \fIic\fP 1i
-Specifies the input context.
-.IP \fIclient_data\fP 1i
-Specifies the additional client data.
-.IP \fIcall_data\fP 1i
-Specifies the preedit drawing information.
-.LP
-.eM
-The callback is passed an 
-.PN XIMPreeditDrawCallbackStruct
-structure in the call_data argument.
-The text member of this structure contains the text to be drawn.
-After the string has been drawn,
-the caret should be moved to the specified location.
-.LP
-The 
-.PN XIMPreeditDrawCallbackStruct
-structure is defined as follows:
-.LP
-.IN "XIMPreeditDrawCallbackStruct" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct _XIMPreeditDrawCallbackStruct {
-	int caret;	/* Cursor offset within preedit string */
-	int chg_first;	/* Starting change position */
-	int chg_length;	/* Length of the change in character count */
-	XIMText *text;
-} XIMPreeditDrawCallbackStruct;
-.De
-.LP
-.eM
-The client must keep updating a buffer of the preedit text
-and the callback arguments referring to indexes in that buffer.
-The call_data fields have specific meanings according to the operation,
-as follows:
-.IP \(bu 5
-To indicate text deletion, 
-the call_data member specifies a NULL text field.
-The text to be deleted is then the current text in the buffer 
-from position chg_first (starting at zero) on a character length
-of chg_length.
-.IP \(bu 5
-When text is non-NULL,
-it indicates insertion or replacement of text in the buffer.
-.IP
-The chg_length member
-identifies the number of characters in the current preedit buffer
-that are affected by this call.
-A positive chg_length indicates that chg_length number of characters, starting
-at chg_first, must be deleted or must be replaced by text, whose length is
-specified in the
-.PN XIMText
-structure.
-.IP
-A chg_length value of zero indicates that text must be inserted
-right at the position specified by chg_first.
-A value of zero for chg_first specifies the first character in the buffer.
-.IP
-chg_length and chg_first combine to identify the modification required to
-the preedit buffer; beginning at chg_first, replace chg_length number of
-characters with the text in the supplied
-.PN XIMText
-structure. For example, suppose the preedit buffer contains the string "ABCDE".
-.IP
-.DS I
-.ft C
-Text:      A B C D E
-          ^ ^ ^ ^ ^ ^
-CharPos:  0 1 2 3 4 5
-.sp
-.ft P
-.DE
-The CharPos in the diagram shows the location of the character position
-relative to the character.
-.IP
-If the value of chg_first is 1 and the value of chg_length is 3, this
-says to replace 3 characters beginning at character position 1 with the
-string in the
-.PN XIMText
-structure.
-Hence, BCD would be replaced by the value in the structure.
-.IP
-Though chg_length and chg_first are both signed integers they will
-never have a negative value.
-.IP \(bu 5
-The caret member
-identifies the character position before which the cursor should
-be placed \- after modification to the preedit buffer has been completed.
-For example, if caret is zero, the cursor is at
-the beginning of the buffer.  If the caret is one, the cursor is between
-the first and second character.
-.LP
-.IN "XIMText" "" @DEF@"
-.sM
-.Ds
-.TA .5i 1.5i 3i
-typedef struct _XIMText {
-	unsigned short length;
-	XIMFeedback * feedback;
-	Bool encoding_is_wchar; 
-	union {
-		char * multi_byte;
-		wchar_t * wide_char;
-	} string; 
-} XIMText;
-.De
-.LP
-.eM
-The text string passed is actually a structure specifying as follows:
-.IP \(bu 5
-The length member is the text length in characters.
-.IP \(bu 5
-The encoding_is_wchar member is a value that indicates 
-if the text string is encoded in wide character or multibyte format.
-The text string may be passed either as multibyte or as wide character;
-the input method controls in which form data is passed.
-The client's
-callback routine must be able to handle data passed in either form.
-.IP \(bu 5
-The string member is the text string.
-.IP \(bu 5
-The feedback member indicates rendering type for each character in the
-string member.
-If string is NULL (indicating that only highlighting of the existing
-preedit buffer should be updated), feedback points to length highlight
-elements that should be applied to the existing preedit buffer, beginning
-at chg_first.
-.LP
-The feedback member expresses the types of rendering feedback
-the callback should apply when drawing text.
-Rendering of the text to be drawn is specified either in generic ways
-(for example, primary, secondary) or in specific ways (reverse, underline).
-When generic indications are given,
-the client is free to choose the rendering style.
-It is necessary, however, that primary and secondary be mapped 
-to two distinct rendering styles.
-.LP
-If an input method wants to control display of the preedit string, an 
-input method can indicate the visibility hints using feedbacks in
-a specific way.
-The 
-.PN XIMVisibleToForward ,
-.PN XIMVisibleToBackward ,
-and
-.PN XIMVisibleCenter
-masks are exclusively used for these visibility hints.
-The 
-.PN XIMVisibleToForward
-mask
-indicates that the preedit text is preferably displayed in the
-primary draw direction from the
-caret position in the preedit area forward.
-The 
-.PN XIMVisibleToBackward
-mask
-indicates that the preedit text is preferably displayed from
-the caret position in the preedit area backward, relative to the primary
-draw direction.
-The 
-.PN XIMVisibleCenter
-mask
-indicates that the preedit text is preferably displayed with
-the caret position in the preedit area centered.
-.LP
-The insertion point of the preedit string could exist outside of
-the visible area when visibility hints are used.
-Only one of the 
-masks
-is valid for the entire preedit string, and only one character
-can hold one of these feedbacks for a given input context at one time.
-This feedback may be OR'ed together with another highlight (such as
-.PN XIMReverse ).
-Only the most recently set feedback is valid, and any previous
-feedback is automatically canceled.  This is a hint to the client, and
-the client is free to choose how to display the preedit string.
-.LP
-The feedback member also specifies how rendering of the text argument
-should be performed.
-If the feedback is NULL,
-the callback should apply the same feedback as is used for the surrounding
-characters in the preedit buffer; if chg_first is at a highlight boundary,
-the client can choose which of the two highlights to use.
-If feedback is not NULL, feedback specifies an array defining the
-rendering for each
-character of the string, and the length of the array is thus length.
-.LP
-If an input method wants to indicate that it is only updating the feedback of
-the preedit text without changing the content of it, 
-the
-.PN XIMText
-structure will contain a NULL value for the string field,
-the number of characters affected (relative to chg_first)
-will be in the length field,
-and the feedback field will point to an array of 
-.PN XIMFeedback .
-.LP
-Each element in the feedback array is a bitmask represented by a value of type
-.PN XIMFeedback .
-The valid mask names are as follows:
-.LP
-.IN "XIMReverse" "" "@DEF@"
-.IN "XIMUnderline" "" "@DEF@"
-.IN "XIMHighlight" "" "@DEF@"
-.IN "XIMPrimary" "" "@DEF@"
-.IN "XIMSecondary" "" "@DEF@"
-.IN "XIMTertiary" "" "@DEF@"
-.IN "XIMVisibleToForward" "" "@DEF@"
-.IN "XIMVisibleToBackward" "" "@DEF@"
-.IN "XIMVisibleCenter" "" "@DEF@"
-.sM
-.LP
-.Ds 0
-typedef unsigned long XIMFeedback;
-.De
-.TS
-lw(.5i) lw(2i) lw(2i).
-T{
-#define
-T}	T{
-.PN XIMReverse
-T}	T{
-1L
-T}
-T{
-#define
-T}	T{
-.PN XIMUnderline
-T}	T{
-(1L<<1) 
-T}
-T{
-#define
-T}	T{
-.PN XIMHighlight
-T}	T{
-(1L<<2)
-T}
-T{
-#define
-T}	T{
-.PN XIMPrimary
-T}	T{
-(1L<<5)\(dg
-T}
-T{
-#define
-T}	T{
-.PN XIMSecondary
-T}	T{
-(1L<<6)\(dg
-T}
-T{
-#define
-T}	T{
-.PN XIMTertiary
-T}	T{
-(1L<<7)\(dg
-T}
-T{
-#define
-T}	T{
-.PN XIMVisibleToForward
-T}	T{
-(1L<<8)
-T}
-T{
-#define
-T}	T{
-.PN XIMVisibleToBackward
-T}	T{
-(1L<<9)
-T}
-T{
-#define
-T}	T{
-.PN XIMVisibleCenter
-T}	T{
-(1L<<10)
-T}
-.TE
-.LP
-.eM
-.LP
-Characters drawn with the
-.PN XIMReverse
-highlight should be drawn by swapping the foreground and background colors
-used to draw normal, unhighlighted characters.
-Characters drawn with the
-.PN XIMUnderline
-highlight should be underlined.
-Characters drawn with the
-.PN XIMHighlight ,
-.PN XIMPrimary ,
-.PN XIMSecondary ,
-and
-.PN XIMTertiary
-highlights should be drawn in some unique manner that must be different
-from
-.PN XIMReverse
-and
-.PN XIMUnderline .
-.FS \(dg
-The values for
-.PN XIMPrimary ,
-.PN XIMSecondary ,
-and
-.PN XIMTertiary
-were incorrectly defined in the R5 specification.
-The X Consortium's X11R5
-implementation correctly implemented the values for these highlights.
-The value of these highlights has been corrected in this specification
-to agree with the values in the Consortium's X11R5 and X11R6 implementations.
-.FE
-.NH 4
-Preedit Caret Callback
-.XS
-\*(SN Preedit Caret Callback
-.XE
-.LP
-An input method may have its own navigation keys to allow the user
-to move the text insertion point in the preedit area 
-(for example, to move backward or forward). 
-Consequently, input method needs to indicate to the client that it
-should move the text insertion point.
-It then calls the PreeditCaretCallback.
-.IN "PreeditCaretCallback" "" "@DEF@"
-.sM
-.FD 0
-void PreeditCaretCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
-.br
-      XIC \fIic\fP\^;
-.br
-      XPointer \fIclient_data\fP\^;
-.br
-      XIMPreeditCaretCallbackStruct *\fIcall_data\fP\^;
-.FN
-.IP \fIic\fP 1i
-Specifies the input context.
-.IP \fIclient_data\fP 1i
-Specifies the additional client data.
-.IP \fIcall_data\fP 1i
-Specifies the preedit caret information.
-.LP
-.eM
-The input method will trigger PreeditCaretCallback
-to move the text insertion point during preedit.
-The call_data argument contains a pointer to an 
-.PN XIMPreeditCaretCallbackStruct
-structure,
-which indicates where the caret should be moved.
-The callback must move the insertion point to its new location
-and return, in field position, the new offset value from the initial position.  
-.LP
-The
-.PN XIMPreeditCaretCallbackStruct
-structure is defined as follows:
-.IN "XIMPreeditCaretCallbackStruct" "" "@DEF@"
-.LP
-.sM
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct _XIMPreeditCaretCallbackStruct {
-	int position;	/* Caret offset within preedit string */
-	XIMCaretDirection direction;	/* Caret moves direction */
-	XIMCaretStyle style;	/* Feedback of the caret */
-} XIMPreeditCaretCallbackStruct;
-.De
-.LP
-.eM
-The
-.PN XIMCaretStyle
-structure is defined as follows:
-.LP
-.IN "XIMCaretStyle" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef enum {
-	XIMIsInvisible,	/* Disable caret feedback */ 
-	XIMIsPrimary,	/* UI defined caret feedback */
-	XIMIsSecondary,	/* UI defined caret feedback */
-} XIMCaretStyle;
-.De
-.LP
-.eM
-The
-.PN XIMCaretDirection
-structure is defined as follows:
-.IN "XIMCaretDirection" "" "@DEF@"
-.LP
-.sM
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef enum {
-	XIMForwardChar, XIMBackwardChar,
-	XIMForwardWord, XIMBackwardWord,
-	XIMCaretUp, XIMCaretDown,
-	XIMNextLine, XIMPreviousLine,
-	XIMLineStart, XIMLineEnd, 
-	XIMAbsolutePosition,
-	XIMDontChange,
- } XIMCaretDirection;
-.De
-.LP
-.eM
-These values are defined as follows:
-.IN "XIMForwardChar" "" "@DEF@"
-.IN "XIMBackwardChar" "" "@DEF@"
-.IN "XIMForwardWord" "" "@DEF@"
-.IN "XIMBackwardWord" "" "@DEF@"
-.IN "XIMCaretUp" "" "@DEF@"
-.IN "XIMCaretDown" "" "@DEF@"
-.TS
-lw(1.5i) lw(4.25i).
-T{
-.PN XIMForwardChar
-T}	T{
-Move the caret forward one character position.
-T}
-T{
-.PN XIMBackwardChar
-T}	T{
-Move the caret backward one character position.
-T}
-T{
-.PN XIMForwardWord
-T}	T{
-Move the caret forward one word.
-T}
-T{
-.PN XIMBackwardWord
-T}	T{
-Move the caret backward one word.
-T}
-T{
-.PN XIMCaretUp
-T}	T{
-Move the caret up one line keeping the current horizontal offset.
-T}
-T{
-.PN XIMCaretDown
-T}	T{
-Move the caret down one line keeping the current horizontal offset.
-T}
-T{
-.PN XIMPreviousLine
-T}	T{
-Move the caret to the beginning of the previous line.
-T}
-T{
-.PN XIMNextLine
-T}	T{
-Move the caret to the beginning of the next line.
-T}
-T{
-.PN XIMLineStart
-T}	T{
-Move the caret to the beginning of the current display line 
-that contains the caret.
-T}
-T{
-.PN XIMLineEnd
-T}	T{
-Move the caret to the end of the current display line 
-that contains the caret.
-T}
-T{
-.PN XIMAbsolutePosition
-T}	T{
-The callback must move to the location specified by the position field
-of the callback data, indicated in characters, starting from the beginning
-of the preedit text.
-Hence, a value of zero means move back to the beginning of the preedit text.
-T}
-T{
-.PN XIMDontChange
-T}	T{
-The caret position does not change.
-T}
-.TE
-.IN "XIMNextLine" "" "@DEF@"
-.IN "XIMPreviousLine" "" "@DEF@"
-.IN "XIMLineStart" "" "@DEF@"
-.IN "XIMLineEnd" "" "@DEF@"
-.IN "XIMAbsolutePosition" "" "@DEF@"
-.IN "XIMDontChange" "" "@DEF@"
-.NH 4
-Status Callbacks
-.XS
-\*(SN Status Callbacks
-.XE
-.LP
-An input method may communicate changes in the status of an input context
-(for example, created, destroyed, or focus changes) with three status
-callbacks:  StatusStartCallback, StatusDoneCallback, and StatusDrawCallback.
-.LP
-.sp
-When the input context is created or gains focus, 
-the input method calls the StatusStartCallback callback.
-.IN "StatusStartCallback" "" "@DEF@"
-.sM
-.FD 0
-void StatusStartCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
-.br
-      XIC \fIic\fP\^;
-.br
-      XPointer \fIclient_data\fP\^;
-.br
-      XPointer \fIcall_data\fP\^;
-.FN
-.IP \fIic\fP 1i
-Specifies the input context.
-.IP \fIclient_data\fP 1i
-Specifies the additional client data.
-.IP \fIcall_data\fP 1i
-Not used for this callback and always passed as NULL.
-.LP
-.eM
-The callback should initialize appropriate data for displaying status
-and for responding to StatusDrawCallback calls.  
-Once StatusStartCallback is called,
-it will not be called again before StatusDoneCallback has been called.
-.LP
-.sp
-When an input context
-is destroyed or when it loses focus, the input method calls StatusDoneCallback.
-.IN "StatusDoneCallback" "" "@DEF@"
-.sM
-.FD 0
-void StatusDoneCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
-.br
-      XIC \fIic\fP\^;
-.br
-      XPointer \fIclient_data\fP\^;
-.br
-      XPointer \fIcall_data\fP\^;
-.FN
-.IP \fIic\fP 1i
-Specifies the input context.
-.IP \fIclient_data\fP 1i
-Specifies the additional client data.
-.IP \fIcall_data\fP 1i
-Not used for this callback and always passed as NULL.
-.LP
-.eM
-The callback may release any data allocated on 
-.PN StatusStart .
-.LP
-.sp
-When an input context status has to be updated, the input method calls
-StatusDrawCallback.
-.IN "StatusDrawCallback" "" "@DEF@"
-.sM
-.FD 0
-void StatusDrawCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
-.br
-      XIC \fIic\fP\^;
-.br
-      XPointer \fIclient_data\fP\^;
-.br
-      XIMStatusDrawCallbackStruct *\fIcall_data\fP\^;
-.FN
-.IP \fIic\fP 1i
-Specifies the input context.
-.IP \fIclient_data\fP 1i
-Specifies the additional client data.
-.IP \fIcall_data\fP 1i
-Specifies the status drawing information.
-.LP
-.eM
-The callback should update the status area by either drawing a string
-or imaging a bitmap in the status area.
-.LP
-The
-.PN XIMStatusDataType
-and
-.PN XIMStatusDrawCallbackStruct
-structures are defined as follows:
-.IN "XIMStatusDataType" "" "@DEF@"
-.IN "XIMStatusDrawCallbackStruct" "" "@DEF@"
-.LP
-.sM
-.Ds 0
-.TA .5i 1i 3i
-.ta .5i 1i 3i
-typedef enum {
-	XIMTextType,
-	XIMBitmapType,
-} XIMStatusDataType;
-
-typedef struct _XIMStatusDrawCallbackStruct {
-	XIMStatusDataType type;
-	union {
-		XIMText *text;
-		Pixmap  bitmap;
-	} data;
-} XIMStatusDrawCallbackStruct;
-.De
-.LP
-.eM
-.LP
-The feedback styles
-.PN XIMVisibleToForward ,
-.PN XIMVisibleToBackward ,
-and
-.PN XIMVisibleToCenter
-are not relevant and will not appear in the
-.PN XIMFeedback
-element of the
-.PN XIMText
-structure.
-.LP
-.NH 3
-Event Filtering
-.XS
-\*(SN Event Filtering
-.XE
-.LP
-Xlib provides the ability for an input method
-to register a filter internal to Xlib.
-This filter is called by a client (or toolkit) by calling
-.PN XFilterEvent
-after calling 
-.PN XNextEvent .
-Any client that uses the 
-.PN XIM
-interface should call
-.PN XFilterEvent
-to allow input methods to process their events without knowledge
-of the client's dispatching mechanism.
-A client's user interface policy may determine the priority
-of event filters with respect to other event-handling mechanisms
-(for example, modal grabs).
-.LP
-Clients may not know how many filters there are, if any,
-and what they do.
-They may only know if an event has been filtered on return of 
-.PN XFilterEvent .
-Clients should discard filtered events.
-.sp
-.LP
-To filter an event, use
-.PN XFilterEvent .
-.IN "XFilterEvent" "" "@DEF@"
-.sM
-.FD 0
-Bool XFilterEvent\^(\^\fIevent\fP\^, \fIw\fP\^)
-.br
-      XEvent *\fIevent\fP\^;
-.br
-      Window \fIw\fP\^;
-.FN
-.ds Ev event to filter
-.IP \fIevent\fP 1i
-Specifies the \*(Ev.
-.ds Wi for which the filter is to be applied
-.IP \fIw\fP 1i
-Specifies the window \*(Wi.
-.LP
-.eM
-If the window argument is
-.PN None ,
-.PN XFilterEvent 
-applies the filter to the window specified in the
-.PN XEvent
-structure.
-The window argument is provided so that layers above Xlib
-that do event redirection can indicate to which window an event
-has been redirected.
-.LP
-If
-.PN XFilterEvent
-returns
-.PN True ,
-then some input method has filtered the event,
-and the client should discard the event.
-If
-.PN XFilterEvent
-returns
-.PN False ,
-then the client should continue processing the event.
-.LP
-If a grab has occurred in the client and
-.PN XFilterEvent
-returns
-.PN True ,
-the client should ungrab the keyboard.
-.NH 3
-Getting Keyboard Input
-.XS
-\*(SN Getting Keyboard Input
-.XE
-.LP
-To get composed input from an input method,
-use
-.PN XmbLookupString
-or
-.PN XwcLookupString .
-.IN "XmbLookupString" "" "@DEF@"
-.IN "XwcLookupString" "" "@DEF@"
-.sM
-.FD 0
-int XmbLookupString\^(\^\fIic\fP\^, \fIevent\fP\^, \fIbuffer_return\fP\^, \fIbytes_buffer\fP\^, \fIkeysym_return\fP\^, \fIstatus_return\fP\^)
-.br
-      XIC \fIic\fP\^;
-.br
-      XKeyPressedEvent *\fIevent\fP;
-.br
-      char *\fIbuffer_return\fP\^;
-.br
-      int \fIbytes_buffer\fP\^;
-.br
-      KeySym *\fIkeysym_return\fP\^;
-.br
-      Status *\fIstatus_return\fP\^;
-.FN
-.FD 0
-int XwcLookupString\^(\^\fIic\fP\^, \fIevent\fP\^, \fIbuffer_return\fP\^, \fIbytes_buffer\fP\^, \fIkeysym_return\fP\^, \fIstatus_return\fP\^)
-.br
-      XIC \fIic\fP\^;
-.br
-      XKeyPressedEvent *\fIevent\fP\^;
-.br
-      wchar_t *\fIbuffer_return\fP\^;
-.br
-      int \fIwchars_buffer\fP\^;
-.br
-      KeySym *\fIkeysym_return\fP\^;
-.br
-      Status *\fIstatus_return\fP\^;
-.FN
-.IP \fIic\fP 1i
-Specifies the input context.
-.ds Ev key event to be used
-.IP \fIevent\fP 1i
-Specifies the \*(Ev.
-.IP \fIbuffer_return\fP 1i
-Returns a multibyte string or wide character string (if any)
-from the input method.
-.IP \fIbytes_buffer\fP 1i
-.br
-.ns
-.IP \fIwchars_buffer\fP 1i
-Specifies space available in the return buffer.
-.IP \fIkeysym_return\fP 1i
-Returns the KeySym computed from the event if this argument is not NULL.
-.IP \fIstatus_return\fP 1i
-Returns a value indicating what kind of data is returned.
-.LP
-.eM
-The
-.PN XmbLookupString
-and
-.PN XwcLookupString
-functions return the string from the input method specified
-in the buffer_return argument.
-If no string is returned,
-the buffer_return argument is unchanged.
-.LP
-The KeySym into which the KeyCode from the event was mapped is returned
-in the keysym_return argument if it is non-NULL and the status_return
-argument indicates that a KeySym was returned.
-If both a string and a KeySym are returned,
-the KeySym value does not necessarily correspond to the string returned.
-.LP
-.PN XmbLookupString
-returns the length of the string in bytes, and
-.PN XwcLookupString
-returns the length of the string in characters.
-Both
-.PN XmbLookupString
-and
-.PN XwcLookupString
-return text in the encoding of the locale bound to the input method
-of the specified input context.
-.LP
-Each string returned by
-.PN XmbLookupString
-and
-.PN XwcLookupString
-begins in the initial state of the encoding of the locale
-(if the encoding of the locale is state-dependent).
-.NT
-To insure proper input processing,
-it is essential that the client pass only 
-.PN KeyPress
-events to
-.PN XmbLookupString
-and
-.PN XwcLookupString .
-Their behavior when a client passes a 
-.PN KeyRelease
-event is undefined.
-.NE
-.LP
-Clients should check the status_return argument before
-using the other returned values.
-These two functions both return a value to status_return 
-that indicates what has been returned in the other arguments.
-The possible values returned are:
-.TS
-lw(1.5i) lw(4.3i).
-T{
-.PN XBufferOverflow
-T}	T{
-The input string to be returned is too large for the supplied buffer_return.
-The required size
-.Pn ( XmbLookupString
-in bytes;
-.PN XwcLookupString
-in characters) is returned as the value of the function,
-and the contents of buffer_return and keysym_return are not modified.
-The client should recall the function with the same event
-and a buffer of adequate size to obtain the string.
-T}
-T{
-.PN XLookupNone
-T}	T{
-No consistent input has been composed so far.
-The contents of buffer_return and keysym_return are not modified, 
-and the function returns zero.
-T}
-T{
-.PN XLookupChars
-T}	T{
-Some input characters have been composed.
-They are placed in the buffer_return argument,
-and the string length is returned as the value of the function.
-The string is encoded in the locale bound to the input context.
-The content of the keysym_return argument is not modified.
-T}
-T{
-.PN XLookupKeySym
-T}	T{
-A KeySym has been returned instead of a string
-and is returned in keysym_return.
-The content of the buffer_return argument is not modified,
-and the function returns zero.
-T}
-T{
-.PN XLookupBoth
-T}	T{
-Both a KeySym and a string are returned;
-.PN XLookupChars
-and
-.PN XLookupKeySym
-occur simultaneously.
-T}
-.TE
-.LP
-It does not make any difference if the input context passed as an argument to
-.PN XmbLookupString
-and
-.PN XwcLookupString
-is the one currently in possession of the focus or not.
-Input may have been composed within an input context before it lost the focus,
-and that input may be returned on subsequent calls to
-.PN XmbLookupString
-or
-.PN XwcLookupString
-even though it does not have any more keyboard focus.
-.NH 3
-Input Method Conventions
-.XS
-\*(SN Input Method Conventions
-.XE
-.LP
-The input method architecture is transparent to the client.
-However, clients should respect a number of conventions in order
-to work properly.
-Clients must also be aware of possible effects of synchronization
-between input method and library in the case of a remote input server.
-.NH 4 
-Client Conventions
-.XS
-\*(SN Client Conventions
-.XE
-.LP
-A well-behaved client (or toolkit) should first query the input method style.
-If the client cannot satisfy the requirements of the supported styles
-(in terms of geometry management or callbacks),
-it should negotiate with the user continuation of the program
-or raise an exception or error of some sort.
-.NH 4 
-Synchronization Conventions
-.XS
-\*(SN Synchronization Conventions
-.XE
-.LP
-A 
-.PN KeyPress
-event with a KeyCode of zero is used exclusively as a
-signal that an input method has composed input that can be returned by
-.PN XmbLookupString
-or
-.PN XwcLookupString .
-No other use is made of a 
-.PN KeyPress
-event with KeyCode of zero.
-.LP
-Such an event may be generated by either a front-end
-or a back-end input method in an implementation-dependent manner.
-Some possible ways to generate this event include:
-.IP \(bu 5
-A synthetic event sent by an input method server
-.IP \(bu 5
-An artificial event created by a input method filter and pushed
-onto a client's event queue
-.IP \(bu 5
-A 
-.PN KeyPress
-event whose KeyCode value is modified by an input method filter
-.LP
-When callback support is specified by the client,
-input methods will not take action unless they explicitly
-called back the client and obtained no response
-(the callback is not specified or returned invalid data).
-.NH 2
-String Constants
-.XS
-\*(SN String Constants
-.XE
-.LP
-The following symbols for string constants are defined in
-.hN X11/Xlib.h .
-Although they are shown here with particular macro definitions,
-they may be implemented as macros, as global symbols, or as a
-mixture of the two.  The string pointer value itself
-is not significant; clients must not assume that inequality of two
-values implies inequality of the actual string data.
-.IN "XNVaNestedList" "" "@DEF@"
-.IN "XNSeparatorofNestedList "" "@DEF@"
-.IN "XNQueryInputStyle" "" "@DEF@"
-.IN "XNClientWindow" "" "@DEF@"
-.IN "XNInputStyle" "" "@DEF@"
-.IN "XNFocusWindow" "" "@DEF@"
-.IN "XNResourceName" "" "@DEF@"
-.IN "XNResourceClass" "" "@DEF@"
-.IN "XNGeometryCallback" "" "@DEF@"
-.IN "XNDestroyCallback" "" "@DEF@"
-.IN "XNFilterEvents" "" "@DEF@"
-.IN "XNPreeditStartCallback" "" "@DEF@"
-.IN "XNPreeditDoneCallback" "" "@DEF@"
-.IN "XNPreeditDrawCallback" "" "@DEF@"
-.IN "XNPreeditCaretCallback" "" "@DEF@"
-.IN "XNPreeditStateNotifyCallback" "" "@DEF@"
-.IN "XNPreeditAttributes" "" "@DEF@"
-.IN "XNStatusStartCallback" "" "@DEF@"
-.IN "XNStatusDoneCallback" "" "@DEF@"
-.IN "XNStatusDrawCallback" "" "@DEF@"
-.IN "XNStatusAttributes" "" "@DEF@"
-.IN "XNArea" "" "@DEF@"
-.IN "XNAreaNeeded" "" "@DEF@"
-.IN "XNSpotLocation" "" "@DEF@"
-.IN "XNColormap" "" "@DEF@"
-.IN "XNStdColormap" "" "@DEF@"
-.IN "XNForeground" "" "@DEF@"
-.IN "XNBackground" "" "@DEF@"
-.IN "XNBackgroundPixmap" "" "@DEF@"
-.IN "XNFontSet" "" "@DEF@"
-.IN "XNLineSpace" "" "@DEF@"
-.IN "XNCursor" "" "@DEF@"
-.TS
-lw(.5i) lw(2.75i) lw(2.5i).
-T{
-#define
-T}	T{
-.PN XNVaNestedList
-T}	T{
-"XNVaNestedList"
-T}
-T{
-#define
-T}	T{
-.PN XNSeparatorofNestedList
-T}	T{
-"separatorofNestedList"
-T}
-T{
-#define
-T}	T{
-.PN XNQueryInputStyle
-T}	T{
-"queryInputStyle"
-T}
-T{
-#define
-T}	T{
-.PN XNClientWindow
-T}	T{
-"clientWindow"
-T}
-T{
-#define
-T}	T{
-.PN XNInputStyle
-T}	T{
-"inputStyle"
-T}
-T{
-#define
-T}	T{
-.PN XNFocusWindow
-T}	T{
-"focusWindow"
-T}
-T{
-#define
-T}	T{
-.PN XNResourceName
-T}	T{
-"resourceName"
-T}
-T{
-#define
-T}	T{
-.PN XNResourceClass
-T}	T{
-"resourceClass"
-T}
-T{
-#define
-T}	T{
-.PN XNGeometryCallback
-T}	T{
-"geometryCallback"
-T}
-T{
-#define
-T}	T{
-.PN XNDestroyCallback
-T}	T{
-"destroyCallback"
-T}
-T{
-#define
-T}	T{
-.PN XNFilterEvents
-T}	T{
-"filterEvents"
-T}
-T{
-#define
-T}	T{
-.PN XNPreeditStartCallback
-T}	T{
-"preeditStartCallback"
-T}
-T{
-#define
-T}	T{
-.PN XNPreeditDoneCallback
-T}	T{
-"preeditDoneCallback"
-T}
-T{
-#define
-T}	T{
-.PN XNPreeditDrawCallback
-T}	T{
-"preeditDrawCallback"
-T}
-T{
-#define
-T}	T{
-.PN XNPreeditCaretCallback
-T}	T{
-"preeditCaretCallback"
-T}
-T{
-#define
-T}	T{
-.PN XNPreeditStateNotifyCallback
-T}	T{
-"preeditStateNotifyCallback"
-T}
-T{
-#define
-T}	T{
-.PN XNPreeditAttributes
-T}	T{
-"preeditAttributes"
-T}
-.TE
-.sp -1
-.TS
-lw(.5i) lw(2.75i) lw(2.5i).
-T{
-#define
-T}	T{
-.PN XNStatusStartCallback
-T}	T{
-"statusStartCallback"
-T}
-T{
-#define
-T}	T{
-.PN XNStatusDoneCallback
-T}	T{
-"statusDoneCallback"
-T}
-T{
-#define
-T}	T{
-.PN XNStatusDrawCallback
-T}	T{
-"statusDrawCallback"
-T}
-T{
-#define
-T}	T{
-.PN XNStatusAttributes
-T}	T{
-"statusAttributes"
-T}
-T{
-#define
-T}	T{
-.PN XNArea
-T}	T{
-"area"
-T}
-T{
-#define
-T}	T{
-.PN XNAreaNeeded
-T}	T{
-"areaNeeded"
-T}
-T{
-#define
-T}	T{
-.PN XNSpotLocation
-T}	T{
-"spotLocation"
-T}
-T{
-#define
-T}	T{
-.PN XNColormap
-T}	T{
-"colorMap"
-T}
-T{
-#define
-T}	T{
-.PN XNStdColormap
-T}	T{
-"stdColorMap"
-T}
-T{
-#define
-T}	T{
-.PN XNForeground
-T}	T{
-"foreground"
-T}
-T{
-#define
-T}	T{
-.PN XNBackground
-T}	T{
-"background"
-T}
-T{
-#define
-T}	T{
-.PN XNBackgroundPixmap
-T}	T{
-"backgroundPixmap"
-T}
-T{
-#define
-T}	T{
-.PN XNFontSet
-T}	T{
-"fontSet"
-T}
-T{
-#define
-T}	T{
-.PN XNLineSpace
-T}	T{
-"lineSpace"
-T}
-T{
-#define
-T}	T{
-.PN XNCursor
-T}	T{
-"cursor"
-T}
-.TE
-.sp -1
-.TS
-lw(.5i) lw(2.75i) lw(2.5i).
-T{
-#define
-T}	T{
-.PN XNQueryIMValuesList
-T}	T{
-"queryIMValuesList"
-T}	
-T{
-#define
-T}	T{
-.PN XNQueryICValuesList
-T}	T{
-"queryICValuesList"
-T}	
-T{
-#define
-T}	T{
-.PN XNStringConversionCallback
-T}	T{
-"stringConversionCallback"
-T}	
-T{
-#define
-T}	T{
-.PN XNStringConversion
-T}	T{
-"stringConversion"
-T}	
-T{
-#define
-T}	T{
-.PN XNResetState
-T}	T{
-"resetState"
-T}	
-T{
-#define
-T}	T{
-.PN XNHotKey
-T}	T{
-"hotkey"
-T}	
-T{
-#define
-T}	T{
-.PN XNHotKeyState
-T}	T{
-"hotkeyState"
-T}	
-T{
-#define
-T}	T{
-.PN XNPreeditState
-T}	T{
-"preeditState"
-T}
-T{
-#define
-T}	T{
-.PN XNVisiblePosition
-T}	T{
-"visiblePosition"
-T}
-T{
-#define
-T}	T{
-.PN XNR6PreeditCallbackBehavior
-T}	T{
-"r6PreeditCallback"
-T}
-.TE
-.sp -1
-.IN "XNQueryIMValuesList" "" "@DEF@"
-.IN "XNQueryICValuesList" "" "@DEF@"
-.IN "XNStringConversionCallback" "" "@DEF@"
-.IN "XNStringConversion" "" "@DEF@"
-.IN "XNResetState" "" "@DEF@"
-.IN "XNHotKey" "" "@DEF@"
-.IN "XNHotKeyState" "" "@DEF@"
-.IN "XNPreeditState" "" "@DEF@"
-.IN "XNVisiblePosition" "" "@DEF@"
-.IN "XNR6PreeditCallbackBehavior" "" "@DEF@"
-.TS
-lw(.5i) lw(2.75i) lw(2.5i).
-T{
-#define
-T}	T{
-.PN XNRequiredCharSet
-T}	T{
-"requiredCharSet"
-T}	
-T{
-#define
-T}	T{
-.PN XNQueryOrientation
-T}	T{
-"queryOrientation"
-T}
-T{
-#define
-T}	T{
-.PN XNDirectionalDependentDrawing
-T}	T{
-"directionalDependentDrawing"
-T}
-T{
-#define
-T}	T{
-.PN XNContextualDrawing
-T}	T{
-"contextualDrawing"
-T}
-T{
-#define
-T}	T{
-.PN XNBaseFontName
-T}	T{
-"baseFontName"
-T}	
-T{
-#define
-T}	T{
-.PN XNMissingCharSet
-T}	T{
-"missingCharSet"
-T}	
-T{
-#define
-T}	T{
-.PN XNDefaultString
-T}	T{
-"defaultString"
-T}	
-T{
-#define
-T}	T{
-.PN XNOrientation
-T}	T{
-"orientation"
-T}	
-T{
-#define
-T}	T{
-.PN XNFontInfo
-T}	T{
-"fontInfo"
-T}	
-T{
-#define
-T}	T{
-.PN XNOMAutomatic
-T}	T{
-"omAutomatic"
-T}
-.TE
-.IN "XNRequiredCharSet" "" "@DEF@"
-.IN "XNQueryOrientation" "" "@DEF@"
-.IN "XNDirectionalDependentDrawing" "" "@DEF@"
-.IN "XNContextualDrawing" "" "@DEF@"
-.IN "XNBaseFontName" "" "@DEF@"
-.IN "XNMissingCharSet" "" "@DEF@"
-.IN "XNDefaultString" "" "@DEF@"
-.IN "XNOrientation" "" "@DEF@"
-.IN "XNFontInfo" "" "@DEF@"
-.IN "XNOMAutomatic" "" "@DEF@"
-.bp
diff --git a/libX11/specs/libX11/CH13.xml b/libX11/specs/libX11/CH13.xml
new file mode 100644
index 000000000..06564c3da
--- /dev/null
+++ b/libX11/specs/libX11/CH13.xml
@@ -0,0 +1,10350 @@
+<chapter id="locales_and_internationalized_text_functions">

+<title>Locales and Internationalized Text Functions</title>

+

+<para>

+An internationalized application is one that is adaptable to the requirements of different native

+languages, local customs, and character string encodings. The process of adapting the operation

+to a particular native language, local custom, or string encoding is called localization. A goal of

+internationalization is to permit localization without program source modifications or recompila-

+tion.

+</para>

+<para>

+As one of the localization mechanisms, Xlib provides an X Input Method (<acronym>XIM</acronym>) functional inter-

+face for internationalized text input and an X Output Method (<acronym>XOM</acronym>) functional interface for

+internationalized text output.

+</para>

+<para>

+Internationalization in X is based on the concept of a locale. A locale defines the localized

+behavior of a program at run time. Locales affect Xlib in its:

+</para>

+

+<itemizedlist>

+  <listitem><para>Encoding and processing of input method text</para></listitem>

+  <listitem><para>Encoding of resource files and values</para></listitem>

+  <listitem><para>Encoding and imaging of text strings</para></listitem>

+  <listitem><para>Encoding and decoding for inter-client text communication</para></listitem>

+</itemizedlist>

+

+

+<para>

+•

+Encoding and decoding for inter-client text communication

+Characters from various languages are represented in a computer using an encoding. Different

+languages have different encodings, and there are even different encodings for the same charac-

+ters in the same language.

+</para>

+<para>

+This chapter defines support for localized text imaging and text input and describes the locale

+mechanism that controls all locale-dependent Xlib functions. Sets of functions are provided for

+multibyte (char *) text as well as wide character (wchar_t) text in the form supported by the host

+C language environment. The multibyte and wide character functions are equivalent except for

+the form of the text argument.

+</para>

+<para>

+The Xlib internationalization functions are not meant to provide support for multilingual applica-

+tions (mixing multiple languages within a single piece of text), but they make it possible to imple-

+ment applications that work in limited fashion with more than one language in independent con-

+texts.

+</para>

+<para>

+The remainder of this chapter discusses:

+</para>

+

+<itemizedlist>

+  <listitem><para>X locale management</para></listitem>

+  <listitem><para>Locale and modifier dependencies</para></listitem>

+  <listitem><para>Variable argument lists</para></listitem>

+  <listitem><para>Output methods</para></listitem>

+  <listitem><para>Input methods</para></listitem>

+  <listitem><para>String constants</para></listitem>

+</itemizedlist>

+

+

+<sect1 id="X_Locale_Management">

+<title>X Locale Management</title>

+<!-- .XS -->

+<!-- (SN X Locale Management -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+X supports one or more of the locales defined by the host environment.

+On implementations that conform to the ANSI C library,

+the locale announcement method is

+<function>setlocale</function>.

+This function configures the locale operation of both

+the host C library and Xlib.

+The operation of Xlib is governed by the LC_CTYPE category;

+this is called the <emphasis remap='I'>current locale</emphasis>.

+An implementation is permitted to provide implementation-dependent

+mechanisms for announcing the locale in addition to

+<function>setlocale</function>.

+</para>

+<para>

+<!-- .LP -->

+On implementations that do not conform to the ANSI C library, 

+the locale announcement method is Xlib implementation-dependent.

+</para>

+<para>

+<!-- .LP -->

+The mechanism by which the semantic operation of Xlib is defined

+for a specific locale is implementation-dependent.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+X is not required to support all the locales supported by the host.

+To determine if the current locale is supported by X, use

+<function>XSupportsLocale</function>.

+</para>

+

+<para>Bool XSupportsLocale()</para>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XSupportsLocale</function>

+function returns 

+<function>True</function>

+if Xlib functions are capable of operating under the current locale.

+If it returns 

+<function>False</function>,

+Xlib locale-dependent functions for which the 

+<function>XLocaleNotSupported </function>

+return status is defined will return 

+<function>XLocaleNotSupported</function>.

+Other Xlib locale-dependent routines will operate in the ``C'' locale.

+</para>

+<para>

+<!-- .LP -->

+The client is responsible for selecting its locale and X modifiers.

+Clients should provide a means for the user to override the clients'

+locale selection at client invocation.

+Most single-display X clients operate in a single locale 

+for both X and the host processing environment.

+They will configure the locale by calling three functions: 

+the host locale configuration function,

+<function>XSupportsLocale</function>,

+and 

+<function>XSetLocaleModifiers</function>.

+</para>

+<para>

+<!-- .LP -->

+The semantics of certain categories of X internationalization capabilities

+can be configured by setting modifiers.

+Modifiers are named by implementation-dependent and locale-specific strings.

+The only standard use for this capability at present

+is selecting one of several styles of keyboard input method.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To configure Xlib locale modifiers for the current locale, use

+<function>XSetLocaleModifiers</function>.

+<indexterm significance="preferred"><primary>XSetLocaleModifiers</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> *XSetLocaleModifiers</function></funcdef>

+  <paramdef>char<parameter> *modifier_list</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>modifier_list</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the modifiers.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetLocaleModifiers</function>

+function sets the X modifiers for the current locale setting.

+The modifier_list argument is a null-terminated string of the form

+``{@<emphasis remap='I'>category</emphasis>=<emphasis remap='I'>value</emphasis>}'', that is,

+having zero or more concatenated ``@<emphasis remap='I'>category</emphasis>=<emphasis remap='I'>value</emphasis>''

+entries, where <emphasis remap='I'>category</emphasis> is a category name 

+and <emphasis remap='I'>value</emphasis> is the (possibly empty) setting for that category.

+The values are encoded in the current locale.

+Category names are restricted to the <acronym>POSIX</acronym> Portable Filename Character Set.

+</para>

+<para>

+<!-- .LP -->

+The local host X locale modifiers announcer (on <acronym>POSIX</acronym>-compliant systems,

+the XMODIFIERS environment variable) is appended to the modifier_list to

+provide default values on the local host.

+If a given category appears more than once in the list,

+the first setting in the list is used.

+If a given category is not included in the full modifier list,

+the category is set to an implementation-dependent default

+for the current locale.

+An empty value for a category explicitly specifies the

+implementation-dependent default.

+</para>

+<para>

+<!-- .LP -->

+If the function is successful, it returns a pointer to a string.

+The contents of the string are such that a subsequent call with that string

+(in the same locale) will restore the modifiers to the same settings.

+If modifier_list is a NULL pointer,

+<function>XSetLocaleModifiers</function>

+also returns a pointer to such a string,

+and the current locale modifiers are not changed.

+</para>

+<para>

+<!-- .LP -->

+If invalid values are given for one or more modifier categories supported by

+the locale, a NULL pointer is returned, and none of the

+current modifiers are changed.

+</para>

+<para>

+<!-- .LP -->

+At program startup,

+the modifiers that are in effect are unspecified until

+the first successful call to set them.  Whenever the locale is changed, the

+modifiers that are in effect become unspecified until the next successful call

+to set them.

+Clients should always call

+<function>XSetLocaleModifiers</function>

+with a non-NULL modifier_list after setting the locale

+before they call any locale-dependent Xlib routine.

+</para>

+<para>

+<!-- .LP -->

+The only standard modifier category currently defined is ``im'',

+which identifies the desired input method.

+The values for input method are not standardized.

+A single locale may use multiple input methods,

+switching input method under user control.

+The modifier may specify the initial input method in effect

+or an ordered list of input methods.

+Multiple input methods may be specified in a single im value string

+in an implementation-dependent manner.

+</para>

+<para>

+<!-- .LP -->

+The returned modifiers string is owned by Xlib and should not be modified or

+freed by the client.

+It may be freed by Xlib after the current locale or modifiers are changed.

+Until freed, it will not be modified by Xlib.

+</para>

+<para>

+<!-- .LP -->

+The recommended procedure for clients initializing their locale and modifiers

+is to obtain locale and modifier announcers separately from

+one of the following prioritized sources:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+A command line option

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A resource

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The empty string ("")

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+The first of these that is defined should be used.

+Note that when a locale command line option or locale resource is defined,

+the effect should be to set all categories to the specified locale,

+overriding any category-specific settings in the local host environment.

+</para>

+</sect1>

+<sect1 id="Locale_and_Modifier_Dependencies">

+<title>Locale and Modifier Dependencies</title>

+<!-- .XS -->

+<!-- (SN Locale and Modifier Dependencies -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The internationalized Xlib functions operate in the current locale

+configured by the host environment and X locale modifiers set by

+<function>XSetLocaleModifiers</function>

+or in the locale and modifiers configured at the time

+some object supplied to the function was created.

+For each locale-dependent function,

+the following table describes the locale (and modifiers) dependency:

+</para>

+

+<informaltable>

+  <tgroup cols='3' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <colspec colname='c3'/>

+  <thead>

+    <row>

+      <entry>Locale from</entry>

+      <entry>Affects the Function</entry>

+      <entry>In</entry>

+    </row>

+  </thead>

+  <tbody>

+    <row>

+      <entry></entry>

+      <entry>Locale Query/Configuration:</entry>

+    </row>

+    <row>

+      <entry><function>setlocale</function></entry>

+      <entry><function>XSupportsLocale</function></entry>

+      <entry>Locale queried</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry><function>XSetLocaleModifiers</function></entry>

+      <entry>Locale modified</entry>

+    </row>

+    <row>

+      <entry></entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>Resources:</entry>

+    </row>

+    <row>

+      <entry><function>setlocale</function></entry>

+      <entry><function>XrmGetFileDatabase</function></entry>

+      <entry>Locale of <function>XrmDatabase</function></entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry><function>XrmGetStringDatabase</function></entry>

+    </row>

+    <row>

+      <entry><function>XrmDatabase</function></entry>

+      <entry><function>XrmPutFileDatabase</function></entry>

+      <entry>Locale of <function>XrmDatabase</function></entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry><function>XrmLocaleOfDatabase</function></entry>

+    </row>

+    <row>

+      <entry></entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>Setting Standard Properties:</entry>

+    </row>

+    <row>

+      <entry><function>setlocale</function></entry>

+      <entry><function>XmbSetWMProperties</function></entry>

+      <entry>Encoding of supplied/returned

+      text (some WM_ property

+      text in environment locale)</entry>

+    </row>

+    <row>

+      <entry><function>setlocale</function></entry>

+      <entry><function>XmbTextPropertyToTextList</function></entry>

+      <entry>Encoding of supplied/returned text</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry><function>XwcTextPropertyToTextList</function></entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry><function>XmbTextListToTextProperty</function></entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry><function>XwcTextListToTextProperty</function></entry>

+    </row>

+    <row>

+      <entry></entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>Text Input:</entry>

+    </row>

+    <row>

+      <entry><function>setlocale</function></entry>

+      <entry><function>XOpenIM</function></entry>

+      <entry><acronym>XIM</acronym> input method selection</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry><function>XRegisterIMInstantiateCallback</function></entry>

+      <entry><acronym>XIM</acronym> selection</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry><function>XUnregisterIMInstantiateCallback</function></entry>

+      <entry><acronym>XIM</acronym> selection</entry>

+    </row>

+    <row>

+      <entry><function>XIM</function></entry>

+      <entry><function>XCreateIC</function></entry>

+      <entry><acronym>XIC</acronym> input method configuration</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry><function>XLocaleOfIM</function>,  and so on</entry>

+      <entry>Queried locale</entry>

+    </row>

+    <row>

+      <entry><function>XIC</function></entry>

+      <entry><function>XmbLookupString</function></entry>

+      <entry>Keyboard layout</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry><function>XwcLookupString</function></entry>

+      <entry>Encoding of returned text</entry>

+    </row>

+    <row>

+      <entry></entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>Text Drawing:</entry>

+    </row>

+    <row>

+      <entry><function>setlocale</function></entry>

+      <entry><function>XOpenOM</function></entry>

+      <entry><acronym>XOM</acronym> output method selection</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry><function>XCreateFontSet</function></entry>

+      <entry>Charsets of fonts in XFontSet</entry>

+    </row>

+    <row>

+      <entry><function>XOM</function></entry>

+      <entry><function>XCreateOC</function></entry>

+      <entry><acronym>XOC</acronym> output method configuration</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry><function>XLocaleOfOM</function>,  and so on</entry>

+      <entry>Queried locale</entry>

+    </row>

+    <row>

+      <entry><function>XFontSet</function></entry>

+      <entry><function>XmbDrawText</function>,</entry>

+      <entry>Locale of supplied text</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry><function>XwcDrawText</function>, and so on</entry>

+      <entry>Locale of supplied text</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry><function>XExtentsOfFontSet</function>, and so on</entry>

+      <entry>Locale-dependent metrics</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry><function>XmbTextExtents</function>,</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry><function>XwcTextExtents</function>,  and so on</entry>

+    </row>

+    <row>

+      <entry></entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry>Xlib Errors:</entry>

+    </row>

+    <row>

+      <entry><function>setlocale</function></entry>

+      <entry><function>XGetErrorDatabaseText</function></entry>

+      <entry>Locale of error message</entry>

+    </row>

+    <row>

+      <entry></entry>

+      <entry><function>XGetErrorText</function></entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<para>

+<!-- .LP -->

+Clients may assume that a locale-encoded text string returned 

+by an X function can be passed to a C library routine, or vice versa,

+if the locale is the same at the two calls.

+</para>

+<para>

+<!-- .LP -->

+All text strings processed by internationalized Xlib functions are assumed

+to begin in the initial state of the encoding of the locale, if the encoding

+is state-dependent.

+</para>

+<para>

+<!-- .LP -->

+All Xlib functions behave as if they do not change the current locale

+or X modifier setting.

+(This means that if they do change locale or call 

+<function>XSetLocaleModifiers</function>

+with a non-NULL argument, they must save and restore the current state on

+entry and exit.)

+Also, Xlib functions on implementations that conform to the ANSI C library do

+not alter the global state associated with the ANSI C functions 

+<function>mblen</function>,

+<function>mbtowc</function>,

+<function>wctomb</function>,

+and 

+<function>strtok</function>.

+</para>

+</sect1>

+<sect1 id="Variable_Argument_Lists">

+<title>Variable Argument Lists</title>

+<!-- .XS -->

+<!-- (SN Variable Argument Lists -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Various functions in this chapter have arguments that conform

+to the ANSI C variable argument list calling convention.

+Each function denoted with an argument of the form ``...'' takes 

+a variable-length list of name and value pairs,

+where each name is a string and each value is of type 

+<function>XPointer</function>.

+A name argument that is NULL identifies the end of the list. 

+</para>

+<para>

+<!-- .LP -->

+A variable-length argument list may contain a nested list.

+If the name 

+<function>XNVaNestedList</function>

+is specified in place of an argument name,

+then the following value is interpreted as an 

+<function>XVaNestedList</function>

+value that specifies a list of values logically inserted into the

+original list at the point of declaration.

+A NULL identifies the end of a nested list.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To allocate a nested variable argument list dynamically, use

+<function>XVaCreateNestedList</function>.

+<indexterm significance="preferred"><primary>XVaCreateNestedList</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XVaNestedList<function> XVaCreateNestedList</function></funcdef>

+  <paramdef>int<parameter> dummy</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dummy</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an unused argument (required by ANSI C).

+<!-- .ds Al -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      ...

+    </term>

+    <listitem>

+      <para>

+Specifies the variable length argument list(Al.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XVaCreateNestedList</function>

+function allocates memory and copies its arguments into

+a single list pointer,

+which may be used as a value for arguments requiring a list value.

+Any entries are copied as specified.

+Data passed by reference is not copied;

+the caller must ensure data remains valid for the lifetime

+of the nested list.

+The list should be freed using

+<function>XFree</function>

+when it is no longer needed.

+</para>

+</sect1>

+<sect1 id="Output_Methods">

+<title>Output Methods</title>

+<!-- .XS -->

+<!-- (SN Output Methods -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+This section provides discussions of the following X Output Method

+(<acronym>XOM</acronym>) topics:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Output method overview

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Output method functions

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Output method values

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Output context functions

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Output context values

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Creating and freeing a font set

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Obtaining font set metrics

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Drawing text using font sets

+    </para>

+  </listitem>

+</itemizedlist>

+<sect2 id="Output_Method_Overview">

+<title>Output Method Overview</title>

+<!-- .XS -->

+<!-- (SN Output Method Overview -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Locale-dependent text may include one or more text components, each of

+which may require different fonts and character set encodings.

+In some languages, each component might have a different

+drawing direction, and some components might contain

+context-dependent characters that change shape based on

+relationships with neighboring characters.

+</para>

+<para>

+<!-- .LP -->

+When drawing such locale-dependent text, some locale-specific

+knowledge is required;

+for example, what fonts are required to draw the text,

+how the text can be separated into components, and which

+fonts are selected to draw each component.

+Further, when bidirectional text must be drawn,

+the internal representation order of the text must be changed

+into the visual representation order to be drawn.

+</para>

+<para>

+<!-- .LP -->

+An X Output Method provides a functional interface so that clients

+do not have to deal directly with such locale-dependent details.

+Output methods provide the following capabilities:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Creating a set of fonts required to draw locale-dependent text.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Drawing locale-dependent text with a font set without the caller

+needing to be aware of locale dependencies.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Obtaining the escapement and extents in pixels of locale-dependent text.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Determining if bidirectional or context-dependent drawing is required

+in a specific locale with a specific font set.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+Two different abstractions are used in the representation of

+the output method for clients.

+</para>

+<para>

+<!-- .LP -->

+The abstraction used to communicate with an output method

+is an opaque data structure represented by the 

+<function>XOM</function>

+data type.

+The abstraction for representing the state of a particular output thread

+is called an <emphasis remap='I'>output context</emphasis>.

+The Xlib representation of an output context is an 

+<function>XOC</function>,

+which is compatible with 

+<function>XFontSet</function>

+in terms of its functional interface, but is 

+a broader, more generalized abstraction.

+</para>

+</sect2>

+<sect2 id="Output_Method_Functions">

+<title>Output Method Functions</title>

+<!-- .XS -->

+<!-- (SN Output Method Functions -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To open an output method, use

+<function>XOpenOM</function>.

+<indexterm significance="preferred"><primary>XOpenOM</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XOM<function> XOpenOM</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XrmDatabase<parameter> db</parameter></paramdef>

+  <paramdef>char<parameter> *res_name</parameter></paramdef>

+  <paramdef>char<parameter> *res_class</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>db</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a pointer to the resource database.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>res_name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the full resource name of the application.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>res_class</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the full class name of the application.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XOpenOM</function>

+function opens an output method

+matching the current locale and modifiers specification.

+The current locale and modifiers are bound to the output method

+when

+<function>XOpenOM</function>

+is called.

+The locale associated with an output method cannot be changed.

+</para>

+<para>

+<!-- .LP -->

+The specific output method to which this call will be routed

+is identified on the basis of the current locale and modifiers.

+<function>XOpenOM</function>

+will identify a default output method corresponding to the

+current locale.

+That default can be modified using 

+<function>XSetLocaleModifiers</function>

+to set the output method modifier.

+</para>

+<para>

+<!-- .LP -->

+The db argument is the resource database to be used by the output method

+for looking up resources that are private to the output method.

+It is not intended that this database be used to look

+up values that can be set as OC values in an output context.

+If db is NULL,

+no database is passed to the output method.

+</para>

+<para>

+<!-- .LP -->

+The res_name and res_class arguments specify the resource name 

+and class of the application. 

+They are intended to be used as prefixes by the output method

+when looking up resources that are common to all output contexts

+that may be created for this output method.

+The characters used for resource names and classes must be in the

+X Portable Character Set.

+The resources looked up are not fully specified

+if res_name or res_class is NULL.

+</para>

+<para>

+<!-- .LP -->

+The res_name and res_class arguments are not assumed to exist beyond

+the call to

+<function>XOpenOM</function>.

+The specified resource database is assumed to exist for the lifetime

+of the output method.

+</para>

+<para>

+<!-- .LP -->

+<function>XOpenOM</function>

+returns NULL if no output method could be opened.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To close an output method, use

+<function>XCloseOM</function>.

+<indexterm significance="preferred"><primary>XCloseOM</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XCloseOM</function></funcdef>

+  <paramdef>XOM<parameter> om</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>om</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the output method.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCloseOM</function>

+function closes the specified output method.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set output method attributes, use 

+<function>XSetOMValues</function>.

+<indexterm significance="preferred"><primary>XSetOMValues</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> *</function></funcdef>

+  <paramdef>XOM<parameter> om</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>om</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the output method.

+<!-- .ds Al \ to set <acronym>XOM</acronym> values -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      ...

+    </term>

+    <listitem>

+      <para>

+Specifies the variable-length argument list(Al.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetOMValues</function>

+function presents a variable argument list programming interface

+for setting properties or features of the specified output method.

+This function returns NULL if it succeeds;

+otherwise,

+it returns the name of the first argument that could not be obtained.

+</para>

+<para>

+<!-- .LP -->

+No standard arguments are currently defined by Xlib.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To query an output method, use 

+<function>XGetOMValues</function>.

+<indexterm significance="preferred"><primary>XGetOMValues</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> *</function></funcdef>

+  <paramdef>XOM<parameter> om</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>om</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the output method.

+<!-- .ds Al \ to get XOM values -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      ...

+    </term>

+    <listitem>

+      <para>

+Specifies the variable-length argument list(Al.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetOMValues</function>

+function presents a variable argument list programming interface

+for querying properties or features of the specified output method.

+This function returns NULL if it succeeds;

+otherwise,

+it returns the name of the first argument that could not be obtained.

+</para>

+<para>

+<!-- .LP -->

+To obtain the display associated with an output method, use

+<function>XDisplayOfOM</function>.

+<indexterm significance="preferred"><primary>XDisplayOfOM</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Display<function> *</function></funcdef>

+  <paramdef>XOM<parameter> om</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>om</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the output method.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XDisplayOfOM</function>

+function returns the display associated with the specified output method.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To get the locale associated with an output method, use

+<function>XLocaleOfOM</function>.

+<indexterm significance="preferred"><primary>XLocaleOfOM</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> *</function></funcdef>

+  <paramdef>XOM<parameter> om</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>om</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the output method.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XLocaleOfOM</function>

+returns the locale associated with the specified output method.

+</para>

+</sect2>

+<sect2 id="X_Output_Method_Values">

+<title>X Output Method Values</title>

+<!-- .XS -->

+<!-- (SN X Output Method Values -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The following table describes how <acronym>XOM</acronym> values are interpreted by an

+output method.

+The first column lists the <acronym>XOM</acronym> values.  The second column indicates

+how each of the <acronym>XOM</acronym> values are treated by a particular output style.

+</para>

+<para>

+<!-- .LP -->

+</para>

+<para>

+<!-- .LP -->

+The following key applies to this table.

+</para>

+

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <thead>

+    <row>

+      <entry>Key</entry>

+      <entry>Explanation</entry>

+    </row>

+  </thead>

+  <tbody>

+    <row>

+      <entry>G</entry>

+      <entry>This value may be read using <function>XGetOMValues</function>.</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <thead>

+    <row>

+      <entry><acronym>XOM</acronym> Value</entry>

+      <entry>Key</entry>

+    </row>

+  </thead>

+  <tbody>

+    <row>

+      <entry><function>XNRequiredCharSet</function></entry>

+      <entry>G</entry>

+    </row>

+    <row>

+      <entry><function>XNQueryOrientation</function></entry>

+      <entry>G</entry>

+    </row>

+    <row>

+      <entry><function>XNDirectionalDependentDrawing</function></entry>

+      <entry>G</entry>

+    </row>

+    <row>

+      <entry><function>XNContextualDrawing</function></entry>

+      <entry>G</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<para>

+<!-- .LP -->

+</para>

+<sect3 id="Required_Char_Set">

+<title>Required Char Set</title>

+<!-- .XS -->

+<!-- (SN Required Char Set -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The

+<function>XNRequiredCharSet</function>

+argument returns the list of charsets that are required for loading the fonts

+needed for the locale.

+The value of the argument is a pointer to a structure of type

+<function>XOMCharSetList</function>.

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XOMCharSetList</function>

+structure is defined as follows:

+<indexterm significance="preferred"><primary>XOMCharSetList</primary></indexterm>

+<!-- .sM -->

+</para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct {

+     int    charset_count;

+     char   **charset_list;

+} XOMCharSetList;

+</literallayout>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The charset_list member is a list of one or more null-terminated

+charset names, and the charset_count member is the number of

+charset names.

+</para>

+<para>

+<!-- .LP -->

+The required charset list is owned by Xlib and should not be modified or

+freed by the client.

+It will be freed by a call to 

+<function>XCloseOM</function>

+with the associated 

+<function>XOM</function>.

+Until freed, its contents will not be modified by Xlib.

+</para>

+<para>

+<!-- .LP -->

+</para>

+</sect3>

+<sect3 id="Query_Orientation">

+<title>Query Orientation</title>

+<!-- .XS -->

+<!-- (SN Query Orientation -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The

+<function>XNQueryOrientation</function>

+argument returns the global orientation of text when drawn.

+Other than

+<function>XOMOrientation_LTR_TTB</function>,

+the set of orientations supported is locale-dependent.

+The value of the argument is a pointer to a structure of type

+<function>XOMOrientation</function>.

+Clients are responsible for freeing the

+<function>XOMOrientation</function>

+structure by using

+<function>XFree</function>;

+this also frees the contents of the structure.

+</para>

+

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct {

+     int          num_orientation;

+     XOrientation *orientation;     /* Input Text description */

+} XOMOrientation;

+

+typedef enum {

+     XOMOrientation_LTR_TTB,

+     XOMOrientation_RTL_TTB,     

+     XOMOrientation_TTB_LTR,

+     XOMOrientation_TTB_RTL,

+     XOMOrientation_Context

+} XOrientation;

+</literallayout>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The possible value for XOrientation may be:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+<function>XOMOrientation_LTR_TTB  </function>

+left-to-right, top-to-bottom global orientation

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XOMOrientation_RTL_TTB  </function>

+right-to-left, top-to-bottom global orientation

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XOMOrientation_TTB_LTR  </function>

+top-to-bottom, left-to-right global orientation

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XOMOrientation_TTB_RTL  </function>

+top-to-bottom, right-to-left global orientation

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>XOMOrientation_Context  </function>

+contextual global orientation

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+</para>

+</sect3>

+<sect3 id="Directional_Dependent_Drawing">

+<title>Directional Dependent Drawing</title>

+<!-- .XS -->

+<!-- (SN Directional Dependent Drawing -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The

+<function>XNDirectionalDependentDrawing</function>

+argument indicates whether the text rendering functions

+implement implicit handling of directional text.  If this value

+is

+<function>True</function>,

+the output method has knowledge of directional

+dependencies and reorders text as necessary when

+rendering text.  If this value is

+<function>False</function>,

+the output method does not implement any directional text

+handling, and all character directions are assumed to be left-to-right.

+</para>

+<para>

+<!-- .LP -->

+Regardless of the rendering order of characters,

+the origins of all characters are on the primary draw direction side

+of the drawing origin.

+</para>

+<para>

+<!-- .LP -->

+This OM value presents functionality identical to the

+<function>XDirectionalDependentDrawing</function>

+function.

+</para>

+</sect3>

+<sect3 id="Context_Dependent_Drawing">

+<title>Context Dependent Drawing</title>

+<!-- .XS -->

+<!-- (SN Context Dependent Drawing -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The

+<function>XNContextualDrawing</function>

+argument indicates whether the text rendering functions

+implement implicit context-dependent drawing.  If this value is

+<function>True</function>,

+the output method has knowledge of context dependencies and

+performs character shape editing, combining glyphs to present

+a single character as necessary.  The actual shape editing is

+dependent on the locale implementation and the font set used.

+</para>

+<para>

+<!-- .LP -->

+This OM value presents functionality identical to the

+<function>XContextualDrawing</function>

+function.

+</para>

+</sect3>

+</sect2>

+<sect2 id="Output_Context_Functions">

+<title>Output Context Functions</title>

+<!-- .XS -->

+<!-- (SN Output Context Functions -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+An output context is an abstraction that contains both the data

+required by an output method and the information required

+to display that data.

+There can be multiple output contexts for one output method.

+The programming interfaces for creating, reading, or modifying

+an output context use a variable argument list.

+The name elements of the argument lists are referred to as <acronym>XOC</acronym> values.

+It is intended that output methods be controlled by these <acronym>XOC</acronym> values.

+As new <acronym>XOC</acronym> values are created,

+they should be registered with the X Consortium.

+An

+<function>XOC</function>

+can be used anywhere an

+<function>XFontSet</function>

+can be used, and vice versa;

+<function>XFontSet</function>

+is retained for compatibility with previous releases.

+The concepts of output methods and output contexts include broader,

+more generalized abstraction than font set,

+supporting complex and more intelligent text display, and dealing not only

+with multiple fonts but also with context dependencies.

+However,

+<function>XFontSet</function>

+is widely used in several interfaces, so

+<function>XOC</function>

+is defined as an upward compatible type of

+<function>XFontSet</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To create an output context, use

+<function>XCreateOC</function>.

+<indexterm significance="preferred"><primary>XCreateOC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XOC<function> XCreateOC</function></funcdef>

+  <paramdef>XOM<parameter> om</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>om</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the output method.

+<!-- .ds Al \ to set <acronym>XOC</acronym> values -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      ...

+    </term>

+    <listitem>

+      <para>

+Specifies the variable-length argument list(Al.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCreateOC </function>

+function creates an output context within the specified output method.

+</para>

+<para>

+<!-- .LP -->

+The base font names argument is mandatory at creation time, and

+the output context will not be created unless it is provided.

+All other output context values can be set later.

+</para>

+<para>

+<!-- .LP -->

+<function>XCreateOC</function>

+returns NULL if no output context could be created.

+NULL can be returned for any of the following reasons:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+A required argument was not set.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A read-only argument was set.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+An argument name is not recognized.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The output method encountered an output method implementation-dependent error.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+<function>XCreateOC</function>

+can generate a

+<function>BadAtom</function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To destroy an output context, use

+<function>XDestroyOC</function>.

+<indexterm significance="preferred"><primary>XDestroyOC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XDestroyOC</function></funcdef>

+  <paramdef>XOC<parameter> oc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>oc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the output context.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XDestroyOC</function>

+function destroys the specified output context.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To get the output method associated with an output context, use

+<function>XOMOfOC</function>.

+<indexterm significance="preferred"><primary>XOMOfOC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XOM<function> XOMOfOC</function></funcdef>

+  <paramdef>XOC<parameter> oc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>oc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the output context.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XOMOfOC</function>

+function returns the output method associated with the

+specified output context.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+Xlib provides two functions for setting and reading output context values,

+respectively,

+<function>XSetOCValues</function>

+and

+<function>XGetOCValues</function>.

+Both functions have a variable-length argument list.

+In that argument list, any <acronym>XOC</acronym> value's name must be denoted

+with a character string using the X Portable Character Set.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set <acronym>XOC</acronym> values, use

+<function>XSetOCValues</function>.

+<indexterm significance="preferred"><primary>XSetOCValues</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> *</function></funcdef>

+  <paramdef>XOC<parameter> oc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>oc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the output context.

+<!-- .ds Al \ to set <acronym>XOC</acronym> values -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      ...

+    </term>

+    <listitem>

+      <para>

+Specifies the variable-length argument list(Al.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetOCValues</function>

+function returns NULL if no error occurred; 

+otherwise,

+it returns the name of the first argument that could not be set.

+An argument might not be set for any of the following reasons:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+The argument is read-only.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The argument name is not recognized.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+An implementation-dependent error occurs.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+Each value to be set must be an appropriate datum,

+matching the data type imposed by the semantics of the argument.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetOCValues</function>

+can generate a

+<function>BadAtom </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain <acronym>XOC</acronym> values, use

+<function>XGetOCValues</function>.

+<indexterm significance="preferred"><primary>XGetOCValues</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> *</function></funcdef>

+  <paramdef>XOC<parameter> oc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>oc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the output context.

+<!-- .ds Al \ to get XOC values -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      ...

+    </term>

+    <listitem>

+      <para>

+Specifies the variable-length argument list(Al.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetOCValues</function>

+function returns NULL if no error occurred; otherwise,

+it returns the name of the first argument that could not be obtained.

+An argument might not be obtained for any of the following reasons:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+The argument name is not recognized.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+An implementation-dependent error occurs.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+Each argument value

+following a name must point to a location where the value is to be stored.

+</para>

+</sect2>

+

+<sect2 id="Output_Context_Values">

+<title>Output Context Values</title>

+<!-- .XS -->

+<!-- (SN Output Context Values -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The following table describes how <acronym>XOC</acronym> values are interpreted

+by an output method.

+The first column lists the <acronym>XOC</acronym> values.

+The second column indicates the alternative interfaces that function

+identically and are provided for compatibility with previous releases.

+The third column indicates how each of the <acronym>XOC</acronym> values is treated.

+</para>

+<!-- .LP -->

+<para>

+The following keys apply to this table.

+</para>

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <thead>

+    <row>

+      <entry>Key</entry>

+      <entry>Explanation</entry>

+    </row>

+  </thead>

+  <tbody>

+    <row>

+      <entry>C</entry>

+      <entry>This value must be set with <function>XCreateOC</function>.</entry>

+    </row>

+    <row>

+      <entry>D</entry>

+      <entry>This value may be set using <function>XCreateOC</function>.

+      If it is not set,a default is provided.</entry>

+    </row>

+    <row>

+      <entry>G</entry>

+      <entry>This value may be read using <function>XGetOCValues</function>.</entry>

+    </row>

+    <row>

+      <entry>S</entry>

+      <entry>This value must be set using <function>XSetOCValues</function>.</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<!-- .LP -->

+<informaltable>

+  <tgroup cols='3' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <colspec colname='c3'/>

+  <thead>

+    <row>

+      <entry><acronym>XOC</acronym> Value</entry>

+      <entry>Alternative Interface</entry>

+      <entry>Key</entry>

+    </row>

+  </thead>

+  <tbody>

+    <row>

+      <entry>BaseFontName</entry>

+      <entry><function>XCreateFontSet</function></entry>

+      <entry>C-G</entry>

+    </row>

+    <row>

+      <entry>MissingCharSet</entry>

+      <entry><function>XCreateFontSet</function></entry>

+      <entry>G</entry>

+    </row>

+    <row>

+      <entry>DefaultString</entry>

+      <entry><function>XCreateFontSet</function></entry>

+      <entry>G</entry>

+    </row>

+    <row>

+      <entry>Orientation</entry>

+      <entry>-</entry>

+      <entry>D-S-G</entry>

+    </row>

+    <row>

+      <entry>ResourceName</entry>

+      <entry>-</entry>

+      <entry>S-G</entry>

+    </row>

+    <row>

+      <entry>ResourceClass</entry>

+      <entry>-</entry>

+      <entry>S-G</entry>

+    </row>

+    <row>

+      <entry>FontInfo</entry>

+      <entry><function>XFontsOfFontSet</function></entry>

+      <entry>G</entry>

+    </row>

+    <row>

+      <entry>OMAutomatic</entry>

+      <entry>-</entry>

+      <entry>G</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<para>

+<!-- .LP -->

+</para>

+<sect3 id="Base_Font_Name">

+<title>Base Font Name</title>

+<!-- .XS -->

+<!-- (SN Base Font Name -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The

+<function>XNBaseFontName</function>

+argument is a list of base font names that Xlib uses

+to load the fonts needed for the locale.

+The base font names are a comma-separated list.  The string is null-terminated

+and is assumed to be in the Host Portable Character Encoding;

+otherwise, the result is implementation-dependent.

+White space immediately on either side of a separating comma is ignored.

+</para>

+<para>

+<!-- .LP -->

+Use of <acronym>XLFD</acronym> font names permits Xlib to obtain the fonts needed for a

+variety of locales from a single locale-independent base font name.

+The single base font name should name a family of fonts whose members

+are encoded in the various charsets needed by the locales of interest.

+</para>

+<para>

+<!-- .LP -->

+An <acronym>XLFD</acronym> base font name can explicitly name a charset needed for the locale.

+This allows the user to specify an exact font for use with a charset required

+by a locale, fully controlling the font selection.

+</para>

+<para>

+<!-- .LP -->

+If a base font name is not an <acronym>XLFD</acronym> name,

+Xlib will attempt to obtain an <acronym>XLFD</acronym> name from the font properties

+for the font.

+If Xlib is successful, the

+<function>XGetOCValues</function>

+function will return this <acronym>XLFD</acronym> name instead of the client-supplied name.

+</para>

+<para>

+<!-- .LP -->

+This argument must be set at creation time

+and cannot be changed.

+If no fonts exist for any of the required charsets,

+or if the locale definition in Xlib requires that a font exist

+for a particular charset and a font is not found for that charset,

+<function>XCreateOC</function>

+returns NULL.

+</para>

+<para>

+<!-- .LP -->

+When querying for the

+<function>XNBaseFontName</function>

+<acronym>XOC</acronym> value,

+<function>XGetOCValues</function>

+returns a null-terminated string identifying the base font names that

+Xlib used to load the fonts needed for the locale.

+This string is owned by Xlib and should not be modified or freed by

+the client.

+The string will be freed by a call to

+<function>XDestroyOC</function>

+with the associated

+<function>XOC</function>.

+Until freed, the string contents will not be modified by Xlib.

+</para>

+</sect3>

+<sect3 id="Missing_CharSet">

+<title>Missing CharSet</title>

+<!-- .XS -->

+<!-- (SN Missing CharSet -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The

+<function>XNMissingCharSet</function>

+argument returns the list of required charsets that are missing from the

+font set.

+The value of the argument is a pointer to a structure of type

+<function>XOMCharSetList</function>.

+</para>

+<para>

+<!-- .LP -->

+If fonts exist for all of the charsets required by the current locale,

+charset_list is set to NULL and charset_count is set to zero.

+If no fonts exist for one or more of the required charsets,

+charset_list is set to a list of one or more null-terminated charset names

+for which no fonts exist, and charset_count is set to the number of

+missing charsets.

+The charsets are from the list of the required charsets for

+the encoding of the locale and do not include any charsets to which Xlib

+may be able to remap a required charset.

+</para>

+<para>

+<!-- .LP -->

+The missing charset list is owned by Xlib and should not be modified or

+freed by the client.

+It will be freed by a call to 

+<function>XDestroyOC</function>

+with the associated

+<function>XOC</function>.

+Until freed, its contents will not be modified by Xlib.

+</para>

+</sect3>

+<sect3 id="Default_String">

+<title>Default String</title>

+<!-- .XS -->

+<!-- (SN Default String -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+When a drawing or measuring function is called with an

+<function>XOC</function>

+that has missing charsets, some characters in the locale will not be

+drawable.

+The

+<function>XNDefaultString</function>

+argument returns a pointer to a string that represents the glyphs

+that are drawn with this

+<function>XOC</function>

+when the charsets of the available fonts do not include all glyphs

+required to draw a character.

+The string does not necessarily consist of valid characters

+in the current locale and is not necessarily drawn with

+the fonts loaded for the font set,

+but the client can draw or measure the default glyphs

+by including this string in a string being drawn or measured with the

+<function>XOC</function>.

+</para>

+<para>

+<!-- .LP -->

+If the

+<function>XNDefaultString</function>

+argument returned the empty string (""),

+no glyphs are drawn and the escapement is zero.

+The returned string is null-terminated.

+It is owned by Xlib and should not be modified or freed by the client.

+It will be freed by a call to

+<function>XDestroyOC</function>

+with the associated

+<function>XOC</function>.

+Until freed, its contents will not be modified by Xlib.

+</para>

+</sect3>

+<sect3 id="Orientation">

+<title>Orientation</title>

+<!-- .XS -->

+<!-- (SN Orientation -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The

+<function>XNOrientation</function>

+argument specifies the current orientation of text when drawn.  The value of

+this argument is one of the values returned by the

+<function>XGetOMValues</function>

+function with the

+<function>XNQueryOrientation</function>

+argument specified in the

+<function>XOrientation</function>

+list.

+The value of the argument is of type

+<function>XOrientation</function>.

+When

+<function>XNOrientation</function>

+is queried, the value specifies the current orientation.  

+When

+<function>XNOrientation</function>

+is set, a value is used to set the current orientation.

+</para>

+<para>

+<!-- .LP -->

+When 

+<function>XOMOrientation_Context</function>

+is set, the text orientation of the 

+text is determined according to an implementation-defined method

+(for example, ISO 6429 control sequences), and the initial text orientation for

+locale-dependent Xlib functions is assumed to 

+be

+<function>XOMOrientation_LTR_TTB</function>.

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XNOrientation</function>

+value does not change the prime drawing direction 

+for Xlib drawing functions.  

+</para>

+</sect3>

+<sect3 id="Resource_Name_and_Class">

+<title>Resource Name and Class</title>

+<!-- .XS -->

+<!-- (SN Resource Name and Class -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The

+<function>XNResourceName</function>

+and

+<function>XNResourceClass</function>

+arguments are strings that specify the full name and class

+used by the client to obtain resources for the display of the output context.

+These values should be used as prefixes for name and class

+when looking up resources that may vary according to the output context.

+If these values are not set,

+the resources will not be fully specified.

+</para>

+<para>

+<!-- .LP -->

+It is not intended that values that can be set as <acronym>XOM</acronym> values be

+set as resources.

+</para>

+<para>

+<!-- .LP -->

+When querying for the

+<function>XNResourceName</function>

+or

+<function>XNResourceClass</function>

+<acronym>XOC</acronym> value,

+<function>XGetOCValues</function>

+returns a null-terminated string.

+This string is owned by Xlib and should not be modified or freed by

+the client.

+The string will be freed by a call to

+<function>XDestroyOC</function>

+with the associated

+<function>XOC</function>

+or when the associated value is changed via

+<function>XSetOCValues</function>.

+Until freed, the string contents will not be modified by Xlib.

+</para>

+</sect3>

+<sect3 id="Font_Info">

+<title>Font Info</title>

+<!-- .XS -->

+<!-- (SN Font Info -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The

+<function>XNFontInfo</function>

+argument specifies a list of one or more 

+<function>XFontStruct</function>

+structures

+and font names for the fonts used for drawing by the given output context.

+The value of the argument is a pointer to a structure of type

+<function>XOMFontInfo</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct {

+     int         num_font;

+     XFontStruct **font_struct_list;

+     char        **font_name_list;

+} XOMFontInfo;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+A list of pointers to the

+<function>XFontStruct</function>

+structures is returned to font_struct_list.

+A list of pointers to null-terminated, fully-specified font name strings

+in the locale of the output context is returned to font_name_list.

+The font_name_list order corresponds to the font_struct_list order.

+The number of

+<function>XFontStruct</function>

+structures and font names is returned to num_font.

+</para>

+<para>

+<!-- .LP -->

+Because it is not guaranteed that a given character will be imaged using a

+single font glyph,

+there is no provision for mapping a character or default string 

+to the font properties, font ID, or direction hint for the font 

+for the character.

+The client may access the 

+<function>XFontStruct</function>

+list to obtain these values for all the fonts currently in use.

+</para>

+<para>

+<!-- .LP -->

+Xlib does not guarantee that fonts are loaded from the server

+at the creation of an 

+<function>XOC</function>.

+Xlib may choose to cache font data, loading it only as needed to draw text 

+or compute text dimensions.

+Therefore, existence of the per_char metrics in the 

+<function>XFontStruct</function>

+structures in the

+<function>XFontStructSet</function>

+is undefined.

+Also, note that all properties in the 

+<function>XFontStruct</function>

+structures are in the STRING encoding.

+</para>

+<para>

+<!-- .LP -->

+The client must not free the 

+<function>XOMFontInfo</function>

+struct itself; it will be freed when the

+<function>XOC</function>

+is closed.

+</para>

+</sect3>

+<sect3 id="OM_Automatic">

+<title>OM Automatic</title>

+<!-- .XS -->

+<!-- (SN OM Automatic -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The

+<function>XNOMAutomatic</function>

+argument returns whether the associated output context was created by

+<function>XCreateFontSet</function>

+or not.  Because the

+<function>XFreeFontSet</function>

+function not only destroys the output context but also closes the implicit

+output method associated with it,

+<function>XFreeFontSet</function>

+should be used with any output context created by 

+<function>XCreateFontSet</function>.

+However, it is possible that a client does not know how the output context

+was created.

+Before a client destroys the output context,

+it can query whether

+<function>XNOMAutomatic</function>

+is set to determine whether 

+<function>XFreeFontSet </function>

+or 

+<function>XDestroyOC</function>

+should be used to destroy the output context.

+</para>

+</sect3>

+</sect2>

+<sect2 id="Creating_and_Freeing_a_Font_Set">

+<title>Creating and Freeing a Font Set</title>

+<!-- .XS -->

+<!-- (SN Creating and Freeing a Font Set -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib international text drawing is done using a set of one or more fonts,

+as needed for the locale of the text.

+Fonts are loaded according to a list of base font names 

+supplied by the client and the charsets required by the locale.

+The

+<function>XFontSet</function>

+is an opaque type representing the state of a particular output thread

+and is equivalent to the type

+<function>XOC</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+The 

+<function>XCreateFontSet</function>

+function is a convenience function for creating an output context using

+only default values.  The returned

+<function>XFontSet</function>

+has an implicitly created

+<function>XOM</function>.

+This

+<function>XOM</function>

+has an OM value

+<function>XNOMAutomatic</function>

+automatically set to

+<function>True</function>

+so that the output context self indicates whether it was created by

+<function>XCreateOC</function>

+or

+<function>XCreateFontSet</function>.

+<indexterm significance="preferred"><primary>XCreateFontSet</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XFontSet<function> XCreateFontSet</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>char<parameter> *base_font_name_list</parameter></paramdef>

+  <paramdef>char<parameter> ***missing_charset_list_return</parameter></paramdef>

+  <paramdef>int<parameter> *missing_charset_count_return</parameter></paramdef>

+  <paramdef>char<parameter> **def_string_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>base_font_name_list</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the base font names.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>missing_charset_list_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the missing charsets.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>missing_charset_count_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of missing charsets.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>def_string_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the string drawn for missing charsets.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XCreateFontSet</function>

+function creates a font set for the specified display.

+The font set is bound to the current locale when 

+<function>XCreateFontSet</function>

+is called.

+The font set may be used in subsequent calls to obtain font

+and character information and to image text in the locale of the font set.

+</para>

+<para>

+<!-- .LP -->

+The base_font_name_list argument is a list of base font names

+that Xlib uses to load the fonts needed for the locale.

+The base font names are a comma-separated list.

+The string is null-terminated

+and is assumed to be in the Host Portable Character Encoding; 

+otherwise, the result is implementation-dependent.

+White space immediately on either side of a separating comma is ignored.

+</para>

+<para>

+<!-- .LP -->

+Use of <acronym>XLFD</acronym> font names permits Xlib to obtain the fonts needed for a

+variety of locales from a single locale-independent base font name.

+The single base font name should name a family of fonts whose members

+are encoded in the various charsets needed by the locales of interest.

+</para>

+<para>

+<!-- .LP -->

+An <acronym>XLFD</acronym> base font name can explicitly name a charset needed for the locale.

+This allows the user to specify an exact font for use with a charset required

+by a locale, fully controlling the font selection.

+</para>

+<para>

+<!-- .LP -->

+If a base font name is not an <acronym>XLFD</acronym> name,

+Xlib will attempt to obtain an <acronym>XLFD</acronym> name from the font properties

+for the font.

+If this action is successful in obtaining an <acronym>XLFD</acronym> name, the

+<function>XBaseFontNameListOfFontSet</function>

+function will return this <acronym>XLFD</acronym> name instead of the client-supplied name.

+</para>

+<para>

+<!-- .LP -->

+Xlib uses the following algorithm to select the fonts

+that will be used to display text with the 

+<function>XFontSet</function>.

+</para>

+<para>

+<!-- .LP -->

+For each font charset required by the locale,

+the base font name list is searched for the first appearance of one 

+of the following cases that names a set of fonts that exist at the server:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+The first <acronym>XLFD</acronym>-conforming base font name that specifies the required

+charset or a superset of the required charset in its 

+<function>CharSetRegistry</function>

+and 

+<function>CharSetEncoding</function>

+fields.

+The implementation may use a base font name whose specified charset

+is a superset of the required charset, for example,

+an ISO8859-1 font for an ASCII charset.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The first set of one or more <acronym>XLFD</acronym>-conforming base font names

+that specify one or more charsets that can be remapped to support the

+required charset.

+The Xlib implementation may recognize various mappings 

+from a required charset to one or more other charsets

+and use the fonts for those charsets.

+For example, JIS Roman is ASCII with tilde and backslash replaced 

+by yen and overbar;

+Xlib may load an ISO8859-1 font to support this character set

+if a JIS Roman font is not available.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The first <acronym>XLFD</acronym>-conforming font name or the first non-<acronym>XLFD</acronym> font name

+for which an <acronym>XLFD</acronym> font name can be obtained, combined with the

+required charset (replacing the 

+<function>CharSetRegistry</function>

+and

+<function>CharSetEncoding</function>

+fields in the <acronym>XLFD</acronym> font name).

+As in case 1,

+the implementation may use a charset that is a superset

+of the required charset.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The first font name that can be mapped in some implementation-dependent

+manner to one or more fonts that support imaging text in the charset.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+For example, assume that a locale required the charsets:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+ISO8859-1

+JISX0208.1983

+JISX0201.1976

+GB2312-1980.0

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+The user could supply a base_font_name_list that explicitly specifies the

+charsets, ensuring that specific fonts are used if they exist.

+For example:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\\

+-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\\

+-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\\

+-Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1"

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+Alternatively, the user could supply a base_font_name_list

+that omits the charsets,

+letting Xlib select font charsets required for the locale.

+For example:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\

+-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\\

+-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\

+-Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150"

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+Alternatively, the user could simply supply a single base font name

+that allows Xlib to select from all available fonts

+that meet certain minimum <acronym>XLFD</acronym> property requirements.

+For example:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+"-*-*-*-R-Normal--*-180-100-100-*-*"

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+If 

+<function>XCreateFontSet</function>

+is unable to create the font set, 

+either because there is insufficient memory or because the current locale

+is not supported,

+<function>XCreateFontSet</function>

+returns NULL, missing_charset_list_return is set to NULL,

+and missing_charset_count_return

+is set to zero.

+If fonts exist for all of the charsets required by the current locale,

+<function>XCreateFontSet</function>

+returns a valid

+<function>XFontSet</function>,

+missing_charset_list_return is set to NULL,

+and missing_charset_count_return is set to zero.

+</para>

+<para>

+<!-- .LP -->

+If no font exists for one or more of the required charsets,

+<function>XCreateFontSet</function>

+sets missing_charset_list_return to a

+list of one or more null-terminated charset names for which no font exists

+and sets missing_charset_count_return to the number of missing fonts.

+The charsets are from the list of the required charsets for

+the encoding of the locale and do not include any charsets to which Xlib

+may be able to remap a required charset.

+</para>

+<para>

+<!-- .LP -->

+If no font exists for any of the required charsets

+or if the locale definition in Xlib requires that a font exist

+for a particular charset and a font is not found for that charset, 

+<function>XCreateFontSet</function>

+returns NULL.

+Otherwise, 

+<function>XCreateFontSet</function>

+returns a valid 

+<function>XFontSet</function>

+to font_set.

+</para>

+<para>

+<!-- .LP -->

+When an Xmb/wc drawing or measuring function is called with an

+<function>XFontSet</function>

+that has missing charsets, some characters in the locale will not be

+drawable.

+If def_string_return is non-NULL,

+<function>XCreateFontSet</function>

+returns a pointer to a string that represents the glyphs

+that are drawn with this 

+<function>XFontSet</function>

+when the charsets of the available fonts do not include all font glyphs

+required to draw a codepoint.

+The string does not necessarily consist of valid characters 

+in the current locale and is not necessarily drawn with

+the fonts loaded for the font set,

+but the client can draw and measure the default glyphs

+by including this string in a string being drawn or measured with the 

+<function>XFontSet</function>.

+</para>

+<para>

+<!-- .LP -->

+If the string returned to def_string_return is the empty string (""),

+no glyphs are drawn, and the escapement is zero.

+The returned string is null-terminated.

+It is owned by Xlib and should not be modified or freed by the client.

+It will be freed by a call to 

+<function>XFreeFontSet</function>

+with the associated 

+<function>XFontSet</function>.

+Until freed, its contents will not be modified by Xlib.

+</para>

+<para>

+<!-- .LP -->

+The client is responsible for constructing an error message from the

+missing charset and default string information and may choose to continue

+operation in the case that some fonts did not exist.

+</para>

+<para>

+<!-- .LP -->

+The returned 

+<function>XFontSet</function>

+and missing charset list should be freed with 

+<function>XFreeFontSet</function>

+and

+<function>XFreeStringList</function>,

+respectively.

+The client-supplied base_font_name_list may be freed 

+by the client after calling 

+<function>XCreateFontSet</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain a list of 

+<function>XFontStruct</function>

+structures and full font names given an 

+<function>XFontSet</function>,

+use

+<function>XFontsOfFontSet</function>.

+<indexterm significance="preferred"><primary>XFontsOfFontSet</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> XFontsOfFontSet</function></funcdef>

+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

+  <paramdef>XFontStruct<parameter> ***font_struct_list_return</parameter></paramdef>

+  <paramdef>char<parameter> ***font_name_list_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_set</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the font set.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_struct_list_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the list of font structs.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_name_list_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the list of font names.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XFontsOfFontSet</function>

+function returns a list of one or more 

+<function>XFontStructs</function>

+and font names for the fonts used by the Xmb and Xwc layers

+for the given font set.

+A list of pointers to the

+<function>XFontStruct</function>

+structures is returned to font_struct_list_return.

+A list of pointers to null-terminated, fully specified font name strings

+in the locale of the font set is returned to font_name_list_return.

+The font_name_list order corresponds to the font_struct_list order.

+The number of

+<function>XFontStruct</function>

+structures and font names is returned as the value of the function.

+</para>

+<para>

+<!-- .LP -->

+Because it is not guaranteed that a given character will be imaged using a

+single font glyph,

+there is no provision for mapping a character or default string 

+to the font properties, font ID, or direction hint for the font 

+for the character.

+The client may access the 

+<function>XFontStruct</function>

+list to obtain these values for all the fonts currently in use.

+</para>

+<para>

+<!-- .LP -->

+Xlib does not guarantee that fonts are loaded from the server

+at the creation of an 

+<function>XFontSet</function>.

+Xlib may choose to cache font data, loading it only as needed to draw text 

+or compute text dimensions.

+Therefore, existence of the per_char metrics in the 

+<function>XFontStruct</function>

+structures in the

+<function>XFontStructSet</function>

+is undefined.

+Also, note that all properties in the 

+<function>XFontStruct</function>

+structures are in the STRING encoding.

+</para>

+<para>

+<!-- .LP -->

+The 

+<function>XFontStruct</function>

+and font name lists are owned by Xlib 

+and should not be modified or freed by the client.

+They will be freed by a call to

+<function>XFreeFontSet</function>

+with the associated

+<function>XFontSet</function>.

+Until freed, their contents will not be modified by Xlib.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the base font name list and the selected font name list given an

+<function>XFontSet</function>,

+use

+<function>XBaseFontNameListOfFontSet</function>.

+<indexterm significance="preferred"><primary>XBaseFontNameListOfFontSet</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> *XBaseFontNameListOfFontSet</function></funcdef>

+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_set</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the font set.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XBaseFontNameListOfFontSet</function>

+function returns the original base font name list supplied

+by the client when the 

+<function>XFontSet</function>

+was created.

+A null-terminated string containing a list of

+comma-separated font names is returned

+as the value of the function.

+White space may appear immediately on either side of separating commas.

+</para>

+<para>

+<!-- .LP -->

+If 

+<function>XCreateFontSet</function>

+obtained an <acronym>XLFD</acronym> name from the font properties for the font specified

+by a non-<acronym>XLFD</acronym> base name, the

+<function>XBaseFontNameListOfFontSet</function>

+function will return the <acronym>XLFD</acronym> name instead of the non-<acronym>XLFD</acronym> base name.

+</para>

+<para>

+<!-- .LP -->

+The base font name list is owned by Xlib and should not be modified or

+freed by the client.

+It will be freed by a call to 

+<function>XFreeFontSet</function>

+with the associated 

+<function>XFontSet</function>.

+Until freed, its contents will not be modified by Xlib.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the locale name given an 

+<function>XFontSet</function>,

+use

+<function>XLocaleOfFontSet</function>.

+<indexterm significance="preferred"><primary>XLocaleOfFontSet</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> *XLocaleOfFontSet</function></funcdef>

+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_set</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the font set.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XLocaleOfFontSet</function>

+function

+returns the name of the locale bound to the specified

+<function>XFontSet</function>,

+as a null-terminated string.

+</para>

+<para>

+<!-- .LP -->

+The returned locale name string is owned by Xlib

+and should not be modified or freed by the client.

+It may be freed by a call to

+<function>XFreeFontSet</function>

+with the associated 

+<function>XFontSet</function>.

+Until freed, it will not be modified by Xlib.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+The 

+<function>XFreeFontSet</function>

+function is a convenience function for freeing an output context.

+<function>XFreeFontSet </function>

+also frees its associated 

+<function>XOM</function>

+if the output context was created by

+<function>XCreateFontSet</function>.

+<indexterm significance="preferred"><primary>XFreeFontSet</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XFreeFontSet</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_set</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the font set.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XFreeFontSet</function>

+function frees the specified font set.

+The associated base font name list, font name list, 

+<function>XFontStruct</function>

+list, and 

+<function>XFontSetExtents</function>,

+if any, are freed.

+</para>

+</sect2>

+<sect2 id="Obtaining_Font_Set_Metrics">

+<title>Obtaining Font Set Metrics</title>

+<!-- .XS -->

+<!-- (SN Obtaining Font Set Metrics -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Metrics for the internationalized text drawing functions 

+are defined in terms of a primary draw direction, 

+which is the default direction in which the character origin advances

+for each succeeding character in the string.

+The Xlib interface is currently defined to support only a left-to-right

+primary draw direction.

+The drawing origin is the position passed to the drawing function 

+when the text is drawn.

+The baseline is a line drawn through the drawing origin parallel

+to the primary draw direction.

+Character ink is the pixels painted in the foreground color 

+and does not include interline or intercharacter spacing 

+or image text background pixels.

+</para>

+<para>

+<!-- .LP -->

+The drawing functions are allowed to implement implicit text

+directionality control, reversing the order in which characters are

+rendered along the primary draw direction in response to locale-specific

+lexical analysis of the string.

+</para>

+<para>

+<!-- .LP -->

+Regardless of the character rendering order,

+the origins of all characters are on the primary draw direction side

+of the drawing origin.

+The screen location of a particular character image may be determined with

+<function>XmbTextPerCharExtents</function>

+or

+<function>XwcTextPerCharExtents</function>.

+</para>

+<para>

+<!-- .LP -->

+The drawing functions are allowed to implement context-dependent

+rendering, where the glyphs drawn for a string are not simply a

+concatenation of the glyphs that represent each individual character.

+A string of two characters drawn with 

+<function>XmbDrawString</function>

+may render differently than if the two characters 

+were drawn with separate calls to

+<function>XmbDrawString</function>.

+If the client appends or inserts a character 

+in a previously drawn string,

+the client may need to redraw some adjacent characters 

+to obtain proper rendering.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To find out about direction-dependent rendering, use

+<function>XDirectionalDependentDrawing</function>.

+<indexterm significance="preferred"><primary>XDirectionalDependentDrawing</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool<function> XDirectionalDependentDrawing</function></funcdef>

+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_set</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the font set.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XDirectionalDependentDrawing</function>

+function returns

+<function>True</function>

+if the drawing functions implement implicit text directionality;

+otherwise, it returns

+<function>False</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To find out about context-dependent rendering, use

+<function>XContextualDrawing</function>.

+<indexterm significance="preferred"><primary>XContextualDrawing</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool<function> XContextualDrawing</function></funcdef>

+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_set</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the font set.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XContextualDrawing</function>

+function returns

+<function>True</function>

+if text drawn with the font set might include context-dependent drawing;

+otherwise, it returns

+<function>False</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To find out about context-dependent or direction-dependent rendering, use

+<function>XContextDependentDrawing</function>.

+<indexterm significance="preferred"><primary>XContextDependentDrawing</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool<function> XContextDependentDrawing</function></funcdef>

+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_set</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the font set.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XContextDependentDrawing</function>

+function returns

+<function>True</function>

+if the drawing functions implement implicit text directionality or

+if text drawn with the font_set might include context-dependent drawing;

+otherwise, it returns

+<function>False</function>.

+</para>

+<para>

+<!-- .LP -->

+The drawing functions do not interpret newline, tab, or other control

+characters.

+The behavior when nonprinting characters other than space are drawn

+is implementation-dependent.

+It is the client's responsibility to interpret control characters

+in a text stream.

+</para>

+<para>

+<!-- .LP -->

+The maximum character extents for the fonts that are used by the text

+drawing layers can be accessed by the 

+<function>XFontSetExtents</function>

+structure:

+<indexterm significance="preferred"><primary>XFontSetExtents</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     XRectangle max_ink_extent;     /* over all drawable characters */

+     XRectangle max_logical_extent; /* over all drawable characters */

+} XFontSetExtents;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+The 

+<function>XRectangle</function>

+structures used to return font set metrics are the usual Xlib screen-oriented 

+rectangles

+with x, y giving the upper left corner, and width and height always positive.

+</para>

+<para>

+<!-- .LP -->

+The max_ink_extent member gives the maximum extent, over all drawable characters, of

+the rectangles that bound the character glyph image drawn in the

+foreground color, relative to a constant origin.

+See 

+<function>XmbTextExtents</function>

+and

+<function>XwcTextExtents</function>

+for detailed semantics.

+</para>

+<para>

+<!-- .LP -->

+The max_logical_extent member gives the maximum extent,

+over all drawable characters, of the rectangles 

+that specify minimum spacing to other graphical features,

+relative to a constant origin.

+Other graphical features drawn by the client, for example,

+a border surrounding the text, should not intersect this rectangle.

+The max_logical_extent member should be used to compute minimum 

+interline spacing and the minimum area that must be allowed

+in a text field to draw a given number of arbitrary characters.

+</para>

+<para>

+<!-- .LP -->

+Due to context-dependent rendering,

+appending a given character to a string may change 

+the string's extent by an amount other than that character's

+individual extent.

+</para>

+<para>

+<!-- .LP -->

+The rectangles for a given character in a string can be obtained from

+<function>XmbPerCharExtents</function>

+or

+<function>XwcPerCharExtents</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the maximum extents structure given an

+<function>XFontSet</function>,

+use

+<function>XExtentsOfFontSet</function>.

+<indexterm significance="preferred"><primary>XExtentsOfFontSet</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XFontSetExtents<function> *XExtentsOfFontSet</function></funcdef>

+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_set</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the font set.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XExtentsOfFontSet</function>

+function returns an

+<function>XFontSetExtents</function>

+structure for the fonts used by the Xmb and Xwc layers

+for the given font set.

+</para>

+<para>

+<!-- .LP -->

+The 

+<function>XFontSetExtents</function>

+structure is owned by Xlib and should not be modified

+or freed by the client.

+It will be freed by a call to 

+<function>XFreeFontSet</function>

+with the associated 

+<function>XFontSet</function>.

+Until freed, its contents will not be modified by Xlib.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the escapement in pixels of the specified text as a value,

+use

+<function>XmbTextEscapement</function>

+or 

+<function>XwcTextEscapement</function>.

+<indexterm significance="preferred"><primary>XmbTextEscapement</primary></indexterm>

+<indexterm significance="preferred"><primary>XwcTextEscapement</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> XmbTextEscapement</function></funcdef>

+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

+  <paramdef>char<parameter> *string</parameter></paramdef>

+  <paramdef>int<parameter> num_bytes</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> XwcTextEscapement</function></funcdef>

+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

+  <paramdef>wchar_t<parameter> *string</parameter></paramdef>

+  <paramdef>int<parameter> num_wchars</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_set</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the font set.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the character string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>num_bytes</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of bytes in the string argument.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>num_wchars</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of characters in the string argument.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XmbTextEscapement</function>

+and

+<function>XwcTextEscapement</function>

+functions return the escapement in pixels of the specified string as a value,

+using the fonts loaded for the specified font set.

+The escapement is the distance in pixels in the primary draw

+direction from the drawing origin to the origin of the next character to

+be drawn, assuming that the rendering of the next character is not

+dependent on the supplied string.

+</para>

+<para>

+<!-- .LP -->

+Regardless of the character rendering order,

+the escapement is always positive.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the overall_ink_return and overall_logical_return arguments,

+the overall bounding box of the string's image, and a logical bounding box,

+use

+<function>XmbTextExtents</function>

+ or

+<function>XwcTextExtents</function>.

+<indexterm significance="preferred"><primary>XmbTextExtents</primary></indexterm>

+<indexterm significance="preferred"><primary>XwcTextExtents</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> XmbTextExtents</function></funcdef>

+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

+  <paramdef>char<parameter> *string</parameter></paramdef>

+  <paramdef>int<parameter> num_bytes</parameter></paramdef>

+  <paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>

+  <paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> XwcTextExtents</function></funcdef>

+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

+  <paramdef>wchar_t<parameter> *string</parameter></paramdef>

+  <paramdef>int<parameter> num_wchars</parameter></paramdef>

+  <paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>

+  <paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_set</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the font set.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the character string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>num_bytes</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of bytes in the string argument.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>num_wchars</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of characters in the string argument.

+<!-- .ds Ov dimensions -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>overall_ink_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the overall ink dimensions.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>overall_logical_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the overall logical dimensions.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XmbTextExtents</function>

+and

+<function>XwcTextExtents</function>

+functions set the components of the specified overall_ink_return and

+overall_logical_return

+arguments to the overall bounding box of the string's image

+and a logical bounding box for spacing purposes, respectively.

+They return the value returned by 

+<function>XmbTextEscapement</function>

+or

+<function>XwcTextEscapement</function>.

+These metrics are relative to the drawing origin of the string,

+using the fonts loaded for the specified font set.

+</para>

+<para>

+<!-- .LP -->

+If the overall_ink_return argument is non-NULL,

+it is set to the bounding box of the string's character ink.

+The overall_ink_return for a nondescending, horizontally drawn

+Latin character is conventionally entirely above the baseline;

+that is, overall_ink_return.height &lt;= -overall_ink_return.y.

+The overall_ink_return for a nonkerned character

+is entirely at, and to the right of, the origin;

+that is, overall_ink_return.x &gt;= 0.

+A character consisting of a single pixel at the origin would set

+overall_ink_return fields y = 0, x = 0, width = 1, and height = 1.

+</para>

+<para>

+<!-- .LP -->

+If the overall_logical_return argument is non-NULL,

+it is set to the bounding box that provides minimum spacing

+to other graphical features for the string.

+Other graphical features, for example, a border surrounding the text,

+should not intersect this rectangle.

+</para>

+<para>

+<!-- .LP -->

+When the 

+<function>XFontSet</function>

+has missing charsets,

+metrics for each unavailable character are taken 

+from the default string returned by 

+<function>XCreateFontSet </function>

+so that the metrics represent the text as it will actually be drawn.

+The behavior for an invalid codepoint is undefined.

+</para>

+<para>

+<!-- .LP -->

+To determine the effective drawing origin for a character in a drawn string,

+the client should call 

+<function>XmbTextPerCharExtents</function>

+on the entire string, then on the character,

+and subtract the x values of the returned 

+rectangles for the character.

+This is useful to redraw portions of a line of text

+or to justify words, but for context-dependent rendering,

+the client should not assume that it can redraw the character by itself

+and get the same rendering.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain per-character information for a text string,

+use

+<function>XmbTextPerCharExtents</function>

+or

+<function>XwcTextPerCharExtents</function>.

+<indexterm significance="preferred"><primary>XmbTextPerCharExtents</primary></indexterm>

+<indexterm significance="preferred"><primary>XwcTextPerCharExtents</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XmbTextPerCharExtents</function></funcdef>

+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

+  <paramdef>char<parameter> *string</parameter></paramdef>

+  <paramdef>int<parameter> num_bytes</parameter></paramdef>

+  <paramdef>XRectangle<parameter> *ink_array_return</parameter></paramdef>

+  <paramdef>XRectangle<parameter> *logical_array_return</parameter></paramdef>

+  <paramdef>int<parameter> array_size</parameter></paramdef>

+  <paramdef>int<parameter> *num_chars_return</parameter></paramdef>

+  <paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>

+  <paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XwcTextPerCharExtents</function></funcdef>

+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

+  <paramdef>wchar_t<parameter> *string</parameter></paramdef>

+  <paramdef>int<parameter> num_wchars</parameter></paramdef>

+  <paramdef>XRectangle<parameter> *ink_array_return</parameter></paramdef>

+  <paramdef>XRectangle<parameter> *logical_array_return</parameter></paramdef>

+  <paramdef>int<parameter> array_size</parameter></paramdef>

+  <paramdef>int<parameter> *num_chars_return</parameter></paramdef>

+  <paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>

+  <paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_set</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the font set.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the character string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>num_bytes</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of bytes in the string argument.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>num_wchars</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of characters in the string argument.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ink_array_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the ink dimensions for each character.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>logical_array_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the logical dimensions for each character.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>array_size</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the size of ink_array_return and logical_array_return.

+The caller must pass in arrays of this size.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>num_chars_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of characters in the string argument.

+<!-- .ds Ov extents of the entire string -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>overall_ink_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the overall ink dimensions.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>overall_logical_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the overall logical dimensions.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XmbTextPerCharExtents</function>

+and

+<function>XwcTextPerCharExtents</function>

+functions return the text dimensions of each character of the specified text,

+using the fonts loaded for the specified font set.

+Each successive element of ink_array_return and logical_array_return

+is set to the successive character's drawn metrics,

+relative to the drawing origin of the string and one 

+rectangle

+for each character in the supplied text string.

+The number of elements of ink_array_return and logical_array_return

+that have been set is returned to num_chars_return.

+</para>

+<para>

+<!-- .LP -->

+Each element of ink_array_return is set to the bounding box 

+of the corresponding character's drawn foreground color.

+Each element of logical_array_return is set to the bounding box 

+that provides minimum spacing to other graphical features

+for the corresponding character.

+Other graphical features should not intersect any of the

+logical_array_return rectangles.

+</para>

+<para>

+<!-- .LP -->

+Note that an 

+<function>XRectangle</function>

+represents the effective drawing dimensions of the character,

+regardless of the number of font glyphs that are used to draw

+the character or the direction in which the character is drawn.

+If multiple characters map to a single character glyph,

+the dimensions of all the 

+<function>XRectangles</function>

+of those characters are the same.

+</para>

+<para>

+<!-- .LP -->

+When the 

+<function>XFontSet</function>

+has missing charsets, metrics for each unavailable

+character are taken from the default string returned by 

+<function>XCreateFontSet</function>

+so that the metrics represent the text as it will actually be drawn.

+The behavior for an invalid codepoint is undefined.

+</para>

+<para>

+<!-- .LP -->

+If the array_size is too small for the number of characters in the

+supplied text, the functions return zero

+and num_chars_return is set to the number of rectangles required.

+Otherwise, the functions return a nonzero value.

+</para>

+<para>

+<!-- .LP -->

+If the overall_ink_return or overall_logical_return argument is non-NULL,

+<function>XmbTextPerCharExtents</function>

+and 

+<function>XwcTextPerCharExtents</function>

+return the maximum extent of the string's metrics to overall_ink_return

+or overall_logical_return, as returned by 

+<function>XmbTextExtents</function>

+or 

+<function>XwcTextExtents</function>.

+</para>

+</sect2>

+<sect2 id="Drawing_Text_Using_Font_Sets">

+<title>Drawing Text Using Font Sets</title>

+<!-- .XS -->

+<!-- (SN Drawing Text Using Font Sets -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The functions defined in this section

+draw text at a specified location in a drawable.

+They are similar to the functions

+<function>XDrawText</function>,

+<function>XDrawString</function>,

+and

+<function>XDrawImageString</function>

+except that they work with font sets instead of single fonts

+and interpret the text based on the locale of the font set

+instead of treating the bytes of the string as direct font indexes.

+See section 8.6 for details of the use of Graphics Contexts (GCs)

+and possible protocol errors.

+If a 

+<function>BadFont</function>

+error is generated,

+characters prior to the offending character may have been drawn.

+</para>

+<para>

+<!-- .LP -->

+The text is drawn using the fonts loaded for the specified font set;

+the font in the GC is ignored and may be modified by the functions.

+No validation that all fonts conform to some width rule is performed.

+</para>

+<para>

+<!-- .LP -->

+The text functions

+<function>XmbDrawText</function>

+and

+<function>XwcDrawText</function>

+use the following structures:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XmbTextItem</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct {

+     char     *chars;    /* pointer to string */

+     int      nchars;    /* number of bytes */

+     int      delta;     /* pixel delta between strings */

+     XFontSet font_set;  /* fonts, None means don't change */

+} XmbTextItem;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XwcTextItem</primary></indexterm>

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct {

+     wchar_t *chars;     /* pointer to wide char string */

+     int nchars;     /* number of wide characters */

+     int delta;     /* pixel delta between strings */

+     XFontSet font_set;     /* fonts, None means don't change */

+} XwcTextItem;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To draw text using multiple font sets in a given drawable, use

+<function>XmbDrawText</function>

+or

+<function>XwcDrawText</function>.

+<indexterm significance="preferred"><primary>XmbDrawText</primary></indexterm>

+<indexterm significance="preferred"><primary>XwcDrawText</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XmbDrawText</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>XmbTextItem<parameter> *items</parameter></paramdef>

+  <paramdef>int<parameter> nitems</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XwcDrawText</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>XwcTextItem<parameter> *items</parameter></paramdef>

+  <paramdef>int<parameter> nitems</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+<!-- .ds Xy -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>items</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array of text items.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nitems</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of text items in the array.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XmbDrawText</function>

+and 

+<function>XwcDrawText </function>

+functions allow complex spacing and font set shifts between text strings.

+Each text item is processed in turn, with the origin of a text

+element advanced in the primary draw direction by the escapement of the

+previous text item.

+A text item delta specifies an additional escapement of the text item

+drawing origin in the primary draw direction.

+A font_set member other than 

+<function>None</function>

+in an item causes the font set to be used for this and subsequent text items

+in the text_items list.

+Leading text items with a font_set member set to

+<function>None</function>

+will not be drawn.

+</para>

+<para>

+<!-- .LP -->

+<function>XmbDrawText</function>

+and

+<function>XwcDrawText</function>

+do not perform any context-dependent rendering between text segments.

+Clients may compute the drawing metrics by passing each text segment to

+<function>XmbTextExtents</function>

+and

+<function>XwcTextExtents</function>

+or 

+<function>XmbTextPerCharExtents</function>

+and

+<function>XwcTextPerCharExtents</function>.

+When the 

+<function>XFontSet</function>

+has missing charsets, each unavailable character is drawn 

+with the default string returned by 

+<function>XCreateFontSet</function>.

+The behavior for an invalid codepoint is undefined.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To draw text using a single font set in a given drawable, use

+<function>XmbDrawString</function>

+or

+<function>XwcDrawString</function>.

+<indexterm significance="preferred"><primary>XmbDrawString</primary></indexterm>

+<indexterm significance="preferred"><primary>XwcDrawString</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XmbDrawString</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>char<parameter> *string</parameter></paramdef>

+  <paramdef>int<parameter> num_bytes</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XwcDrawString</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>wchar_t<parameter> *string</parameter></paramdef>

+  <paramdef>int<parameter> num_wchars</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_set</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the font set.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+<!-- .ds Xy -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the character string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>num_bytes</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of bytes in the string argument.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>num_wchars</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of characters in the string argument.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XmbDrawString</function>

+and

+<function>XwcDrawString</function>

+functions draw the specified text with the foreground pixel.

+When the 

+<function>XFontSet</function>

+has missing charsets, each unavailable character is drawn 

+with the default string returned by 

+<function>XCreateFontSet</function>.

+The behavior for an invalid codepoint is undefined.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To draw image text using a single font set in a given drawable, use

+<function>XmbDrawImageString</function>

+or

+<function>XwcDrawImageString</function>.

+<indexterm significance="preferred"><primary>XmbDrawImageString</primary></indexterm>

+<indexterm significance="preferred"><primary>XwcDrawImageString</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XmbDrawImageString</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>char<parameter> *string</parameter></paramdef>

+  <paramdef>int<parameter> num_bytes</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XwcDrawImageString</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>wchar_t<parameter> *string</parameter></paramdef>

+  <paramdef>int<parameter> num_wchars</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>font_set</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the font set.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+<!-- .ds Xy -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the character string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>num_bytes</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of bytes in the string argument.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>num_wchars</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of characters in the string argument.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XmbDrawImageString</function>

+and

+<function>XwcDrawImageString</function>

+functions fill a destination rectangle with the background pixel defined

+in the GC and then paint the text with the foreground pixel.

+The filled rectangle is the rectangle returned to overall_logical_return by

+<function>XmbTextExtents</function>

+or 

+<function>XwcTextExtents</function>

+for the same text and 

+<function>XFontSet</function>.

+</para>

+<para>

+<!-- .LP -->

+When the 

+<function>XFontSet</function>

+has missing charsets, each unavailable character is drawn 

+with the default string returned by 

+<function>XCreateFontSet</function>.

+The behavior for an invalid codepoint is undefined.

+</para>

+</sect2>

+</sect1>

+<sect1 id="Input_Methods">

+<title>Input Methods</title>

+<!-- .XS -->

+<!-- (SN Input Methods -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+This section provides discussions of the following X Input Method

+(<acronym>XIM</acronym>) topics:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Input method overview

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Input method management

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Input method functions

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Input method values

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Input context functions

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Input context values

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Input method callback semantics

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Event filtering

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Getting keyboard input

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Input method conventions

+    </para>

+  </listitem>

+</itemizedlist>

+<sect2 id="Input_Method_Overview">

+<title>Input Method Overview</title>

+<!-- .XS -->

+<!-- (SN Input Method Overview -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+This section provides definitions for terms and concepts used

+for internationalized text input and a brief overview of the

+intended use of the mechanisms provided by Xlib.

+</para>

+<para>

+<!-- .LP -->

+A large number of languages in the world use alphabets

+consisting of a small set of symbols (letters) to form words.

+To enter text into a computer in an alphabetic language,

+a user usually has a keyboard on which there exist key symbols corresponding

+to the alphabet.

+Sometimes, a few characters of an alphabetic language are missing

+on the keyboard.

+Many computer users who speak a Latin-alphabet-based language 

+only have an English-based keyboard.

+They need to hit a combination of keystrokes

+to enter a character that does not exist directly on the keyboard.

+A number of algorithms have been developed for entering such characters.

+These are known as European input methods, compose input methods, 

+or dead-key input methods.

+</para>

+<para>

+<!-- .LP -->

+Japanese is an example of a language with a phonetic symbol set,

+where each symbol represents a specific sound.

+There are two phonetic symbol sets in Japanese:  Katakana and Hiragana.

+In general,

+Katakana is used for words that are of foreign origin,

+and Hiragana is used for writing native Japanese words.

+Collectively, the two systems are called Kana.

+Each set consists of 48 characters.

+</para>

+<para>

+<!-- .LP -->

+Korean also has a phonetic symbol set, called Hangul.

+Each of the 24 basic phonetic symbols (14 consonants and 10 vowels)

+represents a specific sound.

+A syllable is composed of two or three parts: 

+the initial consonants, the vowels, and the optional last consonants.

+With Hangul,

+syllables can be treated as the basic units on which text processing is done.

+For example,

+a delete operation may work on a phonetic symbol or a syllable.

+Korean code sets include several thousands of these syllables.

+A user types the phonetic symbols that make up the syllables of the words

+to be entered.

+The display may change as each phonetic symbol is entered.

+For example,

+when the second phonetic symbol of a syllable is entered,

+the first phonetic symbol may change its shape and size.

+Likewise, when the third phonetic symbol is entered,

+the first two phonetic symbols may change their shape and size.

+</para>

+<para>

+<!-- .LP -->

+Not all languages rely solely on alphabetic or phonetic systems.

+Some languages, including Japanese and Korean, employ an

+ideographic writing system.

+In an ideographic system, rather than taking a small set of

+symbols and combining them in different ways to create words,

+each word consists of one unique symbol (or, occasionally, several symbols).

+The number of symbols can be very large: 

+approximately 50,000 have been identified in Hanzi,

+the Chinese ideographic system.

+</para>

+<para>

+<!-- .LP -->

+Two major aspects of ideographic systems impact their use with computers.

+First, the standard computer character sets in Japan, China, and Korea

+include roughly 8,000 characters,

+while sets in Taiwan have between 15,000 and 30,000 characters.

+This makes it necessary to use more than one byte to represent a character.

+Second, it obviously is impractical to have a keyboard that includes

+all of a given language's ideographic symbols.

+Therefore, a mechanism is required for entering characters

+so that a keyboard with a reasonable number of keys can be used.

+Those input methods are usually based on phonetics,

+but there also exist methods based on the graphical properties of

+characters.

+</para>

+<para>

+<!-- .LP -->

+In Japan, both Kana and the ideographic system Kanji are used.

+In Korea, Hangul and sometimes the ideographic system Hanja are used.

+Now consider entering ideographs in Japan, Korea, China, and Taiwan.

+</para>

+<para>

+<!-- .LP -->

+In Japan, either Kana or English characters are typed and then a region

+is selected (sometimes automatically) for conversion to Kanji.

+Several Kanji characters may have the same phonetic representation.

+If that is the case with the string entered,

+a menu of characters is presented and

+the user must choose the appropriate one.

+If no choice is necessary or a preference has been established,

+the input method does the substitution directly.

+When Latin characters are converted to Kana or Kanji,

+it is called a romaji conversion.

+</para>

+<para>

+<!-- .LP -->

+In Korea, it is usually acceptable to keep Korean text in Hangul form,

+but some people may choose to write Hanja-originated words in Hanja

+rather than in Hangul.

+To change Hangul to Hanja,

+the user selects a region for conversion

+and then follows the same basic method as that described for Japanese.

+</para>

+<para>

+<!-- .LP -->

+Probably because there are well-accepted phonetic writing systems

+for Japanese and Korean,

+computer input methods in these countries for entering ideographs 

+are fairly standard.

+Keyboard keys have both English characters and phonetic symbols

+engraved on them, and the user can switch between the two sets.

+</para>

+<para>

+<!-- .LP -->

+The situation is different for Chinese.

+While there is a phonetic system called Pinyin promoted by authorities,

+there is no consensus for entering Chinese text.

+Some vendors use a phonetic decomposition (Pinyin or another),

+others use ideographic decomposition of Chinese words,

+with various implementations and keyboard layouts. 

+There are about 16 known methods, none of which is a clear standard. 

+</para>

+<para>

+<!-- .LP -->

+Also, there are actually two ideographic sets used:

+Traditional Chinese (the original written Chinese)

+and Simplified Chinese.

+Several years ago,

+the People's Republic of China launched a campaign to simplify

+some ideographic characters and eliminate redundancies altogether.

+Under the plan, 

+characters would be streamlined every five years.

+Characters have been revised several times now, 

+resulting in the smaller, simpler set that makes up Simplified Chinese.

+</para>

+<sect3 id="Input_Method_Architecture">

+<title>Input Method Architecture</title>

+<!-- .XS -->

+<!-- (SN Input Method Architecture -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+As shown in the previous section,

+there are many different input methods in use today,

+each varying with language, culture, and history. 

+A common feature of many input methods is that the user may type

+multiple keystrokes to compose a single character (or set

+of characters).

+The process of composing characters from keystrokes is called

+<emphasis remap='I'>preediting</emphasis>.

+It may require complex algorithms and large dictionaries 

+involving substantial computer resources.

+</para>

+<para>

+<!-- .LP -->

+Input methods may require one or more areas in which to show the

+feedback of the actual keystrokes, to propose disambiguation to the

+user, to list dictionaries, and so on.

+The input method areas of concern are as follows:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+The <emphasis remap='I'>status</emphasis> area is a logical extension of the

+LEDs that exist on the physical keyboard.

+It is a window that is intended to present the internal state

+of the input method that is critical to the user.

+The status area may consist of text data and bitmaps or some combination.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The <emphasis remap='I'>preedit</emphasis> area displays the

+intermediate text for those languages that are composing prior to 

+the client handling the data.   

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The <emphasis remap='I'>auxiliary</emphasis> area is used for pop-up menus and customizing

+dialogs that may be required for an input method.

+There may be multiple auxiliary areas for an input method.

+Auxiliary areas are managed by the input method independent of the client.

+Auxiliary areas are assumed to be separate dialogs,

+which are maintained by the input method.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+There are various user interaction styles used for preediting.

+The ones supported by Xlib are as follows:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+For <emphasis remap='I'>on-the-spot</emphasis> input methods,

+preediting data will be displayed directly in the application window.

+Application data is moved to allow preedit data to appear

+at the point of insertion.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<emphasis remap='I'>Over-the-spot</emphasis> preediting means that the data is displayed in

+a preedit window that is placed over the point of insertion.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<emphasis remap='I'>Off-the-spot</emphasis> preediting means that the preedit window is

+inside the application window but not at the point of insertion.

+Often, this type of window is placed at the bottom of the application window.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<emphasis remap='I'>Root-window</emphasis> preediting refers to input methods that use a preedit

+window that is the child of 

+<function>RootWindow</function>.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+It would require a lot of computing resources if portable applications

+had to include input methods for all the languages in the world.

+To avoid this,

+a goal of the Xlib design is to allow an application 

+to communicate with an input method placed in a separate process.

+Such a process is called an <emphasis remap='I'>input server</emphasis>.

+The server to which the application should connect is dependent on

+the environment when the application is started up,

+that is, the user language and the actual encoding to be used for it.

+The input method connection is said to be <emphasis remap='I'>locale-dependent</emphasis>.

+It is also user-dependent.

+For a given language, the user can choose, to some extent,

+the user interface style of input method (if choice is possible among

+several).

+</para>

+<para>

+<!-- .LP -->

+Using an input server implies communication overhead,

+but applications can be migrated without relinking.

+Input methods can be implemented either as a

+stub communicating to an input server or as a local library.

+</para>

+<para>

+<!-- .LP -->

+An input method may be based on a <emphasis remap='I'>front-end</emphasis> or a <emphasis remap='I'>back-end</emphasis>

+architecture.

+In a front-end architecture,

+there are two separate connections to the X server:

+keystrokes go directly from the X server to the input method on

+one connection and other events to the regular client connection.

+The input method is then acting as a filter and sends composed strings

+to the client.

+A front-end architecture requires synchronization between the

+two connections to avoid lost key events or locking issues.

+</para>

+<para>

+<!-- .LP -->

+In a back-end architecture,

+a single X server connection is used.

+A dispatching mechanism must decide on this channel to delegate appropriate

+keystrokes to the input method.

+For instance,

+it may retain a Help keystroke for its own purpose.

+In the case where the input method is a separate process (that is, a server),

+there must be a special communication protocol between the back-end client

+and the input server.

+</para>

+<para>

+<!-- .LP -->

+A front-end architecture introduces synchronization issues

+and a filtering mechanism for noncharacter keystrokes

+(Function keys, Help, and so on).

+A back-end architecture sometimes implies more communication overhead

+and more process switching.

+If all three processes (X server, input server, client)

+are running on a single workstation, 

+there are two process switches for each keystroke in a back-end

+architecture,

+but there is only one in a front-end architecture.

+</para>

+<para>

+<!-- .LP -->

+The abstraction used by a client to communicate with an input method

+is an opaque data structure represented by the 

+<function>XIM</function>

+data type.

+This data structure is returned by the 

+<function>XOpenIM</function>

+function, which opens an input method on a given display.

+Subsequent operations on this data structure encapsulate all communication

+between client and input method.

+There is no need for an X client to use any networking library 

+or natural language package to use an input method.

+</para>

+<para>

+<!-- .LP -->

+A single input server may be used for one or more languages,

+supporting one or more encoding schemes.

+But the strings returned from an input method will always be encoded

+in the (single) locale associated with the

+<function>XIM</function>

+object.

+</para>

+</sect3>

+<sect3 id="Input_Contexts">

+<title>Input Contexts</title>

+<!-- .XS -->

+<!-- (SN Input Contexts -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides the ability to manage a multi-threaded state for text input.

+A client may be using multiple windows,

+each window with multiple text entry areas,

+and the user possibly switching among them at any time.

+The abstraction for representing the state of a particular input thread

+is called an <emphasis remap='I'>input context</emphasis>.

+The Xlib representation of an input context is an 

+<function>XIC</function>.

+</para>

+<para>

+<!-- .LP -->

+An input context is the abstraction retaining the state, properties,

+and semantics of communication between a client and an input method.

+An input context is a combination of an input method, a locale

+specifying the encoding of the character strings to be returned,

+a client window, internal state information,

+and various layout or appearance characteristics.

+The input context concept somewhat matches for input the graphics context

+abstraction defined for graphics output.

+</para>

+<para>

+<!-- .LP -->

+One input context belongs to exactly one input method.

+Different input contexts may be associated with the same input method,

+possibly with the same client window.

+An 

+<function>XIC</function>

+is created with the

+<function>XCreateIC</function>

+function, providing an 

+<function>XIM</function>

+argument and affiliating the input context to the input method

+for its lifetime. 

+When an input method is closed with 

+<function>XCloseIM</function>,

+all of its affiliated input contexts should not be used any more

+(and should preferably be destroyed before closing the input method).

+</para>

+<para>

+<!-- .LP -->

+Considering the example of a client window with multiple text entry areas,

+the application programmer could, for example, choose to implement as follows:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+As many input contexts are created as text entry areas, and the client

+will get the input accumulated on each context each time it looks up

+in that context.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A single context is created for a top-level window in the application.

+If such a window contains several text entry areas, 

+each time the user moves to another text entry area,

+the client has to indicate changes in the context.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+A range of choices can be made by application designers to use

+either a single or multiple input contexts,

+according to the needs of their application.

+</para>

+</sect3>

+<sect3 id="Getting_Keyboard_Input">

+<title>Getting Keyboard Input</title>

+<!-- .XS -->

+<!-- (SN Getting Keyboard Input -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To obtain characters from an input method,

+a client must call the function

+<function>XmbLookupString</function>

+or 

+<function>XwcLookupString</function>

+with an input context created from that input method.

+Both a locale and display are bound to an input method when it is opened,

+and an input context inherits this locale and display.

+Any strings returned by 

+<function>XmbLookupString</function>

+or

+<function>XwcLookupString</function>

+will be encoded in that locale. 

+</para>

+</sect3>

+<sect3 id="Focus_Management">

+<title>Focus Management</title>

+<!-- .XS -->

+<!-- (SN Focus Management -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+For each text entry area in which the

+<function>XmbLookupString</function>

+or

+<function>XwcLookupString</function>

+functions are used,

+there will be an associated input context.

+</para>

+<para>

+<!-- .LP -->

+When the application focus moves to a text entry area,

+the application must set the input context focus to the

+input context associated with that area.

+The input context focus is set by calling 

+<function>XSetICFocus</function>

+with the appropriate input context.

+</para>

+<para>

+<!-- .LP -->

+Also, when the application focus moves out of a text entry area, the

+application should unset the focus for the associated input context

+by calling

+<function>XUnsetICFocus</function>.

+As an optimization, if

+<function>XSetICFocus</function>

+is called successively on two different input contexts,

+setting the focus on the second 

+will automatically unset the focus on the first.

+</para>

+<para>

+<!-- .LP -->

+To set and unset the input context focus correctly,

+it is necessary to track application-level focus changes.

+Such focus changes do not necessarily correspond to X server focus changes.

+</para>

+<para>

+<!-- .LP -->

+If a single input context

+is being used to do input for

+multiple text entry areas, it will also be necessary

+to set the focus window of the

+input context whenever the focus window changes

+(see section 13.5.6.3).

+</para>

+</sect3>

+<sect3 id="Geometry_Management">

+<title>Geometry Management</title>

+<!-- .XS -->

+<!-- (SN Geometry Management -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+In most input method architectures 

+(on-the-spot being the notable exception),

+the input method will perform the display of its own data.

+To provide better visual locality,

+it is often desirable to have the input method areas embedded within a client.

+To do this,

+the client may need to allocate space for an input method.

+Xlib provides support that allows the size and position of input method

+areas to be provided by a client.

+The input method areas that are supported for geometry management

+are the status area and the preedit area.

+</para>

+<para>

+<!-- .LP -->

+The fundamental concept on which geometry management for input method windows

+is based is the proper division of responsibilities between the

+client (or toolkit) and the input method.

+The division of responsibilities is as follows:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+The client is responsible for the geometry of the input method window.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The input method is responsible for the contents of the input method window.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+An input method is able to suggest a size to the client,

+but it cannot suggest a placement.

+Also the input method can only suggest a size.

+It does not determine the size,

+and it must accept the size it is given.

+</para>

+<para>

+<!-- .LP -->

+Before a client provides geometry management for an input method,

+it must determine if geometry management is needed.

+The input method indicates the need for geometry management 

+by setting 

+<function>XIMPreeditArea</function>

+or 

+<function>XIMStatusArea</function>

+in its 

+<function>XIMStyles</function>

+value returned by 

+<function>XGetIMValues</function>.

+When a client has decided that it will provide geometry management

+for an input method, 

+it indicates that decision by setting the

+<function>XNInputStyle</function>

+value in the 

+<function>XIC</function>.

+</para>

+<para>

+<!-- .LP -->

+After a client has established with the input method

+that it will do geometry management,

+the client must negotiate the geometry with the input method.

+The geometry is negotiated by the following steps:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+The client suggests an area to the input method by setting the

+<function>XNAreaNeeded</function>

+value for that area.

+If the client has no constraints for the input method,

+it either will not suggest an area or will set the width and height to zero.

+Otherwise, it will set one of the values.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The client will get the <acronym>XIC</acronym> value 

+<function>XNAreaNeeded</function>.

+The input method will return its suggested size in this value.

+The input method should pay attention to any constraints suggested

+by the client.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The client sets the <acronym>XIC</acronym> value

+<function>XNArea</function>

+to inform the input method of the geometry of its window.  

+The client should try to honor the geometry requested by the input method.

+The input method must accept this geometry.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+Clients doing geometry management must be aware that setting other

+<acronym>XIC</acronym> values may affect the geometry desired by an input method.

+For example, 

+<function>XNFontSet</function>

+and

+<function>XNLineSpacing</function>

+may change the geometry desired by the input method.  

+</para>

+<para>

+<!-- .LP -->

+The table of <acronym>XIC</acronym> values (see section 13.5.6)

+indicates the values that can cause the desired geometry to change

+when they are set.

+It is the responsibility of the client to renegotiate the geometry

+of the input method window when it is needed.

+</para>

+<para>

+<!-- .LP -->

+In addition,

+a geometry management callback is provided

+by which an input method can initiate a geometry change.

+</para>

+</sect3>

+<sect3 id="Event_Filtering">

+<title>Event Filtering</title>

+<!-- .XS -->

+<!-- (SN Event Filtering -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+A filtering mechanism is provided to allow input methods

+to capture X events transparently to clients.

+It is expected that toolkits (or clients) using

+<function>XmbLookupString</function>

+or

+<function>XwcLookupString </function>

+will call this filter at some point in the event processing mechanism

+to make sure that events needed by an input method can be filtered

+by that input method.

+</para>

+<para>

+<!-- .LP -->

+If there were no filter,

+a client could receive and discard events that are necessary

+for the proper functioning of an input method.

+The following provides a few examples of such events:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Expose events on preedit window in local mode.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Events may be used by an input method to communicate with an input server.

+Such input server protocol-related events have to be intercepted

+if one does not want to disturb client code.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Key events can be sent to a filter before they are bound

+to translations such as those the X Toolkit Intrinsics library provides.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+Clients are expected to get the <acronym>XIC</acronym> value 

+<function>XNFilterEvents</function>

+and augment the event mask for the client window with that event mask.

+This mask may be zero.

+</para>

+</sect3>

+<sect3 id="Callbacks">

+<title>Callbacks</title>

+<!-- .XS -->

+<!-- (SN Callbacks -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+When an on-the-spot input method is implemented,

+only the client can insert or delete preedit data in place

+and possibly scroll existing text.

+This means that the echo of the keystrokes has to be achieved 

+by the client itself, tightly coupled with the input method logic.

+</para>

+<para>

+<!-- .LP -->

+When the user enters a keystroke,

+the client calls

+<function>XmbLookupString</function>

+or

+<function>XwcLookupString</function>.

+At this point, in the on-the-spot case,

+the echo of the keystroke in the preedit has not yet been done.

+Before returning to the client logic that handles the input characters,

+the look-up function

+must call the echoing logic to insert the new keystroke.

+If the keystrokes entered so far make up a character,

+the keystrokes entered need to be deleted,

+and the composed character will be returned.

+Hence, what happens is that, while being called by client code,

+the input method logic has to call back to the client before it returns.

+The client code, that is, a callback procedure,

+is called from the input method logic.

+</para>

+<para>

+<!-- .LP -->

+There are a number of cases where the input method logic has to

+call back the client.

+Each of those cases is associated with a well-defined callback action.

+It is possible for the client to specify, for each input context,

+what callback is to be called for each action.

+</para>

+<para>

+<!-- .LP -->

+There are also callbacks provided for feedback of status information

+and a callback to initiate a geometry request for an input method.

+</para>

+</sect3>

+<sect3 id="Visible_Position_Feedback_Masks">

+<title>Visible Position Feedback Masks</title>

+<!-- .XS -->

+<!-- (SN Visible Position Feedback Masks -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+In the on-the-spot input style, there is a problem when

+attempting to draw preedit strings that are longer than the

+available space.  Once the display area is exceeded, it is not

+clear how best to display the preedit string.

+The visible position feedback masks of

+<function>XIMText</function>

+help resolve this problem by allowing the input method to specify hints that

+indicate the essential portions of the preedit string.

+For example, such hints can help developers implement

+scrolling of a long preedit string within a short preedit display area.

+</para>

+</sect3>

+<sect3 id="Preedit_String_Management">

+<title>Preedit String Management</title>

+<!-- .XS -->

+<!-- (SN Preedit String Management -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+As highlighted before, the input method architecture provides

+preediting, which supports a type of preprocessor input composition.

+In this case, composition consists of interpreting a sequence

+of key events and returning a committed string via 

+<function>XmbLookupString</function>

+or

+<function>XwcLookupString</function>.

+This provides the basics for input methods.

+</para>

+<para>

+<!-- .LP -->

+In addition to preediting based on key events, a general framework

+is provided to give a client that desires it more advanced preediting based

+on the text within the client.  This framework is called 

+<emphasis remap='I'>string conversion</emphasis> and is provided using <acronym>XIC</acronym> values. 

+The fundamental concept of string conversion

+is to allow the input method to manipulate the client's

+text independent of any user preediting operation.

+</para>

+<para>

+<!-- .LP -->

+The need for string conversion is based on 

+language needs and input method capabilities.

+The following are some examples of string conversion:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Transliteration conversion provides language-specific conversions

+within the input method.

+In the case of Korean input, users wish to convert a Hangul string 

+into a Hanja string while in preediting, after preediting,

+or in other situations (for example, on a selected string).

+The conversion is triggered when the user

+presses a Hangul-to-Hanja key sequence (which may be input method specific).

+Sometimes the user may want to invoke the conversion after finishing

+preediting or on a user-selected string.  

+Thus, the string to be converted is in an application buffer, not in 

+the preedit area of the input method.  The string conversion services

+allow the client to request this transliteration conversion from the 

+input method.

+There are many other transliteration conversions defined for 

+various languages, for example, Kana-to-Kanji conversion in Japanese.

+<!-- .sp -->

+The key to remember is that transliteration conversions are triggered

+at the request of the user and returned to the client 

+immediately without affecting the preedit area of the input method.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Reconversion of a previously committed string or 

+a selected string is supported by many input methods as a 

+convenience to the user.

+For example, a user tends to mistype the commit key while

+preediting.  In that case, some input methods provide a special

+key sequence to request a ``reconvert'' operation on the 

+committed string, similiar to the undo facility provided by most

+text editors.

+Another example is where the user is proofreading a document 

+that has some misconversions from preediting and wants to correct

+the misconverted text.  Such reconversion is again triggered

+by the user invoking some special action, but reconversions should

+not affect the state of the preedit area.  

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Context-sensitive conversion is required for some languages

+and input methods that need to retrieve text that surrounds the

+current spot location (cursor position) of the client's buffer.

+Such text is needed when the preediting operation depends on 

+some surrounding characters (usually preceding the spot location).

+For example, 

+in Thai language input, certain character sequences may be invalid and

+the input method may want to check whether characters constitute a

+valid word.  Input methods that do such context-dependent

+checking need to retrieve the characters surrounding the current

+cursor position to obtain complete words.

+<!-- .sp -->

+Unlike other conversions, this conversion is not explicitly 

+requested by the user.

+Input methods that provide such context-sensitive conversion 

+continuously need to request context from the client, and any change

+in the context of the spot location may affect such conversions.

+The client's context would be needed if the user moves the cursor

+and starts editing again.

+<!-- .sp -->

+For this reason, an input method supporting this type of conversion

+should take notice of when the client calls

+<function>XmbResetIC</function>

+or

+<function>XwcResetIC</function>,

+which is usually an indication of a context change.  

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+Context-sensitive conversions just need a copy of the client's text,

+while other conversions replace the client's text with new text

+to achieve the reconversion or transliteration.   Yet in all

+cases the result of a conversion, either immediately or via preediting,

+is returned by the

+<function>XmbLookupString</function>

+and

+<function>XwcLookupString</function>

+functions.

+</para>

+<para>

+<!-- .LP -->

+String conversion support is dependent on the availability of the 

+<function>XNStringConversion</function>

+or 

+<function>XNStringConversionCallback </function>

+<acronym>XIC</acronym> values.

+Because the input method may not support string conversions,

+clients have to query the availability of string conversion

+operations by checking the supported <acronym>XIC</acronym> values list by calling

+<function>XGetIMValues</function>

+with the

+<function>XNQueryICValuesList</function>

+IM value.

+</para>

+<para>

+<!-- .LP -->

+The difference between these two values is whether the

+conversion is invoked by the client or the input method.  

+The 

+<function>XNStringConversion</function>

+<acronym>XIC</acronym> value is used by clients to request 

+a string conversion from the input method.  The client

+is responsible for determining which events are used 

+to trigger the string conversion and whether the string to be

+converted should be copied or deleted.  The type of conversion

+is determined by the input method; the client can only 

+pass the string to be converted.  The client is guaranteed that

+no

+<function>XNStringConversionCallback</function>

+will be issued when this value is set; thus, the client need

+only set one of these values.

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XNStringConversionCallback</function>

+<acronym>XIC</acronym> value is used by the client to notify the input method that

+it will accept requests from the input method for string conversion.

+If this value is set,

+it is the input method's responsibility to determine which

+events are used to trigger the string conversion.

+When such events occur, the input method issues a call to the

+client-supplied procedure to retrieve the string to be converted.  The client's

+callback procedure is notified whether to copy or delete the string and 

+is provided with hints as to the amount of text needed.

+The

+<function>XIMStringConversionCallbackStruct</function>

+specifies which text should be passed back to the input method.

+</para>

+<para>

+<!-- .LP -->

+Finally, the input method may call the client's 

+<function>XNStringConversionCallback</function>

+procedure multiple times if the string returned from the callback is

+not sufficient to perform a successful conversion.   The arguments

+to the client's procedure allow the input method to define a

+position (in character units) relative to the client's cursor position 

+and the size of the text needed.  By varying the position and size of

+the desired text in subsequent callbacks, the input method can retrieve 

+additional text.

+</para>

+<para>

+<!-- .LP -->

+</para>

+</sect3>

+</sect2>

+<sect2 id="Input_Method_Management">

+<title>Input Method Management</title>

+<!-- .XS -->

+<!-- (SN Input Method Management -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The interface to input methods might appear to be simply creating

+an input method

+(<function>XOpenIM</function>)

+and freeing an input method

+(<function>XCloseIM</function>).

+However, input methods may 

+require complex communication with input method servers (IM servers),

+for example:

+</para>

+

+<itemizedlist>

+  <listitem>

+    <para>

+If the X server, IM server, and X clients are started asynchronously,

+some clients may attempt to connect to the IM server before it is

+fully operational, and fail.

+Therefore, some mechanism is needed to allow clients to detect when an IM 

+server has started.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+It is up to clients to decide what should be done when an IM server is 

+not available (for example, wait, or use some other IM server).

+</para>

+<para>

+<!-- .LP -->

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Some input methods may allow the underlying IM server to be switched. 

+Such customization may be desired without restarting the entire client.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+To support management of input methods in these cases, the following 

+functions are provided:

+</para>

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <tbody>

+    <row>

+      <entry><function>XRegisterIMInstantiateCallback</function></entry>

+      <entry>This function allows clients to register a callback procedure

+      to be called when Xlib detects that an IM server is up and available.</entry>

+    </row>

+    <row>

+      <entry><function>XOpenIM</function></entry>

+      <entry>A client calls this function as a result of the callback procedure

+      being called.</entry>

+    </row>

+    <row>

+      <entry><function>XSetIMValue</function>, <function>XSetICValue</function></entry>

+      <entry>These functions use the <acronym>XIM</acronym> and <acronym>XIC</acronym> values,

+      <function>XNDestroyCallback</function>,

+      to allow a client 

+      to register a callback procedure to be called when Xlib detects that

+      an IM server that was associated with an opened 

+      input method is no longer available.

+      In addition, this function can be used to switch IM servers for those input 

+      methods that support such functionality.  The IM value for switching IM 

+      servers is implementation-dependent; see the description below about

+      switching IM servers.</entry>

+    </row>

+    <row>

+      <entry><function>XUnregisterIMInstantiateCallback</function></entry>

+      <entry>This function removes a callback procedure registered by the client.</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<para>

+<!-- .LP -->

+Input methods that support switching of IM servers may exhibit some

+side-effects:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+The input method will ensure that any new IM server supports any of the 

+input styles being used by input contexts already associated with the

+input method.

+However, the list of supported input styles may be different.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Geometry management requests on previously created input contexts

+may be initiated by the new IM server.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+</para>

+<sect3 id="Hot_Keys">

+<title>Hot Keys</title>

+<!-- .XS -->

+<!-- (SN Hot Keys -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Some clients need to guarantee which keys can be used to escape from the

+input method, regardless of the input method state;

+for example, the client-specific Help key or the keys to move the

+input focus.

+The HotKey mechanism allows clients 

+to specify a set of keys for this purpose.  However, the input 

+method might not allow clients to specify hot keys.

+Therefore, clients have to query support of hot keys by checking the

+supported <acronym>XIC</acronym> values list by calling

+<function>XGetIMValues</function>

+with the

+<function>XNQueryICValuesList</function>

+IM value.

+When the hot keys specified conflict with the key bindings of the 

+input method, hot keys take precedence over the key bindings of the input 

+method.

+</para>

+<para>

+<!-- .LP -->

+</para>

+</sect3>

+<sect3 id="Preedit_State_Operation">

+<title>Preedit State Operation</title>

+<!-- .XS -->

+<!-- (SN Preedit State Operation -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+An input method may have several internal states, depending on its

+implementation and the locale.  However, one state that is

+independent of locale and implementation is whether the input method

+is currently performing a preediting operation.

+Xlib provides the ability for an application to manage the preedit state

+programmatically.  Two methods are provided for

+retrieving the preedit state of an input context.

+One method is to query the state by calling

+<function>XGetICValues</function>

+with the

+<function>XNPreeditState</function>

+<acronym>XIC</acronym> value.

+Another method is to receive notification whenever

+the preedit state is changed.  To receive such notification,

+an application needs to register a callback by calling

+<function>XSetICValues</function>

+with the

+<function>XNPreeditStateNotifyCallback</function>

+<acronym>XIC</acronym> value. 

+In order to change the preedit state programmatically, an application 

+needs to call 

+<function>XSetICValues</function>

+with

+<function>XNPreeditState</function>.

+</para>

+<para>

+<!-- .LP -->

+Availability of the preedit state is input method dependent.  The input 

+method may not provide the ability to set the state or to

+retrieve the state programmatically.  Therefore, clients have to 

+query availability of preedit state operations by checking the 

+supported <acronym>XIC</acronym> values list by calling

+<function>XGetIMValues</function>

+with the

+<function>XNQueryICValuesList</function>

+IM value.

+</para>

+</sect3>

+</sect2>

+<sect2 id="Input_Method_Functions">

+<title>Input Method Functions</title>

+<!-- .XS -->

+<!-- (SN Input Method Functions -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To open a connection, use

+<function>XOpenIM</function>.

+<indexterm significance="preferred"><primary>XOpenIM</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XIM<function> XOpenIM</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XrmDatabase<parameter> db</parameter></paramdef>

+  <paramdef>char<parameter> *res_name</parameter></paramdef>

+  <paramdef>char<parameter> *res_class</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>db</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a pointer to the resource database.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>res_name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the full resource name of the application.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>res_class</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the full class name of the application.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XOpenIM</function>

+function opens an input method, 

+matching the current locale and modifiers specification.

+Current locale and modifiers are bound to the input method at opening time.

+The locale associated with an input method cannot be changed dynamically.

+This implies that the strings returned by

+<function>XmbLookupString</function>

+or

+<function>XwcLookupString</function>,

+for any input context affiliated with a given input method,

+will be encoded in the locale current at the time the input method is opened.

+</para>

+<para>

+<!-- .LP -->

+The specific input method to which this call will be routed

+is identified on the basis of the current locale. 

+<function>XOpenIM</function>

+will identify a default input method corresponding to the

+current locale.

+That default can be modified using 

+<function>XSetLocaleModifiers</function>

+for the input method modifier.

+</para>

+<para>

+<!-- .LP -->

+The db argument is the resource database to be used by the input method

+for looking up resources that are private to the input method.

+It is not intended that this database be used to look

+up values that can be set as IC values in an input context.

+If db is NULL,

+no database is passed to the input method.

+</para>

+<para>

+<!-- .LP -->

+The res_name and res_class arguments specify the resource name 

+and class of the application. 

+They are intended to be used as prefixes by the input method

+when looking up resources that are common to all input contexts

+that may be created for this input method.

+The characters used for resource names and classes must be in the

+X Portable Character Set.

+The resources looked up are not fully specified

+if res_name or res_class is NULL.

+</para>

+<para>

+<!-- .LP -->

+The res_name and res_class arguments are not assumed to exist beyond

+the call to

+<function>XOpenIM</function>.

+The specified resource database is assumed to exist for the lifetime

+of the input method.

+</para>

+<para>

+<!-- .LP -->

+<function>XOpenIM</function>

+returns NULL if no input method could be opened.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To close a connection, use

+<function>XCloseIM</function>.

+<indexterm significance="preferred"><primary>XCloseIM</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XCloseIM</function></funcdef>

+  <paramdef>XIM<parameter> im</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>im</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input method.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCloseIM</function>

+function closes the specified input method.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set input method attributes, use

+<function>XSetIMValues</function>.

+<indexterm significance="preferred"><primary>XSetIMValues</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> *</function></funcdef>

+  <paramdef>XIM<parameter> im</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>im</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input method.

+<!-- .ds Al \ to set <acronym>XIM</acronym> values -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      ...

+    </term>

+    <listitem>

+      <para>

+Specifies the variable-length argument list(Al.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetIMValues</function>

+function presents a variable argument list programming interface

+for setting attributes of the specified input method.

+It returns NULL if it succeeds;

+otherwise,

+it returns the name of the first argument that could not be set.

+Xlib does not attempt to set arguments from the supplied list that

+follow the failed argument;

+all arguments in the list preceding the failed argument have been set

+correctly.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To query an input method, use 

+<function>XGetIMValues</function>.

+<indexterm significance="preferred"><primary>XGetIMValues</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> *</function></funcdef>

+  <paramdef>XIM<parameter> im</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>im</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input method.

+<!-- .ds Al \ to get XIM values -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      ...

+    </term>

+    <listitem>

+      <para>

+Specifies the variable length argument list(Al.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetIMValues</function>

+function presents a variable argument list programming interface

+for querying properties or features of the specified input method.

+This function returns NULL if it succeeds;

+otherwise,

+it returns the name of the first argument that could not be obtained.

+</para>

+<para>

+<!-- .LP -->

+Each <acronym>XIM</acronym> value argument (following a name) must point to

+a location where the <acronym>XIM</acronym> value is to be stored.

+That is, if the <acronym>XIM</acronym> value is of type T,

+the argument must be of type T*.

+If T itself is a pointer type,

+then

+<function>XGetIMValues</function>

+allocates memory to store the actual data,

+and the client is responsible for freeing this data by calling

+<function>XFree</function>

+with the returned pointer.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the display associated with an input method, use

+<function>XDisplayOfIM</function>.

+<indexterm significance="preferred"><primary>XDisplayOfIM</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Display<function> *</function></funcdef>

+  <paramdef>XIM<parameter> im</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>im</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input method.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XDisplayOfIM</function>

+function returns the display associated with the specified input method.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To get the locale associated with an input method, use

+<function>XLocaleOfIM</function>.

+<indexterm significance="preferred"><primary>XLocaleOfIM</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> *</function></funcdef>

+  <paramdef>XIM<parameter> im</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>im</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input method.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XLocaleOfIM</function>

+function returns the locale associated with the specified input method.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To register an input method instantiate callback, use

+<function>XRegisterIMInstantiateCallback</function>.

+<indexterm significance="preferred"><primary>XRegisterIMInstantiateCallback</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool<function> XRegisterIMInstantiateCallback</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XrmDatabase<parameter> db</parameter></paramdef>

+  <paramdef>char<parameter> *res_name</parameter></paramdef>

+  <paramdef>char<parameter> *res_class</parameter></paramdef>

+  <paramdef>XIMProc<parameter> callback</parameter></paramdef>

+  <paramdef>XPointer<parameter> *client_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>db</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a pointer to the resource database.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>res_name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the full resource name of the application.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>res_class</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the full class name of the application.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>callback</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a pointer to the input method instantiate callback.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>client_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the additional client data.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XRegisterIMInstantiateCallback</function>

+function registers a callback to be invoked whenever a new input method

+becomes available for the specified display that matches the current

+locale and modifiers.

+</para>

+<para>

+<!-- .LP -->

+The function returns 

+<function>True</function>

+ if it succeeds; otherwise, it returns 

+<function>False</function>.

+</para>

+<para>

+<!-- .LP -->

+The generic prototype is as follows:

+<indexterm significance="preferred"><primary>IMInstantiateCallback</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> IMInstantiateCallback</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

+  <paramdef>XPointer<parameter> call_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>client_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the additional client data.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>call_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Not used for this callback and always passed as NULL.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+To unregister an input method instantiation callback, use

+<function>XUnregisterIMInstantiateCallback</function>.

+<indexterm significance="preferred"><primary>XUnregisterIMInstantiateCallback</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool<function> XUnregisterIMInstantiateCallback</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XrmDatabase<parameter> db</parameter></paramdef>

+  <paramdef>char<parameter> *res_name</parameter></paramdef>

+  <paramdef>char<parameter> *res_class</parameter></paramdef>

+  <paramdef>XIMProc<parameter> callback</parameter></paramdef>

+  <paramdef>XPointer<parameter> *client_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>db</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a pointer to the resource database.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>res_name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the full resource name of the application.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>res_class</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the full class name of the application.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>callback</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a pointer to the input method instantiate callback.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>client_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the additional client data.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XUnregisterIMInstantiateCallback</function>

+function removes an input method instantiation callback previously

+registered.

+The function returns

+<function>True</function>

+if it succeeds; otherwise, it returns 

+<function>False</function>.

+</para>

+</sect2>

+<sect2 id="Input_Method_Values">

+<title>Input Method Values</title>

+<!-- .XS -->

+<!-- (SN Input Method Values -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The following table describes how <acronym>XIM</acronym> values are interpreted

+by an input method.

+The first column lists the <acronym>XIM</acronym> values.

+The second column indicates how each of the <acronym>XIM</acronym> values 

+are treated by that input style.

+</para>

+<para>

+<!-- .LP -->

+</para>

+<para>

+<!-- .LP -->

+The following keys apply to this table.

+</para>

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <thead>

+    <row>

+      <entry>Key</entry>

+      <entry>Explanation</entry>

+    </row>

+  </thead>

+  <tbody>

+    <row>

+      <entry>D</entry>

+      <entry>This value may be set using

+      <function>XSetIMValues</function>.

+      If it is not set,

+      a default is provided.</entry>

+    </row>

+    <row>

+      <entry>S</entry>

+      <entry>This value may be set using <function>XSetIMValues</function>.</entry>

+    </row>

+    <row>

+      <entry>G</entry>

+      <entry>This value may be read using <function>XGetIMValues</function>.</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<!-- .LP -->

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <thead>

+    <row>

+      <entry><acronym>XIM</acronym> Value</entry>

+      <entry>Key</entry>

+    </row>

+  </thead>

+  <tbody>

+    <row>

+      <entry><function>XNQueryInputStyle</function></entry>

+      <entry>G</entry>

+    </row>

+    <row>

+      <entry><function>XNResourceName</function></entry>

+      <entry>D-S-G</entry>

+    </row>

+    <row>

+      <entry><function>XNResourceClass</function></entry>

+      <entry>D-S-G</entry>

+    </row>

+    <row>

+      <entry><function>XNDestroyCallback</function></entry>

+      <entry>D-S-G</entry>

+    </row>

+    <row>

+      <entry><function>XNQueryIMValuesList</function></entry>

+      <entry>G</entry>

+    </row>

+    <row>

+      <entry><function>XNQueryICValuesList</function></entry>

+      <entry>G</entry>

+    </row>

+    <row>

+      <entry><function>XNVisiblePosition</function></entry>

+      <entry>G</entry>

+    </row>

+    <row>

+      <entry><function>XNR6PreeditCallbackBehavior</function></entry>

+      <entry>D-S-G</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<para>

+<!-- .LP -->

+<function>XNR6PreeditCallbackBehavior</function>

+is obsolete and its use is not recommended (see section 13.5.4.6).

+</para>

+

+<sect3 id="Query_Input_Style">

+<title>Query Input Style</title>

+<!-- .XS -->

+<!-- (SN Query Input Style -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+A client should always query the input method to determine which input 

+styles are supported.

+The client should then find an input style it is capable of supporting.

+</para>

+<para>

+<!-- .LP -->

+If the client cannot find an input style that it can support,

+it should negotiate with the user the continuation of the program

+(exit, choose another input method, and so on).

+</para>

+<para>

+<!-- .LP -->

+The argument value must be a pointer to a location

+where the returned value will be stored.

+The returned value is a pointer to a structure of type

+<function>XIMStyles</function>.

+Clients are responsible for freeing the 

+<function>XIMStyles</function>

+structure.

+To do so, use

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XIMStyles</function>

+structure is defined as follows:

+</para>

+

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XIMStyle</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMPreeditArea</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMPreeditCallbacks</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMPreeditPosition</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMPreeditNothing</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMPreeditNone</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMStatusArea</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMStatusCallbacks</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMStatusNothing</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMStatusNone</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMStyles</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+typedef unsigned long XIMStyle;

+

+

+#define     XIMPreeditArea             0x0001L

+#define     XIMPreeditCallbacks        0x0002L

+#define     XIMPreeditPosition         0x0004L

+#define     XIMPreeditNothing          0x0008L

+#define     XIMPreeditNone             0x0010L

+

+#define     XIMStatusArea              0x0100L

+#define     XIMStatusCallbacks         0x0200L

+#define     XIMStatusNothing           0x0400L

+#define     XIMStatusNone              0x0800L

+

+typedef struct {

+      unsigned short count_styles;

+      XIMStyle * supported_styles;

+} XIMStyles;

+

+</literallayout>

+

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+An 

+<function>XIMStyles</function>

+structure contains the number of input styles supported

+in its count_styles field.

+This is also the size of the supported_styles array.

+</para>

+<para>

+<!-- .LP -->

+The supported styles is a list of bitmask combinations,

+which indicate the combination of styles for each of the areas supported.

+These areas are described later.

+Each element in the list should select one of the bitmask values for

+each area.

+The list describes the complete set of combinations supported.

+Only these combinations are supported by the input method.

+</para>

+<para>

+<!-- .LP -->

+The preedit category defines what type of support is provided

+by the input method for preedit information.

+</para>

+<indexterm significance="preferred"><primary>XIMPreeditArea</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMPreeditPosition</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMPreeditCallbacks</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMPreeditNothing</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMPreeditNone</primary></indexterm>

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <tbody>

+    <row>

+      <entry><function>XIMPreeditArea </function></entry>

+      <entry>If chosen,

+      the input method would require the client to provide some area values

+      for it to do its preediting.

+      Refer to <acronym>XIC</acronym> values 

+      <function>XNArea</function>

+      and

+      <function>XNAreaNeeded</function>.</entry>

+    </row>

+    <row>

+      <entry><function>XIMPreeditPosition</function></entry>

+      <entry>If chosen,

+      the input method would require the client to provide positional values. 

+      Refer to <acronym>XIC</acronym> values 

+      <function>XNSpotLocation</function>

+      and

+      <function>XNFocusWindow</function>.</entry>

+    </row>

+    <row>

+      <entry><function>XIMPreeditCallbacks</function></entry>

+      <entry>If chosen,

+      the input method would require the client to define the set of preedit callbacks.

+      Refer to <acronym>XIC</acronym> values 

+      <function>XNPreeditStartCallback</function>,

+      <function>XNPreeditDoneCallback</function>,

+      <function>XNPreeditDrawCallback</function>,

+      and

+      <function>XNPreeditCaretCallback</function>.</entry>

+    </row>

+    <row>

+      <entry><function>XIMPreeditNothing</function></entry>

+      <entry>If chosen, the input method can function without any preedit values.</entry>

+    </row>

+    <row>

+      <entry><function>XIMPreeditNone</function></entry>

+      <entry>The input method does not provide any preedit feedback.

+      Any preedit value is ignored.

+      This style is mutually exclusive with the other preedit styles.</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<para>

+<!-- .LP -->

+The status category defines what type of support is provided

+by the input method for status information.

+</para>

+<indexterm significance="preferred"><primary>XIMStatusArea</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMStatusCallbacks</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMStatusNothing</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMStatusNone</primary></indexterm>

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <tbody>

+    <row>

+      <entry><function>XIMStatusArea</function></entry>

+      <entry>The input method requires the client to provide

+      some area values for it to do its status feedback.

+      See

+      <function>XNArea</function>

+      and

+      <function>XNAreaNeeded</function>.</entry>

+    </row>

+    <row>

+      <entry><function>XIMStatusCallbacks</function></entry>

+      <entry>The input method requires the client to define the set of status callbacks,

+      <function>XNStatusStartCallback</function>,

+      <function>XNStatusDoneCallback</function>,

+      and

+      <function>XNStatusDrawCallback</function>.</entry>

+    </row>

+    <row>

+      <entry><function>XIMStatusNothing</function></entry>

+      <entry>The input method can function without any status values.</entry>

+    </row>

+    <row>

+      <entry><function>XIMStatusNone</function></entry>

+      <entry>The input method does not provide any status feedback.

+      If chosen, any status value is ignored.

+      This style is mutually exclusive with the other status styles.</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+</sect3>

+<sect3 id="Resource_Name_and_Class_c">

+<title>Resource Name and Class</title>

+<!-- .XS -->

+<!-- (SN Resource Name and Class -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The

+<function>XNResourceName</function>

+and

+<function>XNResourceClass</function>

+arguments are strings that specify the full name and class

+used by the input method.

+These values should be used as prefixes for the name and class

+when looking up resources that may vary according to the input method.

+If these values are not set,

+the resources will not be fully specified.

+</para>

+<para>

+<!-- .LP -->

+It is not intended that values that can be set as <acronym>XIM</acronym> values be

+set as resources.

+</para>

+<para>

+<!-- .LP -->

+</para>

+</sect3>

+<sect3 id="Destroy_Callback">

+<title>Destroy Callback</title>

+<!-- .XS -->

+<!-- (SN Destroy Callback -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The 

+<function>XNDestroyCallback </function>

+argument is a pointer to a structure of type

+<function>XIMCallback</function>.

+<function>XNDestroyCallback</function>

+is triggered when an input method stops its service for any reason. 

+After the callback is invoked, the input method is closed and the

+associated input context(s) are destroyed by Xlib.

+Therefore, the client should not call

+<function>XCloseIM</function>

+or

+<function>XDestroyIC</function>.

+</para>

+<para>

+<!-- .LP -->

+The generic prototype of this callback function is as follows:

+<indexterm significance="preferred"><primary>DestroyCallback</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> DestroyCallback</function></funcdef>

+  <paramdef>XIM<parameter> im</parameter></paramdef>

+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

+  <paramdef>XPointer<parameter> call_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>im</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input method.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>client_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the additional client data.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>call_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Not used for this callback and always passed as NULL.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+A DestroyCallback is always called with a NULL call_data argument.

+</para>

+<para>

+<!-- .LP -->

+</para>

+</sect3>

+<sect3 id="Query_IM_IC_Values_List">

+<title>Query IM/IC Values List</title>

+<!-- .XS -->

+<!-- (SN Query IM/IC Values List -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<function>XNQueryIMValuesList</function>

+and

+<function>XNQueryICValuesList</function>

+are used to query about <acronym>XIM</acronym> and <acronym>XIC</acronym> values supported by the input method.

+</para>

+<para>

+<!-- .LP -->

+The argument value must be a pointer to a location where the returned

+value will be stored.  The returned value is a pointer to a structure

+of type

+<function>XIMValuesList</function>.

+Clients are responsible for freeing the 

+<function>XIMValuesList</function>

+structure.

+To do so, use

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XIMValuesList</function>

+structure is defined as follows:

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct {

+     unsigned short count_values;

+     char **supported_values;

+} XIMValuesList;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+</para>

+</sect3>

+<sect3 id="Visible_Position">

+<title>Visible Position</title>

+<!-- .XS -->

+<!-- (SN Visible Position -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The 

+<function>XNVisiblePosition</function>

+argument indicates whether the visible position masks of 

+<function>XIMFeedback</function>

+in

+<function>XIMText</function>

+are available.

+</para>

+<para>

+<!-- .LP -->

+The argument value must be a pointer to a location where the returned

+value will be stored.  The returned value is of type

+<function>Bool</function>.

+If the returned value is

+<function>True</function>,

+the input method uses the visible position masks of

+<function>XIMFeedback</function>

+in

+<function>XIMText</function>;

+otherwise, the input method does not use the masks.

+</para>

+<para>

+<!-- .LP -->

+Because this <acronym>XIM</acronym> value is optional, a client should call

+<function>XGetIMValues</function>

+with argument

+<function>XNQueryIMValues</function>

+before using this argument.

+If the 

+<function>XNVisiblePosition</function>

+does not exist in the IM values list returned from 

+<function>XNQueryIMValues</function>,

+the visible position masks of

+<function>XIMFeedback</function>

+in

+<function>XIMText</function>

+are not used to indicate the visible position.

+</para>

+<para>

+<!-- .LP -->

+</para>

+</sect3>

+<sect3 id="Preedit_Callback_Behavior">

+<title>Preedit Callback Behavior</title>

+<!-- .XS -->

+<!-- (SN Preedit Callback Behavior -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The

+<function>XNR6PreeditCallbackBehavior</function>

+argument originally included in the X11R6 specification has been

+deprecated.\(dg

+<!-- .\" If XNR6PreeditCallbackBehavior is not deprecated, then its type -->

+<!-- .\" should be changed from *Bool to Bool. -->

+<!-- .FS \(dg -->

+During formulation of the X11R6 specification, the behavior of

+the R6 PreeditDrawCallbacks was going to differ significantly from

+that of the R5 callbacks.

+Late changes to the specification converged the R5 and R6 behaviors,

+eliminating the need for

+<function>XNR6PreeditCallbackBehavior</function>.

+Unfortunately, this argument was not removed from the R6 specification

+before it was published.

+<!-- .FE -->

+</para>

+<para>

+<!-- .LP -->

+The 

+<function>XNR6PreeditCallbackBehavior</function>

+argument indicates whether the behavior of preedit callbacks regarding

+<function>XIMPreeditDrawCallbackStruct</function>

+values follows Release 5 or Release 6 semantics.

+</para>

+<para>

+<!-- .LP -->

+The value is of type

+<function>Bool</function>.

+When querying for

+<function>XNR6PreeditCallbackBehavior</function>,

+if the returned value is

+<function>True</function>,

+the input method uses the Release 6 behavior;

+otherwise, it uses the Release 5 behavior.

+The default value is

+<function>False</function>.

+In order to use Release 6 semantics, the value of

+<function>XNR6PreeditCallbackBehavior</function>

+must be set to

+<function>True</function>.

+</para>

+<para>

+<!-- .LP -->

+Because this <acronym>XIM</acronym> value is optional, a client should call

+<function>XGetIMValues</function>

+with argument

+<function>XNQueryIMValues</function>

+before using this argument.

+If the

+<function>XNR6PreeditCallbackBehavior</function>

+does not exist in the IM values list returned from

+<function>XNQueryIMValues</function>,

+the PreeditCallback behavior is Release 5 semantics.

+</para>

+<para>

+<!-- .LP -->

+</para>

+</sect3>

+</sect2>

+<sect2 id="Input_Context_Functions">

+<title>Input Context Functions</title>

+<!-- .XS -->

+<!-- (SN Input Context Functions -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+An input context is an abstraction that is used to contain both the data

+required (if any) by an input method and the information required

+to display that data.

+There may be multiple input contexts for one input method.

+The programming interfaces for creating, reading, or modifying

+an input context use a variable argument list.

+The name elements of the argument lists are referred to as <acronym>XIC</acronym> values.

+It is intended that input methods be controlled by these <acronym>XIC</acronym> values.

+As new <acronym>XIC</acronym> values are created,

+they should be registered with the X Consortium.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To create an input context, use

+<function>XCreateIC</function>.

+<indexterm significance="preferred"><primary>XCreateIC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XIC<function> XCreateIC</function></funcdef>

+  <paramdef>XIM<parameter> im</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>im</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input method.

+<!-- .ds Al \ to set <acronym>XIC</acronym> values -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      ...

+    </term>

+    <listitem>

+      <para>

+Specifies the variable length argument list(Al.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCreateIC </function>

+function creates a context within the specified input method.

+</para>

+<para>

+<!-- .LP -->

+Some of the arguments are mandatory at creation time, and

+the input context will not be created if those arguments are not provided.

+The mandatory arguments are the input style and the set of text callbacks

+(if the input style selected requires callbacks).

+All other input context values can be set later.

+</para>

+<para>

+<!-- .LP -->

+<function>XCreateIC</function>

+returns a NULL value if no input context could be created.

+A NULL value could be returned for any of the following reasons:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+A required argument was not set.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A read-only argument was set (for example,

+<function>XNFilterEvents</function>).

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The argument name is not recognized.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The input method encountered an input method implementation-dependent error.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+<function>XCreateIC</function>

+can generate

+<function>BadAtom</function>,

+<function>BadColor</function>,

+<function>BadPixmap</function>,

+and

+<function>BadWindow</function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To destroy an input context, use

+<function>XDestroyIC</function>.

+<indexterm significance="preferred"><primary>XDestroyIC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XDestroyIC</function></funcdef>

+  <paramdef>XIC<parameter> ic</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ic</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input context.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<function>XDestroyIC</function>

+destroys the specified input context.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To communicate to and synchronize with input method

+for any changes in keyboard focus from the client side,

+use 

+<function>XSetICFocus</function>

+and

+<function>XUnsetICFocus</function>.

+<indexterm significance="preferred"><primary>XSetICFocus</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XSetICFocus</function></funcdef>

+  <paramdef>XIC<parameter> ic</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ic</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input context.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetICFocus</function>

+function allows a client to notify an input method that the focus window

+attached to the specified input context has received keyboard focus.

+The input method should take action to provide appropriate feedback.

+Complete feedback specification is a matter of user interface policy.

+</para>

+<para>

+<!-- .LP -->

+Calling

+<function>XSetICFocus</function>

+does not affect the focus window value.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<indexterm significance="preferred"><primary>XUnsetICFocus</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XUnsetICFocus</function></funcdef>

+  <paramdef>XIC<parameter> ic</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ic</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input context.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XUnsetICFocus</function>

+function allows a client to notify an input method that the specified input context

+has lost the keyboard focus and that no more input is expected on the focus window

+attached to that input context.

+The input method should take action to provide appropriate feedback.

+Complete feedback specification is a matter of user interface policy.

+</para>

+<para>

+<!-- .LP -->

+Calling

+<function>XUnsetICFocus</function>

+does not affect the focus window value;

+the client may still receive 

+events from the input method that are directed to the focus window.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To reset the state of an input context to its initial state, use

+<function>XmbResetIC</function>

+or

+<function>XwcResetIC</function>.

+<indexterm significance="preferred"><primary>XmbResetIC</primary></indexterm>

+<indexterm significance="preferred"><primary>XwcResetIC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> *</function></funcdef>

+  <paramdef>XIC<parameter> ic</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>wchar_t<function> *</function></funcdef>

+  <paramdef>XIC<parameter> ic</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ic</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input context.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+When

+<function>XNResetState</function>

+is set to

+<function>XIMInitialState</function>,

+<function>XmbResetIC</function>

+and

+<function>XwcResetIC</function>

+reset an input context to its initial state;

+when

+<function>XNResetState</function>

+is set to

+<function>XIMPreserveState</function>,

+the current input context state is preserved.

+In both cases, any input pending on that context is deleted.

+The input method is required to clear the preedit area, if any,

+and update the status accordingly.

+Calling 

+<function>XmbResetIC</function>

+or

+<function>XwcResetIC</function>

+does not change the focus.

+</para>

+<para>

+<!-- .LP -->

+The return value of

+<function>XmbResetIC</function>

+is its current preedit string as a multibyte string.

+If there is any preedit text drawn or visible to the user,

+then these procedures must return a non-NULL string.

+If there is no visible preedit text, 

+then it is input method implementation-dependent 

+whether these procedures return a non-NULL string or NULL.

+</para>

+<para>

+<!-- .LP -->

+The client should free the returned string by calling

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To get the input method associated with an input context, use

+<function>XIMOfIC</function>.

+<indexterm significance="preferred"><primary>XIMOfIC</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XIM<function> XIMOfIC</function></funcdef>

+  <paramdef>XIC<parameter> ic</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ic</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input context.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XIMOfIC</function>

+function returns the input method associated with the specified input context.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+Xlib provides two functions for setting and reading <acronym>XIC</acronym> values, respectively,

+<function>XSetICValues</function>

+and

+<function>XGetICValues</function>.

+Both functions have a variable-length argument list.

+In that argument list, any <acronym>XIC</acronym> value's name must be denoted

+with a character string using the X Portable Character Set.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set <acronym>XIC</acronym> values, use

+<function>XSetICValues</function>.

+<indexterm significance="preferred"><primary>XSetICValues</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> *</function></funcdef>

+  <paramdef>XIC<parameter> ic</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ic</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input context.

+<!-- .ds Al \ to set <acronym>XIC</acronym> values -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      ...

+    </term>

+    <listitem>

+      <para>

+Specifies the variable length argument list(Al.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetICValues</function>

+function returns NULL if no error occurred; 

+otherwise,

+it returns the name of the first argument that could not be set.

+An argument might not be set for any of the following reasons:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+The argument is read-only (for example,

+<function>XNFilterEvents</function>).

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The argument name is not recognized.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+An implementation-dependent error occurs.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+Each value to be set must be an appropriate datum,

+matching the data type imposed by the semantics of the argument.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetICValues</function>

+can generate

+<function>BadAtom</function>,

+<function>BadColor</function>,

+<function>BadCursor</function>,

+<function>BadPixmap</function>,

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain <acronym>XIC</acronym> values, use

+<function>XGetICValues</function>.

+<indexterm significance="preferred"><primary>XGetICValues</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char<function> *</function></funcdef>

+  <paramdef>XIC<parameter> ic</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ic</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input context.

+<!-- .ds Al \ to get XIC values -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      ...

+    </term>

+    <listitem>

+      <para>

+Specifies the variable length argument list(Al.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetICValues</function>

+function returns NULL if no error occurred; otherwise,

+it returns the name of the first argument that could not be obtained.

+An argument could not be obtained for any of the following reasons:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+The argument name is not recognized.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The input method encountered an implementation-dependent error.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+Each IC attribute value argument (following a name) must point to

+a location where the IC value is to be stored.

+That is, if the IC value is of type T,

+the argument must be of type T*.

+If T itself is a pointer type,

+then

+<function>XGetICValues</function>

+allocates memory to store the actual data,

+and the client is responsible for freeing this data by calling

+<function>XFree</function>

+with the returned pointer.

+The exception to this rule is for an IC value of type

+<function>XVaNestedList</function>

+(for preedit and status attributes).

+In this case,  the argument must also be of type

+<function>XVaNestedList</function>.

+Then, the rule of changing type T to T* and freeing the allocated data

+applies to each element of the nested list.

+</para>

+</sect2>

+<sect2 id="Input_Context_Values">

+<title>Input Context Values</title>

+<!-- .XS -->

+<!-- (SN Input Context Values -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The following tables describe how <acronym>XIC</acronym> values are interpreted

+by an input method depending on the input style chosen by the 

+user.

+</para>

+<para>

+<!-- .LP -->

+The first column lists the <acronym>XIC</acronym> values.

+The second column indicates which values are involved in affecting,

+negotiating, and setting the geometry of the input method windows.

+The subentries under the third column indicate the different

+input styles that are supported.

+Each of these columns indicates how each of the <acronym>XIC</acronym> values 

+are treated by that input style.

+</para>

+<para>

+<!-- .LP -->

+The following keys apply to these tables.

+</para>

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <thead>

+    <row>

+      <entry>Key</entry>

+      <entry>Explanation</entry>

+    </row>

+  </thead>

+  <tbody>

+    <row>

+      <entry>C</entry>

+      <entry>This value must be set with <function>XCreateIC</function>.</entry>

+    </row>

+    <row>

+      <entry>D</entry>

+      <entry>This value may be set using 

+      <function>XCreateIC</function>.>

+      If it is not set,>

+      a default is provided.</entry>

+    </row>

+    <row>

+      <entry>G</entry>

+      <entry>This value may be read using 

+      <function>XGetICValues</function>.</entry>

+    </row>

+    <row>

+      <entry>GN</entry>

+      <entry>This value may cause geometry negotiation when its value is set by means of

+      <function>XCreateIC</function>

+      or

+      <function>XSetICValues</function>.</entry>

+    </row>

+    <row>

+      <entry>GR</entry>

+      <entry>This value will be the response of the input method when any 

+      GN value is changed.</entry>

+    </row>

+    <row>

+      <entry>GS</entry>

+      <entry>This value will cause the geometry of the input method window to be set.</entry>

+    </row>

+    <row>

+      <entry>O</entry>

+      <entry>This value must be set once and only once.

+      It need not be set at create time.</entry>

+    </row>

+    <row>

+      <entry>S</entry>

+      <entry>This value may be set with

+      <function>XSetICValues</function>.</entry>

+    </row>

+    <row>

+      <entry>Ignored</entry>

+      <entry>This value is ignored by the input method for the given input style.</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<!-- .LP -->

+<informaltable>

+  <tgroup cols='7' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <colspec colname='c3'/>

+  <colspec colname='c4'/>

+  <colspec colname='c5'/>

+  <colspec colname='c6'/>

+  <colspec colname='c7'/>

+  <tbody>

+    <row>

+      <entry><acronym>XIC</acronym> Value</entry>

+      <entry>Geometry Mangement</entry>

+      <entry>Preedit Callback</entry>

+      <entry>Preedit Position</entry>

+      <entry>Input Style Preedit Area</entry>

+      <entry>Preedit Nothing</entry>

+      <entry>Preedit None</entry>

+    </row>

+    <row>

+      <entry>Input Style</entry>

+      <entry></entry>

+      <entry>C-G</entry>

+      <entry>C-G</entry>

+      <entry>C-G</entry>

+      <entry>C-G</entry>

+      <entry>C-G</entry>

+    </row>

+    <row>

+      <entry>Client Window</entry>

+      <entry></entry>

+      <entry>O-G</entry>

+      <entry>O-G</entry>

+      <entry>O-G</entry>

+      <entry>O-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Focus Window</entry>

+      <entry>GN</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Resource Name</entry>

+      <entry></entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Resource Class</entry>

+      <entry></entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Geometry Callback</entry>

+      <entry></entry>

+      <entry>Ignored</entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Filter Events</entry>

+      <entry></entry>

+      <entry>G</entry>

+      <entry>G</entry>

+      <entry>G</entry>

+      <entry>G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Destroy Callback</entry>

+      <entry></entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+    </row>

+    <row>

+      <entry>String Conversion Callback</entry>

+      <entry></entry>

+      <entry>S-G</entry>

+      <entry>S-G</entry>

+      <entry>S-G</entry>

+      <entry>S-G</entry>

+      <entry>S-G</entry>

+    </row>

+    <row>

+      <entry>String Conversion</entry>

+      <entry></entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+    </row>

+    <row>

+      <entry>Reset State</entry>

+      <entry></entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>HotKey</entry>

+      <entry></entry>

+      <entry>S-G</entry>

+      <entry>S-G</entry>

+      <entry>S-G</entry>

+      <entry>S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>HotKeyState</entry>

+      <entry></entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry><function>Preedit</function></entry>

+    </row>

+    <row>

+      <entry>Area</entry>

+      <entry>GS</entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Area Needed</entry>

+      <entry>GN-GR</entry>

+      <entry>Ignored</entry>

+      <entry>Ignored</entry>

+      <entry>S-G</entry>

+      <entry>Ignored</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Spot Location</entry>

+      <entry></entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+      <entry>Ignored</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Colormap</entry>

+      <entry></entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Foreground</entry>

+      <entry></entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Background</entry>

+      <entry></entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Background Pixmap</entry>

+      <entry></entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Font Set</entry>

+      <entry>GN</entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Line Spacing</entry>

+      <entry>GN</entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Cursor</entry>

+      <entry></entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Preedit State</entry>

+      <entry></entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Preedit State Notify Callback</entry>

+      <entry></entry>

+      <entry>S-G</entry>

+      <entry>S-G</entry>

+      <entry>S-G</entry>

+      <entry>S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Preedit Callbacks</entry>

+      <entry></entry>

+      <entry>C-S-G</entry>

+      <entry>Ignored</entry>

+      <entry>Ignored</entry>

+      <entry>Ignored</entry>

+      <entry>Ignored</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<!-- .LP -->

+<informaltable>

+  <tgroup cols='6' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <colspec colname='c3'/>

+  <colspec colname='c4'/>

+  <colspec colname='c5'/>

+  <colspec colname='c6'/>

+  <thead>

+    <row>

+      <entry><acronym>XIC</acronym> Value</entry>

+      <entry>Geomentry Management</entry>

+      <entry>Status Callback</entry>

+      <entry>Status Area</entry>

+      <entry>Status Nothing</entry>

+      <entry>Status None</entry>

+    </row>

+  </thead>

+  <tbody>

+    <row>

+      <entry>Input Style</entry>

+      <entry></entry>

+      <entry>C-G</entry>

+      <entry>C-G</entry>

+      <entry>C-G</entry>

+      <entry>C-G</entry>

+    </row>

+    <row>

+      <entry>Client Window</entry>

+      <entry></entry>

+      <entry>O-G</entry>

+      <entry>O-G</entry>

+      <entry>O-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Focus Window</entry>

+      <entry>GN</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Resource Name</entry>

+      <entry></entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Resource Class</entry>

+      <entry></entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Geometry Callback</entry>

+      <entry></entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Filter Events</entry>

+      <entry></entry>

+      <entry>G</entry>

+      <entry>G</entry>

+      <entry>G</entry>

+      <entry>G</entry>

+    </row>

+    <row>

+      <entry><function>Status</function></entry>

+    </row>

+    <row>

+      <entry>Area</entry>

+      <entry>GS</entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Area Needed</entry>

+      <entry>GN-GR</entry>

+      <entry>Ignored</entry>

+      <entry>S-G</entry>

+      <entry>Ignored</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Colormap</entry>

+      <entry></entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Foreground</entry>

+      <entry></entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Background</entry>

+      <entry></entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Background Pixmap</entry>

+      <entry></entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Font Set</entry>

+      <entry>GN</entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Line Spacing</entry>

+      <entry>GN</entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Cursor</entry>

+      <entry></entry>

+      <entry>Ignored</entry>

+      <entry>D-S-G</entry>

+      <entry>D-S-G</entry>

+      <entry>Ignored</entry>

+    </row>

+    <row>

+      <entry>Status Callbacks</entry>

+      <entry></entry>

+      <entry>C-S-G</entry>

+      <entry>Ignored</entry>

+      <entry>Ignored</entry>

+      <entry>Ignored</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+<sect3 id="Input_Style">

+<title>Input Style</title>

+<!-- .XS -->

+<!-- (SN Input Style -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The

+<function>XNInputStyle</function>

+argument specifies the input style to be used.

+The value of this argument must be one of the values returned by the

+<function>XGetIMValues</function>

+function with the

+<function>XNQueryInputStyle</function>

+argument specified in the supported_styles list.

+</para>

+<para>

+<!-- .LP -->

+Note that this argument must be set at creation time

+and cannot be changed.

+</para>

+</sect3>

+<sect3 id="Client_Window">

+<title>Client Window</title>

+<!-- .XS -->

+<!-- (SN Client Window -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XNClientWindow</primary></indexterm>

+The

+<function>XNClientWindow</function>

+argument specifies to the input method the client window in

+which the input method

+can display data or create subwindows.

+Geometry values for input method areas are given with respect to the client

+window.

+Dynamic change of client window is not supported.

+This argument may be set only once and

+should be set before any input is done using this input context.

+If it is not set,

+the input method may not operate correctly.

+</para>

+<para>

+<!-- .LP -->

+If an attempt is made to set this value a second time with

+<function>XSetICValues</function>,

+the string

+<function>XNClientWindow</function>

+will be returned by

+<function>XSetICValues</function>,

+and the client window will not be changed.

+</para>

+<para>

+<!-- .LP -->

+If the client window is not a valid window ID on the display

+attached to the input method,

+a 

+<function>BadWindow </function>

+error can be generated when this value is used by the input method.

+</para>

+</sect3>

+<sect3 id="Focus_Window">

+<title>Focus Window</title>

+<!-- .XS -->

+<!-- (SN Focus Window -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XNFocusWindow</primary></indexterm>

+The

+<function>XNFocusWindow</function>

+argument specifies the focus window.

+The primary purpose of the 

+<function>XNFocusWindow</function>

+is to identify the window that will receive the key event when input

+is composed.

+In addition, the input method may possibly affect the focus window

+as follows:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Select events on it

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Send events to it

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Modify its properties

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Grab the keyboard within that window  

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+The associated value must be of type 

+<function>Window</function>.

+If the focus window is not a valid window ID on the display 

+attached to the input method,

+a 

+<function>BadWindow</function>

+error can be generated when this value is used by the input method.

+</para>

+<para>

+<!-- .LP -->

+When this <acronym>XIC</acronym> value is left unspecified,

+the input method will use the client window as the default focus window.

+</para>

+</sect3>

+<sect3 id="Resource_Name_and_Class_b">

+<title>Resource Name and Class</title>

+<!-- .XS -->

+<!-- (SN Resource Name and Class -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XNResourceName</primary></indexterm>

+<indexterm significance="preferred"><primary>XNResourceClass</primary></indexterm>

+The

+<function>XNResourceName</function>

+and

+<function>XNResourceClass</function>

+arguments are strings that specify the full name and class

+used by the client to obtain resources for the client window. 

+These values should be used as prefixes for name and class

+when looking up resources that may vary according to the input context.

+If these values are not set,

+the resources will not be fully specified.

+</para>

+<para>

+<!-- .LP -->

+It is not intended that values that can be set as <acronym>XIC</acronym> values be

+set as resources.

+</para>

+</sect3>

+<sect3 id="Geometry_Callback">

+<title>Geometry Callback</title>

+<!-- .XS -->

+<!-- (SN Geometry Callback -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XNGeometryCallback</primary></indexterm>

+The 

+<function>XNGeometryCallback</function>

+argument is a structure of type 

+<function>XIMCallback </function>

+(see section 13.5.6.13.12).

+</para>

+<para>

+<!-- .LP -->

+The 

+<function>XNGeometryCallback</function>

+argument specifies the geometry callback that a client can set.

+This callback is not required for correct operation of either 

+an input method or a client.

+It can be set for a client whose user interface policy permits

+an input method to request the dynamic change of that input 

+method's window.

+An input method that does dynamic change will need to filter any

+events that it uses to initiate the change.

+</para>

+</sect3>

+<sect3 id="Filter_Events">

+<title>Filter Events</title>

+<!-- .XS -->

+<!-- (SN Filter Events -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XNFilterEvents</primary></indexterm>

+The 

+<function>XNFilterEvents</function>

+argument returns the event mask that an input method needs

+to have selected for.

+The client is expected to augment its own event mask 

+for the client window with this one.

+</para>

+<para>

+<!-- .LP -->

+This argument is read-only, is set by the input method at create time,

+and is never changed.

+</para>

+<para>

+<!-- .LP -->

+The type of this argument is 

+<function>unsigned</function>

+<function>long</function>.

+Setting this value will cause an error.

+</para>

+</sect3>

+<sect3 id="Destroy_Callback_b">

+<title>Destroy Callback</title>

+<!-- .XS -->

+<!-- (SN Destroy Callback  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The 

+<function>XNDestroyCallback </function>

+argument is a pointer to a structure of type

+<function>XIMCallback </function>

+(see section 13.5.6.13.12).  This callback is triggered when the input method 

+stops its service for any reason; for example, when a connection to an IM

+server is broken.  After the destroy callback is called, 

+the input context is destroyed and the input method is closed.

+Therefore, the client should not call 

+<function>XDestroyIC</function>

+and

+<function>XCloseIM</function>.

+</para>

+<para>

+<!-- .LP -->

+</para>

+</sect3>

+<sect3 id="String_Conversion_Callback">

+<title>String Conversion Callback</title>

+<!-- .XS -->

+<!-- (SN String Conversion Callback -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The

+<function>XNStringConversionCallback</function>

+argument is a structure of type

+<function>XIMCallback </function>

+(see section 13.5.6.13.12).

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XNStringConversionCallback</function>

+argument specifies a string conversion callback.  This callback

+is not required for correct operation of

+either the input method or the client.  It can be set by a client

+to support string conversions that may be requested

+by the input method.  An input method that does string conversions

+will filter any events that it uses to initiate the conversion.

+</para>

+<para>

+<!-- .LP -->

+Because this <acronym>XIC</acronym> value is optional, a client should call

+<function>XGetIMValues</function>

+with argument

+<function>XNQueryICValuesList</function>

+before using this argument.

+</para>

+<para>

+<!-- .LP -->

+</para>

+</sect3>

+<sect3 id="String_Conversion_">

+<title>String Conversion </title>

+<!-- .XS -->

+<!-- (SN String Conversion -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The

+<function>XNStringConversion</function>

+argument is a structure of type

+<function>XIMStringConversionText</function>.

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XNStringConversion</function>

+argument specifies the string to be converted by an input method.

+This argument is not required for correct operation of either

+the input method or the client.

+</para>

+<para>

+<!-- .LP -->

+String conversion facilitates the manipulation of text independent

+of preediting.

+It is essential for some input methods and clients to manipulate

+text by performing context-sensitive conversion,

+reconversion, or transliteration conversion on it.

+</para>

+<para>

+<!-- .LP -->

+Because this <acronym>XIC</acronym> value is optional, a client should call

+<function>XGetIMValues</function>

+with argument

+<function>XNQueryICValuesList</function>

+before using this argument.

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XIMStringConversionText</function>

+structure is defined as follows:

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+

+typedef struct _XIMStringConversionText {

+     unsigned short              length;

+     XIMStringConversionFeedback *feedback;

+     Bool                        encoding_is_wchar;

+     union {

+          char     *mbs;

+          wchar_t  *wcs;

+     } string;

+} XIMStringConversionText;

+

+typedef unsigned long XIMStringConversionFeedback;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The feedback member is reserved for future use.  The text to be

+converted is defined by the string and length members.  The length

+is indicated in characters.  To prevent the library from freeing memory

+pointed to by an uninitialized pointer, the client should set the feedback

+element to NULL.

+</para>

+<para>

+<!-- .LP -->

+</para>

+</sect3>

+<sect3 id="Reset_State">

+<title>Reset State</title>

+<!-- .XS -->

+<!-- (SN Reset State -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The

+<function>XNResetState</function>

+argument specifies the state the input context will return to after calling

+<function>XmbResetIC</function>

+or

+<function>XwcResetIC</function>.

+</para>

+<para>

+<!-- .LP -->

+The <acronym>XIC</acronym> state may be set to its initial state, as specified by the

+<function>XNPreeditState</function>

+value when

+<function>XCreateIC</function>

+was called, or it may be set to preserve the current state.

+</para>

+<para>

+<!-- .LP -->

+The valid masks for

+<function>XIMResetState</function>

+are as follows:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XIMInitialState</primary></indexterm>

+<indexterm significance="preferred"><primary>XINPreserveState</primary></indexterm>

+<!-- .sM -->

+</para>

+<literallayout class="monospaced">

+typedef unsigned long XIMResetState;

+

+#define XIMInitialState  (1L)

+#define XIMPreserveState (1L&lt;&lt;1)

+

+</literallayout>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If

+<function>XIMInitialState</function>

+is set, then

+<function>XmbResetIC</function>

+and

+<function>XwcResetIC</function>

+will return to the initial

+<function>XNPreeditState</function>

+state of the <acronym>XIC</acronym>.

+</para>

+<para>

+<!-- .LP -->

+If

+<function>XIMPreserveState</function>

+is set, then 

+<function>XmbResetIC</function>

+and

+<function>XwcResetIC</function>

+will preserve the current state of the <acronym>XIC</acronym>.

+</para>

+<para>

+<!-- .LP -->

+If

+<function>XNResetState</function>

+is left unspecified, the default is

+<function>XIMInitialState</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XIMResetState</function>

+values other than those specified above will default to

+<function>XIMInitialState</function>.

+</para>

+<para>

+<!-- .LP -->

+Because this <acronym>XIC</acronym> value is optional, a client should call

+<function>XGetIMValues</function>

+with argument

+<function>XNQueryICValuesList</function>

+before using this argument.

+</para>

+<para>

+<!-- .LP -->

+</para>

+</sect3>

+<sect3 id="Hot_Keys_b">

+<title>Hot Keys</title>

+<!-- .XS -->

+<!-- (SN Hot Keys -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The

+<function>XNHotKey</function>

+argument specifies the hot key list to the <acronym>XIC</acronym>.

+The hot key list is a pointer to the structure of type

+<function>XIMHotKeyTriggers</function>,

+which specifies the key events that must be received

+without any interruption of the input method.

+For the hot key list set with this argument to be utilized, the client

+must also set

+<function>XNHotKeyState</function>

+to

+<function>XIMHotKeyStateON</function>.

+</para>

+<para>

+<!-- .LP -->

+Because this <acronym>XIC</acronym> value is optional, a client should call

+<function>XGetIMValues</function>

+with argument

+<function>XNQueryICValuesList</function>

+before using this functionality.

+</para>

+<para>

+<!-- .LP -->

+The value of the argument is a pointer to a structure of type

+<function>XIMHotKeyTriggers</function>.

+</para>

+<para>

+<!-- .LP -->

+If an event for a key in the hot key list is found, then the process will

+receive the event and it will be processed inside the client.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct {

+     KeySym keysym;

+     unsigned int modifier;

+     unsigned int modifier_mask;

+} XIMHotKeyTrigger;

+

+typedef struct {

+     int num_hot_key;

+     XIMHotKeyTrigger *key;

+} XIMHotKeyTriggers;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+</para>

+<para>

+<!-- .LP -->

+The combination of modifier and modifier_mask are used to represent one of

+three states for each modifier:

+either the modifier must be on, or the modifier must be off, or the modifier

+is a ``don't care'' - it may be on or off.

+When a modifier_mask bit is set to 0, the state of the associated modifier

+is ignored when evaluating whether the key is hot or not.

+</para>

+

+<informaltable>

+  <tgroup cols='3' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <colspec colname='c3'/>

+  <thead>

+    <row>

+      <entry>Modifier Bit</entry>

+      <entry>Mask Bit</entry>

+      <entry>Meaning</entry>

+    </row>

+  </thead>

+  <tbody>

+    <row>

+      <entry>0</entry>

+      <entry>1</entry>

+      <entry>The modifier must be off.</entry>

+    </row>

+    <row>

+      <entry>1</entry>

+      <entry>1</entry>

+      <entry>The modifier must be on.</entry>

+    </row>

+    <row>

+      <entry>n/a</entry>

+      <entry>0</entry>

+      <entry>Do not care if the modifier is on or off.</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+</sect3>

+<sect3 id="Hot_Key_State">

+<title>Hot Key State</title>

+<!-- .XS -->

+<!-- (SN Hot Key State -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The

+<function>XNHotKeyState</function>

+argument specifies the hot key state of the input method.

+This is usually used to switch the input method between hot key

+operation and normal input processing.

+</para>

+<para>

+<!-- .LP -->

+The value of the argument is a pointer to a structure of type

+XIMHotKeyState .

+</para>

+<literallayout class="monospaced">

+typedef unsigned long XIMHotKeyState;

+

+#define XIMHotKeyStateON            (0x0001L)

+#define XIMHotKeyStateOFF           (0x0002L)

+

+</literallayout>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+</para>

+<para>

+<!-- .LP -->

+If not specified, the default is

+<function>XIMHotKeyStateOFF</function>.

+</para>

+<para>

+<!-- .LP -->

+</para>

+</sect3>

+<sect3 id="Preedit_and_Status_Attributes">

+<title>Preedit and Status Attributes</title>

+<!-- .XS -->

+<!-- (SN Preedit and Status Attributes -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XNPreeditAttributes</primary></indexterm>

+<indexterm significance="preferred"><primary>XNStatusAttributes</primary></indexterm>

+The

+<function>XNPreeditAttributes</function>

+and

+<function>XNStatusAttributes</function>

+arguments specify to an input method the attributes to be used for the 

+preedit and status areas,

+if any.

+Those attributes are passed to 

+<function>XSetICValues</function>

+or

+<function>XGetICValues</function>

+as a nested variable-length list.

+The names to be used in these lists are described in the following sections.

+</para>

+<sect4 id="Area">

+<title>Area</title>

+<!-- .XS -->

+<!-- (SN Area -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XNArea</primary></indexterm>

+The value of the

+<function>XNArea</function>

+argument must be a pointer to a structure of type

+<function>XRectangle</function>.

+The interpretation of the

+<function>XNArea</function>

+argument is dependent on the input method style that has been set.

+</para>

+<para>

+<!-- .LP -->

+If the input method style is 

+<function>XIMPreeditPosition</function>,

+<function>XNArea</function>

+specifies the clipping region within which preediting will take place.

+If the focus window has been set,

+the coordinates are assumed to be relative to the focus window.

+Otherwise, the coordinates are assumed to be relative to the client window.

+If neither has been set,

+the results are undefined.

+</para>

+<para>

+<!-- .LP -->

+If 

+<function>XNArea</function>

+is not specified, is set to NULL, or is invalid,

+the input method will default the clipping region

+to the geometry of the

+<function>XNFocusWindow</function>.

+If the area specified is NULL or invalid,

+the results are undefined.

+</para>

+<para>

+<!-- .LP -->

+If the input style is 

+<function>XIMPreeditArea</function>

+or 

+<function>XIMStatusArea</function>,

+<function>XNArea</function>

+specifies the geometry provided by the client to the input method.

+The input method may use this area to display its data,

+either preedit or status depending on the area designated.

+The input method may create a window as a child of the client window

+with dimensions that fit the

+<function>XNArea</function>.

+The coordinates are relative to the client window.

+If the client window has not been set yet,

+the input method should save these values 

+and apply them when the client window is set.

+If 

+<function>XNArea</function>

+is not specified, is set to NULL, or is invalid,

+the results are undefined.

+</para>

+</sect4>

+<sect4 id="Area_Needed">

+<title>Area Needed</title>

+<!-- .XS -->

+<!-- (SN Area Needed -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XNAreaNeeded</primary></indexterm>

+When set, the

+<function>XNAreaNeeded</function>

+argument specifies the geometry suggested by the client for this area

+(preedit or status).

+The value associated with the argument must be a pointer to a 

+structure of type 

+<function>XRectangle</function>.

+Note that the x, y values are not used

+and that nonzero values for width or height are the constraints 

+that the client wishes the input method to respect.

+</para>

+<para>

+<!-- .LP -->

+When read, the

+<function>XNAreaNeeded</function>

+argument specifies the preferred geometry desired by the input method

+for the area.

+</para>

+<para>

+<!-- .LP -->

+This argument is only valid if the input style is 

+<function>XIMPreeditArea</function>

+or 

+<function>XIMStatusArea</function>.

+It is used for geometry negotiation between the client and the input method

+and has no other effect on the input method 

+(see section 13.5.1.5).

+</para>

+</sect4>

+<sect4 id="Spot_Location">

+<title>Spot Location</title>

+<!-- .XS -->

+<!-- (SN Spot Location -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XNSpotLocation</primary></indexterm>

+The

+<function>XNSpotLocation</function>

+argument specifies to the input method the coordinates of the spot

+to be used by an input method executing with 

+<function>XNInputStyle </function>

+set to 

+<function>XIMPreeditPosition</function>.

+When specified to any input method other than 

+<function>XIMPreeditPosition</function>,

+this <acronym>XIC</acronym> value is ignored.

+</para>

+<para>

+<!-- .LP -->

+The x coordinate specifies the position where the next character

+would be inserted.

+The y coordinate is the position of the baseline used

+by the current text line in the focus window.

+The x and y coordinates are relative to the focus window, if it has been set;

+otherwise, they are relative to the client window.

+If neither the focus window nor the client window has been set,

+the results are undefined.

+</para>

+<para>

+<!-- .LP -->

+The value of the argument is a pointer to a structure of type

+<function>XPoint</function>.

+</para>

+</sect4>

+<sect4 id="Colormap">

+<title>Colormap</title>

+<!-- .XS -->

+<!-- (SN Colormap -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Two different arguments can be used to indicate what colormap the input method

+should use to allocate colors, a colormap ID, or a standard colormap name.

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XNColormap</primary></indexterm>

+The

+<function>XNColormap</function>

+argument is used to specify a colormap ID.

+The argument value is of type

+<function>Colormap</function>.

+An invalid argument may generate a 

+<function>BadColor</function>

+error when it is used by the input method.

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XNStdColormap</primary></indexterm>

+The

+<function>XNStdColormap</function>

+argument is used to indicate the name of the standard colormap

+in which the input method should allocate colors.

+The argument value is an 

+<function>Atom</function>

+that should be a valid atom for calling

+<function>XGetRGBColormaps</function>.

+An invalid argument may generate a

+<function>BadAtom</function>

+error when it is used by the input method.

+</para>

+<para>

+<!-- .LP -->

+If the colormap is left unspecified,

+the client window colormap becomes the default.

+</para>

+</sect4>

+<sect4 id="Foreground_and_Background">

+<title>Foreground and Background</title>

+<!-- .XS -->

+<!-- (SN Foreground and Background -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XNForeground</primary></indexterm>

+<indexterm significance="preferred"><primary>XNBackground</primary></indexterm>

+The

+<function>XNForeground</function>

+and

+<function>XNBackground</function>

+arguments specify the foreground and background pixel, respectively.

+The argument value is of type

+<function>unsigned</function>

+<function>long</function>.

+It must be a valid pixel in the input method colormap.

+</para>

+<para>

+<!-- .LP -->

+If these values are left unspecified,

+the default is determined by the input method.

+</para>

+</sect4>

+<sect4 id="Background_Pixmap">

+<title>Background Pixmap</title>

+<!-- .XS -->

+<!-- (SN Background Pixmap -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The

+<function>XNBackgroundPixmap</function>

+argument specifies a background pixmap to be used as the background of the

+window.

+The value must be of type 

+<function>Pixmap</function>.

+An invalid argument may generate a

+<function>BadPixmap</function>

+error when it is used by the input method.

+</para>

+<para>

+<!-- .LP -->

+If this value is left unspecified,

+the default is determined by the input method.

+</para>

+</sect4>

+<sect4 id="Font_Set">

+<title>Font Set</title>

+<!-- .XS -->

+<!-- (SN Font Set -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XNFontSet</primary></indexterm>

+The

+<function>XNFontSet</function>

+argument specifies to the input method what font set is to be used.

+The argument value is of type

+<function>XFontSet</function>.

+</para>

+<para>

+<!-- .LP -->

+If this value is left unspecified,

+the default is determined by the input method.

+</para>

+</sect4>

+<sect4 id="Line_Spacing">

+<title>Line Spacing</title>

+<!-- .XS -->

+<!-- (SN Line Spacing -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The

+<function>XNLineSpace</function>

+argument specifies to the input method what line spacing is to be used

+in the preedit window if more than one line is to be used.

+This argument is of type

+<function>int</function>.

+</para>

+<para>

+<!-- .LP -->

+If this value is left unspecified,

+the default is determined by the input method.

+</para>

+</sect4>

+<sect4 id="Cursor">

+<title>Cursor</title>

+<!-- .XS -->

+<!-- (SN Cursor -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XNCursor</primary></indexterm>

+The

+<function>XNCursor</function>

+argument specifies to the input method what cursor is to be used

+in the specified window.

+This argument is of type 

+<function>Cursor</function>.

+</para>

+<para>

+<!-- .LP -->

+An invalid argument may generate a

+<function>BadCursor</function>

+error when it is used by the input method.

+If this value is left unspecified,

+the default is determined by the input method.

+</para>

+</sect4>

+<sect4 id="Preedit_State">

+<title>Preedit State</title>

+<!-- .XS -->

+<!-- (SN Preedit State -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The

+<function>XNPreeditState</function>

+argument specifies the state of input preediting for the input method.

+Input preediting can be on or off.

+</para>

+<para>

+<!-- .LP -->

+The valid mask names for

+<function>XNPreeditState</function>

+are as follows:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XIMPreeditUnknown</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMPreeditEnable</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMPreeditDisable</primary></indexterm>

+<!-- .sM -->

+</para>

+<!-- .LP -->

+<literallayout class="monospaced">

+typedef unsigned long XIMPreeditState;

+

+#define XIMPreeditUnknown    0L

+#define XIMPreeditEnable     1L

+#define XIMPreeditDisable    (1L&lt;&lt;1)

+

+</literallayout>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If a value of

+<function>XIMPreeditEnable</function>

+is set, then input preediting is turned on by the input method.

+</para>

+<para>

+<!-- .LP -->

+If a value of

+<function>XIMPreeditDisable</function>

+is set, then input preediting is turned off by the input method.

+</para>

+<para>

+<!-- .LP -->

+If

+<function>XNPreeditState</function>

+is left unspecified, then the state will be implementation-dependent.

+</para>

+<para>

+<!-- .LP -->

+When

+<function>XNResetState</function>

+is set to

+<function>XIMInitialState</function>,

+the

+<function>XNPreeditState</function>

+value specified at the creation time will be reflected as the initial state for

+<function>XmbResetIC</function>

+and

+<function>XwcResetIC</function>.

+</para>

+<para>

+<!-- .LP -->

+Because this <acronym>XIC</acronym> value is optional, a client should call

+<function>XGetIMValues</function>

+with argument

+<function>XNQueryICValuesList</function>

+before using this argument.

+</para>

+</sect4>

+<sect4 id="Preedit_State_Notify_Callback">

+<title>Preedit State Notify Callback</title>

+<!-- .XS -->

+<!-- (SN Preedit State Notify Callback -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The preedit state notify callback is triggered by the input method

+when the preediting state has changed.

+The value of the

+<function>XNPreeditStateNotifyCallback</function>

+argument is a pointer to a structure of type

+<function>XIMCallback</function>.

+The generic prototype is as follows:

+<indexterm significance="preferred"><primary>PreeditStateNotifyCallback</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> PreeditStateNotifyCallback</function></funcdef>

+  <paramdef>XIC<parameter> ic</parameter></paramdef>

+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

+  <paramdef>XIMPreeditStateNotifyCallbackStruct<parameter> *call_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ic</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input context.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>client_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the additional client data.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>call_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the current preedit state.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XIMPreeditStateNotifyCallbackStruct</function>

+structure is defined as follows:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XIMPreeditStateNotifyCallbackStruct</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct _XIMPreeditStateNotifyCallbackStruct {

+     XIMPreeditState state;

+} XIMPreeditStateNotifyCallbackStruct;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+</para>

+<para>

+<!-- .LP -->

+Because this <acronym>XIC</acronym> value is optional, a client should call

+<function>XGetIMValues</function>

+with argument

+<function>XNQueryICValuesList</function>

+before using this argument.

+</para>

+</sect4>

+<sect4 id="Preedit_and_Status_Callbacks">

+<title>Preedit and Status Callbacks</title>

+<!-- .XS -->

+<!-- (SN Preedit and Status Callbacks -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+A client that wants to support the input style

+<function>XIMPreeditCallbacks</function>

+must provide a set of preedit callbacks to the input method.

+The set of preedit callbacks is as follows:

+</para>

+<indexterm significance="preferred"><primary>XNPreeditStartCallback</primary></indexterm>

+<indexterm significance="preferred"><primary>XNPreeditDoneCallback</primary></indexterm>

+<indexterm significance="preferred"><primary>XNPreeditDrawCallback</primary></indexterm>

+<indexterm significance="preferred"><primary>XNPreeditCaretCallback</primary></indexterm>

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <tbody>

+    <row>

+      <entry><function>XNPreeditStartCallback</function></entry>

+      <entry>This is called when the input method starts preedit.</entry>

+    </row>

+    <row>

+      <entry><function>XNPreeditDoneCallback</function></entry>

+      <entry>This is called when the input method stops preedit.</entry>

+    </row>

+    <row>

+      <entry><function>XNPreeditDrawCallback</function></entry>

+      <entry>This is called when a number of preedit keystrokes should be echoed.</entry>

+    </row>

+    <row>

+      <entry><function>XNPreeditCaretCallback</function></entry>

+      <entry>This is called to move the text insertion point within the preedit string.</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<para>

+<!-- .LP -->

+A client that wants to support the input style

+<function>XIMStatusCallbacks</function>

+must provide a set of status callbacks to the input method.

+The set of status callbacks is as follows:

+</para>

+

+<indexterm significance="preferred"><primary>XNStatusStartCallback</primary></indexterm>

+<indexterm significance="preferred"><primary>XNStatusDoneCallback</primary></indexterm>

+<indexterm significance="preferred"><primary>XNStatusDrawCallback</primary></indexterm>

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <tbody>

+    <row>

+      <entry><function>XNStatusStartCallback</function></entry>

+      <entry>This is called when the input method initializes the status area.</entry>

+    </row>

+    <row>

+      <entry><function>XNStatusDoneCallback</function></entry>

+      <entry>This is called when the input method no longer needs the status area.</entry>

+    </row>

+    <row>

+      <entry><function>XNStatusDrawCallback</function></entry>

+      <entry>This is called when updating of the status area is required.</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+<para>

+<!-- .LP -->

+The value of any status or preedit argument is a pointer

+to a structure of type

+<function>XIMCallback</function>.

+<indexterm significance="preferred"><primary>XIMProc</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMCallback</primary></indexterm>

+<!-- .sM -->

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef void (*XIMProc)();

+

+typedef struct {

+     XPointer client_data;

+     XIMProc callback;

+} XIMCallback;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Each callback has some particular semantics and will carry the data

+that expresses the environment necessary to the client 

+into a specific data structure.

+This paragraph only describes the arguments to be used to set

+the callback.

+</para>

+<para>

+<!-- .LP -->

+Setting any of these values while doing preedit

+may cause unexpected results.

+</para>

+</sect4>

+</sect3>

+</sect2>

+<sect2 id="Input_Method_Callback_Semantics">

+<title>Input Method Callback Semantics</title>

+<!-- .XS -->

+<!-- (SN Input Method Callback Semantics -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<acronym>XIM</acronym> callbacks are procedures defined by clients or text drawing packages

+that are to be called from the input method when selected events occur.

+Most clients will use a text editing package or a toolkit

+and, hence, will not need to define such callbacks.

+This section defines the callback semantics, when they are triggered,

+and what their arguments are.

+This information is mostly useful for X toolkit implementors.

+</para>

+<para>

+<!-- .LP -->

+Callbacks are mostly provided so that clients (or text editing

+packages) can implement on-the-spot preediting in their own window.

+In that case,

+the input method needs to communicate and synchronize with the client.

+The input method needs to communicate changes in the preedit window 

+when it is under control of the client.

+Those callbacks allow the client to initialize the preedit area,

+display a new preedit string,

+move the text insertion point during preedit,

+terminate preedit, or update the status area.

+</para>

+<para>

+<!-- .LP -->

+All callback procedures follow the generic prototype:

+<indexterm significance="preferred"><primary>CallbackPrototype</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> CallbackPrototype</function></funcdef>

+  <paramdef>XIC<parameter> ic</parameter></paramdef>

+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

+  <paramdef>SomeType<parameter> call_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ic</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input context.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>client_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the additional client data.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>call_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies data specific to the callback.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The call_data argument is a structure that expresses the arguments needed

+to achieve the semantics;

+that is,

+it is a specific data structure appropriate to the callback.

+In cases where no data is needed in the callback,

+this call_data argument is NULL.

+The client_data argument is a closure that has been initially specified

+by the client when specifying the callback and passed back.

+It may serve, for example, to inherit application context in the callback.

+</para>

+<para>

+<!-- .LP -->

+The following paragraphs describe the programming semantics

+and specific data structure associated with the different reasons.

+</para>

+<sect3 id="Geometry_Callback_b">

+<title>Geometry Callback</title>

+<!-- .XS -->

+<!-- (SN Geometry Callback -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The geometry callback is triggered by the input method 

+to indicate that it wants the client to negotiate geometry.

+The generic prototype is as follows:

+<indexterm significance="preferred"><primary>GeometryCallback</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> GeometryCallback</function></funcdef>

+  <paramdef>XIC<parameter> ic</parameter></paramdef>

+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

+  <paramdef>XPointer<parameter> call_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ic</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input context.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>client_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the additional client data.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>call_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Not used for this callback and always passed as NULL.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The callback is called with a NULL call_data argument.

+</para>

+</sect3>

+<sect3 id="Destroy_Callback_c">

+<title>Destroy Callback</title>

+<!-- .XS -->

+<!-- (SN Destroy Callback -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The destroy callback is triggered by the input method 

+when it stops service for any reason.

+After the callback is invoked, the input context will be freed by Xlib.

+The generic prototype is as follows:

+<indexterm significance="preferred"><primary>DestroyCallback</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> DestroyCallback</function></funcdef>

+  <paramdef>XIC<parameter> ic</parameter></paramdef>

+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

+  <paramdef>XPointer<parameter> call_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ic</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input context.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>client_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the additional client data.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>call_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Not used for this callback and always passed as NULL.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The callback is called with a NULL call_data argument.

+</para>

+</sect3>

+<sect3 id="String_Conversion_Callback_b">

+<title>String Conversion Callback</title>

+<!-- .XS -->

+<!-- (SN String Conversion Callback -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The string conversion callback is triggered by the input method 

+to request the client to return the string to be converted.  The

+returned string may be either a multibyte or wide character string,

+with an encoding matching the locale bound to the input context.

+The callback prototype is as follows:

+<indexterm significance="preferred"><primary>StringConversionCallback</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> StringConversionCallback</function></funcdef>

+  <paramdef>XIC<parameter> ic</parameter></paramdef>

+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

+  <paramdef>XIMStringConversionCallbackStruct<parameter> *call_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ic</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input method.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>client_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the additional client data.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>call_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the amount of the string to be converted.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The callback is passed an

+<function>XIMStringConversionCallbackStruct</function>

+structure in the call_data argument.

+The text member is an

+<function>XIMStringConversionText</function>

+structure (see section 13.5.6.9) to be filled in by the client

+and describes the text to be sent to the input method.

+The data pointed to by the 

+string and feedback elements of the

+<function>XIMStringConversionText</function>

+structure will be freed using

+<function>XFree</function>

+by the input method

+after the callback returns.  So the client should not point to 

+internal buffers that are critical to the client.

+Similarly, because the feedback element is currently reserved for future

+use, the client should set feedback to NULL to prevent the library from

+freeing memory at some random location due to an uninitialized pointer.

+</para>

+<para>

+<!-- .LP -->

+The 

+<function>XIMStringConversionCallbackStruct</function>

+structure is defined as follows:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XIMStringConversionCallbackStruct</primary></indexterm>

+<!-- .sM -->

+</para>

+<!-- .LP -->

+<literallayout class="monospaced">

+typedef struct _XIMStringConversionCallbackStruct {

+     XIMStringConversionPosition position;          

+     XIMCaretDirection direction;

+     short factor;

+     XIMStringConversionOperation operation;

+     XIMStringConversionText *text;

+} XIMStringConversionCallbackStruct;

+

+typedef short XIMStringConversionPosition;

+

+typedef unsigned short XIMStringConversionOperation;

+

+#define XIMStringConversionSubstitution       (0x0001)

+#define XIMStringConversionRetrieval          (0x0001)

+

+</literallayout>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<function>XIMStringConversionPosition</function>

+specifies the starting position of the string to be returned

+in the

+<function>XIMStringConversionText</function>

+structure.  The value identifies a position, in units of characters,

+relative to the client's cursor position in the client's buffer.

+</para>

+<para>

+<!-- .LP -->

+The ending position of the text buffer is determined by

+the direction and factor members.  Specifically, it is the character position 

+relative to the starting point as defined by the

+<function>XIMCaretDirection</function>.

+The factor member of 

+<function>XIMStringConversionCallbackStruct </function>

+specifies the number of

+<function>XIMCaretDirection </function>

+positions to be applied.  For example, if the direction specifies

+<function>XIMLineEnd</function>

+and factor is 1, then all characters from the starting position to 

+the end of the current display line are returned.  If the direction

+specifies

+<function>XIMForwardChar</function>

+or

+<function>XIMBackwardChar</function>,

+then the factor specifies a relative position, indicated in characters, 

+from the starting position.

+</para>

+<para>

+<!-- .LP -->

+<function>XIMStringConversionOperation</function>

+specifies whether the string to be converted should be 

+deleted (substitution) or copied (retrieval) from the client's

+buffer.  When the

+<function>XIMStringConversionOperation</function>

+is

+<function>XIMStringConversionSubstitution</function>,

+the client must delete the string to be converted from its own buffer.

+When the

+<function>XIMStringConversionOperation</function>

+is

+<function>XIMStringConversionRetrieval</function>,

+the client must not delete the string to be converted from its buffer.

+The substitute operation is typically used for reconversion and

+transliteration conversion,

+while the retrieval operation is typically used for context-sensitive 

+conversion.

+</para>

+</sect3>

+<sect3 id="Preedit_State_Callbacks">

+<title>Preedit State Callbacks</title>

+<!-- .XS -->

+<!-- (SN Preedit State Callbacks -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+When the input method turns preediting on or off, a

+<function>PreeditStartCallback</function>

+or

+<function>PreeditDoneCallback</function>

+callback is triggered to let the toolkit do the setup

+or the cleanup for the preedit region.

+<indexterm significance="preferred"><primary>PreeditStartCallback</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> PreeditStartCallback</function></funcdef>

+  <paramdef>XIC<parameter> ic</parameter></paramdef>

+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

+  <paramdef>XPointer<parameter> call_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ic</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input context.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>client_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the additional client data.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>call_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Not used for this callback and always passed as NULL.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+When preedit starts on the specified input context,

+the callback is called with a NULL call_data argument.

+<function>PreeditStartCallback</function>

+will return the maximum size of the preedit string.

+A positive number indicates the maximum number of bytes allowed

+in the preedit string, 

+and a value of -1 indicates there is no limit.

+<indexterm significance="preferred"><primary>PreeditDoneCallback</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> PreeditDoneCallback</function></funcdef>

+  <paramdef>XIC<parameter> ic</parameter></paramdef>

+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

+  <paramdef>XPointer<parameter> call_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ic</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input context.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>client_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the additional client data.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>call_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Not used for this callback and always passed as NULL.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+When preedit stops on the specified input context,

+the callback is called with a NULL call_data argument.

+The client can release the data allocated by

+<function>PreeditStartCallback</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>PreeditStartCallback</function>

+should initialize appropriate data needed for

+displaying preedit information and for handling further 

+<function>PreeditDrawCallback</function>

+calls.

+Once

+<function>PreeditStartCallback</function>

+is called, it will not be called again before

+<function>PreeditDoneCallback</function>

+has been called.

+</para>

+</sect3>

+<sect3 id="Preedit_Draw_Callback">

+<title>Preedit Draw Callback</title>

+<!-- .XS -->

+<!-- (SN Preedit Draw Callback -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+This callback is triggered to draw and insert, delete or replace,

+preedit text in the preedit region.

+The preedit text may include unconverted input text such as Japanese Kana,

+converted text such as Japanese Kanji characters, or characters of both kinds.

+That string is either a multibyte or wide character string, 

+whose encoding matches the locale bound to the input context.

+The callback prototype

+is as follows:

+<indexterm significance="preferred"><primary>PreeditDrawCallback</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> PreeditDrawCallback</function></funcdef>

+  <paramdef>XIC<parameter> ic</parameter></paramdef>

+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

+  <paramdef>XIMPreeditDrawCallbackStruct<parameter> *call_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ic</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input context.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>client_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the additional client data.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>call_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the preedit drawing information.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The callback is passed an 

+<function>XIMPreeditDrawCallbackStruct</function>

+structure in the call_data argument.

+The text member of this structure contains the text to be drawn.

+After the string has been drawn,

+the caret should be moved to the specified location.

+</para>

+<para>

+<!-- .LP -->

+The 

+<function>XIMPreeditDrawCallbackStruct</function>

+structure is defined as follows:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XIMPreeditDrawCallbackStruct</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct _XIMPreeditDrawCallbackStruct {

+     int caret;     /* Cursor offset within preedit string */

+     int chg_first;     /* Starting change position */

+     int chg_length;     /* Length of the change in character count */

+     XIMText *text;

+} XIMPreeditDrawCallbackStruct;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The client must keep updating a buffer of the preedit text

+and the callback arguments referring to indexes in that buffer.

+The call_data fields have specific meanings according to the operation,

+as follows:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+To indicate text deletion, 

+the call_data member specifies a NULL text field.

+The text to be deleted is then the current text in the buffer 

+from position chg_first (starting at zero) on a character length

+of chg_length.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+When text is non-NULL,

+it indicates insertion or replacement of text in the buffer.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The chg_length member

+identifies the number of characters in the current preedit buffer

+that are affected by this call.

+A positive chg_length indicates that chg_length number of characters, starting

+at chg_first, must be deleted or must be replaced by text, whose length is

+specified in the

+<function>XIMText</function>

+structure.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A chg_length value of zero indicates that text must be inserted

+right at the position specified by chg_first.

+A value of zero for chg_first specifies the first character in the buffer.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+chg_length and chg_first combine to identify the modification required to

+the preedit buffer; beginning at chg_first, replace chg_length number of

+characters with the text in the supplied

+<function>XIMText</function>

+structure. For example, suppose the preedit buffer contains the string "ABCDE".

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<literallayout class="monospaced">

+<!-- .ft C -->

+Text:      A B C D E

+          ^ ^ ^ ^ ^ ^

+CharPos:  0 1 2 3 4 5

+<!-- .sp -->

+<!-- .ft P -->

+</literallayout>

+The CharPos in the diagram shows the location of the character position

+relative to the character.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If the value of chg_first is 1 and the value of chg_length is 3, this

+says to replace 3 characters beginning at character position 1 with the

+string in the

+<function>XIMText</function>

+structure.

+Hence, <acronym>BCD</acronym> would be replaced by the value in the structure.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Though chg_length and chg_first are both signed integers they will

+never have a negative value.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The caret member

+identifies the character position before which the cursor should

+be placed - after modification to the preedit buffer has been completed.

+For example, if caret is zero, the cursor is at

+the beginning of the buffer.  If the caret is one, the cursor is between

+the first and second character.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XIMText</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 1.5i 3i -->

+typedef struct _XIMText {

+     unsigned short length;

+     XIMFeedback * feedback;

+     Bool encoding_is_wchar; 

+     union {

+          char * multi_byte;

+          wchar_t * wide_char;

+     } string; 

+} XIMText;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The text string passed is actually a structure specifying as follows:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+The length member is the text length in characters.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The encoding_is_wchar member is a value that indicates 

+if the text string is encoded in wide character or multibyte format.

+The text string may be passed either as multibyte or as wide character;

+the input method controls in which form data is passed.

+The client's

+callback routine must be able to handle data passed in either form.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The string member is the text string.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+The feedback member indicates rendering type for each character in the

+string member.

+If string is NULL (indicating that only highlighting of the existing

+preedit buffer should be updated), feedback points to length highlight

+elements that should be applied to the existing preedit buffer, beginning

+at chg_first.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+The feedback member expresses the types of rendering feedback

+the callback should apply when drawing text.

+Rendering of the text to be drawn is specified either in generic ways

+(for example, primary, secondary) or in specific ways (reverse, underline).

+When generic indications are given,

+the client is free to choose the rendering style.

+It is necessary, however, that primary and secondary be mapped 

+to two distinct rendering styles.

+</para>

+<para>

+<!-- .LP -->

+If an input method wants to control display of the preedit string, an 

+input method can indicate the visibility hints using feedbacks in

+a specific way.

+The 

+<function>XIMVisibleToForward</function>,

+<function>XIMVisibleToBackward</function>,

+and

+<function>XIMVisibleCenter</function>

+masks are exclusively used for these visibility hints.

+The 

+<function>XIMVisibleToForward</function>

+mask

+indicates that the preedit text is preferably displayed in the

+primary draw direction from the

+caret position in the preedit area forward.

+The 

+<function>XIMVisibleToBackward</function>

+mask

+indicates that the preedit text is preferably displayed from

+the caret position in the preedit area backward, relative to the primary

+draw direction.

+The 

+<function>XIMVisibleCenter</function>

+mask

+indicates that the preedit text is preferably displayed with

+the caret position in the preedit area centered.

+</para>

+<para>

+<!-- .LP -->

+The insertion point of the preedit string could exist outside of

+the visible area when visibility hints are used.

+Only one of the 

+masks

+is valid for the entire preedit string, and only one character

+can hold one of these feedbacks for a given input context at one time.

+This feedback may be OR'ed together with another highlight (such as

+<function>XIMReverse</function>).

+Only the most recently set feedback is valid, and any previous

+feedback is automatically canceled.  This is a hint to the client, and

+the client is free to choose how to display the preedit string.

+</para>

+<para>

+<!-- .LP -->

+The feedback member also specifies how rendering of the text argument

+should be performed.

+If the feedback is NULL,

+the callback should apply the same feedback as is used for the surrounding

+characters in the preedit buffer; if chg_first is at a highlight boundary,

+the client can choose which of the two highlights to use.

+If feedback is not NULL, feedback specifies an array defining the

+rendering for each

+character of the string, and the length of the array is thus length.

+</para>

+<para>

+<!-- .LP -->

+If an input method wants to indicate that it is only updating the feedback of

+the preedit text without changing the content of it, 

+the

+<function>XIMText</function>

+structure will contain a NULL value for the string field,

+the number of characters affected (relative to chg_first)

+will be in the length field,

+and the feedback field will point to an array of 

+<function>XIMFeedback</function>.

+</para>

+<para>

+<!-- .LP -->

+Each element in the feedback array is a bitmask represented by a value of type

+<function>XIMFeedback</function>.

+The valid mask names are as follows:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XIMReverse</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMUnderline</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMHighlight</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMPrimary</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMSecondary</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMTertiary</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMVisibleToForward</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMVisibleToBackward</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMVisibleCenter</primary></indexterm>

+<!-- .sM -->

+</para>

+<literallayout class="monospaced">

+typedef unsigned long XIMFeedback;

+

+#define     XIMReverse                     1L

+#define     XIMUnderline                   (1L&lt;&lt;1)

+#define     XIMHighlight                   (1L&lt;&lt;2)

+#define     XIMPrimary                     (1L&lt;&lt;5)*

+#define     XIMSecondary                   (1L&lt;&lt;6)*

+#define     XIMTertiary                    (1L&lt;&lt;7)*

+#define     XIMVisibleToForward            (1L&lt;&lt;8)

+#define     XIMVisibleToBackward           (1L&lt;&lt;9)

+#define     XIMVisibleCenter               (1L&lt;&lt;10)

+

+*† The values for XIMPrimary, XIMSecondary, and XIMTertiary were incorrectly defined in

+the R5 specification. The X Consortium’s X11R5 implementation correctly implemented the val-

+ues for these highlights. The value of these highlights has been corrected in this specification to

+agree with the values in the Consortium’s X11R5 and X11R6 implementations.

+

+</literallayout>

+

+<para>

+<!-- .LP -->

+Characters drawn with the

+<function>XIMReverse</function>

+highlight should be drawn by swapping the foreground and background colors

+used to draw normal, unhighlighted characters.

+Characters drawn with the

+<function>XIMUnderline</function>

+highlight should be underlined.

+Characters drawn with the

+<function>XIMHighlight</function>,

+<function>XIMPrimary</function>,

+<function>XIMSecondary</function>,

+and

+<function>XIMTertiary</function>

+highlights should be drawn in some unique manner that must be different

+from

+<function>XIMReverse</function>

+and

+<function>XIMUnderline</function>.

+<!-- .FS \(dg -->

+The values for

+<function>XIMPrimary</function>,

+<function>XIMSecondary</function>,

+and

+<function>XIMTertiary</function>

+were incorrectly defined in the R5 specification.

+The X Consortium's X11R5

+implementation correctly implemented the values for these highlights.

+The value of these highlights has been corrected in this specification

+to agree with the values in the Consortium's X11R5 and X11R6 implementations.

+<!-- .FE -->

+</para>

+</sect3>

+<sect3 id="Preedit_Caret_Callback">

+<title>Preedit Caret Callback</title>

+<!-- .XS -->

+<!-- (SN Preedit Caret Callback -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+An input method may have its own navigation keys to allow the user

+to move the text insertion point in the preedit area 

+(for example, to move backward or forward). 

+Consequently, input method needs to indicate to the client that it

+should move the text insertion point.

+It then calls the PreeditCaretCallback.

+<indexterm significance="preferred"><primary>PreeditCaretCallback</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> PreeditCaretCallback</function></funcdef>

+  <paramdef>XIC<parameter> ic</parameter></paramdef>

+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

+  <paramdef>XIMPreeditCaretCallbackStruct<parameter> *call_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ic</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input context.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>client_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the additional client data.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>call_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the preedit caret information.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The input method will trigger PreeditCaretCallback

+to move the text insertion point during preedit.

+The call_data argument contains a pointer to an 

+<function>XIMPreeditCaretCallbackStruct</function>

+structure,

+which indicates where the caret should be moved.

+The callback must move the insertion point to its new location

+and return, in field position, the new offset value from the initial position.  

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XIMPreeditCaretCallbackStruct</function>

+structure is defined as follows:

+<indexterm significance="preferred"><primary>XIMPreeditCaretCallbackStruct</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct _XIMPreeditCaretCallbackStruct {

+     int position;     /* Caret offset within preedit string */

+     XIMCaretDirection direction;     /* Caret moves direction */

+     XIMCaretStyle style;     /* Feedback of the caret */

+} XIMPreeditCaretCallbackStruct;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XIMCaretStyle</function>

+structure is defined as follows:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XIMCaretStyle</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef enum {

+     XIMIsInvisible,     /* Disable caret feedback */ 

+     XIMIsPrimary,     /* <acronym>UI</acronym> defined caret feedback */

+     XIMIsSecondary,     /* <acronym>UI</acronym> defined caret feedback */

+} XIMCaretStyle;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XIMCaretDirection</function>

+structure is defined as follows:

+<indexterm significance="preferred"><primary>XIMCaretDirection</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef enum {

+     XIMForwardChar, XIMBackwardChar,

+     XIMForwardWord, XIMBackwardWord,

+     XIMCaretUp, XIMCaretDown,

+     XIMNextLine, XIMPreviousLine,

+     XIMLineStart, XIMLineEnd, 

+     XIMAbsolutePosition,

+     XIMDontChange,

+ } XIMCaretDirection;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+These values are defined as follows:

+</para>

+<indexterm significance="preferred"><primary>XIMForwardChar</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMBackwardChar</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMForwardWord</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMBackwardWord</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMCaretUp</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMCaretDown</primary></indexterm>

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <tbody>

+    <row>

+      <entry><function>XIMForwardChar</function></entry>

+      <entry>Move the caret forward one character position.</entry>

+    </row>

+    <row>

+      <entry><function>XIMBackwardChar</function></entry>

+      <entry>Move the caret backward one character position.</entry>

+    </row>

+    <row>

+      <entry><function>XIMForwardWord</function></entry>

+      <entry>Move the caret forward one word.</entry>

+    </row>

+    <row>

+      <entry><function>XIMBackwardWord</function></entry>

+      <entry>Move the caret backward one word.</entry>

+    </row>

+    <row>

+      <entry><function>XIMCaretUp</function></entry>

+      <entry>Move the caret up one line keeping the current horizontal offset.</entry>

+    </row>

+    <row>

+      <entry><function>XIMCaretDown</function></entry>

+      <entry>Move the caret down one line keeping the current horizontal offset.</entry>

+    </row>

+    <row>

+      <entry><function>XIMPreviousLine</function></entry>

+      <entry>Move the caret to the beginning of the previous line.</entry>

+    </row>

+    <row>

+      <entry><function>XIMNextLine</function></entry>

+      <entry>Move the caret to the beginning of the next line.</entry>

+    </row>

+    <row>

+      <entry><function>XIMLineStart</function></entry>

+      <entry>Move the caret to the beginning of the current display line that contains the caret.</entry>

+    </row>

+    <row>

+      <entry><function>XIMLineEnd</function></entry>

+      <entry>Move the caret to the end of the current display line that contains the caret.</entry>

+    </row>

+    <row>

+      <entry><function>XIMAbsolutePosition</function></entry>

+      <entry>The callback must move to the location specified by the position field

+      of the callback data, indicated in characters, starting from the beginning

+      of the preedit text.

+      Hence, a value of zero means move back to the beginning of the preedit text.</entry>

+    </row>

+    <row>

+      <entry><function>XIMDontChange</function></entry>

+      <entry>The caret position does not change.</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<indexterm significance="preferred"><primary>XIMNextLine</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMPreviousLine</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMLineStart</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMLineEnd</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMAbsolutePosition</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMDontChange</primary></indexterm>

+</sect3>

+<sect3 id="Status_Callbacks">

+<title>Status Callbacks</title>

+<!-- .XS -->

+<!-- (SN Status Callbacks -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+An input method may communicate changes in the status of an input context

+(for example, created, destroyed, or focus changes) with three status

+callbacks:  StatusStartCallback, StatusDoneCallback, and StatusDrawCallback.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+When the input context is created or gains focus, 

+the input method calls the StatusStartCallback callback.

+<indexterm significance="preferred"><primary>StatusStartCallback</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> StatusStartCallback</function></funcdef>

+  <paramdef>XIC<parameter> ic</parameter></paramdef>

+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

+  <paramdef>XPointer<parameter> call_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ic</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input context.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>client_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the additional client data.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>call_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Not used for this callback and always passed as NULL.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The callback should initialize appropriate data for displaying status

+and for responding to StatusDrawCallback calls.  

+Once StatusStartCallback is called,

+it will not be called again before StatusDoneCallback has been called.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+When an input context

+is destroyed or when it loses focus, the input method calls StatusDoneCallback.

+<indexterm significance="preferred"><primary>StatusDoneCallback</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> StatusDoneCallback</function></funcdef>

+  <paramdef>XIC<parameter> ic</parameter></paramdef>

+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

+  <paramdef>XPointer<parameter> call_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ic</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input context.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>client_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the additional client data.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>call_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Not used for this callback and always passed as NULL.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The callback may release any data allocated on 

+<function>StatusStart</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+When an input context status has to be updated, the input method calls

+StatusDrawCallback.

+<indexterm significance="preferred"><primary>StatusDrawCallback</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> StatusDrawCallback</function></funcdef>

+  <paramdef>XIC<parameter> ic</parameter></paramdef>

+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

+  <paramdef>XIMStatusDrawCallbackStruct<parameter> *call_data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ic</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input context.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>client_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the additional client data.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>call_data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the status drawing information.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The callback should update the status area by either drawing a string

+or imaging a bitmap in the status area.

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XIMStatusDataType</function>

+and

+<function>XIMStatusDrawCallbackStruct</function>

+structures are defined as follows:

+<indexterm significance="preferred"><primary>XIMStatusDataType</primary></indexterm>

+<indexterm significance="preferred"><primary>XIMStatusDrawCallbackStruct</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 1i 3i -->

+<!-- .ta .5i 1i 3i -->

+typedef enum {

+     XIMTextType,

+     XIMBitmapType,

+} XIMStatusDataType;

+

+typedef struct _XIMStatusDrawCallbackStruct {

+     XIMStatusDataType type;

+     union {

+          XIMText *text;

+          Pixmap  bitmap;

+     } data;

+} XIMStatusDrawCallbackStruct;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+</para>

+<para>

+<!-- .LP -->

+The feedback styles

+<function>XIMVisibleToForward</function>,

+<function>XIMVisibleToBackward</function>,

+and

+<function>XIMVisibleToCenter</function>

+are not relevant and will not appear in the

+<function>XIMFeedback</function>

+element of the

+<function>XIMText</function>

+structure.

+</para>

+<para>

+<!-- .LP -->

+</para>

+</sect3>

+</sect2>

+<sect2 id="Event_Filtering_b">

+<title>Event Filtering</title>

+<!-- .XS -->

+<!-- (SN Event Filtering -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides the ability for an input method

+to register a filter internal to Xlib.

+This filter is called by a client (or toolkit) by calling

+<function>XFilterEvent</function>

+after calling 

+<function>XNextEvent</function>.

+Any client that uses the 

+<function>XIM</function>

+interface should call

+<function>XFilterEvent</function>

+to allow input methods to process their events without knowledge

+of the client's dispatching mechanism.

+A client's user interface policy may determine the priority

+of event filters with respect to other event-handling mechanisms

+(for example, modal grabs).

+</para>

+<para>

+<!-- .LP -->

+Clients may not know how many filters there are, if any,

+and what they do.

+They may only know if an event has been filtered on return of 

+<function>XFilterEvent</function>.

+Clients should discard filtered events.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To filter an event, use

+<function>XFilterEvent</function>.

+<indexterm significance="preferred"><primary>XFilterEvent</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool<function> XFilterEvent</function></funcdef>

+  <paramdef>XEvent<parameter> *event</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<!-- .ds Ev event to filter -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the (Ev.

+<!-- .ds Wi for which the filter is to be applied -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window (Wi.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If the window argument is

+<function>None</function>,

+<function>XFilterEvent </function>

+applies the filter to the window specified in the

+<function>XEvent</function>

+structure.

+The window argument is provided so that layers above Xlib

+that do event redirection can indicate to which window an event

+has been redirected.

+</para>

+<para>

+<!-- .LP -->

+If

+<function>XFilterEvent</function>

+returns

+<function>True</function>,

+then some input method has filtered the event,

+and the client should discard the event.

+If

+<function>XFilterEvent</function>

+returns

+<function>False</function>,

+then the client should continue processing the event.

+</para>

+<para>

+<!-- .LP -->

+If a grab has occurred in the client and

+<function>XFilterEvent</function>

+returns

+<function>True</function>,

+the client should ungrab the keyboard.

+</para>

+</sect2>

+<sect2 id="Getting_Keyboard_Input_b">

+<title>Getting Keyboard Input</title>

+<!-- .XS -->

+<!-- (SN Getting Keyboard Input -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To get composed input from an input method,

+use

+<function>XmbLookupString</function>

+or

+<function>XwcLookupString</function>.

+<indexterm significance="preferred"><primary>XmbLookupString</primary></indexterm>

+<indexterm significance="preferred"><primary>XwcLookupString</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> XmbLookupString</function></funcdef>

+  <paramdef>XIC<parameter> ic</parameter></paramdef>

+  <paramdef>XKeyPressedEvent<parameter> *event</parameter></paramdef>

+  <paramdef>char<parameter> *buffer_return</parameter></paramdef>

+  <paramdef>int<parameter> bytes_buffer</parameter></paramdef>

+  <paramdef>KeySym<parameter> *keysym_return</parameter></paramdef>

+  <paramdef>Status<parameter> *status_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> XwcLookupString</function></funcdef>

+  <paramdef>XIC<parameter> ic</parameter></paramdef>

+  <paramdef>XKeyPressedEvent<parameter> *event</parameter></paramdef>

+  <paramdef>wchar_t<parameter> *buffer_return</parameter></paramdef>

+  <paramdef>int<parameter> wchars_buffer</parameter></paramdef>

+  <paramdef>KeySym<parameter> *keysym_return</parameter></paramdef>

+  <paramdef>Status<parameter> *status_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ic</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the input context.

+<!-- .ds Ev key event to be used -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the (Ev.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>buffer_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns a multibyte string or wide character string (if any)

+from the input method.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>bytes_buffer</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>wchars_buffer</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies space available in the return buffer.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keysym_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the KeySym computed from the event if this argument is not NULL.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>status_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns a value indicating what kind of data is returned.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XmbLookupString</function>

+and

+<function>XwcLookupString</function>

+functions return the string from the input method specified

+in the buffer_return argument.

+If no string is returned,

+the buffer_return argument is unchanged.

+</para>

+<para>

+<!-- .LP -->

+The KeySym into which the KeyCode from the event was mapped is returned

+in the keysym_return argument if it is non-NULL and the status_return

+argument indicates that a KeySym was returned.

+If both a string and a KeySym are returned,

+the KeySym value does not necessarily correspond to the string returned.

+</para>

+<para>

+<!-- .LP -->

+<function>XmbLookupString</function>

+returns the length of the string in bytes, and

+<function>XwcLookupString</function>

+returns the length of the string in characters.

+Both

+<function>XmbLookupString</function>

+and

+<function>XwcLookupString</function>

+return text in the encoding of the locale bound to the input method

+of the specified input context.

+</para>

+<para>

+<!-- .LP -->

+Each string returned by

+<function>XmbLookupString</function>

+and

+<function>XwcLookupString</function>

+begins in the initial state of the encoding of the locale

+(if the encoding of the locale is state-dependent).

+<!-- .NT -->

+<note><para>

+To insure proper input processing,

+it is essential that the client pass only 

+<function>KeyPress</function>

+events to

+<function>XmbLookupString</function>

+and

+<function>XwcLookupString</function>.

+Their behavior when a client passes a 

+<function>KeyRelease</function>

+event is undefined.

+</para></note>

+<!-- .NE -->

+</para>

+<para>

+<!-- .LP -->

+Clients should check the status_return argument before

+using the other returned values.

+These two functions both return a value to status_return 

+that indicates what has been returned in the other arguments.

+The possible values returned are:

+</para>

+

+<informaltable>

+  <tgroup cols='2' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <tbody>

+    <row>

+      <entry><function>XBufferOverflow</function></entry>

+      <entry>The input string to be returned is too large for the supplied buffer_return.

+      The required size

+      (<function>XmbLookupString</function>

+      in bytes;

+      <function>XwcLookupString</function>

+      in characters) is returned as the value of the function,

+      and the contents of buffer_return and keysym_return are not modified.

+      The client should recall the function with the same event

+      and a buffer of adequate size to obtain the string.</entry>

+    </row>

+    <row>

+      <entry><function>XLookupNone</function></entry>

+      <entry>No consistent input has been composed so far.

+      The contents of buffer_return and keysym_return are not modified, 

+      and the function returns zero.</entry>

+    </row>

+    <row>

+      <entry><function>XLookupChars</function></entry>

+      <entry>Some input characters have been composed.

+      They are placed in the buffer_return argument,

+      and the string length is returned as the value of the function.

+      The string is encoded in the locale bound to the input context.

+      The content of the keysym_return argument is not modified.</entry>

+    </row>

+    <row>

+      <entry><function>XLookupKeySym</function></entry>

+      <entry>A KeySym has been returned instead of a string

+      and is returned in keysym_return.

+      The content of the buffer_return argument is not modified,

+      and the function returns zero.</entry>

+    </row>

+    <row>

+      <entry><function>XLookupBoth</function></entry>

+      <entry>Both a KeySym and a string are returned;

+      <function>XLookupChars</function>

+      and

+      <function>XLookupKeySym</function>

+      occur simultaneously.</entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<para>

+<!-- .LP -->

+It does not make any difference if the input context passed as an argument to

+<function>XmbLookupString</function>

+and

+<function>XwcLookupString</function>

+is the one currently in possession of the focus or not.

+Input may have been composed within an input context before it lost the focus,

+and that input may be returned on subsequent calls to

+<function>XmbLookupString</function>

+or

+<function>XwcLookupString</function>

+even though it does not have any more keyboard focus.

+</para>

+</sect2>

+<sect2 id="Input_Method_Conventions">

+<title>Input Method Conventions</title>

+<!-- .XS -->

+<!-- (SN Input Method Conventions -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The input method architecture is transparent to the client.

+However, clients should respect a number of conventions in order

+to work properly.

+Clients must also be aware of possible effects of synchronization

+between input method and library in the case of a remote input server.

+</para>

+<sect3 id="Client_Conventions">

+<title>Client Conventions</title>

+<!-- .XS -->

+<!-- (SN Client Conventions -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+A well-behaved client (or toolkit) should first query the input method style.

+If the client cannot satisfy the requirements of the supported styles

+(in terms of geometry management or callbacks),

+it should negotiate with the user continuation of the program

+or raise an exception or error of some sort.

+</para>

+</sect3>

+<sect3 id="Synchronization_Conventions">

+<title>Synchronization Conventions</title>

+<!-- .XS -->

+<!-- (SN Synchronization Conventions -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+A 

+<function>KeyPress</function>

+event with a KeyCode of zero is used exclusively as a

+signal that an input method has composed input that can be returned by

+<function>XmbLookupString</function>

+or

+<function>XwcLookupString</function>.

+No other use is made of a 

+<function>KeyPress</function>

+event with KeyCode of zero.

+</para>

+<para>

+<!-- .LP -->

+Such an event may be generated by either a front-end

+or a back-end input method in an implementation-dependent manner.

+Some possible ways to generate this event include:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+A synthetic event sent by an input method server

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+An artificial event created by a input method filter and pushed

+onto a client's event queue

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A 

+<function>KeyPress</function>

+event whose KeyCode value is modified by an input method filter

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+When callback support is specified by the client,

+input methods will not take action unless they explicitly

+called back the client and obtained no response

+(the callback is not specified or returned invalid data).

+</para>

+</sect3>

+</sect2>

+</sect1>

+<sect1 id="String_Constants">

+<title>String Constants</title>

+<!-- .XS -->

+<!-- (SN String Constants -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The following symbols for string constants are defined in

+&lt;X11/Xlib.h&gt; .

+Although they are shown here with particular macro definitions,

+they may be implemented as macros, as global symbols, or as a

+mixture of the two.  The string pointer value itself

+is not significant; clients must not assume that inequality of two

+values implies inequality of the actual string data.

+</para>

+

+<literallayout class="monospaced">

+#define XNVaNestedList                       "XNVaNestedList"

+#define XNSeparatorofNestedList              "separatorofNestedList"

+#define XNQueryInputStyle                    "queryInputStyle"

+#define XNClientWindow                       "clientWindow"

+#define XNInputStyle                         "inputStyle"

+#define XNFocusWindow                        "focusWindow"

+#define XNResourceName                       "resourceName"

+#define XNResourceClass                      "resourceClass"

+#define XNGeometryCallback                   "geometryCallback"

+#define XNDestroyCallback                    "destroyCallback"

+#define XNFilterEvents                       "filterEvents"

+#define XNPreeditStartCallback               "preeditStartCallback"

+#define XNPreeditDoneCallback                "preeditDoneCallback"

+#define XNPreeditDrawCallback                "preeditDrawCallback"

+#define XNPreeditCaretCallback               "preeditCaretCallback"

+#define XNPreeditStateNotifyCallback         "preeditStateNotifyCallback"

+#define XNPreeditAttributes                  "preeditAttributes"

+#define XNStatusStartCallback                "statusStartCallback"

+#define XNStatusDoneCallback                 "statusDoneCallback"

+#define XNStatusDrawCallback                 "statusDrawCallback"

+#define XNStatusAttributes                   "statusAttributes"

+#define XNArea                               "area"

+#define XNAreaNeeded                         "areaNeeded"

+#define XNSpotLocation                       "spotLocation"

+#define XNColormap                           "colorMap"

+#define XNStdColormap                        "stdColorMap"

+#define XNForeground                         "foreground"

+#define XNBackground                         "background"

+#define XNBackgroundPixmap                   "backgroundPixmap"

+#define XNFontSet                            "fontSet"

+#define XNLineSpace                          "lineSpace"

+#define XNCursor                             "cursor"

+#define XNQueryIMValuesList                  "queryIMValuesList"

+#define XNQueryICValuesList                  "queryICValuesList"

+#define XNStringConversionCallback           "stringConversionCallback"

+#define XNStringConversion                   "stringConversion"

+#define XNResetState                         "resetState"

+#define XNHotKey                             "hotkey"

+#define XNHotKeyState                        "hotkeyState"

+#define XNPreeditState                       "preeditState"

+#define XNVisiblePosition                    "visiblePosition"

+#define XNR6PreeditCallbackBehavior          "r6PreeditCallback"

+#define XNRequiredCharSet                    "requiredCharSet"

+#define XNQueryOrientation                   "queryOrientation"

+#define XNDirectionalDependentDrawing        "directionalDependentDrawing"

+#define XNContextualDrawing                  "contextualDrawing"

+#define XNBaseFontName                       "baseFontName"

+#define XNMissingCharSet                     "missingCharSet"

+#define XNDefaultString                      "defaultString"

+#define XNOrientation                        "orientation"

+#define XNFontInfo                           "fontInfo"

+#define XNOMAutomatic                        "omAutomatic"

+

+</literallayout>

+

+</sect1>

+</chapter>

diff --git a/libX11/specs/libX11/CH14 b/libX11/specs/libX11/CH14
deleted file mode 100644
index 34c09da8b..000000000
--- a/libX11/specs/libX11/CH14
+++ /dev/null
@@ -1,3590 +0,0 @@
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-.\" OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" Except as contained in this notice, the name of the X Consortium shall
-.\" not be used in advertising or otherwise to promote the sale, use or
-.\" other dealings in this Software without prior written authorization
-.\" from the X Consortium.
-.\"
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
-.\" Digital Equipment Corporation
-.\"
-.\" Portions Copyright \(co 1990, 1991 by
-.\" Tektronix, Inc.
-.\"
-.\" Permission to use, copy, modify and distribute this documentation for
-.\" any purpose and without fee is hereby granted, provided that the above
-.\" copyright notice appears in all copies and that both that copyright notice
-.\" and this permission notice appear in all copies, and that the names of
-.\" Digital and Tektronix not be used in in advertising or publicity pertaining
-.\" to this documentation without specific, written prior permission.
-.\" Digital and Tektronix makes no representations about the suitability
-.\" of this documentation for any purpose.
-.\" It is provided ``as is'' without express or implied warranty.
-.\" 
-\&
-.sp 1
-.ce 3
-\s+1\fBChapter 14\fP\s-1
-
-\s+1\fBInter-Client Communication Functions\fP\s-1
-.sp 2
-.nr H1 14
-.nr H2 0
-.nr H3 0
-.nr H4 0
-.nr H5 0
-.na
-.LP
-.XS
-Chapter 14: Inter-Client Communication Functions
-.XE
-The \fIInter-Client Communication Conventions Manual\fP,
-hereafter referred to as the ICCCM, details the
-X Consortium approved conventions that govern inter-client communications.
-These conventions ensure peer-to-peer client cooperation in the use 
-of selections, cut buffers, and shared resources as well as client cooperation
-with window and session managers.
-For further information,
-see the \fIInter-Client Communication Conventions Manual\fP.
-.LP
-Xlib provides a number of standard properties and programming interfaces
-that are ICCCM compliant.
-The predefined atoms for some of these properties are defined in the
-.hN X11/Xatom.h
-header file, where
-to avoid name conflicts with user symbols their
-.PN #define
-name has an XA_ prefix.
-For further information about atoms and properties,
-see section 4.3.
-.LP
-Xlib's selection and cut buffer mechanisms provide the primary programming 
-interfaces by which peer client applications communicate with each other 
-(see sections 4.5 and 16.6).
-The functions discussed in this chapter provide 
-the primary programming interfaces by which client applications communicate 
-with their window and session managers as well as share standard colormaps.
-.LP
-The standard properties that are of special interest for communicating 
-with window and session managers are:
-.IN "Atom" "predefined"
-.TS H
-lw(2i) lw(1.1i) lw(.4i) lw(2.25i)
-lw(2i) lw(1.1i) cw(.4i) lw(2.25i).
-_
-.sp 6p
-.B
-Name	Type	Format	Description
-.sp 6p
-_
-.TH
-.R
-T{
-\s-1WM_CLASS\s+1
-T}	T{
-\s-1STRING\s+1
-T}	T{
-8
-T}	T{
-Set by application programs to allow window and session
-managers to obtain the application's resources from the resource database.
-T}
-.sp 6p
-T{
-\s-1WM_CLIENT_MACHINE\s+1
-T}	T{
-\s-1TEXT\s+1
-T}	T{
-T}	T{
-The string name of the machine on which the client application is running.
-T}
-.sp 6p
-T{
-\s-1WM_COLORMAP_WINDOWS\s+1
-T}	T{
-\s-1WINDOW\s+1
-T}	T{
-32
-T}	T{
-The list of window IDs that may need a different colormap
-from that of their top-level window.
-T}
-.sp 6p
-T{
-\s-1WM_COMMAND\s+1
-T}	T{
-\s-1TEXT\s+1
-T}	T{
-T}	T{
-The command and arguments, null-separated, used to invoke the
-application.
-T}
-.sp 6p
-T{
-\s-1WM_HINTS\s+1
-T}	T{
-\s-1WM_HINTS\s+1
-T}	T{
-32
-T}	T{
-Additional hints set by the client for use by the window manager.
-The C type of this property is 
-.PN XWMHints .
-T}
-.sp 6p
-T{
-\s-1WM_ICON_NAME\s+1
-T}	T{
-\s-1TEXT\s+1
-T}	T{
-T}	T{
-The name to be used in an icon.
-T}
-.sp 6p
-T{
-\s-1WM_ICON_SIZE\s+1
-T}	T{
-\s-1WM_ICON_SIZE\s+1
-T}	T{
-32
-T}	T{
-The window manager may set this property on the root window to
-specify the icon sizes it supports.
-The C type of this property is 
-.PN XIconSize .
-T}
-.sp 6p
-T{
-\s-1WM_NAME\s+1
-T}	T{
-\s-1TEXT\s+1
-T}	T{
-T}	T{
-The name of the application.
-T}
-.sp 6p
-T{
-\s-1WM_NORMAL_HINTS\s+1
-T}	T{
-\s-1WM_SIZE_HINTS\s+1
-T}	T{
-32
-T}	T{
-Size hints for a window in its normal state.
-The C type of this property is
-.PN XSizeHints .
-T}
-.sp 6p
-T{
-\s-1WM_PROTOCOLS\s+1
-T}	T{
-\s-1ATOM\s+1
-T}	T{
-32
-T}	T{
-List of atoms that identify the communications protocols between the
-client and window manager in which the client is willing to participate.
-T}
-.sp 6p
-T{
-\s-1WM_STATE\s+1
-T}	T{
-\s-1WM_STATE\s+1
-T}	T{
-32
-T}	T{
-Intended for communication between window and session managers only.
-T}
-.sp 6p
-T{
-\s-1WM_TRANSIENT_FOR\s+1
-T}	T{
-\s-1WINDOW\s+1
-T}	T{
-32
-T}	T{
-Set by application programs to indicate to the window manager that a transient
-top-level window, such as a dialog box.
-T}
-.sp 6p
-_
-.TE
-.LP
-The remainder of this chapter discusses:
-.IP \(bu 5
-Client to window manager communication
-.IP \(bu 5
-Client to session manager communication
-.IP \(bu 5
-Standard colormaps
-.NH 2
-Client to Window Manager Communication
-.XS
-\*(SN Client to Window Manager Communication
-.XE
-.LP
-This section discusses how to:
-.IP \(bu 5
-Manipulate top-level windows
-.IP \(bu 5
-Convert string lists
-.IP \(bu 5
-Set and read text properties
-.IP \(bu 5
-Set and read the WM_NAME property
-.IP \(bu 5
-Set and read the WM_ICON_NAME property
-.IP \(bu 5
-Set and read the WM_HINTS property
-.IP \(bu 5
-Set and read the WM_NORMAL_HINTS property
-.IP \(bu 5
-Set and read the WM_CLASS property
-.IP \(bu 5
-Set and read the WM_TRANSIENT_FOR property
-.IP \(bu 5
-Set and read the WM_PROTOCOLS property
-.IP \(bu 5
-Set and read the WM_COLORMAP_WINDOWS property
-.IP \(bu 5
-Set and read the WM_ICON_SIZE property
-.IP \(bu 5
-Use window manager convenience functions
-.NH 3
-Manipulating Top-Level Windows
-.XS
-\*(SN Manipulating Top-Level Windows
-.XE
-.LP
-Xlib provides functions that you can use to change the visibility or size
-of top-level windows (that is, those that were created as children 
-of the root window).
-Note that the subwindows that you create are ignored by window managers.
-Therefore,
-you should use the basic window functions described in chapter 3
-to manipulate your application's subwindows.
-.LP
-To request that a top-level window be iconified, use
-.PN XIconifyWindow .
-.IN "XIconifyWindow" "" "@DEF@"
-.sM
-.FD 0
-Status XIconifyWindow\^(\^\fIdisplay\fP, \fIw\fP, \fIscreen_number\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP;
-.br
-      int \fIscreen_number\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIscreen_number\fP 1i
-Specifies the appropriate screen number on the host server.
-.LP
-.eM
-The 
-.PN XIconifyWindow 
-function sends a WM_CHANGE_STATE 
-.PN ClientMessage 
-event with a format of 32 and a first data element of 
-.PN IconicState 
-(as described in section 4.1.4 of the 
-\fIInter-Client Communication Conventions Manual\fP)
-and a window of w
-to the root window of the specified screen
-with an event mask set to
-.PN SubstructureNotifyMask |
-.PN SubstructureRedirectMask .
-Window managers may elect to receive this message and
-if the window is in its normal state, 
-may treat it as a request to change the window's state from normal to iconic.
-If the WM_CHANGE_STATE property cannot be interned, 
-.PN XIconifyWindow
-does not send a message and returns a zero status.
-It returns a nonzero status if the client message is sent successfully;
-otherwise, it returns a zero status.
-.sp
-.LP
-To request that a top-level window be withdrawn, use
-.PN XWithdrawWindow .
-.IN "XWithdrawWindow" "" "@DEF@"
-.sM
-.FD 0
-Status XWithdrawWindow\^(\^\fIdisplay\fP, \fIw\fP, \fIscreen_number\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      int \fIscreen_number\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIscreen_number\fP 1i
-Specifies the appropriate screen number on the host server.
-.LP
-.eM
-The 
-.PN XWithdrawWindow 
-function unmaps the specified window 
-and sends a synthetic 
-.PN UnmapNotify 
-event to the root window of the specified screen.
-Window managers may elect to receive this message 
-and may treat it as a request to change the window's state to withdrawn.
-When a window is in the withdrawn state, 
-neither its normal nor its iconic representations is visible.
-It returns a nonzero status if the 
-.PN UnmapNotify 
-event is successfully sent; 
-otherwise, it returns a zero status.
-.LP
-.PN XWithdrawWindow
-can generate a
-.PN BadWindow
-error.
-.sp
-.LP
-To request that a top-level window be reconfigured, use
-.PN XReconfigureWMWindow .
-.IN "XReconfigureWMWindow" "" "@DEF@"
-.sM
-.FD 0
-Status XReconfigureWMWindow\^(\^\fIdisplay\fP, \fIw\fP, \fIscreen_number\fP, \
-\fIvalue_mask\fP, \fIvalues\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      int \fIscreen_number\fP\^;
-.br
-      unsigned int \fIvalue_mask\fP\^;
-.br
-      XWindowChanges *\fIvalues\fP;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIscreen_number\fP 1i
-Specifies the appropriate screen number on the host server.
-.IP \fIvalue_mask\fP 1i
-Specifies which values are to be set using information in
-the values structure.
-This mask is the bitwise inclusive OR of the valid configure window values bits.
-.IP \fIvalues\fP 1i
-Specifies the 
-.PN XWindowChanges 
-structure.
-.LP
-.eM
-The 
-.PN XReconfigureWMWindow 
-function issues a 
-.PN ConfigureWindow 
-request on the specified top-level window.
-If the stacking mode is changed and the request fails with a 
-.PN BadMatch 
-error, 
-the error is trapped by Xlib and a synthetic 
-.PN ConfigureRequestEvent 
-containing the same configuration parameters is sent to the root 
-of the specified window.
-Window managers may elect to receive this event 
-and treat it as a request to reconfigure the indicated window.
-It returns a nonzero status if the request or event is successfully sent;
-otherwise, it returns a zero status.
-.LP
-.PN XReconfigureWMWindow 
-can generate
-.PN BadValue 
-and 
-.PN BadWindow 
-errors.
-.NH 3
-Converting String Lists
-.XS
-\*(SN Converting String Lists
-.XE
-.LP
-Many of the text properties allow a variety of types and formats.
-Because the data stored in these properties are not
-simple null-terminated strings, an
-.PN XTextProperty
-structure is used to describe the encoding, type, and length of the text 
-as well as its value.
-The
-.PN XTextProperty
-structure contains:
-.IN "XTextProperty" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	unsigned char *value;	/* property data */
-	Atom encoding;	/* type of property */
-	int format;	/* 8, 16, or 32 */
-	unsigned long nitems;	/* number of items in value */
-} XTextProperty;
-.De
-.LP
-.eM
-Xlib provides functions to convert localized text to or from encodings
-that support the inter-client communication conventions for text.
-In addition, functions are provided for converting between lists of pointers 
-to character strings and text properties in the STRING encoding.
-.LP
-The functions for localized text return a signed integer error status 
-that encodes 
-.PN Success
-as zero, specific error conditions as negative numbers, and partial conversion
-as a count of unconvertible characters.
-.LP
-.IN "XICCEncodingStyle" "" "@DEF@"
-.sM
-.TS
-lw(.5i) lw(2i) lw(2.5i).
-T{
-#define
-T}	T{
-.PN XNoMemory
-T}	T{
-\-1
-T}
-T{
-#define
-T}	T{
-.PN XLocaleNotSupported
-T}	T{
-\-2
-T}
-T{
-#define
-T}	T{
-.PN XConverterNotFound
-T}	T{
-\-3
-T}
-.TE
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef enum {
-	XStringStyle,		/* STRING */
-	XCompoundTextStyle,	/* COMPOUND_TEXT */
-	XTextStyle,		/* text in owner's encoding (current locale) */
-	XStdICCTextStyle	/* STRING, else COMPOUND_TEXT */
-} XICCEncodingStyle;
-.De
-.LP
-.eM
-.sp
-.LP
-To convert a list of text strings to an 
-.PN XTextProperty
-structure, use
-.PN XmbTextListToTextProperty
-or
-.PN XwcTextListToTextProperty .
-.IN "XmbTextListToTextProperty" "" "@DEF@"
-.IN "XwcTextListToTextProperty" "" "@DEF@"
-.sM
-.FD 0
-int XmbTextListToTextProperty\^(\^\fIdisplay\fP\^, \fIlist\fP\^, \fIcount\fP\^, \fIstyle\fP\^, \fItext_prop_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      char **\fIlist\fP\^;
-.br
-      int \fIcount\fP\^;
-.br
-      XICCEncodingStyle \fIstyle\fP\^;
-.br
-      XTextProperty *\fItext_prop_return\fP\^;
-.FN
-.FD 0
-int XwcTextListToTextProperty\^(\^\fIdisplay\fP\^, \fIlist\fP\^, \fIcount\fP\^, \fIstyle\fP\^, \fItext_prop_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      wchar_t **\fIlist\fP\^;
-.br
-      int \fIcount\fP\^;
-.br
-      XICCEncodingStyle \fIstyle\fP\^;
-.br
-      XTextProperty *\fItext_prop_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIlist\fP 1i
-Specifies a list of null-terminated character strings.
-.IP \fIcount\fP 1i
-Specifies the number of strings specified.
-.IP \fIstyle\fP 1i
-Specifies the manner in which the property is encoded.
-.IP \fItext_prop_return\fP 1i
-Returns the
-.PN XTextProperty
-structure.
-.LP
-.eM
-The
-.PN XmbTextListToTextProperty
-and
-.PN XwcTextListToTextProperty
-functions set the specified 
-.PN XTextProperty
-value to a set of null-separated elements representing the concatenation
-of the specified list of null-terminated text strings.
-A final terminating null is stored at the end of the value field 
-of text_prop_return but is not included in the nitems member.
-.LP
-The functions set the encoding field of text_prop_return to an
-.PN Atom 
-for the specified display 
-naming the encoding determined by the specified style
-and convert the specified text list to this encoding for storage in
-the text_prop_return value field.
-If the style 
-.PN XStringStyle
-or 
-.PN XCompoundTextStyle
-is specified,
-this encoding is ``STRING'' or ``COMPOUND_TEXT'', respectively.
-If the style 
-.PN XTextStyle
-is specified,
-this encoding is the encoding of the current locale.
-If the style 
-.PN XStdICCTextStyle
-is specified,
-this encoding is ``STRING'' if the text is fully convertible to STRING,
-else ``COMPOUND_TEXT''.
-.LP
-If insufficient memory is available for the new value string,
-the functions return 
-.PN XNoMemory .
-If the current locale is not supported,
-the functions return 
-.PN XLocaleNotSupported .
-In both of these error cases,
-the functions do not set text_prop_return.
-.LP
-To determine if the functions are guaranteed not to return
-.PN XLocaleNotSupported ,
-use
-.PN XSupportsLocale .
-.LP
-If the supplied text is not fully convertible to the specified encoding,
-the functions return the number of unconvertible characters.
-Each unconvertible character is converted to an implementation-defined and
-encoding-specific default string.
-Otherwise, the functions return 
-.PN Success .
-Note that full convertibility to all styles except 
-.PN XStringStyle
-is guaranteed.
-.LP
-To free the storage for the value field, use
-.PN XFree .
-.sp
-.LP
-To obtain a list of text strings from an 
-.PN XTextProperty 
-structure, use
-.PN XmbTextPropertyToTextList
-or
-.PN XwcTextPropertyToTextList .
-.IN "XmbTextPropertyToTextList" "" "@DEF@"
-.IN "XwcTextPropertyToTextList" "" "@DEF@"
-.sM
-.FD 0
-int XmbTextPropertyToTextList\^(\^\fIdisplay\fP\^, \fItext_prop\fP\^, \fIlist_return\fP\^, \fIcount_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XTextProperty *\fItext_prop\fP\^;
-.br
-      char ***\fIlist_return\fP\^;
-.br
-      int *\fIcount_return\fP\^;
-.FN
-.FD 0
-int XwcTextPropertyToTextList\^(\^\fIdisplay\fP\^, \fItext_prop\fP\^, \fIlist_return\fP\^, \fIcount_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XTextProperty *\fItext_prop\fP\^;
-.br
-      wchar_t ***\fIlist_return\fP\^;
-.br
-      int *\fIcount_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fItext_prop\fP 1i
-Specifies the
-.PN XTextProperty
-structure to be used.
-.IP \fIlist_return\fP 1i
-Returns a list of null-terminated character strings.
-.ds Cn strings
-.IP \fIcount_return\fP 1i
-Returns the number of \*(Cn.
-.LP
-.eM
-The 
-.PN XmbTextPropertyToTextList
-and 
-.PN XwcTextPropertyToTextList
-functions return a list of text strings in the current locale representing the
-null-separated elements of the specified
-.PN XTextProperty
-structure.
-The data in text_prop must be format 8.
-.LP
-Multiple elements of the property (for example, the strings in a disjoint
-text selection) are separated by a null byte.
-The contents of the property are not required to be null-terminated;
-any terminating null should not be included in text_prop.nitems.
-.LP
-If insufficient memory is available for the list and its elements,
-.PN XmbTextPropertyToTextList
-and
-.PN XwcTextPropertyToTextList
-return 
-.PN XNoMemory .
-If the current locale is not supported,
-the functions return
-.PN XLocaleNotSupported .
-Otherwise, if the encoding field of text_prop is not convertible 
-to the encoding of the current locale,
-the functions return
-.PN XConverterNotFound .
-For supported locales,
-existence of a converter from COMPOUND_TEXT, STRING
-or the encoding of the current locale is guaranteed if
-.PN XSupportsLocale 
-returns 
-.PN True
-for the current locale (but the actual text
-may contain unconvertible characters).
-Conversion of other encodings is implementation-dependent.
-In all of these error cases,
-the functions do not set any return values.
-.LP
-Otherwise, 
-.PN XmbTextPropertyToTextList
-and
-.PN XwcTextPropertyToTextList
-return the list of null-terminated text strings to list_return
-and the number of text strings to count_return.
-.LP
-If the value field of text_prop is not fully convertible to the encoding of
-the current locale,
-the functions return the number of unconvertible characters.
-Each unconvertible character is converted to a string in the
-current locale that is specific to the current locale.
-To obtain the value of this string, 
-use
-.PN XDefaultString .
-Otherwise,
-.PN XmbTextPropertyToTextList
-and
-.PN XwcTextPropertyToTextList
-return 
-.PN Success .
-.LP
-To free the storage for the list and its contents returned by
-.PN XmbTextPropertyToTextList ,
-use
-.PN XFreeStringList .
-To free the storage for the list and its contents returned by
-.PN XwcTextPropertyToTextList ,
-use
-.PN XwcFreeStringList .
-.sp
-.LP
-To free the in-memory data associated with the specified
-wide character string list, use
-.PN XwcFreeStringList .
-.IN "XwcFreeStringList" "" "@DEF@"
-.sM
-.FD 0
-void XwcFreeStringList\^(\^\fIlist\fP\^)
-.br
-      wchar_t **\fIlist\fP\^;
-.FN
-.IP \fIlist\fP 1i
-Specifies the list of strings to be freed.
-.LP
-.eM
-The
-.PN XwcFreeStringList
-function frees memory allocated by
-.PN XwcTextPropertyToTextList .
-.sp
-.LP
-To obtain the default string for text conversion in the current locale,
-use
-.PN XDefaultString .
-.IN "XDefaultString" "" "@DEF@"
-.sM
-.FD 0
-char *XDefaultString\^(\|)
-.FN
-.LP
-.eM
-The
-.PN XDefaultString
-function returns the default string used by Xlib for text conversion
-(for example, in 
-.PN XmbTextPropertyToTextList ).
-The default string is the string in the current locale that is output 
-when an unconvertible character is found during text conversion.
-If the string returned by
-.PN XDefaultString
-is the empty string ("\^"),
-no character is output in the converted text.
-.PN XDefaultString
-does not return NULL.
-.LP
-The string returned by 
-.PN XDefaultString
-is independent of the default string for text drawing;
-see 
-.PN XCreateFontSet
-to obtain the default string for an
-.PN XFontSet .
-.LP
-The behavior when an invalid codepoint is supplied to any Xlib function is
-undefined.
-.LP
-The returned string is null-terminated.
-It is owned by Xlib and should not be modified or freed by the client.
-It may be freed after the current locale is changed.
-Until freed, it will not be modified by Xlib.
-.sp
-.LP
-To set the specified list of strings in the STRING encoding to a 
-.PN XTextProperty
-structure, use
-.PN XStringListToTextProperty .
-.IN "XStringListToTextProperty" "" "@DEF@"
-.sM
-.FD 0
-Status XStringListToTextProperty\^(\^\fIlist\fP, \fIcount\fP, \
-\fItext_prop_return\fP\^)
-.br
-      char **\fIlist\fP\^;
-.br
-      int \fIcount\fP\^;
-.br
-      XTextProperty *\fItext_prop_return\fP\^;
-.FN
-.IP \fIlist\fP 1i
-Specifies a list of null-terminated character strings.
-.ds Cn strings
-.IP \fIcount\fP 1i
-Specifies the number of \*(Cn.
-.IP \fItext_prop_return\fP 1i
-Returns the
-.PN XTextProperty
-structure.
-.LP
-.eM
-The 
-.PN XStringListToTextProperty 
-function sets the specified 
-.PN XTextProperty
-to be of type STRING (format 8) with a value representing the
-concatenation of the specified list of null-separated character strings.
-An extra null byte (which is not included in the nitems member) 
-is stored at the end of the value field of text_prop_return.
-The strings are assumed (without verification) to be in the STRING encoding.
-If insufficient memory is available for the new value string, 
-.PN XStringListToTextProperty
-does not set any fields in the
-.PN XTextProperty
-structure and returns a zero status.
-Otherwise, it returns a nonzero status.
-To free the storage for the value field, use 
-.PN XFree .
-.sp
-.LP
-To obtain a list of strings from a specified
-.PN XTextProperty
-structure in the STRING encoding, use
-.PN XTextPropertyToStringList .
-.IN "XTextPropertyToStringList" "" "@DEF@"
-.sM
-.FD 0
-Status XTextPropertyToStringList\^(\^\fItext_prop\fP, \fIlist_return\fP, \
-\fIcount_return\fP\^)
-.br
-       XTextProperty *\fItext_prop\fP\^;
-.br
-       char ***\fIlist_return\fP\^;
-.br
-       int *\fIcount_return\fP\^;
-.FN
-.IP \fItext_prop\fP 1i
-Specifies the
-.PN XTextProperty
-structure to be used.
-.IP \fIlist_return\fP 1i
-Returns a list of null-terminated character strings.
-.ds Cn strings
-.IP \fIcount_return\fP 1i
-Returns the number of \*(Cn.
-.LP
-.eM
-The 
-.PN XTextPropertyToStringList 
-function returns a list of strings representing the null-separated elements 
-of the specified
-.PN XTextProperty
-structure.
-The data in text_prop must be of type STRING and format 8. 
-Multiple elements of the property 
-(for example, the strings in a disjoint text selection) 
-are separated by NULL (encoding 0).
-The contents of the property are not null-terminated.
-If insufficient memory is available for the list and its elements, 
-.PN XTextPropertyToStringList
-sets no return values and returns a zero status.
-Otherwise, it returns a nonzero status.
-To free the storage for the list and its contents, use 
-.PN XFreeStringList .
-.sp
-.LP
-To free the in-memory data associated with the specified string list, use
-.PN XFreeStringList .
-.IN "XFreeStringList" "" "@DEF@"
-.sM
-.FD 0
-void XFreeStringList\^(\^\fIlist\fP\^)
-.br
-      char **\fIlist\fP\^;
-.FN
-.IP \fIlist\fP 1i
-Specifies the list of strings to be freed.
-.LP
-.eM
-The 
-.PN XFreeStringList 
-function releases memory allocated by 
-.PN XmbTextPropertyToTextList
-and
-.PN XTextPropertyToStringList
-and the missing charset list allocated by 
-.PN XCreateFontSet .
-.NH 3
-Setting and Reading Text Properties
-.XS
-\*(SN Setting and Reading Text Properties
-.XE
-.LP
-Xlib provides two functions that you can use to set and read
-the text properties for a given window.
-You can use these functions to set and read those properties of type TEXT
-(WM_NAME, WM_ICON_NAME, WM_COMMAND, and WM_CLIENT_MACHINE).
-In addition,
-Xlib provides separate convenience functions that you can use to set each 
-of these properties.
-For further information about these convenience functions,
-see sections 14.1.4, 14.1.5, 14.2.1, and 14.2.2, respectively.
-.sp
-.LP
-To set one of a window's text properties, use
-.PN XSetTextProperty .
-.IN "XSetTextProperty" "" "@DEF@"
-.sM
-.FD 0
-void XSetTextProperty\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP, \
-\fIproperty\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XTextProperty *\fItext_prop\fP\^;
-.br
-      Atom \fIproperty\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fItext_prop\fP 1i
-Specifies the
-.PN XTextProperty
-structure to be used.
-.IP \fIproperty\fP 1i
-Specifies the property name.
-.LP
-.eM
-The
-.PN XSetTextProperty
-function replaces the existing specified property for the named window 
-with the data, type, format, and number of items determined 
-by the value field, the encoding field, the format field, 
-and the nitems field, respectively, of the specified
-.PN XTextProperty
-structure.
-If the property does not already exist,
-.PN XSetTextProperty
-sets it for the specified window.
-.LP
-.PN XSetTextProperty
-can generate
-.PN BadAlloc ,
-.PN BadAtom , 
-.PN BadValue , 
-and 
-.PN BadWindow  
-errors.
-.sp
-.LP
-To read one of a window's text properties, use
-.PN XGetTextProperty .
-.IN "XGetTextProperty" "" "@DEF@"
-.sM
-.FD 0
-Status XGetTextProperty\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP, \
-\fIproperty\fP\^)
-.br
-       Display *\fIdisplay\fP\^;
-.br
-       Window \fIw\fP\^;
-.br
-       XTextProperty *\fItext_prop_return\fP\^;
-.br
-       Atom \fIproperty\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fItext_prop_return\fP 1i
-Returns the
-.PN XTextProperty
-structure.
-.IP \fIproperty\fP 1i
-Specifies the property name.
-.LP
-.eM
-The
-.PN XGetTextProperty 
-function reads the specified property from the window
-and stores the data in the returned
-.PN XTextProperty
-structure.
-It stores the data in the value field,
-the type of the data in the encoding field,
-the format of the data in the format field, 
-and the number of items of data in the nitems field.
-An extra byte containing null (which is not included in the nitems member) 
-is stored at the end of the value field of text_prop_return.
-The particular interpretation of the property's encoding 
-and data as text is left to the calling application.
-If the specified property does not exist on the window,
-.PN XGetTextProperty
-sets the value field to NULL, 
-the encoding field to
-.PN None , 
-the format field to zero, 
-and the nitems field to zero.
-.LP
-If it was able to read and store the data in the
-.PN XTextProperty
-structure,
-.PN XGetTextProperty
-returns a nonzero status; 
-otherwise, it returns a zero status.
-.LP
-.PN XGetTextProperty
-can generate
-.PN BadAtom 
-and 
-.PN BadWindow 
-errors.
-.NH 3
-Setting and Reading the WM_NAME Property
-.XS
-\*(SN Setting and Reading the WM_NAME Property
-.XE
-.LP
-Xlib provides convenience functions that you can use to set and read 
-the WM_NAME property for a given window.
-.sp
-.LP
-To set a window's WM_NAME property with the supplied convenience function, use
-.PN XSetWMName .
-.IN "XSetWMName" "" "@DEF@"
-.sM
-.FD 0
-void XSetWMName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XTextProperty *\fItext_prop\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fItext_prop\fP 1i
-Specifies the
-.PN XTextProperty
-structure to be used.
-.LP
-.eM
-The
-.PN XSetWMName
-convenience function calls
-.PN XSetTextProperty 
-to set the WM_NAME property.
-.sp
-.LP
-To read a window's WM_NAME property with the supplied convenience function, use
-.PN XGetWMName .
-.IN "XGetWMName" "" "@DEF@"
-.sM
-.FD 0
-Status XGetWMName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XTextProperty *\fItext_prop_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fItext_prop_return\fP 1i
-Returns the
-.PN XTextProperty
-structure.
-.LP
-.eM
-The
-.PN XGetWMName 
-convenience function calls
-.PN XGetTextProperty 
-to obtain the WM_NAME property.
-It returns a nonzero status on success;
-otherwise, it returns a zero status.
-.LP
-The following two functions have been superseded by
-.PN XSetWMName
-and
-.PN XGetWMName ,
-respectively. 
-You can use these additional convenience functions 
-for window names that are encoded as STRING properties.
-.sp
-.LP
-To assign a name to a window, use
-.PN XStoreName .
-.IN "Window" "name"
-.IN "XStoreName" "" "@DEF@"
-.sM
-.FD 0
-XStoreName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwindow_name\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      char *\fIwindow_name\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIwindow_name\fP 1i
-Specifies the window name,
-which should be a null-terminated string.
-.LP
-.eM
-The
-.PN XStoreName
-function assigns the name passed to window_name to the specified window.
-A window manager can display the window name in some prominent
-place, such as the title bar, to allow users to identify windows easily.
-Some window managers may display a window's name in the window's icon,
-although they are encouraged to use the window's icon name
-if one is provided by the application.
-If the string is not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-.LP
-.PN XStoreName
-can generate
-.PN BadAlloc
-and
-.PN BadWindow
-errors.
-.LP
-.sp
-To get the name of a window, use
-.PN XFetchName .
-.IN "XFetchName" "" "@DEF@"
-.sM
-.FD 0
-Status XFetchName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwindow_name_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      char **\fIwindow_name_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIwindow_name_return\fP 1i
-Returns the window name, which is a null-terminated string.
-.LP
-.eM
-The
-.PN XFetchName
-function returns the name of the specified window.
-If it succeeds,
-it returns a nonzero status; 
-otherwise, no name has been set for the window,
-and it returns zero.
-If the WM_NAME property has not been set for this window,
-.PN XFetchName
-sets window_name_return to NULL.
-If the data returned by the server is in the Latin Portable Character Encoding,
-then the returned string is in the Host Portable Character Encoding.
-Otherwise, the result is implementation-dependent.
-When finished with it, a client must free
-the window name string using
-.PN XFree .
-.LP
-.PN XFetchName
-can generate a
-.PN BadWindow
-error.
-.NH 3
-Setting and Reading the WM_ICON_NAME Property
-.XS
-\*(SN Setting and Reading the WM_ICON_NAME Property
-.XE
-.LP
-Xlib provides convenience functions that you can use to set and read 
-the WM_ICON_NAME property for a given window.
-.LP
-.sp
-To set a window's WM_ICON_NAME property,
-use
-.PN XSetWMIconName .
-.IN "XSetWMIconName" "" "@DEF@"
-.sM
-.FD 0
-void XSetWMIconName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XTextProperty *\fItext_prop\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fItext_prop\fP 1i
-Specifies the
-.PN XTextProperty
-structure to be used.
-.LP
-.eM
-The
-.PN XSetWMIconName
-convenience function calls
-.PN XSetTextProperty
-to set the WM_ICON_NAME property.
-.sp
-.LP
-To read a window's WM_ICON_NAME property,
-use
-.PN XGetWMIconName .
-.IN "XGetWMIconName" "" "@DEF@"
-.sM
-.FD 0
-Status XGetWMIconName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XTextProperty *\fItext_prop_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fItext_prop_return\fP 1i
-Returns the
-.PN XTextProperty
-structure.
-.LP
-.eM
-The 
-.PN XGetWMIconName 
-convenience function calls
-.PN XGetTextProperty 
-to obtain the WM_ICON_NAME property.
-It returns a nonzero status on success;
-otherwise, it returns a zero status.
-.LP
-The next two functions have been superseded by
-.PN XSetWMIconName
-and
-.PN XGetWMIconName ,
-respectively.
-You can use these additional convenience functions 
-for window names that are encoded as STRING properties.
-.sp
-.LP
-.sp
-To set the name to be displayed in a window's icon, use
-.PN XSetIconName .
-.IN "Window" "icon name"
-.IN "XSetIconName" "" "@DEF@"
-.sM
-.FD 0
-XSetIconName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIicon_name\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      char *\fIicon_name\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIicon_name\fP 1i
-Specifies the icon name,
-which should be a null-terminated string.
-.LP
-.eM
-If the string is not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-.PN XSetIconName
-can generate
-.PN BadAlloc
-and
-.PN BadWindow
-errors.
-.LP
-.sp
-To get the name a window wants displayed in its icon, use
-.PN XGetIconName .
-.IN "XGetIconName" "" "@DEF@"
-.sM
-.FD 0
-Status XGetIconName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIicon_name_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      char **\fIicon_name_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIicon_name_return\fP 1i
-Returns the window's icon name,
-which is a null-terminated string.
-.LP
-.eM
-The
-.PN XGetIconName
-function returns the name to be displayed in the specified window's icon.
-If it succeeds, it returns a nonzero status; otherwise, 
-if no icon name has been set for the window,
-it returns zero.
-If you never assigned a name to the window,
-.PN XGetIconName
-sets icon_name_return to NULL.
-If the data returned by the server is in the Latin Portable Character Encoding,
-then the returned string is in the Host Portable Character Encoding.
-Otherwise, the result is implementation-dependent.
-When finished with it, a client must free
-the icon name string using
-.PN XFree .
-.LP
-.PN XGetIconName
-can generate a
-.PN BadWindow
-error.
-.NH 3
-Setting and Reading the WM_HINTS Property
-.XS
-\*(SN Setting and Reading the WM_HINTS Property
-.XE
-.LP
-Xlib provides functions that you can use to set and read 
-the WM_HINTS property for a given window.
-These functions use the flags and the
-.PN XWMHints 
-structure, as defined in the
-.hN X11/Xutil.h
-header file.
-.sp
-.LP
-To allocate an
-.PN XWMHints
-structure, use
-.PN XAllocWMHints .
-.IN "XAllocWMHints" "" "@DEF@"
-.sM
-.FD 0
-XWMHints *XAllocWMHints\^(\|)
-.FN
-.LP
-.eM
-The
-.PN XAllocWMHints
-function allocates and returns a pointer to an
-.PN XWMHints
-structure.
-Note that all fields in the
-.PN XWMHints
-structure are initially set to zero.
-If insufficient memory is available, 
-.PN XAllocWMHints
-returns NULL.
-To free the memory allocated to this structure,
-use
-.PN XFree .
-.LP
-The
-.PN XWMHints
-structure contains:
-.LP
-.sM
-/* Window manager hints mask bits */
-.TS
-lw(.5i) lw(2.5i) lw(2.5i).
-T{
-#define
-T}	T{
-.PN InputHint
-T}	T{
-(1L << 0)
-T}
-T{
-#define
-T}	T{
-.PN StateHint
-T}	T{
-(1L << 1)
-T}
-T{
-#define
-T}	T{
-.PN IconPixmapHint
-T}	T{
-(1L << 2)
-T}
-T{
-#define
-T}	T{
-.PN IconWindowHint
-T}	T{
-(1L << 3)
-T}
-T{
-#define
-T}	T{
-.PN IconPositionHint
-T}	T{
-(1L << 4)
-T}
-T{
-#define
-T}	T{
-.PN IconMaskHint
-T}	T{
-(1L << 5)
-T}
-T{
-#define
-T}	T{
-.PN WindowGroupHint
-T}	T{
-(1L << 6)
-T}
-T{
-#define
-T}	T{
-.PN UrgencyHint
-T}	T{
-(1L << 8)
-T}
-T{
-#define
-T}	T{
-.PN AllHints
-T}	T{
-(InputHint|StateHint|IconPixmapHint|
-.br
-IconWindowHint|IconPositionHint|
-.br
-IconMaskHint|WindowGroupHint)
-T}
-.TE
-.IN "XWMHints" "" "@DEF@"
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-/* Values */
-
-typedef struct {
-	long flags;	/* marks which fields in this structure are defined */
-	Bool input;	/* does this application rely on the window manager to
-			get keyboard input? */
-	int initial_state;	/* see below */
-	Pixmap icon_pixmap;	/* pixmap to be used as icon */
-	Window icon_window;	/* window to be used as icon */
-	int icon_x, icon_y;	/* initial position of icon */
-	Pixmap icon_mask;	/* pixmap to be used as mask for icon_pixmap */
-	XID window_group;	/* id of related window group */
-	/* this structure may be extended in the future */
-} XWMHints;
-.De
-.LP
-.eM
-The input member is used to communicate to the window manager the input focus
-model used by the application.
-Applications that expect input but never explicitly set focus to any 
-of their subwindows (that is, use the push model of focus management), 
-such as X Version 10 style applications that use real-estate
-driven focus, should set this member to 
-.PN True .  
-Similarly, applications
-that set input focus to their subwindows only when it is given to their
-top-level window by a window manager should also set this member to 
-.PN True .
-Applications that manage their own input focus by explicitly setting
-focus to one of their subwindows whenever they want keyboard input 
-(that is, use the pull model of focus management) should set this member to 
-.PN False .
-Applications that never expect any keyboard input also should set this member
-to 
-.PN False .
-.LP
-Pull model window managers should make it possible for push model
-applications to get input by setting input focus to the top-level windows of
-applications whose input member is 
-.PN True .  
-Push model window managers should
-make sure that pull model applications do not break them 
-by resetting input focus to 
-.PN PointerRoot 
-when it is appropriate (for example, whenever an application whose
-input member is 
-.PN False 
-sets input focus to one of its subwindows).
-.LP
-The definitions for the initial_state flag are:
-.TS
-lw(.5i) lw(2i) lw(.2i) lw(2.8i).
-T{
-#define
-T}	T{
-.PN WithdrawnState
-T}	T{
-0
-T}	T{
-T}
-T{
-#define
-T}	T{
-.PN NormalState
-T}	T{
-1
-T}	T{
-/* most applications start this way */
-T}
-T{
-#define
-T}	T{
-.PN IconicState
-T}	T{
-3
-T}	T{
-/* application wants to start as an icon */
-T}
-.TE
-The icon_mask specifies which pixels of the icon_pixmap should be used as the
-icon.  
-This allows for nonrectangular icons.
-Both icon_pixmap and icon_mask must be bitmaps.
-The icon_window lets an application provide a window for use as an icon
-for window managers that support such use.
-The window_group lets you specify that this window belongs to a group
-of other windows.
-For example, if a single application manipulates multiple 
-top-level windows, this allows you to provide enough
-information that a window manager can iconify all of the windows
-rather than just the one window.
-.LP
-The
-.PN UrgencyHint
-flag, if set in the flags field, indicates that the client deems the window
-contents to be urgent, requiring the timely response of the user.  The
-window manager will make some effort to draw the user's attention to this
-window while this flag is set.  The client must provide some means by which the
-user can cause the urgency flag to be cleared (either mitigating
-the condition that made the window urgent or merely shutting off the alarm)
-or the window to be withdrawn.
-.LP
-.sp
-To set a window's WM_HINTS property, use
-.PN XSetWMHints .
-.IN "XSetWMHints" "" "@DEF@"
-.sM
-.FD 0
-XSetWMHints\^(\^\fIdisplay\fP, \fIw\fP, \fIwmhints\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XWMHints *\fIwmhints\fP\^;
-
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIwmhints\fP 1i
-Specifies the 
-.PN XWMHints
-structure to be used.
-.LP
-.eM
-The
-.PN XSetWMHints
-function sets the window manager hints that include icon information and location,
-the initial state of the window, and whether the application relies on the
-window manager to get keyboard input.
-.LP
-.PN XSetWMHints
-can generate
-.PN BadAlloc
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To read a window's WM_HINTS property, use
-.PN XGetWMHints .
-.IN "XGetWMHints" "" "@DEF@"
-.sM
-.FD 0
-XWMHints *XGetWMHints\^(\^\fIdisplay\fP, \fIw\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.LP
-.eM
-The
-.PN XGetWMHints
-function reads the window manager hints and 
-returns NULL if no WM_HINTS property was set on the window 
-or returns a pointer to an 
-.PN XWMHints 
-structure if it succeeds.
-When finished with the data,
-free the space used for it by calling
-.PN XFree .
-.LP
-.PN XGetWMHints
-can generate a
-.PN BadWindow 
-error.
-.NH 3
-Setting and Reading the WM_NORMAL_HINTS Property
-.XS
-\*(SN Setting and Reading the WM_NORMAL_HINTS Property
-.XE
-.LP
-Xlib provides functions that you can use to set or read 
-the WM_NORMAL_HINTS property for a given window.
-The functions use the flags and the
-.PN XSizeHints 
-structure, as defined in the
-.hN X11/Xutil.h
-header file.
-.LP
-The size of the
-.PN XSizeHints
-structure may grow in future releases, as new components are
-added to support new ICCCM features.
-Passing statically allocated instances of this structure into
-Xlib may result in memory corruption when running against a
-future release of the library.
-As such, it is recommended that only dynamically allocated
-instances of the structure be used.
-.sp
-.LP
-To allocate an
-.PN XSizeHints
-structure, use
-.PN XAllocSizeHints .
-.IN "XAllocSizeHints" "" "@DEF@"
-.sM
-.FD 0
-XSizeHints *XAllocSizeHints\^(\|)
-.FN
-.LP
-.eM
-The
-.PN XAllocSizeHints
-function allocates and returns a pointer to an
-.PN XSizeHints
-structure.
-Note that all fields in the
-.PN XSizeHints
-structure are initially set to zero.
-If insufficient memory is available, 
-.PN XAllocSizeHints
-returns NULL.
-To free the memory allocated to this structure,
-use
-.PN XFree .
-.LP
-The
-.PN XSizeHints
-structure contains:
-.LP
-.sM
-/* Size hints mask bits */
-.TS
-lw(.5i) lw(1.1i) lw(1.5i) lw(3.1i).
-T{
-#define
-T}	T{
-.PN USPosition
-T}	T{
-(1L << 0)
-T}	T{
-/* user specified x, y */
-T}
-T{
-#define
-T}	T{
-.PN USSize
-T}	T{
-(1L << 1)
-T}	T{
-/* user specified width, height */
-T}
-T{
-#define
-T}	T{
-.PN PPosition
-T}	T{
-(1L << 2)
-T}	T{
-/* program specified position */
-T}
-T{
-#define
-T}	T{
-.PN PSize
-T}	T{
-(1L << 3)
-T}	T{
-/* program specified size */
-T}
-T{
-#define
-T}	T{
-.PN PMinSize
-T}	T{
-(1L << 4)
-T}	T{
-/* program specified minimum size */
-T}
-T{
-#define
-T}	T{
-.PN PMaxSize
-T}	T{
-(1L << 5)
-T}	T{
-/* program specified maximum size */
-T}
-T{
-#define
-T}	T{
-.PN PResizeInc
-T}	T{
-(1L << 6)
-T}	T{
-/* program specified resize increments */
-T}
-T{
-#define
-T}	T{
-.PN PAspect
-T}	T{
-(1L << 7)
-T}	T{
-/* program specified min and max aspect ratios */
-T}
-T{
-#define
-T}	T{
-.PN PBaseSize
-T}	T{
-(1L << 8)
-T}
-T{
-#define
-T}	T{
-.PN PWinGravity
-T}	T{
-(1L << 9)
-T}
-T{
-#define
-T}	T{
-.PN PAllHints
-T}	T{
-(PPosition|PSize|
-.br
-PMinSize|PMaxSize|
-.br
-PResizeInc|PAspect)
-T}	T{
-T}
-.TE
-.IN "XSizeHints" "" "@DEF@"
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-/* Values */
-
-typedef struct {
-	long flags;	/* marks which fields in this structure are defined */
-	int x, y;	/* Obsolete */
-	int width, height;	/* Obsolete */
-	int min_width, min_height;
-	int max_width, max_height;
-	int width_inc, height_inc;
-	struct {
-	       int x;	/* numerator */
-	       int y;	/* denominator */
-	} min_aspect, max_aspect;
-	int base_width, base_height;
-	int win_gravity;
-	/* this structure may be extended in the future */
-} XSizeHints;
-.De
-.LP
-.eM
-The x, y, width, and height members are now obsolete
-and are left solely for compatibility reasons.
-The min_width and min_height members specify the
-minimum window size that still allows the application to be useful.
-The max_width and max_height members specify the maximum window size.
-The width_inc and height_inc members define an arithmetic progression of
-sizes (minimum to maximum) into which the window prefers to be resized.
-The min_aspect and max_aspect members are expressed
-as ratios of x and y, 
-and they allow an application to specify the range of aspect
-ratios it prefers.
-The base_width and base_height members define the desired size of the window.
-The window manager will interpret the position of the window 
-and its border width to position the point of the outer rectangle 
-of the overall window specified by the win_gravity member.
-The outer rectangle of the window includes any borders or decorations
-supplied by the window manager.
-In other words,
-if the window manager decides to place the window where the client asked,
-the position on the parent window's border named by the win_gravity 
-will be placed where the client window would have been placed 
-in the absence of a window manager.
-.LP
-Note that use of the
-.PN PAllHints
-macro is highly discouraged.
-.sp
-.LP
-To set a window's WM_NORMAL_HINTS property, use
-.PN XSetWMNormalHints .
-.IN "XSetWMNormalHints" "" "@DEF@"
-.sM
-.FD 0
-void XSetWMNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XSizeHints *\fIhints\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIhints\fP 1i
-Specifies the size hints for the window in its normal state.
-.LP
-.eM
-The 
-.PN XSetWMNormalHints 
-function replaces the size hints for the WM_NORMAL_HINTS property 
-on the specified window.
-If the property does not already exist,
-.PN XSetWMNormalHints
-sets the size hints for the WM_NORMAL_HINTS property on the specified window.
-The property is stored with a type of WM_SIZE_HINTS and a format of 32.
-.LP
-.PN XSetWMNormalHints
-can generate
-.PN BadAlloc
-and
-.PN BadWindow
-errors.
-.sp
-.LP
-To read a window's WM_NORMAL_HINTS property, use
-.PN XGetWMNormalHints .
-.IN "XGetWMNormalHints" "" "@DEF@"
-.sM
-.FD 0
-Status XGetWMNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP, \
-\fIsupplied_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XSizeHints *\fIhints_return\fP\^;
-.br
-      long *\fIsupplied_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIhints_return\fP 1i
-Returns the size hints for the window in its normal state.
-.IP \fIsupplied_return\fP 1i
-Returns the hints that were supplied by the user.
-.LP
-.eM
-The 
-.PN XGetWMNormalHints 
-function returns the size hints stored in the WM_NORMAL_HINTS property 
-on the specified window.
-If the property is of type WM_SIZE_HINTS, is of format 32,
-and is long enough to contain either an old (pre-ICCCM) 
-or new size hints structure, 
-.PN XGetWMNormalHints
-sets the various fields of the 
-.PN XSizeHints
-structure, sets the supplied_return argument to the list of fields 
-that were supplied by the user (whether or not they contained defined values),
-and returns a nonzero status.
-Otherwise, it returns a zero status.
-.LP
-If 
-.PN XGetWMNormalHints
-returns successfully and a pre-ICCCM size hints property is read, 
-the supplied_return argument will contain the following bits:
-.LP
-.Ds
-(USPosition|USSize|PPosition|PSize|PMinSize|
- PMaxSize|PResizeInc|PAspect)
-.De
-.LP
-If the property is large enough to contain the base size 
-and window gravity fields as well, 
-the supplied_return argument will also contain the following bits:
-.LP
-.Ds
-PBaseSize|PWinGravity
-.De
-.LP
-.PN XGetWMNormalHints
-can generate a
-.PN BadWindow
-error.
-.sp
-.LP
-To set a window's WM_SIZE_HINTS property, use
-.PN XSetWMSizeHints .
-.IN "XSetWMSizeHints" "" "@DEF@"
-.sM
-.FD 0
-void XSetWMSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP, \fIproperty\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XSizeHints *\fIhints\fP\^;
-.br
-      Atom \fIproperty\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIhints\fP 1i
-Specifies the
-.PN XSizeHints
-structure to be used.
-.IP \fIproperty\fP 1i
-Specifies the property name.
-.LP
-.eM
-The 
-.PN XSetWMSizeHints 
-function replaces the size hints for the specified property 
-on the named window.
-If the specified property does not already exist,
-.PN XSetWMSizeHints
-sets the size hints for the specified property
-on the named window.
-The property is stored with a type of WM_SIZE_HINTS and a format of 32.
-To set a window's normal size hints, 
-you can use the 
-.PN XSetWMNormalHints
-function.
-.LP
-.PN XSetWMSizeHints
-can generate
-.PN BadAlloc ,
-.PN BadAtom , 
-and 
-.PN BadWindow
-errors.
-.sp
-.LP
-To read a window's WM_SIZE_HINTS property, use
-.PN XGetWMSizeHints .
-.IN "XGetWMSizeHints" "" "@DEF@"
-.sM
-.FD 0
-Status XGetWMSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP, \
-\fIsupplied_return\fP, \fIproperty\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XSizeHints *\fIhints_return\fP\^;
-.br
-      long *\fIsupplied_return\fP\^;
-.br
-      Atom \fIproperty\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIhints_return\fP 1i
-Returns the
-.PN XSizeHints
-structure.
-.IP \fIsupplied_return\fP 1i
-Returns the hints that were supplied by the user.
-.IP \fIproperty\fP 1i
-Specifies the property name.
-.LP
-.eM
-The 
-.PN XGetWMSizeHints
-function returns the size hints stored in the specified property 
-on the named window.
-If the property is of type WM_SIZE_HINTS, is of format 32, 
-and is long enough to contain either an old (pre-ICCCM) 
-or new size hints structure, 
-.PN XGetWMSizeHints
-sets the various fields of the 
-.PN XSizeHints
-structure, sets the supplied_return argument to the
-list of fields that were supplied by the user 
-(whether or not they contained defined values), 
-and returns a nonzero status.
-Otherwise, it returns a zero status.
-To get a window's normal size hints, 
-you can use the 
-.PN XGetWMNormalHints 
-function.
-.LP
-If 
-.PN XGetWMSizeHints
-returns successfully and a pre-ICCCM size hints property is read, 
-the supplied_return argument will contain the following bits:
-.LP
-.Ds
-(USPosition|USSize|PPosition|PSize|PMinSize|
- PMaxSize|PResizeInc|PAspect)
-.De
-.LP
-If the property is large enough to contain the base size 
-and window gravity fields as well, 
-the supplied_return argument will also contain the following bits:
-.LP
-.Ds
-PBaseSize|PWinGravity
-.De
-.LP
-.PN XGetWMSizeHints
-can generate
-.PN BadAtom 
-and 
-.PN BadWindow
-errors.
-.NH 3
-Setting and Reading the WM_CLASS Property
-.XS
-\*(SN Setting and Reading the WM_CLASS Property
-.XE
-.LP
-Xlib provides functions that you can use to set and get 
-the WM_CLASS property for a given window.
-These functions use the
-.PN XClassHint 
-structure, which is defined in the
-.hN X11/Xutil.h
-header file.
-.sp
-.LP
-To allocate an
-.PN XClassHint
-structure, use
-.PN XAllocClassHint .
-.IN "XAllocClassHint" "" "@DEF@"
-.sM
-.FD 0
-XClassHint *XAllocClassHint\^(\|)
-.FN
-.LP
-.eM
-The
-.PN XAllocClassHint
-function allocates and returns a pointer to an
-.PN XClassHint
-structure.
-Note that the pointer fields in the
-.PN XClassHint
-structure are initially set to NULL.
-If insufficient memory is available, 
-.PN XAllocClassHint
-returns NULL.
-To free the memory allocated to this structure,
-use
-.PN XFree .
-.LP
-The
-.PN XClassHint
-contains:
-.LP
-.sM
-.IN "XClassHint" "" "@DEF@"
-.Ds 0
-.TA .5i
-.ta .5i
-typedef struct {
-	char *res_name;
-	char *res_class;
-} XClassHint;
-.De
-.LP
-.eM
-The res_name member contains the application name, 
-and the res_class member contains the application class. 
-Note that the name set in this property may differ from the name set as WM_NAME.
-That is, WM_NAME specifies what should be displayed in the title bar and,
-therefore, can contain temporal information (for example, the name of
-a file currently in an editor's buffer).
-On the other hand, 
-the name specified as part of WM_CLASS is the formal name of the application
-that should be used when retrieving the application's resources from the 
-resource database.
-.LP
-.sp
-To set a window's WM_CLASS property, use
-.PN XSetClassHint .
-.IN "XSetClassHint" "" "@DEF@"
-.sM
-.FD 0
-XSetClassHint\^(\^\fIdisplay\fP, \fIw\fP, \fIclass_hints\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XClassHint *\fIclass_hints\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIclass_hints\fP 1i
-Specifies the
-.PN XClassHint
-structure that is to be used.
-.LP
-.eM
-The
-.PN XSetClassHint
-function sets the class hint for the specified window.
-If the strings are not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-.LP
-.PN XSetClassHint
-can generate
-.PN BadAlloc
-and
-.PN BadWindow
-errors. 
-.LP
-.sp
-To read a window's WM_CLASS property, use
-.PN XGetClassHint .
-.IN "XGetClassHint" "" "@DEF@"
-.sM
-.FD 0
-Status XGetClassHint\^(\^\fIdisplay\fP, \fIw\fP, \fIclass_hints_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP;
-.br
-      XClassHint *\fIclass_hints_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIclass_hints_return\fP 1i
-Returns the 
-.PN XClassHint
-structure.
-.LP
-.eM
-The
-.PN XGetClassHint
-function returns the class hint of the specified window to the members
-of the supplied structure.
-If the data returned by the server is in the Latin Portable Character Encoding,
-then the returned strings are in the Host Portable Character Encoding.
-Otherwise, the result is implementation-dependent.
-It returns a nonzero status on success;
-otherwise, it returns a zero status.
-To free res_name and res_class when finished with the strings,
-use
-.PN XFree
-on each individually.
-.LP
-.PN XGetClassHint
-can generate a
-.PN BadWindow 
-error.
-.NH 3
-Setting and Reading the WM_TRANSIENT_FOR Property
-.XS
-\*(SN Setting and Reading the WM_TRANSIENT_FOR Property
-.XE
-.LP
-Xlib provides functions that you can use to set and read
-the WM_TRANSIENT_FOR property for a given window.
-.LP
-.sp
-To set a window's WM_TRANSIENT_FOR property, use
-.PN XSetTransientForHint .
-.IN "XSetTransientForHint" "" "@DEF@"
-.sM
-.FD 0
-XSetTransientForHint\^(\^\fIdisplay\fP, \fIw\fP, \fIprop_window\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      Window \fIprop_window\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIprop_window\fP 1i
-Specifies the window that the WM_TRANSIENT_FOR property is to be set to.
-.LP
-.eM
-The
-.PN XSetTransientForHint
-function sets the WM_TRANSIENT_FOR property of the specified window to the 
-specified prop_window.
-.LP
-.PN XSetTransientForHint
-can generate
-.PN BadAlloc
-and
-.PN BadWindow
-errors.
-.LP
-.sp
-To read a window's WM_TRANSIENT_FOR property, use
-.PN XGetTransientForHint .
-.IN "XGetTransientForHint" "" "@DEF@"
-.sM
-.FD 0
-Status XGetTransientForHint\^(\^\fIdisplay\fP, \fIw\fP, \fIprop_window_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      Window *\fIprop_window_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIprop_window_return\fP 1i
-Returns the WM_TRANSIENT_FOR property of the specified window.
-.LP
-.eM
-The
-.PN XGetTransientForHint
-function returns the WM_TRANSIENT_FOR property for the specified window.
-It returns a nonzero status on success;
-otherwise, it returns a zero status.
-.LP
-.PN XGetTransientForHint
-can generate a
-.PN BadWindow 
-error.
-.NH 3
-Setting and Reading the WM_PROTOCOLS Property
-.XS
-\*(SN Setting and Reading the WM_PROTOCOLS Property
-.XE
-.LP
-Xlib provides functions that you can use to set and read
-the WM_PROTOCOLS property for a given window.
-.LP
-.sp
-To set a window's WM_PROTOCOLS property, use
-.PN XSetWMProtocols .
-.IN "XSetWMProtocols" "" "@DEF@"
-.sM
-.FD 0
-Status XSetWMProtocols\^(\^\fIdisplay\fP, \fIw\fP, \fIprotocols\fP, \
-\fIcount\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      Atom *\fIprotocols\fP\^;
-.br
-      int \fIcount\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIprotocols\fP 1i
-Specifies the list of protocols.
-.ds Cn protocols in the list
-.IP \fIcount\fP 1i
-Specifies the number of \*(Cn.
-.LP
-.eM
-The 
-.PN XSetWMProtocols 
-function replaces the WM_PROTOCOLS property on the specified window 
-with the list of atoms specified by the protocols argument.
-If the property does not already exist,
-.PN XSetWMProtocols
-sets the WM_PROTOCOLS property on the specified window
-to the list of atoms specified by the protocols argument.
-The property is stored with a type of ATOM and a format of 32.
-If it cannot intern the WM_PROTOCOLS atom, 
-.PN XSetWMProtocols
-returns a zero status.
-Otherwise, it returns a nonzero status.
-.LP
-.PN XSetWMProtocols
-can generate
-.PN BadAlloc
-and
-.PN BadWindow
-errors.
-.sp
-.LP
-To read a window's WM_PROTOCOLS property, use
-.PN XGetWMProtocols .
-.IN "XGetWMProtocols" "" "@DEF@"
-.sM
-.FD 0
-Status XGetWMProtocols\^(\^\fIdisplay\fP, \fIw\fP, \fIprotocols_return\fP, \
-\fIcount_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      Atom **\fIprotocols_return\fP\^;
-.br
-      int *\fIcount_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIprotocols_return\fP 1i
-Returns the list of protocols.
-.ds Cn protocols in the list
-.IP \fIcount_return\fP 1i
-Returns the number of \*(Cn.
-.LP
-.eM
-The 
-.PN XGetWMProtocols 
-function returns the list of atoms stored in the WM_PROTOCOLS property 
-on the specified window.
-These atoms describe window manager protocols in which the owner 
-of this window is willing to participate.
-If the property exists, is of type ATOM, is of format 32, 
-and the atom WM_PROTOCOLS can be interned, 
-.PN XGetWMProtocols
-sets the protocols_return argument to a list of atoms, 
-sets the count_return argument to the number of elements in the list, 
-and returns a nonzero status.
-Otherwise, it sets neither of the return arguments
-and returns a zero status.
-To release the list of atoms, use
-.PN XFree .
-.LP
-.PN XGetWMProtocols
-can generate a
-.PN BadWindow
-error.
-.NH 3
-Setting and Reading the WM_COLORMAP_WINDOWS Property
-.XS
-\*(SN Setting and Reading the WM_COLORMAP_WINDOWS Property
-.XE
-.LP
-Xlib provides functions that you can use to set and read
-the WM_COLORMAP_WINDOWS property for a given window.
-.sp
-.LP
-To set a window's WM_COLORMAP_WINDOWS property, use
-.PN XSetWMColormapWindows .
-.IN "XSetWMColormapWindows" "" "@DEF@"
-.sM
-.FD 0
-Status XSetWMColormapWindows\^(\^\fIdisplay\fP, \fIw\fP, \
-\fIcolormap_windows\fP, \fIcount\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      Window *\fIcolormap_windows\fP\^;
-.br
-      int \fIcount\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIcolormap_windows\fP 1i
-Specifies the list of windows.
-.ds Cn windows in the list
-.IP \fIcount\fP 1i
-Specifies the number of \*(Cn.
-.LP
-.eM
-The 
-.PN XSetWMColormapWindows 
-function replaces the WM_COLORMAP_WINDOWS property on the specified
-window with the list of windows specified by the colormap_windows argument.
-If the property does not already exist,
-.PN XSetWMColormapWindows
-sets the WM_COLORMAP_WINDOWS property on the specified
-window to the list of windows specified by the colormap_windows argument.
-The property is stored with a type of WINDOW and a format of 32.
-If it cannot intern the WM_COLORMAP_WINDOWS atom,
-.PN XSetWMColormapWindows
-returns a zero status.
-Otherwise, it returns a nonzero status.
-.LP
-.PN XSetWMColormapWindows
-can generate
-.PN BadAlloc
-and
-.PN BadWindow
-errors.
-.sp
-.LP
-To read a window's WM_COLORMAP_WINDOWS property, use
-.PN XGetWMColormapWindows .
-.IN "XGetWMColormapWindows" "" "@DEF@"
-.sM
-.FD 0
-Status XGetWMColormapWindows\^(\^\fIdisplay\fP, \fIw\fP, \
-\fIcolormap_windows_return\fP, \fIcount_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      Window **\fIcolormap_windows_return\fP\^;
-.br
-      int *\fIcount_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIcolormap_windows_return\fP 1i
-Returns the list of windows.
-.ds Cn windows in the list
-.IP \fIcount_return\fP 1i
-Returns the number of \*(Cn.
-.LP
-.eM
-The 
-.PN XGetWMColormapWindows 
-function returns the list of window identifiers stored 
-in the WM_COLORMAP_WINDOWS property on the specified window.
-These identifiers indicate the colormaps that the window manager
-may need to install for this window.
-If the property exists, is of type WINDOW, is of format 32, 
-and the atom WM_COLORMAP_WINDOWS can be interned, 
-.PN XGetWMColormapWindows
-sets the windows_return argument to a list of window identifiers, 
-sets the count_return argument to the number of elements in the list, 
-and returns a nonzero status.
-Otherwise, it sets neither of the return arguments
-and returns a zero status.
-To release the list of window identifiers, use
-.PN XFree . 
-.LP
-.PN XGetWMColormapWindows
-can generate a
-.PN BadWindow
-error.
-.NH 3
-Setting and Reading the WM_ICON_SIZE Property
-.XS
-\*(SN Setting and Reading the WM_ICON_SIZE Property
-.XE
-.LP
-Xlib provides functions that you can use to set and read 
-the WM_ICON_SIZE property for a given window.
-These functions use the 
-.PN XIconSize 
-.IN "XIconSize"
-structure, which is defined in the
-.hN X11/Xutil.h
-header file.
-.sp
-.LP
-To allocate an
-.PN XIconSize
-structure, use
-.PN XAllocIconSize .
-.IN "XAllocIconSize" "" "@DEF@"
-.sM
-.FD 0
-XIconSize *XAllocIconSize\^(\|)
-.FN
-.LP
-.eM
-The
-.PN XAllocIconSize 
-function allocates and returns a pointer to an
-.PN XIconSize 
-structure.
-Note that all fields in the
-.PN XIconSize
-structure are initially set to zero.
-If insufficient memory is available, 
-.PN XAllocIconSize
-returns NULL.
-To free the memory allocated to this structure,
-use
-.PN XFree .
-.LP
-The
-.PN XIconSize
-structure contains:
-.LP
-.sM
-.IN "XIconSize" "" "@DEF@"
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	int min_width, min_height;
-	int max_width, max_height;
-	int width_inc, height_inc;
-} XIconSize;
-.De
-.LP
-.eM
-The width_inc and height_inc members define an arithmetic progression of
-sizes (minimum to maximum) that represent the supported icon sizes.
-.LP
-.sp
-To set a window's WM_ICON_SIZE property, use
-.PN XSetIconSizes .
-.IN "XSetIconSizes" "" "@DEF@"
-.sM
-.FD 0
-XSetIconSizes\^(\^\fIdisplay\fP, \fIw\fP, \fIsize_list\fP, \fIcount\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XIconSize *\fIsize_list\fP\^;
-.br
-      int \fIcount\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIsize_list\fP 1i
-Specifies the size list.
-.IP \fIcount\fP 1i
-Specifies the number of items in the size list.
-.LP
-.eM
-The
-.PN XSetIconSizes
-function is used only by window managers to set the supported icon sizes.
-.LP
-.PN XSetIconSizes
-can generate
-.PN BadAlloc
-and
-.PN BadWindow 
-errors.
-.LP
-.sp
-To read a window's WM_ICON_SIZE property, use
-.PN XGetIconSizes .
-.IN "XGetIconSizes" "" "@DEF@"
-.sM
-.FD 0
-Status XGetIconSizes\^(\^\fIdisplay\fP, \fIw\fP, \fIsize_list_return\fP, \fIcount_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XIconSize **\fIsize_list_return\fP\^;
-.br
-      int *\fIcount_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIsize_list_return\fP 1i
-Returns the size list.
-.IP \fIcount_return\fP 1i
-Returns the number of items in the size list.
-.LP
-.eM
-The
-.PN XGetIconSizes
-function returns zero if a window manager has not set icon sizes;
-otherwise, it returns nonzero.
-.PN XGetIconSizes
-should be called by an application that
-wants to find out what icon sizes would be most appreciated by the
-window manager under which the application is running.
-The application
-should then use
-.PN XSetWMHints
-to supply the window manager with an icon pixmap or window in one of the
-supported sizes.
-To free the data allocated in size_list_return, use
-.PN XFree .
-.LP
-.PN XGetIconSizes
-can generate a
-.PN BadWindow 
-error.
-.NH 3
-Using Window Manager Convenience Functions
-.XS
-\*(SN Using Window Manager Convenience Functions
-.XE
-.LP
-The 
-.PN XmbSetWMProperties
-function stores the standard set of window manager properties,
-with text properties in standard encodings
-for internationalized text communication.
-The standard window manager properties for a given window are
-WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS,
-WM_COMMAND, WM_CLIENT_MACHINE, and WM_LOCALE_NAME.
-.IN "XmbSetWMProperties" "" "@DEF@"
-.sM
-.FD 0
-void XmbSetWMProperties\^(\^\fIdisplay\fP\^, \fIw\fP\^, \fIwindow_name\fP\^, \fIicon_name\fP\^, \fIargv\fP\^, \fIargc\fP\^,
-.br
-                      \fInormal_hints\fP\^, \fIwm_hints\fP\^, \fIclass_hints\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      char *\fIwindow_name\fP\^;
-.br
-      char *\fIicon_name\fP\^;
-.br
-      char *\fIargv\fP\^[];
-.br
-      int \fIargc\fP\^;
-.br
-      XSizeHints *\fInormal_hints\fP\^;
-.br
-      XWMHints *\fIwm_hints\fP\^;
-.br
-      XClassHint *\fIclass_hints\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIwindow_name\fP 1i
-Specifies the window name,
-which should be a null-terminated string.
-.IP \fIicon_name\fP 1i
-Specifies the icon name,
-which should be a null-terminated string.
-.IP \fIargv\fP 1i
-Specifies the application's argument list.
-.IP \fIargc\fP 1i
-Specifies the number of arguments.
-.IP \fIhints\fP 1i
-Specifies the size hints for the window in its normal state.
-.IP \fIwm_hints\fP 1i
-Specifies the
-.PN XWMHints
-structure to be used.
-.IP \fIclass_hints\fP 1i
-Specifies the
-.PN XClassHint
-structure to be used.
-.LP
-.eM
-The
-.PN XmbSetWMProperties
-convenience function provides a simple programming interface 
-for setting those essential window properties that are used 
-for communicating with other clients
-(particularly window and session managers).
-.LP
-If the window_name argument is non-NULL,
-.PN XmbSetWMProperties
-sets the WM_NAME property.
-If the icon_name argument is non-NULL,
-.PN XmbSetWMProperties
-sets the WM_ICON_NAME property.
-The window_name and icon_name arguments are null-terminated strings
-in the encoding of the current locale.
-If the arguments can be fully converted to the STRING encoding,
-the properties are created with type ``STRING''; 
-otherwise, the arguments are converted to Compound Text, 
-and the properties are created with type ``COMPOUND_TEXT''.
-.LP
-If the normal_hints argument is non-NULL,
-.PN XmbSetWMProperties
-calls
-.PN XSetWMNormalHints ,
-which sets the WM_NORMAL_HINTS property (see section 14.1.7).
-If the wm_hints argument is non-NULL, 
-.PN XmbSetWMProperties
-calls
-.PN XSetWMHints ,
-which sets the WM_HINTS property (see section 14.1.6).
-.LP
-If the argv argument is non-NULL,
-.PN XmbSetWMProperties
-sets the WM_COMMAND property from argv and argc.
-An argc of zero indicates a zero-length command.
-.LP
-The hostname of the machine is stored using 
-.PN XSetWMClientMachine 
-(see section 14.2.2).
-.LP
-If the class_hints argument is non-NULL,
-.PN XmbSetWMProperties
-sets the WM_CLASS property.
-If the res_name member in the 
-.PN XClassHint
-structure is set to the NULL pointer and the RESOURCE_NAME
-environment variable is set,
-the value of the environment variable is substituted for res_name.
-If the res_name member is NULL,
-the environment variable is not set, and argv and argv[0] are set,
-then the value of argv[0], stripped of any directory prefixes,
-is substituted for res_name.
-.LP
-It is assumed that the supplied class_hints.res_name and argv,
-the RESOURCE_NAME environment variable, and the hostname of the machine
-are in the encoding of the locale announced for the LC_CTYPE category
-(on POSIX-compliant systems, the LC_CTYPE, else LANG environment variable).
-The corresponding WM_CLASS, WM_COMMAND, and WM_CLIENT_MACHINE properties
-are typed according to the local host locale announcer.
-No encoding conversion is performed prior to storage in the properties.
-.LP
-For clients that need to process the property text in a locale,
-.PN XmbSetWMProperties
-sets the WM_LOCALE_NAME property to be the name of the current locale.
-The name is assumed to be in the Host Portable Character Encoding
-and is converted to STRING for storage in the property.
-.LP
-.PN XmbSetWMProperties
-can generate
-.PN BadAlloc
-and
-.PN BadWindow
-errors.
-.sp
-.LP
-To set a window's standard window manager properties
-with strings in client-specified encodings, use
-.PN XSetWMProperties .
-The standard window manager properties for a given window are
-WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS,
-WM_COMMAND, and WM_CLIENT_MACHINE.
-.IN "XSetWMProperties" "" "@DEF@"
-.sM
-.FD 0
-void XSetWMProperties\^(\^\fIdisplay\fP, \fIw\fP, \fIwindow_name\fP, \
-\fIicon_name\fP, \fIargv\fP, \fIargc\fP, \fInormal_hints\fP, \fIwm_hints\fP, \
-\fIclass_hints\fP\^)
-.br
-      Display *\fIdisplay\fP\^; 
-.br
-      Window \fIw\fP\^;
-.br
-      XTextProperty *\fIwindow_name\fP\^;
-.br
-      XTextProperty *\fIicon_name\fP\^;
-.br
-      char **\fIargv\fP\^;
-.br
-      int \fIargc\fP\^;
-.br
-      XSizeHints *\fInormal_hints\fP\^;
-.br
-      XWMHints *\fIwm_hints\fP\^;
-.br
-      XClassHint *\fIclass_hints\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIwindow_name\fP 1i
-Specifies the window name,
-which should be a null-terminated string.
-.IP \fIicon_name\fP 1i
-Specifies the icon name,
-which should be a null-terminated string.
-.IP \fIargv\fP 1i
-Specifies the application's argument list.
-.IP \fIargc\fP 1i
-Specifies the number of arguments.
-.IP \fInormal_hints\fP 1i
-Specifies the size hints for the window in its normal state.
-.IP \fIwm_hints\fP 1i
-Specifies the
-.PN XWMHints
-structure to be used.
-.IP \fIclass_hints\fP 1i
-Specifies the
-.PN XClassHint
-structure to be used.
-.LP
-.eM
-The 
-.PN XSetWMProperties 
-convenience function provides a single programming interface 
-for setting those essential window properties that are used 
-for communicating with other clients (particularly window and session
-managers).
-.LP
-If the window_name argument is non-NULL, 
-.PN XSetWMProperties
-calls
-.PN XSetWMName ,
-which, in turn, sets the WM_NAME property (see section 14.1.4).
-If the icon_name argument is non-NULL,
-.PN XSetWMProperties
-calls
-.PN XSetWMIconName ,
-which sets the WM_ICON_NAME property (see section 14.1.5).
-If the argv argument is non-NULL, 
-.PN XSetWMProperties
-calls
-.PN XSetCommand ,
-which sets the WM_COMMAND property (see section 14.2.1).
-Note that an argc of zero is allowed to indicate a zero-length command.
-Note also that the hostname of this machine is stored using
-.PN XSetWMClientMachine 
-(see section 14.2.2).
-.LP
-If the normal_hints argument is non-NULL, 
-.PN XSetWMProperties
-calls
-.PN XSetWMNormalHints ,
-which sets the WM_NORMAL_HINTS property (see section 14.1.7).
-If the wm_hints argument is non-NULL, 
-.PN XSetWMProperties
-calls
-.PN XSetWMHints ,
-which sets the WM_HINTS property (see section 14.1.6).
-.LP
-If the class_hints argument is non-NULL, 
-.PN XSetWMProperties
-calls
-.PN XSetClassHint ,
-which sets the WM_CLASS property (see section 14.1.8).
-If the res_name member in the
-.PN XClassHint
-structure is set to the NULL pointer and the RESOURCE_NAME environment 
-variable is set, 
-then the value of the environment variable is substituted for res_name.
-If the res_name member is NULL, 
-the environment variable is not set, 
-and argv and argv[0] are set, 
-then the value of argv[0], stripped of
-any directory prefixes, is substituted for res_name.
-.LP
-.PN XSetWMProperties
-can generate
-.PN BadAlloc
-and
-.PN BadWindow
-errors.
-.NH 2
-Client to Session Manager Communication
-.XS
-\*(SN Client to Session Manager Communication
-.XE
-.LP
-This section discusses how to:
-.IP \(bu 5
-Set and read the WM_COMMAND property
-.IP \(bu 5
-Set and read the WM_CLIENT_MACHINE property
-.NH 3
-Setting and Reading the WM_COMMAND Property
-.XS
-\*(SN Setting and Reading the WM_COMMAND Property
-.XE
-.LP
-Xlib provides functions that you can use to set and read
-the WM_COMMAND property for a given window.
-.sp
-.LP
-To set a window's WM_COMMAND property, use
-.PN XSetCommand .
-.IN "XSetCommand" "" "@DEF@"
-.sM
-.FD 0
-XSetCommand\^(\^\fIdisplay\fP, \fIw\fP, \fIargv\fP, \fIargc\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      char **\fIargv\fP\^;
-.br
-      int \fIargc\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIargv\fP 1i
-Specifies the application's argument list.
-.IP \fIargc\fP 1i
-Specifies the number of arguments.
-.LP
-.eM
-The
-.PN XSetCommand
-function sets the command and arguments used to invoke the
-application.
-(Typically, argv is the argv array of your main program.)
-If the strings are not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-.LP
-.PN XSetCommand
-can generate
-.PN BadAlloc
-and
-.PN BadWindow 
-errors.
-.sp
-.LP
-To read a window's WM_COMMAND property, use
-.PN XGetCommand .
-.IN "XGetCommand" "" "@DEF@"
-.sM
-.FD 0
-Status XGetCommand\^(\^\fIdisplay\fP, \fIw\fP, \fIargv_return\fP, \
-\fIargc_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      char ***\fIargv_return\fP\^;
-.br
-      int *\fIargc_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIargv_return\fP 1i
-Returns the application's argument list.
-.IP \fIargc_return\fP 1i
-Returns the number of arguments returned.
-.LP
-.eM
-The 
-.PN XGetCommand 
-function reads the WM_COMMAND property from the specified window 
-and returns a string list.
-If the WM_COMMAND property exists, 
-it is of type STRING and format 8.
-If sufficient memory can be allocated to contain the string list, 
-.PN XGetCommand
-fills in the argv_return and argc_return arguments
-and returns a nonzero status.
-Otherwise, it returns a zero status.
-If the data returned by the server is in the Latin Portable Character Encoding,
-then the returned strings are in the Host Portable Character Encoding.
-Otherwise, the result is implementation-dependent.
-To free the memory allocated to the string list, use
-.PN XFreeStringList .
-.NH 3
-Setting and Reading the WM_CLIENT_MACHINE Property
-.XS
-\*(SN Setting and Reading the WM_CLIENT_MACHINE Property
-.XE
-.LP
-Xlib provides functions that you can use to set and read 
-the WM_CLIENT_MACHINE property for a given window.
-.sp
-.LP
-To set a window's WM_CLIENT_MACHINE property, use
-.PN XSetWMClientMachine .
-.IN "XSetWMClientMachine" "" "@DEF@"
-.sM
-.FD 0
-void XSetWMClientMachine\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XTextProperty *\fItext_prop\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fItext_prop\fP 1i
-Specifies the
-.PN XTextProperty
-structure to be used.
-.LP
-.eM
-The
-.PN XSetWMClientMachine
-convenience function calls
-.PN XSetTextProperty
-to set the WM_CLIENT_MACHINE property.
-.sp
-.LP
-To read a window's WM_CLIENT_MACHINE property, use
-.PN XGetWMClientMachine .
-.IN "XGetWMClientMachine" "" "@DEF@"
-.sM
-.FD 0
-Status XGetWMClientMachine\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XTextProperty *\fItext_prop_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fItext_prop_return\fP 1i
-Returns the
-.PN XTextProperty
-structure.
-.LP
-.eM
-The
-.PN XGetWMClientMachine
-convenience function performs an 
-.PN XGetTextProperty 
-on the WM_CLIENT_MACHINE property.
-It returns a nonzero status on success;
-otherwise, it returns a zero status.
-.NH 2
-Standard Colormaps
-.XS
-\*(SN Standard Colormaps 
-.XE
-.LP
-Applications with color palettes, smooth-shaded drawings, or digitized
-images demand large numbers of colors.  
-In addition, these applications often require an efficient mapping 
-from color triples to pixel values that display the appropriate colors.
-.LP
-As an example, consider a three-dimensional display program that wants 
-to draw a smoothly shaded sphere.  
-At each pixel in the image of the sphere, 
-the program computes the intensity and color of light
-reflected back to the viewer.  
-The result of each computation is a triple of red, green, and blue (RGB)
-coefficients in the range 0.0 to 1.0.  
-To draw the sphere, the program needs a colormap that provides a
-large range of uniformly distributed colors.  
-The colormap should be arranged so that the program can
-convert its RGB triples into pixel values very quickly,
-because drawing the entire sphere requires many such
-conversions.
-.LP
-On many current workstations,
-the display is limited to 256 or fewer colors.  
-Applications must allocate colors carefully, 
-not only to make sure they cover the entire range they need 
-but also to make use of as many of the available colors as possible.
-On a typical X display, 
-many applications are active at once.
-Most workstations have only one hardware look-up table for colors,
-so only one application colormap can be installed at a given time.
-The application using the installed colormap is displayed correctly, 
-and the other applications go technicolor and are
-displayed with false colors.
-.LP
-As another example, consider a user who is running an 
-image processing program to display earth-resources data.  
-The image processing program needs a colormap set up with 8 reds, 
-8 greens, and 4 blues, for a total of 256 colors.
-Because some colors are already in use in the default colormap, 
-the image processing program allocates and installs a new colormap.
-.LP
-The user decides to alter some of the colors in the image
-by invoking a color palette program to mix and choose colors.
-The color palette program also needs a
-colormap with eight reds, eight greens, and four blues, so just like
-the image processing program, it must allocate and
-install a new colormap.
-.LP
-Because only one colormap can be installed at a time,
-the color palette may be displayed incorrectly
-whenever the image processing program is active.
-Conversely, whenever the palette program is active, 
-the image may be displayed incorrectly.  
-The user can never match or compare colors in the palette and image.
-Contention for colormap resources can be reduced if applications
-with similar color needs share colormaps.
-.LP
-The image processing program and the color palette program 
-could share the same colormap if there existed a convention that described
-how the colormap was set up.  
-Whenever either program was active, 
-both would be displayed correctly.
-.LP
-The standard colormap properties define a set of commonly used
-colormaps.  
-Applications that share these colormaps and conventions display 
-true colors more often and provide a better interface to the user.
-.LP
-Standard colormaps allow applications to share commonly used color
-resources.  
-This allows many applications to be displayed in true colors
-simultaneously, even when each application needs an entirely filled
-colormap.
-.LP
-Several standard colormaps are described in this section.
-Usually, a window manager creates these colormaps.
-Applications should use the standard colormaps if they already exist.
-.sp
-.LP
-To allocate an
-.PN XStandardColormap
-structure, use
-.PN XAllocStandardColormap .
-.IN "XAllocStandardColormap" "" "@DEF@"
-.sM
-.FD 0
-XStandardColormap *XAllocStandardColormap\^(\|)
-.FN
-.LP
-.eM
-The
-.PN XAllocStandardColormap
-function allocates and returns a pointer to an
-.PN XStandardColormap
-structure.
-Note that all fields in the
-.PN XStandardColormap
-structure are initially set to zero.
-If insufficient memory is available, 
-.PN XAllocStandardColormap
-returns NULL.
-To free the memory allocated to this structure,
-use
-.PN XFree .
-.LP
-The 
-.PN XStandardColormap 
-structure contains:
-.LP
-.sM
-/* Hints */
-.TS
-lw(.5i) lw(2i) lw(1i).
-T{
-#define
-T}	T{
-.PN ReleaseByFreeingColormap
-T}	T{
-( (XID) 1L)
-T}
-.TE
-/* Values */
-.IN "XStandardColormap" "" "@DEF@"
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	Colormap colormap;
-	unsigned long red_max;
-	unsigned long red_mult;
-	unsigned long green_max;
-	unsigned long green_mult;
-	unsigned long blue_max;
-	unsigned long blue_mult;
-	unsigned long base_pixel;
-	VisualID visualid;
-	XID killid;
-} XStandardColormap;
-.De
-.LP
-.eM
-The colormap member is the colormap created by the
-.PN XCreateColormap
-function.
-The red_max, green_max, and blue_max members give the maximum
-red, green, and blue values, respectively.  
-Each color coefficient ranges from zero to its max, inclusive.  
-For example,
-a common colormap allocation is 3/3/2 (3 planes for red, 3
-planes for green, and 2 planes for blue).  
-This colormap would have red_max = 7, green_max = 7, 
-and blue_max = 3.  
-An alternate allocation that uses only 216 colors is red_max = 5, 
-green_max = 5, and blue_max = 5.
-.LP
-The red_mult, green_mult, and blue_mult members give the
-scale factors used to compose a full pixel value. 
-(See the discussion of the base_pixel members for further information.)
-For a 3/3/2 allocation, red_mult might be 32,
-green_mult might be 4, and blue_mult might be 1.  
-For a 6-colors-each allocation, red_mult might be 36, 
-green_mult might be 6, and blue_mult might be 1.
-.LP
-The base_pixel member gives the base pixel value used to
-compose a full pixel value.  
-Usually, the base_pixel is obtained from a call to the 
-.PN XAllocColorPlanes
-function.  
-Given integer red, green, and blue coefficients in their appropriate 
-ranges, one then can compute a corresponding pixel value by
-using the following expression:
-.LP
-.Ds
-.TA .5i 1.5i
-.ta .5i 1.5i
-(r * red_mult + g * green_mult + b * blue_mult + base_pixel) & 0xFFFFFFFF
-.De
-.LP
-For 
-.PN GrayScale
-colormaps, 
-only the colormap, red_max, red_mult, 
-and base_pixel members are defined. 
-The other members are ignored.  
-To compute a 
-.PN GrayScale 
-pixel value, use the following expression:
-.LP
-.Ds
-.TA .5i 1.5i
-.ta .5i 1.5i
-(gray * red_mult + base_pixel) & 0xFFFFFFFF
-.De
-.LP
-Negative multipliers can be represented by converting the 2's
-complement representation of the multiplier into an unsigned long and
-storing the result in the appropriate _mult field.
-The step of masking by 0xFFFFFFFF effectively converts the resulting
-positive multiplier into a negative one.
-The masking step will take place automatically on many machine architectures,
-depending on the size of the integer type used to do the computation.
-.LP
-The visualid member gives the ID number of the visual from which the
-colormap was created.
-The killid member gives a resource ID that indicates whether
-the cells held by this standard colormap are to be released 
-by freeing the colormap ID or by calling the
-.PN XKillClient
-function on the indicated resource.
-(Note that this method is necessary for allocating out of an existing colormap.)
-.LP
-The properties containing the 
-.PN XStandardColormap 
-information have 
-the type RGB_COLOR_MAP.
-.LP
-The remainder of this section discusses standard colormap properties and atoms
-as well as how to manipulate standard colormaps.
-.NH 3
-Standard Colormap Properties and Atoms
-.XS
-\*(SN Standard Colormap Properties and Atoms 
-.XE
-.LP
-.IN "Standard Colormaps"
-.IN "Colormaps" "standard"
-Several standard colormaps are available.  
-Each standard colormap is defined by a property, 
-and each such property is identified by an atom.  
-The following list names the atoms and describes the colormap
-associated with each one.
-The
-.hN X11/Xatom.h
-header file contains the definitions for each of the following atoms,
-which are prefixed with XA_.
-.IP RGB_DEFAULT_MAP 5
-This atom names a property.
-The value of the property is an array of
-.PN XStandardColormap
-structures.
-Each entry in the array describes an RGB subset of the default color
-map for the Visual specified by visual_id.
-.IP
-Some applications only need a few RGB colors and
-may be able to allocate them from the system default colormap.
-This is the ideal situation because the fewer colormaps that are
-active in the system the more applications are displayed
-with correct colors at all times.
-.IP
-A typical allocation for the RGB_DEFAULT_MAP on 8-plane displays
-is 6 reds, 6 greens, and 6 blues.  
-This gives 216 uniformly distributed colors 
-(6 intensities of 36 different hues) and still leaves 40 elements 
-of a 256-element colormap available for special-purpose colors 
-for text, borders, and so on.
-.IP RGB_BEST_MAP 5
-.br
-This atom names a property.
-The value of the property is an 
-.PN XStandardColormap .
-.IP 
-The property defines the best RGB colormap available on
-the screen.
-(Of course, this is a subjective evaluation.)
-Many image processing and three-dimensional applications need to
-use all available colormap cells and to distribute as many
-perceptually distinct colors as possible over those cells.
-This implies that there may be more green values available than
-red, as well as more green or red than blue.
-.IP
-For an 8-plane 
-.PN PseudoColor 
-visual, 
-RGB_BEST_MAP is likely to be a 3/3/2 allocation.  
-For a 24-plane 
-.PN DirectColor 
-visual, 
-RGB_BEST_MAP is normally an 8/8/8 allocation.  
-.IP RGB_RED_MAP 5
-.br
-.ns
-.IP RGB_GREEN_MAP 5
-.br
-.ns
-.IP RGB_BLUE_MAP 5
-These atoms name properties.
-The value of each property is an
-.PN XStandardColormap . 
-.IP
-The properties define all-red, all-green, and all-blue
-colormaps, respectively.  
-These maps are used by applications that want to make color-separated 
-images.  
-For example, a user might generate a full-color image 
-on an 8-plane display both by rendering an image three times 
-(once with high color resolution in red, once with green, 
-and once with blue) and by multiply exposing a single frame in a camera.
-.IP RGB_GRAY_MAP 5
-This atom names a property.
-The value of the property is an 
-.PN XStandardColormap .
-.IP
-The property describes the best 
-.PN GrayScale 
-colormap available on the screen.  
-As previously mentioned, 
-only the colormap, red_max, red_mult, and base_pixel members of the
-.PN XStandardColormap 
-structure are used for 
-.PN GrayScale 
-colormaps.
-.NH 3
-Setting and Obtaining Standard Colormaps
-.XS
-\*(SN Setting and Obtaining Standard Colormaps
-.XE
-.LP
-Xlib provides functions that you can use to set and obtain an
-.PN XStandardColormap
-structure.
-.sp
-.LP
-To set an
-.PN XStandardColormap
-structure, use
-.PN XSetRGBColormaps .
-.IN "XSetRGBColormaps" "" "@DEF@"
-.sM
-.FD 0
-void XSetRGBColormaps\^(\^\fIdisplay\fP, \fIw\fP, \fIstd_colormap\fP, \
-\fIcount\fP, \fIproperty\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XStandardColormap *\fIstd_colormap\fP\^;
-.br
-      int \fIcount\fP\^;
-.br
-      Atom \fIproperty\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIstd_colormap\fP 1i
-Specifies the
-.PN XStandardColormap
-structure to be used.
-.ds Cn colormaps
-.IP \fIcount\fP 1i
-Specifies the number of \*(Cn.
-.IP \fIproperty\fP 1i
-Specifies the property name.
-.LP
-.eM
-The 
-.PN XSetRGBColormaps 
-function replaces the RGB colormap definition in the specified property 
-on the named window.
-If the property does not already exist,
-.PN XSetRGBColormaps
-sets the RGB colormap definition in the specified property
-on the named window.
-The property is stored with a type of RGB_COLOR_MAP and a format of 32.
-Note that it is the caller's responsibility to honor the ICCCM
-restriction that only RGB_DEFAULT_MAP contain more than one definition.
-.LP
-The
-.PN XSetRGBColormaps
-function usually is only used by window or session managers.
-To create a standard colormap, 
-follow this procedure:
-.IP 1. 5
-Open a new connection to the same server.
-.IP 2. 5
-Grab the server.
-.IP 3. 5
-See if the property is on the property list of the root window for the screen.
-.IP 4. 5
-If the desired property is not present:
-.RS
-.IP \(bu 5
-Create a colormap (unless you are using the default colormap of the screen).
-.IP \(bu 5
-Determine the color characteristics of the visual.
-.IP \(bu 5
-Allocate cells in the colormap (or create it with
-.PN AllocAll ).
-.IP \(bu 5
-Call 
-.PN XStoreColors
-to store appropriate color values in the colormap.
-.IP \(bu 5
-Fill in the descriptive members in the 
-.PN XStandardColormap
-structure.
-.IP \(bu 5
-Attach the property to the root window.
-.IP \(bu 5
-Use
-.PN XSetCloseDownMode
-to make the resource permanent.
-.RE
-.IP 5. 5
-Ungrab the server.
-.LP
-.PN XSetRGBColormaps
-can generate
-.PN BadAlloc ,
-.PN BadAtom ,
-and
-.PN BadWindow
-errors.
-.sp
-.LP
-To obtain the 
-.PN XStandardColormap 
-structure associated with the specified property, use
-.PN XGetRGBColormaps .
-.IN "XGetRGBColormaps" "" "@DEF@"
-.sM
-.FD 0
-Status XGetRGBColormaps\^(\^\fIdisplay\fP, \fIw\fP, \fIstd_colormap_return\fP, \
-\fIcount_return\fP, \fIproperty\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Window \fIw\fP\^;
-.br
-      XStandardColormap **\fIstd_colormap_return\fP\^;
-.br
-      int *\fIcount_return\fP\^;
-.br
-      Atom \fIproperty\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIw\fP 1i
-Specifies the window.
-.IP \fIstd_colormap_return\fP 1i
-Returns the
-.PN XStandardColormap
-structure.
-.ds Cn colormaps
-.IP \fIcount_return\fP 1i
-Returns the number of \*(Cn.
-.IP \fIproperty\fP 1i
-Specifies the property name.
-.LP
-.eM
-The 
-.PN XGetRGBColormaps
-function returns the RGB colormap definitions stored 
-in the specified property on the named window.
-If the property exists, is of type RGB_COLOR_MAP, is of format 32, 
-and is long enough to contain a colormap definition,
-.PN XGetRGBColormaps
-allocates and fills in space for the returned colormaps
-and returns a nonzero status.
-If the visualid is not present, 
-.PN XGetRGBColormaps 
-assumes the default visual for the screen on which the window is located; 
-if the killid is not present, 
-.PN None
-is assumed, which indicates that the resources cannot be released.
-Otherwise, 
-none of the fields are set, and 
-.PN XGetRGBColormaps
-returns a zero status.
-Note that it is the caller's responsibility to honor the ICCCM
-restriction that only RGB_DEFAULT_MAP contain more than one definition.
-.LP
-.PN XGetRGBColormaps
-can generate
-.PN BadAtom
-and
-.PN BadWindow
-errors.
-.bp
diff --git a/libX11/specs/libX11/CH14.xml b/libX11/specs/libX11/CH14.xml
new file mode 100644
index 000000000..dd301bf9f
--- /dev/null
+++ b/libX11/specs/libX11/CH14.xml
@@ -0,0 +1,5190 @@
+<chapter id="inter_client_communication_functions">

+<title>Inter-Client Communication Functions</title>

+<para>

+The Inter-Client Communication Conventions Manual, hereafter referred to as the <acronym>ICCCM</acronym>,

+details the X Consortium approved conventions that govern inter-client communications. These

+conventions ensure peer-to-peer client cooperation in the use of selections, cut buffers, and shared

+resources as well as client cooperation with window and session managers. For further informa-

+tion, see the Inter-Client Communication Conventions Manual.

+</para>

+<para>

+Xlib provides a number of standard properties and programming interfaces that are <acronym>ICCCM</acronym> com-

+pliant. The predefined atoms for some of these properties are defined in the &lt;X11/Xatom.h&gt;

+header file, where to avoid name conflicts with user symbols their #define name has an XA_ pre-

+fix. For further information about atoms and properties, see section 4.3.

+</para>

+<para>

+Xlib’s selection and cut buffer mechanisms provide the primary programming interfaces by which

+peer client applications communicate with each other (see sections 4.5 and 16.6). The functions

+discussed in this chapter provide the primary programming interfaces by which client applications

+communicate with their window and session managers as well as share standard colormaps.

+</para>

+<para>

+The standard properties that are of special interest for communicating with window and session

+managers are:

+</para>

+

+<informaltable>

+  <tgroup cols='4' align='center'>

+  <colspec colname='c1'/>

+  <colspec colname='c2'/>

+  <colspec colname='c3'/>

+  <colspec colname='c4'/>

+  <thead>

+    <row>

+      <entry>Name</entry>

+      <entry>Type</entry>

+      <entry>Format</entry>

+      <entry>Description</entry>

+    </row>

+  </thead>

+  <tbody>

+    <row>

+      <entry>WM_CLASS</entry>

+      <entry>STRING</entry>

+      <entry>8</entry>

+      <entry>Set by application programs to allow

+      window and session managers to

+      obtain the application’s resources

+      from the resource database.

+      </entry>

+    </row>

+    <row>

+      <entry>WM_CLIENT_MACHINE</entry>

+      <entry>TEXT</entry>

+      <entry></entry>

+      <entry>The string name of the machine on

+      which the client application is run-

+      ning.

+      </entry>

+    </row>

+    <row>

+      <entry>WM_COLORMAP_WINDOWS</entry>

+      <entry>WINDOWS</entry>

+      <entry>32</entry>

+      <entry>The list of window IDs that may

+      need a different colormap from that

+      of their top-level window.

+      </entry>

+    </row>

+    <row>

+      <entry>WM_COMMAND</entry>

+      <entry>TEXT</entry>

+      <entry></entry>

+      <entry>The command and arguments, null-

+      separated, used to invoke the application.

+      </entry>

+    </row>

+    <row>

+      <entry>WM_HINTS</entry>

+      <entry>WM_HINTS</entry>

+      <entry>32</entry>

+      <entry>Additional hints set by the client for

+      use by the window manager. The C

+      type of this property is XWMHints.

+      </entry> 

+    </row>

+    <row>

+      <entry>WM_ICON_NAME</entry>

+      <entry>TEXT</entry>

+      <entry></entry>

+      <entry>The name to be used in an icon.</entry>

+    </row>

+    <row>

+      <entry>WM_ICON_SIZE</entry>

+      <entry>WM_ICON_SIZE</entry>

+      <entry>32</entry>

+      <entry>The window manager may set this

+      property on the root window to

+      specify the icon sizes it supports.

+      The C type of this property is

+      XIconSize.

+      </entry>

+    </row>

+    <row>

+      <entry>WM_NAME</entry>

+      <entry>TEXT</entry>

+      <entry></entry>

+      <entry>The name of the application.</entry>

+    </row>

+    <row>

+      <entry>WM_NORMAL_HINTS</entry>

+      <entry>WM_NORMAL_HINTS</entry>

+      <entry>32</entry>

+      <entry>Size hints for a window in its

+      normal state. The C type of this

+      property is XSizeHints.

+      </entry>

+    </row>

+    <row>

+      <entry>WM_PROTOCOLS</entry>

+      <entry>ATOM</entry>

+      <entry>32</entry>

+      <entry>List of atoms that identify the 

+      communications protocols between the

+      client and window manager in

+      which the client is willing to participate.

+      </entry>

+    </row>

+    <row>

+      <entry>WM_STATE</entry>

+      <entry>WM_STATE</entry>

+      <entry>32</entry>

+      <entry>Intended for communication

+      between window and session man-

+      agers only.

+      </entry>

+    </row>

+    <row>

+      <entry>WM_TRANSIENT_FOR</entry>

+      <entry>WINDOW</entry>

+      <entry>32</entry>

+      <entry>Set by application programs to 

+      indicate to the window manager that a

+      transient top-level window, such as a

+      dialog box.

+      </entry>

+    </row>

+  </tbody>

+  </tgroup>

+</informaltable>

+

+<para>

+The remainder of this chapter discusses:

+</para>

+

+<itemizedlist>

+  <listitem><para>Client to window manager communication</para></listitem>

+  <listitem><para>Client to session manager communication</para></listitem>

+  <listitem><para>Standard colormaps</para></listitem>

+</itemizedlist>

+

+<sect1 id="Client_to_Window_Manager_Communication">

+<title>Client to Window Manager Communication</title>

+<!-- .XS -->

+<!-- (SN Client to Window Manager Communication -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+This section discusses how to:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Manipulate top-level windows

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Convert string lists

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Set and read text properties

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Set and read the WM_NAME property

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Set and read the WM_ICON_NAME property

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Set and read the WM_HINTS property

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Set and read the WM_NORMAL_HINTS property

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Set and read the WM_CLASS property

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Set and read the WM_TRANSIENT_FOR property

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Set and read the WM_PROTOCOLS property

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Set and read the WM_COLORMAP_WINDOWS property

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Set and read the WM_ICON_SIZE property

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Use window manager convenience functions

+    </para>

+  </listitem>

+</itemizedlist>

+<sect2 id="Manipulating_Top_Level_Windows">

+<title>Manipulating Top-Level Windows</title>

+<!-- .XS -->

+<!-- (SN Manipulating Top-Level Windows -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to change the visibility or size

+of top-level windows (that is, those that were created as children 

+of the root window).

+Note that the subwindows that you create are ignored by window managers.

+Therefore,

+you should use the basic window functions described in chapter 3

+to manipulate your application's subwindows.

+</para>

+<para>

+<!-- .LP -->

+To request that a top-level window be iconified, use

+<function>XIconifyWindow</function>.

+<indexterm significance="preferred"><primary>XIconifyWindow</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XIconifyWindow</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>int<parameter> screen_number</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate screen number on the host server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XIconifyWindow </function>

+function sends a WM_CHANGE_STATE 

+<function>ClientMessage </function>

+event with a format of 32 and a first data element of 

+<function>IconicState </function>

+(as described in section 4.1.4 of the 

+<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>)

+and a window of w

+to the root window of the specified screen

+with an event mask set to

+<function>SubstructureNotifyMask |</function>

+<function>SubstructureRedirectMask</function>.

+Window managers may elect to receive this message and

+if the window is in its normal state, 

+may treat it as a request to change the window's state from normal to iconic.

+If the WM_CHANGE_STATE property cannot be interned, 

+<function>XIconifyWindow</function>

+does not send a message and returns a zero status.

+It returns a nonzero status if the client message is sent successfully;

+otherwise, it returns a zero status.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To request that a top-level window be withdrawn, use

+<function>XWithdrawWindow</function>.

+<indexterm significance="preferred"><primary>XWithdrawWindow</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XWithdrawWindow</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>int<parameter> screen_number</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate screen number on the host server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XWithdrawWindow </function>

+function unmaps the specified window 

+and sends a synthetic 

+<function>UnmapNotify </function>

+event to the root window of the specified screen.

+Window managers may elect to receive this message 

+and may treat it as a request to change the window's state to withdrawn.

+When a window is in the withdrawn state, 

+neither its normal nor its iconic representations is visible.

+It returns a nonzero status if the 

+<function>UnmapNotify </function>

+event is successfully sent; 

+otherwise, it returns a zero status.

+</para>

+<para>

+<!-- .LP -->

+<function>XWithdrawWindow</function>

+can generate a

+<function>BadWindow</function>

+error.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To request that a top-level window be reconfigured, use

+<function>XReconfigureWMWindow</function>.

+<indexterm significance="preferred"><primary>XReconfigureWMWindow</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XReconfigureWMWindow</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>int<parameter> screen_number</parameter></paramdef>

+  <paramdef>unsignedint<parameter> value_mask</parameter></paramdef>

+  <paramdef>XWindowChanges<parameter> *values</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen_number</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the appropriate screen number on the host server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>value_mask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies which values are to be set using information in

+the values structure.

+This mask is the bitwise inclusive OR of the valid configure window values bits.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>values</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the 

+<function>XWindowChanges </function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XReconfigureWMWindow </function>

+function issues a 

+<function>ConfigureWindow </function>

+request on the specified top-level window.

+If the stacking mode is changed and the request fails with a 

+<function>BadMatch </function>

+error, 

+the error is trapped by Xlib and a synthetic 

+<function>ConfigureRequestEvent </function>

+containing the same configuration parameters is sent to the root 

+of the specified window.

+Window managers may elect to receive this event 

+and treat it as a request to reconfigure the indicated window.

+It returns a nonzero status if the request or event is successfully sent;

+otherwise, it returns a zero status.

+</para>

+<para>

+<!-- .LP -->

+<function>XReconfigureWMWindow </function>

+can generate

+<function>BadValue </function>

+and 

+<function>BadWindow </function>

+errors.

+</para>

+</sect2>

+<sect2 id="Converting_String_Lists">

+<title>Converting String Lists</title>

+<!-- .XS -->

+<!-- (SN Converting String Lists -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Many of the text properties allow a variety of types and formats.

+Because the data stored in these properties are not

+simple null-terminated strings, an

+<function>XTextProperty</function>

+structure is used to describe the encoding, type, and length of the text 

+as well as its value.

+The

+<function>XTextProperty</function>

+structure contains:

+<indexterm significance="preferred"><primary>XTextProperty</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct {

+	unsigned char *value;	/* property data */

+	Atom encoding;	/* type of property */

+	int format;	/* 8, 16, or 32 */

+	unsigned long nitems;	/* number of items in value */

+} XTextProperty;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Xlib provides functions to convert localized text to or from encodings

+that support the inter-client communication conventions for text.

+In addition, functions are provided for converting between lists of pointers 

+to character strings and text properties in the STRING encoding.

+</para>

+<para>

+<!-- .LP -->

+The functions for localized text return a signed integer error status 

+that encodes 

+<function>Success</function>

+as zero, specific error conditions as negative numbers, and partial conversion

+as a count of unconvertible characters.

+</para>

+

+<literallayout class="monospaced">

+

+#define #XNoMemory           -1

+#define #XLocaleNotSupported -2

+#define #XConverterNotFound  -3

+

+typedef enum {

+	XStringStyle,		/* STRING */

+	XCompoundTextStyle,	/* COMPOUND_TEXT */

+	XTextStyle,		/* text in owner's encoding (current locale) */

+	XStdICCTextStyle	/* STRING, else COMPOUND_TEXT */

+} XICCEncodingStyle;

+</literallayout>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To convert a list of text strings to an 

+<function>XTextProperty</function>

+structure, use

+<function>XmbTextListToTextProperty</function>

+or

+<function>XwcTextListToTextProperty</function>.

+<indexterm significance="preferred"><primary>XmbTextListToTextProperty</primary></indexterm>

+<indexterm significance="preferred"><primary>XwcTextListToTextProperty</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> XmbTextListToTextProperty</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>char<parameter> **list</parameter></paramdef>

+  <paramdef>int<parameter> count</parameter></paramdef>

+  <paramdef>XICCEncodingStyle<parameter> style</parameter></paramdef>

+  <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> XwcTextListToTextProperty</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>wchar_t<parameter> **list</parameter></paramdef>

+  <paramdef>int<parameter> count</parameter></paramdef>

+  <paramdef>XICCEncodingStyle<parameter> style</parameter></paramdef>

+  <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>list</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a list of null-terminated character strings.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>count</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of strings specified.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>style</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the manner in which the property is encoded.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>text_prop_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the

+<function>XTextProperty</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XmbTextListToTextProperty</function>

+and

+<function>XwcTextListToTextProperty</function>

+functions set the specified 

+<function>XTextProperty</function>

+value to a set of null-separated elements representing the concatenation

+of the specified list of null-terminated text strings.

+A final terminating null is stored at the end of the value field 

+of text_prop_return but is not included in the nitems member.

+</para>

+<para>

+<!-- .LP -->

+The functions set the encoding field of text_prop_return to an

+<function>Atom </function>

+for the specified display 

+naming the encoding determined by the specified style

+and convert the specified text list to this encoding for storage in

+the text_prop_return value field.

+If the style 

+<function>XStringStyle</function>

+or 

+<function>XCompoundTextStyle</function>

+is specified,

+this encoding is ``STRING'' or ``COMPOUND_TEXT'', respectively.

+If the style 

+<function>XTextStyle</function>

+is specified,

+this encoding is the encoding of the current locale.

+If the style 

+<function>XStdICCTextStyle</function>

+is specified,

+this encoding is ``STRING'' if the text is fully convertible to STRING,

+else ``COMPOUND_TEXT''.

+</para>

+<para>

+<!-- .LP -->

+If insufficient memory is available for the new value string,

+the functions return 

+<function>XNoMemory</function>.

+If the current locale is not supported,

+the functions return 

+<function>XLocaleNotSupported</function>.

+In both of these error cases,

+the functions do not set text_prop_return.

+</para>

+<para>

+<!-- .LP -->

+To determine if the functions are guaranteed not to return

+<function>XLocaleNotSupported</function>,

+use

+<function>XSupportsLocale</function>.

+</para>

+<para>

+<!-- .LP -->

+If the supplied text is not fully convertible to the specified encoding,

+the functions return the number of unconvertible characters.

+Each unconvertible character is converted to an implementation-defined and

+encoding-specific default string.

+Otherwise, the functions return 

+<function>Success</function>.

+Note that full convertibility to all styles except 

+<function>XStringStyle</function>

+is guaranteed.

+</para>

+<para>

+<!-- .LP -->

+To free the storage for the value field, use

+<function>XFree</function>.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To obtain a list of text strings from an 

+<function>XTextProperty </function>

+structure, use

+<function>XmbTextPropertyToTextList</function>

+or

+<function>XwcTextPropertyToTextList</function>.

+<indexterm significance="preferred"><primary>XmbTextPropertyToTextList</primary></indexterm>

+<indexterm significance="preferred"><primary>XwcTextPropertyToTextList</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> XmbTextPropertyToTextList</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>

+  <paramdef>char<parameter> ***list_return</parameter></paramdef>

+  <paramdef>int<parameter> *count_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int<function> XwcTextPropertyToTextList</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>

+  <paramdef>wchar_t<parameter> ***list_return</parameter></paramdef>

+  <paramdef>int<parameter> *count_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>text_prop</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the

+<function>XTextProperty</function>

+structure to be used.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>list_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns a list of null-terminated character strings.

+<!-- .ds Cn strings -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>count_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of (Cn.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XmbTextPropertyToTextList</function>

+and 

+<function>XwcTextPropertyToTextList</function>

+functions return a list of text strings in the current locale representing the

+null-separated elements of the specified

+<function>XTextProperty</function>

+structure.

+The data in text_prop must be format 8.

+</para>

+<para>

+<!-- .LP -->

+Multiple elements of the property (for example, the strings in a disjoint

+text selection) are separated by a null byte.

+The contents of the property are not required to be null-terminated;

+any terminating null should not be included in text_prop.nitems.

+</para>

+<para>

+<!-- .LP -->

+If insufficient memory is available for the list and its elements,

+<function>XmbTextPropertyToTextList</function>

+and

+<function>XwcTextPropertyToTextList</function>

+return 

+<function>XNoMemory</function>.

+If the current locale is not supported,

+the functions return

+<function>XLocaleNotSupported</function>.

+Otherwise, if the encoding field of text_prop is not convertible 

+to the encoding of the current locale,

+the functions return

+<function>XConverterNotFound</function>.

+For supported locales,

+existence of a converter from COMPOUND_TEXT, STRING

+or the encoding of the current locale is guaranteed if

+<function>XSupportsLocale </function>

+returns 

+<function>True</function>

+for the current locale (but the actual text

+may contain unconvertible characters).

+Conversion of other encodings is implementation-dependent.

+In all of these error cases,

+the functions do not set any return values.

+</para>

+<para>

+<!-- .LP -->

+Otherwise, 

+<function>XmbTextPropertyToTextList</function>

+and

+<function>XwcTextPropertyToTextList</function>

+return the list of null-terminated text strings to list_return

+and the number of text strings to count_return.

+</para>

+<para>

+<!-- .LP -->

+If the value field of text_prop is not fully convertible to the encoding of

+the current locale,

+the functions return the number of unconvertible characters.

+Each unconvertible character is converted to a string in the

+current locale that is specific to the current locale.

+To obtain the value of this string, 

+use

+<function>XDefaultString</function>.

+Otherwise,

+<function>XmbTextPropertyToTextList</function>

+and

+<function>XwcTextPropertyToTextList</function>

+return 

+<function>Success</function>.

+</para>

+<para>

+<!-- .LP -->

+To free the storage for the list and its contents returned by

+<function>XmbTextPropertyToTextList</function>,

+use

+<function>XFreeStringList</function>.

+To free the storage for the list and its contents returned by

+<function>XwcTextPropertyToTextList</function>,

+use

+<function>XwcFreeStringList</function>.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To free the in-memory data associated with the specified

+wide character string list, use

+<function>XwcFreeStringList</function>.

+<indexterm significance="preferred"><primary>XwcFreeStringList</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XwcFreeStringList</function></funcdef>

+  <paramdef>wchar_t<parameter> **list</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>list</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the list of strings to be freed.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XwcFreeStringList</function>

+function frees memory allocated by

+<function>XwcTextPropertyToTextList</function>.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To obtain the default string for text conversion in the current locale,

+use</para>

+

+<para>char *XDefaultString()</para>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XDefaultString</function>

+function returns the default string used by Xlib for text conversion

+(for example, in 

+<function>XmbTextPropertyToTextList</function>).

+The default string is the string in the current locale that is output 

+when an unconvertible character is found during text conversion.

+If the string returned by

+<function>XDefaultString</function>

+is the empty string (""),

+no character is output in the converted text.

+<function>XDefaultString</function>

+does not return NULL.

+</para>

+<para>

+<!-- .LP -->

+The string returned by 

+<function>XDefaultString</function>

+is independent of the default string for text drawing;

+see 

+<function>XCreateFontSet</function>

+to obtain the default string for an

+<function>XFontSet</function>.

+</para>

+<para>

+<!-- .LP -->

+The behavior when an invalid codepoint is supplied to any Xlib function is

+undefined.

+</para>

+<para>

+<!-- .LP -->

+The returned string is null-terminated.

+It is owned by Xlib and should not be modified or freed by the client.

+It may be freed after the current locale is changed.

+Until freed, it will not be modified by Xlib.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To set the specified list of strings in the STRING encoding to a 

+<function>XTextProperty</function>

+structure, use

+<function>XStringListToTextProperty</function>.

+<indexterm significance="preferred"><primary>XStringListToTextProperty</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XStringListToTextProperty</function></funcdef>

+  <paramdef>char<parameter> **list</parameter></paramdef>

+  <paramdef>int<parameter> count</parameter></paramdef>

+  <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>list</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a list of null-terminated character strings.

+<!-- .ds Cn strings -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>count</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of (Cn.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>text_prop_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the

+<function>XTextProperty</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XStringListToTextProperty </function>

+function sets the specified 

+<function>XTextProperty</function>

+to be of type STRING (format 8) with a value representing the

+concatenation of the specified list of null-separated character strings.

+An extra null byte (which is not included in the nitems member) 

+is stored at the end of the value field of text_prop_return.

+The strings are assumed (without verification) to be in the STRING encoding.

+If insufficient memory is available for the new value string, 

+<function>XStringListToTextProperty</function>

+does not set any fields in the

+<function>XTextProperty</function>

+structure and returns a zero status.

+Otherwise, it returns a nonzero status.

+To free the storage for the value field, use 

+<function>XFree</function>.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To obtain a list of strings from a specified

+<function>XTextProperty</function>

+structure in the STRING encoding, use

+<function>XTextPropertyToStringList</function>.

+<indexterm significance="preferred"><primary>XTextPropertyToStringList</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XTextPropertyToStringList</function></funcdef>

+  <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>

+  <paramdef>char<parameter> ***list_return</parameter></paramdef>

+  <paramdef>int<parameter> *count_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>text_prop</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the

+<function>XTextProperty</function>

+structure to be used.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>list_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns a list of null-terminated character strings.

+<!-- .ds Cn strings -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>count_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of (Cn.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XTextPropertyToStringList </function>

+function returns a list of strings representing the null-separated elements 

+of the specified

+<function>XTextProperty</function>

+structure.

+The data in text_prop must be of type STRING and format 8. 

+Multiple elements of the property 

+(for example, the strings in a disjoint text selection) 

+are separated by NULL (encoding 0).

+The contents of the property are not null-terminated.

+If insufficient memory is available for the list and its elements, 

+<function>XTextPropertyToStringList</function>

+sets no return values and returns a zero status.

+Otherwise, it returns a nonzero status.

+To free the storage for the list and its contents, use 

+<function>XFreeStringList</function>.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To free the in-memory data associated with the specified string list, use

+<function>XFreeStringList</function>.

+<indexterm significance="preferred"><primary>XFreeStringList</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XFreeStringList</function></funcdef>

+  <paramdef>char<parameter> **list</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>list</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the list of strings to be freed.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XFreeStringList </function>

+function releases memory allocated by 

+<function>XmbTextPropertyToTextList</function>

+and

+<function>XTextPropertyToStringList</function>

+and the missing charset list allocated by 

+<function>XCreateFontSet</function>.

+</para>

+</sect2>

+<sect2 id="Setting_and_Reading_Text_Properties">

+<title>Setting and Reading Text Properties</title>

+<!-- .XS -->

+<!-- (SN Setting and Reading Text Properties -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides two functions that you can use to set and read

+the text properties for a given window.

+You can use these functions to set and read those properties of type TEXT

+(WM_NAME, WM_ICON_NAME, WM_COMMAND, and WM_CLIENT_MACHINE).

+In addition,

+Xlib provides separate convenience functions that you can use to set each 

+of these properties.

+For further information about these convenience functions,

+see sections 14.1.4, 14.1.5, 14.2.1, and 14.2.2, respectively.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To set one of a window's text properties, use

+<function>XSetTextProperty</function>.

+<indexterm significance="preferred"><primary>XSetTextProperty</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XSetTextProperty</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>

+  <paramdef>Atom<parameter> property</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>text_prop</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the

+<function>XTextProperty</function>

+structure to be used.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>property</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the property name.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetTextProperty</function>

+function replaces the existing specified property for the named window 

+with the data, type, format, and number of items determined 

+by the value field, the encoding field, the format field, 

+and the nitems field, respectively, of the specified

+<function>XTextProperty</function>

+structure.

+If the property does not already exist,

+<function>XSetTextProperty</function>

+sets it for the specified window.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetTextProperty</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadAtom</function>,

+<function>BadValue</function>,

+and 

+<function>BadWindow  </function>

+errors.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To read one of a window's text properties, use

+<function>XGetTextProperty</function>.

+<indexterm significance="preferred"><primary>XGetTextProperty</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XGetTextProperty</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>

+  <paramdef>Atom<parameter> property</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>text_prop_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the

+<function>XTextProperty</function>

+structure.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>property</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the property name.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetTextProperty </function>

+function reads the specified property from the window

+and stores the data in the returned

+<function>XTextProperty</function>

+structure.

+It stores the data in the value field,

+the type of the data in the encoding field,

+the format of the data in the format field, 

+and the number of items of data in the nitems field.

+An extra byte containing null (which is not included in the nitems member) 

+is stored at the end of the value field of text_prop_return.

+The particular interpretation of the property's encoding 

+and data as text is left to the calling application.

+If the specified property does not exist on the window,

+<function>XGetTextProperty</function>

+sets the value field to NULL, 

+the encoding field to

+<function>None</function>,

+the format field to zero, 

+and the nitems field to zero.

+</para>

+<para>

+<!-- .LP -->

+If it was able to read and store the data in the

+<function>XTextProperty</function>

+structure,

+<function>XGetTextProperty</function>

+returns a nonzero status; 

+otherwise, it returns a zero status.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetTextProperty</function>

+can generate

+<function>BadAtom </function>

+and 

+<function>BadWindow </function>

+errors.

+</para>

+</sect2>

+<sect2 id="Setting_and_Reading_the_WM_NAME_Property">

+<title>Setting and Reading the WM_NAME Property</title>

+<!-- .XS -->

+<!-- (SN Setting and Reading the WM_NAME Property -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides convenience functions that you can use to set and read 

+the WM_NAME property for a given window.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To set a window's WM_NAME property with the supplied convenience function, use

+<function>XSetWMName</function>.

+<indexterm significance="preferred"><primary>XSetWMName</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XSetWMName</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>text_prop</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the

+<function>XTextProperty</function>

+structure to be used.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetWMName</function>

+convenience function calls

+<function>XSetTextProperty </function>

+to set the WM_NAME property.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To read a window's WM_NAME property with the supplied convenience function, use

+<function>XGetWMName</function>.

+<indexterm significance="preferred"><primary>XGetWMName</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XGetWMName</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>text_prop_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the

+<function>XTextProperty</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetWMName </function>

+convenience function calls

+<function>XGetTextProperty </function>

+to obtain the WM_NAME property.

+It returns a nonzero status on success;

+otherwise, it returns a zero status.

+</para>

+<para>

+<!-- .LP -->

+The following two functions have been superseded by

+<function>XSetWMName</function>

+and

+<function>XGetWMName</function>,

+respectively. 

+You can use these additional convenience functions 

+for window names that are encoded as STRING properties.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To assign a name to a window, use

+<function>XStoreName</function>.

+<indexterm><primary>Window</primary><secondary>name</secondary></indexterm>

+<indexterm significance="preferred"><primary>XStoreName</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XStoreName</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>char<parameter> *window_name</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>window_name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window name,

+which should be a null-terminated string.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XStoreName</function>

+function assigns the name passed to window_name to the specified window.

+A window manager can display the window name in some prominent

+place, such as the title bar, to allow users to identify windows easily.

+Some window managers may display a window's name in the window's icon,

+although they are encouraged to use the window's icon name

+if one is provided by the application.

+If the string is not in the Host Portable Character Encoding,

+the result is implementation-dependent.

+</para>

+<para>

+<!-- .LP -->

+<function>XStoreName</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadWindow</function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To get the name of a window, use

+<function>XFetchName</function>.

+<indexterm significance="preferred"><primary>XFetchName</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XFetchName</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>char<parameter> **window_name_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>window_name_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the window name, which is a null-terminated string.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XFetchName</function>

+function returns the name of the specified window.

+If it succeeds,

+it returns a nonzero status; 

+otherwise, no name has been set for the window,

+and it returns zero.

+If the WM_NAME property has not been set for this window,

+<function>XFetchName</function>

+sets window_name_return to NULL.

+If the data returned by the server is in the Latin Portable Character Encoding,

+then the returned string is in the Host Portable Character Encoding.

+Otherwise, the result is implementation-dependent.

+When finished with it, a client must free

+the window name string using

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XFetchName</function>

+can generate a

+<function>BadWindow</function>

+error.

+</para>

+</sect2>

+<sect2 id="Setting_and_Reading_the_WM_ICON_NAME_Property">

+<title>Setting and Reading the WM_ICON_NAME Property</title>

+<!-- .XS -->

+<!-- (SN Setting and Reading the WM_ICON_NAME Property -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides convenience functions that you can use to set and read 

+the WM_ICON_NAME property for a given window.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set a window's WM_ICON_NAME property,

+use

+<function>XSetWMIconName</function>.

+<indexterm significance="preferred"><primary>XSetWMIconName</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XSetWMIconName</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>text_prop</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the

+<function>XTextProperty</function>

+structure to be used.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetWMIconName</function>

+convenience function calls

+<function>XSetTextProperty</function>

+to set the WM_ICON_NAME property.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To read a window's WM_ICON_NAME property,

+use

+<function>XGetWMIconName</function>.

+<indexterm significance="preferred"><primary>XGetWMIconName</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XGetWMIconName</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>text_prop_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the

+<function>XTextProperty</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XGetWMIconName </function>

+convenience function calls

+<function>XGetTextProperty </function>

+to obtain the WM_ICON_NAME property.

+It returns a nonzero status on success;

+otherwise, it returns a zero status.

+</para>

+<para>

+<!-- .LP -->

+The next two functions have been superseded by

+<function>XSetWMIconName</function>

+and

+<function>XGetWMIconName</function>,

+respectively.

+You can use these additional convenience functions 

+for window names that are encoded as STRING properties.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the name to be displayed in a window's icon, use

+<function>XSetIconName</function>.

+<indexterm><primary>Window</primary><secondary>icon name</secondary></indexterm>

+<indexterm significance="preferred"><primary>XSetIconName</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetIconName</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>char<parameter> *icon_name</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>icon_name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the icon name,

+which should be a null-terminated string.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If the string is not in the Host Portable Character Encoding,

+the result is implementation-dependent.

+<function>XSetIconName</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadWindow</function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To get the name a window wants displayed in its icon, use

+<function>XGetIconName</function>.

+<indexterm significance="preferred"><primary>XGetIconName</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XGetIconName</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>char<parameter> **icon_name_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>icon_name_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the window's icon name,

+which is a null-terminated string.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetIconName</function>

+function returns the name to be displayed in the specified window's icon.

+If it succeeds, it returns a nonzero status; otherwise, 

+if no icon name has been set for the window,

+it returns zero.

+If you never assigned a name to the window,

+<function>XGetIconName</function>

+sets icon_name_return to NULL.

+If the data returned by the server is in the Latin Portable Character Encoding,

+then the returned string is in the Host Portable Character Encoding.

+Otherwise, the result is implementation-dependent.

+When finished with it, a client must free

+the icon name string using

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetIconName</function>

+can generate a

+<function>BadWindow</function>

+error.

+</para>

+</sect2>

+<sect2 id="Setting_and_Reading_the_WM_HINTS_Property">

+<title>Setting and Reading the WM_HINTS Property</title>

+<!-- .XS -->

+<!-- (SN Setting and Reading the WM_HINTS Property -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to set and read 

+the WM_HINTS property for a given window.

+These functions use the flags and the

+<function>XWMHints </function>

+structure, as defined in the

+<!-- .hN X11/Xutil.h -->

+header file.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To allocate an

+<function>XWMHints</function>

+structure, use

+<function>XAllocWMHints</function>.

+</para>

+

+<para>

+  XWMHints *XAllocWMHints()

+</para>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XAllocWMHints</function>

+function allocates and returns a pointer to an

+<function>XWMHints</function>

+structure.

+Note that all fields in the

+<function>XWMHints</function>

+structure are initially set to zero.

+If insufficient memory is available, 

+<function>XAllocWMHints</function>

+returns NULL.

+To free the memory allocated to this structure,

+use

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XWMHints</function>

+structure contains:

+</para>

+

+<literallayout class="monospaced">

+/* Window manager hints mask bits */

+

+#define         InputHint             (1L&lt;&lt;0)

+#define         StateHint             (1L&lt;&lt;1)

+#define         IconPixmapHint        (1L&lt;&lt;2)

+#define         IconWindowHint        (1L&lt;&lt;3)

+#define         IconPositionHint      (1L&lt;&lt;4)

+#define         IconMaskHint          (1L&lt;&lt;5)

+#define         WindowGroupHint       (1L&lt;&lt;6)

+#define         UrgencyHint           (1L&lt;&lt;8)

+#define         AllHints              (InputHint|StateHint|IconPixmapHint|

+                                       IconWIndowHint|IconPositionHint|

+                                       IconMaskHint|WindowGroupHint)

+

+

+/* Values */

+

+typedef struct {

+	long flags;	        /* marks which fields in this structure are defined */

+	Bool input;	        /* does this application rely on the window manager to

+			           get keyboard input? */

+	int initial_state;	/* see below */

+	Pixmap icon_pixmap;	/* pixmap to be used as icon */

+	Window icon_window;	/* window to be used as icon */

+	int icon_x, icon_y;	/* initial position of icon */

+	Pixmap icon_mask;	/* pixmap to be used as mask for icon_pixmap */

+	XID window_group;	/* id of related window group */

+	/* this structure may be extended in the future */

+} XWMHints;

+</literallayout>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The input member is used to communicate to the window manager the input focus

+model used by the application.

+Applications that expect input but never explicitly set focus to any 

+of their subwindows (that is, use the push model of focus management), 

+such as X Version 10 style applications that use real-estate

+driven focus, should set this member to 

+<function>True</function>.

+Similarly, applications

+that set input focus to their subwindows only when it is given to their

+top-level window by a window manager should also set this member to 

+<function>True</function>.

+Applications that manage their own input focus by explicitly setting

+focus to one of their subwindows whenever they want keyboard input 

+(that is, use the pull model of focus management) should set this member to 

+<function>False</function>.

+Applications that never expect any keyboard input also should set this member

+to 

+<function>False</function>.

+</para>

+<para>

+<!-- .LP -->

+Pull model window managers should make it possible for push model

+applications to get input by setting input focus to the top-level windows of

+applications whose input member is 

+<function>True</function>.

+Push model window managers should

+make sure that pull model applications do not break them 

+by resetting input focus to 

+<function>PointerRoot </function>

+when it is appropriate (for example, whenever an application whose

+input member is 

+<function>False </function>

+sets input focus to one of its subwindows).

+</para>

+<para>

+<!-- .LP -->

+The definitions for the initial_state flag are:

+</para>

+

+<literallayout class="monospaced">

+#define      WithdrawnState 0

+#define      NormalState    1   /* most applications start this way */

+#define      IconicState    2   /* application wants to start as an icon */

+

+</literallayout>

+<para>

+The icon_mask specifies which pixels of the icon_pixmap should be used as the

+icon.  

+This allows for nonrectangular icons.

+Both icon_pixmap and icon_mask must be bitmaps.

+The icon_window lets an application provide a window for use as an icon

+for window managers that support such use.

+The window_group lets you specify that this window belongs to a group

+of other windows.

+For example, if a single application manipulates multiple 

+top-level windows, this allows you to provide enough

+information that a window manager can iconify all of the windows

+rather than just the one window.

+</para>

+<para>

+<!-- .LP -->

+The

+<function>UrgencyHint</function>

+flag, if set in the flags field, indicates that the client deems the window

+contents to be urgent, requiring the timely response of the user.  The

+window manager will make some effort to draw the user's attention to this

+window while this flag is set.  The client must provide some means by which the

+user can cause the urgency flag to be cleared (either mitigating

+the condition that made the window urgent or merely shutting off the alarm)

+or the window to be withdrawn.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set a window's WM_HINTS property, use

+<function>XSetWMHints</function>.

+<indexterm significance="preferred"><primary>XSetWMHints</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetWMHints</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XWMHints<parameter> *wmhints</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>wmhints</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the 

+<function>XWMHints</function>

+structure to be used.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetWMHints</function>

+function sets the window manager hints that include icon information and location,

+the initial state of the window, and whether the application relies on the

+window manager to get keyboard input.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetWMHints</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To read a window's WM_HINTS property, use

+<function>XGetWMHints</function>.

+<indexterm significance="preferred"><primary>XGetWMHints</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XWMHints<function> *XGetWMHints</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetWMHints</function>

+function reads the window manager hints and 

+returns NULL if no WM_HINTS property was set on the window 

+or returns a pointer to an 

+<function>XWMHints </function>

+structure if it succeeds.

+When finished with the data,

+free the space used for it by calling

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetWMHints</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+</sect2>

+<sect2 id="Setting_and_Reading_the_WM_NORMAL_HINTS_Property">

+<title>Setting and Reading the WM_NORMAL_HINTS Property</title>

+<!-- .XS -->

+<!-- (SN Setting and Reading the WM_NORMAL_HINTS Property -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to set or read 

+the WM_NORMAL_HINTS property for a given window.

+The functions use the flags and the

+<function>XSizeHints </function>

+structure, as defined in the

+<!-- .hN X11/Xutil.h -->

+header file.

+</para>

+<para>

+<!-- .LP -->

+The size of the

+<function>XSizeHints</function>

+structure may grow in future releases, as new components are

+added to support new <acronym>ICCCM</acronym> features.

+Passing statically allocated instances of this structure into

+Xlib may result in memory corruption when running against a

+future release of the library.

+As such, it is recommended that only dynamically allocated

+instances of the structure be used.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To allocate an

+<function>XSizeHints</function>

+structure, use

+<function>XAllocSizeHints</function>.

+</para>

+

+<para>

+XSizeHints *XAllocSizeHints()

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XAllocSizeHints</function>

+function allocates and returns a pointer to an

+<function>XSizeHints</function>

+structure.

+Note that all fields in the

+<function>XSizeHints</function>

+structure are initially set to zero.

+If insufficient memory is available, 

+<function>XAllocSizeHints</function>

+returns NULL.

+To free the memory allocated to this structure,

+use

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XSizeHints</function>

+structure contains:

+</para>

+

+

+<literallayout class="monospaced">

+/* Size hints mask bits */

+

+#define           USPosition         (1L&lt;&lt;0)  /* user specified x,y */

+#define           USSize             (1L&lt;&lt;1)  /* user specified width,height */

+#define           PPosition          (1L&lt;&lt;2)  /* program specified posistion */

+#define           PSize              (1L&lt;&lt;3)  /* program specified size */

+#define           PMinSize           (1L&lt;&lt;4)  /* program specified minimum size */

+#define           PMaxSize           (1L&lt;&lt;5)  /* program specified maximum size */

+#define           PResizeInc         (1L&lt;&lt;5)  /* program specified resize increments */

+#define           PAspect            (1L&lt;&lt;6)  /* program specified min and max aspect ratios */

+#define           PBaseSize          (1L&lt;&lt;8)

+#define           PWinGravity        (1L&lt;&lt;9)

+#define           PAllHints          (PPosition|Psize|

+                                      PMinSize|PMaxSize|

+                                      PResizeInc|PAspect)

+

+

+/* Values */

+

+typedef struct {

+	long flags;	        /* marks which fields in this structure are defined */

+	int x, y;	        /* Obsolete */

+	int width, height;	/* Obsolete */

+	int min_width, min_height;

+	int max_width, max_height;

+	int width_inc, height_inc;

+	struct {

+	       int x;	        /* numerator */

+	       int y;	        /* denominator */

+	} min_aspect, max_aspect;

+	int base_width, base_height;

+	int win_gravity;

+	/* this structure may be extended in the future */

+} XSizeHints;

+</literallayout>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The x, y, width, and height members are now obsolete

+and are left solely for compatibility reasons.

+The min_width and min_height members specify the

+minimum window size that still allows the application to be useful.

+The max_width and max_height members specify the maximum window size.

+The width_inc and height_inc members define an arithmetic progression of

+sizes (minimum to maximum) into which the window prefers to be resized.

+The min_aspect and max_aspect members are expressed

+as ratios of x and y, 

+and they allow an application to specify the range of aspect

+ratios it prefers.

+The base_width and base_height members define the desired size of the window.

+The window manager will interpret the position of the window 

+and its border width to position the point of the outer rectangle 

+of the overall window specified by the win_gravity member.

+The outer rectangle of the window includes any borders or decorations

+supplied by the window manager.

+In other words,

+if the window manager decides to place the window where the client asked,

+the position on the parent window's border named by the win_gravity 

+will be placed where the client window would have been placed 

+in the absence of a window manager.

+</para>

+<para>

+<!-- .LP -->

+Note that use of the

+<function>PAllHints</function>

+macro is highly discouraged.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To set a window's WM_NORMAL_HINTS property, use

+<function>XSetWMNormalHints</function>.

+<indexterm significance="preferred"><primary>XSetWMNormalHints</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XSetWMNormalHints</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hints</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the size hints for the window in its normal state.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XSetWMNormalHints </function>

+function replaces the size hints for the WM_NORMAL_HINTS property 

+on the specified window.

+If the property does not already exist,

+<function>XSetWMNormalHints</function>

+sets the size hints for the WM_NORMAL_HINTS property on the specified window.

+The property is stored with a type of WM_SIZE_HINTS and a format of 32.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetWMNormalHints</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadWindow</function>

+errors.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To read a window's WM_NORMAL_HINTS property, use

+<function>XGetWMNormalHints</function>.

+<indexterm significance="preferred"><primary>XGetWMNormalHints</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XGetWMNormalHints</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef>

+  <paramdef>long<parameter> *supplied_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hints_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the size hints for the window in its normal state.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>supplied_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the hints that were supplied by the user.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XGetWMNormalHints </function>

+function returns the size hints stored in the WM_NORMAL_HINTS property 

+on the specified window.

+If the property is of type WM_SIZE_HINTS, is of format 32,

+and is long enough to contain either an old (pre-<acronym>ICCCM</acronym>) 

+or new size hints structure, 

+<function>XGetWMNormalHints</function>

+sets the various fields of the 

+<function>XSizeHints</function>

+structure, sets the supplied_return argument to the list of fields 

+that were supplied by the user (whether or not they contained defined values),

+and returns a nonzero status.

+Otherwise, it returns a zero status.

+</para>

+<para>

+<!-- .LP -->

+If 

+<function>XGetWMNormalHints</function>

+returns successfully and a pre-<acronym>ICCCM</acronym> size hints property is read, 

+the supplied_return argument will contain the following bits:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+(USPosition|USSize|PPosition|PSize|PMinSize|

+ PMaxSize|PResizeInc|PAspect)

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+If the property is large enough to contain the base size 

+and window gravity fields as well, 

+the supplied_return argument will also contain the following bits:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+PBaseSize|PWinGravity

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<function>XGetWMNormalHints</function>

+can generate a

+<function>BadWindow</function>

+error.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To set a window's WM_SIZE_HINTS property, use

+<function>XSetWMSizeHints</function>.

+<indexterm significance="preferred"><primary>XSetWMSizeHints</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XSetWMSizeHints</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>

+  <paramdef>Atom<parameter> property</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hints</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the

+<function>XSizeHints</function>

+structure to be used.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>property</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the property name.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XSetWMSizeHints </function>

+function replaces the size hints for the specified property 

+on the named window.

+If the specified property does not already exist,

+<function>XSetWMSizeHints</function>

+sets the size hints for the specified property

+on the named window.

+The property is stored with a type of WM_SIZE_HINTS and a format of 32.

+To set a window's normal size hints, 

+you can use the 

+<function>XSetWMNormalHints</function>

+function.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetWMSizeHints</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadAtom</function>,

+and 

+<function>BadWindow</function>

+errors.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To read a window's WM_SIZE_HINTS property, use

+<function>XGetWMSizeHints</function>.

+<indexterm significance="preferred"><primary>XGetWMSizeHints</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XGetWMSizeHints</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef>

+  <paramdef>long<parameter> *supplied_return</parameter></paramdef>

+  <paramdef>Atom<parameter> property</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hints_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the

+<function>XSizeHints</function>

+structure.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>supplied_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the hints that were supplied by the user.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>property</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the property name.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XGetWMSizeHints</function>

+function returns the size hints stored in the specified property 

+on the named window.

+If the property is of type WM_SIZE_HINTS, is of format 32, 

+and is long enough to contain either an old (pre-<acronym>ICCCM</acronym>) 

+or new size hints structure, 

+<function>XGetWMSizeHints</function>

+sets the various fields of the 

+<function>XSizeHints</function>

+structure, sets the supplied_return argument to the

+list of fields that were supplied by the user 

+(whether or not they contained defined values), 

+and returns a nonzero status.

+Otherwise, it returns a zero status.

+To get a window's normal size hints, 

+you can use the 

+<function>XGetWMNormalHints </function>

+function.

+</para>

+<para>

+<!-- .LP -->

+If 

+<function>XGetWMSizeHints</function>

+returns successfully and a pre-<acronym>ICCCM</acronym> size hints property is read, 

+the supplied_return argument will contain the following bits:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+(USPosition|USSize|PPosition|PSize|PMinSize|

+ PMaxSize|PResizeInc|PAspect)

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+If the property is large enough to contain the base size 

+and window gravity fields as well, 

+the supplied_return argument will also contain the following bits:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+PBaseSize|PWinGravity

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<function>XGetWMSizeHints</function>

+can generate

+<function>BadAtom </function>

+and 

+<function>BadWindow</function>

+errors.

+</para>

+</sect2>

+<sect2 id="Setting_and_Reading_the_WM_CLASS_Property">

+<title>Setting and Reading the WM_CLASS Property</title>

+<!-- .XS -->

+<!-- (SN Setting and Reading the WM_CLASS Property -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to set and get 

+the WM_CLASS property for a given window.

+These functions use the

+<function>XClassHint </function>

+structure, which is defined in the

+<!-- .hN X11/Xutil.h -->

+header file.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To allocate an

+<function>XClassHint</function>

+structure, use

+<function>XAllocClassHint</function>.

+<indexterm significance="preferred"><primary>XAllocClassHint</primary></indexterm>

+<!-- .sM -->

+</para>

+<para>

+

+  XClassHint *XAllocClassHint()

+</para>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XAllocClassHint</function>

+function allocates and returns a pointer to an

+<function>XClassHint</function>

+structure.

+Note that the pointer fields in the

+<function>XClassHint</function>

+structure are initially set to NULL.

+If insufficient memory is available, 

+<function>XAllocClassHint</function>

+returns NULL.

+To free the memory allocated to this structure,

+use

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XClassHint</function>

+contains:

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<indexterm significance="preferred"><primary>XClassHint</primary></indexterm>

+<literallayout class="monospaced">

+<!-- .TA .5i -->

+<!-- .ta .5i -->

+typedef struct {

+	char *res_name;

+	char *res_class;

+} XClassHint;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The res_name member contains the application name, 

+and the res_class member contains the application class. 

+Note that the name set in this property may differ from the name set as WM_NAME.

+That is, WM_NAME specifies what should be displayed in the title bar and,

+therefore, can contain temporal information (for example, the name of

+a file currently in an editor's buffer).

+On the other hand, 

+the name specified as part of WM_CLASS is the formal name of the application

+that should be used when retrieving the application's resources from the 

+resource database.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set a window's WM_CLASS property, use

+<function>XSetClassHint</function>.

+<indexterm significance="preferred"><primary>XSetClassHint</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetClassHint</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XClassHint<parameter> *class_hints</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>class_hints</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the

+<function>XClassHint</function>

+structure that is to be used.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetClassHint</function>

+function sets the class hint for the specified window.

+If the strings are not in the Host Portable Character Encoding,

+the result is implementation-dependent.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetClassHint</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadWindow</function>

+errors. 

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To read a window's WM_CLASS property, use

+<function>XGetClassHint</function>.

+<indexterm significance="preferred"><primary>XGetClassHint</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XGetClassHint</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XClassHint<parameter> *class_hints_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>class_hints_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the 

+<function>XClassHint</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetClassHint</function>

+function returns the class hint of the specified window to the members

+of the supplied structure.

+If the data returned by the server is in the Latin Portable Character Encoding,

+then the returned strings are in the Host Portable Character Encoding.

+Otherwise, the result is implementation-dependent.

+It returns a nonzero status on success;

+otherwise, it returns a zero status.

+To free res_name and res_class when finished with the strings,

+use

+<function>XFree</function>

+on each individually.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetClassHint</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+</sect2>

+<sect2 id="Setting_and_Reading_the_WM_TRANSIENT_FOR_Property">

+<title>Setting and Reading the WM_TRANSIENT_FOR Property</title>

+<!-- .XS -->

+<!-- (SN Setting and Reading the WM_TRANSIENT_FOR Property -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to set and read

+the WM_TRANSIENT_FOR property for a given window.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set a window's WM_TRANSIENT_FOR property, use

+<function>XSetTransientForHint</function>.

+<indexterm significance="preferred"><primary>XSetTransientForHint</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetTransientForHint</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>Window<parameter> prop_window</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>prop_window</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window that the WM_TRANSIENT_FOR property is to be set to.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetTransientForHint</function>

+function sets the WM_TRANSIENT_FOR property of the specified window to the 

+specified prop_window.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetTransientForHint</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadWindow</function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To read a window's WM_TRANSIENT_FOR property, use

+<function>XGetTransientForHint</function>.

+<indexterm significance="preferred"><primary>XGetTransientForHint</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XGetTransientForHint</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>Window<parameter> *prop_window_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>prop_window_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the WM_TRANSIENT_FOR property of the specified window.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetTransientForHint</function>

+function returns the WM_TRANSIENT_FOR property for the specified window.

+It returns a nonzero status on success;

+otherwise, it returns a zero status.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetTransientForHint</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+</sect2>

+<sect2 id="Setting_and_Reading_the_WM_PROTOCOLS_Property">

+<title>Setting and Reading the WM_PROTOCOLS Property</title>

+<!-- .XS -->

+<!-- (SN Setting and Reading the WM_PROTOCOLS Property -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to set and read

+the WM_PROTOCOLS property for a given window.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set a window's WM_PROTOCOLS property, use

+<function>XSetWMProtocols</function>.

+<indexterm significance="preferred"><primary>XSetWMProtocols</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XSetWMProtocols</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>Atom<parameter> *protocols</parameter></paramdef>

+  <paramdef>int<parameter> count</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>protocols</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the list of protocols.

+<!-- .ds Cn protocols in the list -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>count</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of (Cn.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XSetWMProtocols </function>

+function replaces the WM_PROTOCOLS property on the specified window 

+with the list of atoms specified by the protocols argument.

+If the property does not already exist,

+<function>XSetWMProtocols</function>

+sets the WM_PROTOCOLS property on the specified window

+to the list of atoms specified by the protocols argument.

+The property is stored with a type of ATOM and a format of 32.

+If it cannot intern the WM_PROTOCOLS atom, 

+<function>XSetWMProtocols</function>

+returns a zero status.

+Otherwise, it returns a nonzero status.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetWMProtocols</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadWindow</function>

+errors.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To read a window's WM_PROTOCOLS property, use

+<function>XGetWMProtocols</function>.

+<indexterm significance="preferred"><primary>XGetWMProtocols</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XGetWMProtocols</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>Atom<parameter> **protocols_return</parameter></paramdef>

+  <paramdef>int<parameter> *count_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>protocols_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the list of protocols.

+<!-- .ds Cn protocols in the list -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>count_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of (Cn.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XGetWMProtocols </function>

+function returns the list of atoms stored in the WM_PROTOCOLS property 

+on the specified window.

+These atoms describe window manager protocols in which the owner 

+of this window is willing to participate.

+If the property exists, is of type ATOM, is of format 32, 

+and the atom WM_PROTOCOLS can be interned, 

+<function>XGetWMProtocols</function>

+sets the protocols_return argument to a list of atoms, 

+sets the count_return argument to the number of elements in the list, 

+and returns a nonzero status.

+Otherwise, it sets neither of the return arguments

+and returns a zero status.

+To release the list of atoms, use

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetWMProtocols</function>

+can generate a

+<function>BadWindow</function>

+error.

+</para>

+</sect2>

+<sect2 id="Setting_and_Reading_the_WM_COLORMAP_WINDOWS_Property">

+<title>Setting and Reading the WM_COLORMAP_WINDOWS Property</title>

+<!-- .XS -->

+<!-- (SN Setting and Reading the WM_COLORMAP_WINDOWS Property -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to set and read

+the WM_COLORMAP_WINDOWS property for a given window.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To set a window's WM_COLORMAP_WINDOWS property, use

+<function>XSetWMColormapWindows</function>.

+<indexterm significance="preferred"><primary>XSetWMColormapWindows</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XSetWMColormapWindows</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>Window<parameter> *colormap_windows</parameter></paramdef>

+  <paramdef>int<parameter> count</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap_windows</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the list of windows.

+<!-- .ds Cn windows in the list -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>count</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of (Cn.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XSetWMColormapWindows </function>

+function replaces the WM_COLORMAP_WINDOWS property on the specified

+window with the list of windows specified by the colormap_windows argument.

+If the property does not already exist,

+<function>XSetWMColormapWindows</function>

+sets the WM_COLORMAP_WINDOWS property on the specified

+window to the list of windows specified by the colormap_windows argument.

+The property is stored with a type of WINDOW and a format of 32.

+If it cannot intern the WM_COLORMAP_WINDOWS atom,

+<function>XSetWMColormapWindows</function>

+returns a zero status.

+Otherwise, it returns a nonzero status.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetWMColormapWindows</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadWindow</function>

+errors.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To read a window's WM_COLORMAP_WINDOWS property, use

+<function>XGetWMColormapWindows</function>.

+<indexterm significance="preferred"><primary>XGetWMColormapWindows</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XGetWMColormapWindows</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>Window<parameter> **colormap_windows_return</parameter></paramdef>

+  <paramdef>int<parameter> *count_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>colormap_windows_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the list of windows.

+<!-- .ds Cn windows in the list -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>count_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of (Cn.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XGetWMColormapWindows </function>

+function returns the list of window identifiers stored 

+in the WM_COLORMAP_WINDOWS property on the specified window.

+These identifiers indicate the colormaps that the window manager

+may need to install for this window.

+If the property exists, is of type WINDOW, is of format 32, 

+and the atom WM_COLORMAP_WINDOWS can be interned, 

+<function>XGetWMColormapWindows</function>

+sets the windows_return argument to a list of window identifiers, 

+sets the count_return argument to the number of elements in the list, 

+and returns a nonzero status.

+Otherwise, it sets neither of the return arguments

+and returns a zero status.

+To release the list of window identifiers, use

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetWMColormapWindows</function>

+can generate a

+<function>BadWindow</function>

+error.

+</para>

+</sect2>

+<sect2 id="Setting_and_Reading_the_WM_ICON_SIZE_Property">

+<title>Setting and Reading the WM_ICON_SIZE Property</title>

+<!-- .XS -->

+<!-- (SN Setting and Reading the WM_ICON_SIZE Property -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to set and read 

+the WM_ICON_SIZE property for a given window.

+These functions use the 

+<function>XIconSize </function>

+<indexterm><primary>XIconSize</primary></indexterm>

+structure, which is defined in the

+<!-- .hN X11/Xutil.h -->

+header file.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To allocate an

+<function>XIconSize</function>

+structure, use

+<function>XAllocIconSize</function>.

+</para>

+

+<para>

+  XIconSize *XAllocIconSize()

+</para>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XAllocIconSize </function>

+function allocates and returns a pointer to an

+<function>XIconSize </function>

+structure.

+Note that all fields in the

+<function>XIconSize</function>

+structure are initially set to zero.

+If insufficient memory is available, 

+<function>XAllocIconSize</function>

+returns NULL.

+To free the memory allocated to this structure,

+use

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XIconSize</function>

+structure contains:

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<indexterm significance="preferred"><primary>XIconSize</primary></indexterm>

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct {

+	int min_width, min_height;

+	int max_width, max_height;

+	int width_inc, height_inc;

+} XIconSize;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The width_inc and height_inc members define an arithmetic progression of

+sizes (minimum to maximum) that represent the supported icon sizes.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set a window's WM_ICON_SIZE property, use

+<function>XSetIconSizes</function>.

+<indexterm significance="preferred"><primary>XSetIconSizes</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetIconSizes</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XIconSize<parameter> *size_list</parameter></paramdef>

+  <paramdef>int<parameter> count</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>size_list</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the size list.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>count</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of items in the size list.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetIconSizes</function>

+function is used only by window managers to set the supported icon sizes.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetIconSizes</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadWindow </function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To read a window's WM_ICON_SIZE property, use

+<function>XGetIconSizes</function>.

+<indexterm significance="preferred"><primary>XGetIconSizes</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XGetIconSizes</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XIconSize<parameter> **size_list_return</parameter></paramdef>

+  <paramdef>int<parameter> *count_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>size_list_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the size list.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>count_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of items in the size list.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetIconSizes</function>

+function returns zero if a window manager has not set icon sizes;

+otherwise, it returns nonzero.

+<function>XGetIconSizes</function>

+should be called by an application that

+wants to find out what icon sizes would be most appreciated by the

+window manager under which the application is running.

+The application

+should then use

+<function>XSetWMHints</function>

+to supply the window manager with an icon pixmap or window in one of the

+supported sizes.

+To free the data allocated in size_list_return, use

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetIconSizes</function>

+can generate a

+<function>BadWindow </function>

+error.

+</para>

+</sect2>

+<sect2 id="Using_Window_Manager_Convenience_Functions">

+<title>Using Window Manager Convenience Functions</title>

+<!-- .XS -->

+<!-- (SN Using Window Manager Convenience Functions -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The 

+<function>XmbSetWMProperties</function>

+function stores the standard set of window manager properties,

+with text properties in standard encodings

+for internationalized text communication.

+The standard window manager properties for a given window are

+WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS,

+WM_COMMAND, WM_CLIENT_MACHINE, and WM_LOCALE_NAME.

+<indexterm significance="preferred"><primary>XmbSetWMProperties</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XmbSetWMProperties</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>char<parameter> *window_name</parameter></paramdef>

+  <paramdef>char<parameter> *icon_name</parameter></paramdef>

+  <paramdef>char<parameter> *argv[]</parameter></paramdef>

+  <paramdef>int<parameter> argc</parameter></paramdef>

+  <paramdef>XSizeHints<parameter> *normal_hints</parameter></paramdef>

+  <paramdef>XWMHints<parameter> *wm_hints</parameter></paramdef>

+  <paramdef>XClassHint<parameter> *class_hints</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>window_name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window name,

+which should be a null-terminated string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>icon_name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the icon name,

+which should be a null-terminated string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>argv</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the application's argument list.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>argc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of arguments.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hints</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the size hints for the window in its normal state.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>wm_hints</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the

+<function>XWMHints</function>

+structure to be used.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>class_hints</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the

+<function>XClassHint</function>

+structure to be used.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XmbSetWMProperties</function>

+convenience function provides a simple programming interface 

+for setting those essential window properties that are used 

+for communicating with other clients

+(particularly window and session managers).

+</para>

+<para>

+<!-- .LP -->

+If the window_name argument is non-NULL,

+<function>XmbSetWMProperties</function>

+sets the WM_NAME property.

+If the icon_name argument is non-NULL,

+<function>XmbSetWMProperties</function>

+sets the WM_ICON_NAME property.

+The window_name and icon_name arguments are null-terminated strings

+in the encoding of the current locale.

+If the arguments can be fully converted to the STRING encoding,

+the properties are created with type ``STRING''; 

+otherwise, the arguments are converted to Compound Text, 

+and the properties are created with type ``COMPOUND_TEXT''.

+</para>

+<para>

+<!-- .LP -->

+If the normal_hints argument is non-NULL,

+<function>XmbSetWMProperties</function>

+calls

+<function>XSetWMNormalHints</function>,

+which sets the WM_NORMAL_HINTS property (see section 14.1.7).

+If the wm_hints argument is non-NULL, 

+<function>XmbSetWMProperties</function>

+calls

+<function>XSetWMHints</function>,

+which sets the WM_HINTS property (see section 14.1.6).

+</para>

+<para>

+<!-- .LP -->

+If the argv argument is non-NULL,

+<function>XmbSetWMProperties</function>

+sets the WM_COMMAND property from argv and argc.

+An argc of zero indicates a zero-length command.

+</para>

+<para>

+<!-- .LP -->

+The hostname of the machine is stored using 

+<function>XSetWMClientMachine </function>

+(see section 14.2.2).

+</para>

+<para>

+<!-- .LP -->

+If the class_hints argument is non-NULL,

+<function>XmbSetWMProperties</function>

+sets the WM_CLASS property.

+If the res_name member in the 

+<function>XClassHint</function>

+structure is set to the NULL pointer and the RESOURCE_NAME

+environment variable is set,

+the value of the environment variable is substituted for res_name.

+If the res_name member is NULL,

+the environment variable is not set, and argv and argv[0] are set,

+then the value of argv[0], stripped of any directory prefixes,

+is substituted for res_name.

+</para>

+<para>

+<!-- .LP -->

+It is assumed that the supplied class_hints.res_name and argv,

+the RESOURCE_NAME environment variable, and the hostname of the machine

+are in the encoding of the locale announced for the LC_CTYPE category

+(on <acronym>POSIX</acronym>-compliant systems, the LC_CTYPE, else LANG environment variable).

+The corresponding WM_CLASS, WM_COMMAND, and WM_CLIENT_MACHINE properties

+are typed according to the local host locale announcer.

+No encoding conversion is performed prior to storage in the properties.

+</para>

+<para>

+<!-- .LP -->

+For clients that need to process the property text in a locale,

+<function>XmbSetWMProperties</function>

+sets the WM_LOCALE_NAME property to be the name of the current locale.

+The name is assumed to be in the Host Portable Character Encoding

+and is converted to STRING for storage in the property.

+</para>

+<para>

+<!-- .LP -->

+<function>XmbSetWMProperties</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadWindow</function>

+errors.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To set a window's standard window manager properties

+with strings in client-specified encodings, use

+<function>XSetWMProperties</function>.

+The standard window manager properties for a given window are

+WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS,

+WM_COMMAND, and WM_CLIENT_MACHINE.

+<indexterm significance="preferred"><primary>XSetWMProperties</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XSetWMProperties</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XTextProperty<parameter> *window_name</parameter></paramdef>

+  <paramdef>XTextProperty<parameter> *icon_name</parameter></paramdef>

+  <paramdef>char<parameter> **argv</parameter></paramdef>

+  <paramdef>int<parameter> argc</parameter></paramdef>

+  <paramdef>XSizeHints<parameter> *normal_hints</parameter></paramdef>

+  <paramdef>XWMHints<parameter> *wm_hints</parameter></paramdef>

+  <paramdef>XClassHint<parameter> *class_hints</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>window_name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window name,

+which should be a null-terminated string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>icon_name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the icon name,

+which should be a null-terminated string.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>argv</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the application's argument list.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>argc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of arguments.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>normal_hints</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the size hints for the window in its normal state.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>wm_hints</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the

+<function>XWMHints</function>

+structure to be used.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>class_hints</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the

+<function>XClassHint</function>

+structure to be used.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XSetWMProperties </function>

+convenience function provides a single programming interface 

+for setting those essential window properties that are used 

+for communicating with other clients (particularly window and session

+managers).

+</para>

+<para>

+<!-- .LP -->

+If the window_name argument is non-NULL, 

+<function>XSetWMProperties</function>

+calls

+<function>XSetWMName</function>,

+which, in turn, sets the WM_NAME property (see section 14.1.4).

+If the icon_name argument is non-NULL,

+<function>XSetWMProperties</function>

+calls

+<function>XSetWMIconName</function>,

+which sets the WM_ICON_NAME property (see section 14.1.5).

+If the argv argument is non-NULL, 

+<function>XSetWMProperties</function>

+calls

+<function>XSetCommand</function>,

+which sets the WM_COMMAND property (see section 14.2.1).

+Note that an argc of zero is allowed to indicate a zero-length command.

+Note also that the hostname of this machine is stored using

+<function>XSetWMClientMachine </function>

+(see section 14.2.2).

+</para>

+<para>

+<!-- .LP -->

+If the normal_hints argument is non-NULL, 

+<function>XSetWMProperties</function>

+calls

+<function>XSetWMNormalHints</function>,

+which sets the WM_NORMAL_HINTS property (see section 14.1.7).

+If the wm_hints argument is non-NULL, 

+<function>XSetWMProperties</function>

+calls

+<function>XSetWMHints</function>,

+which sets the WM_HINTS property (see section 14.1.6).

+</para>

+<para>

+<!-- .LP -->

+If the class_hints argument is non-NULL, 

+<function>XSetWMProperties</function>

+calls

+<function>XSetClassHint</function>,

+which sets the WM_CLASS property (see section 14.1.8).

+If the res_name member in the

+<function>XClassHint</function>

+structure is set to the NULL pointer and the RESOURCE_NAME environment 

+variable is set, 

+then the value of the environment variable is substituted for res_name.

+If the res_name member is NULL, 

+the environment variable is not set, 

+and argv and argv[0] are set, 

+then the value of argv[0], stripped of

+any directory prefixes, is substituted for res_name.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetWMProperties</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadWindow</function>

+errors.

+</para>

+</sect2>

+</sect1>

+<sect1 id="Client_to_Session_Manager_Communication">

+<title>Client to Session Manager Communication</title>

+<!-- .XS -->

+<!-- (SN Client to Session Manager Communication -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+This section discusses how to:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Set and read the WM_COMMAND property

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Set and read the WM_CLIENT_MACHINE property

+    </para>

+  </listitem>

+</itemizedlist>

+<sect2 id="Setting_and_Reading_the_WM_COMMAND_Property">

+<title>Setting and Reading the WM_COMMAND Property</title>

+<!-- .XS -->

+<!-- (SN Setting and Reading the WM_COMMAND Property -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to set and read

+the WM_COMMAND property for a given window.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To set a window's WM_COMMAND property, use

+<function>XSetCommand</function>.

+<indexterm significance="preferred"><primary>XSetCommand</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetCommand</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>char<parameter> **argv</parameter></paramdef>

+  <paramdef>int<parameter> argc</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>argv</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the application's argument list.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>argc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of arguments.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetCommand</function>

+function sets the command and arguments used to invoke the

+application.

+(Typically, argv is the argv array of your main program.)

+If the strings are not in the Host Portable Character Encoding,

+the result is implementation-dependent.

+</para>

+<para>

+<!-- .LP -->

+<function>XSetCommand</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadWindow </function>

+errors.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To read a window's WM_COMMAND property, use

+<function>XGetCommand</function>.

+<indexterm significance="preferred"><primary>XGetCommand</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XGetCommand</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>char<parameter> ***argv_return</parameter></paramdef>

+  <paramdef>int<parameter> *argc_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>argv_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the application's argument list.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>argc_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of arguments returned.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XGetCommand </function>

+function reads the WM_COMMAND property from the specified window 

+and returns a string list.

+If the WM_COMMAND property exists, 

+it is of type STRING and format 8.

+If sufficient memory can be allocated to contain the string list, 

+<function>XGetCommand</function>

+fills in the argv_return and argc_return arguments

+and returns a nonzero status.

+Otherwise, it returns a zero status.

+If the data returned by the server is in the Latin Portable Character Encoding,

+then the returned strings are in the Host Portable Character Encoding.

+Otherwise, the result is implementation-dependent.

+To free the memory allocated to the string list, use

+<function>XFreeStringList</function>.

+</para>

+</sect2>

+<sect2 id="Setting_and_Reading_the_WM_CLIENT_MACHINE_Property">

+<title>Setting and Reading the WM_CLIENT_MACHINE Property</title>

+<!-- .XS -->

+<!-- (SN Setting and Reading the WM_CLIENT_MACHINE Property -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to set and read 

+the WM_CLIENT_MACHINE property for a given window.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To set a window's WM_CLIENT_MACHINE property, use

+<function>XSetWMClientMachine</function>.

+<indexterm significance="preferred"><primary>XSetWMClientMachine</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XSetWMClientMachine</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>text_prop</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the

+<function>XTextProperty</function>

+structure to be used.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetWMClientMachine</function>

+convenience function calls

+<function>XSetTextProperty</function>

+to set the WM_CLIENT_MACHINE property.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To read a window's WM_CLIENT_MACHINE property, use

+<function>XGetWMClientMachine</function>.

+<indexterm significance="preferred"><primary>XGetWMClientMachine</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XGetWMClientMachine</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>text_prop_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the

+<function>XTextProperty</function>

+structure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetWMClientMachine</function>

+convenience function performs an 

+<function>XGetTextProperty </function>

+on the WM_CLIENT_MACHINE property.

+It returns a nonzero status on success;

+otherwise, it returns a zero status.

+</para>

+</sect2>

+</sect1>

+<sect1 id="Standard_Colormaps">

+<title>Standard Colormaps</title>

+<!-- .XS -->

+<!-- (SN Standard Colormaps  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Applications with color palettes, smooth-shaded drawings, or digitized

+images demand large numbers of colors.  

+In addition, these applications often require an efficient mapping 

+from color triples to pixel values that display the appropriate colors.

+</para>

+<para>

+<!-- .LP -->

+As an example, consider a three-dimensional display program that wants 

+to draw a smoothly shaded sphere.  

+At each pixel in the image of the sphere, 

+the program computes the intensity and color of light

+reflected back to the viewer.  

+The result of each computation is a triple of red, green, and blue (<acronym>RGB</acronym>)

+coefficients in the range 0.0 to 1.0.  

+To draw the sphere, the program needs a colormap that provides a

+large range of uniformly distributed colors.  

+The colormap should be arranged so that the program can

+convert its <acronym>RGB</acronym> triples into pixel values very quickly,

+because drawing the entire sphere requires many such

+conversions.

+</para>

+<para>

+<!-- .LP -->

+On many current workstations,

+the display is limited to 256 or fewer colors.  

+Applications must allocate colors carefully, 

+not only to make sure they cover the entire range they need 

+but also to make use of as many of the available colors as possible.

+On a typical X display, 

+many applications are active at once.

+Most workstations have only one hardware look-up table for colors,

+so only one application colormap can be installed at a given time.

+The application using the installed colormap is displayed correctly, 

+and the other applications go technicolor and are

+displayed with false colors.

+</para>

+<para>

+<!-- .LP -->

+As another example, consider a user who is running an 

+image processing program to display earth-resources data.  

+The image processing program needs a colormap set up with 8 reds, 

+8 greens, and 4 blues, for a total of 256 colors.

+Because some colors are already in use in the default colormap, 

+the image processing program allocates and installs a new colormap.

+</para>

+<para>

+<!-- .LP -->

+The user decides to alter some of the colors in the image

+by invoking a color palette program to mix and choose colors.

+The color palette program also needs a

+colormap with eight reds, eight greens, and four blues, so just like

+the image processing program, it must allocate and

+install a new colormap.

+</para>

+<para>

+<!-- .LP -->

+Because only one colormap can be installed at a time,

+the color palette may be displayed incorrectly

+whenever the image processing program is active.

+Conversely, whenever the palette program is active, 

+the image may be displayed incorrectly.  

+The user can never match or compare colors in the palette and image.

+Contention for colormap resources can be reduced if applications

+with similar color needs share colormaps.

+</para>

+<para>

+<!-- .LP -->

+The image processing program and the color palette program 

+could share the same colormap if there existed a convention that described

+how the colormap was set up.  

+Whenever either program was active, 

+both would be displayed correctly.

+</para>

+<para>

+<!-- .LP -->

+The standard colormap properties define a set of commonly used

+colormaps.  

+Applications that share these colormaps and conventions display 

+true colors more often and provide a better interface to the user.

+</para>

+<para>

+<!-- .LP -->

+Standard colormaps allow applications to share commonly used color

+resources.  

+This allows many applications to be displayed in true colors

+simultaneously, even when each application needs an entirely filled

+colormap.

+</para>

+<para>

+<!-- .LP -->

+Several standard colormaps are described in this section.

+Usually, a window manager creates these colormaps.

+Applications should use the standard colormaps if they already exist.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To allocate an

+<function>XStandardColormap</function>

+structure, use

+<function>XAllocStandardColormap</function>.

+</para>

+

+<para>

+XStandardColormap *XAllocStandardColormap()

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XAllocStandardColormap</function>

+function allocates and returns a pointer to an

+<function>XStandardColormap</function>

+structure.

+Note that all fields in the

+<function>XStandardColormap</function>

+structure are initially set to zero.

+If insufficient memory is available, 

+<function>XAllocStandardColormap</function>

+returns NULL.

+To free the memory allocated to this structure,

+use

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+The 

+<function>XStandardColormap </function>

+structure contains:

+</para>

+<literallayout class="monospaced">

+/* Hints */

+

+#define       ReeaseByFreeingColormap  ((XID)1L)

+

+/* Values */

+

+typedef struct {

+	Colormap colormap;

+	unsigned long red_max;

+	unsigned long red_mult;

+	unsigned long green_max;

+	unsigned long green_mult;

+	unsigned long blue_max;

+	unsigned long blue_mult;

+	unsigned long base_pixel;

+	VisualID visualid;

+	XID killid;

+} XStandardColormap;

+</literallayout>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The colormap member is the colormap created by the

+<function>XCreateColormap</function>

+function.

+The red_max, green_max, and blue_max members give the maximum

+red, green, and blue values, respectively.  

+Each color coefficient ranges from zero to its max, inclusive.  

+For example,

+a common colormap allocation is 3/3/2 (3 planes for red, 3

+planes for green, and 2 planes for blue).  

+This colormap would have red_max = 7, green_max = 7, 

+and blue_max = 3.  

+An alternate allocation that uses only 216 colors is red_max = 5, 

+green_max = 5, and blue_max = 5.

+</para>

+<para>

+<!-- .LP -->

+The red_mult, green_mult, and blue_mult members give the

+scale factors used to compose a full pixel value. 

+(See the discussion of the base_pixel members for further information.)

+For a 3/3/2 allocation, red_mult might be 32,

+green_mult might be 4, and blue_mult might be 1.  

+For a 6-colors-each allocation, red_mult might be 36, 

+green_mult might be 6, and blue_mult might be 1.

+</para>

+<para>

+<!-- .LP -->

+The base_pixel member gives the base pixel value used to

+compose a full pixel value.  

+Usually, the base_pixel is obtained from a call to the 

+<function>XAllocColorPlanes</function>

+function.  

+Given integer red, green, and blue coefficients in their appropriate 

+ranges, one then can compute a corresponding pixel value by

+using the following expression:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA .5i 1.5i -->

+<!-- .ta .5i 1.5i -->

+(r * red_mult + g * green_mult + b * blue_mult + base_pixel) &amp; 0xFFFFFFFF

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+For 

+<function>GrayScale</function>

+colormaps, 

+only the colormap, red_max, red_mult, 

+and base_pixel members are defined. 

+The other members are ignored.  

+To compute a 

+<function>GrayScale </function>

+pixel value, use the following expression:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA .5i 1.5i -->

+<!-- .ta .5i 1.5i -->

+(gray * red_mult + base_pixel) &amp; 0xFFFFFFFF

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+Negative multipliers can be represented by converting the 2's

+complement representation of the multiplier into an unsigned long and

+storing the result in the appropriate _mult field.

+The step of masking by 0xFFFFFFFF effectively converts the resulting

+positive multiplier into a negative one.

+The masking step will take place automatically on many machine architectures,

+depending on the size of the integer type used to do the computation.

+</para>

+<para>

+<!-- .LP -->

+The visualid member gives the ID number of the visual from which the

+colormap was created.

+The killid member gives a resource ID that indicates whether

+the cells held by this standard colormap are to be released 

+by freeing the colormap ID or by calling the

+<function>XKillClient</function>

+function on the indicated resource.

+(Note that this method is necessary for allocating out of an existing colormap.)

+</para>

+<para>

+<!-- .LP -->

+The properties containing the 

+<function>XStandardColormap </function>

+information have 

+the type RGB_COLOR_MAP.

+</para>

+<para>

+<!-- .LP -->

+The remainder of this section discusses standard colormap properties and atoms

+as well as how to manipulate standard colormaps.

+</para>

+<sect2 id="Standard_Colormap_Properties_and_Atoms">

+<title>Standard Colormap Properties and Atoms</title>

+<!-- .XS -->

+<!-- (SN Standard Colormap Properties and Atoms  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Standard Colormaps</primary></indexterm>

+<indexterm><primary>Colormaps</primary><secondary>standard</secondary></indexterm>

+Several standard colormaps are available.  

+Each standard colormap is defined by a property, 

+and each such property is identified by an atom.  

+The following list names the atoms and describes the colormap

+associated with each one.

+The

+<!-- .hN X11/Xatom.h -->

+header file contains the definitions for each of the following atoms,

+which are prefixed with XA_.

+</para>

+

+

+

+<variablelist>

+  <varlistentry>

+    <term>RGB_DEFAULT_MAP</term>

+    <listitem>

+      <para>

+This atom names a property.

+The value of the property is an array of

+<function>XStandardColormap</function>

+structures.

+Each entry in the array describes an <acronym>RGB</acronym> subset of the default color

+map for the Visual specified by visual_id.

+      </para>

+      <para>

+Some applications only need a few <acronym>RGB</acronym> colors and

+may be able to allocate them from the system default colormap.

+This is the ideal situation because the fewer colormaps that are

+active in the system the more applications are displayed

+with correct colors at all times.

+      </para>

+      <para>

+A typical allocation for the RGB_DEFAULT_MAP on 8-plane displays

+is 6 reds, 6 greens, and 6 blues.  

+This gives 216 uniformly distributed colors 

+(6 intensities of 36 different hues) and still leaves 40 elements 

+of a 256-element colormap available for special-purpose colors 

+for text, borders, and so on.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>RGB_BEST_MAP</term>

+    <listitem>

+      <para>

+This atom names a property.  The value of the property is an 

+<function>XStandardColormap</function>.

+      </para>

+      <para>

+The property defines the best <acronym>RGB</acronym> colormap available on

+the screen.

+(Of course, this is a subjective evaluation.)

+Many image processing and three-dimensional applications need to

+use all available colormap cells and to distribute as many

+perceptually distinct colors as possible over those cells.

+This implies that there may be more green values available than

+red, as well as more green or red than blue.

+      </para>

+      <para>

+For an 8-plane 

+<function>PseudoColor </function>

+visual, 

+RGB_BEST_MAP is likely to be a 3/3/2 allocation.  

+For a 24-plane 

+<function>DirectColor </function>

+visual, 

+RGB_BEST_MAP is normally an 8/8/8 allocation.  

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>RGB_RED_MAP,RGB_GREEN_MAP,RGB_BLUE_MAP</term>

+    <listitem>

+      <para>

+These atoms name properties.

+The value of each property is an

+<function>XStandardColormap</function>.

+      </para>

+      <para>

+The properties define all-red, all-green, and all-blue

+colormaps, respectively.  

+These maps are used by applications that want to make color-separated 

+images.  

+For example, a user might generate a full-color image 

+on an 8-plane display both by rendering an image three times 

+(once with high color resolution in red, once with green, 

+and once with blue) and by multiply exposing a single frame in a camera.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry> 

+    <term>RGB_GRAY_MAP</term>

+    <listitem>

+      <para>

+This atom names a property.

+The value of the property is an 

+<function>XStandardColormap</function>.

+      </para>

+      <para>

+The property describes the best 

+<function>GrayScale </function>

+colormap available on the screen.  

+As previously mentioned, 

+only the colormap, red_max, red_mult, and base_pixel members of the

+<function>XStandardColormap </function>

+structure are used for 

+<function>GrayScale </function>

+colormaps.

+      </para>

+    </listitem>

+  </varlistentry>

+</variablelist>

+

+</sect2>

+

+<sect2 id="Setting_and_Obtaining_Standard_Colormaps">

+<title>Setting and Obtaining Standard Colormaps</title>

+<!-- .XS -->

+<!-- (SN Setting and Obtaining Standard Colormaps -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to set and obtain an

+<function>XStandardColormap</function>

+structure.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To set an

+<function>XStandardColormap</function>

+structure, use

+<function>XSetRGBColormaps</function>.

+<indexterm significance="preferred"><primary>XSetRGBColormaps</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void<function> XSetRGBColormaps</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XStandardColormap<parameter> *std_colormap</parameter></paramdef>

+  <paramdef>int<parameter> count</parameter></paramdef>

+  <paramdef>Atom<parameter> property</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>std_colormap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the

+<function>XStandardColormap</function>

+structure to be used.

+<!-- .ds Cn colormaps -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>count</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of (Cn.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>property</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the property name.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XSetRGBColormaps </function>

+function replaces the <acronym>RGB</acronym> colormap definition in the specified property 

+on the named window.

+If the property does not already exist,

+<function>XSetRGBColormaps</function>

+sets the <acronym>RGB</acronym> colormap definition in the specified property

+on the named window.

+The property is stored with a type of RGB_COLOR_MAP and a format of 32.

+Note that it is the caller's responsibility to honor the <acronym>ICCCM</acronym>

+restriction that only RGB_DEFAULT_MAP contain more than one definition.

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XSetRGBColormaps</function>

+function usually is only used by window or session managers.

+To create a standard colormap, 

+follow this procedure:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Open a new connection to the same server.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Grab the server.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+See if the property is on the property list of the root window for the screen.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If the desired property is not present:

+<!-- .RS -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Create a colormap (unless you are using the default colormap of the screen).

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Determine the color characteristics of the visual.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Allocate cells in the colormap (or create it with

+<function>AllocAll</function>).

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Call 

+<function>XStoreColors</function>

+to store appropriate color values in the colormap.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Fill in the descriptive members in the 

+<function>XStandardColormap</function>

+structure.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Attach the property to the root window.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Use

+<function>XSetCloseDownMode</function>

+to make the resource permanent.

+<!-- .RE -->

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Ungrab the server.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+<function>XSetRGBColormaps</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadAtom</function>,

+and

+<function>BadWindow</function>

+errors.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To obtain the 

+<function>XStandardColormap </function>

+structure associated with the specified property, use

+<function>XGetRGBColormaps</function>.

+<indexterm significance="preferred"><primary>XGetRGBColormaps</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status<function> XGetRGBColormaps</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Window<parameter> w</parameter></paramdef>

+  <paramdef>XStandardColormap<parameter> **std_colormap_return</parameter></paramdef>

+  <paramdef>int<parameter> *count_return</parameter></paramdef>

+  <paramdef>Atom<parameter> property</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>w</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the window.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>std_colormap_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the

+<function>XStandardColormap</function>

+structure.

+<!-- .ds Cn colormaps -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>count_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of (Cn.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>property</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the property name.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XGetRGBColormaps</function>

+function returns the <acronym>RGB</acronym> colormap definitions stored 

+in the specified property on the named window.

+If the property exists, is of type RGB_COLOR_MAP, is of format 32, 

+and is long enough to contain a colormap definition,

+<function>XGetRGBColormaps</function>

+allocates and fills in space for the returned colormaps

+and returns a nonzero status.

+If the visualid is not present, 

+<function>XGetRGBColormaps </function>

+assumes the default visual for the screen on which the window is located; 

+if the killid is not present, 

+<function>None</function>

+is assumed, which indicates that the resources cannot be released.

+Otherwise, 

+none of the fields are set, and 

+<function>XGetRGBColormaps</function>

+returns a zero status.

+Note that it is the caller's responsibility to honor the <acronym>ICCCM</acronym>

+restriction that only RGB_DEFAULT_MAP contain more than one definition.

+</para>

+<para>

+<!-- .LP -->

+<function>XGetRGBColormaps</function>

+can generate

+<function>BadAtom</function>

+and

+<function>BadWindow</function>

+errors.

+<!-- .bp -->

+

+</para>

+</sect2>

+</sect1>

+</chapter>

diff --git a/libX11/specs/libX11/CH15 b/libX11/specs/libX11/CH15
deleted file mode 100644
index a10df0a53..000000000
--- a/libX11/specs/libX11/CH15
+++ /dev/null
@@ -1,1628 +0,0 @@
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-.\" OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" Except as contained in this notice, the name of the X Consortium shall
-.\" not be used in advertising or otherwise to promote the sale, use or
-.\" other dealings in this Software without prior written authorization
-.\" from the X Consortium.
-.\"
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
-.\" Digital Equipment Corporation
-.\"
-.\" Portions Copyright \(co 1990, 1991 by
-.\" Tektronix, Inc.
-.\"
-.\" Permission to use, copy, modify and distribute this documentation for
-.\" any purpose and without fee is hereby granted, provided that the above
-.\" copyright notice appears in all copies and that both that copyright notice
-.\" and this permission notice appear in all copies, and that the names of
-.\" Digital and Tektronix not be used in in advertising or publicity pertaining
-.\" to this documentation without specific, written prior permission.
-.\" Digital and Tektronix makes no representations about the suitability
-.\" of this documentation for any purpose.
-.\" It is provided ``as is'' without express or implied warranty.
-.\" 
-\&
-.sp 1
-.ce 3
-\s+1\fBChapter 15\fP\s-1
-
-\s+1\fBResource Manager Functions\fP\s-1
-.sp 2
-.nr H1 15
-.nr H2 0
-.nr H3 0
-.nr H4 0
-.nr H5 0
-.na
-.LP
-.XS
-Chapter 15: Resource Manager Functions
-.XE
-A program often needs a variety of options in the X environment
-(for example, fonts, colors, icons, and cursors).
-Specifying all of these options on the command line is awkward
-because users may want to customize many aspects of the program
-and need a convenient way to establish these customizations as
-the default settings.
-The resource manager is provided for this purpose.
-Resource specifications are usually stored in human-readable files
-and in server properties.
-.LP
-The resource manager is a database manager with a twist.
-In most database systems, 
-you perform a query using an imprecise specification,
-and you get back a set of records.
-The resource manager, however, allows you to specify a large
-set of values with an imprecise specification, to query the database 
-with a precise specification, and to get back only a single value.
-This should be used by applications that need to know what the
-user prefers for colors, fonts, and other resources.
-It is this use as a database for dealing with X resources that
-inspired the name ``Resource Manager,''
-although the resource manager can be and is used in other ways.
-.LP
-For example, 
-a user of your application may want to specify 
-that all windows should have a blue background 
-but that all mail-reading windows should have a red background.
-With well-engineered and coordinated applications,
-a user can define this information using only two lines of specifications.
-.LP
-As an example of how the resource manager works,
-consider a mail-reading application called xmh.
-Assume that it is designed so that it uses a
-complex window hierarchy all the way down to individual command buttons,
-which may be actual small subwindows in some toolkits.
-These are often called objects or widgets.
-In such toolkit systems,
-each user interface object can be composed of other objects
-and can be assigned a name and a class.
-Fully qualified names or classes can have arbitrary numbers of component names,
-but a fully qualified name always has the same number of component names as a
-fully qualified class.
-This generally reflects the structure of the application as composed
-of these objects, starting with the application itself.
-.LP
-For example, the xmh mail program has a name ``xmh'' and is one
-of a class of ``Mail'' programs.
-By convention, the first character of class components is capitalized,
-and the first letter of name components is in lowercase.
-Each name and class finally has an attribute
-(for example, ``foreground'' or ``font'').
-If each window is properly assigned a name and class,
-it is easy for the user to specify attributes of any portion 
-of the application.
-.LP
-At the top level, 
-the application might consist of a paned window (that is, a window divided
-into several sections) named ``toc''.
-One pane of the paned window is a button box window named ``buttons''
-and is filled with command buttons. 
-One of these command buttons is used to incorporate
-new mail and has the name ``incorporate''.
-This window has a fully qualified name, ``xmh.toc.buttons.incorporate'',
-and a fully qualified class, ``Xmh.Paned.Box.Command''.
-Its fully qualified name is the name of its parent, ``xmh.toc.buttons'', 
-followed by its name, ``incorporate''.
-Its class is the class of its parent, ``Xmh.Paned.Box'', 
-followed by its particular class, ``Command''.  
-The fully qualified name of a resource is
-the attribute's name appended to the object's fully qualified
-name, and the fully qualified class is its class appended to the object's
-class.
-.LP
-The incorporate button might need the following resources: 
-Title string,
-Font,
-Foreground color for its inactive state,
-Background color for its inactive state,
-Foreground color for its active state, and
-Background color for its active state.
-Each resource is considered
-to be an attribute of the button and, as such, has a name and a class.
-For example, the foreground color for the button in
-its active state might be named ``activeForeground'',
-and its class might be ``Foreground''.
-.LP
-When an application looks up a resource (for example, a color),
-it passes the complete name and complete class of the resource
-to a look-up routine.
-The resource manager compares this complete specification
-against the incomplete specifications of entries in the resource
-database, finds the best match, and returns the corresponding
-value for that entry.
-.LP
-The definitions for the resource manager are contained in
-.hN X11/Xresource.h .
-.NH 2
-Resource File Syntax
-.XS
-\*(SN Resource File Syntax
-.XE
-.LP
-The syntax of a resource file is a sequence of resource lines
-terminated by newline characters or the end of the file.
-The syntax of an individual resource line is:
-.LP
-.\" Start marker code here
-.Ds 0
-.TA 1.5i 1.75i
-.ta 1.5i 1.75i
-ResourceLine	=	Comment | IncludeFile | ResourceSpec | <empty line>
-Comment	=	"!" {<any character except null or newline>}
-IncludeFile	=	"#" WhiteSpace "include" WhiteSpace FileName WhiteSpace
-FileName	=	<valid filename for operating system>
-ResourceSpec	=	WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value
-ResourceName	=	[Binding] {Component Binding} ComponentName
-Binding	=	"\&." | "*"
-WhiteSpace	=	{<space> | <horizontal tab>}
-Component	=	"?" | ComponentName
-ComponentName	=	NameChar {NameChar}
-NameChar	=	"a"\-"z" | "A"\-"Z" | "0"\-"9" | "_" | "-"
-Value	=	{<any character except null or unescaped newline>}
-.De
-.\" End marker code here
-.LP
-Elements separated by vertical bar (|) are alternatives.
-Curly braces ({\&.\&.\&.}) indicate zero or more repetitions
-of the enclosed elements.
-Square brackets ([\&.\&.\&.]) indicate that the enclosed element is optional.
-Quotes ("\&.\&.\&.") are used around literal characters.
-.LP
-IncludeFile lines are interpreted by replacing the line with the
-contents of the specified file.
-The word ``include'' must be in lowercase.
-The file name is interpreted relative to the directory of the file in
-which the line occurs (for example, if the file name contains no
-directory or contains a relative directory specification).
-.LP
-If a ResourceName contains a contiguous sequence of two or more Binding
-characters, the sequence will be replaced with a single ``\&.'' character
-if the sequence contains only ``\&.'' characters;
-otherwise, the sequence will be replaced with a single ``*'' character.
-.LP
-A resource database never contains more than one entry for a given
-ResourceName.  If a resource file contains multiple lines with the
-same ResourceName, the last line in the file is used.
-.LP
-Any white space characters before or after the name or colon in a ResourceSpec
-are ignored.
-To allow a Value to begin with white space,
-the two-character sequence ``\^\\\^\fIspace\fP'' (backslash followed by space)
-is recognized and replaced by a space character,
-and the two-character sequence ``\^\\\^\fItab\fP''
-(backslash followed by horizontal tab)
-is recognized and replaced by a horizontal tab character.
-To allow a Value to contain embedded newline characters,
-the two-character sequence ``\^\\\^n'' is recognized and replaced by a
-newline character.
-To allow a Value to be broken across multiple lines in a text file,
-the two-character sequence ``\^\\\^\fInewline\fP''
-(backslash followed by newline) is
-recognized and removed from the value.
-To allow a Value to contain arbitrary character codes,
-the four-character sequence ``\^\\\^\fInnn\fP'',
-where each \fIn\fP is a digit character in the range of ``0''\^\-``7'',
-is recognized and replaced with a single byte that contains
-the octal value specified by the sequence.
-Finally, the two-character sequence ``\^\\\\'' is recognized
-and replaced with a single backslash.
-.LP
-As an example of these sequences,
-the following resource line contains a value consisting of four
-characters: a backslash, a null, a ``z'', and a newline:
-.Ds 
-magic.values: \\\\\\\^000\^\\
-z\\\^n
-.De
-.NH 2
-Resource Manager Matching Rules
-.XS
-\*(SN Resource Manager Matching Rules
-.XE
-.LP
-The algorithm for determining which resource database entry
-matches a given query is the heart of the resource manager.
-All queries must fully specify the name and class of the desired resource
-(use of the characters ``*'' and ``?'' is not permitted).
-The library supports up to 100 components in a full name or class.
-Resources are stored in the database with only partially specified
-names and classes, using pattern matching constructs.
-An asterisk (*) is a loose binding and is used to represent any number
-of intervening components, including none.
-A period (.) is a tight binding and is used to separate immediately
-adjacent components.
-A question mark (?) is used to match any single component name or class.
-A database entry cannot end in a loose binding;
-the final component (which cannot be the character ``?'') must be specified.
-The lookup algorithm searches the database for the entry that most
-closely matches (is most specific for) the full name and class being queried.
-When more than one database entry matches the full name and class,
-precedence rules are used to select just one.
-.LP
-The full name and class are scanned from left to right (from highest
-level in the hierarchy to lowest), one component at a time.
-At each level, the corresponding component and/or binding of each
-matching entry is determined, and these matching components and
-bindings are compared according to precedence rules.
-Each of the rules is applied at each level before moving to the next level,
-until a rule selects a single entry over all others.
-The rules, in order of precedence, are:
-.IP 1. 5
-An entry that contains a matching component (whether name, class,
-or the character ``?'')
-takes precedence over entries that elide the level (that is, entries
-that match the level in a loose binding).
-.IP 2. 5
-An entry with a matching name takes precedence over both
-entries with a matching class and entries that match using the character ``?''.
-An entry with a matching class takes precedence over
-entries that match using the character ``?''.
-.IP 3. 5
-An entry preceded by a tight binding takes precedence over entries
-preceded by a loose binding.
-.LP
-To illustrate these rules,
-consider the following resource database entries:
-.Ds 
-.TA 2.5i 3.5i
-.ta 2.5i 3.5i
-xmh*Paned*activeForeground:	red	\fI(entry A)\fP
-*incorporate.Foreground:	blue	\fI(entry B)\fP
-xmh.toc*Command*activeForeground:	green	\fI(entry C)\fP
-xmh.toc*?.Foreground:	white	\fI(entry D)\fP
-xmh.toc*Command.activeForeground:	black	\fI(entry E)\fP
-.De
-.LP
-Consider a query for the resource:
-.LP
-.Ds 
-.TA 3.5i
-.ta 3.5i
-xmh.toc.messagefunctions.incorporate.activeForeground	\fI(name)\fP
-Xmh.Paned.Box.Command.Foreground	\fI(class)\fP
-.De
-.LP
-At the first level (xmh, Xmh), rule 1 eliminates entry B.
-At the second level (toc, Paned), rule 2 eliminates entry A.
-At the third level (messagefunctions, Box), no entries are eliminated.
-At the fourth level (incorporate, Command), rule 2 eliminates entry D.
-At the fifth level (activeForeground, Foreground), rule 3 eliminates entry C.
-.NH 2
-Quarks
-.XS
-\*(SN Quarks
-.XE
-.LP
-Most uses of the resource manager involve defining names,
-classes, and representation types as string constants.
-However, always referring to strings in the resource manager can be slow,
-because it is so heavily used in some toolkits.
-To solve this problem, 
-a shorthand for a string is used in place of the string
-in many of the resource manager functions.
-Simple comparisons can be performed rather than string comparisons.
-The shorthand name for a string is called a quark and is the
-type 
-.PN XrmQuark .
-On some occasions,
-you may want to allocate a quark that has no string equivalent.
-.LP
-A quark is to a string what an atom is to a string in the server,
-but its use is entirely local to your application.
-.LP
-.sp
-To allocate a new quark, use
-.PN XrmUniqueQuark .
-.IN "XrmUniqueQuark" "" "@DEF@"
-.sM
-.FD 0
-XrmQuark XrmUniqueQuark\^(\|)
-.FN
-.LP
-.eM
-The
-.PN XrmUniqueQuark
-function allocates a quark that is guaranteed not to represent any string that
-is known to the resource manager.
-.LP
-.sp
-Each name, class, and representation type is typedef'd as an
-.PN XrmQuark .
-.LP
-.sM
-.Ds 0
-typedef int XrmQuark, *XrmQuarkList;
-typedef XrmQuark XrmName;
-typedef XrmQuark XrmClass;
-typedef XrmQuark XrmRepresentation;
-#define NULLQUARK ((XrmQuark) 0)
-.De
-.LP
-.eM
-Lists are represented as null-terminated arrays of quarks.
-The size of the array must be large enough for the number of components used.
-.LP
-.sM
-.Ds 0
-typedef XrmQuarkList XrmNameList;
-typedef XrmQuarkList XrmClassList;
-.De
-.LP
-.eM
-.sp
-To convert a string to a quark, use
-.PN XrmStringToQuark
-or
-.PN XrmPermStringToQuark .
-.IN "XrmStringToQuark" "" "@DEF@"
-.IN "XrmPermStringToQuark" "" "@DEF@"
-.sM
-.FD 0
-#define XrmStringToName(string) XrmStringToQuark(string)
-#define XrmStringToClass(string) XrmStringToQuark(string)
-#define XrmStringToRepresentation(string) XrmStringToQuark(string)
-.sp
-XrmQuark XrmStringToQuark\^(\^\fIstring\fP\^)
-.br
-     char *\fIstring\fP\^;
-.sp
-XrmQuark XrmPermStringToQuark\^(\^\fIstring\fP\^)
-.br
-     char *\fIstring\fP\^;
-.FN
-.ds Ql
-.IP \fIstring\fP 1i
-Specifies the string for which a quark\*(Ql is to be allocated.
-.LP
-.eM
-These functions can be used to convert from string to quark representation.
-If the string is not in the Host Portable Character Encoding,
-the conversion is implementation-dependent.
-The string argument to
-.PN XrmStringToQuark
-need not be permanently allocated storage.
-.PN XrmPermStringToQuark
-is just like
-.PN XrmStringToQuark ,
-except that Xlib is permitted to assume the string argument is permanently
-allocated,
-and, hence, that it can be used as the value to be returned by
-.PN XrmQuarkToString .
-.LP
-For any given quark, if
-.PN XrmStringToQuark
-returns a non-NULL value,
-all future calls will return the same value (identical address).
-.LP
-.sp
-To convert a quark to a string, use 
-.PN XrmQuarkToString .
-.IN "XrmQuarkToString" "" "@DEF@"
-.sM
-.FD 0
-#define XrmNameToString(name) XrmQuarkToString(name)
-#define XrmClassToString(class) XrmQuarkToString(class)
-#define XrmRepresentationToString(type) XrmQuarkToString(type)
-.sp
-char *XrmQuarkToString\^(\^\fIquark\fP\^)
-.br
-     XrmQuark \fIquark\fP\^;
-.FN
-.IP \fIquark\fP 1i
-Specifies the quark for which the equivalent string is desired.
-.LP
-.eM
-These functions can be used to convert from quark representation to string.
-The string pointed to by the return value must not be modified or freed.
-The returned string is byte-for-byte equal to the original
-string passed to one of the string-to-quark routines.
-If no string exists for that quark,
-.PN XrmQuarkToString
-returns NULL.
-For any given quark, if
-.PN XrmQuarkToString
-returns a non-NULL value,
-all future calls will return the same value (identical address).
-.LP
-.sp
-To convert a string with one or more components to a quark list, use
-.PN XrmStringToQuarkList .
-.IN "XrmStringToQuarkList" "" "@DEF@"
-.sM
-.FD 0
-#define XrmStringToNameList(str, name)  XrmStringToQuarkList((str), (name))
-#define XrmStringToClassList(str, class) XrmStringToQuarkList((str), (class))
-.sp
-void XrmStringToQuarkList\^(\^\fIstring\fP, \fIquarks_return\fP\^)
-.br
-     char *\fIstring\fP\^;
-.br
-     XrmQuarkList \fIquarks_return\fP\^;
-.FN
-.ds Ql \ list
-.IP \fIstring\fP 1i
-Specifies the string for which a quark\*(Ql is to be allocated.
-.IP \fIquarks_return\fP 1i
-Returns the list of quarks.
-The caller must allocate sufficient space for the quarks list before calling 
-.PN XrmStringToQuarkList .
-.LP
-.eM
-The
-.PN XrmStringToQuarkList
-function converts the null-terminated string (generally a fully qualified name)
-to a list of quarks.
-Note that the string must be in the valid ResourceName format 
-(see section 15.1).
-If the string is not in the Host Portable Character Encoding,
-the conversion is implementation-dependent.
-.LP
-A binding list is a list of type
-.PN XrmBindingList
-and indicates if components of name or class lists are bound tightly or loosely
-(that is, if wildcarding of intermediate components is specified).
-.LP
-.Ds 0
-typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList;
-.De
-.LP
-.PN XrmBindTightly
-indicates that a period separates the components, and
-.PN XrmBindLoosely
-indicates that an asterisk separates the components.
-.LP
-.sp
-To convert a string with one or more components to a binding list
-and a quark list, use
-.PN XrmStringToBindingQuarkList .
-.IN "XrmStringToBindingQuarkList" "" "@DEF@"
-.sM
-.FD 0
-XrmStringToBindingQuarkList\^(\^\fIstring\fP, \fIbindings_return\fP, \
-\fIquarks_return\fP\^)
-.br
-     char *\fIstring\fP\^;
-.br
-     XrmBindingList \fIbindings_return\fP\^;
-.br
-     XrmQuarkList \fIquarks_return\fP\^;
-.FN
-.ds Ql \ list
-.IP \fIstring\fP 1i
-Specifies the string for which a quark\*(Ql is to be allocated.
-.IP \fIbindings_return\fP 1i
-Returns the binding list.
-The caller must allocate sufficient space for the binding list before calling 
-.PN XrmStringToBindingQuarkList .
-.IP \fIquarks_return\fP 1i
-Returns the list of quarks.
-The caller must allocate sufficient space for the quarks list before calling 
-.PN XrmStringToBindingQuarkList .
-.LP
-.eM
-Component names in the list are separated by a period or 
-an asterisk character.
-The string must be in the format of a valid ResourceName (see section 15.1).
-If the string does not start with a period or an asterisk, 
-a tight binding is assumed.
-For example, the string ``*a.b*c'' becomes:
-.LP
-.Ds 0
-.TA .75i 1.5i 2.25i
-.ta .75i 1.5i 2.25i
-quarks:	a	b	c
-bindings:	loose	tight	loose
-.De
-.NH 2
-Creating and Storing Databases
-.XS
-\*(SN Creating and Storing Databases
-.XE
-.LP
-.IN "XrmDatabase" "" "@DEF@"
-A resource database is an opaque type,
-.PN XrmDatabase .
-Each database value is stored in an
-.PN XrmValue 
-structure.
-This structure consists of a size, an address, and a representation type.
-The size is specified in bytes.
-The representation type is a way for you to store data tagged by some 
-application-defined type (for example, the strings ``font'' or ``color'').
-It has nothing to do with the C data type or with its class. 
-The
-.PN XrmValue 
-structure is defined as:
-.LP
-.IN "XrmValue" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	unsigned int size;
-	XPointer addr;
-} XrmValue, *XrmValuePtr;
-.De
-.LP
-.eM
-.sp
-To initialize the resource manager, use
-.PN XrmInitialize .
-.IN "XrmInitialize" "" "@DEF@"
-.sM
-.FD 0
-void XrmInitialize\^(\|);
-.FN
-.LP
-.eM
-To retrieve a database from disk, use
-.PN XrmGetFileDatabase .
-.IN "XrmGetFileDatabase" "" "@DEF@"
-.sM
-.FD 0
-XrmDatabase XrmGetFileDatabase\^(\^\fIfilename\fP\^)
-.br
-     char *\fIfilename\fP\^;
-.FN
-.IP \fIfilename\fP 1i
-Specifies the resource database file name.
-.LP
-.eM
-The
-.PN XrmGetFileDatabase
-function opens the specified file,
-creates a new resource database, and loads it with the specifications
-read in from the specified file.
-The specified file should contain a sequence of entries in valid ResourceLine
-format (see section 15.1); the database that results from reading a file
-with incorrect syntax is implementation-dependent.
-The file is parsed in the current locale, 
-and the database is created in the current locale.
-If it cannot open the specified file,
-.PN XrmGetFileDatabase
-returns NULL.
-.LP
-.sp
-To store a copy of a database to disk, use
-.PN XrmPutFileDatabase .
-.IN "XrmPutFileDatabase" "" "@DEF@"
-.sM
-.FD 0
-void XrmPutFileDatabase\^(\^\fIdatabase\fP, \fIstored_db\fP\^)
-.br
-     XrmDatabase \fIdatabase\fP\^;
-.br
-     char *\fIstored_db\fP\^;
-.FN
-.IP \fIdatabase\fP 1i
-Specifies the database that is to be used.
-.IP \fIstored_db\fP 1i
-Specifies the file name for the stored database.
-.LP
-.eM
-The
-.PN XrmPutFileDatabase
-function stores a copy of the specified database in the specified file.
-Text is written to the file as a sequence of entries in valid
-ResourceLine format (see section 15.1).
-The file is written in the locale of the database.
-Entries containing resource names that are not in the Host Portable Character
-Encoding or containing values that are not in the encoding of the database
-locale, are written in an implementation-dependent manner.
-The order in which entries are written is implementation-dependent.
-Entries with representation types other than ``String'' are ignored.
-.LP
-.sp
-To obtain a pointer to the screen-independent resources of a display, use
-.PN XResourceManagerString .
-.IN "XResourceManagerString" "" "@DEF@"
-.sM
-.FD 0
-char *XResourceManagerString\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-The
-.PN XResourceManagerString
-function returns the RESOURCE_MANAGER property from the server's root
-window of screen zero, which was returned when the connection was opened using
-.PN XOpenDisplay .
-The property is converted from type STRING to the current locale.
-The conversion is identical to that produced by 
-.PN XmbTextPropertyToTextList
-for a single element STRING property.
-The returned string is owned by Xlib and should not be freed by the client.
-The property value must be in a format that is acceptable to
-.PN XrmGetStringDatabase .
-If no property exists, NULL is returned.
-.LP
-.sp
-To obtain a pointer to the screen-specific resources of a screen, use
-.PN XScreenResourceString .
-.IN "XScreenResourceString" "" "@DEF@"
-.sM
-.FD 0
-char *XScreenResourceString\^(\^\fIscreen\fP\^)
-.br
-      Screen *\fIscreen\fP\^;
-.FN
-.IP \fIscreen\fP 1i
-Specifies the screen.
-.LP
-.eM
-The
-.PN XScreenResourceString
-function returns the SCREEN_RESOURCES property from the root window of the
-specified screen.
-The property is converted from type STRING to the current locale.
-The conversion is identical to that produced by 
-.PN XmbTextPropertyToTextList
-for a single element STRING property.
-The property value must be in a format that is acceptable to
-.PN XrmGetStringDatabase .
-If no property exists, NULL is returned.
-The caller is responsible for freeing the returned string by using
-.PN XFree .
-.LP
-.sp
-To create a database from a string, use
-.PN XrmGetStringDatabase .
-.IN "XrmGetStringDatabase" "" "@DEF@"
-.sM
-.FD 0
-XrmDatabase XrmGetStringDatabase\^(\^\fIdata\fP\^)
-.br
-     char *\fIdata\fP\^;
-.FN
-.IP \fIdata\fP 1i
-Specifies the database contents using a string.
-.LP
-.eM
-The
-.PN XrmGetStringDatabase
-function creates a new database and stores the resources specified
-in the specified null-terminated string.
-.PN XrmGetStringDatabase
-is similar to
-.PN XrmGetFileDatabase
-except that it reads the information out of a string instead of out of a file.
-The string should contain a sequence of entries in valid ResourceLine
-format (see section 15.1) terminated by a null character;
-the database that results from using a string
-with incorrect syntax is implementation-dependent.
-The string is parsed in the current locale, 
-and the database is created in the current locale.
-.LP
-.sp
-To obtain the locale name of a database, use
-.PN XrmLocaleOfDatabase .
-.IN "XrmLocaleOfDatabase" "" "@DEF@"
-.sM
-.FD 0
-char *XrmLocaleOfDatabase\^(\^\fIdatabase\fP\^)
-.br
-      XrmDatabase \fIdatabase\fP\^;
-.FN
-.IP \fIdatabase\fP 1i
-Specifies the resource database.
-.LP
-.eM
-The
-.PN XrmLocaleOfDatabase
-function returns the name of the locale bound to the specified
-database, as a null-terminated string.
-The returned locale name string is owned by Xlib and should not be
-modified or freed by the client.
-Xlib is not permitted to free the string until the database is destroyed.
-Until the string is freed,
-it will not be modified by Xlib.
-.LP
-.sp
-To destroy a resource database and free its allocated memory, use
-.PN XrmDestroyDatabase .
-.IN "XrmDestroyDatabase" "" "@DEF@"
-.sM
-.FD 0
-void XrmDestroyDatabase\^(\^\fIdatabase\fP\^)
-.br
-      XrmDatabase \fIdatabase\fP\^;
-.FN
-.IP \fIdatabase\fP 1i
-Specifies the resource database.
-.LP
-.eM
-If database is NULL,
-.PN XrmDestroyDatabase
-returns immediately.
-.LP
-.sp
-To associate a resource database with a display, use
-.PN XrmSetDatabase .
-.IN "XrmSetDatabase" "" "@DEF@"
-.sM
-.FD 0
-void XrmSetDatabase\^(\^\fIdisplay\fP\^, \fIdatabase\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XrmDatabase \fIdatabase\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIdatabase\fP 1i
-Specifies the resource database.
-.LP
-.eM
-The
-.PN XrmSetDatabase
-function associates the specified resource database (or NULL)
-with the specified display.
-The database previously associated with the display (if any) is not destroyed.
-A client or toolkit may find this function convenient for retaining a database
-once it is constructed.
-.LP
-.sp
-To get the resource database associated with a display, use
-.PN XrmGetDatabase .
-.IN "XrmGetDatabase" "" "@DEF@"
-.sM
-.FD 0
-XrmDatabase XrmGetDatabase\^(\^\fIdisplay\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.LP
-.eM
-The
-.PN XrmGetDatabase
-function returns the database associated with the specified display.
-It returns NULL if a database has not yet been set.
-.NH 2
-Merging Resource Databases
-.XS
-\*(SN Merging Resource Databases
-.XE
-.LP
-To merge the contents of a resource file into a database, use
-.PN XrmCombineFileDatabase .
-.IN "XrmCombineFileDatabase" "" "@DEF@"
-.sM
-.FD 0
-Status XrmCombineFileDatabase(\^\fIfilename\fP, \fItarget_db\fP, \fIoverride\fP\^)
-.br
-      char *\fIfilename\fP;
-.br
-      XrmDatabase *\fItarget_db\fP\^;
-.br
-      Bool \fIoverride\fP;
-.FN
-.IP \fIfilename\fP 1i
-Specifies the resource database file name.
-.IP \fItarget_db\fP 1i
-Specifies the resource database into which the source 
-database is to be merged.
-.IP \fIoverride\fP 1i
-Specifies whether source entries override target ones.
-.LP
-.eM 
-The
-.PN XrmCombineFileDatabase
-function merges the contents of a resource file into a database.
-If the same specifier is used for an entry in both the file and
-the database,
-the entry in the file will replace the entry in the database
-if override is
-.PN True ;
-otherwise, the entry in the file is discarded.
-The file is parsed in the current locale.
-If the file cannot be read,
-a zero status is returned;
-otherwise, a nonzero status is returned.
-If target_db contains NULL,
-.PN XrmCombineFileDatabase
-creates and returns a new database to it.
-Otherwise, the database pointed to by target_db is not destroyed by the merge.
-The database entries are merged without changing values or types,
-regardless of the locale of the database.
-The locale of the target database is not modified.
-.LP
-.sp
-To merge the contents of one database into another database, use
-.PN XrmCombineDatabase .
-.IN "XrmCombineDatabase" "" "@DEF@"
-.sM
-.FD 0
-void XrmCombineDatabase(\^\fIsource_db\fP, \fItarget_db\fP, \fIoverride\fP\^)
-.br
-      XrmDatabase \fIsource_db\fP, *\fItarget_db\fP\^;
-.br
-      Bool \fIoverride\fP;
-.FN
-.IP \fIsource_db\fP 1i
-Specifies the resource database that is to be merged into the target database.
-.IP \fItarget_db\fP 1i
-Specifies the resource database into which the source 
-database is to be merged.
-.IP \fIoverride\fP 1i
-Specifies whether source entries override target ones.
-.LP
-.eM 
-The
-.PN XrmCombineDatabase
-function merges the contents of one database into another.
-If the same specifier is used for an entry in both databases,
-the entry in the source_db will replace the entry in the target_db
-if override is
-.PN True ;
-otherwise, the entry in source_db is discarded.
-If target_db contains NULL,
-.PN XrmCombineDatabase
-simply stores source_db in it.
-Otherwise, source_db is destroyed by the merge, but the database pointed
-to by target_db is not destroyed.
-The database entries are merged without changing values or types,
-regardless of the locales of the databases.
-The locale of the target database is not modified.
-.LP
-.sp
-To merge the contents of one database into another database with override
-semantics, use
-.PN XrmMergeDatabases .
-.IN "XrmMergeDatabases" "" "@DEF@"
-.sM
-.FD 0
-void XrmMergeDatabases(\^\fIsource_db\fP, \fItarget_db\fP\^)
-.br
-      XrmDatabase \fIsource_db\fP, *\fItarget_db\fP\^;
-.FN
-.IP \fIsource_db\fP 1i
-Specifies the resource database that is to be merged into the target database.
-.IP \fItarget_db\fP 1i
-Specifies the resource database into which the source 
-database is to be merged.
-.LP
-.eM 
-Calling the
-.PN XrmMergeDatabases
-function is equivalent to calling the
-.PN XrmCombineDatabase
-function with an override argument of
-.PN True .
-.NH 2
-Looking Up Resources
-.XS
-\*(SN Looking Up Resources
-.XE
-.LP
-To retrieve a resource from a resource database, use
-.PN XrmGetResource ,
-.PN XrmQGetResource ,
-or
-.PN XrmQGetSearchResource .
-.LP
-.sp
-.IN "XrmGetResource" "" "@DEF@"
-.sM
-.FD 0
-Bool XrmGetResource\^(\^\fIdatabase\fP, \fIstr_name\fP, \fIstr_class\fP, \
-\fIstr_type_return\fP, \fIvalue_return\fP\^)
-.br
-     XrmDatabase \fIdatabase\fP\^;
-.br
-     char *\fIstr_name\fP\^;
-.br
-     char *\fIstr_class\fP\^;
-.br
-     char **\fIstr_type_return\fP\^;
-.br
-     XrmValue *\fIvalue_return\fP\^; 
-.FN
-.IP \fIdatabase\fP 1i
-Specifies the database that is to be used.
-.IP \fIstr_name\fP 1i
-Specifies the fully qualified name of the value being retrieved (as a string).
-.IP \fIstr_class\fP 1i
-Specifies the fully qualified class of the value being retrieved (as a string).
-.IP \fIstr_type_return\fP 1i
-Returns the representation type of the destination (as a string).
-.IP \fIvalue_return\fP 1i
-Returns the value in the database.
-.LP
-.eM
-.sp
-.IN "XrmQGetResource" "" "@DEF@"
-.sM
-.FD 0
-Bool XrmQGetResource\^(\^\fIdatabase\fP, \fIquark_name\fP, \fIquark_class\fP, \
-\fIquark_type_return\fP, \fIvalue_return\fP\^)
-.br
-     XrmDatabase \fIdatabase\fP\^;
-.br
-     XrmNameList \fIquark_name\fP\^;
-.br
-     XrmClassList \fIquark_class\fP\^;
-.br
-     XrmRepresentation *\fIquark_type_return\fP\^;
-.br
-     XrmValue *\fIvalue_return\fP\^; 
-.FN
-.IP \fIdatabase\fP 1i
-Specifies the database that is to be used.
-.IP \fIquark_name\fP 1i
-Specifies the fully qualified name of the value being retrieved (as a quark).
-.IP \fIquark_class\fP 1i
-Specifies the fully qualified class of the value being retrieved (as a quark).
-.IP \fIquark_type_return\fP 1i
-Returns the representation type of the destination (as a quark).
-.IP \fIvalue_return\fP 1i
-Returns the value in the database.
-.LP
-.eM
-The 
-.PN XrmGetResource 
-and 
-.PN XrmQGetResource 
-functions retrieve a resource from the specified database.
-Both take a fully qualified name/class pair, a destination
-resource representation, and the address of a value
-(size/address pair).  
-The value and returned type point into database memory;
-therefore, you must not modify the data.
-.LP
-The database only frees or overwrites entries on
-.PN XrmPutResource , 
-.PN XrmQPutResource ,
-or 
-.PN XrmMergeDatabases .
-A client that is not storing new values into the database or
-is not merging the database should be safe using the address passed 
-back at any time until it exits.
-If a resource was found, both
-.PN XrmGetResource 
-and
-.PN XrmQGetResource 
-return 
-.PN True ;
-otherwise, they return 
-.PN False .
-.LP
-.sp
-.EQ
-delim %%
-.EN
-Most applications and toolkits do not make random probes
-into a resource database to fetch resources.
-The X toolkit access pattern for a resource database is quite stylized.
-A series of from 1 to 20 probes is made with only the 
-last name/class differing in each probe.
-The 
-.PN XrmGetResource 
-function is at worst a %2 sup n% algorithm,
-where \fIn\fP is the length of the name/class list.
-This can be improved upon by the application programmer by prefetching a list
-of database levels that might match the first part of a name/class list.
-.LP
-.sp
-To obtain a list of database levels, use
-.PN XrmQGetSearchList .
-.IN "XrmQGetSearchList" "" "@DEF@"
-.sM
-.FD 0
-typedef XrmHashTable *XrmSearchList;
-.sp
-Bool XrmQGetSearchList\^(\^\fIdatabase\fP, \fInames\fP, \fIclasses\fP, \
-\fIlist_return\fP, \fIlist_length\fP\^)
-.br
-     XrmDatabase \fIdatabase\fP\^;
-.br
-     XrmNameList \fInames\fP\^;
-.br
-     XrmClassList \fIclasses\fP\^;
-.br
-     XrmSearchList \fIlist_return\fP\^;
-.br
-     int \fIlist_length\fP\^;
-.FN
-.IP \fIdatabase\fP 1i
-Specifies the database that is to be used.
-.IP \fInames\fP 1i
-Specifies a list of resource names.
-.IP \fIclasses\fP 1i
-Specifies a list of resource classes.
-.IP \fIlist_return\fP 1i
-Returns a search list for further use.
-The caller must allocate sufficient space for the list before calling 
-.PN XrmQGetSearchList .
-.IP \fIlist_length\fP 1i
-Specifies the number of entries (not the byte size) allocated for list_return.
-.LP
-.eM
-The
-.PN XrmQGetSearchList
-function takes a list of names and classes
-and returns a list of database levels where a match might occur.
-The returned list is in best-to-worst order and
-uses the same algorithm as 
-.PN XrmGetResource 
-for determining precedence.
-If list_return was large enough for the search list,
-.PN XrmQGetSearchList
-returns 
-.PN True ;
-otherwise, it returns
-.PN False .
-.LP
-The size of the search list that the caller must allocate is
-dependent upon the number of levels and wildcards in the resource specifiers 
-that are stored in the database.
-The worst case length is %3 sup n%,
-where \fIn\fP is the number of name or class components in names or classes.
-.LP
-When using 
-.PN XrmQGetSearchList 
-followed by multiple probes for resources with a common name and class prefix,
-only the common prefix should be specified in the name and class list to 
-.PN XrmQGetSearchList .
-.LP
-.sp
-To search resource database levels for a given resource, use
-.PN XrmQGetSearchResource .
-.IN "XrmQGetSearchResource" "" "@DEF@"
-.sM
-.FD 0
-Bool XrmQGetSearchResource\^(\^\fIlist\fP, \fIname\fP, \fIclass\fP, \
-\fItype_return\fP, \fIvalue_return\fP\^)
-.br
-     XrmSearchList \fIlist\fP\^;
-.br
-     XrmName \fIname\fP\^;
-.br
-     XrmClass \fIclass\fP\^;
-.br
-     XrmRepresentation *\fItype_return\fP\^;
-.br
-     XrmValue *\fIvalue_return\fP\^;
-.FN
-.IP \fIlist\fP 1i
-Specifies the search list returned by
-.PN XrmQGetSearchList .
-.IP \fIname\fP 1i
-Specifies the resource name.
-.IP \fIclass\fP 1i
-Specifies the resource class.
-.IP \fItype_return\fP 1i
-Returns data representation type.
-.IP \fIvalue_return\fP 1i
-Returns the value in the database.
-.LP
-.eM
-The
-.PN XrmQGetSearchResource
-function searches the specified database levels for the resource 
-that is fully identified by the specified name and class.
-The search stops with the first match.
-.PN XrmQGetSearchResource
-returns 
-.PN True 
-if the resource was found;
-otherwise, it returns
-.PN False .
-.LP
-A call to 
-.PN XrmQGetSearchList 
-with a name and class list containing all but the last component 
-of a resource name followed by a call to 
-.PN XrmQGetSearchResource 
-with the last component name and class returns the same database entry as 
-.PN XrmGetResource 
-and 
-.PN XrmQGetResource 
-with the fully qualified name and class.
-.NH 2
-Storing into a Resource Database
-.XS
-\*(SN Storing into a Resource Database
-.XE
-.LP
-To store resources into the database, use
-.PN XrmPutResource 
-or
-.PN XrmQPutResource .
-Both functions take a partial resource specification, a
-representation type, and a value.
-This value is copied into the specified database.
-.LP
-.sp
-.IN "XrmPutResource" "" "@DEF@"
-.sM
-.FD 0
-void XrmPutResource\^(\^\fIdatabase\fP, \fIspecifier\fP, \fItype\fP, \fIvalue\fP\^)
-.br
-     XrmDatabase *\fIdatabase\fP\^;
-.br
-     char *\fIspecifier\fP\^;
-.br
-     char *\fItype\fP\^;
-.br
-     XrmValue *\fIvalue\fP\^;
-.FN
-.IP \fIdatabase\fP 1i
-Specifies the resource database.
-.IP \fIspecifier\fP 1i
-Specifies a complete or partial specification of the resource.
-.IP \fItype\fP 1i
-Specifies the type of the resource.
-.IP \fIvalue\fP 1i
-Specifies the value of the resource, which is specified as a string.
-.LP
-.eM
-If database contains NULL,
-.PN XrmPutResource
-creates a new database and returns a pointer to it.
-.PN XrmPutResource
-is a convenience function that calls
-.PN XrmStringToBindingQuarkList
-followed by:
-.LP
-.Ds
-XrmQPutResource(database, bindings, quarks, XrmStringToQuark(type), value)
-.De
-If the specifier and type are not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-The value is stored in the database without modification.
-.LP
-.sp
-.IN "XrmQPutResource" "" "@DEF@"
-.sM
-.FD 0
-void XrmQPutResource\^(\^\fIdatabase\fP, \fIbindings\fP, \fIquarks\fP, \
-\fItype\fP, \fIvalue\fP\^)
-.br
-     XrmDatabase *\fIdatabase\fP\^;
-.br
-     XrmBindingList \fIbindings\fP\^;
-.br
-     XrmQuarkList \fIquarks\fP\^;
-.br
-     XrmRepresentation \fItype\fP\^;
-.br
-     XrmValue *\fIvalue\fP\^;
-.FN
-.IP \fIdatabase\fP 1i
-Specifies the resource database.
-.IP \fIbindings\fP 1i
-Specifies a list of bindings.
-.IP \fIquarks\fP 1i
-Specifies the complete or partial name or the class list of the resource.
-.IP \fItype\fP 1i
-Specifies the type of the resource.
-.IP \fIvalue\fP 1i
-Specifies the value of the resource, which is specified as a string.
-.LP
-.eM
-If database contains NULL,
-.PN XrmQPutResource
-creates a new database and returns a pointer to it.
-If a resource entry with the identical bindings and quarks already
-exists in the database, the previous type and value are replaced by the new
-specified type and value.
-The value is stored in the database without modification.
-.LP
-.sp
-To add a resource that is specified as a string, use
-.PN XrmPutStringResource .
-.IN "XrmPutStringResource" "" "@DEF@"
-.sM
-.FD 0
-void XrmPutStringResource\^(\^\fIdatabase\fP, \fIspecifier\fP, \fIvalue\fP\^)
-.br
-     XrmDatabase *\fIdatabase\fP\^;
-.br
-     char *\fIspecifier\fP\^;
-.br
-     char *\fIvalue\fP\^;
-.FN
-.IP \fIdatabase\fP 1i
-Specifies the resource database.
-.IP \fIspecifier\fP 1i
-Specifies a complete or partial specification of the resource.
-.IP \fIvalue\fP 1i
-Specifies the value of the resource, which is specified as a string.
-.LP
-.eM
-If database contains NULL,
-.PN XrmPutStringResource
-creates a new database and returns a pointer to it.
-.PN XrmPutStringResource
-adds a resource with the specified value to the specified database.
-.PN XrmPutStringResource
-is a convenience function that first calls
-.PN XrmStringToBindingQuarkList
-on the specifier and then calls
-.PN XrmQPutResource ,
-using a ``String'' representation type.
-If the specifier is not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-The value is stored in the database without modification.
-.LP
-.sp
-To add a string resource using quarks as a specification, use
-.PN XrmQPutStringResource .
-.IN "XrmQPutStringResource" "" "@DEF@"
-.sM
-.FD 0
-void XrmQPutStringResource\^(\^\fIdatabase\fP, \fIbindings\fP, \fIquarks\fP, \
-\fIvalue\fP\^)
-.br
-     XrmDatabase *\fIdatabase\fP\^;
-.br
-     XrmBindingList \fIbindings\fP\^;
-.br
-     XrmQuarkList \fIquarks\fP\^;
-.br
-     char *\fIvalue\fP\^;
-.FN
-.IP \fIdatabase\fP 1i
-Specifies the resource database.
-.IP \fIbindings\fP 1i
-Specifies a list of bindings.
-.IP \fIquarks\fP 1i
-Specifies the complete or partial name or the class list of the resource.
-.IP \fIvalue\fP 1i
-Specifies the value of the resource, which is specified as a string.
-.LP
-.eM
-If database contains NULL,
-.PN XrmQPutStringResource
-creates a new database and returns a pointer to it.
-.PN XrmQPutStringResource
-is a convenience routine that constructs an
-.PN XrmValue
-for the value string (by calling
-.PN strlen
-to compute the size) and
-then calls
-.PN XrmQPutResource ,
-using a ``String'' representation type.
-The value is stored in the database without modification.
-.LP
-.sp
-To add a single resource entry that is specified as a string that contains
-both a name and a value, use
-.PN XrmPutLineResource .
-.IN "XrmPutLineResource" "" "@DEF@"
-.sM
-.FD 0
-void XrmPutLineResource\^(\^\fIdatabase\fP, \fIline\fP\^)
-.br
-     XrmDatabase *\fIdatabase\fP\^;
-.br
-     char *\fIline\fP\^;
-.FN
-.IP \fIdatabase\fP 1i
-Specifies the resource database.
-.IP \fIline\fP 1i
-Specifies the resource name and value pair as a single string.
-.LP
-.eM
-If database contains NULL,
-.PN XrmPutLineResource
-creates a new database and returns a pointer to it.
-.PN XrmPutLineResource
-adds a single resource entry to the specified database.
-The line should be in valid ResourceLine format (see section 15.1)
-terminated by a newline or null character;
-the database that results from using a string
-with incorrect syntax is implementation-dependent.
-The string is parsed in the locale of the database.
-If the
-.PN ResourceName
-is not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-Note that comment lines are not stored.
-.NH 2
-Enumerating Database Entries
-.XS
-\*(SN Enumerating Database Entries
-.XE
-.LP
-To enumerate the entries of a database, use
-.PN XrmEnumerateDatabase .
-.IN "XrmEnumerateDatabase" "" "@DEF@"
-.sM
-.TS
-lw(.5i) lw(2i) lw(2.5i).
-T{
-#define
-T}	T{
-.PN XrmEnumAllLevels
-T}	T{
-0
-T}
-T{
-#define
-T}	T{
-.PN XrmEnumOneLevel
-T}	T{
-1
-T}
-.TE
-.FD 0
-Bool XrmEnumerateDatabase\^(\^\fIdatabase\fP, \fIname_prefix\fP, \fIclass_prefix\fP, \fImode\fP, \fIproc\fP, \fIarg\fP\^)
-.br
-      XrmDatabase \fIdatabase\fP\^;
-.br
-      XrmNameList \fIname_prefix\fP\^;
-.br
-      XrmClassList \fIclass_prefix\fP\^;
-.br
-      int \fImode\fP\^;
-.br
-      Bool (\^*\fIproc\fP\^)\^(\^)\^;
-.br
-      XPointer \fIarg\fP\^;
-.FN
-.IP \fIdatabase\fP 1i
-Specifies the resource database.
-.IP \fIname_prefix\fP 1i
-Specifies the resource name prefix.
-.IP \fIclass_prefix\fP 1i
-Specifies the resource class prefix.
-.IP \fImode\fP 1i
-Specifies the number of levels to enumerate.
-.IP \fIproc\fP 1i
-Specifies the procedure that is to be called for each matching entry.
-.IP \fIarg\fP 1i
-Specifies the user-supplied argument that will be passed to the procedure.
-.LP
-.eM
-The
-.PN XrmEnumerateDatabase
-function calls the specified procedure for each resource in the database
-that would match some completion of the given name/class resource prefix.
-The order in which resources are found is implementation-dependent.
-If mode is
-.PN XrmEnumOneLevel ,
-a resource must match the given name/class prefix with
-just a single name and class appended.  If mode is
-.PN XrmEnumAllLevels ,
-the resource must match the given name/class prefix with one or more names and
-classes appended.
-If the procedure returns
-.PN True ,
-the enumeration terminates and the function returns
-.PN True . 
-If the procedure always returns
-.PN False ,
-all matching resources are enumerated and the function returns
-.PN False .
-.LP
-The procedure is called with the following arguments:
-.LP
-.\" Start marker code here
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-(*\fIproc\fP\^)(\^\fIdatabase\fP, \fIbindings\fP, \fIquarks\fP, \fItype\fP, \fIvalue\fP, \fIarg\fP\^)
-	XrmDatabase *\fIdatabase\fP\^;
-	XrmBindingList \fIbindings\fP\^;
-	XrmQuarkList \fIquarks\fP\^;
-	XrmRepresentation *\fItype\fP\^;
-	XrmValue *\fIvalue\fP\^;
-	XPointer \fIarg\fP\^;
-.De
-.\" End marker code here
-.LP
-The bindings and quarks lists are terminated by
-.PN NULLQUARK .
-Note that pointers
-to the database and type are passed, but these values should not be modified.
-.LP
-The procedure must not modify the database.
-If Xlib has been initialized for threads, the procedure is called with
-the database locked and the result of a call by the procedure to any
-Xlib function using the same database is not defined.
-.NH 2
-Parsing Command Line Options
-.XS
-\*(SN Parsing Command Line Options 
-.XE
-.LP
-The
-.PN XrmParseCommand
-function can be used to parse the command line arguments to a program
-and modify a resource database with selected entries from the command line.
-.LP
-.IN "XrmOptionKind" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef enum {
-	XrmoptionNoArg,	/* Value is specified in XrmOptionDescRec.value */
-	XrmoptionIsArg,	/* Value is the option string itself */
-	XrmoptionStickyArg,	/* Value is characters immediately following option */
-	XrmoptionSepArg,	/* Value is next argument in argv */
-	XrmoptionResArg,	/* Resource and value in next argument in argv */
-	XrmoptionSkipArg,	/* Ignore this option and the next argument in argv */
-	XrmoptionSkipLine,	/* Ignore this option and the rest of argv */
-	XrmoptionSkipNArgs	/* Ignore this option and the next
-		\ \ \ XrmOptionDescRec.value arguments in argv */
-} XrmOptionKind;
-.De
-.LP
-.eM
-Note that
-.PN XrmoptionSkipArg
-is equivalent to 
-.PN XrmoptionSkipNArgs
-with the
-.PN XrmOptionDescRec.value
-field containing the value one.
-Note also that the value zero for
-.PN XrmoptionSkipNArgs
-indicates that only the option itself is to be skipped.
-.LP
-.IN "XrmOptionDescRec" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 2.5i
-.ta .5i 2.5i
-typedef struct {
-	char *option;	/* Option specification string in argv		    */
-	char *specifier;	/* Binding and resource name (sans application name)    */
-	XrmOptionKind argKind;	/* Which style of option it is	    */
-	XPointer value;	/* Value to provide if XrmoptionNoArg or 
-		\ \ \ XrmoptionSkipNArgs   */
-} XrmOptionDescRec, *XrmOptionDescList;
-.De
-.LP
-.eM
-.sp
-To load a resource database from a C command line, use
-.PN XrmParseCommand .
-.IN "XrmParseCommand" "" "@DEF@"
-.sM
-.FD 0
-void XrmParseCommand\^(\^\fIdatabase\fP\^, \^\fItable\fP\^, \^\fItable_count\fP\^, \
-\^\fIname\fP\^, \^\fIargc_in_out\fP\^, \^\fIargv_in_out\fP\^)
-.br
-      XrmDatabase *\fIdatabase\fP\^;
-.br
-      XrmOptionDescList \fItable\fP\^;
-.br
-      int \fItable_count\fP\^;
-.br
-      char *\fIname\fP\^;
-.br
-      int *\fIargc_in_out\fP\^;
-.br
-      char **\fIargv_in_out\fP\^;
-.FN
-.IP \fIdatabase\fP 1i
-Specifies the resource database.
-.IP \fItable\fP 1i
-Specifies the table of command line arguments to be parsed.
-.IP \fItable_count\fP 1i
-Specifies the number of entries in the table.
-.IP \fIname\fP 1i
-Specifies the application name.
-.IP \fIargc_in_out\fP 1i
-Specifies the number of arguments and returns the number of remaining arguments.
-.IP \fIargv_in_out\fP 1i
-Specifies the command line arguments
-and returns the remaining arguments.
-.LP
-.eM
-The
-.PN XrmParseCommand
-function parses an (argc, argv) pair according to the specified option table,
-loads recognized options into the specified database with type ``String,''
-and modifies the (argc, argv) pair to remove all recognized options.
-If database contains NULL,
-.PN XrmParseCommand
-creates a new database and returns a pointer to it.
-Otherwise, entries are added to the database specified.
-If a database is created, it is created in the current locale.
-.LP
-The specified table is used to parse the command line.
-Recognized options in the table are removed from argv,
-and entries are added to the specified resource database
-in the order they occur in argv.
-The table entries contain information on the option string,
-the option name, the style of option, 
-and a value to provide if the option kind is 
-.PN XrmoptionNoArg .
-The option names are compared byte-for-byte to arguments in argv,
-independent of any locale.
-The resource values given in the table are stored in the resource database
-without modification.
-All resource database entries are created
-using a ``String'' representation type.
-The argc argument specifies the number of arguments in argv
-and is set on return to the remaining number of arguments that were not parsed.
-The name argument should be the name of your application
-for use in building the database entry.
-The name argument is prefixed to the resourceName in the option table
-before storing a database entry.
-The name argument is treated as a single component, even if it
-has embedded periods.
-No separating (binding) character is inserted,
-so the table must contain either a period (.) or an asterisk (*)
-as the first character in each resourceName entry.
-To specify a more completely qualified resource name,
-the resourceName entry can contain multiple components.
-If the name argument and the resourceNames are not in the
-Host Portable Character Encoding,
-the result is implementation-dependent.
-.LP
-The following provides a sample option table:
-.LP
-.Ds 0
-.TA 1.25i 3.25i 4.75i
-.ta 1.25i 3.25i 4.75i
-static XrmOptionDescRec opTable[] = {
-{"\-background",	"*background",	XrmoptionSepArg,	(XPointer) NULL},
-{"\-bd",	"*borderColor",	XrmoptionSepArg,	(XPointer) NULL},
-{"\-bg",	"*background",	XrmoptionSepArg,	(XPointer) NULL},
-{"\-borderwidth",	"*TopLevelShell.borderWidth",	XrmoptionSepArg,	(XPointer) NULL},
-{"\-bordercolor",	"*borderColor",	XrmoptionSepArg,	(XPointer) NULL},
-{"\-bw",	"*TopLevelShell.borderWidth",	XrmoptionSepArg,	(XPointer) NULL},
-{"\-display",	".display",	XrmoptionSepArg,	(XPointer) NULL},
-{"\-fg",	"*foreground",	XrmoptionSepArg,	(XPointer) NULL},
-{"\-fn",	"*font",	XrmoptionSepArg,	(XPointer) NULL},
-{"\-font",	"*font",	XrmoptionSepArg,	(XPointer) NULL},
-{"\-foreground",	"*foreground",	XrmoptionSepArg,	(XPointer) NULL},
-{"\-geometry",	".TopLevelShell.geometry",	XrmoptionSepArg,	(XPointer) NULL},
-{"\-iconic",	".TopLevelShell.iconic",	XrmoptionNoArg,	(XPointer) "on"},
-{"\-name",	".name",	XrmoptionSepArg,	(XPointer) NULL},
-{"\-reverse",	"*reverseVideo",	XrmoptionNoArg,	(XPointer) "on"},
-{"\-rv",	"*reverseVideo",	XrmoptionNoArg,	(XPointer) "on"},
-{"\-synchronous",	"*synchronous",	XrmoptionNoArg,	(XPointer) "on"},
-{"\-title",	".TopLevelShell.title",	XrmoptionSepArg,	(XPointer) NULL},
-{"\-xrm",	NULL,	XrmoptionResArg,	(XPointer) NULL},
-};
-.De
-.LP
-In this table, if the \-background (or \-bg) option is used to set
-background colors, the stored resource specifier matches all
-resources of attribute background.  
-If the \-borderwidth option is used, 
-the stored resource specifier applies only to border width
-attributes of class TopLevelShell (that is, outer-most windows, including
-pop-up windows).  
-If the \-title option is used to set a window name,
-only the topmost application windows receive the resource.
-.LP
-When parsing the command line,
-any unique unambiguous abbreviation for an option name in the table is 
-considered a match for the option.
-Note that uppercase and lowercase matter.
-.bp
diff --git a/libX11/specs/libX11/CH15.xml b/libX11/specs/libX11/CH15.xml
new file mode 100644
index 000000000..299a1196f
--- /dev/null
+++ b/libX11/specs/libX11/CH15.xml
@@ -0,0 +1,2485 @@
+<chapter id="resource_manager_functions">

+<title>Resource Manager Functions</title>

+<!-- .sp 2 -->

+<!-- .nr H1 15 -->

+<!-- .nr H2 0 -->

+<!-- .nr H3 0 -->

+<!-- .nr H4 0 -->

+<!-- .nr H5 0 -->

+<!-- .na -->

+<para>

+<!-- .LP -->

+<!-- .XS -->

+<!-- Chapter 15: Resource Manager Functions -->

+<!-- .XE -->

+A program often needs a variety of options in the X environment

+(for example, fonts, colors, icons, and cursors).

+Specifying all of these options on the command line is awkward

+because users may want to customize many aspects of the program

+and need a convenient way to establish these customizations as

+the default settings.

+The resource manager is provided for this purpose.

+Resource specifications are usually stored in human-readable files

+and in server properties.

+</para>

+<para>

+<!-- .LP -->

+The resource manager is a database manager with a twist.

+In most database systems, 

+you perform a query using an imprecise specification,

+and you get back a set of records.

+The resource manager, however, allows you to specify a large

+set of values with an imprecise specification, to query the database 

+with a precise specification, and to get back only a single value.

+This should be used by applications that need to know what the

+user prefers for colors, fonts, and other resources.

+It is this use as a database for dealing with X resources that

+inspired the name "Resource Manager,"

+although the resource manager can be and is used in other ways.

+</para>

+<para>

+<!-- .LP -->

+For example, 

+a user of your application may want to specify 

+that all windows should have a blue background 

+but that all mail-reading windows should have a red background.

+With well-engineered and coordinated applications,

+a user can define this information using only two lines of specifications.

+</para>

+<para>

+<!-- .LP -->

+As an example of how the resource manager works,

+consider a mail-reading application called xmh.

+Assume that it is designed so that it uses a

+complex window hierarchy all the way down to individual command buttons,

+which may be actual small subwindows in some toolkits.

+These are often called objects or widgets.

+In such toolkit systems,

+each user interface object can be composed of other objects

+and can be assigned a name and a class.

+Fully qualified names or classes can have arbitrary numbers of component names,

+but a fully qualified name always has the same number of component names as a

+fully qualified class.

+This generally reflects the structure of the application as composed

+of these objects, starting with the application itself.

+</para>

+<para>

+<!-- .LP -->

+For example, the xmh mail program has a name "xmh" and is one

+of a class of "Mail" programs.

+By convention, the first character of class components is capitalized,

+and the first letter of name components is in lowercase.

+Each name and class finally has an attribute

+(for example, "foreground" or "font").

+If each window is properly assigned a name and class,

+it is easy for the user to specify attributes of any portion 

+of the application.

+</para>

+<para>

+<!-- .LP -->

+At the top level, 

+the application might consist of a paned window (that is, a window divided

+into several sections) named "toc".

+One pane of the paned window is a button box window named "buttons"

+and is filled with command buttons. 

+One of these command buttons is used to incorporate

+new mail and has the name "incorporate".

+This window has a fully qualified name, "xmh.toc.buttons.incorporate",

+and a fully qualified class, "Xmh.Paned.Box.Command".

+Its fully qualified name is the name of its parent, "xmh.toc.buttons", 

+followed by its name, "incorporate".

+Its class is the class of its parent, "Xmh.Paned.Box", 

+followed by its particular class, "Command".  

+The fully qualified name of a resource is

+the attribute's name appended to the object's fully qualified

+name, and the fully qualified class is its class appended to the object's

+class.

+</para>

+<para>

+<!-- .LP -->

+The incorporate button might need the following resources: 

+Title string,

+Font,

+Foreground color for its inactive state,

+Background color for its inactive state,

+Foreground color for its active state, and

+Background color for its active state.

+Each resource is considered

+to be an attribute of the button and, as such, has a name and a class.

+For example, the foreground color for the button in

+its active state might be named "activeForeground",

+and its class might be "Foreground".

+</para>

+<para>

+<!-- .LP -->

+When an application looks up a resource (for example, a color),

+it passes the complete name and complete class of the resource

+to a look-up routine.

+The resource manager compares this complete specification

+against the incomplete specifications of entries in the resource

+database, finds the best match, and returns the corresponding

+value for that entry.

+</para>

+<para>

+<!-- .LP -->

+The definitions for the resource manager are contained in

+<!-- .hN X11/Xresource.h . -->

+</para>

+<sect1 id="Resource_File_Syntax">

+<title>Resource File Syntax</title>

+<!-- .XS -->

+<!-- (SN Resource File Syntax -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The syntax of a resource file is a sequence of resource lines

+terminated by newline characters or the end of the file.

+The syntax of an individual resource line is:

+</para>

+<para>

+<!-- .LP -->

+<!-- .\" Start marker code here -->

+<literallayout class="monospaced">

+<!-- .TA 1.5i 1.75i -->

+<!-- .ta 1.5i 1.75i -->

+ResourceLine     =     Comment | IncludeFile | ResourceSpec | &lt;empty line&gt;

+Comment     =     "!" {&lt;any character except null or newline&gt;}

+IncludeFile     =     "#" WhiteSpace "include" WhiteSpace FileName WhiteSpace

+FileName     =     &lt;valid filename for operating system&gt;

+ResourceSpec     =     WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value

+ResourceName     =     [Binding] {Component Binding} ComponentName

+Binding     =     "." | "*"

+WhiteSpace     =     {&lt;space&gt; | &lt;horizontal tab&gt;}

+Component     =     "?" | ComponentName

+ComponentName     =     NameChar {NameChar}

+NameChar     =     "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-"

+Value     =     {&lt;any character except null or unescaped newline&gt;}

+</literallayout>

+<!-- .\" End marker code here -->

+</para>

+<para>

+<!-- .LP -->

+Elements separated by vertical bar (|) are alternatives.

+Curly braces ({......}) indicate zero or more repetitions

+of the enclosed elements.

+Square brackets ([......]) indicate that the enclosed element is optional.

+Quotes ("......") are used around literal characters.

+</para>

+<para>

+<!-- .LP -->

+IncludeFile lines are interpreted by replacing the line with the

+contents of the specified file.

+The word "include" must be in lowercase.

+The file name is interpreted relative to the directory of the file in

+which the line occurs (for example, if the file name contains no

+directory or contains a relative directory specification).

+</para>

+<para>

+<!-- .LP -->

+If a ResourceName contains a contiguous sequence of two or more Binding

+characters, the sequence will be replaced with a single ".." character

+if the sequence contains only ".." characters;

+otherwise, the sequence will be replaced with a single "*" character.

+</para>

+<para>

+<!-- .LP -->

+A resource database never contains more than one entry for a given

+ResourceName.  If a resource file contains multiple lines with the

+same ResourceName, the last line in the file is used.

+</para>

+<para>

+<!-- .LP -->

+Any white space characters before or after the name or colon in a ResourceSpec

+are ignored.

+To allow a Value to begin with white space,

+the two-character sequence "\\<emphasis remap='I'>space</emphasis>" (backslash followed by space)

+is recognized and replaced by a space character,

+and the two-character sequence "\\<emphasis remap='I'>tab</emphasis>"

+(backslash followed by horizontal tab)

+is recognized and replaced by a horizontal tab character.

+To allow a Value to contain embedded newline characters,

+the two-character sequence "\\n" is recognized and replaced by a

+newline character.

+To allow a Value to be broken across multiple lines in a text file,

+the two-character sequence "\\<emphasis remap='I'>newline</emphasis>"

+(backslash followed by newline) is

+recognized and removed from the value.

+To allow a Value to contain arbitrary character codes,

+the four-character sequence "\\<emphasis remap='I'>nnn</emphasis>",

+where each <emphasis remap='I'>n</emphasis> is a digit character in the range of "0"-"7",

+is recognized and replaced with a single byte that contains

+the octal value specified by the sequence.

+Finally, the two-character sequence "\newline" is recognized

+and replaced with a single backslash.

+</para>

+<para>

+<!-- .LP -->

+As an example of these sequences,

+the following resource line contains a value consisting of four

+characters: a backslash, a null, a "z", and a newline:

+<literallayout class="monospaced">

+magic.values: \\000\

+z\n

+</literallayout>

+</para>

+</sect1>

+<sect1 id="Resource_Manager_Matching_Rules">

+<title>Resource Manager Matching Rules</title>

+<!-- .XS -->

+<!-- (SN Resource Manager Matching Rules -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The algorithm for determining which resource database entry

+matches a given query is the heart of the resource manager.

+All queries must fully specify the name and class of the desired resource

+(use of the characters "*" and "?" is not permitted).

+The library supports up to 100 components in a full name or class.

+Resources are stored in the database with only partially specified

+names and classes, using pattern matching constructs.

+An asterisk (*) is a loose binding and is used to represent any number

+of intervening components, including none.

+A period (.) is a tight binding and is used to separate immediately

+adjacent components.

+A question mark (?) is used to match any single component name or class.

+A database entry cannot end in a loose binding;

+the final component (which cannot be the character "?") must be specified.

+The lookup algorithm searches the database for the entry that most

+closely matches (is most specific for) the full name and class being queried.

+When more than one database entry matches the full name and class,

+precedence rules are used to select just one.

+</para>

+<para>

+<!-- .LP -->

+The full name and class are scanned from left to right (from highest

+level in the hierarchy to lowest), one component at a time.

+At each level, the corresponding component and/or binding of each

+matching entry is determined, and these matching components and

+bindings are compared according to precedence rules.

+Each of the rules is applied at each level before moving to the next level,

+until a rule selects a single entry over all others.

+The rules, in order of precedence, are:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+An entry that contains a matching component (whether name, class,

+or the character "?")

+takes precedence over entries that elide the level (that is, entries

+that match the level in a loose binding).

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+An entry with a matching name takes precedence over both

+entries with a matching class and entries that match using the character "?".

+An entry with a matching class takes precedence over

+entries that match using the character "?".

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+An entry preceded by a tight binding takes precedence over entries

+preceded by a loose binding.

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+To illustrate these rules,

+consider the following resource database entries:

+<literallayout class="monospaced">

+<!-- .TA 2.5i 3.5i -->

+<!-- .ta 2.5i 3.5i -->

+xmh*Paned*activeForeground:     red     <emphasis remap='I'>(entry A)</emphasis>

+*incorporate.Foreground:     blue     <emphasis remap='I'>(entry B)</emphasis>

+xmh.toc*Command*activeForeground:     green     <emphasis remap='I'>(entry C)</emphasis>

+xmh.toc*?.Foreground:     white     <emphasis remap='I'>(entry D)</emphasis>

+xmh.toc*Command.activeForeground:     black     <emphasis remap='I'>(entry E)</emphasis>

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+Consider a query for the resource:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA 3.5i -->

+<!-- .ta 3.5i -->

+xmh.toc.messagefunctions.incorporate.activeForeground     <emphasis remap='I'>(name)</emphasis>

+Xmh.Paned.Box.Command.Foreground     <emphasis remap='I'>(class)</emphasis>

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+At the first level (xmh, Xmh), rule 1 eliminates entry B.

+At the second level (toc, Paned), rule 2 eliminates entry A.

+At the third level (messagefunctions, Box), no entries are eliminated.

+At the fourth level (incorporate, Command), rule 2 eliminates entry D.

+At the fifth level (activeForeground, Foreground), rule 3 eliminates entry C.

+</para>

+</sect1>

+<sect1 id="Quarks">

+<title>Quarks</title>

+<!-- .XS -->

+<!-- (SN Quarks -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Most uses of the resource manager involve defining names,

+classes, and representation types as string constants.

+However, always referring to strings in the resource manager can be slow,

+because it is so heavily used in some toolkits.

+To solve this problem, 

+a shorthand for a string is used in place of the string

+in many of the resource manager functions.

+Simple comparisons can be performed rather than string comparisons.

+The shorthand name for a string is called a quark and is the

+type 

+<function>XrmQuark</function>.

+On some occasions,

+you may want to allocate a quark that has no string equivalent.

+</para>

+<para>

+<!-- .LP -->

+A quark is to a string what an atom is to a string in the server,

+but its use is entirely local to your application.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To allocate a new quark, use

+<function>XrmUniqueQuark</function>.

+</para>

+<indexterm significance="preferred"><primary>XrmUniqueQuark</primary></indexterm>

+<!-- .sM -->

+<para>XrmQuark XrmUniqueQuark()</para>

+<!-- .FN -->

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XrmUniqueQuark</function>

+function allocates a quark that is guaranteed not to represent any string that

+is known to the resource manager.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+Each name, class, and representation type is typedef'd as an

+<function>XrmQuark</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+typedef int XrmQuark, *XrmQuarkList;

+typedef XrmQuark XrmName;

+typedef XrmQuark XrmClass;

+typedef XrmQuark XrmRepresentation;

+#define NULLQUARK ((XrmQuark) 0)

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Lists are represented as null-terminated arrays of quarks.

+The size of the array must be large enough for the number of components used.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+typedef XrmQuarkList XrmNameList;

+typedef XrmQuarkList XrmClassList;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To convert a string to a quark, use

+<function>XrmStringToQuark</function>

+or

+<function>XrmPermStringToQuark</function>.

+</para>

+<literallayout class="monospaced">

+#define XrmStringToName(string) XrmStringToQuark(string)

+#define XrmStringToClass(string) XrmStringToQuark(string)

+#define XrmStringToRepresentation(string) XrmStringToQuark(string)

+</literallayout>

+

+<indexterm significance="preferred"><primary>XrmStringToQuark</primary></indexterm>

+<indexterm significance="preferred"><primary>XrmPermStringToQuark</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XrmQuark <function>XrmStringToQuark</function></funcdef>

+  <paramdef>char<parameter> *string</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<!-- .ds Ql -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the string for which a quark(Ql is to be allocated.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+These functions can be used to convert from string to quark representation.

+If the string is not in the Host Portable Character Encoding,

+the conversion is implementation-dependent.

+The string argument to

+<function>XrmStringToQuark</function>

+need not be permanently allocated storage.

+<function>XrmPermStringToQuark</function>

+is just like

+<function>XrmStringToQuark</function>,

+except that Xlib is permitted to assume the string argument is permanently

+allocated,

+and, hence, that it can be used as the value to be returned by

+<function>XrmQuarkToString</function>.

+</para>

+<para>

+<!-- .LP -->

+For any given quark, if

+<function>XrmStringToQuark</function>

+returns a non-NULL value,

+all future calls will return the same value (identical address).

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To convert a quark to a string, use 

+<function>XrmQuarkToString</function>.

+</para>

+

+<literallayout class="monospaced">

+#define XrmNameToString(name)  XrmQuarkToString(name)

+#define XrmClassToString(class)  XrmQuarkToString(name)

+#define XrmRepresentationToString(type)  XrmQuarkToString(type)

+</literallayout>

+<indexterm significance="preferred"><primary>XrmQuarkToString</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char <function> *XrmQuarkToString</function></funcdef>

+  <paramdef>XrmQuark<parameter> quark</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>quark</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the quark for which the equivalent string is desired.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+<!-- AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA -->

+<para>

+These functions can be used to convert from quark representation to string.

+The string pointed to by the return value must not be modified or freed.

+The returned string is byte-for-byte equal to the original

+string passed to one of the string-to-quark routines.

+If no string exists for that quark,

+<function>XrmQuarkToString</function>

+returns NULL.

+For any given quark, if

+<function>XrmQuarkToString</function>

+returns a non-NULL value,

+all future calls will return the same value (identical address).

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To convert a string with one or more components to a quark list, use

+<function>XrmStringToQuarkList</function>.

+</para>

+

+<literallayout class="monospaced">

+#define XrmStringToNameList(str,name)  XrmStringToQuarkList((str), (name))

+#define XrmStringToClassList(str,class)  XrmStringToQuarkList((str), (class))

+</literallayout>

+

+<indexterm significance="preferred"><primary>XrmStringToQuarkList</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function> XrmStringToQuarkList</function></funcdef>

+  <paramdef>char<parameter> *string</parameter></paramdef>

+  <paramdef>XrmQuarkList<parameter> quarks_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<!-- .ds Ql \ list -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the string for which a quark(Ql is to be allocated.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>quarks_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the list of quarks.

+The caller must allocate sufficient space for the quarks list before calling 

+<function>XrmStringToQuarkList</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XrmStringToQuarkList</function>

+function converts the null-terminated string (generally a fully qualified name)

+to a list of quarks.

+Note that the string must be in the valid ResourceName format 

+(see section 15.1).

+If the string is not in the Host Portable Character Encoding,

+the conversion is implementation-dependent.

+</para>

+<para>

+<!-- .LP -->

+A binding list is a list of type

+<function>XrmBindingList</function>

+and indicates if components of name or class lists are bound tightly or loosely

+(that is, if wildcarding of intermediate components is specified).

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<function>XrmBindTightly</function>

+indicates that a period separates the components, and

+<function>XrmBindLoosely</function>

+indicates that an asterisk separates the components.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To convert a string with one or more components to a binding list

+and a quark list, use

+<function>XrmStringToBindingQuarkList</function>.

+<indexterm significance="preferred"><primary>XrmStringToBindingQuarkList</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XrmStringToBindingQuarkList</function></funcdef>

+  <paramdef>char<parameter> *string</parameter></paramdef>

+  <paramdef>XrmBindingList<parameter> bindings_return</parameter></paramdef>

+  <paramdef>XrmQuarkList<parameter> quarks_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<!-- .ds Ql \ list -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the string for which a quark(Ql is to be allocated.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>bindings_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the binding list.

+The caller must allocate sufficient space for the binding list before calling 

+<function>XrmStringToBindingQuarkList</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>quarks_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the list of quarks.

+The caller must allocate sufficient space for the quarks list before calling 

+<function>XrmStringToBindingQuarkList</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Component names in the list are separated by a period or 

+an asterisk character.

+The string must be in the format of a valid ResourceName (see section 15.1).

+If the string does not start with a period or an asterisk, 

+a tight binding is assumed.

+For example, the string ``*a.b*c'' becomes:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA .75i 1.5i 2.25i -->

+<!-- .ta .75i 1.5i 2.25i -->

+quarks:       a         b         c

+bindings:     loose     tight     loose

+</literallayout>

+</para>

+</sect1>

+<sect1 id="Creating_and_Storing_Databases">

+<title>Creating and Storing Databases</title>

+<!-- .XS -->

+<!-- (SN Creating and Storing Databases -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XrmDatabase</primary></indexterm>

+A resource database is an opaque type,

+<function>XrmDatabase</function>.

+Each database value is stored in an

+<function>XrmValue </function>

+structure.

+This structure consists of a size, an address, and a representation type.

+The size is specified in bytes.

+The representation type is a way for you to store data tagged by some 

+application-defined type (for example, the strings ``font'' or ``color'').

+It has nothing to do with the C data type or with its class. 

+The

+<function>XrmValue </function>

+structure is defined as:

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XrmValue</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+typedef struct {

+     unsigned int size;

+     XPointer addr;

+} XrmValue, *XrmValuePtr;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To initialize the resource manager, use

+<function>XrmInitialize</function>.

+<indexterm significance="preferred"><primary>XrmInitialize</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function> XrmInitialize</function></funcdef>

+  <paramdef>void<parameter> XrmInitialize(\|)</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+To retrieve a database from disk, use

+<function>XrmGetFileDatabase</function>.

+<indexterm significance="preferred"><primary>XrmGetFileDatabase</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XrmDatabase <function> XrmGetFileDatabase</function></funcdef>

+  <paramdef>char<parameter> *filename</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>filename</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource database file name.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XrmGetFileDatabase</function>

+function opens the specified file,

+creates a new resource database, and loads it with the specifications

+read in from the specified file.

+The specified file should contain a sequence of entries in valid ResourceLine

+format (see section 15.1); the database that results from reading a file

+with incorrect syntax is implementation-dependent.

+The file is parsed in the current locale, 

+and the database is created in the current locale.

+If it cannot open the specified file,

+<function>XrmGetFileDatabase</function>

+returns NULL.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To store a copy of a database to disk, use

+<function>XrmPutFileDatabase</function>.

+<indexterm significance="preferred"><primary>XrmPutFileDatabase</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function> XrmPutFileDatabase</function></funcdef>

+  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>

+  <paramdef>char<parameter> *stored_db</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>database</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the database that is to be used.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>stored_db</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the file name for the stored database.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XrmPutFileDatabase</function>

+function stores a copy of the specified database in the specified file.

+Text is written to the file as a sequence of entries in valid

+ResourceLine format (see section 15.1).

+The file is written in the locale of the database.

+Entries containing resource names that are not in the Host Portable Character

+Encoding or containing values that are not in the encoding of the database

+locale, are written in an implementation-dependent manner.

+The order in which entries are written is implementation-dependent.

+Entries with representation types other than ``String'' are ignored.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain a pointer to the screen-independent resources of a display, use

+<function>XResourceManagerString</function>.

+<indexterm significance="preferred"><primary>XResourceManagerString</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char *<function> XResourceManagerString</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XResourceManagerString</function>

+function returns the RESOURCE_MANAGER property from the server's root

+window of screen zero, which was returned when the connection was opened using

+<function>XOpenDisplay</function>.

+The property is converted from type STRING to the current locale.

+The conversion is identical to that produced by 

+<function>XmbTextPropertyToTextList</function>

+for a single element STRING property.

+The returned string is owned by Xlib and should not be freed by the client.

+The property value must be in a format that is acceptable to

+<function>XrmGetStringDatabase</function>.

+If no property exists, NULL is returned.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain a pointer to the screen-specific resources of a screen, use

+<function>XScreenResourceString</function>.

+<indexterm significance="preferred"><primary>XScreenResourceString</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char *<function> XScreenResourceString</function></funcdef>

+  <paramdef>Screen<parameter> *screen</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the screen.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XScreenResourceString</function>

+function returns the SCREEN_RESOURCES property from the root window of the

+specified screen.

+The property is converted from type STRING to the current locale.

+The conversion is identical to that produced by 

+<function>XmbTextPropertyToTextList</function>

+for a single element STRING property.

+The property value must be in a format that is acceptable to

+<function>XrmGetStringDatabase</function>.

+If no property exists, NULL is returned.

+The caller is responsible for freeing the returned string by using

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To create a database from a string, use

+<function>XrmGetStringDatabase</function>.

+<indexterm significance="preferred"><primary>XrmGetStringDatabase</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XrmDatabase <function> XrmGetStringDatabase</function></funcdef>

+  <paramdef>char<parameter> *data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the database contents using a string.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XrmGetStringDatabase</function>

+function creates a new database and stores the resources specified

+in the specified null-terminated string.

+<function>XrmGetStringDatabase</function>

+is similar to

+<function>XrmGetFileDatabase</function>

+except that it reads the information out of a string instead of out of a file.

+The string should contain a sequence of entries in valid ResourceLine

+format (see section 15.1) terminated by a null character;

+the database that results from using a string

+with incorrect syntax is implementation-dependent.

+The string is parsed in the current locale, 

+and the database is created in the current locale.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the locale name of a database, use

+<function>XrmLocaleOfDatabase</function>.

+<indexterm significance="preferred"><primary>XrmLocaleOfDatabase</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char *<function> XrmLocaleOfDatabase</function></funcdef>

+  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>database</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource database.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XrmLocaleOfDatabase</function>

+function returns the name of the locale bound to the specified

+database, as a null-terminated string.

+The returned locale name string is owned by Xlib and should not be

+modified or freed by the client.

+Xlib is not permitted to free the string until the database is destroyed.

+Until the string is freed,

+it will not be modified by Xlib.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To destroy a resource database and free its allocated memory, use

+<function>XrmDestroyDatabase</function>.

+<indexterm significance="preferred"><primary>XrmDestroyDatabase</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function> XrmDestroyDatabase</function></funcdef>

+  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>database</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource database.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If database is NULL,

+<function>XrmDestroyDatabase</function>

+returns immediately.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To associate a resource database with a display, use

+<function>XrmSetDatabase</function>.

+<indexterm significance="preferred"><primary>XrmSetDatabase</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function> XrmSetDatabase</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>database</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource database.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XrmSetDatabase</function>

+function associates the specified resource database (or NULL)

+with the specified display.

+The database previously associated with the display (if any) is not destroyed.

+A client or toolkit may find this function convenient for retaining a database

+once it is constructed.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To get the resource database associated with a display, use

+<function>XrmGetDatabase</function>.

+<indexterm significance="preferred"><primary>XrmGetDatabase</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XrmDatabase <function> XrmGetDatabase</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XrmGetDatabase</function>

+function returns the database associated with the specified display.

+It returns NULL if a database has not yet been set.

+</para>

+</sect1>

+<sect1 id="Merging_Resource_Databases">

+<title>Merging Resource Databases</title>

+<!-- .XS -->

+<!-- (SN Merging Resource Databases -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To merge the contents of a resource file into a database, use

+<function>XrmCombineFileDatabase</function>.

+<indexterm significance="preferred"><primary>XrmCombineFileDatabase</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function> XrmCombineFileDatabase</function></funcdef>

+  <paramdef>char<parameter> *filename</parameter></paramdef>

+  <paramdef>XrmDatabase<parameter> *target_db</parameter></paramdef>

+  <paramdef>Bool<parameter> override</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>filename</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource database file name.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>target_db</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource database into which the source 

+database is to be merged.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>override</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies whether source entries override target ones.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XrmCombineFileDatabase</function>

+function merges the contents of a resource file into a database.

+If the same specifier is used for an entry in both the file and

+the database,

+the entry in the file will replace the entry in the database

+if override is

+<function>True</function>;

+otherwise, the entry in the file is discarded.

+The file is parsed in the current locale.

+If the file cannot be read,

+a zero status is returned;

+otherwise, a nonzero status is returned.

+If target_db contains NULL,

+<function>XrmCombineFileDatabase</function>

+creates and returns a new database to it.

+Otherwise, the database pointed to by target_db is not destroyed by the merge.

+The database entries are merged without changing values or types,

+regardless of the locale of the database.

+The locale of the target database is not modified.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To merge the contents of one database into another database, use

+<function>XrmCombineDatabase</function>.

+<indexterm significance="preferred"><primary>XrmCombineDatabase</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function> XrmCombineDatabase</function></funcdef>

+  <paramdef>XrmDatabasesource_db,<parameter> *target_db</parameter></paramdef>

+  <paramdef>Bool<parameter> override</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>source_db</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource database that is to be merged into the target database.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>target_db</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource database into which the source 

+database is to be merged.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>override</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies whether source entries override target ones.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XrmCombineDatabase</function>

+function merges the contents of one database into another.

+If the same specifier is used for an entry in both databases,

+the entry in the source_db will replace the entry in the target_db

+if override is

+<function>True</function>;

+otherwise, the entry in source_db is discarded.

+If target_db contains NULL,

+<function>XrmCombineDatabase</function>

+simply stores source_db in it.

+Otherwise, source_db is destroyed by the merge, but the database pointed

+to by target_db is not destroyed.

+The database entries are merged without changing values or types,

+regardless of the locales of the databases.

+The locale of the target database is not modified.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To merge the contents of one database into another database with override

+semantics, use

+<function>XrmMergeDatabases</function>.

+<indexterm significance="preferred"><primary>XrmMergeDatabases</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function> XrmMergeDatabases</function></funcdef>

+  <paramdef>XrmDatabasesource_db,<parameter> *target_db</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>source_db</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource database that is to be merged into the target database.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>target_db</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource database into which the source 

+database is to be merged.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+Calling the

+<function>XrmMergeDatabases</function>

+function is equivalent to calling the

+<function>XrmCombineDatabase</function>

+function with an override argument of

+<function>True</function>.

+</para>

+</sect1>

+<sect1 id="Looking_Up_Resources">

+<title>Looking Up Resources</title>

+<!-- .XS -->

+<!-- (SN Looking Up Resources -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To retrieve a resource from a resource database, use

+<function>XrmGetResource</function>,

+<function>XrmQGetResource</function>,

+or

+<function>XrmQGetSearchResource</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<indexterm significance="preferred"><primary>XrmGetResource</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool <function> XrmGetResource</function></funcdef>

+  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>

+  <paramdef>char<parameter> *str_name</parameter></paramdef>

+  <paramdef>char<parameter> *str_class</parameter></paramdef>

+  <paramdef>char<parameter> **str_type_return</parameter></paramdef>

+  <paramdef>XrmValue<parameter> *value_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>database</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the database that is to be used.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>str_name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the fully qualified name of the value being retrieved (as a string).

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>str_class</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the fully qualified class of the value being retrieved (as a string).

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>str_type_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the representation type of the destination (as a string).

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>value_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the value in the database.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+<indexterm significance="preferred"><primary>XrmQGetResource</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool <function> XrmQGetResource</function></funcdef>

+  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>

+  <paramdef>XrmNameList<parameter> quark_name</parameter></paramdef>

+  <paramdef>XrmClassList<parameter> quark_class</parameter></paramdef>

+  <paramdef>XrmRepresentation<parameter> *quark_type_return</parameter></paramdef>

+  <paramdef>XrmValue<parameter> *value_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>database</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the database that is to be used.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>quark_name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the fully qualified name of the value being retrieved (as a quark).

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>quark_class</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the fully qualified class of the value being retrieved (as a quark).

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>quark_type_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the representation type of the destination (as a quark).

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>value_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the value in the database.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XrmGetResource </function>

+and 

+<function>XrmQGetResource </function>

+functions retrieve a resource from the specified database.

+Both take a fully qualified name/class pair, a destination

+resource representation, and the address of a value

+(size/address pair).  

+The value and returned type point into database memory;

+therefore, you must not modify the data.

+</para>

+<para>

+<!-- .LP -->

+The database only frees or overwrites entries on

+<function>XrmPutResource</function>,

+<function>XrmQPutResource</function>,

+or 

+<function>XrmMergeDatabases</function>.

+A client that is not storing new values into the database or

+is not merging the database should be safe using the address passed 

+back at any time until it exits.

+If a resource was found, both

+<function>XrmGetResource </function>

+and

+<function>XrmQGetResource </function>

+return 

+<function>True</function>;

+otherwise, they return 

+<function>False</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .EQ -->

+<!-- delim %% -->

+<!-- .EN -->

+Most applications and toolkits do not make random probes

+into a resource database to fetch resources.

+The X toolkit access pattern for a resource database is quite stylized.

+A series of from 1 to 20 probes is made with only the 

+last name/class differing in each probe.

+The 

+<function>XrmGetResource </function>

+function is at worst a %2 sup n% algorithm,  <!-- FIXME: log(n) ?  -->

+where <emphasis remap='I'>n</emphasis> is the length of the name/class list.

+This can be improved upon by the application programmer by prefetching a list

+of database levels that might match the first part of a name/class list.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain a list of database levels, use

+<function>XrmQGetSearchList</function>.

+<indexterm significance="preferred"><primary>XrmQGetSearchList</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool <function> XrmQGetSearchResource</function></funcdef>

+  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>

+  <paramdef>XrmNameList<parameter> names</parameter></paramdef>

+  <paramdef>XrmClassList<parameter> classes</parameter></paramdef>

+  <paramdef>XrmSearchList<parameter> list_return</parameter></paramdef>

+  <paramdef>int<parameter> list_length</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>database</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the database that is to be used.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>names</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a list of resource names.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>classes</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a list of resource classes.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>list_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns a search list for further use.

+The caller must allocate sufficient space for the list before calling 

+<function>XrmQGetSearchList</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>list_length</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of entries (not the byte size) allocated for list_return.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XrmQGetSearchList</function>

+function takes a list of names and classes

+and returns a list of database levels where a match might occur.

+The returned list is in best-to-worst order and

+uses the same algorithm as 

+<function>XrmGetResource </function>

+for determining precedence.

+If list_return was large enough for the search list,

+<function>XrmQGetSearchList</function>

+returns 

+<function>True</function>;

+otherwise, it returns

+<function>False</function>.

+</para>

+<para>

+<!-- .LP -->

+The size of the search list that the caller must allocate is

+dependent upon the number of levels and wildcards in the resource specifiers 

+that are stored in the database.

+The worst case length is %3 sup n%,

+where <emphasis remap='I'>n</emphasis> is the number of name or class components in names or classes.

+</para>

+<para>

+<!-- .LP -->

+When using 

+<function>XrmQGetSearchList </function>

+followed by multiple probes for resources with a common name and class prefix,

+only the common prefix should be specified in the name and class list to 

+<function>XrmQGetSearchList</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To search resource database levels for a given resource, use

+<function>XrmQGetSearchResource</function>.

+<indexterm significance="preferred"><primary>XrmQGetSearchResource</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool <function> XrmQGetSearchResource</function></funcdef>

+  <paramdef>XrmSearchList<parameter> list</parameter></paramdef>

+  <paramdef>XrmName<parameter> name</parameter></paramdef>

+  <paramdef>XrmClass<parameter> class</parameter></paramdef>

+  <paramdef>XrmRepresentation<parameter> *type_return</parameter></paramdef>

+  <paramdef>XrmValue<parameter> *value_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>list</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the search list returned by

+<function>XrmQGetSearchList</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource name.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>class</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource class.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>type_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns data representation type.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>value_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the value in the database.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XrmQGetSearchResource</function>

+function searches the specified database levels for the resource 

+that is fully identified by the specified name and class.

+The search stops with the first match.

+<function>XrmQGetSearchResource</function>

+returns 

+<function>True </function>

+if the resource was found;

+otherwise, it returns

+<function>False</function>.

+</para>

+<para>

+<!-- .LP -->

+A call to 

+<function>XrmQGetSearchList </function>

+with a name and class list containing all but the last component 

+of a resource name followed by a call to 

+<function>XrmQGetSearchResource </function>

+with the last component name and class returns the same database entry as 

+<function>XrmGetResource </function>

+and 

+<function>XrmQGetResource </function>

+with the fully qualified name and class.

+</para>

+</sect1>

+<sect1 id="Storing_into_a_Resource_Database">

+<title>Storing into a Resource Database</title>

+<!-- .XS -->

+<!-- (SN Storing into a Resource Database -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To store resources into the database, use

+<function>XrmPutResource </function>

+or

+<function>XrmQPutResource</function>.

+Both functions take a partial resource specification, a

+representation type, and a value.

+This value is copied into the specified database.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<indexterm significance="preferred"><primary>XrmPutResource</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function> XrmPutResource</function></funcdef>

+  <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>

+  <paramdef>char<parameter> *specifier</parameter></paramdef>

+  <paramdef>char<parameter> *type</parameter></paramdef>

+  <paramdef>XrmValue<parameter> *value</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>database</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource database.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>specifier</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a complete or partial specification of the resource.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>type</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the type of the resource.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>value</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the value of the resource, which is specified as a string.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If database contains NULL,

+<function>XrmPutResource</function>

+creates a new database and returns a pointer to it.

+<function>XrmPutResource</function>

+is a convenience function that calls

+<function>XrmStringToBindingQuarkList</function>

+followed by:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+XrmQPutResource(database, bindings, quarks, XrmStringToQuark(type), value)

+</literallayout>

+If the specifier and type are not in the Host Portable Character Encoding,

+the result is implementation-dependent.

+The value is stored in the database without modification.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+<indexterm significance="preferred"><primary>XrmQPutResource</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function> XrmQPutResource</function></funcdef>

+  <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>

+  <paramdef>XrmBindingList<parameter> bindings</parameter></paramdef>

+  <paramdef>XrmQuarkList<parameter> quarks</parameter></paramdef>

+  <paramdef>XrmRepresentation<parameter> type</parameter></paramdef>

+  <paramdef>XrmValue<parameter> *value</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>database</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource database.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>bindings</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a list of bindings.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>quarks</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the complete or partial name or the class list of the resource.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>type</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the type of the resource.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>value</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the value of the resource, which is specified as a string.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If database contains NULL,

+<function>XrmQPutResource</function>

+creates a new database and returns a pointer to it.

+If a resource entry with the identical bindings and quarks already

+exists in the database, the previous type and value are replaced by the new

+specified type and value.

+The value is stored in the database without modification.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To add a resource that is specified as a string, use

+<function>XrmPutStringResource</function>.

+<indexterm significance="preferred"><primary>XrmPutStringResource</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function> XrmPutStringResource</function></funcdef>

+  <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>

+  <paramdef>char<parameter> *specifier</parameter></paramdef>

+  <paramdef>char<parameter> *value</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>database</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource database.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>specifier</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a complete or partial specification of the resource.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>value</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the value of the resource, which is specified as a string.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If database contains NULL,

+<function>XrmPutStringResource</function>

+creates a new database and returns a pointer to it.

+<function>XrmPutStringResource</function>

+adds a resource with the specified value to the specified database.

+<function>XrmPutStringResource</function>

+is a convenience function that first calls

+<function>XrmStringToBindingQuarkList</function>

+on the specifier and then calls

+<function>XrmQPutResource</function>,

+using a ``String'' representation type.

+If the specifier is not in the Host Portable Character Encoding,

+the result is implementation-dependent.

+The value is stored in the database without modification.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To add a string resource using quarks as a specification, use

+<function>XrmQPutStringResource</function>.

+<indexterm significance="preferred"><primary>XrmQPutStringResource</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function> XrmQPutStringResource</function></funcdef>

+  <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>

+  <paramdef>XrmBindingList<parameter> bindings</parameter></paramdef>

+  <paramdef>XrmQuarkList<parameter> quarks</parameter></paramdef>

+  <paramdef>char<parameter> *value</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>database</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource database.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>bindings</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies a list of bindings.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>quarks</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the complete or partial name or the class list of the resource.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>value</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the value of the resource, which is specified as a string.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If database contains NULL,

+<function>XrmQPutStringResource</function>

+creates a new database and returns a pointer to it.

+<function>XrmQPutStringResource</function>

+is a convenience routine that constructs an

+<function>XrmValue</function>

+for the value string (by calling

+<function>strlen</function>

+to compute the size) and

+then calls

+<function>XrmQPutResource</function>,

+using a ``String'' representation type.

+The value is stored in the database without modification.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To add a single resource entry that is specified as a string that contains

+both a name and a value, use

+<function>XrmPutLineResource</function>.

+<indexterm significance="preferred"><primary>XrmPutLineResource</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function> XrmPutLineResource</function></funcdef>

+  <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>

+  <paramdef>char<parameter> *line</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>database</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource database.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>line</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource name and value pair as a single string.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If database contains NULL,

+<function>XrmPutLineResource</function>

+creates a new database and returns a pointer to it.

+<function>XrmPutLineResource</function>

+adds a single resource entry to the specified database.

+The line should be in valid ResourceLine format (see section 15.1)

+terminated by a newline or null character;

+the database that results from using a string

+with incorrect syntax is implementation-dependent.

+The string is parsed in the locale of the database.

+If the

+<function>ResourceName</function>

+is not in the Host Portable Character Encoding,

+the result is implementation-dependent.

+Note that comment lines are not stored.

+</para>

+</sect1>

+<sect1 id="Enumerating_Database_Entries">

+<title>Enumerating Database Entries</title>

+<!-- .XS -->

+<!-- (SN Enumerating Database Entries -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To enumerate the entries of a database, use

+<function>XrmEnumerateDatabase</function>.

+<indexterm significance="preferred"><primary>XrmEnumerateDatabase</primary></indexterm>

+<!-- .sM -->

+</para>

+

+<literallayout class="monospaced">

+#define       XrmEnumAllLevels       0

+#define       XrmEnumOneLevel        0

+</literallayout>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool <function> XrmEnumerateDatabase</function></funcdef>

+  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>

+  <paramdef>XrmNameList<parameter> name_prefix</parameter></paramdef>

+  <paramdef>XrmClassList<parameter> class_prefix</parameter></paramdef>

+  <paramdef>int<parameter> mode</parameter></paramdef>

+  <paramdef>Bool<parameter> (*proc)()</parameter></paramdef>

+  <paramdef>XPointer<parameter> arg</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>database</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource database.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>name_prefix</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource name prefix.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>class_prefix</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource class prefix.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>mode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of levels to enumerate.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>proc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the procedure that is to be called for each matching entry.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>arg</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the user-supplied argument that will be passed to the procedure.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XrmEnumerateDatabase</function>

+function calls the specified procedure for each resource in the database

+that would match some completion of the given name/class resource prefix.

+The order in which resources are found is implementation-dependent.

+If mode is

+<function>XrmEnumOneLevel</function>,

+a resource must match the given name/class prefix with

+just a single name and class appended.  If mode is

+<function>XrmEnumAllLevels</function>,

+the resource must match the given name/class prefix with one or more names and

+classes appended.

+If the procedure returns

+<function>True</function>,

+the enumeration terminates and the function returns

+<function>True</function>.

+If the procedure always returns

+<function>False</function>,

+all matching resources are enumerated and the function returns

+<function>False</function>.

+</para>

+<para>

+<!-- .LP -->

+The procedure is called with the following arguments:

+</para>

+<para>

+<!-- .LP -->

+<!-- .\" Start marker code here -->

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>database</emphasis>, <emphasis remap='I'>bindings</emphasis>, <emphasis remap='I'>quarks</emphasis>, <emphasis remap='I'>type</emphasis>, <emphasis remap='I'>value</emphasis>, <emphasis remap='I'>arg</emphasis>)

+     XrmDatabase *<emphasis remap='I'>database</emphasis>;

+     XrmBindingList <emphasis remap='I'>bindings</emphasis>;

+     XrmQuarkList <emphasis remap='I'>quarks</emphasis>;

+     XrmRepresentation *<emphasis remap='I'>type</emphasis>;

+     XrmValue *<emphasis remap='I'>value</emphasis>;

+     XPointer <emphasis remap='I'>arg</emphasis>;

+</literallayout>

+<!-- .\" End marker code here -->

+</para>

+<para>

+<!-- .LP -->

+The bindings and quarks lists are terminated by

+<function>NULLQUARK</function>.

+Note that pointers

+to the database and type are passed, but these values should not be modified.

+</para>

+<para>

+<!-- .LP -->

+The procedure must not modify the database.

+If Xlib has been initialized for threads, the procedure is called with

+the database locked and the result of a call by the procedure to any

+Xlib function using the same database is not defined.

+</para>

+</sect1>

+<sect1 id="Parsing_Command_Line_Options">

+<title>Parsing Command Line Options</title>

+<!-- .XS -->

+<!-- (SN Parsing Command Line Options  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The

+<function>XrmParseCommand</function>

+function can be used to parse the command line arguments to a program

+and modify a resource database with selected entries from the command line.

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XrmOptionKind</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef enum {

+     XrmoptionNoArg,     /* Value is specified in XrmOptionDescRec.value */

+     XrmoptionIsArg,     /* Value is the option string itself */

+     XrmoptionStickyArg,     /* Value is characters immediately following option */

+     XrmoptionSepArg,     /* Value is next argument in argv */

+     XrmoptionResArg,     /* Resource and value in next argument in argv */

+     XrmoptionSkipArg,     /* Ignore this option and the next argument in argv */

+     XrmoptionSkipLine,     /* Ignore this option and the rest of argv */

+     XrmoptionSkipNArgs     /* Ignore this option and the next

+          \ \ \ XrmOptionDescRec.value arguments in argv */

+} XrmOptionKind;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Note that

+<function>XrmoptionSkipArg</function>

+is equivalent to 

+<function>XrmoptionSkipNArgs</function>

+with the

+<function>XrmOptionDescRec.value</function>

+field containing the value one.

+Note also that the value zero for

+<function>XrmoptionSkipNArgs</function>

+indicates that only the option itself is to be skipped.

+</para>

+<para>

+<!-- .LP -->

+<indexterm significance="preferred"><primary>XrmOptionDescRec</primary></indexterm>

+<!-- .sM -->

+<literallayout class="monospaced">

+<!-- .TA .5i 2.5i -->

+<!-- .ta .5i 2.5i -->

+typedef struct {

+     char *option;     /* Option specification string in argv              */

+     char *specifier;     /* Binding and resource name (sans application name)    */

+     XrmOptionKind argKind;     /* Which style of option it is         */

+     XPointer value;     /* Value to provide if XrmoptionNoArg or 

+          \ \ \ XrmoptionSkipNArgs   */

+} XrmOptionDescRec, *XrmOptionDescList;

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To load a resource database from a C command line, use

+<function>XrmParseCommand</function>.

+<indexterm significance="preferred"><primary>XrmParseCommand</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function> XrmParseCommand</function></funcdef>

+  <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>

+  <paramdef>XrmOptionDescList<parameter> table</parameter></paramdef>

+  <paramdef>int<parameter> table_count</parameter></paramdef>

+  <paramdef>char<parameter> *name</parameter></paramdef>

+  <paramdef>int<parameter> *argc_in_out</parameter></paramdef>

+  <paramdef>char<parameter> **argv_in_out</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>database</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource database.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>table</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the table of command line arguments to be parsed.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>table_count</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of entries in the table.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>name</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the application name.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>argc_in_out</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of arguments and returns the number of remaining arguments.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>argv_in_out</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the command line arguments

+and returns the remaining arguments.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XrmParseCommand</function>

+function parses an (argc, argv) pair according to the specified option table,

+loads recognized options into the specified database with type ``String,''

+and modifies the (argc, argv) pair to remove all recognized options.

+If database contains NULL,

+<function>XrmParseCommand</function>

+creates a new database and returns a pointer to it.

+Otherwise, entries are added to the database specified.

+If a database is created, it is created in the current locale.

+</para>

+<para>

+<!-- .LP -->

+The specified table is used to parse the command line.

+Recognized options in the table are removed from argv,

+and entries are added to the specified resource database

+in the order they occur in argv.

+The table entries contain information on the option string,

+the option name, the style of option, 

+and a value to provide if the option kind is 

+<function>XrmoptionNoArg</function>.

+The option names are compared byte-for-byte to arguments in argv,

+independent of any locale.

+The resource values given in the table are stored in the resource database

+without modification.

+All resource database entries are created

+using a ``String'' representation type.

+The argc argument specifies the number of arguments in argv

+and is set on return to the remaining number of arguments that were not parsed.

+The name argument should be the name of your application

+for use in building the database entry.

+The name argument is prefixed to the resourceName in the option table

+before storing a database entry.

+The name argument is treated as a single component, even if it

+has embedded periods.

+No separating (binding) character is inserted,

+so the table must contain either a period (.) or an asterisk (*)

+as the first character in each resourceName entry.

+To specify a more completely qualified resource name,

+the resourceName entry can contain multiple components.

+If the name argument and the resourceNames are not in the

+Host Portable Character Encoding,

+the result is implementation-dependent.

+</para>

+<para>

+<!-- .LP -->

+The following provides a sample option table:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+<!-- .TA 1.25i 3.25i 4.75i -->

+<!-- .ta 1.25i 3.25i 4.75i -->

+static XrmOptionDescRec opTable[] = {

+{"-background",     "*background",                 XrmoptionSepArg,    (XPointer) NULL},

+{"-bd",             "*borderColor",                XrmoptionSepArg,    (XPointer) NULL},

+{"-bg",             "*background",                 XrmoptionSepArg,    (XPointer) NULL},

+{"-borderwidth",    "*TopLevelShell.borderWidth",  XrmoptionSepArg,    (XPointer) NULL},

+{"-bordercolor",    "*borderColor",                XrmoptionSepArg,    (XPointer) NULL},

+{"-bw",             "*TopLevelShell.borderWidth",  XrmoptionSepArg,    (XPointer) NULL},

+{"-display",        ".display",                    XrmoptionSepArg,    (XPointer) NULL},

+{"-fg",             "*foreground",                 XrmoptionSepArg,    (XPointer) NULL},

+{"-fn",             "*font",                       XrmoptionSepArg,    (XPointer) NULL},

+{"-font",           "*font",                       XrmoptionSepArg,    (XPointer) NULL},

+{"-foreground",     "*foreground",                 XrmoptionSepArg,    (XPointer) NULL},

+{"-geometry",       ".TopLevelShell.geometry",     XrmoptionSepArg,    (XPointer) NULL},

+{"-iconic",         ".TopLevelShell.iconic",       XrmoptionNoArg,     (XPointer) "on"},

+{"-name",           ".name",                       XrmoptionSepArg,    (XPointer) NULL},

+{"-reverse",        "*reverseVideo",               XrmoptionNoArg,     (XPointer) "on"},

+{"-rv",             "*reverseVideo",               XrmoptionNoArg,     (XPointer) "on"},

+{"-synchronous",    "*synchronous",                XrmoptionNoArg,     (XPointer) "on"},

+{"-title",          ".TopLevelShell.title",        XrmoptionSepArg,    (XPointer) NULL},

+{"-xrm",            NULL,                          XrmoptionResArg,    (XPointer) NULL},

+};

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+In this table, if the -background (or -bg) option is used to set

+background colors, the stored resource specifier matches all

+resources of attribute background.  

+If the -borderwidth option is used, 

+the stored resource specifier applies only to border width

+attributes of class TopLevelShell (that is, outer-most windows, including

+pop-up windows).  

+If the -title option is used to set a window name,

+only the topmost application windows receive the resource.

+</para>

+<para>

+<!-- .LP -->

+When parsing the command line,

+any unique unambiguous abbreviation for an option name in the table is 

+considered a match for the option.

+Note that uppercase and lowercase matter.

+<!-- .bp -->

+

+</para>

+</sect1>

+</chapter>

diff --git a/libX11/specs/libX11/CH16 b/libX11/specs/libX11/CH16
deleted file mode 100644
index 3a21a2290..000000000
--- a/libX11/specs/libX11/CH16
+++ /dev/null
@@ -1,2364 +0,0 @@
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-.\" OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" Except as contained in this notice, the name of the X Consortium shall
-.\" not be used in advertising or otherwise to promote the sale, use or
-.\" other dealings in this Software without prior written authorization
-.\" from the X Consortium.
-.\"
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
-.\" Digital Equipment Corporation
-.\"
-.\" Portions Copyright \(co 1990, 1991 by
-.\" Tektronix, Inc.
-.\"
-.\" Permission to use, copy, modify and distribute this documentation for
-.\" any purpose and without fee is hereby granted, provided that the above
-.\" copyright notice appears in all copies and that both that copyright notice
-.\" and this permission notice appear in all copies, and that the names of
-.\" Digital and Tektronix not be used in in advertising or publicity pertaining
-.\" to this documentation without specific, written prior permission.
-.\" Digital and Tektronix makes no representations about the suitability
-.\" of this documentation for any purpose.
-.\" It is provided ``as is'' without express or implied warranty.
-.\" 
-\&
-.sp 1
-.ce 3
-\s+1\fBChapter 16\fP\s-1
-
-\s+1\fBApplication Utility Functions\fP\s-1
-.sp 2
-.nr H1 16
-.nr H2 0
-.nr H3 0
-.nr H4 0
-.nr H5 0
-.na
-.LP
-.XS
-Chapter 16: Application Utility Functions 
-.XE
-Once you have initialized the X system,
-you can use the Xlib utility functions to:
-.IP \(bu 5
-Use keyboard utility functions
-.IP \(bu 5
-Use Latin-1 keyboard event functions
-.IP \(bu 5
-Allocate permanent storage
-.IP \(bu 5
-Parse the window geometry
-.IP \(bu 5
-Manipulate regions
-.IP \(bu 5
-Use cut buffers
-.IP \(bu 5
-Determine the appropriate visual type
-.IP \(bu 5
-Manipulate images
-.IP \(bu 5
-Manipulate bitmaps
-.IP \(bu 5
-Use the context manager
-.LP
-As a group,
-the functions discussed in this chapter provide the functionality that 
-is frequently needed and that spans toolkits.
-Many of these functions do not generate actual protocol requests to the server.
-.NH 2
-Using Keyboard Utility Functions
-.XS
-\*(SN Using Keyboard Utility Functions 
-.XE
-.LP
-This section discusses mapping between KeyCodes and KeySyms,
-classifying KeySyms, and mapping between KeySyms and string names.
-The first three functions in this section operate on a cached copy of the
-server keyboard mapping.
-The first four KeySyms for each KeyCode
-are modified according to the rules given in section 12.7.
-To obtain the untransformed KeySyms defined for a key,
-use the functions described in section 12.7.
-.LP
-.sp
-To obtain a KeySym for the KeyCode of an event, use
-.PN XLookupKeysym .
-.IN "XLookupKeysym" "" "@DEF@"
-.sM
-.FD 0
-KeySym XLookupKeysym(\^\fIkey_event\fP, \fIindex\fP\^)
-.br
-      XKeyEvent *\fIkey_event\fP\^;
-.br
-      int \fIindex\fP\^;
-.FN
-.IP \fIkey_event\fP 1i
-Specifies the 
-.PN KeyPress
-or
-.PN KeyRelease
-event.
-.IP \fIindex\fP 1i
-Specifies the index into the KeySyms list for the event's KeyCode.
-.LP
-.eM
-The
-.PN XLookupKeysym
-function uses a given keyboard event and the index you specified to return
-the KeySym from the list that corresponds to the KeyCode member in the
-.PN XKeyPressedEvent
-or
-.PN XKeyReleasedEvent
-structure.
-If no KeySym is defined for the KeyCode of the event,
-.PN XLookupKeysym
-returns
-.PN NoSymbol .
-.LP
-.sp
-To obtain a KeySym for a specific KeyCode, use
-.PN XKeycodeToKeysym .
-.IN "XKeycodeToKeysym" "" "@DEF@"
-.sM
-.FD 0
-KeySym XKeycodeToKeysym\^(\^\fIdisplay\fP, \fIkeycode\fP, \fIindex\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      KeyCode \fIkeycode\fP\^;
-.br
-      int \fIindex\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIkeycode\fP 1i
-Specifies the KeyCode.
-.IP \fIindex\fP 1i
-Specifies the element of KeyCode vector.
-.LP
-.eM
-The
-.PN XKeycodeToKeysym
-function uses internal Xlib tables
-and returns the KeySym defined for the specified KeyCode and
-the element of the KeyCode vector.
-If no symbol is defined,
-.PN XKeycodeToKeysym
-returns
-.PN NoSymbol .
-.LP
-.sp
-To obtain a KeyCode for a key having a specific KeySym, use
-.PN XKeysymToKeycode .
-.IN "XKeysymToKeycode" "" "@DEF@"
-.sM
-.FD 0
-KeyCode XKeysymToKeycode\^(\^\fIdisplay\fP, \fIkeysym\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      KeySym \fIkeysym\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIkeysym\fP 1i
-Specifies the KeySym that is to be searched for.
-.LP
-.eM
-If the specified KeySym is not defined for any KeyCode,
-.PN XKeysymToKeycode
-returns zero.
-.LP
-.sp
-The mapping between KeyCodes and KeySyms is cached internal to Xlib.
-When this information is changed at the server, an Xlib function must
-be called to refresh the cache.
-To refresh the stored modifier and keymap information, use
-.PN XRefreshKeyboardMapping .
-.IN "XRefreshKeyboardMapping" "" "@DEF@"
-.sM
-.FD 0
-XRefreshKeyboardMapping(\^\fIevent_map\fP\^)
-.br
-      XMappingEvent *\fIevent_map\fP\^;
-.FN
-.IP \fIevent_map\fP 1i
-Specifies the mapping event that is to be used.
-.LP
-.eM
-The
-.PN XRefreshKeyboardMapping
-function refreshes the stored modifier and keymap information.
-You usually call this function when a
-.PN MappingNotify
-event with a request member of
-.PN MappingKeyboard
-or
-.PN MappingModifier
-occurs.
-The result is to update Xlib's knowledge of the keyboard.
-.LP
-.sp
-To obtain the uppercase and lowercase forms of a KeySym, use
-.PN XConvertCase .
-.IN "XConvertCase" "" "@DEF@"
-.sM
-.FD 0
-void XConvertCase(\^\fIkeysym\fP, \fIlower_return\fP, \fIupper_return\fP\^)
-.br
-      KeySym \fIkeysym\fP\^;
-.br
-      KeySym *\fIlower_return\fP\^;
-.br
-      KeySym *\fIupper_return\fP\^;
-.FN
-.ds Fn converted
-.IP \fIkeysym\fP 1i
-Specifies the KeySym that is to be \*(Fn.
-.IP \fIlower_return\fP 1i
-Returns the lowercase form of keysym, or keysym.
-.IP \fIupper_return\fP 1i
-Returns the uppercase form of keysym, or keysym.
-.LP
-.eM
-The
-.PN XConvertCase
-function returns the uppercase and lowercase forms of the specified Keysym,
-if the KeySym is subject to case conversion;
-otherwise, the specified KeySym is returned to both lower_return and
-upper_return.
-Support for conversion of other than Latin and Cyrillic KeySyms is
-implementation-dependent.
-.LP
-.sp
-KeySyms have string names as well as numeric codes.
-To convert the name of the KeySym to the KeySym code, use
-.PN XStringToKeysym .
-.IN "XStringToKeysym" "" "@DEF@"
-.sM
-.FD 0
-KeySym XStringToKeysym\^(\^\fIstring\fP\^)
-.br
-      char *\fIstring\fP\^;
-.FN
-.IP \fIstring\fP 1i
-Specifies the name of the KeySym that is to be converted.
-.LP
-.eM
-Standard KeySym names are obtained from
-.hN X11/keysymdef.h
-by removing the XK_ prefix from each name.
-KeySyms that are not part of the Xlib standard also may be obtained
-with this function.
-The set of KeySyms that are available in this manner 
-and the mechanisms by which Xlib obtains them is implementation-dependent.
-.LP
-If the KeySym name is not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-If the specified string does not match a valid KeySym,
-.PN XStringToKeysym
-returns
-.PN NoSymbol .
-.LP
-.sp
-To convert a KeySym code to the name of the KeySym, use
-.PN XKeysymToString .
-.IN "XKeysymToString" "" "@DEF@"
-.sM
-.FD 0
-char *XKeysymToString\^(\^\fIkeysym\fP\^)
-.br
-      KeySym \fIkeysym\fP\^;
-.FN
-.ds Fn converted
-.IP \fIkeysym\fP 1i
-Specifies the KeySym that is to be \*(Fn.
-.LP
-.eM
-The returned string is in a static area and must not be modified.
-The returned string is in the Host Portable Character Encoding.
-If the specified KeySym is not defined,
-.PN XKeysymToString
-returns a NULL.
-.NH 3
-KeySym Classification Macros
-.XS
-\*(SN KeySym Classification Macros
-.XE
-.LP
-You may want to test if a KeySym is, for example, 
-on the keypad or on one of the function keys.
-You can use KeySym macros to perform the following tests.
-.LP
-.sp
-.sM
-.FD 0
-IsCursorKey\^(\^\fIkeysym\fP\^)
-.FN
-.ds Fn tested
-.IP \fIkeysym\fP 1i
-Specifies the KeySym that is to be \*(Fn.
-.LP
-.eM
-.IN "IsCursorKey" "" "@DEF@"
-Returns
-.PN True
-if the specified KeySym is a cursor key.
-.LP
-.sp
-.sM
-.FD 0
-IsFunctionKey\^(\^\fIkeysym\fP\^)
-.FN
-.ds Fn tested
-.IP \fIkeysym\fP 1i
-Specifies the KeySym that is to be \*(Fn.
-.LP
-.eM
-.IN "IsFunctionKey" "" "@DEF@"
-Returns 
-.PN True
-if the specified KeySym is a function key.
-.LP
-.sp
-.sM
-.FD 0
-IsKeypadKey\^(\^\fIkeysym\fP\^)
-.FN
-.ds Fn tested
-.IP \fIkeysym\fP 1i
-Specifies the KeySym that is to be \*(Fn.
-.LP
-.eM
-.IN "IsKeypadKey" "" "@DEF@"
-Returns
-.PN True
-if the specified KeySym is a standard keypad key.
-.LP
-.sp
-.sM
-.FD 0
-IsPrivateKeypadKey\^(\^\fIkeysym\fP\^)
-.FN
-.ds Fn tested
-.IP \fIkeysym\fP 1i
-Specifies the KeySym that is to be \*(Fn.
-.LP
-.eM
-.IN "IsPrivateKeypadKey" "" "@DEF@"
-Returns
-.PN True
-if the specified KeySym is a vendor-private keypad key.
-.LP
-.sp
-.sM
-.FD 0
-IsMiscFunctionKey\^(\^\fIkeysym\fP\^)
-.FN
-.ds Fn tested
-.IP \fIkeysym\fP 1i
-Specifies the KeySym that is to be \*(Fn.
-.LP
-.eM
-.IN "IsMiscFunctionKey" "" "@DEF@"
-Returns 
-.PN True
-if the specified KeySym is a miscellaneous function key.
-.LP
-.sp
-.sM
-.FD 0
-IsModifierKey\^(\^\fIkeysym\fP\^)
-.FN
-.ds Fn tested
-.IP \fIkeysym\fP 1i
-Specifies the KeySym that is to be \*(Fn.
-.LP
-.eM
-.IN "IsModifierKey" "" "@DEF@"
-Returns 
-.PN True
-if the specified KeySym is a modifier key.
-.LP
-.sp
-.sM
-.FD 0
-IsPFKey\^(\^\fIkeysym\fP\^)
-.FN
-.ds Fn tested
-.IP \fIkeysym\fP 1i
-Specifies the KeySym that is to be \*(Fn.
-.LP
-.eM
-.IN "IsPFKey" "" "@DEF@"
-Returns 
-.PN True
-if the specified KeySym is a PF key.
-.NH 2
-Using Latin-1 Keyboard Event Functions
-.XS
-\*(SN Using Latin-1 Keyboard Event Functions 
-.XE
-.LP
-Chapter 13 describes internationalized text input facilities,
-but sometimes it is expedient to write an application that
-only deals with Latin-1 characters and ASCII controls,
-so Xlib provides a simple function for that purpose.
-.PN XLookupString
-handles the standard modifier semantics described in section 12.7.
-This function does not use any of the input method facilities
-described in chapter 13 and does not depend on the current locale.
-.LP
-.sp
-To map a key event to an ISO Latin-1 string, use
-.PN XLookupString .
-.IN "XLookupString" "" "@DEF@"
-.sM
-.FD 0
-int XLookupString(\^\fIevent_struct\fP, \fIbuffer_return\fP,\
- \fIbytes_buffer\fP, \fIkeysym_return\fP, \fIstatus_in_out\fP\^)
-.br
-      XKeyEvent *\fIevent_struct\fP\^;
-.br
-      char *\fIbuffer_return\fP\^;
-.br
-      int \fIbytes_buffer\fP\^;
-.br
-      KeySym *\fIkeysym_return\fP\^;
-.br
-      XComposeStatus *\fIstatus_in_out\fP\^;
-.FN
-.IP \fIevent_struct\fP 1i
-Specifies the key event structure to be used.
-You can pass
-.PN XKeyPressedEvent
-or
-.PN XKeyReleasedEvent .
-.IP \fIbuffer_return\fP 1i
-Returns the translated characters.
-.IP \fIbytes_buffer\fP 1i
-Specifies the length of the buffer.
-No more than bytes_buffer of translation are returned.
-.IP \fIkeysym_return\fP 1i
-Returns the KeySym computed from the event if this argument is not NULL.
-.IP \fIstatus_in_out\fP 1i
-Specifies or returns the 
-.PN XComposeStatus 
-structure or NULL.
-.LP
-.eM
-The
-.PN XLookupString
-function translates a key event to a KeySym and a string.
-The KeySym is obtained by using the standard interpretation of the
-.PN Shift ,
-.PN Lock ,
-group, and numlock modifiers as defined in the X Protocol specification.
-If the KeySym has been rebound (see
-.PN XRebindKeysym ),
-the bound string will be stored in the buffer.
-Otherwise, the KeySym is mapped, if possible, to an ISO Latin-1 character
-or (if the Control modifier is on) to an ASCII control character,
-and that character is stored in the buffer.
-.PN XLookupString
-returns the number of characters that are stored in the buffer.
-.LP
-If present (non-NULL),
-the
-.PN XComposeStatus
-structure records the state,
-which is private to Xlib,
-that needs preservation across calls to
-.PN XLookupString
-to implement compose processing.
-The creation of
-.PN XComposeStatus
-structures is implementation-dependent;
-a portable program must pass NULL for this argument.
-.LP
-.PN XLookupString
-depends on the cached keyboard information mentioned in the
-previous section, so it is necessary to use
-.PN XRefreshKeyboardMapping
-to keep this information up-to-date.
-.LP
-.sp
-To rebind the meaning of a KeySym for
-.PN XLookupString ,
-use
-.PN XRebindKeysym .
-.IN "XRebindKeysym" "" "@DEF@"
-.sM
-.FD 0
-XRebindKeysym(\^\fIdisplay\fP, \fIkeysym\fP, \fIlist\fP, \fImod_count\fP, \fIstring\fP, \fInum_bytes\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      KeySym \fIkeysym\fP\^;
-.br
-      KeySym \fIlist\fP\^[\^]\^;
-.br
-      int \fImod_count\fP\^;
-.br
-      unsigned char *\fIstring\fP\^;
-.br
-      int \fInum_bytes\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Fn rebound
-.IP \fIkeysym\fP 1i
-Specifies the KeySym that is to be \*(Fn.
-.IP \fIlist\fP 1i
-Specifies the KeySyms to be used as modifiers.
-.IP \fImod_count\fP 1i
-Specifies the number of modifiers in the modifier list.
-.IP \fIstring\fP 1i
-Specifies the string that is copied and will be returned by 
-.PN XLookupString .
-.IP \fInum_bytes\fP 1i
-Specifies the number of bytes in the string argument.
-.LP
-.eM
-The
-.PN XRebindKeysym
-function can be used to rebind the meaning of a KeySym for the client.
-It does not redefine any key in the X server but merely
-provides an easy way for long strings to be attached to keys.
-.PN XLookupString
-returns this string when the appropriate set of
-modifier keys are pressed and when the KeySym would have been used for
-the translation.
-No text conversions are performed;
-the client is responsible for supplying appropriately encoded strings.
-Note that you can rebind a KeySym that may not exist.
-.NH 2
-Allocating Permanent Storage
-.XS
-\*(SN Allocating Permanent Storage
-.XE
-.LP
-To allocate some memory you will never give back, use
-.PN Xpermalloc .
-.IN "Xpermalloc" "" "@DEF@"
-.sM
-.FD 0
-char *Xpermalloc\^(\^\fIsize\fP\^)
-.br
-     unsigned int \fIsize\fP\^;
-.FN
-.LP
-.eM
-The
-.PN Xpermalloc
-function allocates storage that can never be freed for the life of the
-program.  The memory is allocated with alignment for the C type double.
-This function may provide some performance and space savings over
-the standard operating system memory allocator.
-.NH 2
-Parsing the Window Geometry
-.XS
-\*(SN Parsing the Window Geometry 
-.XE
-.LP
-To parse standard window geometry strings, use
-.PN XParseGeometry .
-.IN "Window" "determining location"
-.IN "XParseGeometry" "" "@DEF@"
-.LP
-.sM
-.FD 0
-int XParseGeometry\^(\^\fIparsestring\fP\^, \fIx_return\fP\^, \fIy_return\fP\^, \fIwidth_return\fP\^, \fIheight_return\fP\^)
-.br
-      char *\fIparsestring\fP\^;
-.br
-      int *\fIx_return\fP\^, *\fIy_return\fP\^; 
-.br
-      unsigned int *\fIwidth_return\fP\^, *\fIheight_return\fP\^;
-.FN
-.IP \fIparsestring\fP 1i
-Specifies the string you want to parse.
-.IP \fIx_return\fP 1i
-.br
-.ns
-.IP \fIy_return\fP 1i
-Return the x and y offsets.
-.IP \fIwidth_return\fP 1i
-.br
-.ns
-.IP \fIheight_return\fP 1i
-Return the width and height determined.
-.LP
-.eM
-By convention,
-X applications use a standard string to indicate window size and placement.
-.PN XParseGeometry
-makes it easier to conform to this standard because it allows you
-to parse the standard window geometry.
-Specifically, this function lets you parse strings of the form:
-.LP
-.\" Start marker code here
-.Ds
-[=][<\fIwidth\fP>{xX}<\fIheight\fP>][{+-}<\fIxoffset\fP>{+-}<\fIyoffset\fP>] 
-.De
-.\" End marker code here
-.LP
-The fields map into the arguments associated with this function.
-(Items enclosed in <\^> are integers, items in [\^] are optional, and
-items enclosed in {\^} indicate ``choose one of.''
-Note that the brackets should not appear in the actual string.)
-If the string is not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-.LP
-The
-.PN XParseGeometry
-function returns a bitmask that indicates which of the four values (width,
-height, xoffset, and yoffset) were actually found in the string 
-and whether the x and y values are negative. 
-By convention, \-0 is not equal to +0, because the user needs to
-be able to say ``position the window relative to the right or bottom edge.''
-For each value found, the corresponding argument is updated.
-For each value not found, the argument is left unchanged.
-The bits are represented by
-.PN XValue , 
-.PN YValue , 
-.PN WidthValue , 
-.PN HeightValue ,
-.PN XNegative , 
-or
-.PN YNegative
-and are defined in 
-.hN X11/Xutil.h .
-They will be set whenever one of the values is defined 
-or one of the signs is set.
-.LP
-If the function returns either the 
-.PN XValue 
-or 
-.PN YValue 
-flag,
-you should place the window at the requested position.
-.sp
-.LP
-To construct a window's geometry information, use
-.PN XWMGeometry .
-.IN "XWMGeometry" "" "@DEF@"
-.sM
-.FD 0
-int XWMGeometry\^(\^\fIdisplay\fP, \fIscreen\fP, \fIuser_geom\fP, \
-\fIdef_geom\fP, \fIbwidth\fP, \fIhints\fP, \fIx_return\fP, \fIy_return\fP,
-.br
-                \fIwidth_return\fP, \fIheight_return\fP, \fIgravity_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIscreen\fP\^;
-.br
-      char *\fIuser_geom\fP\^;
-.br
-      char *\fIdef_geom\fP\^;
-.br
-      unsigned int \fIbwidth\fP\^;
-.br
-      XSizeHints *\fIhints\fP\^;
-.br
-      int *\fIx_return\fP, *\fIy_return\fP\^; 
-.br
-      int *\fIwidth_return\fP\^;
-.br
-      int *\fIheight_return\fP\^;
-.br
-      int *\fIgravity_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIscreen\fP 1i
-Specifies the screen.
-.IP \fIuser_geom\fP 1i
-Specifies the user-specified geometry or NULL.
-.IP \fIdef_geom\fP 1i
-Specifies the application's default geometry or NULL.
-.IP \fIbwidth\fP 1i
-Specifies the border width.
-.IP \fIhints\fP 1i
-Specifies the size hints for the window in its normal state.
-.IP \fIx_return\fP 1i
-.br
-.ns
-.IP \fIy_return\fP 1i
-Return the x and y offsets.
-.IP \fIwidth_return\fP 1i
-.br
-.ns
-.IP \fIheight_return\fP 1i
-Return the width and height determined.
-.IP \fIgravity_return\fP 1i
-Returns the window gravity.
-.LP
-.eM
-The 
-.PN XWMGeometry 
-function combines any geometry information (given in the format used by 
-.PN XParseGeometry )
-specified by the user and by the calling program with size hints 
-(usually the ones to be stored in WM_NORMAL_HINTS) and returns the position, 
-size, and gravity
-.Pn ( NorthWestGravity , 
-.PN NorthEastGravity , 
-.PN SouthEastGravity ,
-or
-.PN SouthWestGravity ) 
-that describe the window.
-If the base size is not set in the 
-.PN XSizeHints
-structure, 
-the minimum size is used if set.
-Otherwise, a base size of zero is assumed.
-If no minimum size is set in the hints structure, 
-the base size is used.
-A mask (in the form returned by 
-.PN XParseGeometry ) 
-that describes which values came from the user specification 
-and whether or not the position coordinates are relative
-to the right and bottom edges is returned.
-Note that these coordinates will have already been accounted for 
-in the x_return and y_return values.
-.LP
-Note that invalid geometry specifications can cause a width or height 
-of zero to be returned.
-The caller may pass the address of the hints win_gravity field 
-as gravity_return to update the hints directly.
-.NH 2
-Manipulating Regions
-.XS
-\*(SN Manipulating Regions 
-.XE
-.LP
-Regions are arbitrary sets of pixel locations.
-Xlib provides functions for manipulating regions.
-The opaque type 
-.PN Region
-is defined in 
-.hN X11/Xutil.h .
-Xlib provides functions that you can use to manipulate regions.
-This section discusses how to:
-.IP \(bu 5
-Create, copy, or destroy regions
-.IP \(bu 5
-Move or shrink regions
-.IP \(bu 5
-Compute with regions
-.IP \(bu 5
-Determine if regions are empty or equal
-.IP \(bu 5
-Locate a point or rectangle in a region
-.NH 3
-Creating, Copying, or Destroying Regions
-.XS
-\*(SN Creating, Copying, or Destroying Regions 
-.XE
-.LP
-To create a new empty region, use
-.PN XCreateRegion .
-.IN "XCreateRegion" "" "@DEF@"
-.sM
-.FD 0
-Region XCreateRegion\^()
-.FN
-.LP
-.eM
-.sp
-To generate a region from a polygon, use
-.PN XPolygonRegion .
-.IN "XPolygonRegion" "" "@DEF@"
-.sM
-.FD 0
-Region XPolygonRegion\^(\^\fIpoints\fP\^, \fIn\fP\^, \fIfill_rule\fP\^)
-.br
-      XPoint \fIpoints[]\fP\^;
-.br
-      int \fIn\fP\^;
-.br
-      int \fIfill_rule\fP\^;	
-.FN
-.IP \fIpoints\fP 1i
-Specifies an array of points.
-.IP \fIn\fP 1i
-Specifies the number of points in the polygon. 
-.IP \fIfill_rule\fP 1i
-Specifies the fill-rule you want to set for the specified GC.
-You can pass 
-.PN EvenOddRule
-or
-.PN WindingRule .
-.LP
-.eM 
-The
-.PN XPolygonRegion
-function returns a region for the polygon defined by the points array.
-For an explanation of fill_rule,
-see
-.PN XCreateGC .
-.LP
-.sp
-To set the clip-mask of a GC to a region, use
-.PN XSetRegion .
-.IN "XSetRegion" "" "@DEF@"
-.sM
-.FD 0
-XSetRegion\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIr\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      GC \fIgc\fP\^;
-.br
-      Region \fIr\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIgc\fP 1i
-Specifies the GC.
-.IP \fIr\fP 1i
-Specifies the region.
-.LP
-.eM
-The
-.PN XSetRegion
-function sets the clip-mask in the GC to the specified region.
-The region is specified relative to the drawable's origin.
-The resulting GC clip origin is implementation-dependent.
-Once it is set in the GC,
-the region can be destroyed.
-.LP 
-.sp
-To deallocate the storage associated with a specified region, use
-.PN XDestroyRegion .
-.IN "XDestroyRegion" "" "@DEF@"
-.sM
-.FD 0
-XDestroyRegion\^(\^\fIr\fP\^)
-.br
-      Region \fIr\fP\^;
-.FN
-.IP \fIr\fP 1i
-Specifies the region.
-.LP
-.eM
-.NH 3
-Moving or Shrinking Regions
-.XS
-\*(SN Moving or Shrinking Regions 
-.XE
-.LP
-To move a region by a specified amount, use 
-.PN XOffsetRegion .
-.IN "XOffsetRegion" "" "@DEF@"
-.sM
-.FD 0
-XOffsetRegion\^(\^\fIr\fP\^, \fIdx\fP\^, \fIdy\fP\^)
-.br
-      Region \fIr\fP\^;
-.br
-      int \fIdx\fP\^, \fIdy\fP\^;
-.FN
-.IP \fIr\fP 1i
-Specifies the region.
-.ds Dy move
-.IP \fIdx\fP 1i
-.br
-.ns
-.IP \fIdy\fP 1i
-Specify the x and y coordinates,
-which define the amount you want to \*(Dy the specified region.
-.LP
-.eM 
-.sp
-To reduce a region by a specified amount, use
-.PN XShrinkRegion .
-.IN "XShrinkRegion" "" "@DEF@"
-.sM
-.FD 0
-XShrinkRegion\^(\^\fIr\fP\^, \fIdx\fP\^, \fIdy\fP\^)
-.br
-      Region \fIr\fP\^;
-.br
-      int \fIdx\fP\^, \fIdy\fP\^;
-.FN
-.IP \fIr\fP 1i
-Specifies the region.
-.ds Dy shrink
-.IP \fIdx\fP 1i
-.br
-.ns
-.IP \fIdy\fP 1i
-Specify the x and y coordinates,
-which define the amount you want to \*(Dy the specified region.
-.LP
-.eM
-Positive values shrink the size of the region, 
-and negative values expand the region.
-.NH 3
-Computing with Regions
-.XS
-\*(SN Computing with Regions 
-.XE
-.LP
-.sp
-To generate the smallest rectangle enclosing a region, use
-.PN XClipBox .
-.IN "XClipBox" "" "@DEF@"
-.sM
-.FD 0
-XClipBox\^(\^\fIr\fP\^, \fIrect_return\fP\^)
-.br
-      Region \fIr\fP\^;
-.br
-      XRectangle *\fIrect_return\fP\^;
-.FN
-.IP \fIr\fP 1i
-Specifies the region.
-.IP \fIrect_return\fP 1i
-Returns the smallest enclosing rectangle.
-.LP
-.eM
-The
-.PN XClipBox
-function returns the smallest rectangle enclosing the specified region.
-.sp
-.LP
-To compute the intersection of two regions, use
-.PN XIntersectRegion .
-.IN "XIntersectRegion" "" "@DEF@"
-.sM
-.FD 0
-XIntersectRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^)
-.br
-      Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^;
-.FN
-.IP \fIsra\fP 1i
-.br
-.ns
-.IP \fIsrb\fP 1i
-Specify the two regions with which you want to perform the computation.
-.IP \fIdr_return\fP 1i
-Returns the result of the computation.
-.LP
-.eM
-.sp
-To compute the union of two regions, use
-.PN XUnionRegion .
-.IN "XUnionRegion" "" "@DEF@"
-.sM
-.FD 0
-XUnionRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^)
-.br
-      Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^;
-.FN
-.IP \fIsra\fP 1i
-.br
-.ns
-.IP \fIsrb\fP 1i
-Specify the two regions with which you want to perform the computation.
-.IP \fIdr_return\fP 1i
-Returns the result of the computation.
-.LP
-.eM
-.sp
-To create a union of a source region and a rectangle, use
-.PN XUnionRectWithRegion .
-.IN "XUnionRectWithRegion" "" "@DEF@"
-.sM
-.FD 0
-XUnionRectWithRegion\^(\^\fIrectangle\fP, \fIsrc_region\fP, \
-\fIdest_region_return\fP\^)
-.br
-     XRectangle *\fIrectangle\fP\^;
-.br
-     Region \fIsrc_region\fP\^;
-.br
-     Region \fIdest_region_return\fP\^;
-.FN
-.IP \fIrectangle\fP 1i
-Specifies the rectangle.
-.IP \fIsrc_region\fP 1i
-Specifies the source region to be used.
-.IP \fIdest_region_return\fP 1i
-Returns the destination region.
-.LP
-.eM
-The
-.PN XUnionRectWithRegion
-function updates the destination region from a union of the specified rectangle
-and the specified source region.
-.LP
-.sp
-To subtract two regions, use
-.PN XSubtractRegion .
-.IN "XSubtractRegion" "" "@DEF@"
-.sM
-.FD 0
-XSubtractRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^)
-.br
-      Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^;
-.FN
-.IP \fIsra\fP 1i
-.br
-.ns
-.IP \fIsrb\fP 1i
-Specify the two regions with which you want to perform the computation.
-.IP \fIdr_return\fP 1i
-Returns the result of the computation.
-.LP
-.eM
-The
-.PN XSubtractRegion
-function subtracts srb from sra and stores the results in dr_return.
-.LP
-.sp
-To calculate the difference between the union and intersection 
-of two regions, use
-.PN XXorRegion .
-.IN "XXorRegion" "" "@DEF@"
-.sM
-.FD 0
-XXorRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^)
-.br
-      Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^;
-.FN
-.IP \fIsra\fP 1i
-.br
-.ns
-.IP \fIsrb\fP 1i
-Specify the two regions with which you want to perform the computation.
-.IP \fIdr_return\fP 1i
-Returns the result of the computation.
-.LP
-.eM
-.NH 3
-Determining if Regions Are Empty or Equal
-.XS
-\*(SN Determining if Regions Are Empty or Equal 
-.XE
-.LP
-To determine if the specified region is empty, use
-.PN XEmptyRegion .
-.IN "XEmptyRegion" "" "@DEF@"
-.sM
-.FD 0
-Bool XEmptyRegion\^(\^\fIr\fP\^)
-.br
-      Region \fIr\fP\^;
-.FN
-.IP \fIr\fP 1i
-Specifies the region.
-.LP
-.eM 
-The
-.PN XEmptyRegion
-function returns
-.PN True
-if the region is empty.
-.LP
-.sp
-To determine if two regions have the same offset, size, and shape, use
-.PN XEqualRegion .
-.IN "XEqualRegion" "" "@DEF@"
-.sM
-.FD 0
-Bool XEqualRegion\^(\^\fIr1\fP\^, \fIr2\fP\^)
-.br
-      Region \fIr1\fP\^, \fIr2\fP\^;
-.FN
-.IP \fIr1\fP 1i
-.br
-.ns
-.IP \fIr2\fP 1i
-Specify the two regions.
-.LP
-.eM
-The
-.PN XEqualRegion
-function returns
-.PN True
-if the two regions have the same offset, size, and shape.
-.NH 3
-Locating a Point or a Rectangle in a Region
-.XS
-\*(SN Locating a Point or a Rectangle in a Region 
-.XE
-.LP
-To determine if a specified point resides in a specified region, use
-.PN XPointInRegion .
-.IN "XPointInRegion" "" "@DEF@"
-.sM
-.FD 0
-Bool XPointInRegion\^(\^\fIr\fP\^, \fIx\fP\^, \fIy\fP\^)
-.br
-      Region \fIr\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^;
-.FN
-.IP \fIr\fP 1i
-Specifies the region.
-.ds Xy , which define the point
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.LP
-.eM
-The
-.PN XPointInRegion
-function returns 
-.PN True
-if the point (x, y) is contained in the region r.
-.LP
-.sp
-To determine if a specified rectangle is inside a region, use
-.PN XRectInRegion .
-.IN "XRectInRegion" "" "@DEF@"
-.sM
-.FD 0
-int XRectInRegion\^(\^\fIr\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^)
-.br
-      Region \fIr\fP\^;
-.br
-      int \fIx\fP\^, \fIy\fP\^; 
-.br
-      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
-.FN
-.IP \fIr\fP 1i
-Specifies the region.
-.ds Xy , which define the coordinates of the upper-left corner of the rectangle
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates\*(Xy.
-.ds Wh , which define the rectangle
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height\*(Wh.
-.LP
-.eM 
-The
-.PN XRectInRegion
-function returns
-.PN RectangleIn
-if the rectangle is entirely in the specified region,
-.PN RectangleOut
-if the rectangle is entirely out of the specified region,
-and
-.PN RectanglePart
-if the rectangle is partially in the specified region.
-.NH 2
-Using Cut Buffers
-.XS
-\*(SN Using Cut Buffers 
-.XE
-.LP
-.IN "Cut Buffers"
-Xlib provides functions to manipulate cut buffers,
-a very simple form of cut-and-paste inter-client communication.
-Selections are a much more powerful and useful mechanism for
-interchanging data between clients (see section 4.5)
-and generally should be used instead of cut buffers.
-.LP
-Cut buffers are implemented as properties on the first root window
-of the display.
-The buffers can only contain text, in the STRING encoding.
-The text encoding is not changed by Xlib when fetching or storing.
-Eight buffers are provided
-and can be accessed as a ring or as explicit buffers (numbered 0 through 7).
-.LP
-.sp
-To store data in cut buffer 0, use 
-.PN XStoreBytes .
-.IN "XStoreBytes" "" "@DEF@"
-.sM
-.FD 0
-XStoreBytes\^(\^\fIdisplay\fP, \fIbytes\fP\^, \fInbytes\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      char *\fIbytes\fP\^;
-.br
-      int \^\fInbytes\fP\^;
-.br
-.FN 
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIbytes\fP 1i
-Specifies the bytes, which are not necessarily ASCII or null-terminated.
-.IP \fInbytes\fP 1i
-Specifies the number of bytes to be stored.
-.LP
-.eM
-The data can have embedded null characters
-and need not be null-terminated.
-The cut buffer's contents can be retrieved later by
-any client calling
-.PN XFetchBytes .
-.LP
-.PN XStoreBytes
-can generate a
-.PN BadAlloc
-error.
-.LP
-.sp
-To store data in a specified cut buffer, use
-.PN XStoreBuffer .
-.IN "XStoreBuffer" "" "@DEF@"
-.sM
-.FD 0
-XStoreBuffer\^(\^\fIdisplay\fP, \fIbytes\fP\^, \fInbytes\fP\^, \fIbuffer\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      char *\fIbytes\fP\^;
-.br
-      int \^\fInbytes\fP\^;
-.br
-      int \fIbuffer\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIbytes\fP 1i
-Specifies the bytes, which are not necessarily ASCII or null-terminated.
-.IP \fInbytes\fP 1i
-Specifies the number of bytes to be stored.
-.ds Fn in which you want to store the bytes
-.IP \fIbuffer\fP 1i
-Specifies the buffer \*(Fn.
-.LP
-.eM
-If an invalid buffer is specified, the call has no effect.
-The data can have embedded null characters
-and need not be null-terminated.
-.LP
-.PN XStoreBuffer
-can generate a
-.PN BadAlloc 
-error.
-.LP
-.sp
-To return data from cut buffer 0, use 
-.PN XFetchBytes .
-.IN "XFetchBytes" "" "@DEF@"
-.sM
-.FD 0
-char *XFetchBytes\^(\^\fIdisplay\fP, \fInbytes_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int *\fInbytes_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fInbytes_return\fP 1i
-Returns the number of bytes in the buffer.
-.LP
-.eM
-The
-.PN XFetchBytes
-function
-returns the number of bytes in the nbytes_return argument,
-if the buffer contains data.
-Otherwise, the function
-returns NULL and sets nbytes to 0.
-The appropriate amount of storage is allocated and the pointer returned.
-The client must free this storage when finished with it by calling
-.PN XFree .
-.LP
-.sp
-To return data from a specified cut buffer, use 
-.PN XFetchBuffer .
-.IN "XFetchBuffer" "" "@DEF@"
-.sM
-.FD 0
-char *XFetchBuffer\^(\^\fIdisplay\fP, \fInbytes_return\fP\^, \fIbuffer\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int *\fInbytes_return\fP\^;
-.br
-      int \fIbuffer\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fInbytes_return\fP 1i
-Returns the number of bytes in the buffer.
-.ds Fn from which you want the stored data returned
-.IP \fIbuffer\fP 1i
-Specifies the buffer \*(Fn.
-.LP
-.eM
-The
-.PN XFetchBuffer
-function returns zero to the nbytes_return argument 
-if there is no data in the buffer or if an invalid
-buffer is specified.
-.LP
-.sp
-To rotate the cut buffers, use 
-.PN XRotateBuffers .
-.IN "XRotateBuffers" "" "@DEF@"
-.sM
-.FD 0
-XRotateBuffers\^(\^\fIdisplay\fP, \fIrotate\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIrotate\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIrotate\fP 1i
-Specifies how much to rotate the cut buffers.
-.LP
-.eM 
-The
-.PN XRotateBuffers
-function rotates the cut
-buffers, such that buffer 0 becomes buffer n, 
-buffer 1 becomes n + 1 mod 8, and so on.
-This cut buffer numbering is global to the display.
-Note that
-.PN XRotateBuffers
-generates
-.PN BadMatch
-errors if any of the eight buffers have not been created.
-.NH 2
-Determining the Appropriate Visual Type
-.XS
-\*(SN Determining the Appropriate Visual Type
-.XE
-.LP
-A single display can support multiple screens.
-Each screen can have several different visual types supported 
-at different depths.
-You can use the functions described in this section to determine
-which visual to use for your application.
-.LP
-The functions in this section use the visual information masks and the
-.PN XVisualInfo 
-structure,
-which is defined in
-.hN X11/Xutil.h
-and contains:
-.sM
-.LP
-/* Visual information mask bits */
-.TS
-lw(.5i) lw(2.5i) lw(.8i).
-T{
-#define
-T}	T{
-.PN VisualNoMask
-T}	T{
-0x0
-T}
-T{
-#define
-T}	T{
-.PN VisualIDMask
-T}	T{
-0x1
-T}
-T{
-#define
-T}	T{
-.PN VisualScreenMask
-T}	T{
-0x2
-T}
-T{
-#define
-T}	T{
-.PN VisualDepthMask
-T}	T{
-0x4
-T}
-T{
-#define
-T}	T{
-.PN VisualClassMask
-T}	T{
-0x8
-T}
-T{
-#define
-T}	T{
-.PN VisualRedMaskMask
-T}	T{
-0x10
-T}
-T{
-#define
-T}	T{
-.PN VisualGreenMaskMask
-T}	T{
-0x20
-T}
-T{
-#define
-T}	T{
-.PN VisualBlueMaskMask
-T}	T{
-0x40
-T}
-T{
-#define
-T}	T{
-.PN VisualColormapSizeMask
-T}	T{
-0x80
-T}
-T{
-#define
-T}	T{
-.PN VisualBitsPerRGBMask
-T}	T{
-0x100
-T}
-T{
-#define
-T}	T{
-.PN VisualAllMask
-T}	T{
-0x1FF
-T}
-.TE
-.IN "XVisualInfo" "" "@DEF@"
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-/* Values */
-
-typedef struct {
-	Visual *visual;
-	VisualID visualid;
-	int screen;
-	unsigned int depth;
-	int class;
-	unsigned long red_mask;
-	unsigned long green_mask;
-	unsigned long blue_mask;
-	int colormap_size;
-	int bits_per_rgb;
-} XVisualInfo;
-.De
-.LP
-.eM
-To obtain a list of visual information structures that match a specified
-template, use
-.PN XGetVisualInfo .
-.IN "XGetVisualInfo" "" "@DEF@"
-.sM
-.FD 0
-XVisualInfo *XGetVisualInfo\^(\^\fIdisplay\fP, \fIvinfo_mask\fP, \fIvinfo_template\fP, \fInitems_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      long \fIvinfo_mask\fP\^;
-.br
-      XVisualInfo *\fIvinfo_template\fP\^;
-.br
-      int *\fInitems_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIvinfo_mask\fP 1i
-Specifies the visual mask value.
-.IP \fIvinfo_template\fP 1i
-Specifies the visual attributes that are to be used in matching the visual
-structures.
-.IP \fInitems_return\fP 1i
-Returns the number of matching visual structures.
-.LP
-.eM
-The
-.PN XGetVisualInfo
-function returns a list of visual structures that have attributes 
-equal to the attributes specified by vinfo_template.
-If no visual structures match the template using the specified vinfo_mask,
-.PN XGetVisualInfo
-returns a NULL.
-To free the data returned by this function, use
-.PN XFree .
-.LP
-.sp
-To obtain the visual information that matches the specified depth and
-class of the screen, use
-.PN XMatchVisualInfo .
-.IN "XMatchVisualInfo" "" "@DEF@"
-.sM
-.FD 0
-Status XMatchVisualInfo\^(\^\fIdisplay\fP, \fIscreen\fP, \fIdepth\fP, \fIclass\fP, \fIvinfo_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      int \fIscreen\fP\^;
-.br
-      int \fIdepth\fP\^;
-.br
-      int \fIclass\fP\^;
-.br
-      XVisualInfo *\fIvinfo_return\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIscreen\fP 1i
-Specifies the screen.
-.IP \fIdepth\fP 1i
-Specifies the depth of the screen.
-.IP \fIclass\fP 1i
-Specifies the class of the screen.
-.IP \fIvinfo_return\fP 1i
-Returns the matched visual information.
-.LP
-.eM
-The
-.PN XMatchVisualInfo
-function returns the visual information for a visual that matches the specified
-depth and class for a screen.
-Because multiple visuals that match the specified depth and class can exist,
-the exact visual chosen is undefined.
-If a visual is found,
-.PN XMatchVisualInfo
-returns nonzero and the information on the visual to vinfo_return.
-Otherwise, when a visual is not found,
-.PN XMatchVisualInfo
-returns zero.
-.NH 2
-Manipulating Images
-.XS
-\*(SN Manipulating Images 
-.XE
-.LP
-Xlib provides several functions that perform basic operations on images.
-All operations on images are defined using an 
-.PN XImage 
-structure, 
-as defined in
-.hN X11/Xlib.h .
-Because the number of different types of image formats can be very large,
-this hides details of image storage properly from applications.
-.LP
-This section describes the functions for generic operations on images.
-Manufacturers can provide very fast implementations of these for the
-formats frequently encountered on their hardware.
-These functions are neither sufficient nor desirable to use for general image
-processing.
-Rather, they are here to provide minimal functions on screen format
-images.
-The basic operations for getting and putting images are
-.PN XGetImage
-and 
-.PN XPutImage .
-.LP
-Note that no functions have been defined, as yet, to read and write images 
-to and from disk files.
-.LP
-The
-.PN XImage 
-structure describes an image as it exists in the client's memory.  
-The user can request that some of the members such as height, width, 
-and xoffset be changed when the image is sent to the server.
-Note that bytes_per_line in concert with offset can be used to
-extract a subset of the image.
-Other members (for example, byte order, bitmap_unit, and so forth)
-are characteristics of both the image and the server.  
-If these members
-differ between the image and the server, 
-.PN XPutImage 
-makes the appropriate conversions.
-The first byte of the first line of
-plane n must be located at the address (data + (n * height * bytes_per_line)).
-For a description of the 
-.PN XImage 
-structure,
-see section 8.7.
-.LP
-.sp
-To allocate an 
-.PN XImage 
-structure and initialize it with image format values from a display, use
-.PN XCreateImage .
-.IN "XCreateImage" "" "@DEF@"
-.sM
-.FD 0
-XImage *XCreateImage\^(\^\fIdisplay\fP, \fIvisual\fP, \fIdepth\fP, \fIformat\fP, \fIoffset\fP, \fIdata\fP, \fIwidth\fP, \fIheight\fP\^, \fIbitmap_pad\fP, 
-.br
-                        \fIbytes_per_line\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Visual *\fIvisual\fP\^;
-.br
-      unsigned int \fIdepth\fP\^;
-.br
-      int \fIformat\fP\^;
-.br
-      int \fIoffset\fP\^;
-.br
-      char *\fIdata\fP\^;
-.br
-      unsigned int \fIwidth\fP\^;
-.br
-      unsigned int \fIheight\fP\^;
-.br
-      int \fIbitmap_pad\fP\^;
-.br
-      int \fIbytes_per_line\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIvisual\fP 1i
-Specifies the
-.PN Visual
-structure.
-.IP \fIdepth\fP 1i
-Specifies the depth of the image.
-.IP \fIformat\fP 1i
-Specifies the format for the image.
-You can pass
-.PN XYBitmap ,
-.PN XYPixmap ,
-or 
-.PN ZPixmap .
-.IP \fIoffset\fP 1i
-Specifies the number of pixels to ignore at the beginning of the scanline.
-.IP \fIdata\fP 1i
-Specifies the image data.
-.IP \fIwidth\fP 1i
-Specifies the width of the image, in pixels.
-.IP \fIheight\fP 1i
-Specifies the height of the image, in pixels.
-.IP \fIbitmap_pad\fP 1i
-Specifies the quantum of a scanline (8, 16, or 32).
-In other words, the start of one scanline is separated in client memory from 
-the start of the next scanline by an integer multiple of this many bits.  
-.IP \fIbytes_per_line\fP 1i
-Specifies the number of bytes in the client image between
-the start of one scanline and the start of the next.  
-.LP
-.eM
-The
-.PN XCreateImage
-function allocates the memory needed for an
-.PN XImage
-structure for the
-specified display but does not allocate space for the image itself.
-Rather, it initializes the structure byte-order, bit-order, and bitmap-unit
-values from the display and returns a pointer to the 
-.PN XImage 
-structure.
-The red, green, and blue mask values are defined for Z format images only
-and are derived from the 
-.PN Visual 
-structure passed in.
-Other values also are passed in.
-The offset permits the rapid displaying of the image without requiring each 
-scanline to be shifted into position.
-If you pass a zero value in bytes_per_line,
-Xlib assumes that the scanlines are contiguous
-in memory and calculates the value of bytes_per_line itself.
-.LP
-Note that when the image is created using
-.PN XCreateImage ,
-.PN XGetImage ,
-or
-.PN XSubImage ,
-the destroy procedure that the 
-.PN XDestroyImage
-function calls frees both the image structure 
-and the data pointed to by the image structure.
-.LP
-The basic functions used to get a pixel, set a pixel, create a subimage,
-and add a constant value to an image are defined in the image object.
-The functions in this section are really macro invocations of the functions
-in the image object and are defined in
-.hN X11/Xutil.h .
-.LP
-.sp
-To obtain a pixel value in an image, use
-.PN XGetPixel .
-.IN "XGetPixel" "" "@DEF@"
-.sM
-.FD 0
-unsigned long XGetPixel\^(\^\fIximage\fP, \fIx\fP, \fIy\fP\^)
-.br
-      XImage *\fIximage\fP\^;
-.br
-      int \fIx\fP\^;
-.br
-      int \fIy\fP\^;
-.FN
-.IP \fIximage\fP 1i
-Specifies the image.
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates.
-.LP
-.eM
-The
-.PN XGetPixel
-function returns the specified pixel from the named image.
-The pixel value is returned in normalized format (that is,
-the least significant byte of the long is the least significant byte
-of the pixel).
-The image must contain the x and y coordinates.
-.LP
-.sp
-To set a pixel value in an image, use
-.PN XPutPixel .
-.IN "XPutPixel" "" "@DEF@"
-.sM
-.FD 0
-XPutPixel\^(\^\fIximage\fP, \fIx\fP, \fIy\fP, \fIpixel\fP\^)
-.br
-      XImage *\fIximage\fP\^;
-.br
-      int \fIx\fP\^;
-.br
-      int \fIy\fP\^;
-.br
-      unsigned long \fIpixel\fP\^;
-.FN
-.IP \fIximage\fP 1i
-Specifies the image.
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates.
-.IP \fIpixel\fP 1i
-Specifies the new pixel value.
-.LP
-.eM
-The
-.PN XPutPixel
-function overwrites the pixel in the named image with the specified pixel value.
-The input pixel value must be in normalized format
-(that is, the least significant byte of the long is the least significant
-byte of the pixel).
-The image must contain the x and y coordinates.
-.LP
-.sp
-To create a subimage, use
-.PN XSubImage .
-.IN "XSubImage" "" "@DEF@"
-.sM
-.FD 0
-XImage *XSubImage\^(\^\fIximage\fP, \fIx\fP, \fIy\fP, \fIsubimage_width\fP, \fIsubimage_height\fP\^)
-.br
-      XImage *\fIximage\fP\^;
-.br
-      int \fIx\fP\^;
-.br
-      int \fIy\fP\^;
-.br
-      unsigned int \fIsubimage_width\fP\^;
-.br
-      unsigned int \fIsubimage_height\fP\^;
-.FN
-.IP \fIximage\fP 1i
-Specifies the image.
-.IP \fIx\fP 1i
-.br
-.ns
-.IP \fIy\fP 1i
-Specify the x and y coordinates.
-.IP \fIsubimage_width\fP 1i
-Specifies the width of the new subimage, in pixels.
-.IP \fIsubimage_height\fP 1i
-Specifies the height of the new subimage, in pixels.
-.LP
-.eM
-The
-.PN XSubImage
-function creates a new image that is a subsection of an existing one.
-It allocates the memory necessary for the new
-.PN XImage
-structure
-and returns a pointer to the new image.
-The data is copied from the source image,
-and the image must contain the rectangle defined by x, y, subimage_width,
-and subimage_height.
-.LP
-.sp
-To increment each pixel in an image by a constant value, use
-.PN XAddPixel .
-.IN "XAddPixel" "" "@DEF@"
-.sM
-.FD 0
-XAddPixel\^(\^\fIximage\fP, \fIvalue\fP\^)
-.br
-      XImage *\fIximage\fP\^;
-.br
-      long \fIvalue\fP\^;
-.FN
-.IP \fIximage\fP 1i
-Specifies the image.
-.IP \fIvalue\fP 1i
-Specifies the constant value that is to be added.
-.LP
-.eM
-The
-.PN XAddPixel
-function adds a constant value to every pixel in an image.
-It is useful when you have a base pixel value from allocating
-color resources and need to manipulate the image to that form.
-.LP
-.sp
-To deallocate the memory allocated in a previous call to
-.PN XCreateImage ,
-use
-.PN XDestroyImage .
-.IN "XDestroyImage" "" "@DEF@"
-.sM
-.FD 0
-XDestroyImage\^(\^\fIximage\fP\^)
-.br
-        XImage *\^\fIximage\fP\^; 
-.FN
-.IP \fIximage\fP 1i
-Specifies the image.
-.LP
-.eM
-The
-.PN XDestroyImage
-function deallocates the memory associated with the
-.PN XImage
-structure.
-.LP
-Note that when the image is created using
-.PN XCreateImage ,
-.PN XGetImage ,
-or 
-.PN XSubImage ,
-the destroy procedure that this macro calls
-frees both the image structure and the data pointed to by the image structure. 
-.NH 2
-Manipulating Bitmaps
-.XS
-\*(SN Manipulating Bitmaps 
-.XE
-.LP
-Xlib provides functions that you can use to read a bitmap from a file,
-save a bitmap to a file, or create a bitmap. 
-This section describes those functions that transfer bitmaps to and
-from the client's file system, thus allowing their reuse in a later
-connection (for example, from an entirely different client or to a
-different display or server).
-.LP
-The X version 11 bitmap file format is:
-.LP
-.sM
-.Ds 0
-#define \fIname\fP_width \fIwidth\fP
-#define \fIname\fP_height \fIheight\fP
-#define \fIname\fP_x_hot \fIx\fP
-#define \fIname\fP_y_hot \fIy\fP
-static unsigned char \fIname\fP_bits[] = { 0x\fINN\fP,... }
-.De
-.LP
-.eM
-The lines for the variables ending with _x_hot and _y_hot suffixes are optional
-because they are present only if a hotspot has been defined for this bitmap.
-The lines for the other variables are required.
-The word ``unsigned'' is optional;
-that is, the type of the _bits array can be ``char'' or ``unsigned char''.
-The _bits array must be large enough to contain the size bitmap.
-The bitmap unit is 8.
-.LP
-.sp
-To read a bitmap from a file and store it in a pixmap, use
-.PN XReadBitmapFile .
-.IN "XReadBitmapFile" "" "@DEF@"
-.sM
-.FD 0
-int XReadBitmapFile(\^\fIdisplay\fP, \fId\fP, \fIfilename\fP, \fIwidth_return\fP, \fIheight_return\fP, \fIbitmap_return\fP, \fIx_hot_return\fP, 
-.br
-                       \fIy_hot_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      char *\fIfilename\fP\^;
-.br
-      unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^;
-.br
-      Pixmap *\fIbitmap_return\fP\^;
-.br
-      int *\fIx_hot_return\fP, *\fIy_hot_return\fP\^;	
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Dr \ that indicates the screen
-.IP \fId\fP 1i
-Specifies the drawable\*(Dr. 
-.IP \fIfilename\fP 1i
-Specifies the file name to use.
-The format of the file name is operating-system dependent.
-.IP \fIwidth_return\fP 1i
-.br
-.ns
-.IP \fIheight_return\fP 1i
-Return the width and height values of the read in bitmap file.
-.IP \fIbitmap_return\fP 1i
-Returns the bitmap that is created.
-.IP \fIx_hot_return\fP 1i
-.br
-.ns
-.IP \fIy_hot_return\fP 1i
-Return the hotspot coordinates.
-.LP
-.eM
-The
-.PN XReadBitmapFile
-function reads in a file containing a bitmap.
-The file is parsed in the encoding of the current locale.
-The ability to read other than the standard format 
-is implementation-dependent.
-If the file cannot be opened, 
-.PN XReadBitmapFile 
-returns 
-.PN BitmapOpenFailed .  
-If the file can be opened but does not contain valid bitmap data, 
-it returns 
-.PN BitmapFileInvalid .  
-If insufficient working storage is allocated,
-it returns
-.PN BitmapNoMemory .  
-If the file is readable and valid,
-it returns 
-.PN BitmapSuccess .
-.LP
-.PN XReadBitmapFile 
-returns the bitmap's height and width, as read
-from the file, to width_return and height_return.
-It then creates a pixmap of the appropriate size, 
-reads the bitmap data from the file into the pixmap,
-and assigns the pixmap to the caller's variable bitmap.  
-The caller must free the bitmap using 
-.PN XFreePixmap 
-when finished.
-If \fIname\fP_x_hot and \fIname\fP_y_hot exist,
-.PN XReadBitmapFile 
-returns them to x_hot_return and y_hot_return;
-otherwise, it returns \-1,\-1.
-.LP
-.PN XReadBitmapFile
-can generate
-.PN BadAlloc ,
-.PN BadDrawable ,
-and
-.PN BadGC
-errors.
-.LP
-.sp
-To read a bitmap from a file and return it as data, use
-.PN XReadBitmapFileData .
-.IN "XReadBitmapFileData" "" "@DEF@"
-.sM
-.FD 0
-int XReadBitmapFileData(\^\fIfilename\fP, \fIwidth_return\fP, \fIheight_return\fP, \fIdata_return\fP, \fIx_hot_return\fP, \fIy_hot_return\fP\^)
-.br
-      char *\fIfilename\fP\^;
-.br
-      unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^;
-.br
-      unsigned char *\fIdata_return\fP\^;
-.br
-      int *\fIx_hot_return\fP, *\fIy_hot_return\fP\^;	
-.FN
-.IP \fIfilename\fP 1i
-Specifies the file name to use.
-The format of the file name is operating-system dependent.
-.IP \fIwidth_return\fP 1i
-.br
-.ns
-.IP \fIheight_return\fP 1i
-Return the width and height values of the read in bitmap file.
-.IP \fIdata_return\fP 1i
-Returns the bitmap data.
-.IP \fIx_hot_return\fP 1i
-.br
-.ns
-.IP \fIy_hot_return\fP 1i
-Return the hotspot coordinates.
-.LP
-.eM
-The
-.PN XReadBitmapFileData
-function reads in a file containing a bitmap, in the same manner as
-.PN XReadBitmapFile ,
-but returns the data directly rather than creating a pixmap in the server.
-The bitmap data is returned in data_return; the client must free this
-storage when finished with it by calling
-.PN XFree .
-The status and other return values are the same as for
-.PN XReadBitmapFile .
-.LP
-.sp
-To write out a bitmap from a pixmap to a file, use
-.PN XWriteBitmapFile .
-.IN "XWriteBitmapFile" "" "@DEF@"
-.sM
-.FD 0
-int XWriteBitmapFile(\^\fIdisplay\fP, \fIfilename\fP, \fIbitmap\fP, \fIwidth\fP, \fIheight\fP, \fIx_hot\fP, \fIy_hot\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      char *\fIfilename\fP\^;
-.br
-      Pixmap \fIbitmap\fP\^;
-.br
-      unsigned int \fIwidth\fP, \fIheight\fP\^;
-.br
-      int \fIx_hot\fP, \fIy_hot\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIfilename\fP 1i
-Specifies the file name to use.
-The format of the file name is operating-system dependent.
-.IP \fIbitmap\fP 1i
-Specifies the bitmap.
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height.
-.IP \fIx_hot\fP 1i
-.br
-.ns
-.IP \fIy_hot\fP 1i
-Specify where to place the hotspot coordinates (or \-1,\-1 if none are present)
-in the file.
-.LP
-.eM
-The
-.PN XWriteBitmapFile
-function writes a bitmap out to a file in the X Version 11 format.
-The name used in the output file is derived from the file name
-by deleting the directory prefix.
-The file is written in the encoding of the current locale.
-If the file cannot be opened for writing, 
-it returns 
-.PN BitmapOpenFailed .  
-If insufficient memory is allocated,
-.PN XWriteBitmapFile
-returns
-.PN BitmapNoMemory ;
-otherwise, on no error,
-it returns
-.PN BitmapSuccess .
-If x_hot and y_hot are not \-1, \-1, 
-.PN XWriteBitmapFile
-writes them out as the hotspot coordinates for the bitmap.
-.LP
-.PN XWriteBitmapFile
-can generate
-.PN BadDrawable
-and
-.PN BadMatch
-errors.
-.LP
-.sp
-To create a pixmap and then store bitmap-format data into it, use
-.PN XCreatePixmapFromBitmapData .
-.IN "XCreatePixmapFromBitmapData" "" "@DEF@"
-.sM
-.FD 0
-Pixmap XCreatePixmapFromBitmapData\^(\^\fIdisplay\fP, \fId\fP, \fIdata\fP, \fIwidth\fP, \fIheight\fP, \fIfg\fP, \fIbg\fP, \fIdepth\fP\^)
-.br
-     Display *\fIdisplay\fP\^;
-.br
-     Drawable \fId\fP\^;
-.br
-     char *\fIdata\fP\^;
-.br
-     unsigned int \fIwidth\fP, \fIheight\fP\^;
-.br
-     unsigned long \fIfg\fP, \fIbg\fP\^;
-.br
-     unsigned int \fIdepth\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Dr \ that indicates the screen
-.IP \fId\fP 1i
-Specifies the drawable\*(Dr. 
-.IP \fIdata\fP 1i
-Specifies the data in bitmap format.
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height.
-.IP \fIfg\fP 1i
-.br
-.ns
-.IP \fIbg\fP 1i
-Specify the foreground and background pixel values to use.
-.IP \fIdepth\fP 1i
-Specifies the depth of the pixmap.
-.LP
-.eM
-The
-.PN XCreatePixmapFromBitmapData
-function creates a pixmap of the given depth and then does a bitmap-format
-.PN XPutImage
-of the data into it.
-The depth must be supported by the screen of the specified drawable,
-or a
-.PN BadMatch
-error results.
-.LP
-.PN XCreatePixmapFromBitmapData
-can generate
-.PN BadAlloc ,
-.PN BadDrawable ,
-.PN BadGC ,
-and
-.PN BadValue
-errors.
-.LP
-.sp
-To include a bitmap written out by 
-.PN XWriteBitmapFile 
-.IN "XWriteBitmapFile"
-in a program directly, as opposed to reading it in every time at run time, use
-.PN XCreateBitmapFromData .
-.IN "XCreateBitmapFromData" "" "@DEF@"
-.sM
-.FD 0
-Pixmap XCreateBitmapFromData(\^\fIdisplay\fP, \fId\fP, \fIdata\fP, \fIwidth\fP, \fIheight\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      Drawable \fId\fP\^;
-.br
-      char *\fIdata\fP\^;
-.br
-      unsigned int \fIwidth\fP, \fIheight\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.ds Dr \ that indicates the screen
-.IP \fId\fP 1i
-Specifies the drawable\*(Dr. 
-.IP \fIdata\fP 1i
-Specifies the location of the bitmap data.
-.IP \fIwidth\fP 1i
-.br
-.ns
-.IP \fIheight\fP 1i
-Specify the width and height.
-.LP
-.eM
-The
-.PN XCreateBitmapFromData
-function allows you to include in your C program (using
-.PN #include )
-a bitmap file that was written out by
-.PN XWriteBitmapFile
-(X version 11 format only) without reading in the bitmap file.
-The following example creates a gray bitmap:
-.LP
-.Ds 0
-#include "gray.bitmap"
-.sp 6p
-Pixmap bitmap;
-bitmap = XCreateBitmapFromData(display, window, gray_bits, gray_width, gray_height);
-.De
-.LP
-If insufficient working storage was allocated,
-.PN XCreateBitmapFromData
-returns
-.PN None .
-It is your responsibility to free the
-bitmap using
-.PN XFreePixmap
-when finished.
-.LP
-.PN XCreateBitmapFromData
-can generate
-.PN BadAlloc
-and
-.PN BadGC
-errors.
-.NH 2
-Using the Context Manager
-.XS
-\*(SN Using the Context Manager 
-.XE
-.LP
-The context manager provides a way of associating data with an X resource ID
-(mostly typically a window) in your program.  
-Note that this is local to your program;
-the data is not stored in the server on a property list.
-Any amount of data in any number of pieces can be associated with a
-resource ID,
-and each piece of data has a type associated with it.  
-The context manager requires knowledge of the resource ID
-and type to store or retrieve data.
-.LP
-Essentially, the context manager can be viewed as a two-dimensional, 
-sparse array:  one dimension is subscripted by the X resource ID
-and the other by a context type field.
-Each entry in the array contains a pointer to the data.
-Xlib provides context management functions with which you can
-save data values, get data values, delete entries, and create a unique
-context type.
-The symbols used are in
-.hN X11/Xutil.h .
-.LP
-.sp
-To save a data value that corresponds to a resource ID and context type, use
-.PN XSaveContext .
-.IN "XSaveContext" "" "@DEF@"
-.sM
-.FD 0
-int XSaveContext(\^\fIdisplay\fP, \fIrid\fP, \fIcontext\fP, \fIdata\fP\^)
-.br
-      Display *\fIdisplay\fP\^;	
-.br
-      XID \fIrid\fP\^;
-.br
-      XContext \fIcontext\fP\^;
-.br
-      XPointer \fIdata\fP\^;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIrid\fP 1i
-Specifies the resource ID with which the data is associated.
-.IP \fIcontext\fP 1i
-Specifies the context type to which the data belongs.
-.IP \fIdata\fP 1i
-Specifies the data to be associated with the window and type.
-.LP
-.eM
-If an entry with the specified resource ID and type already exists,
-.PN XSaveContext
-overrides it with the specified context.
-The
-.PN XSaveContext
-function returns a nonzero error code if an error has occurred
-and zero otherwise.
-Possible errors are
-.PN XCNOMEM
-(out of memory).
-.LP
-.sp
-To get the data associated with a resource ID and type, use
-.PN XFindContext .
-.IN "XFindContext" "" "@DEF@"
-.sM
-.FD 0
-int XFindContext(\^\fIdisplay\fP, \fIrid\fP, \fIcontext\fP, \fIdata_return\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XID \fIrid\fP\^;
-.br
-      XContext \fIcontext\fP\^;
-.br
-      XPointer *\fIdata_return\fP\^;	
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIrid\fP 1i
-Specifies the resource ID with which the data is associated.
-.IP \fIcontext\fP 1i
-Specifies the context type to which the data belongs.
-.IP \fIdata_return\fP 1i
-Returns the data.
-.LP
-.eM
-Because it is a return value,
-the data is a pointer.
-The
-.PN XFindContext
-function returns a nonzero error code if an error has occurred
-and zero otherwise.
-Possible errors are
-.PN XCNOENT
-(context-not-found).
-.LP
-.sp
-To delete an entry for a given resource ID and type, use
-.PN XDeleteContext .
-.IN "XDeleteContext" "" "@DEF@"
-.sM
-.FD 0
-int XDeleteContext(\^\fIdisplay\fP, \fIrid\fP, \fIcontext\fP\^)
-.br
-      Display *\fIdisplay\fP\^;
-.br
-      XID \fIrid\fP;
-.br
-      XContext \fIcontext\fP;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the connection to the X server.
-.IP \fIrid\fP 1i
-Specifies the resource ID with which the data is associated.
-.IP \fIcontext\fP 1i
-Specifies the context type to which the data belongs.
-.LP
-.eM
-The
-.PN XDeleteContext
-function deletes the entry for the given resource ID 
-and type from the data structure.
-This function returns the same error codes that
-.PN XFindContext
-returns if called with the same arguments.
-.PN XDeleteContext
-does not free the data whose address was saved.
-.LP
-.sp
-To create a unique context type that may be used in subsequent calls to
-.PN XSaveContext 
-and
-.PN XFindContext ,
-use
-.PN XUniqueContext .
-.IN "XUniqueContext" "" "@DEF@"
-.sM
-.FD 0
-XContext XUniqueContext(\^)
-.FN
-.LP
-.eM
-.bp
diff --git a/libX11/specs/libX11/CH16.xml b/libX11/specs/libX11/CH16.xml
new file mode 100644
index 000000000..7575c4a61
--- /dev/null
+++ b/libX11/specs/libX11/CH16.xml
@@ -0,0 +1,4136 @@
+<chapter id="application_utility_functions">

+<title>Application Utility Functions</title>

+<!-- .sp 2 -->

+<!-- .nr H1 16 -->

+<!-- .nr H2 0 -->

+<!-- .nr H3 0 -->

+<!-- .nr H4 0 -->

+<!-- .nr H5 0 -->

+<!-- .na -->

+<para>

+<!-- .LP -->

+<!-- .XS -->

+<!-- Chapter 16: Application Utility Functions  -->

+<!-- .XE -->

+Once you have initialized the X system,

+you can use the Xlib utility functions to:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Use keyboard utility functions

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Use Latin-1 keyboard event functions

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Allocate permanent storage

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Parse the window geometry

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Manipulate regions

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Use cut buffers

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Determine the appropriate visual type

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Manipulate images

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Manipulate bitmaps

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Use the context manager

+    </para>

+  </listitem>

+</itemizedlist>

+<para>

+<!-- .LP -->

+As a group,

+the functions discussed in this chapter provide the functionality that 

+is frequently needed and that spans toolkits.

+Many of these functions do not generate actual protocol requests to the server.

+</para>

+<sect1 id="Using_Keyboard_Utility_Functions">

+<title>Using Keyboard Utility Functions</title>

+<!-- .XS -->

+<!-- (SN Using Keyboard Utility Functions  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+This section discusses mapping between KeyCodes and KeySyms,

+classifying KeySyms, and mapping between KeySyms and string names.

+The first three functions in this section operate on a cached copy of the

+server keyboard mapping.

+The first four KeySyms for each KeyCode

+are modified according to the rules given in section 12.7.

+To obtain the untransformed KeySyms defined for a key,

+use the functions described in section 12.7.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain a KeySym for the KeyCode of an event, use

+<function>XLookupKeysym</function>.

+<indexterm significance="preferred"><primary>XLookupKeysym</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>KeySym <function> XLookupKeysym</function></funcdef>

+  <paramdef>XKeyEvent<parameter> *key_event</parameter></paramdef>

+  <paramdef>int<parameter> index</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>key_event</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the 

+<function>KeyPress</function>

+or

+<function>KeyRelease</function>

+event.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>index</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the index into the KeySyms list for the event's KeyCode.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XLookupKeysym</function>

+function uses a given keyboard event and the index you specified to return

+the KeySym from the list that corresponds to the KeyCode member in the

+<function>XKeyPressedEvent</function>

+or

+<function>XKeyReleasedEvent</function>

+structure.

+If no KeySym is defined for the KeyCode of the event,

+<function>XLookupKeysym</function>

+returns

+<function>NoSymbol</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain a KeySym for a specific KeyCode, use

+<function>XKeycodeToKeysym</function>.

+<indexterm significance="preferred"><primary>XKeycodeToKeysym</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>KeySym <function> XKeycodeToKeysym</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>KeyCode<parameter> keycode</parameter></paramdef>

+  <paramdef>int<parameter> index</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keycode</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the KeyCode.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>index</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the element of KeyCode vector.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XKeycodeToKeysym</function>

+function uses internal Xlib tables

+and returns the KeySym defined for the specified KeyCode and

+the element of the KeyCode vector.

+If no symbol is defined,

+<function>XKeycodeToKeysym</function>

+returns

+<function>NoSymbol</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain a KeyCode for a key having a specific KeySym, use

+<function>XKeysymToKeycode</function>.

+<indexterm significance="preferred"><primary>XKeysymToKeycode</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>KeyCode <function> XKeysymToKeycode</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>KeySym<parameter> keysym</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keysym</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the KeySym that is to be searched for.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If the specified KeySym is not defined for any KeyCode,

+<function>XKeysymToKeycode</function>

+returns zero.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+The mapping between KeyCodes and KeySyms is cached internal to Xlib.

+When this information is changed at the server, an Xlib function must

+be called to refresh the cache.

+To refresh the stored modifier and keymap information, use

+<function>XRefreshKeyboardMapping</function>.

+<indexterm significance="preferred"><primary>XRefreshKeyboardMapping</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XRefreshKeyboardMapping</function></funcdef>

+  <paramdef>XMappingEvent<parameter> *event_map</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_map</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the mapping event that is to be used.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XRefreshKeyboardMapping</function>

+function refreshes the stored modifier and keymap information.

+You usually call this function when a

+<function>MappingNotify</function>

+event with a request member of

+<function>MappingKeyboard</function>

+or

+<function>MappingModifier</function>

+occurs.

+The result is to update Xlib's knowledge of the keyboard.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the uppercase and lowercase forms of a KeySym, use

+<function>XConvertCase</function>.

+<indexterm significance="preferred"><primary>XConvertCase</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function> XConvertCase</function></funcdef>

+  <paramdef>KeySym<parameter> keysym</parameter></paramdef>

+  <paramdef>KeySym<parameter> *lower_return</parameter></paramdef>

+  <paramdef>KeySym<parameter> *upper_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<!-- .ds Fn converted -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keysym</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the KeySym that is to be (Fn.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>lower_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the lowercase form of keysym, or keysym.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>upper_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the uppercase form of keysym, or keysym.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XConvertCase</function>

+function returns the uppercase and lowercase forms of the specified Keysym,

+if the KeySym is subject to case conversion;

+otherwise, the specified KeySym is returned to both lower_return and

+upper_return.

+Support for conversion of other than Latin and Cyrillic KeySyms is

+implementation-dependent.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+KeySyms have string names as well as numeric codes.

+To convert the name of the KeySym to the KeySym code, use

+<function>XStringToKeysym</function>.

+<indexterm significance="preferred"><primary>XStringToKeysym</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>KeySym <function> XStringToKeysym</function></funcdef>

+  <paramdef>char<parameter> *string</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the name of the KeySym that is to be converted.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Standard KeySym names are obtained from

+<!-- .hN X11/keysymdef.h -->

+by removing the XK_ prefix from each name.

+KeySyms that are not part of the Xlib standard also may be obtained

+with this function.

+The set of KeySyms that are available in this manner 

+and the mechanisms by which Xlib obtains them is implementation-dependent.

+</para>

+<para>

+<!-- .LP -->

+If the KeySym name is not in the Host Portable Character Encoding,

+the result is implementation-dependent.

+If the specified string does not match a valid KeySym,

+<function>XStringToKeysym</function>

+returns

+<function>NoSymbol</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To convert a KeySym code to the name of the KeySym, use

+<function>XKeysymToString</function>.

+<indexterm significance="preferred"><primary>XKeysymToString</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char *<function> XKeysymToString</function></funcdef>

+  <paramdef>KeySym<parameter> keysym</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<!-- .ds Fn converted -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keysym</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the KeySym that is to be (Fn.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The returned string is in a static area and must not be modified.

+The returned string is in the Host Portable Character Encoding.

+If the specified KeySym is not defined,

+<function>XKeysymToString</function>

+returns a NULL.

+</para>

+<sect2 id="KeySym_Classification_Macros">

+<title>KeySym Classification Macros</title>

+<!-- .XS -->

+<!-- (SN KeySym Classification Macros -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+You may want to test if a KeySym is, for example, 

+on the keypad or on one of the function keys.

+You can use KeySym macros to perform the following tests.

+</para>

+<para>IsCursorKey(<emphasis remap='I'>keysym</emphasis>)</para>

+<!-- .FN -->

+<!-- .ds Fn tested -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keysym</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the KeySym that is to be tested.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>IsCursorKey</primary></indexterm>

+Returns

+<function>True</function>

+if the specified KeySym is a cursor key.

+</para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+<para>IsFunctionKey(<emphasis remap='I'>keysym</emphasis>)</para>

+<!-- .FN -->

+<!-- .ds Fn tested -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keysym</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the KeySym that is to be tested.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>IsFunctionKey</primary></indexterm>

+Returns 

+<function>True</function>

+if the specified KeySym is a function key.

+</para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+<para>IsKeypadKey(<emphasis remap='I'>keysym</emphasis>)</para>

+<!-- .FN -->

+<!-- .ds Fn tested -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keysym</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the KeySym that is to be (Fn.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>IsKeypadKey</primary></indexterm>

+Returns

+<function>True</function>

+if the specified KeySym is a standard keypad key.

+</para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+<para>IsPrivateKeypadKey(<emphasis remap='I'>keysym</emphasis>)</para>

+

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keysym</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the KeySym that is to be (Fn.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>IsPrivateKeypadKey</primary></indexterm>

+Returns

+<function>True</function>

+if the specified KeySym is a vendor-private keypad key.

+</para>

+

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+<para>IsMiscFunctionKey(<emphasis remap='I'>keysym</emphasis>)</para>

+<!-- .FN -->

+<!-- .ds Fn tested -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keysym</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the KeySym that is to be (Fn.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>IsMiscFunctionKey</primary></indexterm>

+Returns 

+<function>True</function>

+if the specified KeySym is a miscellaneous function key.

+</para>

+<!-- .LP -->

+<!-- .sp -->

+<!-- .sM -->

+<para>IsModifierKey(<emphasis remap='I'>keysym</emphasis>)</para>

+

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keysym</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the KeySym that is to be tested.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>IsModifierKey</primary></indexterm>

+Returns 

+<function>True</function>

+if the specified KeySym is a modifier key.

+</para>

+

+<para>IsPFKey(<emphasis remap='I'>keysym</emphasis>)</para>

+

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keysym</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the KeySym that is to be tested.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<indexterm significance="preferred"><primary>IsPFKey</primary></indexterm>

+Returns 

+<function>True</function>

+if the specified KeySym is a PF key.

+</para>

+</sect2>

+</sect1>

+<sect1 id="Using_Latin_Keyboard_Event_Functions">

+<title>Using Latin-1 Keyboard Event Functions</title>

+<!-- .XS -->

+<!-- (SN Using Latin-1 Keyboard Event Functions  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Chapter 13 describes internationalized text input facilities,

+but sometimes it is expedient to write an application that

+only deals with Latin-1 characters and ASCII controls,

+so Xlib provides a simple function for that purpose.

+<function>XLookupString</function>

+handles the standard modifier semantics described in section 12.7.

+This function does not use any of the input method facilities

+described in chapter 13 and does not depend on the current locale.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To map a key event to an ISO Latin-1 string, use

+<function>XLookupString</function>.

+<indexterm significance="preferred"><primary>XLookupString</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XLookupString</function></funcdef>

+  <paramdef>XKeyEvent<parameter> *event_struct</parameter></paramdef>

+  <paramdef>char<parameter> *buffer_return</parameter></paramdef>

+  <paramdef>int<parameter> bytes_buffer</parameter></paramdef>

+  <paramdef>KeySym<parameter> *keysym_return</parameter></paramdef>

+  <paramdef>XComposeStatus<parameter> *status_in_out</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>event_struct</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the key event structure to be used.

+You can pass

+<function>XKeyPressedEvent</function>

+or

+<function>XKeyReleasedEvent</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>buffer_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the translated characters.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>bytes_buffer</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the length of the buffer.

+No more than bytes_buffer of translation are returned.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keysym_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the KeySym computed from the event if this argument is not NULL.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>status_in_out</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies or returns the 

+<function>XComposeStatus </function>

+structure or NULL.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XLookupString</function>

+function translates a key event to a KeySym and a string.

+The KeySym is obtained by using the standard interpretation of the

+<function>Shift</function>,

+<function>Lock</function>,

+group, and numlock modifiers as defined in the X Protocol specification.

+If the KeySym has been rebound (see

+<function>XRebindKeysym</function>),

+the bound string will be stored in the buffer.

+Otherwise, the KeySym is mapped, if possible, to an ISO Latin-1 character

+or (if the Control modifier is on) to an ASCII control character,

+and that character is stored in the buffer.

+<function>XLookupString</function>

+returns the number of characters that are stored in the buffer.

+</para>

+<para>

+<!-- .LP -->

+If present (non-NULL),

+the

+<function>XComposeStatus</function>

+structure records the state,

+which is private to Xlib,

+that needs preservation across calls to

+<function>XLookupString</function>

+to implement compose processing.

+The creation of

+<function>XComposeStatus</function>

+structures is implementation-dependent;

+a portable program must pass NULL for this argument.

+</para>

+<para>

+<!-- .LP -->

+<function>XLookupString</function>

+depends on the cached keyboard information mentioned in the

+previous section, so it is necessary to use

+<function>XRefreshKeyboardMapping</function>

+to keep this information up-to-date.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To rebind the meaning of a KeySym for

+<function>XLookupString</function>,

+use

+<function>XRebindKeysym</function>.

+<indexterm significance="preferred"><primary>XRebindKeysym</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XRebindKeysym</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>KeySym<parameter> keysym</parameter></paramdef>

+  <paramdef>KeySym<parameter> list[\^]\^</parameter></paramdef>

+  <paramdef>int<parameter> mod_count</parameter></paramdef>

+  <paramdef>unsignedchar<parameter> *string</parameter></paramdef>

+  <paramdef>int<parameter> num_bytes</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Fn rebound -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>keysym</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the KeySym that is to be (Fn.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>list</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the KeySyms to be used as modifiers.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>mod_count</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of modifiers in the modifier list.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>string</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the string that is copied and will be returned by 

+<function>XLookupString</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>num_bytes</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of bytes in the string argument.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XRebindKeysym</function>

+function can be used to rebind the meaning of a KeySym for the client.

+It does not redefine any key in the X server but merely

+provides an easy way for long strings to be attached to keys.

+<function>XLookupString</function>

+returns this string when the appropriate set of

+modifier keys are pressed and when the KeySym would have been used for

+the translation.

+No text conversions are performed;

+the client is responsible for supplying appropriately encoded strings.

+Note that you can rebind a KeySym that may not exist.

+</para>

+</sect1>

+<sect1 id="Allocating_Permanent_Storage">

+<title>Allocating Permanent Storage</title>

+<!-- .XS -->

+<!-- (SN Allocating Permanent Storage -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To allocate some memory you will never give back, use

+<function>Xpermalloc</function>.

+<indexterm significance="preferred"><primary>Xpermalloc</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char *<function> Xpermalloc</function></funcdef>

+  <paramdef>unsignedint<parameter> size</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>Xpermalloc</function>

+function allocates storage that can never be freed for the life of the

+program.  The memory is allocated with alignment for the C type double.

+This function may provide some performance and space savings over

+the standard operating system memory allocator.

+</para>

+</sect1>

+<sect1 id="Parsing_the_Window_Geometry">

+<title>Parsing the Window Geometry</title>

+<!-- .XS -->

+<!-- (SN Parsing the Window Geometry  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To parse standard window geometry strings, use

+<function>XParseGeometry</function>.

+<indexterm><primary>Window</primary><secondary>determining location</secondary></indexterm>

+<indexterm significance="preferred"><primary>XParseGeometry</primary></indexterm>

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XParseGeometry</function></funcdef>

+  <paramdef>char<parameter> *parsestring</parameter></paramdef>

+  <paramdef>int*x_return,<parameter> *y_return</parameter></paramdef>

+  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>parsestring</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the string you want to parse.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Return the x and y offsets.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Return the width and height determined.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+By convention,

+X applications use a standard string to indicate window size and placement.

+<function>XParseGeometry</function>

+makes it easier to conform to this standard because it allows you

+to parse the standard window geometry.

+Specifically, this function lets you parse strings of the form:

+</para>

+<para>

+<!-- .LP -->

+<!-- .\" Start marker code here -->

+<literallayout class="monospaced">

+[=][&lt;<emphasis remap='I'>width</emphasis>&gt;{xX}&lt;<emphasis remap='I'>height</emphasis>&gt;][{+-}&lt;<emphasis remap='I'>xoffset</emphasis>&gt;{+-}&lt;<emphasis remap='I'>yoffset</emphasis>&gt;] 

+</literallayout>

+<!-- .\" End marker code here -->

+</para>

+<para>

+<!-- .LP -->

+The fields map into the arguments associated with this function.

+(Items enclosed in &lt;\^&gt; are integers, items in [\^] are optional, and

+items enclosed in {\^} indicate ``choose one of.''

+Note that the brackets should not appear in the actual string.)

+If the string is not in the Host Portable Character Encoding,

+the result is implementation-dependent.

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XParseGeometry</function>

+function returns a bitmask that indicates which of the four values (width,

+height, xoffset, and yoffset) were actually found in the string 

+and whether the x and y values are negative. 

+By convention, \-0 is not equal to +0, because the user needs to

+be able to say ``position the window relative to the right or bottom edge.''

+For each value found, the corresponding argument is updated.

+For each value not found, the argument is left unchanged.

+The bits are represented by

+<function>XValue</function>,

+<function>YValue</function>,

+<function>WidthValue</function>,

+<function>HeightValue</function>,

+<function>XNegative</function>,

+or

+<function>YNegative</function>

+and are defined in 

+<!-- .hN X11/Xutil.h . -->

+They will be set whenever one of the values is defined 

+or one of the signs is set.

+</para>

+<para>

+<!-- .LP -->

+If the function returns either the 

+<function>XValue </function>

+or 

+<function>YValue </function>

+flag,

+you should place the window at the requested position.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To construct a window's geometry information, use

+<function>XWMGeometry</function>.

+<indexterm significance="preferred"><primary>XWMGeometry</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XWMGeometry</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> screen</parameter></paramdef>

+  <paramdef>char<parameter> *user_geom</parameter></paramdef>

+  <paramdef>char<parameter> *def_geom</parameter></paramdef>

+  <paramdef>unsignedint<parameter> bwidth</parameter></paramdef>

+  <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>

+  <paramdef>int*x_return,<parameter> *y_return</parameter></paramdef>

+  <paramdef>int<parameter> *width_return</parameter></paramdef>

+  <paramdef>int<parameter> *height_return</parameter></paramdef>

+  <paramdef>int<parameter> *gravity_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the screen.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>user_geom</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the user-specified geometry or NULL.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>def_geom</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the application's default geometry or NULL.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>bwidth</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the border width.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>hints</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the size hints for the window in its normal state.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Return the x and y offsets.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Return the width and height determined.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gravity_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the window gravity.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The 

+<function>XWMGeometry </function>

+function combines any geometry information (given in the format used by 

+<function>XParseGeometry</function>)

+specified by the user and by the calling program with size hints 

+(usually the ones to be stored in WM_NORMAL_HINTS) and returns the position, 

+size, and gravity

+(<function>NorthWestGravity</function>,

+<function>NorthEastGravity</function>,

+<function>SouthEastGravity</function>,

+or

+<function>SouthWestGravity</function>)

+that describe the window.

+If the base size is not set in the 

+<function>XSizeHints</function>

+structure, 

+the minimum size is used if set.

+Otherwise, a base size of zero is assumed.

+If no minimum size is set in the hints structure, 

+the base size is used.

+A mask (in the form returned by 

+<function>XParseGeometry</function>)

+that describes which values came from the user specification 

+and whether or not the position coordinates are relative

+to the right and bottom edges is returned.

+Note that these coordinates will have already been accounted for 

+in the x_return and y_return values.

+</para>

+<para>

+<!-- .LP -->

+Note that invalid geometry specifications can cause a width or height 

+of zero to be returned.

+The caller may pass the address of the hints win_gravity field 

+as gravity_return to update the hints directly.

+</para>

+</sect1>

+

+<sect1 id="Manipulating_Regions">

+<title>Manipulating Regions</title>

+<!-- .XS -->

+<!-- (SN Manipulating Regions  -->

+<!-- .XE -->

+<para>

+Regions are arbitrary sets of pixel locations.

+Xlib provides functions for manipulating regions.

+The opaque type 

+<function>Region</function>

+is defined in 

+<!-- .hN X11/Xutil.h . -->

+Xlib provides functions that you can use to manipulate regions.

+This section discusses how to:

+</para>

+

+<itemizedlist>

+  <listitem>

+    <para>

+Create, copy, or destroy regions

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Move or shrink regions

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Compute with regions

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Determine if regions are empty or equal

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Locate a point or rectangle in a region

+    </para>

+  </listitem>

+</itemizedlist>

+

+<sect2 id="Creating_Copying_or_Destroying_Regions">

+<title>Creating, Copying, or Destroying Regions</title>

+<!-- .XS -->

+<!-- (SN Creating, Copying, or Destroying Regions  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To create a new empty region, use

+<function>XCreateRegion</function>.

+</para>

+<para>Region XCreateRegion()</para>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To generate a region from a polygon, use

+<function>XPolygonRegion</function>.

+</para>

+<indexterm significance="preferred"><primary>XPolygonRegion</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Region <function> XPolygonRegion</function></funcdef>

+  <paramdef>XPoint<parameter> points[]</parameter></paramdef>

+  <paramdef>int<parameter> n</parameter></paramdef>

+  <paramdef>int<parameter> fill_rule</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>points</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies an array of points.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>n</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of points in the polygon. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>fill_rule</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the fill-rule you want to set for the specified GC.

+You can pass 

+<function>EvenOddRule</function>

+or

+<function>WindingRule</function>.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XPolygonRegion</function>

+function returns a region for the polygon defined by the points array.

+For an explanation of fill_rule,

+see

+<function>XCreateGC</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set the clip-mask of a GC to a region, use

+<function>XSetRegion</function>.

+<indexterm significance="preferred"><primary>XSetRegion</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSetRegion</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>GC<parameter> gc</parameter></paramdef>

+  <paramdef>Region<parameter> r</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>gc</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the GC.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>r</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the region.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSetRegion</function>

+function sets the clip-mask in the GC to the specified region.

+The region is specified relative to the drawable's origin.

+The resulting GC clip origin is implementation-dependent.

+Once it is set in the GC,

+the region can be destroyed.

+</para>

+<para>

+<!-- .LP  -->

+<!-- .sp -->

+To deallocate the storage associated with a specified region, use

+<function>XDestroyRegion</function>.

+<indexterm significance="preferred"><primary>XDestroyRegion</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDestroyRegion</function></funcdef>

+  <paramdef>Region<parameter> r</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>r</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the region.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+</para>

+</sect2>

+<sect2 id="Moving_or_Shrinking_Regions">

+<title>Moving or Shrinking Regions</title>

+<!-- .XS -->

+<!-- (SN Moving or Shrinking Regions  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To move a region by a specified amount, use 

+<function>XOffsetRegion</function>.

+<indexterm significance="preferred"><primary>XOffsetRegion</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XOffsetRegion</function></funcdef>

+  <paramdef>Region<parameter> r</parameter></paramdef>

+  <paramdef>intdx,<parameter> dy</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>r</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the region.

+<!-- .ds Dy move -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dx</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dy</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates,

+which define the amount you want to (Dy the specified region.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+<!-- .sp -->

+To reduce a region by a specified amount, use

+<function>XShrinkRegion</function>.

+<indexterm significance="preferred"><primary>XShrinkRegion</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XShrinkRegion</function></funcdef>

+  <paramdef>Region<parameter> r</parameter></paramdef>

+  <paramdef>intdx,<parameter> dy</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>r</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the region.

+<!-- .ds Dy shrink -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dx</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dy</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates,

+which define the amount you want to (Dy the specified region.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Positive values shrink the size of the region, 

+and negative values expand the region.

+</para>

+</sect2>

+<sect2 id="Computing_with_Regions">

+<title>Computing with Regions</title>

+<!-- .XS -->

+<!-- (SN Computing with Regions  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To generate the smallest rectangle enclosing a region, use

+<function>XClipBox</function>.

+<indexterm significance="preferred"><primary>XClipBox</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XClipBox</function></funcdef>

+  <paramdef>Region<parameter> r</parameter></paramdef>

+  <paramdef>XRectangle<parameter> *rect_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>r</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the region.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>rect_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the smallest enclosing rectangle.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XClipBox</function>

+function returns the smallest rectangle enclosing the specified region.

+<!-- .sp -->

+</para>

+<para>

+<!-- .LP -->

+To compute the intersection of two regions, use

+<function>XIntersectRegion</function>.

+<indexterm significance="preferred"><primary>XIntersectRegion</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XIntersectRegion</function></funcdef>

+  <paramdef>Regionsra,srb,<parameter> dr_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>sra</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>srb</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the two regions with which you want to perform the computation.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dr_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the result of the computation.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To compute the union of two regions, use

+<function>XUnionRegion</function>.

+<indexterm significance="preferred"><primary>XUnionRegion</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XUnionRegion</function></funcdef>

+  <paramdef>Regionsra,srb,<parameter> dr_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>sra</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>srb</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the two regions with which you want to perform the computation.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dr_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the result of the computation.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+<!-- .sp -->

+To create a union of a source region and a rectangle, use

+<function>XUnionRectWithRegion</function>.

+<indexterm significance="preferred"><primary>XUnionRectWithRegion</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XUnionRectWithRegion</function></funcdef>

+  <paramdef>XRectangle<parameter> *rectangle</parameter></paramdef>

+  <paramdef>Region<parameter> src_region</parameter></paramdef>

+  <paramdef>Region<parameter> dest_region_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>rectangle</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the rectangle.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>src_region</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the source region to be used.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dest_region_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the destination region.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XUnionRectWithRegion</function>

+function updates the destination region from a union of the specified rectangle

+and the specified source region.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To subtract two regions, use

+<function>XSubtractRegion</function>.

+<indexterm significance="preferred"><primary>XSubtractRegion</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XSubtractRegion</function></funcdef>

+  <paramdef>Regionsra,srb,<parameter> dr_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>sra</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>srb</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the two regions with which you want to perform the computation.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dr_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the result of the computation.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSubtractRegion</function>

+function subtracts srb from sra and stores the results in dr_return.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To calculate the difference between the union and intersection 

+of two regions, use

+<function>XXorRegion</function>.

+<indexterm significance="preferred"><primary>XXorRegion</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XXorRegion</function></funcdef>

+  <paramdef>Regionsra,srb,<parameter> dr_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>sra</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>srb</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the two regions with which you want to perform the computation.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>dr_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the result of the computation.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+</para>

+</sect2>

+<sect2 id="Determining_if_Regions_Are_Empty_or_Equal">

+<title>Determining if Regions Are Empty or Equal</title>

+<!-- .XS -->

+<!-- (SN Determining if Regions Are Empty or Equal  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To determine if the specified region is empty, use

+<function>XEmptyRegion</function>.

+<indexterm significance="preferred"><primary>XEmptyRegion</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool <function> XEmptyRegion</function></funcdef>

+  <paramdef>Region<parameter> r</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>r</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the region.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XEmptyRegion</function>

+function returns

+<function>True</function>

+if the region is empty.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To determine if two regions have the same offset, size, and shape, use

+<function>XEqualRegion</function>.

+<indexterm significance="preferred"><primary>XEqualRegion</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool <function> XEqualRegion</function></funcdef>

+  <paramdef>Regionr1,<parameter> r2</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>r1</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>r2</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the two regions.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XEqualRegion</function>

+function returns

+<function>True</function>

+if the two regions have the same offset, size, and shape.

+</para>

+</sect2>

+<sect2 id="Locating_a_Point_or_a_Rectangle_in_a_Region">

+<title>Locating a Point or a Rectangle in a Region</title>

+<!-- .XS -->

+<!-- (SN Locating a Point or a Rectangle in a Region  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+To determine if a specified point resides in a specified region, use

+<function>XPointInRegion</function>.

+<indexterm significance="preferred"><primary>XPointInRegion</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool <function> XPointInRegion</function></funcdef>

+  <paramdef>Region<parameter> r</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>r</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the region.

+<!-- .ds Xy , which define the point -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XPointInRegion</function>

+function returns 

+<function>True</function>

+if the point (x, y) is contained in the region r.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To determine if a specified rectangle is inside a region, use

+<function>XRectInRegion</function>.

+<indexterm significance="preferred"><primary>XRectInRegion</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XRectInRegion</function></funcdef>

+  <paramdef>Region<parameter> r</parameter></paramdef>

+  <paramdef>intx,<parameter> y</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>r</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the region.

+<!-- .ds Xy , which define the coordinates of the upper-left corner of the rectangle -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates(Xy.

+<!-- .ds Wh , which define the rectangle -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height(Wh.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XRectInRegion</function>

+function returns

+<function>RectangleIn</function>

+if the rectangle is entirely in the specified region,

+<function>RectangleOut</function>

+if the rectangle is entirely out of the specified region,

+and

+<function>RectanglePart</function>

+if the rectangle is partially in the specified region.

+</para>

+</sect2>

+</sect1>

+<sect1 id="Using_Cut_Buffers">

+<title>Using Cut Buffers</title>

+<!-- .XS -->

+<!-- (SN Using Cut Buffers  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+<indexterm><primary>Cut Buffers</primary></indexterm>

+Xlib provides functions to manipulate cut buffers,

+a very simple form of cut-and-paste inter-client communication.

+Selections are a much more powerful and useful mechanism for

+interchanging data between clients (see section 4.5)

+and generally should be used instead of cut buffers.

+</para>

+<para>

+<!-- .LP -->

+Cut buffers are implemented as properties on the first root window

+of the display.

+The buffers can only contain text, in the STRING encoding.

+The text encoding is not changed by Xlib when fetching or storing.

+Eight buffers are provided

+and can be accessed as a ring or as explicit buffers (numbered 0 through 7).

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To store data in cut buffer 0, use 

+<function>XStoreBytes</function>.

+<indexterm significance="preferred"><primary>XStoreBytes</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XStoreBytes</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>char<parameter> *bytes</parameter></paramdef>

+  <paramdef>int<parameter> \^nbytes</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN  -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>bytes</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the bytes, which are not necessarily ASCII or null-terminated.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nbytes</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of bytes to be stored.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The data can have embedded null characters

+and need not be null-terminated.

+The cut buffer's contents can be retrieved later by

+any client calling

+<function>XFetchBytes</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XStoreBytes</function>

+can generate a

+<function>BadAlloc</function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To store data in a specified cut buffer, use

+<function>XStoreBuffer</function>.

+<indexterm significance="preferred"><primary>XStoreBuffer</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XStoreBuffer</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>char<parameter> *bytes</parameter></paramdef>

+  <paramdef>int<parameter> \^nbytes</parameter></paramdef>

+  <paramdef>int<parameter> buffer</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>bytes</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the bytes, which are not necessarily ASCII or null-terminated.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nbytes</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of bytes to be stored.

+<!-- .ds Fn in which you want to store the bytes -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>buffer</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the buffer (Fn.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If an invalid buffer is specified, the call has no effect.

+The data can have embedded null characters

+and need not be null-terminated.

+</para>

+<para>

+<!-- .LP -->

+<function>XStoreBuffer</function>

+can generate a

+<function>BadAlloc </function>

+error.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To return data from cut buffer 0, use 

+<function>XFetchBytes</function>.

+<indexterm significance="preferred"><primary>XFetchBytes</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char *<function> XFetchBytes</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> *nbytes_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nbytes_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of bytes in the buffer.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XFetchBytes</function>

+function

+returns the number of bytes in the nbytes_return argument,

+if the buffer contains data.

+Otherwise, the function

+returns NULL and sets nbytes to 0.

+The appropriate amount of storage is allocated and the pointer returned.

+The client must free this storage when finished with it by calling

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To return data from a specified cut buffer, use 

+<function>XFetchBuffer</function>.

+<indexterm significance="preferred"><primary>XFetchBuffer</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>char *<function> XFetchBuffer</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> *nbytes_return</parameter></paramdef>

+  <paramdef>int<parameter> buffer</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nbytes_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of bytes in the buffer.

+<!-- .ds Fn from which you want the stored data returned -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>buffer</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the buffer (Fn.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XFetchBuffer</function>

+function returns zero to the nbytes_return argument 

+if there is no data in the buffer or if an invalid

+buffer is specified.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To rotate the cut buffers, use 

+<function>XRotateBuffers</function>.

+<indexterm significance="preferred"><primary>XRotateBuffers</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XRotateBuffers</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> rotate</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>rotate</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies how much to rotate the cut buffers.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM  -->

+The

+<function>XRotateBuffers</function>

+function rotates the cut

+buffers, such that buffer 0 becomes buffer n, 

+buffer 1 becomes n + 1 mod 8, and so on.

+This cut buffer numbering is global to the display.

+Note that

+<function>XRotateBuffers</function>

+generates

+<function>BadMatch</function>

+errors if any of the eight buffers have not been created.

+</para>

+</sect1>

+<sect1 id="Determining_the_Appropriate_Visual_Type">

+<title>Determining the Appropriate Visual Type</title>

+<!-- .XS -->

+<!-- (SN Determining the Appropriate Visual Type -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+A single display can support multiple screens.

+Each screen can have several different visual types supported 

+at different depths.

+You can use the functions described in this section to determine

+which visual to use for your application.

+</para>

+<para>

+<!-- .LP -->

+The functions in this section use the visual information masks and the

+<function>XVisualInfo </function>

+structure,

+which is defined in

+<!-- .hN X11/Xutil.h -->

+and contains:

+<!-- .sM -->

+</para>

+<!-- .LP -->

+<literallayout class="monospaced">

+

+/* Visual information mask bits */

+

+

+#define   VisualNoMask                 0x0

+#define   VisualIDMask                 0x1

+#define   VisualScreenMask             0x2

+#define   VisualDepthMask              0x4

+#define   VisualClassMask              0x8

+#define   VisualRedMaskMask            0x10

+#define   VisualGreenMaskMask          0x20

+#define   VisualBlueMaskMask           0x40

+#define   VisualColormapSizeMask       0x80

+#define   VisualBitsPerRGBMask         0x100

+#define   VisualAllMask                0x1FF

+

+</literallayout>

+

+<literallayout class="monospaced">

+<!-- .TA .5i 3i -->

+<!-- .ta .5i 3i -->

+/* Values */

+

+typedef struct {

+     Visual *visual;

+     VisualID visualid;

+     int screen;

+     unsigned int depth;

+     int class;

+     unsigned long red_mask;

+     unsigned long green_mask;

+     unsigned long blue_mask;

+     int colormap_size;

+     int bits_per_rgb;

+} XVisualInfo;

+</literallayout>

+

+<para>

+<!-- .LP -->

+<!-- .eM -->

+To obtain a list of visual information structures that match a specified

+template, use

+<function>XGetVisualInfo</function>.

+<indexterm significance="preferred"><primary>XGetVisualInfo</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XVisualInfo *<function> XGetVisualInfo</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>long<parameter> vinfo_mask</parameter></paramdef>

+  <paramdef>XVisualInfo<parameter> *vinfo_template</parameter></paramdef>

+  <paramdef>int<parameter> *nitems_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>vinfo_mask</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the visual mask value.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>vinfo_template</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the visual attributes that are to be used in matching the visual

+structures.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>nitems_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the number of matching visual structures.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetVisualInfo</function>

+function returns a list of visual structures that have attributes 

+equal to the attributes specified by vinfo_template.

+If no visual structures match the template using the specified vinfo_mask,

+<function>XGetVisualInfo</function>

+returns a NULL.

+To free the data returned by this function, use

+<function>XFree</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain the visual information that matches the specified depth and

+class of the screen, use

+<function>XMatchVisualInfo</function>.

+<indexterm significance="preferred"><primary>XMatchVisualInfo</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function> XMatchVisualInfo</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>int<parameter> screen</parameter></paramdef>

+  <paramdef>int<parameter> depth</parameter></paramdef>

+  <paramdef>int<parameter> class</parameter></paramdef>

+  <paramdef>XVisualInfo<parameter> *vinfo_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>screen</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the screen.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>depth</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the depth of the screen.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>class</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the class of the screen.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>vinfo_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the matched visual information.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XMatchVisualInfo</function>

+function returns the visual information for a visual that matches the specified

+depth and class for a screen.

+Because multiple visuals that match the specified depth and class can exist,

+the exact visual chosen is undefined.

+If a visual is found,

+<function>XMatchVisualInfo</function>

+returns nonzero and the information on the visual to vinfo_return.

+Otherwise, when a visual is not found,

+<function>XMatchVisualInfo</function>

+returns zero.

+</para>

+</sect1>

+<sect1 id="Manipulating_Images">

+<title>Manipulating Images</title>

+<!-- .XS -->

+<!-- (SN Manipulating Images  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides several functions that perform basic operations on images.

+All operations on images are defined using an 

+<function>XImage </function>

+structure, 

+as defined in

+<!-- .hN X11/Xlib.h . -->

+Because the number of different types of image formats can be very large,

+this hides details of image storage properly from applications.

+</para>

+<para>

+<!-- .LP -->

+This section describes the functions for generic operations on images.

+Manufacturers can provide very fast implementations of these for the

+formats frequently encountered on their hardware.

+These functions are neither sufficient nor desirable to use for general image

+processing.

+Rather, they are here to provide minimal functions on screen format

+images.

+The basic operations for getting and putting images are

+<function>XGetImage</function>

+and 

+<function>XPutImage</function>.

+</para>

+<para>

+<!-- .LP -->

+Note that no functions have been defined, as yet, to read and write images 

+to and from disk files.

+</para>

+<para>

+<!-- .LP -->

+The

+<function>XImage </function>

+structure describes an image as it exists in the client's memory.  

+The user can request that some of the members such as height, width, 

+and xoffset be changed when the image is sent to the server.

+Note that bytes_per_line in concert with offset can be used to

+extract a subset of the image.

+Other members (for example, byte order, bitmap_unit, and so forth)

+are characteristics of both the image and the server.  

+If these members

+differ between the image and the server, 

+<function>XPutImage </function>

+makes the appropriate conversions.

+The first byte of the first line of

+plane n must be located at the address (data + (n * height * bytes_per_line)).

+For a description of the 

+<function>XImage </function>

+structure,

+see section 8.7.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To allocate an 

+<function>XImage </function>

+structure and initialize it with image format values from a display, use

+<function>XCreateImage</function>.

+<indexterm significance="preferred"><primary>XCreateImage</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XImage *<function> XCreateImage</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Visual<parameter> *visual</parameter></paramdef>

+  <paramdef>unsignedint<parameter> depth</parameter></paramdef>

+  <paramdef>int<parameter> format</parameter></paramdef>

+  <paramdef>int<parameter> offset</parameter></paramdef>

+  <paramdef>char<parameter> *data</parameter></paramdef>

+  <paramdef>unsignedint<parameter> width</parameter></paramdef>

+  <paramdef>unsignedint<parameter> height</parameter></paramdef>

+  <paramdef>int<parameter> bitmap_pad</parameter></paramdef>

+  <paramdef>int<parameter> bytes_per_line</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>visual</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the

+<function>Visual</function>

+structure.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>depth</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the depth of the image.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>format</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the format for the image.

+You can pass

+<function>XYBitmap</function>,

+<function>XYPixmap</function>,

+or 

+<function>ZPixmap</function>.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>offset</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of pixels to ignore at the beginning of the scanline.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the image data.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the width of the image, in pixels.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the height of the image, in pixels.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>bitmap_pad</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the quantum of a scanline (8, 16, or 32).

+In other words, the start of one scanline is separated in client memory from 

+the start of the next scanline by an integer multiple of this many bits.  

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>bytes_per_line</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the number of bytes in the client image between

+the start of one scanline and the start of the next.  

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCreateImage</function>

+function allocates the memory needed for an

+<function>XImage</function>

+structure for the

+specified display but does not allocate space for the image itself.

+Rather, it initializes the structure byte-order, bit-order, and bitmap-unit

+values from the display and returns a pointer to the 

+<function>XImage </function>

+structure.

+The red, green, and blue mask values are defined for Z format images only

+and are derived from the 

+<function>Visual </function>

+structure passed in.

+Other values also are passed in.

+The offset permits the rapid displaying of the image without requiring each 

+scanline to be shifted into position.

+If you pass a zero value in bytes_per_line,

+Xlib assumes that the scanlines are contiguous

+in memory and calculates the value of bytes_per_line itself.

+</para>

+<para>

+<!-- .LP -->

+Note that when the image is created using

+<function>XCreateImage</function>,

+<function>XGetImage</function>,

+or

+<function>XSubImage</function>,

+the destroy procedure that the 

+<function>XDestroyImage</function>

+function calls frees both the image structure 

+and the data pointed to by the image structure.

+</para>

+<para>

+<!-- .LP -->

+The basic functions used to get a pixel, set a pixel, create a subimage,

+and add a constant value to an image are defined in the image object.

+The functions in this section are really macro invocations of the functions

+in the image object and are defined in

+<!-- .hN X11/Xutil.h . -->

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To obtain a pixel value in an image, use

+<function>XGetPixel</function>.

+<indexterm significance="preferred"><primary>XGetPixel</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>unsigned long <function> XGetPixel</function></funcdef>

+  <paramdef>XImage<parameter> *ximage</parameter></paramdef>

+  <paramdef>int<parameter> x</parameter></paramdef>

+  <paramdef>int<parameter> y</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ximage</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the image.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XGetPixel</function>

+function returns the specified pixel from the named image.

+The pixel value is returned in normalized format (that is,

+the least significant byte of the long is the least significant byte

+of the pixel).

+The image must contain the x and y coordinates.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To set a pixel value in an image, use

+<function>XPutPixel</function>.

+<indexterm significance="preferred"><primary>XPutPixel</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XPutPixel</function></funcdef>

+  <paramdef>XImage<parameter> *ximage</parameter></paramdef>

+  <paramdef>int<parameter> x</parameter></paramdef>

+  <paramdef>int<parameter> y</parameter></paramdef>

+  <paramdef>unsignedlong<parameter> pixel</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ximage</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the image.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>pixel</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the new pixel value.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XPutPixel</function>

+function overwrites the pixel in the named image with the specified pixel value.

+The input pixel value must be in normalized format

+(that is, the least significant byte of the long is the least significant

+byte of the pixel).

+The image must contain the x and y coordinates.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To create a subimage, use

+<function>XSubImage</function>.

+<indexterm significance="preferred"><primary>XSubImage</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XImage *<function> XSubImage</function></funcdef>

+  <paramdef>XImage<parameter> *ximage</parameter></paramdef>

+  <paramdef>int<parameter> x</parameter></paramdef>

+  <paramdef>int<parameter> y</parameter></paramdef>

+  <paramdef>unsignedint<parameter> subimage_width</parameter></paramdef>

+  <paramdef>unsignedint<parameter> subimage_height</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ximage</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the image.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the x and y coordinates.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>subimage_width</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the width of the new subimage, in pixels.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>subimage_height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the height of the new subimage, in pixels.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XSubImage</function>

+function creates a new image that is a subsection of an existing one.

+It allocates the memory necessary for the new

+<function>XImage</function>

+structure

+and returns a pointer to the new image.

+The data is copied from the source image,

+and the image must contain the rectangle defined by x, y, subimage_width,

+and subimage_height.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To increment each pixel in an image by a constant value, use

+<function>XAddPixel</function>.

+<indexterm significance="preferred"><primary>XAddPixel</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XAddPixel</function></funcdef>

+  <paramdef>XImage<parameter> *ximage</parameter></paramdef>

+  <paramdef>long<parameter> value</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ximage</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the image.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>value</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the constant value that is to be added.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XAddPixel</function>

+function adds a constant value to every pixel in an image.

+It is useful when you have a base pixel value from allocating

+color resources and need to manipulate the image to that form.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To deallocate the memory allocated in a previous call to

+<function>XCreateImage</function>,

+use

+<function>XDestroyImage</function>.

+<indexterm significance="preferred"><primary>XDestroyImage</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef><function> XDestroyImage</function></funcdef>

+  <paramdef>XImage<parameter> *\^ximage</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>ximage</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the image.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XDestroyImage</function>

+function deallocates the memory associated with the

+<function>XImage</function>

+structure.

+</para>

+<para>

+<!-- .LP -->

+Note that when the image is created using

+<function>XCreateImage</function>,

+<function>XGetImage</function>,

+or 

+<function>XSubImage</function>,

+the destroy procedure that this macro calls

+frees both the image structure and the data pointed to by the image structure. 

+</para>

+</sect1>

+<sect1 id="Manipulating_Bitmaps">

+<title>Manipulating Bitmaps</title>

+<!-- .XS -->

+<!-- (SN Manipulating Bitmaps  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+Xlib provides functions that you can use to read a bitmap from a file,

+save a bitmap to a file, or create a bitmap. 

+This section describes those functions that transfer bitmaps to and

+from the client's file system, thus allowing their reuse in a later

+connection (for example, from an entirely different client or to a

+different display or server).

+</para>

+<para>

+<!-- .LP -->

+The X version 11 bitmap file format is:

+</para>

+<para>

+<!-- .LP -->

+<!-- .sM -->

+<literallayout class="monospaced">

+#define <emphasis remap='I'>name</emphasis>_width <emphasis remap='I'>width</emphasis>

+#define <emphasis remap='I'>name</emphasis>_height <emphasis remap='I'>height</emphasis>

+#define <emphasis remap='I'>name</emphasis>_x_hot <emphasis remap='I'>x</emphasis>

+#define <emphasis remap='I'>name</emphasis>_y_hot <emphasis remap='I'>y</emphasis>

+static unsigned char <emphasis remap='I'>name</emphasis>_bits[] = { 0x<emphasis remap='I'>NN</emphasis>,... }

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The lines for the variables ending with _x_hot and _y_hot suffixes are optional

+because they are present only if a hotspot has been defined for this bitmap.

+The lines for the other variables are required.

+The word ``unsigned'' is optional;

+that is, the type of the _bits array can be ``char'' or ``unsigned char''.

+The _bits array must be large enough to contain the size bitmap.

+The bitmap unit is 8.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To read a bitmap from a file and store it in a pixmap, use

+<function>XReadBitmapFile</function>.

+<indexterm significance="preferred"><primary>XReadBitmapFile</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XReadBitmapFile</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>char<parameter> *filename</parameter></paramdef>

+  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>

+  <paramdef>Pixmap<parameter> *bitmap_return</parameter></paramdef>

+  <paramdef>int*x_hot_return,<parameter> *y_hot_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Dr \ that indicates the screen -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable(Dr. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>filename</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the file name to use.

+The format of the file name is operating-system dependent.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Return the width and height values of the read in bitmap file.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>bitmap_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the bitmap that is created.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x_hot_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y_hot_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Return the hotspot coordinates.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XReadBitmapFile</function>

+function reads in a file containing a bitmap.

+The file is parsed in the encoding of the current locale.

+The ability to read other than the standard format 

+is implementation-dependent.

+If the file cannot be opened, 

+<function>XReadBitmapFile </function>

+returns 

+<function>BitmapOpenFailed</function>.

+If the file can be opened but does not contain valid bitmap data, 

+it returns 

+<function>BitmapFileInvalid</function>.

+If insufficient working storage is allocated,

+it returns

+<function>BitmapNoMemory</function>.

+If the file is readable and valid,

+it returns 

+<function>BitmapSuccess</function>.

+</para>

+<para>

+<!-- .LP -->

+<function>XReadBitmapFile </function>

+returns the bitmap's height and width, as read

+from the file, to width_return and height_return.

+It then creates a pixmap of the appropriate size, 

+reads the bitmap data from the file into the pixmap,

+and assigns the pixmap to the caller's variable bitmap.  

+The caller must free the bitmap using 

+<function>XFreePixmap </function>

+when finished.

+If <emphasis remap='I'>name</emphasis>_x_hot and <emphasis remap='I'>name</emphasis>_y_hot exist,

+<function>XReadBitmapFile </function>

+returns them to x_hot_return and y_hot_return;

+otherwise, it returns \-1,\-1.

+</para>

+<para>

+<!-- .LP -->

+<function>XReadBitmapFile</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadDrawable</function>,

+and

+<function>BadGC</function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To read a bitmap from a file and return it as data, use

+<function>XReadBitmapFileData</function>.

+<indexterm significance="preferred"><primary>XReadBitmapFileData</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XReadBitmapFileData</function></funcdef>

+  <paramdef>char<parameter> *filename</parameter></paramdef>

+  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>

+  <paramdef>unsignedchar<parameter> *data_return</parameter></paramdef>

+  <paramdef>int*x_hot_return,<parameter> *y_hot_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>filename</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the file name to use.

+The format of the file name is operating-system dependent.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Return the width and height values of the read in bitmap file.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>data_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the bitmap data.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x_hot_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y_hot_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Return the hotspot coordinates.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XReadBitmapFileData</function>

+function reads in a file containing a bitmap, in the same manner as

+<function>XReadBitmapFile</function>,

+but returns the data directly rather than creating a pixmap in the server.

+The bitmap data is returned in data_return; the client must free this

+storage when finished with it by calling

+<function>XFree</function>.

+The status and other return values are the same as for

+<function>XReadBitmapFile</function>.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To write out a bitmap from a pixmap to a file, use

+<function>XWriteBitmapFile</function>.

+<indexterm significance="preferred"><primary>XWriteBitmapFile</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XWriteBitmapFile</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>char<parameter> *filename</parameter></paramdef>

+  <paramdef>Pixmap<parameter> bitmap</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+  <paramdef>intx_hot,<parameter> y_hot</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>filename</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the file name to use.

+The format of the file name is operating-system dependent.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>bitmap</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the bitmap.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>x_hot</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>y_hot</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify where to place the hotspot coordinates (or \-1,\-1 if none are present)

+in the file.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XWriteBitmapFile</function>

+function writes a bitmap out to a file in the X Version 11 format.

+The name used in the output file is derived from the file name

+by deleting the directory prefix.

+The file is written in the encoding of the current locale.

+If the file cannot be opened for writing, 

+it returns 

+<function>BitmapOpenFailed</function>.

+If insufficient memory is allocated,

+<function>XWriteBitmapFile</function>

+returns

+<function>BitmapNoMemory</function>;

+otherwise, on no error,

+it returns

+<function>BitmapSuccess</function>.

+If x_hot and y_hot are not \-1, \-1, 

+<function>XWriteBitmapFile</function>

+writes them out as the hotspot coordinates for the bitmap.

+</para>

+<para>

+<!-- .LP -->

+<function>XWriteBitmapFile</function>

+can generate

+<function>BadDrawable</function>

+and

+<function>BadMatch</function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To create a pixmap and then store bitmap-format data into it, use

+<function>XCreatePixmapFromBitmapData</function>.

+<indexterm significance="preferred"><primary>XCreatePixmapFromBitmapData</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Pixmap <function> XCreatePixmapFromBitmapData</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>char<parameter> *data</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+  <paramdef>unsignedlongfg,<parameter> bg</parameter></paramdef>

+  <paramdef>unsignedint<parameter> depth</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Dr \ that indicates the screen -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable(Dr. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the data in bitmap format.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>fg</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>bg</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the foreground and background pixel values to use.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>depth</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the depth of the pixmap.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCreatePixmapFromBitmapData</function>

+function creates a pixmap of the given depth and then does a bitmap-format

+<function>XPutImage</function>

+of the data into it.

+The depth must be supported by the screen of the specified drawable,

+or a

+<function>BadMatch</function>

+error results.

+</para>

+<para>

+<!-- .LP -->

+<function>XCreatePixmapFromBitmapData</function>

+can generate

+<function>BadAlloc</function>,

+<function>BadDrawable</function>,

+<function>BadGC</function>,

+and

+<function>BadValue</function>

+errors.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To include a bitmap written out by 

+<function>XWriteBitmapFile </function>

+<indexterm><primary>XWriteBitmapFile</primary></indexterm>

+in a program directly, as opposed to reading it in every time at run time, use

+<function>XCreateBitmapFromData</function>.

+<indexterm significance="preferred"><primary>XCreateBitmapFromData</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Pixmap <function> XCreateBitmapFromData</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>Drawable<parameter> d</parameter></paramdef>

+  <paramdef>char<parameter> *data</parameter></paramdef>

+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+<!-- .ds Dr \ that indicates the screen -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>d</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the drawable(Dr. 

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the location of the bitmap data.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>width</emphasis>

+    </term>

+    <listitem>

+      <para>

+<!-- .br -->

+<!-- .ns -->

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>height</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specify the width and height.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XCreateBitmapFromData</function>

+function allows you to include in your C program (using

+<function>#include</function>)

+a bitmap file that was written out by

+<function>XWriteBitmapFile</function>

+(X version 11 format only) without reading in the bitmap file.

+The following example creates a gray bitmap:

+</para>

+<para>

+<!-- .LP -->

+<literallayout class="monospaced">

+#include "gray.bitmap"

+<!-- .sp 6p -->

+Pixmap bitmap;

+bitmap = XCreateBitmapFromData(display, window, gray_bits, gray_width, gray_height);

+</literallayout>

+</para>

+<para>

+<!-- .LP -->

+If insufficient working storage was allocated,

+<function>XCreateBitmapFromData</function>

+returns

+<function>None</function>.

+It is your responsibility to free the

+bitmap using

+<function>XFreePixmap</function>

+when finished.

+</para>

+<para>

+<!-- .LP -->

+<function>XCreateBitmapFromData</function>

+can generate

+<function>BadAlloc</function>

+and

+<function>BadGC</function>

+errors.

+</para>

+</sect1>

+<sect1 id="Using_the_Context_Manager">

+<title>Using the Context Manager</title>

+<!-- .XS -->

+<!-- (SN Using the Context Manager  -->

+<!-- .XE -->

+<para>

+<!-- .LP -->

+The context manager provides a way of associating data with an X resource ID

+(mostly typically a window) in your program.  

+Note that this is local to your program;

+the data is not stored in the server on a property list.

+Any amount of data in any number of pieces can be associated with a

+resource ID,

+and each piece of data has a type associated with it.  

+The context manager requires knowledge of the resource ID

+and type to store or retrieve data.

+</para>

+<para>

+<!-- .LP -->

+Essentially, the context manager can be viewed as a two-dimensional, 

+sparse array:  one dimension is subscripted by the X resource ID

+and the other by a context type field.

+Each entry in the array contains a pointer to the data.

+Xlib provides context management functions with which you can

+save data values, get data values, delete entries, and create a unique

+context type.

+The symbols used are in

+<!-- .hN X11/Xutil.h . -->

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To save a data value that corresponds to a resource ID and context type, use

+<function>XSaveContext</function>.

+<indexterm significance="preferred"><primary>XSaveContext</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XSaveContext</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XID<parameter> rid</parameter></paramdef>

+  <paramdef>XContext<parameter> context</parameter></paramdef>

+  <paramdef>XPointer<parameter> data</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>rid</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource ID with which the data is associated.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>context</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the context type to which the data belongs.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>data</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the data to be associated with the window and type.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+If an entry with the specified resource ID and type already exists,

+<function>XSaveContext</function>

+overrides it with the specified context.

+The

+<function>XSaveContext</function>

+function returns a nonzero error code if an error has occurred

+and zero otherwise.

+Possible errors are

+<function>XCNOMEM</function>

+(out of memory).

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To get the data associated with a resource ID and type, use

+<function>XFindContext</function>.

+<indexterm significance="preferred"><primary>XFindContext</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XFindContext</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XID<parameter> rid</parameter></paramdef>

+  <paramdef>XContext<parameter> context</parameter></paramdef>

+  <paramdef>XPointer<parameter> *data_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>rid</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource ID with which the data is associated.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>context</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the context type to which the data belongs.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>data_return</emphasis>

+    </term>

+    <listitem>

+      <para>

+Returns the data.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+Because it is a return value,

+the data is a pointer.

+The

+<function>XFindContext</function>

+function returns a nonzero error code if an error has occurred

+and zero otherwise.

+Possible errors are

+<function>XCNOENT</function>

+(context-not-found).

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To delete an entry for a given resource ID and type, use

+<function>XDeleteContext</function>.

+<indexterm significance="preferred"><primary>XDeleteContext</primary></indexterm>

+<!-- .sM -->

+<funcsynopsis>

+<funcprototype>

+  <funcdef>int <function> XDeleteContext</function></funcdef>

+  <paramdef>Display<parameter> *display</parameter></paramdef>

+  <paramdef>XID<parameter> rid</parameter></paramdef>

+  <paramdef>XContext<parameter> context</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+<!-- .FN -->

+<variablelist>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>display</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the connection to the X server.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>rid</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the resource ID with which the data is associated.

+      </para>

+    </listitem>

+  </varlistentry>

+  <varlistentry>

+    <term>

+      <emphasis remap='I'>context</emphasis>

+    </term>

+    <listitem>

+      <para>

+Specifies the context type to which the data belongs.

+    </para>

+  </listitem>

+  </varlistentry>

+</variablelist>

+</para>

+<para>

+<!-- .LP -->

+<!-- .eM -->

+The

+<function>XDeleteContext</function>

+function deletes the entry for the given resource ID 

+and type from the data structure.

+This function returns the same error codes that

+<function>XFindContext</function>

+returns if called with the same arguments.

+<function>XDeleteContext</function>

+does not free the data whose address was saved.

+</para>

+<para>

+<!-- .LP -->

+<!-- .sp -->

+To create a unique context type that may be used in subsequent calls to

+<function>XSaveContext </function>

+and

+<function>XFindContext</function>,

+use

+<function>XUniqueContext</function>.

+</para>

+<para>XContext XuniqueContext()</para>

+

+</sect1>

+</chapter>

diff --git a/libX11/specs/libX11/Makefile.am b/libX11/specs/libX11/Makefile.am
index c76b4e943..76fa0f688 100644
--- a/libX11/specs/libX11/Makefile.am
+++ b/libX11/specs/libX11/Makefile.am
@@ -21,36 +21,34 @@
 # DEALINGS IN THE SOFTWARE.

 #

 

-# Based on xc/doc/specs/X11/Makefile from X11R6.9

+if ENABLE_SPECS

 

-doc_sources = libX11.ms

+specdir = $(docdir)/$(subdir)

+doc_sources = libX11.xml

+dist_spec_DATA = $(doc_sources)	\

+	AppA.xml		\

+	AppB.xml		\

+	AppC.xml		\

+	AppD.xml		\

+	CH01.xml		\

+	CH02.xml		\

+	CH03.xml		\

+	CH04.xml		\

+	CH05.xml		\

+	CH06.xml		\

+	CH07.xml		\

+	CH08.xml		\

+	CH09.xml		\

+	CH10.xml		\

+	CH11.xml		\

+	CH12.xml		\

+	CH13.xml		\

+	CH14.xml		\

+	CH15.xml		\

+	CH16.xml		\

+	credits.xml		\

+	glossary.xml

 

-doc_includes = \

-	abstract.t \

-	credits.t \

-	CH01 \

-	CH02 \

-	CH03 \

-	CH04 \

-	CH05 \

-	CH06 \

-	CH07 \

-	CH08 \

-	CH09 \

-	CH10 \

-	CH11 \

-	CH12 \

-	CH13 \

-	CH14 \

-	CH15 \

-	CH16 \

-	AppA \

-	AppB \

-	AppC \

-	AppD \

-	glossary \

-	postproc

+include $(top_srcdir)/specs/xmlrules.in

 

-include $(top_srcdir)/specs/troffrules.in

-

-EXTRA_DIST += $(doc_includes)

+endif ENABLE_SPECS

diff --git a/libX11/specs/libX11/abstract.t b/libX11/specs/libX11/abstract.t
deleted file mode 100644
index 153fbc7a2..000000000
--- a/libX11/specs/libX11/abstract.t
+++ /dev/null
@@ -1,105 +0,0 @@
-.EH ''''
-.OH ''''
-.EF ''''
-.OF ''''
-.ps 11
-.nr PS 11
-\&
-.sp 5
-.ce 6
-\s+2\fBXlib \- C Language X Interface\fP\s-2
-
-\s+1\fBX Window System Standard\fP\s-1
-
-\s+1\fBX Version 11, Release 7\fP\s-1
-
-\s+1\fB\*(xV\fP\s-1
-.sp 6
-.ce 4
-\s-1James Gettys
-.sp 6p
-Cambridge Research Laboratory
-Digital Equipment Corporation
-.sp 2
-.ce 4
-Robert W. Scheifler
-.sp 6p
-Laboratory for Computer Science
-Massachusetts Institute of Technology
-.sp 3
-.ce 1
-\fIwith contributions from\fP
-.sp 3
-.ce 11
-Chuck Adams, Tektronix, Inc.
-.sp 1
-Vania Joloboff, Open Software Foundation
-.sp 1
-Hideki Hiura, Sun Microsystems, Inc.
-.sp 1
-Bill McMahon, Hewlett-Packard Company
-.sp 1
-Ron Newman, Massachusetts Institute of Technology
-.sp 1
-Al Tabayoyon, Tektronix, Inc.
-.sp 1
-Glenn Widener, Tektronix, Inc.
-.sp 1
-Shigeru Yamada, Fujitsu OSSI
-.bp
-\&
-.ps 9
-.nr PS 9
-.sp 8
-.LP
-The X Window System is a trademark of The Open Group.
-.LP
-TekHVC is a trademark of Tektronix, Inc.
-.sp 2
-.LP
-Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996, 2002
-The Open Group
-.LP
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-.LP
-The above copyright notice and this permission notice shall be included
-in all copies or substantial portions of the Software.
-.LP
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
-.LP
-Except as contained in this notice, the name of The Open Group shall
-not be used in advertising or otherwise to promote the sale, use or
-other dealings in this Software without prior written authorization
-from The Open Group.
-.sp 3
-.LP
-Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
-Digital Equipment Corporation
-.LP
-Portions Copyright \(co 1990, 1991 by
-Tektronix, Inc.
-.LP
-Permission to use, copy, modify and distribute this documentation for
-any purpose and without fee is hereby granted, provided that the above
-copyright notice appears in all copies and that both that copyright notice and
-this permission notice appear in all copies, and that the names of
-Digital and Tektronix not be used in in advertising or publicity
-pertaining to this documentation without specific, written prior permission.
-Digital and Tektronix makes no representations about the suitability
-of this documentation for any purpose.
-It is provided ``as is'' without express or implied warranty.
-.ps 11
-.nr PS 11
-.bp
diff --git a/libX11/specs/libX11/credits.t b/libX11/specs/libX11/credits.xml
index 5d9909d7c..17713d3cb 100644
--- a/libX11/specs/libX11/credits.t
+++ b/libX11/specs/libX11/credits.xml
@@ -1,216 +1,232 @@
-.EH ''''
-.OH ''''
-.EF ''''
-.OF ''''
-.XS ii
-Table of Contents
-.XE
-.XS iii
-Acknowledgments
-.XE
-\&
-.sp 1
-.ce 3
-\s+1\fBAcknowledgments\fP\s-1
-.sp 2
-.na
-.LP
-The design and implementation of the first 10 versions of X
-were primarily the work of three individuals: Robert Scheifler of the
-MIT Laboratory for Computer Science and Jim Gettys of Digital
-Equipment Corporation and Ron Newman of MIT, both at MIT
-Project Athena. 
-X version 11, however, is the result of the efforts of 
-dozens of individuals at almost as many locations and organizations.
-At the risk of offending some of the players by exclusion, 
-we would like to acknowledge some of the people who deserve special credit 
-and recognition for their work on Xlib.
-Our apologies to anyone inadvertently overlooked.
-.SH
-Release 1
-.LP
-Our thanks does to Ron Newman (MIT Project Athena),
-who contributed substantially to the
-design and implementation of the Version 11 Xlib interface.
-.LP
-Our thanks also goes to Ralph Swick (Project Athena and Digital) who kept 
-it all together for us during the early releases.
-He handled literally thousands of requests from people everywhere
-and saved the sanity of at least one of us.
-His calm good cheer was a foundation on which we could build.
-.LP
-Our thanks also goes to Todd Brunhoff (Tektronix) who was ``loaned'' 
-to Project Athena at exactly the right moment to provide very capable 
-and much-needed assistance during the alpha and beta releases.
-He was responsible for the successful integration of sources
-from multiple sites;
-we would not have had a release without him.
-.LP
-Our thanks also goes to Al Mento and Al Wojtas of Digital's ULTRIX 
-Documentation Group.
-With good humor and cheer,
-they took a rough draft and made it an infinitely better and more useful 
-document.
-The work they have done will help many everywhere.
-We also would like to thank Hal Murray (Digital SRC) and
-Peter George (Digital VMS) who contributed much
-by proofreading the early drafts of this document.
-.LP
-Our thanks also goes to Jeff Dike (Digital UEG), Tom Benson, 
-Jackie Granfield, and Vince Orgovan (Digital VMS) who helped with the 
-library utilities implementation;
-to Hania Gajewska (Digital UEG-WSL) who,
-along with Ellis Cohen (CMU and Siemens),
-was instrumental in the semantic design of the window manager properties;
-and to Dave Rosenthal (Sun Microsystems) who also contributed to the protocol 
-and provided the sample generic color frame buffer device-dependent code.
-.LP
-The alpha and beta test participants deserve special recognition and thanks
-as well.
-It is significant
-that the bug reports (and many fixes) during alpha and beta test came almost
-exclusively from just a few of the alpha testers, mostly hardware vendors
-working on product implementations of X.  
-The continued public
-contribution of vendors and universities is certainly to the benefit 
-of the entire X community.
-.LP
-Our special thanks must go to Sam Fuller, Vice-President of Corporate
-Research at Digital, who has remained committed to the widest public 
-availability of X and who made it possible to greatly supplement MIT's
-resources with the Digital staff in order to make version 11 a reality.
-Many of the people mentioned here are part of the Western
-Software Laboratory (Digital UEG-WSL) of the ULTRIX Engineering group
-and work for Smokey Wallace, who has been vital to the project's success. 
-Others not mentioned here worked on the toolkit and are acknowledged 
-in the X Toolkit documentation.
-.LP
-Of course, 
-we must particularly thank Paul Asente, formerly of Stanford University
-and now of Digital UEG-WSL, who wrote W, the predecessor to X,
-and Brian Reid, formerly of Stanford University and now of Digital WRL,
-who had much to do with W's design.
-.LP
-Finally, our thanks goes to MIT,  Digital Equipment Corporation,
-and IBM for providing the environment where it could happen.
-.SH
-Release 4
-.LP
-Our thanks go to Jim Fulton (MIT X Consortium) for designing and
-specifying the new Xlib functions for Inter-Client Communication
-Conventions (ICCCM) support.
-.LP
-We also thank Al Mento of Digital for his continued effort in
-maintaining this document and Jim Fulton and Donna Converse (MIT X Consortium)
-for their much-appreciated efforts in reviewing the changes.
-.SH
-Release 5
-.LP
-The principal authors of the Input Method facilities are
-Vania Joloboff (Open Software Foundation) and Bill McMahon (Hewlett-Packard).
-The principal author of the rest of the internationalization facilities
-is Glenn Widener (Tektronix).  Our thanks to them for keeping their
-sense of humor through a long and sometimes difficult design process.
-Although the words and much of the design are due to them, many others
-have contributed substantially to the design and implementation.
-Tom McFarland (HP) and Frank Rojas (IBM) deserve particular recognition
-for their contributions.   Other contributors were:
-Tim Anderson (Motorola), Alka Badshah (OSF), Gabe Beged-Dov (HP),
-Chih-Chung Ko (III), Vera Cheng (III), Michael Collins (Digital),
-Walt Daniels (IBM), Noritoshi Demizu (OMRON), Keisuke Fukui (Fujitsu),
-Hitoshoi Fukumoto (Nihon Sun), Tim Greenwood (Digital), John Harvey (IBM),
-Hideki Hiura (Sun), Fred Horman (AT&T), Norikazu Kaiya (Fujitsu),
-Yuji Kamata (IBM),
-Yutaka Kataoka (Waseda University), Ranee Khubchandani (Sun), Akira Kon (NEC),
-Hiroshi Kuribayashi (OMRON), Teruhiko Kurosaka (Sun), Seiji Kuwari (OMRON),
-Sandra Martin (OSF), Narita Masahiko (Fujitsu), Masato Morisaki (NTT),
-Nelson Ng (Sun),
-Takashi Nishimura (NTT America), Makato Nishino (IBM),
-Akira Ohsone (Nihon Sun), Chris Peterson (MIT), Sam Shteingart (AT&T),
-Manish Sheth (AT&T), Muneiyoshi Suzuki (NTT), Cori Mehring (Digital),
-Shoji Sugiyama (IBM), and Eiji Tosa (IBM).
-.LP
-We are deeply indebted to Tatsuya Kato (NTT),
-Hiroshi Kuribayashi (OMRON), Seiji Kuwari (OMRON), Muneiyoshi Suzuki (NTT),
-and Li Yuhong (OMRON) for producing one of the first complete
-sample implementation of the internationalization facilities, and 
-Hiromu Inukai (Nihon Sun), Takashi Fujiwara (Fujitsu), Hideki Hiura (Sun), 
-Yasuhiro Kawai (Oki Technosystems Laboratory), Kazunori Nishihara (Fuji Xerox),
-Masaki Takeuchi (Sony), Katsuhisa Yano (Toshiba),
-Makoto Wakamatsu (Sony Corporation) for producing the another complete
-sample implementation of the internationalization facilities.
-.LP
-The principal authors (design and implementation) of the Xcms color
-management facilities are Al Tabayoyon (Tektronix)
-and Chuck Adams (Tektronix).  
-Joann Taylor (Tektronix), Bob Toole (Tektronix),
-and Keith Packard (MIT X Consortium) also
-contributed significantly to the design.  Others who contributed are:
-Harold Boll (Kodak), Ken Bronstein (HP), Nancy Cam (SGI),
-Donna Converse (MIT X Consortium), Elias Israel (ISC), Deron Johnson (Sun),
-Jim King (Adobe), Ricardo Motta (HP), Chuck Peek (IBM),
-Wil Plouffe (IBM), Dave Sternlicht (MIT X Consortium), Kumar Talluri (AT&T),
-and Richard Verberg (IBM).
-.LP
-We also once again thank Al Mento of Digital for his work in formatting
-and reformatting text for this manual, and for producing man pages.
-Thanks also to Clive Feather (IXI) for proof-reading and finding a
-number of small errors.
-.SH
-Release 6
-.LP
-Stephen Gildea (X Consortium) authored the threads support.
-Ovais Ashraf (Sun) and Greg Olsen (Sun) contributed substantially
-by testing the facilities and reporting bugs in a timely fashion.
-.LP
-The principal authors of the internationalization facilities, including
-Input and Output Methods, are Hideki Hiura (SunSoft) and
-Shigeru Yamada (Fujitsu OSSI).
-Although the words and much of the design are due to them, many others
-have contributed substantially to the design and implementation.
-They are: Takashi Fujiwara (Fujitsu), Yoshio Horiuchi (IBM),
-Makoto Inada (Digital), Hiromu Inukai (Nihon SunSoft),
-Song JaeKyung (KAIST), Franky Ling (Digital), Tom McFarland (HP),
-Hiroyuki Miyamoto (Digital), Masahiko Narita (Fujitsu),
-Frank Rojas (IBM), Hidetoshi Tajima (HP), Masaki Takeuchi (Sony),
-Makoto Wakamatsu (Sony), Masaki Wakao (IBM), Katsuhisa Yano(Toshiba) and
-Jinsoo Yoon (KAIST).
-.LP
-The principal producers of the sample implementation of the 
-internationalization facilities are: 
-Jeffrey Bloomfield (Fujitsu OSSI), Takashi Fujiwara (Fujitsu),
-Hideki Hiura (SunSoft), Yoshio Horiuchi (IBM), 
-Makoto Inada (Digital), Hiromu Inukai (Nihon SunSoft), 
-Song JaeKyung (KAIST), Riki Kawaguchi (Fujitsu), 
-Franky Ling (Digital), Hiroyuki Miyamoto (Digital), 
-Hidetoshi Tajima (HP), Toshimitsu Terazono (Fujitsu), 
-Makoto Wakamatsu (Sony), Masaki Wakao (IBM), 
-Shigeru Yamada (Fujitsu OSSI) and Katsuhisa Yano (Toshiba).
-.LP
-The coordinators of the integration, testing, and release of this 
-implementation of the internationalization facilities are
-Nobuyuki Tanaka (Sony) and Makoto Wakamatsu (Sony).
-.LP
-Others who have contributed to the architectural design or
-testing of the sample implementation of the
-internationalization facilities are:
-Hector Chan (Digital), Michael Kung (IBM), Joseph Kwok (Digital),
-Hiroyuki Machida (Sony), Nelson Ng (SunSoft), Frank Rojas (IBM), 
-Yoshiyuki Segawa (Fujitsu OSSI), Makiko Shimamura (Fujitsu), 
-Shoji Sugiyama (IBM), Lining Sun (SGI), Masaki Takeuchi (Sony),
-Jinsoo Yoon (KAIST) and Akiyasu Zen (HP).
-.sp 2
-.LP
-.Ds 0
-.TA 1.5i 3i
-.ta 1.5i 3i
-.R
-Jim Gettys
-Cambridge Research Laboratory
-Digital Equipment Corporation
-
-Robert W. Scheifler
-Laboratory for Computer Science
-Massachusetts Institute of Technology
-.DE
-.bp 1
+<preface id="acknowledgments">

+<title>Acknowledgments</title>

+<para>

+The design and implementation of the first 10 versions of X

+were primarily the work of three individuals: Robert Scheifler of the

+MIT Laboratory for Computer Science and Jim Gettys of Digital

+Equipment Corporation and Ron Newman of MIT, both at MIT

+Project Athena. 

+X version 11, however, is the result of the efforts of 

+dozens of individuals at almost as many locations and organizations.

+At the risk of offending some of the players by exclusion, 

+we would like to acknowledge some of the people who deserve special credit 

+and recognition for their work on Xlib.

+Our apologies to anyone inadvertently overlooked.

+</para>

+<sect1 id="release1">

+<title>

+Release 1

+</title>

+<para>

+Our thanks does to Ron Newman (MIT Project Athena),

+who contributed substantially to the

+design and implementation of the Version 11 Xlib interface.

+</para>

+<para>

+Our thanks also goes to Ralph Swick (Project Athena and Digital) who kept 

+it all together for us during the early releases.

+He handled literally thousands of requests from people everywhere

+and saved the sanity of at least one of us.

+His calm good cheer was a foundation on which we could build.

+</para>

+<para>

+Our thanks also goes to Todd Brunhoff (Tektronix) who was ``loaned'' 

+to Project Athena at exactly the right moment to provide very capable 

+and much-needed assistance during the alpha and beta releases.

+He was responsible for the successful integration of sources

+from multiple sites;

+we would not have had a release without him.

+</para>

+<para>

+Our thanks also goes to Al Mento and Al Wojtas of Digital's ULTRIX 

+Documentation Group.

+With good humor and cheer,

+they took a rough draft and made it an infinitely better and more useful 

+document.

+The work they have done will help many everywhere.

+We also would like to thank Hal Murray (Digital SRC) and

+Peter George (Digital VMS) who contributed much

+by proofreading the early drafts of this document.

+</para>

+<para>

+Our thanks also goes to Jeff Dike (Digital UEG), Tom Benson, 

+Jackie Granfield, and Vince Orgovan (Digital VMS) who helped with the 

+library utilities implementation;

+to Hania Gajewska (Digital UEG-WSL) who,

+along with Ellis Cohen (CMU and Siemens),

+was instrumental in the semantic design of the window manager properties;

+and to Dave Rosenthal (Sun Microsystems) who also contributed to the protocol 

+and provided the sample generic color frame buffer device-dependent code.

+</para>

+<para>

+The alpha and beta test participants deserve special recognition and thanks

+as well.

+It is significant

+that the bug reports (and many fixes) during alpha and beta test came almost

+exclusively from just a few of the alpha testers, mostly hardware vendors

+working on product implementations of X.  

+The continued public

+contribution of vendors and universities is certainly to the benefit 

+of the entire X community.

+</para>

+<para>

+Our special thanks must go to Sam Fuller, Vice-President of Corporate

+Research at Digital, who has remained committed to the widest public 

+availability of X and who made it possible to greatly supplement MIT's

+resources with the Digital staff in order to make version 11 a reality.

+Many of the people mentioned here are part of the Western

+Software Laboratory (Digital UEG-WSL) of the ULTRIX Engineering group

+and work for Smokey Wallace, who has been vital to the project's success. 

+Others not mentioned here worked on the toolkit and are acknowledged 

+in the X Toolkit documentation.

+</para>

+<para>

+Of course, 

+we must particularly thank Paul Asente, formerly of Stanford University

+and now of Digital UEG-WSL, who wrote W, the predecessor to X,

+and Brian Reid, formerly of Stanford University and now of Digital WRL,

+who had much to do with W's design.

+</para>

+<para>

+Finally, our thanks goes to MIT,  Digital Equipment Corporation,

+and IBM for providing the environment where it could happen.

+</para>

+</sect1>

+<sect1 id="release4">

+<title>

+Release 4

+</title>

+<para>

+Our thanks go to Jim Fulton (MIT X Consortium) for designing and

+specifying the new Xlib functions for Inter-Client Communication

+Conventions (<acronym>ICCCM</acronym>) support.

+</para>

+<para>

+We also thank Al Mento of Digital for his continued effort in

+maintaining this document and Jim Fulton and Donna Converse (MIT X Consortium)

+for their much-appreciated efforts in reviewing the changes.

+</para>

+</sect1>

+<sect1 id="release5">

+<title>

+Release 5

+</title>

+<para>

+The principal authors of the Input Method facilities are

+Vania Joloboff (Open Software Foundation) and Bill McMahon (Hewlett-Packard).

+The principal author of the rest of the internationalization facilities

+is Glenn Widener (Tektronix).  Our thanks to them for keeping their

+sense of humor through a long and sometimes difficult design process.

+Although the words and much of the design are due to them, many others

+have contributed substantially to the design and implementation.

+Tom McFarland (HP) and Frank Rojas (IBM) deserve particular recognition

+for their contributions.   Other contributors were:

+Tim Anderson (Motorola), Alka Badshah (OSF), Gabe Beged-Dov (HP),

+Chih-Chung Ko (III), Vera Cheng (III), Michael Collins (Digital),

+Walt Daniels (IBM), Noritoshi Demizu (OMRON), Keisuke Fukui (Fujitsu),

+Hitoshoi Fukumoto (Nihon Sun), Tim Greenwood (Digital), John Harvey (IBM),

+Hideki Hiura (Sun), Fred Horman (AT&amp;T), Norikazu Kaiya (Fujitsu),

+Yuji Kamata (IBM),

+Yutaka Kataoka (Waseda University), Ranee Khubchandani (Sun), Akira Kon (NEC),

+Hiroshi Kuribayashi (OMRON), Teruhiko Kurosaka (Sun), Seiji Kuwari (OMRON),

+Sandra Martin (OSF), Narita Masahiko (Fujitsu), Masato Morisaki (NTT),

+Nelson Ng (Sun),

+Takashi Nishimura (NTT America), Makato Nishino (IBM),

+Akira Ohsone (Nihon Sun), Chris Peterson (MIT), Sam Shteingart (AT&amp;T),

+Manish Sheth (AT&amp;T), Muneiyoshi Suzuki (NTT), Cori Mehring (Digital),

+Shoji Sugiyama (IBM), and Eiji Tosa (IBM).

+</para>

+<para>

+We are deeply indebted to Tatsuya Kato (NTT),

+Hiroshi Kuribayashi (OMRON), Seiji Kuwari (OMRON), Muneiyoshi Suzuki (NTT),

+and Li Yuhong (OMRON) for producing one of the first complete

+sample implementation of the internationalization facilities, and 

+Hiromu Inukai (Nihon Sun), Takashi Fujiwara (Fujitsu), Hideki Hiura (Sun), 

+Yasuhiro Kawai (Oki Technosystems Laboratory), Kazunori Nishihara (Fuji Xerox),

+Masaki Takeuchi (Sony), Katsuhisa Yano (Toshiba),

+Makoto Wakamatsu (Sony Corporation) for producing the another complete

+sample implementation of the internationalization facilities.

+</para>

+<para>

+The principal authors (design and implementation) of the Xcms color

+management facilities are Al Tabayoyon (Tektronix)

+and Chuck Adams (Tektronix).  

+Joann Taylor (Tektronix), Bob Toole (Tektronix),

+and Keith Packard (MIT X Consortium) also

+contributed significantly to the design.  Others who contributed are:

+Harold Boll (Kodak), Ken Bronstein (HP), Nancy Cam (SGI),

+Donna Converse (MIT X Consortium), Elias Israel (ISC), Deron Johnson (Sun),

+Jim King (Adobe), Ricardo Motta (HP), Chuck Peek (IBM),

+Wil Plouffe (IBM), Dave Sternlicht (MIT X Consortium), Kumar Talluri (AT&amp;T),

+and Richard Verberg (IBM).

+</para>

+<para>

+We also once again thank Al Mento of Digital for his work in formatting

+and reformatting text for this manual, and for producing man pages.

+Thanks also to Clive Feather (IXI) for proof-reading and finding a

+number of small errors.

+</para>

+</sect1>

+<sect1 id="release6">

+<title>

+Release 6

+</title>

+<para>

+Stephen Gildea (X Consortium) authored the threads support.

+Ovais Ashraf (Sun) and Greg Olsen (Sun) contributed substantially

+by testing the facilities and reporting bugs in a timely fashion.

+</para>

+<para>

+The principal authors of the internationalization facilities, including

+Input and Output Methods, are Hideki Hiura (SunSoft) and

+Shigeru Yamada (Fujitsu OSSI).

+Although the words and much of the design are due to them, many others

+have contributed substantially to the design and implementation.

+They are: Takashi Fujiwara (Fujitsu), Yoshio Horiuchi (IBM),

+Makoto Inada (Digital), Hiromu Inukai (Nihon SunSoft),

+Song JaeKyung (KAIST), Franky Ling (Digital), Tom McFarland (HP),

+Hiroyuki Miyamoto (Digital), Masahiko Narita (Fujitsu),

+Frank Rojas (IBM), Hidetoshi Tajima (HP), Masaki Takeuchi (Sony),

+Makoto Wakamatsu (Sony), Masaki Wakao (IBM), Katsuhisa Yano(Toshiba) and

+Jinsoo Yoon (KAIST).

+</para>

+<para>

+The principal producers of the sample implementation of the 

+internationalization facilities are: 

+Jeffrey Bloomfield (Fujitsu OSSI), Takashi Fujiwara (Fujitsu),

+Hideki Hiura (SunSoft), Yoshio Horiuchi (IBM), 

+Makoto Inada (Digital), Hiromu Inukai (Nihon SunSoft), 

+Song JaeKyung (KAIST), Riki Kawaguchi (Fujitsu), 

+Franky Ling (Digital), Hiroyuki Miyamoto (Digital), 

+Hidetoshi Tajima (HP), Toshimitsu Terazono (Fujitsu), 

+Makoto Wakamatsu (Sony), Masaki Wakao (IBM), 

+Shigeru Yamada (Fujitsu OSSI) and Katsuhisa Yano (Toshiba).

+</para>

+<para>

+The coordinators of the integration, testing, and release of this 

+implementation of the internationalization facilities are

+Nobuyuki Tanaka (Sony) and Makoto Wakamatsu (Sony).

+</para>

+<para>

+Others who have contributed to the architectural design or

+testing of the sample implementation of the

+internationalization facilities are:

+Hector Chan (Digital), Michael Kung (IBM), Joseph Kwok (Digital),

+Hiroyuki Machida (Sony), Nelson Ng (SunSoft), Frank Rojas (IBM), 

+Yoshiyuki Segawa (Fujitsu OSSI), Makiko Shimamura (Fujitsu), 

+Shoji Sugiyama (IBM), Lining Sun (SGI), Masaki Takeuchi (Sony),

+Jinsoo Yoon (KAIST) and Akiyasu Zen (HP).

+</para>

+<para>

+<literallayout>

+Jim Gettys

+Cambridge Research Laboratory

+Digital Equipment Corporation

+

+Robert W. Scheifler

+Laboratory for Computer Science

+Massachusetts Institute of Technology

+</literallayout>

+</para>

+</sect1>

+</preface>

diff --git a/libX11/specs/libX11/glossary b/libX11/specs/libX11/glossary
deleted file mode 100644
index a130928a6..000000000
--- a/libX11/specs/libX11/glossary
+++ /dev/null
@@ -1,1484 +0,0 @@
-\&
-.sp 1
-.ce 1
-\s+1\fBGlossary\fP\s-1
-.sp 2
-.na
-.LP
-.XS
-Glossary
-.XE
-.KS
-\fBAccess control list\fP
-.IN "Access control list" "" "@DEF@"
-.IP
-X maintains a list of hosts from which client programs can be run.  
-By default, 
-only programs on the local host and hosts specified in an initial list read
-by the server can use the display.
-This access control list can be changed by clients on the local host.  
-Some server implementations can also implement other authorization mechanisms
-in addition to or in place of this mechanism.
-The action of this mechanism can be conditional based on the authorization 
-protocol name and data received by the server at connection setup. 
-.KE
-.LP
-.KS
-\fBActive grab\fP
-.IN "Active grab" "" "@DEF@"
-.IP
-A grab is active when the pointer or keyboard is actually owned by the 
-single grabbing client.
-.KE
-.LP
-.KS
-\fBAncestors\fP
-.IN "Ancestors" "" "@DEF@"
-.IP
-If W is an inferior of A, then A is an ancestor of W.
-.KE
-.LP
-.KS
-\fBAtom\fP
-.IN "Atom" "" "@DEF@"
-.IP
-An atom is a unique ID corresponding to a string name.
-Atoms are used to identify properties, types, and selections.
-.KE
-.LP
-.KS
-\fBBackground\fP
-.IN "Background" "" "@DEF@"
-.IP
-An
-.PN InputOutput
-window can have a background, which is defined as a pixmap.
-When regions of the window have their contents lost 
-or invalidated,
-the server automatically tiles those regions with the background.
-.KE
-.LP
-.KS
-\fBBacking store\fP
-.IN "Backing store" "" "@DEF@"
-.IP
-When a server maintains the contents of a window, 
-the pixels saved off-screen are known as a backing store.
-.KE
-.LP
-.KS
-\fBBase font name\fP
-.IN "Base font name" "" "@DEF@"
-.IP
-A font name used to select a family of fonts whose members may be encoded 
-in various charsets.
-The
-.PN CharSetRegistry
-and 
-.PN CharSetEncoding
-fields of an XLFD name identify the charset of the font.
-A base font name may be a full XLFD name, with all fourteen '-' delimiters, 
-or an abbreviated XLFD name containing only the first 12 fields of an XLFD name,
-up to but not including 
-.PN CharSetRegistry ,
-with or without the thirteenth '-', or a non-XLFD name.
-Any XLFD fields may contain wild cards.
-.IP
-When creating an 
-.PN XFontSet ,
-Xlib accepts from the client a list of one or more base font names 
-which select one or more font families.
-They are combined with charset names obtained from the encoding of the locale
-to load the fonts required to render text.
-.KE
-.LP
-.KS
-\fBBit gravity\fP
-.IN "Bit" "gravity" "@DEF@"
-.IP
-When a window is resized, 
-the contents of the window are not necessarily discarded.  
-It is possible to request that the server relocate the previous contents 
-to some region of the window (though no guarantees are made).
-This attraction of window contents for some location of
-a window is known as bit gravity.
-.KE
-.LP
-.KS
-\fBBit plane\fP
-.IN "Bit" "plane" "@DEF@"
-.IP
-When a pixmap or window is thought of as a stack of bitmaps,
-each bitmap is called a bit plane or plane.
-.KE
-.LP
-.KS
-\fBBitmap\fP
-.IN "Bitmap" "" "@DEF@"
-.IP
-A bitmap is a pixmap of depth one.
-.KE
-.LP
-.KS
-\fBBorder\fP
-.IN "Border" "" "@DEF@"
-.IP
-An
-.PN InputOutput
-window can have a border of equal thickness on all four sides of the window.
-The contents of the border are defined by a pixmap,
-and the server automatically maintains the contents of the border.
-Exposure events are never generated for border regions.
-.KE
-.LP
-.KS
-\fBButton grabbing\fP
-.IN "Button" "grabbing" "@DEF@"
-.IP
-Buttons on the pointer can be passively grabbed by a client.
-When the button is pressed, 
-the pointer is then actively grabbed by the client.
-.KE
-.LP
-.KS
-\fBByte order\fP
-.IN "Byte" "order" "@DEF@"
-.IP
-For image (pixmap/bitmap) data, 
-the server defines the byte order,
-and clients with different native byte ordering must swap bytes as
-necessary.  
-For all other parts of the protocol, 
-the client defines the byte order,
-and the server swaps bytes as necessary.
-.KE
-.LP
-.KS
-\fBCharacter\fP
-.IN "Character" "" "@DEF@"
-.IP
-A member of a set of elements used for the organization,
-control, or representation of text (ISO2022, as adapted by XPG3).
-Note that in ISO2022 terms, a character is not bound to a coded value 
-until it is identified as part of a coded character set.
-.KE
-.LP
-.KS
-\fBCharacter glyph\fP
-.IN "Character glyph" "" "@DEF@"
-.IP
-The abstract graphical symbol for a character.
-Character glyphs may or may not map one-to-one to font glyphs,
-and may be context-dependent, varying with the adjacent characters.
-Multiple characters may map to a single character glyph.
-.KE
-.LP
-.KS
-\fBCharacter set\fP
-.IN "Character set" "" "@DEF@"
-.IP
-A collection of characters.
-.KE
-.LP
-.KS
-\fBCharset\fP
-.IN "Charset" "" "@DEF@"
-.IP
-An encoding with a uniform, state-independent mapping from characters 
-to codepoints.
-A coded character set.
-.IP
-For display in X,
-there can be a direct mapping from a charset to one font,
-if the width of all characters in the charset is either one or two bytes.
-A text string encoded in an encoding such as Shift-JIS cannot be passed
-directly to the X server, because the text imaging requests accept only
-single-width charsets (either 8 or 16 bits).
-Charsets which meet these restrictions can serve as ``font charsets''.
-Font charsets strictly speaking map font indices to font glyphs,
-not characters to character glyphs.
-.IP
-Note that a single font charset is sometimes used as the encoding of a locale,
-for example, ISO8859-1.
-.KE
-.LP
-.KS
-\fBChildren\fP
-.IN "Children" "" "@DEF@"
-.IP
-The children of a window are its first-level subwindows.
-.KE
-.LP
-.KS
-\fBClass\fP
-.IN "Class" "" "@DEF@"
-.IP
-Windows can be of different classes or types.
-See the entries for
-.PN InputOnly
-and
-.PN InputOutput
-windows for further information about valid window types.
-.KE
-.LP
-.KS
-\fBClient\fP
-.IN "Client" "" "@DEF@"
-.IP
-An application program connects to the window system server by some
-interprocess communication (IPC) path, such as a TCP connection or a
-shared memory buffer.  
-This program is referred to as a client of the window system server.  
-More precisely, 
-the client is the IPC path itself. 
-A program with multiple paths open to the server is viewed as
-multiple clients by the protocol.  
-Resource lifetimes are controlled by
-connection lifetimes, not by program lifetimes.
-.KE
-.LP
-.KS
-\fBClipping region\fP
-.IN "Clipping region" "" "@DEF@"
-.IP
-In a graphics context, 
-a bitmap or list of rectangles can be specified
-to restrict output to a particular region of the window.  
-The image defined by the bitmap or rectangles is called a clipping region.
-.KE
-.LP
-.KS
-\fBCoded character\fP
-.IN "Coded character" "" "@DEF@"
-.IP
-A character bound to a codepoint.
-.KE
-.LP
-.KS
-\fBCoded character set\fP
-.IN "Coded character set" "" "@DEF@"
-.IP
-A set of unambiguous rules that establishes a character set 
-and the one-to-one relationship between each character of the set 
-and its bit representation.
-(ISO2022, as adapted by XPG3)
-A definition of a one-to-one mapping of a set of characters to a set of
-codepoints.
-.KE
-.LP
-.KS
-\fBCodepoint\fP
-.IN "Codepoint" "" "@DEF@"
-.IP
-The coded representation of a single character in a coded character set.
-.KE
-.LP
-.KS
-\fBColormap\fP
-.IN "Colormap" "" "@DEF@"
-.IP
-A colormap consists of a set of entries defining color values.
-The colormap associated with a window is used to display the contents of
-the window; each pixel value indexes the colormap to produce an RGB value
-that drives the guns of a monitor.
-Depending on hardware limitations, 
-one or more colormaps can be installed at one time so
-that windows associated with those maps display with true colors.
-.KE
-.LP
-.KS
-\fBConnection\fP
-.IN "Connection" "" "@DEF@"
-.IP
-The IPC path between the server and client program is known as a connection.
-A client program typically (but not necessarily) has one
-connection to the server over which requests and events are sent.
-.KE
-.LP
-.KS
-\fBContainment\fP
-.IN "Containment" "" "@DEF@"
-.IP
-A window contains the pointer if the window is viewable and the
-hotspot of the cursor is within a visible region of the window or a
-visible region of one of its inferiors.  
-The border of the window is included as part of the window for containment.  
-The pointer is in a window if the window contains the pointer
-but no inferior contains the pointer.
-.KE
-.LP
-.KS
-\fBCoordinate system\fP
-.IN "Coordinate system" "" "@DEF@"
-.IP
-The coordinate system has X horizontal and Y vertical, 
-with the origin [0, 0] at the upper left.  
-Coordinates are integral and coincide with pixel centers.
-Each window and pixmap has its own coordinate system.  
-For a window, 
-the origin is inside the border at the inside upper-left corner.
-.KE
-.LP
-.KS
-\fBCursor\fP
-.IN "Cursor" "" "@DEF@"
-.IP
-A cursor is the visible shape of the pointer on a screen.  
-It consists of a hotspot, a source bitmap, a shape bitmap, 
-and a pair of colors.  
-The cursor defined for a window controls the visible
-appearance when the pointer is in that window.
-.KE
-.LP
-.KS
-\fBDepth\fP
-.IN "Depth" "" "@DEF@"
-.IP
-The depth of a window or pixmap is the number of bits per pixel it has.
-The depth of a graphics context is the depth of the drawables it can be
-used in conjunction with graphics output.
-.KE
-.LP
-.KS
-\fBDevice\fP
-.IN "Device" "" "@DEF@"
-.IP
-Keyboards, mice, tablets, track-balls, button boxes, and so on are all
-collectively known as input devices.
-Pointers can have one or more buttons 
-(the most common number is three).
-The core protocol only deals with two devices: the keyboard 
-and the pointer.
-.KE
-.LP
-.KS
-\fBDirectColor\fP
-.IN "DirectColor" "" "@DEF@"
-.IP
-.PN DirectColor
-is a class of colormap in which a pixel value is decomposed into three
-separate subfields for indexing.
-The first subfield indexes an array to produce red intensity values. 
-The second subfield indexes a second array to produce blue intensity values.
-The third subfield indexes a third array to produce green intensity values.
-The RGB (red, green, and blue) values in the colormap entry can be 
-changed dynamically.
-.KE
-.LP
-.KS
-\fBDisplay\fP
-.IN "Display" "" "@DEF@"
-.IP
-A server, together with its screens and input devices, is called a display.
-The Xlib
-.PN Display
-.IN "Display" "structure"
-structure contains all information about the particular display and its screens
-as well as the state that Xlib needs to communicate with the display over a
-particular connection.
-.KE
-.LP
-.KS
-\fBDrawable\fP
-.IN "Drawable" "" "@DEF@"
-.IP
-Both windows and pixmaps can be used as sources and destinations 
-in graphics operations.  
-These windows and pixmaps are collectively known as drawables.
-However, an 
-.PN InputOnly 
-window cannot be used as a source or destination in a
-graphics operation.
-.KE
-.LP
-.KS
-\fBEncoding\fP
-.IN "Encoding" "" "@DEF@"
-.IP
-A set of unambiguous rules that establishes a character set 
-and a relationship between the characters and their representations.
-The character set does not have to be fixed to a finite pre-defined set of
-characters.
-The representations do not have to be of uniform length.
-Examples are an ISO2022 graphic set, a state-independent 
-or state-dependent combination of graphic sets, possibly including control
-sets, and the X Compound Text encoding.
-.IP
-In X, encodings are identified by a string
-which appears as: the
-.PN CharSetRegistry
-and
-.PN CharSetEncoding
-components of an XLFD
-name; the name of a charset of the locale for which a font could not be
-found; or an atom which identifies the encoding of a text property or
-which names an encoding for a text selection target type.
-Encoding names should be composed of characters from the X Portable 
-Character Set.
-.KE
-.LP
-.KS
-\fBEscapement\fP
-.IN "Escapement" "" "@DEF@"
-.IP
-The escapement of a string is the distance in pixels in the
-primary draw direction from the drawing origin to the origin of the next
-character (that is, the one following the given string) to be drawn.
-.KE
-.LP
-.KS
-\fBEvent\fP
-.IN "Event" "" "@DEF@"
-.IP
-Clients are informed of information asynchronously by means of events.
-These events can be either asynchronously generated from devices or
-generated as side effects of client requests.  
-Events are grouped into types. 
-The server never sends an event to a client unless the
-client has specifically asked to be informed of that type of event.
-However, clients can force events to be sent to other clients.  
-Events are typically reported relative to a window.
-.KE
-.LP
-.KS
-\fBEvent mask\fP
-.IN "Event" "mask" "@DEF@"
-.IP
-Events are requested relative to a window.  
-The set of event types a client requests relative to a window is described 
-by using an event mask.
-.KE
-.LP
-.KS
-\fBEvent propagation\fP
-.IN "Event" "propagation" "@DEF@"
-.IP
-Device-related events propagate from the source window to ancestor
-windows until some client has expressed interest in handling that type
-of event or until the event is discarded explicitly.
-.KE
-.LP
-.KS
-\fBEvent source\fP
-.IN "Event" "source" "@DEF@"
-.IP
-The deepest viewable window that the pointer is in is called
-the source of a device-related event.
-.KE
-.LP
-.KS
-\fBEvent synchronization\fP
-.IN "Event" "synchronization" "@DEF@"
-.IP
-There are certain race conditions possible when demultiplexing device
-events to clients (in particular, deciding where pointer and keyboard
-events should be sent when in the middle of window management
-operations).  
-The event synchronization mechanism allows synchronous processing of 
-device events.
-.KE
-.LP
-.KS
-\fBExposure event\fP
-.IN "Event" "Exposure" "@DEF@"
-.IP
-Servers do not guarantee to preserve the contents of windows when
-windows are obscured or reconfigured.  
-Exposure events are sent to clients to inform them when contents of regions
-of windows have been lost.
-.KE
-.LP
-.KS
-\fBExtension\fP
-.IN "Extension" "" "@DEF@"
-.IP
-Named extensions to the core protocol can be defined to extend the system.  
-Extensions to output requests, resources, and event types are all possible
-and expected.
-.KE
-.LP
-.KS
-\fBFont\fP
-.IN "Font" "" "@DEF@"
-.IP
-A font is an array of glyphs (typically characters).  
-The protocol does no translation or interpretation of character sets.  
-The client simply indicates values used to index the glyph array.  
-A font contains additional metric information to determine interglyph 
-and interline spacing.
-.KE
-.LP
-.KS
-\fBFont glyph\fP
-.IN "Font glyph" "" "@DEF@"
-.IP
-The abstract graphical symbol for an index into a font.
-.KE
-.LP
-.KS
-\fBFrozen events\fP
-.IN "Frozen events" "" "@DEF@"
-.IP
-Clients can freeze event processing during keyboard and pointer grabs.
-.KE
-.LP
-.KS
-\fBGC\fP
-.IN "GC" "" "@DEF@"
-.IP
-GC is an abbreviation for graphics context.
-See \fBGraphics context\fP.
-.KE
-.LP
-.KS
-\fBGlyph\fP
-.IN "Glyph" "" "@DEF@"
-.IP
-An identified abstract graphical symbol independent of any actual image.
-(ISO/IEC/DIS 9541-1)
-An abstract visual representation of a graphic character,
-not bound to a codepoint.
-.KE
-.LP
-.KS
-\fBGlyph image\fP
-.IN "Glyph image" "" "@DEF@"
-.IP
-An image of a glyph, as obtained from a glyph representation displayed 
-on a presentation surface.
-(ISO/IEC/DIS 9541-1)
-.KE
-.LP
-.KS
-\fBGrab\fP
-.IN "Grab" "" "@DEF@"
-.IP
-Keyboard keys, the keyboard, pointer buttons, the pointer, 
-and the server can be grabbed for exclusive use by a client.  
-In general, 
-these facilities are not intended to be used by normal applications
-but are intended for various input and window managers to implement various
-styles of user interfaces.
-.KE
-.LP
-.KS
-\fBGraphics context\fP
-.IN "Graphics context" "" "@DEF@"
-.IP
-Various information for graphics output is stored in a graphics
-context (GC), such as foreground pixel, background
-pixel, line width, clipping region, and so on.
-A graphics context can only
-be used with drawables that have the same root and the same depth as
-the graphics context. 
-.KE
-.LP
-.KS
-\fBGravity\fP
-.IN "Gravity" "" "@DEF@"
-.IP
-The contents of windows and windows themselves have a gravity,
-which determines how the contents move when a window is resized.
-See \fBBit gravity\fP and \fBWindow gravity\fP.
-.KE
-.LP
-.KS
-\fBGrayScale\fP
-.IN "GrayScale" "" "@DEF@"
-.IP
-.PN GrayScale 
-can be viewed as a degenerate case of 
-.PN PseudoColor , 
-in which the red, green, and blue values in any given colormap entry 
-are equal and thus, produce shades of gray.
-The gray values can be changed dynamically.
-.KE
-.LP
-.KS
-\fBHost Portable Character Encoding\fP
-.IN "Host Portable Character Encoding" "" "@DEF@"
-.IP
-The encoding of the X Portable Character Set on the host.
-The encoding itself is not defined by this standard,
-but the encoding must be the same in all locales supported by Xlib on the host.
-If a string is said to be in the Host Portable Character Encoding,
-then it only contains characters from the X Portable Character Set,
-in the host encoding.
-.KE
-.LP
-.KS
-\fBHotspot\fP
-.IN "Hotspot" "" "@DEF@"
-.IP
-A cursor has an associated hotspot, which defines the point in the
-cursor corresponding to the coordinates reported for the pointer.
-.KE
-.LP
-.KS
-\fBIdentifier\fP
-.IN "Identifier" "" "@DEF@"
-.IP
-An identifier is a unique value associated with a resource
-that clients use to name that resource.  
-The identifier can be used over any connection to name the resource.
-.KE
-.LP
-.KS
-\fBInferiors\fP
-.IN "Inferiors" "" "@DEF@"
-.IP
-The inferiors of a window are all of the subwindows nested below it:
-the children, the children's children, and so on.
-.KE
-.LP
-.KS
-\fBInput focus\fP
-.IN "Input" "focus" "@DEF@"
-.IP
-The input focus is usually a window defining the scope for processing
-of keyboard input.
-If a generated keyboard event usually would be reported to this window 
-or one of its inferiors,
-the event is reported as usual.
-Otherwise, the event is reported with respect to the focus window.
-The input focus also can be set such that all keyboard events are discarded
-and such that the focus window is dynamically taken to be the root window
-of whatever screen the pointer is on at each keyboard event.
-.KE
-.LP
-.KS
-\fBInput manager\fP
-.IN "Input" "manager" "@DEF@"
-.IP
-Control over keyboard input is typically provided by an input manager 
-client, which usually is part of a window manager.
-.KE
-.LP
-.KS
-\fBInputOnly window\fP
-.IN "Window" "InputOnly" "@DEF@"
-.IP
-An
-.PN InputOnly
-window is a window that cannot be used for graphics requests.  
-.PN InputOnly 
-windows are invisible and are used to control such things as cursors,
-input event generation, and grabbing.
-.PN InputOnly 
-windows cannot have 
-.PN InputOutput 
-windows as inferiors.
-.KE
-.LP
-.KS
-\fBInputOutput window\fP
-.IN "Window" "InputOutput" "@DEF@"
-.IP
-An
-.PN InputOutput
-window is the normal kind of window that is used for both input and output.
-.PN InputOutput 
-windows can have both 
-.PN InputOutput 
-and 
-.PN InputOnly 
-windows as inferiors.
-.KE
-.LP
-.KS
-\fBInternationalization\fP
-.IN "Internationalization" "" "@DEF@"
-.IP
-The process of making software adaptable to the requirements
-of different native languages, local customs, and character string encodings.
-Making a computer program adaptable to different locales 
-without program source modifications or recompilation.
-.KE
-.LP
-.KS
-\fBISO2022\fP
-.IN "ISO2022" "" "@DEF@"
-.IP
-ISO standard for code extension techniques for 7-bit and 8-bit coded 
-character sets.
-.KE
-.LP
-.KS
-\fBKey grabbing\fP
-.IN "Key" "grabbing" "@DEF@"
-.IP
-Keys on the keyboard can be passively grabbed by a client.  
-When the key is pressed, 
-the keyboard is then actively grabbed by the client.
-.KE
-.LP
-.KS
-\fBKeyboard grabbing\fP
-.IN "Keyboard" "grabbing" "@DEF@"
-.IP
-A client can actively grab control of the keyboard, and key events
-will be sent to that client rather than the client the events would
-normally have been sent to.
-.KE
-.LP
-.KS
-\fBKeysym\fP
-.IN "Keysym" "" "@DEF@"
-.IP
-An encoding of a symbol on a keycap on a keyboard.
-.KE
-.LP
-.KS
-\fBLatin-1\fP
-.IN "Latin-1" "" "@DEF@"
-.IP
-The coded character set defined by the ISO8859-1 standard.
-.KE
-.LP
-.KS
-\fBLatin Portable Character Encoding\fP
-.IN "Latin Portable Character Encoding" "" "@DEF@"
-.IP
-The encoding of the X Portable Character Set using the Latin-1 codepoints
-plus ASCII control characters.
-If a string is said to be in the Latin Portable Character Encoding,
-then it only contains characters from the X Portable Character Set,
-not all of Latin-1.
-.KE
-.LP
-.KS
-\fBLocale\fP
-.IN "Locale" "" "@DEF@"
-.IP
-The international environment of a computer program defining the ``localized''
-behavior of that program at run-time.
-This information can be established from one or more sets of localization data.
-ANSI C defines locale-specific processing by C system library calls.
-See ANSI C and the X/Open Portability Guide specifications for more details.
-In this specification, on implementations that conform to the ANSI C library,
-the ``current locale'' is the current setting of the LC_CTYPE
-.PN setlocale
-category.
-Associated with each locale is a text encoding.  When text is processed
-in the context of a locale, the text must be in the encoding of the locale.
-The current locale affects Xlib in its:
-.RS
-.IP \(bu 5
-Encoding and processing of input method text
-.IP \(bu 5
-Encoding of resource files and values
-.IP \(bu 5
-Encoding and imaging of text strings
-.IP \(bu 5
-Encoding and decoding for inter-client text communication
-.RE
-.KE
-.LP
-.KS
-\fBLocale name\fP
-.IN "Locale name" "" "@DEF@"
-.IP
-The identifier used to select the desired locale for the host C library 
-and X library functions.
-On ANSI C library compliant systems,
-the locale argument to the
-.PN setlocale
-function.
-.KE
-.LP
-.KS
-\fBLocalization\fP
-.IN "Localization" "" "@DEF@"
-.IP
-The process of establishing information within a computer system specific 
-to the operation of particular native languages, local customs 
-and coded character sets.
-(XPG3)
-.KE
-.LP
-.KS
-\fBMapped\fP
-.IN "Mapped window" "" "@DEF@"
-.IP
-A window is said to be mapped if a map call has been performed on it.
-Unmapped windows and their inferiors are never viewable or visible.
-.KE
-.LP
-.KS
-\fBModifier keys\fP
-.IN "Modifier keys" "" "@DEF@"
-.IP
-Shift, Control, Meta, Super, Hyper, Alt, Compose, Apple, CapsLock,
-ShiftLock, and similar keys are called modifier keys.
-.KE
-.LP
-.KS
-\fBMonochrome\fP
-.IN "Monochrome" "" "@DEF@"
-.IP
-Monochrome is a special case of 
-.PN StaticGray
-in which there are only two colormap entries.
-.KE
-.LP
-.KS
-\fBMultibyte\fP
-.IN "Multibyte" "" "@DEF@"
-.IP
-A character whose codepoint is stored in more than one byte;
-any encoding which can contain multibyte characters;
-text in a multibyte encoding.
-The ``char *'' null-terminated string datatype in ANSI C.
-Note that references in this document to multibyte strings
-imply only that the strings \fImay\fP contain multibyte characters.
-.KE
-.LP
-.KS
-\fBObscure\fP
-.IN "Obscure" "" "@DEF@"
-.IP
-A window is obscured if some other window obscures it.
-A window can be partially obscured and so still have visible regions.
-Window A obscures window B if both are viewable 
-.PN InputOutput 
-windows, if A is higher in the global stacking order, 
-and if the rectangle defined by the outside
-edges of A intersects the rectangle defined by the outside edges of B.
-Note the distinction between obscures and occludes.
-Also note that window borders are included in the calculation.
-.KE
-.LP
-.KS
-\fBOcclude\fP
-.IN "Occlude" "" "@DEF@"
-.IP
-A window is occluded if some other window occludes it.
-Window A occludes window B if both are mapped, 
-if A is higher in the global stacking order, 
-and if the rectangle defined by the outside edges of A intersects the rectangle defined 
-by the outside edges of B.  
-Note the distinction between occludes and obscures.
-Also note that window borders are included in the calculation
-and that
-.PN InputOnly
-windows never obscure other windows but can occlude other windows.
-.KE
-.LP
-.KS
-\fBPadding\fP
-.IN "Padding" "" "@DEF@"
-.IP
-Some padding bytes are inserted in the data stream to maintain
-alignment of the protocol requests on natural boundaries.  
-This increases ease of portability to some machine architectures.
-.KE
-.LP
-.KS
-\fBParent window\fP
-.IN "Window" "parent" "@DEF@"
-.IP
-If C is a child of P, then P is the parent of C.
-.KE
-.LP
-.KS
-\fBPassive grab\fP
-.IN "Passive grab" "" "@DEF@"
-.IP
-Grabbing a key or button is a passive grab.  
-The grab activates when the key or button is actually pressed.
-.KE
-.LP
-.KS
-\fBPixel value\fP
-.IN "Pixel value" "" "@DEF@"
-.IP
-A pixel is an N-bit value,
-where N is the number of bit planes used in a particular window or pixmap
-(that is, is the depth of the window or pixmap).  
-A pixel in a window indexes a colormap to derive an actual color to be 
-displayed.
-.KE
-.LP
-.KS
-\fBPixmap\fP
-.IN "Pixmap" "" "@DEF@"
-.EQ
-delim %%
-.EN
-.IP
-A pixmap is a three-dimensional array of bits.  
-A pixmap is normally thought of as a two-dimensional array of pixels, 
-where each pixel can be a value from 0 to %2 sup N %\-1, 
-and where N is the depth (z axis) of the pixmap.  
-A pixmap can also be thought of as a stack of N bitmaps.
-A pixmap can only be used on the screen that it was created in.
-.KE
-.LP
-.KS
-\fBPlane\fP
-.IN "Plane" "" "@DEF@"
-.IP
-When a pixmap or window is thought of as a stack of bitmaps, each
-bitmap is called a plane or bit plane.
-.KE
-.LP
-.KS
-\fBPlane mask\fP
-.IN "Plane" "mask" "@DEF@"
-.IP
-Graphics operations can be restricted to only affect a subset of bit
-planes of a destination.  
-A plane mask is a bit mask describing which planes are to be modified.
-The plane mask is stored in a graphics context.
-.KE
-.LP
-.KS
-\fBPointer\fP
-.IN "Pointer" "" "@DEF@"
-.IP
-The pointer is the pointing device currently attached to the cursor
-and tracked on the screens.
-.KE
-.LP
-.KS
-\fBPointer grabbing\fP
-.IN "Pointer" "grabbing" "@DEF@"
-.IP
-A client can actively grab control of the pointer. 
-Then button and motion events will be sent to that client 
-rather than the client the events would normally have been sent to.
-.KE
-.LP
-.KS
-\fBPointing device\fP
-.IN "Pointing device"  "" "@DEF@"
-.IP
-A pointing device is typically a mouse, tablet, or some other
-device with effective dimensional motion.  
-The core protocol defines only one visible cursor,
-which tracks whatever pointing device is attached as the pointer.
-.KE
-.LP
-.KS
-\fBPOSIX\fP
-.IN "POSIX" "" "@DEF@"
-.IP
-Portable Operating System Interface, ISO/IEC 9945-1 (IEEE Std 1003.1).
-.KE
-.LP
-.KS
-\fBPOSIX Portable Filename Character Set\fP
-.IN "POSIX Portable Filename Character Set" "" "@DEF@"
-.IP
-The set of 65 characters which can be used in naming files on a POSIX-compliant
-host that are correctly processed in all locales.
-The set is:
-.IP
-.Ds 0
-a..z A..Z 0..9 ._-
-.De
-.KE
-.LP
-.KS
-\fBProperty\fP
-.IN "Property" "" "@DEF@"
-.IP
-Windows can have associated properties that consist of a name, a type,
-a data format, and some data. 
-The protocol places no interpretation on properties. 
-They are intended as a general-purpose naming mechanism for clients.  
-For example, clients might use properties to share information such as resize
-hints, program names, and icon formats with a window manager.
-.KE
-.LP
-.KS
-\fBProperty list\fP
-.IN "Property list" "" "@DEF@"
-.IP
-The property list of a window is the list of properties that have
-been defined for the window.
-.KE
-.LP
-.KS
-\fBPseudoColor\fP
-.IN "PseudoColor" "" "@DEF@"
-.IP
-.PN PseudoColor
-is a class of colormap in which a pixel value indexes the colormap entry to
-produce an independent RGB value;
-that is, the colormap is viewed as an array of triples (RGB values).
-The RGB values can be changed dynamically.
-.KE
-.LP
-.KS
-\fBRectangle\fP
-.IN "Rectangle" "" "@DEF@"
-.IP
-A rectangle specified by [x,y,w,h] has an infinitely thin
-outline path with corners at [x,y], [x+w,y], [x+w,y+h], and [x, y+h].
-When a rectangle is filled,
-the lower-right edges are not drawn.
-For example,
-if w=h=0,
-nothing would be drawn.
-For w=h=1,
-a single pixel would be drawn.
-.KE
-.LP
-.KS
-\fBRedirecting control\fP
-.IN "Redirecting control" "" "@DEF@"
-.IP
-Window managers (or client programs) may enforce window layout
-policy in various ways.  
-When a client attempts to change the size or position of a window, 
-the operation may be redirected to a specified client
-rather than the operation actually being performed.
-.KE
-.LP
-.KS
-\fBReply\fP
-.IN "Reply" "" "@DEF@"
-.IP
-Information requested by a client program using the X protocol 
-is sent back to the client with a reply.
-Both events and replies are multiplexed on the same connection.  
-Most requests do not generate replies,
-but some requests generate multiple replies.
-.KE
-.LP
-.KS
-\fBRequest\fP
-.IN "Request" "" "@DEF@"
-.IP
-A command to the server is called a request.
-It is a single block of data sent over a connection.
-.KE
-.LP
-.KS
-\fBResource\fP
-.IN "Resource" "" "@DEF@"
-.IP
-Windows, pixmaps, cursors, fonts, graphics contexts, and colormaps are
-known as resources.  
-They all have unique identifiers associated with them for naming purposes.  
-The lifetime of a resource usually is bounded by the lifetime of the 
-connection over which the resource was created.
-.KE
-.LP
-.KS
-\fBRGB values\fP
-.IN "RGB values" "" "@DEF@"
-.IP
-RGB values are the red, green, and blue intensity values that are used
-to define a color.
-These values are always represented as 16-bit, unsigned numbers, with 0
-the minimum intensity and 65535 the maximum intensity.
-The X server scales these values to match the display hardware.
-.KE
-.LP
-.KS
-\fBRoot\fP
-.IN "Root" "" "@DEF@"
-.IP
-The root of a pixmap or graphics context is the same as the root 
-of whatever drawable was used when the pixmap or GC was created.  
-The root of a window is the root window under which the window was created.
-.KE
-.LP
-.KS
-\fBRoot window\fP
-.IN "Window" "root" "@DEF@"
-.IP
-Each screen has a root window covering it.
-The root window cannot be reconfigured or unmapped, 
-but otherwise it acts as a full-fledged window.
-A root window has no parent.
-.KE
-.LP
-.KS
-\fBSave set\fP
-.IN "Save set" "" "@DEF@"
-.IP
-The save set of a client is a list of other clients' windows that,
-if they are inferiors of one of the client's windows at connection
-close, should not be destroyed and that should be remapped 
-if currently unmapped.
-Save sets are typically used by window managers to avoid
-lost windows if the manager should terminate abnormally.
-.KE
-.LP
-.KS
-\fBScanline\fP
-.IN "Scanline" "" "@DEF@"
-.IP
-A scanline is a list of pixel or bit values viewed as a horizontal
-row (all values having the same y coordinate) of an image, with the
-values ordered by increasing the x coordinate.
-.KE
-.LP
-.KS
-\fBScanline order\fP
-.IN "Scanline" "order" "@DEF@"
-.IP
-An image represented in scanline order contains scanlines ordered by
-increasing the y coordinate.
-.KE
-.LP
-.KS
-\fBScreen\fP
-.IN "Screen" "" "@DEF@"
-.IP
-A server can provide several independent screens, 
-which typically have physically independent monitors.  
-This would be the expected configuration when there is only a single keyboard 
-and pointer shared among the screens.
-A 
-.PN Screen 
-.IN "Screen" "structure"
-structure contains the information about that screen
-and is linked to the 
-.PN Display
-.IN "Display" "structure"
-structure.
-.KE
-.LP
-.KS
-\fBSelection\fP
-.IN "Selection" "" "@DEF@"
-.IP
-A selection can be thought of as an indirect property with dynamic
-type.
-That is, rather than having the property stored in the X server,
-it is maintained by some client (the owner).
-A selection is global and is thought of as belonging to the user 
-and being maintained by clients, 
-rather than being private to a particular window subhierarchy
-or a particular set of clients.
-When a client asks for the contents of
-a selection, it specifies a selection target type,
-which can be used to control the transmitted representation of the contents.
-For example, if the selection is ``the last thing the user clicked on,''
-and that is currently an image, then the target type might specify
-whether the contents of the image should be sent in XY format or
-Z format.
-.IP
-The target type can also be used to control the class of
-contents transmitted; for example, 
-asking for the ``looks'' (fonts, line
-spacing, indentation, and so forth) of a paragraph selection, rather than the
-text of the paragraph.
-The target type can also be used for other
-purposes.
-The protocol does not constrain the semantics.
-.KE
-.LP
-.KS
-\fBServer\fP
-.IN "Server" "" "@DEF@"
-.IP
-The server, which is also referred to as the X server, 
-provides the basic windowing mechanism.  
-It handles IPC connections from clients, 
-multiplexes graphics requests onto the screens, 
-and demultiplexes input back to the appropriate clients.
-.KE
-.LP
-.KS
-\fBServer grabbing\fP
-.IN "Server" "grabbing" "@DEF@"
-.IP
-The server can be grabbed by a single client for exclusive use.  
-This prevents processing of any requests from other client connections until
-the grab is completed.
-This is typically only a transient state for such things as rubber-banding,
-pop-up menus, or executing requests indivisibly.
-.KE
-.LP
-.KS
-\fBShift sequence\fP
-.IN "Shift sequence" "" "@DEF@"
-.IP
-ISO2022 defines control characters and escape sequences 
-which temporarily (single shift) or permanently (locking shift) cause a
-different character set to be in effect (``invoking'' a character set).
-.KE
-.LP
-.KS
-\fBSibling\fP
-.IN "Sibling" "" "@DEF@"
-.IP
-Children of the same parent window are known as sibling windows.
-.KE
-.LP
-.KS
-\fBStacking order\fP
-.IN "Stacking order" "" "@DEF@"
-.IP
-Sibling windows, similar to sheets of paper on a desk,
-can stack on top of each other.  
-Windows above both obscure and occlude lower windows.  
-The relationship between sibling windows is known as the stacking order.
-.KE
-.LP
-.KS
-\fBState-dependent encoding\fP
-.IN "State-dependent encoding" "" "@DEF@"
-.IP
-An encoding in which an invocation of a charset can apply to multiple
-characters in sequence.
-A state-dependent encoding begins in an ``initial state'' 
-and enters other ``shift states'' when specific ``shift sequences'' 
-are encountered in the byte sequence.
-In ISO2022 terms,
-this means use of locking shifts, not single shifts.
-.KE
-.LP
-.KS
-\fBState-independent encoding\fP
-.IN "State-independent encoding" "" "@DEF@"
-.IP
-Any encoding in which the invocations of the charsets are fixed,
-or span only a single character.
-In ISO2022 terms,
-this means use of at most single shifts, not locking shifts.
-.KE
-.LP
-.KS
-\fBStaticColor\fP
-.IN "StaticColor" "" "@DEF@"
-.IP
-.PN StaticColor 
-can be viewed as a degenerate case of 
-.PN PseudoColor
-in which the RGB values are predefined and read-only.
-.KE
-.LP
-.KS
-\fBStaticGray\fP
-.IN "StaticGray" "" "@DEF@"
-.IP
-.PN StaticGray 
-can be viewed as a degenerate case of 
-.PN GrayScale
-in which the gray values are predefined and read-only.
-The values are typically linear or near-linear increasing ramps.
-.KE
-.LP
-.KS
-\fBStatus\fP
-.IN "Status" "" "@DEF@"
-.IP
-Many Xlib functions return a success status.
-If the function does not succeed,
-however, its arguments are not disturbed.
-.KE
-.LP
-.KS
-\fBStipple\fP
-.IN "Stipple" "" "@DEF@"
-.IP
-A stipple pattern is a bitmap that is used to tile a region to serve
-as an additional clip mask for a fill operation with the foreground
-color.
-.KE
-.KS
-.LP
-.KS
-\fBSTRING encoding\fP
-.IN "STRING encoding" "" "@DEF@"
-.IP
-Latin-1, plus tab and newline.
-.KE
-.LP
-\fBString Equivalence\fP
-.IN "String Equivalence" "" "@DEF@"
-.IP
-Two ISO Latin-1 STRING8 values are considered equal if they are the same
-length and if corresponding bytes are either equal or are equivalent as
-follows:  decimal values 65 to 90 inclusive (characters ``A'' to ``Z'') are
-pairwise equivalent to decimal values 97 to 122 inclusive
-(characters ``a'' to ``z''), decimal values 192 to 214 inclusive
-(characters ``A grave'' to ``O diaeresis'') are pairwise equivalent to decimal
-values 224 to 246 inclusive (characters ``a grave'' to ``o diaeresis''),
-and decimal values 216 to 222 inclusive (characters ``O oblique'' to ``THORN'')
-are pairwise equivalent to decimal values 246 to 254 inclusive
-(characters ``o oblique'' to ``thorn'').
-.KE
-.LP
-.KS
-\fBTile\fP
-.IN "Tile" "" "@DEF@"
-.IP
-A pixmap can be replicated in two dimensions to tile a region.  
-The pixmap itself is also known as a tile.
-.KE
-.LP
-.KS
-\fBTimestamp\fP
-.IN "Timestamp" "" "@DEF@"
-.IP
-A timestamp is a time value expressed in milliseconds. 
-It is typically the time since the last server reset.
-Timestamp values wrap around (after about 49.7 days).
-The server, given its current time is represented by timestamp T, 
-always interprets timestamps from clients by treating half 
-of the timestamp space as being earlier in time than T 
-and half of the timestamp space as being later in time than T.
-One timestamp value, represented by the constant 
-.PN CurrentTime ,
-is never generated by the server. 
-This value is reserved for use in requests to represent the current server time.
-.KE
-.LP
-.KS
-\fBTrueColor\fP
-.IN "TrueColor" "" "@DEF@"
-.IP
-.PN TrueColor
-can be viewed as a degenerate case of 
-.PN DirectColor
-in which the subfields in the pixel value directly encode the corresponding RGB
-values.
-That is, the colormap has predefined read-only RGB values.
-The values are typically linear or near-linear increasing ramps.
-.KE
-.LP
-.KS
-\fBType\fP
-.IN "Type" "" "@DEF@"
-.IP
-A type is an arbitrary atom used to identify the interpretation of property 
-data.  
-Types are completely uninterpreted by the server. 
-They are solely for the benefit of clients.
-X predefines type atoms for many frequently used types,
-and clients also can define new types.
-.KE
-.LP
-.KS
-\fBViewable\fP
-.IN "Viewable" "" "@DEF@"
-.IP
-A window is viewable if it and all of its ancestors are mapped.  
-This does not imply that any portion of the window is actually visible.
-Graphics requests can be performed on a window when it is not
-viewable, but output will not be retained unless the server is maintaining
-backing store. 
-.KE
-.LP
-.KS
-\fBVisible\fP
-.IN "Visible" "" "@DEF@"
-.IP
-A region of a window is visible if someone looking at the screen can
-actually see it; that is, the window is viewable and the region is not occluded
-by any other window.
-.KE
-.LP
-.KS
-\fBWhitespace\fP
-.IN "Whitespace" "" "@DEF@"
-.IP
-Any spacing character.
-On implementations that conform to the ANSI C library,
-whitespace is any character for which
-.PN isspace
-returns true.
-.KE
-.LP
-.KS
-\fBWindow gravity\fP
-.IN "Window" "gravity" "@DEF@"
-.IP
-When windows are resized, 
-subwindows may be repositioned automatically relative to some position in the 
-window.
-This attraction of a subwindow to some part of its parent is known 
-as window gravity.
-.KE
-.LP
-.KS
-\fBWindow manager\fP
-.IN "Window" "manager" "@DEF@"
-.IP
-Manipulation of windows on the screen and much of the user interface
-(policy) is typically provided by a window manager client.
-.KE
-.LP
-.KS
-\fBX Portable Character Set\fP
-.IN "X Portable Character Set" "" "@DEF@"
-.IP
-A basic set of 97 characters which are assumed to exist in all
-locales supported by Xlib.  This set contains the following characters:
-.IP
-.Ds 0
-.EQ
-delim DD
-.EN
-a..z A..Z 0..9
-!"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~
-<space>, <tab>, and <newline>
-.EQ
-delim %%
-.EN
-.De
-.IP
-This is the left/lower half (also called the G0 set)
-of the graphic character set of ISO8859-1 plus <space>, <tab>, and <newline>.
-It is also the set of graphic characters in 7-bit ASCII plus the same
-three control characters.
-The actual encoding of these characters on the host is system dependent;
-see the Host Portable Character Encoding.
-.KE
-.LP
-.KS
-\fBXLFD\fP
-.IN "XLFD" "" "@DEF@"
-.IP
-The X Logical Font Description Conventions that define a standard syntax 
-for structured font names.
-.KE
-.LP
-.KS
-\fBXY format\fP
-.IN "XY format" "" "@DEF@"
-.IP
-The data for a pixmap is said to be in XY format if it is organized as
-a set of bitmaps representing individual bit planes with the planes
-appearing from most-significant to least-significant bit order.
-.KE
-.LP
-.KS
-\fBZ format\fP
-.IN "Z format" "" "@DEF@"
-.IP
-The data for a pixmap is said to be in Z format if it is organized as
-a set of pixel values in scanline order.
-.KE
-.LP
-\fBReferences\fP
-.LP
-ANSI Programming Language - C: ANSI X3.159-1989, December 14, 1989.
-.LP
-Draft Proposed Multibyte Extension of ANSI C, Draft 1.1, November 30,
-1989, SC22/C WG/SWG IPSJ/ITSCJ Japan.
-.LP
-ISO2022: Information processing - ISO 7-bit and 8-bit coded character
-sets - Code extension techniques.
-.LP
-ISO8859-1: Information processing - 8-bit single-byte coded graphic
-character sets - Part 1: Latin alphabet No. 1.
-.LP
-POSIX: Information Technology - Portable Operating System Interface (POSIX) -
-Part 1: System Application Program Interface (API) [C Language],
-ISO/IEC 9945-1.
-.LP
-Text of ISO/IEC/DIS 9541-1, Information Processing - Font Information
-Interchange - Part 1:  Architecture.
-.LP
-X/Open Portability Guide, Issue 3, December 1988 (XPG3), X/Open Company,
-Ltd, Prentice-Hall, Inc. 1989. ISBN 0-13-685835-8.
-(See especially Volume 3:  XSI Supplementary Definitions.)
-.bp
diff --git a/libX11/specs/libX11/glossary.xml b/libX11/specs/libX11/glossary.xml
new file mode 100644
index 000000000..eda236875
--- /dev/null
+++ b/libX11/specs/libX11/glossary.xml
@@ -0,0 +1,1901 @@
+<glossary id='glossary'>

+<title>Glossary</title>

+<glossentry>

+  <glossterm>Access control list</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Access control list</primary></indexterm>

+    <para>

+X maintains a list of hosts from which client programs can be run.  

+By default, 

+only programs on the local host and hosts specified in an initial list read

+by the server can use the display.

+This access control list can be changed by clients on the local host.  

+Some server implementations can also implement other authorization mechanisms

+in addition to or in place of this mechanism.

+The action of this mechanism can be conditional based on the authorization 

+protocol name and data received by the server at connection setup. 

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Active grab</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Active grab</primary></indexterm>

+    <para>

+A grab is active when the pointer or keyboard is actually owned by the 

+single grabbing client.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Ancestors</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Ancestors</primary></indexterm>

+    <para>

+If W is an inferior of A, then A is an ancestor of W.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Atom</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Atom</primary></indexterm>

+    <para>

+An atom is a unique ID corresponding to a string name.

+Atoms are used to identify properties, types, and selections.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Background</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Background</primary></indexterm>

+    <para>

+An

+<function>InputOutput</function>

+window can have a background, which is defined as a pixmap.

+When regions of the window have their contents lost 

+or invalidated,

+the server automatically tiles those regions with the background.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Backing store</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Backing store</primary></indexterm>

+    <para>

+When a server maintains the contents of a window, 

+the pixels saved off-screen are known as a backing store.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Base font name</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Base font name</primary></indexterm>

+    <para>

+A font name used to select a family of fonts whose members may be encoded 

+in various charsets.

+The

+<function>CharSetRegistry</function>

+and 

+<function>CharSetEncoding</function>

+fields of an <acronym>XLFD</acronym> name identify the charset of the font.

+A base font name may be a full <acronym>XLFD</acronym> name, with all fourteen '-' delimiters, 

+or an abbreviated <acronym>XLFD</acronym> name containing only the first 12 fields of an <acronym>XLFD</acronym> name,

+up to but not including 

+<function>CharSetRegistry</function>,

+with or without the thirteenth '-', or a non-<acronym>XLFD</acronym> name.

+Any <acronym>XLFD</acronym> fields may contain wild cards.

+</para>

+    <para>

+When creating an 

+<function>XFontSet</function>,

+Xlib accepts from the client a list of one or more base font names 

+which select one or more font families.

+They are combined with charset names obtained from the encoding of the locale

+to load the fonts required to render text.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Bit gravity</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Bit</primary><secondary>gravity</secondary></indexterm>

+    <para>

+When a window is resized, 

+the contents of the window are not necessarily discarded.  

+It is possible to request that the server relocate the previous contents 

+to some region of the window (though no guarantees are made).

+This attraction of window contents for some location of

+a window is known as bit gravity.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Bit plane</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Bit</primary><secondary>plane</secondary></indexterm>

+    <para>

+When a pixmap or window is thought of as a stack of bitmaps,

+each bitmap is called a bit plane or plane.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Bitmap</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Bitmap</primary></indexterm>

+    <para>

+A bitmap is a pixmap of depth one.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Border</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Border</primary></indexterm>

+    <para>

+An

+<function>InputOutput</function>

+window can have a border of equal thickness on all four sides of the window.

+The contents of the border are defined by a pixmap,

+and the server automatically maintains the contents of the border.

+Exposure events are never generated for border regions.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Button grabbing</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Button</primary><secondary>grabbing</secondary></indexterm>

+    <para>

+Buttons on the pointer can be passively grabbed by a client.

+When the button is pressed, 

+the pointer is then actively grabbed by the client.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Byte order</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Byte</primary><secondary>order</secondary></indexterm>

+    <para>

+For image (pixmap/bitmap) data, 

+the server defines the byte order,

+and clients with different native byte ordering must swap bytes as

+necessary.  

+For all other parts of the protocol, 

+the client defines the byte order,

+and the server swaps bytes as necessary.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Character</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Character</primary></indexterm>

+    <para>

+A member of a set of elements used for the organization,

+control, or representation of text (ISO2022, as adapted by XPG3).

+Note that in ISO2022 terms, a character is not bound to a coded value 

+until it is identified as part of a coded character set.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Character glyph</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Character glyph</primary></indexterm>

+    <para>

+The abstract graphical symbol for a character.

+Character glyphs may or may not map one-to-one to font glyphs,

+and may be context-dependent, varying with the adjacent characters.

+Multiple characters may map to a single character glyph.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Character set</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Character set</primary></indexterm>

+    <para>

+A collection of characters.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Charset</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Charset</primary></indexterm>

+    <para>

+An encoding with a uniform, state-independent mapping from characters 

+to codepoints.

+A coded character set.

+</para>

+    <para>

+For display in X,

+there can be a direct mapping from a charset to one font,

+if the width of all characters in the charset is either one or two bytes.

+A text string encoded in an encoding such as Shift-JIS cannot be passed

+directly to the X server, because the text imaging requests accept only

+single-width charsets (either 8 or 16 bits).

+Charsets which meet these restrictions can serve as ``font charsets''.

+Font charsets strictly speaking map font indices to font glyphs,

+not characters to character glyphs.

+</para>

+    <para>

+Note that a single font charset is sometimes used as the encoding of a locale,

+for example, ISO8859-1.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Children</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Children</primary></indexterm>

+    <para>

+The children of a window are its first-level subwindows.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Class</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Class</primary></indexterm>

+    <para>

+Windows can be of different classes or types.

+See the entries for

+<function>InputOnly</function>

+and

+<function>InputOutput</function>

+windows for further information about valid window types.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Client</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Client</primary></indexterm>

+    <para>

+An application program connects to the window system server by some

+interprocess communication (<acronym>IPC</acronym>) path, such as a <acronym>TCP</acronym> connection or a

+shared memory buffer.  

+This program is referred to as a client of the window system server.  

+More precisely, 

+the client is the <acronym>IPC</acronym> path itself. 

+A program with multiple paths open to the server is viewed as

+multiple clients by the protocol.  

+Resource lifetimes are controlled by

+connection lifetimes, not by program lifetimes.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Clipping region</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Clipping region</primary></indexterm>

+    <para>

+In a graphics context, 

+a bitmap or list of rectangles can be specified

+to restrict output to a particular region of the window.  

+The image defined by the bitmap or rectangles is called a clipping region.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Coded character</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Coded character</primary></indexterm>

+    <para>

+A character bound to a codepoint.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Coded character set</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Coded character set</primary></indexterm>

+    <para>

+A set of unambiguous rules that establishes a character set 

+and the one-to-one relationship between each character of the set 

+and its bit representation.

+(ISO2022, as adapted by XPG3)

+A definition of a one-to-one mapping of a set of characters to a set of

+codepoints.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Codepoint</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Codepoint</primary></indexterm>

+    <para>

+The coded representation of a single character in a coded character set.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Colormap</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Colormap</primary></indexterm>

+    <para>

+A colormap consists of a set of entries defining color values.

+The colormap associated with a window is used to display the contents of

+the window; each pixel value indexes the colormap to produce an <acronym>RGB</acronym> value

+that drives the guns of a monitor.

+Depending on hardware limitations, 

+one or more colormaps can be installed at one time so

+that windows associated with those maps display with true colors.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Connection</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Connection</primary></indexterm>

+    <para>

+The <acronym>IPC</acronym> path between the server and client program is known as a connection.

+A client program typically (but not necessarily) has one

+connection to the server over which requests and events are sent.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Containment</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Containment</primary></indexterm>

+    <para>

+A window contains the pointer if the window is viewable and the

+hotspot of the cursor is within a visible region of the window or a

+visible region of one of its inferiors.  

+The border of the window is included as part of the window for containment.  

+The pointer is in a window if the window contains the pointer

+but no inferior contains the pointer.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Coordinate system</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Coordinate system</primary></indexterm>

+    <para>

+The coordinate system has X horizontal and Y vertical, 

+with the origin [0, 0] at the upper left.  

+Coordinates are integral and coincide with pixel centers.

+Each window and pixmap has its own coordinate system.  

+For a window, 

+the origin is inside the border at the inside upper-left corner.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Cursor</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Cursor</primary></indexterm>

+    <para>

+A cursor is the visible shape of the pointer on a screen.  

+It consists of a hotspot, a source bitmap, a shape bitmap, 

+and a pair of colors.  

+The cursor defined for a window controls the visible

+appearance when the pointer is in that window.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Depth</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Depth</primary></indexterm>

+    <para>

+The depth of a window or pixmap is the number of bits per pixel it has.

+The depth of a graphics context is the depth of the drawables it can be

+used in conjunction with graphics output.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Device</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Device</primary></indexterm>

+    <para>

+Keyboards, mice, tablets, track-balls, button boxes, and so on are all

+collectively known as input devices.

+Pointers can have one or more buttons 

+(the most common number is three).

+The core protocol only deals with two devices: the keyboard 

+and the pointer.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>DirectColor</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>DirectColor</primary></indexterm>

+    <para>

+<function>DirectColor</function>

+is a class of colormap in which a pixel value is decomposed into three

+separate subfields for indexing.

+The first subfield indexes an array to produce red intensity values. 

+The second subfield indexes a second array to produce blue intensity values.

+The third subfield indexes a third array to produce green intensity values.

+The <acronym>RGB</acronym> (red, green, and blue) values in the colormap entry can be 

+changed dynamically.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Display</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Display</primary></indexterm>

+    <para>

+A server, together with its screens and input devices, is called a display.

+The Xlib

+<function>Display</function>

+<indexterm><primary>Display</primary><secondary>structure</secondary></indexterm>

+structure contains all information about the particular display and its screens

+as well as the state that Xlib needs to communicate with the display over a

+particular connection.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Drawable</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Drawable</primary></indexterm>

+    <para>

+Both windows and pixmaps can be used as sources and destinations 

+in graphics operations.  

+These windows and pixmaps are collectively known as drawables.

+However, an 

+<function>InputOnly </function>

+window cannot be used as a source or destination in a

+graphics operation.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Encoding</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Encoding</primary></indexterm>

+    <para>

+A set of unambiguous rules that establishes a character set 

+and a relationship between the characters and their representations.

+The character set does not have to be fixed to a finite pre-defined set of

+characters.

+The representations do not have to be of uniform length.

+Examples are an ISO2022 graphic set, a state-independent 

+or state-dependent combination of graphic sets, possibly including control

+sets, and the X Compound Text encoding.

+</para>

+    <para>

+In X, encodings are identified by a string

+which appears as: the

+<function>CharSetRegistry</function>

+and

+<function>CharSetEncoding</function>

+components of an <acronym>XLFD</acronym>

+name; the name of a charset of the locale for which a font could not be

+found; or an atom which identifies the encoding of a text property or

+which names an encoding for a text selection target type.

+Encoding names should be composed of characters from the X Portable 

+Character Set.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Escapement</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Escapement</primary></indexterm>

+    <para>

+The escapement of a string is the distance in pixels in the

+primary draw direction from the drawing origin to the origin of the next

+character (that is, the one following the given string) to be drawn.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Event</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Event</primary></indexterm>

+    <para>

+Clients are informed of information asynchronously by means of events.

+These events can be either asynchronously generated from devices or

+generated as side effects of client requests.  

+Events are grouped into types. 

+The server never sends an event to a client unless the

+client has specifically asked to be informed of that type of event.

+However, clients can force events to be sent to other clients.  

+Events are typically reported relative to a window.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Event mask</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Event</primary><secondary>mask</secondary></indexterm>

+    <para>

+Events are requested relative to a window.  

+The set of event types a client requests relative to a window is described 

+by using an event mask.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Event propagation</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Event</primary><secondary>propagation</secondary></indexterm>

+    <para>

+Device-related events propagate from the source window to ancestor

+windows until some client has expressed interest in handling that type

+of event or until the event is discarded explicitly.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Event source</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Event</primary><secondary>source</secondary></indexterm>

+    <para>

+The deepest viewable window that the pointer is in is called

+the source of a device-related event.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Event synchronization</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Event</primary><secondary>synchronization</secondary></indexterm>

+    <para>

+There are certain race conditions possible when demultiplexing device

+events to clients (in particular, deciding where pointer and keyboard

+events should be sent when in the middle of window management

+operations).  

+The event synchronization mechanism allows synchronous processing of 

+device events.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Exposure event</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Event</primary><secondary>Exposure</secondary></indexterm>

+    <para>

+Servers do not guarantee to preserve the contents of windows when

+windows are obscured or reconfigured.  

+Exposure events are sent to clients to inform them when contents of regions

+of windows have been lost.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Extension</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Extension</primary></indexterm>

+    <para>

+Named extensions to the core protocol can be defined to extend the system.  

+Extensions to output requests, resources, and event types are all possible

+and expected.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Font</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Font</primary></indexterm>

+    <para>

+A font is an array of glyphs (typically characters).  

+The protocol does no translation or interpretation of character sets.  

+The client simply indicates values used to index the glyph array.  

+A font contains additional metric information to determine interglyph 

+and interline spacing.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Font glyph</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Font glyph</primary></indexterm>

+    <para>

+The abstract graphical symbol for an index into a font.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Frozen events</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Frozen events</primary></indexterm>

+    <para>

+Clients can freeze event processing during keyboard and pointer grabs.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>GC</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>GC</primary></indexterm>

+    <para>

+GC is an abbreviation for graphics context.

+See <function>Graphics context</function>.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Glyph</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Glyph</primary></indexterm>

+    <para>

+An identified abstract graphical symbol independent of any actual image.

+(ISO/IEC/DIS 9541-1)

+An abstract visual representation of a graphic character,

+not bound to a codepoint.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Glyph image</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Glyph image</primary></indexterm>

+    <para>

+An image of a glyph, as obtained from a glyph representation displayed 

+on a presentation surface.

+(ISO/IEC/DIS 9541-1)

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Grab</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Grab</primary></indexterm>

+    <para>

+Keyboard keys, the keyboard, pointer buttons, the pointer, 

+and the server can be grabbed for exclusive use by a client.  

+In general, 

+these facilities are not intended to be used by normal applications

+but are intended for various input and window managers to implement various

+styles of user interfaces.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Graphics context</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Graphics context</primary></indexterm>

+    <para>

+Various information for graphics output is stored in a graphics

+context (GC), such as foreground pixel, background

+pixel, line width, clipping region, and so on.

+A graphics context can only

+be used with drawables that have the same root and the same depth as

+the graphics context. 

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Gravity</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Gravity</primary></indexterm>

+    <para>

+The contents of windows and windows themselves have a gravity,

+which determines how the contents move when a window is resized.

+See <function>Bit gravity</function> and <function>Window gravity</function>.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>GrayScale</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>GrayScale</primary></indexterm>

+    <para>

+<function>GrayScale </function>

+can be viewed as a degenerate case of 

+<function>PseudoColor</function>,

+in which the red, green, and blue values in any given colormap entry 

+are equal and thus, produce shades of gray.

+The gray values can be changed dynamically.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Host Portable Character Encoding</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Host Portable Character Encoding</primary></indexterm>

+    <para>

+The encoding of the X Portable Character Set on the host.

+The encoding itself is not defined by this standard,

+but the encoding must be the same in all locales supported by Xlib on the host.

+If a string is said to be in the Host Portable Character Encoding,

+then it only contains characters from the X Portable Character Set,

+in the host encoding.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Hotspot</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Hotspot</primary></indexterm>

+    <para>

+A cursor has an associated hotspot, which defines the point in the

+cursor corresponding to the coordinates reported for the pointer.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Identifier</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Identifier</primary></indexterm>

+    <para>

+An identifier is a unique value associated with a resource

+that clients use to name that resource.  

+The identifier can be used over any connection to name the resource.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Inferiors</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Inferiors</primary></indexterm>

+    <para>

+The inferiors of a window are all of the subwindows nested below it:

+the children, the children's children, and so on.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Input focus</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Input</primary><secondary>focus</secondary></indexterm>

+    <para>

+The input focus is usually a window defining the scope for processing

+of keyboard input.

+If a generated keyboard event usually would be reported to this window 

+or one of its inferiors,

+the event is reported as usual.

+Otherwise, the event is reported with respect to the focus window.

+The input focus also can be set such that all keyboard events are discarded

+and such that the focus window is dynamically taken to be the root window

+of whatever screen the pointer is on at each keyboard event.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Input manager</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Input</primary><secondary>manager</secondary></indexterm>

+    <para>

+Control over keyboard input is typically provided by an input manager 

+client, which usually is part of a window manager.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>InputOnly window</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Window</primary><secondary>InputOnly</secondary></indexterm>

+    <para>

+An

+<function>InputOnly</function>

+window is a window that cannot be used for graphics requests.  

+<function>InputOnly </function>

+windows are invisible and are used to control such things as cursors,

+input event generation, and grabbing.

+<function>InputOnly </function>

+windows cannot have 

+<function>InputOutput </function>

+windows as inferiors.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>InputOutput window</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Window</primary><secondary>InputOutput</secondary></indexterm>

+    <para>

+An

+<function>InputOutput</function>

+window is the normal kind of window that is used for both input and output.

+<function>InputOutput </function>

+windows can have both 

+<function>InputOutput </function>

+and 

+<function>InputOnly </function>

+windows as inferiors.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Internationalization</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Internationalization</primary></indexterm>

+    <para>

+The process of making software adaptable to the requirements

+of different native languages, local customs, and character string encodings.

+Making a computer program adaptable to different locales 

+without program source modifications or recompilation.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>ISO2022</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>ISO2022</primary></indexterm>

+    <para>

+ISO standard for code extension techniques for 7-bit and 8-bit coded 

+character sets.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Key grabbing</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Key</primary><secondary>grabbing</secondary></indexterm>

+    <para>

+Keys on the keyboard can be passively grabbed by a client.  

+When the key is pressed, 

+the keyboard is then actively grabbed by the client.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Keyboard grabbing</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Keyboard</primary><secondary>grabbing</secondary></indexterm>

+    <para>

+A client can actively grab control of the keyboard, and key events

+will be sent to that client rather than the client the events would

+normally have been sent to.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Keysym</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Keysym</primary></indexterm>

+    <para>

+An encoding of a symbol on a keycap on a keyboard.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Latin-1</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Latin-1</primary></indexterm>

+    <para>

+The coded character set defined by the ISO8859-1 standard.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Latin Portable Character Encoding</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Latin Portable Character Encoding</primary></indexterm>

+    <para>

+The encoding of the X Portable Character Set using the Latin-1 codepoints

+plus ASCII control characters.

+If a string is said to be in the Latin Portable Character Encoding,

+then it only contains characters from the X Portable Character Set,

+not all of Latin-1.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Locale</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Locale</primary></indexterm>

+    <para>

+The international environment of a computer program defining the ``localized''

+behavior of that program at run-time.

+This information can be established from one or more sets of localization data.

+ANSI C defines locale-specific processing by C system library calls.

+See ANSI C and the X/Open Portability Guide specifications for more details.

+In this specification, on implementations that conform to the ANSI C library,

+the ``current locale'' is the current setting of the LC_CTYPE

+<function>setlocale</function>

+category.

+Associated with each locale is a text encoding.  When text is processed

+in the context of a locale, the text must be in the encoding of the locale.

+The current locale affects Xlib in its:

+<!-- .RS -->

+</para>

+    <para>

+Encoding and processing of input method text

+</para>

+    <para>

+Encoding of resource files and values

+</para>

+    <para>

+Encoding and imaging of text strings

+</para>

+    <para>

+Encoding and decoding for inter-client text communication

+<!-- .RE -->

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Locale name</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Locale name</primary></indexterm>

+    <para>

+The identifier used to select the desired locale for the host C library 

+and X library functions.

+On ANSI C library compliant systems,

+the locale argument to the

+<function>setlocale</function>

+function.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Localization</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Localization</primary></indexterm>

+    <para>

+The process of establishing information within a computer system specific 

+to the operation of particular native languages, local customs 

+and coded character sets.

+(XPG3)

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Mapped</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Mapped window</primary></indexterm>

+    <para>

+A window is said to be mapped if a map call has been performed on it.

+Unmapped windows and their inferiors are never viewable or visible.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Modifier keys</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Modifier keys</primary></indexterm>

+    <para>

+Shift, Control, Meta, Super, Hyper, Alt, Compose, Apple, CapsLock,

+ShiftLock, and similar keys are called modifier keys.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Monochrome</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Monochrome</primary></indexterm>

+    <para>

+Monochrome is a special case of 

+<function>StaticGray</function>

+in which there are only two colormap entries.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Multibyte</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Multibyte</primary></indexterm>

+    <para>

+A character whose codepoint is stored in more than one byte;

+any encoding which can contain multibyte characters;

+text in a multibyte encoding.

+The ``char *'' null-terminated string datatype in ANSI C.

+Note that references in this document to multibyte strings

+imply only that the strings <emphasis remap='I'>may</emphasis> contain multibyte characters.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Obscure</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Obscure</primary></indexterm>

+    <para>

+A window is obscured if some other window obscures it.

+A window can be partially obscured and so still have visible regions.

+Window A obscures window B if both are viewable 

+<function>InputOutput </function>

+windows, if A is higher in the global stacking order, 

+and if the rectangle defined by the outside

+edges of A intersects the rectangle defined by the outside edges of B.

+Note the distinction between obscures and occludes.

+Also note that window borders are included in the calculation.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Occlude</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Occlude</primary></indexterm>

+    <para>

+A window is occluded if some other window occludes it.

+Window A occludes window B if both are mapped, 

+if A is higher in the global stacking order, 

+and if the rectangle defined by the outside edges of A intersects the rectangle defined 

+by the outside edges of B.  

+Note the distinction between occludes and obscures.

+Also note that window borders are included in the calculation

+and that

+<function>InputOnly</function>

+windows never obscure other windows but can occlude other windows.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Padding</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Padding</primary></indexterm>

+    <para>

+Some padding bytes are inserted in the data stream to maintain

+alignment of the protocol requests on natural boundaries.  

+This increases ease of portability to some machine architectures.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Parent window</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Window</primary><secondary>parent</secondary></indexterm>

+    <para>

+If C is a child of P, then P is the parent of C.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Passive grab</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Passive grab</primary></indexterm>

+    <para>

+Grabbing a key or button is a passive grab.  

+The grab activates when the key or button is actually pressed.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Pixel value</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Pixel value</primary></indexterm>

+    <para>

+A pixel is an N-bit value,

+where N is the number of bit planes used in a particular window or pixmap

+(that is, is the depth of the window or pixmap).  

+A pixel in a window indexes a colormap to derive an actual color to be 

+displayed.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Pixmap</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Pixmap</primary></indexterm>

+<!-- .EQ -->

+<!-- .EN -->

+    <para>

+A pixmap is a three-dimensional array of bits.  

+A pixmap is normally thought of as a two-dimensional array of pixels, 

+where each pixel can be a value from 0 to %2 sup N %\-1, 

+and where N is the depth (z axis) of the pixmap.  

+A pixmap can also be thought of as a stack of N bitmaps.

+A pixmap can only be used on the screen that it was created in.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Plane</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Plane</primary></indexterm>

+    <para>

+When a pixmap or window is thought of as a stack of bitmaps, each

+bitmap is called a plane or bit plane.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Plane mask</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Plane</primary><secondary>mask</secondary></indexterm>

+    <para>

+Graphics operations can be restricted to only affect a subset of bit

+planes of a destination.  

+A plane mask is a bit mask describing which planes are to be modified.

+The plane mask is stored in a graphics context.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Pointer</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Pointer</primary></indexterm>

+    <para>

+The pointer is the pointing device currently attached to the cursor

+and tracked on the screens.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Pointer grabbing</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Pointer</primary><secondary>grabbing</secondary></indexterm>

+    <para>

+A client can actively grab control of the pointer. 

+Then button and motion events will be sent to that client 

+rather than the client the events would normally have been sent to.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Pointing device</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Pointing device</primary></indexterm>

+    <para>

+A pointing device is typically a mouse, tablet, or some other

+device with effective dimensional motion.  

+The core protocol defines only one visible cursor,

+which tracks whatever pointing device is attached as the pointer.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm><acronym>POSIX</acronym></glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary><acronym>POSIX</acronym></primary></indexterm>

+    <para>

+Portable Operating System Interface, ISO/IEC 9945-1 (IEEE Std 1003.1).

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm><acronym>POSIX</acronym> Portable Filename Character Set</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary><acronym>POSIX</acronym> Portable Filename Character Set</primary></indexterm>

+    <para>

+The set of 65 characters which can be used in naming files on a <acronym>POSIX</acronym>-compliant

+host that are correctly processed in all locales.

+The set is:

+</para>

+    <para>

+<!-- .Ds 0 -->

+a..z A..Z 0..9 ._-

+<!-- .De -->

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Property</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Property</primary></indexterm>

+    <para>

+Windows can have associated properties that consist of a name, a type,

+a data format, and some data. 

+The protocol places no interpretation on properties. 

+They are intended as a general-purpose naming mechanism for clients.  

+For example, clients might use properties to share information such as resize

+hints, program names, and icon formats with a window manager.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Property list</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Property list</primary></indexterm>

+    <para>

+The property list of a window is the list of properties that have

+been defined for the window.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>PseudoColor</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>PseudoColor</primary></indexterm>

+    <para>

+<function>PseudoColor</function>

+is a class of colormap in which a pixel value indexes the colormap entry to

+produce an independent <acronym>RGB</acronym> value;

+that is, the colormap is viewed as an array of triples (<acronym>RGB</acronym> values).

+The <acronym>RGB</acronym> values can be changed dynamically.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Rectangle</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Rectangle</primary></indexterm>

+    <para>

+A rectangle specified by [x,y,w,h] has an infinitely thin

+outline path with corners at [x,y], [x+w,y], [x+w,y+h], and [x, y+h].

+When a rectangle is filled,

+the lower-right edges are not drawn.

+For example,

+if w=h=0,

+nothing would be drawn.

+For w=h=1,

+a single pixel would be drawn.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Redirecting control</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Redirecting control</primary></indexterm>

+    <para>

+Window managers (or client programs) may enforce window layout

+policy in various ways.  

+When a client attempts to change the size or position of a window, 

+the operation may be redirected to a specified client

+rather than the operation actually being performed.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Reply</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Reply</primary></indexterm>

+    <para>

+Information requested by a client program using the X protocol 

+is sent back to the client with a reply.

+Both events and replies are multiplexed on the same connection.  

+Most requests do not generate replies,

+but some requests generate multiple replies.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Request</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Request</primary></indexterm>

+    <para>

+A command to the server is called a request.

+It is a single block of data sent over a connection.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Resource</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Resource</primary></indexterm>

+    <para>

+Windows, pixmaps, cursors, fonts, graphics contexts, and colormaps are

+known as resources.  

+They all have unique identifiers associated with them for naming purposes.  

+The lifetime of a resource usually is bounded by the lifetime of the 

+connection over which the resource was created.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm><acronym>RGB</acronym> values</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary><acronym>RGB</acronym> values</primary></indexterm>

+    <para>

+<acronym>RGB</acronym> values are the red, green, and blue intensity values that are used

+to define a color.

+These values are always represented as 16-bit, unsigned numbers, with 0

+the minimum intensity and 65535 the maximum intensity.

+The X server scales these values to match the display hardware.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Root</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Root</primary></indexterm>

+    <para>

+The root of a pixmap or graphics context is the same as the root 

+of whatever drawable was used when the pixmap or GC was created.  

+The root of a window is the root window under which the window was created.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Root window</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Window</primary><secondary>root</secondary></indexterm>

+    <para>

+Each screen has a root window covering it.

+The root window cannot be reconfigured or unmapped, 

+but otherwise it acts as a full-fledged window.

+A root window has no parent.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Save set</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Save set</primary></indexterm>

+    <para>

+The save set of a client is a list of other clients' windows that,

+if they are inferiors of one of the client's windows at connection

+close, should not be destroyed and that should be remapped 

+if currently unmapped.

+Save sets are typically used by window managers to avoid

+lost windows if the manager should terminate abnormally.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Scanline</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Scanline</primary></indexterm>

+    <para>

+A scanline is a list of pixel or bit values viewed as a horizontal

+row (all values having the same y coordinate) of an image, with the

+values ordered by increasing the x coordinate.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Scanline order</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Scanline</primary><secondary>order</secondary></indexterm>

+    <para>

+An image represented in scanline order contains scanlines ordered by

+increasing the y coordinate.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Screen</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Screen</primary></indexterm>

+    <para>

+A server can provide several independent screens, 

+which typically have physically independent monitors.  

+This would be the expected configuration when there is only a single keyboard 

+and pointer shared among the screens.

+A 

+<function>Screen </function>

+<indexterm><primary>Screen</primary><secondary>structure</secondary></indexterm>

+structure contains the information about that screen

+and is linked to the 

+<function>Display</function>

+<indexterm><primary>Display</primary><secondary>structure</secondary></indexterm>

+structure.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Selection</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Selection</primary></indexterm>

+    <para>

+A selection can be thought of as an indirect property with dynamic

+type.

+That is, rather than having the property stored in the X server,

+it is maintained by some client (the owner).

+A selection is global and is thought of as belonging to the user 

+and being maintained by clients, 

+rather than being private to a particular window subhierarchy

+or a particular set of clients.

+When a client asks for the contents of

+a selection, it specifies a selection target type,

+which can be used to control the transmitted representation of the contents.

+For example, if the selection is ``the last thing the user clicked on,''

+and that is currently an image, then the target type might specify

+whether the contents of the image should be sent in XY format or

+Z format.

+</para>

+    <para>

+The target type can also be used to control the class of

+contents transmitted; for example, 

+asking for the ``looks'' (fonts, line

+spacing, indentation, and so forth) of a paragraph selection, rather than the

+text of the paragraph.

+The target type can also be used for other

+purposes.

+The protocol does not constrain the semantics.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Server</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Server</primary></indexterm>

+    <para>

+The server, which is also referred to as the X server, 

+provides the basic windowing mechanism.  

+It handles <acronym>IPC</acronym> connections from clients, 

+multiplexes graphics requests onto the screens, 

+and demultiplexes input back to the appropriate clients.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Server grabbing</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Server</primary><secondary>grabbing</secondary></indexterm>

+    <para>

+The server can be grabbed by a single client for exclusive use.  

+This prevents processing of any requests from other client connections until

+the grab is completed.

+This is typically only a transient state for such things as rubber-banding,

+pop-up menus, or executing requests indivisibly.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Shift sequence</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Shift sequence</primary></indexterm>

+    <para>

+ISO2022 defines control characters and escape sequences 

+which temporarily (single shift) or permanently (locking shift) cause a

+different character set to be in effect (``invoking'' a character set).

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Sibling</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Sibling</primary></indexterm>

+    <para>

+Children of the same parent window are known as sibling windows.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Stacking order</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Stacking order</primary></indexterm>

+    <para>

+Sibling windows, similar to sheets of paper on a desk,

+can stack on top of each other.  

+Windows above both obscure and occlude lower windows.  

+The relationship between sibling windows is known as the stacking order.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>State-dependent encoding</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>State-dependent encoding</primary></indexterm>

+    <para>

+An encoding in which an invocation of a charset can apply to multiple

+characters in sequence.

+A state-dependent encoding begins in an ``initial state'' 

+and enters other ``shift states'' when specific ``shift sequences'' 

+are encountered in the byte sequence.

+In ISO2022 terms,

+this means use of locking shifts, not single shifts.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>State-independent encoding</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>State-independent encoding</primary></indexterm>

+    <para>

+Any encoding in which the invocations of the charsets are fixed,

+or span only a single character.

+In ISO2022 terms,

+this means use of at most single shifts, not locking shifts.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>StaticColor</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>StaticColor</primary></indexterm>

+    <para>

+<function>StaticColor </function>

+can be viewed as a degenerate case of 

+<function>PseudoColor</function>

+in which the <acronym>RGB</acronym> values are predefined and read-only.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>StaticGray</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>StaticGray</primary></indexterm>

+    <para>

+<function>StaticGray </function>

+can be viewed as a degenerate case of 

+<function>GrayScale</function>

+in which the gray values are predefined and read-only.

+The values are typically linear or near-linear increasing ramps.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Status</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Status</primary></indexterm>

+    <para>

+Many Xlib functions return a success status.

+If the function does not succeed,

+however, its arguments are not disturbed.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Stipple</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Stipple</primary></indexterm>

+    <para>

+A stipple pattern is a bitmap that is used to tile a region to serve

+as an additional clip mask for a fill operation with the foreground

+color.

+    </para>

+  </glossdef>

+</glossentry>

+<!-- .KE -->

+<glossentry>

+  <glossterm>STRING encoding</glossterm>

+  <glossdef>

+    <para>

+Latin-1, plus tab and newline.

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>String Equivalence</glossterm>

+  <glossdef>

+    <para>

+<indexterm significance="preferred"><primary>String Equivalence</primary></indexterm>

+Two ISO Latin-1 STRING8 values are considered equal if they are the same

+length and if corresponding bytes are either equal or are equivalent as

+follows:  decimal values 65 to 90 inclusive (characters ``A'' to ``Z'') are

+pairwise equivalent to decimal values 97 to 122 inclusive

+(characters ``a'' to ``z''), decimal values 192 to 214 inclusive

+(characters ``A grave'' to ``O diaeresis'') are pairwise equivalent to decimal

+values 224 to 246 inclusive (characters ``a grave'' to ``o diaeresis''),

+and decimal values 216 to 222 inclusive (characters ``O oblique'' to ``THORN'')

+are pairwise equivalent to decimal values 246 to 254 inclusive

+(characters ``o oblique'' to ``thorn'').

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Tile</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Tile</primary></indexterm>

+    <para>

+A pixmap can be replicated in two dimensions to tile a region.  

+The pixmap itself is also known as a tile.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Timestamp</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Timestamp</primary></indexterm>

+    <para>

+A timestamp is a time value expressed in milliseconds. 

+It is typically the time since the last server reset.

+Timestamp values wrap around (after about 49.7 days).

+The server, given its current time is represented by timestamp T, 

+always interprets timestamps from clients by treating half 

+of the timestamp space as being earlier in time than T 

+and half of the timestamp space as being later in time than T.

+One timestamp value, represented by the constant 

+<function>CurrentTime</function>,

+is never generated by the server. 

+This value is reserved for use in requests to represent the current server time.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>TrueColor</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>TrueColor</primary></indexterm>

+    <para>

+<function>TrueColor</function>

+can be viewed as a degenerate case of 

+<function>DirectColor</function>

+in which the subfields in the pixel value directly encode the corresponding <acronym>RGB</acronym>

+values.

+That is, the colormap has predefined read-only <acronym>RGB</acronym> values.

+The values are typically linear or near-linear increasing ramps.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Type</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Type</primary></indexterm>

+    <para>

+A type is an arbitrary atom used to identify the interpretation of property 

+data.  

+Types are completely uninterpreted by the server. 

+They are solely for the benefit of clients.

+X predefines type atoms for many frequently used types,

+and clients also can define new types.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Viewable</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Viewable</primary></indexterm>

+    <para>

+A window is viewable if it and all of its ancestors are mapped.  

+This does not imply that any portion of the window is actually visible.

+Graphics requests can be performed on a window when it is not

+viewable, but output will not be retained unless the server is maintaining

+backing store. 

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Visible</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Visible</primary></indexterm>

+    <para>

+A region of a window is visible if someone looking at the screen can

+actually see it; that is, the window is viewable and the region is not occluded

+by any other window.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Whitespace</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Whitespace</primary></indexterm>

+    <para>

+Any spacing character.

+On implementations that conform to the ANSI C library,

+whitespace is any character for which

+<function>isspace</function>

+returns true.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Window gravity</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Window</primary><secondary>gravity</secondary></indexterm>

+    <para>

+When windows are resized, 

+subwindows may be repositioned automatically relative to some position in the 

+window.

+This attraction of a subwindow to some part of its parent is known 

+as window gravity.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Window manager</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Window</primary><secondary>manager</secondary></indexterm>

+    <para>

+Manipulation of windows on the screen and much of the user interface

+(policy) is typically provided by a window manager client.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>X Portable Character Set</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>X Portable Character Set</primary></indexterm>

+    <para>

+A basic set of 97 characters which are assumed to exist in all

+locales supported by Xlib.  This set contains the following characters:

+    </para>

+    <para>

+<!-- .Ds 0 -->

+<!-- .EQ -->

+<!-- .EN -->

+    </para>

+    <para>

+a..z A..Z 0..9

+!"#$%&amp;'()*+,-./:;&lt;=&gt;?@[\\]^_`{|}~

+&lt;space&gt;, &lt;tab&gt;, and &lt;newline&gt;

+<!-- .EQ -->

+<!-- .EN -->

+<!-- .De -->

+    </para>

+    <para>

+This is the left/lower half (also called the G0 set)

+of the graphic character set of ISO8859-1 plus &lt;space&gt;, &lt;tab&gt;, and &lt;newline&gt;.

+It is also the set of graphic characters in 7-bit ASCII plus the same

+three control characters.

+The actual encoding of these characters on the host is system dependent;

+see the Host Portable Character Encoding.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm><acronym>XLFD</acronym></glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary><acronym>XLFD</acronym></primary></indexterm>

+    <para>

+The X Logical Font Description Conventions that define a standard syntax 

+for structured font names.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>XY format</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>XY format</primary></indexterm>

+    <para>

+The data for a pixmap is said to be in XY format if it is organized as

+a set of bitmaps representing individual bit planes with the planes

+appearing from most-significant to least-significant bit order.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+<glossentry>

+  <glossterm>Z format</glossterm>

+  <glossdef>

+<indexterm significance="preferred"><primary>Z format</primary></indexterm>

+    <para>

+The data for a pixmap is said to be in Z format if it is organized as

+a set of pixel values in scanline order.

+<!-- .KE -->

+    </para>

+  </glossdef>

+</glossentry>

+

+<bibliography>

+<title>References</title>

+<biblioentry>

+<title>Draft Proposed Multibyte Extension of ANSI C, Draft 1.1</title>

+<date>November 30, 1989 SC22/C WG/SWG IPSJ/ITSCJ Japan</date>

+</biblioentry>

+

+<biblioentry>

+<title>

+ISO2022: Information processing - ISO 7-bit and 8-bit coded character

+sets - Code extension techniques.

+</title>

+</biblioentry>

+

+<biblioentry>

+<title>

+ISO8859-1: Information processing - 8-bit single-byte coded graphic

+character sets - Part 1: Latin alphabet No. 1.

+</title>

+</biblioentry>

+

+<biblioentry>

+<title>

+<acronym>POSIX</acronym>: Information Technology - Portable Operating System Interface (<acronym>POSIX</acronym>) -

+Part 1: System Application Program Interface (API) [C Language],

+ISO/IEC 9945-1.

+</title>

+</biblioentry>

+

+<biblioentry>

+<title>

+Text of ISO/IEC/DIS 9541-1, Information Processing - Font Information

+Interchange - Part 1:  Architecture.

+</title>

+</biblioentry>

+

+<biblioentry>

+<title>

+X/Open Portability Guide, Issue 3, December 1988 (XPG3), X/Open Company,

+Ltd, Prentice-Hall, Inc. 1989. ISBN 0-13-685835-8.

+(See especially Volume 3:  XSI Supplementary Definitions.)

+</title>

+</biblioentry>

+</bibliography>

+

+</glossary>

diff --git a/libX11/specs/libX11/indexmacros.t b/libX11/specs/libX11/indexmacros.t
deleted file mode 100644
index ec5d4fa6d..000000000
--- a/libX11/specs/libX11/indexmacros.t
+++ /dev/null
@@ -1,3 +0,0 @@
-.eh '\fBXlib \- C Library\fP''\fB\*(xV\fP'

-.oh '\fBXlib \- C Library\fP''\fB\*(xV\fP'

-.so index.pageno

diff --git a/libX11/specs/libX11/libX11.ms b/libX11/specs/libX11/libX11.ms
deleted file mode 100644
index b44425623..000000000
--- a/libX11/specs/libX11/libX11.ms
+++ /dev/null
@@ -1,24 +0,0 @@
-.so abstract.t
-.so credits.t
-.so CH01
-.so CH02
-.so CH03
-.so CH04
-.so CH05
-.so CH06
-.so CH07
-.so CH08
-.so CH09
-.so CH10
-.so CH11
-.so CH12
-.so CH13
-.so CH14
-.so CH15
-.so CH16
-.so AppA
-.so AppB
-.so AppC
-.so AppD
-.so glossary
-.so postproc
diff --git a/libX11/specs/libX11/libX11.xml b/libX11/specs/libX11/libX11.xml
new file mode 100644
index 000000000..40a1d95ec
--- /dev/null
+++ b/libX11/specs/libX11/libX11.xml
@@ -0,0 +1,147 @@
+<?xml version="1.0" encoding="UTF-8" ?>

+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"

+                   "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">

+

+<book id="libX11">

+

+<bookinfo>

+   <title>Xlib - C Language X Interface</title>

+   <subtitle>X Window System Standard</subtitle>

+   <releaseinfo>X Version 11, Release 7</releaseinfo>

+   <authorgroup>

+      <author>

+         <firstname>James</firstname><surname>Gettys</surname>

+         <affiliation>

+	   <orgname>Digital Equipment Corporation</orgname>

+	   <orgdiv>Cambridge Research Laboratory</orgdiv>

+	 </affiliation>

+      </author>

+      <author>

+         <firstname>Robert</firstname><othername role='mi'>W.</othername> <surname>Scheifler</surname>

+         <affiliation>

+	   <orgname>Massachusetts Institute of Technology</orgname>

+	   <orgdiv>Laboratory for Computer Science</orgdiv>

+	 </affiliation>

+      </author>

+      <othercredit>

+         <firstname>Chuck</firstname><surname>Adams</surname>

+         <affiliation><orgname>Tektronix, Inc.</orgname></affiliation>

+      </othercredit>

+      <othercredit>

+         <firstname>Vania</firstname><surname>Joloboff</surname>

+         <affiliation><orgname>Open Software Foundation</orgname></affiliation>

+      </othercredit>

+      <othercredit>

+         <firstname>Hideki</firstname><surname>Hiura</surname>

+         <affiliation><orgname>Sun Microsystems, Inc.</orgname></affiliation>

+      </othercredit>

+      <othercredit>

+         <firstname>Bill</firstname><surname>McMahon</surname>

+         <affiliation><orgname>Hewlett-Packard Company</orgname></affiliation>

+      </othercredit>

+      <othercredit>

+         <firstname>Ron</firstname><surname>Newman</surname>

+         <affiliation><orgname>Massachusetts Institute of Technology</orgname></affiliation>

+      </othercredit>

+      <othercredit>

+         <firstname>Al</firstname><surname>Tabayoyon</surname>

+         <affiliation><orgname>Tektronix, Inc.</orgname></affiliation>

+      </othercredit>

+      <othercredit>

+         <firstname>Glenn</firstname><surname>Widener</surname>

+         <affiliation><orgname>Tektronix, Inc.</orgname></affiliation>

+      </othercredit>

+      <othercredit>

+         <firstname>Shigeru</firstname><surname>Yamada</surname>

+         <affiliation><orgname>Fujitsu OSSI</orgname></affiliation>

+      </othercredit>

+   </authorgroup>

+   <copyright><year>1985</year><year>1986</year><year>1987</year>

+     <year>1988</year><year>1989</year><year>1991</year><year>1994</year>

+     <year>1996</year><year>2002</year><holder>The Open Group</holder>

+   </copyright>

+   <copyright><year>1985</year><year>1986</year><year>1987</year>

+     <year>1988</year><year>1989</year><year>1991</year>

+     <holder>Digital Equipment Corporation</holder>

+   </copyright>

+

+   <affiliation><orgname>formerly MIT X Consortium</orgname></affiliation>

+   <productnumber>X Version 11, Release 7</productnumber>

+

+<legalnotice>

+

+<para>

+Permission is hereby granted, free of charge, to any person obtaining a copy 

+of this software and associated documentation files 

+(the &ldquo;Software&rdquo;), to deal in the Software without restriction, 

+including without limitation the rights to use, copy, modify, merge, publish, 

+distribute, sublicense, and/or sell copies of the Software, and to permit 

+persons to whom the Software is furnished to do so, subject to the following 

+conditions:

+</para>

+

+<para>

+The above copyright notice and this permission notice shall be included in all 

+copies or substantial portions of the Software.

+</para>

+

+<para>

+THE SOFTWARE IS PROVIDED &ldquo;AS IS&rdquo;, WITHOUT WARRANTY OF ANY KIND, 

+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 

+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN 

+NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 

+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 

+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 

+THE SOFTWARE.

+</para>

+

+<para>

+Except as contained in this notice, the name of The Open Group shall not 

+be used in advertising or otherwise to promote the sale, use or other dealings 

+in this Software without prior written authorization from The Open Group.

+</para>

+

+<para>

+Permission to use, copy, modify and distribute this documentation for any

+purpose and without fee is hereby granted, provided that the above copyright

+notice appears in all copies and that both that copyright notice and this

+permission notice appear in supporting documentation, and that the names of

+Digital and Tetronix not be used in in advertising or publicity pertaining

+to distribution of the software without specific, written prior permission.

+Digital and Tetronix make no representations about the suitability of the

+software described herein for any purpose.

+It is provided "as is" without express or implied warranty.

+</para>

+

+

+<para>TekHVC is a trademark of Tektronix, Inc.</para>

+

+</legalnotice>

+</bookinfo>

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="credits.xml"/>

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="CH01.xml"/>

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="CH02.xml"/>

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="CH03.xml"/>

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="CH04.xml"/>

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="CH05.xml"/>

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="CH06.xml"/>

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="CH07.xml"/>

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="CH08.xml"/>

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="CH09.xml"/>

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="CH10.xml"/>

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="CH11.xml"/>

+<!--   -->

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="CH12.xml"/>

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="CH13.xml"/>

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="CH14.xml"/>

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="CH15.xml"/>

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="CH16.xml"/>

+<!--  runs out of mem at here -->

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="AppA.xml"/>

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="AppB.xml"/>

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="AppC.xml"/>

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="AppD.xml"/>

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="glossary.xml"/>

+<index />

+</book>

+

diff --git a/libX11/specs/libX11/postproc b/libX11/specs/libX11/postproc
deleted file mode 100644
index 0f45a5a00..000000000
--- a/libX11/specs/libX11/postproc
+++ /dev/null
@@ -1,17 +0,0 @@
-.\"
-.\" print Table of Contents
-.if e \& \" Force blank page to begin TOC on an odd (right-hand) page.
-.EH ''''
-.OH ''''
-.bp
-\& \" Want old footings if blank page was forced.
-.EF ''''
-.OF ''''
-.XS
-Index
-.XE
-.EQ
-delim $$
-.EN
-.tm .pn \n%
-.PX
diff --git a/libX11/specs/xmlrules.in b/libX11/specs/xmlrules.in
new file mode 100644
index 000000000..50865b5b8
--- /dev/null
+++ b/libX11/specs/xmlrules.in
@@ -0,0 +1,59 @@
+#

+# Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.

+#

+# Permission is hereby granted, free of charge, to any person obtaining a

+# copy of this software and associated documentation files (the "Software"),

+# to deal in the Software without restriction, including without limitation

+# the rights to use, copy, modify, merge, publish, distribute, sublicense,

+# and/or sell copies of the Software, and to permit persons to whom the

+# Software is furnished to do so, subject to the following conditions:

+#

+# The above copyright notice and this permission notice (including the next

+# paragraph) shall be included in all copies or substantial portions of the

+# Software.

+#

+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL

+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING

+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER

+# DEALINGS IN THE SOFTWARE.

+#

+

+if HAVE_XMLTO

+spec_DATA = $(doc_sources:.xml=.html)

+

+if HAVE_FOP

+spec_DATA += $(doc_sources:.xml=.ps) $(doc_sources:.xml=.pdf)

+endif

+

+if HAVE_XMLTO_TEXT

+spec_DATA += $(doc_sources:.xml=.txt)

+endif

+

+if HAVE_STYLESHEETS

+XMLTO_FLAGS = -m $(XSL_STYLESHEET)

+

+spec_DATA += xorg.css

+xorg.css: $(STYLESHEET_SRCDIR)/xorg.css

+	$(AM_V_GEN)cp -pf $(STYLESHEET_SRCDIR)/xorg.css $@

+endif

+

+CLEANFILES = $(spec_DATA)

+

+SUFFIXES = .xml .ps .pdf .txt .html

+

+.xml.txt:

+	$(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) txt $<

+

+.xml.html:

+	$(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) xhtml-nochunks $<

+

+.xml.pdf:

+	$(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop pdf $<

+

+.xml.ps:

+	$(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop ps $<

+

+endif HAVE_XMLTO