File: XWindows.txt

package info (click to toggle)
polyml 5.6-8
links: PTS, VCS
area: main
in suites: stretch
size: 31,892 kB
ctags: 34,453
sloc: cpp: 44,983; ansic: 24,520; asm: 14,850; sh: 11,730; makefile: 551; exp: 484; python: 253; awk: 91; sed: 9
file content (10261 lines) | stat: -rw-r--r-- 417,712 bytes
parent folder | download | duplicates (5)


 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.

       "<functionName> failed"                                            Xlib  detected  an  error  condition  when
                                                                          executing <functionName>

       "Bad<className> in <functionName>"                                 The  X  server  detected  an  error  con-
                                                                          dition  occurred  when  executing  <func-
                                                                          tionName>.     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