



 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

