Oc Abstract Hardware Ltd Poly/ML for X Reference Manual Mike Crawley cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 1 Copyright (c) Abstract Hardware Limited 1991, 1994 Copyright (c) 1987 Digital Equipment Corporation Copyright (c) 1987 Massachusetts Institute of Technology All Rights Reserved. Permission to use, copy, modify, and distribute this signature and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notices appear in all copies and that both the copyright notices and this permission notice appear in supporting documentation, and that the names of Digital, MIT and AHL not be used in advertising or publicity pertaining to distribution of the signature and its documentation without specific, written prior permission. Digital, MIT and AHL disclaim all warranties with regard to this signature and its documentation, including all implied warranties of merchantability and fitness, in no event shall Digital, MIT or AHL be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this signature and its documentation. The X Window System is a Trademark of MIT. 2 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 Contents 1 Introduction 11 1.1 The ML interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . 11 1.2 Naming and calling conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 1.3 Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . 12 1.4 X and the Garbage Collector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 1.5 X and Persistent Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * 13 2 Function Reference 15 2.1 Colours, Pixels and RGB values . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 2.1.1 And, Or, Xor, Not, >>, << . . . . . . . . . . . . . . . . . . . . . . . . . . 15 2.1.2 BlackPixel, WhitePixel . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * 15 2.1.3 Pixel, RGB, XColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * 16 2.1.4 XAllocColor, XAllocColorCells, XAllocColorPlanes, XAllocNamedColor, XFreeColors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . 17 2.1.5 XLookupColor, XQueryColor, XQueryColors . . . . . . . . . . . . . . . . 19 2.1.6 XParseColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . 20 2.1.7 XStoreColor, XStoreColors, XStoreNamedColor . . . . . . . . . . . . . . 21 2.2 Colormaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . . 22 2.2.1 DefaultColormap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * 22 2.2.2 DefaultDepth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . 22 2.2.3 DisplayCells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . 23 2.2.4 VisualClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . 23 2.2.5 XCreateColormap, XCopyColormapAndFree, XFreeColormap, XSetWin- dowColormap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . 24 3 4 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 2.2.6 XInstallColormap, XUninstallColormap, XListInstalledColormaps . . . . 25 2.2.7 XSetRGBColormaps, XGetRGBColormaps . . . . . . . . . . . . . . . . . 26 2.3 Cursors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . . . @ 2.3.1 XCreateFontCursor, XCreatePixmapCursor, XCreateGlyphCursor . . . . 28 2.3.2 XDefineCursor, XUndefineCursor, NoCursor . . . . . . . . . . . . . . . . 29 2.3.3 XRecolorCursor, XFreeCursor . . . . . . . . . . . . . . . . . . . . . . . . 30 2.4 Display Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . 31 2.4.1 AllPlanes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . . 31 2.4.2 BitmapBitOrder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. 31 2.4.3 BitmapPad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . 31 2.4.4 BitmapUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . 32 2.4.5 ByteOrder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . 32 2.4.6 CellsOfScreen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . 32 2.4.7 ColormapExists, CursorExists, DrawableExists, FontExists, GCExists, Vi- sualExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . . 33 2.4.8 ColormapID, CursorID, DrawableID, FontID, GCID, VisualID, Same- Drawable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . . 33 2.4.9 DefaultVisual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . 34 2.4.10 DisplayConnected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * 34 2.4.11 DisplayHeight, DisplayHeightMM, DisplayWidth, DisplayWidthMM . . . 34 2.4.12 DisplayPlanes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . 35 2.4.13 DisplayString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . 35 2.4.14 DoesBackingStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * 35 2.4.15 DoesSaveUnders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. 36 2.4.16 EventMaskOfScreen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * 36 2.4.17 MinCmapsOfScreen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * 36 2.4.18 MaxCmapsOfScreen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * 37 2.4.19 NoColormap, NoCursor, NoDrawable, NoFont, NoVisual, ParentRelative, CopyFromParentDrawable, CopyFromParentVisual, PointerWindow, In- putFocus, PointerRoot . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * 37 2.4.20 ProtocolRevision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . 37 2.4.21 ProtocolVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . 38 cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 5 2.4.22 RootWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . 38 2.4.23 ServerVendor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . 38 2.4.24 VendorRelease . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . 39 2.4.25 XQueryBestCursor, XQueryBestSize, XQueryBestStipple, XQueryBest- Tile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . . . @ 2.5 Drawing Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . 40 2.5.1 XClearArea, XClearWindow . . . . . . . . . . . . . . . . . . . . . . . . . 40 2.5.2 XCopyArea, XCopyPlane . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 2.5.3 XDrawArc, XDrawArcs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 2.5.4 XDrawImageString, XDrawImageString16 . . . . . . . . . . . . . . . . . 44 2.5.5 XDrawLine, XDrawLines, XDrawSegments . . . . . . . . . . . . . . . . . 45 2.5.6 XDrawPoint, XDrawPoints . . . . . . . . . . . . . . . . . . . . . . . . . . 46 2.5.7 XDrawRectangle, XDrawRectangles . . . . . . . . . . . . . . . . . . . . . 46 2.5.8 XDrawString, XDrawString16 . . . . . . . . . . . . . . . . . . . . . . . . 47 2.5.9 XDrawText, XDrawText16 . . . . . . . . . . . . . . . . . . . . . . . . . . 48 2.5.10 XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFillRectangles . . . 49 2.6 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . . 51 2.6.1 Range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . . 51 2.6.2 XWindows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . 51 2.7 Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . 52 2.7.1 IsCursorKey, IsFunctionKey, IsKeypadKey, IsMiscFunctionKey, IsModi- fierKey, IsPFKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. 52 2.7.2 ShiftDown, ControlDown . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 2.7.3 XLookupString, NoSymbol . . . . . . . . . . . . . . . . . . . . . . . . . . 53 2.7.4 XSelectInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . 54 2.7.5 XSetHandler, NullHandler . . . . . . . . . . . . . . . . . . . . . . . . . . 55 2.7.6 XSetInputFocus, XGetInputFocus . . . . . . . . . . . . . . . . . . . . . . 56 2.7.7 XSync, XFlush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . 57 2.7.8 XSyncronise, XSynchronize . . . . . . . . . . . . . . . . . . . . . . . . . . 58 2.7.9 XTranslateCoordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * 58 2.8 Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . . . . @ 6 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 2.8.1 CharLBearing, CharRBearing, CharWidth, CharAscent, CharDescent, CharAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . 59 2.8.2 FSFont, FSDirection, FSMinChar, FSMaxChar, FSMinByte1, FS- MaxByte1, FSAllCharsExist, FSAllCharsExist, FSDefaultChar, FSMin- Bounds, FSMaxBounds, PSPerChar, FSPerChar, FSAscent, FSDescent, FSAscent, FSDescent, FSMinWidth, FSMaxWidth, FSMinHeight, FS- MaxHeight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . 59 2.8.3 XListFonts, XListFontsWithInfo . . . . . . . . . . . . . . . . . . . . . . . 60 2.8.4 XLoadFont, XLoadQueryFont, XQueryFont, XFreeFont, XUnloadFont . 61 2.8.5 XSetFontPath, XGetFontPath . . . . . . . . . . . . . . . . . . . . . . . . 64 2.8.6 XTextExtents, XTextExtents16 . . . . . . . . . . . . . . . . . . . . . . . 64 2.8.7 XTextWidth, XTextWidth16 . . . . . . . . . . . . . . . . . . . . . . . . . 65 2.9 Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . . 66 2.9.1 AddPoint, SubtractPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 2.9.2 Inside, Overlap, Within, LeftOf, RightOf, AboveOf, BelowOf, Horizon- tallyAbutting, VerticallyAbutting . . . . . . . . . . . . . . . . . . . . . . 66 2.9.3 Intersection, Union, Section . . . . . . . . . . . . . . . . . . . . . . . . . * *67 2.9.4 Left, Right, Top, Bottom, Width, Height, TopLeft, TopRight, Bottom- Left, BottomRight, XRectangle, Area, Rect, DestructRect, DestructArea, empty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . . 67 2.9.5 MakeRect, SplitRect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * 68 2.9.6 NegativePoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . 69 2.9.7 OutsetRect, OffsetRect, IncludePoint . . . . . . . . . . . . . . . . . . . . 69 2.9.8 Reflect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . . . 7@ 2.9.9 XPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . . 70 2.10 GC - Graphics Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * 70 2.10.1 DefaultGC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . 70 2.10.2 XCreateGC, XChangeGC, XFreeGC . . . . . . . . . . . . . . . . . . . . . 71 2.10.3 XSetArcMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . 76 2.10.4 XSetBackground . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. 76 2.10.5 XSetClipMask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . 77 2.10.6 XSetClipOrigin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . 77 2.10.7 XSetClipRectangles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * 77 cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 7 2.10.8 XSetColours . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . 78 2.10.9 XSetDashes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . 79 2.10.10 XSetFillRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . 79 2.10.11 XSetFillStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . 80 2.10.12 XSetFont . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . . 80 2.10.13 XSetForeground . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. 81 2.10.14 XSetFunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . 81 2.10.15 XSetGraphicsExposures . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 2.10.16 XSetLineAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * 82 2.10.17 XSetPlaneMask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. 82 2.10.18 XSetState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . 83 2.10.19 XSetStipple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . 83 2.10.20 XSetSubwindowMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 2.10.21 XSetTile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . . 84 2.10.22 XSetTSOrigin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . 85 2.11 Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . . . @ 2.11.1 ImageByteOrder, ImageDepth, ImageSize . . . . . . . . . . . . . . . . . . 85 2.11.2 VisualRedMask, VisualGreenMask, VisualBlueMask . . . . . . . . . . . . 86 2.11.3 XCreateImage, XGetPixel, XPutPixel, XSubImage, XAddPixel . . . . . 86 2.11.4 XPutImage, XGetImage, XGetSubImage . . . . . . . . . . . . . . . . . . 88 2.12 Properties and Selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * 90 2.12.1 XDeleteProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. 90 2.12.2 XInternAtom, XGetAtomName . . . . . . . . . . . . . . . . . . . . . . . 90 2.12.3 XSetProperty, XGetTextProperty . . . . . . . . . . . . . . . . . . . . . . 91 2.12.4 XSetSelectionOwner, XGetSelectionOwner, XConvertSelection, XSendSe- lectionNotify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . 92 2.13 Screen Saver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . . 94 2.13.1 XSetScreenSaver, XForceScreenSaver, XActivateScreenSaver, XResetScreenSaver, XGetScreenSaver . . . . . . . . . . . . . . . . . . . . 94 2.14 Tiles, Stipples, Bitmaps and Pixmaps . . . . . . . . . . . . . . . . . . . . . . . . 95 2.14.1 XCreatePixmap, XFreePixmap . . . . . . . . . . . . . . . . . . . . . . . . 95 8 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 2.14.2 XReadBitmapFile, XWriteBitmapFile, XCreatePixmapFromBitmapData, XCreateBitmapFromData . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 2.15 User Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . 98 2.15.1 XAutoRepeatOn, XAutoRepeatOff, XBell, XQueryKeymap . . . . . . . 98 2.15.2 XGetDefault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . 98 2.16 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . . 99 2.16.1 XCreateWindow, XCreateSimpleWindow . . . . . . . . . . . . . . . . . . 99 2.16.2 XDestroyWindow, XDestroySubwindows . . . . . . . . . . . . . . . . . . 101 2.16.3 XGetGeometry, XGetWindowAttributes . . . . . . . . . . . . . . . . . . 101 2.16.4 XGetWindowRoot, XGetWindowPosition, XGetWindowSize, XGetWin- dowBorderWidth, XGetWindowDepth, XGetWindowParent, XGetWin- dowChildren . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . 104 2.16.5 XChangeWindowAttributes, XSetWindowBackground, XSetWindow- BackgroundPixmap, XSetWindowBorder, XSetWindowBorderPixmap . . 104 2.16.6 XConfigureWindow, XMoveWindow, XResizeWindow, XMoveResizeWin- dow, XSetWindowBorderWidth . . . . . . . . . . . . . . . . . . . . . . . 106 2.16.7 XMapWindow, XMapRaised, XMapSubwindows . . . . . . . . . . . . . . 108 2.16.8 XQueryPointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . 109 2.16.9 XQueryTree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . 110 2.16.10 XRaiseWindow, XLowerWindow, XCirculateSubwindows, XCirculateSub- windowsDown, XCirculateSubwindowsUp, XRestackWindows . . . . . . 110 2.16.11 XReparentWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1* *12 2.16.12 XUnmapWindow, XUnmapSubwindows . . . . . . . . . . . . . . . . . . . 113 2.17 Window Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. 113 2.17.1 XSetIconSizes, XGetIconSizes . . . . . . . . . . . . . . . . . . . . . . . . 113 2.17.2 XSetTransientForHint, XGetTransientForHint . . . . . . . . . . . . . . . 114 2.17.3 XSetWMClass, XGetWMClass . . . . . . . . . . . . . . . . . . . . . . . . 114 2.17.4 XSetWMClientMachine, XGetWMClientMachine . . . . . . . . . . . . . 115 2.17.5 XSetWMColormapWindows, XGetWMColormapWindows . . . . . . . . 116 2.17.6 XSetWMCommand, XGetWMCommand . . . . . . . . . . . . . . . . . . 116 2.17.7 XSetWMHints, XGetWMHints . . . . . . . . . . . . . . . . . . . . . . . . 117 2.17.8 XSetWMIconName, XGetWMIconName . . . . . . . . . . . . . . . . . . 118 cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 9 2.17.9 XSetWMName, XGetWMName . . . . . . . . . . . . . . . . . . . . . . . 119 2.17.10 XSetWMProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *119 2.17.11 XSetWMSizeHints, XGetWMSizeHints, XSetWMNormalHints, XGetWMNormalHints . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 2.17.12 XWMGeometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * 122 3 Event Reference 125 3.1 XEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . . . 125 3.2 ButtonPress, ButtonRelease, KeyPress, KeyRelease, MotionNotify . . . . . . . . 126 3.3 CirculateNotify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . 128 3.4 CirculateRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . 128 3.5 ColormapNotify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . 128 3.6 ConfigureNotify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . 129 3.7 ConfigureRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . 130 3.8 CreateNotify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . . 130 3.9 DeleteRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . 130 3.10 DestroyNotify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . 131 3.11 EnterNotify, LeaveNotify, NotifyMode, NotifyDetail . . . . . . . . . . . . . . . . 131 3.12 Expose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . . . 13@ 3.13 FocusIn, FocusOut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . 133 3.14 GraphicsExpose, NoExpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 3.15 GravityNotify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . 134 3.16 KeymapNotify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . 134 3.17 MapNotify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . . 135 3.18 MapRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . 135 3.19 Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . . . 135 3.20 ReparentNotify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . 135 3.21 ResizeRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . 136 3.22 SelectionClear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . . 136 3.23 SelectionNotify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . . 137 3.24 SelectionRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . 137 10 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 3.25 UnmapNotify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . 137 3.26 VisibilityNotify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . . 138 4 Protocol Error Messages 139 4.1 BadAccess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . . 139 4.2 BadAlloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . . 139 4.3 BadAtom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . . 139 4.4 BadColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . . 139 4.5 BadCursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . . 140 4.6 BadDrawable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . 140 4.7 BadFont . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . . 140 4.8 BadGC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . . 140 4.9 BadImplementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. 140 4.10 BadIDChoice, BadLength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 4.11 BadMatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * *. . . 141 4.12 BadPixmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . 142 4.13 BadRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . 142 4.14 BadValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .* * . . . 142 4.15 BadWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * * . . 142 Chapter 1 Introduction 1.1 The ML interface We have implemented an ML interface to Xlib, the industry standard C interface for X at the lowest level, and which is widely used as the basis for many toolkits. We provide all the major function groups, so that this interface can be used to implement fully functional complex applications. We also provide a set of geometric functions for handling points and rectangles, and a set of functions for performing logical operations on plane masks and pixel values. Xlib is now widely documented, with many good reference and programming manuals available. We provide our version of the Xlib reference manual with ML signatures and types, and a more functional style to the programming interface. We provide ML example programs to show the functionality of the ML interface to Xlib. These examples range from simple line drawing applications through to colour examples and a mini text editor showing how to program with selections. The full signatures of the structures are also provided so that modules may be written for separate compilation. Because of the great similarity between our interface and the original Xlib, experienced X pro- grammers can use the skills they have already developed with very few changes. 1.2 Naming and calling conventions We have kept to the Xlib naming conventions as closely as possible. This means that standard Xlib documentation can be used along with our reference manual. Types Drawable, Cursor Functions XDrawLines, XSetWindowColormap, XLoadQueryFont Constructors FillTiled, JoinMiter, AllowExposures Constants XA__PRIMARY, XA__STRING Labels borderWidth 11 12 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 Datatypes are used where possible so that arguments are strongly typed and pattern matching may be used for returned values, this is especially useful for pattern matching the different sub- types of events. Abstypes are only used for the X resource types which have no meaningful textual representation. The functions have been made more functional. Where an Xlib function modified its arguments, this has been changed so that the function returns new, modified copies of the arguments. Where values were passed in partially filled-in structures with OR-ed bit masks, now the programmer uses constructors to make the list of values. Similarly, return values of this type are now lists of constructed values. The majority of X applications use a single display and single screen. Typically, they connect to the display when initialising and then pass the display parameter into every Xlib call from then on. In release 1 we connect to the display when initialising and implicitly pass the display and screen parameters to all Xlib functions. This reduces the number of parameters that have to be supplied and simplifies the signature. Another way of looking at this is to say that we have already called XOpenDisplay for the user and have partially applied all the Xlib functions with that display. In subsequent releases every X resource value will have its display parameter implicitly built in, a display connection function will be provided, and the types of the other Xlib functions will be unchanged. 1.3 Event Handling We provide an alternative event handling scheme. In normal Xlib programs written in C the user calls XNextEvent and then has to work out which window the event is for. This soon gets unwieldy as the number of windows increases, and is very difficult to use when interfacing with toolkits of window functions. In many X toolkits each newly created window registers a function with an event handler, then events for that window are passed directly to the window function when the event reaches the head of the event queue. We implement a similar scheme. When a window is created it is initially unhandled. It can be used for drawing on, but it will not process any events. An ML function can then be registered for that window, and an initial value supplied. The registered function will transform the value to a new value every time an event arrives for that window. In other words, a functional state machine is set up for each window. We also implement strongly typed message passing between windows, and extra event types for decoding multi-click events such as double clicking, and for implementing millisecond-resolution timer events. In more detail, we have a single Poly/ML process that handles events arriving down the event queue. It reads each event in turn, finds the window, the window function and the window state, and applies the event and state to the function. This returns a new state, which replaces the original state. Because only one process handles the events, we guarantee that no other window function can run at the same time. Any messages 'sent' by this window function are queued up and processed when this event has finished, before the next event from the server. If the window function raises an exception, instead of returning a new state, then the current state is left unchanged, and the exception is reported at the terminal. In this way all events are handled in turn in a predictable order, and in the same way that C event handlers work. The Poly/ML top level shell process is still available for debugging and control. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 13 If a window has an operation that takes a long time to complete, then the programmer can use Poly/ML processes to do the computations 'in the background' and 'send' the result as a message to the window for display. However, the use of processes in this way is discouraged as they are not standard. If a window function loops, then all other windows will freeze. Since the Poly/ML top level shell is available the user can type ^C followed by 'f' to raise Interrupt in that window function. 1.4 X and the Garbage Collector The garbage collector in Poly/ML can detect when a value is no longer referenced, and can perform an action in this circumstance. This is already done with streams. If you create an instream or an outstream and forget to close it with close_in or close_out, then it would hang on to its Unix file descriptor for the rest of the session. File descriptors are considered a precious resource in Unix, you are only allowed to have a small number of files open at any one time, so the garbage collector detects out of scope streams and closes the associated file descriptor. In X there are several types of precious resources. These include Windows, GCs, Pixmaps, Fonts and Cursors. Functions are provided so that the user can explicitly reclaim the resources used by these types of object, but a similar problem occurs. If a resource is not explicitly reclaimed, and allowed to go out of scope then it can never be reclaimed by the user. The garbage collector steps in and automatically cleans up. The table below summarises the effect. Window close the window with XDestroyWindow GC free the GC with XFreeGC Pixmap free the Pixmap with XFreePixmap Font unload the Font with XUnloadFont Cursor free the Cursor with XFreeCursor XColor free the XColor with XFreeColors Colormap free the Colormap with XFreeColormap Xlib includes a function called XFree which is used to free the storage required by the return types of several of its functions. This is not required in the ML interface because the garbage collector performs this operation. 1.5 X and Persistent Store In Poly/ML, persistent store is used to carry all ML values across to the next ML session with no change, except for a couple of cases. If you have a stream open when you save your environment, and then you attempt to read or write that stream in the next session, then Poly/ML will raise the Io exception. 14 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 In X, many values such as Windows and Pixmaps are volatile, they can only be used in the session that created them. If you attempt to draw in a window that you have brought across from an earlier session then Poly/ML will raise an exception. To make things cleaner we provide the following functions on volatile objects. val DrawableExists: Drawable -> bool ; val GCExists: GC -> bool ; val FontExists: Font -> bool ; val CursorExists: Cursor -> bool ; val PixelExists: int -> bool ; and so on. These are useful for restarting applications. If an application loads fonts, generates some bitmaps, and creates some windows to work in, and then gets saved to persistent store, then when the next session is started the application can detect that its resources have evaporated and can recreate them only when needed. Chapter 2 Function Reference 2.1 Colours, Pixels and RGB values 2.1.1 And, Or, Xor, Not, >>, << Types: infix And Or Xor >> << val Not: int -> int val And: int * int -> int val Or: int * int -> int val Xor: int * int -> int val >> : int * int -> int val << : int * int -> int Description: These functions provide useful arithmetic operations on ints representing pixel values and plane masks, which, in X, are unsigned 32-bit quantities. The least significant bits of these quantities are on the right, and the most significant bits are on the left. And, Or and Xor perform bitwise boolean functions. Not performs bitwise negation, so Not 0 = 4294967295 . a >> b returns a shifted b bits to the right, where b is not negative. a << b returns a shifted b bits to the left, where b is not negative. If negative values, or values greater than 4294967295 are passed to these functions then exception Range is raised. 2.1.2 BlackPixel, WhitePixel Types: val BlackPixel: unit -> int val WhitePixel: unit -> int 15 16 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 Syntax: val black = BlackPixel() ; val white = WhitePixel() ; Description: The BlackPixel function returns the black pixel value for the screen. The WhitePixel function returns the white pixel value for the screen. 2.1.3 Pixel, RGB, XColor Types: val Pixel: XColor -> int val RGB: XColor -> (int * int * int) Syntax: val pixel = Pixel colour ; val (red,green,blue) = RGB colour ; Arguments: pixel Returns the pixel field of the XColor structure red Returns the red, green and blue components of the XColor structure as num- bers in the range 0..65535. Argument Type: datatype XColor = XColor of { doRed: bool, doGreen: bool, doBlue: bool, red: int, green: int, blue: int, pixel: int } Description: The red, green, and blue values are scaled between 0 and 65535. Full brightness in a colour is a value of 65535 independent of the number of bits actually used in the display hardware. Half brightness in a colour is a value of 32767, and off is 0. This representation gives uniform results for colour values across different screens. In some functions, the doRed, doGreen and doBlue fields control which of the red, green, and blue members are used. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 17 2.1.4 XAllocColor, XAllocColorCells, XAllocColorPlanes, XAllocNamedColor, XFreeColors Types: val XAllocColor: Colormap -> XColor -> XColor val XAllocNamedColor: Colormap -> string -> (XColor * XColor) val XFreeColors: Colormap -> int list -> int -> unit val XAllocColorCells: Colormap -> bool -> int -> int -> (int list * int list) val XAllocColorPlanes: Colormap -> bool -> int -> int -> int -> int -> (int list * int * int * int) Syntax: val real = XAllocColor cmap colour ; val (real,desired) = XAllocNamedColor cmap name ; XFreeColors cmap pixels planes ; val (masks,basePixels) = XAllocColorCells cmap contig nplanes ncolours ; val (basePixels, redMask, greenMask, blueMask) = XAllocColorPlanes cmap contig ncolours nreds ngreens nblues ; Arguments: name Specifies the colour name string (for example, red) whose colour defini- tion structure you want returned. cmap Specifies the colormap. contig Specifies a bool that indicates whether the planes must be contiguous. ncolours Specifies the number of pixel values that are to be returned. nplanes Specifies the number of plane masks that are to be returned. nreds Specifies the number of red planes. The value you pass must be nonneg- ative. ngreens Specifies the number of green planes. The value you pass must be non- negative. nblues Specifies the number of blue planes. The value you pass must be non- negative. pixels Specifies a list of pixel values. planes Specifies the planes you want to free. colour Specifies the values actually used in the colormap. desired Returns the exact RGB values. 18 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 real Returns the closest RGB values provided by the hardware. masks Returns the list of plane masks basePixels Returns the list of base pixels redMask Returns the red mask greenMask Returns the green mask blueMask Returns the blue mask Argument Type: datatype XColor = XColor of { doRed: bool, doGreen: bool, doBlue: bool, red: int, green: int, blue: int, pixel: int } Description: The XAllocColor function allocates a read-only colormap entry corresponding to the closest RGB values supported by the hardware. XAllocColor returns the pixel value of the colour closest to the specified RGB elements supported by the hardware and returns the RGB values actually used. The corresponding colormap cell is read-only. If XAllocColor fails then exception XWindows is raised with "XAllocColor failed" . Multiple clients that request the same effective RGB values 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. XAllocColor does not use or affect the flags in the XColor structure. The XAllocNamedColor function looks up the named colour with respect to the screen that is associated with the specified colormap. It returns both the exact database definition and the closest colour supported by the screen. The allocated colour cell is read-only. You should use the ISO Latin-1 encoding; uppercase and lowercase do not matter. If XAllocNamedColor fails then exception XWindows is raised with "XAllocNamedColor failed" . The XAllocColorCells function allocates read/write colour cells. The number of colours must be positive and the number of planes nonnegative, otherwise exception Range is raised or a BadValue error results. If ncolours and nplanes are requested, then ncolours pixels and nplanes 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, ncolours * 2 ^ nplanes distinct pixels can be produced. All of these are allocated writable by the request. For GrayScale or PseudoColor, each mask has exactly one bit set to 1. For DirectColor, each has exactly three bits set to 1. If contig is true and if all masks are ORed together, a single contiguous set of bits set to 1 will be formed for GrayScale or PseudoColor and three contiguous sets of bits set to 1 (one within each pixel subfield) for DirectColor. The RGB values of the allocated entries are undefined. If XAllocColorCells fails then exception XWindows is raised with "XAllocColorCells failed" . The XAllocColorPlanes function allocates read/write colour cells. The specified ncolours must be positive; and nreds, ngreens, and nblues must be nonnegative, other- wise exception Range is raised or a BadValue error results. If ncolours colours, nreds reds, ngreens greens, and nblues blues are requested, ncolours pixels are returned; and the masks have nreds, ngreens, and nblues bits set to 1, respectively. If contig is true, each cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 19 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 DirectColor, each mask will lie within the corresponding pixel subfield. By ORing together subsets of masks with each pixel value, ncolours * 2 ^ (nreds+ngreens+nblues) distinct pixel values can be pro- duced. All of these are allocated by the request. However, in the colormap, there are only ncolours * 2 ^ nreds independent red entries, ncolours * 2 ^ ngreens independent green entries, and ncolours * 2 ^ nblues independent blue entries. This is true even for PseudoColor. When the colormap entry of a pixel value is changed (using XStoreCol- ors, XStoreColor, or XStoreNamedColor), the pixel is decomposed according to the masks, and the corresponding independent entries are updated. If XAllocColorPlanes fails then exception XWindows is raised with "XAllocColorPlanes failed" . The XFreeColors function frees the cells represented by pixels whose values are in the pixels list. 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 XAllocColor, XAllocNamedColor, XAllocColorCells, and XAllocColorPlanes). Note that freeing an individual pixel obtained from 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. 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 BadValue error results. If a specified pixel is not allocated by the client (that is, is unallocated or is only allocated by another client), a BadAccess error results. If more than one pixel is in error, the one that gets reported is arbitrary. 2.1.5 XLookupColor, XQueryColor, XQueryColors Types: val XLookupColor: Colormap -> string -> (XColor * XColor) val XQueryColor: Colormap -> int -> XColor val XQueryColors: Colormap -> int list -> XColor list Syntax: val (desired,real) = XLookupColor cmap name ; val colour = XQueryColor cmap pixel ; val colours = XQueryColors cmap pixels ; Arguments: colormap Specifies the colormap. name Specifies the colour name string (for example, red) whose colour definition structure you want returned. colour Returns the RGB values for the specified pixel. colours Returns a list of colour definition structures for the pixel specified. desired Returns the exact RGB values. 20 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 real Returns the closest RGB values provided by the hardware. Description: The XLookupColor function looks up the string name of a colour with respect to the screen associated with the specified colormap. It returns both the exact colour values and the closest values provided by the screen with respect to the visual type of the specified colormap. You should use the ISO Latin-1 encoding; uppercase and lowercase do not matter. XLookupColor raises exception XWindows with "XLookupColor failed" if the name did not exist. The XQueryColor function returns the hardware-specific RGB values for the specified pixel and sets the DoRed, DoGreen, and DoBlue flags. The XQueryColors function returns the RGB values for each pixel in the list and sets the DoRed, DoGreen, and DoBlue flags. 2.1.6 XParseColor Types: val XParseColor: Colormap -> string -> XColor Syntax: val colour = XParseColor cmap name ; Arguments: cmap Specifies the colormap. name Specifies the colour name string; case is ignored. colour Returns the exact colour value for later use and sets the doRed, doGreen, and doBlue flags. Argument Type: datatype XColor = XColor of { doRed: bool, doGreen: bool, doBlue: bool, red: int, green: int, blue: int, pixel: int } Description: The XParseColor function provides a simple way to create a standard user interface to colour. It takes a string specification of a colour, typically from a command line or XGetDefault option, and returns the corresponding red, green, and blue values that are suitable for a subsequent call to XAllocColor or XStoreColor. The colour can be specified either as a colour name (as in XAllocNamedColor) or as an initial sharp sign character followed by a numeric specification, in one of the following formats: #RGB (4 bits each) cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 21 #RRGGBB (8 bits each) #RRRGGGBBB (12 bits each) #RRRRGGGGBBBB (16 bits each) The R, G, and B represent single hexadecimal digits (both uppercase and lowercase). When fewer than 16 bits each are specified, they represent the most-significant bits of the value. For example, #3a7 is the same as #3000a0007000. The colormap is used only to determine which screen to look up the colour on. For example, you can use the screen's default colormap. If the initial character is a sharp sign but the string otherwise fails to fit the above formats or if the initial character is not a sharp sign and the named colour does not exist in the server's database, then exception XWindows is raised with "XParseColor failed" . 2.1.7 XStoreColor, XStoreColors, XStoreNamedColor Types: val XStoreColor: Colormap -> XColor -> unit val XStoreColors: Colormap -> XColor list -> unit val XStoreNamedColor: Colormap -> string -> int -> (bool * bool * bool) -> unit Syntax: XStoreColor cmap colour ; XStoreColors cmap colours ; XStoreNamedColor cmap name pixel (doRed,doGreen,doBlue) ; Arguments: colour Specifies the pixel and RGB values colours Specifies a list of pixel and RGB values cmap Specifies the colormap. doRed Specifies if the red component is set doGreen Specifies if the green component is set doBlue Specifies if the blue component is set. name Name of colour to copy RGB values from. pixel Specifies the entry in the colormap. Argument Type: datatype XColor = XColor of { doRed: bool, doGreen: bool, doBlue: bool, red: int, green: int, blue: int, pixel: int } 22 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 Description: The XStoreColors function changes the colormap entries of the pixel values specified in the pixel members of the XColor structures. You specify which colour components are to be changed by setting doRed, doGreen, and/or doBlue in the XColor structures. If the colormap is an installed map for its screen, the changes are visible immediately. 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 BadValue error results. If a specified pixel either is unallocated or is allocated read-only, a BadAccess error results. If more than one pixel is in error, the one that gets reported is arbitrary. The XStoreColor function changes the colormap entry of the pixel value specified in the pixel member of the XColor structure. You specified this value in the pixel member of the 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 BadValue error results. XStoreColor also changes the red, green, and/or blue colour components. You specify which colour components are to be changed by setting doRed, doGreen, and/or doBlue in the XColor structure. If the colormap is an installed map for its screen, the changes are visible immediately. The XStoreNamedColor function looks up the named colour 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 booleans doRed, doGreen, and doBlue determine which of the red, green, and blue components are set. If the specified pixel is not a valid index into the colormap, a BadValue error results. If the specified pixel either is unallocated or is allocated read-only, a BadAccess error results. You should use the ISO Latin-1 encoding; uppercase and lowercase do not matter. 2.2 Colormaps 2.2.1 DefaultColormap Types: val DefaultColormap: unit -> Colormap Syntax: val cmap = DefaultColormap() ; Description: The DefaultColormap function returns the default colormap for allocation on the screen. 2.2.2 DefaultDepth Types: val DefaultDepth: unit -> int cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 23 Syntax: val depth = DefaultDepth() ; Description: The DefaultDepth function returns the depth (number of planes) of the default root window for the screen. 2.2.3 DisplayCells Types: val DisplayCells: unit -> int Syntax: val cells = DisplayCells() ; Description: The DisplayCells function returns the number of entries in the default colormap. 2.2.4 VisualClass Types: val VisualClass: Visual -> VisualClass Syntax: val class = VisualClass visual ; Arguments: visual Specifies the visual. class Returns the class from the visual. Argument Type: datatype VisualClass = StaticGray | GrayScale | StaticColor | PseudoColor | TrueColor | DirectColor Description: Returns the visual class from the specified visual. 24 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 2.2.5 XCreateColormap, XCopyColormapAndFree, XFreeColormap, XSetWindowColormap Types: val XCreateColormap: Drawable -> Visual -> AllocType -> Colormap val XCopyColormapAndFree: Colormap -> Colormap val XFreeColormap: Colormap -> unit val XSetWindowColormap: Drawable -> Colormap -> unit Syntax: val cmap = XCreateColormap w visual alloc ; val copy = XCopyColormapAndFree cmap ; XFreeColormap cmap ; XSetWindowColormap w cmap ; Arguments: w Specifies the window visual Specifies a visual type supported on the screen. If the visual type is not one supported by the screen, a BadMatch error results. alloc Specifies the colormap entries to be allocated. You can pass AllocNone or AllocAll. cmap Specifies the colormap. copy Returns a copy of the colormap. Argument Type: datatype AllocType = AllocNone | AllocAll datatype VisualClass = StaticGray | GrayScale | StaticColor | PseudoColor | TrueColor | DirectColor datatype XColor = XColor of { doRed: bool, doGreen: bool, doBlue: bool, red: int, green: int, blue: int, pixel: int } Argument Description: The red, green, and blue values are scaled between 0 and 65535. Full brightness in a colour is a value of 65535 independent of the number of bits actually used in the display hardware. Half brightness in a colour is a value of 32767, and off is 0. This representation gives uniform results for colour values across different screens. In some functions, the doRed, doGreen and doBlue fields control which of the red, green, and blue members are used. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 25 Description: The XCreateColormap function creates a colormap of the specified visual type for the screen on which the specified window resides and returns the colormap associated with it. Note that the specified window is only used to determine the screen. The initial values of the colormap entries are undefined for the visual classes GrayScale, PseudoColor, and DirectColor. For StaticGray, StaticColor, and TrueColor, the entries have defined values, but those values are specific to the visual and are not defined by X. For StaticGray, StaticColor, and TrueColor, alloc must be AllocNone, or a BadMatch error results. For the other visual classes, if alloc is AllocNone, the colormap initially has no allocated entries, and clients can allocate them. If alloc is AllocAll, the entire colormap is allocated writable. The initial values of all allocated entries are undefined. For GrayScale and PseudoColor, the effect is as if an XAllocColorCells call returned all pixel values from zero to N - 1, where N is the colormap entries value in the specified visual. For DirectColor, the effect is as if an XAllocColorPlanes call returned a pixel value of zero and redMask, greenMask, and blueMask 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 XFreeColors. The XCopyColormapAndFree function creates a colormap of the same visual type and for the same screen as the specified colormap and returns the new colormap. It also moves all of the client's existing allocation from the specified colormap to the new colormap with their colour 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 AllocAll, the new colormap is also created with AllocAll, all colour 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 AllocAll, the allocations to be moved are all those pixels and planes that have been allocated by the client using XAllocColor, XAllocNamedColor, XAllocColorCells, or XAllocColorPlanes and that have not been freed since they were allocated. The XFreeColormap function deletes the association between the colormap resource in the server and the ML Colormap value. 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 XUninstallColormap). If the specified colormap is de- fined as the colormap for a window (by XCreateWindow, XSetWindowColormap, or XChangeWindowAttributes), XFreeColormap changes the colormap associated with the window to NoColormap and generates a ColormapNotify event. X does not define the colours displayed for a window with a colormap of NoColormap. The XSetWindowColormap function sets the specified colormap of the specified win- dow. The colormap must have the same visual type as the window, or a BadMatch error results. 2.2.6 XInstallColormap, XUninstallColormap, XListInstalledColormaps Types: val XInstallColormap: Colormap -> unit val XListInstalledColormaps: Drawable -> Colormap list val XUninstallColormap: Colormap -> unit 26 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 Syntax: XInstallColormap cmap ; XUninstallColormap cmap ; val cmaps = XListInstalledColormaps w ; Arguments: cmap Specifies the colormap. w Specifies the window that determines the screen. Description: The XInstallColormap function installs the specified colormap for its associated screen. All windows associated with this colormap immediately display with true colours. You associated the windows with this colormap when you created them by calling XCre- ateWindow, XCreateSimpleWindow, XChangeWindowAttributes, or XSetWin- dowColormap. If the specified colormap is not already an installed colormap, the X server generates a 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 XInstallColormap, the X server generates a ColormapNotify event on each window that has that colormap. The 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. If the specified colormap becomes uninstalled, the X server generates a 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 XUninstallColormap, the X server generates a ColormapNotify event on each window that has that colormap. The XListInstalledColormaps function returns a list of the currently installed col- ormaps 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. If XListInstalledCol- ormaps fails then exception XWindows is raised with "XListInstalledColormaps failed" . 2.2.7 XSetRGBColormaps, XGetRGBColormaps Types: val XSetRGBColormaps: Drawable -> int -> XStandardColormap list -> unit val XGetRGBColormaps: Drawable -> int -> XStandardColormap list Syntax: XSetRGBColormaps w property stdmaps ; val maps = XGetRGBColormaps w property ; Arguments: w Specifies the window. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 27 property Specifies the property atom. stdmaps Specifies the XStandardColormaps to be used maps Returns the XStandardColormap Argument Type: datatype XStandardColormap = XStandardColormap of { colormap: Colormap, redMax: int, redMult: int, greenMax: int, greenMult: int, blueMax: int, blueMult: int, basePixel: int, visual: Visual } Argument Description: The colormap member is the colormap created by the XCreateColormap function. The redMax, greenMax, and blueMax members give the maximum red, green, and blue values, respectively. Each colour 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 redMax = 7, greenMax = 7, and blueMax = 3. An alternate allocation that uses only 216 colours is redMax = 5, greenMax = 5, and blueMax = 5. The redMult, greenMult, and blueMult members give the scale factors used to compose a full pixel value. (See the discussion of the basePixel members for further information.) For a 3/3/2 allocation, redMult might be 32, greenMult might be 4, and blueMult might be 1. For a 6-colours-each allocation, redMult might be 36, greenMult might be 6, and blueMult might be 1. The basePixel member gives the base pixel value used to compose a full pixel value. Usually, the basePixel is obtained from a call to the 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: r * redMult + g * greenMult + b * blueMult + basePixel For GrayScale colormaps, only the colormap, redMax, redMult, and basePixel members are defined. The other members are ignored. To compute a GrayScale pixel value, use the following expression: gray * redMult + basePixel The visual member gives the the visual from which the colormap was created. The properties containing the XStandardColormap information have the type RGB__COLOR__MAP. Description: 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 honour the ICCCM restriction that only RGB__DEFAULT__MAP can contain more than one definition. 28 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 The 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 (if the visual is not present, XGetRGBColormaps assumes the default visual for the screen on which the window is located), XGetRGBColormaps re- turns the list of colormaps. Otherwise, XGetRGBColormaps returns the empty list. Note that it is the caller's responsibility to honour the ICCCM restriction that only RGB__DEFAULT__MAP can contain more than one definition. 2.3 Cursors 2.3.1 XCreateFontCursor, XCreatePixmapCursor, XCreateGlyphCursor Types: val XCreateFontCursor: int -> Cursor val XCreatePixmapCursor: Drawable -> Drawable -> XColor -> XColor -> XPoint -> Cursor val XCreateGlyphCursor: Font -> Font -> int -> int -> XColor -> XColor -> Cursor Syntax: val cursor = XCreateFontCursor shape ; val cursor = XCreatePixmapCursor source mask foreground background hotspot ; val cursor = XCreateGlyphCursor sourceFont maskFont sourceChar maskChar foreground background ; Arguments: background Specifies the RGB values for the background of the source. foreground Specifies the RGB values for the foreground of the source. mask Specifies the cursor's mask bits to be displayed or NoDrawable. maskChar Specifies the glyph character for the mask. maskFont Specifies the font for the mask glyph or NoFont. shape Specifies the shape name of the cursor. source Specifies the cursor's source bits to be displayed. sourceChar Specifies the character glyph for the source. sourceFont Specifies the font for the source glyph. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 29 hotspot Specifies the x and y coordinates, which indicate the hotspot relative to the source's origin. cursor Returns the new cursor Argument Type: datatype XColor = XColor of { doRed: bool, doGreen: bool, doBlue: bool, red: int, green: int, blue: int, pixel: int } Description: 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. The hotspot comes from the information stored in the cursor font. The initial colours of a cursor are a black foreground and a white background (see XRecolorCursor). The XCreatePixmapCursor function creates and returns a cursor. The foreground and background RGB values must be specified using foreground and background, even if the X server only has a StaticGray or GrayScale screen. The foreground colour is used for the pixels set to 1 in the source, and the background colour is used for the pixels set to 0. Both source and mask, if specified, must have depth one (or a 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 BadMatch error results. The hotspot must be a point within the source, or a BadMatch error results. 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. The XCreateGlyphCursor function is similar to XCreatePixmapCursor except that the source and mask bitmaps are obtained from the specified font glyphs. The sourceChar must be a defined glyph in sourceFont, or a BadValue error results. If maskFont is given, maskChar must be a defined glyph in maskFont, or a BadValue error results. The maskFont and maskChar are optional. The origins of the sourceChar and maskChar (if defined) glyphs are positioned coincidently and define the hotspot. The sourceChar and maskChar 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 maskChar is given, all pixels of the source are displayed. You can free the fonts immediately by calling XFreeFont if no further explicit references to them are to be made. 2.3.2 XDefineCursor, XUndefineCursor, NoCursor Types: 30 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 val XDefineCursor: Drawable -> Cursor -> unit val XUndefineCursor: Drawable -> unit val NoCursor: Cursor Syntax: XDefineCursor w cursor ; XUndefineCursor w ; Arguments: cursor Specifies the cursor that is to be displayed or NoCursor. w Specifies the window. Description: If a cursor is set, it will be used when the pointer is in the window. If the cursor is NoCursor, it is equivalent to XUndefineCursor. The XUndefineCursor undoes the effect of a previous 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. 2.3.3 XRecolorCursor, XFreeCursor Types: val XRecolorCursor: Cursor -> XColor -> XColor -> unit val XFreeCursor: Cursor -> unit Syntax: XRecolorCursor cursor fg bg ; XFreeCursor cursor ; Arguments: bg Specifies the RGB values for the background of the source. cursor Specifies the cursor. fg Specifies the RGB values for the foreground of the source. Description: The XRecolorCursor function changes the colour of the specified cursor, and if the cursor is being displayed on a screen, the change is visible immediately. The XFreeCursor function deletes the association between the Cursor value and the specified cursor in the server. The cursor storage is freed when no other resource references it. The specified cursor should not be referred to again. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 31 2.4 Display Specifications 2.4.1 AllPlanes Types: val AllPlanes: int Syntax: val planeMask = AllPlanes ; Description: AllPlanes is a value with all bits set to 1 and is suitable for use in a plane mask argument to a function. 2.4.2 BitmapBitOrder Types: val BitmapBitOrder: unit -> ImageOrder Argument Type: datatype ImageOrder = LSBFirst | MSBFirst Syntax: val order = BitmapBitOrder() ; Description: The BitmapBitOrder function returns LSBFirst or MSBFirst to indicate whether the leftmost bit in the bitmap as displayed on the screen is the least or most significant bit in the bytes comprising the bitmap data. 2.4.3 BitmapPad Types: val BitmapPad: unit -> int Syntax: val pad = BitmapPad() ; Description: The BitmapPad function returns the number of bits that each scanline must be padded. 32 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 2.4.4 BitmapUnit Types: val BitmapUnit: unit -> int Syntax: val scanline = BitmapUnit() ; Description: The BitmapUnit function returns the size of a bitmap's scanline unit in bits. 2.4.5 ByteOrder Types: val ByteOrder: unit -> ImageOrder Argument Type: datatype ImageOrder = LSBFirst | MSBFirst Syntax: val order = ByteOrder ; Description: The ByteOrder function specifies the required byte order for images for each scanline unit in XY format (bitmap) or for each pixel value in Z format. 2.4.6 CellsOfScreen Types: val CellsOfScreen: unit -> int Syntax: val cells = CellsOfScreen() ; Description: The CellsOfScreen function returns the number of colormap cells in the default colormap of the screen. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 33 2.4.7 ColormapExists, CursorExists, DrawableExists, FontExists, GCExists, VisualExists Types: val ColormapExists: Colormap -> bool val CursorExists: Cursor -> bool val DrawableExists: Drawable -> bool val FontExists: Font -> bool val GCExists: GC -> bool val VisualExists: Visual -> bool Description: In Poly/ML all values may be committed to the database and then referenced in future Poly/ML sessions. X resources are stored in the X server and are destroyed at the end of every Poly/ML session. If the user attempts to use an ML value corresponding to an X resource that existed in an earlier session, then exception XWindows is raised with "Non-existant resource" . To allow programmers to detect old resources these functions return true only if the ML value passed in corresponds to an X resource created in this session, and return false otherwise. 2.4.8 ColormapID, CursorID, DrawableID, FontID, GCID, VisualID, SameDrawable Types: type Colormap ; type Cursor ; type Drawable ; type Font ; type GC ; type Visual ; val ColormapID: Colormap -> int val CursorID: Cursor -> int val DrawableID: Drawable -> int val FontID: Font -> int val GCID: GC -> int val VisualID: Visual -> int val SameDrawable: Drawable -> Drawable -> bool Description: These functions return the X identifiers for the corresponding ML value. In X, unique num- bers are generated for client resources such as windows and pixmaps, and these numbers are sent in the messages between the X server and the client to identify the resources. If two resources have the same X identifier, then they are the same resource. Thus the convenience function SameDrawable is defined as: fun SameDrawable a b = (DrawableID a = DrawableID b) 34 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 2.4.9 DefaultVisual Types: val DefaultVisual: unit -> Visual Syntax: val visual = DefaultVisual() ; Description: The DefaultVisual function returns the default visual type for the screen. 2.4.10 DisplayConnected Types: val DisplayConnected: unit -> bool Description: In release 1 of the X Window interface in Poly/ML, the display is connected to automati- cally when Poly/ML starts. If -noDisplay was specified on the command line, or Poly/ML cannot connect to the display for whatever reason, then Poly/ML runs without a display connected. An attempt to use an X function that needs the display will raise exception XWindows with "Display not connected" . To allow programmers to avoid this situation, this function returns true only if the display is connected, and false otherwise. 2.4.11 DisplayHeight, DisplayHeightMM, DisplayWidth, DisplayWidthMM Types: val DisplayHeight: unit -> int val DisplayHeightMM: unit -> int val DisplayWidth: unit -> int val DisplayWidthMM: unit -> int Syntax: val height = DisplayHeight() ; val height = DisplayHeightMM() ; val width = DisplayWidth() ; val width = DisplayWidthMM() ; Description: The DisplayHeight function returns the height of the specified screen in pixels. The DisplayHeightMM function returns the height of the screen in millimeters. The DisplayWidth function returns the width of the screen in pixels. The DisplayWidthMM function returns the width of the specified screen in millimeters. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 35 2.4.12 DisplayPlanes Types: val DisplayPlanes: unit -> int Syntax: val planes = DisplayPlanes() ; Description: The DisplayPlanes function returns the depth of the root window of the screen. 2.4.13 DisplayString Types: val DisplayString: unit -> string Syntax: val s = DisplayString() ; Description: The DisplayString function returns the string that was passed to XOpenDisplay when the current display was opened. 2.4.14 DoesBackingStore Types: val DoesBackingStore: unit -> BackingStore Syntax: val bs = DoesBackingStore() ; Argument Type: datatype BackingStore = NotUseful | WhenMapped | Always Description: The DoesBackingStore function returns WhenMapped, NotUseful, or Always, which indicate whether the screen supports backing stores. 36 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 2.4.15 DoesSaveUnders Types: val DoesSaveUnders: unit -> bool Syntax: val su = DoesSaveUnders() ; Description: The DoesSaveUnders function returns a bool indicating whether the screen supports save unders. 2.4.16 EventMaskOfScreen Types: val EventMaskOfScreen: unit -> EventMask list Syntax: val mask = EventMaskOfScreen() ; Description: The EventMaskOfScreen function returns the root event mask of the root window for the screen at connection setup. 2.4.17 MinCmapsOfScreen Types: val MinCmapsOfScreen: unit -> int Syntax: val n = MinCmapsOfScreen() ; Description: The MinCmapsOfScreen function returns the minimum number of installed colormaps supported by the screen. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 37 2.4.18 MaxCmapsOfScreen Types: val MaxCmapsOfScreen: unit -> int Syntax: val n = MaxCmapsOfScreen() ; Description: The MaxCmapsOfScreen function returns the maximum number of installed colormaps supported by the screen. 2.4.19 NoColormap, NoCursor, NoDrawable, NoFont, NoVisual, ParentRelative, CopyFromParentDrawable, CopyFromParentVisual, PointerWindow, InputFocus, PointerRoot Types: val NoColormap: Colormap val NoCursor: Cursor val NoDrawable: Drawable val NoFont: Font val NoVisual: Visual val ParentRelative: Drawable val CopyFromParentDrawable: Drawable val CopyFromParentVisual: Visual val PointerWindow: Drawable val InputFocus: Drawable val PointerRoot: Drawable Description: These names refer to constant values of the indicated type that may be used instead of passing a real, live instance of one of these types. Typically they are used to indicate that some default action should take place. For example, setting the background pixmap of a window to ParentRelative specifies that the background pixmap of the window's parent is to be used. 2.4.20 ProtocolRevision Types: val ProtocolRevision: unit -> int Syntax: val rev = ProtocolRevision() ; 38 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 Description: The ProtocolRevision function returns the minor protocol revision number of the X server. 2.4.21 ProtocolVersion Types: val ProtocolVersion: unit -> int Syntax: val v = ProtocolVersion() ; Description: The ProtocolVersion function returns the major version number (11) of the X protocol associated with the connected display. 2.4.22 RootWindow Types: val RootWindow: unit -> Drawable Syntax: val root = RootWindow() ; Description: The RootWindow function returns the root window. 2.4.23 ServerVendor Types: val ServerVendor: unit -> string Syntax: val s = ServerVendor() ; Description: The ServerVendor function returns a string that provides some identification of the owner of the X server implementation. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 39 2.4.24 VendorRelease Types: val VendorRelease: unit -> int Syntax: val n = VendorRelease() ; Description: The VendorRelease function returns a number related to a vendor's release of the X server. 2.4.25 XQueryBestCursor, XQueryBestSize, XQueryBestStipple, XQueryBestTile Types: val XQueryBestSize: ShapeClass -> Drawable -> XRectangle -> XRectangle val XQueryBestCursor: Drawable -> XRectangle -> XRectangle val XQueryBestStipple: Drawable -> XRectangle -> XRectangle val XQueryBestTile: Drawable -> XRectangle -> XRectangle Syntax: val bestSize = XQueryBestCursor whichScreen area ; val bestSize = XQueryBestSize whichScreen class area ; val bestSize = XQueryBestStipple whichScreen area ; val bestSize = XQueryBestTile whichScreen area ; Argument Type: datatype ShapeClass = CursorShape | TileShape | StippleShape Arguments: class Specifies the class that you are interested in. You can pass TileShape, CursorShape, or StippleShape. whichScreen Drawable to determine which screen. area Specifies the width and height. bestSize Returns the width and height of the object best supported by the display hardware. 40 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 Description: The XQueryBestSize function returns the best or closest size to the specified size. For CursorShape, this is the largest size that can be fully displayed on the screen specified by whichScreen. For TileShape, this is the size that can be tiled fastest. For StippleShape, this is the size that can be stippled fastest. For CursorShape, the drawable indicates the desired screen. For TileShape and StippleShape, the drawable indicates the screen and possibly the window class and depth. An InputOnly window cannot be used as the drawable for TileShape or StippleShape, or a BadMatch error results. The XQueryBestTile function returns the best or closest size, that is, the size that can be tiled fastest on the screen specified by d. The drawable indicates the screen and possibly the window class and depth. If an InputOnly window is used as the drawable, a BadMatch error results. The XQueryBestStipple function returns the best or closest size, that is, the size that can be stippled fastest on the screen specified by whichScreen. The drawable indicates the screen and possibly the window class and depth. If an InputOnly window is used as the drawable, a BadMatch error results. Some displays allow larger cursors than other displays. The XQueryBestCursor function provides a way to find out what size cursors are actually possible on the display. It returns the largest size that can be displayed. Applications should be prepared to use smaller cursors on displays that cannot support large ones. 2.5 Drawing Primitives 2.5.1 XClearArea, XClearWindow Types: val XClearArea: Drawable -> XRectangle -> bool -> unit val XClearWindow: Drawable -> unit Syntax: XClearArea w area exposures ; XClearWindow w ; Arguments: exposures Specifies a bool that indicates if Expose events are to be generated. area Specifies the area to be cleared in the window. w Specifies the window. Description: The 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 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 NoDrawable, the cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 41 contents of the window are not changed. In either case, if exposures is true, one or more 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 InputOnlyClass, a BadMatch error results. The XClearWindow function clears the entire area in the specified window and is equiv- alent to XClearArea w empty false . If the window has a defined background tile, the rectangle is tiled with a plane-mask of all ones and GXcopy function. If the window has background NoDrawable, the contents of the window are not changed. If you specify a window whose class is InputOnlyClass, a BadMatch error results. 2.5.2 XCopyArea, XCopyPlane Types: val XCopyArea: Drawable -> Drawable -> GC -> XPoint -> XRectangle -> unit val XCopyPlane: Drawable -> Drawable -> GC -> XPoint -> XRectangle -> int -> unit Syntax: XCopyArea src dest gc srcPoint destArea ; XCopyPlane src dest gc srcPoint destArea plane ; Arguments: destArea Specifies the destination rectangle gc Specifies the GC. plane Specifies the bit plane. You must set exactly one bit to 1. src Specifies the source dest and destination drawables to be combined. srcPoint Specifies the upper-left corner of the source rectangle. Description: The XCopyArea function combines the specified rectangle of src with the specified rect- angle of dest. The drawables must have the same root and depth, or a BadMatch error results. 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 NoDrawable, corresponding regions of the destination are tiled with that background (with plane-mask of all ones and GXcopy function). Regardless of tiling or whether the destination is a window or a pixmap, if graphics-exposures is true, then GraphicsExpose events for all corresponding destination regions are generated. If graphics-exposures is true but no GraphicsExpose events are generated, a NoExpose event is generated. Note that by default graphics-exposures is true in new GCs. 42 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 This function uses these GC components: function, plane-mask, subwindow-mode, graphics-exposures, clip-origin, and clip-mask. The XCopyPlane function uses a single bit plane of the specified source rectangle com- bined 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 BadMatch error results. If plane does not have exactly one bit set to 1 and is less than 2 ^ n , where n is the depth of the drawables, a BadValue error results. Effectively, 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 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 FillOpaqueStippled for filling a rectangular area of the destination. This function uses these GC components: function, plane-mask, foreground, background, subwindow-mode, graphics-exposures, clip-origin, and clip-mask. 2.5.3 XDrawArc, XDrawArcs Types: val XDrawArc: Drawable -> GC -> XArc -> unit val XDrawArcs: Drawable -> GC -> XArc list -> unit Syntax: XDrawArc d gc (XArc (area,angle1,angle2)) ; XDrawArcs d gc arcs ; Arguments: angle1 Specifies the start of the arc relative to the three-o'clock position from the center, in units of degrees * 64. angle2 Specifies the path and extent of the arc relative to the start of the arc, in units of degrees * 64. arcs Specifies a list of arcs. d Specifies the drawable. gc Specifies the GC. area Specifies the bounding rectangle of the area. The x and y coordinates, which are relative to the origin of the drawable, specify the upper-left corner of the bounding rectangle. The width and height are the major and minor axes of the arc. Argument Type: datatype XArc = XArc of XRectangle * int * int cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 43 Description: XDrawArc draws a single circular or elliptical arc, and 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, XDrawArc or XDrawArcs truncates it to 360 degrees. For an arc specified as (XArc (Area {x,y,width,height}),angle1,angle2), the origin of the major and minor axes is at (x + width div 2,y + height div 2), and the infinitely thin path describing the entire circle or ellipse intersects the horizontal axis at (x,y + height div 2) and (x + width,y + height div 2) and intersects the vertical axis at (x + width div 2,y) and (x + width div 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. For an arc specified as (XArc (Area {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: skewed-angle = atan (tan normal-angle * width div height) + adjust 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/2,pi/2) and adjust is: 0 for normal-angle in the range (0,pi/2) pi for normal-angle in the range (pi/2,3*pi/2) 2*pi for normal-angle in the range (3*pi/2,2*pi) For any given arc, XDrawArc and 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, XDrawArc and XDrawArcs do not draw a pixel more than once. Otherwise, the in- tersecting pixels of intersecting arcs are drawn multiple times. Specifying an arc with one 44 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 endpoint and a clockwise extent draws the same pixels as specifying the other endpoint and an equivalent counterclockwise extent, except as it affects joins. 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. Both functions use these GC components: foreground, background, tile, stipple, tile- stipple-origin, dash-offset, dash-list, function, plane-mask, line-width, line-style, cap-style, join-style, fill-style, subwindow-mode, clip-origin, and clip-mask. 2.5.4 XDrawImageString, XDrawImageString16 Types: val XDrawImageString: Drawable -> GC -> XPoint -> string -> unit val XDrawImageString16: Drawable -> GC -> XPoint -> int list -> unit Syntax: XDrawImageString d gc point string ; XDrawImageString16 d gc point bigChars ; Arguments: d Specifies the drawable. gc Specifies the GC. string Specifies the character string. bigChars Specifies the character string as a list of 16 bit integers. point Specifies the x and y coordinates, which are relative to the origin of the specified drawable and define the origin of the first character. Description: The XDrawImageString16 function is similar to XDrawImageString except that it uses 16-bit characters. Both functions also use both the foreground and background pixels of the GC in the destination. 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 (x,y-ascent), the width is overall, and the height is ascent+descent. The overall, ascent, and descent are as would be returned by XTextExtents using the font in the gc and string. The function and fill-style defined in the GC are ignored for these functions. The effective function is GXcopy, and the effective fill-style is FillSolid. For fonts defined with 16-bit matrix indexing and used with XDrawImageString, each 8-bit character in the string is used to form the least-significant 8-bits of the index, the most-significant bits are taken to be zero. Both functions use these GC components: plane-mask, foreground, background, font, subwindow-mode, clip-origin, and clip-mask. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 45 2.5.5 XDrawLine, XDrawLines, XDrawSegments Types: val XDrawLine: Drawable -> GC -> XPoint -> XPoint -> unit val XDrawLines: Drawable -> GC -> XPoint list -> CoordMode -> unit val XDrawSegments: Drawable -> GC -> (XPoint * XPoint) list -> unit Syntax: XDrawLine d gc point1 point2 ; XDrawLines d gc points mode ; XDrawSegments d gc segments ; Arguments: d Specifies the drawable. gc Specifies the GC. mode Specifies the coordinate mode. You can pass CoordModeOrigin or Co- ordModePrevious. points Specifies a list of points. segments Specifies a list of pairs of points. point1 Specifies the points point2 to be connected. Argument Type: datatype CoordMode = CoordModeOrigin | CoordModePrevious Description: The 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, XDrawLine does not draw a pixel more than once. If lines intersect, the intersecting pixels are drawn multiple times. The 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 list of XPoint structures. It draws the lines in the same order as the list. 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, 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 PolyLine pro- tocol request were a single, filled shape. CoordModeOrigin treats all coordinates as relative to the origin, and CoordModePrevious treats all coordinates after the first as relative to the previous point. The XDrawSegments function draws multiple, unconnected lines. For each segment, XDrawSegments draws a line between (x1,y1) and (x2,y2). It draws the lines in the same order as the list of pairs of points and does not perform joining at coincident endpoints. For any given line, XDrawSegments does not draw a pixel more than once. If lines intersect, the intersecting pixels are drawn multiple times. All three functions use these GC components: foreground, background, tile, stipple, tile- stipple-origin, dash-offset, dash-list, function, plane-mask, line-width, line-style, cap-style, fill-style, subwindow-mode, clip-origin, and clip-mask. The XDrawLines function also uses the join-style GC component. 46 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 2.5.6 XDrawPoint, XDrawPoints Types: val XDrawPoint: Drawable -> GC -> XPoint -> unit val XDrawPoints: Drawable -> GC -> XPoint list -> CoordMode -> unit Syntax: XDrawPoint d gc point ; XDrawPoints d gc points mode ; Arguments: d Specifies the drawable. gc Specifies the GC. points Specifies a list of points. point Specifies the point. mode Specifies the coordinate mode. You can pass CoordModeOrigin or Coord- ModePrevious. Argument Type: datatype CoordMode = CoordModeOrigin | CoordModePrevious Description: The XDrawPoint function uses the foreground pixel and function components of the GC to draw a single point into the specified drawable; XDrawPoints draws multiple points this way. CoordModeOrigin treats all coordinates as relative to the origin, and CoordModePrevious treats all coordinates after the first as relative to the previous point. XDrawPoints draws the points in the same order as the list. Both functions use these GC components: function, plane-mask, foreground, subwindow- mode, clip-origin, and clip-mask. 2.5.7 XDrawRectangle, XDrawRectangles Types: val XDrawRectangle: Drawable -> GC -> XRectangle -> unit val XDrawRectangles: Drawable -> GC -> XRectangle list -> unit Syntax: XDrawRectangle d gc (Area{x=x,y=y,w=width,h=height}) ; XDrawRectangles d gc rectangles ; Arguments: d Specifies the drawable. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 47 gc Specifies the GC. rectangles Specifies a list of rectangles. x,y Specifies the upper-left corner of the rectangle. width Specifies the dimensions height of the rectangle. Description: The XDrawRectangle and XDrawRectangles functions draw the outlines of the spec- ified rectangle or rectangles as if a five-point PolyLine protocol request were specified for each rectangle: [(x,y),(x+width,y),(x+width,y+height),(x,y+height),(x,y)] For the specified rectangle or rectangles, these functions do not draw a pixel more than once. XDrawRectangles draws the rectangles in the same order as the list. If rectangles intersect, the intersecting pixels are drawn multiple times. Both functions use these GC components: foreground, background, tile, stipple, tile- stipple-origin, dash-offset, dash-list, function, plane-mask, line-width, line-style, join-style, fill-style, subwindow-mode, clip-origin, and clip-mask. 2.5.8 XDrawString, XDrawString16 Types: val XDrawString: Drawable -> GC -> XPoint -> string -> unit val XDrawString16: Drawable -> GC -> XPoint -> int list -> unit Syntax: XDrawString d gc point string ; XDrawString16 d gc point bigChars ; Arguments: d Specifies the drawable. gc Specifies the GC. string Specifies the character string. bigChars Specifies the character string as a list of 16-bit integers. point Specifies the x and y coordinates, which are relative to the origin of the specified drawable and define the origin of the first character. Description: 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 with 2-byte indexing rather than 16-bit linear indexing, pass byte 1 as the most- significant 8-bits and byte 2 as the least-significant 8-bits in the bigChars argument. 48 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 For fonts defined with 16-bit linear indexing and used with XDrawString, each 8-bit character in the string is used to form the least-significant 8-bits of the index, the most- significant bits are taken to be zero. For fonts defined with 2-byte matrix indexing and used with XDrawString, each 8-bit character in the string is used to form byte 2 of the index, byte 1 is taken to be zero. Both functions use these GC components: foreground, background, tile, stipple, tile- stipple-origin, function, plane-mask, fill-style, font, subwindow-mode, clip-origin, and clip- mask. 2.5.9 XDrawText, XDrawText16 Types: val XDrawText: Drawable -> GC -> XPoint -> XTextItem list -> unit val XDrawText16: Drawable -> GC -> XPoint -> XTextItem16 list -> unit Syntax: XDrawText d gc point items ; XDrawText16 d gc point items ; Arguments: d Specifies the drawable. gc Specifies the GC. point Specifies the x and y coordinates, which are relative to the origin of the specified drawable and define the origin of the first character. items Specifies a list of text items. Argument Type: datatype XTextItem = XTextItem of string * int * Font datatype XTextItem16 = XTextItem16 of int list * int * Font Argument Description: If the font member is not NoFont, 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. For example, consider the background rectangle drawn by 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 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 XFontStruct structure. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 49 Description: The XDrawText16 function is similar to XDrawText except that it uses 16-bit charac- ters. Both functions allow complex spacing and font shifts between counted strings. Each text item is processed in turn. A font member other than NoFont 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 BadFont error, the previous text items may have been drawn. For fonts with 2-byte indexing rather than 16-bit linear indexing, pass byte 1 as the high order 8-bits and byte 2 as the low order 8-bits in the XTextItem16 list. Both functions use these GC components: foreground, background, tile, stipple, tile- stipple-origin, function, plane-mask, fill-style, font, subwindow-mode, clip-origin, and clip- mask. 2.5.10 XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFillRectangles Types: val XFillArc: Drawable -> GC -> XArc -> unit val XFillArcs: Drawable -> GC -> XArc list -> unit val XFillRectangle: Drawable -> GC -> XRectangle -> unit val XFillRectangles: Drawable -> GC -> XRectangle list -> unit val XFillPolygon: Drawable -> GC -> XPoint list -> PolyShape -> CoordMode -> unit Syntax: XFillArc d gc (XArc (area,angle1,angle2)) ; XFillArcs d gc arcs ; XFillPolygon d gc points shape mode ; XFillRectangle d gc (Area{x=x,y=y,w=width,h=height}) ; XFillRectangles d gc rectangles ; Argument Type: datatype PolyShape = Complex | Nonconvex | Convex datatype CoordMode = CoordModeOrigin | CoordModePrevious Arguments: d Specifies the drawable. gc Specifies the GC. 50 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 area Specifies the bounding rectangle of the area. The x and y coordinates, which are relative to the origin of the drawable, specify the upper-left corner of the bounding rectangle. The width and height are the major and minor axes of the arc. angle1 Specifies the start of the arc relative to the three-o'clock position from the center, in units of degrees * 64. angle2 Specifies the path and extent of the arc relative to the start of the arc, in units of degrees * 64. arcs Specifies a list of arcs. points Specifies a list of points. shape Specifies a shape that helps the server to improve performance. You can pass Complex, Convex, or Nonconvex. mode Specifies the coordinate mode. You can pass CoordModeOrigin or CoordModePrevious. x,y Specifies the upper-left corner of the rectangle. width Specifies the dimensions height of the rectangle. rectangles Specifies a list of rectangles. Description: The XFillRectangle and XFillRectangles functions fill the specified rectangle or rect- angles as if a four-point FillPolygon protocol request were specified for each rectangle: [(x,y),(x+width,y),(x+width,y+height),(x,y+height)] Each function uses the x and y coordinates, width and height dimensions, and GC you specify. XFillRectangles fills the rectangles in the same order as the list. For any given rectangle, XFillRectangle and XFillRectangles do not draw a pixel more than once. If rectangles intersect, the intersecting pixels are drawn multiple times. Both functions use these GC components: foreground, background, tile, stipple, tile- stipple-origin, function, plane-mask, fill-style, subwindow-mode, clip-origin, and clip-mask. XFillPolygon fills the region closed by the specified path. The path is closed automati- cally if the last point in the list does not coincide with the first point. XFillPolygon does not draw a pixel of the region more than once. CoordModeOrigin treats all coordinates as relative to the origin, and CoordModePrevious treats all coordinates after the first as relative to the previous point. Depending on the specified shape, the following occurs: If shape is Complex, the path may self-intersect. Note that contiguous coincident points in the path are not treated as self-intersection. If shape is 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 Convex can improve performance. If you specify Convex for a path that is not convex, the graphics results are undefined. If shape is Nonconvex, the path does not self-intersect, but the shape is not wholly convex. If known by the client, specifying Nonconvex instead of Complex may improve performance. If you specify Nonconvex for a self-intersecting path, the graphics results are undefined. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 51 The fill-rule of the GC controls the filling behavior of self-intersecting polygons. This function uses these GC components: foreground, background, tile, stipple, tile- stipple-origin, function, plane-mask, fill-style, fill-rule, subwindow-mode, clip-origin, and clip-mask. For each arc, XFillArc or 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 ArcChord, the single line segment joining the endpoints of the arc is used. For ArcPieSlice, the two line segments joining the endpoints of the arc with the center point are used. XFillArcs fills the arcs in the same order as the list. For any given arc, XFillArc and XFillArcs do not draw a pixel more than once. If regions intersect, the intersecting pixels are drawn multiple times. Both functions use these GC components: foreground, background, tile, stipple, tile- stipple-origin, function, plane-mask, fill-style, arc-mode, subwindow-mode, clip-origin, and clip-mask. 2.6 Exceptions 2.6.1 Range Types: exception Range Description: Range is raised when an argument to a function is not inside the allowable range of values. There are many restricted ranges for function arguments. In brief: x and y coordinates must lie between "32768 and 32767 inclusive, width and height values must be between 0 and 65535 inclusive. This means that Rect {top,left,bottom,right} must have right >= left and bottom >= top . Similarly, Area {x,y,w,h} must have w >= 0 and h >= 0 . Where an XRectangle is used to pass width and height values only, the x and y members must both be 0. 2.6.2 XWindows Types: exception XWindows of string Arguments: "Display not connected" Attempt to use X functions with no dis- play connected. "Non-existant resource" Attempt to use a resource value from a previous session. 52 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 "Not a window" Attempt to use a pixmap Drawable as a window "Not a pixmap" Attempt to use a window Drawable as a pixmap "Handler mismatch" Attempt to send a message to a window handler when the window has had a new handler installed with XSetHandler. " failed" Xlib detected an error condition when executing "Bad in " The X server detected an error con- dition occurred when executing . This is only reported when running synchronously. For exam- ple, "BadMatch in XChangeWindowAt- tributes" . Description: exception XWindows is raised when an Xlib function returns an error condition. 2.7 Event Handling 2.7.1 IsCursorKey, IsFunctionKey, IsKeypadKey, IsMiscFunctionKey, IsModifierKey, IsPFKey Types: val IsCursorKey: int -> bool val IsFunctionKey: int -> bool val IsKeypadKey: int -> bool val IsMiscFunctionKey: int -> bool val IsModifierKey: int -> bool val IsPFKey: int -> bool Description: The IsCursorKey function returns true if the specified KeySym is a cursor key. The IsFunctionKey function returns true if the KeySym is a function key. The IsKeypadKey function returns true if the specified KeySym is a keypad key. The IsMiscFunctionKey function returns true if the specified KeySym is a miscellaneous function key. The IsModifierKey function returns true if the specified KeySym is a modifier key. The IsPFKey function returns true if the specified KeySym is a PF key. 2.7.2 ShiftDown, ControlDown Types: cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 53 val ShiftDown: Modifier list -> bool val ControlDown: Modifier list -> bool Syntax: ShiftDown modifiers ControlDown modifiers Arguments: modifiers Specifies the modifiers from a key event Description: The ShiftDown convenience function returns true if ShiftMask is in the modifiers list, and false otherwise. This indicates if the Shift key was pressed when the key event was generated. The ControlDown convenience function returns true if ControlMask is in the modifiers list, and false otherwise. This indicates if the Control key was pressed when the key event was generated. 2.7.3 XLookupString, NoSymbol Types: val XLookupString: int -> Modifier list -> (string * int) val NoSymbol: int Syntax: val (string,keysym) = XLookupString keycode modifiers ; Arguments: keycode Specifies the keycode from a key event modifiers Specifies the modifiers from a key event string Returns the string for that combination keysym Returns the keysym for that combination Description: The XLookupString function translates a key event to a KeySym and a string. The KeySym is obtained by using the standard interpretation of the Shift, Lock, and group modifiers as defined in the X Protocol specification. If the KeySym has been rebound, the bound string will be returned. 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 returned. If no KeySym is defined for keycode, the KeySym returned is NoSymbol. 54 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 2.7.4 XSelectInput Types: val XSelectInput: Drawable -> EventMask list -> unit Syntax: XSelectInput w events ; Arguments: events Specifies the list of events you wish to handle. w Specifies the window. Argument Type: datatype EventMask = KeyPressMask | KeyReleaseMask | ButtonPressMask | ButtonReleaseMask | EnterWindowMask | LeaveWindowMask | PointerMotionMask | PointerMotionHintMask | Button1MotionMask | Button2MotionMask | Button3MotionMask | Button4MotionMask | Button5MotionMask | ButtonMotionMask | KeymapStateMask | ExposureMask | VisibilityChangeMask | StructureNotifyMask | ResizeRedirectMask | SubstructureNotifyMask | SubstructureRedirectMask | FocusChangeMask | PropertyChangeMask | ColormapChangeMask | OwnerGrabButtonMask | ButtonClickMask Description: The 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 doNotPropagate attribute prohibits it. 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: 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. Only one client at a time can select CirculateRequest, ConfigureRequest, or MapRequest events, which are associated with the event mask SubstructureRedi- rectMask. Only one client at a time can select a ResizeRequest event, which is associated with the event mask ResizeRedirectMask. Only one client at a time can select a ButtonPress event, which is associated with the event mask ButtonPressMask. The server reports the event to all interested clients. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 55 2.7.5 XSetHandler, NullHandler Types: val XSetHandler: Drawable -> ('a XEvent * 'state -> 'state) -> 'state -> (int -> 'a -> unit) val NullHandler: 'a XEvent * 'state -> 'state Syntax: val sender = XSetHandler w Handler initialState ; sender delay message ; Arguments: w Specifies the window. Handler Specifies the event handling function. initialState Specifies the initial state. sender Returns a function that can send a strongly typed message to the win- dow at any specified time in the future. delay Specifies a delay in milliseconds before the message is sent. message Specifies the message value. The type of the message matches the type of the XEvent processed by the event handling function. Description: When a window is created it is initially unhandled. It can be used for drawing on, but it will not process any events. An ML function can then be registered for that window, and an initial value supplied. The registered function will transform the value to a new value every time an event arrives for that window. In other words, a functional state machine is set up for each window. We also implement strongly typed message passing between windows, and millisecond-resolution timer events. XSetHandler installs a new event handling function for a window. Event handlers typ- ically pattern-match on the XEvent members, choosing to match events that they are interested in, and then finish off with a default pattern match to provide a default action for all other events. For example: fun Handler (Expose {window,region,...},state) = ... | Handler (EnterNotify {window,...},state) = ... | Handler (LeaveNotify {window,...},state) = ... | Handler (MotionNotify {window,pointer,...},state) = ... | Handler (_,state) = state ; (* default is to do nothing *) Underneath, we have a process that maintains a current state and an event handler for every window, and manages the events from the X server. As each event arrives it applies the handler for that window to the event and the current state, which returns a new state, which replaces the original state. Because only one process handles the events, 56 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 we guarantee that no other handler function can run at the same time. If the handler function raises an exception, instead of returning a new state, then the current state is left unchanged, and the exception is reported at the terminal. In this way all events are handled in turn in a predictable order, and in much the same way that other X toolkits work. The Poly/ML top level shell process is still available for debugging and control. If a window has an operation that takes a long time to complete, then the programmer can use Poly/ML processes to do the computations 'in the background' and 'send' the result as a message to the window for display. However, the use of processes in this way is discouraged as they are not standard. If a window function loops, then all other windows will freeze. Since the Poly/ML top level shell is available the user can type ^C followed by 'f' to raise Interrupt in that window function. The function returned by XSetHandler can be used to send messages to this window, if messages are not required then this function can be ignored. The message value will be wrapped up in a Message XEvent and passed to the event handling function, the type of the message value is guaranteed match the type of XEvent handled by the event handler. The time the message arrives can be modified using the delay parameter, which is the delay in milliseconds. This is often useful for implementing flashing displays, or auto-repeat functions. 2.7.6 XSetInputFocus, XGetInputFocus Types: val XSetInputFocus: Drawable -> RevertCode -> int -> unit val XGetInputFocus: unit -> (Drawable * RevertCode) Syntax: XSetInputFocus focus revertTo time ; val (focus,revertTo) = XGetInputFocus() ; Arguments: focus Specifies or returns the window, PointerRoot, or NoDrawable. revertTo Specifies or returns where the input focus reverts to if the window becomes not viewable. You can pass RevertToParent, RevertToPointerRoot, or RevertToNone. time Specifies the time. You can pass either a timestamp or CurrentTime. Argument Type: datatype RevertCode = RevertToParent | RevertToPointerRoot | RevertToNone val CurrentTime: int Description: The 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 cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 57 than the current X server time. Otherwise, the last-focus-change time is set to the specified time (CurrentTime is replaced by the current X server time). XSetInputFocus causes the X server to generate FocusIn and FocusOut events. Depending on the focus argument, the following occurs: If focus is NoDrawable, all keyboard events are discarded until a new focus window is set, and the revertTo argument is ignored. 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. If focus is 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 revertTo argument is ignored. The specified focus window must be viewable at the time XSetInputFocus is called, or a BadMatch error results. If the focus window later becomes not viewable, the X server evaluates the revertTo argument to determine the new focus window as follows: If revertTo is RevertToParent, the focus reverts to the parent (or the closest view- able ancestor), and the new revertTo value is taken to be RevertToNone. If revertTo is RevertToPointerRoot or RevertToNone, the focus reverts to PointerRoot or NoDrawable, respectively. When the focus reverts, the X server generates FocusIn and FocusOut events, but the last-focus-change time is not af- fected. The XGetInputFocus function returns the focus window and the current focus state. 2.7.7 XSync, XFlush Types: val XSync: bool -> unit val XFlush: unit -> unit Syntax: XSync discard ; XFlush() ; Arguments: discard Specifies a bool that indicates whether XSync discards all events on the event queue. Description: The 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 error event received by Xlib, XSync calls the client application's 58 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 error handling routine. Any events generated by the server are enqueued into the library's event queue. If you passed false, XSync does not discard the events in the queue. If you passed true, XSync discards all events in the queue, including those events that were on the queue before XSync was called. Client applications seldom need to call XSync. The XFlush function flushes the output buffer. Most client applications need not use this function because the output buffer is automatically flushed internally as events are read. 2.7.8 XSyncronise, XSynchronize Types: val XSyncronise: int -> unit Syntax: XSyncronise flag ; Arguments: flag Specifies that synchronization is enabled or disabled Description: If flag is non-zero, XSynchronize turns on synchronous behavior. If flag is zero, XSynchro- nize turns off synchronous behavior. NOTE that the current release has XSynchronize misspelled as XSyncronise. 2.7.9 XTranslateCoordinates Types: val XTranslateCoordinates: Drawable -> Drawable -> XPoint -> XPoint * Drawable Syntax: val (dstPoint,child) = XTranslateCoordinates srcWindow destWindow srcPoint ; Arguments: srcWindow Specifies the source window. destWindow Specifies the destination window. srcPoint Specifies the x and y coordinates within the source window dstPoint Return the x and y coordinates within the destination window child Returns the child if the coordinates are contained in a mapped child of the destination window. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 59 Description: The XTranslateCoordinates function takes the srcPoint coordinates relative to the source window's origin and returns these coordinates to dstPoint relative to the desti- nation window's origin. If XTranslateCoordinates returns zero, srcWindow and dest- Window are on different screens, and dstPoint is (0,0). If the coordinates are contained in a mapped child of destWindow, that child is returned as child. Otherwise, child has the value NoDrawable. 2.8 Fonts 2.8.1 CharLBearing, CharRBearing, CharWidth, CharAscent, CharDescent, CharAttributes Types: val CharLBearing: XCharStruct -> int val CharRBearing: XCharStruct -> int val CharWidth: XCharStruct -> int val CharAscent: XCharStruct -> int val CharDescent: XCharStruct -> int val CharAttributes: XCharStruct -> int Argument Type: datatype XCharStruct = XCharStruct of { lbearing: int, rbearing: int, width: int, ascent: int, descent: int, attributes: int } Description: These convenience functions return the individual fields of the XCharStruct datatype. 2.8.2 FSFont, FSDirection, FSMinChar, FSMaxChar, FSMinByte1, FSMaxByte1, FSAllCharsExist, FSAllCharsExist, FSDefaultChar, FSMinBounds, FSMaxBounds, PSPerChar, FSPerChar, FSAscent, FSDescent, FSAscent, FSDescent, FSMinWidth, FSMaxWidth, FSMinHeight, FSMaxHeight Types: val FSFont: XFontStruct -> Font val FSDirection: XFontStruct -> FontDirection val FSMinChar: XFontStruct -> int val FSMaxChar: XFontStruct -> int val FSMinByte1: XFontStruct -> int val FSMaxByte1: XFontStruct -> int 60 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 val FSAllCharsExist: XFontStruct -> bool val FSDefaultChar: XFontStruct -> int val FSMinBounds: XFontStruct -> XCharStruct val FSMaxBounds: XFontStruct -> XCharStruct val PSPerChar: XFontStruct -> XCharStruct list val FSAscent: XFontStruct -> int val FSDescent: XFontStruct -> int val FSMinWidth: XFontStruct -> int val FSMaxWidth: XFontStruct -> int val FSMinHeight: XFontStruct -> int val FSMaxHeight: XFontStruct -> int Argument Type: datatype XFontStruct = XFontStruct of { font: Font, direction: FontDirection, minChar: int, maxChar: int, minByte1: int, maxByte1: int, allCharsExist: bool, defaultChar: int, minBounds: XCharStruct, maxBounds: XCharStruct, perChar: XCharStruct list, ascent: int, descent: int } Description: These convenience functions return the individual fields of the XFontStruct datatype. NOTE that the current release has FSPerChar misspelled as PSPerChar. FSMinWidth, FSMaxWidth, FSMinHeight and FSMaxHeight are defined as: fun FSMinWidth f = CharWidth (FSMinBounds f) ; fun FSMaxWidth f = CharWidth (FSMaxBounds f) ; fun FSMinHeight f = CharAscent (FSMinBounds f) + CharDescent (FSMinBounds f) ; fun FSMaxHeight f = CharAscent (FSMaxBounds f) + CharDescent (FSMaxBounds f) ; 2.8.3 XListFonts, XListFontsWithInfo Types: val XListFonts: string -> int -> string list val XListFontsWithInfo: string -> int -> (string list * XFontStruct list) Syntax: val names = XListFonts pattern maxNames ; val (names,fonts) = XListFontsWithInfo pattern maxNames ; cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 61 Arguments: pattern Specifies the pattern string that can contain wildcard characters. maxNames Specifies the maximum number of names to be returned. names Specifies the list of font names returned. fonts Specifies the list of font structures returned. Description: The XListFonts function returns a list of available font names (as controlled by the font search path; see XSetFontPath) that match the string you passed to the pattern argument. The string should be ISO Latin-1; uppercase and lowercase do not matter. 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. The list of names is limited to size specified by maxNames. If XListFonts fails then exception XWindows is raised with "XListFonts failed" . The 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 speci- fied by maxNames. The information returned for each font is identical to what XLoad- QueryFont 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 XListFontsWithInfo fails then exception XWindows is raised with "XListFontsWith- Info failed" . 2.8.4 XLoadFont, XLoadQueryFont, XQueryFont, XFreeFont, XUnloadFont Types: val XLoadFont: string -> Font val XLoadQueryFont: string -> XFontStruct val XQueryFont: Font -> XFontStruct val XFreeFont: XFontStruct -> unit val XUnloadFont: Font -> unit Syntax: val font = XLoadFont name ; val fs = XLoadQueryFont name ; val fs = XQueryFont font ; XFreeFont fs ; XUnloadFont font ; Arguments: font Specifies the font identifier. fs Specifies the font structure. name Specifies the name of the font. Argument Type: 62 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 datatype FontDirection = FontLeftToRight | FontRightToLeft datatype XCharStruct = XCharStruct of { lbearing: int, rbearing: int, width: int, ascent: int, descent: int, attributes: int } datatype XFontStruct = XFontStruct of { font: Font, direction: FontDirection, minChar: int, maxChar: int, minByte1: int, maxByte1: int, allCharsExist: bool, defaultChar: int, minBounds: XCharStruct, maxBounds: XCharStruct, perChar: XCharStruct list, ascent: int, descent: int } Argument Description: The XFontStruct structure contains all of the information for the font and consists of the font-specific information as well as a list of XCharStruct structures for the characters contained in the font. X supports single byte/character, two bytes/character matrix, and 16-bit character text op- erations. 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: byte 1 specifies the range of defined rows and byte 2 defines the range of defined columns of the font. Single byte/character fonts have one row defined, and the byte 2 range specified in the structure defines a range of characters. The bounding box of a character is defined by the XCharStruct of that character. When characters are absent from a font, the defaultChar is used. When fonts have all characters of the same size, only the information in the XFontStruct min and max bounds are used. The members of the XFontStruct have the following semantics: The direction member can be either FontLeftToRight or FontRightToLeft. It is just a hint as to whether most XCharStruct elements have a positive (FontLeft- ToRight) or a negative (FontRightToLeft) character width metric. The core pro- tocol defines no support for vertical text. If the minByte1 and maxByte1 members are both zero, minChar specifies the linear character index corresponding to the first element of the perChar list, and maxChar specifies the linear character index of the last element. If either minByte1 or maxByte1 are non-zero, then both minChar and maxChar are less than 256, and the 2-byte character index values corresponding to the perChar list element N (counting from 0) are: byte 1 = N div D + minByte1 byte 2 = N mod D + minChar cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 63 If the perChar list is empty, all glyphs between the first and last character indexes inclusive have the same information, as given by both minBounds and maxBounds. If allCharsExist is true, all characters in the perChar list have non-zero bounding boxes. The defaultChar member specifies the character that will be used when an undefined or nonexistent character is printed. The defaultChar is a 16-bit character (not a 2- byte character). For a font using 2-byte matrix format, the defaultChar has byte 1 in the most-significant byte and byte 2 in the least-significant byte. If the defaultChar itself specifies an undefined or nonexistent character, no printing is performed for an undefined or nonexistent character. The minBounds and maxBounds members contain the most extreme values of each individual XCharStruct component over all elements of this list (and ig- nore nonexistent characters). The bounding box of the font (the smallest rect- angle enclosing the shape obtained by superimposing all of the characters at the same origin (x,y)) has its upper-left coordinate at (x+minBounds.lbearing,y- maxBounds.ascent). Its width is (maxBounds.rbearing-minBounds.lbearing) and its height is (maxBounds.ascent+maxBounds.descent). 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. 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. If the baseline is at Y-coordinate y, the logical extent of the font is inclusive be- tween 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). 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 XCharStruct com- ponents is a rectangle with its upper-left corner at (x+lbearing,y-ascent). Its width is (rbearing-lbearing) and its height is (ascent+descent). The origin for the next character is defined to be (x+width,y) 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. Description: The XLoadFont function loads the specified font and returns the Font value for it. The name should be ISO Latin-1 encoding; uppercase and lowercase do not matter. The interpretation of characters "?" and "*" in the name is not defined by the core protocol but is reserved for future definition. A structured format for font names is specified in the X Consortium standard X Logical Font Description Conventions. If the font does not exist then exception XWindows is raised with "XLoadFont failed" . 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 XUnloadFont. The XQueryFont function returns an XFontStruct structure, which contains informa- tion associated with the font. If XQueryFont fails then exception XWindows is raised with "XQueryFont failed" . The XLoadQueryFont function provides the most common way for accessing a font. XLoadQueryFont both opens (loads) the specified font and returns the appropriate 64 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 XFontStruct structure. If the font does not exist then exception XWindows is raised with "XLoadQueryFont failed" . The XFreeFont function deletes the association between the Font value in the XFontStruct and the specified font in the server. The font itself will be freed when no other resource references it. The XFontStruct and the font should not be referenced again. The XUnloadFont function deletes the association between the Font value and the spec- ified font in the server. The font itself will be freed when no other resource references it. The font should not be referenced again. 2.8.5 XSetFontPath, XGetFontPath Types: val XSetFontPath: string list -> unit val XGetFontPath: unit -> string list Syntax: XSetFontPath directories ; val directories = XGetFontPath() ; Arguments: directories 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. Description: The XSetFontPath function defines the directory search path for font lookup. There is only one search path per X server, not one per client. The interpretation of the strings is operating system dependent, but they are intended to specify directories to be searched in the order listed. Also, the contents of these strings are operating system dependent and are not intended to be used by client applications. Usually, the X server is free to cache font information internally rather than having to read fonts from files. In addition, the X server is guaranteed to flush all cached information about fonts which are currently referenced by an application. The meaning of an error from this request is operating system dependent. The XGetFontPath function returns a list of strings containing the search path. If XGetFontPath fails then exception XWindows is raised with "XGetFontPath failed" . 2.8.6 XTextExtents, XTextExtents16 Types: val XTextExtents: XFontStruct -> string -> (FontDirection * int * int * XCharStruct) val XTextExtents16: XFontStruct -> int list -> (FontDirection * int * int * XCharStruct) cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 65 Syntax: val (direction,ascent,descent,overall) = XTextExtents fs string ; val (direction,ascent,descent,overall) = XTextExtents16 fs bigChars ; Arguments: direction Returns the value of the direction hint (FontLeftToRight or FontRight- ToLeft). fs Specifies the XFontStruct to use. ascent Returns the font ascent. descent Returns the font descent. string Specifies the character string. bigChars Specifies the character string as a list of 16 bit integers. overall Returns the overall size in a XCharStruct structure. Description: The XTextExtents and XTextExtents16 functions perform the size computation lo- cally using the XFontStruct provided. Both functions return an XCharStruct structure, whose members are set to the values as follows. 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. For fonts defined with 2-byte matrix indexing rather than 16-bit linear indexing, the most- significant 8-bits of each int in bigChars is used as byte 1, and the least-significant 8-bits is used as byte 2. If the font has no defined default character, undefined characters in the string are taken to have all zero metrics. Characters with all zero metrics are ignored. If the font has no defined defaultChar, the undefined characters in the string are also ignored. 2.8.7 XTextWidth, XTextWidth16 Types: val XTextWidth: XFontStruct -> string -> int val XTextWidth16: XFontStruct -> int list -> int Syntax: val width = XTextWidth fs string ; val width = XTextWidth16 fs bigChars ; 66 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 Arguments: fs Specifies the XFontStruct to use. string Specifies the character string. bigChars Specifies the character string as a list of 16 bit integers. width Returns the width in pixels. Description: The XTextWidth and XTextWidth16 functions return the width of the specified 8-bit or 2-byte character strings. 2.9 Geometry 2.9.1 AddPoint, SubtractPoint Types: infix AddPoint SubtractPoint val AddPoint: (XPoint * XPoint) -> XPoint val SubtractPoint: (XPoint * XPoint) -> XPoint Description: AddPoint takes two points and adds the x coordinates together and the y coordinates together to make the resulting point. In vector arithmetic this is equivalent to adding two vectors. SubtractPoint subtracts the x coordinate of the second point from the x coordinate of the first, and subtracts the y coordinate of the second point from the y coordinate of the first. In vector arithmetic this is equivalent to vector subtraction. 2.9.2 Inside, Overlap, Within, LeftOf, RightOf, AboveOf, BelowOf, HorizontallyAbutting, VerticallyAbutting Types: infix Inside Overlap Within infix LeftOf RightOf AboveOf BelowOf infix HorizontallyAbutting VerticallyAbutting val Inside: (XRectangle * XRectangle) -> bool val Overlap: (XRectangle * XRectangle) -> bool val Within: (XPoint * XRectangle) -> bool val LeftOf: (XPoint * XRectangle) -> bool val RightOf: (XPoint * XRectangle) -> bool val AboveOf: (XPoint * XRectangle) -> bool val BelowOf: (XPoint * XRectangle) -> bool val HorizontallyAbutting: (XRectangle * XRectangle) -> bool val VerticallyAbutting: (XRectangle * XRectangle) -> bool cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 67 Description: a Inside b is true if rectangle a is totally enclosed by b. a Overlap b is true if the two rectangles intersect. a Within b is true if point a is inside rectangle b. a LeftOf b is true if point a is outside and to the left of rectangle b. a RightOf b is true if point a is outside and to the right of rectangle b. a AboveOf b is true if point a is outside and above rectangle b. a BelowOf b is true if point a is outside and below rectangle b. a HorizontallyAbutting b is true if the left edge of a touches the right edge of b, or the right edge of a touches the left edge of b. a VerticallyAbutting b is true if the top edge of a touches the bottom edge of b, or the bottom edge of a touches the top edge of b. 2.9.3 Intersection, Union, Section Types: val Intersection: XRectangle -> XRectangle -> Section val Union: XRectangle -> XRectangle -> XRectangle Argument Type: datatype Section = Nothing | Section of XRectangle Description: Intersection computes the intersection of the two rectangles. If the rectangles do not intersect then it returns Nothing, otherwise it returns Section of the intersection. Union computes the bounding rectangle for the union of the two rectangles. 2.9.4 Left, Right, Top, Bottom, Width, Height, TopLeft, TopRight, BottomLeft, BottomRight, XRectangle, Area, Rect, DestructRect, DestructArea, empty Types: eqtype XRectangle val Rect: {left:int,right:int,top:int,bottom:int} -> XRectangle val Area: {x:int,y:int,w:int,h:int} -> XRectangle val DestructRect: XRectangle -> {left:int,right:int,top:int,bottom:int} val DestructArea: XRectangle -> {x:int,y:int,w:int,h:int} exception XRectangle of {top:int,left:int,bottom:int,right:int} val Left: XRectangle -> int 68 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 val Right: XRectangle -> int val Top: XRectangle -> int val Bottom: XRectangle -> int val Width: XRectangle -> int val Height: XRectangle -> int val TopLeft: XRectangle -> XPoint val TopRight: XRectangle -> XPoint val BottomLeft: XRectangle -> XPoint val BottomRight: XRectangle -> XPoint val empty = Area {x=0,y=0,w=0,h=0} Syntax: val area = Area { x = 0, y = 0, w = 100, h = 200 } ; val {x,y,w,h} = DestructArea area ; val left = Left area ; Description: XRectangles are used to represent pixel areas. For example, an Expose event on a window will contain the position and size of the rectangular area which needs refreshing. XRect- angles may also represent size only. For example, the coordinate system of a window is represented as an XRectangle which has width and height, but the top left corner of the rectangle is at (0,0). XRectangles representing pixel areas can be thought of in two ways. The first way is to call the top left pixel in the rectangle (x,y) and the width and height of the rectangle are (width,height) . Then, an empty rectangle has width = 0 and height = 0 , and the point (a,b) is in a non-empty rectangle only if a >= x and a < (x+width) and b >= y and b < (y+height) . The second way is to call the top left pixel inside the area (top,left) and to call the outside bottom right pixel (bottom,right) . Then, the empty rectangle has (top,left) = (bottom,right) , and the point (x,y) is in a non-empty rectangle if x >= left and x < right and y >= top and y < bottom . NOTE that in X, y coordi- nates increase down the screen, so top <= bottom . You should be careful not to generate coordinates out of range. x and y coordinates must lie between "32768 and 32767 inclusive, width and height values must be between 0 and 65535 inclusive. This means that Rect {top,left,bottom,right} must have right >= left and bottom >= top . Similarly, Area {x,y,w,h} must have w >= 0 and h >= 0 . If these constraints are not met then exception XRectangle is raised. Convenience functions exist to destruct XRectangles. Left, Right, Top and Bottom return the single coordinate for an edge of an XRectangle. Width and Height re- turn the width and height of an XRectangle. TopLeft, TopRight, BottomLeft and BottomRight return the coordinates of a corner of an XRectangle as points. empty is a rectangle with zero area. 2.9.5 MakeRect, SplitRect Types: cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 69 val MakeRect: XPoint -> XPoint -> XRectangle val SplitRect: XRectangle -> (XPoint * XPoint) Syntax: val (topLeft,bottomRight) = SplitRect r ; val r = MakeRect corner1 corner2 ; Description: MakeRect constructs an XRectangle given two points corresponding to any pair of opposite corners of the rectangle. This is useful when the order of the two points is not known, for example when dragging a rubber-banded box on the screen. SplitRect returns the pair of points corresponding to the top-left and bottom-right corners of the XRectangle. It will always be the case that left <= right and top <= bottom . 2.9.6 NegativePoint Types: val NegativePoint: XPoint -> XPoint Description: NegativePoint negates both the x and y coordinates of the point. This is equivalent to reflecting about the x axis and the y axis. 2.9.7 OutsetRect, OffsetRect, IncludePoint Types: val OutsetRect: int -> XRectangle -> XRectangle val OffsetRect: XRectangle -> XPoint -> XRectangle val IncludePoint: XPoint -> XRectangle -> XRectangle Description: OutsetRect n R takes rectangle R and expands its area by n units in all four directions. Typically n is positive and this function is used to expand areas to incorporate borders of the same width all around. With a negative n it can be used to shrink an area towards the centre of the area. If n is more negative than half the width or height of the area then exception XRectangle is raised. OffsetRect R (XPoint{x,y}) adds x to both x coordinates and y to both y coordinates of R. This is typically used to move a rectangle by an (x,y) offset or vector. IncludePoint p R is used to expand the area of R to include the point p. If p is already inside the rectange R then R is returned unchanged. If p is outside the rectangle R then R is expanded in the direction of p so that p is now just inside R. 70 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 2.9.8 Reflect Types: val Reflect: XRectangle -> XRectangle Description: Reflect takes an XRectangle and swaps the x and y coordinates over; left is swapped with top and right is swapped with bottom. This is equivalent to reflecting the points about the 45-degree line that has the equation y = x. 2.9.9 XPoint Types: datatype XPoint = XPoint of { x:int,y:int } val origin = XPoint {x=0,y=0} Syntax: XPoint { x=100,y=200 } Description: XPoints are used to represent the coordinates of pixels. For example, the position of the top left pixel of a window on the screen is represented as an XPoint. You should be careful not to generate coordinates out of range. x and y coordinates must lie between "32768 and 32767 inclusive. origin is the point (0,0), and is typically used to refer to the origin of the coordinate system. In X, the origin is the top left corner of a window. 2.10 GC - Graphics Context 2.10.1 DefaultGC Types: val DefaultGC: unit -> GC Syntax: val gc = DefaultGC() ; Description: The DefaultGC function returns the default GC for the root window of the screen. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 71 2.10.2 XCreateGC, XChangeGC, XFreeGC Types: val XCreateGC: Drawable -> XGCValue list -> GC val XChangeGC: GC -> XGCValue list -> unit val XFreeGC: GC -> unit Syntax: val gc = XCreateGC d values ; XChangeGC gc values ; XFreeGC gc ; Arguments: d Specifies the drawable. gc Specifies the GC. values Specifies which components in the GC are to be set or changed. Argument Type: datatype XGCValue = GCFunction of GCFunction | GCPlaneMask of int | GCForeground of int | GCBackground of int | GCLineWidth of int | GCLineStyle of GCLineStyle | GCCapStyle of GCCapStyle | GCJoinStyle of GCJoinStyle | GCFillStyle of GCFillStyle | GCFillRule of GCFillRule | GCTile of Drawable | GCStipple of Drawable | GCTSOrigin of XPoint | GCFont of Font | GCSubwindowMode of GCSubwindowMode | GCGraphicsExposures of bool | GCClipOrigin of XPoint | GCClipMask of Drawable | GCDashOffset of int | GCDashList of int | GCArcMode of GCArcMode Argument Description: The GCFunction 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. GXcopy is typically the most useful because it will work on a colour display, but special applications may use other functions, particularly in concert with particular planes of a colour display. The 16 GC functions are: 72 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 datatype GCFunction = GXclear | GXand | GXandReverse | GXcopy | GXandInverted | GXnoop | GXxor | GXor | GXnor | GXequiv | GXinvert | GXorReverse | GXcopyInverted | GXorInverted | GXnand | GXset Many graphics operations depend on either pixel values or planes in a GC. The GC- PlaneMask attribute is an int, and it specifies which planes of the destination are to be modified, one bit per plane. 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. 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. The value AllPlanes can be used to refer to all planes of the screen simultaneously. The result is computed by the following: ((src GC-FUNCTION dst) AND plane-mask) OR (dst AND (NOT plane-mask)) 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). 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: (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)) 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). 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. 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. 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. 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 cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 73 manufacturers' line drawing hardware, which may run many times faster than the more precisely specified wide lines. In general, drawing a thin line will be faster than drawing a wide line of width one. How- ever, 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. datatype GCLineStyle = LineSolid | LineOnOffDash | LineDoubleDash The line-style defines which sections of a line are drawn: LineSolid The full path of the line is drawn. LineDoubleDash The full path of the line is drawn, but the even dashes are filled differently than the odd dashes (see fill-style) with CapButt style used where even and odd dashes meet. LineOnOffDash Only the even dashes are drawn, and cap-style applies to all inter- nal ends of the individual dashes, except CapNotLast is treated as CapButt. datatype GCCapStyle = CapNotLast | CapButt | CapRound | CapProjecting The cap-style defines how the endpoints of a path are drawn: CapNotLast This is equivalent to CapButt except that for a line-width of zero the final endpoint is not drawn. CapButt The line is square at the endpoint (perpendicular to the slope of the line) with no projection beyond. CapRound The line has a circular arc with the diameter equal to the line- width, centered on the endpoint. (This is equivalent to CapButt for line-width of zero). CapProjecting 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 equiv- alent to CapButt for line-width of zero). datatype GCJoinStyle = JoinMiter | JoinRound | JoinBevel The join-style defines how corners are drawn for wide lines: JoinMiter The outer edges of two lines extend to meet at an angle. However, if the angle is less than 11 degrees, then a JoinBevel join-style is used instead. JoinRound The corner is a circular arc with the diameter equal to the line-width, centered on the joinpoint. JoinBevel The corner has CapButt endpoint styles with the triangular notch filled. 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: 74 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 CapNotLast thin The results are device-dependent, but the desired ef- fect is that nothing is drawn. CapButt thin The results are device-dependent, but the desired ef- fect is that a single pixel is drawn. CapRound thin The results are the same as for CapButt/thin. CapProjecting thin The results are the same as for CapButt/thin. CapButt wide nothing is drawn. CapRound wide The closed path is a circle, centered at the endpoint, and with the diameter equal to the line-width. CapProjecting wide The closed path is a square, aligned with the coor- dinate axes, centered at the endpoint, and with the sides equal to the line-width. 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. The tile/stipple and clip origins are interpreted relative to the origin of whatever destina- tion drawable is specified in a graphics request. The tile pixmap must have the same root and depth as the GC, or a BadMatch error results. The stipple pixmap must have depth one and must have the same root as the GC, or a BadMatch error results. For stipple operations where the fill-style is FillStippled but not 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. datatype GCFillStyle = FillSolid | FillTiled | FillStippled | FillOpaqueStippled The fill-style defines the contents of the source for line, text, and fill requests. For all text and fill requests, for line requests with line-style LineSolid, and for the even dashes for line requests with line-style LineOnOffDash or LineDoubleDash, the following apply: FillSolid Foreground FillTiled Tile FillOpaqueStippled 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 FillStippled Foreground masked by stipple When drawing lines with line-style LineDoubleDash, the odd dashes are controlled by the fill-style in the following manner: FillSolid Background FillTiled Same as for even dashes FillOpaqueStippled Same as for even dashes FillStippled Background masked by stipple 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. For optimum performance, you should draw as much as possible with the same GC (with- out changing its components). The costs of changing GC components relative to using cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 75 different GCs depend upon 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. The dashes value is actually a simplified form of the more general patterns that can be set with XSetDashes. Specifying a value of N is equivalent to specifying the two-element list [N,N] in XSetDashes. The value must be non-zero, or a BadValue error results. The value must be less than 256 or exception Range is raised. 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 BadMatch error results. If clip-mask is set to NoDrawable, the pixels are always drawn regardless of the clip origin. The clip-mask also can be set by calling the XSetClipRectangles or 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. datatype GCSubwindowMode = ClipByChildren | IncludeInferiors You can set the subwindow-mode to ClipByChildren or IncludeInferiors. For Clip- ByChildren, both source and destination windows are additionally clipped by all viewable InputOutputClass children. For IncludeInferiors, neither source nor destination win- dow 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 IncludeInfe- riors on a window of one depth with mapped inferiors of differing depth is not illegal, but the semantics are undefined by the core protocol. datatype GCFillRule = EvenOddRule | WindingRule The fill-rule defines what pixels are inside (drawn) for paths given in XFillPolygon re- quests and can be set to EvenOddRule or WindingRule. For EvenOddRule, a point is inside if an infinite ray with the point as origin crosses the path an odd number of times. For 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 ob- served 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. For both EvenOddRule and 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). datatype GCArcMode = ArcChord | ArcPieSlice The arc-mode controls filling in the XFillArcs function and can be set to ArcPieSlice or ArcChord. For ArcPieSlice, the arcs are pie-slice filled. For ArcChord, the arcs are chord filled. The graphics-exposure flag controls GraphicsExpose event generation for XCopyArea and XCopyPlane requests (and any similar requests defined by extensions). 76 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 Description: The 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 BadMatch error. The XChangeGC function changes the components specified by values for the specified GC. The values argument contains the values to be set. The values and restrictions are the same as for XCreateGC. Changing the clip-mask overrides any previous XSetClipRect- angles request on the context. Changing the dash-offset or dash-list overrides any previous XSetDashes request on the context. The order in which components are verified and al- tered is server-dependent. If an error is generated, a subset of the components may have been altered. The XFreeGC function destroys the specified GC. 2.10.3 XSetArcMode Types: val XSetArcMode: GC -> GCArcMode -> unit Syntax: XSetArcMode gc mode ; Arguments: gc Specifies the GC. mode Specifies the arc mode. You can pass ArcChord or ArcPieSlice. Argument Type: datatype GCArcMode = ArcChord | ArcPieSlice Description: The XSetArcMode function sets the arc mode in the specified GC. 2.10.4 XSetBackground Types: val XSetBackground: GC -> int -> unit Syntax: XSetBackground gc background ; Arguments: background Specifies the background pixel. gc Specifies the GC. Description: The XSetBackground function sets the background pixel in the specified GC. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 77 2.10.5 XSetClipMask Types: val XSetClipMask: GC -> Drawable -> unit Syntax: XSetClipMask gc pixmap ; Arguments: gc Specifies the GC. pixmap Specifies the pixmap or NoDrawable. Description: The XSetClipMask function sets the clip-mask in the specified GC to the specified pixmap. If the clip-mask is set to NoDrawable, the pixels are are always drawn (regardless of the clip-origin). 2.10.6 XSetClipOrigin Types: val XSetClipOrigin: GC -> XPoint -> unit Syntax: XSetClipOrigin gc origin ; Arguments: gc Specifies the GC. origin Specifies the x and y coordinates of the clip-mask origin. Description: The XSetClipOrigin function sets the clip origin in the specified GC. The clip-mask origin is interpreted relative to the origin of whatever destination drawable is specified in the graphics request. 2.10.7 XSetClipRectangles Types: val XSetClipRectangles: GC -> XPoint -> XRectangle list -> GCOrder -> unit Syntax: 78 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 XSetClipRectangles gc origin rectangles ordering ; Arguments: gc Specifies the GC. origin Specifies the x and y coordinates of the clip-mask origin. rectangles Specifies a list of rectangles that define the clip-mask. ordering Specifies the ordering relations on the rectangles. You can pass Un- sorted, YSorted, YXSorted, or YXBanded. Argument Type: datatype GCOrder = Unsorted | YSorted | YXSorted | YXBanded Description: The 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 con- tained within the rectangles. The clip-origin is interpreted relative to the origin of what- ever 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 NoDrawable as the clip-mask in XCreateGC, XChangeGC, and XSetClipMask. 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 BadMatch error, but it is not required to do so. If no error is generated, the graphics results are undefined. Unsorted means the rectangles are in arbitrary order. YSorted means that the rectangles are nondecreasing in their Y origin. YXSorted additionally constrains YSorted order in that all rectangles with an equal Y origin are nondecreasing in their X origin. YXBanded additionally constrains YXSorted by requiring that, for every possible Y scanline, all rectangles that include that scanline have an identical Y origins and Y extents. 2.10.8 XSetColours Types: val XSetColours: GC -> int -> int -> unit Syntax: XSetColours gc foreground background ; Arguments: background Specifies the background pixel. foreground Specifies the foreground pixel. gc Specifies the GC. Description: The XSetColours convenience function sets the foreground and background components for the specified GC. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 79 2.10.9 XSetDashes Types: val XSetDashes: GC -> int -> int list -> unit Syntax: XSetDashes offset dashes ; Arguments: dashes Specifies the dash-list for the dashed line-style you want to set for the specified GC. offset Specifies the phase of the pattern for the dashed line-style you want to set for the specified GC. Description: The 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 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 non-zero, or a BadValue error results. All of the elements must be less than 256 or exception Range is raised. Specifying an odd-length list is equivalent to specifying the same list concatenated with itself to produce an even-length list. 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. 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 315 and 225 degrees from the x axis. For all other lines, the major axis is the y axis. 2.10.10 XSetFillRule Types: val XSetFillRule: GC -> GCFillRule -> unit Syntax: XSetFillRule gc rule ; Arguments: 80 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 gc Specifies the GC. rule Specifies the fill-rule you want to set for the specified GC. You can pass Even- OddRule or WindingRule. Argument Type: datatype GCFillRule = EvenOddRule | WindingRule Description: The XSetFillRule function sets the fill-rule in the specified GC. 2.10.11 XSetFillStyle Types: val XSetFillStyle: GC -> GCFillStyle -> unit Syntax: XSetFillStyle gc style ; Arguments: gc Specifies the GC. style Specifies the fill-style you want to set for the specified GC. You can pass Fill- Solid, FillTiled, FillStippled, or FillOpaqueStippled. Argument Type: datatype GCFillStyle = FillSolid | FillTiled | FillStippled | FillOpaqueStippled Description: The XSetFillStyle function sets the fill-style in the specified GC. 2.10.12 XSetFont Types: val XSetFont: GC -> Font -> unit Syntax: XSetFont gc font ; Arguments: gc Specifies the GC. font Specifies the font. Description: The XSetFont function sets the current font in the specified GC. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 81 2.10.13 XSetForeground Types: val XSetForeground: GC -> int -> unit Syntax: XSetForeground gc foreground ; Arguments: foreground Specifies the foreground pixel. gc Specifies the GC. Description: The XSetForeground function sets the foreground pixel in the specified GC. 2.10.14 XSetFunction Types: val XSetFunction: GC -> GCFunction -> unit Syntax: XSetFunction gc function ; Arguments: function Specifies the drawing function. gc Specifies the GC. Description: XSetFunction sets the drawing function in the specified GC. 2.10.15 XSetGraphicsExposures Types: val XSetGraphicsExposures: GC -> bool -> unit Syntax: XSetGraphicsExposures gc exposures ; Arguments: 82 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 gc Specifies the GC. exposures Specifies a bool that indicates whether you want GraphicsExpose and NoExpose events to be reported when calling XCopyArea and XCopyPlane with this GC. Description: The XSetGraphicsExposures function sets the graphics-exposures flag in the specified GC. 2.10.16 XSetLineAttributes Types: val XSetLineAttributes: GC -> int -> GCLineStyle -> GCCapStyle -> GCJoinStyle -> unit Syntax: XSetLineAttributes gc lineWidth lineStyle capStyle joinStyle ; Arguments: capStyle Specifies the line-style and cap-style you want to set for the specified GC. You can pass CapNotLast, CapButt, CapRound, or CapProjecting. joinStyle Specifies the line join-style you want to set for the specified GC. You can pass JoinMiter, JoinRound, or JoinBevel. lineStyle Specifies the line-style you want to set for the specified GC. You can pass LineSolid, LineOnOffDash, or LineDoubleDash. lineWidth Specifies the line-width you want to set for the specified GC. Description: The XSetLineAttributes function sets the line drawing components in the specified GC. 2.10.17 XSetPlaneMask Types: val XSetPlaneMask: GC -> int -> unit Syntax: XSetPlaneMask gc planeMask ; Arguments: gc Specifies the GC. planeMask Specifies the plane mask. Description: The XSetPlaneMask function sets the plane mask in the specified GC. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 83 2.10.18 XSetState Types: val XSetState: GC -> int -> int -> GCFunction -> int -> unit Syntax: XSetState gc foreground background function planeMask ; Arguments: background Specifies the background pixel. foreground Specifies the foreground pixel. function Specifies the drawing function. gc Specifies the GC. planeMask Specifies the plane mask. Description: The XSetState function sets the foreground, background, plane mask, and function com- ponents for the specified GC. 2.10.19 XSetStipple Types: val XSetStipple: GC -> Drawable -> unit Syntax: XSetStipple gc stipple ; Arguments: gc Specifies the GC. stipple Specifies the stipple you want to set for the specified GC. Description: The XSetStipple function sets the stipple in the specified GC. The stipple and GC must have the same depth, or a BadMatch error results. 84 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 2.10.20 XSetSubwindowMode Types: val XSetSubwindowMode: GC -> GCSubwindowMode -> unit Syntax: XSetSubwindowMode gc mode ; Arguments: gc Specifies the GC. mode Specifies the subwindow mode. You can pass ClipByChildren or Include- Inferiors. Argument Type: datatype GCSubwindowMode = ClipByChildren | IncludeInferiors Description: The XSetSubwindowMode function sets the subwindow mode in the specified GC. 2.10.21 XSetTile Types: val XSetTile: GC -> Drawable -> unit Syntax: XSetTile gc tile ; Arguments: gc Specifies the GC. tile Specifies the fill tile you want to set for the specified GC. Description: The XSetTile function sets the fill tile in the specified GC. The tile and GC must have the same depth, or a BadMatch error results. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 85 2.10.22 XSetTSOrigin Types: val XSetTSOrigin: GC -> XPoint -> unit Syntax: XSetTSOrigin gc origin ; Arguments: gc Specifies the GC. origin Specifies the x and y coordinates of the tile and stipple origin. Description: The XSetTSOrigin function sets the tile/stipple origin in the specified GC. When graph- ics requests call for tiling or stippling, the parent's origin will be interpreted relative to whatever destination drawable is specified in the graphics request. 2.11 Images 2.11.1 ImageByteOrder, ImageDepth, ImageSize Types: val ImageByteOrder: XImage -> ImageOrder val ImageDepth: XImage -> int val ImageSize: XImage -> XRectangle Argument Type: datatype ImageOrder = LSBFirst | MSBFirst Syntax: val order = ImageByteOrder image ; val depth = ImageDepth image ; val area = ImageSize image ; Description: The ImageByteOrder function returns the byte order value of an XImage. The ImageSize function returns the size in pixels of an XImage. The ImageDepth function returns the depth value of an XImage. 86 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 2.11.2 VisualRedMask, VisualGreenMask, VisualBlueMask Types: val VisualRedMask: Visual -> int val VisualGreenMask: Visual -> int val VisualBlueMask: Visual -> int Syntax: val redMask = VisualRedMask visual ; val greenMask = VisualGreenMask visual ; val blueMask = VisualBlueMask visual ; Arguments: visual Specifies the visual. Description: These functions return the masks used for Z format images. 2.11.3 XCreateImage, XGetPixel, XPutPixel, XSubImage, XAddPixel Types: val XGetPixel: XImage -> XPoint -> int val XPutPixel: XImage -> XPoint -> int -> unit val XSubImage: XImage -> XRectangle -> XImage val XAddPixel: XImage -> int -> unit val XCreateImage: Visual -> int -> ImageFormat -> int -> string -> XRectangle -> int -> int -> XImage Syntax: val image = XCreateImage visual depth format offset data area bitmapPad bytesPerLine ; val pixel = XGetPixel image point ; val image = XSubImage image subArea ; XPutPixel image point pixel ; XAddPixel image value ; Arguments: bitmapPad Specifies the quantum of a scanline (8, 16, or 32 bits). 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. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 87 bytesPerLine Specifies the number of bytes in the client image between the start of one scanline and the start of the next. data Specifies the image data. depth Specifies the depth of the image. format Specifies the format for the image. You can pass XYBitmap, XYP- ixmap, or ZPixmap. area Specifies the width and height of the image, in pixels. offset Specifies the number of pixels to ignore at the beginning of the scan- line. pixel Specifies the new pixel value. subArea Specifies the position and size of the new subimage, in pixels. value Specifies the constant value that is to be added. visual Specifies the visual. ximage Specifies the image. point Specifies the x and y coordinates. Argument Type: datatype ImageFormat = XYBitmap | XYPixmap | ZPixmap datatype ImageOrder = LSBFirst | MSBFirst type ImageData val Data: string -> ImageData datatype XImage = XImage of { data: ImageData, size: XRectangle, depth: int, format: ImageFormat, xoffset: int, bitmapPad: int, byteOrder: ImageOrder, bitmapUnit: int, bitsPerPixel: int, bytesPerLine: int, visualRedMask: int, bitmapBitOrder: ImageOrder, visualBlueMask: int, visualGreenMask: int } Description: The XCreateImage function initializes the XImage byteOrder, bitmapBitOrder, and bitmapUnit values from the display and returns an XImage structure. The red, green, and blue mask values are defined for Z format images only and are derived from the 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 bytesPerLine, Xlib assumes that the scanlines are contiguous in memory and calculates the value of bytesPerLine itself. 88 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 The 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 int is the least-significant byte of the pixel). The image must contain the x and y coordinates. The 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 int is the least-significant byte of the pixel). The image must contain the x and y coordinates. The XSubImage function creates a new image that is a subsection of an existing one. The data is copied from the source image, and the image must contain the rectangle defined by subArea. If XSubImage fails then exception XWindows is raised with "XSubImage failed" . The XAddPixel function adds a constant value to every pixel in an image. It is useful when you have a base pixel value from allocating colour resources and need to manipulate the image to that form. 2.11.4 XPutImage, XGetImage, XGetSubImage Types: val XPutImage: Drawable -> GC -> XImage -> XPoint -> XRectangle -> unit val XGetImage: Drawable -> XRectangle -> int -> ImageFormat -> XImage val XGetSubImage: Drawable -> XRectangle -> int -> ImageFormat -> XImage -> XPoint -> unit Syntax: val image = XGetImage d area planeMask format ; XGetSubImage d area planeMask format destImage destPoint ; XPutImage d gc image srcPoint destArea ; Arguments: d Specifies the drawable. destImage Specifies the destination image. destPoint Specifies the x and y coordinates, which are relative to the origin of the drawable and are the coordinates of the subimage or 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. format Specifies the format for the image. You can pass XYBitmap, XYP- ixmap, or ZPixmap. gc Specifies the GC. image Specifies the image you want combined with the rectangle. planeMask Specifies the plane mask. srcPoint Specifies the offsets from the left and top edges of the image defined by the XImage structure. area Specifies the position and size of the subimage, cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 89 destArea Specifies coordinates relative to the origin of the drawable to define the destination rectangle. Description: The XPutImage function combines an image in memory with a rectangle of the specified drawable. If XYBitmap format is used, the depth must be one, or a 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 XYPixmap and ZPixmap, the depth must match the depth of the drawable, or a BadMatch error results. The section of the image defined by the srcPoint and area arguments is drawn on the specified part of the drawable at the position specified by destArea This function uses these GC components: foreground, background, function, plane-mask, subwindow-mode, clip-origin, and clip-mask. The XGetImage function returns an 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 XYPixmap, the image contains only the bit planes you passed to the planeMask argument. If the planeMask 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 ZPixmap, XGetImage returns as zero the bits in all planes not specified in the planeMask argument. The function performs no range checking on the values in planeMask and ignores extraneous bits. XGetImage returns the depth of the image to the depth member of the XImage struc- ture. The depth of the image is as specified when the drawable was created, except when getting a subset of the planes in XYPixmap format, when the depth is given by the number of bits set to 1 in planeMask. If the drawable is a pixmap, the given rectangle must be wholly contained within the pixmap, or a 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 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 XGetImage fails then exception XWindows is raised with "XGetImage failed" . The XGetSubImage function updates destImage with the specified subimage in the same manner as XGetImage. If the format argument is XYPixmap, the image contains only the bit planes you passed to the planeMask argument. If the format argument is ZPixmap, XGetSubImage returns as zero the bits in all planes not specified in the planeMask argument. The function performs no range checking on the values in planeMask and ignores extraneous bits. The depth of the destination 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 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 BadMatch error results. If the window has backing-store, then the backing-store contents 90 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 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. 2.12 Properties and Selections 2.12.1 XDeleteProperty Types: val XDeleteProperty: Drawable -> int -> unit Syntax: XDeleteProperty w property ; Arguments: property Specifies the property name. w Specifies the window containing the property. Description: The XDeleteProperty function deletes the specified property only if the property was defined on the specified window and causes the X server to generate a PropertyNotify event on the window unless the property does not exist. 2.12.2 XInternAtom, XGetAtomName Types: val XInternAtom: string -> bool -> int val XGetAtomName: int -> string Syntax: val atom = XInternAtom name onlyIfExists ; val name = XGetAtomName atom ; Arguments: atom Specifies the atom whose name you want returned. name Specifies the name associated with the atom you want returned. onlyIfExists Specifies a bool that indicates whether XInternAtom creates the atom. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 91 Description: The XInternAtom function returns the atom identifier associated with the specified name string. If onlyIfExists is false, the atom is created if it does not exist, otherwise, XInternAtom returns zero. You should use an ISO Latin-1 string for name. Case matters; 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. The XGetAtomName function returns the name associated with the specified atom. If XGetAtomName fails then exception XWindows is raised with "XGetAtomName failed" . 2.12.3 XSetProperty, XGetTextProperty Types: val XSetProperty: Drawable -> int -> PropertyValue -> int -> unit val XGetTextProperty: Drawable -> int -> (string * int * int * int) Syntax: XSetProperty w propertyAtom propertyValue propertyTypeAtom ; val (value,encoding,format,nitems) = XGetTextProperty w propertyAtom ; Arguments: w Specifies the window propertyAtom Specifies the property name as an Atom. propertyValue Specifies the property value as one of the predefined types. propertyTypeAtom Specifies the name of the property type as an Atom. value Returns the contents of the property as chars/bytes. encoding Returns the property type atom format Returns the property format which is 1, 2 or 4 bytes per item. nitems Returns the number of items in the value Argument Type: datatype PropertyValue = PropertyArc of XArc list | PropertyAtom of int list | PropertyBitmap of Drawable list | PropertyColormap of Colormap list | PropertyCursor of Cursor list | PropertyDrawable of Drawable list | PropertyFont of Font list | PropertyInteger of int list | PropertyPixmap of Drawable list | PropertyPoint of XPoint list | PropertyRectangle of XRectangle list | PropertyRGBColormap of XStandardColormap list | PropertyString of string 92 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 | PropertyVisual of Visual list | PropertyWindow of Drawable list | PropertyWMHints of XWMHint list | PropertyWMSizeHints of XWMSizeHint list | PropertyWMIconSizes of (XRectangle * XRectangle * XRectangle) list Properties: WM__CLIENT__MACHINE The string name of the machine on which the client application is running. WM__COMMAND The command and arguments, separated by ASCII nulls, used to invoke the application. WM__ICON__NAME Name to be used in icon. WM__NAME Name of the application. Description: The XSetProperty function replaces the existing, specified property for the named win- dow with the value and type specified. If the property does not already exist, XSetProp- erty creates it for the specified window. The XGetTextProperty function reads the specified property from the window. The particular interpretation of the property's encoding and value as 'text' is left to the call- ing application. If the specified property does not exist on the window, then exception XWindows is raised with "XGetTextProperty failed" . 2.12.4 XSetSelectionOwner, XGetSelectionOwner, XConvertSelection, XSendSelectionNotify Types: val XSetSelectionOwner: int -> Drawable -> int -> unit val XGetSelectionOwner: int -> Drawable val XConvertSelection: { selection: int, target: int, property: int, requestor: Drawable, time: int } -> unit val XSendSelectionNotify: { selection: int, target: int, property: int, requestor: Drawable, time: int } -> unit Syntax: XSetSelectionOwner selection owner time ; val owner = XGetSelectionOwner selection ; XConvertSelection {selection,target,property,requestor,time} ; XSendSelectionNotify {selection,target,property,requestor,time} ; cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 93 Arguments: selection Specifies the selection atom. owner Specifies/returns the owner of the specified selection atom. You can pass a window or NoDrawable. time Specifies the time. You can pass either a timestamp or CurrentTime. target Specifies the target atom. property Specifies the property name. You also can pass zero. requestor Specifies the requestor. Argument Type: val CurrentTime: int Description: The XSetSelectionOwner function changes the owner and last-change time for the spec- ified 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 CurrentTime replaced by the current server time. If the owner window is specified as NoDrawable, then the owner of the selection becomes NoDrawable (that is, no owner). Otherwise, the owner of the selection becomes the client executing the request. If the new owner (whether a client or NoDrawable) is not the same as the current owner of the selection and the current owner is not NoDrawable, the current owner is sent a 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 NoDrawable, but the last-change time is not affected. The selection atom is uninterpreted by the X server. XGetSelectionOwner returns the owner window, which is reported in SelectionRe- quest and SelectionClear events. Selections are global to the X server. The XGetSelectionOwner function returns the Drawable associated with the window that currently owns the specified selection. If no selection was specified, the function returns the constant NoDrawable. If NoDrawable is returned, there is no owner for the selection. XConvertSelection requests that the specified selection be converted to the specified target type: If the specified selection has an owner, the X server sends a SelectionRequest event to that owner. If no owner for the specified selection exists, the X server generates a SelectionNotify event to the requestor with property zero. The arguments are passed on unchanged in either of the events. There are two predefined selection atoms: XA__PRIMARY and XA__SECONDARY. XSendSelectionNotify is called when you have received a SelectionRequest event asking for the selection, which you currently own, to be converted to some desired type. When you have completed the conversion you store the converted value in the indicated property on the window. Then you call XSendSelectionNotify with the same parameters as the SelectionRequest event to indicate that the conversion was successful. If cannot 94 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 perform the conversion then you call XSendSelectionNotify with property set to zero to indicate that the conversion failed. If the conversion was successful then the requestor will read the value from the property on the window, and will delete the property to indicate that the transfer has been completed. 2.13 Screen Saver 2.13.1 XSetScreenSaver, XForceScreenSaver, XActivateScreenSaver, XResetScreenSaver, XGetScreenSaver Types: val XSetScreenSaver: int -> int -> Blanking -> Exposures -> unit val XForceScreenSaver: SaveMode -> unit val XActivateScreenSaver: unit -> unit val XResetScreenSaver: unit -> unit val XGetScreenSaver: unit -> (int * int * Blanking * Exposures) Syntax: XSetScreenSaver timeout interval preferBlanking allowExposures ; XForceScreenSaver mode ; XActivateScreenSaver() ; XResetScreenSaver() ; val (timeout,interval,preferBlanking,allowExposures) = XGetScreenSaver() ; Arguments: allowExposures Specifies/returns the screen save control values. You can pass DontAllowExposures, AllowExposures, or DefaultExpo- sures. interval Specifies/returns the interval, in seconds, between screen saver al- terations. mode Specifies the mode that is to be applied. You can pass Screen- SaverActive or ScreenSaverReset. preferBlanking Specifies/returns how to enable screen blanking. You can pass DontPreferBlanking, PreferBlanking, or DefaultBlanking. timeout Specifies the timeout, in seconds, until the screen saver turns on. Argument Type: datatype SaveMode = ScreenSaverReset | ScreenSaverActive datatype Blanking = DontPreferBlanking | PreferBlanking | DefaultBlanking datatype Exposures = DontAllowExposures | AllowExposures | DefaultExposures Description: 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 de- fault. Other negative values generate a BadValue error. If the timeout value is non-zero, cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 95 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. 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 Expose events to clients, the screen is tiled with the root window background tile randomly re-origined each interval minutes. 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 XForceScreenSaver with mode ScreenSaverReset. If the server-dependent screen saver method supports periodic change, the interval argu- ment 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 scram- bling 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. If the specified mode is ScreenSaverActive and the screen saver currently is deactivated, XForceScreenSaver activates the screen saver even if the screen saver had been disabled with a timeout of zero. If the specified mode is ScreenSaverReset and the screen saver currently is enabled, 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). The XActivateScreenSaver function activates the screen saver. The XResetScreenSaver function resets the screen saver. The XGetScreenSaver function gets the current screen saver values. 2.14 Tiles, Stipples, Bitmaps and Pixmaps 2.14.1 XCreatePixmap, XFreePixmap Types: val XCreatePixmap: Drawable -> XRectangle -> int -> Drawable val XFreePixmap: Drawable -> unit Syntax: val pixmap = XCreatePixmap d area depth ; XFreePixmap pixmap ; Arguments: d Specifies which screen the pixmap is created on. depth Specifies the depth of the pixmap. pixmap Specifies the pixmap. area Specifies the width and height, which define the dimensions of the pixmap. 96 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 Description: The XCreatePixmap function creates a pixmap of the width, height, and depth you specified and returns a Drawable that identifies it. It is valid to pass an InputOnlyClass window to the drawable argument. The width and height arguments must be non-zero, or a BadValue error results. The depth argument must be one of the depths supported by the screen of the specified drawable, or a BadValue error results. 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 XCopyPlane for an exception to this rule). The initial contents of the pixmap are undefined. The XFreePixmap function first deletes the association between the Drawable value and the pixmap in the server. Then, the X server frees the pixmap storage when there are no references to it. The pixmap should never be referenced again. 2.14.2 XReadBitmapFile, XWriteBitmapFile, XCreatePixmapFromBitmapData, XCreateBitmapFromData Types: val XReadBitmapFile: Drawable -> string -> BitmapStatus val XWriteBitmapFile: string -> Drawable -> XRectangle -> XPoint -> BitmapStatus val XCreatePixmapFromBitmapData: Drawable -> string -> XRectangle -> int -> int -> int -> Drawable val XCreateBitmapFromData: Drawable -> string -> XRectangle -> Drawable Syntax: val status = XReadBitmapFile d filename ; val status = XWriteBitmapFile filename bitmap area hotspot ; val pixmap = XCreatePixmapFromBitmapData d data area fg bg depth ; val bitmap = XCreateBitmapFromData d data area ; Arguments: bitmap Specifies the bitmap. status Returns the bitmap that is created, or an error condition. d Specifies the drawable that indicates the screen. data Specifies the data in bitmap format. depth Specifies the depth of the pixmap. fg Specifies the foreground and bg background pixel values to use. filename Specifies the file name to use. area Specifies the width and height. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 97 hotspot Specifies where to place the hotspot coordinates, or ("1,"1) if none are present in the file. Argument Type: datatype BitmapStatus = BitmapOpenFailed | BitmapFileInvalid | BitmapNoMemory | BitmapSuccess of Drawable * XRectangle * XPoint Description: The XReadBitmapFile function reads in a file containing a bitmap. The ability to read other than the standard format is implementation dependent. If the file cannot be opened, XReadBitmapFile returns BitmapOpenFailed. If the file can be opened but does not contain valid bitmap data, it returns BitmapFileInvalid. If insufficient working storage is allocated, it returns BitmapNoMemory. If the file is readable and valid, it returns BitmapSuccess. XReadBitmapFile reads the bitmap's height and width from the file. It then creates a pixmap of the appropriate size and reads the bitmap data from the file into the pixmap. The caller must free the bitmap using XFreePixmap when finished. If the hotspot is defined in the bitmap file, XReadBitmapFile returns the hotspot in the status as well, otherwise it returns ("1,"1). The XWriteBitmapFile function writes a bitmap out to a file in the X version 11 format. If the file cannot be opened for writing, it returns BitmapOpenFailed. If insufficient memory is allocated, XWriteBitmapFile returns BitmapNoMemory; otherwise, on no error, it returns BitmapSuccess. If the hotspot is not ("1,"1), XWriteBitmapFile writes it out as the hotspot coordinates for the bitmap. The XCreatePixmapFromBitmapData function creates a pixmap of the given depth and then does a bitmap-format XPutImage of the data into it. The depth must be supported by the screen of the specified drawable, or a BadMatch error results. The XCreateBitmapFromData function allows you to include a bitmap file without reading in the bitmap file. The following example creates a weave bitmap: val data = [17, 17, 184, 184, 124, 124, 58, 58, 17, 17, 163, 163, 199, 199, 139, 139, 17, 17, 184, 184, 124, 124, 58, 58, 17, 17, 163, 163, 199, 199, 139, 139] ; fun MakeData [] = "" | MakeData (H::T) = chr H ^ MakeData T ; val wideWeave = XCreateBitmapFromData root (MakeData data) (Area{x=0,y=0,w=16,h=16}) ; If insufficient working storage was allocated, XCreateBitmapFromData returns NoDrawable. It is your responsibility to free the bitmap using XFreePixmap when finished. 98 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 2.15 User Preferences 2.15.1 XAutoRepeatOn, XAutoRepeatOff, XBell, XQueryKeymap Types: val XAutoRepeatOff: unit -> unit val XAutoRepeatOn: unit -> unit val XBell: int -> unit val XQueryKeymap: unit -> bool list (* 256 bools *) Syntax: XAutoRepeatOn() ; XAutoRepeatOff() ; XBell percent ; val keymap = XQueryKeymap() ; Arguments: percent Specifies the volume for the bell, which can range from "100 to 100 inclusive. keymap Returns the keyboard state vector Description: The XAutoRepeatOn function turns on auto-repeat for the keyboard. The XAutoRepeatOff function turns off auto-repeat for the keyboard. The 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 BadValue error results. The volume at which the bell rings when the percent argument is nonnegative is: base - (base * percent) / 100 + percent The volume at which the bell rings when the percent argument is negative is: base + (base * percent) / 100 To change the base volume of the bell, use XChangeKeyboardControl. The XQueryKeymap function returns a bit vector for the logical state of the keyboard. The vector is returned as a list of 256 bools, representing the keys 0 to 255 in that order. Each bool set to true indicates that the corresponding key is currently pressed. Note that the logical state of a device (as seen by client applications) may lag the physical state if device event processing is frozen. 2.15.2 XGetDefault Types: val XGetDefault: string -> string -> string cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 99 Syntax: val default = XGetDefault program option ; Arguments: option Specifies the option name. program Specifies the program name. Description: XGetDefault returns the value for the program and option entry in the user's defaults database. If XGetDefault fails then exception XWindows is raised with "XGetDefault failed" . 2.16 Windows 2.16.1 XCreateWindow, XCreateSimpleWindow Types: val XCreateWindow: Drawable -> XPoint -> XRectangle -> int -> int -> WindowClass -> Visual -> XSetWindowAttributes list -> Drawable val XCreateSimpleWindow: Drawable -> XPoint -> XRectangle -> int -> int -> int -> Drawable Syntax: val window = XCreateWindow parent point area borderWidth depth class visual attributes ; val window = XCreateSimpleWindow parent point area borderWidth borderPixel backgroundPixel ; Arguments: attributes Specifies the initial values for the window's attributes. backgroundPixel Specifies the background pixel value of the window. borderPixel Specifies the border pixel value of the window. borderWidth Specifies the width of the window's border in pixels. class Specifies the window's class. You can pass InputOutput- Class, InputOnlyClass, or CopyFromParentClass. A class of CopyFromParentClass means the class is taken from the parent. depth Specifies the window's depth. A depth of zero means the depth is taken from the parent. parent Specifies the parent window. 100 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 visual Specifies the visual type. A visual of CopyFromParentVisual means the visual type is taken from the parent. area Specifies the width and height, which are the created window's inside dimensions and do not include the created window's bor- ders. point Specifies the x and y coordinates, which are the top-left outside corner of the window's borders and are relative to the inside of the parent window's borders. Argument Type: datatype XSetWindowAttributes = CWBackPixmap of Drawable | CWBackPixel of int | CWBorderPixmap of Drawable | CWBorderPixel of int | CWBitGravity of Gravity | CWWinGravity of Gravity | CWBackingStore of BackingStore | CWBackingPlanes of int | CWBackingPixel of int | CWOverrideRedirect of bool | CWSaveUnder of bool | CWEventMask of EventMask list | CWDontPropagate of EventMask list | CWColormap of Colormap | CWCursor of Cursor datatype BackingStore = NotUseful | WhenMapped | Always datatype WindowClass = CopyFromParentClass | InputOutputClass | InputOnlyClass Description: The XCreateWindow function creates an unmapped subwindow for a specified parent window, returns the Drawable value for the created window, and causes the X server to generate a CreateNotify event. The created window is placed on top in the stacking order with respect to siblings. The borderWidth for an InputOnlyClass window must be zero, or a BadMatch error results. For class InputOutputClass, the visual type and depth must be a combination supported for the screen, or a BadMatch error results. The depth need not be the same as the parent, but the parent must not be a window of class InputOnlyClass, or a BadMatch error results. For an InputOnlyClass window, the depth must be zero, and the visual must be one supported by the screen. If either condition is not met, a BadMatch error results. The parent window, however, may have any depth and class. If you specify any invalid window attribute for a window, a BadMatch error results. The created window is not yet displayed (mapped) on the user's display. To display the window, call XMapWindow. The new window initially uses the same cursor as its parent. A new cursor can be defined for the new window by calling 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. If XCreateWindow fails then exception XWindows is raised with "XCreateWindow failed" . cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 101 The XCreateSimpleWindow function creates an unmapped InputOutputClass sub- window for a specified parent window, returns the Drawable value for the created window, and causes the X server to generate a 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 borderWidth for an InputOnlyClass win- dow must be zero, or a BadMatch error results. XCreateSimpleWindow inherits its depth, class, and visual from its parent. All other window attributes, except background and border, have their default values. If XCreateSimpleWindow fails then exception XWindows is raised with "XCreateSimpleWindow failed" . 2.16.2 XDestroyWindow, XDestroySubwindows Types: val XDestroyWindow: Drawable -> unit val XDestroySubwindows: Drawable -> unit Syntax: XDestroyWindow w ; XDestroySubwindows w ; Arguments: w Specifies the window. Description: The XDestroyWindow function destroys the specified window as well as all of its sub- windows and causes the X server to generate a 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 DestroyNotify events is such that for any given window being destroyed, 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 Expose events on other windows that were obscured by the window being destroyed. The XDestroySubwindows function destroys all inferior windows of the specified win- dow, in bottom-to-top stacking order. It causes the X server to generate a DestroyNotify event for each window. If any mapped subwindows were actually destroyed, XDestroy- Subwindows causes the X server to generate 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. If XDestroySubwindows fails then exception XWindows is raised with "XDestroySubwindows failed" . 2.16.3 XGetGeometry, XGetWindowAttributes Types: 102 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 val XGetGeometry: Drawable -> (Drawable * XPoint * XRectangle * int * int) val XGetWindowAttributes: Drawable -> XWindowAttributes Syntax: val (root,position,size,borderWidth,depth) = XGetGeometry w ; val attributes = XGetWindowAttributes w ; Arguments: d Specifies the drawable, which can be a window or a pixmap. root Returns the root window position Returns the x and y coordinates that define the location of the draw- able. For a window, these coordinates specify the upper-left outer corner relative to its parent's origin. For pixmaps, these coordinates are always zero. size Returns the drawable's dimensions (width and height). borderWidth Returns the border width in pixels. depth Returns the depth of the drawable (bits per pixel for the object). Argument Type: datatype WindowClass = CopyFromParentClass | InputOutputClass | InputOnlyClass datatype MapState = IsUnmapped | IsUnviewable | IsViewable datatype Gravity = ForgetGravity | NorthWestGravity | NorthGravity | NorthEastGravity | WestGravity | CenterGravity | EastGravity | SouthWestGravity | SouthGravity | SouthEastGravity | StaticGravity val UnmapGravity: Gravity (* same as ForgetGravity *) datatype BackingStore = NotUseful | WhenMapped | Always val NoColormap: Colormap datatype XWindowAttributes = XWindowAttributes of { position: XPoint, size: XRectangle, borderWidth: int, depth: int, visual: Visual, root: Drawable, class: WindowClass, bitGravity: Gravity, winGravity: Gravity, backingStore: BackingStore, backingPlanes: int, backingPixel: int, cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 103 saveUnder: bool, colormap: Colormap, mapInstalled: bool, mapState: MapState, allEventMasks: EventMask list, yourEventMask: EventMask list, doNotPropagateMask: EventMask list, overrideRedirect: bool } Argument Description: The position member is set to the upper-left outer corner relative to the parent window's origin. The size member is set to the inside size of the window, not including the border. The borderWidth 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 the screen's associated 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 InputOutputClass or InputOnlyClass. The bitGravity member is set to the window's bit gravity and can be one of the following: ForgetGravity EastGravity NorthWestGravity SouthWestGravity NorthGravity SouthGravity NorthEastGravity SouthEastGravity WestGravity StaticGravity CenterGravity The winGravity member is set to the window's window gravity and can be one of the following: UnmapGravity EastGravity NorthWestGravity SouthWestGravity NorthGravity SouthGravity NorthEastGravity SouthEastGravity WestGravity StaticGravity CenterGravity The backingStore member is set to indicate how the X server should maintain the contents of a window and can be WhenMapped, Always, or NotUseful. The backingPlanes 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 backingPixel member is set to indicate what values to use for planes not set in backingPlanes. The saveUnder member is set to true or false. The colormap member is set to the colormap for the specified window and can be a Colormap or NoColormap. The mapInstalled member is set to indicate whether the colormap is currently installed and can be true or false. The mapState member is set to indicate the state of the window and can be IsUnmapped, IsUnviewable, or IsViewable. IsUnviewable is used if the window is mapped but some ancestor is unmapped. The allEventMasks member is set to the event masks selected on the window by all clients. The yourEventMask member is set to the event masks selected by the querying client. The doNotPropagateMask member is set to the list of events that should not propagate. The overrideRedirect member is set to indicate whether this window overrides structure control facilities and can be true or false. Window manager clients should ignore the window if this member is true. 104 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 Description: The XGetWindowAttributes function returns the current attributes for the specified window as an XWindowAttributes structure. If XGetWindowAttributes fails then exception XWindows is raised with "XGetWin- dowAttributes failed" . The XGetGeometry function returns the root window and the current geometry of the drawable. The geometry of the drawable includes the position as x and y coordinates, the size as width and height, the border width, and the depth. These are described in the argument list. It is legal to pass to this function a window whose class is InputOnlyClass. If XGetGeometry fails then exception XWindows is raised with "XGetGeometry failed" . 2.16.4 XGetWindowRoot, XGetWindowPosition, XGetWindowSize, XGetWindowBorderWidth, XGetWindowDepth, XGetWindowParent, XGetWindowChildren Types: val XGetWindowRoot: Drawable -> Drawable val XGetWindowPosition: Drawable -> XPoint val XGetWindowSize: Drawable -> XRectangle val XGetWindowBorderWidth: Drawable -> int val XGetWindowDepth: Drawable -> int val XGetWindowParent: Drawable -> Drawable val XGetWindowChildren: Drawable -> Drawable list Description: These convenience functions return the individual attributes returned in bulk by XGet- Geometry and XQueryTree. XGetWindowRoot returns the root window for the drawable. XGetWindowPosition returns the coordinates of the outer top left corner of the window. XGetWindowSize returns the inside size of the window. XGetWindowBorderWidth returns the border width in pixels of the window. XGetWindowDepth returns the depth of the window. XGetWindowParent returns the parent window of the specified window. XGetWin- dowChildren returns the children of the specified window. 2.16.5 XChangeWindowAttributes, XSetWindowBackground, XSetWindowBackgroundPixmap, XSetWindowBorder, XSetWindowBorderPixmap Types: val XChangeWindowAttributes: Drawable -> XSetWindowAttributes list -> unit val XSetWindowBackground: Drawable -> int -> unit val XSetWindowBackgroundPixmap: Drawable -> Drawable -> unit val XSetWindowBorder: Drawable -> int -> unit val XSetWindowBorderPixmap: Drawable -> Drawable -> unit cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 105 Syntax: XChangeWindowAttributes w attributes ; XSetWindowBackground w backgroundPixel ; XSetWindowBackgroundPixmap w backgroundPixmap ; XSetWindowBorder w borderPixel ; XSetWindowBorderPixmap w borderPixmap ; Arguments: attributes Specifies the list of attributes to change. backgroundPixel Specifies the pixel that is to be used for the background. backgroundPixmap Specifies the background pixmap, ParentRelative, or NoDrawable. borderPixel Specifies the entry in the colormap. borderPixmap Specifies the border pixmap or CopyFromParentDrawable. w Specifies the window. Argument Type: datatype XSetWindowAttributes = CWBackPixmap of Drawable | CWBackPixel of int | CWBorderPixmap of Drawable | CWBorderPixel of int | CWBitGravity of Gravity | CWWinGravity of Gravity | CWBackingStore of BackingStore | CWBackingPlanes of int | CWBackingPixel of int | CWOverrideRedirect of bool | CWSaveUnder of bool | CWEventMask of EventMask list | CWDontPropagate of EventMask list | CWColormap of Colormap | CWCursor of Cursor Description: The XChangeWindowAttributes function uses the window attributes in the XSetWindowAttributes list 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 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 NoDrawable or ParentRelative restores the default background pixmap. Changing the border of a root window to CopyFromParentDraw- able 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 WhenMapped or 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 ColormapNotify event. Changing the colormap of a visible window may have no imme- diate effect on the screen because the map may not be installed (see XInstallColormap). 106 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 Changing the cursor of a root window to NoCursor restores the default cursor. Whenever possible, you are encouraged to share colormaps. 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 SubstructureRedirectMask, ResizeRedirect- Mask, and ButtonPressMask. If a client attempts to select any of these event masks and some other client has already selected one, a BadAccess error results. There is only one do-not-propagate-mask for a window, not one per client. The XSetWindowBackground function sets the background of the window to the spec- ified pixel value. Changing the background does not cause the window contents to be changed. XSetWindowBackground uses a pixmap of undefined size filled with the pixel value you passed. If you try to change the background of an InputOnlyClass window, a BadMatch error results. The 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 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 InputOnlyClass window, a BadMatch error results. If the background is set to NoDrawable, the window has no defined background. The XSetWindowBorder function sets the border of the window to the pixel value you specify. If you attempt to perform this on an InputOnlyClass window, a BadMatch error results. The 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 CopyFromParentDrawable, a copy of the parent window's border pixmap is used. If you attempt to perform this on an InputOnlyClass window, a BadMatch error results. 2.16.6 XConfigureWindow, XMoveWindow, XResizeWindow, XMoveResizeWindow, XSetWindowBorderWidth Types: val XConfigureWindow: Drawable -> XWindowChanges list -> unit val XMoveWindow: Drawable -> XPoint -> unit val XResizeWindow: Drawable -> XRectangle -> unit val XMoveResizeWindow: Drawable -> XPoint -> XRectangle -> unit val XSetWindowBorderWidth: Drawable -> int -> unit Syntax: XConfigureWindow w changes ; XMoveWindow w origin ; XResizeWindow w area ; XMoveResizeWindow w origin area ; XSetWindowBorderWidth w borderWidth ; Arguments: cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 107 changes Specifies a list of XWindowChanges. w Specifies the window to be reconfigured. borderWidth Specifies the width of the window border. area Specifies the interior dimensions of the window. origin Specifies the x and y coordinates, which define the new location of the top-left pixel of the window's border or the window itself if it has no border relative to its parent. Argument Type: datatype XWindowChanges = CWPosition of XPoint | CWSize of XRectangle | CWBorderWidth of int | CWStackMode of StackMode | CWSibling of Drawable datatype StackMode = Above | Below | TopIf | BottomIf | Opposite Argument Description: The CWPosition member is 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 CWSize member is used to set the inside size of the window, not including the border, and must be non-zero, or a BadValue error results. Attempts to configure a root window have no effect. The CWBorderWidth 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 InputOnlyClass window non-zero, a BadMatch error results. The CWSibling member is used to set the sibling window for stacking operations. The CWStackMode member is used to set how the window is to be restacked and can be set to Above, Below, TopIf, BottomIf, or Opposite. Description: The XConfigureWindow function uses the values specified in the XWindowChanges list to reconfigure a window's size, position, border, and stacking order. Values not specified are taken from the existing geometry of the window. If a sibling is specified without a stack-mode or if the window is not actually a sibling, a BadMatch error results. Note that the computations for BottomIf, TopIf, and Oppo- site are performed with respect to the window's final geometry (as controlled by the other arguments passed to 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). The XMoveWindow function moves the specified window to the specified x and y coor- dinates, 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 Expose events. Moving a mapped window generates Expose events on any formerly obscured windows. 108 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 If the override-redirect flag of the window is false and some other client has selected Sub- structureRedirectMask on the parent, the X server generates a ConfigureRequest event, and no further processing is performed. Otherwise, the window is moved. The 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 Expose events. If a mapped window is made smaller, changing its size generates Expose events on windows that the mapped window formerly obscured. If the override-redirect flag of the window is false and some other client has selected Sub- structureRedirectMask on the parent, the X server generates a ConfigureRequest event, and no further processing is performed. If either width or height is zero, a Bad- Value error results. The XMoveResizeWindow function changes the size and location of the specified win- dow without raising it. Moving and resizing a mapped window may generate an Expose event on the window. Depending on the new size and location parameters, moving and resizing a window may generate Expose events on windows that the window formerly obscured. If the override-redirect flag of the window is false and some other client has selected Sub- structureRedirectMask on the parent, the X server generates a ConfigureRequest event, and no further processing is performed. Otherwise, the window size and location are changed. The XSetWindowBorderWidth function sets the specified window's border width to the specified width. 2.16.7 XMapWindow, XMapRaised, XMapSubwindows Types: val XMapWindow: Drawable -> unit val XMapRaised: Drawable -> unit val XMapSubwindows: Drawable -> unit Syntax: XMapWindow w ; XMapRaised w ; XMapSubwindows w ; Arguments: w Specifies the window. Description: The 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. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 109 If the override-redirect of the window is false and if some other client has selected Sub- structureRedirectMask on the parent window, then the X server generates a MapRe- quest event, and the XMapWindow function does not map the window. Otherwise, the window is mapped, and the X server generates a MapNotify event. 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 Expose events. If backing-store was maintained while the window was unmapped, no 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. If the window is an InputOutputClass window, XMapWindow generates Expose events on each InputOutputClass 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 Expose events and then map the window, so the client processes input events as usual. The event list will include Expose for each window that has appeared on the screen. The client's normal response to an Expose event should be to repaint the window. This method usually leads to simpler programs and to proper interaction with window managers. The XMapRaised function essentially is similar to 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. The XMapSubwindows function maps all subwindows for a specified window in top-to- bottom stacking order. The X server generates 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. 2.16.8 XQueryPointer Types: val XQueryPointer: Drawable -> (bool * Drawable * Drawable * XPoint * XPoint * Modifier list) Syntax: val (sameScreen,root,child,rootPointer,pointer,modifiers) = XQueryPointer w ; Arguments: sameScreen Returns true if the pointer is on the same screen as the specified window. child Returns the child window that the pointer is located in, if any. modifiers Returns the current state of the modifier keys and pointer buttons. root Returns the root window that the pointer is in. rootPointer Return the pointer coordinates relative to the root window's origin. w Specifies the window. 110 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 pointer Return the pointer coordinates relative to the specified window. Description: The XQueryPointer function returns the root window the pointer is logically on and the pointer coordinates relative to the root window's origin. If sameScreen is false, the pointer is not on the same screen as the specified window, and XQueryPointer returns NoDrawable to child and (0,0) to pointer. If sameScreen is true, the pointer coordi- nates returned to pointer are relative to the origin of the specified window. In this case, XQueryPointer returns the child that contains the pointer, if any, or else NoDrawable to child. XQueryPointer returns the current logical state of the keyboard buttons and the modifier keys in modifiers. It sets modifiers to the list of button or modifier key masks to match the current state of the mouse buttons and the modifier keys. 2.16.9 XQueryTree Types: val XQueryTree: Drawable -> (Drawable * Drawable * Drawable list) Syntax: val (root,parent,children) = XQueryTree w ; Arguments: children Returns a list of children. parent Returns the parent window. root Returns the root window. w Specifies the window whose list of children, root, and parent you want to obtain. Description: The XQueryTree function returns the root window, the parent window, and a list of children windows for the specified window. The children are listed in current stacking order, from bottom-most (first) to top-most (last). If it fails, XQueryTree raises exception XWindows with "XQueryTree failed" . 2.16.10 XRaiseWindow, XLowerWindow, XCirculateSubwindows, XCirculateSubwindowsDown, XCirculateSubwindowsUp, XRestackWindows Types: val XRaiseWindow: Drawable -> unit val XLowerWindow: Drawable -> unit val XCirculateSubwindows: Drawable -> CirculateDirection -> unit val XCirculateSubwindowsDown: Drawable -> unit val XCirculateSubwindowsUp: Drawable -> unit val XRestackWindows: Drawable list -> unit cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 111 Syntax: XRaiseWindow w ; XLowerWindow w ; XCirculateSubwindows w direction ; XCirculateSubwindowsDown w ; XCirculateSubwindowsUp w ; XRestackWindows windows ; Arguments: direction Specifies the direction (up or down) that you want to circulate the window. You can pass RaiseLowest or LowerHighest. w Specifies the window. windows Specifies the list of windows to be restacked. Argument Type: datatype CirculateDirection = RaiseLowest | LowerHighest Description: The 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 Expose events for the window and any mapped subwindows that were formerly obscured. If the override-redirect attribute of the window is false and some other client has se- lected SubstructureRedirectMask on the parent, the X server generates a Configur- eRequest event, and no processing is performed. Otherwise, the window is raised. The 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 Expose events on any windows it formerly obscured. If the override-redirect attribute of the window is false and some other client has se- lected SubstructureRedirectMask on the parent, the X server generates a Configur- eRequest event, and no processing is performed. Otherwise, the window is lowered to the bottom of the stack. The XCirculateSubwindows function circulates children of the specified window in the specified direction. If you specify RaiseLowest, XCirculateSubwindows raises the low- est mapped child (if any) that is occluded by another child to the top of the stack. If you specify LowerHighest, 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 Substructur- eRedirectMask on the window, the X server generates a CirculateRequest event, and no further processing is performed. If a child is actually restacked, the X server generates a CirculateNotify event. The XCirculateSubwindowsUp function raises the lowest mapped child of the specified window that is partially or completely occluded by another child. Completely unobscured 112 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 children are not affected. This is a convenience function equivalent to XCirculateSub- windows with RaiseLowest specified. The XCirculateSubwindowsDown function lowers the highest mapped child of the spec- ified window that partially or completely occludes another child. Completely unobscured children are not affected. This is a convenience function equivalent to XCirculateSub- windows with LowerHighest specified. The XRestackWindows function restacks the windows in the order specified, from top to bottom. The stacking order of the first window in the windows list is unaffected, but the other windows in the list are stacked underneath the first window, in the order of the list. The stacking order of the other windows is not affected. For each window in the window list that is not a child of the specified window, a BadMatch error results. If the override-redirect attribute of a window is false and some other client has selected SubstructureRedirectMask on the parent, the X server generates 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. 2.16.11 XReparentWindow Types: val XReparentWindow: Drawable -> Drawable -> XPoint -> unit Syntax: XReparentWindow w parent topLeft ; Arguments: parent Specifies the parent window. w Specifies the window. topLeft Specifies the x and y coordinates of the position in the new parent window. Description: If the specified window is mapped, XReparentWindow automatically performs an Un- mapWindow 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. After reparenting the specified window, XReparentWindow causes the X server to gen- erate a ReparentNotify event. The overrideRedirect 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 true. Finally, if the specified window was originally mapped, the X server automatically performs a MapWindow request on it. The X server performs normal exposure processing on formerly obscured windows. The X server might not generate Expose events for regions from the initial UnmapWindow request that are immediately obscured by the final MapWindow request. A BadMatch error results if the new parent window is not on the same screen as the old parent window, or if the new parent window is the specified window or an inferior of the specified window, or if the specified window has a ParentRelative background, and the new parent window is not the same depth as the specified window. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 113 2.16.12 XUnmapWindow, XUnmapSubwindows Types: val XUnmapWindow: Drawable -> unit val XUnmapSubwindows: Drawable -> unit Syntax: XUnmapWindow w ; XUnmapSubwindows w ; Arguments: w Specifies the window. Description: The XUnmapWindow function unmaps the specified window and causes the X server to generate an UnmapNotify event. If the specified window is already unmapped, XUn- mapWindow 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 Expose events on windows that were formerly obscured by it. The XUnmapSubwindows function unmaps all subwindows for the specified window in bottom-to-top stacking order. It causes the X server to generate an UnmapNotify event on each subwindow and Expose events on formerly obscured windows. 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. 2.17 Window Manager 2.17.1 XSetIconSizes, XGetIconSizes Types: val XSetIconSizes: Drawable -> (XRectangle * XRectangle * XRectangle) list -> unit val XGetIconSizes: Drawable -> (XRectangle * XRectangle * XRectangle) list Syntax: XSetIconSizes w sizes ; val sizes = XGetIconSizes w ; Arguments: 114 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 sizes Specifies the size list. w Specifies the window. Description: The XSetIconSizes function is used only by window managers to set the supported icon sizes. The size is specified as (minimum size,maximum size,size increment). The XGetIconSizes function returns the empty list if a window manager has not set icon sizes, otherwise it returns a list of supported sizes. 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 XSetWMHints to supply the window manager with an icon pixmap or window in one of the supported sizes. 2.17.2 XSetTransientForHint, XGetTransientForHint Types: val XSetTransientForHint: Drawable -> Drawable -> unit val XGetTransientForHint: Drawable -> Drawable Syntax: XSetTransientForHint transientWindow mainWindow ; val mainWindow = XGetTransientForHint transientWindow ; Arguments: transientWindow Specifies the transient window. mainWindow Specifies a more permanent window in the application. Properties: WM__TRANSIENT__FOR Set by application programs to indicate to the window manager a transient top-level window, such as a dialog box. Description: The XSetTransientForHint function sets the WM__TRANSIENT__FOR property of transientWindow to mainWindow. The XGetTransientForHint function returns the WM__TRANSIENT__FOR property for the specified transientWindow. If the property does not exist then exception XWin- dows is raised with "XGetTransientForHint failed" . 2.17.3 XSetWMClass, XGetWMClass Types: val XSetWMClass: Drawable -> string list -> unit val XGetWMClass: Drawable -> string list cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 115 Syntax: XSetWMClass w class ; val class = XGetWMClass w ; Arguments: class Specifies the class names for the window w Specifies the window Properties: WM__CLASS Set by application programs to allow window and session managers to obtain the application's resources from the resource database. Description: XSetWMClass sets the WM__CLASS property on the specified window. XGetWM- Class returns the WM__CLASS property on the specified window. 2.17.4 XSetWMClientMachine, XGetWMClientMachine Types: val XSetWMClientMachine: Drawable -> string -> unit val XGetWMClientMachine: Drawable -> string Syntax: XSetWMClientMachine w machine ; val machine = XGetWMClientMachine w ; Arguments: w Specifies the window machine Specifies the name of the machine on which the application is running. Properties: WM__CLIENT__MACHINE The string name of the machine on which the client application is running. Description: The XSetWMClientMachine convenience function performs a XSetProperty on the WM__CLIENT__MACHINE property. The XGetWMClientMachine convenience function performs an XGetTextProperty on the WM__CLIENT__MACHINE property. 116 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 2.17.5 XSetWMColormapWindows, XGetWMColormapWindows Types: val XSetWMColormapWindows: Drawable -> Drawable list -> unit val XGetWMColormapWindows: Drawable -> Drawable list Syntax: XSetWMColormapWindows topWindow colormapWindows ; val colormapWindows = XGetWMColormapWindows topWindow ; Arguments: colormapWindows Specifies the list of windows. topWindow Specifies one of the application's top level windows. Properties: WM__COLORMAP__WINDOWS List of windows that may need a different col- ormap than that of their top-level window. Description: The XSetWMColormapWin- dows function replaces the WM__COLORMAP__WINDOWS property on the specified window with the list of windows specified by the colormapWindows argument. The prop- erty is stored with a type of XA__WINDOW and a format of 32. If it cannot intern the WM__COLORMAP__WINDOWS atom, XSetWMColormapWindows raises excep- tion XWindows with "XSetWMColormapWindows failed" . The XGetWMColormapWindows function returns the list of window identifiers stored in the WM__COLORMAP__WINDOWS property on the specified window. These iden- tifiers 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, XGetWMColormapWindows returns the list of windows. Otherwise, it returns the empty list. 2.17.6 XSetWMCommand, XGetWMCommand Types: val XSetWMCommand: Drawable -> string list -> unit val XGetWMCommand: Drawable -> string list Syntax: XSetWMCommand w commands ; val commands = XGetWMCommand w ; Arguments: cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 117 w Specifies the window. commands Specifies the list of strings. Description: The XSetWMCommand function sets the WM__COMMAND property on the speci- fied window. Typically it is set to the command and arguments used to invoke the appli- cation. The XGetWMCommand function reads the WM__COMMAND property from the specified window and returns a string list. If the WM__COMMAND property exists, and it is of type XA__STRING and format 8 then it is returned as a string list. Otherwise, it raises exception XWindows with "XGetWMCommand" . 2.17.7 XSetWMHints, XGetWMHints Types: val XSetWMHints: Drawable -> XWMHint list -> unit val XGetWMHints: Drawable -> XWMHint list Syntax: XSetWMHints w hints ; val hints = XGetWMHints w ; Arguments: w Specifies the window hints Specifies the list of XWMHint values Argument Type: datatype XWMStateHint = DontCareState | NormalState | ZoomState | IconicState | InactiveState datatype XWMHint = InputHint of bool | StateHint of XWMStateHint | IconPixmapHint of Drawable | IconWindowHint of Drawable | IconPositionHint of XPoint | IconMaskHint of Drawable Argument Description: The InputHint 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 X10-style applications that use real-estate driven focus, should set this member to 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 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 118 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 focus management) should set this member to false. Applications that never expect any keyboard input also should set this member to false. 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 true. Push model window managers should make sure that pull model applications do not break them by resetting input focus to PointerRoot when it is appropriate (for example, whenever an application whose input member is false sets input focus to one of its subwindows). Possible values for the StateHint member are DontCareState (* don't know or care *) NormalState (* most applications want to start this way *) ZoomState (* application wants to start zoomed *) IconicState (* application wants to start as an icon *) InactiveState (* application wants to start invisibly *) The IconMaskHint member specifies which pixels of the IconPixmapHint member should be used as the icon. This allows for nonrectangular icons. Both the Icon- PixmapHint member and the IconMaskHint member must be bitmaps. The Icon- WindowHint member lets an application provide a window for use as an icon for window managers that support such use. The IconPositionHint member specifies a position on the screen for the icon. Description: The XSetWMHints function sets the window manager hints that include icon informa- tion and location, the initial state of the window, and whether the application relies on the window manager to get keyboard input. The XGetWMHints function reads the window manager hints and returns the empty list if no WM__HINTS property was set on the window or returns a list of XWMHints if it succeeds. 2.17.8 XSetWMIconName, XGetWMIconName Types: val XSetWMIconName: Drawable -> string -> unit val XGetWMIconName: Drawable -> string Syntax: XSetWMIconName w iconName ; val iconName = XGetWMIconName w ; Arguments: iconName Specifies the icon name w Specifies the window cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 119 Description: The XSetWMIconName convenience function performs a XSetProperty on the WM__ICON__NAME property. The XSetWMIconName function sets the name to be displayed in a window's icon. The XGetWMIconName convenience function performs an XGetTextProperty on the WM__ICON__NAME property. The XGetWMIconName function returns the name to be displayed in the specified window's icon. If it succeeds, it returns the name, otherwise, if no icon name has been set for the window, it raises exception XWindows with "XGetWMIconName" . 2.17.9 XSetWMName, XGetWMName Types: val XSetWMName: Drawable -> string -> unit val XGetWMName: Drawable -> string Syntax: XSetWMName w windowName ; windowName = XGetWMName w ; Arguments: windowName Specifies the window name w Specifies the window Description: The XSetWMName convenience function performs a XSetProperty on the WM__NAME property. The XSetWMName function assigns the name passed to win- dowName 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. The XGetWMName convenience function performs an XGetTextProperty on the WM__NAME property. The XGetWMName function returns the name of the specified window. If the WM__NAME property has not been set for this window, XGetWMName raises exception XWindows with "XGetWMName" . 2.17.10 XSetWMProperties Types: val XSetWMProperties: Drawable -> string -> string -> string list -> XWMSizeHint list -> XWMHint list -> string list -> unit 120 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 Syntax: XSetWMProperties w windowName iconName commands normalHints wmHints class ; Arguments: w Specifies the window windowName Specifies the window name iconName Specifies the icon name commands Specifies the list of strings used to invoke the window normalHints Specifies the list of XWMSizeHint values for the window wmHints Specifies the list of XWMHint values for the window class Specifies the class names for the window Properties: WM__CLASS Set by application programs to allow window and ses- sion managers to obtain the application's resources from the resource database. WM__CLIENT__MACHINE The string name of the machine on which the client application is running. WM__COMMAND The command and arguments, separated by ASCII nulls, used to invoke the application. WM__HINTS Additional hints set by client for use by the window manager. The ML type of this property is XWMHints. WM__ICON__NAME Name to be used in icon. WM__NAME Name of the application. WM__NORMAL__HINTS Size hints for a window in its normal state. The ML type of this property is XWMSizeHint. Description: The 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). If the windowName argument is not empty, XSetWMProperties calls XSetWM- Name, which, in turn, sets the WM__NAME property. If the iconName argu- ment is not empty, XSetWMProperties calls XSetWMIconName, which sets the WM__ICON__NAME property. If the commands argument is not empty, XSetWM- Properties calls XSetWMCommand, which sets the WM__COMMAND property. If the normalHints argument is not empty, XSetWMProperties calls XSetWMNor- malHints, which sets the WM__NORMAL__HINTS property. If the wmHints argument is not empty, XSetWMProperties calls XSetWMHints, which sets the WM__HINTS property. If the class argument is not empty, XSetWMProperties calls XSetWM- Class, which sets the WM__CLASS property. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 121 2.17.11 XSetWMSizeHints, XGetWMSizeHints, XSetWMNormalHints, XGetWMNormalHints Types: val XSetWMSizeHints: Drawable -> int -> XWMSizeHint list -> unit val XGetWMSizeHints: Drawable -> int -> XWMSizeHint list val XSetWMNormalHints: Drawable -> XWMSizeHint list -> unit val XGetWMNormalHints: Drawable -> XWMSizeHint list Syntax: XSetWMSizeHints w property hints ; val hints = XGetWMSizeHints w property ; XSetWMNormalHints w hints ; val hints = XGetWMNormalHints w ; Arguments: w Specifies the window property Specifies the property atom hints Specifies the list of XWMSizeHint values Argument Type: datatype XWMSizeHint = PPosition of XPoint | PSize of XRectangle | PMinSize of XRectangle | PMaxSize of XRectangle | PResizeInc of XRectangle | PAspect of XPoint * XPoint | PBaseSize of XRectangle | PWinGravity of Gravity Argument Description: The PPosition and PSize members are now obsolete and are left solely for compatibility reasons. The PMinSize member specifies the minimum window size that still allows the application to be useful. The PMaxSize member specifies the maximum window size. The PResizeInc member defines a size increment which the window prefers to be resized to. The two points in the PAspect member give minimum and maximum aspect ratios. They are expressed as ratios of x and y, and they allow an application to specify the range of aspect ratios it prefers. The PBaseSize member defines the desired size of the window. The PWinGravity member defines the region of the window that is to be retained when it is resized. Description: The XSetWMSizeHints function replaces the size hints for the specified property on the named window. If the specified property does not already exist, 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 XSetWMNormalHints function. 122 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 The XGetWMSizeHints function returns the size hints stored in the specified property on the named window. If the property is of type WM__SIZE__HINTS, of format 32, and is long enough to contain either an old (pre-ICCCM) or new size hints structure, XGetWM- SizeHints returns the list of fields that were supplied by the user. Otherwise, it returns the empty list. To get a window's normal size hints, you can use the XGetWMNormalHints function. If XGetWMSizeHints returns successfully and a pre-ICCCM size hints property is read, the list returned may contain the following members: [PPosition,PSize,PMinSize,PMaxSize,PResizeInc,PAspect] If the property is large enough to contain the base size and window gravity fields as well, the list returned may contain the following members: [PBaseSize,PWinGravity] The XSetWMNormalHints function replaces the size hints for the WM__NORMAL__HINTS property on the specified window. If the property does not already exist, 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. The 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, of format 32, and is long enough to contain either an old (pre- ICCCM) or new size hints structure, XGetWMNormalHints returns the list of fields that were supplied by the user. Otherwise, it returns the empty list. If XGetWMNormalHints returns successfully and a pre-ICCCM size hints property is read, the list returned may contain the following members: [PPosition,PSize,PMinSize,PMaxSize,PResizeInc,PAspect] If the property is large enough to contain the base size and window gravity fields as well, the list returned may contain the following members: [PBaseSize,PWinGravity] 2.17.12 XWMGeometry Types: val XWMGeometry: string -> string -> int -> XWMSizeHint list -> XPoint * XRectangle * Gravity Syntax: val (topLeft,area,gravity) = XWMGeometry userGeometry defaultGeometry borderWidth sizeHints ; Arguments: cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 123 userGeometry Specifies the user-specified geometry or empty string. borderWidth Specifies the border width. defaultGeometry Specifies the application's default geometry or empty string. sizeHints Specifies the size hints for the window in its normal state. topLeft Return the x and y offsets. area Return the width and height determined. gravity Returns the window gravity. Description: The XWMGeometry function combines any geometry information (given in the format used by 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 (NorthWestGravity, NorthEastGravity, SouthEastGravity or South- WestGravity) that describe the window. If the base size is not set in the XWMSizeHint list, the minimum size is used if set. Otherwise, a base size of 0 is assumed. If no minimum size is set in the hints list, the base size is used. Note that invalid geometry specifications can cause a width or height of 0 to be returned. 124 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 Chapter 3 Event Reference 3.1 XEvent Types: datatype 'a XEvent = ButtonPress of ... | ButtonRelease of ... | ButtonClick of ... | CirculateNotify of ... | CirculateRequest of ... | ColormapNotify of ... | ConfigureNotify of ... | ConfigureRequest of ... | CreateNotify of ... | DestroyNotify of ... | EnterNotify of ... | LeaveNotify of ... | Expose of ... | FocusIn of ... | FocusOut of ... | GraphicsExpose of ... | NoExpose of ... | GravityNotify of ... | KeymapNotify of ... | KeyPress of ... | KeyRelease of ... | MapNotify of ... | UnmapNotify of ... | MapRequest of ... | MotionNotify of ... | ReparentNotify of ... | ResizeRequest of ... | SelectionClear of ... | SelectionNotify of ... | SelectionRequest of ... | VisibilityNotify of ... | DeleteRequest of ... | Message of ... Description: The XEvent type is a union of the individual types returned for each different type of event. Event handlers typically pattern-match on the XEvent members, choosing to match events that they are interested in, and then a default pattern match to provide a default action for all other events. For example: fun Handler (Expose {window,region,...},state) = ... | Handler (EnterNotify {window,...},state) = ... | Handler (LeaveNotify {window,...},state) = ... | Handler (MotionNotify {window,pointer,...},state) = ... | Handler (_,state) = state ; (* default is to do nothing *) 125 126 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 All the event types have a sendEvent member which is set to true if the event came from a SendEvent protocol request. Most events also contain a time member, which is the time at which the event occurred. 3.2 ButtonPress, ButtonRelease, KeyPress, KeyRelease, MotionNotify Types: datatype Modifier = ShiftMask | LockMask | ControlMask | Mod1Mask | Mod2Mask | Mod3Mask | Mod4Mask | Mod5Mask | Button1Mask | Button2Mask | Button3Mask | Button4Mask | Button5Mask | AnyModifier ; datatype ButtonName = Button1 | Button2 | Button3 | Button4 | Button5 | AnyButton ; ButtonPress of { sendEvent: bool, window: Drawable, root: Drawable, subwindow: Drawable, time: int, pointer: XPoint, rootPointer: XPoint, modifiers: Modifier list, button: ButtonName } ButtonRelease of { sendEvent: bool, window: Drawable, root: Drawable, subwindow: Drawable, time: int, pointer: XPoint, rootPointer: XPoint, modifiers: Modifier list, button: ButtonName } ButtonClick of { sendEvent: bool, window: Drawable, root: Drawable, subwindow: Drawable, time: int, pointer: XPoint, rootPointer: XPoint, modifiers: Modifier list, button: ButtonName, up: int, (* number of up transitions *) down: int } (* number of down transitions *) KeyPress of { sendEvent: bool, window: Drawable, root: Drawable, cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 127 subwindow: Drawable, time: int, pointer: XPoint, rootPointer: XPoint, modifiers: Modifier list, keycode: int } KeyRelease of { sendEvent: bool, window: Drawable, root: Drawable, subwindow: Drawable, time: int, pointer: XPoint, rootPointer: XPoint, modifiers: Modifier list, keycode: int } MotionNotify of { sendEvent: bool, window: Drawable, root: Drawable, subwindow: Drawable, time: int, pointer: XPoint, rootPointer: XPoint, modifiers: Modifier list, isHint: bool } Description: These structures have the following common members: window, root, subwindow, time, pointer, rootPointer, and modifiers. The window member is set to the window on which the event was generated and is referred to as the event window. The root member is set to the source window's root window. The rootPointer member is set to the pointer's coordinates relative to the root window's origin at the time of the event. 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 member or an ancestor of it. Otherwise, the X server sets the subwindow member to NoDrawable. The time member is set to the time when the event was generated and is expressed in milliseconds. If the event window is on the same screen as the root window, the pointer member is set to the coordinates relative to the event window's origin. Otherwise, this member is set to (0,0). The modifiers member is set to indicate the state of the pointer buttons and modifier keys just prior to the event. It is a list of button or modifier key masks: Button1Mask, But- ton2Mask, Button3Mask, Button4Mask, Button5Mask, ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask. KeyPress and KeyRelease events have a member called 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. ButtonPress and ButtonRelease events have a member called button. It represents the pointer button that changed state and can be Button1, Button2, Button3, Button4, or Button5. The ButtonClick event can be used as an alternative to the ButtonPress and Button- Release combinations. It returns the number of up and down transitions of the pointer 128 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 button in a small predetermined time interval. In this way it is easy to detect double and triple clicks. MotionNotify events have a member called isHint. It can be set to true or false. 3.3 CirculateNotify Types: datatype Placement = PlaceOnTop | PlaceOnBottom ; CirculateNotify of { sendEvent: bool, event: Drawable, window: Drawable, place: Placement } Description: The event member is set either to the restacked window or to its parent, depending on whether StructureNotifyMask or SubstructureNotifyMask was selected. The win- dow member is set to the window that was restacked. The place member is set to the win- dow's position after the restack occurs and is either PlaceOnTop or PlaceOnBottom. If it is PlaceOnTop, the window is now on top of all siblings. If it is PlaceOnBottom, the window is now below all siblings. 3.4 CirculateRequest Types: datatype Placement = PlaceOnTop | PlaceOnBottom ; CirculateRequest of { sendEvent: bool, parent: Drawable, window: Drawable, place: Placement } Description: The parent member is set to the parent window. The window member is set to the sub- window to be restacked. The place member is set to what the new position in the stacking order should be and is either PlaceOnTop or PlaceOnBottom. If it is PlaceOnTop, the subwindow should be on top of all siblings. If it is PlaceOnBottom, the subwindow should be below all siblings. 3.5 ColormapNotify Types: cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 129 ColormapNotify of { sendEvent: bool, window: Drawable, colormap: Colormap, new: bool, installed: bool } Description: 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 XFreeColormap, the colormap member is set to NoColormap. The new member is set to indicate whether the colormap for the specified window was changed or installed or uninstalled and can be true or false. If it is true, the colormap was changed. If it is false, the colormap was installed or uninstalled. The installed member is always set to indicate whether the colormap is installed or uninstalled. 3.6 ConfigureNotify Types: ConfigureNotify of { sendEvent: bool, event: Drawable, window: Drawable, position: XPoint, size: XRectangle, borderWidth: int, above: Drawable, overrideRedirect: bool } Description: The event member is set either to the reconfigured window or to its parent, depending on whether StructureNotifyMask or SubstructureNotifyMask was selected. The window member is set to the window whose size, position, border, and/or stacking order was changed. The position member is set to the coordinates relative to the parent window's origin and indicates the position of the upper-left outside corner of the window. The size member is set to the inside size of the window, not including the border. The borderWidth member is set to the width of the window's border, in pixels. The above member is set to the sibling window and is used for stacking operations. If the X server sets this member to NoDrawable, 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. The overrideRedirect member is set to the override-redirect attribute of the window. Win- dow manager clients normally should ignore this window if the overrideRedirect member is true. 130 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 3.7 ConfigureRequest Types: datatype StackMode = Above | Below | TopIf | BottomIf | Opposite ; ConfigureRequest of { sendEvent: bool, parent: Drawable, window: Drawable, position: XPoint, size: XRectangle, borderWidth: int, above: Drawable, detail: StackMode } Description: 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. 3.8 CreateNotify Types: CreateNotify of { sendEvent: bool, parent: Drawable, window: Drawable, position: XPoint, size: XRectangle, borderWidth: int, overrideRedirect: bool } Description: The parent member is set to the created window's parent. The window member specifies the created window. The position member is set to the created window's coordinates relative to the parent window's origin and indicates the position of the upper-left outside corner of the created window. The size member is set to the inside size of the created window (not including the border) and is always nonzero. The borderWidth member is set to the width of the created window's border, in pixels. The overrideRedirect member is set to the override-redirect attribute of the window. Window manager clients normally should ignore this window if the overrideRedirect member is true. 3.9 DeleteRequest Types: DeleteRequest of { window: Drawable } cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 131 Description: This event is generated when the window manager tries to destroy a top level window. Instead of the window being destroyed the window manager sends this event to the ap- plication. The application can either ignore the event, or, typically, it can will perform some save operations and then destroy the window itself. The window member is set to the window that is to be destroyed. 3.10 DestroyNotify Types: DestroyNotify of { sendEvent: bool, event: Drawable, window: Drawable } Description: The event member is set either to the destroyed window or to its parent, depending on whether StructureNotifyMask or SubstructureNotifyMask was selected. The win- dow member is set to the window that is destroyed. 3.11 EnterNotify, LeaveNotify, NotifyMode, NotifyDetail Types: datatype NotifyMode = NotifyNormal | NotifyGrab | NotifyUngrab | NotifyWhileGrabbed ; datatype NotifyDetail = NotifyAncestor | NotifyVirtual | NotifyInferior | NotifyNonLinear | NotifyNonLinearVirtual | NotifyPointer | NotifyPointerRoot | NotifyDetailNone ; EnterNotify of { sendEvent: bool, window: Drawable, root: Drawable, subwindow: Drawable, time: int, pointer: XPoint, rootPointer: XPoint, mode: NotifyMode, detail: NotifyDetail, focus: bool, modifiers: Modifier list } LeaveNotify of { sendEvent: bool, window: Drawable, root: Drawable, subwindow: Drawable, 132 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 time: int, pointer: XPoint, rootPointer: XPoint, mode: NotifyMode, detail: NotifyDetail, focus: bool, modifiers: Modifier list } Description: The window member is set to the window on which the EnterNotify or 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. For a 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 NoDrawable. For an EnterNotify event, if a child of the event window contains the final pointer position, the subwindow component is set to that child or NoDrawable. The time member is set to the time when the event was generated and is expressed in milliseconds. The pointer member is 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, pointer is the pointer coordinates relative to the event window's origin. Otherwise, pointer is set to (0,0). The rootPointer member is set to the pointer's coordinates relative to the root window's origin at the time of the event. 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 true or false. If true, the event window is the focus window or an inferior of the focus window. If false, the event window is not the focus window or an inferior of the focus window. The modifiers member is set to indicate the state of the pointer buttons and modifier keys just prior to the event. It is a list of button or modifier key masks: Button1Mask, But- ton2Mask, Button3Mask, Button4Mask, Button5Mask, ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask. 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 NotifyNormal, NotifyGrab, or NotifyUngrab. The detail member is set to indicate the notify detail and can be NotifyAncestor, No- tifyVirtual, NotifyInferior, NotifyNonLinear, or NotifyNonLinearVirtual. 3.12 Expose Types: Expose of { sendEvent: bool, window: Drawable, region: XRectangle, count: int } cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 133 Description: The window member is set to the exposed (damaged) window. The region member is set to the damaged area within the window. The count member is set to the number of Expose events that are to follow. If count is zero, no more Expose events follow for this window. However, if count is nonzero, at least that number of 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 Expose events with nonzero counts and perform full redisplays on events with zero counts. 3.13 FocusIn, FocusOut Types: FocusIn of { sendEvent: bool, window: Drawable, mode: NotifyMode, detail: NotifyDetail } FocusOut of { sendEvent: bool, window: Drawable, mode: NotifyMode, detail: NotifyDetail } Description: The window member is set to the window on which the FocusIn or FocusOut event was generated. This is the window used by the X server to report the event. The mode mem- ber 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 NotifyNormal, NotifyWhileGrabbed, Notify- Grab, or NotifyUngrab. All FocusOut events caused by a window unmap are generated after any UnmapNotify event; however, the X protocol does not constrain the ordering of FocusOut events with respect to generated EnterNotify, LeaveNotify, VisibilityNotify, and Expose events. Depending on the event mode, the detail member is set to indicate the notify detail and can be NotifyAncestor, NotifyVirtual, NotifyInferior, NotifyNonLinear, Noti- fyNonLinearVirtual, NotifyPointer, NotifyPointerRoot, or NotifyDetailNone. 3.14 GraphicsExpose, NoExpose Types: datatype GraphicsCode = CopyArea | CopyPlane ; GraphicsExpose of { sendEvent: bool, window: Drawable, region: XRectangle, count: int, code: GraphicsCode } 134 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 NoExpose of { sendEvent: bool, window: Drawable, code: GraphicsCode } Description: Both structures have drawable and code as common members. The drawable member is set to the drawable of the destination region on which the graphics request was to be performed. The code member is set to the graphics request initiated by the client and can be either CopyArea or CopyPlane. If it is CopyArea, a call to XCopyArea initiated the request. If it is CopyPlane, a call to XCopyPlane initiated the request. The GraphicsExpose structure has these additional members: region, and count. The region member is set to the area within the drawable. The count member is set to the number of GraphicsExpose events to follow. If count is zero, no more GraphicsExpose events follow for this window. However, if count is nonzero, at least that number of GraphicsExpose events (and possibly more) are to follow for this window. 3.15 GravityNotify Types: GravityNotify of { sendEvent: bool, event: Drawable, window: Drawable, position: XPoint } Description: The event member is set either to the window that was moved or to its parent, depending on whether StructureNotifyMask or SubstructureNotifyMask was selected. The window member is set to the child window that was moved. The position member is set to the coordinates relative to the new parent window's origin and indicates the position of the upper-left outside corner of the window. 3.16 KeymapNotify Types: KeymapNotify of { sendEvent: bool, window: Drawable, keyVector: bool list (* 256 bools *) } Description: The keyVector member is set to the bit vector of the keyboard. The vector is returned as a list of 256 bools, representing the keys 0 to 255 in that order. Each bool set to true indicates that the corresponding key is currently pressed. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 135 3.17 MapNotify Types: MapNotify of { sendEvent: bool, event: Drawable, window: Drawable, overrideRedirect: bool } Description: The event member is set either to the window that was mapped or to its parent, depending on whether StructureNotifyMask or SubstructureNotifyMask was selected. The window member is set to the window that was mapped. The overrideRedirect 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 true, because these events usually are generated from pop-ups, which override structure control. 3.18 MapRequest Types: MapRequest of { sendEvent: bool, parent: Drawable, window: Drawable } Description: The parent member is set to the parent window. The window member is set to the window to be mapped. 3.19 Message Types: Message of { window: Drawable, message: 'a } ; Description: This event is received when a message is sent to a window. The only way to send a message to a window is to call the message-sender function returned by XSetHandler. This will only allow a strongly typed messages to be sent. 3.20 ReparentNotify Types: 136 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 ReparentNotify of { sendEvent: bool, event: Drawable, window: Drawable, parent: Drawable, position: XPoint, overrideRedirect: bool } Description: The event member is set either to the reparented window or to the old or the new par- ent, depending on whether StructureNotifyMask or SubstructureNotifyMask was selected. The window member is set to the window that was reparented. The parent member is set to the new parent window. The position member is set to the reparented window's coordinates relative to the new parent window's origin and defines the upper-left outer corner of the reparented window. The overrideRedirect 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 overrideRedirect member is true. 3.21 ResizeRequest Types: ResizeRequest of { sendEvent: bool, window: Drawable, size: XRectangle } Description: The window member is set to the window whose size another client attempted to change. The size member is set to the inside size of the window, excluding the border. 3.22 SelectionClear Types: SelectionClear of { sendEvent: bool, window: Drawable, selection: int, time: int } Description: The window member is set to the window losing ownership of the selection. The selection member is set to the selection atom. The time member is set to the last change time recorded for the selection. The owner member is the window that was specified by the current owner in its XSetSelectionOwner call. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 137 3.23 SelectionNotify Types: SelectionNotify of { sendEvent: bool, requestor: Drawable, selection: int, target: int, property: int, time: int } Description: The requestor member is set to the window associated with the requestor of the selec- tion. The selection member is set to the atom that indicates the selection. For example, XA__PRIMARY is used for the primary selection. The target member is set to the atom that indicates the converted type. For example, XA__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 zero. The time member is set to the time the conversion took place and can be a timestamp or CurrentTime. 3.24 SelectionRequest Types: SelectionRequest of { sendEvent: bool, owner: Drawable, requestor: Drawable, selection: int, target: int, property: int, time: int } Description: The owner member is set to the window owning the selection and is the window that was specified by the current owner in its 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, XA__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 zero. The time member is set to the time and is a timestamp or CurrentTime from the XConvertSelection request. 3.25 UnmapNotify Types: UnmapNotify of { sendEvent: bool, event: Drawable, window: Drawable, fromConfigure: bool } 138 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 Description: The event member is set either to the unmapped window or to its parent, depending on whether StructureNotifyMask or SubstructureNotifyMask 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 fromConfigure member is set to true if the event was generated as a result of a resizing of the window's parent when the window itself had a winGravity of UnmapGravity. 3.26 VisibilityNotify Types: datatype Visibility = VisibilityUnobscured | VisibilityPartiallyObscured | VisibilityObscured ; VisibilityNotify of { sendEvent: bool, window: Drawable, visibility: Visibility } Description: 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 VisibilityUnobscured, Visibil- ityPartiallyObscured, or VisibilityObscured. The X server ignores all of a window's subwindows when determining the visibility state of the window and processes Visibili- tyNotify events according to the following: When the window changes state from partially obscured, fully obscured, or not view- able to viewable and completely unobscured, the X server generates the event with the state member of the VisibilityNotify structure set to VisibilityUnobscured. 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 VisibilityNotify structure set to VisibilityPartiallyOb- scured. 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 VisibilityNotify structure set to VisibilityObscured. Chapter 4 Protocol Error Messages 4.1 BadAccess Description: XFreeColors pixel not allocated. XSelectInput selecting event that can only be selected by one client at a time, when another client already has it selected. XStoreColors pixel not allocated, or allocated read-only. XStoreNamedColor pixel not allocated, or allocated read-only. 4.2 BadAlloc Description: The server failed to allocate the requested resource. 4.3 BadAtom Description: A value for an atom argument does not name a defined atom. 4.4 BadColor Description: A value for a Colormap argument does not name a defined Colormap. ML type-checking should avoid this error. 139 140 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 4.5 BadCursor Description: A value for a Cursor argument does not name a defined Cursor. ML type-checking should avoid this error. 4.6 BadDrawable Description: A value for a Drawable argument does not name a defined Window or Pixmap. ML type-checking should avoid this error. 4.7 BadFont Description: A value for a Font argument does not name a defined Font. ML type-checking should avoid this error. 4.8 BadGC Description: A value for a GC argument does not name a defined GC. ML type-checking should avoid this error. 4.9 BadImplementation Description: The server does not implement some aspect of the request. This should never occur in Xlib since only standard requests are made. 4.10 BadIDChoice, BadLength Description: Internal Xlib error. cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 141 4.11 BadMatch Description: Some argument, or arguments, have the correct type and range, but fail to 'match' in some other way. XChangeWindowAtrributes Changing the background or border of an In- putOnlyClass window. XClearArea InputOnlyClass window specified. XClearWindow InputOnlyClass window specified. XConfigureWindow Sibling incorrectly specified, or changing the background or border of an InputOnlyClass window. XCopyArea The drawables must have the same root and depth. XCopyPlane The drawables must have the same root. XCreateColormap Visual type not supported, or bad Alloc- Type. XSetWindowColormap Colormap has different visual type to win- dow. XCreatePixmapCursor Masks must have depth of 1, and must be the same size, and the hotspot must be within that size. XChangeGC Tile pixmap must have the same root and depth as the GC. Stipple pixmap must have depth of 1 and must have the same root as the GC. Clip-mask pixmap must have depth of 1 and must have the same root as the GC. Us- ing a GC with a Drawable of different root or depth results in BadMatch. XPutImage If XYBitmap format is used, the depth must be 1. For XYPixmap and ZPixmap, the depth must match the depth of the drawable. XGetImage Specified area not within the source drawable. XGetSubImage Specified area not within the source drawable. XRestackWindows Specified window is not child window. XCreatePixmapFromBitmapData Depth must be supported by screen. XReparentWindow New parent is not on same screen as old par- ent. XSetClipRectangles Incorrect ordering. XSetInputFocus Focus window must be viewable. 142 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 4.12 BadPixmap Description: A value for a Pixmap does not name a defined Pixmap. ML type-checking should avoid this error. 4.13 BadRequest Description: This should never occur in Xlib since only standard requests are made. 4.14 BadValue Description: Some numeric value falls outside the range of values accepted by the request. XAllocColorCells Number of colours must be positive and planes must be non-negative. XAllocColorPlanes Number of colours must be positive, and reds, green and blues must be non-negative XFreeColors Specified pixel is not a valid index into the colormap. XBell Percent must be "100 to 100. XResizeWindow Window width must be non-zero. XCopyPlane Plane must have one bit set to 1, and specify an existing plane. XCreateGlyphCursor Source char and mask char must exist in the font. XSetDashes Dash elements must be positive and less than 256. XCreatePixmap Specified width must be non-zero, and depth must be sup- ported. XSetScreenSaver Incorrect timeout value. XStoreColors Specified pixel is not a valid index into the colormap. 4.15 BadWindow Description: A value for a Window does not name a defined Window. ML type-checking should avoid this error. Index A BitmapOpenFailed 97 Above 107, 130 BitmapPad 31 AboveOf 66, 67 BitmapStatus 96, 97 AddPoint 66 BitmapSuccess 97 AllocAll 24, 25 BitmapUnit 32 AllocNone 24, 25 BlackPixel 15, 16 AllocType 24, 141 Blanking 94 AllowExposures 11, 94 Bottom 67, 68 AllPlanes 31, 72 BottomIf 107, 130 Always 35, 100, 102, 103, 105 BottomLeft 67, 68 And 15 BottomRight 67, 68 AnyButton 126 Button1 126, 127 AnyModifier 126 Button1Mask 126, 127, 132 ArcChord 51, 75, 76 Button1MotionMask 54 ArcPieSlice 51, 75, 76 Button2 126, 127 Area 43, 46, 49, 51, 67, 68, 97 Button2Mask 126, 127, 132 Button2MotionMask 54 Button3 126, 127 B Button3Mask 126, 127, 132 BackingStore 35, 100, 102, 105 Button3MotionMask 54 BadAccess 19, 22, 106, 139 Button4 126, 127 BadAlloc 139 Button4Mask 126, 127, 132 BadAtom 139 Button4MotionMask 54 BadColor 139 Button5 126, 127 BadCursor 140 Button5Mask 126, 127, 132 BadDrawable 140 Button5MotionMask 54 BadFont 49, 140 ButtonClick 125, 126, 127 BadGC 140 ButtonClickMask 54 BadIDChoice 140 ButtonMotionMask 54 BadImplementation 140 ButtonName 126 BadLength 140 ButtonPress 54, 125, 126, 127 BadMatch 24, 25, 29, 40, 41, 42, 57, 74, ButtonPressMask 54, 106 75, 76, 78, 83, 84, 89, 97, 100, 101, ButtonRelease 125, 126, 127 106, 107, 112, 141 ButtonReleaseMask 54 BadPixmap 142 ByteOrder 32 BadRequest 142 BadValue 18, 19, 22, 29, 42, 75, 79, 94, 96, 98, 107, 108, 142 C BadWindow 142 CapButt 73, 74, 82 Below 107, 130 CapNotLast 73, 74, 82 BelowOf 66, 67 CapProjecting 73, 74, 82 BitmapBitOrder 31 CapRound 73, 74, 82 BitmapFileInvalid 97 CellsOfScreen 32 BitmapNoMemory 97 CenterGravity 102, 103 143 144 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 CharAscent 59, 60 CWWinGravity 100, 105 CharAttributes 59 CharDescent 59, 60 CharLBearing 59 D CharRBearing 59 Data 87 CharWidth 59, 60 DefaultBlanking 94 CirculateDirection 110, 111 DefaultColormap 22 CirculateNotify 111, 125, 128 DefaultDepth 22, 23 CirculateRequest 54, 111, 125, 128 DefaultExposures 94 ClipByChildren 40, 75, 84 DefaultGC 70 ColormapChangeMask 54 DefaultVisual 34 ColormapExists 33 DeleteRequest 125, 130 ColormapID 33 DestroyNotify 101, 125, 131 ColormapNotify 25, 26, 105, 125, 128 DestructArea 67, 68 Complex 49, 50 DestructRect 67 ConfigureNotify 125, 129 DirectColor 18, 19, 23, 24, 25 ConfigureRequest 54, 108, 111, 112, 125, DisplayCells 23 130 DisplayConnected 34 ControlDown 52, 53 DisplayHeight 34 ControlMask 53, 126, 127, 132 DisplayHeightMM 34 Convex 49, 50 DisplayPlanes 35 CoordMode 45, 46, 49 DisplayString 35 CoordModeOrigin 45, 46, 49, 50 DisplayWidth 34 CoordModePrevious 45, 46, 49, 50 DisplayWidthMM 34 CopyArea 42, 133, 134 DoesBackingStore 35 CopyFromParentClass 99, 100, 102 DoesSaveUnders 36 CopyFromParentDrawable 37, 105, 106 DontAllowExposures 94 CopyFromParentVisual 37, 100 DontCareState 117, 118 CopyPlane 133, 134 DontPreferBlanking 94 CreateNotify 100, 101, 125, 130 DrawableExists 14, 33 CurrentTime 56, 57, 93, 137 DrawableID 33 CursorExists 14, 33 CursorID 33 E CursorShape 39, 40 EastGravity 102, 103 CWBackingPixel 100, 105 EnterNotify 55, 125, 131, 132, 133 CWBackingPlanes 100, 105 EnterWindowMask 54 CWBackingStore 100, 105 EvenOddRule 75, 80 CWBackPixel 100, 105 EventMask 36, 54, 100, 102, 105 CWBackPixmap 100, 105 EventMaskOfScreen 36 CWBitGravity 100, 105 Expose 40, 41, 55, 68, 95, 101, 107, 108, CWBorderPixel 100, 105 109, 111, 112, 113, 125, 132, 133 CWBorderPixmap 100, 105 ExposureMask 54 CWBorderWidth 107 Exposures 94 CWColormap 100, 105 CWCursor 100, 105 CWDontPropagate 100, 105 F CWEventMask 100, 105 FillOpaqueStippled 42, 74, 80 CWOverrideRedirect 100, 105 FillSolid 44, 74, 80 CWPosition 107 FillStippled 74, 80 CWSaveUnder 100, 105 FillTiled 11, 74, 80 CWSibling 107 FocusChangeMask 54 CWSize 107 FocusIn 57, 125, 133 CWStackMode 107 FocusOut 57, 125, 133 cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 145 FontDirection 59, 60, 61, 64 GrayScale 18, 23, 24, 25, 27, 29 FontExists 14, 33 GXand 71 FontID 33 GXandInverted 71 FontLeftToRight 61, 62, 65 GXandReverse 71 FontRightToLeft 61, 62, 65 GXclear 71 ForgetGravity 102, 103 GXcopy 41, 44, 71 FSAllCharsExist 59 GXcopyInverted 71 FSAscent 59 GXequiv 71 FSDefaultChar 59 GXinvert 71 FSDescent 59 GXnand 71 FSDirection 59 GXnoop 71 FSFont 59 GXnor 71 FSMaxBounds 59, 60 GXor 71 FSMaxByte1 59 GXorInverted 71 FSMaxChar 59 GXorReverse 71 FSMaxHeight 59, 60 GXset 71 FSMaxWidth 59, 60 GXxor 71 FSMinBounds 59, 60 FSMinByte1 59 FSMinChar 59 H FSMinHeight 59, 60 Height 67, 68 FSMinWidth 59, 60 HorizontallyAbutting 66, 67 G IconicState I 117, 118 GCArcMode 71, 75, 76 IconMaskHint 117, 118 GCBackground 71 IconPixmapHint 117, 118 GCCapStyle 71, 73, 82 IconPositionHint 117, 118 GCClipMask 71 IconWindowHint 117, 118 GCClipOrigin 71 ImageByteOrder 85 GCDashList 71 ImageData 87 GCDashOffset 71 ImageDepth 85 GCExists 14, 33 ImageFormat 86, 87, 88 GCFillRule 71, 75, 79, 80 ImageOrder 31, 32, 85, 87 GCFillStyle 71, 74, 80 ImageSize 85 GCFont 71 InactiveState 117, 118 GCForeground 71 IncludeInferiors 75, 84 GCFunction 71, 81, 83 IncludePoint 69 GCGraphicsExposures 71 InputFocus 37 GCID 33 InputHint 117 GCJoinStyle 71, 73, 82 InputOnlyClass 41, 96, 99, 100, 101, 102, GCLineStyle 71, 73, 82 103, 104, 106, 107, 141 GCLineWidth 71 InputOutputClass 75, 99, 100, 101, 102, GCOrder 77, 78 103, 109 GCPlaneMask 71, 72 Inside 66, 67 GCStipple 71 Intersection 67 GCSubwindowMode 71, 75, 84 IsCursorKey 52 GCTile 71 IsFunctionKey 52 GCTSOrigin 71 IsKeypadKey 52 GraphicsCode 133 IsMiscFunctionKey 52 GraphicsExpose 41, 75, 82, 125, 133, 134 IsModifierKey 52 Gravity 100, 102, 105, 121, 122 IsPFKey 52 GravityNotify 125, 134 IsUnmapped 102, 103 146 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 IsUnviewable 102, 103 NoDrawable 28, 37, 40, 41, 56, IsViewable 102, 103 57, 59, 75, 77, 78, 93, 97, 105, 106, 110, 127, 129, 132 NoExpose 41, 82, 125, 133 J NoFont 28, 37, 48, 49 JoinBevel 73, 82 Nonconvex 49, 50 JoinMiter 11, 73, 82 NormalState 117, 118 JoinRound 73, 82 NorthEastGravity 102, 103, 123 NorthGravity 102, 103 K NorthWestGravity 102, 103, 123 KeymapNotify 125, 134 NoSymbol 53 KeymapStateMask 54 Not 15, 52 KeyPress 125, 126, 127 Nothing 67 KeyPressMask 54 NotifyAncestor 131, 132, 133 KeyRelease 125, 126, 127 NotifyDetail 131, 133 KeyReleaseMask 54 NotifyDetailNone 131, 133 NotifyGrab 131, 132, 133 NotifyInferior 131, 132, 133 L NotifyMode 131, 133 LeaveNotify 55, 125, 131, 132, 133 NotifyNonLinear 131, 132, 133 LeaveWindowMask 54 NotifyNonLinearVirtual 131, 132, 133 Left 67, 68 NotifyNormal 131, 132, 133 LeftOf 66, 67 NotifyPointer 131, 133 LineDoubleDash 73, 74, 82 NotifyPointerRoot 131, 133 LineOnOffDash 73, 74, 82 NotifyUngrab 131, 132, 133 LineSolid 73, 74, 82 NotifyVirtual 131, 132, 133 LockMask 126, 127, 132 NotifyWhileGrabbed 131, 133 LowerHighest 111, 112 NotUseful 35, 100, 102, 103 LSBFirst 31, 32, 85, 87 NoVisual 37 NullHandler 55 M MakeRect 68, 69 O MapNotify 109, 125, 135 OffsetRect 69 MapRequest 54, 109, 125, 135 Opposite 107, 130 MapState 102 Or 15 MaxCmapsOfScreen 37 OutsetRect 69 Message 56, 125, 135 Overlap 66, 67 MinCmapsOfScreen 36 OwnerGrabButtonMask 54 Mod1Mask 126, 127, 132 Mod2Mask 126, 127, 132 P Mod3Mask 126, 127, 132 ParentRelative 37, 105, 106, 112 Mod4Mask 126, 127, 132 PAspect 121, 122 Mod5Mask 126, 127, 132 PBaseSize 121, 122 Modifier 52, 53, 109, 126, 131 Pixel 16 MotionNotify 55, 125, 126, 128 Placement 128 MSBFirst 31, 32, 85, 87 PlaceOnBottom 128 PlaceOnTop 128 N PMaxSize 121, 122 NegativePoint 69 PMinSize 121, 122 NoColormap 25, 37, 102, 103, 129 PointerMotionHintMask 54 NoCursor 29, 30, 37, 106 PointerMotionMask 54 PointerRoot 37, 56, 57, 118 cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 147 PointerWindow 37 ScreenSaverActive 94, 95 PolyShape 49 ScreenSaverReset 94, 95 PPosition 121, 122 Section 67 PreferBlanking 94 SelectionClear 93, 125, 136 PResizeInc 121, 122 SelectionNotify 93, 125, 137 PropertyArc 91 SelectionRequest 93, 125, 137 PropertyAtom 91 ServerVendor 38 PropertyBitmap 91 ShapeClass 39 PropertyChangeMask 54 ShiftDown 52, 53 PropertyColormap 91 ShiftMask 53, 126, 127, 132 PropertyCursor 91 SouthEastGravity 102, 103, 123 PropertyDrawable 91 SouthGravity 102, 103 PropertyFont 91 SouthWestGravity 102, 103, 123 PropertyInteger 91 SplitRect 68, 69 PropertyPixmap 91 StackMode 107, 130 PropertyPoint 91 StateHint 117, 118 PropertyRectangle 91 StaticColor 23, 24, 25 PropertyRGBColormap 91 StaticGravity 102, 103 PropertyString 91 StaticGray 23, 24, 25, 29 PropertyValue 91 StippleShape 39, 40 PropertyVisual 91 StructureNotifyMask 54, 128, 129, 131, 134, PropertyWindow 91 135, 136, 138 PropertyWMHints 91 SubstructureNotifyMask 54, 128, 129, 131, PropertyWMIconSizes 91 134, 135, 136, 138 PropertyWMSizeHints 91 SubstructureRedirectMask 54, 106, 108, ProtocolRevision 37, 38 109, 111, 112 ProtocolVersion 38 SubtractPoint 66 PseudoColor 18, 19, 23, 24, 25 PSize 121, 122 PSPerChar 59, 60 T PWinGravity 121, 122 TileShape 39, 40 Top 67, 68 TopIf 107, 130 R TopLeft 67, 68 RaiseLowest 111, 112 TopRight 67, 68 Rect 51, 67, 68 TrueColor 23, 24, 25 Reflect 70 ReparentNotify 112, 125, 135 ResizeRedirectMask 54, 106 U ResizeRequest 54, 125, 136 Union 67 RevertCode 56 UnmapGravity 102, 103, 138 RevertToNone 56, 57 UnmapNotify 113, 125, 133, 137 RevertToParent 56, 57 Unsorted 78 RevertToPointerRoot 56, 57 RGB_COLOR_MAP 27, 28 V RGB_DEFAULT_MAP 27, 28 VendorRelease 39 Right 67, 68 VerticallyAbutting 66, 67 RightOf 66, 67 Visibility 138 RootWindow 38 VisibilityChangeMask 54 VisibilityNotify 125, 133, 138 S VisibilityObscured 138 SameDrawable 33 VisibilityPartiallyObscured 138 SaveMode 94 VisibilityUnobscured 138 148 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 VisualBlueMask 86 XConfigureWindow 106, 107, 141 VisualClass 23, 24 XConvertSelection 92, 93, 137 VisualExists 33 XCopyArea 41, 75, 82, 134, 141 VisualGreenMask 86 XCopyColormapAndFree 24, 25 VisualID 33 XCopyPlane41, 42, 75, 82, 96, 134, 141, 142 VisualRedMask 86 XCreateBitmapFromData 96, 97 XCreateColormap 24, 25, 27, 141 W XCreateFontCursorXCreateGC 28 71, 76,* * 78 WestGravity 102, 103 XCreateGlyphCursor 28, 29, 142 WhenMapped 35, 100, 102, 103, 105 XCreateImage 86, 87 WhitePixel 15, 16 XCreatePixmap 95, 96, 142 Width 67, 68 XCreatePixmapCursor 28, 29, 141 WindingRule 75, 80 XCreatePixmapFromBitmapData 96, 97, WindowClass 99, 100, 102 141 Within 66, 67 XCreateSimpleWindow 26, 99, 101 WM_CLASS 115, 120 XCreateWindow 25, 26, 99, 100 WM_CLIENT_MACHINE 92, 115, 120 XDefineCursor 29, 30, 100 WM_COLORMAP_WINDOWS 116 XDeleteProperty 90 WM_COMMAND 92, 117, 120 XDestroySubwindows 101 WM_HINTS 118, 120 XDestroyWindow 13, 101 WM_ICON_NAME 92, 119, 120 XDrawArc 42, 43 WM_NAME 92, 119, 120 XDrawArcs 42, 43 WM_NORMAL_HINTS 120, 122, 123 XDrawImageString 44, 48 WM_SIZE_HINTS 121, 122 XDrawImageString16 44 WM_TRANSIENT_FOR 114 XDrawLine 45 XDrawLines 11, 45 X XDrawPoint 46 XActivateScreenSaver 94, 95 XDrawPoints 46 XAddPixel 86, 88 XDrawRectangle 46, 47 XAllocColor 17, 18, 19, 20, 25 XDrawRectangles 46, 47 XAllocColorCells 17, 18, 19, 25, 142 XDrawSegments 45 XAllocColorPlanes 17, 18, 19, 25, 27, 142 XDrawString 47, 48 XAllocNamedColor 17, 18, 19, 20, 25 XDrawString16 47 XArc 42, 43, 49, 91 XDrawText 48, 49 XAutoRepeatOff 98 XDrawText16 48, 49 XAutoRepeatOn 98 XEvent 55, 56, 125 XA_PIXMAP 137 XFillArc 49, 51 XA_PRIMARY 11, 93, 137 XFillArcs 49, 51, 75 XA_SECONDARY 93 XFillPolygon 49, 50, 75 XA_STRING 11, 117 XFillRectangle 49, 50 XA_WINDOW 116 XFillRectangles 49, 50 XBell 98, 142 XFlush 57, 58 XChangeGC 71, 76, 78, 141 XFontStruct 48, 59, 60, 61, 62, 63, 64, 65, XChangeWindowAttributes 25, 26, 104, 105 66 XCharStruct 59, 60, 61, 62, 63, 64, 65 XForceScreenSaver 94, 95 XCirculateSubwindows 110, 111, 112 XFreeColormap 13, 24, 25, 129 XCirculateSubwindowsDown 110, 111, 112 XFreeColors 13, 17, 19, 25, 139, 142 XCirculateSubwindowsUp 110, 111 XFreeCursor 13, 30 XClearArea 40, 41, 141 XFreeFont 29, 61, 64 XClearWindow 40, 41, 105, 141 XFreeGC 13, 71, 76 XColor 13, 16, 17, 18, 19, 20, 21, 22, 24, 28, XFreePixmap 13, 95, 96, 97 29, 30 XGCValue 71 cOAbstract Hardware Ltd 1991,1994 X Reference 1.1 149 XGetAtomName 90, 91 XQueryBestStipple 39, 40 XGetDefault 20, 98, 99 XQueryBestTile 39, 40 XGetFontPath 64 XQueryColor 19, 20 XGetGeometry 101, 102, 104 XQueryColors 19, 20 XGetIconSizes 113, 114 XQueryFont 61, 63 XGetImage 88, 89, 141 XQueryKeymap 98 XGetInputFocus 56, 57 XQueryPointer 109, 110 XGetPixel 86, 88 XQueryTree 104, 110 XGetRGBColormaps 26, 28 XRaiseWindow 110, 111 XGetScreenSaver 94, 95 XReadBitmapFile 96, 97 XGetSelectionOwner 92, 93 XRecolorCursor 29, 30 XGetSubImage 88, 89, 141 XReparentWindow 112, 141 XGetTextProperty 91, 92, 115, 119 XResetScreenSaver 94, 95 XGetTransientForHint 114 XResizeWindow 106, 108, 142 XGetWindowAttributes 101, 102, 104 XRestackWindows 110, 111, 112, 141 XGetWindowBorderWidth 104 XSelectInput 54, 139 XGetWindowChildren 104 XSendSelectionNotify 92, 93, 94 XGetWindowDepth 104 XSetArcMode 76 XGetWindowParent 104 XSetBackground 76 XGetWindowPosition 104 XSetClipMask 77, 78 XGetWindowRoot 104 XSetClipOrigin 77 XGetWindowSize 104 XSetClipRectangles 75, 76, 77, 78, 141 XGetWMClass 114, 115 XSetColours 78 XGetWMClientMachine 115 XSetDashes 75, 76, 79, 142 XGetWMColormapWindows 116 XSetFillRule 79, 80 XGetWMCommand 116, 117 XSetFillStyle 80 XGetWMHints 117, 118 XSetFont 80 XGetWMIconName 118, 119 XSetFontPath 61, 64 XGetWMName 119 XSetForeground 81 XGetWMNormalHints 121, 122 XSetFunction 81 XGetWMSizeHints 121, 122 XSetGraphicsExposures 81, 82 XImage 85, 86, 87, 88, 89 XSetHandler 52, 55, 56, 135 XInstallColormap 25, 26, 105 XSetIconSizes 113, 114 XInternAtom 90, 91 XSetInputFocus 56, 57, 141 XListFonts 60, 61 XSetLineAttributes 82 XListFontsWithInfo 60, 61 XSetPlaneMask 82 XListInstalledColormaps 25, 26 XSetProperty 91, 92, 115, 119 XLoadFont 61, 63 XSetRGBColormaps 26, 27 XLoadQueryFont 11, 61, 63 XSetScreenSaver 94, 95, 142 XLookupColor 19, 20 XSetSelectionOwner 92, 93, 136, 137 XLookupString 53 XSetState 83 XLowerWindow 110, 111 XSetStipple 83 XMapRaised 108, 109 XSetSubwindowMode 84 XMapSubwindows 108, 109 XSetTile 84 XMapWindow 100, 108, 109 XSetTransientForHint 114 XMoveResizeWindow 106, 108 XSetTSOrigin 85 XMoveWindow 106, 107 XSetWindowAttributes 99, 100, 104, 105 Xor 15 XSetWindowBackground 104, 105, 106 XParseColor 20 XSetWindowBackgroundPixmap 104, 105, XPutImage 88, 89, 97, 141 106 XPutPixel 86, 88 XSetWindowBorder 104, 105, 106 XQueryBestCursor 39, 40 XSetWindowBorderPixmap 104, 105, 106 XQueryBestSize 39, 40 XSetWindowBorderWidth 106, 108 150 X Reference 1.1 Oc Abstract Hardware Ltd 1991,1994 XSetWindowColormap 11, 24, 25, 26, 141 XSetWMClass 114, 115, 120 XSetWMClientMachine 115 XSetWMColormapWindows 116 XSetWMCommand 116, 117, 120 XSetWMHints 114, 117, 118, 120 XSetWMIconName 118, 119, 120 XSetWMName 119, 120 XSetWMNormalHints 120, 121, 122 XSetWMProperties 119, 120 XSetWMSizeHints 121 XStandardColormap 26, 27, 91 XStoreColor 19, 20, 21, 22 XStoreColors 19, 21, 22, 139, 142 XStoreNamedColor 19, 21, 22, 139 XSubImage 86, 88 XSync 57, 58 XSyncronise 58 XTextExtents 44, 64, 65 XTextExtents16 64, 65 XTextItem 48 XTextItem16 48, 49 XTextWidth 65, 66 XTextWidth16 65, 66 XTranslateCoordinates 58, 59 XUndefineCursor 29, 30 XUninstallColormap 25, 26 XUnloadFont 13, 61, 63, 64 XUnmapSubwindows 113 XUnmapWindow 113 XWindowAttributes 101, 102, 104 XWindowChanges 106, 107 XWindows 18, 19, 20, 21, 26, 33, 34, 51, 52, 61, 63, 64, 88, 89, 91, 92, 99, 100, 101, 104, 110, 114, 116, 117, 119 XWMGeometry 122, 123 XWMHint 91, 117, 119, 120 XWMSizeHint 91, 119, 120, 121, 122, 123 XWMStateHint 117 XWriteBitmapFile 96, 97 XYBitmap 87, 88, 89, 141 XYPixmap 87, 88, 89, 141 Y YSorted 78 YXBanded 78 YXSorted 78 Z ZoomState 117, 118 ZPixmap 87, 88, 89, 141