(navigation image)
Home American Libraries | Canadian Libraries | Universal Library | Community Texts | Project Gutenberg | Children's Library | Biodiversity Heritage Library | Additional Collections
Search: Advanced Search
Anonymous User (login or join us)
Upload
See other formats

Full text of "Xlib Reference Manual for Version 11 Vol. 2"

The Definitive Guides 
to the X Window System 



Volume Two 



Xlib Reference 
Manual 

for Version 11 



O Reilly & Associates, Inc. 



Volume Two 



Xlib Reference 
Manual 



for Version 11 of the 
X Window System 

edited by Adrian Nye 



O Reilly & Associates, Inc. 



Copyright 1988,1989,1990 O Reilly & Associates, Inc. 
All Rights Reserved 

The X Window System is a trademark of the Massachusetts Institute of Technology. 
UNIX is a registered trademark of AT&T. 

Revision and Printing History 

August 1988: First Printing. 

November 1988: Second Printing. Minor revisions. 

May 1989: Third Printing. Release 3 updates added. Minor revisions. 

April 1990: Second Edition covers Release 3 and Release 4. Major revisions. 

July 1990: Fifth Printing. Minor revisions. 

Small Print 

This document is based in part on Xlib-C Language X Interface, by Jim Gettys, Ron Newman, and Robert Scheifler, 
and the X Window System Protocol, Version 11, by Robert Scheifler and Ron Newman, both of which are copyright 
1985, 1986, 1987 the Massachusetts Institute of Technology, Cambridge, Massachusetts, and Digital Equipment 
Corporation, Maynard, Massachusetts. In addition, we have included some material provided in Oliver Jones Xlib 
Tutorial Overheads, which was distributed at the MIT X Conference in January 1988 and which is copyright 1987 
Apollo Computer, Inc. Appendix F is based on the Inter-Client Communication Conventions Manual by David 
Rosenthal, which is copyright 1988 Sun Microsystems, Inc. 

We have used this material under the terms of its copyright, which grants free use, subject to the following condi 
tions: 

"Permission to use, copy, modify and distribute this documentation (i.e., the original MIT, 
DEC, Sun Microsystems, or Apollo material) for any purpose and without fee is hereby 
granted, provided that the above copyright notice appears in all copies and that both that 
copyright notice and this permission notice appear in supporting documentation, and that the 
name of MTT, Apollo, Digital, or Sun not be used in advertising or publicity pertaining to 
distribution of the software without specific, written prior permission. MIT and Digital make 
no representations about the suitability of the software described herein for any purpose. It 
is provided as is without expressed or implied warranty." 

Note, however, that those portions of this document that are based on the original XI 1 documentation and other 
source material have been significantly revised and that all such revisions are copyright 1987, 1988, 1989, 1990 
O Reilly & Associates, Inc. Inasmuch as the proprietary revisions cannot be separated from the freely copyable MTT 
source material, the net result is that copying of this document is not allowed. Sorry for the doublespeak! 

While every precaution has been taken in the preparation of this book, we assume no responsibility for errors or 
omissions. Neither is any liability assumed for damages resulting from the use of the information contained herein. 

Volume 2: ISBN 0-937175-12-9 Set: ISBN 0-937175-13-7 



The X Window System 

The books in the X Window System Series are based in part on the original MIT X Window System 
documentation, but are far more comprehensive, easy to use, and are loaded with examples, tutorials 
and helpful hints. Over 20 major computer vendors recommend or license volumes in the series. In 
short, these are the definitive guides to the X Window System. 

Volume 0: 

X Protocol Reference Manual 

A complete programmer s reference to the X Network Protocol, the language of communication 
between the X server and the X clients. 498 pages. $30.00. 

Volumes 1 and 2: 

Xlib Programming Manual 

Xlib Reference Manual 

Revised for Release 4. Complete guide and reference to programming with the X library (Xlib), the 
lowest level of programming interface to X. 672 and 792 pages. $60.00 for the set. or $34.95 each. 

Volume 3: 

X Window System User s Guide 

Revised and enlarged for X 1 1 Release 4. Describes window system concepts and the most common 
client applications available for X 1 1 . Includes complete explanation of the new window manager, 
fww, and a chapter on Motif. For experienced users, later chapters explain customizing the X envi 
ronment. Useful with either Release 3 or Release 4. 749 pages. $30.00. 

Volumes 4 and 5: 

X Toolkit Intrinsics Programming Manual 

X Toolkit Intrinsics Reference Manual 

Complete guides to programming with the X Toolkit. The Programming Manual provides concepts 
and examples for using widgets and for the more complex task of writing new widgets. The Reference 
Manual provides reference pages for Xt functions, and Xt and Athena widgets. 582 and 545 pages. 
$55.00 for the set, or $30.00 each. 

Volume 7: 

XView Programming Manual 

XView is an easy-to-use toolkit that is not just for Sun developers. It is available on MIT s R4 tape 
and System V Release 4, as well as being a part of Sun s Open Windows package. This manual 
provides complete information on XView, from concepts to creating applications to reference pages. 
566 pages. $30.00. 

The X Window System in a Nutshell 

For the experienced X programmer, contains essential information from other volumes of the series 
in a boiled-down, quick reference format that makes it easy to find the answers needed most often. 380 
pages. $24.95. 

For orders or a free catalog of all our books, please contact us. 



O Reilly & Associates, Inc. 



Creators and Publishers of Nutshell Handbooks 

632 Petaluma Avenue. Sebastopol. CA 95472 

email: uunet!ora!nuts 1-800-338-6887 1-707-829-0515 FAX 1-707-829-0104 



Table of Contents 



Page 



Preface xvii 

About This Manual xvii 

Summary of Contents xvii 

How to Use This Manual xviii 

Example Programs xix 

Assumptions xx 

Font Conventions Used in This Manual xx 

Related Documents xxi 

Requests for Comments xxi 

Bulk Sales Information xxii 

Acknowledgements xxii 



Permuted Index .. ... i 



Xlib Function Reference 33 

Introduction 33 

XActivateScreenSaver 35 

XAddHost 36 

XAddHosts 38 

XAddPixel 40 

XAddToSaveSet 42 

XAllocClassHint 43 

XAllocColor 44 

XAllocColorCells 46 

XAllocColorPlanes 48 

XAllocIconSize 50 

XAllocNamedColor 51 

XAllocSizeHints 53 

XAllocStandardColormap 54 

XAllocWMHints 55 

XAllowEvents 56 

XAutoRepeatOff 59 

XAutoRepeatOn 60 

XBell 61 

XChangeActivePointerGrab 62 



XChangeGC 63 

XChangeKeyboardControl 65 

XChangeKeyboardMapping 67 

XChangePointerControl 69 

XChangeProperty 71 

XChangeSaveSet 73 

XChange Window Attributes 74 

XChecklffivent 77 

XCheckMaskEvent 78 

XCheckTypedEvent 79 

XCheckTypedWindowEvent 80 

XCheckWindowEvent 81 

XCirculateSubwindows 82 

XCirculateSubwindowsDown 83 

XCirculateSubwindowsUp 84 

XClearArea 85 

XClearWindow 87 

XClipBox 88 

XCloseDisplay 89 

XConfigure Window 90 

XConvertSelection 94 

XCopyArea 95 

XCopyColormapAndFree 97 

XCopyGC 98 

XCopyPlane 100 

XCreateAssocTable 102 

XCreateBitmapFromData 103 

XCreateColormap 105 

XCreateFontCursor 107 

XCreateGC 109 

XCreateGlyphCursor 112 

XCreatelmage 114 

XCreatePixmap 116 

XCreatePixmapCursor 117 

XCreatePixmapFromBitmapData 119 

XCreateRegion 121 

XCreateSimple Window 122 

XCreateWindow 124 

XDefineCursor 127 

XDeleteAssoc 128 

XDeleteContext 129 

XDeleteModifiermapEntry 130 

XDeleteProperty 132 

XDestroyAssocTable 133 

XDestroylmage 134 

XDestroyRegion 135 

XDestroySubwindows 136 

XDestroyWindow 137 



vl 



XDisableAccessControl 138 

XDisplayKeycodes 139 

XDisplayName 140 

XDraw 141 

XDrawArc 143 

XDrawArcs 146 

XDrawFilled 149 

XDrawImageString 150 

XDrawImageStringl6 152 

XDrawLine 154 

XDrawLines 155 

XDrawPoint 157 

XDrawPoints 158 

XDrawRectangle 160 

XDrawRectangles 162 

XDrawSegments 164 

XDrawString 166 

XDrawStringl6 168 

XDrawText 170 

XDrawTextl6 172 

XEmptyRegion 174 

XEnableAccessControl 175 

XEqualRegion 176 

XEventsQueued 177 

XFetchBuffer 178 

XFetchBytes 179 

XFetchName 180 

XFillArc 181 

XFillArcs 183 

XFillPolygon 185 

XFillRectangle 187 

XFillRectangles 189 

XFindContext 191 

XFlush 192 

XForceScreenSaver 193 

XFree 194 

XFreeColormap 195 

XFreeColors 196 

XFreeCursor 197 

XFreeExtensionList 198 

XFreeFont 199 

XFreeFondnfo 200 

XFreeFontNames 201 

XFreeFontPath 202 

XFreeGC 203 

XFreeModifiermap 204 

XFreePixmap 205 

XFreeStringList 206 



vii 



XGContextFromGC 207 

XGeometry 208 

XGetAtomName 210 

XGetClassHint 211 

XGetDefault 212 

XGetErrorDatabaseText 214 

XGetEnorText 216 

XGelFontPath 217 

XGetFontProperty 218 

XGetGCValues 219 

XGetGeometry 221 

XGetlconName 222 

XGetlconSizes 223 

XGetlmage 225 

XGetlnputFocus 227 

XGetKeyboardControl 228 

XGetKeyboardMapping 229 

XGetModifierMapping 231 

XGetMotionEvents 232 

XGetNormalHints 234 

XGetPixel 236 

XGetPointerControl 238 

XGetPointerMapping 239 

XGetRGBColormaps 240 

XGetScreenSaver 242 

XGetSelectionOwner 243 

XGetSizeHints 244 

XGetStandardColormap 246 

XGetSublmage 248 

XGetTextProperty 250 

XGetTransientForHint 252 

XGetVisuallnfo 253 

XGetWMIconName 255 

XGetWMName 256 

XGetWMNormalHints 257 

XGetWMSizeHints 259 

XGetWindowAttributes 261 

XGetWindowProperty 264 

XGetWMHints 267 

XGetZoomHints 268 

XGrabButton 270 

XGrabKey 273 

XGrabKeyboard 275 

XGrabPointer 277 

XGrabServer 280 

XlconifyWindow 281 

XlfEvent 282 

XlnsertModifiermapEntry 283 



via 



XInstallColormap 285 

XInternAtom 287 

XIntersectRegion 289 

XKeycodeToKeysym 290 

XKeysymToKeycode 291 

XKeysymToString 292 

XKillClient 293 

XListDepths 294 

XListExtensions 295 

XListFonts 296 

XListFontsWithlnfo 297 

XListHosts 299 

XListlnstalledColormaps 300 

XListPixmapFormats 301 

XListProperties 302 

XLoadFont 303 

XLoadQueryFont 304 

XLookUpAssoc 306 

XLookupColor 307 

XLookupKeysym 309 

XLookupString 311 

XLowerWindow 313 

XMakeAssoc 314 

XMapRaised 315 

XMapSubwindows 316 

XMapWindow 317 

XMaskEvent 318 

XMatchVisuallnfo 319 

XMoveResizeWindow 320 

XMoveWindow 321 

XNewModifiermap 322 

XNextEvent 323 

XNoOp 324 

XOffsetRegion 325 

XOpenDisplay 326 

XParseColor 328 

XParseGeometry 330 

XPeekEvent 331 

XPeeklfEvent 332 

XPending 333 

Xpermalloc 334 

XPointlnRegion 335 

XPolygonRegion 336 

XPutBackEvent 337 

XPutlmage 338 

XPutPixel 340 

XQueryBestCursor 342 

XQueryBestSize 343 



XQueryBestStipple 345 

XQueryBestTile 346 

XQueryColor 347 

XQueryColors 348 

XQueryExtension 349 

XQueryFont 350 

XQueryKeymap 352 

XQueryPointer 353 

XQueryTextExtents 355 

XQueryTextExtentsl6 357 

XQueryTree 359 

XRaise Window 360 

XReadBitmapFile 361 

XRebindKeysym 363 

XRecolorCursor 364 

XReconfigureWMWindow 365 

XRecanRegion 367 

XRefreshKeyboardMapping 368 

XRemoveFromSaveSet 369 

XRemoveHost 370 

XRemoveHosts 372 

XReparentWindow 374 

XResetScreenSaver 376 

XResizeWindow 377 

XRestackWindows 378 

XrmDestroyDatabase 379 

XrmGetFileDatabase 380 

XrmGetResource 381 

XrmGetStringDatabase 385 

Xrmlnitialize 386 

XrmMergeDatabases 387 

XrmParseCommand 388 

XrmPutFileDatabase 391 

XrmPutLineResource 392 

XrmPutResource 394 

XrmPutStringResource 395 

XrmQGetResource 396 

XrmQGetSearchList 398 

XrmQGetSearchResource 400 

XrmQPutResource 402 

XrmQPutStringResource 404 

XrmQuarkToString 406 

XrmSlringToBindingQuarkList 407 

XrmStringToQuark 409 

XrmStringToQuarkList 410 

XrmUniqueQuark 412 

XRotateBuffers 413 

XRotateWindowProperties 414 



XSaveContext 416 

XSelectlnput 417 

XSendEvent 419 

XSetAccessControl 421 

XSetAfterFunction 422 

XSetArcMode 423 

XSetBackground 425 

XSetClassHint 426 

XSetClipMask 427 

XSetClipOrigin 428 

XSetClipRectangles 429 

XSetCloseDownMode 431 

XSetCommand 432 

XSetDashes 433 

XSetErrorHandler 435 

XSetFillRule 437 

XSetFillStyle 439 

XSetFont 441 

XSetFontPath 442 

XSetForeground 443 

XSetFunction 444 

XSetGraphicsExposures 446 

XSetlconName 447 

XSetlconSizes 448 

XSetlnputFocus 449 

XSetlOErrorHandler 451 

XSetLineAttributes 452 

XSetModifierMapping 454 

XSetNormalHints 456 

XSetPlaneMask 458 

XSetPointerMapping 459 

XSetRGBColormaps 460 

XSetRegion 462 

XSetScreenSaver 463 

XSetSelectionOwner 465 

XSetSizeHints 467 

XSetStandardColormap 469 

XSetStandardProperties 471 

XSetState 473 

XSetStipple 474 

XSetSubwindowMode 475 

XSctTcxtProDcrtv 476 

XSetTile 477 

XSetTransientForHint 478 

XSetTSOrigin 479 

XSetWMClientMachine 480 

XSetWMColormapWindows 481 

XSetWMIconName 482 



xi 



XSetWMName 483 

XSetWMNormalHints 484 

XSetWMProperties 486 

XSetWMProtocols 489 

XSetWMSizeHints 490 

XSetWindowBackground 492 

XSetWindowBackgroundPixmap 493 

XSetWindowBorder 495 

XSetWindowBorderPixmap 496 

XSetWindowBorderWidth 497 

XSetWindowColormap 498 

XSetWMHints 499 

XSetZoomHints 501 

XShrinkRegion 503 

XStoreBuffer 504 

XStoreBytes 505 

XStoreColor 506 

XStoreColors 507 

XStoreName 508 

XStoreNamedColor 509 

XStringListToTextProperty 510 

XStringToKeysym 511 

XSublmage 512 

XSubtractRegion 513 

XSync 514 

XSynchronize 515 

XTextExtents 516 

XTextExtentsl6 518 

XTextPropertyToStringList 520 

XTextWidth 521 

XTextWidthl6 522 

XTranslateCoordinates 523 

XUndefineCursor 524 

XUngrabButton 525 

XUngrabKey 526 

XUngrabKeyboard 527 

XUngrabPointer 528 

XUngrabServer 529 

XUninstallColormap 530 

XUnionRectWithRegion 531 

XUnionRegion 532 

XUniqueContext 533 

XUnloadFont 534 

XUnmapSubwindows 535 

XUnmapWindow 536 

XVisuallDFrom Visual 537 

XWMGeometry 538 

XWarpPointer 540 



xii 



XWindowEvent 542 

XWithdrawWindow 543 

XWriteBitmapFile 544 

XXorRegion ,... 545 



Appendix A: Function Group Summary 547 

Group Listing with Brief Descriptions 547 

Alphabetical Listing of Routines ... 563 



Appendix B: Error Messages and Protocol Requests 573 



Appendix C: Macros 581 

Display Macros 582 

Image Format Macros 586 

Keysym Classification Macros 586 

Resource Manager Macros 586 



Appendix D: The Color Database 589 

Appendix E: Event Reference 599 

Meaning of Common Structure Elements 601 

ButtonPress, ButtonRelease 603 

CirculateNotify 605 

CirculateRequest 606 

ClientMessage 607 

ColormapNotify 608 

ConfigureNotify 609 

ConfigureRequest 611 

CreateNotify 613 

DestroyNotify 615 

EnterNotify, LeaveNotify 616 

Extx) sc *.................... 622 

Focusln, FocusOut 624 

GraphicsExpose, NoExpose 630 

GravityNotify 632 

KeymapNotify 633 

KeyPress, KeyRelease 634 

MapNotify, UnmapNotify 636 

MappingNotify 638 



xiii 



MapRequest 640 

MotionNotify 641 

PropertyNotify 643 

ReparentNotify 644 

ResizeRequest 645 

SelectionClear 646 

SelectionNotify 647 

SelectionRequest 648 

VisibilityNotify 649 



Appendix F: Structure Reference 651 

Description of Header Files 651 

Resource Types 652 

Structure Definitions ... .... 652 



Appendix G: Symbol Reference 665 

Appendix H: Keysyms 691 

Keysyms and Description 692 

Appendix I: The Cursor Font 709 

Appendix J: The Xmu Library 711 

XctCreate 712 

XctFree 714 

XctNextltem 715 

XctReset 717 

XmuAddCloseDisplayHook 718 

XmuAllStandardColormaps 719 

XmuClientWindow 712 

XmuComparelSOLatinl 722 

XmuCopylSOLatinlLowered 723 

XmuCopylSOLatinlUppered 724 

XmuCreateColormap 725 

XmuCreatePixmapFromBitmap 726 

XmuCreateStippledPixmap 727 

XmuCursorNameToIndex 728 

XmuDQAddDisplay 729 

XmuDQCreate 730 

XmuDQDestroy 731 



xiv 



XmuDQLookupDisplay 732 

XmuDQNDisplays 733 

XmuDQRemoveDisplay 734 

XmuDeleteStandardColormap 735 

XmuDrawLogo 736 

XmuDrawRoundedRectangle 737 

XmuFillRoundedRectangle 738 

XmuGetAtomName 739 

XmuGetColormapAllocation 740 

XmuGetHostname 741 

XmuInternAtom 742 

XmuInternStrings 743 

XmuLocateBitmapFile 744 

XmuLookup* 745 

XmuLookupCloseDisplayHook 747 

XmuLookupStandardColormap 748 

XmuMakeAtom 750 

XmuNameOfAtom 751 

XmuPrintDefaultErrorMessage 752 

XmuReadBitmapData 753 

XmuReadBitmapDataFromFile 754 

XmuReleaseStippledPixmap 755 

XmuRemoveCloseDisplayHook 756 

XmuScreenOfWindow 757 

XmuSimpleError Handler 758 

XmuStandardColormap 759 

XmuUpdateMapHints 760 

XmuVisualStandardColormaps 761 



Window Attributes At-a-glance 763 

GC At-a-glance 765 



XV 



Preface 



About This Manual 

This manual describes the X library, the C Language programming interface to Version 1 1 of 
the X Window System. The X library, known as Xlib, is the lowest level of programming 
interface to X. This library enables a programmer to write applications with an advanced 
user interface based on windows on the screen, with complete network transparency, that will 
run without changes on many types of workstations and personal computers. 

Xlib is powerful enough to write effective applications without additional programming tools 
and is necessary for certain tasks even in applications written with higher-level "toolkits." 

There are a number of these toolkits for X programming, the most notable being the 
DEC/MIT toolkit Xt, the Andrew toolkit developed by IBM and Carnegie-Mellon University, 
and the Interviews toolkit from Stanford. These toolkits are still evolving, and only Xt is 
currently part of the X standard. Toolkits simplify the process of application writing con 
siderably, providing a number of widgets that implement menus, command buttons, and other 
common features of the user interface. 

This manual does not describe Xt or any other toolkit. That is done in Volumes Four, Five, 
and Six of our X Window System series. Nonetheless, much of the material described in this 
book is helpful for understanding and using the toolkits, since the toolkits themselves are 
written using Xlib and allow Xlib code to be intermingled with toolkit code. 



Summary of Contents 

This manual is divided into two volumes. This is the second volume, the Xlib Reference 
Manual. It includes reference pages for each of the Xlib functions (organized alphabeti 
cally), a permuted index, and numerous appendices and quick reference aids. 

The first volume, the Xlib Programming Manual, provides a conceptual introduction to Xlib, 
including tutorial material and numerous programming examples. Arranged by task or topic, 
each chapter brings together a group of Xlib functions, describes the conceptual foundation 
they are based on, and illustrates how they are most often used in writing applications (or, in 
the case of the last chapter, in writing window managers). Volume One is structured so as to 
be useful as a tutorial and also as a task-oriented reference. 



Preface 



Volume One and Volume Two are designed to be used together. To get the most out of the 
examples in Volume One, you will need the exact calling sequences of each function from 
Volume Two. To understand fully how to use each of the functions described in Vol 
ume Two, all but the most experienced X "hacker" will need the explanation and examples in 
Volume One. 

Both volumes include material from the original Xlib and XI 1 Protocol documentation pro 
vided by MIT, as well as from other documents provided on the MIT release tape. We have 
done our best to incorporate all of the useful information from the MIT documentation, to 
correct references we found to be in error, to reorganize and present it in a more useful form, 
and to supplement it with conceptual material, tutorials, reference aids, and examples. In 
other words, this manual is not only a replacement but is a superset of the MIT documenta 
tion. 

Those of you familiar with the MIT documentation will recognize that each reference page in 
Volume Two includes the detailed description of the routine found in Gettys, Newman, and 
Scheifler s Xlib-C Language X Interface, plus, in many cases, additional text that clarifies 
ambiguities and describes the context in which the routine would be used. We have also 
added cross references to related reference pages and to where additional information can be 
found in Volume One. 



How to Use This Manual 

Volume Two is designed to make it as easy and fast as possible to look up virtually any fact 
about Xlib. It includes a permuted index, reference pages for each library function, appen 
dices that cover macros, structures, function groups, events, fonts, colors, cursors, keysyms, 
and errors, and at-a-glance tables for the graphics context and window attributes. 

The permuted index is the standard UNIX way of finding a particular function name given a 
keyword. By looking up a word in the second column that you think describes the function 
you are looking for, you can find the group of functions that have that word in their descrip 
tion lines. The description line also appears at the top of each reference page. Once you 
have found the routine you are looking for, you can look for its reference page. 

The reference pages themselves provide all the details necessary for calling each routine, 
including its arguments, returned values, definitions of the structure types of arguments and 
returned values, and the errors it may generate. Many of the pages also give hints about how 
the routine is used in the context of other routines. This is the part of this volume you will 
use the most. 

Appendix A, Function Group Summary, groups the routines according to function, and pro 
vides brief descriptions. You ll find it useful to have in one place a description of related 
routines, so their differences can be noted and the appropriate one chosen. 

Appendix B, Error Messages and Protocol Requests, describes the errors that Xlib routines 
can generate. When an error is handled by the default error handler, one of these messages is 
printed. Also printed is the X Protocol request that caused the error. Since Protocol requests 
do not map directly to Xlib routines, this appendix provides a table with which you can find 
out which Xlib routine in your code caused the error. 



Xlib Reference Manual 



Appendix C, Macros, describes the macros that access members of the Display structure, 
classify keysyms, and convert resource manager types. 

Appendix D, ColorCaEE, presents the standard color database. The color names in this data 
base should be available on all servers, though the corresponding RGB values may have been 
modified to account for screen variations. 

Appendix E, Event Reference, describes each event type and structure, in a reference page 
format. This is an invaluable reference for event programming. 

Appendix F, Structure Reference, describes all structures used by Xlib except the event struc 
tures described in Appendix E, including which routines use each structure. 

Appendix G, Symbol Reference, lists in alphabetical order and describes all of the symbols 
defined in Xlib include files. 

Appendix H, Keysym Reference, lists and describes each character in the standard keysym 
families, used for translating keyboard events. The characters for English and foreign lan 
guage keysyms are shown where possible. 

Appendix I, The Cursor Font, describes the standard cursor font, including a illustration of 
the font shapes. 

Appendix J, The Xmu Library, provides reference pages for each function in the miscella 
neous utilities library. This library is provided with the standard X distribution and is very 
useful when programming with Xlib. 

Finally, Volume Two concludes with at-a-glance charts that help in setting the graphics con 
text (GC) and the window attributes. 



Example Programs 

The example programs in this book are on the XI 1 Release 4 distribution in the contributed 
section. There are many ways of getting this distribution; most are described in Appendix H. 

The example programs are also available free from UUNET (that is, free except for UUNET s 
usual connect-time charges). If you have access to UUNET, you can retrieve the source code 
using uucp orftp. For uucp, find a machine with direct access to UUNET and type the follow 
ing command: 

uucp uunet\ ! ~uucp/nutshell/Xlib/xlibprgs.tar .Z yourhosW /yourname/ 

The backslashes can be omitted if you use the Bourne shell (sh) instead of csh. The file 
should appear some time later (up to a day or more) in the directory lusrlspoolluucp- 
publicl yourname. 

To ustftp,ftp to uunet.uu.net and use anonymous as your user name and guest as your pass 
word. Then type the following: 

cd /nutshell/Xlib 

binary ( you must specify binary transfer for compressed files ) 

get xlibprgs.tar.Z 

bye 



Preface 



xix 



The file is a compressed tar archive. To restore the files once you have retrieved the archive, 
type: 

uncompress xlibprgs.tar 
tar xvf xlibprgs.tar 

The example programs are also available free by/fp from expo.lcs.mit.edu. The directory 
containing the examples is contriblexampleslOReillylXlib . 

The examples will be installed in subdirectories under the current directory, one for each 
chapter in the book. Imakefiles are included. (Imakefiles are used with imake, a program 
supplied with the XI 1 distribution that generates proper Makefiles on a wide variety of sys 
tems.) 

Assumptions 

Readers should be proficient in the C programming language, although examples are pro 
vided for infrequently used features of the language that are necessary or useful when pro 
gramming with X. In addition, general familiarity with the principles of raster graphics will 
be helpful. 

Font Conventions Used in This Manual 



Italic is used for: 

UNIX pathnames, filenames, program names, user command names, and options for user 
commands. 

New terms where they are defined. 

Typewriter Font is used for: 

Anything that would be typed verbatim into code, such as examples of source code and 
text on the screen. 

The contents of include files, such as structure types, structure members, symbols 
(defined constants and bit flags), and macros. 

Xlib functions. 

Names of subroutines of the example programs. 

Italic Typewri ter Fon t is used for: 

Arguments to Xlib functions, since they could be typed in code as shown but are arbi 
trary. 

Helvetica Italics are used for: 

Titles of examples, figures, and tables. 



xx Xlib Reference Manual 



Boldface is used for: 

Chapter and section headings. 

Related Documents 

The C Programming Language by B. W. Kernighan and D. M. Ritchie 
The following documents are included on the XI 1 source tape: 

Xt Toolkit Intrinsics by Joel McCormack, Paul Asente, and Ralph Swick 

Xt Toolkit Widgets by Ralph Swick and Terry Weissman 

Xlib-C Language X Interface by Jim Gettys, Ron Newman, and Robert Scheifler 

X Window System Protocol, Version 11 by Robert Scheifler 

The following books on the X Window System are available from O Reilly and Associates, 
Inc.: 

Volume Zero X Protocol Reference Manual 

Volume Three X Window System User s Guide 

Volume Four X Toolkit Intrinsics Programming Manual 

Volume Five X Toolkit Intrinsics Reference Manual 

Volume Six X Toolkit Widgets Reference Manual (available summer 1990) 

Volume Seven XView Programmer s Guide 

Quick Reference The X Window System in a Nutshell 

Requests for Comments 

Please write to tell us about any flaws you find in this manual or how you think it could be 
improved, to help us provide you with the best documentation possible. 

Our U.S. mail address, e-mail address, and telephone number are as follows: 

O Reilly and Associates, Inc. 
632 Petaluma Avenue 
Sebastopol, CA 95472 
(800) 338-6887 

UUCP: uunet!ora!adrian ARPA: adrian@ora.UU.NET 



Preface xxi 



Bulk Sales Information 

This manual is being resold as the official X Window System documentation by many work 
station manufacturers. For information on volume discounts for bulk purchase, call Linda 
Walsh at O Reilly and Associates, Inc., at 617-354-5800, or send e-mail to linda@ora.com. 

For companies requiring extensive customization of the book, source licensing terms are also 
available. 



Acknowledgements 

The information contained in this manual is based in part on Xlib-C Language X Interface, 
written by Jim Gettys, Ron Newman, and Robert Scheifler, and the X Window System Proto 
col, Version 11, by Robert Scheifler (with many contributors). The X Window System soft 
ware and these documents were written under the auspices of Project Athena at MIT. In 
addition, this manual includes material from Oliver Jones Xlib tutorial presentation, which 
was given at the MIT X Conference in January 1988, and from David Rosenthal s Inter- 
Client Communication Conventions Manual. 

I would like to thank the people who helped this book come into being. It was Tim O Reilly 
who originally sent me out on a contract to write a manual for X Version 10 for a workstation 
manufacturer and later to another company to write a manual for X Version 11, from which 
this book began. I have learned most of what I know about computers and technical writing 
while working for Tim. For this book, he acted as an editor, he helped me reorganize several 
chapters, he worked on the Color and Managing User Preferences chapters when time was 
too short for me to do it, and he kept my spirits up through this long project. While I was 
concentrating on the details, his eye was on the overall presentation, and his efforts improved 
the book enormously. 

This book would not be as good (and we might still be working on it) had it not been for 
Daniel Gilly. Daniel was my production assistant for critical periods in the project. He dealt 
with formatting issues, checked for consistent usage of terms and noticed irregularities in 
content, and edited files from written corrections by me and by others. His job was to take as 
much of the work off me as possible, and with his technical skill and knowledge of UNIX, he 
did that very well. 

This manual has benefitted from the work and assistance of the entire staff of O Reilly and 
Associates, Inc. Susan Willing was responsible for graphics and design, and she proofed 
many drafts of the book; Linda Mui tailored the troff macros to the design by Sue Willing 
and myself and was invaluable in the final production process; John Strang figured out the 
resource manager and wrote the original section on that topic; Karen Cakebread edited a 
draft of the manual and established some conventions for terms and format. Peter Mui exe 
cuted the "at-a-glance" tables for the inside back cover; Tom Scanlon entered written edits 
and performed copy fitting; Donna Woonteiler wrote the index of the book, Valerie Quercia, 
Tom Van Raalte, and Linda Walsh all contributed in some small ways; and Cathy Brennan, 
Suzanne Van Hove, and Jill Berlin fielded many calls from people interested in the X manual 
and saved me all the time that would have taken. Ruth Terry, Lenny Muellner, and Donna 



xxii Xlib Reference Manual 



Woonteiler produced the Second Edition, with graphics done by Chris Reilly. A special 
thanks to everyone at O Reilly and Associates for putting up with my habits of printer and 
terminal hogging, lugging X books around, recycling paper, and for generally being good at 
what they do and good-natured to boot. 

Many people sent in corrections for this Second Edition of the manual. Those whose efforts 
were most noteworthy were Jane-Na Chang of NEC, Jonathan Saunders of Identification and 
Security Systems Inc., Saundra Miller, and Russell Ferriday. 

I would also like to thank the people from other companies that reviewed the book or other 
wise made this project possible: John Posner, Barry Kingsbury, Jeff MacMann and Jeffrey 
Vroom of Stellar Computer; Oliver Jones of Apollo Computer; Sam Black, Jeff Graber, and 
Janet Egan of Masscomp; Al Tabayoyon, Paul Shearer, and many others from Tektronix; 
Robert Scheifler and Jim Fulton of the X Consortium (who helped with the Color and 
Managing User Preferences chapters), and Peter Winston II and Aub Harden of Integrated 
Computer Solutions. Despite the efforts of the reviewers and everyone else, any errors that 
remain are my own. 

Adrian Nye 



Preface 



Permuted Index 



How to Use the Permuted Index 

The permuted index takes the brief descriptive string from the title of each command page 
and rotates (permutes) the string so that each keyword will at one point start the second, or 
center, column of the line. The beginning and end of the original string are indicated by a 
slash when they are in other than their original position; if the string is too long, it is trun 
cated. 

To find the command you want, simply scan down the middle of the page, looking for a key 
word of interest on the right side of the blank gutter. Once you find the keyword you want, 
you can read (with contortions) the brief description of the command that makes up the entry. 
If things still look promising, you can look all the way over to the right for the name of the 
relevant command page. 

The Permuted Index 



for string and font metrics of a 16-bit character string /server XQueryTextExtents 1 6 

/get string and font metrics of a 16-bit character string, locally XTextExtentsl6 

/get the width in pixels of a 1 6-bit character string, locally XTextWidth 1 6 

XDrawImageStringl6: draw 16-bit image text characters XDrawImageStringl6 

XDrawTextl6: draw 16-bit polytext strings XDrawTextl6 

/get the width in pixels of an 8-bit character string, locally XTextWidth 

XDrawImageString: draw 8-bit image text characters XDrawImageString 

XDrawText: draw 8-bit polytext strings XDrawText 

only XDrawString: draw an 8-bit text string, foreground XDrawString 

/disable or enable access control XSetAccessControl 

XAddHost: add a host to the access control list XAddHost 

add multiple hosts to the access control list XAddHosts: XAddHosts 

/remove a host from the access control list XRemoveHost 

/remove multiple hosts from the access control list XRemoveHosts 

deny/ XEnableAccessControl: use access control list to allow or XEnableAccessControl 

XDisableAccessControl: allow access from any host XDisableAccessControl 

/obtain a b st of hosts having access to this display XListHosts 

XActivateScreenSaver: activate screen blanking XActivateScreenSaver 

release the keyboard from an active grab XUngrabKeyboard: XUngrabKeyboard 

release the pointer from an active grab XUngrabPointer: XUngrabPointer 

/change the parameters of an active pointer grab XChangeActivePointerGrab 

pixel value in an/ XAddPixel: add a constant value to every XAddPixel 

b st XAddHost: add a host to the access control XAddHost 



Permuted Index 



XInsertModifiermapEntry: add a new entry to an/ XInsertModifiermapEntry 

XUnionRectWithRegion: add a rectangle to a region XUnionRectWithRegion 

a/ XrmQPutStringResource: add a resource specification to XrmQPutStringResource 

a resource/ XrmPutLineResource: add a resource specification to XrmPutLineResource 

with/ XrmPutStringResource: add a resource specification XrmPutStringResource 

save-set XAddToSaveSet: add a window to the client s XAddToSaveSet 

control list XAddHosts: add multiple hosts to the access XAddHosts 

the client s/ XChangeSaveSet: add or remove a sub window from XChangeSaveSet 

XrmUniqueQuark: allocate a new quark XrmUniqueQuark 

from color/ XAUocNamedColor: aUocate a read-only colorcell XAUocNamedColor 

cell with closest/ XAUocColor: aUocate a read-only colormap XAllocColor 

XAllocClassHint: allocate an XClassHint structure XAUocClassHint 

XAllocIconSize: allocate an XlconSize structure XAllocIconSize 

XAllocSizeHints: allocate an XSizeHints structure XAllocSizeHints 

XAllocStandardColormap: allocate an XStandardColormap/ XAllocStandardColormap 

XAllocWMHints: aUocate an XWMHints structure XAllocWMHints 

structure XCreatelmage: allocate memory for an Xlmage XCreatelmage 

freed Xpermalloc: allocate memory never to be Xpermalloc 

XAllocColorPlanes: aUocate read/write/ XAUocColorPlanes 

colorceUs XAUocColorCeUs: aUocate read/write (nonshared) XAUocColorCeUs 

XFree: free specified memory aUocated by an Xlib function XFree 

XFreeFontPath: free the memory aUocated by XGetFontPath XFreeFontPath 

XFreeFontNames: free the memory aUocated by XListFonts XFreeFontNames 

XFreeFontlnfo: free the memory aUocated by XListFonts Withlnfo XFreeFontlnfo 

XFreeExtensionList: free memory aUocated for a list of/ XFreeExtensionList 

table, /free the memory aUocated for an association XDestroyAssocTable 

XDisableAccessControl: aUow access from any host XDisableAccessControl 

/use access control Ust to aUow or deny connection/ XEnableAccessControl 

colormap; instaU default if not already instaUed /uninstaU a XUninstaUColormap 

XLoadFont: load a font if not already loaded; get font ID XLoadFont 

contents of one database into another /merge the XrmMergeDatabases 

subtract one region from another XSubtractRegion: XSubtractRegion 

system from one window to another /change the coordinate XTranslateCoordinates 

/move the pointer to another point on the screen XWarpPointer 

/insert a window between another window and its parent XReparentWindow 

into a drawable with depth, applying pixel values /drawable XCopyPlane 

/convert a keysym to the appropriate keycode XKeysymToKeycode 

XFiUArc: fdl an arc XFiUArc 

XDrawArc: draw an arc fitting inside a rectangle XDrawArc 

XSetArcMode: set the arc mode in a graphics context XSetArcMode 

XDrawArcs: draw multiple arcs XDrawArcs 

XFiUArcs: fiU multiple arcs XFiUArcs 

fiU a rectangular area XFiURectangle: XFillRectangle 

XClearArea: clear a rectangular area in a window XClearArea 

XCopyArea: copy an area of a drawable XCopyArea 

fiU multiple rectangular areas XFillRectangles: XFillRectangles 

database from command line arguments /load a resource XrmParseCommand 

XA_WM_COMMAND atom (command line arguments) XSetCommand: set the XSetCommand 

properties in the properties array /rotate XRotateWindowProperties 

/obtain RGB values for an array of colorceUs XQueryColors 

/look up RGB values from ASCII color name or translate/ XParseColor 

/map a key event to ASCII string, keysym, and/ XLookupString 

XDefineCursor: assign a cursor to a window XDefineCursor 

the window manager XStoreName: assign a name to a window for XStoreName 

/deaUocate storage associated with a region XDestroyRegion 

/change a property associated with a window XChangeProperty 

XDestroylmage: deallocate memory associated with an image XDestroylmage 

/the GContext (resource ID) associated with the specified/ XGContextFromGC 



Xlib Reference Manual 



/the XStandardColoimap structure associated with the specified/ XGetRGBColormaps 

string/ /free the in-memory data associated with the specified XFreeStringLast 

/delete an entry from an association table XDeleteAssoc 

/free the memory allocated for an association table XDestroyAssocTable 

obtain data from an association table XLookUpAssoc: XLookUpAssoc 

create an entry in an association table XMakeAssoc: XMakeAssoc 

XCreateAssocTable: create a new association table (X10) XCreateAssocTable 

name for a property given its atom XGetAtomName: get a string XGetAtomName 

get a font property given its atom XGetFontProperty: XGetFontProperty 

/set the XA_WM_COMMAND atom (command line arguments) XSetCommand 

string XInternAtom: return an atom for a given property name XInternAtom 

XGetWindowProperty: obtain the atom type and property format/ XGetWindowProperty 

/a window border pixel value attribute and repaint the border XSetWindowBorder 

/change a window border tile attribute and repaint the border XSetWindowBorderPixmap 

/set the colormap attribute for a window XSetWindowColormap 

/set the background pixel value attribute of a window XSetWindowBackground 

/change the background tile attribute of a window XSetWindowBackgroundPixmap 

/set window attributes XChangeWindow Attributes 

create a window and set attributes XCreateWindow: XCreate Window 

/obtain the current attributes of window XGetWindow Attributes 

/turn off the keyboard auto-repeat keys X AutoRepeatOff 

turn on the keyboard auto-repeat keys XAutoRepeatOn: XAutoRepeatOn 

XPutBackEvent: push an event back on the input queue XPutBackEvent 

XSetState: set the foreground, background, logical function,/ XSetState 

XSetWindowBackground: set the background pixel value attribute/ XSetWindowBackground 

XSelBackground: set the background pixel value in a/ XSetBackground 

window /change the background tile attribute of a XSetWindowBackgroundPixmap 

XAllowEvents: control the behavior of keyboard and pointer/ X AUowEvents 

XBell: ring the bell (Control G) XBell 

or/ XQueryBestSize: obtain the "best" supported cursor, tile, XQueryBestSize 

XReparentWindow: insert a window between another window and its/ XReparentWindow 

/calculate the difference between the union and/ XXorRegion 

XDrawLine: draw a line between two points XDrawLine 

XDraw: draw a polyline or curve between vertex list (from X10) XDraw 

/convert a key string to a binding list and a quark list XrmStringToBindingQuarkList 

of the/ XQueryKeymap: obtain a bit vector for the current state XQueryKeymap 

/create a pixmap with depth from bitmap data XCreatePixmapFromBitmapData 

/create a bitmap from XI 1 bitmap format data XCreateBitmapFromData 

XReadBitmapFile: read a bitmap from disk XReadBitmapFile 

XCreateBitmapFromData: create a bitmap from XI 1 bitmap format/ XCreateBitmapFromData 

XWriteBitmapFile: write a bitmap to a file XWriteBitmapFile 

create a cursor from two bitmaps XCreatePixmapCursor: XCreatePixmapCursor 

graphics/ XSetFunction: set the bitwise logical operation in a XSetFunction 

activate screen blanking XActivateScreenSaver: XActivateScreenSaver 

value attribute and repaint the border /a window border pixel XSetWindowBorder 

tile attribute and repaint the border /change a window border XSetWindowBorderPixmap 

repaint the/ /change a window border pixel value attribute and XSetWindowBorder 

repaint the/ /change a window border tile attribute and XSetWindowBorderPixmap 

/change the border width of a window XSetWindowBorderWidth 

/the window position, size, border width, or stacking order XConfigureWindow 

/remove the next event matching both passed window and passed/ XCheckWindowEvent 

stacking order /circulate the bottom child to the top of the XCirculateSubwindowsDown 

/circulate the top child to the bottom of the stacking order XCirculateSubwindowsUp 

return data from a cut buffer XFetchBuffen XFetchBuffer 

from pointer motion history buffer /get events XGetMotionEvents 

store data in a cut buffer XStoreBuffer: XStoreBuffer 

return data from cut buffer XFetchBytes: XFetchBytes 

XStoreBytes: store data in cut buffer XStoreBytes 



Permuted Index 



XPending: flush the request buffer and return the number of/ XPending 

and/ XSync: flush the request buffer and wait for all events XSync 

XFlush: flush the request buffer (display all queued/ XFlush 

XRotateBuffers: rotate the cut buffers XRotateBuffers 

XGrabButton: grab a pointer button XGrabButton 

XUngrabButton: release a button from a passive grab XUngrabButton 

/get the pointer button mapping XGetPointerMapping 

/set the pointer button mapping XSetPointerMapping 

of a given GC from Xlib s GC cache /obtain components XGetGCValues 

the union and/ XXorRegion: calculate the difference between XXorRegion 

user geometry string/ XGeometry: calculate window geometry given XGeometry 

/set a function called after all Xlib functions XSetAfterFunction 

allocate a read-only colormap cell with closest/ XAllocColon XAllocColor 

with a window XChangeProperty: change a property associated XChangeProperty 

value/ XSetWindowBorder: change a window border pixel XSetWindowBorder 

XSetWindowBorderPixmap: change a window border tile/ XSetWindowBorderPixmap 

XResize Window: change a window s size XResize Window 

context to/ XSetClipRectangles: change clip_mask in a graphics XSetClipRectangles 

XOffsetRegion: change offset of a region XOffsetRegion 

XSetWindowBackgroundPixmap: change the background tile/ XSetWindowBackgroundPixmap 

window XSetWindowBorderWidth: change the border width of a XSetWindowBorderWidth 

client XSetCloseDownMode: change the close down mode of a XSetCloseDownMode 

XRecolorCursor: change the color of a cursor XRecolorCursor 

graphics context XChangeGC: change the components of a given XChangeGC 

from one/ XTranslateCoordinates: change the coordinate system XTranslateCoordinates 

XChangeKeyboardMapping: change the keyboard mapping XChangeKeyboardMapping 

such as/ XChangeKeyboardControl: change the keyboard preferences XChangeKeyboardControl 

XChangeActivePointerGrab: change the parameters of an/ XChangeActivePointerGrab 

XChangePointerControl: change the pointer preferences XChangePointerControl 

read/write/ XStoreColor: set or change the RGB values of a XStoreColor 

read/write/ XStoreColors: set or change the RGB values of XStoreColors 

a window XMoveResize Window: change the size and position of XMoveResize Window 

siblings XRestack Windows: change the stacking order of XRestack Windows 

property XSetStandardColormap: change the standard colormap XSetStandardColormap 

size, border/ XConfigure Window: change the window position, XConfigureWindow 

and font metrics of a 16-bit character string /for string XQueryTextExtentsl6 

/and font metrics of a 16-bit character string, locally XTextExtentsl6 

the width in pixels of an 8-bit character string, locally /get XTextWidth 

the width in pixels of a 16-bit character string, locally /get XTextWidthl6 

draw 8-bit image text characters XDrawImageString: XDrawImageString 

draw 16-bit image text characters XDrawImageString 16: XDrawImageString 16 

matching event XChecklfEvent: check the event queue for a XChecklfEvent 

the event queue XEventsQueued: check the number of events in XEventsQueued 

stacking/ /circulate the top child to the bottom of the XCirculateSubwindowsUp 

order /circulate the bottom child to the top of the stacking XCirculateSubwindowsDown 

XQueryTree: return a list of children, parent, and root XQueryTree 

/circulate the stacking order of children up or down XCirculateSubwindows 

the/ XCirculateSubwindowsDown: circulate the bottom child to XCirculateSubwindowsDown 

children/ XCirculateSubwindows: circulate the stacking order of XCirculateSubwindows 

bottom/ XCirculateSubwindowsUp: circulate the top child to the XCirculateSubwindowsUp 

matches the desired depth and class /visual information that XMatchVisuallnfo 

a resource value using name and class as quarks /get XrmQGetResource 

/get a resource from name and class as strings XrmGetResource 

window XClearArea: clear a rectangular area in a XClearArea 

XClearWindow: clear an entire window XClearWindow 

keyboard preferences such as key click /change the XChangeKeyboardControl 

rebind a keysym to a string for client XRebindKeysym: XRebindKeysym 

change the close down mode of a client XSetCloseDownMode: XSetCloseDownMode 



Xlib Reference Manual 



XKillClient: destroy a client or its remaining/ XKillClient 

and/ XCloseDisplay: disconnect a client program from an X server XCloseDisplay 

XOpenDisplay: connect a client program to an X server XOpenDisplay 

/add a window to the client s save-set XAddToSaveSet 

or remove a subwindow from the client s save-set /add XChangeSaveSet 

/remove a window from the client s save-set XRemoveFromSaveSet 

context XSetClipOrigin: set the clip origin in a graphics XSetClipOrigin 

to a/ XSetClipRectangles: change clip_mask in a graphics context XSetClipRectangles 

context to the/ XSetRegion: set clip_mask of the graphics XSetRegion 

context XSetClipMask: set clip_mask pixmap in a graphics XSetClipMask 

XSetaoseDownMode: change the close down mode of a client XSetCloseDownMode 

/a read-only colormap cell with closest hardware-supported color XAllocColor 

/get database RGB values and closest hardware-supported RGB/ XLookupColor 

/read/write colormap entry to the closest possible hardware color XStoreColor 

/of read/write colorcells to the closest possible hardware colors XStoreColors 

XQueryBestCursor: get the closest supported cursor sizes XQueryBestCursor 

obtain a description of error code XGetErrorText: XGetErrorText 

with closest hardware-supported color /a read-only colormap cell XAllocColor 

to the closest possible hardware color /read/write colormap entry XStoreColor 

a read-only colorcell from color name /allocate XAllocNamedColor 

RGB values from color name /hardware-supported XLookupColor 

of a read/write colorcell by color name /set RGB values XStoreNamedColor 

/look up RGB values from ASCII color name or translate/ XParseColor 

XRecolorCursor: change the color of a cursor XRecolorCursor 

read/write (nonshareable) color planes /allocate XAllocColorPlanes 

values and flags for a specified colorcell /obtain the RGB XQueryColor 

/set RGB values of a read/write colorcell by color name XStoreNamedColor 

/allocate a read-only colorcell from color name XAllocNamedColor 

allocate read/write (nonshared) colorcells XAllocColorCells: XAllocColorCells 

RGB values for an array of colorcells XQueryColors: obtain XQueryColors 

/the RGB values of read/write colorcells to the closest/ XStoreColors 

XCreateColormap: create a colormap XCreateColormap 

colormap and install the default colormap /delete a XFreeColormap 

XInstallColormap: install a colormap XlnstallColormap 

XFreeColormap: delete a colormap and install the default/ XFreeColormap 

XCopyColonmapAndFree: copy a colormap and return a new/ XCopyColormapAndFree 

XSetWindowColormap: set the colormap attribute for a window XSetWindowColormap 

/allocate a read-only colormap cell with closest/ XAllocColor 

XFreeColors: free colormap cells or planes XFreeColors 

/the RGB values of a read/write colormap entry to the closest/ XStoreColor 

/copy a colormap and return a new colormap ID XCopyColormapAndFree 

XUninstallColormap: uninstall a colormap; install default if not/ XUninstallColormap 

/get the standard colormap property XGetStandardColormap 

/change the standard colormap property XSetStandardColormap 

/get a list of installed colormaps XListlnstalledColormaps 

to the closest possible hardware colors /of read/write colorcells XStoreColors 

/load a resource database from command line arguments XrmParseCommand 

/set the XA_WM_COMMAND atom (command line arguments) XSetCommand 

/set the graphics_exposures component in a graphics context XSetGraphicsExposures 

/set the line drawing components in a graphics context XSetLineAttributes 

Xlib s GC/ XGetGCValues: obtain components of a given GC from XGetGCValues 

context XChangeGC: change the components of a given graphics XChangeGC 

to ASCT string, keysym, and ComposeStatus /map a key event XLookupString 

regions XIntersectRegion: compute the intersection of two XIntersectRegion 

XUnionRegion: compute the union of two regions XUnionRegion 

server XOpenDisplay: connect a client program to an X XOpenDisplay 

XDrawLines: draw multiple connected lines XDrawLines 

control list to allow or deny connection requests /use access XEnableAccessControl 



Permuted Index 



/report the display name (when connection to a display fails) XDisplayName 

XNoOp: send a NoOp to exercise connection with the server XNoOp 

value in an/ XAddPixel: add a constant value to every pixel XAddPixel 

drawable into/ XGetLnage: place contents of a rectangle from XGetLnage 

XrmMcrgeDatabases: merge the contents of one database into/ XnmMcrgcDatahascs 

components of a given graphics context XChangeGC: change the XChangcGC 

XCopyGC: copy a graphics context XCopyGC 

context manager (not graphics context) /get data from the XFindContext 

XFreeGC: free a graphics context XFreeGC 

with the specified graphics context /ID) associated XGContextFromGC 

and context type (not graphics context) /to a window XSaveContext 

set the arc mode in a graphics context XSetArcMode: XSetArcMode 

pixel value in a graphics context /set the background XSetBackground 

clipjmask pixmap in a graphics context XSetClipMask: set XSetClipMask 

the clip origin in a graphics context XSetClipOrigin: set XSetClipOrigin 

of line dashes in a graphics context /set a pattern XSetDashes 

set the fill rule in a graphics context XSetFillRule: XSetFillRule 

set the fill style in a graphics context XSetFillStyle: XSetFillStyle 

the current font in a graphics context XSetFont: set XSetFont 

pixel value in a graphics context /set the foreground XSetForeground 

logical operation in a graphics context /set the bitwise XSetFunction 

component in a graphics context /the graphics_exposures XSetGraphicsExposures 

drawing components in a graphics context /set the line XSetLJneAttributes 

set the plane mask in a graphics context XSetPlaneMask: XSetPlaneMask 

and plane mask in a graphics context /logical function, XSctState 

set the stipple in a graphics context XSetStipple: XSetStipple 

the sub window mode in a graphics context XSetSubwindowMode: set XSetSubwindowMode 

set the fill tile in a graphics context XSetTile: XSetTile 

origin in a graphics context /set the tile/stipple XSetTSOrigin 

a new context ID (not graphics context) XUniqueContext: create XUniqueContext 

and/ XDeleteContext: delete a context entry for a given window XDeleteContext 

XCreateGC: create a new graphics context for a given screen with/ XCreateGC 

XUniqueContext: create a new context ID (not graphics/ XUniqueContext 

XFindContext: get data from the context manager (not graphics/ XFindContext 

/change clip_mask in a graphics context to a list of rectangles XSetClipRectangles 

/set clip_mask of the graphics context to the specified region XSetRegion 

/corresponding to a window and context type (not graphics/ XSaveContext 

disable or enable access control XSetAccessControl: XSetAccessControl 

mapping of modifier keys (Shift, Control, etc.) /obtain a XGetModifierMapping 

to be used as modifiers (Shift, Control, etc.) /set keycodes XSetModifierMapping 

XBell: ring the bell (Control G) XBell 

add a host to the access control list XAddHost: XAddHost 

add multiple hosts to the access control list XAddHosts: XAddHosts 

remove a host from the access control list XRemoveHost: XRemoveHost 

multiple hosts from the access control list /remove XRemoveHosts 

XEnableAccessControl: use access control list to allow or deny/ XEnableAccessControl 

and pointer/ XAllowEvents: control the behavior of keyboard XAllowEvents 

XrmStringToBindingQuarkList: convert a key string to a/ XrmStringToBindingQuarkList 

list XrmStringToQuarkList: convert a key string to a quark XrmStringToQuarkUst 

XKeycodeToKeysym: convert a keycode to a keysym XKeycodeToKeysym 

a keysym XStringToKeysym: convert a keysym name string to XStringToKeysym 

string XKeysymToString: convert a keysym symbol to a XKeysymToString 

appropriate/ XKeysymToKeycode: convert a keysym to the XKeysymToKeycode 

XrmQuarkToString: convert a quark to a string XrmQuarkToString 

XrmStringToQuark: convert a string to a quark XrmStringToQuark 

window to another /change the coordinate system from one XTranslateCoordinates 

colormap/ XCopyColormapAndFree: copy a colormap and return a new XCopyColormapAndFree 

XCopyGC: copy a graphics context XCopyGC 



Xlib Reference Manual 



a location within/ XGetSublmage: copy a rectangle in drawable to XGetSublmage 

drawable into a/ XCopyPlane: copy a single plane of a XCopyPlane 

XCopyArea: copy an area of a drawable XCopyArea 

XLookupKeysym: get the keysym corresponding to a keycode in/ XLookupKeysym 

XSaveContext: save a data value corresponding to a window and/ XSaveContext 

format/ XCreateBitmapFromData: create a bitmap from XI 1 bitmap XCreateBitmapFromData 

XCreateColormap: create a colormap XCreateColormap 

XCreateGlyphCursor: create a cursor from font glyphs XCreateGlyphCursor 

standard/ XCreateFontCursor: create a cursor from the XCreateFontCursor 

XCreatePixmapCursor: create a cursor from two bitmaps XCreatePixmapCursor 

XrmGetStringDatabase: create a database from a string XrmGetStringDatabase 

mapping/ XNewModifiermap: create a keyboard modifier XNewModifiermap 

(X10) XCreateAssocTable: create a new association table XCreateAssocTable 

graphics/ XUniqueContext: create a new context ID (not XUniqueContext 

XCreateRegion: create a new empty region XCreateRegion 

for a given screen/ XCreateGC: create a new graphics context XCreateGC 

XCreatePixmap: create a pixmap XCreatePixmap 

XCreatePixmapFromBitmapData: create a pixmap with depth from/ XCreatePixmapFromBitmapData 

an image XSublmage: create a subimage from part of XSublmage 

attributes XCreateWindow: create a window and set XCreate Window 

association table XMakeAssoc: create an entry in an XMakeAssoc 

window XCreateSimple Window: create an unmapped InputOutput XCreateSimple Window 

XGetWindow Attributes: obtain the current attributes of window XGetWindow Attributes 

context XSetFont: set the current font in a graphics XSetFont 

XGetFontPath: get the current font search path XGetFontPath 

XGetGeometry: obtain the current geometry of drawable XGetGeometry 

XGetlnputFocus: return the current keyboard focus window XGetlnputFocus 

/obtain a list of the current keyboard preferences XGetKeyboardControl 

XQueryPointer: get the current pointer location XQueryPointer 

XGetPointerControl: get the current pointer preferences XGetPointerControl 

XGetScreenSaver: get the current screen saver parameters XGetScreenSaver 

/obtain a bit vector for the current state of the keyboard XQueryKeymap 

XFreeCursor: release a cursor XFreeCursor 

change the color of a cursor XRecolorCursor: XRecolorCursor 

a cursor from the standard cursor font /create XCreateFontCursor 

XUndefineCursor: disassociate a cursor from a window XUndefineCursor 

XCreateGlyphCursor: create a cursor from font glyphs XCreateGlyphCursor 

XCreateFontCursor: create a cursor from the standard cursor/ XCreateFontCursor 

XCreatePixmapCursor: create a cursor from two bitmaps XCreatePixmapCursor 

get the closest supported cursor sizes XQueryBestCursor: XQueryBestCursor 

/obtain the "best" supported cursor, tile, or stipple size XQueryBestSize 

XDefineCursor: assign a cursor to a window XDefineCursor 

X10) XDraw: draw a polyline or curve between vertex list (from XDraw 

X10) /draw a filled polygon or curve from vertex list (from XDrawFilled 

XFetchBuffer: return data from a cut buffer XFetchBuffer 

XStoreBuffer: store data in a cut buffer XStoreBuffer 

XFetchBytes: return data from cut buffer XFetchBytes 

XStoreBytes: store data in cut buffer XStoreBytes 

XRotateBuffers: rotate the cut buffers XRotateBuffers 

/set a pattern of line dashes in a graphics context XSetDashes 

a bitmap from XI 1 bitmap format data /create XCreateBitmapFromData 

a pixmap with depth from bitmap data, /create XCreatePixmapFromBitmapData 

specified/ /free the in-memory data associated with the XFreeStringList 

XFetchBuffer: return data from a cut buffer XFetchBuffer 

XLookUpAssoc: obtain data from an association table XLookllpAssoc 

XFetchBytes: return data from cut buffer XFetchBytes 

(not graphics/ XFindContext: get data from the context manager XFindContext 

XStoreBuffer: store data in a cut buffer XStoreBuffer 



Permuted Index 



XStoreBytes: store 

window and/ XSaveContext: save a 

option value from the resource 

error messages from the error 

destroy a resource 

specification to a resource 

specification into a resource 

XrmGetFileDatabase: retrieve a 

XrmGetStringDatabase: create a 

XrmParseCommand: load a resource 

/store a resource 

/merge the contents of one 

/return a list of 

XLookupColor: get 

/a resource specification to a 

a resource specification into a 

with an image XDestroylmage: 

with a region XDestroyRegion: 

or disable synchronization for 

a colormap and install the 

given user geometry string and 

/uninstall a colormap; install 

the default/ XFreeColormap: 

given window/ XDeleteContext: 

XDeleteProperty: 

association/ XDeleteAssoc: 

XDeleteModifiermapEntry: 

access control list to allow or 

that matches the desired 

a drawable into a drawable with 

/create a pixmap with 

/for a given screen with the 

XListDepths: determine the 

XGetErrorText: obtain a 

information that matches the 

remaining/ XKillClient: 

XrmDestroyDatabase: 

XDestroyWindow: unmap and 

window XDestroySubwindows: 

modifier/ XFreeModifiermap: 

region XPointlnRegion: 

in a region XRectlnRegion: 

XEmptyRegion: 

the same size,/ XEqualRegion: 

on a given screen XListDepths: 

XXorRegion: calculate the 

XSetAccessControl: 

XSynchronize: enable or 

window XUndefineCursor: 

an X server and/ XCloseDisplay: 

XDrawSegments: draw multiple 

read a bitmap from 

program from an X server and 

of hosts having access to this 

XFlush: flush the request buffer 

name (when connection to a 

a/ XDisplayName: report the 

XSetlconName: set the name to be 



data in cut buffer 

data value corresponding to a 

database /extract an 

database /obtain 



XStoreBytes 

XSaveContext 

XGetDefault 

XGetErrorDatabaseText 

database. XrmDestroyDatabase: XrmDestroyDatabase 

database /add a resource XrmPutLineResource 

database /store a resource XrmPutResource 

database from a file XrmGetFileDatabase 

database from a string XrmGetStringDatabase 

database from command line/ XrmParseCommand 

database in a file XrmPutFileDatabase 

database into another XrmMergeDatabases 

database levels XrmQGetSearchList 

database RGB values and closest/ XLookupColor 

database using a quark resource/ XrmQPutStringResource 

database using quarks /store XrmQPutResource 

deallocate memory associated XDestroylmage 

deallocate storage associated XDestroyRegion 

debugging XSynchronize: enable XSynchronize 

default colormap /delete XFreeColormap 

default geometry /geometry XGeometry 

default if not already installed XUninstallColormap 

delete a colormap and install XFreeColormap 

delete a context entry for a XDeleteContext 

delete a window property XDeleteProperty 

delete an entry from an XDeleteAssoc 

delete an entry from an/ XDeleteModifiermapEntry 

deny connection requests /use XEnableAccessControl 

depth and class /information XMatchVisuallnfo 

depth, applying pixel values /of XCopyPlane 

depth from bitmap data XCreatePixmapFromBitmapData 

depth of the specified drawable XCreateGC 

depths available on a given/ XListDepths 

description of error code XGetErrorText 

desired depth and class /visual XMatchVisuallnfo 

destroy a client or its XKillClient 

destroy a resource database XrmDestroyDatabase 

destroy a window and all/ XDestroyWindow 

destroy all subwindows of a XDestroySubwindows 

destroy and free a keyboard XFreeModifiermap 

determine if a point is inside a XPointlnRegion 

determine if a rectangle resides XRectlnRegion 

determine if a region is empty XEmptyRegion 

determine if two regions have XEqualRegion 

determine the depths available XListDepths 

difference between the union and/ XXorRegion 

disable or enable access control XSetAccessControl 

disable synchronization for/ XSynchronize 

disassociate a cursor from a XUndefineCursor 



disconnect a client program from 

disjoint lines 

disk XReadBitmapFile: 

display /disconnect a client 

display /obtain a list 



... XCloseDisplay 
XDrawSegments 
XReadBitmapFile 
XCloseDisplay 
XlistHosts 
XFlush 
XDisplayName 



(display all queued requests) 

display fails) /the display 

display name (when connection to XDisplayName 

displayed in a window s icon XSetlconName 



Xlib Reference Manual 



XGetlconName: get the name to be 

next event that matches mask; 

queue that matches event type; 

passed window and passed mask; 

stacking order of children up or 

/change the close 

characters XDrawImageStringl6: 

XDrawTextl6: 

XDrawImageString : 

XDrawText: 

from vertex list/ XDrawFilled: 
XDrawLine: 
XDrawPoint: 

vertex list (from X10) XDraw: 

foreground only XDrawString: 

rectangle XDrawArc: 

pixmap XPutlmage: 

XDrawRectangle: 

XDraw Arcs: 

XDrawUnes: 

XDra wSegments : 

XDrawPoints: 

rectangles XDrawRectangles: 

XDrawStringl6: 

XCopyArea: copy an area of a 

with the depth of the specified 

obtain the current geometry of 

depth J /copy a single plane of a 

contents of a rectangle from 

the/ /copy a rectangle in 

/plane of a drawable into a 

XSetLine Attributes: set the line 

determine if a region is 

XCreateRegion: create a new 

XSetAccessControl: disable or 

synchronization/ XSynchronize: 

generate the smallest rectangle 

XClearWindow: clear an 

XDeleteContext: delete a context 

XDeleteAssoc: delete an 

structure /delete an 

XMakeAssoc: create an 

structure /add a new 

/values of a read/write colormap 

obtain a description of 

/obtain error messages from the 

XSetErrorHandler: set a nonfatal 

XGetErrorDatabaseText: obtain 

/and wait for all events and 

modifier keys (Shift, Control, 

as modifiers (Shift, Control, 

the event queue for a matching 

XSendEvent: send an 

XPutBackEvent: push an 

set a nonfatal error 

window /return the next 

event type;/ /return the next 

procedure/ XPeeklfEvent: get an 



displayed in an icon 

don t wait /remove the 

don t wait /the next event in ...... 

don t wait /event matching both 
down /circulate the 

down mode of a client 

draw 16-bit image text 

draw 1 6-bit polytext strings 

draw 8 -bit image text characters 

draw 8-bit polytext strings 

draw a filled polygon or curve 

draw a line between two points 

draw a point 

draw a polyline or curve between .... 

draw an 8-bit text string 

draw an arc fitting inside a 

draw an image on a window or 

draw an outline of a rectangle 

draw multiple arcs 

draw multiple connected lines 

draw multiple disjoint lines 

draw multiple points 

draw the outlines of multiple 

draw two-byte text strings 

drawable 

drawable /for a given screen 

drawable XGetGeometry: 

drawable into a drawable with 

drawable into an image /place 

drawable to a location within 

drawable with depth, applying/ 

drawing components in a graphics/ . 

empty XEmptyRegion: 

empty region 

enable access control 

enable or disable 

enclosing a region XQipBox: 

entire window 

entry for a given window and/ 

entry from an association table 

entry from an XModifierKeymap .... 

entry in an association table 

entry to an XModifierKeymap 

entry to the closest possible/ 

error code XGetErrorText: 

error database 

error event handler 

error messages from the error/ 

errors to be processed by the/ 

etc.) /obtain a mapping of 

etc.) /set keycodes to be used 

event XChecklfEvent: check 

event back on the input queue 

event handler XSetErrorHandler: .... 
event in queue matching type and ... 

event in queue that matches 

event matched by predicate 



, XGetlconName 

, XCheckMaskEvent 

, XCheckTypedEvent 

, XCheckWindowEvent 

, XCirculateSubwindows 

, XSetCloseDownMode 

, XDrawImageString 16 

,XDrawTextl6 

, XDrawImageString 

, XDrawText 

, XDrawFilled 

.XDrawLine 

, XDrawPoint 

.XDraw 

. XDrawString 

. XDrawArc 

. XPutlmage 

. XDrawRectangle 

. XDrawArcs 

. XDrawLines 

. XDrawSegments 

. XDrawPoints 

. XDrawRectangles 

.XDrawString 16 

. XCopyArea 

. XCreateGC 

. XGetGeometry 

. XCopyPlane 

. XGetlmage 

. XGetSublmage 

. XCopyPlane 

: XSetLineAttributes 

. XEmptyRegion 

. XCreateRegion 

. XSetAccessControl 

. XSynchronize 

. XClipBox 

. XClearWindow 

. XDeleteContext 

. XDeleteAssoc 

. XDeleteModifiermapEntry 

. XMakeAssoc 

. XInsertModifiermapEntry 

. XStoreColor 

. XGetErrorText 

. XGetErrorDatabaseText 

. XSetErrorHandler 

. XGetErrorDatabaseText 

.XSync 

. XGetModifierMapping 

. XSetModifierMapping 

. XChecklfEvent 

. XSendEvent 

, XPutBackEvent 

, XSetErrorHandler 

, XCheckTypedWindowEvent 

, XCheckTypedEvent 

, XPeeklfEvent 



Permuted Index 



procedure XlfEvent: wait for 

window and/ /remove the next 

XNextEvent: get the next 

the number of events in the 

XChecklfEvent: check the 

XMaskEvent: remove the next 

XCheckMaskEvent: remove the next 

XWindowEvent: remove the next 

and/ XLookupString: map a key 

next event in queue that matches 

window XSelectlnput: select the 

the queue XPeekEvent: get an 

the number of pending input 

request buffer and wait for all 

history/ XGetMotionEvents: get 

/check the number of 

/behavior of keyboard and pointer 

server XNoOp: send a NoOp to 

XShrinkRegion: reduce or 

XQueryExtension: get 

for a list of installed 

Xlib and/ /return a list of all 

resource database XGetDefault: 

(when connection to a display 

XQueryBestTile: obtain the 

XQueryBestStipple: obtain the 

retrieve a database from a 

store a resource database in a 

write a bitmap to a 

XFillPolygon: 

XFillRectangle: 

XFillArc: 

XLoadQueryFont: load a font and 

XFillArcs: 

XFillRectangles: 

XSetFillRule:setthe 

XSetFillStyle: set the 

XSetTilersetthe 

obtain the fastest supported 

vertex list/ XDrawFilled: draw a 

structures that/ XGetVisuallnfo: 

XDrawArc: draw an arc 

/obtain the RGB values and 

return the number of/ XPending: 

wait for all events and/ XSync: 

(display all queued/ XFlush: 

return the current keyboard 

XSetlnputFocus: set the keyboard 

cursor from the standard cursor 

information about a loaded 

XUnloadFont: unload a 

XLoadQueryFont: load a 

font/ XFreeFont: unload a 

create a cursor from 

font if not already loaded; get 

font ID XLoadFont: load a 

XSetFont: set the current 

query the server for string and 



event matched in predicate 

event matching both passed 

event of any type or window 

event queue /check 

event queue for a matching event 

event that matches mask 

event that matches mask; don t/ ... 
event that matches the specified/ . 
event to ASCII string, keysym, .... 

event type; don t wait /the 

event types to be sent to i 

event without removing it from ........ 

events /buffer and return 

events and errors to be/ /the 

events from pointer motion 

events in the event queue 

events when these resources are/ .... 

exercise connection with the 

expand the size of a region 

extension information 

extensions /memory allocated 

extensions to X supported by 

extract an option value from the 

fails) /report the display name 

fastest supported fill tile/ 

fastest supported stipple shape 

file XrmGetFileDatabase: 

file XrmPutFileDatabase: 

file XWriteBitmapFile: 

fill a polygon 

fill a rectangular area 

fill an arc 

fill information structure 

fill multiple arcs 

fill multiple rectangular areas 

fill rule in a graphics context 

fill style in a graphics context 

fill tile in a graphics context 

fill tile shape XQueryBestTile: 

filled polygon or curve from 

find the visual information 

fitting inside a rectangle 

flags for a specified colorcell 

flush the request buffer and 

flush the request buffer and 

flush the request buffer 

focus window XGetlnputFocus: ... 

focus window 

font /create a 

font XQueryFont: return 

font and fill information/ 

font and free storage for the 

font glyphs XCreateGlyphCursor: 

font ID XLoadFont: load a 

font if not already loaded; get 

font in a graphics context 

font metrics XQueryTextExtents: . 



. XlfEvent 

. XCheckWindowEvent 

. XNextEvent 

. XEventsQueued 

. XChecklfEvent 

.XMaskEvent 

. XCheckMaskEvent 

. XWindowEvent 

. XLookupString 

. XCheckTypedEvent 

, XSelectlnput 

. XPeekEvent 

. XPending 

.XSync 

. XGetMotionEvents 

. XEventsQueued 

. XAllowEvents 

.XNoOp 

. XShrinkRegion 

. XQueryExtension 

. XFreeExtensionList 

. XListExtensions 

.XGetDefault 

. XDisplayName 

. XQueryBestTile 

. XQueryBestStipple 

. XrmGetFileDatabase 

. XrmPutFileDatabase 

. XWriteBitmapFile 

. XFillPolygon 

. XFillRectangle 

. XFillArc 

, XLoadQueryFont 

, XFillArcs 

, XFillRectangles 

.XSetFillRule 

, XSetFillStyle 

.XSetTile 

, XQueryBestTile 

, XDrawFilled 

, XGetVisuallnfo 

, XDrawArc 

, XQueryColor 

, XPending 

, XSync 

, XFlush 

, XGetlnputFocus 

, XSetlnputFocus 

, XCreateFontCursor 

, XQueryFont 

, XUnloadFont 

, XLoadQueryFont 

, XFreeFont 

, XCreateGlyphCursor 

, XLoadFont 

, XLoadFont 

, XSetFont 

, XQueryTextExtents 



10 



Xlib Reference Manual 



XTextExtents: get string and font metrics locally XTextExtents 

/query the server for string and font metrics of a 16-bit/ XQueryTextExtentsl6 

XTextExtents 16: get string and font metrics of a 16-bit/ XTextExtents 16 

return a list of the available font names XlistFonts: XUstFonts 

XGetFontProperty: get a font property given its atom XGetFontProperty 

XGetFontPath: get the current font search path XGetFontPath 

XSetFontPath: set the font search path XSetFontPath 

a font and free storage for the font structure /unload XFreeFont 

and information about loaded fonts /obtain the names XListFontsWithlnfo 

function,/ XSetState: set the foreground, background, logical XSetState 

draw an 8-bit text string, foreground only XDrawString: XDrawString 

XSetForeground: set the foreground pixel value in a/ XSetForeground 

/create a bitmap from XI 1 bitmap format data XCreateBitmapFromData 

the atom type and property format for a window /obtain XGetWindowProperty 

/obtain the supported pixmap formats for a given server XUstPixmapFormats 

XFreeGC: free a graphics context XFreeGC 

XFreeModifiermap: destroy and free a keyboard modifier mapping/ XFreeModifiermap 

XFreePixmap: free a pixmap ID XFreePixmap 

XFreeColors: free colormap cells or planes XFreeColors 

of/ XFreeExtensionList: free memory allocated for a list XFreeExtensionUst 

by an Xlib function XFree: free specified memory allocated XFree 

XFreeFont: unload a font and free storage for the font/ XFreeFont 

associated/ XFreeStringlist: free the in-memory data XFreeStringList 

XGetFontPath XFreeFontPath: free the memory allocated by XFreeFontPath 

XUstFonts. XFreeFontNames: free the memory allocated by XFreeFontNames 

XFreeFontlnfo: free the memory allocated by/ XFreeFontlnfo 

association/ XDestroyAssocTable: free the memory allocated for an XDestroyAssocTable 

allocate memory never to be freed Xpermalloc: Xpermalloc 

memory allocated by an Xlib function XFree: free specified XFree 

/foreground, background, logical function, and plane mask in a/ XSetState 

XSetAfterFunction: set a function called after all Xlib/ XSetAfterFunction 

a function called after all Xlib functions /set XSetAfterFunction 

XBell: ring the bell (Control G) XBell 

of a given GC from XHb s GC cache /obtain components XGetGCValues 

/obtain components of a given GC from Xlib s GC cache XGetGCValues 

XGContextFromGC: obtain the GContext (resource ID)/ XGContextFromGC 

XPolygonRegion: generate a region from points XPolygonRegion 

standard window/ XParseGeometry: generate position and size from XParseGeometry 

enclosing a region XClipBox: generate the smallest rectangle XClipBox 

user geometry string and default geometry /window geometry given XGeometry 

XGeometry: calculate window geometry given user geometry/ XGeometry 

XWMGeometry: obtain a window s geometry information XWMGeometry 

XGetGeometry: obtain the current geometry of drawable XGetGeometry 

and size from standard window geometry string /position XParseGeometry 

/window geometry given user geometry string and default/ XGeometry 

atom XGetFontProperty: get a font property given its XGetFontProperty 

XListlnstalledColormaps: get a list of installed/ XListlnstaUedColormaps 

class as/ XrmGetResource: get a resource from name and XrmGetResource 

and class as/ XrmQGetResource: get a resource value using name XrmQGetResource 

given its atom XGetAtomName: get a string name for a property XGetAtomName 

property) XFetchName: get a window s name (XA_WM_NAME . XFetchName 

predicate/ XPeeklfEvent: get an event matched by XPeeklfEvent 

from the queue XPeekEvent: get an event without removing it XPeekEvent 

manager (not/ XFindContext: get data from the context XFindContext 

closest/ XLookupColor: get database RGB values and XLookupColor 

history/ XGetMotionEvents: get events from pointer motion XGetMotionEvents 

XQuery Extension: get extension information XQuery Extension 

a font if not already loaded; get font ID XLoadFont: load XLoadFont 



Permuted Index 1 1 



XGetlconSizes: get preferred icon sizes XGetlconSizes 

locally XTextExtents: get string and font metrics XTextExtents 

1 6-bit/ XTextExtents 16: get string and font metrics of a XTextExtents 1 6 

sizes XQueryBestCursor: get the closest supported cursor XQueryBestCursor 

XGetFontPath: get the current font search path XGetFontPath 

XQueryPointer: get the current pointer location XQueryPointer 

preferences XGetPointerControl: get the current pointer XGetPointerControl 

parameters XGetScreenSaver: get the current screen saver XGetScreenSaver 

a keycode in/ XLookupKeysym: get the keysym corresponding to XLookupKeysym 

an icon XGetlconName: get the name to be displayed in XGetlconName 

or window XNextEvent: get the next event of any type XNextEvent 

XGetPointerMapping: get the pointer button mapping XGetPointerMapping 

window XListProperties: get the property list for a XListProperties 

window in/ XGetNormalHints: get the size hints property of a XGetNormalHints 

property XGetStandardColormap: get the standard colormap XGetStandardColormap 

1 6-bit character/ XTextWidth 16: get the width in pixels of a XTextWidth 1 6 

8-bit character/ XTextWidth: get the width in pixels of an XTextWidth 

a window XGetClassHint: get the XA_WM_CLASS property of XGelClassHint 

property/ XGetTransientForHint: get the XA_WM_TRANSIENT_FOR XGetTransientForHint 

create a cursor from font glyphs XCreateGlyphCurson XCreateGlyphCursor 

parameters of an active pointer grab /change the XChangeActivePointerGrab 

release a button from a passive grab XUngrabButton: XUngrabButton 

release a key from a passive grab XUngrabKey: XUngrabKey 

the keyboard from an active grab XUngrabKeyboard: release XUngrabKeyboard 

the pointer from an active grab XUngrabPointer: release XUngrabPointer 

release the server from grab XUngrabServer: XUngrabServer 

XGrabKey: grab a key XGrabKey 

XGrabButton: grab a pointer button XGrabButton 

XGrabKeyboard: grab the keyboard XGrabKeyboard 

XGrabPointer: grab the pointer XGrabPointer 

XGrabServer: grab the server XGrabServer 

events when these resources are grabbed /of keyboard and pointer XAllowEvents 

change the components of a given graphics context XChangeGC: XChangeGC 

XCopyGC: copy a graphics context XCopyGC 

from the context manager (not graphics context) /get data XFindContext 

XFreeGC: free a graphics context XFreeGC 

associated with the specified graphics context /(resource ID) XGContextFromGC 

a window and context type (not graphics context) Ao XSaveContext 

set the arc mode in a graphics context XSetArcMode: XSetArcMode 

the background pixel value in a graphics context /set XSetBackground 

set clip_mask pixmap in a graphics context XSetClipMask: XSetClipMask 

/set the clip origin in a graphics context XSetClipOrigin 

a pattern of line dashes in a graphics context /set XSetDashes 

set the fill rule in a graphics context XSetFillRule: XSetFillRule 

set the fill style in a graphics context XSetFillStyle: XSetFUlStyle 

set the current font in a graphics context XSetFont: XSetFont 

the foreground pixel value in a graphics context /set XSetForeground 

bitwise logical operation in a graphics context /set the XSetFunction 

/component in a graphics context XSetGraphicsExposures 

the line drawing components in a graphics context /set XSetLineAttributes 

set the plane mask in a graphics context XSetPlaneMask: XSetPlaneMask 

function, and plane mask in a graphics context /logical XSetState 

set the stipple in a graphics context XSetStipple: XSetStipple 

/set the subwindow mode in a graphics context XSetSubwindowMode 

XSetTile: set the fill tile in a graphics context XSetTile 

set the tile/supple origin in a graphics context XSetTSOrigin: XSetTSOrigin 

/create a new context ID (not graphics context) XUniqueContext 

screen/ XCreateGC: create a new graphics context for a given XCreateGC 



12 Xlib Reference Manual 



/change clip_mask in a graphics context to a list of/ XSetClipRectangles 

XSctRegion: set clip_mask of the graphics context to the/ XSetRegion 

XSetGraphicsExposures: set the graphics_exposures component in/ XSetGraphicsExposures 

set a nonfatal error event handler XSetErrorHandlen XSetErrorHandler 

entry to the closest possible hardware color /colormap XStoreColor 

to the closest possible hardware colors /colorcells XStoreColors 

/colormap cell with closest hardware-supported color XAllocColor 

/database RGB values and closest hardware-supported RGB values/ XLookupColor 

/obtain a list of hosts having access to this display XListHosts 

ASCII color name or translate hexadecimal value /values from XParseColor 

read the window manager hints property XGetWMHints: XGetWMHints 

set a window manager hints property XSetWMHints: XSetWMHints 

XGetNormalHints: get the size hints property of a window in/ XGetNormalHints 

XSetNormalHints: set the size hints property of a window in/ XSetNormalHints 

XGetZoomHints: read the size hints property of a zoomed/ XGetZoomHints 

XSetZoomHints: set the size hints property of a zoomed/ XSetZoomHints 

/get events from pointer motion history buffer XGetMotionEvents 

allow access from any host XDisableAccessControl: XDisableAccessControl 

list XRemoveHosl: remove a host from the access control XRemoveHost 

XAddHost: add a host to the access control list XAddHost 

XRemoveHosts: remove multiple hosts from the access control/ XRemoveHosts 

XListHosts: obtain a list of hosts having access to this/ XListHosts 

XAddHosts: add multiple hosts to the access control list XAddHosts 

the name to be displayed in an icon XGetlconName: get XGetlconName 

to be displayed in a window s icon XSetlconName: set the name XSetlconName 

XGetlconSizes: get preferred icon sizes XGetlconSizes 

in normal state (not zoomed or iconified) /property of a window XGetNormalHints 

that a top-level window be iconified /request XlconifyWindow 

in normal state (not zoomed or iconified) /property of a window XSetNormalHints 

and return a new colormap ID /copy a colormap XCopyColormapAndFree 

XFreePixmap: free a pixmap ID XFreePixmap 

if not already loaded; get font ID XLoadFont: load a font XLoadFont 

/obtain the GContext (resource ID) associated with the/ XGContextFromGC 

/obtain the visual ID from a Visual XVisuallDFrom Visual 

/create a new context ID (not graphics context) XUniqueContext 

value to every pixel value in an image XAddPixel: add a constant XAddPixel 

memory associated with an image XDestroylmage: deallocate XDestroylmage 

rectangle from drawable into an image /place contents of a XGetlmage 

a single pixel value from an image XGetPixel: obtain XGetPixel 

location within the pre-existing image /in drawable to a XGetSublmage 

set a pixel value in an image XPutPixel: XPutPixel 

a subimage from part of an image XSublmage: create XSublmage 

XPutlmage: draw an image on a window or pixmap XPutlmage 

XDrawImageString: draw 8-bit image text characters XDrawImageString 

XDrawImageStringl6: draw 16-bit image text characters XDrawImageString 16 

XQueryExtension: get extension information XQueryExtension 

obtain a window s geometry information XWMGeometry: XWMGeometry 

XQueryFont: return information about a loaded font XQueryFont 

/obtain the names and information about loaded fonts XListFontsWithlnfo 

/load a font and fill information structure XLoadQueryFont 

XGetVisuallnfo: find the visual information structures that/ XGetVisuallnfo 

desired depth/ /obtain the visual information that matches the XMatchVisuallnfo 

Xrmlnitialize: initialize the resource manager Xrmlnitialize 

the/ XFreeStringList: free the in-memory data associated with XFreeStringList 

and return the number of pending input events /the request buffer XPending 

push an event back on the input queue XPutBackEvent: XPutBackEvent 

/create an unmapped InputOutput window XCreateSimple Window 

window and its/ XReparentWindow: insert a window between another XReparentWindow 



Permuted Index 13 



XDrawArc: draw an arc fitting inside a rectangle XDrawArc 

determine if a point is inside a region XPointlnRegion: XPointlnRegion 

XInstallColormap: install a colormap XListallColormap 

installed /uninstall a colormap; install default if not already XUninstallColormap 

/delete a colormap and install the default colormap XFreeColormap 

install default if not already installed /uninstall a colormap; XUninstallColormap 

/get a list of installed colormaps XListlnstalledColormaps 

memory allocated for a list of installed extensions /free XFreeExtensionList 

XIntersectRegion: compute the intersection of two regions XIntersectRegion 

difference between the union and intersection of two regions /the XXorRegion 

XGrabKey: grab a key XGrabKey 

the keyboard preferences such as key click /change XChangeKeyboardControl 

keysym,/ XLookupString: map a key event to ASCII string, XLookupString 

XUngrabKey: release a key from a passive grab XUngrabKey 

a quark list /convert a key string to a binding list and XrmStringToBindingQuarkList 

XrrnStringToQuarkList: convert a key string to a quark list XrmStringToQuarkList 

XGrabKeyboard: grab the keyboard XGrabKeyboard 

for the current state of the keyboard /obtain a bit vector XQueryKeymap 

these/ /control the behavior of keyboard and pointer events when XAllowEvents 

XAutoRepeatOff : turn off the keyboard auto-repeat keys XAutoRepeatOff 

XAutoRepeatOn: turn on the keyboard auto-repeat keys XAutoRepeatOn 

/return the current keyboard focus window XGetlnputFocus 

XSetlnputFocus: set the keyboard focus window XSetlnputFocus 

XUngrabKeyboard: release the keyboard from an active grab XUngrabKeyboard 

/change the keyboard mapping XChangeKeyboardMapping 

structure /destroy and free a keyboard modifier mapping XFreeModifiermap 

XNewModifiermap: create a keyboard modifier mapping/ XNewModifiermap 

/obtain a list of the current keyboard preferences XGetKeyboardControl 

click /change the keyboard preferences such as key XChangeKeyboardControl 

a keysym to the appropriate keycode /convert XKeysymToKeycode 

the keysym corresponding to a keycode in structure /get XLookupKeysym 

XKeycodeToKeysym: convert a keycode to a keysym XKeycodeToKeysym 

XRefreshKeyboardMapping: read keycode-keysym mapping from/ XRefreshKeyboardMapping 

return symbols for keycodes XGetKeyboardMapping: XGetKeyboardMapping 

/obtain the range of legal keycodes for a server XDisplayKeycodes 

XSetModifierMapping: set keycodes to be used as modifiers/ XSetModifierMapping 

off the keyboard auto-repeat keys XAutoRepeatOff: turn XAutoRepeatOff 

turn on the keyboard auto-repeat keys XAutoRepeatOn: XAutoRepeatOn 

/obtain a mapping of modifier keys (Shift, Control, etc.) XGetModifierMapping 

convert a keycode to a keysym XKeycodeToKeysym: XKeycodeToKeysym 

a keysym name string to a keysym XStringToKeysym: convert XStringToKeysym 

/map a key event to ASCII string, keysym, and ComposeStatus XLookupString 

keycode/ XLookupKeysym: get the keysym corresponding to a XLookupKeysym 

XStringToKeysym: convert a keysym name string to a keysym XStringToKeysym 

XKeysymToString: convert a keysym symbol to a string XKeysymToString 

XRebindKeysym: rebind a keysym to a string for client XRebindKeysym 

XKeysymToKeycode: convert a keysym to the appropriate/ XKeysymToKeycode 

/obtain the range of legal keycodes for a server XDisplayKeycodes 

return a list of database levels XrmQGetSearchList: XrmQGetSearchList 

a resource database from command line arguments /load XrmParseCommand 

the XA_WM_COMMAND atom (command line arguments) /set XSetCommand 

XDrawLine: draw a line between two points XDrawLine 

XSetDashes: set a pattern of line dashes in a graphics/ XSetDashes 

XSetLine Attributes: set the line drawing components in a/ XSetLineAttributes 

draw multiple connected lines. XDrawLines: XDrawLines 

draw multiple disjoint lines XDrawSegments: XDrawSegments 

add a host to the access control list XAddHost: XAddHost 

hosts to the access control list XAddHosts: add multiple XAddHosts 



14 Xlib Reference Manual 



with the specified string list /in-memory data associated XFreeStringList 

a host from the access control list XRemoveHost: remove XRemoveHost 

hosts from the access control list /remove multiple XRemoveHosts 

to a binding list and a quark list /convert a key string XrmStringToBindingQuarkList 

convert a key string to a quark list XrmStringToQuarkList: XrmStringToQuarkList 

a key string to a binding list and a quark list /convert XrmStringToBindingQuarkList 

/search prepared list for a given resource XrmQGetSearchResource 

/get the property list for a window XListProperties 

polyline or curve between vertex list (from XI 0) XDraw: draw a XDraw 

polygon or curve from vertex list (from X10) /draw a filled XDrawFilled 

XListExtensions: return a list of all extensions to X/ XListExtensions 

root XQueryTree: return a list of children, parent, and XQueryTree 

XrmQGetSearchList: return a list of database levels XrmQGetSearchList 

this/ XListHosts: obtain a list of hosts having access to XListHosts 

XListlnstalledColormaps: get a list of installed colormaps XListlnstalledColormaps 

/free memory allocated for a list of installed extensions XFreeExtensionUst 

in a graphics context to a list of rectangles /clip_mask XSetClipRectangles 

XTextProperty/ /obtain a list of strings from a specified XTextPropertyToStringList 

XTextProperty/ /set the specified list of strings to an XStringListToTextProperty 

XListFonts: return a list of the available font names XListFonts 

XGetKeyboardControl: obtain a list of the current keyboard/ XGetKeyboardControl 

requests /use access control list to allow or deny connection XEnableAccessControl 

structure XLoadQueryFont: load a font and fill information XLoadQueryFont 

loaded; get font ID XLoadFont: load a font if not already XLoadFont 

command line/ XrmParseCommand: load a resource database from XrmParseCommand 

return information about a loaded font XQueryFont: XQueryFont 

the names and information about loaded fonts /obtain XListFonts Withlnfo 

load a font if not already loaded; get font ID XLoadFont: XLoadFont 

get string and font metrics locally XTextExtents: XTextExtents 

of a 16-bit character string, locally /string and font metrics XTextExtents 16 

of an 8-bit character string, locally /get the width in pixels XTextWidth 

of a 16-bit character string, locally /get the width in pixels XTextWidth 16 

get the current pointer location XQueryPointer: XQueryPointer 

/a rectangle in drawable to a location within the pre-existing/ XGetSublmage 

/set the foreground, background, logical function, and plane mask/ XSetState 

XSetFunction: set the bitwise logical operation in a graphics/ XSetFunction 

color name or/ XParseColor: look up RGB values from ASCII XParseColor 

order XLowerWindow: lower a window in the stacking XLowerWindow 

initialize the resource manager Xrmlnitialize: Xrmlnitialize 

set of properties for the window manager /set the minimum XSetStandardProperties 

name to a window for the window manager XStoreName: assign a XStoreName 

XGetWMHints: read the window manager hints property XGetWMHints 

XSetWMHints: set a window manager hints property XSetWMHints 

/get data from the context manager (not graphics context) XFindContext 

/set a window s standard window manager properties XSetWMProperties 

keysym, and/ XLookupString: map a key event to ASCII string XLookupString 

XMapWindow: map a window XMap Window 

siblings XMapRaised: map a window on top of its XMapRaised 

XMapSub windows: map all subwindows of window XMapSubwindows 

change the keyboard mapping XChangeKeyboardMapping: ... XChangeKeyboardMapping 

get the pointer button mapping XGetPointerMapping: XGetPointerMapping 

set the pointer button mapping XSetPointerMapping: XSetPointerMapping 

/read keycode-keysym mapping from server into Xlib XRefreshKeyboardMapping 

XGetModifierMapping: obtain a mapping of modifier keys (Shift,/ XGetModifierMapping 

and free a keyboard modifier mapping structure /destroy XFreeModifiermap 

/create a keyboard modifier mapping structure XNewModifiermap 

the next event that matches mask XMaskEvent: remove XMaskEvent 

event that matches the specified mask and window /remove the next XWindowEvent 



Permuted Index 15 



the next event that matches 

both passed window and passed 

XSetPlaneMask: set the plane 

/logical function, and plane 

/information structures that 

XPeeklfEvent: get an event 

XlfEvent: wait for event 

/the next event in queue that 

remove the next event that 

/remove the next event that 

/the visual information that 

/remove the next event that 

passed/ /remove the next event 

check the event queue for a 

/return the next event in queue 

function XFree: free specified 

XFreeFontPath: free the 

XFreeFontNames: free the 

XFreeFontlnfo: free the 

XFreeExtensionList: free 

XDestroyAssocTable: free the 

XDestroy Image: deallocate 

XCreatelmage: allocate 

Xpermalloc: allocate 

database/ XrmMergeDatabases: 

/obtain error 

the server for string and font 

get string and font 

/the server for string and font 

stringy /get string and font 

XSetStandardProperties: set the 

XSetArcMode: set the arc 

/set the subwindow 

/change the close down 

etc.) /obtain a mapping of 

/destroy and free a keyboard 

/create a keyboard 

/set keycodes to be used as 

/get events from pointer 

XMoveWindow: 

point on the/ XWarpPointer: 

XDrawArcs: draw 

XFillArcs: fill 

XDrawLines: draw 

XDrawSegments: draw 

control/ XRemoveHosts: remove 

control list XAddHosts: add 

XDrawPoints: draw 

/draw the outlines of 

XFillRectangles: fill 

a read-only colorcell from color 

RGB values from color 

a read/write colorcell by color 

/get a resource value using 

/get a resource from 

database using a quark resource 

with separate resource 

Uom XGetAtomName: get a string 



mask; don t wait /remove , 
mask; don t wait /event matching 
mask in a graphics context ............ 

mask in a graphics context 

match the specified template , 

matched by predicate procedure/ , 

matched in predicate procedure 

matches event type; don t wait 

matches mask XMaskEvent: , 

matches mask; don t wait 

matches the desired depth and/ , 

matches the specified mask and/ 

matching both passed window and .... 

matching event XChecklfEvent: 

matching type and window 

memory allocated by an Xlib 

memory allocated by XGetFontPath . 

memory allocated by XUstFonts 

memory allocated by/ 

memory allocated for a list of/ 

memory allocated for an/ 

memory associated with an image 

memory for an Xlmage structure 

memory never to be freed 

merge the contents of one 

messages from the error database 

metrics /Query 

metrics locally XTextExtents: 

metrics of a 16-bit character/ 

metrics of a 16-bit character 

minimum set of properties for/ 

mode in a graphics context 

mode in a graphics context 

mode of a client 

modifier keys (Shift, Control, 

modifier mapping structure 

modifier mapping structure 

modifiers (Shift, Control, etc.) 

motion history buffer 

move a window 

move the pointer to another 

multiple arcs 

multiple arcs 

multiple connected lines 

multiple disjoint lines 

multiple hosts from the access 

multiple hosts to the access 

multiple points 

multiple rectangles 

multiple rectangular areas 

name XAllocNamedColor: allocate .. 
name /closest hardware-supported .... 

name /set RGB values of 

name and class as quarks 

name and class as strings 

name and string value Ao a 

name and value /specification 

name for a property given its 



, XCheckMaskEvent 

. XCheckWindowEvent 

. XSetPlaneMask 

.XSetState 

.XGetVisuallnfo 

. XPeeklfEvent 

. XlfEvent 

. XCheckTypedEvent 

. XMaskEvent 

. XCheckMaskEvent 

. XMatchVisuallnfo 

. XWindowEvent 

.XCheckWindowEvent 

. XChecklfEvent 

. XCheckTypedWindowEvent 

.XFree 

. XFreeFontPath 

. XFreeFontNames 

. XFreeFontlnfo 

. XFreeExtensionList 

. XDestroyAssocTable 

. XDestroylmage 

. XCreatelmage 

. Xpermalloc 

. XrmMergeDatabases 

. XGetErrorDatabaseText 

. XQueryTextExtents 

. XTextExtents 

. XQueryTextExtents 1 6 

.XTextExtents 16 

. XSetStandardProperties 

. XSetArcMode 

. XSetSubwindowMode 

. XSetCloseDownMode 

. XGetModifierMapping 

. XFreeModifiermap 

, XNewModifiermap 

. XSetModifierMapping 

, XGetMotionEvents 

. XMoveWindow 

. XWarpPointer 

. XDrawArcs 

. XFillArcs 

, XDrawLines 

. XDrawSegments 

. XRemoveHosts 

. XAddHosts 

. XDrawPoints 

, XDrawRectangles 

. XFillRectangles 

. XAllocNamedColor 

. XLookupColor 

. XStoreNamedColor 

. XrmQGetResource 

. XrmGetResource 

. XrmQPutStringResource 

, XrmPutStringResource 

, XGetAtomName 



16 



Xlib Reference Manual 



/up RGB values from ASCII color name or translate hexadecimal/ XParseColor 

an atom for a given property name string XInternAtom: return XInternAtom 

/convert a keysym name string to a keysym XStringToKeysym 

manager XStoreName: assign a name to a window for the window XStoreName 

window s/ XSetlconName: set the name to be displayed in a XSetlconName 

XGetlconName: get the name to be displayed in an icon XGetlconName 

XDisplayName: report the display name (when connection to a/ XDisplayName 

XFetchName: get a window s name (XA_WM_NAME property) XFetchName 

a list of the available font names XlistFonts: return XUstFonts 

XUstFontsWithlnfo: obtain the names and information about/ XListFontsWithlnfo 

Xpermalloc: allocate memory never to be freed Xpermalloc 

XCreateAssocTable: create a new association table (X10) XCreateAssocTable 

/copy a colormap and return a new colormap ID XCopyColormapAndFree 

XUniqueContext: create a new context ID (not graphics/ XUniqueContext 

XCreateRegion: create a new empty region XCreateRegion 

XInsertModifiermapEntry: add a new entry to an XModifierKeymap/ XlnsertModifiermapEntry 

screen with/ XCreateGC: create a new graphics context for a given XCreateGC 

XrmUniqueQuark: allocate a new quark XrmUniqueQuark 

type and window /return the next event in queue matching XCheckTypedWindowEvent 

XCheckTypedEvent: return the next event in queue that matches/ XCheckTypedEvent 

XCheckWindowEvent: remove the next event matching both passed/ XCheckWindowEvent 

XNextEvent: get the next event of any type or window XNextEvent 

XMaskEvent: remove the next event that matches mask XMaskEvent 

XCheckMaskEvent: remove the next event that matches mask;/ XCheckMaskEvent 

XWindowEvent: remove the next event that matches the/ XWindowEvent 

XSetErrorHandler: set a nonfaial error event handler XSetErrorHandler 

/allocate read/write (nonshareable) color planes X AllocColorPlanes 

/allocate read/write (nonshared) colorcells XAllocColorCells 

the server XNoOp: send a NoOp to exercise connection with XNoOp 

/hints property of a window in normal state (not zoomed or/ XGetNormalHints 

/hints property of a window in normal state (not zoomed or/ XSetNormalHinls 

a colormap; install default if not already installed /uninstall XUninstallColormap 

XLoadFont: load a font if not already loaded; get font ID XLoadFont 

data from the context manager (not graphics context) /get XFindContext 

/to a window and context type (not graphics context) XSaveContext 

/create a new context ID (not graphics context) XUniqueContext 

/of a window in normal state (not zoomed or iconified) XGetNormalHints 

/of a window in normal state (not zoomed or iconified) XSetNormalHints 

queue XEventsQueued: check the number of events in the event XEventsQueued 

/request buffer and return the number of pending input events XPending 

current state of/ XQueryKeymap: obtain a bit vector for the XQueryKeymap 

code XGetErrorText: obtain a description of error XGetErrorText 

access to this/ XListHosts: obtain a list of hosts having XListHosts 

XTextPropertyToStringLJst: obtain a list of strings from a/ XTextPropertyToStringLJst 

keyboard/ XGetKeyboardControl: obtain a list of the current XGetKeyboardControl 

keys/ XGetModifierMapping: obtain a mapping of modifier XGetModifierMapping 

an image XGetPixel: obtain a single pixel value from XGetPixel 

information XWMGeometry: obtain a window s geometry XWMGeometry 

from Xlib s GC/ XGetGCValues: obtain components of a given GC XGetGCValues 

table XLookUpAssoc: obtain data from an association XLookUpAssoc 

error/ XGetErrorDatabaseText: obtain error messages from the XGetErrorDatabaseText 

of colorcells XQueryColors: obtain RGB values for an array XQueryColors 

property/ XGetWindowProperty: obtain the atom type and XGetWindowProperty 

cursor, tile,/ XQueryBestSize: obtain the "best" supported XQueryBestSize 

window XGetWindow Attributes: obtain the current attributes of XGetWindow Attributes 

drawable XGetGeometry: obtain the current geometry of XGetGeometry 

fill tile shape XQueryBestTile: obtain the fastest supported XQueryBestTile 

stipple/ XQueryBestStipple: obtain the fastest supported XQueryBestStipple 



Permuted Index 



ID) associated/ XGContextFromGC: obtain the GContext (resource XGContextFromGC 

about/ XlistFontsWithlnfo: obtain the names and information XListFontsWithlnfo 

key codes for/ XDisplayKeycodes: obtain the range of legal XDisplayKeycodes 

for a specified/ XQueryColor: obtain the RGB values and flags XQueryColor 

formats for/ XListPixmapFormats: obtain the supported pixmap XListPixmapFormats 

Visual XVisuallDFrom Visual: obtain the visual ID from a XVisuallDFrom Visual 

that matches/ XMatchVisuallnfo: obtain the visual information XMatchVisuallnfo 

structure/ XGetRGBColormaps: obtain the XStandardColormap XGetRGBColormaps 

turn the screen saver on or off XForceScreenSaver: XForceScreenSaver 

keys XAutoRepeatOff : turn off the keyboard auto-repeat XAutoRepeatOff 

two regions have the same size, offset, and shape /determine if XEqualRegion 

XOffsetRegion: change offset of a region XOffsetRegion 

an 8-bit text string, foreground only XDrawString: draw XDrawString 

/set the bitwise logical operation in a graphics context XSetFunction 

XGetDefault: extract an option value from the resource/ XGetDefault 

child to the top of the stacking order /circulate the bottom XCirculaleSubwindowsDown 

to the bottom of the stacking order /circulate the top child XCirculateSubwindowsUp 

size, border width, or stacking order /the window position, XConfigureWindow 

lower a window in the stacking order XLowerWindow: XLowerWindow 

to the top of the stacking order /raise a window XRaise Window 

/circulate the stacking order of children up or down XCirculateSubwindows 

/change the stacking order of siblings XRestack Windows 

XSetClipOrigin: set the clip origin in a graphics context XSetClipOrigin 

/set the tile/stipple origin in a graphics context XSetTSOrigin 

XDrawRectangle: draw an outline of a rectangle XDrawRectangle 

XDrawRectangles: draw the outlines of multiple rectangles XDrawRectangles 

XGetSelectionOwner: return the owner of a selection XGetSelectionOwner 

XSetSelectionOwner: set the owner of a selection XSetSelectionOwner 

get the current screen saver parameters XGetScreenSaver: XGetScreenSaver 

grab /change the parameters of an active pointer XChangeActivePointerGrab 

XSetScreenSaver: set the parameters of the screen saver XSetScreenSaver 

between another window and its parent /insert a window XReparentWindow 

return a list of children, parent, and root XQueryTree: XQueryTree 

create a subimage from part of an image XSublmage: XSuhlmage 

matching both passed window and passed mask; don t wait /event XCheckWindowEvent 

/the next event matching both passed window and passed mask;/ XCheckWindowEvent 

release a button from a passive grab XUngrabButton: XUngrabButton 

XUngrabKey: release a key from a passive grab XUngrabKey 

get the current font search path XGetFontPath: XGetFontPath 

set the font search path XSetFontPath: XSetFontPath 

graphics/ XSetDashes: set a pattern of line dashes in a XSetDashes 

buffer and return the number of pending input events /request XPending 

repaint/ /change a window border pixel value attribute and XSetWindowBorder 

window /set the background pixel value attribute of a XSetWindowBackground 

XGetPixel: obtain a single pixel value from an image XGetPixel 

context /set the background pixel value in a graphics XSetBackground 

context /set the foreground pixel value in a graphics XSetForeground 

/add a constant value to every pixel value in an image XAddPixel 

XPutPixel: set a pixel value in an image XPutPixel 

a drawable with depth, applying pixel values /of a drawable into XCopyPlane 

XTextWidthl6: get the width in pixels of a 16-bit character/ XTextWidthl6 

XTextWidth: get the width in pixels of an 8-bit character/ XTextWidth 

XCreatePixmap: create a pixmap XCreatePixmap 

draw an image on a window or pixmap XPutlmage: XPutlmage 

server /obtain the supported pixmap formats for a given XListPixmapFormats 

XFreePixmap: free a pixmap ID XFreePixmap 

XSetClipMask: set clip_mask pixmap in a graphics context XSetClipMask 

data, /create a pixmap with depth from bitmap XCreatePixmapFromBitmapData 



18 Xlib Reference Manual 



from drawable into/ XGetlmage: place contents of a rectangle XGetlmage 

XSetPlaneMask: set the plane mask in a graphics context XSetPlaneMask 

/logical function, and plane mask in a graphics context XSetState 

XCopyPlane: copy a single plane of a drawable into a/ XCopyPlane 

read/write (nonshareable) color planes /allocate XAllocColorPlanes 

free colormap cells or planes XFreeColors: XFreeColors 

XDrawPoint: draw a point XDrawPoint 

XPointlnRegion: determine if a point is inside a region XPointlnRegion 

/move the pointer to another point on the screen XWarpPointer 

XGrabPointer: grab the pointer XGrabPointer 

XGrabButton: grab a pointer button XGrabButton 

XGetPointerMapping: get the pointer button mapping XGetPointerMapping 

XSetPointerMapping: set the pointer button mapping XSetPointerMapping 

/the behavior of keyboard and pointer events when these/ XAllowEvents 

XUngrabPointer: release the pointer from an active grab XUngrabPointer 

the parameters of an active pointer grab /change XChangeActivePointerGrab 

XQueryPointer: get the current pointer location XQueryPointer 

/get events from pointer motion history buffer XGetMotionEvents 

/change the pointer preferences XChangePointerControl 

/get the current pointer preferences XGetPointerControl 

screen XWarpPointer: move the pointer to another point on the XWarpPointer 

draw a line between two points XDrawLine: XDrawLJne 

XDrawPoints: draw multiple points XDrawPoints 

generate a region from points XPolygonRegion: XPolygonRegion 

XFillPolygon: fill a polygon XFillPolygon 

list/ XDrawFilled: draw a filled polygon or curve from vertex XDrawFilled 

list (from X10) XDraw: draw a polyline or curve between vertex XDraw 

XDrawText: draw 8-bit polylext strings XDrawText 

XDrawTextl6: draw 16-bit polytext strings XDrawTextl6 

window/ XParseGeometry: generate position and size from standard XParseGeometry 

/change the size and position of a window XMoveResize Window 

stacking/ /change the window position, size, border width, or XConfigu re Window 

/colormap entry to the closest possible hardware color XStoreColor 

/colorcells to the closest possible hardware colors XStoreColors 

wait for event matched in predicate procedure XlfEvent: XlfEvent 

/get an event matched by predicate procedure without/ XPeeklfEvent 

to a location within the pre-existing image fm drawable XGetSublmage 

/change the pointer preferences XChangePointerControl 

a list of the current keyboard preferences /obtain XGetKeyboardControl 

get the current pointer preferences XGetPointerControl: XGetPointerControl 

/change the keyboard preferences such as key click XChangeKeyboardControl 

XGetlconSizes: get preferred icon sizes XGetlconSizes 

XrmQGetSearchResource: search prepared list for a given/ XrmQGetSearchResource 

for event matched in predicate procedure XlfEvent: wait XlfEvent 

/an event matched by predicate procedure without removing it/ XPeeklfEvent 

for all events and errors to be processed by the server /wait XSync 

display /disconnect a client program from an X server and XCloseDisplay 

XOpenDisplay: connect a client program to an X server XOpenDisplay 

read one of a window s text properties XGetTextProperty: XGetTextProperty 

set one of a window s text properties XSetTextProperty: XSetTextProperty 

window s standard window manager properties /set a XSetWMProperties 

/rotate properties in the properties array XRotateWindowProperties 

manager /set the minimum set of properties for the window XSetStandardProperties 

XRotateWindowProperties: rotate properties in the properties/ XRotateWindowProperties 

XDeleteProperty: delete a window property XDeleteProperty 

get a window s name (XA_WM_NAME property) XFetchName: XFetchName 

associated with the specified property /structure XGetRGBColormaps 

get the standard colormap property XGetStandardColormap: XGetStandardColormap 



Permuted Index 19 



read the window manager hints 

read a window s XA_WM_ICON_NAME 

read a window s XA_WM_NAME 

a window s XA_WM_NORMAL_HINTS 

read a window s XA_WM_SEE_fflNTS 

the value of the XA_WM_ICON_SIZE 

change the standard colormap 

set a window s WM_CLffiNT_MACHINE 

a window s WM_COLORMAP_WINDOWS 

set a window manager hints 

set a window s XA_WM_ICON_NAME 

set a window s XA_WM_NAME 

a window s XA_WM_NORMAL_fflNTS 

set a window s WM_PROTOCOLS 

set a window s WM_SEE_HINTS 

XChangeProperty: change a 

/set the XA_WM_TRANSIENT_FOR 

/obtain the atom type and 

/get a string name for a 

XGetFontProperty: get a font 

XUstProperries: get the 

/return an atom for a given 

/gettheXA_WM_CLASS 

/gettheXA_WM TRANSffiNT_FOR 

/settheXA_WM_CLASS 

state (not/ /get the size hints 

state (not/ /set the size hints 

/read the size hints 

/set the size hints 

XGetSizeHints: read any 

/set the value of any 

queue XPutBackEvent: 

convert a string to a 

XrmUniqueQuark: allocate a new 

string to a binding list and a 

/convert a key string to a 

value Ao a database using a 

XrmQuarkToString: convert a 

value using name and class as 

into a database using 

font metrics XQueryTextExtents: 

font/ XQueryTextExtents 16: 

number of events in the event 

without removing it from the 

without removing it from the 

push an event back on the input 

XChecklfEvent: check the event 

/return the next event in 

don t/ /return the next event in 

the request buffer (display all 

stacking order XRaiseWindow: 

XDisplayKeycodes: obtain the 

XReadBitmapFile: 

property XGetWMIconName: 

property XGetWMName: 

XGetWMNormalHints: 

property XGetWMSizeHints: 

XA_SIZE_HINTS XGetSizeHints: 



property XGetWMHints: 

property XGetWMIconName: 
property XGetWMName: ....... 

property /read 

property XGetWMSizeHints: 

property XSetlcon Sizes: set ........... 

property XSetStandardColormap: . 
property XSetWMClientMachine: 
property /set 



.XGetWMHints 

.XGetWMIconName 

.XGetWMName 

.XGetWMNormalHints 
.. XGetWMSizeHints 
.. XSetlconSizes 
.. XSetStandardColormap 
... XSetWMClientMachine 
... XSetWMColormapWindows 
,. XSetWMHints 
..XSetWMIconName 
,.. XSetWMName 
.. XSetWMNormalHints 
,. XSetWMProtocols 



property XSetWMHints: 

property XSetWMIconName: 

property. XSetWMName: 

property XSetWMNormalHints: set 

property XSetWMProtocols: 

property XSetWMSizeHints: XSetWMSizeHints 

property associated with a/ XChangeProperty 

property for a window XSetTransientForHint 

property format for a window XGetWindowProperty 

property given its atom XGetAtomName 

property given its atom XGelFontProperty 

property list for a window XListProperties 

property name string XIntemAtom 

property of a window XGetClassHint 

property of a window XGetTransientForHint 

property of a window XSetClassHint 

property of a window in normal XGetNormalHints 

property of a window in normal XSetNormalHints 

property of a zoomed window XGetZoomHints 

property of a zoomed window XSetZoomHints 

property of type XA_SIZE_HINTS XGetSizeHints 

property of type XA_SEE_HINTS XSetSizeHints 

push an event back on the input XPutBackEvent 

quark XrmStringToQuark: XrmStringToQuark 

Quark XrmUniqueQuark 

quark list /convert a key XrmStringToBindingQuarkList 

quark list XrmStringToQuarkList 



.... XrmQPutStringResource 
.... XrmQuarkToString 
.... XrmQGetResource 
.... XrmQPutResource 
.... XQueryTextExtents 
.... XQueryTextExtents 16 
.... XEventsQueued 



quark resource name and string 

quark to a string 

quarks /get a resource 

quarks /a resource specification 

query the server for string and 

query the server for string and ........ 

queue XEventsQueued: check the ... 

queue XPeekEvent: get an event XPeekEvent 

queue /by predicate procedure XPeeklfEvent 

queue XPutBackEvent: XPutBackEvent 

queue for a matching event XChecklfEvent 

queue matching type and window XCheckTypedWindowEvent 

queue that matches event type; XCheckTypedEvent 

queued requests) XFlush: flush XFlush 

raise a window to the top of the XRaiseWindow 

range of legal keycodes for a/ XDisplayKeycodes 

read a bitmap from disk XReadBitmapFile 

read a window s XA_WM_ICON_NAME XGetWMIconName 

read a window s XA_WM_NAME XGetWMName 

read a window s/ XGetWMNormalHints 

read a window s XA_WM_SEE_fflNTS XGetWMSizeHints 
read any property of type XGetSizeHints 



20 



Xlib Reference Manual 



server/ XRefreshKeyboardMapping: read keycode-keysym mapping from XRefreshKeyboardMapping 

properties XGetTextProperty: read one of a window s text XGetTextProperty 

a zoomed window XGetZoomffints: read the size hints property of XGetZoomHints 

property XGetWMHints: read the window manager hints XGetWMffints 

XAllocNamedColor: allocate a read-only colorcell from color/ XAllocNamedColor 

closest/ XAllocColor: allocate a read-only coloimap cell with XAllocColor 

name /set RGB values of a read/write colorcell by color XStoreNamedColor 

/set or change the RGB values of read/write colorcells to the/ XStoreColors 

/or change the RGB values of a read/write colormap entry to the/ XStoreColor 

XAllocColorPlanes: allocate read/write (nonshareable) color/ XAllocColorPlanes 

XAllocColorCells: allocate read/write (nonshared)/ XAllocColorCells 

client XRebindKeysym: rebind a keysym to a string for XRebindKeysym 

that a top-level window be reconfigured /request XReconfigureWMWindow 

draw an arc fitting inside a rectangle XDrawArc: XDrawArc 

draw an outline of a rectangle XDrawRectangle: XDrawRectangle 

XClipBox: generate the smallest rectangle enclosing a region XClipBox 

XGetlmage: place contents of a rectangle from drawable into an/ XGetlmage 

location/ XGetSublmage: copy a rectangle in drawable to a XGetSublmage 

XRectlnRegion: detemune if a rectangle resides in a region XRectlnRegion 

XUnionRectWithRegion: add a rectangle to a region XUnionRectWithRegion 

draw the outlines of multiple rectangles XDrawRectangles: XDrawRectangles 

a graphics context to a list of rectangles /change clip_mask in XSetClipRectangles 

XFillRectangle: fill a rectangular area XFillRectangle 

XClearArea: clear a rectangular area in a window XClearArea 

XFillRectangles: fill multiple rectangular areas XFillRectangles 

region XShrinkRegion: reduce or expand the size of a XShrinkRegion 

smallest rectangle enclosing a region XClipBox: generate the XClipBox 

create a new empty region XCreateRegion: XCreateRegion 

storage associated with a region /deallocate XDestroyRegion 

change offset of a region XOffsetRegion: XOffsetRegion 

determine if a point is inside a region XPointlnRegion: XPointlnRegion 

if a rectangle resides in a region XRectlnRegion: determine XRectlnRegion 

context to the specified region /of the graphics XSetRegion 

reduce or expand the size of a region XShrinkRegion: XShrinkRegion 

add a rectangle to a region XUnionRectWithRegion: XUnionRectWithRegion 

XSubtractRegion: subtract one region from another XSubtraciRegion 

XPolygonRegion: generate a region from points XPolygonRegion 

XFjnptyRegion: determine if a region is empty XEmptyRegion 

compute the intersection of two regions XIntersectRegion: XIntersectRegion 

compute the union of two regions XUnionRegion: XUnionRegion 

union and intersection of two regions /difference between the XXorRegion 

XEqualRegion: determine if two regions have the same size,/ XEqualRegion 

grab XUngrabButton: release a button from a passive XUngrabButton 

XFreeCursor: release a cursor XFreeCursor 

grab XUngrabKey: release a key from a passive XUngrabKey 

active grab XUngrabKeyboard: release the keyboard from an XUngrabKeyboard 

active grab XUngrabPointer: release the pointer from an XUngrabPointer 

XUngrabServer: release the server from grab XUngrabServer 

/destroy a client or its remaining resources XKillClient 

control list XRemoveHost: remove a host from the access XRemoveHost 

client s/ XChangeSaveSet: add or remove a subwindow from the XChangeSaveSet 

client s/ XRemoveFromSaveSet: remove a window from the XRemoveFromSaveSet 

access control/ XRemoveHosts: remove multiple hosts from the XRemoveHosts 

both passed/ XCheckWindowEvent: remove the next event matching XCheckWindowEvent 

matches mask XMaskEvent: remove the next event that XMaskEvent 

matches mask;/ XCheckMaskEvent: remove the next event that XCheckMaskEvent 

matches the/ XWindowEvent: remove the next event that XWindowEvent 

XPeekEvent: get an event without removing it from the queue XPeekEvent 



Permuted Index 21 



/by predicate procedure without 

border pixel value attribute and 

window border tile attribute and 

connection to a/ XDisplayName: 

number of/ XPending: flush the 

events and/ XSync: flush the 

queued/ X Flush: flush the 

be iconified Xlconify Window: 

be/ XReconfigureWMWindow: 

be withdrawn XWithdraw Window: 

list to allow or deny connection 

buffer (display all queued 

XResetScreenSaver: 

/determine if a rectangle 

search prepared list for a given 

extract an option value from the 

XrmDestroyDatabase: destroy a 

a resource specification to a 

a resource specification into a 

line/ XrmParseCommand: load a 

XrmPutFileDatabase: store a 

strings XrmGetResource: get a 

the/ /obtain the GContext 

Xrmlnitialize: initialize the 

Ao a database using a quark 

/specification with separate 

XrmQPutResource: store a 

XrmPutResource: store a 

XrmQPutStringResource: add a 

XrmPutLineResource: add a 

XrmPutStringResource: add a 

class as/ XrmQGetResource: get a 

a client or its remaining 

and pointer events when these 

XrmGetFileDatabase: 

to X supported/ XListExtensions: 

parent, and root XQueryTree: 

XrmQGetSearchList: 

font names XListFonts: 

/copy a colormap and 

property name/ XInternAtom: 

XFetchBuffer: 

XFetchBytes: 

loaded font XQueryFont: 

XGetKeyboardMapping: 

focus window XGetlnputFocus: 

XCheckTypedWindowEvent: 

that matches/ XCheckTypedEvent: 

/flush the request buffer and 

XGetSelectionOwner: 

XLookupColor: get database 

XQueryColor: obtain the 

colorcells XQueryColors: obtain 

or/ XParseColor: look up 

/and closest hardware-supported 

colorcelV XStoreNamedColor: set 

XStoreColor: set or change the 

XStoreColors: set or change the 



removing it from the queue , 

repaint the border /a window , 

repaint the border /change a , 

report the display name (when , 

request buffer and return the , 

request buffer and wait for all 

request buffer (display all 

request that a top-level window 

request that a top-level window ....... 

request that a top-level window ....... 

requests /use access control 

requests) /flush the request 

reset the screen saver 

resides in a region 

resource XrmQGetSearchResource: 

resource database XGetDefault: 

resource database 

resource database /add ..................... 



resource database /store ... 
resource database from command 
resource database in a file 
resource from name and class as ....... 

(resource ID) associated with 

resource manager 

resource name and string value 
resource name and value 
resource specification into a/ 
resource specification into a/ 
resource specification to a/ 
resource specification to a/ 
resource specification with/ 
resource value using name and 
resources XKillClient: destroy 
resources are grabbed /keyboard 
retrieve a database from a file 
return a list of all extensions 

return a list of children, 

return a list of database levels 

return a list of the available 

return a new colormap ID 

return an atom for a given 

return data from a cut buffer 

return data from cut buffer 

return information about a 

return symbols for keycodes 

return the current keyboard 

return the next event in queue/ 

return the next event in queue 

return the number of pending/ 

return the owner of a selection 

RGB values and closest/ 

RGB values and flags for a/ 

RGB values for an array of 

RGB values from ASCII color name . 

RGB values from color name 

RGB values of a read/write 

RGB values of a read/write/ 

RGB values of read/write/ 



.XPeeklfEvent 

, XSetWindowBorder 

, XSetWindowBorderPixmap 

, XDisplayName 

, XPending 

, XSync 

, XFlush 

, Xlconify Window 

, XReconfigureWMWindow 

, XWithdrawWindow 

, XEnableAccessControl 

, XFlush 

, XResetScreenSaver 

, XRectlnRegion 

, XrmQGetSearchResource 

. XGetDefault 

. XrmDestroyDatabase 

, XrmPutLineResource 

, XrmPutResource 

, XrmParseCommand 

. XrmPutFileDatabase 

. XrmGetResource 

. XGContextFromGC 

, Xrmlnitialize 

, XrmQPutStringResource 

, XrmPutStringResource 

, XrmQPutResource 

. XrmPutResource 

. XrmQPutStringResource 

. XrmPutLineResource 

, XrmPutStringResource 

, XrmQGetResource 

. XKillClient 

. XAllowEvents 

. XrmGetFileDatabase 

, XListExtensions 

, XQueryTree 

, XrmQGetSearchList 

, XListFonts 

, XCopyColormapAndFree 

, XInternAtom 

, XFetchBuffer 

, XFetchBytes 

, XQueryFont 

. XGetKeyboardMapping 

. XGetlnputFocus 

. XCheckTypedWindowEvent 

. XCheckTypedEvent 

. XPending 

. XGetSelectionOwner 

. XLookupColor 

. XQueryColor 

. XQueryColors 

. XParseColor 

. XLookupColor 

.XStoreNamedColor 

. XStoreColor 

. XStoreColors 



22 



Xlib Reference Manual 



XBell: 

a list of children, parent, and 

XRotateWindowProperties : 

XRotateBuffers: 

XSetFillRule: set the fill 

fif two regions have the 

to a window and/ XSaveContext: 

reset the screen 

set the parameters of the screen 

/turn the screen 

/get the current screen 

add a window to the client s 

a subwindow from the client s 

a window from the client s 

the depths available on a given 

pointer to another point on the 

XActivateScreenSaver: activate 

XResetScreenSaver: reset the 

set the parameters of the 

XForceScreenSaver: turn the 

XGetScreenSaver: get the current 

. new graphics context for a given 

get the current font 

XSetFontPath: set the font 

resource XrmQGetSearchResource: 

sent to a window XSelectlnput: 

use the value of a 

return the owner of a 

set the owner of a 

connection with the/ XNoOp: 

XSendEvent: 

select the event types to be 

/a resource specification with 

range of legal keycodes for a 

XGrabServer: grab the 

to X supported by Xh b and the 

pixmap formats for a given 

to exercise connection with the 

connect a client program to an X 

errors to be processed by the 

a client program from an X 

XQueryTextExtents: query the 

XQueryTextExtentsl6: query the 

XUngrabServer: release the 

/read keycode-keysym mapping from 

Xlib/ XSetAfterFunction: 

handler XSetErrorHandler: 

a graphics context XSetDashes: 

XPutPixel: 

property XSetWMHints: 

manager/ XSetWMProperties: 

property XSetWMClientMachine: 

XSetWMColormapWindows: 

property XSetWMProtocols: 

property XSetWMSizeHints: 

property XSetWMIconName: 

property. XSetWMName: 

XSetWMNormalHints : 



XBell 

XQueryTree 

, XRotateWindowProperties 



ring the bell (Control G) 

root XQueryTree: return 

rotate properties in the/ 

rotate the cut buffers XRotateBuffers 

rule in a graphics context XSetFillRule 

same size, offset, and shape XEqualRegion 

save a data value corresponding XSaveContext 

saver XResetScreenSaver: XResetScreenSaver 

saver XSetScreenSaver: XSetScreenSaver 

saver on or off XForceScreenSaver 

saver parameters XGetScreenSaver 

save-set XAddToSaveSet: XAddToSaveSet 

save-set /add or remove XChangeSaveSet 

save-set /remove XRemoveFromSaveSet 

screen XUstDepths: determine XListDepths 

screen XWarpPointer: move the XWarpPointer 

screen blanking XActivateScreenSaver 

screen saver XResetScreenSaver 

screen saver XSetScreenSaver: XSetScreenSaver 

screen saver on or off XForceScreenSaver 

screen saver parameters XGetScreenSaver 

screen with the depth of the/ /a XCreateGC 

search path XGetFontPath: XGetFontPath 

search path XSetFontPath 

search prepared list for a given 

select the event types to be 

selection XConvertSelection: 

selection XGetSelectionOwner: .... 

selection XSetSelectionOwner: 

send a NoOp to exercise 

send an event 

sent to a window XSelectlnput: XSelectlnput 

separate resource name and value XrmPutStringResource 

server /obtain the XDisplayKeycodes 

server XGrabServer 

server /a list of all extensions XListExtensions 

server /obtain the supported XListPixmapFormats 

server XNoOp: send a NoOp XNoOp 

server XOpenDisplay: XOpenDisplay 

server /wait for all events and XSync 

server and display /disconnect XCloseDisplay 

server for string and font/ XQueryTextExtents 

server for string and font/ XQueryTextExtents 16 

server from grab XUngrabServer 

server into Xlib XRefreshKeyboardMapping 

set a function called after all XSetAfterFunction 

set a nonfatal error event XSetErrorHandler 

set a pattern of line dashes in XSetDashes 

set a pixel value in an image XPutPixel 

set a window manager hints XSetWMHints 

set a window s standard window XSetWMProperties 

set a window s WM_CLIENT_MACHINE XSetWMClientMachine 

set a window s/ XSetWMColormapWindows 

set a window s WM.PROTOCOLS XSetWMProtocols 

set a window s WM_SEE_HINTS XSetWMSizeHints 

set a window s XA_WM_ICON_NAME XSetWMIconName 

set a window s XA_WM_NAME XSetWMName 

set a window s/ XSetWMNormalHints 



XrmQGetSearchResource 

XSelectlnput 

XConvertSelection 

XGetSelectionOwner 

XSetSelectionOwner 

XNoOp 

XSendEvent 



Permuted Index 



23 



structure XSetRGBColormaps: 

create a window and 

context to the/ XSetRegion: 

graphics context XSetClipMask: 

modifiers/ XSetModifierMapping: 

manager /set the minimum 

properties XSetTextProperty: 

a read/write/ XStoreColor: 

read/write/ XStoreColors: 

colorcell by/ XStoreNamedColor: 

context XSetArcMode: 

attribute/ XSetWindowBackground: 

in a graphics/ XSetBackground: 

operation in a/ XSetFunction: 

graphics/ XSetClipOrigin: 

window XSetWindowColormap: 

graphics context XSetFont: 

context XSetFillRule: 

context XSetFillStyle: 

context XSetTile: 

XSetFontPath: 

logical function,/ XSetState: 

in a graphics/ XSetForeground: 

XSetGraphicsExposures: 

XSetlnputFocus: 

in a/ XSetLine Attributes: 

XSetStandardProperties : 

a window s icon XSetlconName: 

XSetSelectionOwner: 

saver XSetScreenSaver: 

context XSetPlaneMask: 

XSetPointerMapping : 

window in/ XSetNormalHints: 

zoomed window XSetZoomHints: 

XStringListToTextProperty: 

context XSetStipple: 

graphics/ XSetSubwindowMode: 

graphics context XSetTSOrigin: 

type/ XSetSizeHints: 

XA_WM_ICON_SIZE/ XSetlconSizes: 

a window XSelClassHint: 

(command line/ XSetCommand: 

property/ XSetTransientForHint: 

XChangeWindow Attributes : 

have the same size, offset, and 

the fastest supported stipple 

the fastest supported fill tile 

a mapping of modifier keys 

keycodes to be used as modifiers 

map a window on top of its 

change the stacking order of 

XGetPixel: obtain a 

a drawable/ XCopyPlane: copy a 

cursor, tile, or stipple 

XResize Window: change a window s 

XMoveResize Window: change the 

/change the window position, 

geometry/ /generate position and 



set an XStandardColormap 

set attributes XCreate Window: 

set clip_mask of the graphics 

set clip_mask pixmap in a 

set keycodes to be used as 

set of properties for the window 

set one of a window s text 

set or change the RGB values of 

set or change the RGB values of 

set RGB values of a read/write 

set the arc mode in a graphics , 

set the background pixel value , 

set the background pixel value , 

set the bitwise logical , 

set the clip origin in a , 

set the colormap attribute for a , 

set the current font in a , 

set the fill rule in a graphics , 

set the fill style in a graphics , 

set the fill tile in a graphics , 

set the font search path , 

set the foreground, background, , 

set the foreground pixel value 

set the graphics_exposures/ 

set the keyboard focus window , 

set the line drawing components , 

set the minimum set of/ 

set the name to be displayed in 

set the owner of a selection 

set the parameters of the screen 

set the plane mask in a graphics 

set the pointer button mapping 

set the size hints property of a 

set the size hints property of a 

set the specified list of/ 

set the stipple in a graphics 

set the subwindow mode in a 

set the tile/stipple origin in a 

set the value of any property of 

set the value of the 

set the XA_WM_CLASS property of .. 
set the XA_WM_COMMAND atom .. 
set the XA_WM_TRANSIENT_FOR 

set window attributes 

shape /determine if two regions 

shape XQueryBestStipple: obtain 

shape XQueryBestTile: obtain 

(Shift, Control, etc.) /obtain 

(Shift, Control, etc.) /set 

siblings XMapRaised: 

siblings XRestackWindows: 

single pixel value from an image 

single plane of a drawable into 

size /the "best" supported 

SJ2 .............,....,....... , 

size and position of a window 

size, border width, or stacking/ , 

size from standard window , 



.XSetRGBColormaps 

. XCreateWindow 

, XSetRegion 

. XSetClipMask 

. XSetModifierMapping 

. XSetStandardProperties 

. XSetTextProperty 

. XStoreColor 

. XStoreColors 

. XStoreNamedColor 

. XSetArcMode 

. XSetWindowBackground 

. XSetBackground 

. XSetFunction 

. XSetClipOrigin 

. XSetWindowColormap 

. XSetFont 

. XSetFillRule 

. XSetFillStyle 

. XSetTile 

. XSetFontPath 

.XSetState 

. XSetForeground 

. XSetGraphicsExposures 

. XSetlnputFocus 

. XSetLineAttributes 

. XSetStandardProperties 

. XSetlconName 

. XSetSelectionOwner 

. XSetScreenSaver 

. XSetPlaneMask 

. XSetPointerMapping 

. XSetNormalHints 

. XSetZoomHints 

. XStringListToTextProperty 

. XSetStipple 

. XSetSubwindowMode 

. XSetTSOrigin 

. XSetSizeHints 

. XSetlconSizes 

. XSetClassHint 

. XSetCommand 

. XSetTransientForHint 

. XChangeWindow Attributes 

. XEqualRegion 

. XQueryBestStipple 

. XQueryBestTile 

. XGetModifierMapping 

. XSetModifierMapping 

.XMapRaised 

. XRestackWindows 

.XGetPixel 

.XCopyPlane 

. XQueryBestSize 

. XResizeWindow 

. XMoveResize Window 

. XConfigure Window 

. XParseGeometry 



24 



Xlib Reference Manual 



in/ XGetNormalHints: get the size hints property of a window XGetNormalHints 

in/ XSetNormalHints: set the size hints property of a window XSetNormalHints 

window XGetZoomHints: read the size hints property of a zoomed XGetZoomHints 

window XSetZoomHints: set the size hints property of a zoomed XSetZoomHints 

reduce or expand the size of a region XShrinkRegion: XShrinkRegion 

/if two regions have the same size, offset, and shape XEqualRegion 

get preferred icon sizes XGetlconSizes: XGetlconSizes 

get the closest supported cursor sizes XQueryBestCurson XQueryBestCursor 

region XClipBox: generate the smallest rectangle enclosing a XClipBox 

using quarks /store a resource specification into a database XrmQPutResource 

XrmPutResource: store a resource specification into a resource/ XrmPutResource 

using a quark/ /add a resource specification to a database XrmQPutStringResource 

database /add a resource specification to a resource XrmPutLJneResource 

resource name/ /add a resource specification with separate XrmPutStringResource 

the RGB values and flags for a specified colorcell /obtain XQueryColor 

screen with the depth of the specified drawable /for a given XCreateGC 

/ID) associated with the specified graphics context XGContextFromGC 

XTextProperty structure /set the specified list of strings to an XStringlastToTextProperty 

/the next event that matches the specified mask and window XWindowEvent 

Xh b function XFree: free specified memory allocated by an XFree 

/structure associated with the specified property XGetRGBColormaps 

of the graphics context to the specified region /set clip_mask XSetRegion 

data associated with the specified string list /in-memory XFreeStringList 

structures that match the specified template /information XGetVisuallnfo 

/obtain a list of strings from a specified XTextProperty/ XTextProperty ToStringList 

bottom child to the top of the stacking order /circulate the XCirculateSubwindowsDown 

top child to the bottom of the stacking order /circulate the XCirculateSubwindowsUp 

position, size, border width, or stacking order /the window XConfigure Window 

lower a window in the stacking order XLowerWindow: XLowerWindow 

raise a window to the top of the stacking order XRaiseWindow: XRaiseWindow 

down /circulate the stacking order of children up or XCirculateSubwindows 

XRestack Windows: change the stacking order of siblings XRestack Windows 

XGetStandardColormap: get the standard colormap property XGetStandardColormap 

XSetStandardColormap: change the standard colormap property XSetStandardColormap 

/create a cursor from the standard cursor font XCreateFontCursor 

/generate position and size from standard window geometry string XParseGeometry 

XSetWMProperties: set a window s standard window manager/ XSetWMProperties 

/property of a window in normal state (not zoomed or iconified) XGetNormalHints 

/property of a window in normal state (not zoomed or iconified) XSetNormalHints 

a bit vector for the current state of the keyboard /obtain XQueryKeymap 

XSetStipple: set the stipple in a graphics context XSetStipple 

/obtain the fastest supported stipple shape XQueryBestStipple 

supported cursor, tile, or stipple size /the "best" XQueryBestSize 

XDestroyRegion: deallocate storage associated with a region XDestroyRegion 

/unload a font and free storage for the font structure XFreeFont 

file XrmPutFileDatabase: store a resource database in a XrmPutFileDatabase 

into a/ XrmQPutResource: store a resource specification XrmQPutResource 

into a resource/ XrmPutResource: store a resource specification XrmPutResource 

XStoreBuffer: store data in a cut buffer XStoreBuffer 

XStoreBytes: store data in cut buffer XStoreBytes 

atom for a given property name string XIntemAtom: return an XIntemAtom 

convert a keysym symbol to a string XKeysymToString: XKeysymToString 

from standard window geometry string /position and size XParseGeometry 

metrics of a 16-bit character string /for string and font XQueryTextExtents 16 

create a database from a string XrmGetStringDatabase: XrmGetStringDatabase 

convert a quark to a string XrmQuarkToString: XrmQuarkToString 

/geometry given user geometry string and default geometry XGeometry 

/query the server for string and font metrics XQueryTextExtents 



Permuted Index 25 



XTextExtents: get string and font metrics locally XTextExtents 

16-bit/ /query the server for string and font metrics of a XQueryTextExtentsl6 

1 6-bit/ XTextExtents 1 6: get string and font metrics of a XTextExtents 1 6 

/rebind a keysym to a string for client XRebindKeysym 

XDrawString: draw an 8-bit text string, foreground only XDrawString 

Anap a key event to ASCII string, keysym, and/ XLookupString 

associated with the specified string list /the in-memory data XFreeStringList 

metrics of a 16-bit character string, locally /string and font XTextExtents 16 

in pixels of an 8-bit character string, locally /get the width XTextWidth 

in pixels of a 16-bit character string, locally /get the width XTextWidth 16 

its atom XGetAtomName: get a string name for a property given XGetAtomName 

quark list /convert a key string to a binding list and a XrmStringToBindingQuarkList 

/convert a keysym name string to a keysym XStringToKeysym 

XrmStringToQuark: convert a string to a quark XrmStringToQuark 

/convert a key string to a quark list XrmStringToQuarkList 

using a quark resource name and string value Ao a database XrmQPutStringResource 

draw two-byte text strings XDrawString 16: XDrawString 16 

XDrawText: draw 8-bit polytext strings XDrawText 

draw 16-bit polytext strings XDrawTextl6: XDrawTextl6 

resource from name and class as strings XrmGetResource: get a XrmGelResource 

XTextProperty/ /obtain a list of strings from a specified XTextPropertyToSlringList 

/set the specified list of strings to an XTextProperty/ XStringListToTextProperty 

allocate an XClassHint structure XAllocClassHint: XAllocClassHint 

allocate an XlconSize structure XAllocIconSize: XAllocIconSize 

allocate an XSizeHints structure XAllocSizeHints: XAllocSizeHints 

/allocate an XStandardColormap structure XAllocStandardColormap 

allocate an XWMHints structure XAllocWMHints: XAllocWMHints 

allocate memory for an Xlmage structure XCreatelmage: XCreatelmage 

an entry from an XModifierKeymap structure /delete XDeleteModifiermapEntry 

and free storage for the font structure Ainload a font XFreeFont 

free a keyboard modifier mapping structure /destroy and XFreeModifiermap 

new entry to an XModifierKeymap structure /add a XlnsertModifiermapEntry 

load a font and fill information structure XLoadQueryFont: XLoadQueryFont 

corresponding to a keycode in structure /get the keysym XLookupKeysym 

a keyboard modifier mapping structure /create XNewModifiermap 

set an XStandardColormap structure XSetRGBColormaps: XSetRGBColormaps 

of strings to an XTextProperty structure /the specified list XStringListToTextProperty 

from a specified XTextProperty structure /a list of strings XTextProperty ToStringList 

/obtain the XStandardColormap structure associated with the/ XGetRGBColormaps 

A"ind the visual information structures that match the/ XGetVisuallnfo 

XSetFillStyle: set the fill style in a graphics context XSetFillStyle 

XSublmage: create a subimage from part of an image XSublmage 

XSubtractRegion: subtract one region from another XSubtractRegion 

XChangeSaveSet: add or remove a subwindow from the client s/ XChangeSaveSet 

XSetSubwindowMode: set the subwindow mode in a graphics/ XSetSubwindowMode 

and destroy a window and all subwindows. Ainmap XDestroy Window 

XUnmapSubwindows: unmap all subwindows of a given window XUnmapSubwindows 

XDestroySubwindows: destroy all subwindows of a window XDestroySubwindows 

XMapSubwindows: map all subwindows of window XMapSubwindows 

/change the keyboard preferences such as key click XChangeKeyboardControl 

/a list of all extensions to X supported by Xlib and the server XListExtensions 

/get the closest supported cursor sizes XQueryBestCursor 

stipple/ /obtain the "best" supported cursor, tile, or XQueryBestSize 

/obtain the fastest supported fill tile shape XQueryBestTile 

XlistPixmapFormats: obtain the supported pixmap formats for a/ XlistPixmapFormats 

/obtain the fastest supported stipple shape XQueryBestStipple 

/convert a keysym symbol to a string XKeysymToString 

XGetKeyboardMapping: return symbols for keycodes XGetKeyboardMapping 



26 Xlib Reference Manual 



XSynchronize: enable or disable synchronization for debugging XSynchronize 

another /change the coordinate system from one window to XTranslateCoordinates 

an entry from an association table. XDeleteAssoc: delete XDeleteAssoc 

allocated for an association table, /free the memory XDestroyAssocTable 

obtain data from an association table XLookUpAssoc: XLookUpAssoc 

an entry in an association table XMakeAssoc: create XMakeAssoc 

create a new association table (X10) XCreateAssocTable: XCreateAssocTable 

that match the specified template /information structures XGetVisuallnfo 

/draw 8-bit image text characters XDrawImageString 

/draw 16-bit image text characters XDrawImageString 16 

/read one of a window s text properties XGetTextProperty 

/set one of a window s text properties XSetTextProperty 

XDrawString: draw an 8-bit text string, foreground only XDrawString 

XDrawString 16: draw two-byte text strings XDrawString 1 6 

border /change a window border tile attribute and repaint the XSetWindowBorderPixmap 

/change the background tile attribute of a window XSetWindowBackgroundPixmap 

XSelTile: set the fill tile in a graphics context XSetTile 

the "best" supported cursor, tile, or stipple size /obtain XQueryBestSize 

the fastest supported fill tile shape /obtain XQueryBestTile 

graphics/ XSetTSOrigin: set the tile/stipple origin in a XSetTSOrigin 

stacking order /circulate the top child to the bottom of the XCirculateSubwindowsUp 

XMapRaised: map a window on top of its siblings XMapRaised 

/the bottom child to the top of the stacking order XCirculateSubwindowsDown 

/raise a window to the top of the stacking order XRaiseWindow 

Xlconify Window: request that a top-level window be iconified XlconifyWindow 

/request that a top-level window be reconfigured XReconfigureWMWindow 

XWithdrawWindow: request that a top-level window be withdrawn XWithdrawWindow 

values from ASCII color name or translate hexadecimal value /RGB XParseColor 

auto-repeat/ XAutoRepeatOff : turn off the keyboard XAutoRepeatOff 

keys XAutoRepeatOn: turn on the keyboard auto-repeat XAutoRepeatOn 

XForceScreenSaver: turn the screen saver on or off XForceScreenSaver 

/create a cursor from two bitmaps XCreatePixmapCursor 

XDrawLine: draw a line between two points XDrawLine 

compute the intersection of two regions XInterseclRegion: XIntersectRegion 

compute the union of two regions XUnionRegion: XUnionRegion 

the union and intersection of two regions /difference between XXorRegion 

XEqualRcgion: determine if two regions have the same size/ XEqualRegion 

XDrawStringl6: draw two-byte text strings XDrawStringl6 

entry for a given window and type /delete a context XDeleteContext 

window /obtain the atom type and property format for a XGetWindowProperty 

the next event in queue matching type and window /return XCheckTypedWindowEvent 

in queue that matches event type; don t wait /the next event XCheckTypedEvent 

Ao a window and context type (not graphics context) XSaveContext 

get the next event of any type or window XNextEvent: XNextEvent 

/read any property of type XA_SEE_fflNTS XGetSizeHints 

/set the value of any property of type XA_SEE_HINTS XSetSizeHints 

XSelectlnput: select the event types to be sent to a window XSelectlnput 

default if/ XUninstallColormap: uninstall a colormap; install XUninstallColormap 

/the difference between the union and intersection of two/ XXorRegion 

XUnionRegion: compute the union of two regions XUnionRegion 

XUnloadFont: unload a font XUnloadFont 

for the font/ XFreeFont: unload a font and free storage XFreeFont 

XUnmapWindow: unmap a window XUnmapWindow 

window XUnmapSubwindows: unmap all subwindows of a given XUnmapSubwindows 

all subwindows. XDestroyWindow: unmap and destroy a window and XDestroyWindow 

XCreateSimple Window: create an unmapped InputOutput window XCreateSimple Window 

/calculate window geometry given user geometry string and default/ XGeometry 

/specification to a database using a quark resource name and/ XrmQPutStringResource 



Permuted Index 27 



/get a resource value using name and class as quarks XrmQGetResource 

specification into a database using quarks /store a resource XrmQPutResource 

name or translate hexadecimal value /values from ASCII color XParseColor 

with separate resource name and value /a resource specification XrmPutStringResource 

a quark resource name and string value /to a database using XrmQPutSlringResource 

/change a window border pixel value attribute and repaint the/ XSetWindowBorder 

/set the background pixel value attribute of a window XSetWindowBackground 

and/ XSaveContext: save a data value corresponding to a window XSaveContext 

XGetPixel: obtain a single pixel value from an image XGetPixel 

XGetDefault: extract an option value from the resource database XGetDefault 

/set the background pixel value in a graphics context XSetBackground 

/set the foreground pixel value in a graphics context XSetForeground 

a constant value to every pixel value in an image /add XAddPixel 

XPutPixel: set a pixel value in an image XPutPixel 

XConvertSelection: use the value of a selection XConvertSelection 

XSetSizeHints: set the value of any property of type/ XSetSizeHints 

property XSetlconSizes: set the value of the XA_WM_ICON_SIZE XSetlconSizes 

image XAddPixel: add a constant value to every pixel value in an XAddPixel 

XrmQGetResource: get a resource value using name and class as/ XrmQGetResource 

with depth, applying pixel values /drawable into a drawable XCopyPlane 

XLookupColor: get database RGB values and closest/ XLookupColor 

XQueryColor: obtain the RGB values and nags for a specified/ XQueryColor 

XQueryColors: obtain RGB values for an array of/ XQueryColors 

XParseColor: look up RGB values from ASCII color name or/ XParseColor 

closest hardware-supported RGB values from color name /and XLookupColor 

by/ XStoreNamedColor: set RGB values of a read/write colorcell XStoreNamedColor 

entry to/ /set or change the RGB values of a read/write colormap XStoreColor 

to the/ /set or change the RGB values of read/write colorcells XStoreColors 

the/ XQueryKeymap: obtain a bit vector for the current state of XQueryKeymap 

draw a polyline or curve between vertex list (from X10) XDraw: XDraw 

a filled polygon or curve from vertex list (from X10) /draw XDrawFilled 

obtain the visual ID from a Visual XVisuallDFrom Visual: XVisuallDFrom Visual 

XVisuallDFrom Visual: obtain the visual ID from a Visual XVisuallDFrom Visual 

that/ XGetVisuallnfo: find the visual information structures XGetVisuallnfo 

XMatchVisuallnfo: obtain the visual information that matches/ XMatchVisuallnfo 

event that matches mask; don t wait /remove the next XCheckMaskEvent 

that matches event type; don t wait /the next event in queue XCheckTypedEvent 

window and passed mask; don t wait /event matching both passed XCheckWindowEvent 

to/ /flush the request buffer and wait for all events and errors XSync 

predicate procedure XlfEvent: wait for event matched in XlfEvent 

fails) /report the display name (when connection to a display XDisplayName 

character/ XTextWidthl6: get the width in pixels of a 16-bit XTextWidthl6 

character/ XTextWidth: get the width in pixels of an 8-bit XTextWidth 

/change the border width of a window XSetWindowBorderWidth 

window position, size, border width, or stacking order /the XConfigure Window 

a property associated with a window XChangeProperty: change XChangeProperty 

event in queue matching type and window /return the next XCheckTypedWindowEvent 

clear a rectangular area in a window XClearArea: XClearArea 

XClearWindow: clear an entire window XClearWindow 

create an unmapped InputOutput window XCreateSimple Window: XCreateSimpleWindow 

assign a cursor to a window XDefineCursor: XDefineCursor 

destroy all subwindows of a window XDestroySubwindows: XDestroySubwindows 

the XA_WM_CLASS property of a window XGetClassHint: get XGetClassHint 

the current keyboard focus window XGetlnputFocus: return , XGetlnputFocus 

property of a window /the XA_WM_TRANSIENT_FOR XGetTransientForHint 

obtain the current attributes of window XGetWindow Attributes: XGetWindow Attributes 

type and property format for a window /obtain the atom XGetWindowProperty 

size hints property of a zoomed window XGetZoomHints: read the XGetZoomHints 



28 Xlib Reference Manual 



get the property list for a window XListProperties: XListProperties 

map all subwindows of window XMapSub windows: XMapSubwindows 

XMapWindow: map a window XMap Window 

the size and position of a window /change XMoveResize Window 

XMove Window: move a window XMoveWindow 

the next event of any type or window XNextEvent: get XNextEvent 

the event types to be sent to a window XSelectlnput: select XSelectlnput 

the XA_WM_CLASS property of a window XSetClassHint: set XSetClassHint 

set the keyboard focus window XSetlnputFocus: XSetlnputFocus 

property for a window /the XA_WM_TRANSIENT_FOR XSetTransientForHint 

pixel value attribute of a window /set the background XSetWindowBackground 

background tile attribute of a window /change the XSetWindowBackgroundPixmap 

change the border width of a window XSetWindowBorderWidth: XSetWindowBorderWidth 

set the colormap attribute for a window XSetWindowColormap: XSetWindowColormap 

size hints property of a zoomed window XSetZoomHints: set the XSetZoomHints 

disassociate a cursor from a window XUndefineCursor: XUndefineCursor 

unmap all subwindows of a given window XUnmapSubwindows: XUnmapSubwindows 

XUnmapWindow: unmap a window XUnmapWindow 

matches the specified mask and window /the next event that XWindowEvent 

/unmap and destroy a window and all subwindows XDestroy Window 

/a data value corresponding to a window and context type (not/ XSaveContext 

/insert a window between another window and its parent XReparentWindow 

/next event matching both passed window and passed mask; don t/ XCheckWindowEvent 

XCreate Window: create a window and set attributes XCreate Window 

a context entry for a given window and type /delete XDeleteContext 

XChangeWindow Attributes: set window attributes XChangeWindow Attributes 

/request that a top-level window be iconified Xlconify Window 

/request that a top-level window be reconfigured XReconfigureWMWindow 

/request that a top-level window be withdrawn XWithdrawWindow 

and/ XReparentWindow: insert a window between another window XReparentWindow 

XSetWindowBorder: change a window border pixel value/ XSetWindowBorder 

XSetWindowBorderPixmap: change a window border tile attribute and/ XSetWindowBorderPixmap 

XStoreName: assign a name to a window for the window manager XStoreName 

XRemoveFromSaveSet: remove a window from the client s/ XRemoveFromSaveSet 

geometry/ XGeometry: calculate window geometry given user XGeometry 

position and size from standard window geometry string /generate XParseGeometry 

/get the size hints property of a window in normal state (not/ XGetNormalHints 

/set the size hints property of a window in normal state (not/ XSetNormalHints 

XLowerWindow: lower a window in the stacking order XLowerWindow 

set of properties for the window manager /set the minimum XSetStandardProperties 

a name to a window for the window manager /assign XStoreName 

XGetWMHints: read the window manager hints property XGetWMHints 

XSetWMHints: set a window manager hints property XSetWMHints 

/set a window s standard window manager properties XSetWMProperties 

XMapRaised: map a window on top of its siblings XMapRaised 

XPutlmage: draw an image on a window or pixmap XPutlmage 

XConfigureWindow: change the window position, size, border/ XConfigureWindow 

XDeleteProperty: delete a window property XDeleteProperty 

the coordinate system from one window to another /change XTranslateCoordinates 

XAddToSaveSet: add a window to the client s save-set XAddToSaveSet 

stacking/ XRaise Window: raise a window to the top of the XRaiseWindow 

XWMGeometry: obtain a window s geometry information XWMGeometry 

the name to be displayed in a window s icon XSetlconName: set XSetlconName 

property) XFetchName: get a window s name (XA_WM_NAME XFetchName 

XResize Window: change a window s size XResizeWindow 

XSetWMProperties: set a window s standard window manager/ . XSetWMProperties 

XGetTextProperty: read one of a window s text properties XGetTextProperty 

XSetTextProperty: set one of a window s text properties XSetTextProperty 



Permuted Index 29 



XSetWMCIientMachine: set a 

XSetWMColoimap Windows: set a 

XSetWMProtocols: set a 

XSetWMSizeHints: set a 

property XGetWMIconName: read a 

property XSetWMIconName: set a 

XGetWMName: read a 

XSetWMName:seta 

XGetWMNormalHints: read a 

XSetWMNormalHints: set a 

XGetWMSizeHints: read a 

that a top-level window be 

/set a window s 

/set a window s 

XSetWMProtocols: set a window s 

XSetWMSizeHints: set a window s 

XWriteBitmapFile: 

connect a client program to an 

a client program from an 

/a list of all extensions to 

create a new association table 

curve between vertex list (from 

or curve from vertex list (from 

/create a bitmap from 

read any property of type 

value of any property of type 

XGetClassHint: get the 

XSetClassHint: set the 

arguments) XSetCommand: set the 

XGetWMIconName: read a window s 

XSetWMIconName: set a window s 

/set the value of the 

XFetchName: get a window s name 

XGetWMName: read a window s 

XSetWMName: set a window s 

/read a window s 

/set a window s 

XGetWMSizeHints: read a window s 

a/ XSetTransientForHint: set the 

a/ XGetTransientForHint: get the 

XAllocClassHint: allocate an 

free the memory allocated by 

XAllocIconSize: allocate an 

allocate memory for an 

components of a given GC from 

free the memory allocated by 

/free the memory allocated by 

/delete an entry from an 

/add a new entry to an 

XAllocSizeHints: allocate an 

/allocate an 

XSetRGBColormaps: set an 

XGetRGBColormaps: obtain the 

specified list of strings to an 

list of strings from a specified 

XAllocWMHints: allocate an 

of a window in normal state (not 

of a window in normal state (not 



window s WM_CLIENT_MACHINE/ ... XSetWMCIientMachine 
window s WM_COLORMAP_WINDOWS/ XSetWMColormapWindows 
window s WM_PROTOCOLS property . XSetWMProtocols 
window s WM_SIZE_HINTS property .. XSetWMSizeHints 

window s XA_WMJCON_NAME XGetWMIconName 

window s XA_WM_ICON_NAME XSetWMIconName 

window s XA_WM_NAME property XGetWMName 

window s XA_WM_NAME property XSetWMName 

window s XA_WM_NORMAL_HINTS/ XGetWMNormalHints 
window s XA_WM_NORMAL_HINTS/ XSetWMNormalHints 

window s XA_WM_SEE_fflNTS/ XGetWMSizeHints 

withdrawn /request XWithdrawWindow 

WM_CLIENT_MACHINE property XSetWMCIientMachine 

WM_COLORMAP_WINDOWS property XSetWMColormapWindows 

WM_PROTOCOLS property XSetWMProtocols 

WM_SEE_fflNTS property XSetWMSizeHints 

write a bitmap to a file XWriteBitmapFile 

X server XOpenDisplay: XOpenDisplay 

X server and display /disconnect XCloseDisplay 

X supported by Xlib and the/ XListExtensions 

(X10) XCreateAssocTable: XCreateAssocTable 

X10) XDraw: draw a polyline or XDraw 

X10) /draw a filled polygon XDrawFilled 

XI 1 bitmap format data XCreateBitmapFromData 

XA_SEE_fflNTS XGetSizeHints: XGetSizeHints 

XA_SEE_HINTS /set the XSetSizeHints 

XA_WM_CLASS property of a window .XGetClassHint 
XA_WM_CLASS property of a window . XSetClassHint 
XA_WM_COMMAND atom (command line XSetCommand 

XA_WM_ICON_NAME property XGetWMIconName 

XA_WM_ICON_NAME property XSetWMIconName 

XA_WM_ICON_SIZE property XSetlconSizes 

(XA_WM_NAME property) XFetchName 

XA_WM_NAME property XGetWMName 

XA_WM_NAME property XSetWMName 

XA_WM_NORMAL_fflNTS property .. XGetWMNormalHints 
XA_WM_NORMAL_HINTS property .. XSetWMNormalHints 

XA_WM_SEE_HINTS property XGetWMSizeHints 

XA_WM_TRANSIENT_FOR property for XSetTransientForHint 
XA_WM_TRANSIENT_FOR property of XGetTransientForHint 



XClassHint structure 

XGetFontPath XFreeFontPath: ... 

XlconSize structure 

Xlmage structure XCreatelmage: 

Xlib s GC cache /obtain 

XListFonts. XFreeFontNames: .... 

XListFontsWithlnfo 

XModifierKeymap structure 

XModifierKeymap structure 

XSizeHints structure 

XStandardColormap structure 

XStandardColormap structure 

XStandardColormap structure/ 

XTextProperty structure /set the 

XTextProperty structure /a 

XWMHints structure 

zoomed or iconified) /property 

zoomed or iconified) /property 



XAllocClassHint 

XFreeFontPath 

XAllocIconSize 

XCreatelmage 

XGetGCValues 

XFreeFontNames 

XFreeFontlnfo 

XDeleteModifiermapEntry 

XlnsertModifiermapEntry 

XAllocSizeHints 

XAllocStandardColormap 

XSetRGBColormaps 

XGetRGBColormaps 

XStringListToTextProperty 

XTextPropertyToStringList 

XAllocWMHints 

XGetNormalHints 

XSetNormalHints 



30 



Xlib Reference Manual 



the size hints property of a zoomed window /read XGetZoomHints 

set the size hints property of a zoomed window XSetZoomHints: XSetZoomHints 



Permuted Index 31 



-xiib- Function Group / Introduction 

This page describes the format of each reference page in this volume. 



Name 

XFunctionName brief description of the function. 

Synopsis 

The Synopsis section presents the calling syntax for the routine, including the declarations of 
the arguments and return type. For example: 

returntype XFunctionName ( argl , arg2 , arg3) ; 
typel argl ; 

type2 *arg2; /* RETURN */ 

type3 *arg3; /* SEND and RETURN */ 

The return type Status is of type int; it returns either True or False to indicate whether 
the routine was successful. 

Arguments 

The Arguments section describes each of the arguments used by the function. There are three 
sorts of arguments: arguments that specify data to the function, arguments that return data from 
the function, and arguments that do both. An example of each type is shown below: 

argl Specifies information for XFunctionName. The description of arguments that 

pass data to the function always begins with the word "Specifies," as shown in this 
example. 

arg2 Returns a pointer to data to be filled in by XFunctionName. The description of 

arguments that return data from the function always begins with the word 
"Returns." 

arg3 Specifies information for XFunctionName, and returns data from the function. 

The description of arguments that both pass data to the function and return data 
from the function uses both the words "Specifies" and "Returns." 

Availability 

The Availability section specifies that a given function is only available in Release 4 and later 
releases. If there is no Availability section, the function is available prior to Release 4. 

Description 

The Description section describes what the function does, what it returns, and what events or 
side-effects it causes. It also contains miscellaneous information such as examples of usage, 
special error cases, and pointers to related information in both volumes of this manual. 

Structures 

The Structures section contains the C definitions of the X-specific data types used by 
FunctionName as arguments or return values. It also contains definitions of important con- 



Xlib Reference Manual 33 



Introduction (continued) Xlib - Function Group 

slants used by the function. Additional structures not shown can be found in Appendix F, 
Structure Reference. 

Errors 

The general description of the error types is contained in Appendix B, Error Messages and Pro 
tocol Requests. Some functions generate errors due to function-specific interpretation of argu 
ments. Where appropriate, these function-specific causes have been listed along with the error 
event types they generate. 

Related Commands 

The Related Commands section lists the Xlib functions and macros related to XFunct ion- 
Name. 



34 Xlib Reference Manual 



Xlib - Screen Saver- 



J XActivateScreenSaver 



Name 

XActivateScreenSaver activate screen blanking. 
Synopsis 

XActivateScreenSaver (display) 
Display *di splay; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

Description 

XActivateScreenSaver turns on the screen saver using the parameters set with XSet- 
ScreenSaver. The screen saver blanks the screen or makes random changes to the display 
in order to save the phosphors from burnout when the screen is left unattended for an extended 
period of time. The interval that the server will wait before starting screen save activity can be 
set with XSetScreenSaver. Exactly how the screen saver works is server-dependent. 

For more information on the screen saver, see Volume One, Chapter 13, Other Programming 
Techniques. 

Related Commands 

XForceScreenSaver, XGetScreenSaver, XResetScreenSaver, XSetScreen 
Saver. 



Xlib Reference Manual 35 



XAddHOSt Xnb-Hos.Accsss- 

Name 

XAddHost add a host to the access control list. 

Synopsis 

XAddHost (display, host) 
Display *display; 
XHostAddress *host; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

host Specifies the network address of the host machine to be added. 

Description 

XAddHost adds the specified host to the access control list for the server specified by dis 
play. The access control list is a primitive security feature that allows access to the server 
only by other machines listed in a file on the machine running the server. On UNIX-based sys 
tems, this file is called letclX?. hosts, where ? is the number of the server. 

The application that calls XAddHost and the server whose list is being updated must be run 
ning on the same host machine. 

The address data must be a valid address for the type of network in which the server oper 
ates, as specified in the family member. Internet, DECnet and ChaosNet networks are cur 
rently supported. 

For TCP/IP, the address should be in network byte order. For the DECnet family, the server 
performs no automatic swapping on the address bytes. A Phase IV address is two bytes long. 
The first byte contains the least significant eight bits of the node number. The second byte con 
tains the most significant two bits of the node number in the least significant two bits of the 
byte, and the area in the most significant six bits of the byte. 

For more information on access control, see Volume One, Chapter 13, Other Programming 
Techniques. 

Structures 

typedef struct { 

int family; /* for example Familylnternet */ 

int length; /* length of address, in bytes */ 

char *address; /* pointer to where to find the bytes */ 

} XHostAddress; 

/* The following constants for family member */ 

#define Familylnternet 

ttdefine FamilyDECnet 1 

#define FamilyChaos 2 

Errors 

BadAccess 
BadValue 



36 XHb Reference Manual 



Xlib - Host Access (continued) XAddHost 

Related Commands 

XAddHosts, XDisableAccessControl, XEnableAccessControl, XListHosts, 
XRemoveHost, XRemoveHosts, XSetAccessControl. 



Xlib Reference Manual 



XAddHOStS X,, b -Hos, Access- 

Name 

XAddHosts add multiple hosts to the access control list. 

Synopsis 

XAddHosts ( display, hosts, num_hosts) 
Display *display; 
XHost Address * hosts; 
int num_hosts; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

hosts Specifies each host that is to be added. 

n um_h osts Specifies the number of hosts that are to be added. 

Description 

XAddHosts adds each specified host to the access control list for the server specified by dis 
play. The access control list is a primitive security feature that allows access to the server 
only by other machines listed in a file on the machine running the server. On UNIX systems, 
this file is letclX?. hosts, where ? is the number of the display. 

The application that calls XAddHosta and the server whose list is being updated must be run 
ning on the same host machine. 

The address data must be a valid address for the type of network in which the server oper 
ates, as specified by the family member. Internet, DECnet and ChaosNet networks are cur 
rently supported. 

For TCP/IP, the address should be in network byte order. For the DECnet family, the server 
performs no automatic swapping on the address bytes. A Phase IV address is two bytes long. 
The first byte contains the least significant eight bits of the node number. The second byte con 
tains the most significant two bits of the node number in the least significant two bits of the 
byte, and the area in the most significant six bits of the byte. 

For more information on access control, see Volume One, Chapter 13, Other Programming 
Techniques. 

Structures 

typedef struct { 

int family; /* for example Family Internet */ 

int length; /* length of address, in bytes */ 

char *address; /* pointer to where to find the bytes */ 

} XHostAddress; 

/* The following constants for family member */ 
tdefine Familylnternet 
#define FamilyDECnet 1 
#define FamilyChaos 2 



38 Xlib Reference Manual 



Xlib - Host Access (continued) XAddHostS 

Errors 

BadAccess 
BadValue 

Related Commands 

XAddHost, XDisableAccessControl, XEnableAccessControl, XListHosts, 
XRemoveHost, XRemoveHosts, XSetAccessControl. 



Xlib Reference Manual 39 



XAddPixel \ Xlib _ lmages _ 

Name 

XAddPixel add a constant value to every pixel value in an image. 

Synopsis 

XAddPixel (ximage, value) 
Xlmage *ximage ; 
unsigned long value; 

Arguments 

x image Specifies a pointer to the image to be modified. 

value Specifies the constant value that is to be added. Valid pixel value ranges 

depend on the visual used to create the image. If this value added to the 
existing value causes an overflow, extra bits in the result are truncated. 

Description 

XAddPixel adds a constant value to every pixel value in an image. This function is useful 
when you have a base pixel value derived from the allocation of color resources and need to 
manipulate an image so that the pixel values are in the same range. 

For more information on images, see Volume One, Chapter 6, Drawing Graphics and Text. 
Structures 

typedef struct Xlmage { 

int width, height; /* size of image */ 

int xoffset; /* number of pixels offset in X direction */ 

int format; /* XYBitmap, XYPixmap, ZPixmap */ 

char *data; /* pointer to image data */ 

int byte_order; /* data byte order, LSBFirst, MSBFirst */ 

int bitmap_unit; /* quantity of scan line 8, 16, 32 */ 

int bitmap_bit_order; /* LSBFirst, MSBFirst */ 

int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */ 

int depth; /* depth of image */ 

int bytes per line; /* accelerator to next line */ 

int bits_per_pixel; /* bits per pixel (ZPixmap) */ 

unsigned long red_mask; /* bits in z arrangment */ 

unsigned long green mask; 

unsigned long blue_mask; 

char *obdata; /* hook for object routines to hang on */ 

struct funcs { /* image manipulation routines */ 

struct _XImage * (*create_image) (); 

int (*destroy_image) (); 

unsigned long (*get_pixel) ( ) ; 

int (*put_pixel) () ; 

struct _XImage * (*sub_image) (); 

int (*add_pixel) (); 

} f; 

} Xlmage; 



40 Xlib Reference Manual 



Xlib- Images (continued) XAddPixel 

Related Commands 

ImageByteOrder, XCreatelmage, XDestroylmage, XGetlmage, XGetPixel, 
XGetSublmage, XPutlmage, XPutPixel, XSub Image. 



Xlib Reference Manual 41 



XAddToSaveSet "\ 



XI ib- Save Set 



Name 

XAddToSaveSet add a window to the client s save-set. 

Synopsis 

XAddToSaveSet ( display, w) 
Display * display; 
Window w; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the ID of the window you want to add to the client s save-set. 

Description 

XAddToSaveSet adds the specified window to the client s save-set. 

The save-set is a safety net for windows that have been reparented by the window manager, 
usually to provide a titlebar or other decorations for each application. When the window man 
ager dies unexpectedly, the windows in the save-set are reparented to their closest living ances 
tor, so that they remain alive. See Volume One, Chapter 13, Other Programming Techniques, 
for more information about save-sets. 

Use XRemoveFromSaveSet to remove a window from the client s save-set. 

Errors 

BadMat ch w not created by some other client. 

BadWindow 

Related Commands 

XChangeSaveSet, XRemoveFromSaveSet. 



42 Xlib Reference Manual 



-XHb- W,ndow Manager Him, / XAIIOCCIaSSHint 

Name 

XAllocClassHint allocate an XClassHint structure. 

Synopsis 

XClassHint *XAllocClassHint ( ) 

Availability 

Release 4 and later. 

Description 

XAllocClassHint allocates and returns a pointer to an XClassHint structure, for use in 
calling XSetWMProperties, XGetClassHint, or XSetClassHint. Note that the 
pointer fields in the XClassHint structure are initially set to NULL. If insufficient memory is 
available, XAllocClassHint returns NULL. To free the memory allocated to this structure, 
useXFree. 

The purpose of this function is to avoid compiled-in structure sizes, so that object files will be 
binary compatible with later releases that may have new members added to structures. 

For more information, see Volume One, Chapter WJnterclient Communication. 
Structures 

typedef struct { 

char *res_name; 

char *res_class; 
} XClassHint; 

Related Commands 

XGetClassHint, XSetClassHint, XSetWMProperties. 



XHb Reference Manual 



43 



XANocColor "\ Yll 

v Xlib - Color Cells- 
Name 

XAllocColor allocate a read-only colormap cell with closest hardware-supported color. 

Synopsis 

Status XAllocColor ( display, cmap, colorcell_def) 
Display * display; 
Colo rmap cmap ; 
XColor *colorcell_def; /* SENDs and RETURNS */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

cmap Specifies the ID of the colormap in which the colorcell is to be allocated. 

col or eel l_def 

Specifies desired RGB values, and also returns the pixel value and the RGB val 
ues actually used in the colormap. 

Description 

XAllocColor returns in the XColor structure the pixel value of a read-only (shareable) 
colorcell with the closest RGB values available in cmap. XAllocColor also returns the red, 
green, and blue values actually used. 

If the display hardware has an immutable hardware colormap, the entire colormap will be read 
only, and the closest cell that exists will be returned. Otherwise, the colormap is read/write, 
and may have some read/write cells, some read-only cells, and some unallocated cells. If a 
read-only cell exists that matches the requested RGB values, that cell is returned. If no match 
ing cell exists but there are unallocated cells, a cell is allocated to match the specified RGB val 
ues. If no matching cell exists and there are no unallocated cells, XAllocColor returns a 
Status of zero (in read/write colormaps, it does not return the closest available read-only 
colorcell that has already been allocated). If it succeeds, XAllocColor returns nonzero. 

Note that colorcell_def stores both the requested color when XAllocColor is called 
and the result when XAllocColor returns. 

XAllocColor does not use or affect the flags member of the XColor structure. 
For more information, see Volume One, Chapter 7, Color. 

Structures 

typedef struct { 

unsigned long pixel; 

unsigned short red, green, blue; 

char flags; /* DoRed, DoGreen, DoBlue */ 

char pad; 
} XColor; 

Errors 

BadColormap 



44 Xlib Reference Manual 



Xlib - Color Cells (continued) XAIIOCColor 

Related Commands 

BlackPixel, WhitePixel, XAllocColorCells, XAllocColorPlanes, XAlloc- 
NamedColor, XFreeColors, XLookupColor, XParseColor, XQueryColor, 
XQueryColors, XStoreColor, XStoreColors, XStoreNamedColor. 



Xlib Reference Manual 45 



XAIIocColorCells 



X 



Xlib- Color Cells- 



Name 

XAIIocColorCells allocate read/write (nonshared) colorcells. 



Synopsis 

Status XAIIocColorCells (display, cmap, 

nplanes, pixels , ncolors) 
Display *display; 
Colo rmap cmap ; 
Bool contig; 

unsigned long plane_masks [nplanes] 
unsigned int nplanes; 
unsigned long pixels [ncolors] ; 
unsigned int ncolors; 



contig, plane_masks, 



/* RETURN 



/* RETURN pixel values */ 



Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

cmap Specifies the ID of the colormap in which the colorcell is to be allocated. 

contig Specifies a boolean value. Pass True if the planes must be contiguous or 

False if the planes need not be contiguous. 

plane_mask Returns an array of plane masks. 

nplanes Specifies the number of plane masks returned in the plane masks array. Must 

be nonnegative. 

pixels Returns an array of pixel values. 

ncolors Specifies the number of pixel values returned in the pixels array. Must be 

positive. 

Description 

XAIIocColorCells allocates read/write colorcells in a read/write colormap. If ncolors 
and nplanes are requested, then ncolors pixels and nplanes plane masks are returned. 
No mask will have any bits in common with any other mask, or with any of the pixels. By 
ORing together each of the pixels with any combination of the plane_masks, 
ncolors*2 (npla/ies ) distinct pixels can be produced. For Grayscale or Pseudocolor, 
each mask will have exactly one bit, and for DirectColor each will have exactly three bits. 
If contig is True, then if all plane masks are ORed together, a single contiguous set of bits 
will be formed for Grayscale or Pseudocolor and three contiguous sets of bits (one 
within each pixel subfield) for DirectColor. The RGB values of the allocated entries are 
undefined until set with XStoreColor, XStoreColors, or XStoreNamedColor. 

Status is zero on failure, and nonzero on success. 

For more information, see Volume One, Chapter 7, Color. 



46 



Xlib Reference Manual 



Xlib - Color Cells (continued) XAIIOCColorCellS 

Errors 

BadColormap 

BadValue npl an es is negative. 

n colors is not positive. 

Related Commands 

BlackPixel, WhitePixel, XAllocColor, XAllocColorPlanes, XAllocNamed- 
Color, XFreeColors, XLookupColor, XParseColor, XQueryColor, XQuery- 
Colors, XStoreColor, XStoreColors, XStoreNamedColor. 



Xlib Reference Manual 



47 



XAIIocColorPlanes X v,, 

v XHb - Color Cells- 
Name 

XAIIocColorPlanes allocate read/write (nonshareable) color planes. 

Synopsis 

Status XAIIocColorPlanes (display, cmap, contig, pixels, ncolors, 

nreds r ngreens , nblues , rmask, gmask, bmask) 
Display *display; 
Colo rmap cmap ; 
Bool contig; 

unsigned long pixels [ncolors] ; /* RETURN */ 
int n colors ; 

int nreds, ngreens, nblues; 
unsigned long *rmask, * gmask, * bmask; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

cmap Specifies the ID of the colormap to be used. 

contig Specifies a boolean value. Pass True if the planes must be contiguous or 
False if the planes do not need to be contiguous. 

pixels Returns an array of pixel values. 

7i colors Specifies the number of pixel values returned in the pixels array. Must be posi 
tive. 

nreds Specify the number of red, green, and blue planes (shades). Must be nonnega- 

ngreens tive. 

nblues 

rmask Return bit masks for the red, green, and blue planes. 

gmask 

bmask 

Description 

If ncolors, nreds, ngreens, and nblues are requested, then ncolors pixels are 
returned, and the masks have nreds, ngreens, and nblues bits set to 1 respectively. 
Unique pixel values are generated by by ORing together subsets of masks with each item in the 
pixels list (pixels does not by itself contain pixel values). In doing this, note that 

nCOlorS*( 2 (nreds+ngreens+nblues) ) distinct pixel ValuCS aTC allocated. 

If contig is True, then each mask will have a contiguous set of bits. No mask will have any 
bits in common with any other mask, or with any of the pixels. For DirectColor, each 
mask will lie within the corresponding pixel subfield. 

Note, however, that there are actually only ncolors*(2 nreds ) independent red entries, 
ncolors~*(2 n e reens ) independent green entries, and n colors* (2 nblues ) independent blue 
entries in the colormap. This is true even for Pseudocolor. This does not cause problems, 
though, because when the colormap entry for a pixel value is changed using xstoreColors 



48 Xlib Reference Manual 



Xlib - Color Cells (continued) XAHocColorPlaneS 

or XStoreNamedColor, the pixel is decomposed according to rmask, gmask, and bmask 
and the corresponding pixel subfield entries are updated. 

Status is zero on failure, and nonzero on success. 

For more information, see Volume One, Chapter 7, Color. 

Errors 

BadColormap 

BadValue n colors is not positive. 

At least one of nreds, ngreens, nbl ues is negative. 

Related Commands 

BlackPixel, WhitePixel, XAllocColor, XAllocColorCells, XAllocNamed- 
Color, XFreeColors, XLookupColor, XParseColor, XQueryColor, XQuery- 
Colors, XStoreColor, XStoreColors, XStoreNamedColor. 



Xlib Reference Manual 49 



XAIIoclconSize V VI1I 

v Xlib - Window Manager Hints- 
Name 

XAllocIconSize allocate anxiconSize structure. 

Synopsis 

XlconSize *XAllocIconSize ( ) 

Availability 

Release 4 and later. 

Description 

XAIIoclconSize allocates and returns a pointer to an XlconSize structure, for use in cal 
ling XGetlconSizes or XSetlconSizes. Note that all fields in the XlconSize struc 
ture are initially set to zero. If insufficient memory is available, XAIIoclconSize returns 
NULL. To free the memory allocated to this structure, use XFree. 

The purpose of this function is to avoid compiled-in structure sizes, so that object files will be 
binary compatible with later releases that may have new members added to structures. 

For more information, see Volume One, Chapter WJnterclient Communication. 
Structures 

typedef struct { 

int min_width, min_height; 

int max_width, max_height; 

int width_inc, heigh t_inc; 
} XlconSize; 

Related Commands 

XGetlconSizes, XSetlconSizes. 



50 Xlib Reference Manual 



Xlib -Color Cells- 



J XAIIocNamedColor 



Name 

XAIIocNamedColor allocate a read-only colorcell from color name. 

Synopsis 

Status XAIIocNamedColor (display, cmap, colorname , 

colorcell_def, rgb_db_def) 
Display * display; 
Colormap cmap; 
char * colorname; 

XColor *colorcell_def; /* RETURN */ 
XColor *rgb_db_def; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

cmap Specifies the ID of the colormap in which the colorcell will be allocated. 

colorname Specifies the color name string (for example, "red") you want. Upper or 
lower case does not matter. The string should be in ISO LATIN- 1 encoding, 
which means that the first 128 character codes are ASCII, and the second 128 
character codes are for special characters needed in western languages other 
than English. 

colorcell_def 

Returns the pixel value and RGB values actually used in the colormap. This 
is the closest color supported by the hardware. 

rgb_db_def Returns the exact RGB values from the database corresponding to the 
colorname supplied. 

Description 

XAIIocNamedColor determines the RGB values for the specified colorname from the 
color database, and then allocates a read-only colorcell with the closest color available, as 
described under XAllocColor. Both the exact database definition of the color, and the 
color actually allocated are returned. If the colormap is not full, the RGB values allocated are 
the closest supported by the hardware. If the colormap is full, and is a StaticColor, 
DirectColor, or StaticGray visual class, XAIIocNamedColor returns the closest 
read-only colorcell already allocated, and does not actually create or set any new colorcell. If 
the colormap is full and is a Pseudocolor, TrueColor, or Grayscale visual class, 
XAIIocNamedColor fails and returns zero. 

XAIIocNamedColor returns a Status of zero if colorname was not found in the data 
base or if the color could not be allocated. The function returns nonzero when it succeeds. 

For more information, see Volume One, Chapter 7, Color. 



Xlib Reference Manual 51 



X AllocNamedColor (continued) Xlib - Color Cells 

Errors 

BadColormap 
BadName 

Structures 

typedef struct { 

unsigned long pixel; 

unsigned short red, green, blue; 

char flags; /* DoRed, DoGreen, DoBlue */ 

char pad; 
} XColor; 

Related Commands 

BlackPixel, WhitePixel, XAllocColor, XAllocColorCells, XAllocColor- 
Planes, XFreeColors, XLookupColor, XParseColor, XQueryColor, XQuery- 
Colors, XStoreColor, XStoreColors, XStoreNamedColor. 



52 Xlib Reference Manual 



-XMb-WmdowManager Him, XAIIOCSizeHintS 

Name 

XAllocSizeHints allocate an XSizeHints structure. 

Synopsis 

XSizeHints *XAllocSizeHints ( ) 

Availability 

Release 4 and later. 

Description 

XAllocSizeHints allocates and returns a pointer to an XSizeHints structure, for use in 
calling XSetWMProperties,XSetWMNormalHints,orXGetWMNormalHints. Note 
that all fields in the XSizeHints structure are initially set to zero. If insufficient memory is 
available, XAllocSizeHints returns NULL. To free the memory allocated to this structure, 
use XFree. 

The purpose of this function is to avoid compiled-in structure sizes, so that object files will be 
binary compatible with later releases that may have new members added to structures. 

For more information, see Volume One, Chapter W,Interclient Communication. 
Structures 

typedef struct { 

long flags; /* marks which fields in this structure are defined */ 

int x, y; /* Obsolete */ 

int width, height; /* Obsolete */ 

int min_width, min_height; 

int max_width, max_height; 

int width_inc, height_inc; 

struct { 

int x; /* numerator */ 

int y; /* denominator */ 
} min_aspect, max_aspect; 
int base_width, base_height ; 
int win_gravity; 
} XSizeHints; 

Related Commands 

XGetWMNormalHints, XSetWMNormalHints, XSetWMProperties. 



Xlib Reference Manual 53 



XAIIocStandardColormap V Vl . 

v Xhb - Window Manager Hints- 
Name 

XAIIocStandardColormap allocate an XStandardColormap structure. 

Synopsis 

XStandardColormap *XAllocStandardColormap ( ) 

Availability 

Release 4 and later. 

Description 

XAIIocStandardColormap allocates and returns a pointer to an XStandardColormap 
structure for use in calling XGetRGBColormaps or XSetRGBColormaps. Note that all 
fields in the XStandardColormap structure are initially set to zero. If insufficient memory 
is available, XAIIocStandardColormap returns NULL. To free the memory allocated to 
this structure, use XFree. 

The purpose of this function is to avoid compiled-in structure sizes, so that object files will be 
binary compatible with later releases that may have new members added to structures. 

For more information, see Volume One, Chapter 7, Color. 
Structures 

/* value for killid field */ 

#define ReleaseByFreeingColormap ( (XID) 1L) 

typedef struct { 

Colormap colormap; 

unsigned long red_max; 

unsigned long red_mult; 

unsigned long green_max; 

unsigned long green_mult ; 

unsigned long blue__max; 

unsigned long blue_mult; 

unsigned long base_pixel; 

VisuallD visualid; 

XID killid; 
} XStandardColormap; 

Related Commands 

XGetRGBColormaps, XSetRGBColormaps. 



54 Xlib Reference Manual 



-Xlib- Window Manager Hints XAIIOCWMHmtS 

Name 

XAllocWMHints allocate an XWMHints structure. 

Synopsis 

XWMHints *XAllocWMHints ( ) 

Availability 

Release 4 and later. 

Description 

The XAllocWMHints function allocates and returns a pointer to an XWMHints structure, for 
use in calling XSetWMProperties, XSetWMHints, or XGetWMHints. Note that all fields 
in the XWMHints structure are initially set to zero. If insufficient memory is available, 
XAllocWMHints returns NULL. To free the memory allocated to this structure, use XFree. 

The purpose of this function is to avoid compiled-in structure sizes, so that object files will be 
binary compatible with later releases that may have new members added to structures. 

For more information, see Volume One, Chapter 10, Interdient Communication. 
Structures 

typedef struct { 

long flags; /* marks which fields in this structure are defined */ 

Bool input; /* does this application rely on the window manager 

to get keyboard input? */ 

int initial_state; /* see below */ 

Pixmap icon_pixmap; /* pixmap to be used as icon */ 

Window icon_window; /* window to be used as icon */ 

int icon_x, icon_y; /* initial position of icon */ 

Pixmap icon_mask; /* pixmap to be used as mask for icon_pixmap */ 

XID window_group; /* id of related window group */ 

/* this structure may be extended in the future */ 
} XWMHints; 

Related Commands 

XGetWMHints, XSetWMHints, XSetWMProperties. 



Xlib Reference Manual 



XAIIowEvents 



X 



Xlib- Input Handling- 



Name 

XAIIowEvents control the behavior of keyboard and pointer events when these resources are 



Synopsis 

XAIIowEvents ( display, event_mode, time) 
Display *display; 
int event_/node; 
Time time; 



Arguments 

display 
event mode 



Specifies a connection to an X server; returned from XOpenDisplay. 

Specifies the event mode. Pass one of these constants: AsyncPointer, 
SyncPointer, AsyncKeyboard, SyncKeyboard, ReplayPointer, 
ReplayKeyboard, AsyncBoth, or SyncBoth. 

time Specifies the time when the grab should take place. Pass either a timestamp, 

expressed in milliseconds, or the constant Cur rent Time. 

Description 

XAIIowEvents releases the events queued in the server since the last XAIIowEvents call 
for the same device and by the same client. Events are queued in the server (not released to 
Xlib to propagate into Xlib s queues) only when the client has caused a device to "freeze" (by 
grabbing the device with mode GrabModeSync). The request has no effect if time is earlier 
than the last-grab time or later than the current server time. 

The event_mode argument controls what device events are released for and just how and 
when they are released. The event_mode is interpreted as follows: 

AsyncPointer If XAIIowEvents is called with AsyncPointer while the 

pointer is frozen by the client, pointer event processing resumes nor 
mally, even if the pointer is frozen twice by the client on behalf of 
two separate grabs. AsyncPointer has no effect if the pointer is 
not frozen by the client, but the pointer need not be grabbed by the 
client. 

AsyncKeyboard If XAIIowEvents is called with AsyncKeyboard while the key 

board is frozen by the client, keyboard event processing resumes 
normally, even if the keyboard is frozen twice by the client on behalf 
of two separate grabs. AsyncKeyboard has no effect if the key 
board is not frozen by the client, but the keyboard need not be 
grabbed by the client. 

SyncPointer If XAIIowEvents is called with SyncPointer while the pointer 

is frozen by the client, normal pointer event processing continues 
until the next ButtonPress or But tonRe lease event is 
reported to the client. At this time, the pointer again appears to 
freeze. However, if the reported event causes the pointer grab to be 



Xlib Reference Manual 



Xlib - Input Handling 



(continued) 



XAIIowEvents 



SyncKeyboard 



ReplayPointer 



ReplayKeyboard 



SyncBoth 



AsyncBoth 



released, then the pointer does not freeze, which is the case when an 
automatic grab is released by a ButtonRelease or when XGrab- 
Button or XGrabKey has been called and the specified key or but 
ton is released. SyncPointer has no effect if the pointer is not 
frozen or not grabbed by the client. 

If XAIIowEvents is called with SyncKeyboard while the key 
board is frozen by the client, normal keyboard event processing con 
tinues until the next KeyPress or KeyRelease event is reported 
to the client. At this time, the keyboard again appears to freeze. 
However, if the reported event causes the keyboard grab to be 
released, then the keyboard does not freeze, which is the case when 
an automatic grab is released by a ButtonRelease or when 
XGrabButton or XGrabKey has been called and the specified key 
or button is released. SyncKeyboard has no effect if the keyboard 
is not frozen or not grabbed by the client. 

This symbol has an effect only if the pointer is grabbed by the client 
and thereby frozen as the result of an event. In other words, 
XGrabButton must have been called and the selected button/key 
combination pressed, or an automatic grab (initiated by a Button- 
Press) must be in effect, or a previous XAIIowEvents must have 
been called with mode SyncPointer. If the pointer_mode of 
the XGrabPointer was GrabModeSync, then the grab is 
released and the releasing event is processed as if it had occurred 
after the release, ignoring any passive grabs at or above in the hierar 
chy (towards the root) on the grab-window of the grab just released. 

This symbol has an effect only if the keyboard is grabbed by the cli 
ent and if the keyboard is frozen as the result of an event. In other 
words, XGrabKey must have been called and the selected key com 
bination pressed, or a previous XAIIowEvents must have been 
called with mode SyncKeyboard. If the pointer_mode or 
keyboard_mode of the XGrabKey was GrabModeSync, then 
the grab is released and the releasing event is processed as if it had 
occurred after the release, ignoring any passive grabs at or above in 
the hierarchy (towards the root). 

SyncBoth has the effect described for both SyncKeyboard and 
SyncPointer. SyncBoth has no effect unless both pointer and 
keyboard are frozen by the client. If the pointer or keyboard is fro 
zen twice by the client on behalf of two separate grabs, SyncBoth 
"thaws" for both (but a subsequent freeze for SyncBoth will only 
freeze each device once). 

AsyncBoth has the effect described for both AsyncKeyboard 
and AsyncPointer. AsyncBoth has no effect unless both 
pointer and keyboard are frozen by the client. If the pointer and the 



Xlib Reference Manual 



57 



XAHowEventS (continued) Xlib- Input Handling 

keyboard were frozen by the client, or if both are frozen twice by 
two separate grabs, event processing (for both devices) continues 
normally. If a device is frozen twice by the client on behalf of the 
two separate grabs, AsyncBoth releases events for both. 

AsyncPointer, SyncPointer, and ReplayPointer have no effect on the processing of 
keyboard events. AsyncKeyboard, SyncKeyboard, and ReplayKeyboard have no 
effect on the processing of pointer events. 

It is possible for both a pointer grab and a keyboard grab (by the same or different clients) to be 
active simultaneously. If a device is frozen on behalf of either grab, no event processing is per 
formed for the device. It is also possible for a single device to be frozen because of both grabs. 
In this case, the freeze must be released on behalf of both grabs before events will be released. 

For more information on event handling, see Volume One, Chapter 9, The Keyboard and 
Pointer. 

Errors 

BadValue Invalid mode constant. 

Related Commands 

QLength, XChecklf Event, XCheckMaskEvent, XCheckTypedEvent, XCheck- 
TypedWindowEvent, XCheckWindowEvent, XEventsQueued, XGetlnputFocus, 
XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeek- 
If Event, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSetlnput- 
Focus, XSynchronize, XWindowEvent. 



58 Xlib Reference Manual 



Xllb - User Preferences- 



J XAutoRepeatOff 



Name 

XAutoRepeatOff turn off the keyboard auto-repeat keys. 

Synopsis 

XAutoRepeatOff (display) 
Display *display; 

Arguments 

display Specifies a connection to an X server; returned from XQpenDisplay. 

Description 

XAutoRepeatOff turns off auto-repeat for the keyboard. It sets the keyboard so that holding 
any non-modal key down will not result in multiple events. 

Related Commands 

XAutoRepeatOn, XBell, XChangeKeyboardControl, XGetDef ault, XGet- 
KeyboardControl, XGet Point erControl. 



Xlib Reference Manual 



XAutoRepeatOn \. 

v Xlib - User Preferences- 
Name 

XAutoRepeatOn turn on the keyboard auto-repeat keys. 

Synopsis 

XAutoRepeatOn (display) 
Display *display; 

Arguments 

display Specifies a connection to an X server; returned from XQpenDisplay. 

Description 

XAutoRepeatOn sets the keyboard to auto-repeat; that is, holding any non-modal key down 
will result in multiple KeyPress and KeyRelease event pairs with the same keycode 
member. Keys such as Shift Lock will still not repeat. 

Related Commands 

XAutoRepeatOf f , XBell, XChangeKeyboardControl, XGetDef ault, XGet- 
KeyboardControl, XGetPointerControl. 



60 Xlib Reference Manual 



Xlib - User Preferences- 



f XBell 



Name 

XBell ring the bell (Control G). 

Synopsis 

XBe 1 1 ( di spl ay, per can t ) 
Display *display; 
int percent; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

percent Specifies the volume for the bell, relative to the base volume set with 
XChangeKeyboardControl. Possible values are -100 (off), through 
(base volume), to 100 (loudest) inclusive. 

Description 

Rings the bell on the keyboard at a volume relative to the base volume, if possible, percent 
can range from -100 to 100 inclusive (else a BadValue error). The volume at which the bell 
is rung when percent is nonnegative is: 

volume = base - [ (base * percent) / 100] + percent 
and when percent is negative: 

volume = base + [ (base * percent) / 100] 

To change the base volume of the bell, set the bell_percent variable of XChange 
KeyboardControl. 

Errors 

BadValue percent < -100 or percent >100. 

Related Commands 

XAutoRepeatOf f , XAutoRepeatOn, XChangeKeyboardControl, XGetDef ault, 
XGetKeyboardControl, XGet Point erControl. 



Xlib Reference Manual 61 



XChangeActivePointerGrab v^ 



Xlib- Pointer- 



Name 

XChangeActivePointerGrab change the parameters of an active pointer grab. 

Synopsis 

XChangeActivePointerGrab (display, event_mask, cursor, time) 
Display *display; 
unsigned, int event_mask ; 
Cursor cursor; 
Time time; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

event_mask Specifies which pointer events are reported to the client. This mask is the bit 
wise OR of one or more of these pointer event masks: ButtonPressMask, 
ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, 
PointerMotionMask, PointerMotionHintMask, Buttonl- 
MotionMask, Button2MotionMask, ButtonSMotionMask, But- 
ton4MotionMask, ButtonSMotionMask, ButtonMotionMask, 
KeymapStateMask. 

cursor Specifies the cursor that is displayed. A value of None will keep the current 

cursor. 

time Specifies the time when the grab should take place. Pass either a timestamp, 

expressed in milliseconds, or the constant CurrentTime. 

Description 

XChangeActivePointerGrab changes the characteristics of an active pointer grab, if the 
specified time is no earlier than the last pointer grab time and no later than the current X server 
time. XChangeActivePointerGrab has no effect on the passive parameters of XGrab- 
Button, or the automatic grab that occurs between ButtonPress and ButtonRelease. 

event_mask is always augmented to include ButtonPress and ButtonRelease. 

For more information on pointer grabbing, see Volume One, Chapter 9, The Keyboard and 
Pointer. 

Errors 

BadCursor 

BadValue The event_mask argument is invalid. 

Related Commands 

XChangePointerControl, XGetPointerControl, XGetPointerMapping, 
XGrabPointer, XQueryPointer, XSetPointerMapping, XUngrabPointer, 
XWarpPointer. 



62 Xlib Reference Manual 



Xlib - Graphics Context- 



f XChangeGC 



Name 

XChangeGC change the components of a given graphics context. 

Synopsis 

XChangeGC (display, gc , valuemask, values) 
Display *display; 
GC gc; 

unsigned long valuemask; 
XGCValues * values; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

gc Specifies the graphics context. 

valuemask Specifies the components in the graphics context that you want to change. 
This argument is the bitwise OR of one or more of the GC component masks. 

val ues Specifies a pointer to the XGCValues structure. 

Description 

XChangeGC changes any or all of the components of a GC. The valuemask specifies which 
components are to be changed; it is made by combining any number of the mask symbols listed 
in the Structures section using bitwise OR (|). The values structure contains the values to be 
set. These two arguments operate just like they do in XCreateGC. Changing the 
clip_mask overrides any previous XSetClipRectangles request for this GC. Changing 
the dash_of f set or dash_list overrides any previous XSetDashes request on this GC. 

Since consecutive changes to the same GC are buffered, there is no performance advantage to 
using this routine over the routines that set individual members of the GC. 

Even if an error occurs, a subset of the components may have already been altered. 

For more information, see Volume One, Chapter 5, The Graphics Context, and Chapter 6, 
Drawing Graphics and Text. 

Structures 

typedef struct { 

int function; /* logical operation */ 

unsigned long plane_mask; /* plane mask */ 

unsigned long foreground; /* foreground pixel */ 

unsigned long background; /* background pixel */ 

int line_width; /* line width */ 

int line style; /* LineSolid, LineOnOf fDash, LineDoubleDash */ 

int cap_style; /* CapNotLast, CapButt, CapRound, CapPro jecting */ 

int join style; /* JoinMiter, JoinRound, JoinBevel */ 

int fill~style; /* FillSolid, FillTiled, FillStippled */ 

int fill_rule; /* EvenOddRule, WindingRule */ 

int arc_mode; /* ArcChord, ArcPieSlice */ 

Pixmap tile; /* tile pixmap for tiling operations */ 

Pixmap stipple; /* stipple 1 plane pixmap for stipping */ 

int ts x origin; /* offset for tile or stipple operations */ 



Xlib Reference Manual 63 



XChangeGC 



(continued) 



Xlib- Graphics Context 



int ts_y_origin; 
Font font; 
int subwindow_mode; 
Bool graphics exposures; 
int clip_x_origin; 
int clip_y_origin; 
Pixmap clip_mask; 
int dash_offset; 
char dashes; 
} XGCValues; 



/* default text font for text operations */ 

/* ClipByChildren, Includelnferiors */ 

/* generate events on XCopy, Area, XCopyPlane*/ 

/* origin for clipping */ 

/* bitmap clipping; other calls for rects */ 

/* patterned/dashed line information */ 



#define 


GCFunction (1L0) 


#define 


GCPlaneMask (1L1) 


#define 


GCForeground (1L2) 


#define 


GCBackground (1L3) 


#define 


GCLineWidth (1L4) 


#def ine 


GCLineStyle (1L5) 


#define 


GCCapStyle (1L6) 


#def ine 


GCJoinStyle (1L7) 


#define 


GCFillStyle (1L8) 


#define 


GCFillRule (1L9) 


#define 


GCTile (1L10) 


#define 


GCStipple (1L11) 


#define 


GCTileStipXOrigin (1L12) 


#def ine 


GCTileStipYOrigin (1L13) 


#define 


GCFont (1L14) 


#def ine 


GCSubwindowMode (1L15) 


#define 


GCGraphicsExposures (1L16) 


#def ine 


GCClipXOrigin (1L17) 


#define 


GCClipYOrigin (1L18) 


#define 


GCClipMask (1L19) 


#def ine 


GCDashOffset (1L20) 


#define 


GCDashList (1L21) 


#def ine 


GCArcMode (1L22) 



Errors 

BadAlloc 

BadFont 

BadGC 

BadMatch 

BadPixmap 

BadValue 

Related Commands 

Def aultGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XGetGCValues, 
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground, 
XSetFunction, XSetGraphicsExposures, XSetLineAttributes, XSetPlane- 
Mask, XSetRegion, XSetState, XSetStipple, XSetSubwindowMode, XSet- 
TSOrigin. 



64 



Xlib Reference Manual 



Xlib - User Preferences- 



J XChangeKeyboardControl 



Name 

XChangeKeyboardControl change the keyboard preferences such as key click. 

Synopsis 

XChangeKeyboardControl (display, value_mask , values) 
Display * display; 
unsigned long value_mask; 
XKeyboardControl * values; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

value_mask Specifies a mask composed of ORed symbols from the table shown in the 
Structures section below, specifying which fields to set. 

values Specifies the settings for the keyboard preferences. 

Description 

XChangeKeyboardControl sets user preferences such as key click, bell volume and dura 
tion, light state, and keyboard auto-repeat. Changing some or all these settings may not be pos 
sible on all servers. 

The value_mask argument specifies which values are to be changed; it is made by combin 
ing any number of the mask symbols listed in the Structures section using bitwise OR (|). 

The values structure contains the values to be set, as follows: 

key_click_percent sets the volume for key clicks between (off) and 100 (loud) inclu 
sive. Setting to -1 restores the default. 

bell_percent sets the base volume for the bell between (off) and 100 (loud) inclusive. 
Setting to -1 restores the default. 

bell _jpitch sets the pitch (specified in Hz) of the bell. Setting to -1 restores the default. 

bell_duration sets the duration (specified in milliseconds) of the bell. Setting to -1 
restores the default. 

led__mode is either LedModeOn or LedModeOf f . led is a number between 1 and 32 inclu 
sive that specifies which light s state is to be changed. If both led_mode and led are speci 
fied, then the state of the LED specified in led is changed to the state specified in led_mode. 
If only led_mode is specified, then all the LEDs assume the value specified by led_mode. 

auto_repeat_mode is either AutoRepeatModeOn, AutoRepeatModeOf f , or Auto- 
RepeatModeDef ault. key is a keycode between 7 and 255 inclusive. If both 
auto_repeat_mode and key are specified, then the auto-repeat mode of the key specified 
by key is set as specified by auto_repeat_mode. If only auto_repeat_mode is speci 
fied, then the global auto repeat mode for the entire keyboard is changed, without affecting the 
settings for each key. If the auto_repeat_mode is AutoRepeatModeDe fault for 
either case, the key or the entire keyboard is returned to its default setting for the server, which 
is normally to have all non-modal keys repeat. 



Xlib Reference Manual 



XChangeKey boardControl (continued) Xlib - User Preferences 

When a key is being used as a modifier key, it does not repeat regardless of the individual or 
global auto repeat mode. 

The order in which the changes are performed is server-dependent, and some may be completed 
when another causes an error. 

For more information on user preferences, see Volume One, Chapter 9, The Keyboard and 
Pointer. 

Structures 

/* masks for ChangeKeyboardControl */ 

#define KBKeyClickPercent (1L0) 

#define KBBellPercent (1L1) 

#define KBBellPitch (1L2) 

#define KBBellDuration (1L3) 

#define KBLed (1L4) 

#define KBLedMode (1L5) 

tdefine KBKey (1L6) 

tdefine KBAutoRepeatMode (1L7) 

/* structure for ChangeKeyboardControl */ 

typedef struct { 

int key_click_percent; 

int bell_percent; 

int bell_pitch; 

int bell_duration; 

int led; 

int led_mode; /* LedModeOn or LedModeOff */ 

int key; 

int auto_repeat_mode; /* AutoRepeatModeOf f , AutoRepeatModeOn, 

AutoRepeatModeDefault */ 
} XKeyboardControl; 

Errors 

BadMatch values, key specified but values, auto . repeat .mode not specified, 
values . led specified but values . led_mode not specified. 

BadValue values. key_click_percent < -1. 

values. be ll_percent < -1. 
values. bell_j3itch < -I. 
values.bell_duration < -1. 

Related Commands 

XAutoRepeatOf f , XAutoRepeatOn, XBell, XGetDef ault, XGetKeyboard- 
Control, XGetPointerControl. 



66 



Xlib Reference Manual 



XI ib- Keyboard - 



J XChangeKeyboardMapping 



Name 

XChangeKeyboardMapping change the keyboard mapping. 
Synopsis 

XChangeKeyboardMapping (display, first_code, keysyms_per_code, 

keysyms, num_codes) 
Display * display; 
int first_keycode; 
int keysyms_per_keycode; 
KeySym * keysyms; 
int num_keycodes ; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

fi rs t_keycode 

Specifies the first keycode that is to be changed. 

key syms_per_key code 

Specifies the number of keysyms that the caller is supplying for each keycode. 

keysyms Specifies a pointer to the list of keysyms. 

num_key codes 

Specifies the number of keycodes that are to be changed. 

Description 

Starting with first_keycode, XChangeKeyboardMapping defines the keysyms for the 
specified number of keycodes. The symbols for keycodes outside this range remain unchanged. 
The number of elements in the keysyms list must be a multiple of key syms_per_key code 
(else a BadLength error). The specified first_keycode must be greater than or equal to 
min_keycode supplied at connection setup and stored in the display structure (else a Bad- 
Value error). In addition, the following expression must be less than or equal to max_key- 
code field of the Display structure (else a BadValue error): 

max_keycode >= first_keycode + (num_keycodes / key syms_per_key code) - 1 

The keysym number N (counting from 0) for keycode K has an index in the keysyms array 
(counting from 0) of the following (in keysyms): 

index = (K - first keycode) * keysyms_per_keycode + N 

The specified keysyms^per_keycode can be chosen arbitrarily by the client to be large 
enough to hold all desired symbols. A special keysym value of NoSymbol should be used to 
fill in unused elements for individual keycodes. It is legal for NoSymbol to appear in nontrail- 
ing positions of the effective list for a keycode. 

XChangeKeyboardMapping generates a MappingNotif y event, sent to this and all other 
clients, since the keycode to keysym mapping is global to all clients. 



Xlib Reference Manual 67 



XChangeKeyboardMapping (continued) Xlib - Keyboard 

Errors 

BadAlloc 

BadValue first . keycode less than display->min_keycode. 

display->max_keycode exceeded (see above). 

Related Commands 

XDeleteModif iermapEntry, XFreeModif iermap, XGetKeyboardMapping, 
XGetModif ierMapping, XInsertModif iermapEntry, XKeycodeToKeysym, 
XKeysymToKeycode, XKeysymToString, XLookupKeysym, XLookupString, 
XNewModif ierMap, XQueryKeymap, XRebindKeySym, XRef reshKeyboard- 
Mapping, XSetModif ierMapping, XStringToKeysym. 



68 Xlib Reference Manual 



Xlib -Pointers- 



J XChangePointerControl 



Name 

XChangePointerControl change the pointer preferences. 

Synopsis 

XChangePointerControl (display, do_accel , do_threshold r 
accel_numerator, accel_denominator, threshold) 
Display *display; 
Bool do_accel , do_threshold; 
int accel_numerator f accel_denominator; 
int threshold; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

do_accel Specifies a boolean value that controls whether the values for the 
accel_numerator or accel_denominator are set. You can pass one 
of these constants: True or False. 

do_ thresh old 

Specifies a boolean value that controls whether the value for the threshold is 
set. You can pass one of these constants: True or False. 

accel_numerator 

Specifies the numerator for the acceleration multiplier. 

accel_denominator 

Specifies the denominator for the acceleration multiplier. 

threshold Specifies the acceleration threshold. 

Description 

XChangePointerControl defines how the pointing device functions. The acceleration is 
a fraction (accel_numerator/accel_denominator) which specifies how many times 
faster than normal the sprite on the screen moves for a given pointer movement. Acceleration 
takes effect only when a particular pointer motion is greater than threshold pixels at once, 
and only applies to the motion beyond threshold pixels. The values for do_accel and 
do_ thresh old must be nonzero for the pointer values to be set; otherwise, the parameters 
will be unchanged. Setting any of the last three arguments to -1 restores the default for that 
argument. 

The fraction may be rounded arbitrarily by the server. 
Errors 

BadValue accel_de/iomiriator isO. 

Negative value for do_accel or do_threshold. 



Xlib Reference Manual 



XChangePolnterControl (continued) Xlib - Pointers 

Related Commands 

XChangeActivePointerGrab, XGetPointerControl, XGetPointerMapping, 
XGrabPointer, XQueryPointer, XSetPointerMapping, XUngrabPointer, 
XWarpPointer. 



70 Xlib Reference Manual 



Xlib -Properties- 



J XChangeProperty 



Name 

XChangeProperty change a property associated with a window. 

Synopsis 

XChangeProperty (display, w, property, type, format, mode, 

data, nelements) 
Display * display; 
Window w; 

Atom property, type; 
int format; 
int mode ; 

unsigned char *data; 
int nelements; 

Arguments 

display Specifies a connection to an X server; returned from XQpenDisplay. 

w Specifies the ID of the window whose property you want to change, 

property Specifies the property atom. 

type Specifies the type of the property. X does not interpret the type, but simply 

passes it back to an application that later calls XGet Property. 

format Specifies whether the data should be viewed as a list of 8-bit, 16-bit, or 32-bit 

quantities. This information allows the X server to correctly perform byte- 
swap operations as necessary. If the format is 16-bit or 32-bit, you must 
explicitly cast your data pointer to a (char *) in the call to XChange 
Property. Possible values are 8, 16, and 32. 

mode Specifies the mode of the operation. Possible values are PropMode- 

Replace, PropModePrepend, PropModeAppend, or no value. 

data Specifies the property data. 

n el emen t s Specifies the number of elements in the property. 

Description 

XChangeProperty changes a property and generates PropertyNotify events if they 
have been selected. 

XChangeProperty does the following according to the mode argument: 

PropModeReplace 

Discards the previous property value and stores the new data. 

PropModePrepend 

Inserts the data before the beginning of the existing data. If the property is undefined, it 
is treated as defined with the correct type and format with zero-length data, type and 
format arguments must match the existing property value; otherwise a BadMatch 
error occurs. 



Xlib Reference Manual 71 



XChangeProperty (continued) Xlib - Properties 

PropMode Append 

Appends the data onto the end of the existing data. If the property is undefined, it is 
treated as defined with the correct type and format with zero-length data, type and 
format arguments must match the existing property value; otherwise a BadMatch 
error occurs. 

The property may remain defined even after the client which defined it exits. The property 
becomes undefined only if the application calls XDeleteProperty, destroys the specified 
window, or closes the last connection to the X server. 

The maximum size of a property is server-dependent and can vary dynamically if the server has 
insufficient memory. 

For more information, see Volume One, Chapter 10, Interdient Communication. 

Errors 

BadAlloc 

BadAtom 

BadMatch 

BadValue 

BadWindow 

Related Commands 

XDeleteProperty, XGetAtomName, XGetFontProperty, XGetWindowProperty, 
XInternAtom, XListProperties, XRotateWindowProperties, XSetStandard- 
Properties. 



72 Xlib Reference Manual 



Xlib - Window Save Set- 



J XChangeSaveSet 



Name 

XChangeSaveSet add or remove a subwindow from the client s save-set. 

Synopsis 

XChangeSaveSet { display, w, change_mode) 
Display *display; 
Window w; 
int change_mode ; 

Arguments 

display Specifies a connection to an X server; returned from XGpenDisplay. 

w Specifies the ID of the window whose children you want to add or remove 

from the client s save-set; it must have been created by some other client. 

change_mode Specifies the mode. Pass one of these constants: SetModelnsert (adds 
the window to this client s save-set) or SetModeDelete (deletes the win 
dow from this client s save-set). 

Description 

XChangeSaveSet adds or deletes windows from a client s save-set. This client is usually 
the window manager. 

The save-set of the window manager is a list of other client s top-level windows which have 
been reparented. If the window manager dies unexpectedly, these top-level application win 
dows are children of a window manager window and therefore would normally be destroyed. 
The save-set prevents this by automatically reparenting the windows listed in the save-set to 
their closest existing ancestor, and then remapping them. 

Windows are removed automatically from the save-set by the server when they are destroyed. 

For more information on save-sets, see Volume One, Chapter 13, Other Programming Tech 
niques. 

Errors 

BadMat ch w not created by some other client. 

BadValue 
BadWindow 

Related Commands 

XAddToSaveSet,XRemoveFromSaveSet. 



Xlib Reference Manual 73 



XChangeWindowAttributes 



Xlib - Window Attributes- 



Name 

XChangeWindowAttributes set window attributes. 

Synopsis 

XChangeWindowAttributes (display, w f valuemask, attributes) 
Display *display; 
Window w; 

unsigned long valuemask; 
XSetWindowAttributes * attributes; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window ID. 

valuemask Specifies which window attributes are defined in the attributes argu 
ment. The mask is made by combining the appropriate mask symbols listed 
in the Structures section using bitwise OR (|). If valuemask is zero, the 
rest is ignored, and attributes is not referenced. The values and restric 
tions are the same as for XCreateWindow. 

attributes Window attributes to be changed. The valuemask indicates which mem 
bers in this structure are referenced. 

Description 

XChangeWindowAttributes changes any or all of the window attributes that can be 
changed. For descriptions of the window attributes, see Volume One, Chapter 4, Window Attri 
butes. 

Changing the background does not cause the window contents to be changed immediately-not 
until the next Expose event or XClearWindow call. Drawing into the pixmap that was set 
as the background pixmap attribute has an undefined effect on the window background. The 
server may or may not make a copy of the pixmap. Setting the border causes the border to be 
repainted immediately. Changing the background of a root window to None or Pa rent - 
Relative restores the default background pixmap. Changing the border of a root window to 
CopyFromParent restores the default border pixmap. 

Changing the win_gravity does not affect the current position of the window. Changing 
the backing_store of an obscured window to WhenMapped or Always may have no 
immediate effect. Also changing the backing_jplanes, backing_pixel, or 
save_under of a mapped window may have no immediate effect. 

Multiple clients can select input on the same window; the event_mask attributes passed are 
disjoint. When an event is generated it will be reported to all interested clients. Therefore, the 
setting of the event_mask attribute by one client will not affect the event_mask of others 
on the same window. However, at most, one client at a time can select each of 
SubstructureRedirectMask, ResizeRedirectMask, and ButtonPressMask on 
any one window. If a client attempts to select on SubtructureRedirectMask, Resize- 



74 Xlib Reference Manual 



Xlib - Window Attributes (continued) X Ch a n g e W i n d o w At t r i b u tes 

RedirectMask, or ButtonPressMask and some other client has already selected it on the 
same window, the X server generates a BadAccess error. 

There is only one do_not_propagate_mask for a window, not one per client. 

Changing the colormap attribute of a window generates a ColormapNotif y event. Chang 
ing the colormap attribute of a visible window may have no immediate effect on the screen 
(because the colormap may not be installed until the window manager calls Xlnstall- 
Colormap). 

Changing the cursor of a root window to None restores the default cursor. 

For more information, see Volume One, Chapter 2, X Concepts, and Chapter 4, Window Attri 
butes. 

Structures 

/* 

* Data structure for setting window attributes. 

*/ 
typedef struct { 

Pixmap background_pixmap; /* pixmap. None, or ParentRelative */ 

unsigned long background_pixel; /* background pixel */ 

Pixmap border_pixmap; /* pixmap, None, or CopyFromParent */ 

unsigned long border_pixel; /* border pixel value */ 

int bit_gravity; /* one of bit gravity values */ 

int win_gravity; /* one of the window gravity values */ 

int backing_store; /* NotUseful, WhenMapped, Always */ 

unsigned long backing_planes; /* planes to be preseved if possible */ 

unsigned long backing_pixel; /* value to use in restoring planes */ 

Bool save_under; /* should bits under be saved (popups) */ 

long event_mask; /* set of events that should be saved */ 

long do not propagate_mask; /* set of events that should not propagate */ 

Bool override_redirect; /* override redirected config request */ 

Colormap colormap; /* colormap to be associated with window */ 

Cursor cursor; /* cursor to be displayed (or None) */ 
} XSetWindowAttributes; 

/* Definitions for valuemask argument of CreateWindow and ChangeWindowAttributes */ 

#define CWBackPixmap (1L0) 

#define CWBackPixel (1L1) 

#define CWBorderPixmap (1L2) 

#define CWBorderPixel (1L3) 

#define CWBitGravity (1L4) 

#define CWWinGravity (1L5) 

#define CWBackingStore (1L6) 

#define CWBackingPlanes (1L7) 

#define CWBackingPixel (1L8) 

#define CWOverrideRedirect (1L9) 

#define CWSaveUnder (1L10) 

#define CWEventMask (1L11) 

#define CWDontPropagate (1L12) 

fdefine CWColormap (1L13) 

#define CWCursor (1L14) 



Xlib Reference Manual 7S 



XChangeWindOW Attributes (continued) Xlib - Window Attributes 

Errors 

BadAccess 

BadColormap 

BadCursor 

BadMatch 

BadPixmap 

BadValue 

BadWindow 



Related Commands 

XGet Geometry, XGetWindowAttributes, XSetWindowBackground, XSet- 
WindowBackgroundPixmap, XSetWindowBorder, XSetWindowBorderPixmap. 



76 Xlib Reference Manual 



-X,ib - input Handling / XCheCklfEvent 

Name 

XChecklfEvent check the event queue for a matching event. 

Synopsis 

Bool XChecklfEvent (display, event, predicate, arg) 
Display *display; 

XEvent * event; /* RETURN */ 

Bool (*predicate) () ; 
char *arg; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

event Returns the matched event. 

predicate Specifies the procedure that is called to determine if the next event matches 
your criteria. 

arg Specifies the user- specified argument that will be passed to the predicate pro 

cedure. 

Description 

XChecklfEvent returns the next event in the queue that is matched by the specified predi 
cate procedure. If found, that event is removed from the queue, and True is returned. If no 
match is found, XChecklfEvent returns False and flushes the request buffer. No other 
events are removed from the queue. Later events in the queue are not searched. 

The predicate procedure is called with the arguments display, event, and arg. 
For more information, see Volume One, Chapter 8, Events. 

Related Commands 

QLength, XAllowEvents, XCheckMaskEvent, XCheckTypedEvent, XCheck- 
TypedWindowEvent, XCheckWindowEvent, XEventsQueued, XGetlnputFocus, 
XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeek- 
If Event, XPending, XPutBackEvent,XSelectInput,XSendEvent,XSet Input- 
Focus, XSynchronize, XWindowEvent. 



Xlib Reference Manual 77 



XCheckMaskEvent \ xnb _ lnputH and,,n g - 

Name 

XCheckMaskEvent remove the next event that matches mask; don t wait. 

Synopsis 

Bool XCheckMaskEvent ( display, event_mask, event) 
Display * display; 
long event_mask; 
XEvent * event; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

even t_mask Specifies the event types to be returned. See list under XSelect Input. 
event Returns a copy of the matched event s XEvent structure. 

Description 

XCheckMaskEvent removes the next event in the queue that matches the passed mask. The 
event is copied into an XEvent supplied by the caller and XCheckMaskEvent returns 
True. Other events earlier in the queue are not discarded. If no such event has been queued, 
XCheckMaskEvent flushes the request buffer and immediately returns False, without wait 
ing. 

For more information, see Volume One, Chapter 8, Events. 
Related Commands 

QLength, XAllowEvents, XChecklf Event, XCheckTypedEvent, XCheckTyped- 
WindowEvent, XCheckWindowEvent, XEvent sQueued, XGetlnputFocus, XGet- 
MotionEvents, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeek- 
If Event, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSetlnput- 
Focus, XSynchronize, XWindowEvent. 



78 Xlib Reference Manual 



Xlib -Input Handling- 



J XCheckTypedEvent 



Name 

XCheckTypedEvent return the next event in queue that matches event type; don t wait. 

Synopsis 

Bool XCheckTypedEvent (display, event_type, report) 
Display *display; 
int event_type ; 
XEvent * report; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XQpenDi splay. 

event_type Specifies the event type to be compared. 
report Returns a copy of the matched event structure. 

Description 

XCheckTypedEvent searches first the event queue, then the events available on the server 
connection, for the specified even t_ type. If there is a match, it returns the associated event 
structure. Events searched but not matched are not discarded. XCheckTypedEvent returns 
True if the event is found. If the event is not found, XCheckTypedEvent flushes the 
request buffer and returns False. 

This command is similar to XCheckMaskEvent, but it searches through the queue instead of 
inspecting only the last item on the queue. It also matches only a single event type instead of 
multiple event types as specified by a mask. 

For more information, see Volume One, Chapter 8, Events. 
Related Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
WindowEvent, XCheckWindowEvent, XEventsQueued, XGetlnputFocus, XGet- 
MotionEvents, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeek- 
If Event, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSetlnput- 
Focus, XSynchronize, XWindowEvent. 



Xlib Reference Manual 79 



XCheckTypedWindowEvent \ 



x ,ib- 



Name 

XCheckTypedWindowEvent return the next event in queue matching type and window. 

Synopsis 

Bool XCheckTypedWindowEvent ( display, w, event _ty pe , report) 
Display * display; 
Window w; 
int event_type; 
XEvent * report; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window ID. 

even t_ type Specifies the event type to be compared. 

report Returns the matched event s associated structure into this client-supplied 

structure. 

Description 

XCheckTypedWindowEvent searches first the event queue, then any events available on 
the server connection, for an event that matches the specified window and the specified event 
type. Events searched but not matched are not discarded. 

XCheckTypedWindowEvent returns True if the event is found; it flushes the request buffer 
and returns False if the event is not found. 

For more information, see Volume One, Chapter 8, Events. 
Related Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event, XCheckWindowEvent, XEventsQueued, XGetlnputFocus, XGetMotion- 
Events, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeeklf Event, 
XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSetlnputFocus, 
XSynchronize, XWindowEvent. 



80 Xlib Reference Manual 



-Xllb- Input Handling / XCheCkWIndOWEvent 

Name 

XCheckWindowEvent remove the next event matching both passed window and passed 
mask; don t wait. 

Synopsis 

Bool XCheckWindowEvent (display, w, event_mask r event) 
Display * display; 
Window w; 
long event_mask; 
XEvent * event; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window ID. The event must match both the passed window and 

the passed event mask. 

even t_mask Specifies the event mask. See XSelect Input for a list of mask elements. 
event Returns the XEvent structure. 

Description 

XCheckWindowEvent removes the next event in the queue that matches both the passed 
window and the passed mask. If such an event exists, it is copied into an XEvent supplied by 
the caller. Other events earlier in the queue are not discarded. 

If a matching event is found, XCheckWindowEvent returns True. If no such event has been 
queued, it flushes the request buffer and returns False, without waiting. 

For more information, see Volume One, Chapter 8, Events. 
Related Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event, XCheckTypedWindowEvent, XEvent sQueued, XGetlnputFocus, XGet- 
MotionEvents, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeek- 
If Event, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSetlnput- 
Focus, XSynchronize, XWindowEvent. 



Xlib Reference Manual 



XCirculateSubwindows 

Xlib - Window Manipulation- 
Name 

XCirculateSubwindows circulate the stacking order of children up or down. 

Synopsis 

XCirculateSubwindows ( display, w, direction) 
Display *display; 
Window w; 
int direction; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window ID of the parent of the subwindows to be circulated. 

direction Specifies the direction (up or down) that you want to circulate the children. 
Pass either RaiseLowest or LowerHighest. 

Description 

XCirculateSubwindows circulates the children of the specified window in the specified 
direction, either RaiseLowest or LowerHighest. If some other client has selected 
SubstructureRedirectMask on the specified window, then a CirculateRequest 
event is generated, and no further processing is performed. If you specify RaiseLowest, this 
function raises the lowest mapped child (if any) that is occluded by another child to the top of 
the stack. If you specify LowerHighest, this function lowers the highest mapped child (if 
any) that occludes another child to the bottom of the stack. Exposure processing is performed 
on formerly obscured windows. 

For more information, see Volume One, Chapter 14, Window Management. 

Errors 

BadValue 
BadWindow 

Related Commands 

XCirculateSubwindowsDown, XCirculateSubwindowsUp, XConf igureWindow, 
XLowerWindow, XMoveResizeWindow, XMoveWindow, XQueryTree, XRaise- 
Window, XReparentWindow, XResizeWindow, XRestackWindows. 



82 Xlib Reference Manual 



-x..b-w,ndowMan. pu .at,on XCirculateSubwindowsDown 

Name 

XCirculateSubwindowsDown circulate the bottom child to the top of the stacking order. 

Synopsis 

XCirculateSubwindowsDown (display, w) 
Display * display ; 
Window w; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window ID of the parent of the windows to be circulated. 

Description 

XCirculateSubwindowsDown lowers the highest mapped child of the specified window 
that partially or completely obscures another child. The lowered child goes to the bottom of the 
stack. Completely unobscured children are not affected. 

This function generates exposure events on any window formerly obscured. Repeated execu 
tions lead to round-robin lowering. This is equivalent to XCirculateSubwindows (dis 
play, w, LowerHighest). 

If some other client has selected SubstructureRedirectMask on the window, then a 
CirculateRequest event is generated, and no further processing is performed. This allows 
the window manager to intercept this request when w is the root window. Usually, only the 
window manager will call this on the root window. 

For more information, see Volume One, Chapter 14, Window Management. 

Errors 

BadWindow 

Related Commands 

XCirculateSubwindows, XCirculateSubwindowsUp, XConf igureWindow, 
XLowerWindow, XMoveResizeWindow, XMoveWindow, XQueryTree, XRaise- 
Window, XReparentWindow, XResizeWindow, XRestackWindows. 



Xlib Reference Manual 



XCirculateSubwindowsUp , vn 

v Xlib - Window Manipulation 

Name 

XCirculateSubwindowsUp circulate the top child to the bottom of the stacking order. 

Synopsis 

XCirculateSubwindowsUp (display, w) 
Display * display ; 
Window w; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window ID of the parent of the windows to be circulated. 

Description 

XCirculateSubwindowsUp raises the lowest mapped child of the specified window that is 
partially or completely obscured by another child. The raised child goes to the top of the stack. 
Completely unobscured children are not affected. This generates exposure events on the raised 
child (and its descendents, if any). Repeated executions lead to round robin-raising. This is 
equivalent to XCirculateSubwindows (display, w, RaiseLowest). 

If some other client has selected SubstructureRedirectMask on the window, then a 
CirculateRequest event is generated, and no further processing is performed. This allows 
the window manager to intercept this request when w is the root window. Usually, only the 
window manager will call this on the root window. 

For more information, see Volume One, Chapter 14, Window Management. 

Errors 

BadWindow 

Related Commands 

XCirculateSubwindows, XCirculateSubwindowsDown, XConf igureWindow, 
XLowerWindow, XMoveResizeWindow, XMoveWindow, XQueryTree, XRaise- 
Window, XReparentWindow, XResizeWindow, XRestackWindows. 



84 Xlib Reference Manual 



Xllb - Drawing Primitives 

Name 

XClearArea clear a rectangular area in a window. 
Synopsis 

XClearArea (display, w, x, y, width, height, exposures) 
Display *display; 
Window w; 
int x f y; 

unsigned int width, height; 
Bool exposures; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the ID of an input Output window. 

x Specify the x and y coordinates of the upper-left corner of the rectangle to be 

y cleared, relative to the origin of the window. 

wi dth Specify the dimensions in pixels of the rectangle to be cleared. 

height 

exposures Specifies whether exposure events are generated. Must be either True or 
False. 

Description 

XClearArea clears a rectangular area in a window. 

If width is zero, the window is cleared from x to the right edge of the window. If height is 
zero, the window is cleared from y to the bottom of the window. See figure above.. 

If the window has a defined background tile or it is ParentRelative, the rectangle is tiled 
with a plane_mask of all 1 s, a function of GXcopy, and a subwindow_mode of 
ClipByChildren. If the window has background None, the contents of the window are not 
changed. In either case, if exposures is True, then one or more exposure events are gen 
erated for regions of the rectangle that are either visible or are being retained in a backing store. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text. 



Xlib Reference Manual 



XCIearArea 



(continued) 



Xlib - Drawing Primitives 



Window 



[x,y] width 




Window 



[x,y] width 




Window 



[x,y] width = 




Window 



[x,y] width = 




Errors 

BadMatch 
BadValue 
BadWindow 



Window is an inputOnly class window. 



Related Commands 

XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc, XDrawArcs, XDraw- 
Filled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle, 
XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFillPolygon, 
XFillRectangle, XFillRectangles. 



Xlib Reference Manual 



-Xlib- Drawing Primitives / 

Name 

XClearWindow clear an entire window. 

Synopsis 

XClearWindow (display, w) 
Display *display; 
Window W, 

Arguments 

display Specifies a connection to an X server; returned from XQpenDi splay. 

w Specifies the ID of the window to be cleared. 

Description 

XClearWindow clears a window, but does not cause exposure events. This function is equiv 
alent to XClearArea (display, w, 0, 0, 0, 0, False). 

If the window has a defined background tile or it is ParentRelative, the rectangle is tiled 
with a plane_mask of all 1 s and function of GXcopy. If the window has background 
None, the contents of the window are not changed. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text. 

Errors 

BadMatch If vis an InputOnly class window. 

BadValue 
BadWindow 

Related Commands 

XClearArea, XCopyArea, XCopyPlane, XDraw, XDrawArc, XDrawArcs, XDraw- 
Filled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle, 
XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFillPolygon, 
XFillRectangle, XFillRectangles. 



Xlib Reference Manual 87 



XCIipBox ~\ 

X Xlib - Regions- 
Name 

XCIipBox generate the smallest rectangle enclosing a region. 

Synopsis 

XCIipBox (r, rect) 
Region r; 
XRect angle *rect ; /* RETURN */ 

Arguments 

r Specifies the region. 

rect Returns the smallest rectangle enclosing region r. 

Description 

XCIipBox returns the smallest rectangle that encloses the given region. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text. 

Structures 

Region is a pointer to an opaque structure type. 

Related Commands 

XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion, 
XIntersectRegion, XOf f setRegion, XPointlnRegion, XPolygonRegion, 
XRect InRegion, XSetRegion, XShrinkRegion, XSubtractRegion, XUnion- 
RectWithRegion, XUnionRegion, XXorRegion. 



Xlib Reference Manual 



Xlib-HouseKeeping- 



J XCIoseDisplay 



Name 

XCIoseDisplay disconnect a client program from an X server and display. 

Synopsis 

XCIoseDisplay (display) 
Display *display; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

Description 

XCIoseDisplay closes the connection between the current client and the X server specified 
by the Display argument. 

The XCIoseDisplay routine destroys all windows, resource IDs (Window, Font, Pixmap, 
Colormap, Cursor, and GContext), or other resources (GCs) that the client application 
has created on this display, unless the close down mode of the client s resources has been 
changed by XSetCloseDownMode. Therefore, these windows, resource IDs, and other 
resources should not be referenced again. In addition, this routine discards any requests that 
have been buffered but not yet sent to the server. 

Although these operations automatically (implicitly) occur when a process exits under UNIX, 
you should call XCIoseDisplay anyway. 

For more information, see Volume One, Chapter 3, Basic Window Program. 
Related Commands 

Def aultScreen, XFree, XNoOp, XOpenDisplay. 



Xlib Reference Manual 89 



XConfigureWindow . V| 

v Xlib - Window Manipulation 

Name 

XConfigureWindow change the window position, size, border width, or stacking order. 

Synopsis 

XConf igureWindow ( display, i/, value_mask , values) 
Display * display; 
Window w; 

unsigned int value_mask; 
XWindowChanges * values; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the ID of the window to be reconfigured. 

value_mask Specifies which values are to be set using information in the values struc 
ture, val ue_mask is the bitwise OR of any number of symbols listed in the 
Structures section below. 

val ues Specifies a pointer to the XWindowChanges structure containing new confi 

guration information. See the Structures section below. 

Description 

XConfigureWindow changes the window position, size, border width, and/or the stacking 
order. If selected, a Conf igureNot if y event is generated to announce any changes. 

If the window to be reconfigured is a top-level window, there will be interaction with the win 
dow manager if the override_redirect attribute of the window is False. In this case, 
the X server sends a Conf igureRequest event to the window manager and does not recon 
figure the window. The window manager receives this event and then makes the decision 
whether to allow the application to reconfigure its window. The client should wait for the 
Conf igureNot if y event to find out the size and position of the window. 

In Release 4, XReconf igureWMWindow should be used instead of XConfigureWindow 
for top-level windows. This routine handles restacking of top-level windows properly. 

If a window s size actually changes, the window s subwindows may move according to their 
window gravity. If they do, GravityNotif y events will be generated for them. Depending 
on the window s bit gravity, the contents of the window also may be moved. See Volume One, 
Chapter 4, Window Attributes for further information. 

Exposure processing is performed on formerly obscured windows, including the window itself 
and its inferiors, if regions of them were obscured but afterward are not. As a result of increas 
ing the width or height, exposure processing is also performed on any new regions of the win 
dow and any regions where window contents are lost. 

The members of XWindowChanges that you specify in val ues are: 



go Xlib Reference Manual 



Xlib - Window Manipulation 



(continued) 



XConfigureWindow 



x Specify the x and y coordinates of the upper-left outer comer of the window 

y relative to the parent s origin. 

width Specify the inside size of the window in pixels, not including the border. 

height These arguments must be positive. 

horde r_width 

Specifies the width of the border in pixels. 

sibling Specifies the sibling window for stacking operations. If not specified, no 

change in the stacking order will be made. If specified, stack_mode must 
also be specified. 

stack_mode The stack mode can be any of these constants: Above, Below, Toplf , 
Bottomlf , or Opposite. 

The computation for the Bottomlf, Toplf, and Opposite stacking modes is performed 
with respect to window i/s final size and position (as controlled by the other arguments to 
XConfigureWindow, not its initial position.) It is an error if sibling is specified without 
stack_mode. If sibling and stack_mode are specified, the window is restacked as fol 
lows: 

Stacking Flag Position 



Above 
Below 
Toplf 

Bottomlf 
Opposite 



w is placed just above sibling 
w is placed just below sibling 

if sibling obscures w, then w is placed at the top 
of the stack 

if w obscures sibling, then w is placed at the bot 
tom of the stack 

if sibling occludes v/, then w is placed at the top 
of the stack. If w occludes sibling, then w is 
placed at the bottom of the stack. If wand sibling 
do not overlap, no change is made. 



Xlib Reference Manual 



91 



XConfigureWindOW (continued) Xlib - Window Manipulation 

If a stack_mode is specified but no sibling is specified, the window is restocked as follows: 



Stacking Flag 



Above 
Below 
Toplf 

Bottomlf 
Opposite 



Position 



w is placed at the top of the stack 
w is placed at the bottom of the stack 

if any sibling obscures w, then w is placed at the top 
of the stack 

if w obscures any sibling, then window is placed at 
the bottom of the stack 

if any sibling occludes w, then w is placed at the top 
of the stack, else if w occludes any sibling, then w is 
placed at the bottom of the stack 



Under Release 4, use XReconf igureWMWindow to configure a top-level window. 
Structures 

typedef struct { 

int x, y; 

int width, height; 

int border_width; 

Window sibling; 

int stack_mode; 
} XWindowChanges; 

/* Conf igureWindow structure */ 

/* ChangeWindow value bits definitions for valuemask */ 

tdefine CWX (10) 

#define CWY (11) 

#define CWWidth (12) 

tdefine CWHeight (13) 

#define CWBorderWidth (14) 

#define CWSibling (15) 

#define CWStackMode (16) 



Errors 

BadMatch 



Attempt to set any invalid attribute of InputOnly window. 
sibling specified without a stack_mode. 
The sibling window is not actually a sibling. 



BadValue width or height isO. 
BadWindow 



92 



Xlib Reference Manual 



Xlib - Window Manipulation (continued) XConf IgureWlndOW 

Related Commands 

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate- 
SubwindowsUp, XLowerWindow, XMoveResizeWindow, XMoveWindow, XQuery- 
Tree, XReconf igureWMWindow, XRaiseWindow, XReparentWindow, XResize- 
Window, XRestackWindows. 



Xlib Reference Manual 9S 



XConvertSelection A 



Name 

XConvertSelection use the value of a selection. 

Synopsis 

XConvertSelection ( display, selection, target, property, 

requestor, time) 
Display * display; 
Atom selection, target; 

Atom property; /* may be None */ 

Window requestor; 
Time time; 

Arguments 

display Specifies a connection to an X server; returned from xopenDisplay. 

selection Specifies the selection atom. XA_PRIMARY and XA_SECONDARY are the stan 
dard selection atoms. 

target Specifies the atom of the type property that specifies the desired format for 

the data. 

property Specifies the property in which the requested data is to be placed. None is 
also valid, but current conventions specify that the requestor is in a better 
position to select a property than the selection owner. 

requestor Specifies the requesting window. 

time Specifies the time when the conversion should take place. Pass either a 

timestamp, expressed in milliseconds, or the constant CurrentTime. 

Description 

XConvertSelection causes a SelectionRequest event to be sent to the current selec 
tion owner if there is one, specifying the property to store the data in (selection), the format 
to convert that data into before storing it (target), the property to place the information in 
(property), the window that wants the information (requestor), and the time to make the 
conversion (time). 

The selection owner responds by sending a SelectionNotify event, which confirms the 
selected atom and type. If no owner for the specified selection exists, or if the owner could not 
convert to the type specified by requestor, the X server generates or the owner sends a 
SelectionNotify event to the requestor with property None. Whether or not the owner 
exists, the arguments are passed unchanged. See Volume One, Chapter I0,lnterclient Commu 
nication, for a description of selection events and selection conventions. 

Errors 

BadAtom 
BadWindow 

Related Commands 

XGet Select ionOwner, XSetSelectionOwner. 



94 Xlib Reference Manual 



Xlib - Drawing Primitives- 



J XCopyArea 



Name 

XCopyArea copy an area of a drawable. 

Synopsis 

XCopyArea (display, src, dest , gc , src_x, src_y, width, 

height, dest_x, dest_y) 
Display *display; 
Drawable src, dest; 
GC gc; 

int src_x, src_y; 
unsigned int width, height; 
int dest_x, dest_y ; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

src Specify the source and destination rectangles to be combined, src and 

dest dest must have the same root and depth. 

gc Specifies the graphics context. 

src_x Specify the x and y coordinates of the upper- left corner of the source rectan- 

src_y gle relative to the origin of the source drawable. 

width Specify the dimensions in pixels of both the source and destination rectan- 

height gles. 

dest_x Specify the x and y coordinates within the destination window. 

dest_y 

Description 

XCopyArea combines the specified rectangle of src with the specified rectangle of dest. 
src and dest must have the same root and depth. 

If regions of the source rectangle are obscured and have not been retained in back- 
ing_store, or if regions outside the boundaries of the source drawable are specified, then 
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 dest is a window with 
a background other than None, the corresponding regions of the destination are tiled (with 
plane_mask of all 1 s and function GXcopy) with that background. Regardless of tiling, if 
the destination is a window and graphics_exposures in gc is True, then Graphics - 
Expose events for all corresponding destination regions are generated. If graph- 
ics_exposures is True but no regions are exposed, then a NoExpose event is generated. 

If regions of the source rectangle are not obscured and graphics_exposures is False, 
one NoExpose event is generated on the destination. 



Xlib Reference Manual 95 



XCopyArea (continued) Xlib - Drawing Primitives 

XCopyArea uses these graphics context components: function, plane_mask, 
subwindow_mode, graphics_exposures, clip_x_origin, clip_y_origin, and 
clip_mask. 

Errors 

BadDrawable 

BadGC 

BadMatch The src and dest rectangles do not have the same root and depth. 

Related Commands 

XClearArea, XClearWindow, XCopyPlane, XDraw, XDrawArc, XDrawArcs, 
XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDraw- 
Rectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFill- 
Polygon, XFillRectangle, XFillRectangles. 



96 Xlib Reference Manual 



Xlib-Colormaps- 



j XCopyColormapAndFree 



Name 

XCopyColormapAndFree copy a colormap and return a new colormap ID. 

Synopsis 

Colormap XCopyColormapAndFree ( display f cmap) 
Display *display; 
Colormap cmap; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

cmap Specifies the colormap you are moving out of. 

Description 

XCopyColormapAndFree is used to obtain a new virtual colormap when allocating color- 
cells out of a previous colormap has failed due to resource exhaustion (that is, too many cells or 
planes were in use in the original colormap). 

XCopyColormapAndFree moves all of the client s existing allocations from cmap to the 
returned Colormap and frees those entries in cmap. The visual type and screen for the new 
colormap is the same as for the old. 

If cmap was created by the client with the all oc argument set to All oc All, the new color- 
map is also created with AllocAll, all color values for all entries are copied from cmap, and 
then all entries in cmap are freed. 

If cmap was created by the client with AllocNone, the allocations to be moved are all those 
pixels and planes that have been allocated by the client using XAllocColor, XAlloc- 
NamedColor, XAllocColorCells, or XAllocColorPlanes and that have not been 
freed since they were allocated. Values in other entries of the new Colormap are undefined. 

For more information, see Volume One, Chapter 7, Color. 

Errors 

BadAlloc 
BadColormap 

Related Commands 

Def aultColormap, DisplayCells, XCreateColormap, XFreeColormap, XGet- 
StandardColormap, XInstallColormap, XListlnstalledColormaps, XSet- 
StandardColormap, XSetWindowColormap, XUninstallColormap. 



Xlib Reference Manual 



Py V xiib - Graphics Context- 

Name 

XCopyGC copy a graphics context. 

Synopsis 

XCopyGC (display, src, valuemask , dest) 
Display *display; 
GC src, dest; 
unsigned long valuemask; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

src Specifies the components of the source graphics context. 

valuemask Specifies the components in the source GC structure to be copied into the des 
tination GC. valuemask is made by combining any number of the mask 
symbols listed in the Structures section using bitwise OR (|). 

dest Specifies the destination graphics context. 

Description 

XCopyGC copies the selected elements of one graphics context to another. See Volume One, 
Chapter 5, The Graphics Context, for a description of the graphics context. 

Structures 

The GC structure contains the following elements: 

/* 

* Data structure for setting graphics context. 

*/ 
typedef struct { 

int function; /* logical operation */ 

unsigned long plane_mask; /* plane mask */ 

unsigned long foreground; /* foreground pixel */ 

unsigned long background; /* background pixel */ 

int line_width; /* line width */ 

int line_style; /* Solid, OnOffDash, DoubleDash */ 

int cap_style; /* NotLast, Butt, Round, Projecting */ 

int join_style; /* Miter, Round, Bevel */ 

int fill_style; /* Solid, Tiled, Stippled */ 

int fill_rule; /* EvenOdd, Winding */ 

int arc_mode; /* PieSlice */ 

Pixmap tile; /* tile pixmap for tiling operations */ 

Pixmap stipple; /* stipple 1 plane pixmap for stipping */ 

int ts_x_origin; /* offset for tile or stipple operations */ 

int ts_y_origin; 

Font font; /* default text font for text operations */ 

int subwindow_mode; /* ClipByChildren, Includelnf eriors */ 

Bool graphics_exposures; /* boolean, should exposures be generated */ 

int clip_x_origin; /* origin for clipping */ 



98 Xlib Reference Manual 



Xlib -Graphics Context (continued) XCopyGC 

int clip_y_origin; 

Pixmap clip_mask; /* bitmap clipping; other calls for rects */ 
int dash_offset; /* patterned/dashed line information */ 

char dashes; 
} XGCValues; 



#define GCFunction 

#define GCPlaneMask 

tdefine GCForeground 

#define GCBackground 

#define GCLineWidth 

#define GCLineStyle 

#define GCCapStyle 

tdefine GCJoinStyle 

tdefine GCFillStyle 

tdefine GCFillRule 

#define GCTile 

#define GCStipple 

#define GCTileStipXOrigin 

tdefine GCTileStipYOrigin 

tdefine GCFont 

tdefine GCSubwindowMode 

tdefine GCGraphicsExposures 

tdefine GCClipXOrigin 

tdefine GCClipYOrigin 

tdefine GCClipMask 

tdefine GCDashOffset (1L20) 

tdefine GCDashList (1L21) 

tdefine GCArcMode (1L22) 

Errors 

BadAlloc 

BadGC 

BadMatch src and dest do not have the same root and depth. 

Related Commands 

Def aultGC, XChangeGC, XCreateGC, XFreeGC, XGContextFromGC, XGet- 
GCValues, XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, 
XSetClipRectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSet- 
Foreground, XSetFunction, XSetGraphicsExposures, XSetLineAttributes, 
XSetPlaneMask, XSetState, XSetStipple, XSetSubwindowMode, XSet- 
TSOrigin. 



Xlib Reference Manual 99 



XCopyPlane \ xnb _ Drawlng 

Name 

XCopyPlane copy a single plane of a drawable into a drawable with depth, applying pixel 
values. 

Synopsis 

XCopyPlane ( display, src, dest , gc , src_x r src_y r width, 

height, dest_x , dest_y, plane) 
Display *display; 
Drawable src, dest , 
GC gc; 

int src_x, src_y; 
unsigned int width, height; 
int dest_x, dest_y; 
unsigned long plane; 

Arguments 

display Specifies a connection to an X server; returned from XQpenDisplay. 

src Specify the source and destination drawables. 

dest 

gc Specifies the graphics context. 

src_x Specify the x and y coordinates of the upper-left corner of the source rectan- 

src_y gle relative to the origin of the drawable. 

width Specify the width and height in pixels. These are the dimensions of both the 

height source and destination rectangles. 

dest_x Specify the x and y coordinates at which the copied area will be placed rela- 

dest_y live to the origin of the destination drawable. 

plane Specifies the source bit-plane. You must set exactly one bit, and the bit must 

specify a plane that exists in src. 

Description 

XCopyPlane copies a single plane of a rectangle in the source into the entire depth of a corre 
sponding rectangle in the destination. The plane of the source drawable and the f ore- 
ground/background pixel values in gc are combined to form a pixmap of the same depth 
as the destination drawable, and the equivalent of an XGopyArea is performed, with all the 
same exposure semantics. 

XCopyPlane uses these graphics context components: function, plane_mask, 
foreground, background, subwindow_mode, graphics_exposures, 
clip_x_origin, clip_y_origin, and clip_mask. 

The src and dest drawables must have the same root, but need not have the same depth. 
For more information, see Volume One, Chapter 5, The Graphics Context. 



100 Xlib Reference Manual 



Xlib - Drawing Primitives (continued) XCopyPlane 

Errors 

BadDrawable 

BadGC 

BadMatch src and dest do not have the same root 

BadValue plane does not have exactly one bit set, or bit specified in plane is not a 
plane in src. 

Related Commands 

XClearArea, XClearWindow, XCopyArea, XDraw, XDrawArc, XDrawArcs, XDraw- 
Filled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle, 
XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFillPolygon, 
XFillRectangle, XFillRectangles. 



Xlib Reference Manual 1 1 



XCreateAssocTable 

Xlib - Association Tables 

Name 

XCreateAssocTable create a new association table (X10). 

Synopsis 

XAssocTable *XCreateAssocTable (size) 
int size; 

Arguments 

si ze Specifies the number of buckets in the hashed association table. 

Description 

XCreateAssocTable creates an association table, which allows you to associate your own 
structures with X resources in a fast lookup table. This function is provided for compatibility 
with X Version 10. To use it you must include the file <Xll/X10.h> and link with the library 
-loldX. 

The size argument specifies the number of buckets in the hash system of XAssocTable. 
For reasons of efficiency the number of buckets should be a power of two. Some size sugges 
tions might be: use 32 buckets per 100 objects; a reasonable maximum number of object per 
buckets is 8. 

If there is an error allocating memory for the XAssocTable, a NULL pointer is returned. 
For more information on association tables, see Volume One, Appendix E,X10 Compatibility. 

Structures 

typedef struct { 

XAssoc *buckets; /* pointer to first bucket in array */ 
int size; /* table size (number of buckets) */ 

} XAssocTable; 

Related Commands 

XDeleteAssoc, XDestroyAssocTable, XLookUpAssoc, XMakeAssoc. 



102 Xlib Reference Manual 



Xlib - Pixmaps and Tiles- 



J XCreateBitmapFromData 



Name 

XCreateBitmapFromData create a bitmap from xil bitmap format data. 

Synopsis 

Pixmap XCreateBitmapFromData ( display, drawable, data, 

width, height) 
Display *display; 
Drawable drawable; 
char *data; 
unsigned int width, height; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenDi splay. 

drawable Specifies a drawable. This determines which screen to create the bitmap on. 
data Specifies the bitmap data, in XI 1 bitmap file format. 

width Specify the dimensions in pixels of the created bitmap. If smaller than the 

height bitmap data, the upper-left corner of the data is used. 

Description 

XCreateBitmapFromData creates a single-plane pixmap from an array of hexadecimal 
data. This data may be defined in the program or included. The bitmap data must be in X ver 
sion 11 format as shown below (it cannot be in X10 format). The following format is assumed 
for the data, where the variables are members of the ximage structure described in Volume 
One, Chapter 6, Drawing Graphics and Text: 

f ormat=XYP ixmap 

bit_order=LSBFirst 

byte_order=LSBFirst 

bitmap_unit=8 

bitmap_pad=8 

xof fset=0 

no extra bytes per line 

XCreateBitmapFromData creates an image with the specified data and copies it into the 
created pixmap. The following is an example of creating a bitmap: 

tdefine gray__width 16 

tdefine gray_height 16 

tdefine gray_x_hot 8 

tdefine gray_y_hot 8 

static char gray_bits [] = { 

Oxf8, Oxlf, Oxe3, Oxc7, Oxcf, Oxf3, Ox9f, Oxf9, 
Oxbf, Oxfd, 0x33, Oxcc, Oxlf, Oxfe, Oxlf, Oxfe, 



Xlib Reference Manual 103 



XCreateBitmapFromData (continued) Xlib - Pixmaps and Tiles 

Ox7e, Ox7e, Ox7f, Oxfe, 0x37, Oxec, Oxbb, Oxdd, 
Ox9c, 0x39, Oxcf, Oxf3, Oxe3, Oxc7, Oxf8, Oxlf}; 

Pixmap XCreateBitmapFromData (display, window, gray_bits, 
gray_width, gray_height) ; 

If the call could not create a pixmap of the requested size on the server, XCreateBitmap 
FromData returns (zero), and the server generates a BadAlloc error. If the requested 
depth is not supported on the screen of the specified drawable, the server generates a Bad- 
Match error. 

The user should free the bitmap using XFreePixmap when it is no longer needed. 
For more information, see Volume One, Chapter 6, Drawing Graphics and Text. 

Errors 

BadAlloc Server has insufficient memory to create bitmap. 

BadDrawable 

BadValue Specified bitmap dimensions are zero. 
Related Commands 

XCreatePixmap, XCreatePixmapFromBitmapData, XCreatePixmapFrom- 
BitmapData, XFreePixmap, XQueryBestSize, XQueryBestStipple, XQuery- 
BestTile, XReadBitmapFile, XSetTile, XSetWindowBackgroundPixmap, 
XSetWindowBorderPixmap, XWriteBitmapFile. 



104 Xlib Reference Manual 



Xlib - Colormaps - 



J XCreateColormap 



Name 

XCreateColormap create a colormap. 

Synopsis 

Colormap XCreateColormap ( display, w, visual, alloc) 
Display *display; 
Window w; 
Visual *visual; 
int alloc; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

w Specifies a window ID. The colormap created will be associated with the 

same screen as the window. 

visual Specifies a pointer to the visual structure for the colormap. The visual 

class and depth must be supported by the screen. 

alloc Specifies how many colormap entries to allocate. Pass either AllocNone or 

AllocAll. 

Description 

XCreateColormap creates a colormap of the specified visual type and allocates either none 
or all of its entries, and returns the colormap ID. 

It is legal to specify any visual class in the structure pointed to by the visual argument. If the 
class is StaticColor, StaticGray, or TrueColor, the colorcells will have pre-allocated 
read-only values defined by the individual server but unspecified by the XI 1 protocol. In these 
cases, alloc must be specified as AllocNone (else a BadMatch error). 

For the other visual classes, Pseudocolor, DirectColor, and Grayscale, you can pass 
either AllocAll or AllocNone to the alloc argument. If you pass AllocNone, the 
colormap has no allocated entries. This allows your client programs to allocate read-only 
colorcells with XAllocColor or read/write cells with XAllocColorCells, Alloc- 
ColorPlanes and XStoreColors. If you pass the constant AllocAll, the entire color- 
map is allocated writable (all the entries are read/write, nonshareable and have undefined initial 
RGB values), and the colors can be set with XStoreColors. However, you cannot free these 
entries with XFreeColors, and no relationships between the entries are defined. 

If the visual class is Pseudocolor or Grayscale and alloc is AllocAll, this function 
simulates a call to the function XAllocColor cells returning all pixel values from 1 to 
(map_entries - 1) . For a visual class of DirectColor, the processing for AllocAll 
simulates a call to the function XAllocColorPlanes, returning a pixel value of and mask 
values the same as the red__mask, green_mask, and blue_mask members in visual. 



Xlib Reference Manual 105 



XCreateColormap (continued) Xlib - Colormaps 

The visual argument should be as returned from the Def aultvisual macro, XMatch- 
Visuallnf o, or XGetVisuallnf o. 

If the hardware colormap on the server is immutable, and therefore there is no possibility that a 
virtual colormap could ever be installed, XCreateColormap returns the default colormap. 
Code should check the returned ID against the default colormap to catch this situation. 

For more information on creating colormaps, see Volume One, Chapter 7, Color. 

Errors 

BadAlloc 

BadMatch Didn t use AllocNone for StaticColor, StaticGray, or True- 
Color, 
visual type not supported on screen. 

BadValue 
BadWindow 

Related Commands 

Def aultColormap, DisplayCells, XCopyColormapAndFree, XFreeColormap, 
XGetStandardColormap, XInstallColormap, XListlnstalledColormaps, 
XSetStandardColormap, XSetWindowColormap, XUninstallColormap. 



106 Xlib Reference Manual 



Xlib- Cursors- 



XCreateFontCursor 



Name 

XCreateFontCursor create a cursor from the standard cursor font. 



Synopsis 

#include <Xll/cursorf ont .h> 
Cursor XCreateFontCursor ( display, 

Display * display ; 

unsigned int shape; 



shape) 



Arguments 

display Specifies a connection to an X server; returned from xopenDisplay. 

shape Specifies which character in the standard cursor font should be used for the cur 

sor. 

Description 

X provides a set of standard cursor shapes in a special font named "cursor." Programs are 
encouraged to use this interface for their cursors, since the font can be customized for the indi 
vidual display type and shared between clients. 

The hotspot comes from the information stored in the font. The initial colors of the cursor arc 
black for the foreground and white for the background. XRecolorCursor can be 
used to change the colors of the cursor to those desired. 

For more information about cursors and their shapes in fonts, see Appendix I, The Cursor Font. 



* 



H 



ft 



V 



D 



H 



H 



4 



a 



r 



X//6 Reference Manual 



107 



XCreateFontCursor (continued) Xlib - Cursors 

Errors 

BadAlloc 

BadFont 

BadValue The shape argument does not specify a character in the standard cursor font. 

Related Commands 

XCreateGlyphCursor, XCreatePixmapCursor, XDef ineCursor, XFreeCursor, 
XQueryBestCursor, XQueryBestSize, XRecolorCursor, XUndef ineCursor. 



108 Xlib Reference Manual 



Xlib - Graphics Context- 



XCreateGC 



Name 

XCreateGC create a new graphics context for a given screen with the depth of the specified 
drawable. 

Synopsis 

GC XCreateGC (display, drawable, valuemask, values) 
Display *display; 
Drawable drawable; 
unsigned long valuemask; 
XGCValues * values ; 



Arguments 

di spl ay 
drawable 

valuemask 
values 



Specifies a connection to an X server; returned from xopenDisplay. 

Specifies a drawable. The created GC can only be used to draw in drawables 
of the same depth as this drawable. 

Specifies which members of the GC are to be set using information in the 
values structure, valuemask is made by combining any number of the 
mask symbols listed in the Structures section. 

Specifies a pointer to an XGCValues structure which will provide compo 
nents for the new GC. 

Description 

XCreateGC creates a new graphics context resource in the server. The returned GC can be 
used in subsequent drawing requests, but only on drawables on the same screen and of the same 
depth as the drawable specified in the drawable argument. 

The specified components of the new graphics context in valuemask are set to the values 
passed in the val ues argument. Unset components default as follows: 



Component Value 



plane_mask 

foreground 

background 

line_width 

line_style 

cap_style 

join_style 

fill_style 

fill_rule 

arc_mode 

tile 

stipple 



alll s 

o 

i 



LineSolid 

CapButt 

JoinMiter 

FillSolid 

EvenOddRule 

ArcPieSlice 

Pixmap filled with foreground pixel 

Pixmap filled with 1 s 



Xlib Reference Manual 



109 



XCreateGC 



(continued) 



Xlib - Graphics Context 



Component 


Value 


ts_x_origin 







ts y origin 







font 


(implementation 


dependent) 


subwindow mode 


ClipByChildren 


graphics_exposures 


True 




clip x origin 







clip_y_origin 







clip_mask 


None 




dash offset 







dash list 


4 (i.e., the list [4 


,4]) 



An application should minimize the number of GCs it creates, because some servers cache a 
limited number of GCs in the display hardware, and can attain better performance with a small 
number of GCs. 

For more information, see Volume One, Chapter 5, The Graphics Context. 

Errors 

BadAlloc Server could not allocate memory for GC. 

BadDrawable Specified drawable is invalid. 

BadFont Font specified for font component of GC has not been loaded. 

BadMatch Pixmap specified for tile component has different depth or is on different 
screen from the specified drawable. Or pixmap specified for stipple or 
clip_mask component has depth other than 1. 

BadPixmap Pixmap specified for tile, stipple, or clip_mask components is inva 
lid. 

BadValue Values specified for function, line_style, cap_style, 
join_style, f ill_style, f ill_rule, subwindow_mode, graph- 
ics_exposures, dashes, or arcjmode are invalid, or invalid mask 
specified for valuemask argument. 



Structures 

typedef struct { 

int function; /* 

unsigned long plane mask; /* 

unsigned long foreground; /* 

unsigned long background; /* 

int line_width; /* 

int line_style; /* 

int cap_style; /* 

int join_style; /* 

int fill_style; /* 

int fill rule; /* 



logical operation */ 

plane mask */ 

foreground pixel */ 

background pixel */ 

line width */ 

LineSolid, LineOnOf f Dash, LineDoubleDash */ 

CapNotLast, CapButt, CapRound, CapPro jecting */ 

JoinMiter, JoinRound, JoinBevel */ 

FillSolid, FillTiled, FillStippled */ 

EvenOddRule, WindingRule */ 



110 



Xlib Reference Manual 



Xlib - Graphics Context 



(continued) 



XCreateGC 



int arc_mode; 
Pixmap tile; 
Pixmap stipple; 
int ts_x_origin; 
int ts_y_origin; 
Font font; 
int subwindow_mode; 
Bool graphics_exposures; 
int clip_x_origin; 
int clip_y_origin; 
Pixmap clip_mask; 
int dash_offset; 
char dashes; 
} XGC Value s; 

#define GCFunction 
#define GCPlaneMask 
#define GCForeground 
#define GCBackground 
#define GCLineWidth 
#define GCLineStyle 
#define GCCapStyle 
#define GCJoinStyle 
#define GCFillStyle 
#define GCFillRule 
#define GCTile 
#define GCStipple 
#define GCTileStipXOrigin 
#define GCTileStipYOrigin 
#define GCFont 
#define GCSubwindowMode 
#define GCGraphicsExposures 
#define GCClipXOrigin 
#define GCClipYOrigin 
tdefine GCClipMask 
#define GCDashOffset 
#define GCDashList 
#define GCArcMode 



/* ArcPieSlice, ArcChord */ 

/* tile pixmap for tiling operations */ 

/* stipple 1 plane pixmap for stipping */ 

/* offset for tile or stipple operations */ 

/* default text font for text operations */ 

/* ClipByChildren, Includelnferiors */ 

/* generate events on XCopyArea, XCopyPlane */ 

/* origin for clipping */ 

/* bitmap clipping; other calls for rects */ 

/* patterned/dashed line information */ 



(1L20) 
(1L22) 



Related Commands 

Def aultGC, XChangeGC, XCopyGC, XFreeGC, XGContextFromGC, XGetGCValues, 
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground, 
XSetFunction, XSetGraphicsExposures, XSetLineAttributes, XSetPlane- 
Mask, XSetState, XSetStipple, XSetSubwindowMode, XSetTSOrigin. 



Xlib Reference Manual 



111 



XCreateGlyphCursor \ 

v Xlib - Cursors- 
Name 

XCreateGlyphCursor create a cursor from font glyphs. 

Synopsis 

Cursor XCreateGlyphCursor ( display, source_font , mask_font, 
source_char r mask_char , foreground_color, back- 
ground_color) 

Display * display ; 

Font source_font , mask_font; 

unsigned int source_char, mask_char; 

XColor * foreground_color; 

XColor *background_color; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

source_font Specifies the font from which a character is to be used for the cursor. 
mask_font Specifies the mask font. Optional; specify if not needed. 
source_char Specifies the index into the cursor shape font. 

mask_char Specifies the index into the mask shape font. Optional; specify if not 
needed. 

foreground_color 

Specifies the red, green, and blue (RGB) values for the foreground. 

background_color 

Specifies the red, green, and blue (RGB) values for the background. 

Description 

XCreateGlyphCursor is similar to XCreatePixmapCursor, but the source and mask 
bitmaps are obtained from separate font characters, perhaps in separate fonts. The mask font 
and character are optional. If mask_char is not specified, all pixels of the source are 
displayed. 

The x offset for the hotspot of the created cursor is the left-bearing for the source character, and 
the y offset is the ascent, each measured from the upper-left corner of the bounding rectangle of 
the character. 

The origins of the source and mask (if it is defined) characters are positioned coincidently and 
define the hotspot. The source and mask need not have the same bounding box metrics, and 
there is no restriction on the placement of the hotspot relative to the bounding boxes. 

Note that source_char and mask_char are of type unsigned int, not of type 
XChar2b. For two-byte matrix fonts, source_char and mask_char should be formed 
with the bytel member in the most significant byte and the byte2 member in the least signif 
icant byte. 



1 12 Xlib Reference Manual 



Xlib- Cursors (continued) XCreateGlyphCursor 

You can free the fonts with XFreeFont if they are no longer needed after creating the glyph 
cursor. 

For more information on fonts and cursors, see Volume One, Chapter 6, Drawing Graphics and 
Text. 

Structures 

typedef struct { 

unsigned long pixel; 

unsigned short red, green, blue; 

char flags; /* DoRed, DoGreen, DoBlue */ 

char pad; 
} XColor; 

Errors 

BadAlloc 

BadFont 

BadValue source_charnot defined in source_font. 

mask_ch a mot defined in mask_font (if mas k_ font defined). 

Related Commands 

XCreateFontCursor, XCreatePixmapCursor, XDef ineCursor, XFreeCursor, 
XQueryBestCursor, XQueryBestSize, XRecolorCursor, XUndef ineCursor. 



Xlib Reference Manual 1 13 



XCreatelmage \ X|jb _ |mages _ 

Name 

XCreatelmage allocate memory for an Xlmage structure. 

Synopsis 

tfinclude <Xll/Xutil.h> 

Xlmage *XCreateImage (display, visual, depth, format, offset, 
data, width, height, bitmap_pad, bytes_per_line) 

Display * display; 

Visual *visual; 

unsigned int depth; 

int format; 

int offset; 

char *data; 

unsigned int width; 

unsigned int height; 

int bitmap_pad; 

int bytes_per_line; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

visual Specifies a pointer to a visual that should match the visual of the window the 

image is to be displayed in. 

depth Specifies the depth of the image. 

format Specifies the format for the image. Pass one of these constants: XYPixmap, 

or ZPixmap. 

offset Specifies the number of pixels beyond the beginning of the data (pointed to 

by data) where the image actually begins. This is useful if the image is not 
aligned on an even addressable boundary. 

da t a Specifies a pointer to the image data. 

wi dth Specify the width and height in pixels of the image. 

height 

bi t/nap_pad Specifies the quantum of a scan line. In other words, the start of one scan line 
is separated in client memory from the start of the next scan line by an integer 
multiple of this many bits. You must pass one of these values: 8 , 1 6 , or 3 2 . 

jbytes_per_line 

Specifies the number of bytes in the client image between the start of one 
scan line and the start of the next. If you pass a value of here, Xlib assumes 
that the scan lines are contiguous in memory and thus calculates the value of 
bytes_per_line itself. 



7 14 Xlib Reference Manual 



Xlib- Images (continued) XCreatelmage 

Description 

XCreatelmage allocates the memory needed for an Xlmage structure for the specified dis 
play and visual. 

This function does not allocate space for the image itself. It initializes the structure with byte 
order, bit order, and bitmap unit values, and returns a pointer to the Xlmage structure. The red, 
green, and blue mask values are defined for ZPixmap format images only and are derived from 
the visual structure passed in. 

For a description of images, see Volume One, Chapter 6, Drawing Graphics and Text. 
Related Commands 

ImageByteOrder, XAddPixel, XDestroylmage, XGetlmage, XGetPixel, XGet- 
Sublmage, XPutlmage, XPutPixel, XSublmage. 



Xlib Reference Manual 



115 



XCreatePixmap 

Xlib - Pixmaps and Tiles- 
Name 

XCreatePixmap create a pixmap. 

Synopsis 

Pixmap XCreatePixmap ( display, drawable , width, height, depth) 
Display * display; 
Drawable drawable; 
unsigned int width, height; 
unsigned int depth; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenDi spl ay. 

drawable Specifies the drawable. May be an inputOnly window. 

width Specify the width and height in pixels of the pixmap. The values must be 

height nonzero. 

depth Specifies the depth of the pixmap. The depth must be supported by the screen 

of the specified drawable. (Use XListDepths if in doubt.) 

Description 

XCreatePixmap creates a pixmap resource and returns its pixmap ID. The initial contents 
of the pixmap are undefined. 

The server uses the drawable argument to determine which screen the pixmap is stored on. 
The pixmap can only be used on this screen. The pixmap can only be drawn drawn into with 
GCs of the same depth, and can only be copied to drawables of the same depth, except in 
XCopyPlane. 

A bitmap is a single-plane pixmap. There is no separate bitmap type in X Version 11. 

Pixmaps should be considered a precious resource, since many servers have limits on the 
amount of off-screen memory available. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text. 

Errors 

BadAlloc 

BadDrawable 

BadValue width or height is 0. 

depth is not supported on screen. 

Related Commands 

XCreateBitmapFromData, XCreatePixmapFromBitmapData, XFreePixmap, 
XListDepths, XListPixmapFormat, XQueryBestCursor, XQueryBestSize, 
XQueryBestStipple, XQueryBestTile, XReadBitmapFile, XSetTile, XSet- 
WindowBackgroundPixmap, XSetWindowBorderPixmap, XWriteBitmapFile. 



1 16 Xlib Reference Manual 



Xlib - Pixmaps and Tiles- 



J XCreatePixmapCursor 



Name 

XCreatePixmapCursor create a cursor from two bitmaps. 

Synopsis 

Cursor XCreatePixmapCursor ( display, source, mask, 

foreground_color, background_color, x_hot , y_hot) 
Display * display; 
Pixmap source; 
Pixmap mask; 

XColor * foreground_color; 
XColor *background_color; 
unsigned int x_hot , y_hot ; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenDi spl ay. 

source Specifies the shape of the source cursor. A pixmap of depth 1. 

mask Specifies the bits of the cursor that are to be displayed (the mask or stipple). 

A pixmap of depth 1. 

-foreground_color 

Specifies the red, green, and blue (RGB) values for the foreground. 

jbacJegrour!d_co-Zor 

Specifies the red, green, and blue (RGB) values for the background. 

x_hot Specify the coordinates of the cursor s hotspot relative to the source s origin. 

y_hot Must be a point within the source. 



Description 

XCreatePixmapCursor creates a cursor and returns a cursor ID. Foreground and back 
ground RGB values must be specified using oreground_color and back- 
ground_color, even if the server only has a monochrome screen. The fore- 
ground_color is used for the 1 bits in the source, and the background is used for the bits. 
Both source and mask (if specified) must have depth 1, but can have any root. The mask pix 
map defines the shape of the cursor; that is, the 1 bits in the mask define which source pixels 
will be displayed. If no mask is given, all pixels of the source are displayed. The mask, if 
present, must be the same size as the source. 

The pixmaps can be freed immediately if no further explicit references to them are to be made. 
For more information on cursors, see Volume One, Chapter 6, Drawing Graphics and Text. 

Structures 

typedef struct { 

unsigned long pixel; 

unsigned short red, green, blue; 

char flags; /* DoRed, DoGreen, DoBlue */ 



Xlib Reference Manual 1 1 7 



XCreatePixmapCursor (continued) Xlib - Pixmaps and Tiles 

char pad; 
} XColor; 

Errors 

BadAlloc 

BadMatch Mask bitmap must be the same size as source bitmap. 
BadPixmap 

Related Commands 

XCreateBitmapFromData, XDef ineCursor, XCreateFontCursor, XCreate- 
Pixmap, XCreatePixmapCursor, XFreeCursor, XFreePixmap, XQueryBest- 
Cursor, XQueryBestCursor, XQueryBestSize, XQueryBestSize, XRead- 
BitmapFile, XRecolorCursor, XUndef ineCursor. 



1 18 Xlib Reference Manual 



Xlib - Pixmaps and Bitmaps - 



XCreatePixmapFromBJtmapData 



Name 

XCreatePixmapFromBitmapData create a pixmap with depth from bitmap data. 

Synopsis 

Pixmap XCreatePixmapFromBitmapData ( display, drawable, data, 

width, height, fg, bg, depth) 
Display * display; 
Drawable drawable; 
char *data; 

unsigned int width, height; 
unsigned long fg, bg; 
unsigned int depth; 

Arguments 

display Specifies a connection to an Display structure, returned from XOpen- 

Display. 

drawable Specifies a drawable ID which indicates which screen the pixmap is to be 
used on. 

data Specifies the data in bitmap format. 

width Specify the width and height in pixels of the pixmap to create. 

height 

fg Specify the foreground and background pixel values to use. 

bg 

depth Specifies the depth of the pixmap. Must be valid on the screen specified by 

drawable. 

Description 

XCreatePixmapFromBitmapData creates a pixmap of the given depth using bitmap data 
and foreground and background pixel values. 

The following format for the data is assigned, where the variables are members of the XI mage 
structure described in Volume One, Chapter 6, Drawing Graphics and Text: 

format =XYP ixmap 

bit_order=LSBFirst 

byte_order=LSBFirst 

bitmap_unit=8 

bitmap_pad=8 

xoffset=0 

no extra bytes per line 

XCreatePixmapFromBitmapData creates an image from the data and uses XPutlmage 
to place the data into the pixmap. For example: 



Xlib Reference Manual 1 19 



XCreatePixmapFromBitmapData (continued) 



Xlib - Pixmaps and Bitmaps 



#define gray_width 16 

#define gray_height 16 

#define gray_x_hot 8 

#define gray_y_hot 8 

static char gray_bits[] = 
Oxf8, Oxlf, Oxe3, Oxc7, 
Oxfd, 0x33, Oxcc, Ox7f, 
Ox7f, Oxfe, 0x37, Oxec, 
Oxf3, Oxe3, Oxc7, Oxf8, 



Oxcf, 
Oxfe, 
Oxbb, 

Oxlf} 



Oxf3, 
Ox7f, 
Oxdd, 



Ox9f, 
Oxfe, 
Ox9c, 



Oxf9, 
Ox7e, 
0x39, 



Oxbf, 
Ox7e, 
Oxcf, 



unsigned long foreground, background; 
unsigned int depth; 

/* open display, determine colors and depth */ 

Pixmap XCreatePixmapFromBitmapData (display, window, gray_bits, 

gray_width, gray_height, foreground, background, depth) ; 

If you want to use data of a different format, it is straightforward to write a routine that does 
this yourself, using images. 

Pixmaps should be considered a precious resource, since many servers have limits on the 
amount of off-screen memory available. 

Errors 

BadAlloc 
BadDrawable 

BadValue The width or height of pixmap are zero, or depth is not a valid depth on 
the screen specified by drawable. 

Related Commands 

XCreateBitmapFromData, XCreateFontCursor, XCreatePixmap, XCreate- 
PixmapCursor, XDef ineCursor, XFreeCursor, XFreePixmap, XListPixmap- 
Formats, XQueryBestCursor, XQueryBestSize, XReadBitmapFile, XRecolor- 
Cursor, XUndef ineCursor. 



120 



Xlib Reference Manual 



Xlib- Regions- 



J XCreateRegion 



Name 

XCreateRegion create a new empty region. 

Synopsis 

Region XCreateRegion () 

Description 

XCreateRegion creates a new region of undefined size. XPolygonRegion can be used to 
create a region with a defined shape and size. Many of the functions that perform operations on 
regions can also create regions. 

For a description of regions, see Volume One, Chapter 6, Drawing Graphics and Text. 

Structures 

Region is a pointer to an opaque structure type. 

Related Commands 

XClipBox, XDestroyRegion, XEmptyRegion, XEqualRegion, Xlntersect- 
Region, XOf f setRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion, 
XSetRegion, XShrinkRegion, XSubtractRegion, XUnionRectWithRegion, 
XUnionRegion, XXorRegion. 



Xlib Reference Manual 121 



XCreateSimpleWindow . vr . 

v Xlib - Window Existence 

Name 

XCreateSimpleWindow create an unmapped InputOutput window. 

Synopsis 

Window XCreateSimpleWindow (display, parent, x, y, width, height, 
border_width, border, background) 

Display * display; 

Window parent; 

int x, y; 

unsigned int width, height, border_width; 

unsigned long border; 

unsigned long background; 

Arguments 

di spl ay Specifies a pointer to the Di spl ay structure; returned from XOpenDi spl ay. 

parent Specifies the parent window ID. Must be an InputOutput window. 

x Specify the x and y coordinates of the upper-left pixel of the new window s 

y border relative to the origin of the parent (inside the parent window s border). 

width Specify the width and height, in pixels, of the new window. These are the 

height inside dimensions, not including the new window s borders, which are entirely 

outside of the window. Must be nonzero. Any part of the window that extends 

outside its parent window is clipped. 

border_wi dth 

Specifies the width, in pixels, of the new window s border. 

border Specifies the pixel value for the border of the window. 

background Specifies the pixel value for the background of the window. 

Description 

XCreateSimpleWindow creates an unmapped InputOutput subwindow of the specified 
parent window. Use XCreateWindow if you want to set the window attributes while creating 
a window. (After creation, XChangeWindowAttributes can be used.) 

XCreateSimpleWindow returns the ID of the created window. The new window is placed 
on top of the stacking order relative to its siblings. Note that the window is unmapped when it 
is created use Mapwindow to display it. This function generates a XCreateNotify event. 

The initial conditions of the window are as follows: 

The window inherits its depth, class, and visual from its parent. All other window attributes 
have their default values. 

All properties have undefined values. 

The new window will not have a cursor defined; the cursor will be that of the window s parent 
until the cursor attribute is set with XDefineCursor or XChangeWindowAttributes. 



122 Xlib Reference Manual 



Xlib- Window Existence (continued) XCreateSimpleWindOW 

If no background or border is specified, CopyFromParent is implied. 

For more information, see Volume One, Chapter 2, X Concepts, and Volume One, Chapter 3, 
Basic Window Program. 

Errors 

BadAlloc 

BadMatch 

BadValue width or height is zero. 

Badwindow Specified parent is an Input Only window. 

Related Commands 

XCreateWindow, XDestroySubwindows, XDestroyWindow. 



Xlib Reference Manual 123 



XCreateWindow "\ 

v Xlib - Window Existence 

Name 

XCreateWindow create a window and set attributes. 

Synopsis 

Window XCreateWindow (display, parent, x, y, width, height, 
border_width, depth, class, visual, valuemask, 
attributes) 

Display * display; 

Window parent; 

int x, y; 

unsigned int width, height; 

unsigned int border_width; 

int depth; 

unsigned int class; 

Visual ^visual 

unsigned long valuemask; 

XSetWindowAttributes * attributes; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

parent Specifies the parent window. Parent must be inputOutput if class of win 

dow created is to be InputOutput. 

x Specify the x and y coordinates of the upper-left pixel of the new window s 

y border relative to the origin of the parent (upper left inside the parent s border). 

width Specify the width and height, in pixels, of the window. These are the new win- 

height dow s inside dimensions. These dimensions do not include the new window s 

borders, which are entirely outside of the window. Must be nonzero, otherwise 

the server generates a BadValue error. 

border_ width 

Specifies the width, in pixels, of the new window s border. Must be for 
inputOnly windows, otherwise a BadMatch error is generated. 

depth Specifies the depth of the window, which is less than or equal to the parent s 

depth. A depth of CopyFromParent means the depth is taken from the par 
ent. Use XListDepths is choosing an unusual depth. The specified depth 
paired with the visual argument must be supported on the screen. 

class Specifies the new window s class. Pass one of these constants: Input- 

Output, InputOnly, or CopyFromParent. 

visual Specifies a connection to an visual structure describing the style of colormap to 

be used with this window. CopyFromParent is valid. 

valuemask Specifies which window attributes are defined in the attributes argument. 
If valuemask is 0, attributes is not referenced. This mask is the bitwise 
OR of the valid attribute mask bits listed in the Structures section below. 



124 Xlib Reference Manual 



Xlib - Window Existence (continued) XCreateWindOW 

attributes Attributes of the window to be set at creation time should be set in this struc 
ture. The value/nasJt should have the appropriate bits set to indicate which 
attributes have been set in the structure. 

Description 

To create an unmapped subwindow for a specified parent window use XCreateWindow or 
XCreateSimpleWindow. XCreateWindow is a more general function that allows you to 
set specific window attributes when you create the window. If you do not want to set specific 
attributes when you create a window, use XCreateSimpleWindow, which creates a window 
that inherits its attributes from its parent. XCreateSimpleWindow creates only Input- 
Output windows that use the default depth and visual. 

XCreateWindow returns the ID of the created window. XCreateWindow causes the X 
server to generate a CreateNotif y event. The newly created window is placed on top of its 
siblings in the stacking order. 

Extension packages may define other classes of windows. 

The visual should be Def aultvisual or one returned by XGetvisuallnf o or XMatch- 
Visuallnfo. The depth should be DefaultDepth, 1, or a depth returned by XList- 
Depths. In current implementations of Xlib, if you specify a visual other than the one used by 
the parent, you must first find (using XGetRGBColormaps) or create a colormap matching 
this visual and then set the colormap window attribute in the attributes and valuemask 
arguments. Otherwise, you will get a BadMatch error. 

For more information, see Volume One, Chapter 4, Window Attributes. 

Structures 

/* 

* Data structure for setting window attributes. 

*/ 
typedef struct { 

Pixmap background_pixmap; /* background or None or ParentRelative */ 

unsigned long background_pixel; /* background pixel */ 

Pixmap border_pixmap; /* border of the window */ 

unsigned long border_pixel; /* border pixel value */ 

int bit_gravity; /* one of bit gravity values */ 

int win gravity; /* one of the window gravity values */ 

int backing store; /* NotUseful, WhenMapped, Always */ 

unsigned long backing_planes; /* planes to be preseved if possible */ 

unsigned long backing_pixel; /* value to use in restoring planes */ 

Bool save_under; /* should bits under be saved (popups) */ 

long event mask; /* set of events that should be saved */ 

long do not propagate_mask; /* set of events that should not propagate i 

Bool override_redirect; /* boolean value for override-redirect */ 

Colormap colormap; /* colormap to be associated with window */ 

Cursor cursor; /* cursor to be displayed (or None) */ 
} XSetWindowAttributes; 



Xlib Reference Manual 125 



XCreateWindOW (continued) Xlib - Window Existence 

/* Definitions for valuemask argument */ 

tdefine CWBackPixmap (1L0) 

tdefine CWBackPixel (1L1) 

tdefine CWBorderPixmap (1L2) 

#define CWBorderPixel (1L3) 

#define CWBitGravity (1L4) 

#define CWWinGravity (1L5) 

#define CWBackingStore (1L6) 

tdefine CWBackingPlanes (1L7) 

#define CWBackingPixel (1L8) 

tdefine CWOverrideRedirect (1L9) 

tdefine CWSaveUnder (1L10) 

#define CWEventMask (1L11) 

tdefine CWDontPropagate (1L12) 

tdefine CWColormap (1L13) 

tdefine CWCursor (1L14) 

Errors 

BadAlloc Attribute besides win_gravity, event_mask, do_not_propagate 
mask, override_redirect or cursor specified for InputOnly win 
dow. 

BadColormap depth nonzero for InputOnly. 
BadCursor Parent of InputOutput is InputOnly. 
BadMatch border_width is nonzero for InputOnly. 
BadPixmap depth not supported on screen for InputOutput. 
BadValue width or height is 0. 
Badwindow visual not supported on screen. 

Related Commands 

XCreateSimpleWindow, XDestroySubwindows, XDestroyWindow, XList- 
Depths. 



126 xiib Reference Manual 



-x,,b - cursors / XDefineCursor 

Name 

XDefineCursor assign a cursor to a window. 

Synopsis 

XDefineCursor (display, w, cursor) 
Display * display; 
Window w; 
Cursor cursor; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

w Specifies the ID of the window in which the cursor is to be displayed. 

cursor Specifies the cursor to be displayed when the pointer is in the specified win 

dow. Pass None to have the parent s cursor displayed in the window, or for 
the root window, to have the default cursor displayed. 

Description 

Sets the cursor attribute of a window, so that the specified cursor is shown whenever this win 
dow is visible and the pointer is inside. If XDefineCursor is not called, the parent s cursor 
is used by default. 

For more information on available cursors, see Appendix I, The Cursor Font. 
Errors 

BadCursor 
BadWindow 

Related Commands 

XCreateFontCursor, XCreateGlyphCursor, XCreatePixmapCursor, XFree- 
Cursor, XQueryBestCursor, XQueryBestSize, XRecolorCursor, XUndef ine- 
Cursor. 



Xlib Reference Manual 127 



XDeleteAssoc , vr . 

v Xlib - Association Tables- 
Name 

XDeleteAssoc delete an entry from an association table. 

Synopsis 

XDeleteAssoc ( display, table , x_id) 
Display * display ; 
XAssocTable * table; 
XID x_id; 

Arguments 

display Specifies a connection to an X server; returned from XQpenDi splay. 

table Specifies one of the association tables created by XCreateAssocTable. 

x_i d Specifies the X resource ID of the association to be deleted. 

Description 

This function is provided for compatibility with X Version 10. To use it you must include the 
file <XlllX10.h> and link with the library -loldX. 

XDeleteAssoc deletes an association in an XAssocTable keyed on its XID. Redundant 
deletes (and deletes of nonexistent X ID S) are meaningless and cause no problems. Deleting 
associations in no way impairs the performance of an XAssocTable. 

For more information on association tables, see Volume One, Appendix R,X10 Compatibility. 
Structures 

typedef struct { 

XAssoc ^buckets; /* pointer to first bucket in array */ 
int size; /* table size (number of buckets) */ 

} XAssocTable; 

Related Commands 

XCreateAssocTable, XDestroyAssocTable, XLookUpAssoc, XMakeAssoc. 



128 Xlib Reference Manual 



-XHb - Conttxt Manager - / 



Name 

XDeleteContext delete a context entry for a given window and type. 

Synopsis 

int XDeleteContext { display, w r context) 
Display * display; 
Window w; 
XContext context; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

w Specifies the window with which the data is associated. 

context Specifies the context type to which the data belongs. 

Description 

XDeleteContext deletes the entry for the given window and type from the context data 
structure defined in <Xll/Xutil.h>. This function returns XCNOENT if the context could not be 
found, or zero if it succeeds. XDeleteContext does not free the memory allocated for the 
data whose address was saved. 

See Volume One, Chapter 13, Other Programming Techniques, for a description of context 
management. 

Structures 

typedef int XContext; 

Related Commands 

XFindContext, XSaveContext, XUniqueContext. 



Xlib Reference Manual 129 



XDeleteModifiermapEntry \ X|lb _ ResourM Manager _ 

Name 

XDeleteModifiermapEntry delete an entry from an XModif ierKeymap structure. 

Synopsis 

XModif ierKeymap *XDeleteModif iermapEntry (/nod/nap, 

keysym_entry, modifier) 
XModif ierKeymap * modmap; 
KeyCode keysym_entry; 
int modifier; 

Arguments 

modmap Specifies a pointer to an XModif ierKeymap structure. 

k eysym_ entry 

Specifies the keycode of the key to be deleted from modmap. 

modifier Specifies the modifier you no longer want mapped to the keycode specified in 
keysym_entry. This should be one of the constants: Shif tMaplndex, 
LockMapIndex, ControlMapIndex, ModlMapIndex, Mod2Map- 
Index, ModSMapIndex, Mod4MapIndex, or ModSMapIndex. 

Description 

XDeleteModifiermapEntry returns an XModif ierKeymap structure suitable for cal 
ling XSetModif ierMapping, in which the specified keycode is deleted from the set of key- 
codes that is mapped to the specified modifier (like Shift or Control). XDelete 
ModifiermapEntry itself does not change the mapping. 

This function is normally used by calling XGetModif ierMapping to get a pointer to the 
current XModif ierKeymap structure for use as the modmap argument to XDelete 
ModifiermapEntry. 

Note that the structure pointed to by modmap is freed by XDeleteModifiermapEntry. It 
should not be freed or otherwise used by applications after this call. 

For a description of the modifier map, see XSetModif ierMapping. 
Structures 

typedef struct { 

int max_keypermod; /* server s max number of keys per modifier */ 
KeyCode *modif iermap; /* an 8 by max_keypermod array of 

* keycodes to be used as modifiers */ 

} XModif ierKeymap; 

#define ShiftMapIndex 

#define LockMapIndex 1 

tdefine ControlMapIndex 2 

#define ModlMapIndex 3 

#define Mod2MapIndex 4 

tdefine ModSMapIndex 5 



130 Xlib Reference Manual 



Xlib - Resource Manager (continued) XDeleteModif iermapEntry 

tdefine Mod4MapIndex 6 
tdefine ModSMapIndex 

Related Commands 

XFreeModif iermap, XGetKeyboardMapping, XGetModif ierMapping, 
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym, 
XLookupString, XNewModif iermap, XQueryKeymap, XRebindKeySym, 
XRef reshKeyboardMapping, XSetModif ierMapping, XStringToKeysym, 
I nsertModif iermapEntry. 



Xlib Reference Manual 131 



XDeleteProperty V 



Name 

XDeleteProperty delete a window property. 

Synopsis 

XDeleteProperty ( display, w, property) 
Display * display ; 
Window w; 
Atom property; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the ID of the window whose property you want to delete. 

property Specifies the atom of the property to be deleted. 

Description 

XDeleteProperty deletes a window property, so that it no longer contains any data. Its 
atom, specified by property, still exists after the call so that it can be used again later by any 
application to set the property once again. If the property was defined on the specified window, 
XDeleteProperty generates a PropertyNotify event. 

See the introduction to properties in Volume One, Chapter 2, X Concepts, or more detailed 
information in Volume One, Chapter 10, Interclient Communication. 

Errors 

BadAtom 
BadWindow 

Related Commands 

XChangeProperty, XGetAtomName, XGetFontProperty, XGetWindowProperty, 
XInternAtom, XListProperties, XRotateWindowProperties, XSetStandard- 
Properties. 



132 xiib Reference Manual 



Xlib - Association Tables- 



J XDestroyAssocTable 



Name 

XDestroyAssocTable free the memory allocated for an association table. 

Synopsis 

XDestroyAssocTable (table) 
XAssocTable *table; 

Arguments 

tabl e Specifies the association table whose memory is to be freed. 

Description 

This function is provided for compatibility with X Version 10. To use it you must include the 
file <Xll/X10.h> and link with the library -loldX. 

Using an XAssocTable after it has been destroyed will have unpredictable consequences. 
For more information on association tables, see Volume One, Appendix B, XI Compatibility. 

Structures 

typedef struct { 

XAssoc ^buckets; /* pointer to first bucket in array */ 
int size; /* table size (number of buckets) */ 

} XAssocTable; 

Related Commands 

XCreateAssocTable, XDeleteAssoc, XLookUpAssoc, XMakeAssoc. 



Xlib Reference Manual 133 



XDestroylmage \ x,,b-,ma ge s- 

Name 

XDestroylmage deallocate memory associated with an image. 

Synopsis 

int XDestroylmage (ximage) 
Xlmage * ximage; 

Arguments 

ximage Specifies a pointer to the image. 

Description 

XDestroylmage deallocates the memory associated with an Ximage structure. This mem 
ory includes both the memory holding the ximage structure, and the memory holding the 
actual image data. (If the image data is statically allocated, the pointer to the data in the 
Ximage structure must be set to zero before calling XDestroylmage.) 

For more information on images, see Volume One, Chapter 6, Drawing Graphics and Text. 
Related Commands 

ImageByteOrder, XAddPixel, XCreatelmage, XGet Image, XGetPixel, XGet- 
Sublmage, XPut Image, XPutPixel, XSub Image. 



134 Xlib Reference Manual 



-x,, b - Regions / XDestroyRegion 

Name 

XDestroyRegion deallocate storage associated with a region. 

Synopsis 

XDestroyRegion ( r) 
Region r; 

Arguments 

r Specifies the region to be destroyed. 

Description 

XDestroyRegion frees the memory associated with a region and invalidates pointer r. 

See Volume One, Chapter 6, Drawing Graphics and Text, for a description of regions. 



Related Commands 

XClipBox, XCreateRegion, XEmptyRegion, XEqualRegion, Xlntersect- 
Region, XOf f setRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion, 
XSetRegion, XShrinkRegion, XSubtractRegion, XUnionRectWithRegion, 
XUnionRegion, XXorRegion. 



Xlib Reference Manual 135 



XDestroySubwindows 



Xlib - Window Existence 



Name 

XDestroySubwindows destroy all subwindows of a window. 

Synopsis 

XDestroySubwindows ( display, w) 
Display * display ; 
Window w; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

w Specifies the ID of the window whose subwindows are to be destroyed. 

Description 

This function destroys all descendants of the specified window (recursively), in bottom to top 
stacking order. 

XDestroySubwindows generates exposure events on window /, if any mapped subwindows 
were actually destroyed. This is much more efficient than deleting many subwindows one at a 
time, since much of the work need only be performed once for all of the windows rather than 
for each window. It also saves multiple exposure events on the windows about to be destroyed. 
The subwindows should never again be referenced. 

xcioseDisplay automatically destroys all windows that have been created by that client on 
the specified display (unless called after a fork system call). 

Never call XDestroySubwindows with the window argument set to the root window! This 
will destroy all the applications on the screen, and if there is only one screen, often the server 
as well. 

Errors 

BadWindow 

Related Commands 

XCreateSimpleWindow, XCreateWindow, XDestroyWindow. 



136 Xlib Reference Manual 



Xlib - Window Existence- 



J XDestroyWindow 



Name 

XDestroyWindow unmap and destroy a window and all subwindows. 

Synopsis 

XDestroyWindow ( display, window) 
Display *display; 
Window window; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

window Specifies the ID of the window to be destroyed. 

Description 

If window is mapped, an UnmapWindow request is performed automatically. The window 
and all inferiors (recursively) are then destroyed, and a DestroyNotif y event is generated 
for each window. The ordering of the DestroyNotif y events is such that for any given win 
dow, DestroyNotif y is generated on all inferiors of the window before being generated on 
the window itself. The ordering among siblings and across subhierarchies is not otherwise con 
strained. 

The windows should never again be referenced. 

Destroying a mapped window will generate exposure events on other windows that were 
obscured by the windows being destroyed. XDestroyWindow may also generate Enter- 
Notify events if window was mapped and contained the pointer. 

No windows are destroyed if you try to destroy the root window. 

Errors 

BadWindow 

Related Commands 

XCreateSimpleWindow, XCreateWindow, XDestroySubwindows. 



Xlib Reference Manual 137 



XDisableAccessControl \ X||b _ Host Accass _ 

Name 

XDisableAccessControl allow access from any host. 

Synopsis 

XDisableAccessControl (display) 
Display * display; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

Description 

XDisableAccessControl instructs the server to allow access from clients on any host. 
This disables use of the host access list. 

This routine can only be called from a client running on the same host as the server. 

For more information on access control, see Volume One, Chapter 13, Other Programming 
Techniques. 

Errors 

BadAccess 

Related Commands 

XAddHost, XAddHosts, XEnableAccessControl, XListHosts, XRemoveHost, 
XRemoveHosts, XSetAccessControl. 



138 Xlib Reference Manual 



Xlib - Window Manager Hints- 



XDisplayKeycodes 



Name 

XDisplayKeycodes obtain the range of legal keycodes for a server. 

Synopsis 

XDisplayKeycodes (display, min_keycodes , max_keycodes) 
Display *display; 
int *min_keycode r *max_keycode; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

min_keycode Returns the minimum keycode. 
max_keycode Returns the maximum keycode. 

Description 

XDisplayKeycodes returns the min_keycode and max_keycode supported by the 
specified server. The minimum keycode returned is never less than 8, and the maximum key- 
code returned is never greater than 255. Not all keycodes in this range are required to have cor 
responding keys. 

For more information, see Volume One, Chapter 9, The Keyboard and Pointer. 
Related Commands 

XKeycodeToKeysym, XKeysymToKeycode, XLookupString. 



Xlib Reference Manual 139 



XDisplayName \ 



Xlib- Error Handling- 



Name 

XDisplayName report the display name (when connection to a display fails). 

Synopsis 

char *XDisplayName ( string) 
char *string; 

Arguments 

string Specifies the character string. 

Description 

XDisplayName is normally used to report the name of the display the program attempted to 
open with xopenDisplay. This is necessary because X error handling begins only after the 
connection to the server succeeds. If a NULL string is specified, XDisplayName looks in the 
DISPLAY environment variable and returns the display name that the user was requesting. 
Otherwise, XDisplayName returns its own argument. This makes it easier to report to the 
user precisely which server the program attempted to connect to. 

For more information, see Volume One, Chapter 3, Basic Window Program. 
Related Commands 

XGetErrorDatabaseText, XGetErrorText, XSetAf terFunction, XSetError- 
Handler, XSetlOErrorHandler, XSynchronize. 



140 Xlib Reference Manual 



Xlib - Drawing Primitives 

Name 

XDraw draw a polyline or curve between vertex list (from XI ) . 
Synopsis 

Status XDraw ( display, drawable, gc f vllst, vcount) 
Display *dlsplay; 
Drawable drawable; 
GC gc; 

Vertex *vllst; 
int vcount ; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

drawable Specifies the drawable. 

gc Specifies the graphics context. 

vllst Specifies a pointer to the list of vertices that indicates what to draw. 

vcount Specifies how many vertices are in vllst. 

Description 

This function is provided for compatibility with X Version 10. To use it you must include the 
file <Xll/X10.h> and link with the library -loldX. Its performance is likely to be low. 

XDraw draws an arbitrary polygon or curve. The figure drawn is defined by the specified list of 
vertices (vllst). The points are connected by lines as specified in the flags each the Vertex 
structure. 

The Vertex structure contains an x,y coordinate and a bitmask called flags that specifies 
the drawing parameters. 

The x and y elements of Vertex are the coordinates of the vertex that are relative to either the 
previous vertex (if VertexRelative is 1) or the upper-left inside corner of the drawable (if 
VertexRelative is 0). If VertexRelative is the coordinates are said to be absolute. 
The first vertex must be an absolute vertex. 

If the VertexDontDraw bit is 1, no line or curve is drawn from the previous vertex to this 
one. This is analogous to picking up the pen and moving to another place before drawing 
another line. 

If the VertexCurved bit is 1, a spline algorithm is used to draw a smooth curve from the pre 
vious vertex, through this one, to the next vertex. Otherwise, a straight line is drawn from the 
previous vertex to this one. It makes sense to set VertexCurved to 1 only if a previous and 
next vertex are both defined (either explicitly in the array, or through the definition of a closed 
curve see below.) 

It is permissible for VertexDontDraw bits and VertexCurved bits to both be 1. This is 
useful if you want to define the previous point for the smooth curve, but you do not want an 
actual curve drawing to start until this point. 



Xlib Reference Manual 14 1 



XDraw (continued) Xlib - Drawing Primitives 

If VertexStartClosed bit is 1, then this point marks the beginning of a closed curve. This 
vertex must be followed later in the array by another vertex whose absolute coordinates are 
identical and which has VertexEndClosed bit of 1. The points in between form a cycle for 
the purpose of determining predecessor and successor vertices for the spline algorithm. 

XDraw achieves the effects of the X10 XDraw, XDrawDashed, and XDrawPatterned 
functions. 

XDraw uses the following graphics context components: function, plane_mask, 
line_width, line_style, cap_style, join_style, fill_style, subwindow_ 
mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses 
these graphics context mode-dependent components: foreground, background, tile, 
stipple, ts_x_origin, ts_y_origin, dash_of f set, and dash_list. 

A Status of zero is returned on failure, and nonzero on success. 

For more information, see Volume One, Appendix B, XI Compatibility. 

Structures 

typedef struct _Vertex { 

short x,y; 

unsigned short flags; 
} Vertex; 

/* defined constants for use as flags */ 

#define VertexRelative 0x0001 /* else absolute */ 

#define VertexDontDraw 0x0002 /* else draw */ 

#define VertexCurved 0x0004 /* else straight */ 

#define VertexStartClosed 0x0008 /* else not */ 

#define VertexEndClosed 0x0010 /* else not */ 

Related Commands 

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDrawArc, XDrawArcs, 
XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDraw- 
Rectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFill- 
Polygon, XFillRectangle, XFillRectangles. 



Xlib Reference Manual 



. . J XDrawArc 

Xlib - Drawing Primitives * 

Name 

XDrawArc draw an arc fitting inside a rectangle. 

Synopsis 

XDrawArc (display, drawable, gc , x f y, width, height, 

anglel , angle2) 
Display *display; 
Drawable drawable ; 
GC gc; 
int x r y; 

unsigned int width, height; 
int anglel, angle2 ; 

Arguments 

display Specifies a connection to an X server; returned from xopenoi splay. 

drawa&le Specifies the drawable. 

gc Specifies the graphics context. 

x Specify the x and y coordinates of the upper-left corner of the rectangle that 

y contains the arc, relative to the origin of the specified drawable. 

width Specify the width and height in pixels of the major and minor axes of the arc. 

height 

anglel Specifies the start of the arc relative to the three-o clock position from the 

center. Angles are specified in 64ths of a degree (360 * 64 is a complete 
circle). 

angle2 Specifies the end of the arc relative to the start of the arc. Angles are speci 

fied in 64ths of a degree (360 * 64 is a complete circle). 

Description 

XDrawArc draws a circular or elliptical arc. An arc is specified by a rectangle and two angles. 
The x and y coordinates are relative to the origin of the drawable, and define the upper-left cor 
ner of the rectangle. 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, respectively. The angles are 
signed integers in 64ths of a degree, with positive values indicating counterclockwise motion 
and negative values indicating clockwise motion, truncated to a maximum of 360 degrees. The 
start of the arc is specified by anglel relative to the three-o clock position from the center, 
and the path and extent of the arc is specified by angle2 relative to the start of the arc. 

By specifying one axis to be zero, a horizontal or vertical line is drawn (inefficiently). 

Angles are computed based solely on the coordinate system and ignore the aspect ratio. In 
other words, if the bounding rectangle of the arc is not square and anglel is zero and 
angle2 is (45x64), a point drawn from the center of the bounding box through the endpoint 
of the arc will not pass through the corner of the rectangle. 



Xlib Reference Manual 143 



XDrawArc 



(continued) 



Xlib - Drawing Primitives 



For any given arc, no pixel is drawn more than once, even if angle2 is greater than anglel 
by more than 360 degrees. 

XDrawArc uses these graphics context components: function, plane_mask, 
line_width, line_style, cap_style, join_style, f ill_style, subwindow_ 
mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses 
these graphics context mode-dependent components: foreground, background, tile, 
stipple, ts_x_origin, ts_y_origin, dash_of f set, and dash_list. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, 



width 



6 o clock 

Angle = 270x64=17280 
Angle = -( 90x64 ) =5760 



12 o clock 


(x,y) v Angle = 90x64 


\ Angle = - (270x64) 






X -4(<A2 


A1 r "**--. % 


. 














/ 


en 


9 o clock 




/ } 






0) 

. 


Angle = 180x64 


__,- 






Angle = - (180x64) 




/ 






,. K^_ 


81 ,-- 



Center of bounding 
rectangle. 

3 o clock 

Angle = 



Example 1: 

Arc from A1 to A2, Counterclockwise 

A1 = 90 X 64 

A2 = 45 X 64 



Example 2: 

Arc from B1 to B2, Clockwise 

B1 = 270 X 64 

B2 = -(45X64) 



Errors 

BadDrawable 

BadGC 

BadMatch 



144 



Xlib Reference Manual 



Xlib - Drawing Primitives (continued) XDrawArc 

Related Commands 

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArcs, 
XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDraw- 
Rectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFill- 
Polygon, XFillRectangle, XFillRectangles. 



Xlib Reference Manual 145 



XDrawArcs 



X 



Xlib - Drawing Primitives- 



Name 

XDrawArcs draw multiple arcs. 

Synopsis 

XDrawArcs ( display, drawable , 
Display * display ; 
Drawable drawable; 
GC gc; 
XArc *arcs; 
int r>arcs; 



gc, arcs, narcs) 



Arguments 

di spl ay 

drawable 

gc 

arcs 

narcs 



Specifies a connection to an X server; returned from XOpenDisplay. 
Specifies the drawable. 
Specifies the graphics context. 
Specifies a pointer to an array of arcs. 
Specifies the number of arcs in the array. 



width 



6 o clock 

Angle = 270x64=17280 
Angle = - (90x64)=5760 



Example 1 : 

Arc from A1 to A2, Counterclockwise 

A1 = 90 X 64 

A2 = 45 X 64 





12 o clock 


(x,y) v Angle = 90x64 
\ Angle = -(270x64) 


height 


9 o clock 

Angle = 180x64 
Angle = -(180x64) 



*^Jf 2 


A1 "" *--,, 




, 









^ s """*-- - -. 


81 



Center of bounding 
rectangle. 

3 o clock 

Angle = 



Example 2: 

Arc from 81 to B2, Clockwise 

B1 = 270 X 64 

B2 = -(45X64) 



146 



Xlib Reference Manual 



Xlib - Drawing Primitives (continued) XDrawArcs 

Description 

This is the plural version of XDrawArc. See XDrawArc for details of drawing a single arc. 

There is a limit to the number of arcs that can be drawn in a single call. It varies according to 
the server. To determine how many arcs you can draw in a single call, find out your server s 
maximum request size using XMaxRequestSize. Subtract 3 and divide by three: this is the 
maximum number of arcs you can draw in a single XDrawArcs call. 

The arcs are drawn in the order listed in the arcs array. 

By specifying one axis to be zero, a horizontal or vertical line can be drawn. Angles are com 
puted based solely on the coordinate system, ignoring the aspect ratio. 

For any given arc, no pixel is drawn more than once. 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. If two arcs join 
correctly and if line_width is greater than and the arcs intersect, no pixel is drawn more 
than once. Otherwise, the intersecting pixels of intersecting arcs are drawn multiple times. 
Specifying an arc with one endpoint and a clockwise extent draws the same pixels as specifying 
the other endpoint and an equivalent counterclockwise extent, except as it affects joins. 

XDrawArcs uses these graphics context components: function, plane_mask, 
line_width, line_style, cap_style, join_style, fill_style, subwindow_ 
mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses 
these graphics context mode-dependent components: foreground, background, tile, 
stipple, ts_x_origin, ts_y_origin, dash_of f set, and dash_list. 

The following is a technical explanation of the points drawn by XDrawArcs. For an arc speci 
fied as [x, y, width, height, anglel, angle2 ] , the origin of the major and minor axes is 
at [x+ (width/2 ) , y+ (height 12 ) ] , and the infinitely thin path describing the entire circle 
or ellipse intersects the horizontal axis at [x, y+ (height /2) ] and [x+width, 
y+ (height/2) ] and intersects the vertical axis at [x+ (width/2) ,y] and 
[x+ (width/2) , y+height] . These coordinates can be fractional. That is, they are not 
truncated to discrete coordinates. The path should be defined by the ideal mathematical path. 
For a wide line with line width line_width, the bounding outlines for filling are given by 
the infinitely thin paths describing the arcs: 

[x+dx/2, y+dy/2, width-dx, height-dy, anglel, angle2] 

and 

[x-line_width/2, y-line_width/2, width+line_width, height+line_width, 
anglel, angle2] 



where 



dx=min(line_width, width) 
dy=min(line width, height) 



Xlib Reference Manual 147 



XDraw Arcs (continued) Xlib - Drawing Primitives 

If (height ! = width) 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 rela 
tionship 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/height) + adjust 

The skewed-angle and normal-angle are expressed in radians (rather than in 64ths of a degree) 
in the range [0,2*PI], and where atan returns a value in the range [-PI/2, PI/2] ,and 
where adjust is: 

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 more information, see Volume One, Chapter 6, Drawing Graphics and Text. 
Structures 

typedef struct { 

short x, y; 

unsigned short width, height; 

short anglel, angle2; /* Start and end of arc, in */ 

/* 64ths of degrees */ 
} XArc; 

Errors 

BadDrawable 

BadGC 

BadMatch 

Related Commands 

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc, 
XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDraw- 
Rectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFill- 
Polygon, XFillRectangle, XFillRectangles. 



148 Xlib Reference Manual 



-Xlib - Drawing Primmv.s / XDrawFilted 

Name 

XDrawFilled draw a filled polygon or curve from vertex list (from X10 ) . 

Synopsis 

Status XDrawFilled (display, drawable, gc, vlist, vcount) 
Display *display; 
Drawable drawable ; 
GC gc; 

Vertex *vlist; 
int vcount ; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

dra wabl e Specifies the drawable. 

gc Specifies the graphics context. 

vl i s t Specifies a pointer to the list of vertices. 

vcount Specifies how many vertices are in v 1 i s t . 

Description 

This function is provided for compatibility with X Version 10. To use it you must include the 
file <XlllX10.h> and link with the library -loldX. XDrawFilled achieves the effects of the 
X Version 10 XDrawTiled and XDrawFilled functions. 

XDrawFilled draws arbitrary polygons or curves, according to the same rules as XDraw, and 
then fills them. 

XDrawFilled uses the following graphics context components: function, plane_mask, 
line_width, line_style, cap_style, join_style, fill_style, 
subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function 
also uses these graphics context mode-dependent components: foreground, background, 
tile, stipple, ts_x_origin, ts_y_origin, dash_offset, dash_list, 
f ill_style and f ill_rule. 

XDrawFilled returns a Status of zero on failure, and nonzero on success. 
For more information, see Volume One, Appendix B,X10 Compatibility. 

Related Commands 

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc, 
XDrawArcs, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDraw- 
Rectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFill- 
Polygon, XFillRectangle, XFillRectangles. 



Xlib Reference Manual 149 



XDrawlmageString \ 



Xlib- Text- 



Name 

XDrawlmageString draw 8-bit image text characters. 

Synopsis 

XDrawlmageString ( display, drawable , gc , x, y, string, length) 
Display *display; 
Drawable drawable ; 
GC gc; 
int x f y; 
char *string; 
int length; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

drawable Specifies the drawable. 

gc Specifies the graphics context. 

x Specify the x and y coordinates of the baseline starting position for the image 

y text character, relative to the origin of the specified drawable. 

string Specifies the character string. 

length Specifies the number of characters in the s t ri n g argument. 

Description 

XDrawlmageString draws a string, but unlike XDrawString it draws both the foreground 
and the background of the characters. It draws the characters in the foreground and fills the 
bounding box with the background. 

XDrawlmageString uses these graphics context components: plane_mask, fore 
ground, background, font, subwindow_mode, clip_x_origin, clip_y_ 
origin, and clip_mask. The function and f ill_style defined in gc are ignored; 
the effective function is GXcopy and the effective f ill_style is FillSolid. 

XDrawlmageString first fills a destination rectangle with the background pixel defined 
in gc, and then paints the text with the foreground pixel. The upper-left corner of the filled 
rectangle is at [x, y - font_ascent], the width is overall->width and the height is 
ascent + descent, where overall->width, ascent, and descent are as would be 
returned by XQueryTextExtents using gc and string. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, 
The Graphics Context. 

Errors 

BadDrawable 

BadGC 

BadMatch 



150 Xlib Reference Manual 



xiib - Text (continued) XDrawlmageString 

Related Commands 

XDrawImageStringlS, XDrawString, XDrawStringl6, XDrawText, XDraw- 
Textl6, XQueryTextExtents, XQueryTextExtentsl6, XTextExtents, XText- 
Extentsl6,XTextWidth,XTextWidthl6. 



Xlib Reference Manual 151 



XDrawlmageStri ng1 6 \ 



Xlib-Text 



Name 

XDrawImageStringl6 draw 16-bit image text characters. 

Synopsis 

XDrawImageStringl 6 (display, drawable, gc , x, y, string, length) 
Display * display; 
Drawable drawable; 
GC gc; 
int x r y; 
XChar2b *string; 
int length; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

drawable Specifies the drawable. 

gc Specifies the graphics context. 

x Specify the x and y coordinates of the baseline starting position for the image 

y text character, relative to the origin of the specified drawable. 

string Specifies the character string. 

length Specifies the number of characters in the string argument. 

Description 

XDrawlmageStringl6 draws a string, but unlike XDrawStringl6 it draws both the fore 
ground and the background of the characters. It draws the characters in the foreground and fills 
the bounding box with the background. 

XDrawlmageStringl6 uses these graphics context components: plane_mask, fore 
ground, background, font, subwindow_mode, clip_x_origin, clip_y_ 
origin, and clip_mask. The function and f ill_style defined in gc are ignored; 
the effective function is GXcopy and the effective f ill_style is FillSolid. 

XDrawlmageStringlG first fills a destination rectangle with the background pixel 
defined in gc, and then paints the text with the foreground pixel. The upper-left corner of 
the filled rectangle is at [x, y - font_ascent], the width is overall->width and the 
height is ascent + descent, where overall->width, ascent, and descent are as 
would be returned by XQueryTextExtentslG using gc and string. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, 
The Graphics Context. 

Structures 

typedef struct { 

unsigned char bytel; 

unsigned char byte2; 
} XChar2b; 



152 Xlib Reference Manual 



- Text (continued) XDrawlmageStringl 6 



Errors 

BadDrawable 

BadGC 

BadMatch 



Related Commands 

XDrawImageString,XDrawString,XDrawStringl6,XDrawText,XDrawTextl6 : 

XQueryTextExtents,XQueryTextExtentsl6,XTextExtents,XText- 

Extentsl6,XTextWidth,XTextWidthl6. 



Xlib Reference Manual 153 



XDrawLine \ _ Xllb _ Drawlng Pr|m|tives _ 

Name 

XDrawLine draw a line between two points. 

Synopsis 

XDrawLine ( display, drawable, gc, xl , yl , x2 , y2) 
Display * display; 
Drawable dravrable; 
GC gc; 
int xl r yl r x2, y2 ; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

dra wabl e Specifies the drawable. 

gc Specifies the graphics context. 

xl Specify the coordinates of the endpoints of the line relative to the drawable 

yl origin. XLine connects point (xl , yl) to point (x2, y2). 

x2 



Description 

XDrawLine uses the components of the specified graphics context to draw a line between two 
points in the specified drawable. No pixel is drawn more than once. 

XDrawLine uses these graphics context components: function, plane_mask, 
line_width, line_style, cap_style, fill_style, subwindow_mode, clip_ 
x_origin, clip_y_origin, and clip_mask. XDrawLine also uses these graphics con 
text mode-dependent components: foreground, background, tile, stipple, 
ts_x_origin, ts_y_origin, dash_of f set, and dash_list. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, 
The Graphics Context. 

Errors 

BadDrawable Specified drawable is invalid. 

BadGC Specified GC is invalid, or does not match the depth of drawable. 

BadMatch Specified drawable is an inputOnly window. 

Related Commands 

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc, 
XDrawArcs, XDrawFilled, XDrawLines, XDrawPoint, XDrawPoints, XDraw- 
Rectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFill- 
Polygon, XFillRectangle, XFillRectangles. 



154 Xlib Reference Manual 



-X..b - Drawing Primitives - / 



Name 

XDrawLines draw multiple connected lines. 

Synopsis 

XDrawLines ( display, drawable, gc , points, npoints, mode) 
Display *display; 
Drawable drawable; 
GC gc; 

XPoint *points; 
int npoints; 
int mode ; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

drawable Specifies the drawable. 

gc Specifies the graphics context. 

point s Specifies a pointer to an array of points. 

npoints Specifies the number of points in the array. 

mode Specifies the coordinate mode. Pass either CoordModeOrigin or Coord- 

ModePrevious. 

Description 

XDrawLines draws a series of lines joined end-to-end. 

It draws lines connecting each point in the list (points array) to the next point in the list. The 
lines are drawn in the order listed in the points array. For any given line, no pixel is drawn 
more than once. If thin (zero line width) lines intersect, pixels will be drawn multiple times. If 
the first and last points coincide, the first and last lines will join correctly. If wide lines inter 
sect, the intersecting pixels are drawn only once, as though the entire multiline request were a 
single filled shape. 

There is a limit to the number of lines that can be drawn in a single call, that varies according to 
the server. To determine how many lines you can draw in a single call, you find out your 
server s maximum request size using XMaxRequestSize. Subtract 3 and divide by two, and 
this is the maximum number of lines you can draw in a single XDrawLines call. 

The mode argument may have two values: 

CoordModeOrigin indicates that all points are relative to the drawable s origin. 

CoordModePrevious indicates that all points after the first are relative to the previ 
ous point. (The first point is always relative to the drawable s origin.) 

XDrawLines uses the following components of the specified graphics context to draw multi 
ple connected lines in the specified drawable: function, plane_mask, line_width, 
line_style, cap_style, join_style, fill_style, subwindow_mode, 



Xlib Reference Manual 155 



XDrawLlnes (continued) Xlib - Drawing Primitives 

clip_x_origin, clip_y_ origin, and clip_mask. This function also uses these 
graphics context mode-dependent components: foreground, background, tile, 
stipple, ts_x_origin, ts_y_origin, dash_of f set, and dash_list. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, 
The Graphics Context. 

Structures 

typedef struct { 
short x, y; 
} XPoint; 

Errors 

BadDrawable Specified drawable is invalid. 

BadGC Specified GC is invalid, or does not match the depth of drawable. 

BadMatch Specified drawable is an InputOnly window. 
BadValue Invalid coordinate_mode. 

Related Commands 

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc, 
XDrawArcs, XDrawFilled, XDrawLine, XDrawPoint, XDrawPoints, XDraw- 
Rectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFill- 
Polygon, XFillRectangle, XFillRectangles. 



156 Xlib Reference Manual 



-X,,b - Drawing Primitives / XDrawPoint 

Name 

XDrawPoint draw a point. 

Synopsis 

XDrawPoint ( display, drawable, gc , x r y) 
Display *display; 
Drawable drawable; 
GC gc; 
int x r y; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

drawable Specifies the drawable. 

gc Specifies the graphics context. 

x Specify the x and y coordinates of the point, relative to the origin of the draw- 

y able. 

Description 

XDrawPoint draws a single point into the specified drawable. XDrawPoint uses these 
graphics context components: function, plane_mask, foreground, subwin- 
dow_mode, clip_x_origin, clip_y_origin, and clip_mask. Use XDrawPoints 
to draw multiple points. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, 
The Graphics Context. 

Errors 

BadDrawable 

BadGC 

BadMatch 

Related Commands 

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc, 
XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoints, XDraw- 
Rectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFill- 
Polygon, XFillRectangle, XFillRectangles. 



Xlib Reference Manual 157 



XDrawPoints \ Xllb _ Drawing Pr|m|tives _ 

Name 

XDrawPoints draw multiple points. 

Synopsis 

XDrawPoints ( display, drawable, gc , points, npoints, mode) 
Display ^display; 
Drawable drawable; 
GC gc; 

XPoint *points; 
int npoints; 
int mode ; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

dra wabl e Specifies the drawable. 

gc Specifies the graphics context. 

points Specifies a pointer to an array of XPoint structures containing the positions 

of the points. 

npoints Specifies the number of points to be drawn. 

mode Specifies the coordinate mode. CoordModeOrigin treats all coordinates as 

relative to the origin, while CoordModePrevious treats all coordinates 
after the first as relative to the previous point, while the first is still relative to 
the origin. 

Description 

XDrawPoints draws one or more points into the specified drawable. 

There is a limit to the number of points that can be drawn in a single call, that varies according 
to the server. To determine how many points you can draw in a single call, you find out your 
server s maximum request size using XMaxRequestSize. Subtract 3 and this is the maxi 
mum number of points you can draw in a single XDrawPoints call. 

XDrawPoints uses these graphics context components: function, plane_mask, fore 
ground, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, 
The Graphics Context. 

Structures 

typedef struct { 
short x, y; 
} XPoint; 



758 Xlib Reference Manual 



Xlib - Drawing Primitives (continued) XDrawPointS 

Errors 

BadDrawable 
BadGC 
BadMatch 
BadValue 

Related Commands 

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc, 
XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPointS, XDraw- 
Rectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFill- 
Polygon, XFillRectangle, XFillRectangles. 



Xlib Reference Manual 159 



XDrawRectangle 



X 



Xllb - Drawing Primitives 



Name 

XDrawRectangle draw an outline of a rectangle. 

Synopsis 

XDrawRectangle (display, drawable, gc, x, y, width, height) 
Display * display; 
Drawable drawable; 
GC gc; 
int x r y; 
unsigned int width, height; 



Arguments 

di spl ay 

drawable 

gc 

x 

y 

width 
height 



Specifies a connection to an X server; returned from XOpenDisplay. 
Specifies the drawable. 
Specifies the graphics context. 

Specify the x and y coordinates of the upper-left corner of the rectangle, rela 
tive to the drawable s origin. 

Specify the width and height in pixels. These dimensions define the outline 
of the rectangle. 



20 pixels 



20 pixels 



Description 

XDrawRectangle draws the outline of the rectangle by using the x and y coordinates, 
width and height, and graphics context you specify. Specifically, XDrawRectangle uses 
these graphics context components: function, plane_mask, line_width, 
line_style, cap_style, join_style, fill_style, subwindow_mode, clip_ 
x_origin, clip_y_origin, and clip_mask. This function also uses these graphics con 
text mode-dependent components: foreground, background, tile, stipple, 
ts_x_origin, ts_y_origin, dash_of f set, and dash_list. 

For the specified rectangle, no pixel is drawn more than once. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, 
The Graphics Context. 



160 



Xlib Reference Manual 



Xlib - Drawing Primitives (continued) X Draw Rectangle 

Structure 

typedef struct { 

short x, y; 

unsigned short width, height; 
} XRectangle; 

Errors 

BadDrawable 

BadGC 

BadMatch 

Related Commands 

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc, 
XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, 
XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFillPolygon, 
XFillRectangle, XFillRectangles. 



Xlib Reference Manual 16 1 



XDrawRectangles 



X 



Xlib - Drawing Primitives- 



Name 

XDrawRectangles draw the outlines of multiple rectangles. 

Synopsis 

XDrawRectangles (display, drawable, gc , rectangles, nrectangles) 
Display *display; 
Drawable drawa≤ 
GC gc; 

XRectangle rectangles [] ; 
int nrectangles; 

Arguments 

di spl ay Specifies a connection to an X server; returned from xopenD isplay. 

dra wabl e Specifies the drawable. 

gc Specifies the graphics context. 

rectangles Specifies a pointer to an array of rectangles containing position and size 
information. 

nrectangles Specifies the number of rectangles in the array. 

20 pixels 






Description 

XDrawRectangles draws the outlines of the specified rectangles by using the position and 
size values in the array of rectangles. The x and y coordinates of each rectangle are relative to 
the drawable s origin, and define the upper-left corner of the rectangle. 

The rectangles are drawn in the order listed. For any given rectangle, no pixel is drawn more 
than once. If rectangles intersect, pixels are drawn multiple times. 

There is a limit to the number of rectangles that can be drawn in a single call. It varies accord 
ing to the server. To determine how many rectangles you can draw in a single call, find out 
your server s maximum request size using XMaxRequestSize. Subtract 3 and divide by 
two. This is the maximum number of rectangles you can draw in a single XDraw 
Rectangles call. 

This function uses these graphics context components: function, plane_mask, 
line_width, line_style, cap_style, join_style, fill_style, subwin- 
dow_mode, clip_x_origin, clip_y_origin, and clip_mask. XDrawRectangles 



162 



Xlib Reference Manual 



Xlib - Drawing Primitives (continued) XDrawRectangles 

also uses these graphics context mode-dependent components: foreground, background, 
tile, stipple, ts_x_origin, ts_y_origin, dash_of f set, and dash_list. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, 
The Graphics Context. 

Structures 

typedef struct { 

short x, y; 

unsigned short width, height; 
} XRectangle; 

Errors 

BadDrawable 

BadGC 

BadMatch 

Related Commands 

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc, 
XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, 
XDrawRectangle, XDrawSegments, XFillArc, XFillArcs, XFillPolygon, 
XFillRectangle, XFillRectangles. 



Xlib Reference Manual 163 



XDrawSegments \ 



Xlib - Drawing Primitives- 



Name 

XDrawSegments draw multiple disjoint lines. 

Synopsis 

XDrawSegments ( display, drawable, gc, segments, nsegments) 
Display *display; 
Drawable drawable; 
GC gc; 

XSegment * segments; 
int nsegments; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

drawable Specifies the drawable. 

gc Specifies the graphics context. 

segments Specifies a pointer to an array of line segments. 

nse gmen ts Specifies the number of segments in the array. 

Description 

XDrawSegments draws multiple line segments into the specified drawable. Each line is 
specified by a pair of points, so the line may be connected or disjoint. 

For each segment, XDrawSegments draws a line between (xl, yl) and (x2, y2). The 
lines are drawn in the order listed in segments. For any given line, no pixel is drawn more 
than once. If lines intersect, pixels will be drawn multiple times. The lines will be drawn sepa 
rately, without regard to the join_style. 

There is a limit to the number of segments that can be drawn in a single call. It varies accord 
ing to the server. To determine how many segments you can draw in a single call, find out your 
server s maximum request size using XMaxRequestSize. Subtract 3 and divide by two. 
This is the maximum number of segments you can draw in a single XDrawSegments call. 

XDrawSegments uses these graphics context components: function, plane_mask, 
line_width, line_style, cap_style, fill_style, subwindow__mode, clip_ 
x_origin, clip_y_origin, and clip_mask. XDrawSegments also uses these graph 
ics context mode-dependent components: foreground, background, tile, stipple, 
ts_x_origin, ts_y_origin, dash_of f set, and dash_list. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, 
The Graphics Context. 

Structures 

typedef struct { 

short xl, yl, x2, y2; 
} XSegment; 



164 Xlib Reference Manual 



Xlib - Drawing Primitives (continued) XDrawSegmentS 

Errors 

BadDrawable Specified drawable is invalid. 

BadGC Specified GC is invalid, or does not match the depth of drawable. 

BadMatch Specified drawable is an InputOnly window. 

Related Commands 

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc, 
XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, 
XDrawRectangle, XDrawRectangles, XFillArc, XFillArcs, XFillPolygon, 
XFillRectangle, XFillRectangles. 



Xlib Reference Manual 165 



XDrawString \ 



Xlib-Text 



Name 

XDrawString draw an 8-bit text string, foreground only. 

Synopsis 

XDrawString ( display, drawable , gc , x, y, string, length) 
Display *display; 
Drawable drawable ; 
GC gc; 
int x, y; 
char *string; 
int length; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

dr a wai>l e Specifies the drawable. 

gc Specifies the graphics context. 

x Specify the x and y coordinates of the baseline starting position for the char- 

y acter, relative to the origin of the specified drawable. 

string Specifies the character string. 

length Specifies the number of characters in s t ri n g. 

Description 

XDrawString draws the given string into a drawable using the foreground only to draw 
set bits in the font. It does not affect any other pixels in the bounding box for each character. 

The y coordinate defines the baseline row of pixels while the x coordinate is the point from 
which Ibearing, rbearing, and width are measured. 

XDrawString uses these graphics context components: function, plane_mask, 
fill_style, font, subwindow_mode, clip_x_origin, clip_y_origin, and 
clip_mask. This function also uses these graphics context mode-dependent components: 
foreground, tile, stipple, ts_x_origin, and ts_y_origin. Each character 
image, as defined by the font in gc, is treated as an additional mask for a fill operation on the 
drawable. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, 
The Graphics Context. 

Errors 

BadDrawable 
BadFont 
BadGC 
BadMatch 



166 Xlib Reference Manual 



Xiib-Text (continued) XDrawString 

Related Commands 

XDrawImageString, XDrawImageStringl6, XDrawStringl6, XDrawText, 
XDrawTextl6, XQueryTextExtents, XQueryTextExtentslG, XTextExtents, 
XTextExtentsl6, XTextWidth, XTextWidthlG. 



Xlib Reference Manual 167 



XDrawString16 , xnb _ Text _ 

Name 

XDrawStringl 6 draw two-byte text strings. 

Synopsis 

XDrawStringl 6 (display, drawable, gc , x, y f string, length) 
Display * display; 
Drawable drawable; 
GC gc ; 
int x, y; 
XChar2b *string; 
int length; 

Arguments 

di splay Specifies a connection to an X server; returned from XOpenDisplay. 

draw-able Specifies the drawable. 

gc Specifies the graphics context. 

x Specify the x and y coordinates of the baseline starting position for the char- 

y acter, relative to the origin of the specified drawable. 

string Specifies the character string. Characters are two bytes wide. 

length Specifies the number of characters in string. 

Description 

XDrawStringl 6 draws a string in the foreground pixel value without drawing the surround 
ing pixels. 

The y coordinate defines the baseline row of pixels while the x coordinate is the point from 
which Ibearing, rbearing, and width are measured. For more information on text 
placement, see Volume One, Chapter 6, Drawing Graphics and Text. 

XDrawStringl 6 uses these graphics context components: function, plane_mask, 
fill_style, font, subwindow_mode, clip_x_origin, clip_y_origin, and 
clip_mask. This function also uses these graphics context mode-dependent components: 
foreground, tile, stipple, ts_x_origin, and ts_y_origin. Each character 
image, as defined by the font in gc, is treated as an additional mask for a fill operation on the 
drawable. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, 
The Graphics Context. 

Structures 

typedef struct { 

unsigned char bytel; 

unsigned char byte2; 
} XChar2b; 



Xlib Reference Manual 



Xiib-Text (continued) XDrawString16 

Errors 

BadDrawable 
BadFont 
BadGC 
BadMatch 

Related Commands 

XDrawImageString, XDrawImageStringlG, XDrawString, XDrawText, XDraw- 
Textl6,XQueryTextExtents,XQueryTextExtentsl6,XTextExtents,XText- 
Extentsl6,XTextWidth, XTextWidthl6. 



Xlib Reference Manual 



XDrawText \ X ,ib-Tex- 

Name 

XDrawText draw 8-bit polytext strings. 

Synopsis 

XDrawText ( display, drawable, gc , x, y, Items, nltems) 
Display *dlsplay; 
Drawable drawable; 
GC gc ; 
int x, y; 
XTextltem * Items; 
int nltems; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

drawable Specifies the drawable. 

gc Specifies the graphics context. 

x Specify the x and y coordinates of the baseline starting position for the initial 

y string, relative to the origin of the specified drawable. 

i t ems Specifies a pointer to an array of text items. 

nl terns Specifies the number of text items in the Items array. 

Description 

XDrawText is capable of drawing multiple strings on the same horizontal line and changing 
fonts between strings. Each XTextltem structure contains a string, the number of characters 
in the string, the delta offset from the starting position for the string, and the font. Each text 
item is processed in turn. The font in each XTextltem is stored in the specified GC and used 
for subsequent text. If the XTextltem. font is None, the font in the GC is used for drawing 
and is not changed. Switching between fonts with different drawing directions is permitted. 

The delta in each XTextltem specifies the change in horizontal position before the string is 
drawn. The delta is always added to the character origin and is not dependent on the draw 
direction of the font. For example, if x = 40, y = 20, and items [0] .delta = 8, the 
string specified by items [0] .chars would be drawn starting at x = 48, y = 20. The 
delta for the second string begins at the rbearing of the last character in the first string. A 
negative delta would tend to overlay subsequent strings on the end of the previous string. 

Only the pixels selected in the font are drawn (the background member of the GC is not used 
to fill the bounding box). 

There is a limit to the number and size of strings that can be drawn in a single call, that varies 
according to the server. To determine how much text you can draw in a single call, you find out 
your server s maximum request size using XMaxRequestSize. Subtract four, and then sub 
tract ( (strlen (string) +2) / 4) for each string. This is the maximum amount of 
text you can draw in a single XDrawText call. 



1 70 Xlib Reference Manual 



Xlib-Text (continued) XDrawText 

XDrawText uses the following elements in the specified GC: function, plane_mask, 
fill_style, font, subwindow_mode, clip_x_origin, clip_y_origin, and 
clip_mask. This function also uses these graphics context mode-dependent components: 
foreground, tile, stipple, ts_x_origin, and ts_y_origin. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, 
The Graphics Context. 

Structures 

typedef struct { 

char *chars; /* pointer to string */ 

int nchars; /* number of characters */ 

int delta; /* delta between strings */ 

Font font; /* font to print it in, None don t change */ 

} XTextltem; 

Errors 

BadDrawable 
BadFont 
BadGC 
BadMatch 

Related Commands 

XDrawImageString, XDrawImageStringl6, XDrawString, XDrawStringlS, 
XDrawTextlS, XQueryTextExtents, XQueryTextExtentslS, XTextExtents, 
XTextExtentsl6, XTextWidth, XTextWidthlG. 



Xlib Reference Manual 1 71 



XDrawText16 \ X|ib Tex( _ 

Name 

XDrawTextl6 draw 16-bit poly text strings. 

Synopsis 

XD r a wTextlS ( display, drawable, gc, x, y, items, nitems) 
Display * display ; 
Drawable drawable; 
GC gc; 
int x r y; 

XTextIteml6 * items; 
int nitems; 

Arguments 

display Specifies a connection to an X server; returned from xopenDisplay. 

drawable Specifies the drawable. 

gc Specifies the graphics context. 

x Specify the x and y coordinates of the baseline starting position for the initial 

y string, relative to the origin of the specified drawable. 

items Specifies a pointer to an array of text items using two-byte characters, 

nit ems Specifies the number of text items in the array. 

Description 

XDrawTextlG is capable of drawing multiple strings on the same horizontal line and chang 
ing fonts between strings. Each XTextltem structure contains a string, the number of charac 
ters in the string, the delta offset from the starting position for the string, and the font. Each 
text item is processed in turn. The font in each XTextltem is stored in the specified GC and 
used for subsequent text. If the XTextIteml6 . font is None, the font in the GC is used for 
drawing and is not changed. Switching between fonts with different drawing directions is per 
mitted. 

The delta in each XTextltem specifies the change in horizontal position before the string is 
drawn. The delta is always added to the character origin and is not dependent on the drawing 
direction of the font. For example, if x = 40,y = 20, and items [0] .delta = 8, the 
string specified by items [0] .chars would be drawn starting at x = 48, y = 20. The 
delta for the second string begins at the rbearing of the last character in the first string. A 
negative delta would tend to overlay subsequent strings on the end of the previous string. 

Only the pixels selected in the font are drawn (the background member of the GC is not used 
to fill the bounding box). 

There is a limit to the number and size of strings that can be drawn in a single call, that varies 
according to the server. To determine how much text you can draw in a single call, you find out 
your server s maximum request size using XMaxRequestSize. Subtract four, and then sub 
tract ( (strlen (string) +2) / 4) for each string. This is the maximum amount of 
text you can draw in a single XDrawText 1 6 call. 



1 72 Xlib Reference Manual 



Xlib - Text 



(continued) 



XDrawText16 



XDrawText 16 uses the following elements in the specified GC: function, plane_mask, 
fill_style, font, subwindow_mode, clip_x_origin, clip_y_origin, and 
clip_mask. This function also uses these graphics context mode-dependent components: 
foreground, tile, stipple, ts_x_origin, and ts_y_origin. 

Note that the chars member of the XText Iteml 6 structure is of type XChar2b, rather than 
of type char as it is in the XText Item structure. For fonts defined with linear indexing 
rather than two-byte matrix indexing, the X server will interpret each member of the XChar2b 
structure as a 16-bit number that has been transmitted most significant byte first. In other 
words, the bytel member of the XChar2b structure is taken as the most significant byte. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, 
The Graphics Context. 



/* 2 byte characters */ 

/* number of characters */ 

/* delta between strings */ 

/* font to print it in, None don t change 



/* normal 16 bit characters are two bytes */ 



Structures 

typedef struct { 

XChar2b *chars; 
int nchars; 
int delta; 

Font font; 
} XTextltemlG; 

typedef struct { 

unsigned char bytel; 

unsigned char byte2; 
} XChar2b; 

Errors 

BadDrawable 
BadFont 
BadGC 
BadMatch 



Related Commands 

XDrawImageString, XDrawImageStringl6, XDrawString, XDrawStringl6, 
XDrawText, XQueryTextExtents, XQueryTextExtentsl6, XTextExtents, 
XTextExtentslG, XTextWidth, XTextWidthl6. 



Xlib Reference Manual 



173 



XEmptyRegion \ 



-Xlib- Regions- 



Name 

XEmptyRegion determine if a region is empty. 

Synopsis 

Bool XEmptyRegion ( r) 
Region r; 

Arguments 

r Specifies the region to be checked. 

Description 

XEmptyRegion will return True if the specified region is empty, or False otherwise. 

Structures 

Region is a pointer to an opaque structure type. 

Related Commands 

XClipBox, XCreateRegion, XDestroyRegion, XEqualRegion, Xlntersect- 
Region, XOf f setRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion, 
XSetRegion, XShrinkRegion, XSubtractRegion, XUnionRectWithRegion, 
XUnionRegion, XXorRegion. 



174 Xlib Reference Manual 



-x,,b - HO, Access / XEnableAccessControl 

Name 

XEnableAccessControl use access control list to allow or deny connection requests. 

Synopsis 

XEnableAccessControl (display) 
Display * display ; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

Description 

XEnableAccessControl instructs the server to use the host access list to determine 
whether access should be granted to clients seeking a connection with the server. 

By default, the host access list is used. If access has not been disabled with XDisable- 
AccessControl or XSetAccessControl, this routine does nothing. 

This routine can only be called by clients running on the same host as the server. 
For more information, see Volume One, Chapter 13, Other Programming Techniques. 

Errors 

BadAccess 

Related Commands 

XAddHost, XAddHosts, XDisableAccessControl, XListHosts, XRemoveHost, 
XRemoveHosts, XSetAccessControl. 



Xlib Reference Manual 1 75 



XEqualRegion 

Xlib - Regions- 
Name 

XEqualRegion determine if two regions have the same size, offset, and shape. 

Synopsis 

Bool XEqualRegion (rl, r2) 
Region rl , r2 ; 

Arguments 

rl Specify the two regions you want to compare. 

r2 

Description 

XEqualRegion returns True if the two regions are identical; i.e., they have the same offset, 
size and shape, or False otherwise. 

Regions are located using an offset from a point (the region origin) which is common to all 
regions. It is up to the application to interpret the location of the region relative to a drawable. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text. 

Structures 

Region is a pointer to an opaque structure type. 

Related Commands 

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, Xlntersect- 
Region, XOf f setRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion, 
XSetRegion, XShrinkRegion, XSubtractRegion, XUnionRectWithRegion, 
XUnionRegion, XXorRegion. 



176 Xlib Reference Manual 



-Xlib - Resource Manager / 

Name 

XEventsQueued check the number of events in the event queue. 

Synopsis 

int XEventsQueued ( display, mode) 
Display * display; 
int mode ; 

Arguments 

display Specifies a connection to a Display structure, returned from XOpen- 

Display. 

mode Specifies whether the request buffer is flushed if there are no events in Xlib s 

queue. You can specify one of these constants: QueuedAl ready, 
QueuedAfterFlush, QueuedAfterReading. 

Description 

XEventsQueued checks whether events are queued. If there are events in Xlib s queue, the 
routine returns immediately to the calling routine. Its return value is the number of events 
regardless of mode. 

mode specifies what happens if no events are found on Xlib s queue. 

If mode is QueuedAlready, and there are no events in the queue, XEvents 
Queued returns zero (it does not flush the request buffer or attempt to read more 
events from the connection). 

If mode is QueuedAfterFlush, and there are no events in the queue, XEvents 
Queued flushes the request buffer, attempts to read more events out of the applica 
tion s connection, and returns the number read. 

If mode is QueuedAfterReading, and there are no events in the queue, 
XEventsQueued attempts to read more events out of the application s connection 
without flushing the request buffer and returns the number read. 

Note that XEventsQueued always returns immediately without I/O if there are events 
already in the queue. 

XEventsQueued with mode QueuedAfterFlush is identical in behavior to XPending. 
XEventsQueued with mode QueuedAlready is identical to the QLength macro (see 
Appendix C, Macros). 

For more information, see Volume One, Chapter 8, Events. 
Related Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XGetlnputFocus, 
XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeek- 
If Event, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSetlnput- 
Focus, XSynchronize, XWindowEvent. 



Xlib Reference Manual 1 77 



XFetchBuffer "\ 



Xlib -Cut Buffers 



Name 

XFetchBuffer return data from a cut buffer. 

Synopsis 

char *XFetchBuffer (display, nbytes , buffer) 
Display * display ; 

int * nbytes; /* RETURN */ 
int buffer; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

nbytes Returns the number of bytes in buffer returned by XFetchBuffer. If 

there is no data in the buffer, * nbytes is set to 0. 

buffer Specifies which buffer you want data from. Specify an integer from to 7 

inclusive. 

Description 

XFetchBuffer returns data from one of the 8 buffers provided for interclient communica 
tion. If the buffer contains data, XFetchBuffer returns the number of bytes in nbytes, 
otherwise it returns NULL and sets *nbytes to 0. The appropriate amount of storage is allo 
cated and the pointer returned; the client must free this storage when finished with it by calling 
XFree. Note that the cut buffer does not necessarily contain text, so it may contain embedded 
null bytes and may not terminate with a null byte. 

Selections are preferred over cut buffers as a communication scheme. 

For more information on cut buffers, see Volume One, Chapter 13, Other Programming Tech 
niques. 

Errors 

BadValue buffer not an integer between and 7 inclusive. 

Related Commands 

XFetchBytes, XRotateBuf f ers, XStoreBuf f er, XStoreBytes. 



1 78 Xlib Reference Manual 



Xlib -Cut Buffers- 



J XFetch Bytes 



Name 

XFetchBytes return data from cut buffer 0. 

Synopsis 

char *XFetchBytes ( display, nbytes) 
Display ^display; 
int * nbytes; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

nbytes Returns the number of bytes in the string returned by XFetchBytes. If 

there is no data in the buffer, * nbytes is set to 0. 

Description 

XFetchBytes returns data from cut buffer of the 8 buffers provided for interclient commu 
nication. If the buffer contains data, XFetchBytes returns the number of bytes in nbytes, 
otherwise it returns NULL and sets * nbytes to 0. The appropriate amount of storage is allo 
cated and the pointer returned; the client must free this storage when finished with it by calling 
XFree. Note that the cut buffer does not necessarily contain text, so it may contain embedded 
null bytes and may not terminate with a null byte. 

Use XFetchBuf f er to fetch data from any specified cut buffer. 
Selections are preferred over cut buffers as a communication method. 

For more information on cut buffers, see Volume One, Chapter 13, Other Programming Tech 
niques. 

Related Commands 

XFetchBuf fer, XRotateBuf f ers, XStoreBuf f er, XStoreBytes. 



Xlib Reference Manual 1 79 



XFetChName V xm>-W.ndow Manager Hints- 

Name 

XFetchName get a window s name (XA_WM_NAME property). 

Synopsis 

Status XFetchName ( display, w, window_name) 
Display * display; 
Window w; 
char **window_name; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XQpenDisplay. 

w Specifies the ID of the window whose name you want a pointer set to. 

window_name Returns a pointer to the window name, which will be a null-terminated string. 
If the XA_WM_NAME property has not been set for this window, XFetchName 
sets windowname to NULL. When finished with it, a client can free the name 
string using XFree. 

Description 

XFetchName is superseded by XGetWMName in Release 4. XFetchName returns the current 
value of the XA_WM_NAME property for the specified window. XFetchName returns nonzero if 
it succeeds, and zero if the property has not been set for the argument window. 

For more information, see Volume One, Chapter 10, Interdient Communication, and Chapter 
14, Window Management. 

Errors 

BadWindow 

Related Commands 

XGetClassHint, XGetlconName, XGetlconSizes, XGetNormalHints, XGet- 
SizeHints, XGetTransientForHint, XGetWMHints, XGetZoomHints, XSet- 
ClassHint, XSetCommand, XSetlconName, XSetlconSizes, XSetNormalHints, 
XSetSizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints, 
XStoreName. 



180 Xlib Reference Manual 



-Xllb - Drawing Primitives XFlll Arc 

Name 

XFillArc fill an arc. 

Synopsis 

XFillArc (display, draw-able, gc , x, y, width, height, 

anglel , angle2) 
Display * display ; 
Drawable drawable; 
GC gc; 
int x , y ; 

unsigned int width, height; 
int anglel, angle2 ; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

dra wabl e Specifies the drawable. 

gc Specifies the graphics context. 

x Specify the x and y coordinates of the upper-left corner of the bounding box 

y containing the arc, relative to the origin of the drawable. 

width Specify the width and height in pixels. These are the major and minor axes of 

height the arc. 

anglel Specifies the start of the arc relative to the three-o clock position from the 

center. Angles are specified in 64ths of degrees. 

angle 2 Specifies the path and extent of the arc relative to the start of the arc. Angles 

are specified in 64ths of degrees. 

Description 

XFillArc draws a filled arc. The x, y, width, and height arguments specify the bounding 
box for the arc. See XDrawArc for the description of how this bounding box is used to com 
pute the arc. Some, but not all, of the pixels drawn with XDrawArc will be drawn by XFill 
Arc with the same arguments. See XFillRectangle for an example of the differences in 
pixels drawn by the draw and fill routines. 

The arc forms one boundary of the area to be filled. The other boundary is determined by the 
arc_mode in the GC. If the arc_mode in the GC is ArcChord, the single line segment 
joining the endpoints of the arc is used. If ArcPieSlice, the two line segments joining the 
endpoints of the arc with the center point are used. 

XFillArc uses these graphics context components: function, plane_mask, 
f ill_style, arc_mode, subwindow_mode, clip_x_origin, clip_y_origin, and 
clip_mask. This function also uses these graphics context mode-dependent components: 
foreground, background, tile, stipple, ts_x_origin, and ts_y_ origin. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, 
The Graphics Context. 



Xlib Reference Manual 18 1 



XFIIIArc (continued) Xlib - Drawing Primitives 

Errors 

BadDrawable 

BadGC 

BadMatch 

Related Commands 

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc, 
XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, 
XDrawRectangle, XDrawRectangles, XDrawSegments, XFillArcs, XFill- 
Polygon, XFillRectangle, XFillRectangles. 



Xlib Reference Manual 



-Xlib - Drawing Primitives XFIIIArCS 

Name 

XFillArcs fill multiple arcs. 

Synopsis 

XFillArcs ( display, drawable , gc , arcs, narcs) 
Display *display; 
Drawable drawable; 
GC gc; 
XArc *arcs; 
int narcs; 

Arguments 

display Specifies a connection to an X server; returned from xopenDisplay. 

dra viable Specifies the drawable. 

gc Specifies the graphics context. 

arcs Specifies a pointer to an array of arc definitions. 

narcs Specifies the number of arcs in the array. 

Description 

For each arc, XFillArcs fills the region closed by the specified arc and one or two line seg 
ments, depending on the arc_mode specified in the GC. It does not draw the complete out 
lines of the arcs, but some pixels may overlap. 

The arc forms one boundary of the area to be filled. The other boundary is determined by the 
arc_mode in the GC. If the arc_mode in the GC is ArcChord, the single line segment 
joining the endpoints of the arc is used. If ArcPieSlice, the two line segments joining the 
endpoints of the arc with the center point are used. The arcs are filled in the order listed in the 
array. For any given arc, no pixel is drawn more than once. If filled arcs intersect, pixels will 
be drawn multiple times. 

There is a limit to the number of arcs that can be filled in a single call, that varies according to 
the server. To determine how many arcs you can fill in a single call, you find out your server s 
maximum request size using XMaxRequestSize. Subtract 3 and divide by three, and this is 
the maximum number of arcs you can fill in a single XFillArcs call. 

XFillArcs use these graphics context components: function, plane_mask, 
f ill_style, arc_mode, subwindow_mode, clip_x_origin, clip_y_origin, and 
clipjmask. This function also uses these graphics context mode-dependent components: 
foreground, background, tile, stipple, ts_x__origin, and ts_y_ origin. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, 
The Graphics Context. 

Structures 

typedef struct { 
short x, y; 
unsigned short width, height; 



Xlib Reference Manual 183 



XFillArcs 



(continued) 



Xlib - Drawing Primitives 



short anglel, angle2; /* 64ths of Degrees */ 

} XArc; 

Errors 

BadDrawable 

BadGC 

BadMatch 

Related Commands 

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc, 
XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, 
XDrawRectangle, XDrawRectangles, XDrawSegments, XFillArc, XFill- 
Polygon, XFillRectangle, XFillRectangles. 



184 



Xlib Reference Manual 



Xlib - Drawing Primitives- 



f XFillPolygon 



Name 

XFillPolygon fill a polygon. 

Synopsis 

XFillPolygon (display, draw-able, gc , points, npoints, shape, mode) 
Display * display; 
Drawable draw-able; 
GC gc; 

XPoint * points; 
int npoints; 
int shape; 
int mode ; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

dr a wabl e Specifies the drawable. 

gc Specifies the graphics context. 

points Specifies a pointer to an array of points. 

npoin t s Specifies the number of points in the array. 

shape Specifies an argument that helps the server to improve performance. Pass the 

last constant in this list that is valid for the polygon to be filled: Complex, 
Nonconvex, or Convex. 

mode Specifies the coordinate mode. Pass either CoordModeOrigin or Coord- 

ModePrevious. 

Description 

XFillPolygon fills the region closed by the specified path. Some but not all of the path 
itself will be drawn. The path is closed automatically if the last point in the list does not coin 
cide with the first point. No pixel of the region is drawn more than once. 

The mode argument affects the interpretation of the points that define the polygon: 

CoordModeOrigin indicates that all points are relative to the drawable s origin. 

CoordModePrevious indicates that all points after the first are relative to the previ 
ous point. (The first point is always relative to the drawable s origin.) 

The shape argument allows the fill routine to optimize its performance given tips on the confi 
guration of the area. 

Complex indicates the path may self-intersect. The f ill_rule of the GC must be 
consulted to determine which areas are filled. See Volume One, Chapter 5, The Graphics 
Context, for a discussion of the fill rules EvenOddRule and WindingRule. 



Xlib Reference Manual 185 



XFMIPolygon (continued) Xlib - Drawing Primitives 

None on vex indicates the path does not self-intersect, but the shape is not wholly con 
vex. 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. 

Convex means that for every pair of points inside the polygon, the line segment con 
necting them does not intersect the path. This can improve performance even more, but 
if the path is not convex, the graphics results are undefined. 

Contiguous coincident points in the path are not treated as self-intersection. 

XFillPolygon uses these graphics context components when filling the polygon area: 

function, plane_mask, fill_style, fill_rule, subwindow_mode, clip_ 
x_origin, clip_y_origin, and clip_mask. This function also uses these mode-depen 
dent components of the GC: foreground, background, tile, stipple, 
ts_x_origin, and ts_y_origin. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, 
The Graphics Context. 

Structures 

typedef struct { 

short x, y; 
} XPoint; 

Errors 

BadDrawable 
BadGC 
BadMatch 
BadValue 

Related Commands 

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc, 
XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, 
XDrawRectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, 
XFillRectangle, XFillRectangles. 



186 xiib Reference Manual 



Xllb - Drawing Primitives- 



XFillRectangle 



Name 

XFillRectangle fill a rectangular area. 

Synopsis 

XFillRectangle (display, drawable, gc, x, y, width, height) 
Display *display; 
Drawable drawable; 
GC gc; 
int x , y ; 
unsigned int width, height; 

Arguments 

display Specifies a connection to an X server; returned from XQpenDisplay. 

drawable Specifies the drawable. 

gc Specifies the graphics context. 

x Specify the x and y coordinates of the upper-left corner of the rectangle, rela- 

y live to the origin of the drawable. 

wi dth Specify the dimensions in pixels of the rectangle to be filled. 

height 

20 pixels 20 pixels 



Description 

XFillRectangle fills the rectangular area in the specified drawable using the x and y coor 
dinates, width and height dimensions, and graphics context you specify. XFill 
Rectangle draws some but not all of the path drawn by XDrawRectangle with the same 
arguments. 

XFillRectangle uses these graphics context components: function, plane_mask, 

fill_style, subwindow_mode, clip_x_origin, clip_y_origin, and clip_ 

mask. This function also uses these graphics context components depending on the 

fill_style: foreground, background tile, stipple, ts_x_origin, and 

ts_y_origin. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, 

The Graphics Context. 



Xlib Reference Manual 



187 



XFillRectangle (continued) Xlib - Drawing Primitives 



Errors 

BadDrawable 

BadGC 

BadMatch 



Related Commands 

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc, 
XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints. 
XDrawRectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, 
XFillPolygon, XFillRectangles. 



188 



Xlib Reference Manual 



Xlib - Drawing Primitives- 



XFMIRectangles 



Name 

XFillRectangles fill multiple rectangular areas. 

Synopsis 

XFillRectangles (display, drawable, gc , rectangles, nrectangles) 
Display * display ; 
Drawable drawable; 
GC gc ; 

XRectangle * rectangles; 
int nrectangles; 



Arguments 

di spl ay 
drawable 



Specifies a connection to an X server; returned from xopenDisplay. 

Specifies the drawable. 
gc Specifies the graphics context. 

rectangles Specifies a pointer to an array of rectangles. 
nrectangles Specifies the number of rectangles in the array. 



20 pixels 



20 pixels 



Description 

XFillRectangles fills multiple rectangular areas in the specified drawable using the graph 
ics context. 

The x and y coordinates of each rectangle are relative to the drawable s origin, and define the 
upper left corner of the rectangle. The rectangles are drawn in the order listed. For any given 
rectangle, no pixel is drawn more than once. If rectangles intersect, the intersecting pixels will 
be drawn multiple times. 

There is a limit to the number of rectangles that can be filled in a single call, that varies accord 
ing to the server. To determine how many rectangles you can fill in a single call, you find out 
your server s maximum request size using XMaxRequestSize. Subtract 3 and divide by 
two, and this is the maximum number of rectangles you can fill in a single XD raw- 
Rectangles call. 

XFillRectangles uses these graphics context components: function, plane_mask, 
fill style, subwindow_mode, clip_x_origin, clip_y_origin, and clip_ 



Xlib Reference Manual 



189 



XFillRectangles (continued) Xlib - Drawing Primitives 

mask. This function also uses these graphics context components depending on the f ill_ 
style: foreground, background, tile, stipple, ts_x_origin, and ts_y_ 
origin. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, 
The Graphics Context. 

Structures 

typedef struct { 

short x, y; 

unsigned short width, height; 
} XRectangle; 

Errors 

BadDrawable 

BadGC 

BadMatch 

Related Commands 

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc, 
XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, 
XDrawRectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, 
XFillPolygon, XFillRectangle, XFillRectangles. 



1QO Xlib Reference Manual 



XFindContext 

Xlib - Context Manager 

Name 

XFindContext get data from the context manager (not graphics context). 

Synopsis 

int XFindContext ( display, w, context, data) 
Display * display; 
Window w; 
XContext context; 
caddr_t *data; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window with which the data is associated. 

context Specifies the context type to which the data corresponds. 

data Returns the data. 

Description 

XFindContext gets data that has been assigned to the specified window and context ID. The 
context manager is used to associate data with windows for use within an application. 

This application should have called XUniqueContext to get a unique ID, and then xsave- 
Context to save the data into the array. The meaning of the data is indicated by the context 
ID, but is completely up to the client. 

XFindContext returns XCNOENT (a nonzero error code) if the context could not be found and 
zero (0) otherwise. 

For more information on the context manager, see Volume One, Chapter 13, Other Program 
ming Techniques. 

Structures 

typedef int XContext/ 

Related Commands 

XDeleteContext, XSaveContext, XUniqueContext. 



Xlib Reference Manual 19 1 



XFIush v xnb . Output Bu((er _ 

Name 

XFIush flush the request buffer (display all queued requests). 

Synopsis 

XFIush (display) 

Display *display; 

Arguments 

display Specifies a connection to an X server; returned from xopenoi splay. 

Description 

XFIush sends to the server ("flushes") all requests that have been buffered but not yet sent. 

Flushing is done automatically when input is read if no matching events are in Xlib s queue 
(with XPending, XNext Event, or XWindowEvent, etc.), or when a call is made that gets 
information from the server (such as XQueryPointer, XGetFontlnf o) so XFIush is sel 
dom needed. It is used when the buffer must be flushed before any of these calls are reached. 

For more information, see Volume One, Chapter 2, X Concepts, and Chapter 3, Basic Window 
Program. 

Related Commands 

XSync. 



192 Xlib Reference Manual 



-Mb - screen saver / XForceScreenSaver 

Name 

XForceScreenSaver turn the screen saver on or off. 

Synopsis 

XForceScreenSaver ( display, mode) 
Display * display; 
int mode ; 

Arguments 

display Specifies a connection to an X server; returned from xopenDisplay. 

mode Specifies whether the screen saver is active or reset. The possible modes are: 

ScreenSaverActive or ScreenSaverReset. 

Description 

XForceScreenSaver resets or activates the screen saver. 

If the specified mode is ScreenSaverActive and the screen saver currently is disabled, the 
screen saver is activated, even if the screen saver had been disabled by calling xset Screen- 
Saver with a timeout of zero (0). This means that the screen may go blank or have some ran 
dom change take place to save the phosphors. 

If the specified mode is ScreenSaverReset and the screen saver currently is enabled, the 
screen is returned to normal, the screen saver is deactivated and the activation timer is reset to 
its initial state (as if device input had been received). Expose events may be generated on all 
visible windows if the server cannot save the entire screen contents. 

For more information on the screen saver, see Volume One, Chapter 13, Other Programming 
Techniques. 

Errors 

BadValue 

Related Commands 

XActivateScreenSaver, XGetScreenSaver, XResetScreenSaver, XSet- 
ScreenSaver. 



Xlib Reference Manual 193 



^ Xlib - HouseKeeping 

Name 

XFree free specified memory allocated by an Xlib function. 

Synopsis 

XFree (data) 

caddr_t data; 

Arguments 

data Specifies a pointer to the data that is to be freed. 

Description 

XFree is a general purpose routine for freeing memory allocated by Xlib calls. 

Related Commands 

Def aultScreen, XCloseDisplay, XNoOp, XOpenDisplay. 



194 Xlib Reference Manual 



-X. - co,ormaps / XFreeColormap 

Name 

XFreeColormap delete a colormap and install the default colormap. 

Synopsis 

XFreeColormap ( display, cmap) 
Display *display; 
Colo r map cmap ; 

Arguments 

display Specifies a connection to an X server; returned from xopenDisplay. 

cmap Specifies the colormap to delete. 

Description 

XFreeColormap destroys the specified colormap, unless it is the default colormap for a 
screen. That is, it not only uninstalls cmap from the hardware colormap if it is installed, but 
also frees the associated memory including the colormap ID. 

XFreeColormap performs the following processing: 

If cmap is an installed map for a screen, it uninstalls the colormap and installs the default 
if not already installed. 

If cmap is defined as the colormap attribute for a window (by XCreateWindow or 
XChangeWindowAttributes), it changes the colormap attribute for the window to 
the constant None, generates a ColormapNotif y event, and frees the colormap. The 
colors displayed with a colormap of None are server-dependent, since the default color- 
map is normally used. 

For more information, see Volume One, Chapter 7, Color. 
Errors 

BadColormap 

Related Commands 

Def aultColormap, DisplayCells, XCopyColormapAndFree, XCreate- 
Colormap, XGetStandardColormap, XInstallColormap, XListlnstalled- 
Colormaps, XSetStandardColormap, XSetWindowColormap, XUninstall- 
Colormap. 



Xlib Reference Manual 195 



XFreeColors \ 



Xlib- Color Cells- 



Name 

XFreeColors free colormap cells or planes. 

Synopsis 

XFreeColors ( display, cmap , pixels, npixels, planes) 
Display *display; 
Colormap cmap; 
unsigned long pixels []; 
int npixels; 
unsigned long planes; 

Arguments 

display Specifies a connection to an X server; returned from XQpenDisplay. 

cmap Specifies the colormap. 

pixels Specifies an array of pixel values. 

npixels Specifies the number of pixels. 

pi anes Specifies the planes you want to free. 

Description 

XFreeColors frees the cells whose values are computed by ORing together subsets of the 
planes argument with each pixel value in the pixels array. 

If the cells are read/write, they become available for reuse, unless they were allocated with 
XAllocColorPlanes, in which case all the related pixels may need to be freed before any 
become available. 

If the cells were read-only, they become available only if this is the last client to have allocated 
those shared cells. 

For more information, see Volume One, Chapter 7, Color. 

Errors 

BadAccess Attempt to free a colorcell not allocated by this client (either unallocated or 
allocated by another client). 

BadColormap 

BadValue A pixel value is not a valid index into cmap. 

Note: if more than one pixel value is in error, the one reported is arbitrary. 

Related Commands 

BlackPixel, WhitePixel, XAllocColor, XAllocColorCells, XAllocColor 
Planes, XAllocNamedColor, XLookupColor, XParseColor, XQueryColor, 
XQueryColors, XStoreColor, XStoreColors, XStoreNamedColor. 



196 Xlib Reference Manual 



Xlib -Cursors- 



J XFreeCursor 



Name 

XFreeCursor release a cursor. 

Synopsis 

XFreeCursor ( display, cursor) 
Display * display; 
Cursor cursor; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

cursor Specifies the ID of the cursor to be affected. 

Description 

XFreeCursor deletes the association between the cursor ID and the specified cursor. The 
cursor storage is freed when all other clients have freed it. Windows with their cursor attribute 
set to this cursor will have this attribute set to None (which implies CopyFromParent). The 
specified cursor ID should not be referred to again. 

Errors 

BadCursor 

Related Commands 

XCreateFontCursor, XCreateGlyphCursor, XCreatePixmapCursor, XDef ine- 
Cursor, XQueryBestCursor, XQueryBestSize, XRecolorCursor, XUndef ine- 
Cursor. 



Xlib Reference Manual 197 



XFreeExtensionList \ XMb _ Extensions _ 

Name 

XFreeExtensionList free memory allocated for a list of installed extensions. 

Synopsis 

XFreeExtensionList ( list) 
char **Iist; 

Arguments 

list Specifies a pointer to the list of extensions returned from XList- 

Extensions. 

Description 

XFreeExtensionList frees the memory allocated by XListExt ens ions. 

For more information, see Volume One, Chapter 13, Other Programming Techniques. 

Related Commands 

XListExt ens ions, XQueryExtension. 



198 XHb Reference Manual 



XFreeFont 



Name 

XFreeFont unload a font and free storage for the font structure. 

Synopsis 

XFreeFont ( display, font_struct ) 
Display * display; 
XFontStruct *font_struct ; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

f ont_struct Specifies the storage associated with the font. 

Description 

XFreeFont frees the memory allocated for the font_struct font information structure 
(XFontStruct) filled by XQueryFont or XLoadQueryFont. XFreeFont frees all stor 
age associated with the font_struct argument. Neither the data nor the font should be ref 
erenced again. 

The server unloads the font itself if no other client has loaded it. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text. 

Structures 

typedef struct { 

XExtData *ext_data; /* hook for extension to hang data */ 

Font fid; /* Font ID for this font */ 

unsigned direction; /* hint about direction the font is painted */ 

unsigned min_char_or_byte2; /* first character */ 

unsigned max_char_or_byte2; /* last character */ 

unsigned min_bytel; /* first row that exists */ 

unsigned max_bytel; /* last row that exists */ 

Bool all_chars_exist; /* flag if all characters have nonzero size*/ 

unsigned def ault_char; /* char to print for undefined character */ 

int n_properties; /* how many properties there are */ 

XFontProp *properties; /* pointer to array of additional properties*/ 

XCharStruct min_bounds; /* minimum bounds over all existing char*/ 

XCharStruct max_bounds; /* minimum bounds over all existing char*/ 

XCharStruct *per_char; /* first_char to last_char information */ 

int ascent; /* logical extent above baseline for spacing */ 

int descent; /* logical descent below baseline for spacing */ 

} XFontStruct; 

Errors 

BadFont 

Related Commands 

XCreateFontCursor, XFreeFontlnf o, XFreeFontNames, XFreeFontPath, 
XGetFontPath, XGetFontProperty, XListFonts, XListFontsWithlnf o, 
XLoadFont, XLoadQueryFont, XQueryFont, XSetFont, XSetFontPath, 
XUnloadFont. 



Xlib Reference Manual 



XFreeFontlnfo \ XIlb _ Fonts _ 

Name 

XFreeFontlnfo free the memory allocated by XListFontsWithlnf o. 

Synopsis 

XFreeFontlnfo (names, info, actual_count) 
char ** names; 
XFontStruct *info; 
int actual_count ; 

Arguments 

names Specifies a pointer to the list of font names that were returned by XList- 

FontsWithlnfo. 

info Specifies a pointer to the list of font information that was returned by 

XListFontsWithlnf o. 

actual_count 

Specifies the number of matched font names returned by XLis t Fonts - 
Withlnfo. 

Description 

XFreeFontlnfo frees the list of font information structures allocated by XListFonts 
Withlnf o. It does not unload the specified fonts themselves. 

Structures 

typedef struct { 

XExtData *ext_data; /* hook for extension to hang data */ 

Font fid; /* Font ID for this font */ 

unsigned direction; /* hint about direction the font is painted */ 

unsigned min_char_or_byte2; /* first character */ 

unsigned max char or byte2; /* last character */ 

unsigned min_bytel; /* first row that exists */ 

unsigned max bytel; /* last row that exists */ 

Bool all_chars_exist; /* flag if all characters have nonzero size*/ 

unsigned default_char; /* char to print for undefined character */ 

int n_properties; /* how many properties there are */ 

XFontProp *properties; /* pointer to array of additional properties*/ 

XCharStruct min_bounds; /* minimum bounds over all existing char*/ 

XCharStruct max bounds; /* minimum bounds over all existing char*/ 

XCharStruct *per_char; /* first_char to last_char information */ 

int ascent; /* logical extent above baseline for spacing */ 

int descent; /* logical descent below baseline for spacing */ 

} XFontStruct; 

Related Commands 

XCreateFontCursor, XFreeFont, XFreeFontNames, XGetFontPath, XGetFont- 
Property, XListFonts, XListFontsWithlnf o, XLoadFont, XLoadQueryFont, 
XQueryFont, XSetFont, XSetFontPath, XUnloadFont. 



200 Xlib Reference Manual 



Xlib -Fonts 



J XFreeFontNames 



Name 

XFreeFontNames free the memory allocated by XListFonts. 
Synopsis 

XFreeFontNames (list) 
char *list [ ] ; 

Arguments 

list Specifies the array of font name strings to be freed. 

Description 

XFreeFontNames frees the array of strings returned by XListFonts. 

Related Commands 

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontPath, XGetFont- 
Path, XGetFontProperty, XListFonts, XListFontsWithlnf o, XLoadFont, 
XLoadQueryFont, XQueryFont, XSetFont, XSetFontPath, XUnloadFont. 



Xlib Reference Manual 201 



XFreeFontPath \ x,, b -Fon,s- 

Name 

XFreeFontPath free the memory allocated by XGetFontPath. 

Synopsis 

XFreeFontPath (list) 
char **list; 

Arguments 

list Specifies an array of strings allocated by XGetFontPath. 

Description 

XFreeFontPath frees the data used by the array of pathnames returned by XGetFont 
Path. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text. 
Related Commands 

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XGet 
FontPath, XGetFontProperty, XListFonts, XListFontsWithlnf o, XLoad- 
Font, XLoadQueryFont, XQueryFont, XSetFont, XSetFontPath, XUnloadFont. 



202 Xlib Reference Manual 



-Xlib - Graphics Context XFreeGC 

Name 

XFreeGC free a graphics context. 

Synopsis 

XFreeGC (display, gc) 
Display * display; 
GC gc ; 

Arguments 

display Specifies a connection to an X server; returned from xopenDisplay. 

gc Specifies the graphics context to be freed. 

Description 

XFreeGC frees all memory associated with a graphics context, and removes the GC from the 
server and display hardware. 

For more information, see Volume One, Chapter 5, The Graphics Context. 

Errors 

BadGC 

Related Commands 

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XGContextFromGC, XSetArcMode, 
XSetBackground, XSetClipMask, XSetClipOrigin, XSetClipRectangles, 
XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground, XSet- 
Function, XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, 
XSetState, XSetStipple, XSetSubwindowMode, XSetTSOrigin. 



Xlib Reference Manual 203 



XFreeModifiermap \ 



X|lb _ 



Name 

XFreeModifiermap destroy and free a keyboard modifier mapping structure. 

Synopsis 

XF r eeModi f ie rmap ( modmap ) 

XModif ierKeymap * modmap; 

Arguments 

modmap Specifies a pointer to the XModif ierKeymap structure to be freed. 

Description 

XFreeModifiermap frees an XModif ierKeymap structure originally allocated by XNew- 
Modif ierMap or XGetModif ierMapping. 

For more information, see Volume One, Chapter 9, The Keyboard and Pointer. 
Structures 

typedef struct { 

int max_keypermod; /* server s max number of keys per modifier */ 
KeyCode *modif iermap; /* an 8 by max_keypermod array of 

* keycodes to be used as modifiers */ 

} XModif ierKeymap; 

Related Commands 

XChangeKeyboardMapping, XDeleteModif iermapEntry, XGetKeyboard- 
Mapping, XGetModif ierMapping, XInsertModif iermapEntry, XKeycode- 
ToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym, XLookup- 
String, XNewModif ierMap, XQueryKeymap, XRebindKeySym, XRef resh- 
KeyboardMapping, XSetModif ierMapping, XStringToKeysym. 



204 Xlib Reference Manual 



-Mb - Pixmaps and TNes / 

Name 

XFreePixmap free a pixmap ID. 

Synopsis 

XFreePixmap ( display, pixmap) 
Display * display; 
Pixmap pixmap; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

pixmap Specifies the pixmap whose ID should be freed. 

Description 

XFreePixmap disassociates a pixmap ID from its resource. If no other client has an ID for 
that resource, it is freed. The Pixmap should never be referenced again by this client. If it is, 
the ID will be unknown and a BadPixmap error will result. 

Errors 

BadPixmap 

Related Commands 

XCreateBitmapFromData, XCreatePixmap, XCreatePixmapFromBitmapData, 
XQueryBestSize, XQueryBestStipple, XQueryBestTile, XReadBitmapFile, 
XSetTile, XSetWindowBackgroundPixmap, XSetWindowBorderPixmap, 
XWriteBitmapFile. 



Xlib Reference Manual 205 



XFreeStringList V Vl] 

^ Xlib - Window Manager Hints- 
Name 

XFreeStringList free the in-memory data associated with the specified string list. 

Synopsis 

void XFreeStringList (list) 
char **Iist; 

Arguments 

list Specifies the list of strings to be freed. 

Availability 

Release 4 and later. 

Description 

XFreeStringList releases memory allocated by XTextPropertyToStringList. 

Related Commands 

XGetTextProperty, XSetTextProperty, XStringListToTextProperty, 
XTextPropertytoStringList. 



206 Xlib Reference Manual 



-xub - Graphic, con, 8 x / XGContextFromGC 

Name 

XGContextFromGC obtain the GContext (resource ID) associated with the specified 
graphics context. 

Synopsis 

GContext XGContextFromGC ( gc) 
GC gc; 

Arguments 

gc Specifies the graphics context of the desired resource ID. 

Description 

XGContextFromGC extracts the resource ID from the GC structure. The GC structure is 
Xlib s local cache of GC values and contains a field for the GContext ID. This function is 
essentially a macro that accesses this field, since the GC structure is intended to be opaque. 

A GContext is needed to set a field of the xvisuallnf o structure prior to calling XGet- 
Visuallnf o. 

Related Commands 

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XSetArcMode, XSet- 
Background, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSet- 
Dashes, XSetFillRule, XSetFillStyle, XSetForeground, XSetFunction, 
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, XSetState, 
XSetStipple, XSetSubwindowMode, XSetTSOrigin. 



Xlib Reference Manual 207 



XGeometry v ^ 

v Xlib - Standard Geometry- 
Name 

XGeometry calculate window geometry given user geometry string and default geometry. 

Synopsis 

int XGeometry ( display, screen, user_geom, default_geom r bwidth, 

fwidth r f height , xadder , yadder f x, y, width, height) 
Display *display; 
int screen; 

char *user_geom r *default_geom; 
unsigned int bwidth; 
unsigned int f width r f height ; 
int xadder, yadder; 
int *x r *y, * width, *height;/* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

screen Specifies which screen the window is on. 

user_geom Specifies the user or program supplied geometry string, perhaps incomplete. 

de fa u 1 1_ ge om 

Specifies the default geometry string and must be complete. 

bwi dth Specifies the border width. 

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

f width 

xadder Specify additional interior padding in pixels needed in the window, 

yadder 

x Return the user-specified or default coordinates of the window. 

y 

wi dth Return the window dimensions in pixels. 

height 

Description 

XGeometry has been superseded by XWMGeometry as of Release 4. 

XGeometry returns the position and size of a window given a user-supplied geometry 
(allowed to be partial) and a default geometry. Each user-supplied specification is copied into 
the appropriate returned argument, unless it is not present, in which case the default specifica 
tion is used. The default geometry should be complete while the user-supplied one may not be. 

XGeometry is useful for processing command line options and user preferences. These geom 
etry strings are of the form: 

=<width>x<height> { +- } <xoffset> ( +- } <yoffset> 



208 Xlib Reference Manual 



Xlib - Standard Geometry (continued) XGeometry 

The "=" at the beginning of the string is now optional. (Items enclosed in <> are integers, and 
items enclosed in {} are a set from which one item is to be chosen. Note that the brackets 
should not appear in the actual string.) 

The XGeometry return value is a bitmask that indicates which values were present in 
user_geom. This bitmask is composed of the exclusive OR of the symbols XValue, 
YValue, WidthValue, HeightValue, XNegative, or YNegative. 

If the function returns either xvalue or YValue, you should place the window at the 
requested position. The border width (bwidtti), size of the width and height increments (typi 
cally fwidth and f height), and any additional interior space (xadder and yadder) are 
passed in to make it easy to compute the resulting size. 

Related Commands 

XParseGeometry, XTranslateCoordinates, XWMGeometry. 



Xlib Reference Manual 209 



XGetAtomName V 

^ Xlib - Properties- 
Name 

XGetAtomName get a string name for a property given its atom. 

Synopsis 

char *XGetAtomName ( display, atom) 
Display *display; 
Atom atom; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

atom Specifies the atom whose string name you want returned. 

Description 

An atom is a number identifying a property. Properties also have a string name. XGetAtom 
Name returns the string name that was specified in the original call to xinternAtom that 
returned this atom, or, for predefined atoms, a string version of the symbolic constant without 
the XA_ is returned. If the specified atom is not defined, XGetAtomName returns NULL, and 
generates a BadAtom error. 

For example, XGetAtomName returns "XA_WM_CLASS" (a string) when passed the prede 
fined atom XA_WM_CLASS (a defined constant). 

You should free the resulting string with XFree when it is no longer needed. 
XinternAtom performs the inverse function, returning the atom given the string. 

Errors 

BadAtom 

Related Commands 

XChangeProperty, XDeleteProperty, XGetFontProperty, XGetWindow- 
Property, XinternAtom, XListProperties, XRotateWindowProperties, 
XSetStandardProperties. 



210 Xlib Reference Manual 



-X.ib-W.ndowManagerH.n,, / XGetClaSSHint 

Name 

XGetClassHint get the XA_WM_CLASS property of a window. 

Synopsis 

Status XGetClassHint (display, v, class_hints) 
Display *display; 
Window w; 
XClassHint *class_hints ; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the ID of the window for which the property is desired. 

class_hints Returns the XClassHints structure. 

Description 

XGetClassHint obtains the XA_WM_CLASS property for the specified window. This property 
stores the resource class and instance name, that the window manager uses to get any resource 
settings that may control how the window manager manages the application that set this prop 
erty. XGetClassHint returns a Status of zero on failure, nonzero on success. 

The XClassHint structure returned contains res_class, which is the name of the client 
such as "emacs", and res_name, which should be the first of the following that applies: 

command line option (-rn name) 

a specific environment variable (e.g., RESOURCE_NAME) 

the trailing component of argv [ ] (after the last /) 

To free res_name and res_class when finished with the strings, use XFree. 
For more information on using hints, see Volume One, Chapter W,Interclient Communication. 

Structures 

typedef struct { 

char *res_name; 

char *res_class; 
} XClassHint; 

Errors 

BadWindow 

Related Commands 

XAllocClassHint, XFetchName, XGetlconName, XGetlconSizes, XGetNormal- 
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XGetZoom- 
Hints, XSetClassHint, XSetCommand, XSetlconName, XSetlconSizes, XSet- 
NormalHints, XSetSizeHints, XSetTransientForHint, XSetWMHints, XSet- 
ZoomHints, XStoreName, XSetWMProperties, XSetWMProperties. 



Xlib Reference Manual 21 1 



XGetCommand I 

v Xllb - Window Manager Hints- 
Name 

XGetCommand get the XA_WM_COMMAND property (command line arguments). 

Synopsis 

Status XGetCommand (display, w, argv_return, argc_return) 
Display ^display; 
Window w; 

char ***argv_return; 
int *argc_return; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window. 

argv_return Returns the application s argument list. 
argc_return Returns the number of arguments returned. 

Description 

XGetCommand reads the XA_WM_COMMAND property from the specified window and returns a 
string list. If the XA_WM_COMMAND property exists, it is of type XA_STRING and format 8. If suf 
ficient memory can be allocated to contain the string list, XGetCommand fills in the 
argv_return and argc_return arguments and returns a non-zero status. Otherwise, it 
returns a zero status. To free the memory allocated to the string list, use XFreeStringList. 

Errors 

BadWindow 

Related Commands 

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal- 
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XGetZoom- 
Hints, XSetClassHint, XSetlconName, XSetlconSizes, XSetNormalHints, 
XSetSizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints, 
XStoreName. 



212 Xlib Reference Manual 



XGetDefault 



Name 

XGetDefault extract an option value from the resource database. 

Synopsis 

char *XGetDefault (display, program, option) 
Display * display ; 
char * program; 
char * opt ion; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

program Specifies the program name to be looked for in the resource database. The pro 
gram name is usually argv [ ] , the first argument on the UNIX command line. 

option Specifies the option name or keyword. Lines containing both the program 

name and the option name, separated only by a period or asterisk, will be 
matched. 

Description 

XGetDefault returns a character string containing the user s default value for the specified 
program name and option name. XGetDefault returns NULL if no key can be found that 
matches option and program. For a description of the matching rules, see XrmGet- 
Resource. 

The strings returned by XGetDefault are owned by Xlib and should not be modified or freed 
by the client. 

Lines in the user s resource database look like this: 

xterm. foreground: #cOcOff 

xterm. geometry : =81x28 

xterm. saveLines : 256 

xterm. font: 8x13 

xterm. keyMapFile: /usr/black/ .keymap 

xterm. activelcon: on 

xmh. header. font 9x15 

The portion on the left is known as a key; the portion on the right is the value. Upper or lower 
case is important in keys. The convention is to capitalize only the second and successive words 
in each option, if any. 

Resource specifications are usually loaded into the XA_RESOURCE_MANAGER property on the 
root window at login. If no such property exists, a resource file in the user s home directory is 
loaded. On a UNIX-based system, this file is $HOMEIXdefoults. After loading these defaults, 
XGetDefault merges additional defaults specified by the XENVIRONMENT environment 
variable. If XENVIRONMENT is defined, it contains a full path name for the additional resource 
file. If XENVIRONMENT is not defined, XGetDefault looks for $HOMEI Xdefoults-name, 
where name specifies the name of the machine on which the application is running. 



Xlib Reference Manual 213 



XGetDefault (continued) Xlib - User Preferences 

The first invocation of XGetDefault reads and merges the various resource files into Xlib so 
that subsequent requests are fast Therefore, changes to the resource files from the program 
will not be felt until the next invocation of the application. 

For more information, see Volume One, Chapter 11, Managing User Preferences. 
Related Commands 

XAutoRepeatOf f , XAutoRepeatOn, XBell, XChangeKeyboardControl, XGet- 
KeyboardControl.XGetPointerControl. 



214 Xlib Reference Manual 



-xnb - Error Handling / XGetErrorDatabaseText 

Name 

XGetErrorDatabaseText obtain error messages from the error database. 

Synopsis 

XGetErrorDatabaseText ( display, name, message, 

default_string, buffer, length) 
Display display; 
char *name, *message; 
char *default_string; 

char * buffer; /* RETURN */ 

int length; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpe nD i s p 1 a y . 

name Specifies the name of the application. 

message Specifies the type of the error message. One of XProtoError, xiib- 
Message, or XRequestMa jor (see Description below). 

default_string 

Specifies the default error message. 

buffer Returns the error description. 
length Specifies the size of the return buffer. 

Description 

XGetErrorDatabaseText returns a message from the error message database. Given 
name and message as keys, XGetErrorDatabaseText uses the resource manager to 
look up a string and returns it in the buffer argument. Xlib uses this function internally to look 
up its error messages. On a UNIX-based system, the error message database is usually 
lusrlliblXl 1 IXErrorDB . 

The name argument should generally be the name of your application. The message argu 
ment should indicate which type of error message you want. Three predefined message types 
are used by Xlib to report errors: 

XProtoError The protocol error number is used as a string for the message argument. 
xlibMessage These are the message strings that are used internally by Xlib. 
XReque s tMa jor The major request protocol number is used for the message argument. 

If no string is found in the error database, XGetErrorDatabaseText returns the 
def ault_string that you specify to the buffer. The string in buffer will be of length 
length. For more information, see Volume One, Chapter 3, Basic Window Program. 

Related Commands 

XDisplayName, XGetErrorText, XSetAf terFunction, XSetErrorHandler, 
XSetlOErrorHandler, XSynchronize. 



Xlib Reference Manual 215 



XGetErrorText \ Xllb _ Error Handnng _ 

Name 

XGetErrorText obtain a description of error code. 

Synopsis 

XGetErrorText ( display, code, buffer, length) 
Display *display; 
int code ; 

char * buffer; /* RETURN */ 

int length; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

code Specifies the error code for which you want to obtain a description. 

buffer Returns a pointer to the error description text. 

length Specifies the size of the buffer. 

Description 

XGetErrorText obtains textual descriptions of errors. XGetErrorText returns a pointer 
to a null-terminated string describing the specified error code with length length. This string 
is copied from static data and therefore may be freed. This routine allows extensions to the 
Xlib library to define their own error codes and error strings that can be accessed easily. 

For more information, see Volume One, Chapter 3, Basic Window Program. 
Related Commands 

XDisplayName, XGetErrorDatabaseText, XSetAf terFunction, XSetError- 
Handler, XSetlOErrorHandler, XSynchronize. 



21 6 Xlib Reference Manual 



XI ib- Fonts- 



J XGetFontPath 



Name 

XGetFontPath get the current font search path. 

Synopsis 

char **XGetFontPath ( display, npaths) 
Display ^display; 
int * npaths; /* RETURN number of elements */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

npaths Returns the number of strings in the font path array. 

Description 

XGetFontPath allocates and returns an array of strings containing the search path for fonts. 
The data in the font path should be freed when no longer needed. 

Related Commands 

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XFree- 
FontPath, XGetFontProperty, XListFonts, XListFontsWithlnf o, XLoad- 
Font, XLoadQueryFont, XQueryFont, XSetFont, XSetFontPath, XUnloadFont. 



Xlib Reference Manual 217 



XGetFontProperty 



X 



Xlib- Properties- 



Name 

XGetFontProperty get a font property given its atom. 

Synopsis 

Bool XGetFontProperty (font_struct f atom, value) 
XFontStruct *f ont_struct ; 
Atom atom; 
unsigned long *value; /* RETURN */ 

Arguments 

font struct Specifies the storage associated with the font. 



atom 
value 



Specifies the atom associated with the property name you want returned. 



Returns the value of the font property. 

Description 

XGetFontProperty returns the value of the specified font property, given the atom for that 
property. The function returns False if the atom was not defined, or True if was defined. 

There are a set of predefined atoms for font properties which can be found in <XlllXatom.h>. 
These atoms are listed and described in Volume One, Chapter 6, Drawing Graphics and Text. 
This set contains the standard properties associated with a font. The predefined font properties 
are likely but not guaranteed to be present for any given font. 

See Volume One, Appendix I, Logical Font Description Conventions, for more information on 
font properties. 



Structures 

typedef struct { 

XExtData *ext_data; 
Font fid; 

unsigned direction; 
unsigned min_char_or_byte2; 
unsigned max_char_or_byte2; 
unsigned min_bytel; 
unsigned max_bytel; 
Bool all_chars_exist; 
unsigned def ault_char; 
int n_properties; 
XFontProp ^properties; 
XCharStruct min_bounds; 
XCharStruct max bounds; 



XCharStruct 
int ascent; 
int descent; 
} XFontStruct; 



per_char; 



/* hook for extension to hang data */ 

/* Font ID for this font */ 

/* hint about direction the font is painted */ 

/* first character */ 

/* last character */ 

/* first row that exists */ 

/* last row that exists */ 

/* flag if all characters have nonzero size*/ 

/* char to print for undefined character */ 

/* how many properties there are */ 

/* pointer to array of additional properties*/ 

/* minimum bounds over all existing char*/ 

/* minimum bounds over all existing char*/ 

/* first_char to last__char information */ 

/* logical extent above baseline for spacing */ 

/* logical descent below baseline for spacing */ 



Related Commands 

XChangeProperty, XDeleteProperty, XGetAtomName, XGetWindowProperty, 
XInternAtom, XListProperties, XRotateWindowProperties, XSetStandard- 
Properties. 



218 



Xlib Reference Manual 



Xlib - Window Manager Hints- 



XGetGCValues 



Name 

XGetGCValues obtain components of a given GC from Xlib s GC cache. 

Synopsis 

Status XGetGCValues (display, gc, valuemask, values) 
Display ^display; 
GC gc; 

unsigned long valuemask; 
XGCValues * values; 



Arguments 

di sp 1 ay 

gc 

valuemask 



values 



/* RETURN */ 

Specifies a connection to an X server; returned from XOpenDisplay. 
Specifies the GC. 

Specifies which components in the GC are to be returned in the values 
argument. This argument is the bitwise inclusive OR of one or more of the 
valid GC component mask bits. 

Returns the GC values in the specified XGCValues structure. 



Availability 

Release 4 and later. 

Description 

XGetGCValues returns the components specified by valuemask for the specified GC. Note 
that the clip mask and dash list (represented by the GCClipMask and GCDashList bits, 
respectively, in the valuemask) cannot be requested. If the valuemask contains a valid set of 
GC mask bits (any of those listed in the Structures section with the exception of GCClipMask 
and GCDashList) and no error occur, XGetGCValues sets the requested components in 
values and returns a nonzero status. Otherwise, it returns a zero status. 

For more information, see Volume One, Chapter 5, The Graphics Context. 



Structures 

typedef struct { 

int function; /* 

unsigned long plane_mask; /* 

unsigned long foreground; /* 

unsigned long background; /* 

int line_width; /* 

int line_style; /* 

int cap_style; /* 

int join_style; /* 

int fill_style; /* 

int fill_rule; /* 

int arc_mode; /* 

Pixmap tile; /* 

Pixmap stipple; /* 

int ts_x_origin; /* 



logical operation */ 

plane mask */ 

foreground pixel */ 

background pixel */ 

line width */ 

LineSolid, LineOnOf fDash, LineDoubleDash */ 

CapNotLast, CapButt, CapRound, CapPro jecting */ 

JoinMiter, JoinRound, JoinBevel */ 

FillSolid, Fill-Tiled, FillStippled */ 

EvenOddRule, WindingRule */ 

ArcPieSlice, ArcChord */ 

tile pixmap for tiling operations */ 

stipple 1 plane pixmap for stipping */ 

offset for tile or stipple operations */ 



Xlib Reference Manual 



219 



XGetGCValues 



(continued) 



Xlib - Window Manager Hints 



int ts_y_origin; 
Font font; 
int subwindow mode; 
Bool graphics_exposures; 
int clip_x_origin; 
int clip_y_origin; 
Pixmap clip_mask; 
int dash_offset; 
char dashes; 
} XGCValues; 



/* default text font for text operations */ 

/* ClipByChildren, Includelnferiors */ 

/* generate events on XCopyArea, XCopyPlane */ 

/* origin for clipping */ 

/* bitmap clipping; other calls for rects */ 

/* patterned/dashed line information */ 



#define 


GCFunction (1L0) 


#define 


GCPlaneMask (1L1) 


#define 


GCForeground (1L2) 


#define 


GCBackground (1L3) 


#define 


GCLineWidth (1L4) 


#define 


GCLineStyle (1L5) 


#define 


GCCapStyle (1L6) 


#define 


GCJoinStyle (1L7) 


#define 


GCFillStyle (1L8) 


#define 


GCFillRule (1L9) 


fdefine 


GCTile (1L10) 


#define 


GCStipple (1L11) 


#define 


GCTileStipXOrigin (1L12) 


#def ine 


GCTileStipYOrigin (1L13) 


tdefine 


GCFont (1L14) 


#def ine 


GCSubwindowMode (1L15) 


#define 


GCGraphicsExposures (1L16) 


#define 


GCClipXOrigin (1L17) 


#define 


GCClipYOrigin (1L18) 


#def ine 


GCClipMask (1L19) 


tdefine 


GCDashOffset (1L20) 


#def ine 


GCDashList (1L21) 


#define 


GCArcMode (1L22) 



/* not valid in this call */ 
/* not valid in this call */ 



Related Commands 

XChangeGC, XCopyGC, XCreateGC. 



220 



Xlib Reference Manual 



Xlib - Window Attributes- 



J XGetGeometry 



Name 

XGetGeometry obtain the current geometry of drawable. 

Synopsis 

Status XGetGeometry (display, drawable, root, x, y, 

width, height, border_ width, depth) 
Display ^display; 
Drawable drawable; 

Window *root; /* RETURN */ 

int *x, *y; /* RETURN */ 

unsigned int *width, *height; /* RETURN */ 

unsigned int *border_width ; /* RETURN */ 

unsigned int * depth; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

drawabl e Specifies the drawable, either a window or a pixmap. 
root Returns the root window ID of the specified window. 

x Return the coordinates of the upper- left pixel of the window s border, relative 

y to its parent s origin. For pixmaps, these coordinates are always zero. 

width Return the dimensions of the drawable. For a window, these return the inside 

height size (not including the border). 

border_width 

Returns the borderwidth, in pixels, of the window s border, if the drawable is a 
window. Returns zero if the drawable is a pixmap. 

depth Returns the depth of the pixmap or window (bits per pixel for the object). 

Description 

This function gets the current geometry of a drawable, plus the ID of the root window of the 
screen the window is on. 

XGetGeometry returns a Status of zero on failure, or nonzero on success. 

Errors 

BadDrawable 

Related Commands 

XConf igureWindow, XGetWindowAttributes, XMoveResizeWindow, XMove- 
Window, XResizeWindow. 



Xlib Reference Manual 221 



XGetlconName V Xlib _ Wlndow Manager Hln , s _ 

Name 

XGetlconName get the name to be displayed in an icon. 

Synopsis 

Status XGetlconName ( display, w, icon_name) 
Display *display; 
Window w; 
char **icon_name; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the ID of the window whose icon name you want to leam. 

icon_name Returns a pointer to the name to be displayed in the window s icon. The 
name should be a null-terminated string. If a name hasn t been assigned to 
the window, XGetlconName sets this argument to NULL. When finished 
with it, a client must free the icon name string using XFree. 

Description 

XGetlconName is superseded by XGetWMlconName in Release 4. XGetlconName reads 
the icon name property of a window. This function is primarily used by window managers to 
get the name to be written in a window s icon when they need to display that icon. 

XGetlconName returns a nonzero Status if it succeeds, and zero if no icon name has been 
set for the argument window. 

For more information, see Volume One, Chapter WJnterclient Communication. 
Errors 

BadWindow 

Related Commands 

XFetchName, XGetClassHint, XGetlconSizes, XGetNormalHints, XGetSize- 
Hints, XGetTransientForHint, XGetWMHints, XGetZoomHints, XSetClass- 
Hint, XSetCommand, XSetlconName, XSetlconSizes, XSetNormalHints, XSet- 
SizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints, XStore- 
Name. 



222 Xlib Reference Manual 



-XHb-W.ndowM.n.g.rH.n., / XGetlCOnSizeS 

Name 

XGetlconSizes get preferred icon sizes. 

Synopsis 

Status XGetlconSizes (display, w, size_list, count) 
Display *display; 
Window w; 

XlconSize **size_list; /* RETURN */ 
int * count; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window ID (usually of the root window). 

si ze_l 1st Returns a pointer to the size list. 

count Returns the number of items in the size list. 

Description 

XGetlconSizes reads the XA_WM_ICON_SIZE property that should be set by the window 
manager to specify its desired icon sizes. XGetlconSizes returns a Status of zero if a 
window manager has not set icon sizes, and a nonzero Status otherwise. This function 
should be called by all programs to find out what icon sizes are preferred by the window man 
ager. The application should then use XSetWMHints to supply the window manager with an 
icon pixmap or window in one of the supported sizes. To free the data allocated in 
size_list, use XFree. 

For more information, see Volume One, Chapter 10, Interclient Communication. 
Structures 

typedef struct { 

int min_width, min_height; 
int max_width, max_height; 
int width_inc, height_inc; 
} XlconSize; 

/* width_inc and height_inc provide the preferred 

* increment of sizes in the range from min_width 

* to max_width and min_height to max_height. */ 

Errors 

BadWindow 



Xlib Reference Manual 223 



XGetlconSizes (continued) Xlib - Window Manager Hints 

Related Commands 

XAllocIconSize, XFetchName, XGetClassHint, XGetlconName, XGetNormal- 
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XGetZoom- 
Hints, XSetClassHint, XSetCommand, XSetlconSizes, XSetNormalHints, 
XSetSizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints, 
XStoreName . 



Xlib Reference Manual 



-X.ib-.mage, / 

Name 

XGetlmage place contents of a rectangle from drawable into an image. 

Synopsis 

Xlmage * XGet Image ( display, drawable, x, y, width, height, 

plan e_ma sk , forma t ) 
Display * display; 
Drawable drawable; 
int x , y ; 

unsigned int width, height; 
unsigned long plane_mask; 
int format; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

drawable Specifies the drawable to get the data from. 

x Specify the x and y coordinates of the upper-left corner of the rectangle, rela- 

y live to the origin of the drawable. 

wi dth Specify the width and height in pixels of the image. 

height 

plane_mask Specifies a plane mask that indicates which planes are represented in the 
image. 

format Specifies the format for the image. Pass either XYPixmap or ZPixmap. 

Description 

XGetlmage dumps the contents of the specified rectangle, a drawable, into a client-side Xlm 
age structure, in the format you specify. Depending on which format you pass to the format 
argument, the function does the following: 

If the format is XYP ixmap 

Gets only the bit planes you passed to the plane_mask argument. 
If the format is ZP ixmap 

Sets to the bits in all planes not specified in the plane_mask argument. The function 
performs no range checking on the values in plane_mask, and ignores extraneous bits. 

XGetlmage returns the depth of the image to the depth member of the ximage structure. 
This depth is as specified when the drawable was created. 

If the drawable is a pixmap, the specified rectangle must be completely inside the pixmap, or a 
BadMatch error will occur, and the visual field in the image will be None. If XGetlmage 
fails, it returns NULL. If the drawable is a window, the window must be viewable, and the speci 
fied rectangle must not go off the edge of the screen. Otherwise, a BadMatch error will occur. 
If the drawable is a window, the visual argument will return the visual specified when the 
drawable was created. 



Xlib Reference Manual 225 



XGetlmage (continued) Xlib - Images 

The returned image will include any visible portions of inferiors or overlapping windows con 
tained in the rectangle. The image will not include the cursor. The specified area can include 
the borders. The returned contents of visible regions of inferiors of different depth than the 
specified window are undefined. 

If the window has a backing-store, the backing-store contents are returned for regions of the 
window that are obscured by noninferior windows. Otherwise, the return contents of such 
obscured regions are undefined. Also undefined are the returned contents of visible regions of 
inferiors of different depth than the specified window. 

The data in the image structure is stored in the server s natural byte- and bit-order. 
For more information, see Volume One, Chapter 6, Drawing Graphics and Text. 

Errors 

BadDrawable 

BadMatch See Description above. 

BadValue 

Related Commands 

ImageByteOrder, XAddPixel, XCreatelmage, XDestroy Image, XGetPixel, 
XGetSublmage, XPutlmage, XPutPixel, XSub Image. 



Xlib Reference Manual 



Xllb -Input Handling- 



J XGetlnputFocus 



Name 

XGetlnputFocus return the current keyboard focus window. 

Synopsis 

XGetlnputFocus (display, focus, revert_to) 
Display *display; 

window * focus; /* RETURN */ 

int *revert_to; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

focus Returns the ID of the focus window, or one of the constants PointerRoot 

or None. 

revert_to Returns the window to which the focus would revert if the focus window 
became invisible. This is one of these constants: Re vert TOP a rent, 
RevertToPointerRoot, or RevertToNone. Must not be a window ID. 

Description 

XGetlnputFocus returns the current keyboard focus window and the window to which the 
focus would revert if the focus window became invisible. 

XGetlnputFocus does not report the last focus change time. This is available only from 
Focus In and FocusOut events. 

Related Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued, 
XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeek- 
If Event, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSetlnput- 
Focus, XSynchronize, XWindowEvent. 



Xlib Reference Manual 227 



XGetKeyboardControl 



Xlib - User Preferences 



Name 

XGetKeyboardControl obtain a list of the current keyboard preferences. 

Synopsis 

XGetKeyboardControl (display, values) 
Display *display; 
XKeyboardState *values; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

values Returns filled XKeyboardState structure. 

Description 

XGetKeyboardControl returns the current control values for the keyboard. For the LEDs 
(light emitting diodes), the least significant bit of led_jnask corresponds to LED 1, and each 
bit that is set to 1 in led_mask indicates an LED that is lit. auto_repeats is a bit vector; 
each bit that is set to 1 indicates that auto-repeat is enabled for the corresponding key. The vec 
tor is represented as 32 bytes. Byte N (from 0) contains the bits for keys 8N to 8N+7, with the 
least significant bit in the byte representing key 8N. global_auto_repeat is either 
AutoRepeatModeOn or AutoRepeatModeOf f . 

For the ranges of each member of XKeyboardState, see the description of XChange- 
PointerControl. 

For more information, see Volume One, Chapter 9, The Keyboard and Pointer. 
Structures 

typedef struct { 

int key_click_percent; 

int bell_percent; 

unsigned int bell_pitch, bell_duration; 

unsigned long led_mask; 

int global_auto_repeat ; 

char auto_repeats [32] ; 
} XKeyboardState; 

Related Commands 

XAutoRepeatOf f , XAutoRepeatOn, XBell, XChangeKeyboardControl, XGet- 
Def ault, XGetPointerControl. 



Xlib Reference Manual 



Xlib- Keyboard 



/ XGetKeyboardMapping 



Name 

XGetKeyboardMapping return symbols for keycodes. 
Synopsis 

KeySym *XGetKeyboardMapping ( display, first_keycode, 

keycode_count , keysyms_per_keycode) 
Display * display ; 
KeyCode first_keycode; 
int keycode_count ; 
int *keysyms_per_keycode; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 
first_keycode 

Specifies the first keycode that is to be returned. 

keycode_count 

Specifies the number of keycodes that are to be returned. 

eysyms_per_.keycode 

Returns the number of keysyms per keycode. 

Description 

Starting with first_keycode, XGetKeyboardMapping returns the symbols for the 
specified number of keycodes. The specified first_keycode must be greater than or equal 
to min_keycode as returned by XDisplayKeycodes, otherwise a BadValue error 
occurs. In addition, the following expression must be less than or equal to max_keycode 
(also returned by XDisplayKeycodes) as returned in the Display structure, otherwise a 
BadValue error occurs: 

first_keycode + keycode_count - 1 
The number of elements in the keysyms list is: 

keycode_count * keysyms_per_keycode 

Then, keysym number N (counting from 0) for keycode K has an index (counting from 0) of the 
following (in keysyms): 

(K - first_keycode) * keysyms_per_keycode + N 

The keysyms_per_keycode value is chosen arbitrarily by the server to be large enough to 
report all requested symbols. A special KeySym value of NoSymbol is used to fill in unused 
elements for individual keycodes. 

Use XFree to free the returned keysym list when you no longer need it. 

For more information, see Volume One, Chapter 9, The Keyboard and Pointer. 



Xlib Reference Manual 229 



XGetKeyboardMapping (continued) Xlib - Keyboard 

Errors 

BadValue first_keycode less than display->min_keycode . 

display->max_keycode exceeded. 

Related Commands 

XChangeKeyboardMapping, XDeleteModif iermapEntry, XFreeModif iermap, 
XGetModif ierMapping, XInsertModif iermapEntry, XKeycodeToKeysym, 
XKeysymToKeycode, XKeysymToString, XLookupKeysym, XLookupString, 
XNewModif ierMap, XQueryKeymap, XRebindKeySym, XRef reshKeyboard- 
Mapping, XSetModif ierMapping, XStringToKeysym. 



230 Xlib Reference Manual 



X Programming Library- 



J XGetModifierMapping 



Name 

XGetModifierMapping obtain a mapping of modifier keys (Shift, Control, etc.). 
Synopsis 

XModifierKeymap *XGetModif ierMapping (display) 
Display *display; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

Description 

XGetModifierMapping returns the keycodes of the keys being used as modifiers. 

There are eight modifiers, represented by the symbols Shif tMapindex, LockMapindex, 
ControlMapIndex, ModlMapIndex, Mod2MapIndex, ModSMapIndex, Mod4Map- 
Index, and ModSMapIndex. The modif iermap member of the XModifierKeymap 
structure contains eight sets of keycodes, each set containing max_keypermod keycodes. 
Zero keycodes are not meaningful. If an entire modif iermap is filled with zero s, the corre 
sponding modifier is disabled. No keycode will appear twice anywhere in the map. 

Structures 

typedef struct { 

int max keypermod; /* server s max number of keys per modifier */ 
KeyCode *modif iermap; /* an 8 by max_keypermod array of 

* keycodes to be used as modifiers */ 

} XModifierKeymap; 

/* modifier names. Used to build a SetModif ierMapping request or 

to read a GetModif ierMapping request. */ 
#define ShiftMapIndex 
#define LockMapindex 1 

#define ControlMapIndex 2 

#define ModlMapIndex 3 
#define Mod2MapIndex 4 
#define ModSMapIndex 5 
tdefine ModSMapIndex 6 
#define ModSMapIndex 7 

Related Commands 

XChangeKeyboardMapping, XDeleteModifiermapEntry, XFreeModif iermap, 
XGetKeyboardMapping, XInsertModif iermapEntry, XKeycodeToKeysym, 
XKeysymToKeycode, XKeysymToString, XLookupKeysym, XLookupString, 
XNewModif ierMap, XQueryKeymap, XRebindKeySym, XRef reshKeyboard- 
Mapping, XSetModif ierMapping, XStringToKeysym. 



Xlib Reference Manual 



XGetMotionEvents \ xlib . lnputH and,,n g - 

Name 

XGetMotionEvents get events from pointer motion history buffer. 

Synopsis 

XTimeCoord *XGetMotionEvents ( display, w, start, stop, nevents) 
Display *display; 
Window w; 
Time start, stop; 
int * nevents; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

vf Specifies the ID of the window whose associated pointer motion events will be 

returned. 

start Specify the time interval for which the events are returned from the motion his- 

stop tory buffer. Pass a time stamp (in milliseconds) or Cur rent Time. 

nevents Returns the number of events returned from the motion history buffer. 

Description 

XGetMotionEvents returns all events in the motion history buffer that fall between the 
specified start and stop times (inclusive) and that have coordinates that lie within (including 
borders) the specified window at its present placement. The x and y coordinates of the 
XTimeCoord return structure are reported relative to the origin of w. 

XGetMotionEvent returns NULL if the server does not support a motion history buffer 
(which is common), or if the start time is after the stop time, or if the start time is in the future. 
A motion history buffer is supported if XDisplayMotionBuf f erSize (display) > 0. The 
pointer position at each pointer hardware interrupt is then stored for later retrieval. 

If the start time is later than the stop time, or if the start time is in the future, no events are 
returned. If the stop time is in the future, it is equivalent to specifying the constant Cur rent - 
Time, since the server does not wait to report future events. 

Use XFree to free the returned XTimeCoord structures when they are no longer needed. 
For more information, see Volume One, Chapter 9, The Keyboard and Pointer. 

Structures 

typedef struct _XTimeCoord { 

Time time; 

short x, y; 
} XTimeCoord; 

Errors 

BadWindow 



232 Xlib Reference Manual 



Xlib - Input Handling (continued) XGetMotionEventS 

Related Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued, 
XGetlnputFocus, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeek- 
If Event, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSetlnput- 
Focus, XSynchronize, XWindowEvent. 



Xlib Reference Manual 233 



XGetNormalHints V X1|b _ Window Manager Hlms _ 

Name 

XGetNormalHints get the size hints property of a window in normal state (not zoomed or 
iconified). 

Synopsis 

Status XGetNormalHints (display, w, hints) 
Display *display; 
Window w; 
XSizeHints *hints; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the ID of the window to be queried. 

hints Returns the sizing hints for the window in its normal state. 

Description 

XGetNormalHints has been superseded by XGetWMNormalHints as of Release 4, 
because new interclient communication conventions are now standard. 

XGetNormalHints returns the size hints for a window in its normal state by reading the 
XA_WM_NORMAL_HINTS property. This function is normally used only by a window manager. It 
returns a nonzero Status if it succeeds, and zero if it fails (e.g., the application specified no 
normal size hints for this window.) 

For more information on using hints, see Volume One, Chapter W, Interclient Communication. 
Structures 

typedef struct { 

long flags; /* which fields in structure are defined */ 

int x, y; 

int width, height; 

int min_width, min_height; 

int max_width, max_height; 

int width_inc, height_inc; 

struct { 

int x; /* numerator */ 

int y; /* denominator */ 
} min_aspect, max_aspect; 
} XSizeHints; 

/* flags argument in size hints */ 

ttdefine USPosition (1L O)/* user specified x, y */ 

#define USSize (1L I)/* user specified width, height */ 

#define PPosition (1L 2)/* program specified position */ 

#define PSize (1L 3)/* program specified size */ 

#define PMinSize (1L 4)/* program specified minimum size */ 

tdefine PMaxSize (1L 5)/* program specified maximum size */ 



234 Xlib Reference Manual 



Xlib - Window Manager Hints (continued) XGetNormalHintS 

tdefine PResizelnc (1L 6)/* program specified resize increments */ 
#define PAspect (1L 7)/* program specified min/max aspect ratios */ 
#def ine PAllHints (PPosition | PSize I PMinSize I PMaxSize | PResizelnc I PAspect) 

Errors 

BadWindow 

Related Commands 

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetSize- 
Hints, XGetTransientForHint, XGetWMHints, XGetZoomHints, XSetClass- 
Hint, XSetCommand, XSetlconName, XSetlconSizes, XSetNormalHints, XSet- 
SizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints, XStore- 
Name. 



Xlib Reference Manual 235 



XGetPixel 



\ 



-Xlib- Images- 



Name 

XGetPixel obtain a single pixel value from an image. 

Synopsis 

unsigned long XGetPixel (ximage, x, y) 
Xlmage * ximage; 
int x; 
int y; 



Arguments 

ximage 

x 

y 



Specifies a pointer to the image. 

Specify the x and y coordinates of the pixel whose value is to be returned. 



Description 

XGetPixel returns the specified pixel from the named image. The x and y coordinates are 
relative to the origin (upper left [0,0]) of the image). The pixel value is returned in the clients 
bit- and byte-order. The x and y coordinates must be contained in the image. 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text. 



Structures 

typedef struct _XImage { 
int width, height; 
int xoffset; 
int format; 
char *data; 
int byte_order; 
int bitmap_unit; 
int bitmap bit order; 
int bitmap_pad; 
int depth; 
int bytes_per_line; 
int bits_per_pixel; 
unsigned long red_mask; 
unsigned long green_mask; 
unsigned long blue mask; 
char *obdata; 
struct funcs { 

struct _XImage * (*create_image) () ; 

int (*destroy_image) () ; 

unsigned long (*get_pixel) () ; 

int (*put_pixel) () ; 

struct _XImage * (*sub_image) () ; 

int (*add_pixel) () ; 
} f; 
} Ximage; 



size of image */ 

number of pixels offset in X direction */ 



/* XYBitmap, XYPixmap, ZPixmap */ 



pointer to image data */ 

data byte order, LSBFirst, MSBFirst */ 

quant, of scan line 8, 16, 32 */ 

LSBFirst, MSBFirst */ 

8, 16, 32 either XY or ZPixmap */ 

depth of image */ 

accelerator to next line */ 

bits per pixel (ZPixmap) */ 

bits in z arrangment */ 



/* hook for the object routines to hang on 
/* image manipulation routines */ 



Xlib Reference Manual 



Xlib - Images (continued) XGetPixel 

Related Commands 

ImageByteOrder, XAddPixel, XCreate Image, XDestroy Image, XGetlmage, 
XGetSublmage, XPutlmage, XPutPixel, XSublmage. 



Xlib Reference Manual 237 



XGetPointerControl "\ 



Xlib- Pointer- 



Name 

XGetPointerControl get the current pointer preferences. 

Synopsis 

XGetPointerControl (display, accel_numerator, accel_denominator , 

threshold) 
Display * display ; 

int *accel_numerator f *accel_denominator; /* RETURN */ 
int * threshold; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

accel_numerator 

Returns the numerator for the acceleration multiplier. 

accel_denominator 

Returns the denominator for the acceleration multiplier. 

threshold Returns the acceleration threshold in pixels. The pointer must move more 
than this amount before acceleration takes effect. 

Description 

XGetPointerControl gets the pointer acceleration parameters. 

accel_numerator divided by accel_denominator is the number of pixels the cursor 
moves per unit of motion of the pointer, applied only to the amount of movement over 
threshold. 

Related Commands 

XChangeActivePointerGrab, XChangePointerControl, XGetPointer- 
Mapping, XGrabPointer, XQueryPointer, XSetPointerMapping, XUngrab- 
Pointer, XWarpPointer. 



Xlib Reference Manual 



Xlib -Pointer 



J XGetPointerMapping 



Name 

XGetPointerMapping get the pointer button mapping. 

Synopsis 

int XGetPointerMapping ( display, map, nmap) 
Display * display; 

unsigned char map [ ] ; /* RETURN */ 
int nmap ; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenDisplay. 

map Returns the mapping list. Array begins with map [ ] . 

nmap Specifies the number of items in mapping list. 

Description 

XGetPointerMapping returns the current mapping of the pointer buttons. Information is 
returned in both the arguments and the function s return value, map is an array of the numbers 
of the buttons as they are currently mapped. Elements of the list are indexed starting from 1. 
The nominal mapping for a pointer is the identity mapping: map[i]=i. If map [3] =2, it 
means that the third physical button triggers the second logical button. 

nmap indicates the desired number of button mappings. 

The return value of the function is the actual number of elements in the pointer list, which may 
be greater or less than nmap. 

Related Commands 

XChangeActivePointerGrab, XChangePointerControl, XGetPointer- 
Control, XGrabPointer, XQueryPointer, XSetPointerMapping, XUngrab- 
Pointer, XWarpPointer. 



Xlib Reference Manual 239 



XGetRGBColOrmapS \ x,, b -W,ndow Manages- 

Name 

XGetRGBColormaps obtain the XStandardColormap structure associated with the 
specified property. 

Synopsis 

Status XGetRGBColormaps ( display, w, std_colormap, count, 

property) 
Display *display; 
Window w; 

XStandardColormap **std_col ormap; /* RETURN */ 
int * count; /* RETURN */ 

Atom property; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window. 

std_col ormap 

Returns the XStandardColormap structure. 

count Returns the number of colormaps . 

property Specifies the property name. 

Availability 

Release 4 and later. 

Description 

XGetRGBColormaps 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, XGetRGBColormaps allocates and fills in 
space for the returned colormaps, and returns a non-zero status. Otherwise, none of the fields 
are set, and XGetRGBColormaps returns a zero status. If the visualid field is not present, 
XGetRGBColormaps assumes the default visual for the screen on which the window is 
located; if the killid field is not present, it is assumed to have a value of None, which indicates 
that the resources cannot be released. Note that it is the caller s responsibility to honor the 
ICCCM restriction that only RGB_DEFAULT_MAP contain more than one definition. 

XGetRGBColormaps supersedes XGetStandardColormap. 
For more information, see Volume One, Chapter 7, Color. 

Structures 

typedef struct { 

Colormap colormap; 
unsigned long red_max; 
unsigned long red_mult; 
unsigned long green max; 



Xlib Reference Manual 



Xlib - Window Manager Hints (continued) XGetRGBColormaps 

unsigned long green_mult; 
unsigned long blue_max; 
unsigned long blue_mult; 
unsigned long base_pixel; 

VisuallD visualid; /* added by ICCCM version 1 */ 

XID killid; /* added by ICCCM version 1 */ 

} XStandardColormap; 

Errors 

BadAtom 
BadWindow 

Related Commands 

XAllocStandardColormap, XSetRGBColormaps. 



Xlib Reference Manual 24 1 



XGetScreenSaver \. 



Xllb - Screen Saver 



Name 

XGetScreenSaver get the current screen saver parameters. 

Synopsis 

XGetScreenSaver ( display, timeout, interval, prefer_blanking, 

allow_exposures) 
Display * display; 

int *timeout, * interval ; /* RETURN */ 
int *prefer_blanking; /* RETURN */ 

int *allow_exposures; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XQpenDisplay. 

timeout Returns the idle time, in seconds, until the screen saver turns on. 

interval Returns the interval between screen changes, in seconds. 

prefer_blanking 

Returns the current screen blanking preference, one of these constants: 
DontPref erBlanking, Pref erBlanking, or Def aultBlanking. 

allotvr_exposures 

Returns the current screen save control value, either DontAl low- 
Exposures, AllowExposures, or Def aultExposures. 

Description 

XGetScreenSaver returns the current settings of the screen saver, which may be set with 

XSet ScreenSaver. 

A positive timeout indicates that the screen saver is enabled. A timeout of zero indicates 
that the screen saver is disabled. 

If the server-dependent screen saver method supports periodic change, interval serves as a 
hint about the length of the change period, and zero serves as a hint that no periodic change 
will be made. An interval of zero indicates that random pattern motion is disabled. 

For more information on the screen saver, see Volume One, Chapter 13, Other Programming 
Techniques. 

Related Commands 

XActivateScreenSaver, XForceScreenSaver, XResetScreenSaver, XSet- 
ScreenSaver. 



242 Xlib Reference Manual 



Xlib -Selections- 



J XGetSelectionOwner 



Name 

XGetSelectionOwner return the owner of a selection. 

Synopsis 

Window XGetSelectionOwner ( display, selection) 
Display * display; 
Atom selection; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

select i on Specifies the selection atom whose owner you want returned. 
Description 

XGetSelectionOwner returns the window ID of the current owner of the specified selec 
tion. If no selection was specified, or there is no owner, the function returns the constant None, 

For more information on selections, see Volume One, Chapter WJnterclient Communication. 
Errors 

BadAtom 

Related Commands 

XConvert Select ion, XSet Select ionOwner. 



Xlib Reference Manual 243 



X,,b-W,ndowMan ag er ,,- 

Name 

XGetSizeHintS read any property of type XA_SIZE_HINTS. 

Synopsis 

Status XGetSizeHintS ( display, w, hints, property) 
Display *display; 
Window w; 

XSizeHints *hints; /* RETURN */ 
Atom property; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenD i sp 1 ay . 

w Specifies the ID of the window for which size hints will be returned. 

hints Returns the size hints structure. 

property Specifies a property atom of type XA_WM_SIZE_HINTS. May be 
XA_WM_NORMAL_HINTS, XA_WM_ZOOM_HINTS (in Release 3), or a property 
defined by an application. 

Description 

XGetSizeHintS has been superseded by XGetWMSizeHints as of Release 4, because the 
interclient communication conventions are now standard. 

XGetSizeHintS returns the XSizeHints structure for the named property and the speci 
fied window. This is used by XGetNormalHints and XGetZoomHints, and can be used to 
retrieve the value of any property of type XA_WM_SIZE_HINTS; thus, it is useful if other proper 
ties of that type get defined. This function is used almost exclusively by window managers. 

XGetSizeHintS returns a nonzero Status if a size hint was defined, and zero otherwise. 
For more information on using hints, see Volume One, Chapter 10, Interclient Communication. 

Structures 

typedef struct { 

long flags; /* which fields in structure are defined */ 

int x, y; 

int width, height; 

int min_width, min_height; 

int max_width, max_height; 

int width_inc, height_inc; 

struct { 

int x; /* numerator */ 

int y; /* denominator */ 
} min_aspect, max_aspect; 
} XSizeHints; 

/* flags argument in size hints */ 

#define USPosition (1L 0) /* user specified x, y */ 

#define USSize (1L 1) /* user specified width, height */ 



244 Xlib Reference Manual 



Xlib - Window Manager Hints 



(continued) 



XGetSizeHints 



#define PPosition (1L 2) /* program specified position */ 



#define PSize (1L 3) A 

tdefine PMinSize (1L 4) / 

#define PMaxSize (1L 5) / 

tfdefine PResizelnc (1L 6) / 

#define PAspect (1L 7) / 



program specified size */ 
program specified minimum size */ 
program specified maximum size */ 
program specified resize increments */ 
program specified min/max aspect ratios */ 



tdefine PAllHints (PPosition | PSize I PMinSize I PMaxSize I PResizelnc I PAspect) 

Errors 

BadAtom 
BadWindow 

Related Commands 

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal- 
Hints, XGetTransientForHint, XGetWMHints, XGetZoomHints, XSetClass- 
Hint, XSet Command, XSetlconName, XSetlconSizes, XSetNormalHints, XSet- 
SizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints, XStore- 
Name. 



Xlib Reference Manual 



245 



XGetStandardColormap \ X1|b _ Colormaps _ 

Name 

XGetStandardColormap get the standard colormap property. 

Synopsis 

Status XGetStandardColormap ( display, w, cmap_info, property) 
Display * display; 
Window w; 

XStandardColormap *cmap_info; /* RETURN */ 
Atom property; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenD i sp 1 ay . 

w Specifies the ID of the window on which the property is set. This is normally 

the root window. 

cmap_info Returns the filled colormap information structure. 

property Specifies the atom indicating the type of standard colormap desired. The 
predefined standard colormap atoms are XA_RGB_BEST_MAP, 

XA_RGB_RED_MAP, XA_RGB_GREEN_MAP, XA_RGB_BLUE_MAP , 
XA_RGB_DEFAULT_MAP, and XA_RGB_GRAY_MAP . 

Description 

XGetStandardColormap is superseded by XGetWMColormap in Release 4. 

XGetStandardColormap gets a property on the root window that describes a standard 
colormap. 

This call does not install the colormap into the hardware colormap, it does not allocate entries, 
and it does not even create a virtual colormap. It just provides information about one design of 
colormap and the ID of the colormap if some other client has already created it. The applica 
tion can otherwise attempt to create a virtual colormap of the appropriate type, and allocate its 
entries according to the information in the XStandardColormap structure. Installing the 
colormap must then be done with XlnstallColormap, in cooperation with the window 
manager. Any of these steps could fail, and the application should be prepared. 

If the server or another client has already created a standard colormap of this type, then its ID 
will be returned in the colormap member of the XStandardColormap structure. Some 
servers and window managers, particular on high-performance workstations, will create some 
or all of the standard colormaps so they can be quickly installed when needed by applications. 

An application should go through the standard colormap creation process only if it needs the 
special qualities of the standard colormaps. For one, they allow the application to convert RGB 
values into pixel values quickly because the mapping is predictable. Given an XStandard 
Colormap structure for an XA_RGB_BEST_MAP colormap, and floating point RGB coefficients 
in the range 0.0 to 1.0, you can compose pixel values with the following C expression: 



246 Xlib Reference Manual 



xiib - coiormaps (continued) XGetStandardColormap 

pixel = base_pixel 

+ ((unsigned long) (0.5 + r * red_max) ) * red_mult 

+ ((unsigned long) (0.5 + g * green_max) ) * greenjmult 

+ ((unsigned long) (0.5 + b * blue_max) ) * blue_mult; 

The use of addition rather than logical-OR for composing pixel values permits allocations 
where the RGB value is not aligned to bit boundaries. 

XGetStandardColormap returns zero if it fails, or nonzero if it succeeds. 

See Volume One, Chapter 7, Color, for a complete description of standard coiormaps. 

Structures 

typedef struct { 

Colormap colormap; /* ID of colormap created by XCreateColormap */ 

unsigned long red_max; 

unsigned long red_mult; 

unsigned long green_max; 

unsigned long green_mult; 

unsigned long blue_max; 

unsigned long blue_mult; 

unsigned long base_pixel; 

/* new fields here in R4 */ 
} XStandardColormap; 

Errors 

BadAtom 
BadWindow 

Related Commands 

Def aultColormap, Display-Cells, XCopyColormapAndFree, XCreate 
Colormap, XFreeColormap, XInstallColormap, XListlnstalledColormaps, 
XSetStandardColormap, XSetWindowColormap, XUninstallColormap. 



Xlib Reference Manual 247 



XGetSublmage \ xnt >. tmages - 

Name 

XGetSublmage copy a rectangle in drawable to a location within the pre-existing image. 
Synopsis 

Xlmage *XGetSubImage ( display, drawable , x, y, width, height, 

plane_mask, format, dest_image, dest_x, dest_y) 
Display * display; 
Drawable drawable; 
int x, y; 

unsigned int width, height; 
unsigned long plane_mask; 
int format; 
Xlmage *dest_image; 
int dest_x, dest_y; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

drawabl e Specifies the drawable from which the rectangle is to be copied. 

x Specify the x and y coordinates of the upper-left corner of the rectangle, rela- 

y live to the origin of the drawable. 

width Specify the width and height in pixels of the subimage taken. 

height 

plane_mask Specifies which planes of the drawable are transferred to the image. 
format Specifies the format for the image. Either XYPixmap or ZPixmap. 

dest_image Specifies the the destination image. 

dest_x Specify the x and y coordinates of the destination rectangle s upper left cor- 

dest_y ner, relative to the image s origin. 

Description 

XGetSublmage updates the dest_image with the specified subimage in the same manner 
as XGet image, except that it does not create the image or necessarily fill the entire image. If 
format is XYPixmap, the function transmits only the bit planes you specify in 
plane_mask. If format is ZPixmap, the function transmits as zero the bits in all planes 
not specified in plane_mask. The function performs no range checking on the values in 
plane_mask and ignores extraneous bits. 

The depth of the destination x image structure must be the same as that of the drawable. 
Otherwise, a BadMatch error is generated. If the specified subimage does not fit at the speci 
fied location on the destination image, the right and bottom edges are clipped. If the drawable 
is a window, the window must be mapped or held in backing store, 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. Otherwise, a BadMatch error is generated. 



248 Xlib Reference Manual 



Xlib - Images (continued) XGetSublmage 

If the window has a backing store, the backing store contents are returned for regions of the 
window that are obscured by noninferior windows. Otherwise, the return contents of such 
obscured regions are undefined. Also undefined are the returned contents of visible regions of 
inferiors of different depth than the specified window. 

XSub Image extracts a subimage from an image, instead of from a drawable like XGetSub 
lmage. 

For more information on images, see Volume One, Chapter 6, Drawing Graphics and Text. 

Errors 

BadDrawable 

BadMatch Depth of dest_i/nage is not the same as depth of drawable. 
BadValue 

Related Commands 

ImageByteOrder, XAddPixel, XCreate Image, XDestroy Image, XGet Image, 
XGetPixel, XPutlmage, XPutPixel, XSublmage. 



Xlib Reference Manual 249 



XGetTeXtPrOperty \ x,,b-W,ndow Manager H,n,s- 

Name 

XGetTextProperty read one of a window s text properties. 

Synopsis 

Status XGetTextProperty ( display, w r text_prop f property) 
Display ^display; 
Window w; 

XTextProperty *text_prop; /* RETURN */ 
Atom property; 

Arguments 

display Specifies a connection to an X server; returned from XQpenDisplay. 

w Specifies the window. 

text_prop Returns the XTextProperty structure. 

property Specifies the property name. 

Availability 

Release 4 and later. 

Description 

XGetTextProperty reads the specified property from the window and stores the data in the 
returned XTextProperty structure. It stores the data in the value field, the type of the data 
in the encoding field, the format of the data in the format field, and the number of items of 
data in the nit ems field. The particular interpretation of the property s encoding and data as 
"text" is left to the calling application. If the specified property does not exist on the window, 
XGetTextProperty sets the value field to NULL, the encoding field to None, the format 
field to zero, and the nit ems field to zero. 

If it was able to set these files in the XTextProperty structure, XGetTextProperty 
returns a non-zero status; otherwise, it returns a zero status. 

For more information, see Volume One, Chapter 10, Interclient Communication. 
Structures 

typedef struct { 

unsigned char *value; /* same as Property routines */ 

Atom encoding; /* prop type */ 

int format; /* prop data format: 8, 16, or 32 */ 

unsigned long nitems; /* number of data items in value */ 
} XTextProperty; 

Errors 

BadAtom 
BadWindow 



250 xiib Reference Manual 



Xlib - Window Manager Hints (continued) XGetTextPfOperty 

Related Commands 

XFreeStringList, XSetTextProperty, XStringListToTextProperty, XText- 
PropertytoStringList. 



Xlib Reference Manual 25 1 



XGetTransientForHint 



Name 

XGetTransientForHint get the XA_WM_TRANSIENT_FOR property of a window. 

Synopsis 

Status XGetTransientForHint ( display, w, prop_window) 
Display * display; 
Window w; 
Window *prop_nrindow; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

w Specifies the ID of the window to be queried. 

prop_window Returns the window contained in the XA_WM_TRANSIENT_FOR property of the 
specified window. 

Description 

XGetTransientForHint obtains the XA_WM_TRANSIENT_FOR property for the specified 
window. This function is normally used by a window manager. This property should be set for 
windows that are to appear only temporarily on the screen, such as pop-up dialog boxes. The 
window returned is the main window to which this popup window is related. This lets the win 
dow manager decorate the popup window appropriately. 

XGetTransientForHint returns a Status of zero on failure, and nonzero on success. 
For more information on using hints, see Volume One, Chapter W,Interclient Communication. 

Errors 

BadWindow 

Related Commands 

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal- 
Hints, XGetSizeHints, XGetWMHints, XGetZoomHints, XSetClassHint, XSet- 
Command, XSetlconName, XSetlconSizes, XSetNormalHints, XSetSizeHints, 
XSetTransientForHint, XSetWMHints, XSetZoomHints, XStoreName. 



252 Xlib Reference Manual 



-xiib-visuais / XGetVisuallnfo 

Name 

XGetVisuallnfo find the visual information structures that match the specified template. 

Synopsis 

XVisuallnfo *XGetVisualInfo ( display, vinfo_mask, 

vinfo_template, nitems) 
Display * display ; 
long vinfo_mask; 
XVisuallnfo *vinfo_template; 
int * nitems; /* RETURN */ 

Arguments 

di splay Specifies a connection to an X server; returned from XOpenDisplay. 

vinfo_mask Specifies the visual mask value. Indicates which elements in template are to 
be matched. 

vi n f o_ t empl a t e 

Specifies the visual attributes that are to be used in matching the visual struc 
tures. 

nitems Returns the number of matching visual structures. 

Description 

XGetVisuallnfo returns a list of visual structures that describe visuals supported by the 
server and that match the attributes specified by the vinfo_ template argument. If no 
visual structures match the template, XGetVisuallnfo returns a NULL. To free the data 
returned by this function, use XFree. 

For more information, see Volume One, Chapter 7, Color. 
Structures 

typedef struct { 

Visual *visuai; 

VisuallD visualid; 

int screen; 

unsigned int depth; 

int class; 

unsigned long red_mask; 

unsigned long green_mask; 

unsigned long blue_mask; 

int colormap_size; 

int bits_per_rgb; 
} XVisuallnfo"; 

/* The symbols for the vinfo_mask argument are: */ 

tdefine VisualNoMask 0x0 

#define VisuallDMask Oxl 

tfdefine VisualScreenMask 0x2 



Xlib Reference Manual 



XGetViSUallnfO (continued) Xlib- Visuals 

#define VisualDepthMask 0x4 

#define VisualClassMask 0x8 

#define VisualRedMaskMask 0x10 

tdefine VisualGreenMaskMask 0x20 

#define VisualBlueMaskMask 0x40 

#define VisualColormapSizeMask 0x80 

#define VisualBitsPerRGBMask 0x100 

tdefine VisualAllMask OxlFF 

Related Commands 

Def aultVisual, XVisuallDFromVisual, XMatchVisuallnf o, XListDepths. 



254 Xlib Reference Manual 



-Xlib- Window Manager Hints XGetWMICOnName 

Name 

XGetWMIconName read a window s XA_WM_ICON_NAME property. 

Synopsis 

Status XGetWMIconName ( display, w, text_prop) 
Display *display; 
Window w; 
XTextProperty *text_prop; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XQpenDisplay. 

w Specifies the window. 

text_prop Returns the XTextProperty structure. 

Availability 

Release 4 and later. 

Description 

XGetWMIconName performs an XGet Text Property on the XA_WM_ICON_NAME property 
of the specified window. XGetWMIconName supersedes XGetlconName. 

This function is primarily used by window managers to get the name to be written in a win 
dow s icon when they need to display that icon. 

For more information, see Volume One, Chapter WJnterclient Communication. 
Structures 

typedef struct { 

unsigned char *value; /* same as Property routines */ 

Atom encoding; /* prop type */ 

int format; /* prop data format: 8, 16, or 32 */ 

unsigned long nitems; /* number of data items in value */ 
} XTextProperty; 

Related Commands 

XGetWMName, XSetWMIconName, XSetWMName, XSetWMProperties. 



Xlib Reference Manual 255 



XGetWMName V 

v Xlib - Window Manager Hints- 
Name 

XGetWMName read a window s XA_WM_NAME property. 

Synopsis 

Status XGetWMName ( display r w, text_prop) 
Display * display; 
Window w; 
XTextProperty *text_prop; /* RETURN */ 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenD i splay. 

w Specifies the window. 

text_prop Returns the XTextProperty structure. 

Availability 

Release 4 and later. 

Description 

XGetWMName performs an XGetTextProperty on the XA_WM_NAME property of the speci 
fied window. XGetWMName supersedes XFetchName. 

XGetWMName returns nonzero if it succeeds, and zero if the property has not been set for the 
argument window. 

For more information, see Volume One, Chapter WJnterclient Communication. 
Structures 

typedef struct { 

unsigned char *value; /* same as Property routines */ 

Atom encoding; /* prop type */ 

int format; /* prop data format: 8, 16, or 32 */ 

unsigned long nitems; /* number of data items in value */ 
} XTextProperty; 

Related Commands 

XGetWMIconName, XSetWMIconName, XSetWMName, XSetWMProperties. 



256 xiib Reference Manual 



-XHb-WindowManager Hints XGetWMNormalHintS 

Name 

XGetWMNormalHintS read a window s XA_WM_NORMAL_HINTS property. 

Synopsis 

Status XGetWMNormalHintS (display, w, hints, supplied) 
Display *display; 
Window w; 

XSizeHints *hints;/* RETURN */ 
long * supplied; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window. 

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

supplied Returns the hints that were supplied by the user. 

Availability 

Release 4 and later. 

Description 

XGetWMNormalHintS returns the size hints stored in the XA_WM_NORMAL_HINTS property on 
the specified window. If the property is of type XA_WM_SIZE_HINTS, of format 32, and is long 
enough to contain either an old (pre-ICCCM) or new size hints structure, XGetWMNormal 
HintS sets the various fields of the XSizeHints structure, sets the supplied argument to 
the list of fields that were supplied by the user (whether or not they contained defined values) 
and returns a non-zero status. XGetWMNormalHintS returns a zero status if the application 
specified no normal size hints for this window. 

XGetWMNormalHintS supersedes XGetNormalHints. 

If XGetWMNormalHintS returns successfully and a pre-ICCCM size hints property is read, 
the supplied argument will contain the following bits: 

(USPosition|USSize|PPosition|PSize|PMinSize| PMaxSize I PResizelnc I PAspect) 

If the property is large enough to contain the base size and window gravity fields as well, the 
supplied argument will also contain the following bits: 

(PBaseSize | PWinGravity) 

This function is normally used only by a window manager. 

For more information, see Volume One, Chapter lOJnterclient Communication. 

Structures 

typedef struct { 

long flags; /* marks which fields in this structure are defined */ 
int x, y; /* obsolete for new window mgrs, but clients */ 



Xlib Reference Manual 257 



XGetWMNormalHintS (continued) Xlib - Window Manager Hints 

int width, height; /* should set so old wm s don t mess up */ 
int min_width, min_height; 
int max_width, max_height; 
int width_inc, height_inc; 
struct { 

int x; /* numerator */ 

int y; /* denominator */ 
} min_aspect, max_aspect; 

int base_width, base_height; /* added by ICCCM version I */ 

int win_gravity; /* added by ICCCM 

version 1 */ 
} XSizeHints; 

Errors 

BadWindow 

Related Commands 

XAllocSizeHints, XGetWMSizeHints, XSetWMNormalHints, XSet- 
WMProperties, XSetWMSizeHints. 



255 Xlib Reference Manual 



-Xllb- Window Manager Hints / XGetWMSizeHintS 

Name 

XGetWMSizeHintS read a window s XA_WM_SIZE_HINTS property. 

Synopsis 

Status XGetWMSizeHintS (display, w, hints, supplied, property) 
Display * display; 
Window w; 

XSizeHints *hints; /* RETURN */ 

long * supplied; /*RETURN */ 

Atom property; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

w Specifies the window. 

hints Returns the XSizeHints structure. 

supplied Returns the hints that were supplied by the user. 

property Specifies the property name. 

Availability 

Release 4 and later. 

Description 

XGetWMSizeHintS returns the size hints stored in the specified property on the named win 
dow. If the property is of type XA_WM_SIZE_HINTS, of format 32, and is long enough to con 
tain either an old (pre-ICCCM) or new size hints structure, XGetWMSizeHintS sets the vari 
ous fields of the XSizeHints structure, sets the supplied argument to the list of fields that 
were supplied by the user (whether or not they contained defined values), and returns a non 
zero status. If the hint was not set, it returns a zero status. To get a window s normal size hints, 
you can use the XGetWMNormalHints function instead. 

XGetWMSizeHintS supersedes XGetSizeHints. 

If XGetWMSizeHintS returns successfully and a pre-ICCCM size hints property is read, the 
supplied argument will contain the following bits: 

(USPosition I USSize IPPosition I P Size IPMinSize I PMaxSize I PResizelnc I P Aspect) 

If the property is large enough to contain the base size and window gravity fields as well, the 
supplied argument will also contain the following bits: 

(PBaseSize I PWinGravity) 

This function is used almost exclusively by window managers. 

For more information, see Volume One, Chapter W,Interclient Communication. 



Xlib Reference Manual 259 



XGetWMSizeHintS (continued) Xlib - Window Manager Hints 

Structures 

typedef struct { 

long flags; /* marks which fields in this structure are defined */ 

int x, y; /* obsolete for new window mgrs, but clients */ 

int width, height; /* should set so old wm s don t mess up */ 

int min_width, min_height; 

int max_width, max_height; 

int width_inc, height_inc; 

struct { 

int x; /* numerator */ 

int y; /* denominator */ 
} min_aspect, max_aspect; 

int base_width, base_height; /* added by ICCCM version 1 */ 

int win_gravity; /* added by ICCCM version 1 */ 

} XSizeHints; 

Errors 

BadAtom 
BadWindow 

Related Commands 

XAllocSizeHints, XGetWMNormalHints, XSetWMNormalHints, XSetWMSize- 
Hints. 



260 Xlib Reference Manual 



/ 



XGetWindowAtlributes 



Name 

XGetWindow Attributes obtain the current attributes of window. 
Synopsis 

Status XGetWindowAt tributes (display, w, window_attributes) 
Display *display; 
Window w; 
XWindowAttributes *window_attributes ; /* RETURN */ 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window whose current attributes you want. 

window_at tributes 

Returns a filled XWindowAttributes structure, containing the current attri 
butes for the specified window. 

Description 

XGetwindowAttributes returns the XWindowAttributes structure containing the cur 
rent window attributes. 

While w is defined as type window, a Pixmap can also be used, in which case all the returned 
members will be zero except width, height, depth, and screen. 

XGetwindowAttributes returns a Status of zero on failure, or nonzero on success. 
However, it will only return zero if you have defined an error handler that does not exit, using 
xSetErrorHandler. The default error handler exits, and therefore XGetwindow 
Attributes never gets a chance to return. (This is relevant only if you are writing a window 
manager or other application that deals with windows that might have been destroyed.) 

The following list briefly describes each member of the XWindowAttributes structure. For 
more information, see Volume One, Chapter 4, Window Attributes. 

x, y The current position of the upper-left pixel of the window s border, relative 

to the origin of its parent. 

width, height The current dimensions in pixels of this window. 

border_width The current border width of the window. 

depth The number of bits per pixel in this window. 

visual The visual structure. 

root The root window ID of the screen containing the window. 

class The window class. One of these constants: InputOutput or Input- 

Only. 

bit_gravity The new position for existing contents after resize. One of the constants 
ForgetGravity, StaticGravity, or CenterGravity, or one of 
the compass constants (NorthWestGravity, NorthGravity, etc.). 



Xlib Reference Manual 26 1 



X Get Window Attributes (continued) Xlib - Window Attributes 

win_gravity The new position for this window after its parent is resized. One of the 
constants CenterGravity, UnmapGravity, StaticGravity, or 
one of the compass constants. 

backing_store When to maintain contents of the window. One of these constants: Not- 
Usef ul, WhenMapped, or Always. 

backing_jplanes 

The bit planes to be preserved in a backing store. 

backing_jpixel The pixel value used when restoring planes from a partial backing store. 

save_under A boolean value, indicating whether saving bits under this window would 
be useful. 

colormap The colormap ID being used in this window, or None. 

map_installed A boolean value, indicating whether the colormap is currently installed. If 
True, the window is being displayed in its chosen colors. 

map_state The window s map state. One of these constants: isUnmapped, Is- 

Unviewable, or IsViewable. IsUnviewable indicates that the 
specified window is mapped but some ancestor is unmapped. 

a 1 l_e ve n t_ma s k s 

The set of events any client have selected. This member is the bitwise 
inclusive OR of all event masks selected on the window by all clients. 

your_event_mask 

The bitwise inclusive OR of all event mask symbols selected by the query 
ing client. 

do_not_propagate_mask 

The bitwise inclusive OR of the event mask symbols that specify the set of 
events that should not propagate. This is global across all clients. 

override_redirect 

A boolean value, indicating whether this window will override structure 
control facilities. This is usually only used for temporary pop-up windows 
such as menus. Either True or False. 

screen A pointer to the Screen structure for the screen containing this window. 

Errors 

BadWindow 

Structures 

The xwindowAttributes structure contains: 

typedef struct { 

int x, y; /* location of window */ 

int width, height; /* width and height of window */ 

int border_width; /* border width of window */ 

int depth; /* depth of window */ 



262 Xlib Reference Manual 



Xlib - Window Attributes 



(continued) 



XGetWindowAttributes 



Visual *visual; /* 

Window root; /* 

int class; /* 

int bit_gravity; /* 

int win_gravity; /* 

int backing_store; /* 
unsigned long backing_planes; /* 

unsigned long backing_pixel; /* 

Bool save_under; /* 

Colormap colormap; /* 

Bool map_installed; /* 

int map_state; /* 

long all_event_masks; /* 

long your_event_mask; /* 

long do_not_propagate_mask; /* 

Bool override_redirect; /* 

Screen *screen; /* 
} XWindowAttributes; 



the associated visual structure */ 
root of screen containing window */ 
InputOutput, InputOnly*/ 
one of bit gravity values */ 
one of the window gravity values */ 
NotUseful, WhenMapped, Always */ 
planes to be preserved if possible */ 
value to be used when restoring planes */ 
boolean, should bits under be saved */ 
colormap to be associated with window */ 
boolean, is colormap currently installed*/ 
IsUnmapped, IsUnviewable, IsViewable */ 
set of events all people have interest in*/ 
my event mask */ 

set of events that should not propagate */ 
boolean value for override-redirect */ 
pointer to correct screen */ 



Related Commands 

XChangeWindowAttributes, XGetGeometry, XSetWindowBackground, XSet- 
WindowBackgroundPixmap, XSetWindowBorder, XSetWindowBorderPixmap. 



Xlib Reference Manual 



263 



XGetWindowProperty \ X)|b _ Propartl8s _ 

Name 

XGetWindowProperty obtain the atom type and property format for a window. 

Synopsis 

int XGetWindowProperty ( display, w, property, long_offset, 

long_length, delete, req_type, actual_type, actual_for- 
mat , nit ems , bytes_after , prop) 
Display *display; 
Window w; 
Atom property; 

long long_offset , long_length; 
Bool delete; 
Atom req_type; 

Atom *actual_type; /* RETURN */ 

int *actual_format; /* RETURN */ 

unsigned long *nitems; /* RETURN */ 

unsigned long *bytes_after; /* RETURN */ 
unsigned char **prop; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the ID of the window whose atom type and property format you 

want to obtain. 

property Specifies the atom of the desired property. 

1 ong_offset Specifies the offset in 32-bit quantities where data will be retrieved. 

1 ong_length Specifies the length in 32-bit multiples of the data to be retrieved. 

delete Specifies a boolean value of True or False. If you pass True and a prop 

erty is returned, the property is deleted from the window after being read and 
a PropertyNotif y event is generated on the window. 

req_type Specifies an atom describing the desired format of the data. If Any- 
Proper tyType is specified, returns the property from the specified window 
regardless of its type. If a type is specified, the function returns the property 
only if its type equals the specified type. 

actual_type Returns the actual type of the property. 

actual_for/nat 

Returns the actual data type of the returned data. 

ni terns Returns the actual number of 8-, 16-, or 32-bit items returned in prop. 

bytes_after Returns the number of bytes remaining to be read in the property if a partial 
read was performed. 



264 Xlib Reference Manual 



xiib - Properties (continued) XGetWindowProperty 

prop Returns a pointer to the data actually returned, in the specified format. 

XGetWindowProperty always allocates one extra byte after the data and 
sets it to NULL. This byte is not counted in nit ems. 

Description 

XGetWindowProperty gets the value of a property if it is the desired type. XGetwindow- 
P rope rt y sets the return arguments acccording to the following rules: 

If the specified property does not exist for the specified window, then: act ual_ type is 
None; act ual_format = 0; and bytes_af ter = 0. delete is ignored in this 
case, and nit ems is empty. 

If the specified property exists, but its type does not match req_type, then: 
actual_type is the actual property type; actual_format is the actual property 
format (never zero); and bytes_after is the property length in bytes (even if 
actual_format is 16 or 32). delete is ignored in this case, and ni terns is empty. 

If the specified property exists, and either recj_type is AnyPropertyType or the 
specified type matches the actual property type, then: actual_type is the actual prop 
erty type; and actual_format is the actual property format (never zero). 
jbytes_ar"ter and nit ems are defined by combining the following values: 

N = actual length of stored property in bytes (even if act ual_format is 16 or 3 2) 
1 = 4* 1 on g_off set (convert offset from longs into bytes) 
L = MINIMUM* (N - I), 4 * long_length) (BadValue if L < 0) 
bytes_after = N - (I + L) (number of trailing unread bytes in stored property) 

The returned data (in prop) starts at byte index I in the property (indexing from 0). The 
actual length of the returned data in bytes is L. L is converted into the number of 8-, 16-, 
or 32-bit items returned by dividing by 1, 2, or 4 respectively and this value is returned in 
nitems. The number of trailing unread bytes is returned in by t es_aft er. 

If delete == True and bytes_after == the function deletes the property 
from the window and generates a PropertyNotif y event on the window. 

When XGetWindowProperty executes successfully, it returns Success. The Success 
return value and the undocumented value returned on failure are the opposite of all other rou 
tines that return int or Status. The value of Success is undocumented, but is zero (0) in 
the current sample implementation from MIT. The failure value, also undocumented, is cur 
rently one (1). Therefore, comparing either value to True or False, or using the syntax "if 
( ! XGetWindowProperty ( . . . ))" is not allowed. 

To free the resulting data, use XFree. 

For more information, see Volume One, Chapter WJnterdient Communication. 



Xlib Reference Manual 265 



XGetWindOwProperty (continued) Xlib - Properties 

Errors 

BadAtom 

BadVa lue Value of I ong_offset caused L to be negative above. 
BadWindow 

Related Commands 

XChangeProperty, XGetAtomName, XGetFontProperty, XListProperties, 
XRotateWindowProperties,XSetStandardProperties. 



Xlib Reference Manual 



-Xllb- Window Manager Hints / XGetWMHintS 

Name 

XGetWMHintS read the window manager hints property. 

Synopsis 

XWMHints *XGetWMHints (display, w) 
Display * display; 
Window w; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the ID of the window to be queried. 

Description 

This function is primarily for window managers. XGetWMHintS returns NULL if no 
XA_WM_HINTS property was set on window w, and returns a pointer to an XWMHints structure 
if it succeeds. Programs must free the space used for that structure by calling XFree. 

For more information on using hints, see Volume One, Chapter 10, Inter -client Communication. 
Structures 

typedef struct { 

long flags; /* marks which fields in this structure are defined */ 

Bool input; /* does application need window manager for input */ 

int initial_state; /* see below */ 

Pixmap icon_pixmap; /* pixmap to be used as icon */ 

Window icon_window; /* window to be used as icon */ 

int icon x, icon y; /* initial position of icon */ 

Pixmap icon_mask; /* icon mask bitmap */ 

XID window group; /* ID of related window group */ 

/* this structure may be extended in the future */ 
} XWMHints; 

/* initial state flag: */ 

#define DontCareState 

#define NormalState 1 

#define ZoomState 2 

#define IconicState 3 

#define InactiveState 4 

Errors 

BadWindow 

Related Commands 

XAllocWMHints, XFetchName, XGetClassHint, XGetlconName, XGetlcon- 
Sizes, XGetNormalHints, XGetSizeHints, XGetTransientForHint, XGet- 
ZoomHints, XSetClassHint, XSetCommand, XSetlconName, XSetlconSizes, 
XSetNormalHints, XSetSizeHints, XSetTransientForHint, XSetWMHints, 
XSetZoomHints, XStoreName, XSetWMProperties. 



Xlib Reference Manual 267 



XGetZoomHints V V1 

N Xlib - Window Manager Hints- 
Name 

XGetZoomHints read the size hints property of a zoomed window. 

Synopsis 

Status XGetZoomHints (display, w, zhints) 
Display *display; 
Window w; 
XSizeHints *zhints; /* RETURN */ 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenD i sp 1 ay . 

w Specifies the ID of the window to be queried. 

zhints Returns a pointer to the zoom hints. 

Description 

XGetZoomHints is obsolete beginning in Release 4, because zoom hints are no longer 
defined in the ICCCM. 

XGetZoomHints is primarily for window managers. XGetZoomHints returns the size 
hints for a window in its zoomed state (not normal or iconified) read from the 
XA_WM_ZOOM_HINTS property. It returns a nonzero Status if it succeeds, and zero if the 
application did not specify zoom size hints for this window. 

For more information on using hints, see Volume One, Chapter WJnterclient Communication. 
Structures 

typedef struct { 

long flags; /* which fields in structure are defined */ 

int x, y; 

int width, height; 

int min_width, min__height; 

int max_width, max_height; 

int width_inc, height_inc; 

struct { 

int x; /* numerator */ 

int y; /* denominator */ 
} min_aspect, max_aspect; 
} XSizeHints; 

/* flags argument in size hints */ 

tdefine USPosition (1L 0) /* user specified x, y */ 

#define USSize (1L 1) /* user specified width, height */ 

#define PPosition (1L 2) /* program specified position */ 

tdefine PSize (1L 3) /* program specified size */ 

tdefine PMinSize (1L 4) /* program specified minimum size */ 

#define PMaxSize (1L 5) /* program specified maximum size */ 

#define PResizelnc (1L 6) /* program specified resize increments */ 



268 Xlib Reference Manual 



Xlib - Window Manager Hints (continued) XGetZoom Hints 

#define PAspect (1L 7) /* program specified min/max aspect ratios */ 
#def ine PAllHints (PPosition I PSize I PMinSize | PMaxSize I PResizelnc I PAspect) 

Errors 

BadWindow 

Related Commands 

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal- 
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XSetClass- 
Hint, XSetCommand, XSetlconName, XSetlconSizes, XSetNormalHints, XSet- 
SizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints, XStore- 
Name. 



Xlib Reference Manual 



269 



XGrabButton V 



Name 

XGrabButton grab a pointer button. 

Synopsis 

XGrabButton ( display, button, modifiers, grab_window, 

owner_events , event_mask, pointer_mode, keyboard_mode , 
confine_to, cursor) 

Display *display; 

unsigned int button; 

unsigned int modifiers; 

Window grab_window; 

Bool owner_events ; 

unsigned int event_mask; 

int point er_mode , keyboard_mode ; 

Window confine_to; 

Cursor cursor; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

button Specifies the mouse button. May be Buttonl, Button2, Buttons, But- 

ton4, Buttons, or AnyButton. The constant AnyButton is equivalent 
to issuing the grab request for all possible buttons. The button symbols can 
not be ORed. 

modifiers Specifies a set of keymasks. This is a bitwise OR of one or more of the fol 
lowing symbols: ShiftMask, LockMask, ControlMask, ModlMask, 
Mod2Mask, ModSMask, Mod4Mask, ModSMask, or AnyModifier. 
AnyModif ier is equivalent to issuing the grab key request for all possible 
modifier combinations (including no modifiers). 

grab_window Specifies the ID of the window you want to the grab to occur in. 

owner_e vents 

Specifies a boolean value of either True or False. See Description below. 

event_mask Specifies the event mask to take effect during the grab. This mask is the bit 
wise OR of one or more of the event masks listed on the reference page for 
XSelectlnput. 

point er_mode 

Controls processing of pointer events during the grab. Pass one of these con 
stants: GrabModeSync or GrabModeAsync. 

keyboa rd_mode 

Controls processing of keyboard events during the grab. Pass one of these 
constants: GrabModeSync or GrabModeAsync. 

confine_to Specifies the ID of the window to confine the pointer. One possible value is 
the constant None, in which case the pointer is not confined to any window. 



270 Xlib Reference Manual 



Xlib- Grabbing (continued) XGrabButton 

cursor Specifies the cursor to be displayed during the grab. One possible value you 

can pass is the constant None, in which case the existing cursor is used. 

Description 

XGrabButton establishes a passive grab, such that an active grab may take place when the 
specified key/button combination is pressed in the specified window. After this call, if 

1) the specified button is pressed when the specified modifier keys are down (and no other 
buttons or modifier keys are down), 

2) grab_window contains the pointer, 

3) the confne_to window (if any) is viewable, and 

4) these constraints are not satisfied for any ancestor, 

then the pointer is actively grabbed as described in XGrabPointer, the last pointer grab time 
is set to the time at which the button was pressed, and the ButtonPress event is reported. 

The interpretation of the remaining arguments is as for XGrabPointer. The active grab is 
terminated automatically when all buttons are released (independent of the state of modifier 
keys). 

A modifier of AnyModif ier is equivalent to issuing the grab request for all possible modifier 
combinations (including no modifiers). A button of AnyButton is equivalent to issuing the 
request for all possible buttons (but at least one). 

XGrabButton overrides all previous passive grabs by the same client on the same key/button 
combination on the same window, but has no effect on an active grab. The request fails if some 
other client has already issued an XGrabButton with the same button/key combination on the 
same window. When using AnyModif ier or AnyButton, the request fails completely (no 
grabs are established) if there is a conflicting grab for any combination. 

The owner_e vents argument specifies whether the grab window should receive all events 
(False) or whether the grabbing application should receive all events normally (True). 

The pointer_mode and keyboard_mode control the processing of events during the grab. 
If either is GrabModeSync, events for that device are not sent from the server to Xlib until 
XAllowEvent s is called to release the events. If either is GrabModeAsync, events for that 
device are sent normally. 

An automatic grab takes place between a ButtonPress event and the corresponding 
ButtonRelease event, so this call is not necessary in some of the most common situations. 
But this call is necessary for certain styles of menus. 

For more information on grabbing, see Volume One, Chapter 9, The Keyboard and Pointer. 



Xlib Reference Manual 271 



XGrabButton 



(continued) 



Xlib- Grabbing 



Errors 

BadAccess When using AnyModif ier or AnyButton and there is a conflicting grab 
by another client. No grabs are established. 

Another client has already issued an XGrabButton request with the same 
key/button combination on the same window. 

BadCursor 

BadValue 

BadWindow 

Related Commands 

XChangeActivePointerGrab, XGrabKey, XGrabKeyboard, XGrabPointer, 
XGrabServer, XUngrabButton, XUngrabKey, XUngrabKeyboard, XUngrab- 
Pointer, XUngrabServer. 



272 



Xlib Reference Manual 



-xiib- Grabbing / XGrabKey 

Name 

XGrabKey grab a key. 

Synopsis 

XGrabKey (display, keycode, modifiers, grab_window , 
owner_events, pointer_mode , keyboard_mode) 
Display *display; 
int keycode ; 
unsigned int modifiers; 
Window grab_window; 
Bool owner_events ; 
int pointer_mode , keyboard_mode ; 

Arguments 

display Specifies a connection to an X server; returned from xopenDisplay. 

keycode Specifies the keycode to be grabbed. It may be a modifier key. Specifying 

AnyKey is equivalent to issuing the request for all key codes. 

modifiers Specifies a set of keymasks. This is a bitwise OR of one or more of the fol 
lowing symbols: ShiftMask, LockMask, ControlMask, ModlMask, 
Mod2Mask, Mod3Mask, Mod4Mask, ModSMask, or AnyModifier. 
AnyModif ier is equivalent to issuing the grab key request for all possible 
modifier combinations (including no modifiers). All specified modifiers do 
not need to have currently assigned keycodes. 

gr a >_ window Specifies the window in which the specified key combination will initiate an 
active grab. 

owner_events 

Specifies whether the grab window should receive all events (True) or 
whether the grabbing application should receive all events normally 
(False). 

point er_mode 

Controls processing of pointer events during the grab. Pass one of these con 
stants: GrabModeSync or GrabModeAsync. 

keyboa rd_mode 

Controls processing of keyboard events during the grab. Pass one of these 
constants: GrabModeSync or GrabModeAsync. 

Description 

XGrabKey establishes a passive grab on the specified keys, such that when the specified 
key/modifier combination is pressed, the keyboard may be grabbed, and all keyboard events 
sent to this application. More formally, once an XGrabKey call has been issued on a particular 
key /button combination: 



Xlib Reference Manual 273 



XGrabKey (continued) Xlib - Grabbing 

IF the keyboard is not already actively grabbed, 

AND the specified key, which itself can be a modifier key, is logically pressed when the 
specified modifier keys are logically down, 

AND no other keys or modifier keys are logically down, 

AND EITHER the grab window is an ancestor of (or is) the focus window OR the grab 
window is a descendent of the focus window and contains the pointer, 

AND a passive grab on the same key combination does not exist on any ancestor of the 
grab window, 

THEN the keyboard is actively grabbed, as for XGrabKeyboard, the last keyboard grab 
time is set to the time at which the key was pressed (as transmitted in the KeyPress 
event), and the KeyPress event is reported. 

The active grab is terminated automatically when the specified key is released (independent of 
the state of the modifier keys). 

The pointer_mode and keyboard_mode control the processing of events during the grab. 
If either is GrabModeSync, events for that device are not sent from the server to Xlib until 
XAllowEvents is called to send the events. If either is GrabModeAsync, events for that 
device are sent normally. 

For more information on grabbing, see Volume One, Chapter 9, The Keyboard and Pointer. 

Errors 

BadAccess When using AnyModif ier or AnyKey and another client has grabbed any 
overlapping combinations. In this case, no grabs are established. 

Another client has issued XGrabKey for the same key combination in 

grab_window. 

BadValue key code is not in the range between min_keycode and max_keycode 
as returned by XDisplayKeycodes. 

BadWindow 

Related Commands 

XChangeActivePointerGrab, XGrabButton, XGrabKeyboard, XGrabPointer, 
XGrabServer, XUngrabButton, XUngrabKey, XUngrabKeyboard, XUngrab- 
Pointer, XUngrabServer. 



274 Xlib Reference Manual 



Xlib -Grabbing- 



J XGrabKeyboard 



Name 

XGrabKeyboard grab the keyboard. 

Synopsis 

int XGrabKeyboard (display, grab_window, owner_events, 

point er_mode, keyboard_mode, time) 
Display *display; 
Window grab_window; 
Bool o wner_e vents; 
int pointer_mode, keyboard_mode ; 
Time time; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

grab_window Specifies the ID of the window that requires continuous keyboard input. 

owner_e vents 

Specifies a boolean value of either True or False. See Description below. 

point er_mode 

Controls processing of pointer events during the grab. Pass either Grab- 
ModeSync or GrabModeAsync. 

k eyb oard_mode 

Controls processing of keyboard events during the grab. Pass either Grab- 
ModeSync or GrabModeAsync. 

time Specifies the time when the grab should take place. Pass either a timestamp, 

expressed in milliseconds, or the constant Cur rent Time. 

Description 

XGrabKeyboard actively grabs control of the main keyboard. Further key events are 
reported only to the grabbing client. This request generates Focus In and FocusOut events. 

XGrabKeyboard processing is controlled by the value in the cw/jer_ events argument: 
If owner_events is False, all generated key events are reported to grab_window. 

If owner_events is True, then if a generated key event would normally be reported 
to this client, it is reported normally. Otherwise the event is reported to grab_window. 

Both KeyPress and KeyRelease events are always reported, independent of any 
event selection made by the client. 

XGrabKeyboard processing of pointer events and keyboard events are controlled by 
poir7ter_modeand A:eyboard_/node: 

If the pointer_mode or keyboard_mode is GrabModeAsync, event processing 
for the respective device continues normally. 

For keyboard_mode GrabModeAsync only: if the keyboard was currently frozen 
by this client, then processing of keyboard events is resumed. 



Xlib Reference Manual 275 



XGrabKeyboard (continued) Xlib - Grabbing 

If the ponter_mode or keyboard_mode is GrabModeSync, events for the 
respective device are queued by the server until a releasing XAllowE vents request 
occurs or until the keyboard grab is released as described above. 

If the grab is successful, XGrabKeyboard returns the constant GrabSuccess. XGrab 
Keyboard fails under the following conditions and returns the following: 

If the keyboard is actively grabbed by some other client, it returns AlreadyGrabbed. 
If grab_window is not viewable, it returns GrabNotViewable. 

If time is earlier than the last keyboard grab time or later than the current server time, it 
returns GrablnvalidTime. 

If the pointer is frozen by an active grab of another client, the request fails with a status 
GrabFrozen. 

If the grab succeeds, the last keyboard grab time is set to the specified time, with Current- 
Time replaced by the current X server time. 

For more information on grabbing, see Volume One, Chapter 9, The Keyboard and Pointer. 

Errors 

BadValue 
Badwindow 

Related Commands 

XChangeActivePointerGrab, XGrabButton, XGrabKey, XGrabPointer, XGrab- 
Server, XUngrabButton, XUngrabKey, XUngrabKeyboard, XUngrabPointer, 
XUngrabServer. 



276 Xlib Reference Manual 



-x -tabbing / XGrabPointer 

Name 

XGrabPointer grab the pointer. 

Synopsis 

int XGrabPointer (display, grab_window, owner_e vents, 

event_mask r pointer_mode , keyboard_mode , confine_to, 
cursor, time) 
Display *display; 
Window grab_window; 
Bool owner_events ; 
unsigned int event_mask; 
int point er_mode, keyboard_mode; 
Window confine_to; 
Cursor cursor; 
Time time; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

grab_window Specifies the ID of the window that should grab the pointer input independent 
of pointer location. 

owner_e vents 

Specifies if the pointer events are to be reported normally within this applica 
tion (pass True) or only to the grab window (pass False). 

event_mask Specifies the event mask symbols that can be ORed together. Only events 
selected by this mask, plus ButtonPress and ButtonRelease, will be 
delivered during the grab. See XSelect Input for a complete list of event 
masks. 

point er_mode 

Controls further processing of pointer events. Pass either GrabModeSync 

or GrabModeAsync. 

k eyb o a rd_m ode 

Controls further processing of keyboard events. Pass either GrabModeSync 
or GrabModeAsync. 

confine_to Specifies the ID of the window to confine the pointer. One option is None, in 
which case the pointer is not confined to any window. 

cursor Specifies the ID of the cursor that is displayed with the pointer during the 

grab. One option is None, which causes the cursor to keep its current pattern. 

time Specifies the time when the grab request took place. Pass either a timestamp, 

expressed in milliseconds (from an event), or the constant Cur rent Time. 



Xlib Reference Manual 277 



XGrabPointer (continued) Xlib- Grabbing 

Description 

XGrabPointer actively grabs control of the pointer. Further pointer events are only reported 
to the grabbing client until XUngrabPo inter is called. 

event_mask is always augmented to include ButtonPressMask and ButtonRelease- 
Mask. If owner_events is False, all generated pointer events are reported to 
grab_window, and are only reported if selected by event_mask. If owner_e vents is 
True, then if a generated pointer event would normally be reported to this client, it is reported 
normally; otherwise the event is reported with respect to the grrab_window, and is only 
reported if selected by event_mask. For either value of owner_e vents, unreported events 
are discarded. 

point er_mode controls processing of pointer events during the grab, and keyboard_mode 
controls further processing of main keyboard events. If the mode is GrabModeAsync, event 
processing continues normally. If the mode is GrabModeSync, events for the device are 
queued by the server but not sent to clients until the grabbing client issues a releasing 
XAllowE vents request or an XUngrabPo inter request. 

If a cursor is specified, then it is displayed regardless of which window the pointer is in. If no 
cursor is specified, then when the pointer is in gra>_window or one of its subwindows, the 
normal cursor for that window is displayed. When the pointer is outside grab_window, the 
cursor for grab_ window is displayed. 

If a con fin e_ to window is specified, then the pointer will be restricted to that window. The 
confine_to window need have no relationship to the graJb_window. If the pointer is not 
initially in the confine_to window, then it is warped automatically to the closest edge (and 
enter/leave events generated normally) just before the grab activates. If the conf~ine_to 
window is subsequently reconfigured, the pointer will be warped automatically as necessary to 
keep it contained in the window. 

The time argument lets you avoid certain circumstances that come up if applications take a 
long while to respond or if there are long network delays. Consider a situation where you have 
two applications, both of which normally grab the pointer when clicked on. If both applica 
tions specify the timestamp from the ButtonPress event, the second application will suc 
cessfully grab the pointer, while the first will get a return value of AlreadyGrabbed, indicat 
ing that the other application grabbed the pointer before its request was processed. This is the 
desired response because the latest user action is most important in this case. 

XGrabPointer generates EnterNotif y and LeaveNotif y events. 

If the grab is successful, it returns the constant GrabSuccess. The XGrabPointer func 
tion fails under the following conditions, with the following return values: 

If grab_window or conf~ine_to window is not viewable, or if the conf ine_to 
window is completely off the screen, GrabNotviewable is returned. 

If the pointer is actively grabbed by some other client, the constant AlreadyGrabbed 
is returned. 

If the pointer is frozen by an active grab of another client, GrabFrozen is returned. 



278 Xlib Reference Manual 



Xllb - Grabbing (continued) XGrabPointer 

If the specified time is earlier than the last-pointer-grab time or later than the current X 
server time, GrablnvalidTime is returned. (If the call succeeds, the last pointer grab 
time is set to the specified time, with the constant CurrentTime replaced by the cur 
rent X server time.) 

For more information on grabbing, see Volume One, Chapter 9, The Keyboard and Pointer. 

Errors 

BadCursor 

BadValue 

BadWindow 

Related Commands 

XChangeActivePointerGrab, XGrabButton, XGrabKey, XGrabKeyboard, 
XGrabServer, XUngrabButton, XUngrabKey, XUngrabKeyboard, XUngrab- 
Pointer, XUngrabServer. 



Xlib Reference Manual 279 



XGrabServer 

Xllb - Grabbing 

Name 

XGrabServer grab the server. 

Synopsis 

XGrabServer (display) 
Display * display ; 

Arguments 

display Specifies a connection to an X server; returned from xopenDisplay. 

Description 

Grabbing the server means that only requests by the calling client will be acted on. All others 
will be queued in the server until the next XUngrabServer call. The X server should not be 
grabbed any more than is absolutely necessary. 

Related Commands 

XChangeActivePointerGrab, XGrabButton, XGrabKey, XGrabKeyboard, 
XGrabPointer, XUngrabButton, XUngrabKey, XUngrabKeyboard, XUngrab- 
Pointer, XUngrabServer. 



Xlib Reference Manual 



-Xlib - Window Manager Hints / XlCOPify WindOW 

Name 

XlconifyWindow request that a top-level window be iconified. 

Synopsis 

Status XlconifyWindow (display, w, screen_number) 
Display * display; 
Window w; 
int screen_n umber; 

Arguments 

display Specifies a connection to an X server; returned from xopenDisplay. 

w Specifies the window. 

s c r e en_n umbe r 

Specifies the appropriate screen number on the server. 

Availability 

Release 4 and later. 

Description 

XlconifyWindow sends a WM_CHANGE_STATE ClientMessage event with a format of 32 
and a first data element of Iconics t ate (as described in Section 4.1.4 of the Inter-Client 
Communication Conventions Manual in Volume Zero, X Protocol Reference Manual), to the 
root window of the specified screen. Window managers may elect to receive this message and, 
if the window is in its normal state, may treat it as a request to change the window s state from 
normal to iconic. If the WM_CHANGE_STATE property cannot be interned, XlconifyWindow 
does not send a message and returns a zero status. It returns a nonzero status if the client mes 
sage is sent successfully; otherwise, it returns a zero status. 

For more information, see Volume One, Chapter WJnterclient Communication. 

Errors 

BadWindow 

Related Commands 

XReconfigureWindow, XWithdrawWindow. 



Xlib Reference Manual 28 1 



Xlf EVent V xilb - input Hand.ing- 

Name 

XlfEvent wait for event matched in predicate procedure. 

Synopsis 

XlfEvent ( display , event, predicate, args) 
Display *dsplay; 

XEvent * event; /* RETURN */ 

Bool (*predicate) () ; 
char *args; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

event Returns the matched event. 

predicate Specifies the procedure to be called to determine if the next event satisfies 
your criteria. 

args Specifies the user- specified arguments to be passed to the predicate proce 

dure. 

Description 

XlfEvent checks the event queue for events, uses the user-supplied routine to check if one 
meets certain criteria, and removes the matching event from the input queue. XlfEvent 
returns only when the specified predicate procedure returns True for an event. The specified 
predicate is called once for each event on the queue until a match is made, and each time an 
event is added to the queue, with the arguments display, event, and arg. 

If no matching events exist on the queue, XlfEvent flushes the request buffer and waits for an 
appropriate event to arrive. Use XChecklf Event if you don t want to wait for an event. 

For more information, see Volume One, Chapter 8, Events. 
Related Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEvent sQueued, 
XGetlnputFocus, XGetMotionEvents, XMaskEvent, XNextEvent, XPeekEvent, 
XPeeklf Event, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSet- 
InputFocus, XSynchronize, XWindowEvent. 



282 Xlib Reference Manual 



Xlib - Resource Manager- 



J XlnsertModifiermapEntry 



Name 

XlnsertModifiermapEntry add a new entry to an XModif ierKeymap structure. 
Synopsis 

XModif ierKeymap *XInsertModif iermapEntry (modmap, 

keysym_entry, modifier) 
XModif ierKeymap * modmap; 
KeyCode keysym_entry ; 
int modifier; 

Arguments 

modmap Specifies a pointer to an XModif ierKeymap structure. 

ey sym_ entry 

Specifies the keycode of the key to be added to modmap. 

modifier Specifies the modifier you want mapped to the keycode specified in 
keysym_entry. This should be one of the constants: Shif tMaplndex, 
LockMapIndex, ControlMapIndex, ModlMapIndex, Mod2Map- 
Index, ModSMapIndex, Mod4MapIndex, or ModSMapIndex. 

Description 

XlnsertModifiermapEntry returns an XModif ierKeymap structure suitable for cal 
ling xsetModif ierMapping, in which the specified keycode is deleted from the set of key- 
codes that is mapped to the specified modifier (like Shift or Control). Xlnsert 
ModifiermapEntry does not change the mapping itself. 

This function is normally used by calling XGetModif ierMapping to get a pointer to the 

current XModif ierKeymap structure for use as the modmap argument to Xlnsert- 

Modi f ie rmapEnt r y . 

Note that the structure pointed to by modmap is freed by XlnsertModifiermapEntry. It 

should not be freed or otherwise used by applications. 

For a description of the modifier map, see XSetModif ierMapping. 

Structures 

typedef struct { 

int max_keypermod; /* server s max number of keys per modifier */ 
KeyCode *modif iermap; /* an 8 by max_keypermod array of 

* keycodes to be used as modifiers */ 

} XModif ierKeymap; 

#define ShiftMapIndex 

#define LockMapIndex 1 

#define ControlMapIndex 2 
#define ModlMapIndex 

#define Mod2MapIndex 4 

#define ModSMapIndex 5 



Xlib Reference Manual 



283 



XlnsertModif iermapEntry (continued) Xlib - Resource Manager 

fdefine Mod4MapIndex 6 

tdefine ModSMapIndex 7 

Related Commands 

XDeleteModif iermapEntry, XFreeModif iermap, XGetKeyboardMapping, 
XGetModif ierMapping, XKeycodeToKeysym, XKeysymToKeycode, XKeysymTo- 
String, XLookupKeysym, XLookupString, XNewModif ierMap, XQueryKeymap, 
XRebindKeySym, XRef reshKeyboardMapping, XSetModif ierMapping, 
XStringToKeysym. 



284 Xlib Reference Manual 



Xlib- Colormaps- 



j XlnstallColormap 



Name 

XlnstallColormap install a colormap. 

Synopsis 

XlnstallColormap ( display, cmap) 
Display * display; 
Colormap cmap; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

cmap Specifies the colormap to install. 

Description 

XlnstallColormap installs a virtual colormap into a hardware company. If there is only 
one hardware colormap, XlnstallColormap loads a virtual colormap into the hardware 
colormap. All windows associated with this colormap immediately display with their chosen 
colors. Other windows associated with the old colormap will display with false colors. 

If additional hardware colormaps are possible, XlnstallColormap loads the new hardware 
map and keeps the existing ones. Other windows will then remain in their true colors unless the 
limit for colormaps has been reached. If the maximum number of allowed hardware colormaps 
is already installed, an old colormap is swapped out The MinCmapsOf Screen (screen) 
and MaxCmapsOf Screen (screen) macros can be used to determine how many hardware 
colormaps are supported. 

If cmap is not already an installed map, a ColormapNotify event is generated on every 
window having cmap as an attribute. If a colormap is uninstalled as a result of the install, a 
ColormapNotify event is generated on every window having that colormap as an attribute. 

Colormaps are usually installed and uninstalled by the window manager, not by clients. 

At any time, there is a subset of the installed colormaps, viewed as an ordered list, called the 
"required list." The length of the required list is at most the min_maps specified for each 
screen in the Display structure. When a colormap is installed with XlnstallColormap it 
is added to the head of the required list and the last colormap in the list is removed if necessary 
to keep the length of the list at mim_maps. When a colormap is uninstalled with 
XUninstallColormap and it is in the required list, it is removed from the list. No other 
actions by the server or the client change the required list. It is important to realize that on all 
but high-performance workstations, min_maps is likely to be 1. 

If the hardware colormap is immutable, and therefore installing any colormap is impossible, 
XlnstallColormap will work but not do anything. 

For more information, see Volume One, Chapter 7, Color. 
Errors 

BadColormap 



Xlib Reference Manual 285 



XlnstallColormap (continued) Xlib - Colormaps 

Related Commands 

Def aultColormap, DisplayCells, XCopyColormapAndFree, XCreate- 
Colormap, XFreeColormap, XGetStandardColormap, XListlnstalled- 
Colormaps, XSetStandardColormap, XSetWindowColormap, XUninstall- 
Colormap. 



286 



Xlib Reference Manual 



-Xllb - Properties / XlntelTlAtOm 

Name 

XInternAtom return an atom for a given property name string. 

Synopsis 

Atom XInternAtom (display, property_name, only_if_exists) 
Display * display; 
char *property_name ; 
Bool only_if_exists ; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

property_name 

Specifies the string name of the property for which you want the atom. Upper 
or lower case is important. The string should be in ISO LATIN- 1 encoding, 
which means that the first 128 character codes are ASCII, and the second 128 
character codes are for special characters needed in western languages other 
than English. 

only_if_exists 

Specifies a boolean value: if no such property_name exists Xlntern- 
Atom will return None if this argument is set to True or will create the atom 
if it is set to False. 

Description 

XInternAtom returns the atom identifier corresponding to string proper ty_name. 

If the atom does not exist, then XInternAtom either returns None (if only_if_exists is 
True) or creates the atom and returns its ID (if only_if_exists is False). 

The string name should be a null-terminated. Case matters: the strings "thing," "Thing," and 
"thinG" all designate different atoms. 

The atom will remain defined even after the client that defined it has exited. It will become 
undefined only when the last connection to the X server closes. Therefore, the number of atoms 
interned should be kept to a minimum. 

This function is the opposite of XGetAtomName, which returns the atom name when given an 
atom ID. 

Predefined atoms require no call to XInternAtom. Predefined atoms are defined in 
<Xll/Xatom.h> and begin with the prefix "XA_". Predefined atoms are the only ones that do 
not require a call to XInternAtom. 

Errors 

BadAlloc 
BadValue 



Xlib Reference Manual 287 



Xlntern Atom (continued) Xlib - Properties 

Related Commands 

XChangeProperty, XDeleteProperty, XGetAtomName, XGetFontProperty, 
XGetWindowProperty, XListProperties, XRotateWindowProperties, XSet- 
StandardProperties. 



Xlib Reference Manual 



Xlib -Regions- 



/ XlntersectRegion 



Name 

XlntersectRegion compute the intersection of two regions. 
Synopsis 

XlntersectRegion (sra, srb, dr) 
Region sra, srb; 
Region dr; /* RETURN */ 

Arguments 

sra Specify the two regions with which to perform the computation. 

srb 

dr Returns the result of the computation. 

Description 

XlntersectRegion generates a region that is the intersection of two regions. 

Structures 

Region is a pointer to an opaque structure type. 

Related Commands 

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion, 
XOf f setRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion, XSet- 
Region, XShrinkRegion, XSubtractRegion, XUnionRectWithRegion, XUnion- 
Region, XXorRegion. 



Xlib Reference Manual 289 



XKeycodeToKeysym \ X||b Keyboard _ 

Name 

XKeycodeToKeysym convert a key code to a keysym. 

Synopsis 

KeySym XKeycodeToKeysym ( display, keycode, index) 
Display *display; 
KeyCode keycode ; 
int index; 

Arguments 

di spl ay Specifies a connection to an X server; returned from xopenD i sp 1 ay . 

keycode Specifies the keycode. 

index Specifies which keysym in the list for the keycode to return. 

Description 

XKeycodeToKeysym returns one of the keysyms defined for the specified keycode. 
XKeycodeToKeysym uses internal Xlib tables, index specifies which keysym in the array 
of keysyms corresponding to a keycode should be returned. If no symbol is defined, 
XKeycodeToKeysym returns NoSymbol. 

Related Commands 

IsCursorKey, IsFunctionKey, IsKeypadKey, IsMiscFunctionKey, Is- 
Modif ierKey, IsPFKey, XChangeKeyboardMapping, XDeleteModif iermap- 
Entry, XDisplayKeycodes, XFreeModif iermap, XGetKeyboardMapping, XGet- 
Modif ierMapping, XInsertModif iermapEntry, XKeysymToKeycode, XKeysym- 
ToString, XLookupKeysym, XLookupString, XNewModif ierMap, XQuery- 
Keymap, XRebindKeySym, XRef reshKeyboardMapping, XSetModif ierMapping, 
XStringToKeysym. 



290 Xlib Reference Manual 



Xlib -Keyboard- 



J XKeysymToKeycode 



Name 

XKeysymToKeycode convert a keysym to the appropriate keycode. 

Synopsis 

KeyCode XKeysymToKeycode (display, keysym) 
Display *display; 
Keysym keysym; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

keysym Specifies the keysym that is to be searched for. 

Description 

XKeysymToKeycode returns the keycode corresponding to the specified keysym in the cur 
rent mapping. If the specified keysym is not defined for any keycode, XKeysymToKeycode 
returns zero. 

Related Commands 

IsCursorKey, IsFunctionKey, IsKeypadKey, IsMiscFunctionKey, Is- 
Modif ierKey, IsPFKey, XChangeKeyboardMapping, XDeleteModif iermap- 
Entry, XDisplayKeycodes, XFreeModif iermap, XGetKeyboardMapping, XGet- 
Modif ierMapping, XInsertModif iermapEntry, XKeycodeToKeysym, XKeysym- 
ToString, XLookupKeysym, XLookupString, XNewModif ierMap, XQuery- 
Keymap, XRebindKeySym, XRef reshKeyboardMapping, XSetModif ierMapping, 
XSt r ingToKeysym. 



Xlib Reference Manual 291 



XKeysymToString \ XB> _ Keyboard _ 

Name 

XKeysymToString convert a keysym symbol to a string. 

Synopsis 

char *XKeysymToSt ring (keysym) 
KeySym keysym; 

Arguments 

keysym Specifies the keysym that is to be converted. 

Description 

XKeysymToString converts a keysym symbol (a number) into a character string. The 
returned string is in a static area and must not be modified. If the specified keysym is not 
defined, XKeysymToString returns NULL. For example, XKeysymToString converts 
XK_Shift to "Shift". 

Note that XKeysymString does not return the string that is mapped to the keysym, but only a 
string version of the keysym itself. In other words, even if the Fl key is mapped to the string "- 
STOP" using XRebindKeysym, XKeysymToString still returns "Fl". XLookupString, 
however, would return "STOP". 

In Release 4, XKeysymToString can process keysyms that are not defined by the Xlib stan 
dard. Note that the set of keysyms that are available in this manner and the mechanisms by 
which Xlib obtains them is implementation dependent. (In the MIT sample implementation, 
the resource file lusrlliblXl 1 IXKeysymDB is used starting in Release 4. The keysym name is 
used as the resource name, and the resource value is the keysym value in uppercase hexade 
cimal.) 

Related Commands 

IsCursorKey, IsFunctionKey, IsKeypadKey, IsMiscFunctionKey, Is- 
Modif ierKey, IsPFKey, XChangeKeyboardMapping, XDeleteModif iermap- 
Entry, XFreeModif iermap, XGetKeyboardMapping, XGetModif ierMapping, 
XInsertModif iermapEntry, XKeycodeToKeysym, XKeysymToKeycode, 
XLookupKeysym, XLookupString, XNewModif ierMap, XQueryKeymap, XRebind 
Keysym, XRef reshKeyboardMapping, XSetModif ierMapping, XStringTo- 
Keysym. 



292 Xlib Reference Manual 



/ 



XKIIICIient 



Name 

XKillClient destroy a client or its remaining resources. 

Synopsis 

XKillClient (display, resource) 
Display * display; 
XID resource; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

resource Specifies any resource created by the client you want to destroy, or the con 
stant AllTemporary. 

Description 

If a valid resource is specified, XKillClient forces a close-down of the client that created 
the resource. If the client has already terminated in either RetainPermanent or Retain- 
Temporary mode, all of the client s resources are destroyed. If AllTemporary is specified 
in the resource argument, then the resources of all clients that have terminated in Retain- 
Temporary are destroyed. 

For more information, see Volume One, Chapter 13, Other Programming Techniques. 

Errors 

BadValue 

Related Commands 

XSetCloseDownMode. 



Xlib Reference Manual 293 



XLiStDepthS \ x,ib-W,ndowM a na g erH,ms- 

Name 

XListDepths determine the depths available on a given screen. 

Synopsis 

int *XListDepths (display, screen_n umber, count) 
Display *display; 
int screen_n umber; 
int * count; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

s c r e en_n umb e r 

Specifies the appropriate screen number on the host server. 

count Returns the number of depths. 

Availability 

Release 4 and later. 

Description 

XListDepths returns the array of depths that are available on the specified screen. If the 
specified screen_n umber is valid and sufficient memory for the array can be allocated, 
XListDepths sets count to the number of available depths. Otherwise, it does not set 
count and returns NULL. To release the memory allocated for the array of depths, use XFree. 

Related Commands 

DefaultDepthOf Screen macro, Def aultDepth macro, XListPixmapFormats. 



294 Xlib Reference Manual 



-Xlib- Extensions / XLiStExtensiOHS 

Name 

XListExtensions return a list of all extensions to X supported by Xlib and the server. 

Synopsis 

char **XListExtensions ( display, nextensions) 
Display *disp_Zay; 
int *nextensions; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

nextensions Returns the number of extensions in the returned list. 

Description 

XListExtensions lists all the X extensions supported by Xlib and the current server. The 
returned strings will be in ISO LATIN- 1 encoding, which means that the first 128 character 
codes are ASCII, and the second 128 character codes are for special characters needed in west 
ern languages other than English. 

For more information on extensions, see Volume One, Chapter 13, Other Programming Tech 
niques. 

Related Commands 

XFreeExtensionList, XQueryExtension. 



Xlib Reference Manual 295 



XListFonts "\ 



Xlib- Fonts- 



Name 

XListFonts return a list of the available font names. 

Synopsis 

char **XListFonts ( display, pattern, maxnames, actual_count) 
Display * display; 
char * pattern; 
int maxnames ; 
int * actual_count ; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

pattern Specifies the string associated with the font names you want returned. You 

can specify any string, including asterisks (*), and question marks. The aster 
isk indicates a wildcard for any number of characters and the question mark 
indicates a wildcard for a single character. Upper or lower case is not impor 
tant. The string should be in ISO LATIN- 1 encoding, which means that the 
first 128 character codes are ASCII, and the second 128 character codes are 
for special characters needed in western languages other than English. 

maxnames Specifies the maximum number of names that are to be in the returned list. 

actual_count 

Returns the actual number of font names in the list. 

Description 

XListFonts returns a list of font names that match the string pattern. Each returned font 
name string is terminated by NULL and is lower case. The maximum number of names returned 
in the list is the value you passed to maxnames. The function returns the actual number of 
font names in actual_count. 

If no fonts match the specified names, XListFonts returns NULL. 

The client should call XFreeFontNames when done with the font name list. 

The font search path (the order in which font names in various directories are compared to 
pat tern) is set by XSetFontPath. 

For more information on fonts, see Volume One, Chapter 6, Drawing Graphics and Text. 
Related Commands 

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XFree- 
FontPath, XGetFontPath, XGetFontProperty, XListFontsWithlnf o, XLoad- 
Font, XLoadQueryFont, XQueryFont, XSetFont, XSetFontPath, XUnloadFont. 



296 Xlib Reference Manual 



-xnb- Fonts J XListFontsWithlnfo 

Name 

XListFontsWithlnfo obtain the names and information about loaded fonts. 

Synopsis 

char **XListFontsWithInfo( display, pattern, maxnames, 

count, info) 
Display *disp_Zay; 

char *pattern; /* null-terminated */ 

int maxnames; 

int * count; /* RETURN */ 

XFontStruct **info; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

pattern Specifies the string associated with the font names you want returned. You 

can specify any string, including asterisks (*) and question marks. The aster 
isk indicates a wildcard on any number of characters and the question mark 
indicates a wildcard on a single character. Upper or lower case is not impor 
tant. The string should be in ISO LATIN- 1 encoding, which means that the 
first 128 character codes are ASCII, and the second 128 character codes are 
for special characters needed in western languages other than English. 

maxnames Specifies the maximum number of names that are to be in the returned list. 
count Returns the actual number of matched font names. 

info Returns a pointer to a list of font information structures. XListFonts 

Withlnfo provides enough space for maxnames pointers. 

Description 

XListFontsWithlnfo returns a list of font names that match the specified pattern and a 
also returns limited information about each font that matches. The list of names is limited to 
the size specified by the maxnames argument The list of names is in lower case. 

XListFontsWithlnfo returns NULL if no matches were found. 

To free the allocated name array, the client should call XFreeFont Names. To free the font 
information array, the client should call XFreeFont Info. 

The information returned for each font is identical to what XQueryFont would return, except 
that the per-character metrics (Ibearing, rbearing, width, ascent, descent for 
single characters) are not returned. 

The font search path (the order in which font names in various directories are compared to 
pattern) is set by XSetFontPath. XListFonts returns NULL if no matches were found. 

For more information on fonts, see Volume One, Chapter 6, Drawing Graphics and Text. 



Xlib Reference Manual 297 



XListFontsWithlnfo 



(continued) 



Xlib - Fonts 



Structures 

typedef struct { 

XExtData *ext_data; /* 

Font fid; /* 

unsigned direction; /* 
unsigned min_char_or_byte2; /* 
unsigned max_char_or_byte2; /* 

unsigned min bytel; /* 

unsigned max_bytel; /* 

Bool all_chars exist; /* 

unsigned default_char; /* 

int n_properties; /* 

XFontProp *properties; /* 

XCharStruct min bounds; /* 

XCharStruct max_bounds; /* 

XCharStruct *per_char; /* 

int ascent; /* 

int descent; /* 

} XFontStruct; 



hook for extension to hang data */ 

Font ID for this font */ 

hint about direction the font is painted */ 

first character */ 

last character */ 

first row that exists */ 

last row that exists */ 

flag if all characters have nonzero size*/ 

char to print for undefined character */ 

how many properties there are */ 

pointer to array of additional properties*/ 

minimum bounds over all existing char*/ 

minimum bounds over all existing char*/ 

first_char to last_char information */ 

logical extent above baseline for spacing */ 

logical descent below baseline for spacing */ 



Related Commands 

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XFree- 
FontPath, XGetFontPath, XGetFontProperty, XListFonts, XLoadFont, 
XLoadQueryFont, XQueryFont, XSetFont, XSetFontPath, XUnloadFont. 



298 



Xlib Reference Manual 



_X,ib - Host Access / XLJStHOStS 

Name 

XListHosts obtain a list of hosts having access to this display. 

Synopsis 

XHost Address *XListHosts (display, nhosts, state) 
Display * display ; 

int *nhosts; /* RETURN */ 

Bool *state; /* RETURN */ 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenD i sp 1 ay . 

nhosts Returns the number of hosts currently in the access control list. 

state Returns whether the access control list is currently being used by the server to 

process new connection requests from clients. True if enabled, False if 
disabled. 

Description 

XListHosts returns the current access control list as well as whether the use of the list is 
enabled or disabled. XListHosts allows a program to find out what machines make connec 
tions, by looking at a list of host structures. This XHost Address list should be freed when it 
is no longer needed. XListHosts returns NULL on failure. 

For more information on access control lists, see Volume One, Chapter 13, Other Programming 
Techniques, 

Structures 

typedef struct { 

int family; 

int length; 

char *address; 
} XHostAddress; 

Related Commands 

XAddHost, XAddHosts, XDisableAccessControl, XEnableAccessControl, 
XRemoveHost, XRemoveHosts, XSetAccessControl. 



Xlib Reference Manual 2 " 



XListlnstalledColormaps \ X|lb _ Colormaps _ 

Name 

XListlnstalledColormaps get a list of installed colormaps. 

Synopsis 

Colormap *XListInstalledColormaps ( display, w, num) 
display * display ; 
Window w; 
int *num; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the ID of the window for whose screen you want the list of currently 

installed colormaps. 

num Returns the number of currently installed colormaps in the returned list. 

Description 

XListlnstalledColormaps returns a list of the currently installed colormaps for the 
screen containing the specified window. The order in the list is not significant. There is no dis 
tinction in the list between colormaps actually being used by windows and colormaps no longer 
in use which have not yet been freed or destroyed. 

XListlnstalledColormaps returns None and sets num to zero on failure. 

The allocated list should be freed using XFree when it is no longer needed. 

For more information on installing colormaps, see Volume One, Chapter 7, Color. 

Errors 

BadWindow 

Related Commands 

Def aultColormap, DisplayCells, XCopyColormapAndFree, XCreate- 
Colormap, XFreeColormap, XGetStandardColormap, XInstallColormap, 
XSetStandardColormap, XSetWindowColormap, XUninstallColormap. 



300 Xlib Reference Manual 



-Xllb- Window Manager Hints / XLJStPixmapFormatS 

Name 

XListPixmapFormats obtain the supported pixmap formats for a given server. 

Synopsis 

XPixmapFormat Values *XListPixmapFormats { display, count) 
Display ^display; 
int * count; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

count Returns the number of pixmap formats that are supported by the server. 

Availability 

Release 4 and later. 

Description 

XListPixmapFormats returns an array of XPixmapFormatValues structures that 
describe the types of Z format images that are supported by the specified server. If insufficient 
memory is available, XListPixmapFormats returns NULL. To free the allocated storage for 
the XPixmapFormatValues structures, use XFree. 

Structures 

typedef struct { 

int depth; 

int bits_per_pixel; 

int scanline_pad; 
} XPixmapFormatValues; 

Related Commands 

XListDepths. 



Xlib Reference Manual 30 1 



XListProperties \, 

^ Xlib - Properties- 
Name 

XListProperties get the property list for a window. 

Synopsis 

Atom *XListProperties ( display, w, num_prop) 
Display *display; 
Window w; 
int *num_jprop; /* RETURN */ 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenD i sp 1 ay . 

w Specifies the window whose property list you want. 

num_prop Returns the length of the properties array. 

Description 

XListProperties returns a pointer to an array of atoms for properties that are defined for 
the specified window. XListProperties returns NULL on failure (when window w is inva 
lid). 

To free the memory allocated by this function, use XFree. 

For more information, see Volume One, Chapter IQJnterclient Communication. 

Errors 

BadWindow 

Related Commands 

XChangeProperty, XDeleteProperty, XGetAtomName, XGetFontProperty, 
XGetWindowProperty, XInternAtom, XRotateWindowProperties, XSet- 
StandardProperties. 



302 Xlib Reference Manual 



-xiib - Fonts / XLoadFont 

Name 

XLoadFont load a font if not already loaded; get font ID. 

Synopsis 

Font XLoadFont (display, name) 
Display *display; 
char *name; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenD i splay. 

name Specifies the name of the font in a null terminated string. As of Release 4, the 

* and ? wildcards are allowed and may be supported by the server. Upper or 
lower case is not important. The string should be in ISO LATIN- 1 encoding, 
which means that the first 128 character codes are ASCII, and the second 128 
character codes are for special characters needed in western languages other 
than English. 

Description 

XLoadFont loads a font into the server if it has not already been loaded by another client. 
XLoadFont returns the font ID or, if it was unsuccessful, generates a BadName error. When 
the font is no longer needed, the client should call xunloadFont. Fonts are not associated 
with a particular screen. Once the font ID is available, it can be set in the font member of any 
GC, and thereby used in subsequent drawing requests. 

Font information is usually necessary for locating the text. Call XLoadFontwithinf o to 
get the info at the time you load the font, or call XQueryFont if you used XLoadFont to 
load the font. 

For more information on fonts, see Volume One, Chapter 6, Drawing Graphics and Text. 

Errors 

BadAlloc Server has insufficient memory to store font. 

BadName name specifies an unavailable font 

Related Commands 

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XFree- 
FontPath, XGetFontPath, XGetFontProperty, XListFonts, XListFontsWith- 
Inf o, XLoadQueryFont, XQueryFont, XSetFont, XSetFontPath, XUnloadFont. 



Xlib Reference Manual 303 



X 



XLoadQueryFont , x,,b- F on,s- 

Name 

XLoadQueryFont load a font and fill information structure. 

Synopsis 

XFontStruct *XLoadQueryFont ( display, name) 
Display *display; 
char *name; 

Arguments 

display Specifies a connection to an X server; returned from xopenDisplay. 

name Specifies the name of the font. This name is a null terminated string. As of 

Release 4, the * and ? wildcards are allowed and may be supported by the 
server. Upper or lower case is not important. 

Description 

XLoadQueryFont performs an XLoadFont and XQueryFont in a single operation. XLoad 
QueryFont provides the easiest way to get character-size tables for placing a proportional font. 
That is, XLoadQueryFont both opens (loads) the specified font and returns a pointer to the 
appropriate XFontStruct structure. If the font does not exist, XLoadQueryFont returns NULL. 

The XFontStruct structure consists of the font-specific information and a pointer to an array 
of xchar struct structures for each character in the font. 

For more information on fonts, see Volume One, Chapter 6, Drawing Graphics and Text. 

Errors 

BadAl loc server has insufficient memory to store font 

BadName name specifies an unavailable font 

Structures 

typedef struct { 

XExtData *ext_data; /* hook for extension to hang data */ 

Font fid; /* Font ID for this font */ 

unsigned direction; /* hint about direction the font is painted */ 

unsigned min_char_or_byte2; /* first character */ 

unsigned max_char_or_byte2; /* last character */ 

unsigned min_bytel; /* first row that exists */ 

unsigned max_bytel; /* last row that exists */ 

Bool all_chars_exist; /* flag if all characters have nonzero size*/ 

unsigned default_char; /* char to print for undefined character */ 

int n_properties; /* how many properties there are */ 

XFontProp *properties; /* pointer to array of additional properties*/ 

XCharStruct min_bounds; /* minimum bounds over all existing char*/ 

XCharStruct max_bounds; /* minimum bounds over all existing char*/ 

XCharStruct *per_char; /* first_char to last_char information */ 

int ascent; /* logical extent above baseline for spacing */ 

int descent; /* logical descent below baseline for spacing */ 

} XFontStruct; 



304 Xlib Reference Manual 



Xlib - Fonts 



(continued) 



XLoadQueryFont 



typedef struct { 

short Ibearing; /* 

short rbearing; /* 

short width; /* 

short ascent; /* 

short descent; /* 
unsigned short attributes; /* 

} XCharStruct; 



origin to left edge of character */ 
origin to right edge of character */ 
advance to next char s origin */ 
baseline to top edge of character */ 
baseline to bottom edge of character 
per char flags (not predefined) */ 



Related Commands 

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XFree- 
FontPath, XGetFontPath, XGetFontProperty, XListFonts, XListFontsWith- 
Info, XLoadFont, XQueryFont, XSetFont, XSetFontPath, XUnloadFont. 



Xlib Reference Manual 



305 



XLookllpAssoc A 



XI ib - Association Tables 



Name 

XLookUpAssoc obtain data from an association table. 

Synopsis 

caddr_t XLookUpAssoc ( display, table, x_id) 
Display *display; 
XAssocTable * table; 
XID x_id; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XQpenD i sp 1 ay . 

t abl e Specifies the association table. 

x_i d Specifies the X resource ID. 

Description 

This function is provided for compatibility with X Version 10. To use it you must include the 
file <XlllX10.h> and link with the library -loldX. 

Association tables provide a way of storing data locally and accessing by ID. XLookUp 
Assoc retrieves the data stored in an XAssocTable by its XID. If the matching XID can be 
found in the table, the routine returns the data associated with it. If the x_i d cannot be found 
in the table the routine returns NULL. 

For more information on association tables, see Volume One, Appendix B,X10 Compatibility. 
Structures 

typedef struct { 

XAssoc ^buckets; /* pointer to first bucket in bucket array */ 
int size; /* table size (number of buckets) */ 

} XAssocTable; 

typedef struct _XAssoc { 

struct _XAssoc *next; /* next object in this bucket */ 

struct _XAssoc *prev; /* previous object in this bucket */ 

Display *display; /* display which owns the ID */ 

XID x_id; /* X Window System ID */ 

char *data; /* pointer to untyped memory */ 

} XAssoc; 

Related Commands 

XCreateAssocTable, XDeleteAssoc, XDestroyAssocTable, XMakeAssoc. 



306 Xlib Reference Manual 



Xllb- Color Cells- 



j XLookupColor 



Name 

XLookupColor get database RGB values and closest hardware-supported RGB values from 
color name. 

Synopsis 

Status XLookupColor ( display, cmap f colorname, rgb_db_def f 

hardware_def) 
Display ^display; 
Colormap cmap ; 
char * colorname ; 
XColor *rgb_db_def r *hardware_def ; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

cmap Specifies the colormap. 

colorname Specifies a color name string (for example "red"). Upper or lower case 

does not matter. The string should be in ISO LATIN 1 encoding, which 
means that the first 128 character codes are ASCII, and the second 128 
character codes are for special characters needed in western languages 
other than English. 

rgb_db_def Returns the exact RGB values for the specified color name from the 
lusrlliblXlllrgb database. 

hardware_def Returns the closest RGB values possible on the hardware. 

Description 

XLookupColor looks up RGB values for a color given the colorname string. It returns both 
the exact color values and the closest values possible on tthe screen specified by cmap. 

XLookupColor returns nonzero if colorname exists in the RGB database or zero if it does 
not exist. 

To determine the exact RGB values, XLookupColor uses a database on the X server. On 
UNIX, this database is lusrlliblXlllrgb, To read the colors provided by the database on a 
UNIX-based system, see lusrlliblXlllrgb.txt. The location, name, and contents of this file are 
server-dependent. 

For more information see Volume One, Chapter 7, Color, and Appendix D, The Color Data 
base, in this volume. 



Xlib Reference Manual 



307 



XLOQkupColor (continued) Xlib - Color Cells 

Errors 

BadName Color name not in database. 

BadColormap Specified colormap invalid. 
Structures 

typedef struct { 

unsigned long pixel; 

unsigned short red, green, blue; 

char flags; /* DoRed, DoGreen, DoBlue */ 

char pad; 
} XColor; 

Related Commands 

BlackPixel, WhitePixel, XAllocColor, XAllocColorCells, XAllocColor- 
Planes, XAllocNamedColor, XFreeColors, XParseColor, XQueryColor, 
XQueryColors, XStoreColor, XStoreColors, XStoreNamedColor. 



308 Xlib Reference Manual 



Xlib -Keyboard 



J XLookupKeysym 



Name 

XLookupKeysym get the keysym corresponding to a keycode in structure. 

Synopsis 

KeySym XLookupKeysym ( event, index) 
XKeyEvent * event ; 
int index; 

Arguments 

event Specifies the KeyPress or KeyRelease event that is to be used. 

index Specifies which keysym from the list associated with the keycode in the event to 

return. These correspond to the modifier keys, and the symbols ShiftMap- 
Index, LockMapIndex, ControlMapIndex, ModlMapIndex, Mod2- 
Maplndex, ModSMapIndex, Mod4MapIndex, and ModSMapIndex can be 
used. 

Description 

Given a keyboard event and the index into the list of keysyms for that keycode, XLookup 
Keysym returns the keysym from the list that corresponds to the keycode in the event. If no 
keysym is defined for the keycode of the event, XLookupKeysym returns NoSymbol. 

Each keycode may have a list of associated keysyms, which are portable symbols representing 
the meanings of the key. The index specifies which keysym in the list is desired, indicating 
the combination of modifier keys that are currently pressed. Therefore, the program must inter 
pret the state member of the XKeyEvent structure to determine the index before calling 
this function. The exact mapping of modifier keys into the list of keysyms for each keycode is 
server-dependent beyond the fact that the first keysym corresponds to the keycode without 
modifier keys, and the second corresponds to the keycode with Shift pressed. 

XLookupKeysym simply calls XKeycodeToKeysym, using arguments taken from the speci 
fied event structure. 

Structures 

typedef struct { 

int type; /* of event */ 

unsigned long serial; /* # of last request processed by server */ 

Bool send_event; /* true if this came from a SendEvent request */ 

Display ^display; /* display the event was read from */ 

Window window; /* "event" window it is reported relative to */ 

Window root; /* root window that the event occured on */ 

Window subwindow; /* child window */ 

Time time; /* milliseconds */ 

int x, y; /* pointer x, y coordinates in event window */ 

int x root, y root; /* coordinates relative to root */ 

unsigned int state; /* key or button mask */ 

unsigned int keycode; /* detail */ 

Bool same_screen; /* same screen flag */ 

} XKeyEvent; 



Xlib Reference Manual 309 



XLOQkupKeysym (continued) Xlib - Keyboard 

Related Commands 

XChangeKeyboardMapping, XDeleteModif iermapEntry, XFreeModif iermap, 
XGetKeyboardMapping, XGetModif ierMapping, XInsertModif iermapEntry, 
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupString, 
XNewModif ierMap, XQueryKeymap, XRebindKeysym, XRef reshKeyboard- 
Mapping, XSetModif ierMapping, XStringToKeysym. 



310 Xlib Reference Manual 



Xlib -Keyboard 



J XLookupString 



Name 

XLookupString map a key event to ASCH string, keysym, and ComposeStatus. 

Synopsis 

int XLookupString ( event, buffer, num_bytes, keysym, status) 
XKeyEvent *event; 

char * buffer; /* RETURN */ 

int num_bytes ; 

KeySym * keysym; /* RETURN */ 

XComposeStatus *status; /* not implemented */ 

Arguments 

event Specifies the key event to be used. 

buffer Returns the resulting string. 

num_bytes Specifies the length of the buffer. No more than num_bytes of translation 
are returned. 

keysym If this argument is not NULL, it specifies the keysym ID computed from the 

event. 

status Specifies the XCompose structure that contains compose key state informa 

tion and that allows the compose key processing to take place. This can be 
NULL if the caller is not interested in seeing compose key sequences. Not 
implemented in X Consortium Xlib through Release 4. 

Description 

XLookupString gets an ASCH string and a keysym that are currently mapped to the keycode 
in a KeyPress or KeyRelease event, using the modifier bits in the key event to deal with 
shift, lock and control. The XLookupString return value is the length of the translated 
string and the string s bytes are copied into buffer. The length may be greater than 1 if the 
event s keycode translates into a keysym that was rebound with XRebindKeysym. 

The compose status is not implemented in any release of the X Consortium version of Xlib 
through Release 4. 

In Release 4, XLookupString implements the new concept of keyboard groups. Keyboard 
groups support having two complete sets of keysyms for a keyboard. Which set will be used 
can be toggled using a particular key. This is implemented by using the first two keysyms in 
the list for a key as one set, and the next two keysyms as the second set. For more information 
on keyboard groups, see Volume One, Appendix G, Release Notes. 

For more information on using XLookupString in general, see Volume One, Chapter 9, The 
Keyboard and Pointer. 

Structures 

/* 

* Compose sequence status structure, used in calling XLookupString. 
*/ 



Xlib Reference Manual 3 1 1 



XLOQkupString (continued) Xlib - Keyboard 

typedef struct _XComposeStatus { 

char *compose_ptr; /* state table pointer */ 

int chars_matched; /* match state */ 
} XComposeStatus; 

typedef struct { 

int type; /* of event */ 

unsigned long serial; /* # of last request processed by server */ 

Bool send_event; /* true if this came from a SendEvent request */ 

isplay display; /* Display the event was read from */ 

Window window; /* "event" window it is reported relative to */ 

Window root; /* roo t window that the event occured on */ 

Window subwindow; /* child window */ 

Time time; /* milliseconds */ 

L x/ y; /* Pointer x, y coordinates in event window */ 

int x_root, y_root; /* coordinates relative to root */ 

unsigned int state; /* key or button mask */ 

unsigned int keycode; /* detail */ 

Bool same_screen; /* same screen flag */ 
} XKeyEvent; 

Related Commands 

XChangeKeyboardMapping,XDeleteModifiermapEntry,XFreeModifiermap 

XGetKeyboardMapping,XGetModifierMa P ping,XInsertModifierma P Entry 

<eycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym 

f ierMap, XQueryKeymap, XRebindKeySym, XRef reshKeyboard- 
Mapping, XSetModif ierMapping, XStringToKeysym. 



312 

Xlib Reference Manual 



-Xlib- Window Manipulation XLOWerWilldOW 

Name 

XLowerWindow lower a window in the stacking order. 

Synopsis 

XLowerWindow ( display, w) 
Display *display; 
Window w; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

w Specifies the ID of the window to be lowered. 

Description 

XLowerWindow lowers a window in the stacking order of its siblings 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, while leaving its x and y location on the desk constant. Lowering a mapped window 
will generate exposure events on any windows it formerly obscured. 

If the override_redirect attribute of the window (see Chapter 4, Window Attributes) is 
False and the window manager has selected SubstructureRedirectMask on the par 
ent, then a Conf igureRequest event is sent to the window manager, and no further pro 
cessing is performed. Otherwise, the window is lowered to the bottom of the stack. 

LeaveNotify events are sent to the lowered window if the pointer was inside it, and 
EnterNotif y events are sent to the window which was immediately below the lowered win 
dow at the pointer position. 

For more information, see Volume One, Chapter 14, Window Management. 

Errors 

BadWindow 

Related Commands 

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate- 
SubwindowsUp, XConf igureWindow, XMoveResizeWindow, XMoveWindow, 
XQueryTree, XRaiseWindow, XReparentWindow, XResizeWindow, XRestack- 
Windows. 



Xlib Reference Manual 313 



XMakeAssoc \ X||b _ Assoc|atlon Tab|es _ 

Name 

XMakeAssoc create an entry in an association table. 

Synopsis 

XMakeAssoc ( display, table, x_id f data) 
Display * display; 
XAssocTable * table; 
XID x_id; 
caddr_t data; 

Arguments 

display Specifies a connection to an X server; returned from xopenDi splay. 

tabl e Specifies the association table in which an entry is to be made. 

x_i d Specifies the X resource ID. 

data Specifies the data to be associated with the X resource ID. 

Description 

XMakeAssoc inserts data into an XAssocTable keyed on an XID. Association tables allow 
you to easily associate data with resource ID s for later retrieval. Association tables are local, 
accessible only by this client. 

This function is provided for compatibility with X Version 10. To use it you must include the 
file <Xll/X10.h> and link with the library -loldX. 

Data is inserted into the table only once. Redundant inserts are meaningless and cause no prob 
lems. The queue in each association bucket is sorted from the lowest XID to the highest XID. 

For more information, see Volume One, Appendix B,X70 Compatibility. 
Structure 

typedef struct { 

XAssoc *buckets; /* pointer to first bucket in bucket array */ 
int size; /* table size (number of buckets) */ 

} XAssocTable; 

typedef struct _XAssoc { 

struct _XAssoc *next; /* next object in this bucket */ 

struct _XAssoc *prev; /* previous object in this bucket */ 

Display *display; /* display which owns the ID */ 

XID x_id; /* X Window System ID * / 

char *data; /* pointer to untyped memory */ 

} XAssoc; 

Related Commands 

XCreateAssocTable, XDeleteAssoc, XDestroyAssocTable, XLookUpAssoc. 



3 14 Xlib Reference Manual 



Xlib - Window Mapping 



J XMapRaised 



Name 

XMapRaised map a window on top of its siblings. 

Synopsis 

XMapRaised ( display, w) 
Display * display ; 
Window w; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenD i sp 1 ay . 

w Specifies the window ID of the window to be mapped and raised. 

Description 

XMapRaised marks a window as eligible to be displayed. It will actually be displayed if its 
ancestors are mapped, it is on top of sibling windows, and it is not obscured by unrelated win 
dows. XMapRaised is similar to XMapWindow, except it additionally raises the specified 
window to the top of the stack among its siblings. Mapping an already mapped window with 
XMapRaised raises the window. See XMapWindow for further details. 

For more information, see Volume One, Chapter 14, Window Management. 
Errors 

BadWindow 

Related Commands 

XMapSubwindows, XMapWindow, XUnmapSubwindows, XUnmapWindow. 



Xlib Reference Manual 



315 



XMapSubwindows 

Xlib - Window Mapping- 
Name 

XMapSubwindows map all subwindows of window. 

Synopsis 

XMapSubwindows ( display, w) 
Display * display; 
Window w; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

w Specifies the ID of the window whose subwindows are to be mapped. 

Description 

XMapSubwindows maps all subwindows of a window in top-to-bottom stacking order. 
XMapSubwindows also generates an Expose event on each newly displayed window. This 
is much more efficient than mapping many windows one at a time, as much of the work need 
only be performed once for all of the windows rather than for each window. XMap 
Subwindows is not recursive it does not map the subwindows of the subwindows. 

For more information, see Volume One, Chapter 14, Window Management. 
Errors 

BadWindow 

Related Commands 

XMapRaised, XMapWindow, XUnmapSubwindows, XUnmapWindow. 



316 Xlib Reference Manual 



-Xlib - Window Mapping XMapWindOW 

Name 

XMapWindow map a window. 

Synopsis 

XMapWindow (display, w) 
Display * display ; 
Window w; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the ID of the window to be mapped. 

Description 

XMapWindow maps a window, making it eligible for display depending on its stacking order 
among its siblings, the mapping status of its ancestors, and the placement of other visible win 
dows. If all the ancestors are mapped, and it is not obscured by siblings higher in the stacking 
order, the window and all of its mapped subwindows are displayed. 

Mapping a window that has an unmapped ancestor does not display the window but marks it as 
eligible for display when its ancestors become mapped. Mapping an already mapped window 
has no effect (it does not raise the window). 

Note that for a top-level window, the window manager may intervene and delay the mapping of 
the window. The application must not draw until it has received an Expose event on the win 
dow. 

If the window is opaque, XMapWindow generates Expose events on each opaque window 
that it causes to become displayed. If the client first maps the window, then paints the window, 
then begins processing input events, the window is painted twice. To avoid this, the client 
should use either of two strategies: 

1. Map the window, call XSelect Input for exposure events, wait for the first Expose 
event, and repaint each window explicitly. 

2. Call XSelect Input for exposure events, map, and process input events normally. 
Exposure events are generated for each window that has appeared on the screen, and the 
client s normal response to an Expose event should be to repaint the window. 

The latter method is preferred as it usually leads to simpler programs. If you fail to wait for the 
Expose event in the first method, it can cause incorrect behavior with certain window manag 
ers that intercept the request. 

Errors 

BadWindow 

Related Commands 

XMapRaised, XMapSubwindows, XUnmapSubwindows, XUnmapWindow. 



Xlib Reference Manual 3 1 7 



XMaskEvent \ X|lb _ |nput Hand||ng _ 

Name 

XMaskEvent remove the next event that matches mask. 

Synopsis 

XMaskEvent ( display, event_mask, rep) 
Display *display; 
long event_mask; 
XEvent *rep; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

even t_mask Specifies the event mask. See XSelect Input for a complete list of the 
event mask symbols that can be ORed together. 

rep Returns the event removed from the input queue. 

Description 

XMaskEvent removes the next event in the queue which matches the passed mask. The event 
is copied into an XEvent supplied by the caller. Other events in the queue are not discarded. 
If no such event has been queued, XMaskEvent flushes the request buffer and waits until one 
is received. Use XCheckMaskEvent if you do not wish to wait. 

XMaskEvent never returns MappingNotify, SelectionClear, SelectionNotify, 
or SelectionRequest events. When you specify ExposureMask it will return 
GraphicsExpose or NoExpose events if those occur. 

Related Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued, 
XGetlnputFocus, XGetMotionEvents, Xlf Event, XNextEvent, XPeekEvent, 
XPeeklf Event, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSet- 
InputFocus, XSynchronize, XWindowEvent. 



318 Xlib Reference Manual 



-x,,b-v,,ua, s / XMatchVisuallnfo 

Name 

XMatchVisuallnfo obtain the visual information that matches the desired depth and class. 

Synopsis 

Status XMatchVisuallnfo ( display, screen, depth, class, vinfo) 
Display *display; 
int screen ; 
int depth; 
int class; 
XVisuallnfo *vinfo; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

screen Specifies the screen. 

depth Specifies the desired depth of the visual. 

class Specifies the desired class of the visual, such as Pseudocolor or True- 

Color. 

vinfo Returns the matched visual information. 

Description 

XMatchVisuallnfo returns the visual information for a visual supported on the screen that 
matches the specified depth and class. Because multiple visuals that match the specified 
depth and class may be supported, the exact visual chosen is undefined. 

If a visual is found, this function returns a nonzero value and the information on the visual is 
returned to vinfo. If a visual is not found, it returns zero. 

For more information on visuals, see Volume One, Chapter 7, Color. 
Structures 

typedef struct { 

Visual *visual; 

VisuallD visualid; 

int screen; 

unsigned int depth; 

int class; 

unsigned long red_mask; 

unsigned long green_mask; 

unsigned long blue_mask; 

int colormap_size; 

int bits_per_rgb; 
} XVisuallnfo; 

Related Commands 

Default Visual, XGetVisuallnf o. 



Xlib Reference Manual 



319 



XMOVeReSizeWindOW . .xpb-nda. Manipulation- 

Name 

XMoveResizeWindow change the size and position of a window. 

Synopsis 

XMoveResizeWindow ( display, w, x, y, width, height) 
Display *display; 
Window w; 
int x, y; 
unsigned int width, height; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

w Specifies the ID of the window to be reconfigured. 

x Specify the new x and y coordinates of the upper-left pixel of the window s bor- 

y der, relative to the window s parent. 

width Specify the new width and height in pixels. These arguments define the interior 

height size of the window. 

Description 

XMoveResizeWindow moves or resizes a window or both. XMoveResizeWindow does 
not raise the window. Resizing a mapped window may lose its contents and generate an 
Expose event on that window depending on the bit_gravity attribute. Configuring a win 
dow may generate exposure events on windows that the window formerly obscured, depending 
on the new size and location parameters. 

If the override_redirect attribute of the window is False (see Volume One, Chapter 4, 
Window Attributes) and the window manager has selected SubstructureRedirectMasJc 
on the parent, then a Conf igureRequest event is sent to the window manager, and no fur 
ther processing is performed. 

If the client has selected StructureNotifyMask on the window, then a Conf igure- 
Notify event is generated after the move and resize takes place, and the event will contain 
the final position and size of the window. 

Errors 

BadValue 
BadWindow 

Related Commands 

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate- 
SubwindowsUp, XConf igureWindow, XLowerWindow, XMoveWindow, XQuery- 
Tree, XRaiseWindow, XReparentWindow, XResizeWindow, XRestackWindows. 



320 Xlib Reference Manual 



-Xlib -Window Manipulation XMOVeWindOW 

Name 

XMoveWindow move a window. 

Synopsis 

XMoveWindow (display, w, x, y) 
Display * display; 
Window w; 
int x, y; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the ID of the window to be moved. 

x Specify the new x and y coordinates of the upper-left pixel of the window s bor- 

y der (or of the window itself, if it has no border), relative to the window s parent. 

Description 

XMoveWindow changes the position of the origin of the specified window relative to its par 
ent. XMoveWindow does not change the mapping state, size, or stacking order of the window, 
nor does it raise the window. Moving a mapped window will lose its contents if: 

Its background_pixmap attribute is ParentRelative. 

The window is obscured by nonchildren and no backing store exists. 

If the contents are lost, exposure events will be generated for the window and any mapped 
subwindows. Moving a mapped window will generate exposure events on any formerly 
obscured windows. 

If the override_redirect attribute of the window is False (see Volume One, Chapter 4, 
Window Attributes) and the window manager has selected SubstructureRedirectMask 
on the parent, then a Conf igureRequest event is sent to the window manager, and no fur 
ther processing is performed. 

If the client has selected StructureNotifyMask on the window, then a Conf igure- 
Notif y event is generated after the move takes place, and the event will contain the final posi 
tion of the window. 

Errors 

BadWindow 

Related Commands 

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate- 
SubwindowsUp, XConf igureWindow, XLowerWindow, XMoveResizeWindow, 
XQueryTree, XRaiseWindow, XReparentWindow, XResizeWindow, XRestack- 
Windows. 



Xlib Reference Manual 321 



XNewModifiermap \ m _ Keyboard _ 

Name 

XNewModifiermap create a keyboard modifier mapping structure. 

Synopsis 

XModif ierKeymap * XNewModifiermap (max_keys_per_mod) 
int max_keys_per_mod; 

Arguments 

max_keys_jper_mod 

Specifies the maximum number of keycodes assigned to any of the modifiers in the 
map. 

Description 

XNewModifiermap returns a XModif ierKeymap structure and allocates the needed space. 
This function is used when more than one XModif ierKeymap structure is needed. 
max_keys_per_mod depends on the server and should be gotten from the XModif ier 
Keymap returned by XGetModif ierMapping. 

For more information on keyboard preferences, see Volume One, Chapter 9, The Keyboard and 
Pointer. 

Structures 

typedef struct { 

int max_keypermod; /* server s max number of keys per modifier */ 
KeyCode *modif iermap; /* An 8 by max_keypermod array 
* of the modifiers */ 

} XModifierKeymap; 

Related Commands 

XChangeKeyboardMapping, XDeleteModifiermapEntry, XFreeModif iermap, 
XGetKeyboardMapping, XGetModif ierMapping, XInsertModif iermapEntry, 
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym, 
XLookupString, XQueryKeymap, XRebindKeysym, XRef reshKeyboardMapping, 
XSetModif ierMapping, XStringToKeysym. 



322 Xlib Reference Manual 



-Xllb - input HandHng / XNeXtEvent 

Name 

XNextEvent get the next event of any type or window. 

Synopsis 

XNextEvent ( display, report) 
Display * display; 
XEvent * report; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

report Returns the event removed from the event queue. 

Description 

XNextEvent removes an event from the head of the event queue and copies it into an 
XEvent structure supplied by the caller. If the event queue is empty, XNextEvent flushes 
the request buffer and waits (blocks) until an event is received. Use XGheckMaskEvent or 
XChecklf Event if you do not want to wait. 

For more information, see Volume One, Chapter 8, Events. 
Related Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued, 
XGetlnputFocus, XGetMotionEvents, Xlf Event, XMaskEvent, XPeekEvent, 
XPeeklf Event, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSet- 
InputFocus, XSynchronize, XWindowEvent. 



Xlib Reference Manual 323 



^ Xlib - HouseKeeping 

Name 

XNoOp send a NoOp to exercise connection with the server. 

Synopsis 

XNoOp (display) 

Display * display; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

Description 

XNoOp sends a NoOperation request to the X server, thereby exercising the connection. 
This request can be used to measure the response time of the network connection. XNoOp does 
not flush the request buffer. 

Related Commands 

Def aultScreen, XCloseDisplay, XFree, XOpenDisplay. 



324 Xlib Reference Manual 



Xlib -Regions- 



J XOffsetReglon 



Name 

XOffsetRegion change offset of a region. 

Synopsis 

XOffsetRegion (r, dx , dy) 
Region r; 
int dx f dy ; 

Arguments 

r Specifies the region. 

dx Specify the amount to move the specified region relative to the origin of all 

dy regions. 



Description 

XOffsetRegion changes the offset of the region the specified amounts in the x and y direc 
tions. 

Regions are located using an offset from a point (the region origin) which is common to all 
regions. It is up to the application to interpret the location of the region relative to a drawable. 
If the region is to be used as a clipjmask by calling XSetRegion, the upper-left corner of 
the region relative to the drawable used in the graphics request will be at (xof fset + 
clip_x_origin, yof f set + clip_y_origin) , where xof fset and yof f set are 
the offset of the region and clip_x_origin and clip_y_origin are components of the 
GC used in the graphics request. 

Structures 

Region is a pointer to an opaque structure type. 

Related Commands 

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion, 
XIntersectRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion, 
XSetRegion, XShrinkRegion, XSubtractRegion, XUnionRectWithRegion, 
XUnionRegion, XXorRegion. 



Xlib Reference Manual 325 



XOpenDisplay 



X 



Xlib-HouseKeeping 



Name 

XOpenDisplay connect a client program to an X server. 

Synopsis 

Display *XOpenDisplay ( display_name) 
char *display_name; 

Arguments 

di spl ay_name 

Specifies the display name, which determines the server to connect to and the 
communications domain to be used. See Description below. 

Description 

The XOpenDisplay routine connects the client to the server controlling the hardware display 
through TCP, or UNIX or DECnet streams. 

If display_name is NULL, the value defaults to the contents of the DISPLAY environment 
variable on UNIX-based systems. On non-UNIX-based systems, see that operating system s 
Xlib manual for the default display_name. The display_name or DISPLAY environment 
variable is a string that has the format hostname: server or host 
name: server. screen. For example, frog : . 2 would specify screen 2 of server on the 
machine frog. 

hostname Specifies the name of the host machine on which the display is physically con 
nected. You follow the hostname with either a single colon (:) or a double colon 
(::), which determines the communications domain to use. Any or all of the 
communication protocols can be used simultaneously on a server built to sup 
port them (but only one per client). 

If hostname is a host machine name and a single colon (:) separates the 
hostname and display number, XOpenDisplay connects the hardware 
display to TCP streams. In Release 4 and later, the string "unix" is no 
longer required and the string ":o" connects the local server. 

If hostname is "unix" and a single colon (:) separates it from the display 
number, XOpenDisplay connects the hardware display to UNIX domain 
IPC streams. In Release 4, the string "unix" should be omitted. 

If hostname is a host machine name and a double colon (::) separates 
the hostname and display number, XOpenDisplay connects with the 
server using DECnet streams. To use DECnet, however, you must build 
all software for DECnet. A single X server can accept both TCP and 
DECnet connections if it has been built for DECnet. 

server Specifies the number of the server on its host machine. This display number 
may be followed by a period (.). A single CPU can have more than one display; 
the displays are numbered starting from 0. 



Xlib Reference Manual 



Xlib - HouseKeepIng (continued) XOpenDiSplay 

screen Specifies the number of the default screen on server. Multiple screens can be 
connected to (controlled by) a single X server, but they are used as a single dis 
play by a single user, screen merely sets an internal variable that is returned 
by the Def aultScreen macro. If screen is omitted, it defaults to 0. 

If successful, XOpenDisplay returns a pointer to a Display. This structure provides many 
of the specifications of the server and its screens. If XOpenDisplay does not succeed, it 
returns a NULL. 

After a successful call to XOpenDisplay, all of the screens on the server may be used by the 
application. The screen number specified in the display_name argument serves only to 
specify the value that will be returned by the Def aultScreen macro. After opening the dis 
play, you can use the ScreenCount macro to determine how many screens are available. 
Then you can reference each screen with integer values between and the value returned by 
(ScreenCount -1). 

For more information, see Volume One, Chapter 2, X Concepts, and Chapter 3, Basic Window 
Program. 

Related Commands 

Def aultScreen, XCloseDisplay, XFree, XNoOp. 



Xlib Reference Manual 327 



XParseColor x ,,b-co,orc e ,,s- 

Name 

XParseColor look up RGB values from ASCII color name or translate hexadecimal value. 

Synopsis 

Status XParseColor ( display, colormap, spec, rgb_db_def) 
Display ^display; 
Colormap colormap; 
char *spec; 
XColor *rgb_db_def; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XQpenDisplay. 

colormap Specifies a colormap. This argument is required but is not used. The same 
code is used to process XParseColor and XLookupColor, but only 
XLookupColor returns the closest values physically possible on the screen 
specified by colormap. 

spec Specifies the color specification, either as a color name or as hexadecimal 

coded in ASCII (see below). Upper or lower case does not matter. The string 
must be null-terminated, and should be in ISO LATIN- 1 encoding, which 
means that the first 128 character codes are ASCII, and the second 128 char 
acter codes are for special characters needed in western languages other than 
English. 

rgb_db_def Returns the RGB values corresponding to the specified color name or hexade 
cimal specification, and sets its DoRed, DoGreen and DoBlue flags. 

Description 

XParseColor returns the RGB values corresponding to the English color name or hexade 
cimal values specified, by looking up the color name in the color database, or translating the 
hexadecimal code into separate RGB values. It takes a string specification of a color, typically 
from a command line or XGet Default option, and returns the corresponding red, green, and 
blue values, suitable for a subsequent call to XAllocColor or XStoreColor. spec can be 
given either as an English color name (as in XAllocNamedColor) or as an initial sharp sign 
character followed by a hexadecimal specification in one of the following formats: 

#RGB (one character per color) 

#RRGGBB (two characters per color) 

#RRRGGGBBB (three characters per color) 

#RRRRGGGGBBBB (four characters per color) 

where R, G, and B represent single hexadecimal digits (upper or lower case). 

The hexadecimal strings must be null-terminated so that XParseColor knows when it has 
reached the end. When fewer than 16 bits each are specified, they represent the most signifi 
cant bits of the value. For example, # 3 a 7 is the same as#3000a0007000. 



Xlib Reference Manual 



Xlib - Color Cells (continued) XParseColor 

This routine will fail and return aStatusof zero if the initial character is a sharp sign but the 
string otherwise fails to fit one of the above formats, or if the initial character is not a sharp sign 
and the named color does not exist in the server s database. 

Status is zero on failure, nonzero on success. 

For more information, see Volume One, Chapter 7, Color. 

Structures 

typedef struct { 

unsigned long pixel; 

unsigned short red, green, blue; 

char flags; /* DoRed, DoGreen, DoBlue */ 

char pad; 
} XColor; 

Errors 

BadColormap 

Related Commands 

BlackPixel, WhitePixel, XAllocColor, XAllocColorCells, XAllocColor- 
Planes, XAllocNamedColor, XFreeColors, XLookupColor, XQueryColor, 
XQueryColors, XStoreColor, XStoreColors, XStoreNamedColor. 



Xlib Reference Manual 329 



XParseGeometry . Vll 

v Xlib - Standard Geometry 

Name 

XParseGeometry generate position and size from standard window geometry string. 

Synopsis 

int XParseGeometry (parsestring, x, y, width, height) 
char *parsestring; 

int *x, *y; /* RETURN */ 

unsigned int * width, *height; /* RETURN */ 

Arguments 

parsestring Specifies the string you want to parse. 

x Return the x and y coordinates (offsets) from the string. 

y 

wi dth Return the width and height in pixels from the string. 

height 

Description 

By convention, X applications provide a geometry command line option to indicate window 
size and placement. XParseGeometry makes it easy to conform to this standard because it 
allows you to parse the standard window geometry string. Specifically, this function lets you 
parse strings of the form: 

= < wi dth>x<height> { +- } <xoffset> { +- } <yoffset> 

The items in this string map into the arguments associated with this function. (Items enclosed 
in o are integers and items enclosed in { } are a set from which one item is allowed. Note that 
the brackets should not appear in the actual string.) 

XParseGeometry returns a bitmask that indicates which of the four values (width, 
height, xoffset, and yoffset) were actually found in the string, and whether the x and y 
values are negative. The bits are represented by these constants: XValue, YValue, width- 
Value, Height Value, XNegative, and YNegative, and are defined in <Xll/Xutil.h>. 
For each value found, the corresponding argument is updated and the corresponding bitmask 
element set; for each value not found, the argument is left unchanged, and the bitmask element 
is not set. 

For more information, see Volume One, Chapter 11, Managing User Preferences. 
Related Commands 

XGeometry, XTranslateCoordinates, XWMGeometry. 



330 Xlib Reference Manual 



-X.ib - input Handling 

Name 

XPeekEvent get an event without removing it from the queue. 

Synopsis 

XPeekEvent ( display, report) 
Display * display; 
XEvent * report; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

report Returns the event peeked from the input queue. 

Description 

XPeekEvent peeks at an input event from the head of the event queue and copies it into an 
XEvent supplied by the caller, without removing it from the input queue. If the queue is 
empty, XPeekEvent flushes the request buffer and waits (blocks) until an event is received. 
If you do not want to wait, use the QLength macro to determine if there are any events to peek 
at, or use XPeeklf Event. XEventsQueued can perform the function of either QLength 
or XPending and more. 

For more information, see Volume One, Chapter 8, Events. 
Related Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued, 
XGetlnputFocus, XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent, 
XPeeklf Event, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSet- 
InputFocus, XSynchronize, XWindowEvent. 



Xlib Reference Manual 33 1 



XPeeklfEvent \ X|lb _ |nput Hand|lng _ 

Name 

XPeeklfEvent get an event matched by predicate procedure without removing it from the 
queue. 

Synopsis 

XPeeklfEvent ( display , event, predicate, args) 
Display *display; 

XEvent *event; /* RETURN */ 

Bool (^predicate) () ; 
char *args; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

event Returns the matched event. 

predicate Specifies the procedure to be called to determine if each event that arrives in 
the queue is the desired one. 

args Specifies the user- specified arguments that will be passed to the predicate 

procedure. 

Description 

XPeeklfEvent returns an event only when the specified predicate procedure returns True 
for the event. The event is copied into event but not removed from the queue. The specified 
predicate is called each time an event is added to the queue, with the arguments display, 
event, and arg. 

XPeeklfEvent flushes the request buffer if no matching events could be found on the queue, 
and then waits for the next matching event. 

For more information, see Volume One, Chapter 8, Events. 
Related Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued, 
XGetlnputFocus, XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent, 
XPeekEvent, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSet- 
InputFocus, XSynchronize, XWindowEvent. 



332 Xlib Reference Manual 



Xlib -Input Handling- 



J XPending 



Name 

XPending flush the request buffer and return the number of pending input events. 

Synopsis 

int XPending ( display) 
Display *display; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

Description 

XPending returns the number of input events that have been received by Xlib from the server, 
but not yet removed from the queue. If there are no events on the queue, XPending flushes 
the request buffer, and returns the number of events transferred to the input queue as a result of 
the flush. 

The QLength macro returns the number of events on the queue, but without flushing the 
request buffer first. 

For more information, see Volume One, Chapter 8, Events. 
Related Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued, 
XGetlnputFocus, XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent, 
XPeekEvent, XPeeklf Event, XPutBackEvent, XSelectlnput, XSendEvent, 
XSetlnputFocus, XSynchronize, XWindowEvent. 



Xlib Reference Manual 333 



Xpermalloc \ Vll 

v Xlib - Resource Manager 

Name 

Xpermalloc allocate memory never to be freed. 

Synopsis 

char *Xpermalloc ( size) 
unsigned int size; 

Arguments 

si ze Specifies the size in bytes of the space to be allocated. This specification is 

rounded to the nearest 4-byte boundary. 

Description 

Xpermalloc allocates some memory that will not be freed until the process exits. Xperm 
alloc is used by some toolkits for permanently allocated storage and allows some perfor 
mance and space savings over the completely general memory allocator. 



334 Xlib Reference Manual 



Xlib -Regions- 



J XPointlnRegion 



Name 

XPointlnRegion determine if a point is inside a region. 

Synopsis 

Bool XPointlnRegion (r, x, y) 
Region r; 
int x, y; 

Arguments 

r Specifies the region. 

x Specify the x and y coordinates of the point relative to the region s origin. 

y 

Description 

XPointlnRegion returns True if the point x, y is contained in the region r. A point 
exactly on the boundary of the region is considered inside the region. 

Regions are located using an offset from a point (the region origin) which is common to all 
regions. It is up to the application to interpret the location of the region relative to a drawable. 

For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text. 

Structures 

Region is a pointer to an opaque structure type. 

Related Commands 

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion, 
XIntersectRegion, XOf f setRegion, XPolygonRegion, XRectlnRegion, XSet- 
Region, XShrinkRegion, XSubtractRegion, XUnionRectWithRegion, XUnion- 
Region, XXorRegion. 



Xlib Reference Manual 335 



XPolygonRegion \. 



xi|b 



Name 

XPolygonRegion generate a region from points. 

Synopsis 

Region XPolygonRegion (points , n, fill_rule) 
XPoint points [] ; 
int n; 
int fill_rule; 

Arguments 

points Specifies a pointer to an array of points. 

n Specifies the number of points in the polygon. 

fill_rule Specifies whether areas overlapping an odd number of times should be part of 
the region (windingRule) or not part of the region (EvenOddRule). See 
Volume One, Chapter 5, The Graphics Context, for a description of the fill 
rule. 

Description 

XPolygonRegion creates a region defined by connecting the specified points, and returns a 
pointer to be used to refer to the region. 

Regions are located relative to a point (the region origin) which is common to all regions. In 
XPolygonRegion, the coordinates specified in points are relative to the region origin. By 
specifying all points relative to the drawable in which they will be used, the region origin can 
be coincident with the drawable origin. It is up to the application whether to interpret the loca 
tion of the region relative to a drawable or not. 

If the region is to be used as a clip_mask by calling XSetRegion, the upper-left corner of 
the region relative to the drawable used in the graphics request will be at (xof f set + 
clip_x_origin, yof f set + clip_y_origin) , where xof f set and yof f set are 
the offset of the region (if any) and clip_x_origin and clip_y_origin are elements of 
the GC used in the graphics request. The fill_rule can be either of these values: 

EvenOddRule Areas overlapping an odd number of times are not part of the region. 

windingRule Overlapping areas are always filled. 

For more information on structures, see Volume One, Chapter 6, Drawing Graphics and Text. 

Structures 

Region is a pointer to an opaque structure type. 

Related Commands 

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion, 
XIntersectRegion, XOf f setRegion, XPointlnRegion, XRectlnRegion, XSet 
Region, XShrinkRegion, XSubtractRegion, XUnionRectWithRegion, XUnion- 
Region, XXorRegion. 



336 Xlib Reference Manual 



-XMb - ,npu, Hand,ing 



Name 

XPutBackEvent push an event back on the input queue. 

Synopsis 

XPutBackEvent (display , event) 
Display ^display; 
XEvent * event; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

even t Specifies a pointer to the event to be requeued. 

Description 

XPutBackEvent pushes an event back onto the head of the current display s input queue (so 
that it would become the one returned by the next XNextEvent call). This can be useful if 
you have read an event and then decide that you d rather deal with it later. There is no limit to 
how many times you can call XPutBackEvent in succession. 

For more information, see Volume One, Chapter 8, Events. 
Related Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued, 
XGetlnputFocus, XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent, 
XPeekEvent, XPeeklf Event, XPending, XSelectlnput, XSendEvent, XSet- 
InputFocus, XSynchronize, XWindowEvent. 



Xlib Reference Manual 337 



XPutlma 9 e x,,b - 

Name 

XPutlmage draw an image on a window or pixmap. 

Synopsis 

XPutlmage ( display, drawable, gc , image, src_x, src_y, 

dst_x, dst_y, width, height) 
Display ^display; 
Drawable drawable; 
GC gc ; 

Xlmage * image; 
int src_x, src_y; 
int dst_x, dst_y ; 
unsigned int width, height; 

Arguments 

display Specifies a connection to an X server; returned from XQpenDisplay. 

drawable Specifies the drawable. 

gc Specifies the graphics context. 

image Specifies the image you want combined with the rectangle. 

src_x Specify the coordinates of the upper-left corner of the rectangle to be copied, 

src_y relative to the origin of the image. 

dst_x Specify the x and y coordinates, relative to the origin of the drawable, where 

dst_y the upper-left corner of the copied rectangle will be placed. 

wi dth Specify the width and height in pixels of the rectangular area to be copied. 

height 

Description 

XPutlmage draws a section of an image on a rectangle in a window or pixmap. The section 
of the image is defined by src_x, src_y, width and height. 

There is no limit to the size of image that can be sent to the server using XPutlmage. XPut 
lmage automatically decomposes the request to make sure that the maximum request size of 
the server is not exceeded. 

XPutlmage uses these graphics context components: function, plane_mask, subwin- 
dow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also 
uses these graphics context mode-dependent components: foreground and background. 

If an XYBitmap format image is used, then the depth of drawable must be 1, otherwise a 
BadMatch error is generated. The foreground pixel in gc defines the source for bits set to 
one in the image, and the background pixel defines the source for the bits set to zero. 

For XYPixmap and ZPixmap format images, the depth of the image must match the depth of 

drawable. 



338 Xlib Reference Manual 



Xlib - Images (continued) XPutlmage 

Structures 

typedef struct _XImage { 

int width, height; /* size of image */ 

int xoffset; /* number of pixels offset in x direction */ 

int format; /* XYBitmap, XYPixmap, ZPixmap */ 

char *data; /* pointer to image data */ 

int byte_order; /* data byte order, LSBFirst, MSBFirst */ 

int bitmap_unit; /* quant, of scan line 8, 16, 32 */ 

int bitmap_bit_order; /* LSBFirst, MSBFirst */ 

int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */ 

int depth; /* depth of image */ 

int bytes_per_line; /* accelerator to next line */ 

int bits_per_pixel; /* bits per pixel (ZPixmap) */ 

char *obdata; /* hook for the object routines to hang on */ 

struct funcs { /* image manipulation routines */ 

struct _XImage * (*create_image) (); 

int { *destroy_image) (); 

unsigned long ( *get_pixel) () ; 

int (*put_pixel) () ; 

struct __XImage * (*sub_image) (); 

int (*add_pixel) () ; 
} f; 
} X Image; 

Errors 

BadDrawable 

BadGC 

BadMatch See Description above. 

BadValue 

Related Commands 

ImageByteOrder, XAddPixel, XCreatelmage, XDestroy Image, XGet Image, 
XGetPixel, XGetSublmage, XPutPixel, XSublmage. 



Xlib Reference Manual 339 



XPutPixel "\ v, 

v Xlib - Images- 
Name 

XPutPixel set a pixel value in an image. 

Synopsis 

int XPutPixel (ximage f x f y, pixel) 
Xlmage * ximage; 
int x; 
int y; 
unsigned long pixel; 

Arguments 

ximage Specifies a pointer to the image to be modified. 

x Specify the x and y coordinates of the pixel to be set, relative to the origin of 

y the image. 

pixel Specifies the new pixel value. 

Description 

XPutPixel overwrites the pixel in the named image with the specified pixel value. The x 
and y coordinates are relative to the origin of the image. The input pixel value must be in same 
bit- and byte-order as the machine in which the client is running (that is, the Least Significant 
Byte (LSB) of the long is the LSB of the pixel). The x and y coordinates must be contained in 
the image. 

Structures 

typedef struct Ximage { 

int width, height; /* size of image */ 

int xoffset; /* number of pixels offset in x direction */ 

int format; /* XYBitmap, XYPixmap, ZPixmap */ 

char *data; /* pointer to image data */ 

int byte_order; /* data byte order, LSBFirst, MSBFirst */ 

int bitmap_unit; /* quant, of scan line 8, 16, 32 */ 

int bitmap_bit_order; /* LSBFirst, MSBFirst */ 

int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */ 

int depth; /* depth of image */ 

int bytes_per_line; /* accelerator to next line */ 

int bits_per_pixel; /* bits per pixel (ZPixmap) */ 

unsigned long red_mask; /* bits in z arrangment */ 

unsigned long green_mask; 

unsigned long blue_mask; 

char *obdata; /* hook for the object routines to hang on */ 

struct funcs { /* image manipulation routines */ 

struct _XImage * (*create_image) ( ) ; 

int (*destroy_image) (); 

unsigned long (*get_pixel)( ) ; 

int (*put_pixel) () ; 

struct Ximage * (*sub image) (); 

int (*add_pixel) () ; 
} f; 
} Ximage; 



340 Xlib Reference Manual 



Xlib- Images (continued) XPutPixel 

Related Commands 

ImageByteOrder, XAddPixel, XCreate Image, XDestroy Image, XGetlmage, 
XGetPixel, XGetSublmage, XPutlmage, XSublmage. 



Xlib Reference Manual 34 1 



XQueryBestCursor v^ 



-Xlib- Cursors- 



Name 

XQueryBestCursor get the closest supported cursor sizes. 

Synopsis 

Status XQueryBestCursor (display, draw-able, width, height, 

rwidth, rheight) 
Display * display ; 
Drawable drawable; 
unsigned int width, height; 
unsigned int * rwidth, * rheight / /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

draw-able Specifies a drawable that indicates which screen the cursor is to be used on. 
The best cursor may be different on different screens. 

width Specify the preferred width and height, in pixels. 

height 

rwidth Returns the closest supported cursor dimensions, in pixels, on the display 

rh ei gh t hardware. 

Description 

XQueryBestCursor returns the closest cursor dimensions actually supported by the display 
hardware to the dimensions you specify. 

Call this function if you wish to use a cursor size other than 16 by 16. XQueryBestCursor 
provides a way to find out what size cursors are actually possible on the display. Applications 
should be prepared to use smaller cursors on displays which cannot support large ones. 

XQueryBestCursor returns nonzero if the call succeeded in getting a supported size (which 
may be the same or different from the specified size), or zero if the call failed. 

Errors 

BadDrawable 

Related Commands 

XCreateFontCursor, XCreateGlyphCursor, XCreatePixmapCursor, XDef ine- 
Cursor, XFreeCursor, XQueryBestSize, XRecolorCursor, XUndef ineCursor. 



342 Xlib Reference Manual 



Xlib - Pixmaps and Tiles - 



J XQueryBestSize 



Name 

XQueryBestSize obtain the "best" supported cursor, tile, or stipple size. 

Synopsis 

Status XQueryBestSize (display, class, drawable, width, 

height, rwidth, rheight) 
Display * display ; 
int class; 
Drawable drawable; 
unsigned int width, height; 
unsigned int * rwidth, * rheight; /* RETURN */ 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenDi splay. 

class Specifies the class that you are interested in. Pass one of these constants: 

TileShape, CursorShape, or StippleShape. 

drawable Specifies a drawable ID that tells the server which screen you want the best 
size for. 

width Specify the preferred width and height in pixels. 

height 

rwidth Return the closest supported width and height, in pixels, available for the 

rheight object on the display hardware. 

Description 

XQueryBestSize returns the "fastest" or "closest" size to the specified size. For class of 
CursorShape, this is the closest size that can be fully displayed on the screen. For Tile- 
Shape and StippleShape, this is the closest size that can be tiled or stippled "fastest." 

For CursorShape, the drawable indicates the desired screen. For TileShape and 
StippleShape, the drawable indicates the screen and possibly the visual class and depth 
(server-dependent). An inputOnly window cannot be used as the drawable for TileShape 
or StippleShape (else a BadMatch error occurs). 

XQueryBestSize returns nonzero if the call succeeded in getting a supported size (may be 
the same or different from the specified size), or zero if the call failed. 

Errors 

BadDrawable 

BadMatch InputOnly drawable for class TileShape or StippleShape. 
BadValue 



Xlib Reference Manual 343 



XQueryBeStSize (continued) Xlib - Pixmaps and Tiles 

Related Commands 

XCreateBitmapFromData, XCreatePixmap, XCreatePixmapFromBitmapData, 
XFreePixmap, XQueryBestStipple, XQueryBestTile, XReadBitmapFile, 
XSetTile, XSetWindowBackgroundPixmap, XSetWindowBorderPixmap, 
XWriteBitmapFile. 



344 Xlib Reference Manual 



Xlib - Pixmaps and Tiles - 



J XQueryBestStipple 



Name 

XQueryBestStipple obtain the fastest supported stipple shape. 

Synopsis 

Status XQueryBestStipple (display, drawable, width, height, 

rwidth, rheight) 
Display * display; 
Drawable drawable; 
unsigned int width, height; 
unsigned int *rwidth, * rheight; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

drawable Specifies a drawable that tells the server which screen you want the best size 
for. 

width Specify the preferred width and height in pixels. 

height 

rwidth Return the width and height, in pixels, of the stipple best supported by the 

rh ei gh t display hardware. 

Description 

XQueryBestStipple returns the closest stipple size that can be stippled fastest. The draw- 
able indicates the screen and possibly the visual class and depth. An inputOnly window 
cannot be used as the drawable (else a BadMatch error occurs). 

XQueryBestStipple returns nonzero if the call succeeded in getting a supported size (may 
be the same or different from the specified size), or zero if the call failed. 

For more information on stipples, see Volume One, Chapter 5, The Graphics Context. 

Errors 

BadDrawable 

BadMatch InputOnly window. 

Related Commands 

XCreateBitmapFromData, XCreatePixmap, XCreatePixmapFromBitmapData, 
XFreePixmap, XQueryBestSize, XQueryBestTile, XReadBitmapFile, XSet- 
Tile, XSetWindowBackgroundPixmap, XSetWindowBorderPixmap, XWrite- 
BitmapFile. 



Xlib Reference Manual 345 



XQueryBestTile \ X||b _ pixmaps and T||es _ 

Name 

XQueryBestTile obtain the fastest supported fill tile shape. 

Synopsis 

Status XQueryBestTile ( display, drawable, width, height, 

rwidth, rheight) 
Display * display; 
Drawable drawable ; 
unsigned int width, height; 
unsigned int * rwidth, * rheight ; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

drawable Specifies a drawable that tells the server which screen you want the best size 
for. 

wi dth Specify the preferred width and height in pixels. 

height 

rwidth Return the width and height, in pixels, of the tile best supported by the dis- 

r height play hardware. 

Description 

XQueryBestTile returns the closest size that can be tiled fastest. The drawable indicates 
the screen and possibly the visual class and depth. An Input Only window cannot be used as 
the drawable. 

XQueryBestTile returns nonzero if the call succeeded in getting a supported size (may be 
the same or different from the specified size), or zero if the call failed. 

For more information on tiles, see Volume One, Chapter 5, The Graphics Context. 
Errors 

BadDrawable 

BadMatch InputOnly drawable specified. 

Related Commands 

XCreateBitmapFromData, XCreatePixmap, XCreatePixmapFromBitmapData, 
XFreePixmap, XQueryBestSize, XQueryBestStipple, XReadBitmapFile, 
XSetTile, XSetWindowBackgroundPixmap, XSetWindowBorderPixmap, 
XWriteBitmapFile. 



346 Xlib Reference Manual 



Xlib- Color Cells- 



J XQueryColor 



Name 

XQueryColor obtain the RGB values and flags for a specified colorcell. 

Synopsis 

XQueryColor ( display f cmap, colorcell_def) 
Display ^display; 
Colormap cmap; 
XColor *colorcell_def; /* SEND and RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

cmap Specifies the ID of the colormap from which RGB values will be retrieved. 

colorcell_def 

Specifies the pixel value and returns the RGB contents of that colorcell. 

Description 

XQueryColor returns the RGB values in colormap cmap for the colorcell corresponding to 
the pixel value specified in the pixel member of the XColor structure colorcell_def . 
The RGB values are returned in the red, green, and blue members of that structure, and the 
flags member of that structure is set to (DoRed I DoGreen | DoBlue) . The values 
returned for an unallocated entry are undefined. 

For more information, see Volume One, Chapter 7, Color. 
Structures 

typedef struct { 

unsigned long pixel; 

unsigned short red, green, blue; 

char flags; /* DoRed, DoGreen, DoBlue */ 

char pad; 
} XColor; 

Errors 

BadColormap 

BadValue Pixel not valid index into cmap. 

Related Commands 

BlackPixel, WhitePixel, XAllocColor, XAllocColorCells, XAllocColor- 
Planes, XAllocNamedColor, XFreeColors, XLookupColor, XParseColor, 
XQueryColors, XStoreColor, XStoreColors, XStoreNamedColor. 



Xlib Reference Manual 347 



XQueryColors 



Xlib- Color Cells- 



Name 

XQueryColors obtain RGB values for an array of colorcells. 

Synopsis 

XQueryColors (display, cmap, colorcell_defs , ncolors) 
Display *display; 
Colormap cmap; 

XColor color cell_defs [ncolors] ; /* SEND and RETURN */ 
int ncolors; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

cmap Specifies the ID of the colormap from which RGB values will be retrieved. 

colorcell_defs 

Specifies an array of XColor structures. In each one, pixel is set to indi 
cate which colorcell in the colormap to return, and the RGB values in that 
colorcell are returned in red, green, and blue. 

ncol ors Specifies the number of XColor structures in the color definition array. 

Description 

XQueryColors is similar to XQueryColor, but it returns an array of RGB values. It 
returns the RGB values in colormap cmap for the colorcell corresponding to the pixel value 
specified in the pixel member of the XColor structure colorcell_def . The RGB values 
are returned in the red, green, and blue members of that same structure, and sets the 
flags member in each XColor structure to (DoRed I DoGreen | DoBlue). 

For more information, see Volume One, Chapter 7, Color. 
Structures 

typedef struct { 

unsigned long pixel; 

unsigned short red, green, blue; 

char flags; /* DoRed, DoGreen, DoBlue */ 

char pad; 
} XColor; 

Errors 

BadColormap Specified colormap does not exist. 

BadValue Pixel not valid index into cmap. 

Note: if more than one pixel value is in error, the one reported is arbitrary. 

Related Commands 

BlackPixel, WhitePixel, XAllocColor, XAllocColorCells, XAllocColor- 
Planes, XAllocNamedColor, XFreeColors, XLookupColor, XParseColor, 
XQueryColor, XStoreColor, XStoreColors, XStoreNamedColor. 



348 Xlib Reference Manual 



Xlib - Extensions- 



J XQueryExtension 



Name 

XQueryExtension get extension information. 

Synopsis 

Bool XQueryExtension ( display, name, major_opcode f 

first_event r first_error) 
Display ^display; 
char *name; 

int *major_opcode; /* RETURN */ 

int *first_event ; /* RETURN */ 

int *first_error; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

name Specifies the name of the desired extension. Upper or lower case is impor 

tant. The string should be in ISO LATIN- 1 encoding, which means that the 
first 128 character codes are ASCII, and the second 128 character codes are 
for special characters needed in western languages other than English. 

major_opcode 

Returns the major opcode of the extension, for use in error handling routines. 

first_event Returns the code of the first custom event type created by the extension. 
f irst_error Returns the code of the first custom error defined by the extension. 

Description 

XQueryExtension determines if the named extension is present, and returns True if it is. 
If so, the routines in the extension can be used just as if they were core Xlib requests, except 
that they may return new types of events or new error codes. The available extensions can be 
listed with XListExtensions. 

The major_opcode for the extension is returned, if it has one. Otherwise, zero is returned. 
This opcode will appear in errors generated in the extension. 

If the extension involves additional event types, the base event type code is returned in 
first__event. Otherwise, zero is returned in first_event. The format of the events is 
specific to the extension. 

If the extension involves additional error codes, the base error code is returned in 
first_error. Otherwise, zero is returned. The format of additional data in the errors is 
specific to the extension. 

See Volume One, Chapter 13, Other Programming Techniques, for more information on using 
extensions, and Volume One, Appendix C, Writing Extensions to X, for information on writing 
them. 

Related Commands 

XFreeExtensionList, XListExtensions. 



Xlib Reference Manual 349 



XQueryFont , X|ib FOM> _ 

Name 

XQueryFont return information about a loaded font. 

Synopsis 

XFontStruct *XQueryFont ( display, font_ID) 
Display * display; 
XID font_ID; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

font_io Specifies either the font ID or the graphics context ID. You can declare the 

data type for this argument as either Font or GContext (both X IDs). If 
GContext, the font in that GC will be queried. 

Description 

XQueryFont returns a pointer to an XFontStruct structure containing information 
describing the specified font. This call is needed if you loaded the font with XLoadFont, but 
need the font information for multiple calls to determine the extent of text. XLoadQuery- 
Font combines these two operations. 

If the font hasn t been loaded (or the font ID passed is invalid), XQueryFont returns NULL. 

If font_lD is declared as data type GContext (also a resource ID), this function queries the 
font specified by the font component of the GC specified by this ID. This is useful for getting 
information about the default font, whose ID is stored in the default GC. However, in this case 
the GContext ID will be the ID stored in the fid field of the returned XFontStruct, and 
you can t use that ID in XSetFont or XUnloadFont, since it is not itself the ID of the font. 

Use XFreeFont to free this data. 

For more information on fonts, see Volume One, Chapter 6, Drawing Graphics and Text. 

Errors 

BadFont 

Structures 

typedef struct { 

XExtData *ext_data; /* hook for extension to hang data */ 

Font fid; /* font ID for this font */ 

unsigned direction; /* hint about direction font is painted */ 

unsigned min_char_or_byte2; /* first character */ 

unsigned max_char_or_byte2; /* last character */ 

unsigned min_bytel; /* first row that exists */ 

unsigned max_bytel; /* last row that exists */ 

Bool all_chars_exist; /* flag if all characters have nonzero size*/ 

unsigned default_char; /* char to print for undefined character */ 

int n_properties; /* how many properties there are */ 

XFontProp *properties; /* pointer to array of additional properties*/ 

XCharStruct min_bounds; /* minimum bounds over all existing char*/ 

XCharStruct max__bounds; /* minimum bounds over all existing char*/ 



350 Xlib Reference Manual 



Xllb - Fonts 



(continued) 



XQueryFont 



XCharStruct 
int ascent; 
int descent; 

XFontStruct; 



per char; 



/* first_char to last_char information */ 

/* logical extent above baseline for spacing */ 

/* logical descent below baseline for spacing */ 



Related Commands 

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XFree- 
FontPath, XGetFontPath, XGetFontProperty, XListFonts, XListFontsWith- 
Inf o, XLoadFont, XLoadQueryFont, XSetFont, XSetFontPath, XUnloadFont. 



Xlib Reference Manual 



351 



XQueryKeymap \ X|ib _ Keyboard _ 

Name 

XQueryKeymap obtain a bit vector for the current state of the keyboard. 

Synopsis 

XQue r yKeymap ( di spl ay, keys ) 
Display * display; 
char keys [32] ; /* RETURN */ 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenD i sp 1 ay . 

keys Returns an array of bytes that identifies which keys are pressed down. Each 

bit represents one key of the keyboard. 

Description 

XQueryKeymap returns a bit vector for the logical state of the keyboard, where each bit set to 
1 indicates that the corresponding key is currently pressed down. The vector is represented as 
32 bytes. Byte N (from 0) contains the bits for keys 8N to 8N+7 with the least significant bit in 
the byte representing key 8N. Note that the logical state may lag the physical state if device 
event processing is frozen due to a grab. 

Related Commands 

XChangeKeyboardMapping, XDeleteModif iermapEntry, XFreeModif iermap, 
XGetKeyboardMapping, XGetModif ierMapping, XInsertModif iermapEntry, 
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym, 
XLookupString, XNewModif ierMap, XRebindKeysym, XRef reshKeyboard- 
Mapping, XSetModif ierMapping, XStringToKeysym. 



352 Xlib Reference Manual 



Xlib-Pointer- 



J XQueryPointer 



Name 

XQueryPointer get the current pointer location. 

Synopsis 

Bool XQueryPointer (display, w, root, child, root_x , root_y , 

win_x, win_y, keys_buttons) 
Display *display; 
Window w; 

Window *root, *child; /* RETURN */ 

int *root_x, *root_y; /* RETURN */ 

int *win_x, *win_y; /* RETURN */ 

unsigned int *keys_buttons / /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from xopenDisplay. 

w Specifies a window which indicates which screen the pointer position is 

returned for, and child will be a child of this window if pointer is inside a 
child. 

root Returns the root window ID the pointer is currently on. 

child Returns the ID of the child of w the pointer is located in, or zero if it not in a 

child. 

root_x Return the x and y coordinates of the pointer relative to the root s origin. 
root_y 

win_x Return the x and y coordinates of the pointer relative to the origin of window w. 

win_y 

keys_buttons 

Returns the current state of the modifier keys and pointer buttons. This is a 
mask composed of the OR of any number of the following symbols: Shift - 
Mask, LockMask, ControlMask, ModlMask, Mod2Mask, ModSMask, 
Mod4Mask, ModSMask, ButtonlMask, Button2Mask, ButtonSMask, 
Button4Mask, ButtonSMask. 

Description 

XQueryPointer gets the pointer coordinates relative to a window and relative to the root 
window, the root window ID and the child window ID (if any) the pointer is currently in, 
and the current state of modifier keys and buttons. 

If XQueryPointer returns False, then the pointer is not on the same screen as v, child is 
None, and win_x and win_y are zero. However, root, root_x, and root_y are still 
valid. If XQueryPointer returns True, then the pointer is on the same screen as the win 
dow v/, and all return values are valid. 

The logical state of the pointer buttons and modifier keys can lag behind their physical state if 
device event processing is frozen due to a grab. 



Xlib Reference Manual 353 



XQueryPointer (continued) Xllb - Pointer 

Errors 

BadWindow 

Related Commands 

XChangeActivePointerGrab, XChangePointerControl, XGetPointer- 
Control, XGetPointerMapping, XGrabPointer, XSetPointerMapping, 
XUngrabPointer, XWarpPointer. 



354 Xlib Reference Manual 



Xlib-Text- 



J XQueryTextExtents 



Name 

XQueryTextExtents query the server for string and font metrics. 
Synopsis 

XQueryTextExtents ( display, font_ID, string, nchars, 

direction, ascent, descent, overall) 
Display *display; 
XID font_ID; 
char *string; 
int nchars; 

int * direct ion; /* RETURN */ 

int * ascent, * descent; /* RETURN */ 
XCharStruct *overall; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

font_lD Specifies the appropriate font ID previously returned by XLoadFont, or the 

GContext that specifies the font. 

string Specifies the character string for which metrics are to be returned. 

nchars Specifies the number of characters in string. 

direction Returns the direction the string would be drawn using the specified font. 
Either FontLef tToRight or FontRightToLef t. 

ascent Returns the maximum ascent for the specified font. 

descent Returns the maximum descent for the specified font. 

overall Returns the overall characteristics of the string. These are the sum of the 

width measurements for each character, the maximum ascent and 
descent, the minimum Ibearing added to the width of all characters up 
to the character with the smallest Ibearing, and the maximum rbearing 
added to the width of all characters up to the character with the largest 
rbearing. 

Description 

XQueryTextExtents returns the dimensions in pixels that specify the bounding box of the 
specified string of characters in the named font, and the maximum ascent and descent for the 
entire font. This function queries the server and, therefore, suffers the round trip overhead that 
is avoided by XTextExtents, but XQueryTextExtents does not require a filled XFont- 
Inf o structure stored on the client side. Therefore, this would be used when memory is pre 
cious, or when just a small number of text width calculations are to be done. 

The returned ascent and descent should usually be used to calculate the line spacing, 
while the width, rbearing, and Ibearing members of overall should be used for hori 
zontal measures. The total height of the bounding rectangle, good for any string in this font, is 

ascent + descent. 



Xlib Reference Manual 355 



XQueryTextExtentS (continued) Xlib - Text 

overall . ascent is the maximum of the ascent metrics of all characters in the string. The 
overall . descent is the maximum of the descent metrics. The overall . width is the 
sum of the character-width metrics of all characters in the string. The overall . Ibearing 
is usually the Ibearing of the first character in the string, and overall . rbearing is the 
rbearing of the last character in the string plus the sum of the widths of all the characters up to 
but not including the last character. More technically, here is the X protocol definition: 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 Ibearing metric of the character plus W, and let R be the 
rbearing metric of the character plus W. The overall . Ibearing is the minimum L of all 
characters in the string, and the overall . rbearing is the maximum R. 

For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and 
Text. 

Structures 

typedef struct { 

short Ibearing; /* origin to left edge of character */ 

short rbearing; /* origin to right edge of character */ 

short width; /* advance to next char s origin */ 

short ascent; /* baseline to top edge of character */ 

short descent; /* baseline to bottom edge of character */ 
unsigned short attributes; /* per char flags (not predefined) */ 

} XCharStruct; 

Errors 

BadFont 

Related Commands 

XDrawImageString, XDrawImageStringl6, XDrawString, XDrawStringl6, 
XDrawText, XDrawTextl6, XQueryTextExtentS 16, XTextExtents, XText- 
Extentsl6, XTextWidth, XTextWidthlG. 



356 Xlib Reference Manual 



Xlib-Text- 



J XQueryTextExtentsI 6 



Name 

XQueryTextExtentsI 6 query the server for string and font metrics of a 16-bit character 
string. 

Synopsis 

XQueryTextExtentsI 6 (display, font_ID, string, nchars, 

direction, ascent, descent, overall) 
Display * display; 
XID font_ID; 
XChar2b *string; 
int nchars; 

int * direct ion; /* RETURN */ 

int *ascent, *descent; /* RETURN */ 
XCharStruct * overall; /* RETURN */ 

Arguments 

di spl ay Specifies a connection to an X server; returned from xopenD i splay. 

font_TD Specifies the appropriate font ID previously returned by XLoadFont, or the 

GContext that specifies the font. 

string Specifies the character string for which metrics are to be returned. 

nchars Specifies the number of characters in string. 

direction Returns the direction of painting in the specified font. Either FontLef tto- 

Right or FontRighttoLef t. 

a scent Returns the maximum ascent in pixels for the specified font. 

descent Returns the maximum descent in pixels for the specified font. 

overall Returns the overall characteristics of the string. These are the sum of the 

width measurements for each character, the maximum ascent and 
descent, the minimum Ibearing added to the width of all characters up 
to the character with the smallest Ibearing, and the maximum rbearing 
added to the width of all characters up to the character with the largest 
rbearing. 

Description 

XQueryTextExtentsI 6 returns the dimensions in pixels that specify the bounding box of 
the specified string of characters in the named font, and the maximum ascent and descent for 
the entire font. This function queries the server and, therefore, suffers the round trip overhead 
that is avoided by XTextExtentslG, but XQueryTextExtents does not require a filled 
XFontlnf o structure. 

The returned ascent and descent should usually be used to calculate the line spacing, 
while the width, rbearing, and Ibearing members of overall should be used for hori 
zontal measures. The total height of the bounding rectangle, good for any string in this font, is 

ascent + descent. 



Xlib Reference Manual 357 



XQueryTextExtentSl 6 (continued) Xlib - Text 

overall . ascent is the maximum of the ascent metrics of all characters in the string. The 
overall . descent is the maximum of the descent metrics. The overall . width is the 
sum of the character-width metrics of all characters in the string. The overall . Ibearing 
is usually the Ibearing of the first character in the string, and overall . rbearing is the 
rbearing of the last character in the string plus the sum of the widths of all the characters up to 
but not including the last character. More technically, here is the X protocol definition: 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 Wearing metric of the character plus W, and let R be the 
rbearing metric of the character plus W. The overall . Ibearing is the minimum L of all 
characters in the string, and the overall . rbearing is the maximum R. 

For fonts defined with linear indexing rather than two-byte matrix indexing, the server inter 
prets each XChar2b as a 16-bit number that has been transmitted with the most significant 
byte first. That is, byte one of the XChar2b is taken as the most significant byte. 

If the font has no defined default character, then undefined characters in the string are taken to 
have all zero metrics. 

Structures 

typedef struct { /* normal 16-bit characters are two bytes */ 

unsigned char bytel; 

unsigned char byte2; 
} XChar2b; 

typedef struct { 

short Ibearing; /* origin to left edge of character */ 

short rbearing; /* origin to right edge of character */ 

short width; /* advance to next char s origin */ 

short ascent; /* baseline to top edge of character */ 

short descent; /* baseline to bottom edge of character */ 
unsigned short attributes; /* per char flags (not predefined) */ 

} XCharStruct; 

Errors 

BadFont 

Related Commands 

XDrawImageString, XDrawImageStringlG, XDrawString, XDrawStringlG, 
XDrawText, XDrawTextlS, XQueryTextExtents, XTextExtents, XText- 
Extentsl6, XTextWidth, XTextWidthl6. 



358 Xlib Reference Manual 



Xlib - Window Manipulation- 
Name 

XQueryTree return a list of children, parent, and root. 

Synopsis 

Status XQueryTree ( display, w 

nchildren) 
Display *display; 
Window w; 

Window *root; /* RETURN 

Window *parent ; /* RETURN 

Window ** children; /* RETURN 
unsigned int * nchildren; /* RETURN 



XQueryTree 



root, parent, children, 



*/ 
*/ 
*/ 
*/ 



Arguments 

display 



Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the ID of the window to be queried. For this window, XQuery 

Tree will list its children, its root, its parent, and the number of children. 

root Returns the root ID for the specified window. 

parent Returns the parent window of the specified window. 

children Returns the list of children associated with the specified window. 
nchildren Returns the number of children associated with the specified window. 
Description 

XQueryTree uses its last four arguments to return the root ID, the parent ID, a pointer to a list 
of children and the number of children in that list, all for the specified window w. The chil 
dren are listed in current stacking order, from bottommost (first) to topmost (last). XQuery 
Tree returns zero if it fails, nonzero if it succeeds. 

You should deallocate the list of children with XFree when it is no longer needed. 

Errors 

BadWindow 

Related Commands 

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate- 
SubwindowsUp, XConf igureWindow, XLowerWindow, XMoveResizeWindow, 
XMoveWindow, XRaiseWindow, XReparentWindow, XResizeWindow, XRestack- 
Windows. 



Xlib Reference Manual 



359 



XRaiseWindow 

Xlib - Window Manipulation 

Name 

XRaiseWindow raise a window to the top of the stacking order. 

Synopsis 

XRaiseWindow (display, v/) 
Display *display; 
Window w; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the ID of the window to be raised to the top of the stack. 

Description 

XRaiseWindow moves a window to the top of the stacking order among its siblings. 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, while leaving its x and y location on 
the desk constant. 

Raising a mapped window may generate exposure events for that window and any mapped 
subwindows of that window that were formerly obscured. 

If the override_redirect attribute of the window (see Volume One, Chapter 4, Window 
Attributes) is False and the window manager has selected SubstructureRedirectMask 
on the parent, then a Conf igureRequest event is sent to the window manager, and no fur 
ther processing is performed. 

Errors 

BadWindow 

Related Commands 

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate- 
SubwindowsUp, XConf igureWindow, XLowerWindow, XMoveResizeWindow, 
XMoveWindow, XQueryTree, XRepa rent Window, XResizeWindow, XRestack- 
Windows. 



360 Xlib Reference Manual 



Xlib - Pixmaps and Tiles- 



j XReadBitmapFlle 



Name 

XReadBitmapFile read a bitmap from disk. 

Synopsis 

int XReadBitmapFile (display, drawable, filename, width, 

height, bitmap, x_hot, y_hot) 
Display * display ; 
Drawable drawable; 
char * filename; 

unsigned int * width, * height; /* RETURN */ 
Pixmap * bitmap; /* RETURN */ 

int *x_hot, *y_hot; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

dr a wabl e Specifies the drawable. 

filename Specifies the filename to use. The format of the filename is operating system 
specific. 

width Return the dimensions in pixels of the bitmap that is read. 

height 

bi tmap Returns the pixmap resource ID that is created. 

x_hot Return the hotspot coordinates in the file (or -1,-1 if none present). 

y_hot 

Description 

XReadBitmapFile reads in a file containing a description of a pixmap of depth 1 (a bitmap) 
in X Version 1 1 bitmap format. 

XReadBitmapFile creates a pixmap of the appropriate size and reads the bitmap data from 
the file into the pixmap. The caller should free the pixmap using XFreePixmap when fin 
ished with it. 

If the file cannot be opened, XReadBitmapFile returns BitmapOpenFailed. If the file 
can be opened but does not contain valid bitmap data, XReadBitmapFile returns Bitmap- 
Filelnvalid. If insufficient working storage is allocated, XReadBitmapFile returns 
BitmapNoMemory. If the file is readable and valid, XReadBitmapFile returns Bitmap- 
Success. 



Xlib Reference Manual 361 



XReadBitmapFile (continued) Xlib - Pixmaps and Tiles 

Here is an example X Version 1 1 bitmap file: 

tdefine name_width 16 

#define name_height 16 

#define name_x_hot 8 

#define name y hot 8 

static char name_bits[] = { 

Oxf8, Oxlf, Oxe3, Oxc7, Oxcf, Oxf3, Ox9f, Oxf9, Oxbf, Oxfd, 0x33, Oxcc, 

Ox7f, Oxfe, Ox7f, Oxfe, Ox7e, Ox7e, Ox7f, Oxfe, 0x37, Oxec, Oxbb, Oxdd, 

Ox9c, 0x39, Oxcf, Oxf3, Oxe3, Oxc7, Oxf8, Oxlf}; 

For more information, see Volume One, Chapter 6, Drawing Graphics and Text. 
Errors 

BadDrawable 

Related Commands 

XCreateBitmapFromData, XCreatePixmap, XCreatePixmapFromBitmapData, 
XFreePixmap, XQueryBestSize, XQueryBestStipple, XQueryBestTile, XSet- 
Tile, XSetWindowBackgroundPixmap, XSetWindowBorderPixmap, XWrite- 
BitmapFile. 



362 Xlib Reference Manual 



Xlib -Keyboard- 



J XRebindKeysym 



Name 

XRebindKeysym rebind a keysym to a string for client. 

Synopsis 

XRebindKeysym (display, keysym, mod_list, mod_count, string, 

num_bytes) 
Display * display ; 
KeySym keysym; 
KeySym *mod_list ; 
int mod_count; 
unsigned char *string; 
int num_bytes; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

keysym Specifies the keysym to be rebound. 

mod_list Specifies a pointer to an array of keysyms that are being used as modifiers. 

mod_ count Specifies the number of modifiers in the modifier list. 

string Specifies a pointer to the string that is to be copied and returned by 

XLookupString in response to later events. 

num_bytes Specifies the length of the string. 
Description 

XRebindKeysym binds the ASCII string to the specified keysym, so that string and 
keysym are returned by XLookukpSt ring when that key is pressed and the modifiers speci 
fied in mod_list are also being held down. This function rebinds the meaning of a keysym 
for a client. It does not redefine the keycode in the server but merely provides an easy way for 
long strings to be attached to keys. Note that you are allowed to rebind a keysym that may not 
exist. 

See Volume One, Chapter 9, The Keyboard and Pointer, for a description of keysyms and key 
board mapping. 

Related Commands 

XChangeKeyboardMapping, XDeleteModif iermapEntry, XFreeModif iermap, 
XGetKeyboardMapping, XGetModif ierMapping, XInsertModif iermapEntry, 
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym, 
XLookupString, XNewModif ierMap, XQueryKeymap, XRef reshKeyboard- 
Mapping, XSetModif ierMapping, XStringToKeysym. 



Xlib Reference Manual 363 



XRecolorCursor \ xHb-cu.r.- 

Name 

XRecolorCursor change the color of a cursor. 

Synopsis 

XRecolorCursor ( display, cursor, foreground_color r 

background_color) 
Display * display; 
Cursor cursor; 
XColor *foreground_color f *background_color ; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

cursor Specifies the cursor ID. 

foreground_col or 

Specifies the red, green, and blue (RGB) values for the foreground. 

background_color 

Specifies the red, green, and blue (RGB) values for the background. 

Description 

XRecolorCursor applies a foreground and background color to a cursor. Cursors are nor 
mally created using a single plane pixmap, composed of O s and 1 s, with one pixel value 
assigned to 1 s and another assigned to O s. XRecolorCursor changes these pixel values. If 
the cursor is being displayed on a screen, the change is visible immediately. On some servers, 
these color selections are read/write cells from the colormap, and can t be shared by applica 
tions. 

Structures 

typedef struct { 

unsigned long pixel; 

unsigned short red, green, blue; 

char flags; /* DoRed, DoGreen, DoBlue */ 

char pad; 
} XColor; 

Errors 

BadCursor 

Related Commands 

XCreateFontCursor, XCreateGlyphCursor, XCreatePixmapCursor, XDef ine- 
Cursor, XFreeCursor, XQueryBestCursor, XQueryBestSize, XUndef ine- 
Cursor. 



364 Xlib Reference Manual 



-X,.b-W.ndowManager Hints / XReCOHfigureWMWindOW 

Name 

XReconfigureWMWindow request that a top-level window be reconfigured. 

Synopsis 

Status XReconf igureWMWindow ( display, w, screen_n umber, 

value_mask, values) 
Display *display; 
Window w; 

int screen_n umber; 
unsigned int value_mask; 
XWindowChanges * values; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window. 

screen_n umber 

Specifies the appropriate screen number on the host server. 

value_mask Specifies which values are to be set using information in the values structure. 
This mask is the bitwise inclusive OR of the valid configure window values 
bits. 

values Specifies a pointer to the XWindowChanges structure. 

Availability 

Release 4 and later. 

Description 

XReconfigureWMWindow issues a Conf igurewindow request on the specified top-level 
window. If the stacking mode is changed and the request fails with a BadMatch error, the 
error event is trapped and a synthetic Conf igureRequest event containing the same confi 
guration parameters is sent to the root of the specified window. Window managers may elect to 
receive this event and treat it as a request to reconfigure the indicated window. 

For more information, see Volume One, Chapter 10, Interclient Communication. 
Structures 

typedef struct { 
int x, y; 

int width, height; 
int border_width; 
Window sibling; 
int stack_mode; 
} XWindowChanges; 



Xlib Reference Manual 365 



XReCOPf igureWMWindOW (continued) Xlib - Window Manager Hints 

Errors 

BadValue 
BadWindow 

Related Commands 

Xlconif yWindow, XWithdrawWindow. 



366 Xlib Reference Manual 



Xlib -Regions- 



J XRectlnRegion 



Name 

XRectlnRegion determine if a rectangle resides in a region. 

Synopsis 

int XRectlnRegion (r, x, y, width, height) 
Region r; 
int x r y; 
unsigned int width, height; 

Arguments 

r Specifies the region. 

x Specify the x and y coordinates of the upper-left corner of the rectangle, rela- 

y live to the region s origin. 

width Specify the width and height in pixels of the rectangle. 

height 

Description 

XRectlnRegion returns Rectangleln if the rectangle is completely contained in the 
region r, RectangleOut if it is completely outside, and RectanglePart if it is partially 
inside. 

Regions are located using an offset from a point (the region origin) which is common to all 
regions. It is up to the application to interpret the location of the region relative to a drawable. 
If the region is to be used as a clip_mask by calling xsetRegion, the upper-left corner of 
region relative to the drawable used in the graphics request will be at (xoffset + 
clip_x_origin, yof f set + clip_y_origin) , where xoffset and yof f set are 
the offset of the region and clip_x_origin and clip_y_origin are the clip origin in the 
GC used. 

For this function, the x and y arguments are interpreted relative to the region origin; no draw- 
able is involved. 

Structures 

Region is a pointer to an opaque structure type. 

Related Commands 

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion, 
XIntersectRegion, XOf f setRegion, XPointlnRegion, XPolygonRegion, 
XSetRegion, XShrinkRegion, XSubtractRegion, XUnionRectWithRegion, 
XUnionRegion, XXorRegion. 



Xlib Reference Manual 367 



XRefreshKeyboardMapping \ X||b _ Keyboard _ 

Name 

XRefreshKeyboardMapping read keycode-keysym mapping from server into Xlib. 

Synopsis 

XRefreshKeyboardMapping ( event ) 
XMappingEvent *event; 

Arguments 

event Specifies the mapping event that triggered this call. 

Description 

XRefreshKeyboardMapping causes Xlib to update its knowledge of the mapping between 
keycodes and keysyms. This updates the application s knowledge of the keyboard. 

The application should call XRefreshKeyboardMapping when a MappingNot if y event 
occurs. MappingNotify events occur when some client has called XChangeKeyboard- 
Mapping. 

For more information, see Volume One, Chapter 9, The Keyboard and Pointer. 
Structures 

typedef struct { 

int type; 

unsigned long serial; /* # of last request processed by server */ 

Bool send_event; /* true if this came from a SendEvent request */ 

Display ^display; /* display the event was read from */ 

Window window; /* unused */ 

int request; /* one of MappingModif ier, MappingKeyboard, 
MappingPointer */ 

int f irst_keycode; /* first keycode */ 

int count; /* defines range of change with f irst_keycode*/ 

} XMappingEvent; 

Related Commands 

XChangeKeyboardMapping, XDeleteModif iermapEntry, XFreeModif iermap, 
XGetKeyboardMapping, XGetModif ierMapping, XInsertModif iermapEntry, 
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym, 
XLookupString, XNewModif ierMap, XQueryKeymap, XRebindKeysym, XSet- 
Modif ierMapping, XStringToKeysym. 



368 Xlib Reference Manual 



-xnb- save set XRemoveFromSaveSet 

Name 

XRemoveFromSaveSet remove a window from the client s save-set. 

Synopsis 

XRemoveFromSaveSet (display, w) 
Display * display ; 
Window v/; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window you want to remove from this client s save-set. This 

window must have been created by a client other than the client making this 
call. 

Description 

XRemoveFromSaveSet removes a window from the save-set of the calling application. 

The save-set is a safety net for windows that have been reparented by the window manager, 
usually to provide a shadow or other background for each window. When the window manager 
dies unexpectedly, the windows in the save-set are reparented to their closest living ancestor, so 
that they remain alive. 

This call is not necessary when a window is destroyed since destroyed windows are automati 
cally removed from the save-set. Therefore, many window managers get away without ever 
calling XRemoveFromSaveSet. See Volume One, Chapter 14, Window Management, for 
more information about save-sets. 

Errors 

BadMatch wnot created by some other client. 

BadWindow 

Related Commands 

XAddToSaveSet, XChangeSaveSet. 



Xlib Reference Manual 369 



XRemoveHost , . XIib -Hos, Access- 

Name 

XRemoveHost remove a host from the access control list. 

Synopsis 

XRemoveHost ( display, host) 
Display ^display; 
XHostAddress *host ; 

Arguments 

display Specifies a connection to an X server; returned from XQpenDisplay. 

host Specifies the network address of the machine to be removed. 

Description 

XRemoveHost removes the specified host from the access control list of the connected server. 
The server must be on the same host as the process that calls XRemoveHost in order to 
change the access control list. 

If you remove your own machine from the access control list, you can no longer connect to that 
server, and there is no way back from this call other than to log out, edit the access control file, 
and reset the server. 

The address data must be a valid address for the type of network in which the server oper 
ates, as specified in the family member. 

For TCP/IP, the address should be in network byte order. For the DECnet family, the server 
performs no automatic swapping on the address bytes. A Phase IV address is two bytes long. 
The first byte contains the least significant eight bits of the node number. The second byte con 
tains the most significant two bits of the node number in the least significant two bits of the 
byte, and the area in the most significant six bits of the byte. 

For more information on access control lists, see Volume One, Chapter 13, Other Programming 
Techniques. 

Structures 

typedef struct { 

int family; /* for example Family Internet */ 

int length; /* length of address, in bytes */ 

char ^address; /* pointer to where to find the bytes */ 

} XHostAddress; 

/* constants used for family member of XHostAddress */ 
#define Familylnternet 
#define FamilyDECnet 1 
#define FamilyChaos 2 

Errors 

BadAccess 
BadValue 



370 Xlib Reference Manual 



Xlib - Host Access (continued) X Re move Host 

Related Commands 

XAddHost, XAddHosts, XDisableAccessControl, XEnableAccessControl, 
XListHosts, XRemoveHosts, XSetAccessControl. 



Xlib Reference Manual 371 



XRemoveHosts A Vl 

v Xlib - Host Access- 
Name 

XRemoveHosts remove multiple hosts from the access control list. 

Synopsis 

XRemoveHosts ( display, hosts, num_hosts) 
Display * display; 
XHostAddress *hosts; 
int num_hosts; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

hosts Specifies the list of hosts that are to be removed. 

n um_h osts Specifies the number of hosts that are to be removed. 

Description 

XRemoveHosts removes each specified host from the access control list of the connected 
server. The server must be on the same host as the process that call XRemoveHosts, in order 
to change the access control list. 

If you remove your machine from the access control list, you can no longer connect to that 
server, and there is no way back from this call except to log out, edit the access control file, and 
reset the server. 

The address data must be a valid address for the type of network in which the server oper 
ates, as specified in the family member. 

For TCP/IP, the address should be in network byte order. For the DECnet family, the server 
performs no automatic swapping on the address bytes. A Phase IV address is two bytes long. 
The first byte contains the least significant eight bits of the node number. The second byte con 
tains the most significant two bits of the node number in the least significant two bits of the 
byte, and the area in the most significant six bits of the byte. 

For more information on access control lists, see Volume One, Chapter 13, Other Programming 
Techniques. 

Structures 

typedef struct { 

int family; /* for example Family Internet */ 

int length; /* length of address, in bytes */ 

char *address; /* pointer to where to find the bytes */ 

} XHostAddress; 

/* constants used for family member of XHostAddress */ 

tdefine Familylnternet 

#define FamilyDECnet 1 

#define FamilyChaos 2 



372 Xlib Reference Manual 



Xllb - Host Access (continued) XRemOveHoStS 



Errors 

BadAccess 
BadValue 



Related Commands 

XAddHost, XAddHosts, XDisableAccessControl, XEnableAccessConti 
XListHosts, XRemoveHost, XSetAccessControl. 



Xlib Reference Manual 



XReparentWindow , XMb . wlndowHanlpulatIon _ 

Name 

XReparentWindow insert a window between another window and its parent. 

Synopsis 

XReparentWindow (display, win, parent, x, y) 
Display * display ; 
Window win ; 
Window parent; 
int x r y; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

win Specifies the ID of the window to be reparented. 

pa ren t Specifies the window ID of the new parent window. 

x Specify the coordinates of the window relative to the new parent. 

y 
Description 

XReparentWindow modifies the window hierarchy by placing window win as a child of 
window parent. This function is usually used by a window manager to put a decoration win 
dow behind each application window. In the case of the window manager, the new parent win 
dow must first be created as a child of the root window. 

If win is mapped, an XUnmapWindow request is performed on it automatically, win is then 
removed from its current position in the hierarchy, and is inserted as a child of the specified 
parent, win is placed on top in the stacking order with respect to siblings. 

A ReparentNotif y event is then generated. The override_redirect member of the 
structure returned by this event is set to either True or False . Window manager clients nor 
mally should ignore this event if this member is set to True. 

Finally, if the window was originally mapped, an XMapWindow request is performed automati 
cally. 

Descendants of win remain descendants of win; they are not reparented to the old parent of 

win. 

Normal exposure processing on formerly obscured windows is performed. The server might 
not generate exposure events for regions from the initial unmap that are immediately obscured 
by the final map. The request fails if the new parent is not on the same screen as the old parent, 
or if the new parent is the window itself or an inferior of the window. 



374 Xlib Reference Manual 



Xlib - Window Manipulation (continued) XRepa rent Window 

Errors 

BadMatch parent not on same screen as old parent of win. 

win has a ParentRelative background and parent is not the same 
depth as win. 

parent is win or an inferior of win. 
BadWindow 

Related Commands 

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate- 
SubwindowsUp, XConf igureWindow, XLowerWindow, XMoveResizeWindow, 
XMoveWindow, XQueryTree, XRaiseWindow, XResizeWindow, XRestack- 
Windows. 



Xlib Reference Manual 375 



XResetScreenSaver \, 

^ Xlib - Screen Saver 

Name 

XResetScreenSaver reset the screen saver. 

Synopsis 

XResetScreenSaver (display) 
Display * display ; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

Description 

XResetScreenSaver redisplays the screen if the screen saver was activated. This may 
result in exposure events to all visible windows if the server cannot save the screen contents. If 
the screen is already active, nothing happens. 

For more information on the screen saver, see Volume One, Chapter 13, Other Programming 
Techniques. 

Related Commands 

XActivateScreenSaver, XForceScreenSaver, XGetScreenSaver, XSet- 
ScreenSaver. 



376 xiib Reference Manual 



Xllb- Window Manipulation XReSJZeWmdOW 

Name 

XResizeWindow change a window s size. 

Synopsis 

XResizeWindow ( display, w, width, height) 
Display ^display; 
Window w; 
unsigned int width, height; 

Arguments 

display Specifies a connection to an X server; returned from xopenDi splay. 

w Specifies the ID of the window to be resized. 

width Specify the new dimensions of the window in pixels. 

height 

Description 

XResizeWindow changes the inside dimensions of the window. The border is resized to 
match but its border width is not changed. XResizeWindow does not raise the window, or 
change its origin. Changing the size of a mapped window may lose its contents and generate an 
Expose event, depending on the bit_gravity attribute (see Volume One, Chapter 4, Win 
dow Attributes). If a mapped window is made smaller, exposure events will be generated on 
windows that it formerly obscured. 

If the override_redirect attribute of the window is False and the window manager has 
selected SubstructureRedirectMask on the parent, then a Conf igureRequest event 
is sent to the window manager, and no further processing is performed. 

If the client has selected StructureNotifyMask on the window, then a Conf igure- 
Notif y event is generated after the move takes place, and the event will contain the final size 
of the window. 

Errors 

BadValue 
BadWindow 

Related Commands 

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate- 
SubwindowsUp, XConf igureWindow, XLowerWindow, XMoveResizeWindow, 
XMoveWindow, XQueryTree, XRaiseWindow, XReparentWindow, XRestack- 
Windows. 



Xlib Reference Manual 377 



XRestack Windows 

Xlib - Window Manipulation 

Name 

XRestackWindows change the stacking order of siblings. 

Synopsis 

XRestackWindows ( display, windows, nwlndows) ; 
Display * display; 
Window windows [] ; 
int nwlndows; 

Arguments 

display Specifies a connection to an X server; returned from XQpenDisplay. 

windows Specifies an array containing the windows to be restacked. All the windows 

must have a common parent. 

nwlndows Specifies the number of windows in the windows array. 

Description 

XRestackWindows restacks the windows in the order specified, from top to bottom. The 
stacking order of the first window in the windows array will be on top, and the other windows 
will be stacked underneath it in the order of the array. Note that you can exclude other siblings 
from the windows array so that the top window in the array will not move relative to these 
other siblings. 

For each window in the window array that is not a child of the specified window, a BadMatch 
error will be generated. If the override_redirect attribute of the window is False and 
the window manager has selected SubstructureRedirectMask on the parent, then 
Conf igureRequest events are sent to the window manager for each window whose over- 
ride_redirect is not set, and no further processing is performed. Otherwise, the windows 
will be restacked in top to bottom order. 

Errors 

BadMatch 
BadWindow 

Related Commands 

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate- 
SubwindowsUp, XConf igureWindow, XLowerWindow, XMoveResizeWindow, 
XMoveWindow, XQueryTree, XRaiseWindow, XReparentWindow, XResize- 
Window. 



378 Xlib Reference Manual 



-x..b - wmdow Manager H.nts / XrmDestroyDatabase 

Name 

XrmDestroyDatabase destroy a resource database. 

Synopsis 

void XrmDestroyDatabase ( database) 
XrmDatabase database; 

Arguments 

da t abase Specifies the resource database. 

Availability 

Release 4 and later. 

Description 

XrmDestroyDatabase destroys a resource database and frees its allocated memory. The 
destroyed resource database should not be referenced again. If database is NULL, Xrm 
DestroyDatabase returns immediately. 

For more information, see Volume One, Chapter 1 1, Managing User Preferences. 
Related Commands 

XrmMergeDat abases. 



Xlib Reference Manual 379 



XrmGetFileDatabase y 

N Xlib - Resource Manager 

Name 

XrmGetFileDatabase retrieve a database from a file. 

Synopsis 

XrmDatabase XrmGetFileDatabase (filename) 
char * filename; 

Arguments 

filename Specifies the resource database filename. 

Description 

XrmGetFileDatabase opens the specified file, creates a new resource database, and loads 
the database with the data read in from the file. The return value of the function is as a pointer 
to the created database. 

The specified file must contain lines in the format accepted by XrmPutLineResource. If 
XrmGetFileDatabase cannot open the specified file, it returns NULL. 

For more information, see Volume One, Chapter II, Managing User Preferences. 

Structures 

XrmDatabase is a pointer to an opaque data type. 

Related Commands 

XrmDestroyDatabase, XrmGetResource, XrmGetStringDatabase, Xrm- 
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, 
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet- 
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, 
XrmQPutStringResource,XrmQuarkToString, XrmStringToBindingQuark- 
List, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark. 



380 Xlib Reference Manual 



-X,ib - Resource Manager / 

Name 

XrmGetResource get a resource from name and class as strings. 

Synopsis 

Bool XrmGetResource ( database, str_name, str_class, 

str_type, value) 
XrmDatabase database; 
char *str_name; 
char *str_class; 

char **str__type; /* RETURN */ 
XrmValue * value; /* RETURN */ 

Arguments 

database Specifies the database that is to be used. 

st r_name Specifies the fully specified name of the value being retrieved. 
str_class Specifies the fully specified class of the value being retrieved. 

str_type Returns a pointer to the representation type of the destination. In this func 
tion, the representation type is represented as a string, not as an Xrm- 

Representation. 

val ue Returns the value in the database. Do not modify or free this data. 

Description 

The resource manager manages databases of resource specifications consisting of lines contain 
ing resource name/class strings followed by a colon and the value of the resource. XrmGet 
Resource retrieves a resource from the specified database. It takes fully specified name and 
class strings, and returns the representation and value of the matching resource. The value 
returned points into database memory; you must not modify that data. If a resource was found, 
XrmGetResource returns True. Otherwise, it returns False. 

Currently, the database only frees or overwrites entries when new data is stored with Xrm- 
MergeDatabases, or XrmPutResource and related routines. A client that avoids these 
functions should be safe using the address passed back at any time until it exits. 

XrmGetResource is very similar to XrmQGetResource, except that in XrmQGet- 
Resource, the equivalent arguments to str_name, str_class, and str_type are 
quarks instead of strings. 

To understand how data is stored and retrieved from the database, you must understand: 

1) The basic components that make up the storage key and retrieval keys. 

2) How keys are made up from components. 

3) The two ways that components can be bound together. 

4) What sort of keys are used to store and retrieve data. 



Xlib Reference Manual 38 1 



XrmGet Resource (continued) Xlib - Resource Manager 

5) How the storage key and retrieval keys are compared to determine whether they match. 

6) If there are multiple matches, how the best match is chosen so only one value is returned. 
Each will be covered in turn. 

1) The storage key and retrieval keys are composed of a variable number of components, 
bound together. There are two types of components: names and classes. By convention, 
names begin with a lower case character and classes begin with an upper case character. 
Therefore, xmh, background, and toe are examples of names, while Xmh, Box, and 
Command are examples of classes. A name key (like str_name) consists purely of 
name components. A class key (like str_class ) consists purely of class components. 
The retrieval keys are a pair of keys, one composed of purely name components, the 
other of purely class components. A storage key (like specifier in XrmPut- 
Resource) consists of a mixture of name and class components. 

2) A key is composed of multiple components bound together in sequence. This allows you 
to build logical keys for your application. For example, at the top level, the application 
might consist of a paned window (that is, a window divided into several sections) named 
toe. One pane of the paned window is a button box window named buttons filled with 
command buttons. One of these command buttons is used to retrieve (include) new 
mail and has the name include. This window has a fully qualified name xmh . toe . but 
tons, include and a fully qualified class Xmh.VPaned. BOX. Command. Its fully quali 
fied name is the name of its parent, xmh . toe .buttons, followed by its name include. 
Its class is the class of its parent, Xmh.VPaned. BOX, followed by its particular class, 

Command. 

3) The components in a key can be bound together in two ways: by a tight binding (a dot 
".") or by a loose binding (an asterisk "*"). Thus xmh. toe. background has three 
name components tightly bound together, while Xmh*Command. foreground uses both a 
loose and a tight binding. Bindings can also precede the first component (but may not 
follow the last component). By convention, if no binding is specified before the first 
component, a tight binding is assumed. For example, xmh. background and 
.xmh. background both begin with tight bindings before the xmh, while 
*xmh . background begins with a loose binding. 

The difference between tight and loose bindings comes when comparing two keys. A 
tight binding means that the components on either side of the binding must be sequential. 
A loose binding is a sort of wildcard, meaning that there may be unspecified components 
between the two components that are loosely bound together. For example, 

xmh. toe. background would match xmh*background and Background but not 
xmh . background or background. 

4) A key used to store data into the database can use both loose and tight bindings. This 
allows you to specify a data value which can match to many different retrieval keys. In 
contrast, keys used to retrieve data from the database can use only tight bindings. You 
can only look up one item in the database at a time. Remember also that a storage key 



382 XHb Reference Manual 



Xlib - Resource Manager (continued) XrmGetResOUrce 

can mix name and class components, while the retrieval keys are a pair of keys, one con 
sisting purely of name (first character lower case) components and one consisting purely 
of class (capitalized) components. 

5) The resource manager must solve the problem of how to compare the pair of retrieval 
keys to a single storage key. (Actually, to many single storage keys, since the resource 
manager will compare the retrieval keys against every key in the database, but one at a 
time.) The solution of comparing a pair of keys to a single key is simple. The resource 
manager compares component by component, comparing a component from the storage 
key against both the corresponding component from the name retrieval key, and the cor 
responding component from the class retrieval key. If the storage key component 
matches either retrieval key component, then that component is considered to match. For 
example, the storage key xmh. toe. Foreground matches the name key 
xmh .toe . foreground with the class key Xmh. Box. Foreground. This is why 
storage keys can mix name and class components, while retrieval keys cannot. 

6) Because the resource manager allows loose bindings (wildcards) and mixing names and 
classes in the storage key, it is possible for many storage keys to match a single 
name/class retrieval key pair. To solve this problem, the resource manager uses the fol 
lowing precedence rules to determine which is the best match (and only the value from 
that match will be returned). The precedence rules are, in order of preference: 

1. The attribute of the name and class must match. For example, queries for 

xterm. scrollbar. background (name) 
XTerm. Scrollbar. Background (class) 

will not match the following database entry: 

xterm. scrollbar: on 

because background does not appear in the database entry. 

2. Database entries with name or class prefixed by a dot ( . ) are more specific than those 
prefixed by an asterisk (*). For example, the entry xterm . geometry is more specific 
than the entry xterm*geometry. 

3. Names are more specific than classes. For example, the entry *scrollbar.- 
background is more specific than the entry * Scrollbar . Background. 

4. A name or class is more specific than omission. For example, the entry 
Scrollbar*Background is more specific than the entry *Background. 

5. Left components are more specific than right components. For example, to query for 
.xterm. scrollbar .background, the entry xterm*background is more spe 
cific than the entry scrollbar*background. 



Xlib Reference Manual 



383 



XrmGetResource (continued) Xlib - Resource Manager 

Names and classes can be mixed. As an example of these rules, assume the following user pref 
erence specification: 

xmh*background: red 

* command. font : 8x13 

*command. background: blue 

*Command. Foreground : green 

xmh. toc*Command. activeForeground: black 

A query for the name xmh. toe .messagef unctions . include .activeForeground 
and class Xmh.VPaned. Box. Command. Foreground would match xmh.toc*- 
Command. activeForeground and return black. However, it also matches *Com- 
mand . Foreground but with lower preference, so it would not return green. 

For more information, see Volume One, Chapter 11, Managing User Preferences, and Volume 
Four, X Toolkit Intrinsics Programming Manual, Chapter 9, Resource Management and Type 
Conversion. 

Structures 

XrmDatabase is a pointer to an opaque data type. 

typedef struct { 

unsigned int size; 

caddr_t addr; 
} XrmValue; 

Related Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetStringDatabase, Xrm- 
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, 
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet- 
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, 
XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuark- 
List, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark. 



384 Xlib Reference Manual 



-xi,b - Resource Manager / XrmGetStringDatabase 

Name 

XrmGetStringDatabase create a database from a string. 

Synopsis 

XrmDatabase XrmGetStringDatabase (data) 
char *data; 

Arguments 

data Specifies the database contents using a string. 

Description 

XrmGetStringDatabase creates a new database and stores in it the resources specified in 
data. The return value is subsequently used to refer to the created database. XrmGet 
StringDatabase is similar to XrmGetFileDatabase, except that it reads the informa 
tion out of a string instead of a file. Each line in the string is separated by a new line character 
in the format accepted by XrmPutLineResource. 

For more information, see Volume One, Chapter 11, Managing User Preferences. 

Structures 

XrmDatabase is a pointer to an opaque data type. 

Related Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, Xrm- 
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, 
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet- 
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, 
XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuark- 
List, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark. 



Xlib Reference Manual 385 



Xrmlnitialize 

Xlib - Resource Manager 

Name 

Xrmlnitialize initialize the resource manager. 

Synopsis 

void Xrmlnitialize ( ) ; 

Description 

Xrmlnitialize initializes the resource manager, and should be called once before using 
any other resource manager functions. It just creates a representation type of "String" for val 
ues defined as strings. This representation type is used by XrmPutStringResource and 
XrmQPutStringResource, which require a value as a string. See XrmQPutResource 
for a description of representation types. 

For more information, see Volume One, Chapter 11, Managing User Preferences. 
Related Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet- 
StringDatabase, XrmMergeDatabases, XrmParseCommand, XrmPutFile- 
Database, XrmPutLineResource, XrmPutResource, XrmPutStringResource, 
XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPut 
Resource, XrmQPutStringResource, XrmQuarkToString, XrmString- 
ToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, Xrm- 
UniqueQuark. 



Xlib Reference Manual 



Xlib - Resource Manager- 



J XrmMergeDatabases 



Name 

XrmMergeDatabases merge the contents of one database into another. 

Synopsis 

void XrmMergeDatabases ( source_db, target _db) 
XrmDat abase source_db, *target_db; 

Arguments 

source_db Specifies the resource database to be merged into the existing database. 

targe t_db Specifies a pointer to the resource database into which the source_db data 
base will be merged. 

Description 

XrmMergeDatabases merges source_db into target_db. This procedure is used to 
combine databases, for example, an application specific database of defaults and a database of 
user preferences. The merge is destructive; it destroys the original source_db database and 
modifies the original targe t_db. 

For more information, see Volume One, Chapter II, Managing User Preferences. 

Structures 

XrmDatabase is a pointer to an opaque data type. 

Related Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet- 
StringDatabase, Xrmlnitialize, XrmParseCommand, XrmPutFileDatabase, 
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet- 
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, 
XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuark- 
List, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark. 



Xlib Reference Manual 387 



XrmParseCommand \. 

v Xlib - Resource Manager- 
Name 

XrmParseCommand load a resource database from command line arguments. 

Synopsis 

void XrmParseCommand ( db, table, table_count , name, argc, 

argv) 

XrmDatabase *db; /* SEND and if NULL, RETURN */ 

XrmOptionDescList table; 
int table_count / 
char *name; 

int *argc; /* SEND and RETURN */ 

char **argv; /* SEND and RETURN */ 

Arguments 

database Specifies a pointer to the resource database. If database contains NULL, a 
new resource database is created and a pointer to it is returned in database. 

t abl e Specifies table of command line arguments to be parsed. 

table_count Specifies the number of entries in the table. 
name Specifies the application name. 

argc Before the call, specifies the number of arguments. After the call, returns the 

number of arguments not parsed. 

argv Before the call, specifies a pointer to the command line arguments. After the 

call, returns a pointer to a string containing the command line arguments that 
could not be parsed. 

Description 

XrmParseCommand parses an (argc, argv) pair according to the specified option table, 
loads recognized options into the specified database, and modifies the (argc, argv) pair to 
remove all recognized options. 

The specified table is used to parse the command line. Recognized entries in the table are 
removed from argv, and entries are made in the specified resource database. The table entries 
contain information on the option string, the option name, which style of option and a value to 
provide if the option kind is XrmoptionNoArg. See the example table below. 

argc specifies the number of arguments in argv and is set to the remaining number of argu 
ments that were not parsed, name should be the name of your application for use in building 
the database entry, name is prepended to the resourceName in the option table before stor 
ing the specification. No separating (binding) character is inserted. The table must contain 
either a dot (".") or an asterisk ("*") as the first character in each resourceName entry. The 
resourceName entry can contain multiple components. 

The following is a typical options table: 

static XrmOptionDescRec opTable[ ] = { 

{"-background", "*background", XrmoptionSepArg, (caddr_t) NULL}, 



358 Xlib Reference Manual 



Xlib - Resource Manager 



(continued) 



XrmParseCommand 



{"-bg", 

{"-borderwidth 1 

{ "-bordercolor 1 

{"-bw", 

{ "-display", 

{"-fg", 

{"-fn", 

{ "-font", 

{ "-foreground", 

{ "-geometry", 

{ "-iconic" , 

{ "-name", 

{ "-reverse" , 

-rv", 

-synchronous 

-title", 

-xrm", 



"*borderColor", 

"* background" , 

"*TopLevelShell . borderWidth", 

"*borderColor " , 

"*TopLevelShell.borderWidth", 

".display", 

"^foreground", 

"*font", 

"*font", 

"*foreground", 

" .TopLevelShell .geometry", 

" .TopLevelShell . iconic", 

" .name", 

"*reverseVideo" , 

"*reverseVideo", 

11 . synchronous", 

11 . TopLevelShell . title" , 

NULL, 



XrmoptionSepArg, 


(caddr_t) 


NULL} 


XrmoptionSepArg, 


(caddr_t) 


NULL} 


XrmoptionSepArg, 


(caddr_t) 


NULL} 


XrmoptionSepArg, 


(caddr_t) 


NULL} 


XrmoptionSepArg, 


(caddr t) 


NULL} 


XrmoptionSepArg, 


(caddr_t) 


NULL} 


XrmoptionSepArg, 


(caddr t) 


NULL} 


XrmoptionSepArg, 


(caddr_t) 


NULL} 


XrmoptionSepArg, 


(caddr_t) 


NULL} 


XrmoptionSepArg, 


(caddr_t) 


NULL} 


XrmoptionSepArg, 


(caddr t) 


NULL} 


XrmoptionNoArg, 


(caddr_t) 


"on" } 


XrmoptionSepArg, 


(caddr t) 


NULL} 


XrmoptionNoArg, 


(caddr_t) 


"on" } 


XrmoptionNoArg, 


(caddr t) 


"on" } 


XrmoptionNoArg, 


(caddr_t) 


"on"} 


XrmoptionSepArg, 


(caddr t) 


NULL} 


XrmoptionResArg, 


(caddr t) 


NULL} 



In this table, if the -background (or -bg) option is used to set background colors, the stored 
resource specifier will match all resources of attribute background. If the -borderwidth option 
is used, the stored resource specifier applies only to border width attributes of class Top 
LevelShell (that is, outermost windows, including pop-up windows). If the -title option is 
used to set a window name, only the topmost application windows receive the resource. 

When parsing the command line, any unique unambiguous abbreviation for an option name in 
the table is considered a match for the option. Note that upper case and lower case matter. 

For more information, see Volume One, Chapter 11, Managing User Preferences. 

Structures 

XrmDatabase is a pointer to an opaque data type. 



typedef enum { 

XrmoptionNoArg, 

XrmoptionlsArg, 

XrmoptionStickyArg, 

XrmoptionSepArg, 

XrmoptionResArg, 

Xrmopt ionSkipArg, 

XrmoptionSkipLine, 

XrmoptionSkipNArgs 

} XrmOptionKind; 

typedef struct { 

char *option; 
char *resourceName; 
XrmOptionKind argKind; 
caddr t value; 



/* value is specified in OptionDescRec. value */ 

/* value is the option string itself */ 

/* value is chars immediately following option */ 

/* value is next argument in argv */ 

/* resource and value in next argument in argv */ 

/* ignore this option and next argument in argv */ 

/* ignore this option and the rest of argv */ 

/* new in R4 : ignore this option, skip 

number specified in next argument */ 



/* option specification string in argv */ 

/* binding & resource name (w/out application name) 

/* which style of option it is */ 

/* value to provide if XrmoptionNoArg */ 



XrmOptionDescRec, *XrmOptionDescList; 



Xlib Reference Manual 



XrmParseCommand (continued) Xlib - Resource Manager 

Related Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmPutFile- 
Database, XrmPutLineResource, XrmPutResource, XrmPutStringResource, 
XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPut- 
Resource, XrmQPutStringResource, XrmQuarkToString, XrmString- 
ToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, Xrm- 
UniqueQuark. 



390 Xlib Reference Manual 



-XHb - Resource Manager / XrmPutFileDatabaSe 

Name 

XrmPutFileDatabase store a resource database in a file. 

Synopsis 

void XrmPutFileDatabase ( database, stored_db) 
XrmDatabase database; 
char *stored_db; 

Arguments 

database Specifies the resource database that is to be saved. 

stored_db Specifies the filename for the stored database. 
Description 

XrmPutFileDatabase stores a copy of the application s current database in the specified 
file. The file is an ASCII text file that contains lines in the format that is accepted by XrmPut- 
LineResource. 

For more information, see Volume One, Chapter 11, Managing User Preferences. 

Structures 

XrmDatabase is a pointer to an opaque data type. 

Related Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, 
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet- 
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, 
XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuark- 
List, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark. 



XHb Reference Manual 391 



XrmPutLineResource \, 

v Xlib - Resource Manager 

Name 

XrmPutLineResource add a resource specification to a resource database. 

Synopsis 

void XrmPutLineResource (database, line) 

XrmDatabase *database; /* SEND, and if NULL, RETURN */ 
char *line; 

Arguments 

database Specifies a pointer to the resource database. If database contains NULL, a 
new resource database is created and a pointer to it is returned in database. 

line Specifies the resource name (possibly with multiple components) and value 

pair as a single string, in the format resource : value. 

Description 

XrmPutLineResource adds a single resource entry to the specified database. 

XrmPutLineResource is similar to XrmPutStringResource, except that instead of 
having separate string arguments for the resource and its value, XrmPutLineResource 
takes a single string argument (line) which consists of the resource name, a colon, then the 
value. Since the value is a string, it is stored into the database with representation type 

String. 

Any whitespace before or after the name or colon in the line argument is ignored. The value 
is terminated by a new-line or a NULL character. The value may contain embedded new-line 
characters represented by the "\" and "n" two character pair (not the single "\n" character), 
which are converted into a single linefeed character. In addition, the value may run over onto 
the next line, this is indicated by a "\" character at the end of each line to be continued. 

Null-terminated strings without a new line are also permitted. XrmPutResource, Xrm- 
QPutResource, XrmPutStringResource, XrmQPutStringResource and Xrm 
PutLineResource all store data into a database. See XrmQPutResource for the most 
complete description of this process. 

For more information, see Volume One, Chapter 11, Managing User Preferences. 

Structures 

XrmDatabase is a pointer to an opaque data type. 



392 Xlib Reference Manual 



Xlib - Resource Manager (continued) XrmPutLineResOurce 

Related Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, 
XrmPutFileDatabase, XrmPutResource, XrmPutStringResource, XrmQGet- 
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPut Re source, 
XrmQPutStringRe source, XrmQuarkToString, XrmStringToBindingQuark- 
List, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark. 



Xlib Reference Manual 393 



XrmPutResource \ 

v Xhb - Resource Manager 

Name 

XrmPutResource store a resource specification into a resource database. 

Synopsis 

void XrmPutResource ( database, specifier, type, value) 

XrmDatabase * database; /* SEND, and if NULL, RETURN */ 
char * specifier; 
char *type; 
XrmValue * value; 

Arguments 

database Specifies a pointer to the resource database. If database contains NULL, a new 
resource database is created and a pointer to it is returned in database. 

sped fier Specifies a complete or partial specification of the resource. 
type Specifies the type of the resource. 

value Specifies the value of the resource. 

Description 

XrmPutResource is one of several functions which store data into a database. 

XrmQPutResource first converts specifier into a binding list and a quark list by calling 
XrmStringToBindingQuarkList, and converts type into an XrmRepresentation 
by calling XrmStringToRepresentation. Finally, it puts the data into the database. 

XrmPutResource, XrmQPutResource, XrmPutStringResource, XrmQPut- 
StringResource and XrmPutLineResource all store data into a database. See the 
description of XrmQPutResource for the most complete description of this process. 

For more information, see Volume One, Chapter II, Managing User Preferences. 

Structures 

XrmDatabase is a pointer to an opaque data type. 

typedef struct { 

unsigned int size; 

caddr_t addr; 
} XrmValue, *XrmValuePtr; 

Related Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, 
XrmPutFileDatabase, XrmPutLineResource, XrmPutStringResource, Xrm- 
QGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPut 
Resource, XrmQPutStringResource, XrmQuarkToString, XrmString 
ToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, Xrm- 
UniqueQuark. 



394 Xlib Reference Manual 



-X,,b- Resource Manager XrmPutStringResource 

Name 

XrmPutStringResource add a resource specification with separate resource name and value. 

Synopsis 

void XrmPutStringResource (database, resource, ^alue) 

XrmDatabase * database; /* SEND, and if NULL, RETURN */ 
char * resource; 
char * value; 

Arguments 

database Specifies a pointer to the resource database. If database contains NULL, a 
new resource database is created and a pointer to it is returned in database. 

resource Specifies the resource, as a string. 

val ue Specifies the value of the resource, as a string. 

Description 

XrmPutStringResource adds a resource specification with the specified resource and 
value to the specified database. The resource string may contain both names and classes, 
bound with either loose (*) or tight (.) bindings. See the description of XrmGetResource for 
more information about bindings. 

The representation type used in the database is String. 

XrmPutResource, XrmQPutResource, XrmPutStringResource, XrmQPut- 
StringResource and XrmPutLineResource all store data into a database. See Xrm 
QPutResource for the most complete description of this process. 

For more information, see Volume One, Chapter II, Managing User Preferences. 

Structures 

XrmDatabase is a pointer to an opaque data type. 

Related Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, 
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmQGet- 
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, 
XrmQPutStringRe source, XrmQuarkToString, XrmStringToBindingQuark- 
List, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark. 



Xlib Reference Manual 395 



XrmQGetResource 

Xllb - Resource Manager 

Name 

XrmQGetResource get a resource value using name and class as quarks. 

Synopsis 

Bool XrmQGetResource (database, quark_name, quark_class, 

quark_type, value) 
XrmDatabase database; 
XrmNameList quark_name ; 
XrmClassList quark_class ; 

XrmRepresentation *quark_type; /* RETURN */ 
XrmValue * value; /* RETURN */ 

Arguments 

da t abase Specifies the database that is to be used. 

quark_name Specifies the fully qualified name of the value being retrieved (as a list of 
quarks). 

quark_class Specifies the fully qualified class of the value being retrieved (as a list of 
quarks). 

quark_type Returns a pointer to the representation type of the value. In this function, the 
representation type is represented as a quark. 

value Returns a pointer to the value in the database. Do not modify or free this 

data. 

Description 

XrmQGetResource retrieves a resource from the specified database. It takes fully qualified 
name and class strings, and returns the representation and value of the matching resource. The 
value returned points into database memory; you must not modify that data. If a resource was 
found, XrmQGetResource returns True. Otherwise, it returns False. 

Currently, the database only frees or overwrites entries when new data is stored with Xrm- 
MergeDatabases, or XrmPutResource and related routines. A client that avoids these 
functions should be safe using the address passed back at any time until it exits. 

XrmQGetResource is very similar to XrmGetResource, except that in XrmGet- 
Resource, the equivalent arguments to quark_name, quark_class, and quark_type 
arguments are strings instead of quarks. 

See XrmGetResource for a full description of how data is looked up in the database. 
For more information, see Volume One, Chapter II, Managing User Preferences. 



396 Xlib Reference Manual 



Xlib - Resource Manager (continued) XrmQGetResource 

Structures 

XrmDatabase is a pointer to an opaque data type. 

typedef XrmQuarkList XrmNameList; 
typedef XrmQuarkList XrmClassList; 
typedef XrmQuark XrmRepresentation; 

typedef struct { 

unsigned int size; 

caddr_t addr; 
} XrmValue, *XrmValuePtr; 

Related Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGet Re source, XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, 
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut- 
StringResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPut- 
Resource, XrmQPutStringResource, XrmQuarkToString, XrmString- 
ToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, Xrm- 
UniqueQuark. 



Xlib Reference Manual 397 



XrmQGetSearch List "\ 

> Xllb - Resource Manager 

Name 

XrmQGetSearchList return a list of database levels. 

Synopsis 

Bool XrmQGetSearchList ( database, names, classes, 

search_list, list_length) 
XrmDatabase database; 
XrmNameList names; 
XrmClassList classes; 

XrmSearchList search_list; /* RETURN */ 
int list_length; 

Arguments 

database Specifies the database to be searched. 

names Specifies a list of resource names. 

classes Specifies a list of resource classes. 

search_list Returns a search list for further use. The caller must allocate sufficient space 
for the list before calling XrmQGetSearchList. 

list_length Specifies the number of entries (not the byte size) allocated for 

search_list. 

Description 

XrmQGetSearchList is a tool for searching the database more efficiently. It is used in 
combination with XrmQGetSearchResource. Often, one searches the database for many 
similar resources which differ only in their final component (e.g., xmh.toc . foreground, 
xmh .toe .background, etc). Rather than looking for each resource in its entirety, Xrm- 
GetSearchList searches the database for the common part of the resource name, returning 
a whole list of items in the database that match it. This list is called the search list. This search 
list is then used by XrmQGetSearchList, which searches for the last components one at a 
time. In this way, the common work of searching for similar resources is done only once, and 
the specific part of the search is done on the much shorter search list. 

XrmQGetSearchList takes a list of names and classes and returns a list of database levels 
where a match might occur. The returned list is in best-to-worst order and uses the same algo 
rithm as XrmGetResource for determining precedence. If search_list was large 
enough for the search list, XrmQGetSearchList returns True. Otherwise, it returns 
False. 

The size of the search list that must be allocated by the caller is dependent upon the number of 
levels and wildcards in the resource specifiers that are stored in the database. The worst case 
length is 3 n , where n is the number of name or class components in names or classes. 

Only the common prefix of a resource name should be specified in the name and class list to 
XrmQGetSearchList. In the example above, the common prefix would be xmh.toc. 
However, note that XrmQGetSearchResource requires that name represent a single 



398 Xlib Reference Manual 



Xlib - Resource Manager (continued) XrmQGetSearchList 

component only. Therefore, the common prefix must be all but the last component of the name 
and class. 

For more information, see Volume One, Chapter 11, Managing User Preferences. 

Structures 

XrmDatabase is a pointer to an opaque data type. 

typedef XrmQuarkList XrmNameList ; 
typedef XrmQuarkList XrmClassList ; 
typedef XrmQuark XrmRepresentation; 

XrmSearchList is a pointer to an opaque data type. 
Related Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, 
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut- 
StringResour.ee, XrmQGetResource, XrmQGetSearchResource, XrmQPut- 
Resource, XrmQPutStringResource, XrmQuarkToString, XrmString- 
ToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, Xrm- 
UniqueQuark. 



Xlib Reference Manual 399 



XrmQGetSearchResource \ X1|b _ Resource Manager _ 

Name 

XrmQGetSearchResource search prepared list for a given resource. 

Synopsis 

Bool XrmQGetSearchResource ( search_list, name, class, 

type, value) 

XrmSearchList search_list ; 
XrmName name ; 
XrmClass class; 

XrmRepresentation *type; /* RETURN */ 
XrmValue * value; /* RETURN */ 

Arguments 

search_list Specifies the search list returned by XrmQGetSearchList. 

name Specifies the resource name. 

class Specifies the resource class. 

type Returns the data representation type. 

value Returns the value from the database. 

Description 

XrmQGetSearchResource is a tool for searching the database more efficiently. It is used 
in combination with XrmQGetSearchList. Often, one searches the database for many simi 
lar resources which differ only in their final component (e.g., xmh. toe . foreground, 
xmh. toe .background, etc). Rather than looking for each resource in its entirety, Xrm 
QGetSearchList searches the database for the common part of the resource name, returning 
a whole list of items in the database that match it. This list is called the search list. Xrm 
QGetSearchResource searches the search list for the resource that is fully identified by 
name and class. The search stops with the first match. XrmQGetSearchResource 
returns True if the resource was found; otherwise, it returns False. 

A call to XrmQGetSearchList with a name and class list containing all but the last compo 
nent of a resource name followed by a call to XrmQGetSearchResource with the last com 
ponent name and class returns the same database entry as XrmQGet Re source or XrmQGet- 
Re source would with the fully qualified name and class. 

For more information, see Volume One, Chapter 1 1, Managing User Preferences. 



400 Xlib Reference Manual 



Xllb - Resource Manager (continued) XrmQGetSearchResource 

Structures 

XrmDat abase is a pointer to an opaque data type. 

typedef XrmQuark XrmName; 

typedef XrmQuark XrmClass; 

typedef XrmQuark XrmRepresentation; 

typedef struct { 

unsigned int size; 

caddr_t addr; 
} XrmValue, *XrmValuePtr; 

XrmSearchList is a pointer to an opaque data type. 

Related Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, 
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut- 
StringResource, XrmQGetResource, XrmQGetSearchList, XrmQPutResource, 
XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuark- 
List, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark. 



Xlib Reference Manual 40 1 



XrmQPutReSOUrce \ x ,,b- Resource Manager- 

Name 

XrmQPutResource store a resource specification into a database using quarks. 

Synopsis 

void XrmQPutResource (database, bindings, quarks, type, value) 
XrmDatabase *database; /* SEND, and if NULL, RETURN */ 
XrmBindingList bindings; 
XrmQuarkList quarks; 
XrmRepresentation type; 
XrmValue * value; 

Arguments 

database Specifies a pointer to the resource database. If database contains NULL, a new 
resource database is created and a pointer to it is returned in database. 

bindings Specifies a list of bindings for binding together the guards argument. 

quarks Specifies the complete or partial name or class list of the resource to be stored, 

type Specifies the type of the resource. 

val ue Specifies the value of the resource. 

Description 

XrmQPutResource stores a resource specification into the database. 

database can be a previously defined database, as returned by XrmGetStringDatabase, 
XrmGetFileDatabase, or from XrmMergeDatabases. If database is NULL, a new 
database is created and a pointer to it returned in database. 

bindings and quarks together specify where the value should be stored in the database. 
See XrmStringToBindingQuarkList for a brief description of binding and quark lists. 
See XrmGetResource for a description of the resource manager naming conventions and 
lookup rules. 

type is the representation type of value. This provides a way to distinguish between differ 
ent representations of the same information. Representation types are user defined character 
strings describing the way the data is represented. For example, a color may be specified by a 
color name ("red"), or be coded in a hexadecimal string ("#4f6c84") (if it is to be used as an 
argument to XParseColor.) The representation type would distinguish between these two. 
Representation types are created from simple character strings by using the macro Xrm- 
StringToRepresentation. The type XrmRepresentation is actually the same type 
as XrmQuark, since it is an ID for a string. The representation is stored along with the value 
in the database, and is returned when the database is accessed. 

value returns the value of the resource, specified as an XrmValue. 

XrmGetResource contains the complete description of how data is accessed from the data 
base, and so provides a good perspective on how it is stored. 



402 Xlib Reference Manual 



Xlib - Resource Manager (continued) XrmQPutResOUrce 

For more information, see Volume One, Chapter 11, Managing User Preferences. 

Structures 

XrmDatabase is a pointer to an opaque data type. 

typedef enum { 

XrmBindTightly, XrmBindLoosely 
} XrmBinding, *XrmBindingList ; 

typedef int XrmQuark, *XrmQuarkList; 
typedef XrmQuarkList XrmNameList; 
typedef XrmQuark XrmRepresentation; 

typedef struct { 

unsigned int size; 

caddr_t addr; 
} XrmValue, *XrmValuePtr; 

Related Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDat abases, XrmParseCommand, 
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut- 
StringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearch- 
Resource, XrmQPutStringResource, XrmQuarkToString, XrmString- 
ToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, Xrm- 
UniqueQuark. 



Xlib Reference Manual 403 



XrmQPutStringResource \ Xllb _ Resource Manager _ 

Name 

XrmQPutStringResource add a resource specification to a database using a quark resource 
name and string value. 

Synopsis 

void XrmQPutStringResource ( database, bindings, quarks, value) 
XrmDatabase *database; /* SEND, and if NULL, RETURN */ 
XrmBindingList bindings; 
XrmQuarkList quarks; 
char * value; 

Arguments 

database Specifies a pointer to the resource database. If database contains NULL, a new 
resource database is created and a pointer to it is returned in database. 

bindings Specifies a list of bindings for binding together the guards argument. 
guards Specifies the complete or partial name or class list of the resource to be stored. 

val ue Specifies the value of the resource as a string. 

Description 

XrmQPutStringResource stores a resource specification into the specified database. 

XrmQPutStringResource is a cross between XrmQPutResource and XrmPut- 
StringResource. Like XrmQPutResource, it specifies the resource by guards and 
bindings, two lists that together make a name/class list with loose and tight bindings. Like 
XrmPutStringResource, it specifies the value to be stored as a string, that value is con 
verted into an XrmValue, and the default representation type String is used. 

XrmPutResource, XrmQPutResource, XrmPutStringResource, XrmQPut 
StringResource and XrmPutLineResource all store data into a database. See Xrm 
QPutResource for the most complete description of this process. 

For more information, see Volume One, Chapter 11, Managing User Preferences. 

Structures 

XrmDatabase is a pointer to an opaque data type. 

typedef enum { 

XrmBindTightly, XrmBindLoosely 
} XrmBinding, *XrmBindingList ; 

typedef int XrmQuark, *XrmQuarkList ; 

Related Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, 
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut 
StringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearch- 



404 Xlib Reference Manual 



Xlib - Resource Manager (continued) XrmQPutStringResource 

Resource, XrmQPutResource, XrmQuarkToString, XrmStringToBinding- 
QuarkList, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark. 



Xlib Reference Manual 405 



XrmQuarkToString \ X||b _ Resource Managar _ 

Name 

XrmQuarkToString convert a quark to a string. 

Synopsis 

char *XrmQuarkToString ( quark) 
XrmQuark quark; 

Arguments 

quark Specifies the quark for which the equivalent string is desired. 

Description 

XrmQuarkToString returns the string for which the specified quark is serving as a short 
hand symbol. The quark was earlier set to represent the string by XrmStringToQuark. The 
string pointed to by the return value must not be modified or freed, because that string is in the 
data structure used by the resource manager for assigning quarks. If no string exists for that 
quark, XrmQuarkToString returns NULL. 

Since the resource manager needs to make many comparisons of strings when it gets data from 
the database, it is more efficient to convert these strings into quarks, and to compare quarks 
instead. Since quarks are represented by integers, comparing quarks is trivial. 

The three #def ine statements in the Structures section provide an extra level of abstraction. 
They define macros so that names, classes and representations can also be represented as 
quarks. 

For more information, see Volume One, Chapter II, Managing User Preferences. 
Structures 

typedef int XrmQuark; 

/* macro definitions from <Xll/Xresource ,h> */ 

#define XrmNameToString (name) XrmQuarkToString (name) 
#define XrmClassToString (class) XrmQuarkToString (class) 
#define XrmRepresentationToString (type) XrmQuarkToString (type) 

Related Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, 
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut- 
StringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearch- 
Resource, XrmQPutResource, XrmQPutStringResource, XrmString- 
ToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, Xrm- 
UniqueQuark. 



406 Xlib Reference Manual 



Xlib - Resource Manager- 



J XrmStringToBindingQuarkList 



Name 

XrmStringToBindingQuarkList convert a key string to a binding list and a quark list. 
Synopsis 

XrmStringToBindingQuarkList (string, bindings, quarks) 
char *string; 

XrmBindingList bindings; /* RETURN */ 
XrmQuarkList quarks; /* RETURN */ 

Arguments 

string Specifies the string for which the list of quarks and list of bindings are to be 

generated. Must be NULL terminated. 

bindings Returns the binding list. The caller must allocate sufficient space for the 
binding list before the call. 

quark Returns the list of quarks. The caller must allocate sufficient space for the 

quarks list before the call. 

Description 

XrmStringToBindingQuarkList converts a resource specification string into two lists 
one of quarks and one of bindings. Component names in the list are separated by a dot (".") 
indicating a tight binding or an asterisk ("*") indicating a loose binding. If the string does not 
start with dot or asterisk, a dot (".") is assumed. 

A tight binding means that the quarks on either side of the binding are consecutive in the key. 
A loose binding, on the other hand, is a wildcard that can match any number of unspecified 
components in between the two quarks separated by the binding. Tight and loose bindings are 
used in the match rules, which compare multicomponent strings to find matches and determine 
the best match. See XrmGet Re source for a full description of lookup rules. 

For example, *a . b*c becomes: 

quarks bindings 

"a" XrmBindLoosely 
"b" XrmBindTightly 
"c" XrmBindLoosely 

For more information, see Volume One, Chapter II, Managing User Preferences. 
Structures 

typedef int XrmQuark, *XrmQuarkList ; 
typedef enum ( 

XrmBindLoosely, XrmBindTightly 
) XrmBinding, *XrmBindingList ; 



Xlib Reference Manual 407 



XrmStrlngToBlndingQuarkLiSt (continued) Xlib - Resource Manager 

Related Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, 
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut- 
StringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearch- 
Resource, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, 
XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark. 



408 Xlib Reference Manual 



Xlib - Resource Manager- 



J XrmStringToQuark 



Name 

XrmStringToQuark convert a string to a quark. 

Synopsis 

XrmQuark XrmStringToQuark (string) 
char *string; 

Arguments 

string Specifies the string for which a quark is to be allocated. 

Description 

XrmStringToQuark returns a quark that will represent the specified string. If a quark 
already exists for the string, that previously existing quark is returned. If no quark exists for the 
string, then a new quark is created, assigned to the string, and string is copied into the quark 
table. (Since string is copied, it may be freed. However, the copy of the string in the quark 
table must not be modified or freed.) XrmQuarkToString performs the inverse function. 

Since the resource manager needs to make many comparisons of strings when it gets data from 
the database, it is more efficient to convert these strings into quarks, and to compare quarks 
instead. Since quarks are presently represented by integers, comparing quarks is trivial. 

The three #def ine statements in the Structures section provide an extra level of abstraction. 
They define macros so that names, classes, and representations can also be represented as 
quarks. 

For more information, see Volume One, Chapter 11, Managing User Preferences. 
Structures 

typedef int XrmQuark; 

/* macro definitions from <Xll/Xresource ,h> */ 

tdefine XrmStringToName (string) XrmStringToQuark (string) 

#define XrmStringToClass (string) XrmStringToQuark (string) 

#def ine XrmStringToRepresentation (string) XrmStringToQuark (string) 

Related Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, 
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut- 
StringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearch- 
Resource, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, 
XrmStringToBindingQuarkList, XrmStringToQuarkList, XrmUniqueQuark. 



Xlib Reference Manual 409 



XrmStringToQuarkList \ XMb _ Resource Manager _ 

Name 

XrmStringToQuarkList convert a key string to a quark list. 

Synopsis 

void XrmStringToQuarkList ( string, quarks) 
char *string; 
XrmQuarkList quarks; /* RETURN */ 

Arguments 

string Specifies the string for which a list of quarks is to be generated. Must be null- 

terminated. The components may be separated by the "." character (tight 
binding) or the "*" character (loose binding). 

quarks Returns the list of quarks. 

Description 

XrmStringToQuarkList converts string (generally a fully qualified name/class string) 
to a list of quarks. Components of the string may be separated by a tight binding (the "." char 
acter) or a loose binding ("*"). Use XrmStringToBindingQuarkList for lists which 
contain both tight and loose bindings. See XrmGetResource for a description of tight and 
loose binding. 

Each component of the string is individually converted into a quark. See XrmString- 
ToQuark for information about quarks and converting strings to quarks, quarks is a null- 
terminated list of quarks. 

For example, xmh . toe . command . background is converted into a list of four quarks: the 
quarks for xmh, toe, command, and background, in that order. A NULLQUARK is appended 
to the end of the list. 

Note that XrmStringToNameList and XrmStringToClassList are macros that per 
form exactly the same function as XrmStringToQuarkList. These may be used in cases 
where they clarify the code. 

For more information, see Volume One, Chapter 11, Managing User Preferences. 
Structures 

typedef int XrmQuark *XrmQuarkList; 

#define XrmStringToNameList (str, name) XrmStringToQuarkList ( (str) , (name)) 
tdefine XrmStringToClassList (str, class) XrmStringToQuarkList ( (str) , (class)) 



410 Xlib Reference Manual 



Xlib - Resource Manager (continued) XrmStringToQuarkList 

Related Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, 
Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, Xrm- 
PutLineResource, XrmPutResource, XrmPutStringResource, XrmQGetResource, Xrm- 
QGetSearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutString- 
Resource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuark, 
XrmStringToRepresentation.XrmUniqueQuark. 



Xlib Reference Manual 411 



XrmUniqueQuark v. 

v Xlib - Resource Manager- 
Name 

XrmUniqueQuark allocate a new quark. 

Synopsis 

XrmQuark XrmUniqueQuark ( ) 

Description 

XrmUniqueQuark allocates a quark that is guaranteed not to represent any existing string. 
For most applications, XrmStringToQuark is more useful, as it binds a quark to a string. 
However, on some occasions, you may want to allocate a quark that has no string equivalent. 

The shorthand name for a string is called a quark and is the type XrmQuark. Quarks are used 
to improve performance of the resource manager, which must make many string comparisons. 
Quarks are presently represented as integers. Simple comparisons of quarks can be performed 
rather than lengthy string comparisons. 

A quark is to a string what an atom is to a property name in the server, but its use is entirely 
local to your application. 

For more information, see Volume One, Chapter 11, Managing User Preferences. 
Structures 

typedef int XrmQuark; 

Related Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, 
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut- 
StringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearch- 
Resource, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, 
XrmStringToBindingQuarkList, XrmStringToQuarkList, XrmStringTo 
Quark. 



4 12 Xlib Reference Manual 



D J XRotateBuffers 

Xlib - Cut Buffers 

Name 

XRotateBuffers rotate the cut buffers. 

Synopsis 

XRotateBuffers (display, rotate) 
Display * display; 
int rotate; 

Arguments 

display Specifies a connection to an X server; returned from xopenDisplay. 

rotate Specifies how many positions to rotate the cut buffers. 

Description 

XRotateBuffers rotates the 8 cut buffers the amount specified by rotate. The contents 

of buffer moves to buffer rotate, contents of buffer 1 moves to buffer (rotate+1) mod 8, 

contents of buffer 2 moves to buffer (rotate+2) mod 8, and so on. 

This routine will not work if any of the buffers have not been stored into with xstoreBuf f er 

orXStoreBytes. 

This cut buffer numbering is global to the display. 

See the description of cut buffers in Volume One, Chapter 13, Other Programming Techniques. 

Related Commands 

XFetchBuf f er, XFetchBytes, XStoreBuf f er, XStoreBytes. 



Xlib Reference Manual 4 1 3 



XRotateWindowProperties 



X 



Xlib- Properties- 



Name 

XRotateWindowProperties rotate properties in the properties array. 



properties, num_jprop, 



Synopsis 

XRotateWindowProperties ( display, 

npositions) 
Display * display; 
Window w; 

Atom properties [] ; 
int num_prop; 
int npositions; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the ID of the window whose properties are to be rearranged. 

properties Specifies the list of properties to be rotated. 
num_prop Specifies the length of the properties array. 

npositions Specifies the number of positions to rotate the property list. The sign controls 
the direction of rotation. 

Description 

XRotateWindowProperties rotates the contents of an array of properties on a window. If 
the property names in the properties array are viewed as if they were numbered starting 
from and if there are num_prop property names in the list, then the value associated with 
property name / becomes the value associated with property name (/ + npositions) mod 
num_prop, for all / from to num_prop - 1. Therefore, the sign of npositions controls 
the direction of rotation. The effect is to rotate the states by npositions places around the 
virtual ring of property names (right for positive npositions, left for negative nposi- 
tion). 

If npositions mod num_j>rop is nonzero, a PropertyNotify event is generated for 
each property, in the order listed. 

If a BadAtom, BadMatch, or Badwindow error is generated, no properties are changed. 



Error 

BadAtom 

BadMatch 
Badwindow 



Atom occurs more than once in list for the window. 
No property with that name for the window. 

An atom appears more that once in the list or no property with that name is 
defined for the window. 



414 



Xlib Reference Manual 



Xlib - Properties (continued) XRotateWindOWPrOpertieS 

Related Commands 

XChangeProperty, XDeleteProperty, XGetAtomName, XGetFontProperty, 
XGetWindowProperty, XInternAtom, XListProperties, XSetStandard- 
Properties. 



Xlib Reference Manual 415 



XSaveContext \ Vll 

N Xlib - Context Manager 

Name 

XSaveContext save a data value corresponding to a window and context type (not graphics 
context). 

Synopsis 

int XSaveContext ( display, w, context, data) 
Display * display; 
Window w; 
XContext context; 
caddr_t data; 

Arguments 

display Specifies a connection to an X server; returned from xopenDisplay. 

w Specifies the ID of the window with which the data is associated. 

context Specifies the context type to which the data corresponds. 

data Specifies the data to be associated with the window and context. 

Description 

XSaveContext saves data to the context manager database, according to the specified win 
dow and context ID. The context manager is used for associating data with windows within 
an application. The client must have called XUniqueContext to get the context ID 
before calling this function. The meaning of the data is indicated by the context ID, but is 
completely up to the client. 

If an entry with the specified window and context ID already exists, XSaveContext writes 
over it with the specified data. 

The XSaveContext function returns XCNOMEM (a nonzero error code) if an error has occurred 
and zero (0) otherwise. For more information, see the description of the context manager in 
Volume One, Chapter 13, Other Programming Techniques. 

Structures 

typedef int XContext; 

Related Commands 

XDeleteContext, XFindContext, XUniqueContext. 



4 16 Xlib Reference Manual 



-X,,b - ,npu, Hand,,ng 



Name 

XSelectlnput select the event types to be sent to a window. 

Synopsis 

XSelectlnput (display, w, event_mask) 
Display * display ; 
Window w; 
long event_mask; 

Arguments 

display Specifies a connection to an X server; returned from xopenDisplay. 

w Specifies the ID of the window interested in the events. 

event_mask Specifies the event mask. This mask is the bitwise OR of one or more of the 
valid event mask bits (see below). 

Description 

XSelectlnput defines which input events the window is interested in. If a window is not 
interested in a device event (button, key, motion, or border crossing), it propagates up to the 
closest ancestor unless otherwise specified in the do_not_propagate_mask attribute. 

The bits of the mask are defined in <Xll/X.h> : 

ButtonPressMask NoEventMask 

ButtonReleaseMask KeyPressMask 

EnterWindowMask KeyReleaseMask 

LeaveWindowMask ExposureMask 

Point erMotionMask VisibilityChangeMask 
PointerMotionHintMask StructureNotifyMask 

ButtonlMotionMask ResizeRedirectMask 

Button2MotionMask SubstructureNotifyMask 

ButtonSMotionMask SubstructureRedirectMask 

Button4MotionMask FocusChangeMask 

ButtonSMotionMask PropertyChangeMask 

ButtonMotionMask ColormapChangeMask 

KeymapStateMask OwnerGrabButtonMask 

A call on XSelectlnput overrides any previous call on XSelectlnput for the same win 
dow from the same client but not for other clients. Multiple clients can select input on the same 
window; their event_mask window attributes are disjoint. When an event is generated it will 
be reported to all interested clients. However, only one client at a time can select for each of 
SubstructureRedirectMask, ResizeRedirectMask, and ButtonPress. 

If a window has both ButtonPressMask and ButtonReleaseMask selected, then a 
ButtonPress event in that window will automatically grab the mouse until all buttons are 
released, with events sent to windows as described for XGrabPointer. This ensures that a 



Xlib Reference Manual 4 1 7 



XSeleCtlnpUt (continued) Xlib - Input Handling 

window will see the ButtonRelease event corresponding to the ButtonPress event, 
even though the mouse may have exited the window in the meantime. 

If PointerMotionMask is selected, events will be sent independent of the state of the 
mouse buttons. If instead, one or more of ButtonlMotionMask, Button2MotionMask, 
Button3MotionMask, Button4MotionMask, ButtonSMotionMask is selected, 
MotionNotif y events will be generated only when one or more of the specified buttons is 
depressed. 

XCreateWindow and XChangeWindowAt tributes can also set the event_mask attri 
bute. 

For more information, see Volume One, Chapter 8, Events. 

Errors 

Badva lue Specified event mask invalid. 

BadWindow 

Related Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued, 
XGetlnputFocus, XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent, 
XPeekEvent, XPeeklf Event, XPending, XPutBackEvent, XSendEvent, XSet- 
InputFocus, XSynchronize, XWindowEvent. 



41 Q Xlib Reference Manual 



-xiib - input Handling / XSendEvent 

Name 

XSendEvent send an event 

Synopsis 

Status XSendEvent (display, w, propagate, event_mask r event) 
Display *display; 
Window w; 
Bool propagate; 
long event_mask / 
XEvent *event; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XQpenD i sp 1 ay. 

w Specifies the ID of the window where you want to send the event Pass the 

window resource ID, PointerWindow, or InputFocus. 

propagate Specifies how the sent event should propagate depending on event_mask. 
See description below. May be True or False. 

event_mask Specifies the event mask. See XSelect Input for a detailed list of the 
event masks. 

event Specifies a pointer to the event to be sent. 

Errors 

BadValue Specified event is not a valid core or extension event type, or event mask is 
invalid. 

BadWindow 

Description 

XSendEvent sends an event from one client to another (or conceivably to itself). This func 
tion is used for communication between clients using selections, for simulating user actions in 
demos, and for other purposes. 

The specified event is sent to the window indicated by w regardless of active grabs. 

If w is set to PointerWindow, the destination of the event will be the window that the pointer 
is in. If w is InputFocus is specified, then the destination is the focus window, regardless of 
pointer position. 

If propagate is False, then the event is sent to every client selecting on the window speci 
fied by w any of the event types in event_mask. If propagate is True and no clients have 
been selected on w any of the event types in event_mask, then the event propagates like any 
other event. 

The event code must be one of the core events, or one of the events defined by a loaded exten 
sion, so that the server can correctly byte swap the contents as necessary. The contents of the 
event are otherwise unaltered and unchecked by the server. The send_event field in every 
event type, which if True indicates that the event was sent with XSendEvent. 



Xlib Reference Manual 4 19 



XSendEvent (continued) Xlib- Input Handling 

This function is often used in selection processing. For example, the owner of a selection 
should use XSendEvent to send a Select ionNot if y event to a requestor when a selec 
tion has been converted and stored as a property. See Volume One, Chapter 10, Interclient 
Communication for more information. 

The status returned by XSendEvent indicates whether or not the given XEvent structure was 
successfully converted into a wire event. This value is zero on failure, or nonzero on success. 
Along with changes in the extensions mechanism, this makes merging of two wire events into a 
single user-visible event possible. 

Structures 

See Appendix E, Event Reference, for the contents of each event structure. 

Related Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued, 
XGetlnputFocus, XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent, 
XPeekEvent, XPeeklf Event, XPending, XPutBackEvent, XSelectlnput, XSet- 
InputFocus, XSynchronize, XWindowEvent. 



420 Xlib Reference Manual 



-x,ib - HO* Acce,, / XSetAccessControl 

Name 

XSetAccessControl disable or enable access control. 

Synopsis 

XSetAccessControl (display, mode) 
Display * display ; 
int mode ; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

mode Specifies whether you want to enable or disable the access control. Pass one 

of these constants: EnableAccess orDisableAccess. 

Description 

XSetAccessControl specifies whether the server should check the host access list before 
allowing access to clients running on remote hosts. If the constant used is DisableAccess, 
clients from any host have access unchallenged. 

This routine can only be called from a client running on the same host as the server. 

For more information on access control lists, see Volume One, Chapter 13, Other Programming 
Techniques. 

Errors 

BadAccess 
BadValue 

Related Commands 

XAddHost, XAddHosts, XDisableAccessControl, XEnableAccessControl, 
XListHosts, XRemoveHost, XRemoveHosts. 



Xlib Reference Manual 42 1 



XSet After Function "\ VI1 

v Xlib - Error Handling- 
Name 

XSetAfterFunction set a function called after all Xlib functions. 

Synopsis 

int (*XSetAfterFunct ion (display, func))() 
Display * display; 
int (*func) () ; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

func Specifies the user-defined function to be called after each Xlib function. This 

function is called with one argument, the display pointer. 

Description 

All Xlib functions that generate protocol requests can call what is known as an after function 
after completing their work (normally, they don t). XSetAfterFunction allows you to 
write a function to be called. 

XSynchronize sets an after function to make sure that the input and request buffers are 
flushed after every Xlib routine. 

For more information, see Volume One, Chapter 13, Other Programming Techniques. 
Related Commands 

XDisplayName, XGetErrorDatabaseText, XGetErrorText, XSetError- 
Handler, XSetlOErrorHandler, XSynchronize. 



422 Xlib Reference Manual 



Xlib - Graphics Context- 



XSetArcMode 



Name 

XSetArcMode set the arc mode in a graphics context. 

Synopsis 

XSetArcMode ( display, gc , arc_mode) 
Display * display; 
GC gc; 
int arc mode; 



Arguments 

display 

gc 

arc mode 



Specifies a connection to an X server; returned from XOpenDi splay. 
Specifies the graphics context. 

Specifies the arc mode for the specified graphics context. Possible values are 
ArcChordorArcPieSli.ee. 



Description 

XSetArcMode sets the arc_mode component of a GC, which controls filling in the XFill- 
Arcs function. ArcChord specifies that the area between the arc and a line segment joining 
the endpoints of the arc is filled. ArcPieSlice specifies that the area filled is delimited by 
the arc and two line segments connecting the ends of the arc to the center point of the rectangle 
defining the arc. 





ArcChord 



ArcPieSlice 



Xlib Reference Manual 



423 



XSetArcMode (continued) Xlib - Graphics Context 

Errors 

BadGC 
BadValue 

Related Commands 

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, 
XSetBackground, XSetClipMask, XSetClipOrigin, XSetClipRectangles, 
XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground, XSet- 
Function, XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, 
XSetState, XSetStipple, XSetSubwindowMode, XSetTSOrigin. 



424 Xlib Reference Manual 



Xlib - Graphics Context- 



J XSetBackground 



Name 

XSetBackground set the background pixel value in a graphics context. 

Synopsis 

XSetBackground (display, gc , background) 
Display * display; 
GC gc; 
unsigned long background; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

gc Specifies the graphics context. 

background Specifies the background component of the GC. 

Description 

XSetBackground sets the background pixel value component of a GC. Note that this is 
different from the background of a window, which can be set with either XSetwindow- 

Background or XSetWindowBackgroundPixmap. 

The specified pixel value must be returned by BlackPixel, WhitePixel, or one of the rou 
tines that allocate colors. 

Errors 

BadGC 

Related Commands 

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, 
XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSet- 
Dashes, XSetFillRule, XSetFillStyle, XSetForeground, XSetFunction, 
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, XSetState, 
XSetStipple, XSetSubwindowMode, XSetTSOrigin. 



Xlib Reference Manual 425 



XSetClaSSHint V X,,b- Window Manager Hints- 

Name 

XSetClassHint set the XA_WM_CLASS property of a window. 

Synopsis 

XSetClassHint ( display, w, class_hints) 
Display * display; 
Window w; 
XClassHint *class_hints ; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenDi spl ay . 

w Specifies the ID of the window for which the class hint is to be set. 

class_hints Specifies the XClassHint structure that is to be used. 

Description 

XSetClassHint sets the XA_WM_CLASS property for the specified window. The window 
manager may (or may not) read this property, and use it to get resource defaults that apply to 
the window manager s handling of this application. 

The XClassHint structure set contains res_class, which is the name of the client such as 
"emacs", and res_name, which is the first of the following that applies: 

command line option (-rn name) 

a specific environment variable (e.g., RESOURCE_NAME) 

the trailing component of argv [ ] (after the last /) 

For more information, see Volume One, Chapter 10, Inter client Communication. 

Errors 

BadAlloc 
BadWindow 

Structures 

typedef struct { 

char *res_name; 

char *res_class; 
} XClassHint; 

Related Commands 

XAllocClassHint,XFetchName,XGetClassHint,XGetIconName,XGet Icon- 
Sizes, XGetNormalHints, XGetSizeHints, XGetTransientForHint, XGet- 
WMHints, XGetZoomHints, XSetCommand, XSet IconName, XSetlconSizes, 
XSetNormalHints, XSetSizeHints, XSetTransientForHint, XSetWMHints, 
XSetZoomHints, XStoreName, XSetWMProperties. 



426 Xlib Reference Manual 



-XHb - Graphics Con,x, XSetClipMask 

Name 

XSetClipMask set clip_mask pixmap in a graphics context. 

Synopsis 

XSetClipMask (display , gc, clip_mask) 
Display *display; 
GC gc; 
Pixmap clip_mask; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

gc Specifies the graphics context. 

clip_jnas;c Specifies a pixmap of depth 1 to be used as the clip mask. Pass the constant 
None if no clipping is desired. 

Description 

XSetClipMask sets the clip_mask component of a GC to a pixmap. The clip_mask fil 
ters which pixels in the destination are drawn. If clip_mask is set to None, the pixels are 
always drawn, regardless of the clip origin. Use XSetClipRectangles to set clip_mask 
to a set of rectangles, or XSetRegion to set clip_mask to a region. 

For more information, see Volume One, Chapter 5, The Graphics Context. 
Errors 

BadGC 

BadMatch 

BadPixmap 

Related Commands 

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, 
XSetArcMode, XSetBackground, XSetClipOrigin, XSetClipRectangles, 
XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground, XSet- 
Function, XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, 
XSetState, XSetStipple, XSetSubwindowMode, XSetTSOrigin. 



Xlib Reference Manual 427 



XSetClipOrigin \ X1|b _ Graph|cs Contexl _ 

Name 

XSetClipOrigin set the clip origin in a graphics context. 

Synopsis 

XSetClipOrigin (display, gc , clip_x_origin, clip_y_origin) 
Display * display; 
GC gc; 
int clip_x_origin f cl ip_y_ origin ; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

gc Specifies the graphics context. 

clip_x_origin Specify the coordinates of the clip origin (interpreted later relative to the 
clip_y_origin window drawn into with this GC). 

Description 

XSetClipOrigin sets the clip_x_origin and clip_y_origin components of a GC. 
The clip origin controls the position of the clip_mask in the GC, which filters which pixels 
are drawn in the destination of a drawing request using this GC. 

For more information, see Volume One, Chapter 5, The Graphics Context. 
Errors 

BadGC 

Related Commands 

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, 
XSetArcMode, XSetBackground, XSetClipMask, XSetClipRectangles, XSet- 
Dashes, XSetFillRule, XSetFillStyle, XSetForeground, XSetFunction, 
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, XSetState, 
XSetStipple, XSetSubwindowMode, XSetTSOrigin. 



428 Xlib Reference Manual 



Xlib - Graphics Context - 



J XSetClipRectangles 



Name 

XSetClipRectangles change clip_mask in a graphics context to a list of rectangles. 

Synopsis 

XSetClipRectangles (display, gc , clip_x_orlgin, 

clip_y_origin, rectangles, nrects , ordering) 
Display * display; 
GC gc; 

int clip_x_origin r clip_y_ origin; 
XRectangle rectangles [] ; 
int nrects; 
int ordering; 

Arguments 

di splay Specifies a connection to an X server; returned from XOpenDi splay. 

gc Specifies the graphics context. 

clip_x_ origin Specify the x and y coordinates of the clip origin (interpreted later rela- 
clip_y_ origin live to the window drawn into with this GC). 

rectangles Specifies an array of rectangles. These are the rectangles you want draw 

ing clipped to. 

nrects Specifies the number of rectangles. 

ordering Specifies the ordering relations of the rectangles. Possible values are 

Unsorted, YSorted, YXSorted, or YXBanded. 

Description 

XSetClipRectangles changes the clip_mask component in the specified GC to the 
specified list of rectangles and sets the clip origin to clip_x_origin and clip_y_ori- 
gin. The rectangle coordinates are interpreted relative to the clip origin. The output from 
drawing requests using that GC are henceforth clipped to remain contained within the rectan 
gles. The rectangles should be nonintersecting, or the graphics results will be undefined. If the 
list of rectangles is empty, output is effectively disabled as all space is clipped in that GC. This 
is the opposite of a clip_mask of None in XCreateGC, XChangeGC, or XSetClipMask. 

If known by the client, ordering relations on the rectangles can be specified with the order 
ing 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 requir 
ing that, for every possible horizontal y scan line, all rectangles that include that scan line have 
identical y origins and y extents. 



Xlib Reference Manual 429 



XSetClip Rectangles (continued) Xlib - Graphics Context 

To cancel the effect of this command, so that there is no clipping, pass None as the 
clip_mask in XChangeGC orXSetClipMask. 

For more information, see Volume One, Chapter 5, The Graphics Context. 
Structures 

typedef struct { 

short x,y; 

unsigned short width, height; 
} XRectangle; 

Errors 

BadAlloc 

BadGC 

BadMatch Incorrect ordering (error message server-dependent). 

BadValue 

Related Commands 

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, 
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSet- 
Dashes, XSetFillRule, XSetFillStyle, XSetForeground, XSetFunction, 
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, XSetState, 
XSetStipple, XSetSubwindowMode, XSetTSOrigin. 



430 Xlib Reference Manual 



-XHb-C,ien, Connections / XSetCIOSeDOWnMOde 

Name 

XSetCloseDownMode change the close down mode of a client. 

Synopsis 

XSetCloseDownMode (display, cl ose_mode ) 
Display * display; 
int close_mode; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

close_mode Specifies the client close down mode you want. Pass one of these constants: 

DestroyAll, RetainPermanent, or RetainTemporary. 

Description 

XSetCloseDownMode defines what will happen to the client s resources at connection close. 
A connection between a client and the server starts in DestroyAll mode, and all resources 
associated with that connection will be freed when the client process dies. If the close down 
mode is RetainTemporary or RetainPermanent when the client dies, its resources live 
on until a call to XKillClient. The resource argument of XKillClient can be used to 
specify which client to kill, or it may be the constant AllTemporary, in which case XKill 
Client kills all resources of all clients that have terminated in RetainTemporary mode. 

One use of RetainTemporary or RetainPermanent might be to allow an application to 
recover from a failure of the network connection to the display server. After restarting, the 
application would need to be able to identify its own resources and reclaim control of them. 

Errors 

BadValue 

Related Commands 

XKillClient. 



Xlib Reference Manual 



^-Window Manager Hints- 

Name 

XSetCommand set the XA_WM_COMMAND atom (command line arguments). 

Synopsis 

XSetCommand (display, w, argv, argc) 
Display * display ; 
Window w; 
char **argv; 
int argc; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenDi spl ay . 

w Specifies the ID of the window whose atom is to be set. 

argv Specifies a pointer to the command and arguments used to start the application. 

argc Specifies the number of arguments. 

Description 

XSetCommand is superseded by XSetWMCommand in Release 4. 

XSetCommand is used by the application to set the XA_WM_COMMAND property for the window 
manager with the command and its arguments used to invoke the application. 

XSetCommand creates a zero-length property if argc is zero. 

Use this command only if not calling XSetStandardProperties or XSet- 
WMProperties. 

Errors 

BadAlloc 
BadWindow 

Related Commands 

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal- 
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XGetZoom- 
Hints,XSetClassHint,XSetIconName,XSetIconSizes,XSetNormalHints, 
XSetSizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints, 
XStoreName. 



432 Xlib Reference Manual 



Xlib - Graphics Context- 



XSetDashes 



Name 

XSetDashes set a pattern of line dashes in a graphics context. 

Synopsis 

XSetDashes (display, gc , dash_offset, dash_list, n) 
Display * display ; 
GC gc; 

int dash_offset ; 
char dash_list[] ; 
int n; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenD i spl ay . 

gc Specifies the graphics context. 

dash_offset Specifies the phase of the pattern for the dashed line style. 

dasi_list Specifies the dash list for the dashed line style. An odd-length list is equiva 
lent to the same list concatenated with itself to produce an even-length list. 

n Specifies the length of the dash list argument. 



First pixel 
in line 



Last pixel 
in line 



dotted (3,1) 
dot_dashed (3,4,3,1) 
short_dashed (4,4) 
long_dashed (4,7) 
odd dashed (1, 2, 3) 



1 2345678 910111213141516171819202122 

Pixels 



Xlib Reference Manual 



433 



XSetDasheS (continued) Xlib - Graphics Context 

Description 

XSetDashes sets the dashes component of a GC. The initial and alternating elements of 
the dash_list argument are the dashes, the others are the gaps. All of the elements must be 
nonzero, with lengths measured in pixels. The dash_offset argument defines the phase of 
the pattern, specifying how many pixels into the dash_list the pattern should actually begin 
in the line drawn by the request. 

n specifies the length of dash_list. An odd value for n is interpreted as specifying the 
dash_list concatenated with itself to produce twice as long a list. 

Ideally, a dash length is measured along the slope of the line, but server implementors 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. 

See Volume One, Chapter 5, The Graphics Context, for further information. 

Errors 

BadAlloc 

BadGC 

BadValue No values in dash_list. 
Element in dash_list is 0. 

Related Commands 

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, 
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip- 
Rectangles, XSetFillRule, XSetFillStyle, XSetForeground, XSet- 
Function, XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, 
XSetState, XSetStipple, XSetSubwindowMode, XSetTSOrigin. 



434 Xlib Reference Manual 



-x.ib - Error Hand.ing / XSetErrorHandler 

Name 

XSetErrorHandler set a nonfatal error event handler. 

Synopsis 

In Release 3: 

XSetErrorHandler (handler) 

int (* handler) (Display *, XErrorEvent *) 
InRelease4: int (*XSetErrorHandler (handler) )() 

int (* handler) (Display *, XErrorEvent *) 

Arguments 

handler The user-defined function to be called to handle error events. If a NULL 

pointer, reinvoke the default handler, which prints a message and exits. 

Description 

The error handler function specified in handler will be called by Xlib whenever an XError 
event is received. These are nonfatal conditions, such as unexpected values for arguments, or a 
failure in server memory allocation. It is acceptable for this procedure to return, though the 
default handler simply prints a message and exits. However, the error handler should NOT per 
form any operations (directly or indirectly) on the server. 

In Release 4, XSetErrorHandler returns a pointer to the previous error handler. 

The function is called with two arguments, the display variable and a pointer to the XError 
Event structure. Here is a trivial example of a user-defined error handler: 

int myhandler (display, myerr) 
Display *display; 
XErrorEvent *myerr; 
{ 

char msg[80] ; 

XGetErrorText (display, myerr->error_code, msg, 80); 

fprintf (stderr, "Error code %s\n", msg); 
} 

This is how the example routine would be used in XSetErrorHandler. 
XSetErrorHandler (myhandler) / 

Note that XSetErrorHandler is one of the few routines that does not require a display 
argument. The routine that calls the error handler gets the display variable from the XError 
Event structure. 

The error handler is not called on BadName errors from OpenFont, LookupColor, and 
AllocNamedColor protocol requests, on BadFont errors from a QueryFont protocol 
request, or on BadAlloc or BadAccess errors. These errors are all indicated by Status 
return value of zero in the corresponding Xlib routines, which must be caught and handled by 
the application. 

Use XlOErrorHandler to provide a handler for I/O errors such as network failures or server 
host crashes. 



Xlib Reference Manual 435 



XSetErrorHandler (continued) Xlib - Error Handling 

In the XErrorEvent structure shown below, the serial member is the number of requests 
(starting from 1) sent over the network connection since it was opened. It is the number that 
was the value of the request sequence number immediately after the failing call was made. The 
request_code member is a protocol representation of the name of the procedure that failed 
and is defined in <Xll/X.h>. 

For more information, see Volume One, Chapter 3, Basic Window Program. 
Structures 

typedef struct { 
int type 

Display *display; /* display the event was read from */ 

XID resourceid; /* resource ID */ 

unsigned long serial; /* serial number of failed request */ 
unsigned char error_code; /* error code of failed request */ 
unsigned char request_code; /* major opcode of failed request */ 
unsigned char minor_code; /* minor opcode of failed request */ 

} XErrorEvent; 

Related Commands 

XDisplayName, XGetErrorDatabaseText, XGetErrorText, XSetAf ter- 
Function, XSetlOErrorHandler, XSynchronize. 



436 Xlib Reference Manual 



Xlib - Graphics Context- 



XSetFillRule 



Name 

XSetFillRule set the fill rule in a graphics context. 

Synopsis 

XSetFillRule (display, gc, fill_rule) 
Display * display; 
GC gc; 
int fill_rule; 

Arguments 

display Specifies a connection to an X server; returned from XQpenDi splay. 

gc Specifies the graphics context. 

fill_rule Specifies the fill rule you want to set for the specified graphics context. Pos 
sible values are EvenOddRule orWindingRule. 

Description 

XSetFillRule sets the fill_rule component of a GC. The fill_rule member of the 
GC determines what pixels are drawn in XFillPolygon requests. Simply put, Winding- 
Rule fills overlapping areas of the polygon, while EvenOddRule does not fill areas that 
overlap an odd number of times. Technically, EvenOddRule means that the point is drawn if 
an arbitrary ray drawn from the point would cross the path determined by the request an odd 
number of times. WindingRule indicates that a point is drawn if a point crosses an unequal 
number of clockwise and counterclockwise path segments, as seen from the point. 




Outline of polygon to fill 



EvenOddRul< 



WindingRule 



Xlib Reference Manual 



437 



XSetFillRule (continued) Xlib - Graphics Context 

A clockwise-directed path segment is one which crosses the ray from left to right as observed 
from the point. A counterclockwise segment is one which crosses the ray from right to left as 
observed from the point. The case where a directed line segment is coincident with the ray is 
uninteresting because you can simply choose a different ray that is not coincident with a seg 
ment 

All calculations are performed on infinitely small points, so that if any point within a pixel is 
considered inside, the entire pixel is drawn. Pixels with centers exactly on boundaries are con 
sidered inside only if the filled area is to the right, except that on horizontal boundaries, the 
pixel is considered inside only if the filled area is below the pixel. 

See Volume One, Chapter 5, The Graphics Context, for more information. 

Errors 

BadGC 
BadValue 

Related Commands 

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, 
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillStyle, XSetForeground, XSetFunction, 
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, XSetState, 
XSetStipple, XSetSubwindowMode, XSetTSOrigin. 



438 Xlib Reference Manual 



Xlib - Graphics Context- 



XSetFillStyle 



Name 

XSetFillStyle set the fill style in a graphics context. 

Synopsis 

XSetFillStyle (display, gc , fill_style) 
Display * display; 
GC gc; 
int fill_style; 



Arguments 

display 



Specifies a connection to an X server; returned from xopenDi splay. 



gc Specifies the graphics context. 

fill_style Specifies the fill style for the specified graphics context. Possible values are 

FillSolid, Fill-Tiled, FillStippled, or FillOpaque- 
Stippled. 



GC foreground 
GC background 
Undrawn Pixels M 



Tile 



Stipple 




FillSolid 



FillTiled 



FillStippled FillOpaqueStippled 







Description 

XSetFillStyle sets the fill_style component of a GC. The fill_style defines the 
contents of the source for line, text, and fill requests. FillSolid indicates that the pixels rep 
resented by set bits in the source are drawn in the foreground pixel value, and unset bits in 
the source are not drawn. FillTiled uses the tile specified in the GC to determine the 
pixel values for set bits in the source. FillOpaqueStippled specifies that bits set in the 
stipple are drawn in the foreground pixel value and unset bits are drawn in the back 
ground. FillStippled draws bits set in the source and set in the stipple in the fore 
ground color, and leaves unset bits alone. 



Xlib Reference Manual 



439 



XSetFillStyle (continued) Xlib - Graphics Context 

For more information, see Volume One, Chapter 5, The Graphics Context. 
Errors 

BadGC 
BadValue 

Related Commands 

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, 
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillRule, XSetForeground, XSetFunction, 
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, XSetState, 
XSetStipple, XSetSubwindowMode, XSetTSOrigin. 



Xlib Reference Manual 



- XI ,-Pon,s 



Name 

XSetFont set the current font in a graphics context. 

Synopsis 

XSetFont (display, gc, font) 
Display * display; 
GC gc; 
Font font; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenDi spl ay. 

gc Specifies the graphics context. 

f on t Specifies the ID of the font to be used. 

Description 

XSetFont sets the font in the GC. Text drawing requests using this GC will use this font 
only if the font is loaded. Otherwise, the text will not be drawn. 

For more information, see Volume One, Chapter 5, The Graphics Context. 
Errors 

BadFont 
BadGC 

Related Commands 

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XFree- 
FontPath, XGetFontPath, XGetFontProperty, XListFonts, XListFontsWith- 
Inf o, XLoadFont, XLoadQueryFont, XQueryFont, XSetFontPath, XUnloadFont. 



Xlib Reference Manual 44 1 



XSetFontPath ~\ 



Xlib- Fonts- 



Name 

XSetFontPath set the font search path. 

Synopsis 

XSetFontPath ( display, directories, ndirs) 
Display * display; 
char ** directories; 
int ndirs; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

directories Specifies the directory path used to look for the font. Setting the path to the 
empty list restores the default path defined for the X server. 

ndi rs Specifies the number of directories in the path. 

Description 

XSetFontPath defines the directory search path for font lookup for all clients. Therefore the 
user should construct a new directory search path carefully by adding to the old directory 
search path obtained by XGetFontPath. Passing an invalid path can result in preventing the 
server from accessing any fonts. Also avoid restoring the default path, since some other client 
may have changed the path on purpose. 

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 specific and are not intended to be used by client applications. 

The meaning of errors from this request is system specific. 

Errors 

BadValue 

Related Commands 

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XFree- 
FontPath, XGetFontPath, XGetFontProperty, XListFonts, XListFontsWith- 
Inf o, XLoadFont, XLoadQueryFont, XQueryFont, XSetFont, XUnloadFont. 



442 Xlib Reference Manual 



-x, lb -Graph,c,con,, / XSetForeground 

Name 

XSetForeground set the foreground pixel value in a graphics context. 

Synopsis 

XSetForeground (display, gc, foreground) 
Display * display ; 
GC gc; 
unsigned long foreground; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

gc Specifies the graphics context. 

foreground Specifies the foreground pixel value you want for the specified graphics con 
text 

Description 

XSetForeground sets the foreground component in a GC. This pixel value is used for 
set bits in the source according to the f ill_style. This pixel value must be returned by 
BlackPixel, whitePixel, or a routine that allocates colors. 

See Volume One, Chapter 5, The Graphics Context, for more information on the GC. 

Errors 

BadGC 

Related Commands 

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, 
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetFunction, 
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, XSetState, 
XSetStipple, XSetSubwindowMode, XSetTSOrigin. 



Xlib Reference Manual 443 



XSetFu notion 



X 



Xlib - Graphics Context 



Name 

XSetFunction set the bitwise logical operation in a graphics context. 

Synopsis 

XSetFunction (display, gc, function) 
Display *display; 
GC gc; 
int function; 



Arguments 

display 

gc 

function 



Specifies a connection to an X server; returned from XOpenDi splay. 
Specifies the graphics context. 

Specifies the logical operation you want for the specified graphics context. See 
Description for the choices and their meanings. 

Description 

XSetFunction sets the logical operation applied between the source pixel values (generated 
by the drawing request) and existing destination pixel values (already in the window or pix- 
map) to generate the final destination pixel values in a drawing request (what is actually drawn 
to the window or pixmap). Of course, the plane_mask and clip_mask in the GC also 
affect this operation by preventing drawing to planes and pixels respectively. GXcopy, GXin- 
vert, and GXxor are the only logical operations that are commonly used. 

See Volume One, Chapter 5, The Graphics Context, for more information about the logical 
function. 



The function syn 
Symbol 


ibolsar 
Bit 


d their logical definitions are: 
Meaning 


GXclear 


0x0 





GXand 


Oxl 


src AND dst 


GXandReverse 


0x2 


srcAND(NOTdst) 


GXcopy 


0x3 


src 


GXandlnverted 


0x4 


(NOT src) AND dst 


GXnoop 


0x5 


dst 


GXxor 


0x6 


src XOR dst 


GXor 


0x7 


src OR dst 


GXnor 


0x8 


(NOT src) AND (NOT dst) 


GXequiv 


0x9 


(NOT src) XOR dst 


GXinvert 


Oxa 


(NOT dst) 


GXorReverse 


Oxb 


src OR (NOT dst) 


GXcopy Inverted 


Oxc 


(NOT src) 


GXorlnverted 


Oxd 


(NOT src) OR dst 


GXnand 


Oxe 


(NOT src) OR (NOT dst) 


GXset 


Oxf 


1 



444 



Xlib Reference Manual 



Xlib - Graphics Context (continued) XSetFunctlon 

Errors 

BadGC 
BadValue 

Related Commands 

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, 
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground, 
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, XSetState, 
XSetStipple, XSetSubwindowMode, XSetTSOrigin. 



Xlib Reference Manual 445 



XSetGraphicsExposures \ 



Xlib - Graphics Context- 



Name 

XSetGraphicsExposures set the graphics_exposures component in a graphics context. 

Synopsis 

XSetGraphicsExposures ( display, gc , graph! cs_exposures) 
Display *display; 
GC gc; 
Bool graphics_exposures ; 

Arguments 

display Specifies a connection to an X server; returned from XQpenDisplay. 

gc Specifies the graphics context. 

graphi cs_exposures 

Specifies whether you want GraphicsExpose and NoExpose events when 
calling XCopyArea and XCopyPlane with this graphics context. 

Description 

XSetGraphicsExposure sets the graphics_exposures member of a GC. If 
graphi cs_exposures is True, GraphicsExpose events will be generated when 
XCopyArea and XCopyPlane requests cannot be completely satisfied because a source 
region is obscured, and NoExpose events are generated when they can be completely satis 
fied. If graphi cs_exposures is False, these events are not generated. 

These events are not selected in the normal way with XSelect Input. Setting the 
graphi cs_exposures member of the GC used in the CopyArea or CopyPlane request 
is the only way to select these events. 

For more information, see Volume One, Chapter 5, The Graphics Context. 
Errors 

BadGC 
BadValue 

Related Commands 

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, 
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground, 
XSetFunction, XSetLineAttributes, XSetPlaneMask, XSetState, XSet- 
Stipple, XSetSubwindowMode, XSetTSOrigin. 



446 Xlib Reference Manual 



-X,, b -W,ndowMana g erH,n,s XSetlCOnNaiTie 

Name 

XSetlconName set the name to be displayed in a window s icon. 

Synopsis 

XSetlconName (display, w, icon_name) 
Display * display ; 
Window w; 
char *icon_name; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenDi splay. 

w Specifies the ID of the window whose icon name is being set. 

i con_name Specifies the name to be displayed in the window s icon. The name should be 
a null-terminated string. This name is returned by any subsequent call to 
XGetlconName. 

Description 

XSetlconName is superseded by XSetWMlconName in Release 4. 

XSetlconName sets the XA_WM_ICON_NAME property for a window. This is usually set by an 
application for the window manager. The name should be short, since it is to be displayed in 
association with an icon. 

XSetStandardProperties (in Release 4) or XSetWMProperties (in Release 4) also 
set this property. 

For more information, see Volume One, Chapter IQJnterclient Communication. 
Errors 

BadAlloc 
BadWindow 

Related Commands 

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal- 
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XGetZoom- 
Hints, XSetClassHint, XSetCorranand, XSetlconSizes, XSetNormalHints, 
XSetSizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints, 
XStoreName. 



Xlib Reference Manual 447 



XSetlconSizes V XIib _ Window Manager Hints _ 

Name 

XSetlconSizes set the value of the XA_WM_ICON_SIZE property. 

Synopsis 

XSetlconSizes (display, w, size_list, count) 
Display * display ; 
Window ur; 

XlconSize *size_list; 
int count; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenDi spl ay . 

w Specifies the ID of the window whose icon size property is to be set. Nor 

mally the root window. 

si ze_l i s t Specifies a pointer to the size list. 

count Specifies the number of items in the size list. 

Description 

XSetlconSizes is normally used by a window manager to set the range of preferred icon 
sizes in the XA_WM_ICON_SIZE property of the root window. 

Applications can then read the property with XGetlconSizes. 
Structures 

typedef struct { 

int min_width, min_height; 

int max_width, max_height; 

int width_inc, height_inc; 
} XlconSize; 

Errors 

BadAlloc 
BadWindow 

Related Commands 

XAllocIconSize, XFetchName, XGetClassHint, XGetlconName, XGetlcon 
Sizes, XGetNormalHints,XGetSizeHints,XGetTransientForHint,XGet- 
WMHints, XGetZoomHints, XSetClassHint, XSetCommand, XSetlconName, 
XSetNormalHints, XSetSizeHints, XSetTransientForHint, XSetWMHints, 
XSetZoomHints, XStoreName. 



448 XIib Reference Manual 



J XSetlnputFocus 

Xlib - Input Handling 

Name 

XSetlnputFocus set the keyboard focus window. 

Synopsis 

XSetlnputFocus (display, focus, revert_to, time) 
Display *display; 
Window focus; 
int revert_to; 
Time time; 

Arguments 

display Specifies a connection to an X server; returned from XQpenDisplay. 

focus Specifies the ID of the window you want to be the keyboard focus. Pass the 

window ID, PointerRoot, or None. 

revert_to Specifies which window the keyboard focus reverts to if the focus window 
becomes not viewable. Pass one of these constants: RevertToParent, 
RevertToPointerRoot, or RevertToNone. Must not be a window ID. 

time Specifies the time when the focus change should take place. Pass either a 

timestamp, expressed in milliseconds, or the constant CurrentTime. Also 
returns the time of the focus change when CurrentTime is specified. 

Description 

XSetlnputFocus changes the keyboard focus and the last-focus-change time. The function 
has no effect if time is earlier than the current last-focus-change time or later than the current 
X server time. Otherwise, the last-focus-change time is set to the specified time, with 
CurrentTime replaced by the current X server time. 

XSetlnputFocus generates Focusln and FocusOut events if focus is different from 
the current focus. 

XSetlnputFocus executes as follows, depending on what value you assign to the focus 
argument: 

If you assign None, all keyboard events are discarded until you set a new focus window. 
In this case, revert_to is ignored. 

If you assign a window ID, it becomes the main 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 normally; otherwise, the event is reported to the focus window. The 
specified focus window must be viewable at the time of the request (else a BadMatch 
error). If the focus window later becomes not viewable, the focus window will change to 
the re vert_ to argument 

If you assign PointerRoot, the focus window is dynamically taken to be the root win 
dow of whatever screen the pointer is on at each keyboard event In this case, 
revert_to is ignored. This is the default keyboard focus setting. 

If the focus window later becomes not viewable, XSetlnputFocus evaluates the 
re vert_ to argument to determine the new focus window: 



Xlib Reference Manual 449 



XSetlnpUtFOGUS (continued) Xlib - Input Handling 

If you assign RevertToParent, the focus reverts to the parent (or the closest viewable 
ancestor) automatically with a new revert_to argument of Revert ToName. 

If you assign RevertToPointerRoot or RevertToNone, the focus reverts to that 
value automatically. Focus in and FocusOut events are generated when the focus 
reverts, but the last focus change time is not affected. 

Errors 

BadMatch focus window not viewable when XSetlnputFocus called. 

BadValue 
BadWindow 

Related Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued, 
XGetlnputFocus.XGetMotionEvents, XI f Event, XMaskEvent,XNextEvent, 
XPeekEvent, XPeeklf Event, XPending, XPutBackEvent, XSelectlnput, 
XSendEvent , XSynchroni ze, XWindowEvent. 



450 Xlib Reference Manual 



f XSetlOErrorHandler 

Xlib - Error Handling 

Name 

XSetErrorHandler set a nonfatal error event handler. 

Synopsis 

In Release 3: 

XSetlOErrorHandler (ha/idler) 

int (* handler) (Display *, XErrorEvent *) 
I n Release 4: 
int (*XSetIOErrorHandler (handler) ) () 

int (* handler) (Display *, XErrorEvent *) 

Arguments 

handler Specifies user-defined fatal error handling routine. If NULL, reinvoke the 

default fatal error handler. 

Description 

XSetlOErrorHandler specifies a user-defined error handling routine for fatal errors. This 
error handler will be called by Xlib if any sort of system call error occurs, such as the connec 
tion to the server being lost. The called routine should not return. If the I/O error handler does 
return, the client process will exit. 

If handler is a NULL pointer, the default error handler is reinstated. The default I/O error 
handler prints an error message and exits. 

In Release 4, XSetlOErrorHandler returns a pointer to the previous error handler. 
For more information, see Volume One, Chapter 3, Basic Window Program. 

Related Commands 

XDisplayName, XGetErrorDatabaseText, XGetErrorText, XSetAf ter- 
Function, XSetErrorHandler, XSynchronize. 



Xlib Reference Manual 451 



XSetLineAttributes 



X 



Xlib - Graphics Context- 



Name 

XSetLineAttributes set the line drawing components in a graphics context. 

Synopsis 

XSetLineAttributes (display, gc, line_width, line_style, 

cap_style , join_style) 
Display *display; 
GC gc; 

unsigned int li/ie_v/idth; 
int li/ie_style; 
int cap_style; 
int join_style; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

gc Specifies the graphics context. 



line_style 



LineSolid 



LineOnOffDash 



Line/Double Dash 



cap_style 

CapNotLast CapButt 



join_style 



CapRound 



CapPro jecting 



JoinRound 




JoinMiter 



N\ 



JoinBevel 



fill_style 

Ti| e GC foreground | GC background Q Undrawn Pixels [x] 

FillSolid FillTiled FillStippled FillOpaqueStippled 

Stipple 







Xlib Reference Manual 



Xlib - Graphics Context (continued) XSetLineAttributes 

line_width Specifies the line width in the specified graphics context. 

line_style Specifies the line style in the specified graphics context. Possible values are 

LineSolid, LineOnOf f Dash, or LineDoubleDash. 

cap_style Specifies the line and cap style in the specified graphics context. Possible 
values are CapNotLast, CapButt, CapRound, or CapPro jecting. 

join_style Specifies the line-join style in the specified graphics context. Possible values 
are JoinMiter, JoinRound, or JoinBevel. If you specify Join- 
Mitre, JoinBevel is used instead if the angle separating the two lines is 
less than 1 1 degrees. 

Description 

XSetLineAttributes sets four types of line characteristics in the GC: line_width, 
line_style, cap_style, and join_style. 

See the description of line and join styles in Volume One, Chapter 5, The Graphics Context. 
See also XSetDashes. 

A line_width of zero (0) means to use the fastest algorithm for drawing a line of one pixel 
width. These lines may not meet properly with lines specified as width one or more. 

Errors 

BadGC 
BadValue 

Related Commands 

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, 
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground, 
XSetFunction, XSetGraphicsExposures, XSetPlaneMask, XSetState, XSet- 
Stipple, XSetSubwindowMode, XSetTSOrigin. 



Xlib Reference Manual 453 



XSetModifierMapping \ x ,, b - Keyboard- 

Name 

XSetModifierMapping set keycodes to be used as modifiers (Shift, Control, etc.). 

Synopsis 

int XSetModif ierMapping ( display, mod_map) 
Display *display; 
XModif ierKeymap *mod_map; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

mod_map Specifies the XModif ierKeymap structure containing the desired modifier 
key codes. 

Description 

XSetModifierMapping is one of two ways to specify the keycodes of the keys that are to 
be used as modifiers (like Shift, Control, etc.). XSetModifierMapping specifies all the 
keycodes for all the modifiers at once. The other, easier, way is to use xinsert- 
Modif iermapEntry and XDeleteModif iermapEntry, which add or delete a single 
keycode for a single modifier key. XSetModifierMapping does the work in a single call, 
but the price of this call is that you need to manually set up the XModif ierKeymap structure 
pointed to by mod_map. This requires you to know how the XModif ierKeymap structure is 
defined and organized, as described in the next three paragraphs. 

The XModif ierKeymap structure for the mod_map argument should be created using 
XNewModif ierMap or XGetModif ierMapping. The Max_keypermod element of the 
structure specifies the maximum number of keycodes that can be mapped to each modifier. You 
define this number but there may be an upper limit on a particular server. 

The modif iermap element of the structure is an array of keycodes. There are eight by 
max_keypermod keycodes in this array: eight because there are eight modifiers, and 
max_keypermod because that is the number of keycodes that must be reserved for each mod 
ifier. 

The eight modifiers are represented by the constants ShiftMaplndex, LockMaplndex, 
ControlMapIndex, ModlMapIndex, Mod2MapIndex, ModSMapIndex, Mod4Map- 
Index, and ModSMapIndex. These are not actually used as arguments, but they are conve 
nient for referring to each row in the modif iermap structure while filling it. The definitions 
of these constants are shown in the Structures section below. 

Now you can interpret the modif iermap array. For each modifier in a given modifier- 
map, the keycodes which correspond are from modif iermap [index * 
max_keypermod] to modif iermap [( (index + 1) * max_keyspermod) -1] 
where index is the appropriate modifier index definition (ShiftMaplndex, LockMap 
lndex, etc.). You must set the mod_map array up properly before calling XSetModifier 
Mapping. Now you know why XInsertModif ierMapEntry and XDeleteModif ier- 
MapEntry were created! 

Zero keycodes are ignored. No keycode may appear twice anywhere in the map (otherwise, a 
BadValue error is generated). In addition, all of the nonzero keycodes must be in the range 



454 Xlib Reference Manual 



Xlib - Keyboard (continued) XSetModifierMapping 

specified by min_keycode and max_keycode in the Display structure (otherwise a 
BadValue error occurs). 

A server can impose restrictions on how modifiers can be changed. For example, certain keys 
may not generate up transitions in hardware, certain keys may always auto-repeat and therefore 
be unsuitable for use as modifiers, or multiple modifier keys may not be supported. If a restric 
tion is violated, then the status reply is MappingFailed, and none of the modifiers are 
changed. 

XSetModifierMapping returns MappingSuccess or MappingBusy. The server gen 
erates a MappingNotif y event on a MappingSuccess status. If the new keycodes speci 
fied for a modifier differ from those currently defined and any (current or new) keys for that 
modifier are in the down state, then the status reply is MappingBusy, and none of the modifi 
ers are changed. 

A value of zero for modif iermap indicates that no keys are valid as any modifier. 
Structures 

typedef struct { 

int max_keypermod; /* server s max # of keys per modifier */ 
KeyCode *modif iermap; /* an 8 by max_keypermod array */ 

} XModifierKeymap; 



c c 



/* Modifier name symbols. Used to build a SetModif ierMapping request 

to read a GetModif ierMapping request. */ 

#define ShiftMapIndex 

#define LockMapIndex 1 

#define ControlMapIndex 2 

#define ModlMapIndex 3 

#define Mod2MapIndex 4 

tdefine Mod3MapIndex 5 

#define ModlMapIndex 6 

#define ModSMapIndex 7 

Errors 

BadAlloc 

BadValue Keycode appears twice in the map. 

Keycode < disp-Zay->min_keycode or 
keycode > display->max_keycode. 

Related Commands 

XChangeKeyboardMapping, XDeleteModif iermapEntry, XDelete- 
Modif iermapEntry, XFreeModif iermap, XGetKeyboardMapping, XGet- 
Modif ierMapping, XInsertModif iermapEntry, XInsertModif iermapEntry, 
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym, 
XLookupString, XNewModif ierMap, XQueryKeymap, XRebindKeysym, 
XRefreshKeyboardMapping, XStringToKeysym. 



Xlib Reference Manual 455 



XSetNormalHints V Xlib _ Wlndow Manager Hlnts _ 

Name 

XSetNormalHints set the size hints property of a window in normal state (not zoomed or 
iconified). 

Synopsis 

void XSetNormalHints (display, w, hints) 
Display *display; 
Window w, 
XSizeHints *hints; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window ID. 

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

Description 

XSetNormalHints has been superseded by XSetWMNormalHints as of Release 4. 

XSetNormalHints sets the XA_WM_NORMAL_HINTS property for the specified window. 
Applications use XSetNormalHints to inform the window manager of the size or position 
desirable for that window. In addition, an application wanting to move or resize itself should 
call XSetNormalHints specifying its new desired location and size, in addition to making 
direct X calls to move or resize. This is because some window managers may redirect window 
configuration requests, but ignore the resulting events and pay attention to property changes 
instead. 

To set size hints, an application must assign values to the appropriate elements in the hints 
structure, and also set the flags field of the structure to indicate which members have 
assigned values and the source of the assignment These flags are listed in the Structures sec 
tion below. 

For more information on using hints, see Volume One, Chapter WJnterclient Communication. 
Structures 

typedef struct { 

long flags; /* which fields in structure are defined */ 

int x, y; 

int width, height; 

int min_width, min_height; 

int max_width, max_height; 

int width_inc, height_inc; 

struct { 

int x; /* numerator */ 

int y; /* denominator */ 
} min_aspect, max_aspect; 
} XSizeHints; /*~new fields in R4 here */ 



456 Xlib Reference Manual 



Xlib - Window Manager Hints (continued) XSetNormalHints 

#define USPosition (1L 0) /* user specified x, y */ 

#define USSize (1L 1) /* user specified width, height */ 

tdefine PPosition (1L 2) /* program specified position */ 

#define PSize (1L 3) /* program specified size */ 

tdefine PMinSize (1L 4) /* program specified minimum size */ 

tdefine PMaxSize (1L 5) /* program specified maximum size */ 

tdefine PResizelnc (1L 6) /* program specified resize increments */ 

tdefine PAspect (1L 7) /* program specified min/max aspect ratios */ 

tdefine PAllHints (PPosition I PSize | PMinSize I PMaxSize I PResizelnc | PAspect) 

Errors 

BadAlloc 
BadWindow 

Related Commands 

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal- 
Hints,XGetSizeHints,XGetTransientForHint,XGetWMHints,XGetZoom- 
Hints,XSetClassHint,XSetCommand,XSetIconName,XSetIconSizes,XSet- 
SizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints, XStore- 
Name. 



Xlib Reference Manual 457 



XSetPlaneMask \ Xlib _ Graphlcs Comext _ 

Name 

XSetPlaneMask set the plane mask in a graphics context. 

Synopsis 

XSetPlaneMask (display, gc, plane_mask) 
Display * display ; 
GC gc; 
unsigned long plane_mask; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

gc Specifies the graphics context. 

plane_mask Specifies the plane mask. You can use the macro AllPlanes if desired. 

Description 

XSetPlaneMask sets the plane_mask component of the specified GC. The plane_mask 
determines which planes of the destination drawable are affected by a graphics request. 

For more information, see Volume One, Chapter 5, The Graphics Context. 

Errors 

BadGC 

Related Commands 

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, 
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground, 
XSetFunction, XSetGraphicsExposures, XSetLineAttributes, XSetState, 
XSetStipple, XSetSubwindowMode, XSetTSOrigin. 



458 Xlib Reference Manual 



Xlib -Pointer 



j XSetPointerMapping 



Name 

XSetPointerMapping set the pointer button mapping. 

Synopsis 

int XSetPointerMapping (display, map, nmap) 
Display * display; 
unsigned char map[] ; 
int nmap; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

map Specifies the mapping list. 

nmap Specifies the number of items in the mapping list. 

Description 

XSetPointerMapping sets the mapping of the pointer buttons. Elements of the map list 
are indexed starting from 1. The length of the list nmap must be the same as XGet Pointer- 
Mapping returns (you must call that first). The index is a physical button number, and the ele 
ment of the list defines the effective button number. In other words, if map [2] is set to 1, 
when the second physical button is pressed, a ButtonPress event will be generated if But- 
tonlMask was selected but not if Button2Mask was selected. The button member in the 
event will read Buttonl. 

No two elements can have the same nonzero value (else a BadValue error). A value of zero 
for an element of map disables a button, and values for elements are not restricted in value by 
the number of physical buttons. If any of the buttons to be altered are currently in the down 
state, the returned value is MappingBusy and the mapping is not changed. 

This function returns either MappingSuccess or MappingBusy. XSetPointer 
Mapping generates a MappingNotif y event when it returns MappingSuccess. 

Errors 

BadValue Two elements of map [ ] have same nonzero value. 

nmap not equal to XGetPointerMapping return value. 

Related Commands 

XChangeActivePointerGrab, XChangePointerControl, XGetPointer- 
Control, XGetPointerMapping, XGrabPointer, XQueryPointer, XUngrab- 
Pointer, XWarpPointer. 



Xlib Reference Manual 459 



XSetRGBColormaps \ X1|b _ W|ndow Hanager H|ms _ 

Name 

XSetRGBColormaps set an XStandardColormap structure. 
Synopsis 

void XSetRGBColormaps ( display, w, std_colormap, count, prop 
erty) 

Display *display; 
Window w; 

XStandardColormap * std_col or/nap; 
int count; 
Atom property; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

w Specifies the window. 

std_col or/nap 

Specifies the XStandardColormap structure to be used. 

count Specifies the number of colormaps . 

property Specifies the property name. 

Availability 

Release 4 and later. 

Description 

XSetRGBColormaps replaces the RGB colormap definition in the specified property on the 
named window. If the property does not already exist, XSetRGBColormaps sets the RGB 
colormap definition in the specified property on the named window. The property is stored with 
a type of RGB_COLOR_MAP and a format of 32. Note that it is the caller s responsibility to honor 
the ICCCM restriction that only RGB_DEFAULT_MAP contain more than one definition. 

XSetRGBColormaps supersedes XSetStandardColormap. 
For more information, see Volume One, Chapter 7, Color. 

Structures 

typedef struct { 

Colormap colormap; 
unsigned long red_max; 
unsigned long red_mult; 
unsigned long green_max; 
unsigned long green_mult; 
unsigned long blue_max; 
unsigned long blue mult; 



460 Xlib Reference Manual 



Xlib - Window Manager Hints (continued) XSetRG BColormapS 

unsigned long base_jpixel; 

VisuallD visualid; /* added by ICCCM version 1 */ 

XID killid; /* added by ICCCM version 1 */ 

} XStandardColormap; 

Errors 

BadAlloc 

BadAtom 

BadWindow 

Related Commands 

XAllocStandardColormap, XGetRGBColormaps, XVisuallDFromVisual. 



Xlib Reference Manual 461 



XSetRegion V, 



Xlib- Regions- 



Name 

XSetRegion set clip_mask of the graphics context to the specified region. 

Synopsis 

XSetRegion (display, gc, r) 
Display * display; 
GC gc; 
Region r; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

gc Specifies the graphics context. 

r Specifies the region. 

Description 

XSetRegion sets the clip_mask component of a GC to the specified region. Thereafter, all 
drawing made with gc will be confined to the the area of intersection of the region and the 
drawable. 

Regions are located using an offset from a point (the region origin) which is common to all 
regions. It is up to the application to interpret the location of the region relative to a drawable. 
When the region is to be used as a clip_mask by calling XSetRegion, the upper-left corner 
of region relative to the drawable used in the graphics request will be at (xof f set + 
clip_x_origin, yof f set + clip_y_origin) , where xof f set and yof f set are 
the offset of the region and clip_x_origin and clip_y_origin are elements of the GC 
used in the graphics request 

For more information on regions, see Volume One, Chapter 5, The Graphics Context, and 
Chapter 6, Drawing Graphics and Text. 

Structures 

Region is a pointer to an opaque structure type. 

Related Commands 

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion, 
XIntersectRegion, XOf f setRegion, XPointlnRegion, XPolygonRegion, 
XRectlnRegion, XShrinkRegion, XSubtractRegion, XUnionRectWithRegion, 
XUnionRegion, XXorRegion. 



462 Xlib Reference Manual 



j XSetScreenSaver 

Xlib - Screen Saver 

Name 

XSetScreenSaver set the parameters of the screen saver. 

Synopsis 

XSetScreenSaver ( display, timeout , interval , 

prefer_blanking, allow_exposures) 
Display *display; 
int timeout, interval; 
int prefer_blanking; 
int allov_exposures; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

timeout Specifies the time of inactivity, in seconds, before the screen saver turns on. 

interval Specifies the interval, in seconds, between screen saver invocations. This is 
for intermittent changes to the display, not blanking. 

prefer_bl anking 

Specifies whether to enable screen blanking. Possible values are Dont- 
Pref erBlanking, Pref erBlanking, or Def aultBlanking. 

allow_exposures 

Specifies the current screen saver control values. Possible values are Dont- 
AllowExposures, AllowExposures, or Def aultExposures. 

Description 

XSetScreenSaver sets the parameters that control the screen saver, timeout and 
interval are specified in seconds. A positive timeout enables the screen saver. A 
timeout of zero (0) disables the screen saver, while a timeout of -1 restores the default. An 
interval of zero (0) disables the random pattern motion. If no input from devices (key 
board, mouse, etc.) is generated for the specified number of timeout seconds, the screen saver is 
activated. 

For each screen, if blanking is preferred and the hardware supports video blanking, the screen 
will simply go blank. Otherwise, if either exposures are allowed or the screen can be regen 
erated without sending exposure events to clients, the screen is tiled with the root window 
background tile, with a random origin, each interval seconds. Otherwise, the state of the 
screen does not change. All screen states are restored at the next input from a device. 

If the server-dependent screen saver method supports periodic change, interval serves as a 
hint about how long the change period should be, and a value of zero (0) hints that no periodic 
change should be made. Examples of ways to change the screen include scrambling the color 
map periodically, moving an icon image about the screen periodically, or tiling the screen with 
the root window background tile, randomly reoriginated periodically. 

For more information on the screen saver, see Volume One, Chapter 13, Other Programming 
Techniques. 



Xlib Reference Manual 463 



XSetScreenSaver (continued) Xlib - Screen Saver 

Errors 

BadValue timeout < -I. 

Related Commands 

XActivateScreenSaver, XForceScreenSaver, XGetScreenSaver, XReset- 
ScreenSaver. 



Xlib Reference Manual 



_x,ib - s,,ec,,on, / XSetSelectionOwner 

Name 

XSetSelectionOwner set the owner of a selection. 

Synopsis 

XSetSelectionOwner ( display, selection, owner, time) 
Display *display; 
Atom selection; 
Window owner; 
Time time; 

Arguments 

display Specifies a connection to an X server; returned from xopenDisplay. 

selection Specifies the selection atom. Predefined atoms are XA PRIMARY and 

XA_SECONDARY. 

owner Specifies the desired owner of the specified selection atom. This value is 

either a window ID or None. 

time Specifies the time when the selection should take place. Pass either a times- 

tamp, expressed in milliseconds, or the constant CurrentTime. 

Description 

XSetSelectionOwner sets the owner and last-change time of a selection property. This 
should be called by an application that supports cutting and pasting between windows (or at 
least cutting), when the user has made a selection of any kind of text, graphics, or data. This 
makes the information available so that other applications can request the data from the new 
selection owner using xconvertselection, which generates a SeiectionRequest event 
specifying the desired type and format of the data. Then the selection owner sends a 
SelectionNotify using xsendEvent, which notes that the information is stored in the selec 
tion property in the desired format or indicates that it couldn t do the conversion to the desired 
type. 

If owner is specified as None, then this client is giving up ownership voluntarily. Otherwise, 
the new owner is the client executing the request 

If the new owner is not the same as the current owner of the selection, and the current owner is 
a window, then the current owner is sent a SeiectionClear event. This indicates to the old 
owner that the selection should be unhighlighted. 

If the selection owner window is later destroyed, the owner of the selection automatically 
reverts to None. 

The value you pass to the time argument must be no earlier than the last-change time of the 
specified selection, and no later than the current time, or the selection is not affected. The new 
last-change time recorded is the specified time, with CurrentTime replaced by the current 
server time. If the X server reverts a selection owner to None, the last-change time is not 
affected. 

For more information on selections, see Volume One, Chapter 10, Inter client Communication. 



Xlib Reference Manual 465 



XSetSeleCtionOwner (continued) Xlib - Selections 

Errors 

BadAtom 
BadWindow 

Related Commands 

XConve rt Select! on, XGet Select ionOwner. 



466 



Xlib Reference Manual 



-X,,b-W,ndowManag e rH,n,, XSetSizeHitltS 

Name 

XSetSizeHints set the value of any property of type XA_SIZE_HINTS. 

Synopsis 

XSetSizeHints (display, w, hints, property) 
Display *display; 
Window w; 

XSizeHints *hints; 
Atom property; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenDi spl ay . 

v Specifies the window ID. 

hints Specifies a pointer to the size hints. 

property Specifies the property atom. 

Description 

XSetSizeHints has been superseded by XSetWMSizeHints as of Release 4. 

XSetSizeHints sets the named property on the specified window to the specified XSize 
Hints structure. This routine is useful if new properties of type XA_WM_SIZE_HINTS are 
defined. The predefined properties of that type have their own set and get functions, XSet- 
NormalHints and XSetZoomHints (XSetWMHints in Release 4 zoom hints are obso 
lete). 

The flags member of XSizeHints must be set to the OR of the symbols representing each 
member to be set 

For more information on using hints, see Volume One, Chapter IQJnterclient Communication. 
Structures 

typedef struct { 

long flags; /* which fields in structure are defined */ 

int x, y; 

int width, height; 

int min_width, min_height; 

int max_width, max_height; 

int width_inc, height_inc; 

struct { 

int x; /* numerator */ 

int y; /* denominator */ 
} min_aspect, max_aspect; 
} XSizeHints; 

/* flags argument in size hints */ 

#define USPosition (1L 0) /* user specified x, y */ 

tdefine USSize (1L 1) /* user specified width, height */ 

#define PPosition (1L 2) /* program specified position */ 

#define PSize (1L 3) /* program specified size */ 



Xlib Reference Manual 467 



XSetSlzeHintS (continued) Xlib - Window Manager Hints 

tdefine PMinSize (1L 4) /* program specified minimum size */ 

tdefine PMaxSize (1L 5) /* program specified maximum size */ 

#define PResizelnc (1L 6) /* program specified resize increments */ 

tdefine PAspect (1L 7) /* program specified min/max aspect ratios */ 

tdefine PAllHints (PPosit ion I PSize I PMinSize I PMaxSize | PResizelnc | PAspect) 

Errors 

BadAlloc 

BadAtom 

BadWindow 

Related Commands 

XFetchName,XGetClassHint,XGetIconName,XGetIconSizes,XGetNormal- 
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XGetZoom- 
Hints, XSetClassHint, XSetCommand, XSetlconName, XSetlconSizes, XSet- 
NormalHints, XSetTransientForHint, XSetWMHints, XSetZoomHints, 
XStoreName. 



Xlib Reference Manual 



Xlib - Colormaps- 



J XSetStandardColormap 



Name 

XSetStandardColormap change the standard colormap property. 

Synopsis 

void XSetStandardColormap ( display, w, cmap_info, property) 
Display * display; 
Window w; 

XStandardColormap *cmap_info; 
Atom property; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenDi spl ay . 
w Specifies the ID of the window with which this colormap will be associated. 

cmap_info Specifies the filled colormap information structure. 

property Specifies the standard colormap property to set. The predefined standard color- 
maps are: XA_RGB_BEST_MAP, XA_RGB_RED_MAP, XA_RGB_GREEN_ MAP, 

XA_RGB_BLUE_MAP, XA_RGB_DEFAULT_MAP, and XA_RGB_ GRAY_MAP. 

Description 

XSetStandardColormap has been superseded by XSetRGBColormap as of Release 4. 

XSetStandardColormap defines a standard colormap property. To create a standard color- 
map, follow this procedure: 

1. Open a new connection to the same server. 

2. Grab the server. 

3. See if property is on the property list of the root window for the display, using XGet - 
StandardColormap. If so, see if the colormap field is nonzero. If it is, the color- 
map already exists. 

4. If the desired property is not present, do the following: 

Determine the color capabilities of the display. Choose a visual. 
Create a colormap (not required for XA_RGB_DEFAULT_MAP). 

Call XAllocColorPlanes or XAllocColorCells to allocate cells in the 
colormap. 

Call xstoreColors to store appropriate color values in the colormap. 
Fill in the descriptive fields in the structure. 

Call XSetStandardColormap to set the property on the root window. 
Use XSetCloseDownMode to make the resource permanent. 

Close the new connection to the server. 



Xlib Reference Manual 



XSetStandardColormap 



(continued) 



Xlib - Colormaps 



5. Ungrab the server. 

6. Close the new connection to the server. 

See description of standard colormaps in Volume One, Chapter 7, Color. 

Errors 

BadAlloc 

BadAtom 

BadWindow 



Structures 

typedef struct { 

Colormap colormap; 

unsigned long red_max; 

unsigned long red_mult; 

unsigned long green_max; 

unsigned long green_mult, 

unsigned long blue_max; 

unsigned long blue_mult; 

unsigned long base_pixel, 
} XStandardColormap; 



ID of colormap made by XCreateColormap */ 



/* new fields in R4 */ 



Related Commands 

Def aultColormap, DisplayCells, XCopyColormapAndFree, XCreate 
Colormap, XFreeColormap, XGetStandardColormap, XInstallColormap, 
XListlnstalledColormaps.XSetWindowColormap, XUninstallColormap. 



470 



Xlib Reference Manual 



-x,, b -Prop.res / XSetStandardProperties 

Name 

XSetStandardProperties set the minimum set of properties for the window manager. 

Synopsis 

XSetStandardProperties ( display, w f window_name, icon_name, 

icon_pixmap, argv, argc, hints) 
Display * display; 
Window w; 

char *window_name; 
char *icon_name; 
Pixmap icon_pixmap; 
char **argv; 
int argc; 
XSizeHints *hints 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenDi splay . 

w Specifies the window ID. 

window_name Specifies the name of the window. 

i con_name Specifies the name to be displayed in the window s icon. 

icon_pixmap Specifies the pixmap that is to be used for the icon, or None. This pixmap 
must be of depth 1. 

argv Specifies a pointer to the command and arguments used to start the applica 

tion. 

argc Specifies the number of arguments. 

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

Description 

XSetStandardProperties is superceded by XSetWMProperties in Release 4. 

XSetStandardProperties sets in a single call the most essential properties for a quickie 
application. XSetStandardProperties gives a window manager some information about 
your program s preferences; it probably will not be sufficient for complex programs. 

See Volume One, Chapter 10, Interclient Communication for a description of standard proper 
ties. 

Structures 

typedef struct { 

long flags; /* which fields in structure are defined */ 

int x, y; 

int width, height; 

int min_width, min_height; 

int max_width, max_height; 

int width_inc, height_inc; 



Xlib Reference Manual 471 



XSetStandardProperties 



(continued) 



Xlib - Properties 



struct { 

int x; 
int y; 

} min_aspect 
} XSizeHints; 



/* numerator */ 
/* denominator */ 
max aspect; /* new fields in R4 */ 



/* flags argument in size hints */ 

#define USPosition (1L O)/* user specified x, y */ 

tdefine USSize (1L I)/* user specified width, height */ 



tdefine PPosition 
#define PSize 
#define PMinSize 
#define PMaxSize 
#define PResizelnc 
#define PAspect 



(1L 2) /* program specified position */ 

(1L 3)/* program specified size */ 

(1L 4)/* program specified minimum size */ 

(1L 5)/* program specified maximum size */ 

(1L 6) /* program specified resize increments */ 

(1L 7)/* program specified min and max aspect ratios */ 



#define PAllHints (PPosition | PSize | PMinSize | PMaxSize | PResizelnc | PAspect) 

Errors 

BadAlloc 
BadWindow 

Related Commands 

XChangeProperty, XDeleteProperty, XGetAtomName, XGetFontProperty, 
XGetWindowProperty, XInternAtom, XListProperties, XRotateWindow- 
Properties. 



472 



Xlib Reference Manual 



-X,,b- G raph,cs Context / XSetState 

Name 

XSetState set the foreground, background, logical function, and plane mask in a graphics 
context. 

Synopsis 

XSetState (display, gc , foreground, background, function, 

plane_mask) 
Display * display; 
GC gc; 

unsigned long foreground, background; 
int function; 
unsigned long plane_mask; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

gc Specifies the graphics context. 

foreground Specifies the foreground for the specified graphics context. 

background Specifies the background for the specified graphics context. 

function Specifies the logical function for the specified graphics context, 

pi ane_mask Specifies the plane mask for the specified graphics context. 

Description 

XSetState sets the foreground and background pixel values, the logical function, 
and the plane_mask in a GC. See XSetForeground, XSetBackground, XSet- 
Function, and XSetPlaneMask for what these members do and appropriate values. 

See Volume One, Chapter 5, The Graphics Context, for more information. 
Errors 

BadGC 
BadValue 

Related Commands 

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, 
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground, 
XSetFunction, XSetGraphicsExposures, XSetLineAttributes, XSetPlane 
Mask, XSetStipple, XSetSubwindowMode, XSetTSOrigin. 



Xlib Reference Manual 473 



XSetStipple ~\ 



Xlib- Graphics Context- 



Name 

XSetStipple set the stipple in a graphics context. 

Synopsis 

XSetStipple (display, gc , stipple) 
Display * display; 
GC gc; 
Pixmap stipple; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

gc Specifies the graphics context. 

stipple Specifies the stipple for the specified graphics context. 

Description 

XSetStipple sets the stipple component of a GC. The stipple is a pixmap of depth 
one. It is laid out like a tile. Set bits in the stipple determine which pixels in an area are drawn 
in the foreground pixel value. Unset bits in the stipple determine which pixels are drawn in 
the background pixel value if the fill_style is FillOpaqueStippled. If 
fill_style is FillStippled, pixels overlayed with unset bits in the stipple are not 
drawn. If f ill_style is FillTiled or FillSolid, the stipple is not used. 

For more information, see Volume One, Chapter 5, The Graphics Context. 
Errors 

BadGC 

BadMatch 

BadPixmap 

Related Commands 

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, 
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground, 
XSetFunction, XSetGraphicsExposures, XSetLineAttributes, XSetPlane- 
Mask, XSetState, XSetSubwindowMode, XSetTSOrigin. 



474 Xlib Reference Manual 



-x,, b - Graph.cs con,t XSetSubwindowMode 

Name 

XSetSubwindowMode set the subwindow mode in a graphics context. 

Synopsis 

XSetSubwindowMode (display, gc , subwindow_mode) 
Display * display; 
GC gc ; 
int subwindow_mode ; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

gc Specifies the graphics context. 

subwindow_mode 

Specifies the subwindow mode you want to set for the specified graphics con 
text. Possible values are ClipByChildren or Includelnf eriors. 

Description 

XSetSubwindowMode sets the subwindow_mode component of a GC. Clip 
ByChildren means that graphics requests will be clipped by all viewable children. 
Includelnf eriors means draw through all subwindows. 

For more information, see Volume One, Chapter 5, The Graphics Context. 
Errors 

BadGC 
BadValue 

Related Commands 

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, 
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground, 
XSetFunction, XSetGraphicsExposures, XSetLineAttributes, XSetPlane- 
Mask, XSetState, XSetStipple, XSetTSOrigin. 



Xlib Reference Manual 475 



XSetTeXtPrOperty \ x,,b -Window Managers- 

Name 

XSetTextProperty set one of a window s text properties. 
Synopsis 

void XSetTextProperty (display, w, text_prop, property) 
Display * display; 
Window w; 

XTextProperty *text_prop; 
Atom property; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window. 

text_prop Specifies the XTextProperty structure to be used. 

property Specifies the property name. 

Availability 

Release 4 and later. 

Description 

XSetTextProperty sets the specified property for the named window with the data, type, 
format, and number of items determined by the value field, the encoding field, the format 
field, and the nitems field, respectively, of the specified XTextProperty structure. 

Structures 

typedef struct { 

unsigned char *value; /* same as Property routines */ 

Atom encoding; /* prop type */ 

int format; /* prop data format: 8, 16, or 32 */ 

unsigned long nitems; /* number of data items in value */ 
} XTextProperty; 

Errors 

BadAlloc 
BadAtom 
BadValue 
BadWindow 

Related Commands 

XFreeStringList, XGetTextProperty, XStringListToTextProperty, XText- 
PropertytoStringList. 



476 Xlib Reference Manual 



-Xllb - Plxmaps and Tiles XSetTHe 

Name 

XSetTile set the fill tile in a graphics context. 

Synopsis 

XSetTile (display, gc , tile) 
Display * display; 
GC gc; 
Pixmap tile; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

gc Specifies the graphics context. 

tile Specifies the desired tile for the specified graphics context. 

Description 

XSetTile sets the tile member of the GC. This member of the GC determines the pixmap 
used to tile areas. The tile must have the same depth as the destination drawable. This tile will 
only be used in drawing if the fill-style is Fill riled. 

For more information, see Volume One, Chapter 5, The Graphics Context. 
Errors 

BadGC 

BadMatch 

BadPixmap 

Related Commands 

XCreateBitmapFromData, XCreatePixmap, XCreatePixmapFromBitmapData, 
XFreePixmap, XQueryBestSize, XQueryBestStipple, XQueryBestTile, 
XReadBitmapFile, XSetWindowBackgroundPixmap, XSetWindowBorder- 
Pixmap, XWriteBitmapFile. 



Xlib Reference Manual 477 



XSetTransientForHint V X,ib- Window Manager H,ms- 

Name 

XSetTransientForHint set the XA_WM_TRANSIENT_FOR property for a window. 

Synopsis 

XSetTransientForHint ( display, w, prop_window) 
Display * display; 
Window w; 
Window prop_window; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window ID, normally of a dialog box popup. 

prop_window Specifies the window ID that the XA_WM_TRANSIENT_FOR property is to be 
set to. This is usually the main window of the application. 

Description 

XSetTransientForHint sets the XA_WM_TRANSIENT_FOR property of the specified win 
dow. This should be done when the window w is a temporary child (for example, a dialog box) 
and the main top-level window of its application is prop_window. Some window managers 
may use this information to unmap an application s dialog boxes (for example, when the main 
application window gets iconified). 

For more information, see Volume One, Chapter 10, Inter -client Communication. 
Errors 

BadAlloc 
BadWindow 

Related Commands 

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal- 
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XGetZoom- 
Hints, XSetClassHint, XSetCommand, XSetlconName, XSetlconSizes, XSet- 
NormalHints, XSetSizeHints, XSetWMHints, XSetZoomHints, XStoreName. 



478 Xlib Reference Manual 



f XSetTSOrigin 

Xlib - Graphics Context 

Name 

XSetTSOrigin set the tile/stipple origin in a graphics context. 

Synopsis 

XSetTSOrigin ( display, gc, ts_x_origin f ts_y_origin) 
Display * display ; 
GC gc; 
int ts_x_origin, ts_y_origin; 

Arguments 

display Specifies a connection to an X server; returned from xopenoisplay. 

gc Specifies the graphics context. 

ts_x_origin Specify the x and y coordinates of the tile/stipple origin. 

ts_y_ origin 

Description 

XSetTSOrigin sets the ts_x_origin and ts_y_origin components in a GC, which 
are measured relative to the origin of the drawable specified in the drawing request that uses the 
GC. This controls the placement of the tile or the stipple pattern that patterns an area. To tile 
or stipple a child so that the pattern matches the parent, you need to subtract the current posi 
tion of the child window from ts_x_ origin and ts_y_origin. 

For more information, see Volume One, Chapter 5, The Graphics Context. 

Errors 

BadGC 

Related Commands 

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, 
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground, 
XSetFunction, XSetGraphicsExposures, XSetLineAttributes, XSetPlane- 
Mask, XSetState, XSetStipple, XSetSubwindowMode. 



Xlib Reference Manual 479 



XSetWMCIientMachine V xlib . wlndow M ,n ag er nu- 

Name 

XSetWMCIientMachine set a window s WM_CLIENT_MACHINE property. 

Synopsis 

void XSetWMCIientMachine (display, w, text_prop) 
Display *display; 
Window w; 
XText Property *text_prop; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window. 

text_jprop Specifies the XText Property structure to be used. 

Availability 

Release 4 and later. 

Description 

XSetWMCIientMachine performs an XSetTextProperty to set the 
WM_CLIENT_MACHINE property of the specified window. This property should contain the 
name of the host machine on which this client is being run, as seen from the server. 

For more information, see Volume One, Chapter 10, Interclient Communication. 
Structures 

typedef struct { 

unsigned char *value; /* same as Property routines */ 

Atom encoding; /* prop type */ 

int format; /* prop data format: 8, 16, or 32 */ 

unsigned long nitems; /* number of data items in value */ 
} XTextProperty; 

Related Commands 

XGetWMClientMachine. 



480 Xlib Reference Manual 



Xlib - Window Manager Hints - 



XSetWMColormapWindows 



Name 

XSetWMColormapWindows set a window s WM_COLORMAP_WINDOWS property. 

Synopsis 

Status XSetWMColormapWindows (display, w, colormap_windows , 

count) 

Display * display; 
Window w; 

Window *colormap_windows ; 
int count ; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

w Specifies the window. 

col ormap_windows 

Specifies the list of windows. 

count Specifies the number of windows in the list. 

Availability 

Release 4 and later. 

Description 

XSetWMColormapWindows sets the WM_cOLORMAP_wiNDOWS property on the specified win 
dow to the list of windows specified by the colormap_windows argument. The property is 
stored with a type of WINDOW and a format of 32. If it cannot intern the 
WM_COLORMAP_WINDOWS atom, XSetWMColormapWindows returns a zero status. Other 
wise, it returns a non-zero status. 

This property tells the window manager that subwindows of this application need to have their 
own colormaps installed. 

For more information, see Volume One, Chapter WJnterclient Communication. 

Errors 

BadAlloc 
BadWindow 

Related Commands 

XGetWMColormapWindows. 



Xlib Reference Manual 48 1 



XSetWMIconName V Xllb _ Wlndow Manager Hlnts _ 

Name 

XSetWMIconName set a window s XA_WM_ICON_NAME property. 

Synopsis 

void XSetWMIconName ( display f w, text_prop) 
Display ^display; 
Window w; 
XTextProperty *text_prop; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window. 

text_j>rop Specifies the XTextProperty structure to be used. 

Availability 

Release 4 and later. 

Description 

XSetWMIconName performs an XSetTextProperty to set the XA_WM_ICON_NAME prop 
erty of the specified window. XSetWMIconName supersedes XSetlconName. 

This is usually called by an application to set the property for the window manager. The name 
should be short, since it is to be displayed in association with an icon. 

XSetStandardProperties (in Release 4) or XSetWMProperties (in Release 4) also 
set this property. 

For more information, see Volume One, Chapter WJnterclient Communication. 
Structures 

typedef struct { 

unsigned char *value; /* same as Property routines */ 

Atom encoding; /* prop type */ 

int format; /* prop data format: 8, 16, or 32 */ 

unsigned long nitems; /* number of data items in value */ 
} XTextProperty; 

Related Commands 

XGetWMIconName, XGetWMName, XSetWMName, XSetWMProperties. 



482 Xlib Reference Manual 



-X,, b -Window Manag., H,n, / XSetWMName 

Name 

XSetWMName set a window s XA_WM_NAME property. 

Synopsis 

void XSetWMName ( display, w, text_prop) 
Display * display; 
Window w; 
XTextProperty *text_propj 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

w Specifies the window. 

text_prop Specifies the XTextProperty structure to be used. 

Availability 

Release 4 and later. 

Description 

XSetWMName performs a xsetTextProperty to set the XA_WM_NAME property on the 
specified window. XSetWMName supersedes XStoreName. This property can also be set 
with XSetWMProperties. 

XSetWMName be used by the application to communicate a string to the window manager. 
According to current conventions, this string should either: 

permit the user to identify one of a number of instances of the same client, or 
provide the user with noncritical state information. 
Clients can assume that at least the beginning of this string is visible to the user. 

The XA_WM_CLASS property, on the other hand, has two members which should be used to iden 
tify the application s instance and class name, for the lookup of resources. See XSetClass- 
Hint for details. 

For more information, see Volume One, Chapter 10, Interclient Communication. 



Structures 

typedef struct { 

unsigned char *value; 

Atom encoding; 

int format; 

unsigned long nitems; 
} XTextProperty; 



/* same as Property routines */ 

/* prop type */ 

/* prop data format: 8, 16, or 32 */ 

/* number of data items in value */ 



Related Commands 

XGetWMIconName, XGetWMName, XSetWMIconName, XSetWMProperties. 



Xlib Reference Manual 



483 



XSetWMNormalHints V Xllb _ Wlndow Manager Hlnts _ 

Name 

XSetWMNormalHints set a window s XA_WM_NORMAL_HINTS property. 

Synopsis 

void XSetWMNormalHints (display, w, hints) 
Display *display; 
Window w; 
XSizeHints *hints; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenD i spl ay . 

w Specifies the window. 

hints Specifies the size hints for the window in its normal state. 

Availability 

Release 4 and later. 

Description 

XSetWMNormalHints sets the size hints in the XA_WM_NORMAL_HINTS property on the 
specified window. The property is stored with a type of WM_SIZE_HINTS and a format of 32. 
XSetWMNormalHints supersedes XSetNormalHints. This property can also be set with 
XSetWMProperties. 

Applications use XSetNormalHints to inform the window manager of the sizes desirable 
for that window. 

To set size hints, an application must assign values to the appropriate elements in the hints 
structure, and also set the flags field of the structure to indicate which members have 
assigned values and the source of the assignment These flags are listed in the Structures sec 
tion below. 

For more information, see Volume One, Chapter 10, Interdient Communication. 
Structures 

typedef struct { 

long flags; /* marks which fields in this structure */ 

/* are defined */ 

int x, y; /* obsolete for new window mgrs, but clients */ 
int width, height; /* should set so old wm s don t mess up */ 
int min_width, min_height; 
int max_width, max_height; 
int width_inc, height_inc; 
struct { 

int x; /* numerator */ 

int y; /* denominator */ 
} min_aspect, max_aspect; 

int base_width, base_height; /* added by ICCCM version 1 */ 
int win_gravity; /* added by ICCCM version 1 */ 



484 Xlib Reference Manual 



Xlib - Window Manager Hints 



(continued) 



XSetWMNormalHints 



} XSizeHints; 

#define USPosition (1L 0) A 
tdefine USSize (1L 1) A 



user specified x, y */ 

user specified width, height */ 



tdefine PPosition (1L 2) /* program specified position 



tdefine PSize (1L 3) / 

tdefine PMinSize (1L 4) / 

tdefine PMaxSize (1L 5) / 

tdefine PResizelnc (1L 6) / 



program specified size V 
program specified minimum size */ 
program specified maximum size */ 
program specified resize increments 



tdefine PAspect (1L 7) /* program specified min/max aspect 
ratios */ 

tdefine PAllHints (PPosition I PSize I PMinSize I PMaxSize I PResizelnc I PAspect) 
tdefine PBaseSize (1L 8) /* program specified base 

for incrementing */ 

tdefine PWinGravity (1L 9)/* program specified window 

gravity */ 

Errors 

BadAlloc 
BadWindow 

Related Commands 

XGetWMNormalHints, XSetWMProperties, XSetWMSizeHints, XGetWMSize- 
Hints. 



Xlib Reference Manual 



485 



XSetWMProperties 



Xlib - Window Manager Hints- 



Name 

XSetWMProperties set a window s standard window manager properties. 

Synopsis 

void XSetWMProperties ( display, w, window_name , icon_name, argv f 

argc , normal_hints , wm_hints, class_hints) 
Display *display; 
Window w; 

XTextProperty *window_name ; 
XTextProperty *icon_name; 
char **argv; 
int argc; 

XSizeHints *normal_hints ; 
XWMHints *wm_hints; 
XClassHint *class_hints ; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window. 

window_name Specifies the window name, which should be a null-terminated string. 

i con_name Specifies the icon name, which should be a null-terminated string. 

argv Specifies the application s argument list. 

argc Specifies the number of arguments . 

normal_hints 

Specifies the size hints for the window in its normal state. 

wm_hints Specifies the XWMHints structure to be used. 
class_hints Specifies the XClassHint structure to be used. 

Availability 

Release 4 and later. 

Description 

XSetWMProperties provides a single programming interface for setting the essential win 
dow properties that communicate with window and session managers. XSetWMProperties 
supersedes XSetStandardProperties. 

If the window_name argument is non-null, XSetWMProperties calls XSetWMName, 
which, in turn, sets the WM_NAME property. If the icon_name argument is non-null, XSet 
WMProperties calls xsetWMiconName, which sets the WM_ICON_NAME property. If the 
argv argument is non-null, XSetWMProperties calls XSetCommand, which sets the 
WM_COMMAND property. Note that an argc of is allowed to indicate a zero-length command. 
XSetWMProperties stores the hostname of this machine using XSetWMClientMachine. 



486 Xlib Reference Manual 



Xlib - Window Manager Hints (continued) XSetWMPropertieS 

If the normal_hints argument is non-null, XSetWMProperties calls XSetWMNormal- 
Hints, which sets the WM_NORMAL_HINTS property. If the wm_hints argument is non-null, 
XSetWMProperties calls XSetWMHints, which sets the WM_HINTS property. 

If the class_hints argument is non-null, XSetWMProperties calls XSetClassHint, 
which sets the WM_CLASS property. If the res_name member in the XClassHint structure 
is set to the null pointer and the RESOURCE_NAME environment variable is set, then value of 
the environment variable is substituted for res_name. If the res_name member is NULL, 
and if the environment variable is not set, and if argvand argv[0] are set, then the value of 
a rgv[ 0], stripped of any directory prefixes, is substituted for res_name. 

For more information, see Volume One, Chapter WJnterclient Communication. 
Structures 

typedef struct { 

unsigned char *value; /* same as Property routines */ 

Atom encoding; /* prop type */ 

int format; /* prop data format: 8, 16, or 32 */ 

unsigned long nitems; /* number of data items in value */ 
} XTextProperty; 

typedef struct { 

long flags; /* marks which fields in this structure */ 
/* are defined */ 

int x, y; /* obsolete for new window mgrs, but clients */ 

int width, height; /* should set so old wm s don t mess up */ 

int min_width, min_height; 

int max_width, max_height; 

int width_inc, height_inc; 

struct { 

int x; /* numerator */ 
int y; /* denominator */ 

} min_aspect, max_aspect; 

int base_width, base_height; /* added by ICCCM version 1 */ 

int win_gravity; /* added by ICCCM version 1 */ 

} XSizeHints; 

typedef struct { 

long flags; /* marks which fields in this structure */ 

/* are defined */ 
Bool input; /* does this application rely on the window */ 

/* manager to get keyboard input? */ 
int initial_state; /* see below */ 

Pixmap icon_pixmap; /* pixmap to be used as icon */ 
Window icon_window; /* window to be used as icon */ 
int icon_x, icon_y; /* initial position of icon */ 
Pixmap icon_mask; /* icon mask bitmap */ 



Xlib Reference Manual 487 



XSetWMProperties (continued) Xlib - Window Manager Hints 

XID window_group; /* id of related window group */ 
/* this structure may be extended in the future */ 
} XWMHints; 

typedef struct { 

char *res_name; 

char *res_class; 
} XClassHint; 

Errors 

BadAlloc 
BadWindow 

Related Commands 

XGetClassHints, XGetCommand, XGetWMHints, XGetWMIconName, XGetWMName, 
XGetWMNormalHints, XSetWMClientMachine, XSetWMColormapWindows, XSet- 
WMProtocols. 



488 Xlib Reference Manual 



J XSetWMProtocols 

Xlib - Window Manager Hints 

Name 

XSetWMProtocols set a window s WM_PROTOCOLS property. 

Synopsis 

Status XSetWMProtocols (display, w, protocols, count) 
Display ^display; 
Window w; 
Atom ^protocols; 
int count; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenD i sp 1 ay . 

w Specifies the window. 

protocols Specifies the list of protocols. 

count Specifies the number of protocols in the list. 

Availability 

Release 4 and later. 

Description 

XSetWMProtocols sets the WM_PROTOCOLS property on the specified window to the list of 
atoms specified by the protocols argument. The property is stored with a type of ATOM and a 
format of 32. If it cannot intern the WM_PROTOCOLS atom, XSetWMProtocols returns a zero 
status. Otherwise, it returns a non-zero status. 

The list of standard protocols at present is as follows: 

WM_TAKE_FOCUS Assignment of keyboard focus 

WM_SAVE_YOURSELF Save client state warning 

WM_DELETE_UNKNOWN Request to delete top-level window 

For more information, see Volume One, Chapter 10, Interclient Communication. 

Errors 

BadAlloc 
BadWindow 

Related Commands 

XGetWMProtocols. 



Xlib Reference Manual 489 



XSetWMSizeHints V Xlib _ window Manager Hints - 

Name 

XSetWMSizeHints set a window s WM_SIZE_HINTS property. 

Synopsis 

void XSetWMSizeHints (display, w, hints, property) 
Display * display; 
Window w; 

XSizeHints *hints; 
Atom property; 

Arguments 

display Specifies a connection to an X server; returned from xopenDi splay. 

w Specifies the window. 

hints Specifies the XSizeHints structure to be used. 

property Specifies the property name. 

Availability 

Release 4 and later. 

Description 

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 nor 
mal size hints, you can use the XSetWMNormalHints function instead. XSetWMSize 
Hints supersedes XSetSizeHints. 

This routine is useful if new properties of type XA_WM_SIZE_HINTS are defined. 

The flags member of XSizeHints must be set to the OR of the symbols representing each 
member to be set 

For more information, see Volume One, Chapter WJnterclient Communication. 
Structures 

typedef struct { 

long flags; /* marks which fields in this structure are */ 

/* defined as */ 

int x, y; /* obsolete for new window mgrs, but clients */ 
int width, height; /* should set so old wm s don t mess up */ 
int min_width, min_height; 
int max_width, max_height; 
int width_inc, height_inc; 
struct { 

int x; /* numerator */ 

int y; /* denominator */ 
} min_aspect, max_aspect; 

int base_width, base_height; /* added by ICCCM version 1 */ 
int win_gravity; /* added by ICCCM version 1 */ 



490 xiib Reference Manual 



Xlib - Window Manager Hints 



(continued) 



XSetWMSizeHints 



} XSizeHints; 

#define USPosition (1L 0) 
#define USSize (1L 1) 



user specified x, y */ 

user specified width, height */ 



#define PPosition (1L 2) /* program specified position 

*/ 

tdefine PSize (1L 3) /* program specified size */ 

#define PMinSize (1L 4) /* program specified minimum size */ 

#define PMaxSize (1L 5) /* program specified maximum size */ 

#define PResizelnc (1L 6) /* program specified resize increments * 

#define PAspect (1L 7) /* program specified min/max aspect 
ratios */ 

#def ine PAllHints (PPosition | PSize I PMinSize I PMaxSize | PResizelnc I PAspect) 
tdefine PBaseSize (1L 8) /* program specified base 

for incrementing */ 
#define PWinGravity (1L 9)/* program specified window 

gravity */ 

Errors 

BadAlloc 

BadAtom 

BadWindow 

Related Commands 

XAllocSizeHints, XGetWMNormalHints, XGetWMSizeHints, XSetWMNormal- 
Hints. 



Xlib Reference Manual 



491 



XSetWindowBackground \ 



Xlib - Window Attributes- 



Name 

XSetWindowBackground set the background pixel value attribute of a window. 

Synopsis 

XSetWindowBackground ( display, w, background_pixel) 
Display * display; 
Window w; 
unsigned long background_pixel ; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window ID. Must be an inputOutput window. 

background_pixel 

Specifies which entry in the colormap is used as the background color. The 
constant CopyFromParent is NOT valid. 

Description 

XSetWindowBackground sets the background attribute of a window, setting the pixel 
value to be used to fill the background. This overrides any previous call to XSetWindow 
Background or XSetWindowBackgroundPixmap on the same window. 

XSetWindowBackground does not change the current window contents immediately. The 
background is automatically repainted after Expose events. You can also redraw the back 
ground without Expose events by calling XClearWindow immediately after. 

For more information, see Volume One, Chapter 4, Window Attributes. 

Errors 

BadMatch Setting background of Input Only window. 

BadWindow 

Related Commands 

XChangeWindowAttributes, XGet Geometry, XGetWindowAttributes, XSet 
WindowBackgroundPixmap, XSetWindowBorder, XSetWindowBorderPixmap. 



Xlib Reference Manual 



XSetWindowBackgroundPixmap 

Xlib - Pixmaps and Tiles 

Name 

XSetWindowBackgroundPixmap change the background tile attribute of a window. 

Synopsis 

XSetWindowBackgroundPixmap (display, w, background_tile) 
Display *display; 
Window w; 
Pixmap background_tile; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window ID. Must be an inputOutput class window. 

background_tile 

Specifies a pixmap ID, None or ParentRelative, to be used as a back 
ground. 

Description 

XSetWindowBackgroundPixmap sets the background_pixmap attribute of a window. 
This overrides any previous background_pixel or background_pixmap attribute set 
ting set with XSetWindowBackgroundPixmap, XSetWindowBackground, or 
XChangeWindowAttributes. Drawing into the pixmap that was set as the background 
pixmap attribute has an undefined effect on the window background. The server may or may 
not make a copy of the pixmap. 

If the background is set to a pixmap, the background is tiled with the pixmap. If the pixmap is 
not explicitly referenced again, it can be freed, since a copy is maintained in the server. The 
background of the window will not be redrawn with the new tile until the next Expose event 
or XClearWindow call. 

If the background is set to None, The window background initially will be invisible and will 
share the bits of its parent, but only if the background_pixel attribute is not set. When 
anything is drawn by any client into the area enclosed by the window, the contents will remain 
until the area is explicitly cleared with XClearWindow. The background is not automatically 
refreshed after exposure. 

If the background is set to ParentRelative, the parent s background is used, and the origin 
for tiling is the parent s origin (or the parent s parent if the parent s background_pixmap 
attribute is also ParentRelative, and so on). The difference between setting Parent- 
Relative and explicitly setting the same pixmap as the parent is the origin of the tiling. The 
difference between ParentRelative and None is that for ParentRelative the back 
ground is automatically repainted on exposure. 

For ParentRelative, the window must have the same depth as the parent, or a BadMatch 
error will occur. If the parent has background None, then the window will also have back 
ground None. The parent s background is re-examined each time the window background is 



Xlib Reference Manual 



XSetWindOwBackgroundPixmap (continued) Xlib - Pixmaps and Tiles 

required (when it needs to be redrawn due to mapping or exposure). The window s contents 
will be lost when the window is moved relative to its parent, and the contents will have to be 
redrawn. 

Changing the background_pixmap attribute of the root window to None or Parent- 
Relative restores the default. 

XSetWindOwBackgroundPixmap can only be performed on an Input Output window. 
A BadMatch error will result otherwise. 

XSetwindowBackground may be used if a solid color instead of a tile is desired. 
For more information, see Volume One, Chapter 4, Window Attributes. 

Errors 

BadMatch 

BadPixmap 

BadWindow 

Related Commands 

XCreateBitmapFromData, XCreatePixmap, XCreatePixmapFromBitmapData, 
XFreePixmap, XQueryBestSize, XQueryBestStipple, XQueryBestTile, 
XReadBitmapFile, XSetTile, XSetWindowBorderPixmap, XWriteBitmapFile. 



494 Xlib Reference Manual 



f XSetWindowBorder 

Xlib - Window Attributes 

Name 

XSetWindowBorder change a window border pixel value attribute and repaint the border. 

Synopsis 

XSetWindowBorder (display, w, border^pixel) 
Display * display ; 
Window v, 
unsigned long border_pixel ; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

w Specifies the window ID. Must be an inputOutput window. 

border_pixel 

Specifies the colormap entry with which the server will paint the border. 

Description 

XSetWindowBorder sets the border _jpixel attribute of window w to a pixel value, and 
repaints the border. The border is also automatically repainted after Expose events. 

Use XSetwindowBorderPixmap to create a tiled border. On top-level windows, the win 
dow manager often resets the border, so applications should not depend on their settings. 

For more information, see Volume One, Chapter 4, Window Attributes. 

Errors 

BadMatch Setting border of inputOnly window. 

BadWindow 

Related Commands 

XChangeWindowAttributes, XGetGeometry, XGetWindowAttributes, XSet- 
WindowBackground, XSetWindowBackgroundPixmap, XSetwindowBorder 
Pixmap. 



Xlib Reference Manual 495 



XSetWindowBorderPixmap 



Xlib - Pixmaps and Tiles- 



Name 

XSetWindowBorderPixmap change a window border tile attribute and repaint the border. 

Synopsis 

XSetWindowBorderPixmap (display, w, border_tile) 
Display * display ; 
Window w; 
Pixmap jborder_tile; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

w Specifies the ID of an inputOutput window whose border is to be to a file. 

border_tile Specifies any pixmap or None. 

Description 

XSetWindowBorderPixmap sets the border_pixmap attribute of a window and repaints 
the border. The border_tile can be freed immediately after the call if no further explicit 
references to it are to be made. 

This function can only be performed on an InputOutput window. On top-level windows, 
the window manager often resets the border, so applications should not depend on their set 
tings. 

Errors 

BadMatch 

BadPixmap 

BadWindow 

Related Commands 

XCreateBitmapFromData, XCreatePixmap, XCreatePixmapFromBitmapData, 
XFreePixmap, XQueryBestSize, XQueryBestStipple, XQueryBestTile, 
XReadBitmapFile, XSetTile, XSetWindowBackgroundPixmap, XWriteBitmap- 

File. 



496 xiib Reference Manual 



XSetWindowBorderWIdth 

Xlib - Window Manipulation- 

Name 

XSetWindowBorderWidth change the border width of a window. 

Synopsis 

XSetWindowBorderWidth (display, w, width) 
Display *display; 
Window w; 
unsigned int width; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the ID of the window whose border is to be changed. 

wi dth Specifies the width of the window border. 

Description 

XSetWindowBorderWidth changes the border width of a window. This request is often 
used on top-level windows by the window manager as an indication of the current keyboard 
focus window, so other clients should not depend on the border width of top-level windows. 

Errors 

BadMatch Setting border width of an Input Only window. 

BadWindow 

Related Commands 

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate- 
SubwindowsUp, XConf igureWindow, XLowerWindow, XMoveResizeWindow, 
XMoveWindow, XQueryTree, XRaiseWindow, XReparentWindow, XResize- 
Window, XRestackWindows. 



Xlib Reference Manual 497 



XSetWindowColormap 



Xlib - Window Attributes- 



Name 

XSetWindowColormap set the colormap attribute for a window. 

Synopsis 

XSetWindowColormap ( display, w r cmap) 
Display * display; 
Window w; 
Colormap cmap; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the ID of the window for which you want to set the colormap. 

cmap Specifies the colormap. 

Description 

XSetWindowColormap sets the colormap attribute of the specified window. The color- 
map need not be installed to be set as an attribute, cmap will be used to translate pixel values 
drawn into this window when cmap is installed in the hardware, which will be taken care of by 
the window manager. 

In Release 3, applications must install their own colormaps if they cannot use the default color- 
map. In Release 4, they should never do so. 

The colormap must have the same visual as the window. 

Errors 

BadColormap 

BadMatch 

BadWindow 

Related Commands 

XChangeWindowAttributes, XGetGeometry, XGetWindowAttributes, XSet- 
WindowBackground, XSetWindowBackgroundPixmap, XSetWindowBorder, 
XSetWindowBorderPixmap, XSetWMColormapWindows. 



Xlib Reference Manual 



-X I ,b-W,ndowMan. g erH,n,, / XSetWMHintS 

Name 

XSetWMHintS set a window manager hints property. 

Synopsis 

XSetWMHintS (display, w, wmhints) 
Display * display; 
Window w; 
XWMHints * wmhints; 

Arguments 

display Specifies a connection to an X server; returned from xopenDi splay. 

w Specifies the ID for which window manager hints are to be set. 

wmh ints Specifies a pointer to the window manager hints. 

Description 

XSetWMHintS sets the window manager hints that include icon information and location, the 
initial state of the window, and whether the application relies on the window manager to get 
keyboard input. 

This function is unnecessary in Release 4 if you call XSetWMProperties. 

See Volume One, Chapter 10, Interclient Communication, for a description of each XWMHints 
structure member. 

Structures 

typedef struct { 

long flags; /* marks defined fields in structure */ 

Bool input; /* does application need window manager for 

* keyboard input */ 

int initial_state; /* see below */ 

Pixmap icon_pixmap; /* pixmap to be used as icon */ 

Window icon_window; /* window to be used as icon */ 

int icon_x, icon_y; /* initial position of icon */ 

Pixmap icon_mask; /* icon mask bitmap */ 

XID window_group; /* ID of related window group */ 

/* this structure may be extended in the future */ 
} XWMHints; 

/* definitions for the flags field: */ 
#define InputHint (1L 0) 
#define StateHint (1L 1) 
#define IconPixmapHint (1L 2) 
fdefine IconWindowHint (1L 3) 
#define IconPositionHint (1L 4) 
tdefine IconMaskHint (1L 5) 
#define WindowGroupHint (1L 6) 

#define AllHints (InputHint | StateHint | IconPixmapHint | IconWindowHint | \ 
IconPositionHint I IconMaskHint I WindowGroupHint) 



Xlib Reference Manual 499 



XSetWMHints 



(continued) 



Xlib - Window Manager Hints 



/* definitions for the initial state flag: */ 



#define DontCareState 

#define NormalState 1 

#define ZoomState 2 

#define IconicState 3 

#define InactiveState 4 



/* don t know or care */ 

/* most applications want to start this way 
/* application wants to start zoomed */ 
/* application wants to start as an icon */ 
/* application believes it is seldom used; 
some wm s may put it on inactive menu */ 



Errors 

BadAlloc 
BadWindow 

Related Commands 

XAllocWMHints, XFetchName, XGetClassHint, XGetlconName, XGetlcon- 
Sizes, XGetNormalHints, XGetSizeHints, XGetTransientForHint, XGet- 
WMHints, XGetZoomHints, XSetClassHint, XSetCommand. XSetlconName, 
XSetlconSizes, XSetNormalHints, XSetSizeHints, XSetTransientForHint, 
XSetZoomHints, XStoreName, XSetWMProperties. 



500 



Xlib Reference Manual 



-Mb - Window Manager H,n,s XSetZOOITlHintS 

Name 

XSetZoomHints set the size hints property of a zoomed window. 

Synopsis 

XSetZoomHints ( display, w, zhints) 
Display * display; 
Window w; 
XSizeHints * zhints; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the ID of the window for which zoom hints are to be set. 

zhints Specifies a pointer to the zoom hints. 

Description 

XSetZoomHints is no longer used as of Release 3. 

XSetZoomHints sets the XA_WM_ZOOM_HINTS property for an application s top-level win 
dow in its zoomed state. Many window managers think of windows in three states: iconified, 
normal, or zoomed, corresponding to small, medium, and large. Applications use XSetZoom 
Hints to inform the window manager of the size or position desirable for the zoomed window. 

In addition, an application wanting to move or resize its zoomed window should call XSet 
ZoomHints specifying its new desired location and size, in addition to making direct X calls 
to move or resize. This is because some window managers may redirect window configuration 
requests, but ignore the resulting events and pay attention to property changes instead. 

To set size hints, an application must assign values to the appropriate elements in the hints 
structure, and set the flags field of the structure to indicate which members have assigned 
values and the source of the assignment. These flags are listed in the Structures section below. 

For more information on using hints, see Volume One, Chapter WJnterclient Communication. 
Structures 

typedef struct { 

long flags; /* marks defined fields in structure */ 

int x, y; 

int width, height; 

int min_width, min_height; 

int max_width, max_height; 

int width_inc, height_inc; 

struct { 

int x; /* numerator */ 

int y; /* denominator */ 

} min_aspect, max_aspect; 

/* new fields in R4 */ 
} XSizeHints; 



Xlib Reference Manual 501 



XSetZoom Hints (continued) Xlib - Window Manager Hints 

/* flags argument in size hints */ 

tdefine USPosition (IL 0) /* user specified x, y */ 

#define USSize (IL 1) /* user specified width, height */ 

#define PPosition (IL 2) /* program specified position */ 

#define PSize (IL 3) /* program specified size */ 

#define PMinSize (IL 4) /* program specified minimum size */ 

#define PMaxSize (IL 5) /* program specified maximum size */ 

#define PResizelnc (IL 6) /* program specified resize increments */ 

#define PAspect (IL 7) /* program specified min/max aspect ratios */ 
#define PAH Hints (PPosition | PSize | PMinSize | PMaxSize | PResizelnc | PAspect) 

Errors 

BadAlloc 
BadWindow 

Related Commands 

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal- 
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XGetZoom- 
Hints, XSetClassHint, XSetCoinmand, XSetlconName, XSetlconSizes, XSet- 
NormalHints, XSetSizeHints, XSetTransientForHint, XSetWMHints, 
XStoreName. 



Xlib Reference Manual 



f XShrinkRegion 

Xlib - Regions 

Name 

XShrinkRegion reduce or expand the size of a region. 

Synopsis 

XShrinkRegion ( r, dx, dy) 
Region r; 
int dx, dy; 

Arguments 

r Specifies the region. 

dx Specify the amounts by which you want to shrink or expand the specified 

dy region. Positive values shrink the region while negative values expand the 

region. 

Description 

XShrinkRegion changes the width and/or height of the specified region. Positive values 
shrink the region; negative values expand the region. It is legal to expand the region in one 
dimension at the same time as shrinking it in the other dimension. The offset of the region is 
changed to keep the center of the resized region near its original position. 

The exact amount of shrinkage for a given value for dx or dy is not specified by Xlib. 

Structures 

Region is a pointer to an opaque structure type. 

Related Commands 

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion, 
XIntersectRegion, XOf f setRegion, XPointlnRegion, XPolygonRegion, 
XRectlnRegion, XSetRegion, XSubtractRegion, XUnionRectWithRegion, 
XUnionRegion, XXorRegion. 



Xlib Reference Manual 503 



XStoreBuffer \ V1 

v Xlib - Cut Buffers 

Name 

XStoreBuffer store data in a cut buffer. 

Synopsis 

XStoreBuffer ( display, bytes, nbytes , buffer) 
Display * display ; 
char bytes [ ] ; 
int nbytes; 
int buffer; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

bytes Specifies the string of bytes you want stored. The byte string is not necessarily 

ASCII or null-terminated. 

nbytes Specifies the number of bytes in the string. 

buffer Specifies the cut buffer in which to store the byte string. Must be in the range 
0-7. 

Description 

XStoreBuffer stores the specified data into any one of the eight cut buffers. All eight buf 
fers must be stored into before they can be circulated with XRotateBuf f ers. The cut buf 
fers are numbered through 7. Use XFetchBuf f er to recover data from any cut buffer. 

Note that selections are the preferred method of transferring data between applications. 

For more information on cut buffers, see Volume One, Chapter 13, Other Programming Tech 
niques. For more information on selections, see Volume One, Chapter 10, Inter client Commu 
nication. 

Errors 

BadAlloc 
BadAtom 

Related Commands 

XFetchBuf fer, XFetchBytes, XRotateBuf f ers, XStoreBytes. 



504 Xlib Reference Manual 



f~ XStoreBytes 

Xlib - Cut Buffers 

Name 

XStoreBytes store data in cut buffer 0. 

Synopsis 

XStoreBytes (display, bytes, nbytes) 
Display * display; 
char bytes[] ; 
int nbytes; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

bytes Specifies the string of bytes to store. The byte string is not necessarily ASCII or 

null-terminated. 

nbytes Specifies the number of bytes to store. 

Description 

XStoreBytes stores data in cut buffer 0, usually for reading by another client that already 
knows the meaning of the contents. Note that the cut buffer s contents need not be text, so null 
bytes are not special. 

The cut buffer s contents may be retrieved later by any client calling XFetchBytes. 

Use XStoreBuf fer to store data in buffers 1-7. Note that selections are the preferred 
method of transferring data between applications. 

For more information on cut buffers, see Volume One, Chapter 13, Other Programming Tech 
niques. For more information on selections, see Volume One, Chapter 10, Inter client Commu 
nication. 

Errors 

BadAlloc 

Related Commands 

XFetchBuf f er, XFetchBytes, XRotateBuf f ers, XStoreBuf fer. 



Xlib Reference Manual 505 



XStoreColor X X|lb _ ^ Ce||s _ 

Name 

XStoreColor set or change the RGB values of a read/write colormap entry to the closest pos 
sible hardware color. 

Synopsis 

XStoreColor ( display, cmap, colorcell_def) 
Display *display; 
Colormap cmap; 
XColor *colorcell_def; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

cmap Specifies the colormap. 

col orcell_def Specifies a pixel value and the desired RGB values. 

Description 

XStoreColor changes the RGB values of a colormap entry specified by 
col orcell_def. pixel to the closest values possible on the hardware. This pixel value 
must be a read/write cell and a valid index into cmap. XStoreColor changes the red, green, 
and/or blue color components in the cell according to the colorcell_def .flags member, 
which you set by ORing the constants DoRed, DoGreen, and/or DoBlue. 

If the colormap is an installed map for its screen, the changes are visible immediately. 
For more information, see Volume One, Chapter 7, Color. 

Structures 

typedef struct { 

unsigned long pixel; 

unsigned short red, green, blue; 

char flags; /* DoRed, DoGreen, DoBlue */ 

char pad; 
} XColor; 

Errors 

BadAccess A specified pixel is unallocated or read-only. 

BadColormap 

BadValue pixel not valid index into cmap. 

Related Commands 

BlackPixel, WhitePixel, XAllocColor, XAllocColorCells, XAllocColor- 
Planes, XAllocNamedColor, XFreeColors, XLookupColor, XParseColor, 
XQueryColor, XQueryColors, XStoreColors, XStoreNamedColor. 



506 Xlib Reference Manual 



Xlib -Color Cells- 



J XStoreColors 



Name 

XStoreColors set or change the RGB values of read/write colorcells to the closest possible 
hardware colors. 

Synopsis 

XStoreColors ( display, cmap , colorcell_defs , ncolors) 
Display * display; 
Colormap cmap; 

XColor colorcell_defs [ncolors] ; 
int ncolors; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

cmap Specifies the colormap. 

colorcell_defs 

Specifies an array of color definition structures. 

ncolors Specifies the number of XColor structures in colorcell_defs. 

Description 

XStoreColors changes the RGB values of each colormap entry specified by color- 
cell_defs [] .pixel to the closest possible hardware colors. Each pixel value must be a 
read/write cell and a valid index into cmap. XStoreColors changes the red, green, and/or 
blue color components in each cell according to the colorcell_def s [ ] .flags member, 
which you set by ORing the constants DoRed, DoGreen, and/or DoBlue. The specified pix 
els are changed if they are writable by any client, even if one or more pixels generates an error. 

If the colormap is an installed map for its screen, the changes are visible immediately. For 
more information, see Volume One, Chapter 7, Color. 

Structures 

typedef struct { 

unsigned long pixel; 

unsigned short red, green, blue; 

char flags; /* DoRed, DoGreen, DoBlue */ 

char pad; 
} XColor; 

Errors 

BadAcce s s A specified pixel is unallocated or read-only. 

BadColormap 

BadValue A specified pixel is not a valid entry into cmap. 

Related Commands 

BlackPixel, WhitePixel, XAllocColor, XAllocColorCells, XAllocColor- 
Planes, XAllocNamedColor, XFreeColors, XLookupColor, XParseColor, 
XQueryColor, XQueryColors, XStoreColor, XStoreNamedColor. 



Xlib Reference Manual 507 



XStoreName V Xlib _ Window Manager Hlnts _ 

Name 

XStoreName assign a name to a window for the window manager. 

Synopsis 

XStoreName ( display , w r window_name) 
Display * display; 
Window w; 
char *window_name ; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the ID of the window to which you want to assign a name. 

window_name Specifies the name of the window. The name should be a null-terminated 
string. This name is returned by any subsequent call to XFetchName. 

Description 

XStoreName is superceded in Release 4 by XSetWMName. 

XStoreName sets the XA_WM_NAME property, which should be used by the application to com 
municate the following information to the window manager, according to current conventions: 

To permit the user to identify one of a number of instances of the same client. 
To provide the user with noncritical state information. 
Clients can assume that at least the beginning of this string is visible to the user. 

The XA_WM_CLASS property, on the other hand, has two members which should be used to iden 
tify the application s instance and class name, for the lookup of resources. See XSetClass- 
Hint for details. 

For more information, see Volume One, Chapter 10, Inter -client Communication. 

Errors 

BadAlloc 
BadWindow 

Related Commands 

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal- 
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XGetZoom- 
Hints, XSetClassHint, XSetCommand, XSetlconName, XSetlconSizes, XSet- 
NormalHints, XSetSizeHints, XSetTransientForHint, XSetWMHints, XSet- 
ZoomHints. 



Xlib Reference Manual 



-x, ib - wmdow Manager H.ms XStoreNamedColor 

Name 

XStoreNamedColor set RGB values of a read/write colorcell by color name. 

Synopsis 

XStoreNamedColor (display, cmap, colorname, pixel, flags) 
Display *display, 
Co lo rmap cmap ; 
char * colorname; 
unsigned long pixel; 
int flags; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

cmap Specifies the colormap. 

colorname Specifies the color name string (for example, "red"). This cannot be in hex for 
mat (as used in XParseColor). Upper or lower case is not important. The 
string should be in ISO LATIN- 1 encoding, which means that the first 128 char 
acter codes are ASCII, and the second 128 character codes are for special char 
acters needed in western languages other than English. 

pixel Specifies the entry in the colormap to store color in. 

flags Specifies which red, green, and blue indexes are set. 

Description 

XStoreNamedColor looks up the named color in the database, with respect to the screen 
associated with cmap, then stores the result in the read/write colorcell of cmap specified by 
pixel. Upper or lower case in name does not matter. The flags argument, a bitwise OR of 
the constants DoRed, DoGreen, and DoBlue, determines which subfields within the pixel 
value in the cell are written. 

For more information, see Volume One, Chapter 7, Color. 

Errors 

BadAccess pixel is unallocated or read-only. 

BadColormap 

BadName col orname is not in server s color database. 

BadValue pixel is not a valid index into cmap. 

Related Commands 

Def aultColormap, DisplayCells, XCopyColormapAndFree, XCreate- 
Colormap, XFreeColormap, XGetStandardColormap, XInstallColormap, 
XListInstalledColormaps,XSetStandardColormap, XSetWindowColormap, 
XUninstallColormap. 



Xlib Reference Manual 509 



XStringListToTextProperty \ XMb . wlndowManager Hints _ 

Name 

XStringListToTextProperty set the specified list of strings to an XTextProperty struc 
ture. 

Synopsis 

Status XStringListToTextProperty (list, count, text^prop) 
char **list; 
int count ; 
XTextProperty *text_prop; /* RETURN */ 

Arguments 

list Specifies a list of null-terminated character strings. 

count Specifies the number of strings. 

text_jDrop Returns the XTextProperty structure. 

Availability 

Release 4 and later. 

Description 

XStringListToTextProperty fills the specified XTextProperty structure so that it 
represents a property of type STRING (format 8) with a value representing the concatenation of 
the specified list of null-separated character strings. An extra byte containing NULL (which is 
not included in the nit ems member) is stored at the end of the value field of text_prop. 
If insufficient memory is available for the new value string, XStringListToText 
Property does not set any fields in the XTextProperty structure and returns a zero status. 
Otherwise, it returns a non-zero status. To free the storage for the value field, use XFree. 

For more information, see Volume One, Chapter IQJnterclient Communication. 
Structures 

typedef struct { 

unsigned char *value; /* same as Property routines */ 

Atom encoding; /* prop type */ 

int format; /* prop data format: 8, 16, or 32 */ 

unsigned long nitems; /* number of data items in value */ 
} XTextProperty; 

Related Commands 

XSetTextProperty, XGetTextProperty, XTextPropertyToStringList, 
XFreeStringList. 



510 xiib Reference Manual 



-* - Keyboard / XStringToKeysym 

Name 

XStringToKeysym convert a keysym name string to a keysym. 

Synopsis 

KeySym XStringToKeysym ( string) 
char *string; 

Arguments 

string Specifies the name of the keysym that is to be converted. 

Description 

XStringToKeysym translates the character string version of a keysym name ("Shift") to the 
matching keysym which is a constant (XK_Shift). Valid keysym names are listed in 
<Xll/keysymdef.h>. If the specified string does not match a valid keysym, XString 
ToKeysym returns NoSymbol. 

This string is not the string returned in the buffer argument of XLookupSt r ing, which can 
be set with XRebindKeysym. If that string is used, XStringToKeysym will return No- 
Symbol except by coincidence. 

In Release 4, XStringToKeysym can return keysyms that are not defined by the Xlib stan 
dard. Note that the set of keysyms that are available in this manner and the mechanisms by 
which Xlib obtains them is implementation dependent. (In the MIT sample implementation, 
the resource file lusrlliblXHIXKeysymDB is used starting in Release 4. The keysym name is 
used as the resource name, and the resource value is the keysym value in uppercase hexade 
cimal.) 

For more information, see Volume One, Chapter 9, The Keyboard and Pointer. 
Related Commands 

XChangeKeyboardMapping, XDeleteModif iermapEntry, XFreeModif iermap, 
XGetKeyboardMapping, XGetModif ierMapping, XInsertModif iermapEntry, 
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym, 
XLookupString, XNewModif ierMap, XQueryKeymap, XRebindKeysym, 
XRefreshKeyboardMapping, XSetModif ierMapping. 



Xlib Reference Manual 51 1 



XSublmage \ X(|b _ lmages _ 

Name 

XSublmage create a subimage from part of an image. 

Synopsis 

Xlmage *XSub Image (ximage, x, y, subimage_width, subimage_height) 
Xlmage * ximage; 
int x;y; 
unsigned int subimage_width ; subimage_height ; 

Arguments 

ximage Specifies a pointer to the image. 

x Specify the x and y coordinates in the existing image where the subimage will be 

y extracted. 

s ubima ge_wi dt h 
subimage_height 

Specify the width and height (in pixels) of the new subimage. 

Description 

XSublmage creates a new image that is a subsection of an existing one. It allocates the mem 
ory necessary for the new Xlmage structure and returns a pointer to the new image. The data 
is copied from the source image, and the rectangle defined by x, y, subimage_width, and 
subimage_height must by contained in the image. 

XSublmage extracts a subimage from an image, while XGet Sub Image extracts an image 
from a drawable. 

For more information on images, see Volume One, Chapter 6, Drawing Graphics and Text. 
Related Commands 

ImageByteOrder, XAddPixel, XCreatelmage, XDestroy Image, XGetlmage, 
XGetPixel, XGet Sub Image, XPut Image, XPutPixel. 



512 Xlib Reference Manual 



J XSubtractRegion 

Xlib - Regions 

Name 

XSubtractRegion subtract one region from another. 

Synopsis 

XSubtractRegion (sra, srb, dr) 
Region sra, srb; 
Region dr; /* RETURN */ 

Arguments 

sra Specify the two regions in which you want to perform the computation. 

srb 

dr Returns the result of the computation. 

Description 

XSubtractRegion calculates the difference between the two regions specified (sra - srb) 
and puts the result in dr. 

This function returns a region which contains all parts of sra that are not also in srb. 
For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text. 

Structures 

Region is a pointer to an opaque structure type. 

Related Commands 

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion, 
XIntersectRegion, XOf f setRegion, XPointlnRegion, XPolygonRegion, 
XRectlnRegion, XSetRegion, XShrinkRegion, XUnionRectWithRegion, 
XUnionRegion, XXorRegion. 



Xlib Reference Manual 513 



XSync 



Xlib- Output Buffer- 



Name 

XSync flush the request buffer and wait for all events and errors to be processed by the 
server. 

Synopsis 

XSync (display, discard) 
Display * display; 
int discard; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

discard Specifies whether XSync discards all events on the input queue. This argu 

ment is either True or False. 

Description 

XSync flushes the request buffer, then waits until all events and errors resulting from previous 
calls have been received and processed by the X server. Events are placed on the input queue. 
The client s XError routine is called once for each error received. 

If discard is True, XSync discards all events on the input queue (including those events that 
were on the queue before XSync was called). 

XSync is sometimes used with window manipulation functions (by the window manager) to 
wait for all resulting exposure events. Very few clients need to use this function. 

Related Commands 

XFlush. 



514 Xlib Reference Manual 



J XSynchronize 

Xlib - Input Handling 

Name 

XSynchronize enable or disable synchronization for debugging. 

Synopsis 

int (*XSynchronize ( display, onoff)) () 
Display * display ; 
Bool onoff; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

onoff Specifies whether to enable or disable synchronization. You can pass False 

(normal asynchronous mode) or True (enable synchronization for debug 
ging). 

Description 

XSynchronize turns on or off synchronous mode for debugging. If onoff is True, it turns 
on synchronous behavior; False resets the state to normal mode. 

When events are synchronized, they are reported as they occur instead of at some later time, but 
server performance is many times slower. This can be useful for debugging complex event 
handling routines. Under UNIX, the same result can be achieved without hardcoding by setting 
the global variable _xdebug to True from within a debugger. 

XSynchronize returns the previous after function. 

For more information, see Volume One, Chapter 3, Basic Window Program. 

Related Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued, 
XGetlnputFocus, XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent, 
XPeekEvent, XPeeklf Event, XPending, XPutBackEvent, XSelectlnput, 
XSendEvent, XSetlnputFocus, XWindowEvent. 



Xlib Reference Manual 515 



XTextExtents \ Xlib _ Text _ 

Name 

XTextExtents get string and font metrics locally. 

Synopsis 

XTextExtents (font_struct , string, nchars , direction, 

ascent, descent, overall) 
XFontStruct *font_struct ; 
char *string; 
int nchars; 

int * direction; /* RETURN */ 

int * ascent, *descent; /* RETURN */ 

XCharStruct * overall; /* RETURN */ 

Arguments 

f ont_struct Specifies a connection to an XFontStruct structure. 

string Specifies the character string for which metrics are to be returned. 

nchars Specifies the number of characters in the character string. 

direction Returns the value of the direction element of the XFontStruct. Either 
Font Right ToLef t or FontLef tToRight. 

ascent Returns the font ascent element of the XFontStruct. This is the overall 

maximum ascent for the font 

descent Returns the font descent element of the XFontStruct. This is the overall 

maximum descent for the font 

overall Returns the overall characteristics of the string. These are the sum of the 

width measurements for each character, the maximum ascent and 
descent, the minimum Ibearing added to the width of all characters up 
to the character with the smallest Ibearing, and the maximum rbearing 
added to the width of all characters up to the character with the largest 
rbearing. 

Description 

XTextExtents returns the dimensions in pixels that specify the bounding box of the speci 
fied string of characters in the named font, and the maximum ascent and descent for the entire 
font This function performs the size computation locally and, thereby, avoids the roundtrip 
overhead of XQueryTextExtents, but it requires a filled XFontStruct. 

ascent and descent return information about the font, while overall returns information 
about the given string. The returned ascent and descent should usually be used to calcu 
late the line spacing, while the width, rbearing, and Ibearing members of overall 
should be used for horizontal measures. The total height of the bounding rectangle, good for 
any string in this font, is ascent + descent. 

overall . ascent is the maximum of the ascent metrics of all characters in the string. The 
overall . descent is the maximum of the descent metrics. The overall . width is the 
sum of the character-width metrics of all characters in the string. The overall . Ibearing 



516 Xlib Reference Manual 



Xlib - Text 



(continued) 



XTextExtents 



is the Ibearing of the character in the string with the smallest Ibearing plus the width of 
all the characters up to but not including that character. The overall . rbearing is the 
rbearing of the character in the string with the largest rbearing plus the width of all the 
characters up to but not including that character. 

For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and 
Text. 



Structures 

typedef struct { 

XExtData *ext_data; /* 

Font fid; /* 

unsigned direction; /* 
unsigned min_char_or_byte2; /* 
unsigned max_char_or_byte2; /* 

unsigned min bytel; /* 

unsigned max_bytel; /* 

Bool all_chars_exist; /* 

unsigned default char; /* 

int n_properties; /* 

XFontProp *properties; /* 

XCharStruct min bounds; /* 

XCharStruct max_bounds; /* 

XCharStruct *per_char; /* 

int ascent; /* 

int descent; /* 

} XFontStruct; 



hook, for extension to hang data */ 

font ID for this font */ 

hint about direction the font is painted */ 

first character */ 

last character */ 

first row that exists */ 

last row that exists */ 

flag if all characters have nonzero size*/ 

char to print for undefined character */ 

how many properties there are */ 

pointer to array of additional properties*/ 

minimum bounds over all existing char*/ 

minimum bounds over all existing char*/ 

first_char to last_char information */ 

logical extent above baseline for spacing */ 

logical descent below baseline for spacing */ 



typedef struct { 

short Ibearing; 

short rbearing; 

short width; 

short ascent; 

short descent; 

unsigned short attributes; 
} XCharStruct; 



/* origin to left edge of character */ 

/* origin to right edge of character */ 

/* advance to next char s origin */ 

/* baseline to top edge of character */ 

/* baseline to bottom edge of character 

/* per char flags (not predefined) */ 



*/ 



Related Commands 

XDrawImageString, XDrawImageStringl6,XDrawString, XDrawStringlG, 
XDrawText, XDrawTextl6, XQueryTextExtents, XQueryTextExtentsl6, 
XTextExtent si 6, XTextWidth, XTextWidthl 6. 



Xlib Reference Manual 



517 



XTextExtentsI 6 \ Xllb _ Text _ 

Name 

XTextExtentsl6 get string and font metrics of a 16-bit character string, locally. 

Synopsis 

XTextExtentsI 6 (font_struct , string, nchars, direction, 

ascent, descent, overall) 
XFontStruct *font_struct ; 
XChar2b *string; 
int nchars; 

int * direction; /* RETURN */ 

int * ascent, * descent; /* RETURN */ 

XCharStruct * overall; /* RETURN */ 

Arguments 

font_struct Specifies a connection to an XFontStruct structure. 

string Specifies the character string made up of XChar2 6 structures. 

nchars Specifies the number of characters in the character string. 

direction Returns the value of the direction element of the XFontStruct. Font- 
RightToLeft of FontLeftToRight. 

ascent Returns the font ascent element of the XFontStruct. This is the overall 

maximum ascent for the font. 

descent Returns the font descent element of the XFontStruct. This is the overall 

maximum descent for the font. 

overall Returns the overall characteristics of the string. These are the sum of the 

width measurements for each character, the maximum ascent and 
descent, the minimum Ibearing added to the width of all characters up 
to the character with the smallest Ibearing, and the maximum rbearing 
added to the width of all characters up to the character with the largest 
rbearing. 

Description 

XTextExtentsI 6 returns the dimensions in pixels that specify the bounding box of the 
specified string of characters in the named font, and the maximum ascent and descent for the 
entire font. This function performs the size computation locally and, thereby, avoids the 
roundtrip overhead of XQueryTextExtentsl 6, but it requires a filled XFontStruct. 

ascent and descent return information about the font, while overall returns information 
about the given string. The returned ascent and descent should usually be used to calcu 
late the line spacing, while the width, rbearing, and Ibearing members of overall 
should be used for horizontal measures. The total height of the bounding rectangle, good for 
any string in this font, is ascent + descent. 

overall . ascent is the maximum of the ascent metrics of all characters in the string. The 
overall . descent is the maximum of the descent metrics. The overall . width is the 
sum of the character-width metrics of all characters in the string. The overall . Ibearing 



518 xiib Reference Manual 



Xlib-Text 



(continued) 



XTextExtents16 



is the Ibearing of the character in the string with the smallest Ibearing plus the width of 
all the characters up to but not including that character. The overall . rbearing is the 
rbearing of the character in the string with the largest rbearing plus the width of all the 
characters up to but not including that character. 

For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and 
Text. 



Structures 

typedef struct { 

short Ibearing; 

short rbearing; 

short width; 

short ascent; 

short descent; 

unsigned short attributes; 
} XCharStruct; 

typedef struct { 

XExtData *ext_data; 

Font fid; 

unsigned direction; 

unsigned min_char_or_byte2; 

unsigned max_char_or_byte2; 

unsigned min_bytel; 

unsigned max_bytel; 

Bool all_chars_exist; 

unsigned default char; 

int n_properties; 

XFontProp *properties; 

XCharStruct min_bounds; 

XCharStruct max_bounds; 

XCharStruct *per_char; 

int ascent; 

int descent; 
} XFontStruct; 

typedef struct { 

unsigned char bytel; 
unsigned char byte2; 

} XChar2b; 



/* origin to left edge of character */ 

/* origin to right edge of character */ 

/* advance to next char s origin */ 

/* baseline to top edge of character */ 

/* baseline to bottom edge of character 

/* per char flags (not predefined) */ 



/* hook for extension to hang data */ 

/* font ID for this font */ 

/* hint about direction the font is painted */ 

/* first character */ 

/* last character */ 

/* first row that exists */ 

/* last row that exists */ 

/* flag if all characters have nonzero size*/ 

/* char to print for undefined character */ 

/* how many properties there are */ 

/* pointer to array of additional properties*/ 

/* minimum bounds over all existing char*/ 

/* minimum bounds over all existing char*/ 

/* first_char to last_char information */ 

/* logical extent above baseline for spacing */ 

/* logical descent below baseline for spacing */ 



/* normal 16 bit characters are two bytes */ 



Related Commands 

XDrawImageString, XDrawImageStringl6,XDrawString, XDrawStringlS, 
XDrawText, XDrawText 1 6, XQueryTextExtent s, XQueryTextExtent si 6, 
XTextExtents, XTextWidth, XTextWidthl6. 



Xlib Reference Manual 



519 



XTextPropertyToStringList \ X|ib . Wlndow Manager Hints _ 

Name 

XTextPropertyToStringList obtain a list of strings from a specified XText Property struc 
ture. 

Synopsis 

Status XTextPropertyToStringList (text_prop f list, count) 
XTextProperty *text_prop; 
char ***list; /* RETURN */ 
int * count; /* RETURN */ 

Arguments 

text_prop Specifies the XTextProperty structure to be used. 

list Returns a list of null-terminated character strings. 

count Returns the number of strings. 

Availability 

Release 4 and later. 

Description 

XTextPropertyToStringList returns a list of strings representing the null-separated 
elements of the specified XTextProperty structure. The data in text_prop must be of 
type STRING and format 8. Multiple elements of the property (for example, the strings in a dis 
joint text selection) are separated by a NULL (encoding 0). The contents of the property are not 
null-terminated. If insufficient memory is available for the list and its elements, XText 
PropertyToStringList sets no return values and returns a zero status. Otherwise, it 
returns a non-zero status. To free the storage for the list and its contents, use XFreeSt ring- 
List. 

For more information, see Volume One, Chapter 10, Inter -client Communication. 
Structures 

typedef struct { 

unsigned char *value; /* same as Property routines */ 

Atom encoding; /* prop type */ 

int format; /* prop data format: 8, 16, or 32 */ 

unsigned long nitems; /* number of data items in value */ 
} XTextProperty; 

Related Commands 

XFreeStringList. XGetTextProperty, XSetTextProperty, XStringListTo- 
TextProperty. 



Xlib Reference Manual 



f XTextWidth 

Xlib - Text 

Name 

XTextWidth get the width in pixels of an 8-bit character string, locally. 

Synopsis 

int XTextWidth (font_struct , string, count) 
XFontStruct *font_struct; 
char *string; 
int count; 

Arguments 

font_struct Specifies the font description structure of the font in which you want to draw 
the string. 

string Specifies the character string whose width is to be returned. 

count Specifies the character count in s t r i n g. 

Description 

XTextWidth returns the width in pixels of the specified string using the specified font This 
is the sum of the XCharSt ruct . width for each character in the string. This is also equiva 
lent to the value of overall, width returned by XQueryTextExtents or XText- 
Extents. The calculation is done assuming 8-bit font indexing. 

For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and 
Text. 

Structures 

typedef struct { 

XExtData *ext_data; /* hook for extension to hang data */ 

Font fid; /* font ID for this font */ 

unsigned direction; /* hint about direction the font is painted */ 

unsigned min_char_or_byte2; /* first character */ 

unsigned max_char_or_byte2; /* last character */ 

unsigned min_bytel; /* first row that exists */ 

unsigned max_bytel; /* last row that exists */ 

Bool all_chars_exist; /* flag if all characters have nonzero size*/ 

unsigned default_char; /* char to print for undefined character */ 

int n_properties; /* how many properties there are */ 

XFontProp ^properties; /* pointer to array of additional properties*/ 

XCharStruct min_bounds; /* minimum bounds over all existing char*/ 

XCharStruct max_bounds; /* minimum bounds over all existing char*/ 

XCharStruct *per_char; /* first_char to last_char information */ 

int ascent; /* logical extent above baseline for spacing */ 

int descent; /* logical descent below baseline for spacing */ 

} XFontStruct; 

Related Commands 

XDrawImageString, XDrawImageStringl6,XDrawString, XDrawStringlS, 
XDrawText, XDrawTextl6, XQueryTextExtents, XQueryTextExtentsl 6, 
XTextExtents,XTextExtentsl6,XTextWidthl6. 

Xlib Reference Manual 521 



XTextWidth16 \ XHb . Text _ 

Name 

XTextWidthl6 get the width in pixels of a 16-bit character string, locally. 

Synopsis 

int XTextWidthl6 (font_struct , string, count) 
XFontStruct *font_struct ; 
XChar2b *string; 
int count; 

Arguments 

font_struct Specifies the font description structure of the font in which you want to draw 
the string. 

string Specifies a character string made up of XChar2b structures, 

count Specifies the character count in s t ri n g. 

Description 

XTextwidthl6 returns the width in pixels of the specified string using the specified font. 
This is the sum of the XCharStruct .width for each character in the string. This is also 
equivalent to the value of overall . width returned by XQueryTextExtentsl6 or 
XTextExtentsl6. 

The calculation is done assuming 16-bit font indexing. 

For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and 
Text. 

Structures 

typedef struct { 

XExtData *ext_data; /* hook for extension to hang data */ 

Font fid; /* font ID for this font */ 

unsigned direction; /* hint about direction the font is painted */ 

unsigned min_char_or_byte2; /* first character */ 

unsigned max_char_or_byte2; /* last character */ 

unsigned min_bytel; /* first row that exists */ 

unsigned max_bytel; /* last row that exists */ 

Bool all_chars_exist; /* flag if all characters have nonzero size*/ 

unsigned default_char; /* char to print for undefined character */ 

int n_properties; /* how many properties there are */ 

XFontProp *properties; /* pointer to array of additional properties*/ 

XCharStruct min_bounds; /* minimum bounds over all existing char*/ 

XCharStruct max_bounds; /* minimum bounds over all existing char*/ 

XCharStruct *per_char; /* first_char to last_char information */ 

int ascent; /* logical extent above baseline for spacing */ 

int descent; /* logical descent below baseline for spacing */ 

} XFontStruct; 

Related Commands 

XDrawImageString, XDrawImageStringl6,XDrawString, XDrawStringlS, 

XDrawText,XDrawTextl6,XQueryTextExtents,XQueryTextExtentsl6, 

XTextExtents,XTextExtentsl6,XTextWidth. 



522 xiib Reference Manual 



j XTranslateCoordinates 

Xlib - Standard Geometry 

Name 

XTranslateCoordinates change the coordinate system from one window to another. 

Synopsis 

Bool XTranslateCoordinates (display, src_w, frame_w, src_x f 

src_y, new_x, new_y, child) 
Display * display; 
Window src_w r frame_w; 
int src_x f src_y; 

int *new_x, *nevr_y; /* RETURN */ 

Window * chi Id; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from xopenDisplay. 

src_w Specifies the ID of the source window. 

frame_w Specifies the ID of the frame of reference window. 

src_x Specify the x and y coordinates within the source window. 

src_y 

new_x Return the translated x and y coordinates within the frame of reference window. 

new_y 

child If the point is contained in a mapped child of the destination window, then that 

child ID is returned in child. 

Description 

XTranslateCoordinates translates coordinates from the frame of reference of one win 
dow to another. 

XTranslateCoordinates returns False and *new_x and *new_y are set to zero if 
src_w and frame_w are on different screens. In addition, if the coordinates are contained in 
a mapped child of frame_w, then that child is returned in the child argument When src_w 
and frame_y are on the same screen, XTranslateCoordinates returns True, sets 
*new_x and *new_y to the location of the point relative to f~rame_w, and sets child to 
None. 

This should be avoided in most applications since it requires a roundtrip request to the server. 
Most applications benefit from the window-based coordinate system anyway and don t need 
global coordinates. Window managers often need to perform a coordinate transformation from 
the coordinate space of one window to another, or unambiguously determine which subwindow 
a coordinate lies in. XTranslateCoordinates fulfills this need, while avoiding any race 
conditions by asking the server to perform this operation. 

Errors 

BadWindow 

Related Commands 

XGeometry, XParseGeometry. 



Xlib Reference Manual 523 



XUndefineCursor \ Vl 

v Xhb - Cursors- 
Name 

XUndefineCursor disassociate a cursor from a window. 

Synopsis 

XUndefineCursor (display, w) 
Display * display; 
Window w; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenD i spl ay . 

w Specifies the ID of the window whose cursor is to be undefined. 

Description 

XUndefineCursor sets the cursor attribute for a window to its parent s cursor, undoing the 
effect of a previous XDef ineCursor for this window. On the root window the default cursor 
is restored. 

Errors 

BadWindow 

Related Commands 

XCreateFontCursor, XCreateGlyphCursor, XCreatePixmapCursor, XDef ine 
Cursor, XFreeCursor, XQueryBestCursor, XQueryBestSize, XRecolor- 
Cursor. 



Xlib Reference Manual 



J XUngrabButton 

Xlib - Grabbing 

Name 

XUngrabButton release a button from a passive grab. 

Synopsis 

XUngrabButton (display, button, modifiers, w) 
Display *display; 
unsigned int button; 
unsigned int modifiers; 
Window w; 

Arguments 

display Specifies a connection to an X server, returned from XOpenDisplay. 

button Specifies the mouse button to be released from grab. Specify Buttonl, 

Button2, Buttons, Button4, Buttons, or the constant AnyButton, 
which is equivalent to issuing the ungrab request for all possible buttons. 

modifiers Specifies a set of keymasks. This is a bitwise OR of one or more of the fol 
lowing symbols: ShiftMask, LockMask, ControlMask, ModlMask, 
Mod2Mask, ModSMask, Mod4Mask, ModSMask, or AnyModifier. 
AnyModif ier is equivalent to issuing the ungrab button request for all pos 
sible modifier combinations (including no modifiers). 

w Specifies the ID of the window you want to release the button grab. 

Description 

XUngrabButton cancels the passive grab on a button/key combination on the specified win 
dow if it was grabbed by this client. A modifiers of AnyModifier is equivalent to issu 
ing the ungrab request for all possible modifier combinations (including the combination of no 
modifiers). A button of AnyButton is equivalent to issuing the request for all possible but 
tons. This call has no effect on an active grab. 

For more information, see Volume One, Chapter 9, The Keyboard and Pointer. 
Errors 

BadWindow 

BadValue Invalid button or modifiers mask. 

Related Commands 

XChangeActivePointerGrab, XGrabButton, XGrabKey, XGrabKeyboard, 
XGrabPointer, XGrabServer, XUngrabKey, XUngrabKeyboard, XUngrab- 
Pointer, XUngrabServer. 



Xlib Reference Manual 525 



XUngrabKey \ 



Xlib- Grabbing 



Name 

XUngrabKey release a key from a passive grab. 

Synopsis 

XUngrabKey (display, keycode, modifiers, w) 
Display * display; 
int keycode; 
unsigned int modifiers; 
Window w; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

keycode Specifies the keycode. This keycode maps to the specific key you want to 

ungrab. Pass either a keycode or AnyKey. 

modifiers Specifies a set of keymasks. This is a bitwise OR of one or more of the fol 
lowing symbols: ShiftMask, LockMask, ControlMask, ModlMask, 
Mod2Mask, ModSMask, Mod4Mask, ModSMask, or AnyModifier. 
AnyModif ier is equivalent to issuing the ungrab key request for all pos 
sible modifier combinations (including no modifiers). 

w Specifies the ID of the window for which you want to ungrab the specified 

keys. 

Description 

XUngrabKey cancels the passive grab on the key combination on the specified window if it 
was grabbed by this client. A modifiers of AnyModifier is equivalent to issuing the 
request for all possible modifier combinations (including the combination of no modifiers). A 
keycode of AnyKey is equivalent to issuing the request for all possible nonmodifier key 
codes. This call has no effect on an active grab. 

For more information, see Volume One, Chapter 9, The Keyboard and Pointer. 

Errors 

BadWindow 

BadValue Invalid keycode or modifiers mask. 

Related Commands 

XChangeActivePointerGrab, XGrabButton, XGrabKey, XGrabKeyboard, 
XGrabPointer, XGrabServer, XUngrabButton, XUngrabKeyboard, XUngrab- 
Pointer, XUngrabServer. 



526 xiib Reference Manual 



-x,,b-Grabb,n g / XUngrabKeyboard 

Name 

XUngrabKeyboard release the keyboard from an active grab. 

Synopsis 

XUngrabKeyboard (display, time) 
Display * display; 
Time time; 

Arguments 

display Specifies a connection to an X server; returned from xopenDisplay. 

time Specifies the time. Pass either a timestamp, expressed in milliseconds, or the 

constant CurrentTime. If this time is earlier than the last-keyboard-grab 
time or later than the current server time, the keyboard will not be ungrabbed. 

Description 

XUngrabKeyboard releases any active grab on the keyboard by this client. It executes as 
follows: 

Releases the keyboard and any queued events if this client has it actively grabbed from 
either XGrabKeyboard or XGrabKey. 

Does not release the keyboard and any queued events if time is earlier than the last-key 
board-grab time or is later than the current X server time. 

Generates Focus In and FocusOut events. 

The X server automatically performs an UngrabKeyboard if the grab_window (argument 
to XGrabkey and XGrabkeyboard) that becomes unviewable. 

For more information, see Volume One, Chapter 9, The Keyboard and Pointer. 
Related Commands 

XChangeActivePointerGrab, XGrabButton, XGrabKey, XGrabKeyboard, 
XGrabPointer, XGrabServer, XUngrabButton, XUngrabKey, XUngrabPointer, 
XUngrabServer. 



Xlib Reference Manual 527 



XUngrabPointer V. 



-Xlib- Pointer- 



Name 

XUngrabPointer release the pointer from an active grab. 

Synopsis 

XUngrabPointer (display, time) 
Display *display; 
Time time; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

time Specifies the time when the grab should take place. Pass either a timestamp, 

expressed in milliseconds, or the constant CurrentTime. If this time is 
earlier than the last-pointer-grab time or later than current server time, the 
pointer will not be grabbed. 

Description 

XUngrabPointer releases an active grab on the pointer by the calling client. It executes as 
follows: 

Releases the pointer and any queued events, if this client has actively grabbed the pointer 
from XGrabPo inter, XGrabButton, or from a normal button press. 

Does not release the pointer if the specified time is earlier than the last-pointer-grab time 
or is later than the current X server time. 

Generates EnterNotif y and LeaveNotif y events. 

The X server performs an XUngrabPointer automatically if the event_window or 
confne_to window (arguments of XGrabButton and XGrabPointer) becomes not 
viewable, or if the conf ine_to window is moved, completely outside the root window. 

For more information, see Volume One, Chapter 9, The Keyboard and Pointer. 
Related Commands 

XChangeActivePointerGrab, XChangePointerControl, XGetPointer- 
Control, XGetPointerMapping, XGrabPointer, XQueryPointer, XSet- 
PointerMapping, XWarpPointer. 



Xlib Reference Manual 



/ 



XUngrabServer 



Name 

XUngrabServer release the server from grab. 

Synopsis 

XUngrabServer (display) 
Display * display; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDi splay. 

Description 

XUngrabServer releases the grabbed server, and begins execution of all the requests queued 
during the grab. XUngrabServer is called automatically when a client closes its connection. 

For more information, see Volume One, Chapter 9, The Keyboard and Pointer. 
Related Commands 

XChangeActivePointerGrab, XGrabButton, XGrabKey, XGrabKeyboard, 
XGrabPointer, XGrabServer, XUngrabButton, XUngrabKey, XUngrab- 
Keyboard, XUngrabPointer. 



Xlib Reference Manual 529 



XUninstaliColormap \ 



Xlib- Colormaps 



Name 

XUninstaliColormap uninstall a colormap; install default if not already installed. 

Synopsis 

XUninstaliColormap (display, c/nap) 
Display * display; 
Colo rmap c/nap ; 

Arguments 

di spl ay Specifies a connection to an X server; returned from XOpenDi spl ay . 

c/nap Specifies the colormap to be uninstalled. 

Description 

If c/nap is an installed map for its screen, it is uninstalled. If the screen s default colormap is 
not installed, it is installed. 

If c/nap is an installed map, a ColormapNotify event is generated on every window having 
this colormap as an attribute. If a colormap is installed as a result of the uninstall, a 
ColormapNotify event is generated on every window having that colormap as an attribute. 

At any time, there is a subset of the installed colormaps, viewed as an ordered list, called the 
required list. The length of the required list is at most the min_maps specified for each screen 
in the Display structure. When a colormap is installed with XInstallColormap it is 
added to the head of the required list and the last colormap in the list is removed if necessary to 
keep the length of the list at min_maps. When a colormap is uninstalled with XUninstali 
Colormap and it is in the required list, it is removed from the list. No other actions by the 
server or the client change the required list. It is important to realize that on all but high-per 
formance workstations, min_maps is likely to be one. 

For more information on installing and uninstalling colormaps, see Volume One, Chapter 7, 
Color. 

Errors 

BadColormap 

Related Commands 

Def aultColormap, DisplayCells, XCopyColormapAndFree, XCreate- 
Colormap, XFreeColormap, XGetStandardColormap, XInstallColormap, 
XListlnstalledColormaps.XSetStandardColormap, XSetWindowColormap. 



Xlib Reference Manual 



/ 



XUnionRectWithRegion 



Name 

XUnionRectWithRegion add a rectangle to a region. 

Synopsis 

XUnionRectWithRegion (rectangle, src_region, dest_region) 
XRectangle * rectangle; 
Region src_regi on ; 
Region dest_region; 

Arguments 

rect angl e Specifies the rectangle to add to the region. 

src_regi on Specifies the source region to be used. 

dest_region Specifies the resulting region. May be the same as src_region. 

Description 

XUnionRectWithRegion computes the destination region from a union of the specified 
rectangle and the specified source region. The source and destination regions may be the same. 

One common application of this function is to simplify the combining of the rectangles speci 
fied in contiguous Expose events into a clip_mask in the GC, thus restricting the redrawn 
areas to the exposed rectangles. Use XUnionRectWithRegion to combine the rectangle in 
each Expose event into a region, then call XSetRegion. XSetRegion sets the 
clip_mask in a GC to the region. In this case, src_region and dest_region would be 
the same region. 

If src_region and dest_region are not the same region, src_region is copied to 
dest_region before the rectangle is added to dest_region. 

For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text. 
Structures 

typedef struct { 

short x, y; 

unsigned short width, height; 
} XRectangle; 

Region is a pointer to an opaque data type. 
Related Commands 

XClipBox, XDestroyRegion, XEmpty Region, XEqualRegion, Xlntersect- 
Region, XOf f setRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion, 
XSetRegion, XShrinkRegion, XSubtractRegion, XUnionRegion, XXorRegion. 



Xlib Reference Manual 531 



XUnionRegion \ 



Xlib- Regions- 



Name 

XUnionRegion compute the union of two regions. 

Synopsis 

XUnionRegion (sra, srb, dr) 
Region sra, srb; 
Region dr; 

Arguments 

sra Specify the two regions in which you want to perform the computation, 

srb 

dr Returns the result of the computation. 

Description 

XUnionRegion computes the union of two regions and places the result in dr. The resulting 
region will contain all the area of both the source regions. 

For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text. 

Structures 

Region is a pointer to an opaque structure type. 

Related Commands 

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion, 
XIntersectRegion, XOf f setRegion, XPointlnRegion, XPolygonRegion, 
XRectlnRegion, XSetRegion, XShrinkRegion, XSubtractRegion, XUnion- 
RectWithRegion, XXorRegion. 



Xlib Reference Manual 



XUniqueContext 

Xlib - Context Manager 

Name 

XUniqueContext create a new context ID (not graphics context). 

Synopsis 

XContext XUniqueContext ( ) 

Description 

The context manager allows association of arbitrary data with a resource ID. This call creates a 
unique ID that can be used in subsequent calls to XFindContext, XDeleteContext, and 
XSaveContext. 

For more information on the context manager, see Volume One, Chapter 13, Other Program 
ming Techniques. 

Structures 

typedef int XContext; 



Related Commands 

XDeleteContext, XFindContext, XSaveContext. 



Xlib Reference Manual 533 



XUnloadFont \ Xlib . Fonts _ 

Name 

XUnloadFont unload a font 

Synopsis 

XUnloadFont ( display, font ) 
Display * display; 
Font font; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

fon t Specifies the ID of the font to be unloaded. 

Description 

XUnloadFont indicates to the server that this client no longer needs the specified font The 
font may be unloaded on the X server if this is the last client that needs the font In any case, 
the font should never again be referenced by this client because Xlib destroys the resource ID. 

For more information on loading and unloading fonts, see Volume One, Chapter 6, Drawing 
Graphics and Text. 

Errors 

BadFont 

Related Commands 

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XFree- 
FontPath, XGetFontPath, XGetFontProperty, XListFonts, XListFontsWith- 
Inf o, XLoadFont, XLoadQueryFont, XQueryFont, XSetFont, XSetFontPath. 



534 



Xlib Reference Manual 



J XUnmapSubwindows 

Xlib - Mapping 

Name 

XUnmapSubwindows unmap all subwindows of a given window. 

Synopsis 

XUnmapSubwindows (display, w) 
Display * display ; 
Window w; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the ID of the window whose subwindows are to be unmapped. 

Description 

XUnmapSubwindows performs an XUnmapWindow on all mapped children of w, in bottom 
to top stacking order. (It does not unmap subwindows of subwindows.) 

XUnmapSubwindows also generates an UnmapNotify event on each subwindow and gen 
erates exposure events on formerly obscured windows. This is much more efficient than 
unmapping many subwindows one at a time, since much of the work need only be performed 
once for all of the subwindows rather than for each subwindow. 

For more information on window mapping, see Volume One, Chapter 2, X Concepts. 
Errors 

BadWindow 

Related Commands 

XMapRaised, XMapSubwindows, XMapWindow, XUnmapWindow. 



Xlib Reference Manual 535 



XUnmapWindow \ 



Xlib- Mapping- 



Name 

XUnmapWindow unmap a window. 

Synopsis 

XUnmapWindow ( di spl ay, w ) 
Display * display; 
Window w; 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the window ID. 

Description 

XUnmapWindow removes w and all its descendants from the screen (but does not unmap the 
descendents). If w is already unmapped, XUnmapWindow has no effect. Otherwise, w is 
unmapped and an UnmapNotify event is generated. Normal exposure processing on for 
merly obscured windows is performed. 

Descendants of w will not be visible until w is mapped again. In other words, the subwindows 
are still mapped, but are not visible because w is unmapped. Unmapping a window will gener 
ate exposure events on windows that were formerly obscured by w. 

For more information on window mapping, see Volume One, Chapter 2, X Concepts. 

Errors 

BadWindow 

Related Commands 

XMapRaised, XMapSubwindows, XMapWindow, XUnmapSubwindows. 



536 



Xlib Reference Manual 



XVisuallDFromVisual 

Xlib - Window Manager Hints- 
Name 

XVisuallDFromVisual obtain the visual ID from a visual. 

Synopsis 

VisuallD XVisuallDFromVisual (visual) 
Visual * visual; 

Arguments 

visual Specifies the visual type. 

Description 

XVisuallDFromVisual returns the visual ID for the specified visual. This is needed when 
filling an xvisuallnf o structure template before calling XGetvisuallnf o. 
For more information, see Volume One, Chapter 10, Interclient Communication. 

Related Commands 

XGetvisuallnf o. 



Xlib Reference Manual 537 



XWMGeometry V Xllb _ window Manager ,_ 

Name 

XWMGeometry obtain a window s geometry information. 

Synopsis 

int XWMGeometry (display, screen, user_geom r def_geom r bwidth, 

hints, x, y, width, height, gravity) 
Display *display; 
int screen; 
char *user_geom; 
char *def_geom; 
unsigned int bwidth; 
XSizeHints *hints; 
int *x, *y; /* RETURN */ 

int * width, *height ; /* RETURN */ 
int * gravity; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

screen Specifies the screen. 

user_geom Specifies the user-specified geometry or NULL. 

def_geom Specifies the application s default geometry or NULL. 

bwi dth Specifies the border width. 

hints Specifies the size hints for the window in its normal state. 

x 

y Return the x and y offsets. 

width 

height Return the width and height determined. 

gra vi ty Returns the window gravity. 

Availability 

Release 4 and later. 

Description 

XWMGeometry combines possibly incomplete or nonexistent geometry information (given in 
the format used by XParseGeometry) specified by the user and by the calling program with 
complete program-supplied default size hints (usually the ones to be stored in 
WM_NORMAL_HINTS) and returns the position, size, and gravity (NorthWestGravity, 
NorthEastGravity, SouthEastGravity or SouthWestGravity) that describe the 
window. If the base size is not set in the XSizeHints structure, the minimum size is used if 
set Otherwise, a base size of zero is assumed. If no minimum size is set in the hints structure, 
the base size is used. A mask (in the form returned by XParseGeometry) that describes 



Xlib Reference Manual 



Xlib - Window Manager Hints (continued) X WMGeo m et ry 

which values came from the user and whether or not the position coordinates are relative to the 
right and bottom edges is returned (which will have already been accounted for in the x and y 
values). 

Note that invalid user geometry specifications can cause a width or height of zero to be 
returned. The caller may pass the address of the win_gravity field of the hints argument 
as the gravity argument 

For more information, see Volume One, Chapter 10, Inter -client Communication. 
Structures 

typedef struct { 

long flags; /* marks which fields in this structure are 

/* defined */ 

int x, y; /* obsolete for new window mgrs, but clients */ 
int width, height; /* should set so old wm s don t mess up */ 
int min_width, min_height; 
int max_width, max_height; 
int width_inc, height_inc; 
struct { 

int x; /* numerator */ 

int y; /* denominator */ 
} min_aspect, max_aspect; 

int base_width, base_height; /* added by ICCCM version 1 */ 
int win_gravity; /* added by ICCCM version 1 */ 

} XSizeHints 

Related Commands 

XChangeWindowAttributes, XParseGeometry, XSetWMProperties. 



Xlib Reference Manual 



XWarpPointer V Xllb _ Polnler _ 

Name 

XWarpPointer move the pointer to another point on the screen. 

Synopsis 

XWarpPointer (display, src_w, dest_w, src_x, src_y , 

src_width r src_height , dest_x, dest_y) 
Display *display; 
Window src_w, dest_w; 
int src_x, src_y; 

unsigned int src_width, src_height ; 
int dest_x, dest_y; 

Arguments 

di splay Specifies a connection to an X server; returned from XOpenDisplay. 

src_w Specifies the ID of the source window. You can also pass None. 

dest_w Specifies the ID of the destination window. You can also pass None. 

src_x Specify the x and y coordinates within the source window. These are used 

src_y with src_width and src_height to determine the rectangle the 

pointer must be in order to be moved. They are not the present pointer posi 
tion. If src_y is None, these coordinates are relative to the root window 
of src_w. 

src_width Specify the width and height in pixels of the source area. Used with src_x 
src_height and src_y. 

dest_x Specify the destination x and y coordinates within the destination window. 

dest_y If dest_w is None, these coordinates are relative to the root window of 

dest_w. 

Description 

XWarpPointer moves the pointer suddenly from one point on the screen to another. 

If dest_w is a window, XWarpPointer moves the pointer to [dest_x, dest_y] relative to 
the destination window s origin. If dest_w is None, XWarpPointer moves the pointer 
according to the offsets [dest_x, dest_y] relative to the current position of the pointer. 

If src_window is None, the move is independent of the current cursor position (dest_x and 
dest_y use global coordinates). If the source window is not None, the move only takes place 
if the pointer is currently contained in a visible portion of the rectangle of the source window 
(including its inferiors) specified by src_x, src_y, src_width and src_height. If 
src_width is zero (0), the pointer must be between src_x and the right edge of the window 
to be moved. If src_height is zero (0), the pointer must be between src_y and the bottom 
edge of the window to be moved. 

XWarpPointer cannot be used to move the pointer outside the conf ine_to window of an 
active pointer grab. If this is attempted the pointer will be moved to the point on the border of 
the conf ine_to window nearest the requested destination. 



540 Xlib Reference Manual 



Xlib- Pointer (continued) XWarpPointer 

XWarpPointer generates events as if the user had (instantaneously) moved the pointer. 

This function should not be used unless absolutely necessary, and then only in tightly con 
trolled, predictable situations. It has the potential to confuse the user. 

Errors 

BadWindow 

Related Commands 

XChangeActivePointerGrab, XChangePointerControl, XGetPointer- 
Control, XGetPointerMapping, XGrabPointer, XQueryPointer, XSet- 
PointerMapping, XUngrabPointer. 



Xlib Reference Manual 54 / 



XWindowEvent A XIib _ lnput Ha nd.ing- 

Name 

XWindowEvent remove the next event that matches the specified mask and window. 

Synopsis 

XWindowEvent (display, w, event_mask, rep) 
Display * display; 
Window w; 
long event_mask; 
XEvent *rep; /* RETURN */ 

Arguments 

display Specifies a connection to an X server; returned from XOpenDisplay. 

w Specifies the ID of the window whose next matching event you want. 

event_mask Specifies the event mask. See XSelectlnput for a complete list of event 
masks. 

rep Returns the event removed from the input queue. 

Description 

XWindowEvent removes the next event in the queue which matches both the passed window 
and the passed mask. The event is copied into an XEvent structure supplied by the caller. 
Other events in the queue are not discarded. If no such event has been queued, XWindow 
Event flushes the request buffer and waits until one is received. 

Structures 

See individual event structures described in Volume One, Chapter 8, Events, and Appendix F, 
Structure Reference in this volume. 

Related Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEvent sQueued, 
XGetInputFocus,XGetMotionEvents,XIf Event, XMaskEvent, XNextEvent, 
XPeekEvent, XPeeklf Event, XPending, XPutBackEvent, XSelectlnput, 
XSendEvent, XSetlnputFocus, XSynchronize. 



XIib Reference Manual 



J XWithdrawWindow 

Xlib - Window Manager Hints * 

Name 

XWithdrawWindow request that a top-level window be withdrawn. 

Synopsis 

Status XWithdrawWindow (display, w, screen_n umber) 
Display * display; 
Window w; 
int screen_n umber; 

Arguments 

di spl ay Specifies a connection to an X server; returned from xopenDi spl ay . 

w Specifies the window. 

s creen_n umber 

Specifies the appropriate screen number on the server. 

Availability 

Release 4 and later. 

Description 

XWithdrawWindow informs the window manager that the specified window and its icon 
should be unmapped. It unmaps the specified window and sends a synthetic UnmapNotify 
event to the root window of the specified screen. Window managers may elect to receive this 
message and may treat it as a request to change the window s state to withdrawn. When a win 
dow is in the withdrawn state, neither its normal nor its iconic representation is visible. 
XWithdrawWindow returns a nonzero status if the UnmapNotify event is successfully sent; 
otherwise, it returns a zero status. 

For more information, see Volume One, Chapter 10, Inter client Communication. 

Errors 

BadWindow 

Related Commands 

XlconifyWindow, XReconf igureWindow. 



Xlib Reference Manual 543 



XWriteBitmapFile V Xlib _ Pixmaps and Tlles _ 

Name 

XWriteBitmapFile write a bitmap to a file. 

Synopsis 

int XWriteBitmapFile (display, filename, bitmap, width, 

height, x_hot, y_hot) 
Display * display ; 
char * filename; 
Pixmap bitmap; 
unsigned int width, height; 
int x_hot r y_hot ; 

Arguments 

display Specifies a connection to an X server; returned from XQpenDisplay. 

filename Specifies the filename to use. The format of the filename is operating system 
specific. 

bi tmap Specifies the bitmap to be written. 

wi dth Specify the width and height in pixels of the bitmap to be written. 

height 

x_hot Specify where to place the hotspot coordinates (or -1,-1 if none present) in 

y_hot the file. 

Description 

XWriteBitmapFile writes a bitmap to a file. The file is written out in X version 11 bitmap 
file format, shown below. 

If the file cannot be opened for writing, XWriteBitmapFile returns BitmapOpen- 
Failed. If insufficient memory is allocated XWriteBitmapFile returns Bitmap- 
NoMemory. Otherwise, on no error, XWriteBitmapFile returns BitmapSuccess. 

If x_hot and y_hot are not -1, -1, then XWriteBitmapFile writes them out as the 
hotspot coordinates for the bitmap. 

The following is an example of the contents of a bitmap file created. The name used ("gray" in 
this example) is the portion of filename after the last "/". 

#define gray_width 16 

tdefine gray_height 16 

#define gray_x_hot 8 

#define gray_y_hot 8 

static char gray_bits[] = { 

Oxf8, Oxlf, Oxe3, Oxc7, Oxcf, Oxf3, Ox9f, Oxf9, Oxbf, Oxfd, 0x33, Oxcc, 
Ox7f, Oxfe, Ox7f, Oxfe, Ox7e, Ox7e, Ox7f, Oxfe, 0x37, Oxec, Oxbb, Oxdd, 
Ox9c, 0x39, Oxcf, Oxf3, Oxe3, Oxc7, Oxf8, Oxlf}; 

For more information on bitmaps, see Volume One, Chapter 6, Drawing Graphics and Text. 



544 xiib Reference Manual 



Xlib - Pixmaps and Tiles (continued) X WriteBitmapFile 

Errors 

BadAlloc 

BadDrawable 

BadMatch The specified width and height did not match dimensions of the specified 
jbi tmap. 

Related Commands 

XCreateBitmapFromData.XCreatePixmap, XCreatePixmapFromBitmapData, 
XFreePixmap,XQueryBestSize,XQueryBestStipple,XQueryBestTile, 
XReadBitmapFile, XSetTile, XSetWindowBackgroundPixmap, XSetWindow- 
BorderPixmap. 



Xlib Reference Manual 



XXorRegion ~\ 



Xlib- Regions- 



Name 

XXorRegion calculate the difference between the union and intersection of two regions. 

Synopsis 

XXorRegion ( sra, srb, dr) 
Region sra, srb; 
Region dr; /* RETURN */ 

Arguments 

sra Specify the two regions on which you want to perform the computation, 

srb 

dr Returns the result of the computation. 

Description 

XXorRegion calculates the union minus the intersection of two regions, and places it in dr. 
Xor is short for "Exclusive OR", meaning that a pixel is included in dr if it is set in either sra 
or srb but not in both. 

For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text. 

Structures 

Region is a pointer to an opaque structure type. 

Related Commands 

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion, 
XIntersectRegion, XOf f setRegion, XPointlnRegion, XPolygonRegion, 
XRectlnRegion, XSetRegion, XShrinkRegion, XSubtractRegion, XUnion- 
RectWithRegion, XUnionRegion. 



546 Xlib Reference Manual 



Function Group Summary 



This quick reference is intended to help you find and use the right function for a particular 
task. It supplies two lists: 

Listing of Functions by Groups 

Alphabetical Listing of Functions 

Both functions and macros are listed in all the groups in which they belong. Therefore, sev 
eral of them are listed more than once. 

Remember that Xlib functions begin with the letter "X"; macros do not 



A.1 Group Listing with Brief Descriptions 



Association Tables 



XCreateAssocTable 

XDeleteAssoc 

XDestroyAssocTable 

XLookUpAssoc 

XMakeAssoc 



Create a new association table (X10). 

Delete an entry from an association table. 

Free the memory allocated for an association table. 

Obtain data from an association table. 

Create an entry in an association table. 



Buffers 



XStoreBuffer 

XStoreBytes 

XFetchBuffer 

XFetchBytes 

XRotateBuffers 



Store data in a cut buffer. 
Store data in cut buffer 0. 
Return data from a cut buffer. 
Return data from cut buffer 0. 
Rotate the cut buffers. 



Function Group Summary 



547 



Client Connections 



XKillClient 
XSetCloseDownMode 



Destroy a client or its remaining resources. 
Change the close down mode of a client. 



Colorcells 



XAllocColor 

XAllocColorCells 
XAllocColorPlanes 
XAllocNamedColor 
XLookupColor 

XParseColor 

XQueryColor 

XQueryColors 

XStoreColor 

XStoreColors 

XStoreNamedColor 
XFreeColors 
BlackPixel 
WhitePixel 



Allocate a read-only colormap cell with closest hardware-sup 
ported color. 

Allocate read/write (nonshared) colorcells. 
Allocate read/write (nonshareable) color planes. 
Allocate a read-only colorcell from color name. 
Get database RGB values and closest hardware-supported 
RGB values from color name. 

Look up or translate RGB values from color name or hexade 
cimal value. 

Obtain the RGB values for a specified pixel value. 
Obtain RGB values and flags for each specified pixel value. 
Set or change a read/write entry of a colormap to the closest 
available hardware color. 

Set or change read/write colorcells to the closest available 
hardware colors. 

Allocate a read/write colorcell by English color name. 
Free colormap cells or planes. 

Return a black pixel value on the default colormap of screen. 
Return a pixel value representing white in default colormap. 



Colormaps 



XCopyColormapAndFree 

XCreateColormap 

XFreeColormap 

XGetStandardColormap 

XSetStandardColormap 

XSetWindowColormap 

XInstallColormap 

XUninstallColormap 

XListlnstalledColormaps 

Default Colormap 

DefaultColormapOf Screen 

DisplayCells 



Copy a colormap and return a new colormap ID. 
Create a colormap. 

Delete a colormap and install the default colormap. 
Get the standard colormap property. 
Change the standard colormap property. 
Set the colormap for a specified window. 
Install a colormap. 

Uninstall a colormap; install default if not already installed. 
Get a list of installed colormaps. 
Return the default colormap on the default screen. 
Return the default colormap on the specified screen. 
Return the maximum number of colormap cells on the con 
nected display. 



Context Manager 



XDeleteContext 
XFindContext 



Delete a context entry for a given window and type. 
Get data from the context manager (not graphics context). 



545 



Xlib Reference Manual 



Context Manager (continued) 



XSaveContext 
XUniqueContext 



Save a data value corresponding to a window and context type 

(not graphics context). 

Create a new context ID (not graphics context). 



Cursors 



XDefineCursor 

XUndefineCursor 

XCreateFontCursor 

XCreateGlyphCursor 

XCreatePixmapCursor 

XFreeCursor 

XRecolorCursor 

XQueryBest Cursor 

XQueryBestSize 



Assign a cursor to a window. 

Disassociate a cursor from a window. 

Create a cursor from the standard cursor font 

Create a cursor from font glyphs. 

Create a cursor from two bitmaps. 

Destroy a cursor. 

Change the color of a cursor. 

Get the closest supported cursor sizes. 

Obtain the "best" supported cursor, tile, or stipple size. 



Display Specifications 



DefaultColormap 

DefaultDepth 

DefaultGC 

Default Screen 



DefaultVisual 
DisplayCells 

DisplayHeight 

DisplayHeightMM 

DisplayPlanes 

DisplayString 

DisplayWidth 

DisplayWidthMM 

RootWindow 

ScreenCount 

XDisplayMotionBufferSize 

XListDepths 

XListPixmapFormats 

XMaxRequestSize 

XResourceManager String 



Return the default colormap on the specified screen. 
Return the depth of the default root window for a screen. 
Return the default graphics context for the root window of a 
screen. 

Return the screen integer; the last segment of a string passed to 
XOpenDisplay, or the DISPLAY environment variable if 
NULL was used. 

Return the default visual structure for a screen. 
Return the maximum number of colormap cells on the con 
nected display. 

Return an integer that describes the height of the screen in pix 
els. 

Return the height of the specified screen in millimeters. 
Return the number of planes on the connected display. 
Return the string that was passed to XOpenDisplay or if 
that was NULL, the DISPLAY variable. 
Return the width of the screen in pixels. 
Return the width of the specified screen in millimeters. 
Return the ID of the root window. 
Return the number of available screens. 
Return size of server s motion history buffer. 
Return a list of the depths supported on this server. 
Return a list of the pixmap formats supported on this server. 
Return maximum request size allowed on this server. 
Return string containing user s resource database. 



Function Group Summary 



549 



Drawing Primitives 



XDraw 

XDrawArc 

XDrawArcs 

XDrawFilled 

XDrawLine 

XDrawLines 

XDrawPoint 

XDrawPoints 

XDrawRect angle 

XDrawRect angles 

XDrawSegments 

XCopyArea 

XCopyPlane 

XFillArc 

XFillArcs 

XFillPolygon 

XFillRectangle 

XFillRect angles 

XClearArea 

XClearWindow 



Draw a polyline or curve between vertex list (from X10). 

Draw an arc fitting inside a rectangle. 

Draw multiple arcs. 

Draw a filled polygon or curve from vertex list (from X10). 

Draw a line between two points. 

Draw multiple connected lines. 

Draw a point. 

Draw multiple points. 

Draw an outline of a rectangle. 

Draw the outlines of multiple rectangles. 

Draw multiple disjoint lines. 

Copy an area of a drawable. 

Copy a single plane of a drawable into a drawable with depth, 

applying pixel values. 

Fill an arc. 

Fill multiple arcs. 

Fill a polygon. 

Fill a rectangular area. 

Fill multiple rectangular areas. 

Clear a rectangular area in a window. 

Clear an entire window. 



Errors 



XGetErrorDatabaseText 

XGetErrorText 

XSetErrorHandler 

XSetlOErrorHandler 

XDisplayName 

XSetAfterFunction 

XSynchronize 



Obtain error messages from the error database. 

Obtain a description of error code. 

Set a nonfatal error event handler. 

Handle fatal I/O errors. 

Report the display name when connection to a display fails. 

Set a function called after all Xlib functions. 

Enable or disable synchronization for debugging. 



Events 



XSelectlnput 

XSendEvent 

XSetlnputFocus 

XGetlnputFocus 

XWindowEvent 

XCheckWindowEvent 

XCheckTypedEvent 

XCheckTypedWindowEvent 

XMaskEvent 

XCheckMaskEvent 



Select the event types to be sent to a window. 
Send an event 

Set the keyboard focus window. 
Return the current keyboard focus window. 
Remove the next event matching mask and window. 
Remove the next event matching both passed window and pas 
sed mask; don t wait. 

Return the next event in queue that matches event type; don t 
wait. 

Return the next event in queue matching type and window. 
Remove the next event that matches mask. 
Remove the next event that matches mask; don t wait. 



550 



Xlib Reference Manual 



Events (continued) 



XI f Event 

XChecklfEvent 

XPeekEvent 

XPeeklfEvent 

XAllowEvents 

XGetMotionEvents 

XNextEvent 

XPutBackEvent 

XEventsQueued 

XPending 

XSynchronize 
QLength 



Wait for matching event 

Check the event queue for a matching event 

Get an event without removing it from the queue. 

Get an event without recovering it from the queue; don t wait 

Control the behavior of keyboard and pointer events when 

these resources are grabbed. 

Get pointer motion events. 

Get the next event of any type or window. 

Push an event back on the input queue. 

Check the number of events in the event queue. 

Rush the request buffer and return the number of pending 

input events. 

Enable or disable synchronization for debugging. 

Return the current length of the input queue on the connected 

display. 



Extensions 



XFreeExtensionList 
XList Ext ens ions 
XQueryExtension 



Free memory allocated for a list of installed extensions to X. 
Return a list of all extensions to X supported by the server. 
Get extension information. 



Fonts 



XLoadFont 

XUnloadFont 

XFreeFont 

XFreeFontlnfo 

XFreeFontNames 

XFreeFontPath 

XListFonts 

XListFontsWithlnfo 

XQueryFont 

XSetFont 

XSetFontPath 

XGetFontPath 

XGetFont Property 

XCreateFont Cursor 



Load a font if not already loaded; get font ID. 

Unload a font 

Unload a font and free storage for the font structure. 

Free multiple font information arrays. 

Free the font name array. 

Free the memory allocated by XGetFontPath. 

Return a list of the available font names. 

Obtain the names and information about loaded fonts. 

Return information about a loaded font. 

Set the current font in a graphics context. 

Set the font search path. 

Get the current font search path. 

Get a font property given its atom. 

Create a cursor from the standard cursor font 



Grabbing 



XGrabKey 

XUngrabKey 

XGrabKeyboard 

XUngrabKeyboard 

XGrabButton 



Grab a key. 

Release a key from grab. 

Grab the keyboard. 

Release the keyboard from grab. 

Grab a pointer button. 



Function Group Summary 



551 



Grabbing (continued) 



XUngrabButton 

XGrabPointer 

XUngrabPointer 

XGrabServer 

XUngrabServer 

XChangeActivePointerGrab 



Release a button from grab. 

Grab the pointer. 

Release the pointer from grab. 

Grab the server grab. 

Release the server from grab. 

Change the parameters of an active pointer grab. 



Graphics Context 



XCreateGC 

XChangeGC 
XCopyGC 
XFreeGC 
XGContextFromGC 

XGetGCValues 

XSetArcMode 

XSetClipMask 

XSetClipOrigin 

XSetClipRectangles 

XSetRegion 

XSetDashes 

XSet Line Attributes 

XSetFillRule 

XSetFillStyle 

XSetTile 

XSetStipple 

XSetTSOrigin 

XSetGraphicsExposures 

XSetForeground 

XSet Background 

XSetFunction 

XSetPlaneMask 

XSetState 

XSetSubwindowMode 
DefaultGC 



Create a new graphics context for a given screen with the 

depth of the specified drawable. 

Change the components of a given graphics context. 

Copy a graphics context. 

Free a graphics context. 

Obtain the GContext (resource ID) associated with the 

specified graphics context. 

Get GC component values from Xlib s GC cache. 

Set the arc mode in a graphics context. 

Set clip_mask pixmap in a graphics context. 

Set the clip origin in a graphics context. 

Set clip_mask in a graphics context to the list of rectangles. 

Set clip_mask of the graphics context to the specified 

region. 

Set dash_of f set and dashes (for lines) in a graphics 

context. 

Set the line drawing components in a graphics context. 

Set the fill rule in a graphics context. 

Set the fill style in a graphics context. 

Set the fill tile in a graphics context. 

Set the stipple in a graphics context. 

Set the tile/stipple origin in a graphics context. 

Set graphics_exposures in a graphics context. 

Set the foreground pixel value in a graphics context. 

Set the background pixel value in a graphics context. 

Set the bitwise logical operation in a graphics context. 

Set the plane mask in a graphics context. 

Set the foreground, background, logical function and plane 

mask in a graphics context. 

Set the subwindow mode in a graphics context. 

Return the default graphics context for the root window of a 

screen. 



552 



Xlib Reference Manual 



Host Access 



XAddHost 

XAddHosts 

XListHosts 

XRemoveHost 

XRemoveHosts 

XDisableAccessControl 

XEnableAccessControl 

XSetAccessControl 



Add a host to the access control list. 

Add multiple hosts to the access control list. 

Obtain a list of hosts having access to this display. 

Remove a host from the access control list. 

Remove multiple hosts from the access control list. 

Allow access from any host 

Use access control list to allow or deny connection requests. 

Disable or enable access control. 



HouseKeeping 



XFree 

XOpenDisplay 
XCloseDisplay 
XNoOp 



Free specified in-memory data created by an Xlib function. 
Connect a client program to an X server. 
Disconnect a client program from an X server and display. 
Send a NoOp to exercise connection with the server. 



Images 



XCreate Image 
XDes troy Image 
XPutlmage 
XSublmage 
XGet Image 
XGetSublmage 

XAddPixel 
XPutPixel 
XGetPixel 
ImageByteOrder 



Allocate memory for an Xlmage structure. 
Deallocate memory associated with an image. 
Draw a rectangular image on a window or pixmap. 
Create a subimage from part of an image. 
Place contents of a rectangle from drawable into an image. 
Copy a rectangle in drawable to a location within the pre 
existing image. 

Add a constant value to every pixel value in an image. 
Set a pixel value in an image. 
Obtain a single pixel value from an image. 
Specify the required byte order for images for each scan line 
unit in XYFormat (bitmap) or for each pixel value in ZFor- 
mat. Returns either LSBFirst orMSBFirst. 



Interclient Communication 



(see Window Manager Hints, Selections, and Cut Buffers) 



Keyboard 



XKeycodeToKeysym 

XKeysymToKeycode 

XKeysymToString 

XStringToKeysym 

XLookupKeysym 

XRebindKeysym 



Convert a keycode to a keysym. 

Convert a keysym to the appropriate keycode. 

Convert a keysym symbol to a string. 

Convert a keysym name string to a keysym. 

Get the keysym corresponding to a keycode in a structure. 

Rebind a keysym to a string for client. 



Function Group Summary 



553 



Keyboard (continued) 



XLookupString 

XQueryKeymap 

XGetKeyboardMapping 

XChangeKeyboardMapping 

XRefreshKeyboardMapping 

XSe-tModifierMapping 

XGetModifierMapping 

XDeleteModifiermapEntry 

XInsertModifiermapEntry 

XNewModifiermap 

XFreeModifiermap 

XDisplayKeycodes 

Macros, Display 



Map a key event to ASCII string, keysym, and Compose- 

Status. 

Obtain a bit vector for the current state of the keyboard. 

Return symbols for keycodes. 

Change the keyboard mapping. 

Update the stored modifier and keymap information. 

Set keycodes to be used as modifiers (Shift, Control, etc.). 

Obtain modifier key mapping (Shift, Control, etc.). 

Delete an entry from an XModif ierKeymap structure. 

Add a new entry to an XModif ierKeymap structure. 

Create a keyboard modifier mapping structure. 

Destroy and free a keyboard modifier mapping structure. 

Returns range of keycodes used by server. 



AllPlanes 
BlackPixel 
BlackPixelOf Screen 

CellsOfScreen 
Connect ionNumber 

DefaultColormap 
DefaultColormapOf Screen 
DefaultDepth 
DefaultDepthOf Screen 
DefaultGC 

DefaultGCOf Screen 

DefaultRootWindow 
DefaultScreen 



DefaultScreenOf Display 
DefaultVisual 
DefaultVisualOf Screen 
DisplayCells 

DisplayHeight 

DisplayHeightMM 
DisplayOf Screen 
Display? lanes 



Return an unsigned long value with all bits set 
Return a black pixel value on the default colormap of screen. 
Return the black pixel value in the default colormap of the 
specified screen. 

Return the number of colormap cells of the specified screen. 
Return the connection number (file descriptor on UNIX sys 
tem). 

Return the default colormap on the specified screen. 
Return the default colormap of the specified screen. 
Return the depth of the default root window for a screen. 
Return the default depth of the specified screen. 
Return the default graphics context for the root window of a 
screen. 

Return the default graphics context (GC) of the specified 
screen. 

Return the root window for the default screen. 
Return the screen integer; the last segment of a string passed to 
XOpenDi splay, or the DISPLAY environment variable if 
NULL was used. 

Return the default screen of the specified display. 
Return the default visual structure for a screen. 
Return the default visual of the specified screen. 
Return the maximum number of colormap cells on the con 
nected display. 

Return an integer that describes the height of the screen in pix 
els. 

Return the height of the specified screen in millimeters. 
Return the display of the specified screen. 
Return the number of planes on the connected display. 



554 



Xlib Reference Manual 



Macros, Display (continued) 



DisplayString 
DisplayType 

DisplayWidth 

DisplayWidthMM 

DoesBackingStore 



DoesSaveUnders 

dpyno 

EventMaskOf Screen 
HeightOfScreen 
HeightMMOfScreen 
Keyboard 

LastKnownRequest- 

Processed 
MaxCmapsOf Screen 

MinCmapsOf Screen 

NextRequest 
PlanesOf Screen 
ProtocolRevision 
ProtocolVersion 

QLength 

RootWindow 
RootWindowOf Screen 
ScreenCount 
XScreenNumberOf Screen 

ScreenOf Display 
ServerVendor 

Vendor Re lease 

WhitePixel 
WhitePixelOf Screen 

WidthOfScreen 

WidthMMOfScreen 

XDisplayMotionBufferSize 



Return the string that was passed to XOpenDisplay or if 
that was NULL, the DISPLAY variable. 
Return the connected display manufacturer, as defined in 
<XlllXvendors.h>. 

Return the width of the screen in pixels. 
Return the width of the specified screen in millimeters. 
Return a value indicating whether the screen supports backing 
stores. Return one of WhenMapped, NotUseful, or 
Always. 

Return whether the screen supports save unders. True or 
False. 

Return the file descriptor of the connected display. 
Return the initial root event mask for the specified screen. 
Return the height of the specified screen. 
Return the height of the specified screen in millimeters. 
Return the device ID for the main keyboard connected to the 
display. 

Return the serial ID of the last known protocol request to have 
been issued. 

Return the maximum number of colormaps supported by a 
screen. 

Return the minimum number of colormaps supported by a 
screen. 

Return the serial ID of the next protocol request to be issued. 
Return the number of planes in a screen. 
Return the minor protocol revision number of the X server. 
Return the version number of the X protocol on the connected 
display. 

Return the current length of the input queue on the connected 
display. 

Return the ID of the root window. 
Return the root window of the specified screen. 
Return the number of available screens. 
Return the integer corresponding to the specified pointer to a 
Screen structure. 

Return the specified screen of the specified display. 
Return a pointer to a null-terminated string giving some identi 
fication of the maker of the X server implementation. 
Return a number related to the release of the X server by the 
vendor. 

Return a pixel value representing white in default colormap. 
Return the white pixel value in the default colormap of the 
specified screen. 

Return the width of the specified screen. 
Return the width of the specified screen in millimeters. 
Return size of server s motion history buffer. 



Function Group Summary 



555 



Macros, Display (continued) 



XListDepths Return a list of the depths supported on this server. 

XListPixmapFormats Return a list of the pixmap formats supported on this server. 

XMaxRequestsize Return maximum request size allowed on this server. 

XResourceManagerString Return string containing user s resource database. 

Macros, Image Format 

BitmapBitOrder Return LeastSignif leant or MostSignif leant. 

Indicates the bit order in BitmapUnit. 

BitmapPad Each scan line is padded to a multiple of bits specified by the 

value returned by this macro. 

BitmapUnit The scan line is quantized (calculated) in multiples of this 

value. 

ByteOrder Specifies the required byte order for images for each scan line 

unit in XYFormat (bitmap) or for each pixel value in ZFor- 
mat. Possible values are LSBFirst orMSBFirst. 

i mage ByteOrder Specifies the required byte order for images for each scan line 

unit in XYFormat (bitmap) or for each pixel value in z For 
mat. Return either LSBFirst orMSBFirst. 



Macros, Keysym Classification 



isCursorKey Return True if the keysym is on the cursor key. 

isFunctionKey Return True if the keysym is on the function keys. 

I sKeypadKey Return T rue if the keysym is on the key pad. 

isMiscFunct ionKey Return True if the keysym is on the miscellaneous function keys. 

isModif ierKey Return True if the keysym is on the modifier keys. 

I sPFKey Return T rue if the keysym is on the PF keys. 

Mapping 



(see Window Mapping, Keyboard, or Pointer) 
Output Buffer 



<Flush Rush the request buffer. 

xs ync Flush the request buffer and wait for all events to be processed 

by the server. 

Pointers 

XQueryPointer Get the current pointer location. 

xwarpPointer Move the pointer to another point on the screen. 

XGrabPointer Grab the pointer. 

xungrabPointer Release the pointer from grab. 



556 



Xlib Reference Manual 



Pointers (continued) 



XGetPointerMapping 

XSetPointerMapping 

XGetPointerControl 

XChangePointerControl 

XChangeActivePointerGrab 



Get the pointer button mapping. 

Set the pointer button mapping. 

Get the current pointer preferences. 

Change the pointer preferences. 

Change the parameters of an active pointer grab. 



Properties 



XListProperties 

XDeleteProperty 

XChangeProperty 

XSetStandardProperties 

XRot a teWindowP roper ties 

XGetAtomName 

XGet Font Property 

XGetWindowProperty 

XInternAtom 

XGetTextProperty 

XSet Text Property 

XStringListToText Property 

XTextPropertyToStringList 

XFreeStringList 



Get the property list for a window. 

Delete a window property. 

Change a property associated with a window. 

Set the minimum set of properties for the window manager. 

Rotate properties in the properties array. 

Get a name for a given atom. 

Get a font property given its atom. 

Obtain the atom type and property format for a window. 

Return an atom for a given name string. 

Read a TEXT property. 

Write a TEXT property. 

Convert a list of strings to an XTextProperty structure. 

Convert an XTextProperty to a list of strings. 

Free memory allocated by XTextPropertyToStringList. 



Regions 



XCreateRegion 

XDestroyRegion 

XEmptyRegion 

XPolygonRegion 

XPointlnRegion 

XRectlnRegion 

XUnionRectWithRegion 

XClipBox 

XOf fsetRegion 

XShrinkRegion 

XEqualRegion 

XSetRegion 

XSubtract Region 
XInter sect Region 
XUnionRegion 
XXorRegion 



Create a new empty region. 

Deallocate storage associated with a region. 

Determine if a region is empty. 

Generate a region from points. 

Determine if a point resides in a region. 

Determine if a rectangle resides in a region. 

Add a rectangle to a region. 

Generate the smallest rectangle enclosing a region. 

Change offset of a region. 

Reduce the size of a region. 

Determine if two regions have the same size, offset, and space. 

Set clip_mask of the graphics context to the specified 

region. 

Subtract one region from another. 

Compute the intersection of two regions. 

Compute the union of two regions. 

Calculate the difference between the union and intersection of 

2 regions. 



Function Group Summary 



557 



Resource Manager 



XrmDestroyDat abase 

XrmGetFileDatabase 

XrmGetResource 

XrmGetStringDat abase 

Xrmlnitialize 

XrmMergeDat abases 

XrmParseCommand 

XrmPutFileDat abase 

XrmPutLineResource 

XrmPutResource 

XrmPutStringResource 

XrmQGetResource 

XrmQGetSearchList 

XrmQGetSearchResource 

XrmQPut Resource 

XrmQPutStringResource 

XrmQuarkToString 

XrmStringToBinding- 

QuarkList 

XrmStringToQuarkList 
XrmStringToQuark 
XrmUniqueQuark 
Xpermalloc 
XResourceManager String 



Destroy a resource database. 

Retrieve a database from a file. 

Get a resource from name and class as strings. 

Create a database from a string. 

Initialize the resource manager. 

Merge the contents of one database with another. 

Load a resource database from command line arguments. 

Store a database in a file. 

Add a resource entry given as a string of name and value. 

Store a resource into a database. 

Add a resource that is specified as a string. 

Get a resource from name and class as quarks. 

Return a list of database levels. 

Search resource database levels for a given resource. 

Store a resource into a database using quarks. 

Add a string resource value to a database using quarks. 

Convert a quark to a string. 

Convert a key string to a binding list and a quark list. 

Convert a key string to a quark list. 

Convert a string to a quark. 

Allocate a new quark. 

Allocate memory never to be freed. 

Get user s database set with xrdb from Display structure. 



Save Set 



XAddToSaveSet 

XRemoveFromSaveSet 

XChangeSaveSet 



Add a window to the client s save-set. 

Remove a window from the client s save-set. 

Add or remove a window to or from the client s save-set. 



Screen Saver 



XActivate Screen Saver 

XForceScreenSaver 

XResetScreenSaver 

XGetScreenSaver 

XSetScreenSaver 



Activate screen blanking. 

Turn the screen saver on or off. 

Reset the screen saver. 

Get the current screen saver parameters. 

Set the parameters of the screen saver. 



Selections 



XGet Select ionOwner 
XSetSelectionOwner 
XConvert Select ion 



Return the owner of a selection. 
Set the owner of a selection. 
Use the value of a selection. 



555 



Xlib Reference Manual 



Server Specifications 

(see Display Specifications) 

Standard Geometry 



XGeometry 
XWMGeometry 
XParseGeometry 
XTranslateCoordinates 



Calculate window geometry given user geometry string and 

default geometry. Superceded in R4 by XWMGeometry. 

Calculate window geometry given user geometry string and 

default geometry. 

Generate position and size from standard window geometry 

string. 

Change the coordinate system from one window to another. 



Text 



XDrawImageString 
XDrawImageStr ingl 6 
XDrawString 
XDrawStringlG 
XDrawText 
XDrawTextl6 
XQueryText Extents 
XQueryTextExtentsl6 

XTextExtents 
XTextExtentslG 
XTextWidth 
XTextWidthlG 



Draw 8-bit image text characters. 
Draw 16-bit image text characters. 
Draw an 8-bit text string, foreground only. 
Draw two-byte text strings. 
Draw 8-bit polytext strings. 
Draw 16-bit polytext strings. 
Query the server for string and font metrics. 
Query the server for string and font metrics of a 16-bit charac 
ter string. 

Get string and font metrics. 

Get string and font metrics of a 16-bit character string. 
Get the width in pixels of an 8-bit character string. 
Get the width in pixels of a 16-bit character string. 



Tile, Pixmap, Stipple and Bitmap 



XCreatePixmap 

XFreePixmap 

XQueryBestSize 

XQueryBest Stipple 

XQueryBestTile 

XSetTile 

XSetWindowBorderP ixmap 

XSetWindowBackgroundPixmap 

XReadBitmapFile 

XWriteBitmapFile 

XCreateBitmapFromData 

XCreatePixmapFromBitmapData 

XListPixmapFormats 



Create a pixmap. 

Free a pixmap ID. 

Obtain the "best" supported cursor, tile, or stipple size. 

Obtain the best supported stipple shape. 

Obtain the best supported fill tile shape. 

Set the fill tile in a graphics context. 

Change a window border tile attribute and repaint the border. 

Change the background tile attribute of a window. 

Read a bitmap from disk. 

Write a bitmap to a file. 

Create a bitmap from XI 1 bitmap format data. 

Create a pixmap with depth from bitmap data. 

Read supported pixmap formats from Display structure. 



Function Group Summary 



559 



User Preferences 



XAutoRepeatOff 

XAutoRepeatOn 

XBell 

XGetDefault 

XGetPointer Control 

XGetKeyboardControl 

XChangeKeyboardControl 



Turn off the keyboard auto-repeat keys. 

Turn on the keyboard auto-repeat keys. 

Ring the bell (Control G). 

Scan the user preferences for program name and options. 

Get the current pointer preferences. 

Obtain a list of the current keyboard preferences. 

Change the keyboard preferences. 



Visuals 



XGetVisuallnfo 
XMatchVisuallnfo 

DefaultVisual 
XVisuallDFromVisual 



Find a visual information structure that matches the specified 

template. 

Obtain the visual information that matches the desired depth 

and class. 

Return the default visual structure for a screen. 

Get resource ID from a visual structure. 



Window Attributes 



XGetWindowAt tributes 
XChangeWindowAttributes 
XSetWindowBackground 
XSetWindowBackgroundP ixmap 
XSetWindowBorder 

XSetWindowBorderP ixmap 

XSetWindowColormap 

XDefineCursor 

XGet Geometry 

XSelectlnput 



Obtain the current attributes of window. 

Set window attributes. 

Set the background pixel attribute of a window. 

Change the background tile attribute of a window. 

Change a window border attribute to the specified pixel value 

and repaint the border. 

Change a window border tile attribute and repaint the border. 

Set the colormap for a specified window. 

Assign a cursor to a window. 

Obtain the current geometry of drawable. 

Select the event types to be sent to a window. 



Window Configuration 



XMoveWindow 

XResizeWindow 

XMoveResizeWindow 

XSetWindowBorderWidth 

XRestackWindows 

XConfigureWindow 

XGetGeometry 
XReconfigureWMWindow 



Move a window. 

Change a window s size. 

Change the size and position of a window. 

Change the border width of a window. 

Change the stacking order of siblings. 

Change the window position, size, border width, or stacking 

order. 

Obtain the current geometry of drawable. 

Change top-level window position, size, border width, or 

stacking order. 



560 



Xlib Reference Manual 



Window Existence 



XCreateSimpleWindow 
XCreateWindow 
XDestroySubwindows 
XDestroy Window 



Create an unmapped inputOutput subwindow. 

Create a window and set attributes. 

Destroy all subwindows of a window. 

Unmap and destroy a window and all subwindows. 



Window Manager Hints 



XGetClassHint 

XSetClassHint 

XGetNormalHints 

XSetNormalHints 

XGetSizeHints 

XSetSizeHints 

XGet Trans lent ForHint 

XSetTransientForHint 

XGetWMHints 

XSetWMHints 

XGetZoomHints 

XSetZoomHints 

XFetchName 

XStoreName 

XGetlconName 
XSetlconName 

XGetlconSizes 
XSetlconSizes 
XSetCommand 

XAllocClassHint 

XAllocIconSize 

XAllocSizeHints 

XAllocStandardColormap 

XAllocWMHints 



Get the XA_WM_CLASS property of a window. Obsolete in 

R4. 

Set the XA_WM_CLASS property of a window. Obsolete in 

R4. 

Get the size hints property of a window in normal state (not 

zoomed or iconified). Obsolete in R4. 

Set the size hints property of a window in normal state (not 

zoomed or iconified). Obsolete in R4. 

Read any property of type XA_WM_SIZE_HINTS. Obsolete 

inR4. 

Set the value of any property of type XA_WM_- 

SIZE_HINTS. Obsolete in R4. 

Get the XA_WM_TRANSIENT_FOR property of a window. 

Set the XA_WM_TRANSIENT_FOR property of a window. 

Read a window manager hints property. 

Set a window manager hints property. 

Read the size hints property of a zoomed window. Obsolete in 

R4. 

Set the size hints property of a zoomed window. Obsolete in 

R4. 

Get a window s name (XA_WM_NAME property). Obsolete in 

R4. 

Assign a name to a window for the window manager. Obsolete 

inR4. 

Get the name to be displayed in an icon. Obsolete in R4. 

Set the name to be displayed in a window s icon. Obsolete in 

R4. 

Get preferred icon sizes. 

Set the value of the XA_WM_ICON_SIZE property. 

Set the XA_WM_COMMAND property (command line arguments). 

Obsolete in R4. 

Allocate and zero fields in XClassHint structure. 

Allocate and zero fields in xlconSize structure. 

Allocate and zero fields in xsizeHints structure. 

Allocate and zero fields in XStandardColormap structure. 

Allocate and zero fields in xwMHints structure. 



Function Group Summary 



561 



Window Manager Hints (continued) 



XGetRGBColormaps 
XSetRGBColormaps 

XGetWMClientMachine 
XSetWMClientMachine 
XGetWMIconName 

XSetWMIconName 

XGetWMProtocols 
XSetWMProtocols 
XGetWMNormalHints 

XSetWMNormalHints 
XSetWMSizeHints 

XSetWMColormapWindows 
XGetWMColormapWindows 
XSetWMProperties 

XSetWMName 
XGetWMName 



Read standard colormap property. Replaces XGetStan- 

dardColormap. 

Write standard colormap property. Replaces xsetstan- 

dardColormap. 

Read WM_CLIENT_MACHINE property. 

Write WM_CLIENT_MACHINE property. 

Read XA_WM_ICON_NAME property. Replaces XGet- 

IconName. 

Write XA_WM_ICON_NAME property. Replaces xset- 

IconName. 

Read WM_PROTOCOLS property. 

Write WM_PROTOCOLS property. 

Read XA_WM_NORMAL_HINTS property. Replaces xGet- 

NormalHints. 

Write XA_WM_NORMAL_HINTS property. Replaces XSet- 

NormalHints. 

Write XA_WM_SIZE_HINTS property. Replaces xset- 

SizeHints. 

Write WM_COLORMAP_WINDOWS property. 

Read WM_COLORMAP_WINDOWS property. 

Write all standard properties. Replaces XSetStan- 

dardProperties. 

Write XA_WM_NAME property. Replaces XStoreName. 

Read XA_WM_NAME property. Replaces XFetchName. 



Window Manipulation 



XLowerWindow 

XRaiseWindow 

XCirculateSubwindows 

XCirculateSubwindowsDown 

XCirculateSubwindowsUp 

XQueryTree 

XRepar en t Window 

XMoveWindow 

XResizeWindow 

XMoveResizeWindow 

XSetWindowBorderWidth 

XRestackWindows 

XConfigureWindow 

XlconifyWindow 

XWithdrawWindow 

XReconfigureWMWindow 



Lower a window in the stacking order. 

Raise a window to the top of the stacking order. 

Circulate the stacking order of children up or down. 

Circulate the bottom child to the top of the stacking order. 

Circulate the top child to the bottom of the stacking order. 

Return a list of children, parent, and root. 

Change a window s parent 

Move a window. 

Change a window s size. 

Change the size and position of a window. 

Change the border width of a window. 

Change the stacking order of siblings. 

Change the window position, size, border width, or stacking 

order. 

Inform window manager that a top-level window should be 

iconified. 

Inform window manager that a top-level window should be 

unmapped. 

Reconfigure a top-level window. 



562 



Xlib Reference Manual 



Window Mapping 



XMapRaised 

XMapSubwindows 

XMapWindow 

XUnmapSubwindows 

XUnmapWindow 

XlconifyWindow 

XWithdrawWindow 



Map a window on top of its siblings. 

Map all subwindows. 

Map a window. 

Unmap all subwindows of a given window. 

Unmap a window. 

Inform window manager that a top-level window should be iconified. 

Inform window manager that a top-level window should be unmapped. 



A.2 Alphabetical Listing of Routines 



Table A-1. Alphabetical Listing of Routines 



Routine 



Description 



XActivateScreenSaver 

XAddHost 

XAddHosts 

XAddPixel 

XAddToSaveSet 

XAllocClassHint 

XAllocIconSize 

XAllocSizeHints 

XAllocStandardColormap 

XAllocWMHints 

XAllocColor 

XAllocColorCells 
XAllocColorPlanes 
XAllocNamedColor 
XAllowEvents 

XAutoRepeatOff 

XAutoRepeatOn 

XBell 

XChangeActivePointerGrab 

XChangeGC 

XChangeKeyboardControl 

XChangeKeyboardMapping 

XChangePointerControl 

XChangeProperty 

XChangeSaveSet 

XChangeWindowAttributes 

XChecklfEvent 

XCheckMaskEvent 



Activate screen blanking. 
Add a host to the access control list. 
Add multiple hosts to the access control list. 
Add a constant value to every pixel value in an image. 
Add a window to the client s save-set. 
Allocate and zero fields in XClassHint structure. 
Allocate and zero fields inxiconSize structure. 
Allocate and zero fields in XSizeHints structure. 
Allocate and zero fields in XStandardColormap structure. 
Allocate and zero fields in XWMHints structure. 
Allocate a read-only colormap cell with closest hardware- 
supported color. 

Allocate read/write (nonshared) colorcells. 
Allocate read/write (nonshareable) color planes. 
Allocate a read-only colorcell from color name. 
Control the behavior of keyboard and pointer events when 
these resources are grabbed. 
Turn off the keyboard auto-repeat keys. 
Turn on the keyboard auto-repeat keys. 
Ring the bell (Control G). 
Change the parameters of an active pointer grab. 
Change the components of a given graphics context. 
Change the keyboard preferences such as key click. 
Change the keyboard mapping. 
Change the pointer preferences. 
Change a property associated with a window. 
Add or remove a window to or from the client s save-set 
Set window attributes. 

Check the event queue for a matching event. 
Remove the next event that matches mask; don t wait. 



Function Group Summary 



563 



Table A-1. Alphabetical Listing of Routines (continued) 



Routine 



Description 



XCheckTypedEvent 

XCheckTypedWindowEvent 

XCheckWindowEvent 

XCirculateSubwindows 
XCirculateSubwindowsDown 

XCirculateSubwindowsUp 

XClearArea 
XClearWindow 
XClipBox 
XCloseDisplay 
XConf igureWindow 

XConvert Select ion 

XCopyArea 

XCopyColormapAndFree 

XCopyGC 

XCopyPlane 

XCreateAssocTable 
XCreateBitmapFromData 
XCreateColormap 
XCreateFont Cursor 
XCreateGC 

XCreateGlyphCursor 
XCreate Image 
XCreatePixmap 
XCreatePixmapCursor 
XCreatePixmapFrom- 

BitmapData 
XCreateRegion 
XCreateSimpleWindow 
XCreateWindow 
XDefineCursor 
XDeleteAssoc 
XDeleteContext 
XDeleteModifiermapEntry 
XDeleteProperty 
XDestroyAssocTable 
XDestroylmage 
XDestroyRegion 



Return the next event in queue that matches event type; 

Return the next event in queue matching type and window. 

Remove the next event matching both passed window and 

passed mask; don t wait. 

Circulate the stacking order of children up or down. 

Circulate the bottom child to the top of the 

stacking order. 

Circulate the top child to the bottom of the 

stacking order. 

Clear a rectangular area in a window. 

Clear an entire window. 

Generate the smallest rectangle enclosing a region. 

Disconnect a client program from an X server and display. 

Change the window position, size, border width, or stacking 

order. 

Use the value of a selection. 

Copy an area of a drawable. 

Copy a colormap and return a new colormap ID. 

Copy a graphics context. 

Copy a single plane of a drawable into a drawable with depth, 

applying pixel values. 

Create a new association table (X10). 

Create a bitmap from XI 1 bitmap format data. 

Create a colormap. 

Create a cursor from the standard cursor font 

Create a new graphics context for a given screen with the depth 

of the specified drawable. 

Create a cursor from font glyphs. 

Allocate memory for an x Image structure. 

Create a pixmap. 

Create a cursor from two bitmaps. 

Create a pixmap with depth from bitmap data. 

Create a new empty region. 

Create an unmapped inputOutput window. 

Create a window and set attributes. 

Assign a cursor to a window. 

Delete an entry from an association table. 

Delete a context entry for a given window and type. 

Delete an entry from an XModif ierKeymap structure. 

Delete a window property. 

Free the memory allocated for an association table. 

Deallocate memory associated with an image. 

Deallocate storage associated with a region. 



564 



Xlib Reference Manual 



Table A-1. Alphabetical Listing of Routines (continued) 



Routine 



Description 



XDestroySubwindows 

XDestroyWindow 

XDisableAccessControl 

XDisplayKeycodes 

XDisplayMotionBuf ferSize 

XDisplayName 

XDraw 

XDrawArc 

XDrawArcs 

XDrawFilled 

XDrawImageString 

XDrawImageStringlG 

XDrawLine 

XDrawLines 

XDrawPoint 

XDrawPoints 

XDrawRect angle 

XDrawRect angles 

XDrawSegments 

XDrawString 

XDrawStringl6 

XDrawText 

XDrawTextlG 

XEmptyRegion 

XEnableAccessControl 

XEqualRegion 

XEventsQueued 

XFetchBuffer 

XFetchBytes 

XFetchName 

XFillArc 

XFillArcs 

XFillPolygon 

XFillRectangle 

XFillRectangles 

XFindContext 

XFlush 

XForceScreenSaver 

XFree 

XFreeColormap 

XFreeColors 

XFreeCursor 



Destroy all subwindows of a window. 

Unmap and destroy a window and all subwindows. 

Allow access from any host 

Returns range of keycodes used by server. 

Return size of server s motion history buffer. 

Report the display name when connection to a display fails. 

Draw a polyline or curve between vertex list (from X10). 

Draw an arc fitting inside a rectangle. 

Draw multiple arcs. 

Draw a filled polygon or curve from vertex list (from X10). 

Draw 8-bit image text characters. 

Draw 16-bit image text characters. 

Draw a line between two points. 

Draw multiple connected lines. 

Draw a point. 

Draw multiple points. 

Draw an outline of a rectangle. 

Draw the outlines of multiple rectangles. 

Draw multiple disjoint lines. 

Draw an 8-bit text string, foreground only. 

Draw two-byte text strings. 

Draw 8-bit polytext strings. 

Draw 16-bit polytext strings. 

Determine if a region is empty. 

Use access control list to allow or deny connection requests. 

Determine if two regions have the same size, offset, and shape. 

Check the number of events in the event queue. 

Return data from a cut buffer. 

Return data from cut buffer 0. 

Get a window s name (XA_WM_NAME property). 

Fill an arc. 

Fill multiple arcs. 

Fill a polygon. 

Fill a rectangular area. 

Fill multiple rectangular areas. 

Get data from the context manager (not graphics context). 

Flush the request buffer (display all queued requests). 

Turn the screen saver on or off. 

Free specified in-memory data created by an Xlib function. 

Delete a colormap and install the default colormap. 

Free colormap cells or planes. 

Destroy a cursor. 



Function Group Summary 



565 



Table A-1. Alphabetical Listing of Routines (continued) 



Routine 



Description 



XCheckTypedEvent 

XCheckTypedWindowEvent 

XCheckWindowEvent 

XCirculateSubwindows 
XCirculateSubwindowsDown 

XCirculateSubwindowsUp 

XClearArea 

XClearWindow 

XClipBox 

XCloseDisplay 

XConfigureWindow 

XConvertSelection 

XCopyArea 

XCopyColormapAndFree 

XCopyGC 

XCopyPlane 

XCreateAssocTable 

XCreateBitmapFromData 

XCreateColormap 

XCr eat eFont Cursor 

XCreateGC 

XCreateGlyphCursor 
XCr eate Image 
XCreatePixmap 
XCreatePixmapCursor 
XCreatePixmapFrom- 

BitmapData 
XCreateRegion 
XCreateSimpleWindow 
XCreateWindow 
XDefineCursor 
XDeleteAssoc 
XDeleteContext 
XDeleteModifiermapEntry 
XDeleteProperty 
XDestroyAssocTable 
XDestroylmage 
XDestroyRegion 



Return the next event in queue that matches event type; 

Return the next event in queue matching type and window. 

Remove the next event matching both passed window and 

passed mask; don t wait. 

Circulate the stacking order of children up or down. 

Circulate the bottom child to the top of the 

stacking order. 

Circulate the top child to the bottom of the 

stacking order. 

Clear a rectangular area in a window. 

Clear an entire window. 

Generate the smallest rectangle enclosing a region. 

Disconnect a client program from an X server and display. 

Change the window position, size, border width, or stacking 

order. 

Use the value of a selection. 

Copy an area of a drawable. 

Copy a colormap and return a new colormap ID. 

Copy a graphics context. 

Copy a single plane of a drawable into a drawable with depth, 

applying pixel values. 

Create a new association table (X10). 

Create a bitmap from XI 1 bitmap format data. 

Create a colormap. 

Create a cursor from the standard cursor font 

Create a new graphics context for a given screen with the depth 

of the specified drawable. 

Create a cursor from font glyphs. 

Allocate memory for an X Image structure. 

Create a pixmap. 

Create a cursor from two bitmaps. 

Create a pixmap with depth from bitmap data. 

Create a new empty region. 

Create an unmapped inputOutput window. 

Create a window and set attributes. 

Assign a cursor to a window. 

Delete an entry from an association table. 

Delete a context entry for a given window and type. 

Delete an entry from an XModif ierKeymap structure. 

Delete a window property. 

Free the memory allocated for an association table. 

Deallocate memory associated with an image. 

Deallocate storage associated with a region. 



564 



Xlib Reference Manual 



Table A-1. Alphabetical Listing of Routines (continued) 



Routine 



Description 



XDestroySubwindows 

XDestroyWindow 

XDisableAccessControl 

XDisplayKeycodes 

XDisplayMotionBufferSize 

XDisplayName 

XDraw 

XDrawArc 

XDrawArcs 

XDrawFilled 

XDrawImageString 

XDrawImageString 16 

XDrawLine 

XDrawLines 

XDrawPoint 

XDrawPoints 

XDrawRect angle 

XDr a wRect angles 

XDrawSegments 

XDrawString 

XDrawStringlG 

XDrawText 

XDrawTextl6 

XEmptyRegion 

XEnableAccessControl 

XEqualRegion 

XEventsQueued 

XFetchBuffer 

XFetchBytes 

XFetchName 

XFillArc 

XFillArcs 

XFillPolygon 

XFillRectangle 

XFillRectangles 

XFindContext 

XFlush 

XForceScreenSaver 

XFree 

XFreeColormap 

XFreeColors 

XFreeCursor 



Destroy all subwindows of a window. 

Unmap and destroy a window and all subwindows. 

Allow access from any host 

Returns range of keycodes used by server. 

Return size of server s motion history buffer. 

Report the display name when connection to a display fails. 

Draw a polyline or curve between vertex list (from X10). 

Draw an arc fitting inside a rectangle. 

Draw multiple arcs. 

Draw a filled polygon or curve from vertex list (from X10). 

Draw 8-bit image text characters. 

Draw 16-bit image text characters. 

Draw a line between two points. 

Draw multiple connected lines. 

Draw a point. 

Draw multiple points. 

Draw an outline of a rectangle. 

Draw the outlines of multiple rectangles. 

Draw multiple disjoint lines. 

Draw an 8-bit text string, foreground only. 

Draw two-byte text strings. 

Draw 8-bit polytext strings. 

Draw 16-bit polytext strings. 

Determine if a region is empty. 

Use access control list to allow or deny connection requests. 

Determine if two regions have the same size, offset, and shape. 

Check the number of events in the event queue. 

Return data from a cut buffer. 

Return data from cut buffer 0. 

Get a window s name (XA_WM_NAME property). 

Fill an arc. 

Fill multiple arcs. 

Fill a polygon. 

Fill a rectangular area. 

Fill multiple rectangular areas. 

Get data from the context manager (not graphics context). 

Flush the request buffer (display all queued requests). 

Turn the screen saver on or off. 

Free specified in-memory data created by an Xlib function. 

Delete a colormap and install the default colormap. 

Free colormap cells or planes. 

Destroy a cursor. 



Function Group Summary 



565 



Table A-1. Alphabetical Listing of Routines (continued) 



Routine 



Description 



XFreeExtensionList 

XFreeFont 

XFreeFontlnfo 

XFreeFontNames 

XFreeFontPath 

XFreeGC 

XFreeModifiermap 

XFreePixmap 

XFreeStringList 

XGContextFromGC 
XGeometry 

XGetAtomName 

XGetClassHint 

XGetDefault 

XGetErrorDatabaseText 

XGetErrorText 

XGetFontPath 

XGetFontProperty 

XGetGeometry 

XGetGCValues 

XGetlconName 

XGetlconSizes 

XGetlmage 

XGetlnputFocus 

XGetKeyboardControl 

XGetKeyboardMapping 

XGetModifierMapping 

XGetMotionE vents 

XGetNormalHints 

XGetPixel 

XGet Point erControl 

XGetPointerMapping 

XGetRGBColormaps 

XGetScreenSaver 
XGet Select ionOwner 
XGetSizeHints 
XGetStandardColormap 



Free memory allocated for a list of installed 

extensions to X. 

Unload a font and free storage for the font structure. 

Free multiple font information arrays. 

Free the font name array. 

Free the memory allocated by XGetFontPath. 

Free a graphics context. 

Destroy and free a keyboard modifier mapping structure. 

Free a pixmap ID. 

Free memory allocated by XTextProperty- 

ToStringList. 

Obtain the GContext (resource ID) associated 

with the specified graphics context. 

Calculate window geometry given user geometry string 

and default geometry. 

Get a name for a given atom. 

Get the XA_WM_CLASS property of a window. 

Scan the user preferences for program name and options. 

Obtain error messages from the error database. 

Obtain a description of error code. 

Get the current font search path. 

Get a font property given its atom. 

Obtain the current geometry of drawable. 

Get GC component values from Xlib s GC cache. 

Get the name to be displayed in an icon. 

Get preferred icon sizes. 

Place contents of a rectangle from drawable into an image. 

Return the current keyboard focus window. 

Obtain a list of the current keyboard preferences. 

Return symbols for keycodes. 

Obtain a mapping of modifier keys (Shift, Control, etc.). 

Get pointer motion events. 

Get the size hints property of a window in normal state (not 

zoomed or iconified). 

Obtain a single pixel value from an image. 

Get the current pointer preferences. 

Get the pointer button mapping. 

Read standard colormap property. 

Replaces XGetStandardColormap. 

Get the current screen saver parameters. 

Return the owner of a selection. 

Read any property of type XA_WM_SIZE_HINTS. 

Get the standard colormap property. 



566 



Xlib Reference Manual 



Table A-1. Alphabetical Listing of Routines (continued) 



Routine 



Description 



XGetSublmage 

XGetTextProperty 

XGetTransientForHint 

XGetVisuallnfo 

XGetWindowAttributes 

XGetWindowProperty 

XGetWMClientMachine 

XGetWMColormapWindows 

XGetWMHints 

XGetWMIconName 

XGetWMName 
XGetWMNormalHints 

XGetWMProtocols 
XGetWMSizeHints 

XGetZoomHints 

XGrabButton 

XGrabKey 

XGrabKeyboard 

XGrabPointer 

XGrabServer 

XlconifyWindow 

XlfEvent 

XInsertModifiermapEntry 

XInstallColormap 

XInternAtom 

XIntersectRegion 

XKeycodeToKeysym 

XKeysymToKeycode 

XKeysymToString 

XKillClient 

XListDepths 

XListExtensions 

XListFonts 

XListFontsWithlnfo 

XListHosts 

XListlnstalledColormaps 

XListPixmapFormats 



Copy a rectangle in drawable to a location within the 

pre-existing image. 

Read a TEXT property. 

Get the XA_WM_TRANS IENT_FOR property of a window. 

Find a visual information structure that matches the 

specified template. 

Obtain the current attributes of window. 

Obtain the atom type and property format for a window. 

Read WM_CLIENT_MACHINE property. 

Read WM_COLORMAP_WINDOWS property. 

Read a window manager hints property. 

Read XA_WM_ICON_NAME property. 

Replaces XGetlconName. 

Read XA_WM_NAME property. Replaces XFetchName. 

Read XA_WM_NORMAL_HINTS property. Replaces 

XGetNormalHints. 

Read WM_PROTOCOLS property. 

Read XA_WM_SIZE_HINTS property. Replaces 

XGetSizeHints. 

Read the size hints property of a zoomed window. 

Grab a pointer button. 

Grab a key. 

Grab the keyboard. 

Grab the pointer. 

Grab the server. 

Inform window manager that a top-level window should 

be iconified. 

Wait for matching event 

Add a new entry to an XModif ierKeymap structure. 

Install a colormap. 

Return an atom for a given name string. 

Compute the intersection of two regions. 

Convert a keycode to a keysym. 

Convert a keysym to the appropriate keycode. 

Convert a keysym symbol to a string. 

Destroy a client or its remaining resources. 

Return a list of the depths supported on this server. 

Return a list of all extensions to X supported by the server. 

Return a list of the available font names. 

Obtain the names and information about loaded fonts. 

Obtain a list of hosts having access to this display. 

Get a list of installed colormaps. 

Return a list of the pixmap formats supported on 

this server. 



Function Group Summary 



567 



Table A-1. Alphabetical Listing of Routines (continued) 



Routine 



Description 



XrmQuarkToString 
XrmStringToBinding- 

QuarkList 
XrmStringToQuark 
XrmStringToQuarkList 
XrmUniqueQuark 
XRotateBuffers 
XRotateWindowProperties 
XSaveContext 

XSelectlnput 

XSendEvent 

XSetAccessControl 

XSetAfterFunction 

XSetArcMode 

XSet Background 

XSetClassHint 

XSetClipMask 

XSetClipOrigin 

XSetClipRectangles 

XSetCloseDownMode 

XSetCommand 

XSetDashes 

XSetErrorHandler 

XSetFillRule 

XSetFillStyle 

XSetFont 

XSetFontPath 

XSet Foreground 

XSetFunction 

XSetGraphicsExposures 

XSetlconName 

XSetlconSizes 

XSetlnputFocus 

XSetlOErrorHandler 

XSetLineAttributes 

XSetModifierMapping 

XSetNormalHints 

XSetPlaneMask 
XSet Point erMapping 



Convert a quark to a string. 

Convert a key string to a binding list and a quark 

list. 

Convert a string to a quark. 

Convert a key string to a quark list. 

Allocate a new quark. 

Rotate the cut buffers. 

Rotate properties in the properties array. 

Save a data value corresponding to a window and 

context type (not graphics context). 

Select the event types to be sent to a window. 

Send an event 

Disable or enable access control. 

Set a function called after all Xlib functions. 

Set the arc mode in a graphics context. 

Set the background pixel value in a graphics context. 

Set the XA_WM_CLASS property of a window. 

Set clip_mask pixmap in a graphics context. 

Set the clip origin in a graphics context. 

Change clip_mask in a graphics context to the 

list of rectangles. 

Change the close down mode of a client. 

Set the XA_WM_COMMAND atom (command line arguments). 

Set dash_of f set and dashes (for lines) in a graphics context. 

Set a nonfatal error event handler. 

Set the fill rule in a graphics context. 

Set the fill style in a graphics context. 

Set the current font in a graphics context. 

Set the font search path. 

Set the foreground pixel value in a graphics context. 

Set the bitwise logical operation in a graphics context. 

Set graphics_exposures in a graphics context. 

Set the name to be displayed in a window s icon. 

Set the value of the XA_WM_ICON_SIZE property. 

Set the keyboard focus window. 

Handle fatal I/O errors. 

Set the line drawing components in a graphics context. 

Set keycodes to be used as modifiers (Shift, Control, 

etc.). 

Set the size hints property of a window in normal state 

(not zoomed or iconified). 

Set the plane mask in a graphics context. 

Set the pointer button mapping. 



570 



Xlib Reference Manual 



Table A-1. Alphabetical Listing of Routines (continued) 



Routine 



Description 



XSetRegion 
XSetRGBColormaps 

XSetScreenSaver 

XSet Select ionOwner 

XSetSizeHints 

XSetStandardColormap 

XSetStandardProperties 

XSetState 

XSetStipple 

XSetSubwindowMode 

XSetTextProperty 

XSetTile 

XSetTransientForHint 

XSetTSOrigin 

XSetWindowBackground 

XSetWindowBackground- 

Pixmap 
XSetWindowBorder 

XSetWindowBorderP ixmap 

XSetWindowBorderWidth 

XSetWindowColormap 

XSetWMClientMachine 

XSetWMColormapWindows 

XSetWMHints 

XSetWMIconName 

XSetWMName 

XSetWMNormalHints 

XSetWMProperties 

XSetWMProtocols 
XSetWMSizeHints 

XSetZoomHints 
XShrinkRegion 
XStoreBuffer 



Set clip_mask of the graphics context to 

the specified region. 

Write standard colormap property. Replaces 

XSetStandardColormap. 

Set the parameters of the screen saver. 

Set the owner of a selection. 

Set the value of any property of type XA_WM_S I z E_H I N T s . 

Change the standard colormap property. 

Set the minimum set of properties for the window manager. 

Set the foreground, background, logical function, and 

plane mask in a graphics context. 

Set the stipple in a graphics context. 

Set the subwindow mode in a graphics context. 

Write a TEXT property using XTextProperty structure. 

Set the fill tile in a graphics context. 

Set the XA_WM_TRANSIENT_FOR property 

of a window. 

Set the tile/stipple origin in a graphics context. 

Set the background pixel attribute of a window. 

Change the background tile attribute of 

a window. 

Change a window border attribute to the specified 

pixel value and repaint the border. 

Change a window border tile attribute and repaint 

the border. 

Change the border width of a window. 

Set the colormap for a specified window. 

Write WM_CLIENT_MACHINE property. 

Write WM_COLORMAP_WINDOWS property. 

Set a window manager hints property. 

Write XA_WM_ICON_NAME property. Replaces 

XSetlconName. 

Write XA_WM_NAME property. Replaces 

XStoreName. 

Write XA_WM_NORMAL_HINTS property. 

Replaces XSetNormalHints. 

Write all standard properties. Replaces 

XSetStandardProperties. 

Write WM_PROTOCOLS property. 

Write XA_WM_SIZE_HINTS property. Replaces 

XSetSizeHints. 

Set the size hints property of a zoomed window. 

Reduce or expand the size of a region. 

Store data in a cut buffer. 



Function Group Summary 



571 



Table A-1. Alphabetical Listing of Routines (continued) 



Routine 



Description 



XStoreBytes 
XStoreColor 

XStoreColors 

XStoreName 

XStoreNamedColor 

XStringListToTextProperty 

XStringToKeysym 
XSublmage 
XSubtract Region 
XSync 

XSynchronize 

XTextExtents 

XTextExtentslG 

XTextWidth 

XTextWidthlG 

XTranslateCoordinates 

XUndef ineCursor 

XUngrabButton 

XUngrabKey 

XUngrabKeyboard 

XUngrabPointer 

XUngrabServer 

XUninstallColormap 

XUnionRectWithRegion 

XUnionRegion 

XUniqueContext 

XUnloadFont 

XUnmapSubwindows 

XUnmapWindow 

XWarpPointer 

XWindowEvent 

XWMGeometry 

XWriteBitmapFile 
XXorRegion 



Store data in cut buffer 0. 

Set or change a read/write entry of a colormap to the closest 

available hardware color. 

Set or change read/write colorcells to the closest available 

hardware colors. 

Assign a name to a window for the window manager. 

Allocate a read/write colorcell by English color name. 

Convert a list of strings to an XText Property 

structure. 

Convert a keysym name string to a keysym. 

Create a subimage from part of an image. 

Subtract one region from another. 

Rush the request buffer and wait for all events and errors 

to be processed by the server. 

Enable or disable synchronization for debugging. 

Get string and font metrics. 

Get string and font metrics of a 16-bit character string. 

Get the width in pixels of an 8-bit character string. 

Get the width in pixels of a 16-bit character string. 

Change the coordinate system from one window to 

another. 

Disassociate a cursor from a window. 

Release a button from grab. 

Release a key from grab. 

Release the keyboard from grab. 

Release the pointer from grab. 

Release the server from grab. 

Uninstall a colormap; install default if not 

already installed. 

Add a rectangle to a region. 

Compute the union of two regions. 

Create a new context ID (not graphics context). 

Unload a font 

Unmap all subwindows of a given window. 

Unmap a window. 

Move the pointer to another point on the screen. 

Remove the next event matching mask and window. 

Calculate window geometry given user geometry string 

and default geometry. 

Write a bitmap to a file. 

Calculate the difference between the union and intersection 

of two regions. 



572 



Xlib Reference Manual 



B 
Error Messages and Protocol Requests 



This appendix contains two tables: Table B-l describes the standard error codes (the 
error_code member of XErrorEvent) and what causes them, and Table B-2 describes 
the mapping between protocol requests and Xlib functions. Each reference page in this vol 
ume describes in more detail the errors that may occur because of that Xlib routine. Volume 
One, Chapter 3, Basic Window Program, describes the handling of errors in general. 

A protocol request is the actual network message that is sent from Xlib to the server. Many 
convenience functions are provided in Xlib to make programs easier to write and more read 
able. When any one of several convenience routines is called it will be translated into one 
type of protocol request. For example, XMoveWindow and XResizeWindow are conve 
nience routines for the more general XConf igureWindow. Both of these Xlib routines 
use the protocol request Configure Window. The protocol request that causes an error, along 
with other information about the error is printed to the standard error output by the default 
error handlers. In order to find out where in your code the error occurred, you will need to 
know what Xlib function to look for. Use Table B-2 to find this function. 

Xlib functions that do not appear in Table B-2 do not generate protocol requests. They per 
form their function without affecting the display and without requiring information from the 
server. If errors can occur in them, the errors are reported in the returned value. 

Table B-1. Error Messages 



Error Codes: 



Possible Cause 



BadAccess 



BadAlloc 
BadAtom 



Specifies that the client attempted to grab a key/button combination 
that is already grabbed by another client; free a colormap entry that 
is not allocated by the client; store into a read-only colormap entry; 
modify the access control list from other than the local (or otherwise 
authorized) host; or select an event type that only one client can 
select at a time, when another client has already selected it. 

Specifies that the server failed to allocate the requested resource. 

Specifies that a value for an Atom argument does not name a defined 
Atom. 



Appendix B: Error Messages and Protocol Requests 



573 



Table B-1. Error Messages (continued) 



Error Codes: 



Possible Cause 



BadColor 

BadCursor 

BadDrawable 

BadFont 

BadGC 

BadlDChoice 



Badlmplement- 
ation 



BadLength 
BadMatch 

BadName 
BadPixmap 

BadRequest 
BadValue 

BadWindow 



Specifies that a value for a Colormap argument does not name a 
defined Colormap. 

Specifies that a value for a Cursor argument does not name a 
defined Cursor. 

Specifies that a value for a Drawable argument does not name a 
defined Window or Pixmap. 

Specifies that a value for a Font or GContext argument does not 
name a defined Font. 

Specifies that a value for a GContext argument does not name a 
defined GContext. 

Specifies that the value chosen for a resource identifier either is not 
included in the range assigned to the client or is already in use. 

Specifies that the server does not implement some aspect of the 
request A server that generates this error for a core request is defi 
cient. Clients should be prepared to receive such errors and either 
handle or discard them. 

Specifies that the length of a request is shorter or longer than that 
required to minimally contain the arguments. This usually indicates 
an internal Xlib error. 

Specifies that an inputOnly window is used as a Drawable. 

Some argument (or pair of arguments) has the correct type and range 
but fails to "match" in some other way required by the request 

Specifies that a font or color of the specified name does not exist. 

Specifies that a value for a Pixmap argument does not name a 
defined Pixmap. 

Specifies that the major or minor opcode does not specify a valid 
request 

Specifies that some numeric value falls outside the range of values 
accepted by the request Unless a specific range is specified for an 
argument, the full range defined by the argument s type is accepted. 
Any argument defined as a set of alternatives can generate this error. 

Specifies that a value for a window argument does not name a 
defined window. 



The BadAtom, BadColor, BadCursor, BadDrawable, BadFont, BadGC, Bad 
Pixmap, and BadWindow errors are also used when the argument type should be among a 



574 



Xlib Reference Manual 



set of fixed alternatives (for example, a window ID, PointerRoot, or None) and some 
other constant or variable is used. 

Table B-2. Xlib Functions and Protocol Requests 



Protocol Request 



AllocColor 

AllocColorCells 

AllocColorPlanes 

AllocNamedColor 

AllowEvents 

Bell 

ChangeActivePointerGrab 

ChangeGC 



ChangeHosts 

ChangeKeyboardControl 

ChangeKeyboardMapping 

ChangePointerControl 

ChangeProperty 



Xlib Function 



XAllocColor 

XAllocColorCells 

XAllocColorPlanes 

XAllocNamedColor 

XAllowEvents 

XBell 

XChange Act ivePointer Grab 

XChangeGC 

XSetArcMode 

XSet Background 

XSetClipMask 

XSetClipOrigin 

XSetFillRule 

XSetFillStyle 

XSetFont 

XSet Foreground 

XSetFunction 

XSetGraphicsExposures 

XSetLineAttributes 

XSetPlaneMask 

XSetState 

XSetStipple 

XSetSubwindowMode 

XSetTile 

XSetTSOrigin 

XAddHost 
XAddHosts 
XRemoveHost 
XRemoveHosts 

XAutoRepeatOff 

XAutoRepeatOn 

XChangeKeyboardControl 

XChangeKeyboardMapping 
XChangePointerControl 

XChangeProperty 

XSetCommand 

XSetlconName 

XSetlconSizes 

XSetNormalHints 



Appendix B: Error Messages and Protocol Requests 



575 



Table B-2. Xlib Functions and Protocol Requests (continued) 



Protocol Request 



Xlib Function 



ChangeSaveSet 



Change Window Attributes 



CirculateWindow 

Clear Area 
CloseFont 
Configure Window 



ConvertSelection 
Copy Area 

CopyColormapAndFree 
CopyGC 
CopyPlane 



XSetWMProperties 

XSetSizeHints 

XSetStandardProperties 

XSetWMHints 

XSetZoomHints 

XStoreBuffer 

XStoreBytes 

XStoreName 

XAddToSaveSet 

XChangeSaveSet 

XRemoveFromSaveSet 

XChangeWindowAttributes 

XDefineCursor 

XSelectlnput 

XSetWindowBackground 

XSetWindowBackgroundPixmap 

XSetWindowBorder 

XSetWindowBorderPixmap 

XSetWindowColormap 

XUndef ineCursor 

XCirculateSubwindows 

XCirculateSubwindowsDown 

XCirculateSubwindowsUp 

XClearArea 
XClearWindow 

XFreeFont 
XUnloadFont 

XConfigureWindow 

XLowerWindow 

XMapRaised 

XMoveResize Window 

XMoveWindow 

XRaiseWindow 

XReconfigureWMWindow 

XResizeWindow 

XRestackWindows 

XSetWindowBorderWidth 

XCon vert Select ion 

XCopyArea 

XCopyColormapAndFree 

XCopyGC 

XCopyPlane 



576 



Xlib Reference Manual 



Table B-2. Xlib Functions and Protocol Requests (continued) 



Protocol Request 



Xlib Function 



CreateColormap 

CreateCursor 

CreateGC 

CreateGlyphCursor 

CreatePixmap 
Create Window 

DeleteProperty 

DestroySubwindows 

DestroyWindow 

FillPoly 

ForceScreenSaver 

FreeColormap 

FreeColors 

FreeCursor 

FreeGC 

FreePixmap 

GetAtomName 

GetFontPath 

GetGeometry 

Getlmage 
GetlnputFocus 

GetKeyboardControl 

GetKeyboardMapping 

GetModifierMapping 

GetMotionEvents 

GetPointerControl 

GetPointerMapping 



XCreateColormap 
XCreatePixmapCursor 

XCreateGC 
XOpenDisplay 

XCr eat eFont Cursor 
XCreateGlyphCursor 

XCreatePixmap 

XCreateSimpleWindow 
XCreateWindow 

XDeleteProperty 
XDestroySubwindows 
XDestroyWindow 
XFillPolygon 

XActi vat e ScreenSaver 
XForceScreenSaver 
XRe set ScreenSaver 

XFreeColormap 

XFreeColors 

XFreeCursor 

XFreeGC 

XFreePixmap 

XGetAtomName 

XGetFontPath 

XGetGeometry 
XGetWindowAttributes 

XGet Image 

XGetlnputFocus 
XSync 

XGetKeyboardControl 

XGetKeyboardMapping 

XGetModifierMapping 

XGetMotionEvents 

XGetPointerControl 

XGetPonterMapping 



Appendix B: Error Messages and Protocol Requests 



577 



Table B-2. Xlib Functions and Protocol Requests (continued) 



Protocol Request 



Xlib Function 



GetProperty 



GetScreenSaver 

GetSelectionOwner 

GetWindow Attributes 

GrabButton 

GrabKey 

GrabKeyboard 

GrabPointer 

GrabServer 

ImageTextS 

ImageTextl6 

InstallColormap 

InternAtom 

KillClient 

ListExtensions 

ListFonts 

ListFontsWithlnfo 

ListHosts 

LisanstaUedColormaps 

ListProperties 

LookupColor 

MapS ub windows 
MapWindow 

NoOperation 



XFetchBytes 

XFetchName 

XGetlconSizes 

XGet IconName 

XGetNormalHints 

XGetSizeHints 

XGe tWindowP roperty 

XGetWMProperties 

XGetWMHints 

XGetZoomHints 

XGetScreenSaver 

XGet Select ionOwner 

XGetWindowAttributes 

XGrabButton 

XGrabKey 

XGrabKeyboard 

XGrabPointer 

XGrabServer 

XDrawImageString 

XDrawImageStringlG 

XInstallColormap 

XInternAtom 

XKillClient 

XList Ext ens ions 

XListFonts 

XListFontsWithlnfo 

XListHosts 

XList InstalledColormaps 

XListProperties 

XLookupColor 
XParseColor 

XMapSubwindows 

XMapRaised 
XMapWindow 

XNoOp 



578 



Xlib Reference Manual 



Table B-2. Xlib Functions and Protocol Requests (continued) 



Protocol Request 



Xlib Function 



OpenFont 
PolyArc 
PolyFillArc 
PolyFillRectangle 

PolyLine 
PolyPoint 

PolyRectangle 
Poly Segment 
PolyText8 
PolyTextl6 

Putlmage 
QueryBestSize 

QueryColors 
QueryExtension 

QueryFont 
QueryKeymap 
QueryPointer 
QueryTextExtents 

Query Tree 
RecolorCursor 
ReparentWindow 
RotateProperties 



XLoadFont 
XLoadQueryFont 

XDrawArc 
XDrawArcs 

XFillArc 
XFillArcs 

XFillRectangle 
XFillRectangles 

XDrawLines 

XDrawPoint 
XDrawPoints 

XDrawRect angle 
XDrawRect angles 

XDrawLine 
XDrawSegments 

XDrawString 
XDrawText 

XDrawStringl6 
XDrawText 16 

XPut Image 

XQueryBest Cursor 
XQueryBestSize 
XQueryBest Stipple 
XQueryBestTile 

XQueryColor 
XQueryColors 

XInitExtension 
XQueryExtension 

XLoadQueryFont 
XQueryKeymap 
XQueryPo inter 

XQueryText Extents 
XQueryTextExtentsl6 

XQueryTree 
XRecolor Cursor 
XReparentWindow 
XRotateBuffers 



Appendix B: Error Messages and Protocol Requests 



579 



Table B-2. Xlib Functions and Protocol Requests (continued) 



Protocol Request 



Xlib Function 



SendEvent 
SetAccessControl 

SetClipRectangles 

SetCloseDownMode 

SetDashes 

SetFontPath 

SetlnputFocus 

SetModifierMapping 

SetPointerMapping 

SetScreenSaver 

SetSelectionOwner 

StoreColors 

StoreNamedColor 

TranslateCoords 

UngrabButton 

UngrabKey 

UngrabKeyboard 

UngrabPointer 

UngrabServer 

UninstallColormap 

UnmapS ubwindows 

UnmapWindow 

WarpPointer 



XRotateWindowProperties 
XSendEvent 

XDisableAccessControl 

XEnableAccessControl 

XSetAccessControl 

XSetClipRect angles 

XSetCloseDownMode 

XSetDashes 

XSetFontPath 

XSetlnputFocus 

XSetModifierMapping 

XSetPointerMapping 

XSetScreenSaver 

XSet Select ionOwner 

XStoreColor 
XStoreColors 

XStoreNamedColor 

XTranslateCoordinates 

XUngrabButton 

XUngrabKey 

XUngrabKeyboard 

XUngrabPointer 

XUngrabServer 

XUninstallColormap 

XUnmapSubWindows 

XUnmapWindow 

XWarpPointer 



580 



Xlib Reference Manual 



c 

Macros 



Once you have successfully connected your application to an X server, you can obtain data 
from the Display structure associated with that display. The Xlib interface provides a 
number of useful C language macros and corresponding functions for other language bind 
ings which return data from the Display structure. 

The function versions of these macros have the same names as the macros except that the 
function forms begin with the letter "X." They use the same arguments. Using the macro 
versions is slightly more efficient in C because it eliminates function call overhead. 

In R3 and R4, a few new functions were added that access members of the Display struc 
ture. These are XDisplayMotionBufferSize, XResourceManagerString, 
XDisplayKeycodes, and XMaxRequestSize in R3 and XScreenNumber- 
OfScreen, XListDepths, and XListPixmapFormats in R4. Also, XVisual- 
iDFromVisual was added in R3 to extract the resource ID from a visual structure. 
XDisplayMotionBufferSize, XResourceManagerString, XMaxRequest 
Size, XScreenNumberOf Screen, and XVisuallDFromVisual are simple enough 
to have macro versions, but these were not provided. Nevertheless, we have chosen to cover 
them in this macro appendix instead of devoting a reference page to each. XDisplay 
Keycodes, XListDepths, and XListPixmapFormats are more complicated and 
therefore have their own reference pages; they are not covered here. 

For the purposes of this appendix, the macros are divided into four categories: Display mac 
ros, Image Format macros, Keysym Classification macros, and Resource Manager macros. 
The macros are listed alphabetically within each category. 

Note that some macros take as arguments an integer screen (scr_num) while others take a 
pointer to a Screen structure (scr_ptr). scr_num is returned by the Default- 
Screen macro and scr_ptr is returned by the Default ScreenOf Display macro. 



Appendix C: Macros 581 



C.1 Display Macros 



AllPlanes 



BlackPixel(di splay, scr_num) 



BlackPixelOf Screen (scr_ptr) 



CellsOf Screen (scr_ptr) 



Connect ionNumber(disp_Z ay) 



Return a value with all bits set suitable for use as 
a plane mask argument 

Return the black pixel value in the default color- 
map that is created by XOpenDisplay. 

Return the black pixel value in the default color- 
map of the specified screen. 

Return the number of colormap cells in the 
default colormap of the specified screen. 



Return a connection number for the specified 
display. On a UNIX system, this is the file 
descriptor of the connection. 

DefaultColormap(dispJay,scr_/ium) Return the default colormap for the specified 

screen. Most routine allocations of color should 
be made out of this colormap. 

DefauitCoiormapOf Screen (scr_ptr) Return the default colormap of the specified 

screen. 



DefaultDepth(dJsplay,scr_/iu/n) 



DefaultDepthOf Screen (scr_ptr) 
DefaultGC(dispJay,scr_/5u/n) 

DefaultGCOfScreen(scr ptr) 
DefaultRootWindow(dispIay) 

DefaultScreen(dispJay) 



Return the depth (number of planes) of the root 
window for the specified screen. Other depths 
may also be supported on this screen. See Vol 
ume One, Chapter 7, Color, or the reference 
pages for XMatchVisuallnfo and XGet- 
visuallnfo to find out how to determine 
what depths are available. 

Return the default depth of the specified screen. 

Return the default graphics context for the speci 
fied screen. 

Return the default graphics context (GC) of the 
specified screen. 

Return the ID of the root window on the default 
screen. Most applications should use Root- 
window instead so that screen selection is sup 
ported. 

Return the integer that was specified in the last 
segment of the string passed to XOpen 
Display or from the DISPLAY environment 
variable if NULL was used. For example, if the 
DISPLAY environment were Ogre : . 1, then 
Def aultScreen would return 1. 



582 



Xlib Reference Manual 



DefaultScreenOfDisplay(display) Return the default screen of the specified dis 
play. 



DefaultVisual(display,scr_/7um) 

DefaultVisualOf Screen (scr_ptr) 
DisplayCells (display, scr_num) 



DisplayHeight(display,scr_r3um) 



DisplayHeightMM(display,scr_/iu/n) 



DisplayOf Screen (scr_ptr) 



Display? lanes (displ ay, scr_n urn) 



Display String (display) 



DisplayWidth(d-isp_Zay,scr nu/n) 



DisplayWidthMM(dispIay,scr num) 



DoesBackingStore(scr_ptr) 



DoesSaveUnders (scr_ptr) 



Return a pointer to the default visual structure 
for the specified screen. 

Return the default visual of the specified screen. 

Return the maximum possible number of color- 
map cells on the specified screen. This macro is 
misnamed: it should have been Screen- 
Cells. 

Return the height in pixels of the screen. This 
macro is misnamed: it should have been 
ScreenHeight. 

Return the height in millimeters of the specified 
screen. This macro is misnamed: it should have 
been ScreenHeightMM. 

Return the display associated with the specified 
screen. 

Return the number of planes on the specified 
screen. This macro is misnamed: it should have 
been ScreenPlanes. 

Return the string that was passed to XOpen- 
Di splay when the current display was opened 
(or, if that was NULL, the value of the DISPLAY 
environment variable). This macro is useful in 
applications which invoke the fork system call 
and want to open a new connection to the same 
display from the child process. 

Return the width in pixels of the screen. This 
macro is misnamed: it should have been 
ScreenWidth. 

Return the width in millimeters of the specified 
screen. This macro is misnamed: it should have 
been ScreenWidthMM. 

Return a value indicating whether the screen 
supports backing stores. Values are When- 
Mapped, NotUsef ul, or Always. See Vol 
ume One, Section 4.3.5 for a discussion of the 
backing store. 

Return a Boolean value indicating whether the 
screen supports save unders. If True, the 
screen supports save unders. If False, the 
screen does not support save unders. See 



Appendix C: Macros 



583 



dpyno( display) 

EventMaskOf Screen (scr_ptr) 
He ightOf Screen (scr_ptr) 
HeightMMOf Screen (scr_ptr) 
Keyboard (display) 



LastKnownRequestProcessed 
(display) 



MaxCmapsOf Screen (scr_ptr) 
MinCmapsOf Screen(scr ptr) 
Next Request (display) 

PlanesOf Screen (scr_ptr) 
ProtocolRe vision (display) 
ProtocolVersion(display) 

QLength(display) 
RootWindow(display,scr num) 



Volume One, Section 4.3.6 for a discussion of 
the save under. 

Return the file descriptor of the connected dis 
play. On a UNIX system, you can then pass this 
returned file descriptor to the select(3) system 
call when your application program is driving 
more than one display at a time. 

Return the initial event mask for the root win 
dow of the specified screen. 

Return the height in pixels of the specified 
screen. 

Return the height in millimeters of the specified 
screen. 

Return the device ID for the main keyboard con 
nected to the display. 

Return the serial ID of the last known protocol 
request to have been issued. This can be useful 
in processing errors, since the serial number of 
failing requests are provided in the XError- 
Event structure. 

Return the maximum number of installed (hard 
ware) colormaps supported by the specified 
screen. 

Return the minimum number of installed (hard 
ware) colormaps supported by the specified 
screen. 

Return the serial ID of the next protocol request 
to be issued. This can be useful in processing 
errors, since the serial number of failing requests 
are provided in the XErrorEvent structure. 

Return the number of planes in the specified 
screen. 

Return the minor protocol revision number of 
the X server. 

Return the version number of the X protocol 
associated with the connected display. This is 
currently 11. 

Return the number of events that can be queued 
by the specified display. 

Return the ID of the root window. This macro is 
necessary for routines that reference the root 



584 



Xlib Reference Manual 



RootWindowOf Screen (scr_ptr) 
ScreenCount( display) 
ScreenOf Display (disp_Zay,scr_/iim?) 
ServerVendor( display) 

VendorRe lease (display) 
WhitePixel(display,scr_/]U/n) 
WhitePixelOf Screen (scr_ptr) 

WidthOfScreen(scr_ptr) 
WidthMMOfScreen(scr_ptr) 

XDisplayMotionBufferSize (display) 

XMaxRequestSize(dispIay) 

XScreenNumberOf Screen (scr_ptr) 
XVisualIDFromVisual( visual) 



window or create a top-level window for an 
application. 

Return the ID of the root window of the speci 
fied screen. 

Return the number of available screens on a 
specified display. 

Return the specified screen of the specified dis 
play. 

Return a pointer to a null terminated string giv 
ing some identification of the owner of the X 
server implementation. 

Return a number related to the release of the X 
server by the vendor. 

Return the white pixel value in the default color- 
map that is created by XOpenDi splay. 

Return the white pixel value in the default color- 
map of the specified screen. 

Return the width of the specified screen. 

Return the width of the specified screen in milli 
meters. 



Return an unsigned long value containing 
the size of the motion buffer on the server. If 
this function returns zero, the server has no 
motion history buffer. 

Return a long value containing the maximum 
size of a protocol request for the specified server, 
in units of four bytes. 

Return the integer screen number corresponding 
to the specified pointer to a Screen structure. 

Returns the ID of the server resource associated 
with a visual structure. This is useful when stor 
ing standard colormap properties. 



Appendix C: Macros 



585 



C.2 Image Format Macros 

BitmapBitOrder(display) Within each BitmapUnit, the leftmost bit in the bit 
map as displayed on the screen is either the least or the 
most significant bit in the unit. Returns LSBFirst or 
MSBFirst. 

BitmapPad(display) Each scan line must be padded to a multiple of bits speci 

fied by the value returned by this macro. 

BitmapUnit (display) Returns the size of a bitmap s unit. The scan line is quan 

tized (calculated) in multiples of this value. 

imageByteOrder(dispiay) Returns the byte order for images required by the server 

for each scan line unit in XY format (bitmap) or for each 
pixel value in Z format. Values are LSBFirst or 
MSBFirst. 



C.3 Keysym Classification Macros 

You may want to test if a keysym of the defined set (XK_MISCELLANY) is, for example, on 
the key pad or the function keys. You can use the keysym macros to perform the following 
tests: 

I sCursorKey (keysym) Return True if the keysym represents a cursor key. 

isFunctionKeyUeysym) Return True if the keysym represents a function key. 

isKeypadKeyUeysym) Return True if the keysym represents a key pad. 

I sMiscFunctionKey( keysym) Return True if the keysym represents a miscellaneous 

function key. 

isModif ierKey (keysym) Return True if the keysym represents a modifier key. 

i sPFKey (keysym) Return True if the keysym represents a PF key. 



C.4 Resource Manager Macros 

These macros convert from strings to quarks and quarks to strings. They are used by the 
resource manager. Note that they do not follow the normal naming conventions for macros, 
since they begin with an X. 

XrmStringToName(stri/ig) Convert String to XrmName. Same as XString- 

ToQuark. 

XrmStringToClass(string) Convert String to XrmClass. Same as XString- 

ToQuark. 



556 Xlib Reference Manual 



XrmStringToRepresentation Convert String to XrmRepresentation. Same as 



(string) 
XrmNameToString(/ja/ne) 

XrmClassToString(class) 



XStringToQuark. 

Convert XrmName to string. Same as XrmQuark- 
ToString. 

Convert XrmClass to string. Same as XrmQuark- 
ToString. 

XrmRepresentationToString Convert XrmRepresentation to String. Same as 
(type) XrmQuarkToString. 

XResourceManagerString( display) 

Return a pointer to the resource database string stored 
in the Display structure. This string is read from the 
RESOURCE_MANAGER property on the root window; 
this property is normally set by the xrdb client. 



Appendix C: Macros 



587 



D 

The Color Database 



The color database translates color name strings into RGB values. It is used by XParse- 
Color, XLookupColor, and xstoreNamedColor. These routines make it easier to 
allow the user to specify color names. Use of these names for routine color allocation of 
read-only colorcells is encouraged since this increases the chance of sharing colorcells and 
thereby makes the colormap go further before running out of colorcells. The location in the 
file system of the text version of the color database is an implementation detail, but by 
default on a UNIX system it is lusrlliblXlllrgb.txt. 

It should be noted that while a sample color database is provided with the standard XI 1 dis 
tribution, it is not specified as an X Consortium standard and is not part of the X Protocol or 
Xlib. Therefore, it is permissible for server vendors to change the color names, although they 
will probably only add color names. Furthermore, hardware vendors can change the RGB 
values for each display hardware to achieve the proper "gamma correction" so that the colors 
described by the name really generate that color. 

The RGB values in the R3 database were originally tuned for the DEC VT240 display. The 
color that appears on a Sun system given these RGB values for "pink," for example, looks 
more like light burgundy. In R4 a new RGB color database is provided, which provides 
many more color names and provides values that generate colors that match their names on 
more monitors. 

Each color name in the database may be used in the form shown or in mixed case, with initial 
capitals and all spaces eliminated. Table D-l (see next page) shows the R3 database, and 
Table D-2 shows the R4 database. 



Appendix D: Colors 589 



Table D- 1. The R3 Color Database 



English Words 


Red 


Green 


Blue 


English Words 


Red 


Green 


Blue 


English Words 


Red 


Green 


Blue 


medium aquamarine 


50 


204 


153 


aquamarine 


112 


219 


147 


English Words 


Red 


Green 


Blue 


black 











medium blue 


50 


50 


204 


blue 








255 


medium forest green 


107 


142 


35 


blue violet 


159 


95 


159 


medium goldenrod 


234 


234 


173 


brown 


165 


42 


42 


medium orchid 


147 


112 


219 


cadet blue 


95 


159 


159 


medium sea green 


66 


111 


66 


coral 


255 


127 





medium slate blue 


127 





255 


cornflower blue 


66 


66 


111 


medium spring green 


127 


255 





cyan 





255 


255 


medium turquoise 


112 


219 


219 


dark green 


47 


79 


47 


medium violet red 


219 


112 


147 


dark olive green 


79 


79 


47 


midnight blue 


47 


47 


79 


dark orchid 


153 


50 


204 


navy 


35 


35 


142 


dark slate blue 


107 


35 


142 


navy blue 


35 


35 


142 


dark slate gray 


47 


79 


79 


orange 


204 


50 


50 


dark slate grey 


47 


79 


79 


orange red 


255 





127 


dark turquoise 


112 


147 


219 


orchid 


219 


112 


219 


dim gray 


84 


84 


84 


pale green 


143 


188 


143 


dim grey 


84 


84 


84 


pink 


188 


143 


143 


firebrick 


142 


35 


35 


plum 


234 


173 


234 


forest green 


35 


142 


35 


purple 


176 





255 


gold 


204 


127 


50 


red 


255 








goldenrod 


219 


219 


112 


salmon 


111 


66 


66 


gray 


192 


192 


192 


sea green 


35 


142 


107 


green 





255 





sienna 


142 


107 


35 


green yellow 


147 


219 


112 


sky blue 


50 


153 


204 


grey 


192 


192 


192 


slate blue 





127 


255 


indian red 


79 


47 


47 


spring green 





255 


127 


khaki 


159 


159 


95 


steel blue 


35 


107 


142 


light blue 


191 


216 


216 


tan 


219 


147 


112 


light gray 


168 


168 


168 


thistle 


216 


191 


216 


light grey 


168 


168 


168 


turquoise 


173 


234 


234 


light steel blue 


143 


143 


188 


violet 


79 


47 


79 


lime green 


50 


204 


50 


violet red 


204 


50 


153 


magenta 


255 





255 


wheat 


216 


216 


191 


maroon 


142 


35 


107 


white 


252 


252 


252 


yellow 


255 


255 





yellow green 


153 


204 


50 



*Also defined are the color names "grayO" through "graylOO", spelled with an V or an "a". "grayO" is black and 
"gray 100" is white. 



530 



Xlib Reference Manual 



Table D-2. The R4 Color Database 



English Words 


Red 


Green 


Blue 


English Words 


Red 


Green 


Blue 


snow 


255 


250 


250 


black 











ghost white 


248 


248 


255 


dark slate gray 


47 


79 


79 


GhostWhite 


248 


248 


255 


DarkSlateGray 


47 


79 


79 


white smoke 


245 


245 


245 


dark slate grey 


47 


79 


79 


WhiteSmoke 


245 


245 


245 


DarkSlateGrey 


47 


79 


79 


gainsboro 


220 


220 


220 


dim gray 


105 


105 


105 


floral white 


255 


250 


240 


DimGray 


105 


105 


105 


Floral White 


255 


250 


240 


dim grey 


105 


105 


105 


old lace 


253 


245 


230 


DimGrey 


105 


105 


105 


OldLace 


253 


245 


230 


slate gray 


112 


128 


144 


linen 


250 


240 


230 


SlateGray 


112 


128 


144 


antique white 


250 


235 


215 


slate grey 


112 


128 


144 


AntiqueWhite 


250 


235 


215 


SlateGrey 


112 


128 


144 


papaya whip 


255 


239 


213 


light slate gray 


119 


136 


153 


PapayaWhip 


255 


239 


213 


LightSlateGray 


119 


136 


153 


blanched almond 


255 


235 


205 


light slate grey 


119 


136 


153 


BlanchedAlmond 


255 


235 


205 


LightSlateGrey 


119 


136 


153 


bisque 


255 


228 


196 


gray 


192 


192 


192 


peach puff 


255 


218 


185 


grey 


192 


192 


192 


PeachPuff 


255 


218 


185 


light grey 


211 


211 


211 


navajo white 


255 


222 


173 


LightGrey 


211 


211 


211 


NavajoWhite 


255 


222 


173 


light gray 


211 


211 


211 


moccasin 


255 


228 


181 


LightGray 


211 


211 


211 


cornsilk 


255 


248 


220 


midnight blue 


25 


25 


112 


ivory 


255 


255 


240 


MidnightBlue 


25 


25 


112 


lemon chiffon 


255 


250 


205 


navy 








128 


LemonChiffon 


255 


250 


205 


navy blue 








128 


seasheU 


255 


245 


238 


NavyBlue 








128 


honeydew 


240 


255 


240 


cornflower blue 


100 


149 


237 


mint cream 


245 


255 


250 


ComflowerBlue 


100 


149 


237 


MintCream 


245 


255 


250 


dark slate blue 


72 


61 


139 


azure 


240 


255 


255 


DarkSlateBlue 


72 


61 


139 


alice blue 


240 


248 


255 


slate blue 


106 


90 


205 


AliceBlue 


240 


248 


255 


SlateBlue 


106 


90 


205 


lavender 


230 


230 


250 


medium slate blue 


123 


104 


238 


lavender blush 


255 


240 


245 


MediumSlateBlue 


123 


104 


238 


LavenderBlush 


255 


240 


245 


light slate blue 


132 


112 


255 


misty rose 


255 


228 


225 


LightSlateBlue 


132 


112 


255 


MistyRose 


255 


228 


225 


medium blue 








205 


white 


255 


255 


255 


MediumBlue 








205 



Appendix D: Colors 



591 



Table D-2. The R4 Color Database (continued) 



English Words 


Red 


Green 


Blue 


English Words 


Red 


Green 


Blue 


royal blue 


65 


105 


225 


sea green 


46 


139 


87 


RoyalBlue 


65 


105 


225 


SeaGreen 


46 


139 


87 


blue 








255 


medium sea green 


60 


179 


113 


dodger blue 


30 


144 


255 


MediumSeaGreen 


60 


179 


113 


DodgerBlue 


30 


144 


255 


light sea green 


32 


178 


170 


deep sky blue 





191 


255 


LightSeaGreen 


32 


178 


170 


DeepSkyBlue 





191 


255 


pale green 


152 


251 


152 


sky blue 


135 


206 


235 


PaleGreen 


152 


251 


152 


SkyBlue 


135 


206 


235 


spring green 





255 


127 


light sky blue 


135 


206 


250 


SpringGreen 





255 


127 


LightSkyBlue 


135 


206 


250 


lawn green 


124 


252 





steel blue 


70 


130 


180 


LawnGreen 


124 


252 





SteelBlue 


70 


130 


180 


green 





255 





light steel blue 


176 


196 


222 


chartreuse 


127 


255 





LightS teelBlue 


176 


196 


222 


medium spring green 





250 


154 


light blue 


173 


216 


230 


MediumSpringGreen 





250 


154 


LightBlue 


173 


216 


230 


green yellow 


173 


255 


47 


powder blue 


176 


224 


230 


GreenYellow 


173 


255 


47 


PowderBlue 


176 


224 


230 


lime green 


50 


205 


50 


pale turquoise 


175 


238 


238 


LimeGreen 


50 


205 


50 


PaleTurquoise 


175 


238 


238 


yellow green 


154 


205 


50 


dark turquoise 





206 


209 


YellowGreen 


154 


205 


50 


DarkTurquoise 





206 


209 


forest green 


34 


139 


34 


medium turquoise 


72 


209 


204 


ForestGreen 


34 


139 


34 


MediumTurquoise 


72 


209 


204 


olive drab 


107 


142 


35 


turquoise 


64 


224 


208 


OliveDrab 


107 


142 


35 


cyan 





255 


255 


dark khaki 


189 


183 


107 


light cyan 


224 


255 


255 


DarkKhaki 


189 


183 


107 


LightCyan 


224 


255 


255 


khaki 


240 


230 


140 


cadet blue 


95 


158 


160 


pale goldenrod 


238 


232 


170 


CadetBlue 


95 


158 


160 


PaleGoldenrod 


238 


232 


170 


medium aquamarine 


102 


205 


170 


light goldenrod yellow 


250 


250 


210 


MediumAquamarine 


102 


205 


170 


LightGoldenrodYellow 


250 


250 


210 


aquamarine 


127 


255 


212 


light yellow 


255 


255 


224 


dark green 





100 





LightYellow 


255 


255 


224 


DarkGreen 





100 





yellow 


255 


255 





dark olive green 


85 


107 


47 


gold 


255 


215 





DarkOliveGreen 


85 


107 


47 


light goldenrod 


238 


221 


130 


dark sea green 


143 


188 


143 


LightGoldenrod 


238 


221 


130 


DarkSeaGreen 


143 


188 


143 


goldenrod 


218 


165 


32 



Xlib Reference Manual 



Table D-2. The R4 Color Database (continued) 



English Words 


Red 


Green 


Blue 


English Words 


Red 


Green 


Blue 


dark goldenrod 


184 


134 


11 


LightPink 


255 


182 


193 


DarkGoldenrod 


184 


134 


11 


pale violet red 


219 


112 


147 


rosy brown 


188 


143 


143 


PaleVioletRed 


219 


112 


147 


RosyBrown 


188 


143 


143 


maroon 


176 


48 


96 


Indian red 


205 


92 


92 


medium violet red 


199 


21 


133 


IndianRed 


205 


92 


92 


MediumVioletRed 


199 


21 


133 


saddle brown 


139 


69 


19 


violet red 


208 


32 


144 


SaddleBrown 


139 


69 


19 


VioletRed 


208 


32 


144 


sienna 


160 


82 


45 


magenta 


255 





255 


peru 


205 


133 


63 


violet 


238 


130 


238 


burlywood 


222 


184 


135 


plum 


221 


160 


221 


beige 


245 


245 


220 


orchid 


218 


112 


214 


wheat 


245 


222 


179 


medium orchid 


186 


85 


211 


sandy brown 


244 


164 


96 


MediumOrchid 


186 


85 


211 


SandyBrown 


244 


164 


96 


dark orchid 


153 


50 


204 


tan 


210 


180 


140 


DarkOrchid 


153 


50 


204 


chocolate 


210 


105 


30 


dark violet 


148 





211 


firebrick 


178 


34 


34 


DarkViolet 


148 





211 


brown 


165 


42 


42 


blue violet 


138 


43 


226 


dark salmon 


233 


150 


122 


BlueViolet 


138 


43 


226 


DarkSalmon 


233 


150 


122 


purple 


160 


32 


240 


salmon 


250 


128 


114 


medium purple 


147 


112 


219 


light salmon 


255 


160 


122 


MediumPurple 


147 


112 


219 


LightS almon 


255 


160 


122 


thistle 


216 


191 


216 


orange 


255 


165 





snowl 


255 


250 


250 


dark orange 


255 


140 





snow2 


238 


233 


233 


DarkOrange 


255 


140 





snow3 


205 


201 


201 


coral 


255 


127 


80 


snow4 


139 


137 


137 


light coral 


240 


128 


128 


seashelll 


255 


245 


238 


LightCoral 


240 


128 


128 


seashel!2 


238 


229 


222 


tomato 


255 


99 


71 


seashelD 


205 


197 


191 


orange red 


255 


69 





seashel!4 


139 


134 


130 


OrangeRed 


255 


69 





AntiqueWhitel 


255 


239 


219 


red 


255 








AntiqueWhite2 


238 


223 


204 


hot pink 


255 


105 


180 


AntiqueWhite3 


205 


192 


176 


HotPink 


255 


105 


180 


AntiqueWhite4 


139 


131 


120 


deep pink 


255 


20 


147 


bisque 1 


255 


228 


196 


DeepPink 


255 


20 


147 


bisque2 


238 


213 


183 


pink 


255 


192 


203 


bisque3 


205 


183 


158 


light pink 


255 


182 


193 


bisque4 


139 


125 


107 



Appendix D: Colors 



593 



Table D-2. The R4 Color Database (continued) 



English Words 


Red 


Green 


Blue 


English Words 


Red 


Green 


Blue 


PeachPuffl 


255 


218 


185 


LightPink 


255 


182 


193 


PeachPuffZ 


238 


203 


173 


pale violet red 


219 


112 


147 


PeachPufO 


205 


175 


149 


PaleVioletRed 


219 


112 


147 


PeachPuff4 


139 


119 


101 


maroon 


176 


48 


96 


NavajoWhitel 


255 


222 


173 


medium violet red 


199 


21 


133 


NavajoWhite2 


238 


207 


161 


MediumVioletRed 


199 


21 


133 


NavajoWhiteS 


205 


179 


139 


violet red 


208 


32 


144 


NavajoWhite4 


139 


121 


94 


VioletRed 


208 


32 


144 


LemonChiffonl 


255 


250 


205 


magenta 


255 





255 


LemonChiffon2 


238 


233 


191 


violet 


238 


130 


238 


LemonChiffonS 


205 


201 


165 


plum 


221 


160 


221 


LemonChiffon4 


139 


137 


112 


orchid 


218 


112 


214 


cornsilkl 


255 


248 


220 


medium orchid 


186 


85 


211 


cornsilk2 


238 


232 


205 


MediumOrchid 


186 


85 


211 


comsilk3 


205 


200 


177 


dark orchid 


153 


50 


204 


cornsilk4 


139 


136 


120 


DarkOrchid 


153 


50 


204 


ivory 1 


255 


255 


240 


dark violet 


148 





211 


ivory2 


238 


238 


224 


DarkViolet 


148 





211 


ivoryS 


205 


205 


193 


blue violet 


138 


43 


226 


ivory4 


139 


139 


131 


BlueViolet 


138 


43 


226 


honeydewl 


240 


255 


240 


purple 


160 


32 


240 


honeydew2 


224 


238 


224 


medium purple 


147 


112 


219 


honeydewS 


193 


205 


193 


MediumPurple 


147 


112 


219 


honeydew4 


131 


139 


131 


thistle 


216 


191 


216 


LavenderBlushl 


255 


240 


245 


snowl 


255 


250 


250 


LavenderBlush2 


238 


224 


229 


snow2 


238 


233 


233 


LavenderBlushS 


205 


193 


197 


snow3 


205 


201 


201 


LavenderBlush4 


139 


131 


134 


snow4 


139 


137 


137 


MistyRosel 


255 


228 


225 


seashelll 


255 


245 


238 


MistyRose2 


238 


213 


210 


seashel!2 


238 


229 


222 


MistyRose3 


205 


183 


181 


seashel!3 


205 


197 


191 


MistyRose4 


139 


125 


123 


seashel!4 


139 


134 


130 


azure 1 


240 


255 


255 


AntiqueWhitel 


255 


239 


219 


azure2 


224 


238 


238 


AntiqueWhite2 


238 


223 


204 


azureS 


193 


205 


205 


AntiqueWhite3 


205 


192 


176 


azure4 


131 


139 


139 


AntiqueWhite4 


139 


131 


120 


SlateBluel 


131 


111 


255 


bisque 1 


255 


228 


196 


SlateBlue2 


122 


103 


238 


bisque2 


238 


213 


183 


SlateBlueS 


105 


89 


205 


bisque3 


205 


183 


158 


SlateBlue4 


71 


60 


139 


bisque4 


139 


125 


107 



Xlib Reference Manual 



Table D-2. The R4 Color Database (continued) 



English Words 


Red 


Green 


Blue 


English Words 


Red 


Green 


Blue 


RoyalBluel 


72 


118 


255 


LightCyanl 


224 


255 


255 


RoyalBlue2 


67 


110 


238 


LightCyan2 


209 


238 


238 


RoyalBlueS 


58 


95 


205 


LightCyan3 


180 


205 


205 


RoyalBlue4 


39 


64 


139 


LightCyan4 


122 


139 


139 


bluel 








255 


PaleTurquoisel 


187 


255 


255 


blue2 








238 


PaleTurquoise2 


174 


238 


238 


blue3 








205 


PaleTurquoiseS 


150 


205 


205 


blue4 








139 


PaleTurquoise4 


102 


139 


139 


DodgerBluel 


30 


144 


255 


CadetBluel 


152 


245 


255 


DodgerBlue2 


28 


134 


238 


CadetBlue2 


142 


229 


238 


DodgerBlueS 


24 


116 


205 


CadetBlue3 


122 


197 


205 


DodgerBlue4 


16 


78 


139 


CadetBlue4 


83 


134 


139 


SteelBluel 


99 


184 


255 


turquoise 1 





245 


255 


SteelBlue2 


92 


172 


238 


turquoise2 





229 


238 


SteelBlueS 


79 


148 


205 


turquoise3 





197 


205 


SteelBlue4 


54 


100 


139 


turquoise4 





134 


139 


DeepSkyBluel 





191 


255 


cyanl 





255 


255 


DeepSkyBlue2 





178 


238 


cyan2 





238 


238 


DeepSkyBlue3 





154 


205 


cyan3 





205 


205 


DeepSkyBlue4 





104 


139 


cyan4 





139 


139 


SkyBluel 


135 


206 


255 


DarkSlateGrayl 


151 


255 


255 


SkyBlue2 


126 


192 


238 


DarkSlateGray2 


141 


238 


238 


SkyBlue3 


108 


166 


205 


DarkSlateGray3 


121 


205 


205 


SkyBlue4 


74 


112 


139 


DarkSlateGray4 


82 


139 


139 


LightSkyBluel 


176 


226 


255 


aquamarine 1 


127 


255 


212 


LightSkyBlue2 


164 


211 


238 


aquamarine2 


118 


238 


198 


LightSkyBlueS 


141 


182 


205 


aquamarines 


102 


205 


170 


LightSkyBlue4 


96 


123 


139 


aquamarine4 


69 


139 


116 


SlateGrayl 


198 


226 


255 


DarkSeaGreenl 


193 


255 


193 


SlateGray2 


185 


211 


238 


DarkSeaGreen2 


180 


238 


180 


SlateGrayS 


159 


182 


205 


DarkSeaGreenS 


155 


205 


155 


SlateGray4 


108 


123 


139 


DarkSeaGreen4 


105 


139 


105 


LightS teelBluel 


202 


225 


255 


SeaGreenl 


84 


255 


159 


Lights teelBlue2 


188 


210 


238 


ScaGreen2 


78 


238 


148 


LightSteelBlue3 


162 


181 


205 


SeaGreen3 


67 


205 


128 


LightS teelBlue4 


110 


123 


139 


SeaGreen4 


46 


139 


87 


LightBluel 


191 


239 


255 


PaleGreenl 


154 


255 


154 


LightBlue2 


178 


223 


238 


PaleGreen2 


144 


238 


144 


LightBlueS 


154 


192 


205 


PaleGreen3 


124 


205 


124 


LightBlue4 


104 


131 


139 


PaleGreen4 


84 


139 


84 



Appendix D: Colors 



595 



Table D-2. The R4 Color Database (continued) 



English Words 


Red 


Green 


Blue 


English Words 


Red 


Green 


Blue 


SpringGreenl 





255 


127 


goldenrodl 


255 


193 


37 


SpringGreen2 





238 


118 


goldenrod2 


238 


180 


34" 


SpringGreenS 





205 


102 


goldenrod3 


205 


155 


29 


SpringGreen4 





139 


69 


goldenrod4 


139 


105 


20 


green 1 





255 





DarkGoldenrodl 


255 


185 


15 


green2 





238 





DarkGoldenrod2 


238 


173 


14 


green3 





205 





DarkGoldenrod3 


205 


149 


12 


green4 





139 





DarkGoldenrod4 


139 


101 


8 


chartreuse 1 


127 


255 





RosyBrownl 


255 


193 


193 


chartreuse2 


118 


238 





RosyBrown2 


238 


180 


180 


chartreuse3 


102 


205 





RosyBrown3 


205 


155 


155 


chartreuse4 


69 


139 





RosyBrown4 


139 


105 


105 


OliveDrabl 


192 


255 


62 


IndianRedl 


255 


106 


106 


OliveDrab2 


179 


238 


58 


IndianRed2 


238 


99 


99 


OliveDrabS 


154 


205 


50 


IndianRed3 


205 


85 


85 


OliveDraM 


105 


139 


34 


IndianRed4 


139 


58 


58 


DarkOliveGreenl 


202 


255 


112 


sienna 1 


255 


130 


71 


DarkOliveGreen2 


188 


238 


104 


sienna2 


238 


121 


66 


DarkOliveGreenS 


162 


205 


90 


sienna3 


205 


104 


57 


DarkOliveGreen4 


110 


139 


61 


sienna4 


139 


71 


38 


khaki 1 


255 


246 


143 


burly wood 1 


255 


211 


155 


khaki2 


238 


230 


133 


burlywood2 


238 


197 


145 


khakiS 


205 


198 


115 


burlywood3 


205 


170 


125 


khaki4 


139 


134 


78 


burlywood4 


139 


115 


85 


LightGoldenrodl 


255 


236 


139 


wheat 1 


255 


231 


186 


LightGoldenrod2 


238 


220 


130 


wheat2 


238 


216 


174 


LightGoldenrod3 


205 


190 


112 


wheat3 


205 


186 


150 


LightGoldenrod4 


139 


129 


76 


wheat4 


139 


126 


102 


LightYellowl 


255 


255 


224 


tanl 


255 


165 


79 


LightYellow2 


238 


238 


209 


tan2 


238 


154 


73 


LightYellowS 


205 


205 


180 


tan3 


205 


133 


63 


LightYellow4 


139 


139 


122 


tan4 


139 


90 


43 


yellow 1 


255 


255 





chocolate 1 


255 


127 


36 


yellow2 


238 


238 





chocolate2 


238 


118 


33 


yellow3 


205 


205 





chocolates 


205 


102 


29 


yellow4 


139 


139 





chocolate4 


139 


69 


19 


goldl 


255 


215 





firebrickl 


255 


48 


48 


gold2 


238 


201 





firebrick2 


238 


44 


44 


gold3 


205 


173 





firebricks 


205 


38 


38 


gold4 


139 


117 





firebrick4 


139 


26 


26 



596 



Xlib Reference Manual 



Table D-2. The R4 Color Database (continued) 



English Words 


Red 


Green 


Blue 


English Words 


Red 


Green 


Blue 


brown 1 


255 


64 


64 


HotPinkl 


255 


110 


180 


brown2 


238 


59 


59 


HotPink2 


238 


106 


167 


brown3 


205 


51 


51 


HotPink3 


205 


96 


144 


brown4 


139 


35 


35 


HotPink4 


139 


58 


98 


salmon 1 


255 


140 


105 


pinkl 


255 


181 


197 


salmon2 


238 


130 


98 


pink2 


238 


169 


184 


salmonS 


205 


112 


84 


pink3 


205 


145 


158 


salmon4 


139 


76 


57 


pink4 


139 


99 


108 


LightSalmonl 


255 


160 


122 


LightPinkl 


255 


174 


185 


LightS almon2 


238 


149 


114 


LightPink2 


238 


162 


173 


LightSalmonS 


205 


129 


98 


LightPink3 


205 


140 


149 


LightSalmon4 


139 


87 


66 


LightPink4 


139 


95 


101 


orangel 


255 


165 





PaleVioletRedl 


255 


130 


171 


orange2 


238 


154 





PaleVioletRed2 


238 


121 


159 


orangeS 


205 


133 





PaleVioletRed3 


205 


104 


137 


orange4 


139 


90 





PaleVioletRed4 


139 


71 


93 


DarkOrangel 


255 


127 





maroon 1 


255 


52 


179 


DarkOrange2 


238 


118 





maroon2 


238 


48 


167 


DarkOrangeS 


205 


102 





maroon3 


205 


41 


144 


DarkOrange4 


139 


69 





maroon4 


139 


28 


98 


coral 1 


255 


114 


86 


VioletRedl 


255 


62 


150 


cora!2 


238 


106 


80 


VioletRed2 


238 


58 


140 


cora!3 


205 


91 


69 


VioletRed3 


205 


50 


120 


cora!4 


139 


62 


47 


VioletRed4 


139 


34 


82 


tomato 1 


255 


99 


71 


magenta 1 


255 





255 


tomato2 


238 


92 


66 


magenta2 


238 





238 


tomatoS 


205 


79 


57 


magenta3 


205 





205 


tomato4 


139 


54 


38 


magenta4 


139 





139 


OrangeRedl 


255 


69 





orchid 1 


255 


131 


250 


OrangeRed2 


238 


64 





orchid2 


238 


122 


233 


OrangeRedS 


205 


55 





orchid3 


205 


105 


201 


OrangeRed4 


139 


37 





orchid4 


139 


71 


137 


redl 


255 








pluml 


255 


187 


255 


red2 


238 








plum2 


238 


174 


238 


red3 


205 








plum3 


205 


150 


205 


red4 


139 








plum4 


139 


102 


139 


DeepPinkl 


255 


20 


147 


MediumOrchidl 


224 


102 


255 


DeepPink2 


238 


18 


137 


MediumOrchid2 


209 


95 


238 


DeepPink3 


205 


16 


118 


MediumOrchidS 


180 


82 


205 


DeepPink4 


139 


10 


80 


MediumOrchid4 


122 


55 


139 



Appendix D: Colors 



597 



Table D-2. The R< 
English Words 


t Color L 
Red 


database* 
Green 


(continued) 
Blue 


DarkOrchidl 


191 


62 


255 


DarkOrchid2 


178 


58 


238 


DaikOrchidS 


154 


50 


205 


DarkOrchid4 


104 


34 


139 


purplel 


155 


48 


255 


purple2 


145 


44 


238 


purpleS 


125 


38 


205 


purple4 


85 


26 


139 


MediumPurplel 


171 


130 


255 


MediumPurple2 


159 


121 


238 


MediumPurpleS 


137 


104 


205 


MediumPurple4 


93 


71 


139 


thistlcl 


255 


225 


255 


thisUe2 


238 


210 


238 


thistleS 


205 


181 


205 


thistle4 


139 


123 


139 



VIV 100,speUedwithdc"or V. "gmyO" black and 



595 



Xlib Reference Manual 



Event Reference 



This appendix describes each event structure in detail and briefly shows how each event type 
is used. It covers the most common uses of each event type, the information contained in 
each event structure, how the event is selected, and the side effects of the event, if any. Each 
event is described on a separate reference page. 

Table E-l lists each event mask, its associated event types, and the associated structure defi 
nition. See Chapter 8, Events, of Volume One, Xlib Programming Manual, for more informa 
tion on events. 

Table E-1. Event Masks, Event Types, and Event Structures 



Event Mask 


Event Type 


Structure 


KeyPressMask 


KeyPress 


XKeyPressedEvent 


KeyReleaseMask 


KeyRelease 


XKeyReleasedEvent 


ButtonPressMask 


ButtonPress 


XButtonPressedEvent 


ButtonReleaseMask 


ButtonRe lease 


XButtonReleasedEvent 


Owner GrabButtonMask 


n/a 


n/a 


KeymapStateMask 


KeymapNotify 


XKeymapEvent 


PointerMotionMask 


MotionNotify 


XPointerMovedEvent 


PointerMotionHintMask 






ButtonMotionMask 






ButtonlMotionMask 






Button2MotionMask 






ButtonSMotionMask 






Button4MotionMask 






ButtonSMotionMask 






EnterWindowMask 


EnterNotify 


XEnterWindowEvent 


LeaveWindowMask 


LeaveNotify 


XLeaveWindowEvent 


FocusChangeMask 


Focusln 


XFocusInEvent 




FocusOut 


XFocusOut Event 



Appendix E: Event Reference 



599 



Table E-1. Event Masks, Event Types, and Event Structures (continued) 



Event Mask 


Event Type 


Structure 


ExposureMask 
selected in GC by 

graphics expose member 


Expose 

GraphicsExpose 
NoExpose 


XExposeEvent 

XGraphicsExposeEvent 
XNoExposeEvent 


ColormapChangeMask 


ColormapNotify 


XColormapEvent 


PropertyChangeMask 


PropertyNotify 


XPropertyEvent 


VisibilityChangeMask 


VisibilityNotify 


XVisibilityEvent 


ResizeRedirectMask 


ResizeRequest 


XResizeRequestEvent 


StructureNotifyMask 


CirculateNotify 
ConfigureNotify 
DestroyNotify 
GravityNotify 
MapNotify 
ReparentNotify 
UnmapNotify 


XCirculateEvent 
XConfigureEvent 
XDestroyWindowEvent 
XGravityEvent 
XMapEvent 
XReparent Event 
XUnmapEvent 


SubstructureNotifyMask 


CirculateNotify 
ConfigureNotify 
CreateNotify 
DestroyNotify 
GravityNotify 
MapNotify 
ReparentNotify 
UnmapNotify 


XCirculateEvent 
XConfigureEvent 
XCreateWindowEvent 
XDestroyWindowEvent 
XGravityEvent 
XMapEvent 
XReparentEvent 
XUnmapEvent 


Subs tructureRedirect Mask 


CirculateRequest 
Conf igureRequest 
MapRequest 


XCirculateRequestEvent 
XConf igureRequestEvent 
XMapRequest Event 


(always selected) 


MappingNotify 


XMappingEvent 


(always selected) 


ClientMessage 


XClientMessageEvent 


(always selected) 


SelectionClear 


XSetSelectClearEvent 


(always selected) 


SelectionNotify 


XSelectionEvent 


(always selected) 


Select ionRequest 


XSelectionRequestEvent 



600 



Xlib Reference Manual 



E.1 Meaning of Common Structure Elements 

Example E-l shows the XEvent union and a simple event structure that is one member of 
the union. Several of the members of this structure are present in nearly every event struc 
ture. They are described here before we go into the event-specific members (see also Sec 
tion 8.2.2 of Volume One, Xlib Programming Manual). 



Example E-1. XEvent union and XAnyEvent structure 



typedef union _XEvent { 

int type; 

XAnyEvent xany; 

XButtonEvent xbutton; 

XCirculateEvent xcirculate; 

XCirculateRequestEvent xcirculaterequest; 

XClientMessageEvent xclient; 

XColormapEvent xcolormap; 

XConf igureEvent xconfigure; 

XConfigureRequestEvent xconf igurerequest; 

XCr eat eWindowE vent xcreatewindow; 

XDestroyWindowEvent xdestroy window; 

XCrossingEvent xcrossing; 

XExposeEvent xexpose; 

XFocusChangeEvent xfocus; 

XNoExposeEvent xnoexpose; 

XGraphicsExposeE vent xgraphicsexpose ; 

XGravityEvent xgravity; 

XKeymapEvent xkeymap; 

XKeyEvent xkey; 

XMapEvent xmap; 

XUnmapEvent xunmap; 

XMappingEvent xmapping; 

XMapRequestEvent xmaprequest; 

XMotionEvent xmotion; 

XPropertyEvent xproperty; 

XReparentEvent xreparent; 

XResizeRequest Event xresizerequest ; 

XSelectionClearEvent xselectionclear; 

XSelectionEvent xselection; 

XSelectionRequest Event xselectionrequest ; 

XVisibilityEvent xvisibility; 
} XEvent; 

typedef struct { 
int type; 

unsigned long serial; 
Bool send_event; 

Display *display; 
Window window; 

} XAnyEvent ; 



/* Must not be changed; first member */ 



/* # of last request processed by server */ 

/* True if this came from SendEvent 

* request */ 

/* Display the event was read from */ 

/* window on which event was requested 

* in event mask */ 



Appendix E: Event Reference 



601 



The first member of the XEvent union is the type of event When an event is received (with 
XNextEvent, for example), the application checks the type member in the XEvent 
union. Then the specific event type is known and the specific event structure (such as 
xbutton) is used to access information specific to that event type. 

Before the branching depending on the event type, only the XEvent union is used. After 
the branching, only the event structure which contains the specific information for each event 
type should be used in each branch. For example, if the XEvent union were called 
report, the report .xexpose structure should be used within the branch for Expose 
events. 

You will notice that each event structure also begins with a type member. This member is 
rarely used, since it is an identical copy of the type member in the XEvent union. 

Most event structures also have a window member. The only ones that do not are selection 
events (SelectionClear, SelectionNotify, and SelectionRequest) and 
events selected by the graphics_exposures member of the GC (GraphicsExpose 
and NoExpose). The window member indicates the event window that selected and 
received the event This is the window where the event arrives if it has propagated through 
the hierarchy as described in Section 8.3.2, of Volume One, Xlib Programming Manual. One 
event type may have two different meanings to an application, depending on which window 
it appears in. 

Many of the event structures also have a display and/or root member. The display 
member identifies the connection to the server that is active. The root member indicates 
which screen the window that received the event is linked to in the hierarchy. Most programs 
only use a single screen and therefore do not need to worry about the root member. The 
display member can be useful, since you can pass the display variable into routines by 
simply passing a pointer to the event structure, eliminating the need for a separate display 
argument 

All event structures include a serial member that gives the nur " er of the last protocol 
request processed by the server. This is useful in debugging, since an error can be detected 
by the server but not reported to the user (or programmer) until the next routine that gets an 
event That means several routines may execute successfully after the error occurs. The last 
request processed will often indicate the request that contained the error. 

All event structures also include a send_event flag, which, if True, indicates that the 
event was sent by XSendEvent (i.e., by another client rather than by the server). 

The following pages describe each event type in detail. The events are presented in alphabet 
ical order, each on a separate page. Each page describes the circumstances under which the 
event is generated, the mask used to select it, the structure itself, its members, and useful pro 
gramming notes. Note that the description of the structure members does not include those 
members common to many structures. If you need more information on these members, 
please refer to this introductory section. 



602 xiib Reference Manual 



xbutton- 



ButtonPress, ButtonRelease 



When Generated 

There are two types of pointer button events: ButtonPress and ButtonRelease. Both 
contain the same information. 

Select With 

May be selected separately, using ButtonPressMask and ButtonReleaseMask. 

XEvent Structure Name 

typedef union _XEvent { 

XButtonEvent xbutton; 
} XEvent; 



Event Structure 

typedef struct { 
int type; 

unsigned long serial; 
Bool send_event; 
Display ^display; 
Window window; 
Window root; 
Window subwindow; 
Time time; 
int x, y; 

int x_root, y_root; 
unsigned int state; 
unsigned int button; 
Bool same_screen; 
} XButtonEvent; 
typedef XButtonEvent 
typedef XButtonEvent 



/* of event */ 

/* # of last request processed by server */ 

/* True if this came from a SendEvent request * 

/* Display the event was read from */ 

/* event window it is reported relative to */ 

/* root window that the event occurred under */ 

/* child window */ 

/* when event occurred, in milliseconds */ 

/* pointer coordinates relative to receiving 

* window */ 

/* coordinates relative to root */ 

/* mask of all buttons and modifier keys */ 

/* button that triggered event */ 

/* same screen flag */ 

XButtonPressedEvent; 
XButtonReleasedEvent ; 



Event Structure Members 

subwindow If the source window is the child of the receiving window, then the 

subwindow member is set to the ID of that child. 



time 



The server time when the button event occurred, in milliseconds. Time 
is declared as unsigned long, so it wraps around when it reaches the 
maximum value of a 32-bit number (every 49.7 days). 

If the receiving window is on the same screen as the root window speci 
fied by root, then x and y are the pointer coordinates relative to the 
receiving window s origin. Otherwise, x and y are zero. 



Xlib Reference Manual 



603 



Button Press, Button Release 



(continued) 



xbutton 



When active button grabs and pointer grabs are in effect (see Section 9.4 
of Volume One, Xlib Programming Manual), the coordinates relative to 
the receiving window may not be within the window (they may be nega 
tive or greater than window height or width). 

x root, y_root The pointer coordinates relative to the root window which is an ancestor 
of the event window. If the pointer was on a different screen, these are 
zero. 

state The state of all the buttons and modifier keys just before the event, 

represented by a mask of the button and modifier key symbols: 

ButtonlMask, Button2Mask, ButtonSMask, Button4Mask, 
ButtonSMask, ControlMask, LockMask, ModlMask, Mod2- 
Mask, ModSMask, Mod4Mask, ModSMask, and ShiftMask. If a 
modifier key is pressed and released when no other modifier keys are 
held, the ButtonPress will have a state member of and the 
ButtonRelease will have a nonzero state member indicating that 
itself was held just before the event 

button A value indicating which button changed state to trigger this event One 

of the constants: Buttonl, Button2, Buttons, Button4, or 
Buttons. 

same_screen Indicates whether the pointer is currently on the same screen as this win 
dow. This is always True unless the pointer was actively grabbed 
before the automatic grab could take place. 

Notes 

Unless an active grab already exists or a passive grab on the button combination that was 
pressed already exists at a higher level in the hierarchy than where the ButtonPress 
occurred, an automatic active grab of the pointer takes place when a ButtonPress occurs. 
Because of the automatic grab, the matching ButtonRelease is sent to the same application 
that received the ButtonPress event If OwnerGrabButtonMask has been selected, the 
ButtonRelease event is delivered to the window which contained the pointer when the 
button was released, as long as that window belongs to the same client as the window in which 
the ButtonPress event occurred. If the ButtonRelease occurs outside of the client s 
windows or OwnerGrabButtonMask was not selected, the ButtonRelease is delivered 
to the window in which the ButtonPress occurred. The grab is terminated when all buttons 
are released. During the grab, the cursor associated with the grabbing window will track the 
pointer anywhere on the screen. 

If the application has invoked a passive button grab on an ancestor of the window in which the 
ButtonPress event occurs, then that grab takes precedence over the automatic grab, and the 
ButtonRelease will go to that window, or it will be handled normally by that client depend 
ing on the owner_events flag in the XGrabButton call. 



604 



Xlib Reference Manual 



xcirculate- 



CirculateNotify 



When Generated 

A CirculateNotify event reports a call to change the stacking order, and it includes 
whether the final position is on the top or on the bottom. This event is generated by 

XCirculateSubwindows, XCirculateSubwindowsDown, or XCirculate- 
SubwindowsUp. See also the CirculateRequest and Conf igureNotify reference 
pages. 

Select With 

This event is selected with StructureNotifyMask in the XSelectlnput call for the 
window to be moved or with SubstructureNotif yMask for the parent of the window to 
be moved. 

XEvent Structure Name 

typedef union _XEvent { 
. . . 

XCirculateEvent xcirculate; 

} XEvent; 



Event Structure 

typedef struct { 

int type; 

unsigned long serial, 

Bool send_event; 

Display *display; 

Window event; 

Window window; 

int place; 
} XCirculateEvent; 



/* # of last request processed by server */ 
/* True if this came from SendEvent request 
/* Display the event was read from */ 



/* PlaceOnTop, PlaceOnBottom */ 



*/ 



Event Structure Members 

event The window receiving the event If the event was selected by Structure 

NotifyMask, event will be the same as window. If the event was selected 
by SubstructureNotif yMask, event will be the parent of window. 

window The window that was restacked. 

place Either PlaceOnTop or PlaceOnBottom. Indicates whether the window was 

raised to the top or bottom of the stack. 



Xlib Reference Manual 



605 



CirculateRequest \ 



xcirculaterequest 



When Generated 

A CirculateRequest event reports when XCirculateSubwindows, XCirculate- 
SubwindowsDown, XCirculateSubwindowsUp, or XRestackWindows is called to 
change the stacking order of a group of children. 

This event differs from CirculateNotif y in that it delivers the parameters of the request 
before it is carried out This gives the client that selects this event (usually the window man 
ager) the opportunity to review the request in the light of its window management policy before 
executing the circulate request itself or to deny the request (CirculateNotify indicates 
the final outcome of the request) 

Select With 

This event is selected for the parent window with SubstructureRedirectMask. 

XEvent Structure Name 

typedef union _XEvent { 

XCirculateRequestEvent xcirculaterequest ; 
} XEvent; 

Event Structure 

typedef struct { 

int type; 

unsigned long serial; /* # of last request processed by server */ 

Bool send_event; /* True if this came from SendEvent request */ 

Display ^display; /* Display the event was read from */ 

Window parent; 

Window window; 

int place; /* PlaceOnTop, PlaceOnBottom */ 

} XCirculateRequestEvent; 

Event Structure Members 

parent The parent of the window that was restacked. This is the window that selected 
the event 

window The window being restacked. 

place PlaceOnTop or PlaceOnBottom. Indicates whether the window was to be 

placed on the top or on the bottom of the stacking order. 



Xlib Reference Manual 



xclient- 



J ClientMessage 



When Generated 

A ClientMessage event is sent as a result of a call to XSendEvent by a client to a particu 
lar window. Any type of event can be sent with XSendEvent, but it will be distinguished 
from normal events by the send_event member being set to True. If your program wants to 
be able to treat events sent with XSendEvent as different from normal events, you can read 
this member. 

Select With 

There is no event mask for ClientMessage events, and they are not selected with 
XSelect Input. Instead XSendEvent directs them to a specific window, which is given as 
a window ID: the PointerWindow or the inputFocus. 

XEvent Structure Name 

typedef union _XEvent { 

XClientMessageEvent xclient; 
} XEvent; 

Event Structure 

typedef struct { 
int type; 

unsigned long serial; /* # of last request processed by server */ 
Bool send_event; /* True if this came from SendEvent request */ 
Display ^display; /* Display the event was read from */ 
Window window; 
Atom message_type; 
int format; 
union { 

char b[20]; 

short s[10] ; 

long 1[5]; 
} data; 
} XClientMessageEvent; 

Event Structure Members 

message_type An atom that specifies how the data is to be interpreted by the receiving 
client. The X server places no interpretation on the type or the data, but 
it must be a list of 8-bit, 16-bit, or 32-bit quantities, so that the X server 
can correctly swap bytes as necessary. The data always consists of 
twenty 8-bit values, ten 16-bit values, or five 32-bit values, although 
each particular message might not make use of all of these values. 

format Specifies the format of the property specified by message_type. This 

will be on of the values 8, 1 6, or 32. 



Xlib Reference Manual 607 



ColormapNotify 



X 



xcolormap 



When Generated 

A ColormapNotify event reports when the colormap attribute of a window changes or 
when the colormap specified by the attribute is installed, uninstalled, or freed. This event is 
generated by XChangeWindowAttributes, XFreeColormap, XInstallColormap, 
and XUninstallColormap. 

Select With 

This event is selected with ColormapChangeMask. 

XEvent Structure Name 

typedef union _XEvent { 

XColormapEvent xcolormap; 
} XEvent; 



Event Structure 

typedef struct { 

int type; 

unsigned long serial, 

Bool send_event; 

Display ^display; 

Window window; 

Colormap colormap; 

Bool new; 

int state; 
} XColormapEvent; 



# of last request processed by server */ 
True if this came from SendEvent request */ 
Display the event was read from */ 

a colormap or None */ 

Colormaplnstalled, ColormapUninstalled */ 



Event Structure Members 

window The window whose associated colormap or attribute changes. 

colormap The colormap associated with the window, either a colormap ID or the constant 
None. It will be None only if this event was generated due to an XFree 
Colormap call. 

new True when the colormap attribute has been changed, or False when the color- 

map is installed or uninstalled. 

state Either Colormaplnstalled or ColormapUninstalled; it indicates 

whether the colormap is installed or uninstalled. 



Xlib Reference Manual 



xconfigure- 



ConfigureNotify 



When Generated 

A ConfigureNotify event announces actual changes to a window s configuration (size, 
position, border, and stacking order). See also the CirculateRequest reference page. 

Select With 

This event is selected for a single window by specifying the window ID of that window with 
StructureNotif yMask. To receive this event for all children of a window, specify the 
parent window ID with SubstructureNotif yMask. 

XEvent Structure Name 

typedef union _XEvent { 

XConf igureEvent xconfigure; 
} XEvent; 



Event Structure 

typedef struct { 

int type; 

unsigned long serial 

Bool send_event; 

Display *display; 

Window event; 

Window window; 

int x, y; 

int width, height; 

int border_width; 

Window above; 

Bool override_redirect; 
} XConf igureEvent; 



/* # of last request processed by server */ 
/* True if this came from SendEvent request 
/* Display the event was read from */ 



Event Structure Members 

event 



window 



width, height 
border_width 
above 



The window that selected the event The event and window 
members are identical if the event was selected with Structure- 
Not if yMask. 

The window whose configuration was changed. 

The final coordinates of the reconfigured window relative to its par 
ent. 

The width and height in pixels of the window after reconfiguration. 
The width in pixels of the border after reconfiguration. 

If this member is None, then the window is on the bottom of the 
stack with respect to its siblings. Otherwise, the window is immedi 
ately on top of the specified sibling window. 



Xlib Reference Manual 



609 



ConfigureNotify (continued) xconflgure 

override_redirect The override_redirect attribute of the reconfigured window. 
If True, it indicates that the client wants this window to be immune 
to interception by the window manager of configuration requests. 
Window managers normally should ignore this event if 

override redirect is True. 



610 Xlib Reference Manual 



xconf igurerequest- 



ConfigureRequest 



When Generated 

A ConfigureRequest event reports when another client attempts to change a window s 
size, position, border, and/or stacking order. 

This event differs from Conf igureNotif y in that it delivers the parameters of the request 
before it is carried out This gives the client that selects this event (usually the window man 
ager) the opportunity to revise the requested configuration before executing the 
XConf igureWindow request itself or to deny the request (Conf igureNotif y indicates 
the final outcome of the request) 

Select With 

This event is selected for any window in a group of children by specifying the parent window 
with SubstructureRedirectMask. 

XEvent Structure Name 

typedef union _XEvent { 

XConf igureRequestEvent xconf igurerequest ; 
} XEvent; 



Event Structure 

typedef struct { 

int type; 

unsigned long serial 

Bool send_event; 

Display *display; 

Window parent; 

Window window; 

int x, y; 

int width, height; 

int border_width; 

Window above; 

int detail; 

unsigned long value_mask 
} XConf igureRequestEvent; 



# of last request processed by server */ 
True if this came from SendEvent request 
Display the event was read from */ 



*/ 



/* Above, Below, Bottomlf, Toplf, Opposite */ 



Event Structure Members 

parent The window that selected the event This is the parent of the window 

being configured. 

window The window that is being configured. 

x, y The requested position for the upper-left pixel of the window s border 

relative to the origin of the parent window. 

width, height The requested width and height in pixels for the window. 



Xlib Reference Manual 



611 



ConfigureRequest 



(continued) 



xconfigurerequest 



border_width The requested border width for the window. 

above None, Above, Below, Toplf , Bottomlf , or Opposite. Specifies 

the sibling window on top of which the specified window should be 
placed. If this member has the constant None, then the specified win 
dow should be placed on the bottom. 



Notes 



The geometry is derived from the XConf igurewindow request that triggered the event. 



612 



Xlib Reference Manual 



xcreatewindow- 



CreateNotify 



When Generated 

A CreateNotify event reports when a window is created. 

Select With 

This event is selected on children of a window by specifying the parent window ID with 
SubstructureNotifyMask. (Note that this event type cannot be selected by 

StructureNotifyMask.) 

XEvent Structure Name 

typedef union _XEvent { 

XCreateWindowEvent xcreatewindow; 
} XEvent; 



Event Structure 

typedef struct { 
int type; 

unsigned long serial; / 
Bool send_event; / 

i 

Display ^display; / 
Window parent; 

Window window; / 

int x, y; / 

int width, height; / 

int border_width; / 
Bool override_redirect; / 
} XCreateWindowEvent; 



# of last request processed by server */ 
True if this came from SendEvent 
request */ 

Display the event was read from */ 
/* parent of the window */ 

window ID of window created */ 

window location */ 

size of window */ 

border width */ 

creation should be overridden */ 



Event Structure Members 

parent 
window 
x,y 

width, height 
border_width 
override redirect 



The ID of the created window s parent 

The ID of the created window. 

The coordinates of the created window relative to its parent 

The width and height in pixels of the created window. 

The width in pixels of the border of the created window. 

The override_redirect attribute of the created window. If 
True, it indicates that the client wants this window to be immune 
to interception by the window manager of configuration requests, 
managers normally should ignore this event if 



Window 

override 



redirect is True. 



Xlib Reference Manual 



613 



CreateNotify (continued) xcreatewlndow 

Notes 

For descriptions of these members, see the XCreateWindow function and the XSet- 
WindowAttributes structure. 



614 Xlib Reference Manual 



xdestroywindow 



DestroyNotify 



When Generated 

A DestroyNotify event reports that a window has been destroyed. 

Select With 

To receive this event type on children of a window, specify the parent window ID and pass 
SubstructureNotifyMask as part of the event_mask argument to XSelect Input. 
This event type cannot be selected with StructureNotif yMask. 

XEvent Structure Name 

typedef union _XEvent { 

XDestroyWindowEvent xdestroywindow; 
} XEvent; 



Event Structure 

typedef struct { 

int type; 

unsigned long serial, 

Bool send_event; 

Display ^display; 

Window event; 

Window window; 
} XDestroyWindowEvent; 



/* # of last request processed by server */ 
/* True if this came from SendEvent request */ 
/* Display the event was read from */ 



Event Structure Members 

event The window that selected the event 

window The window that was destroyed. 



Xlib Reference Manual 



615 



EnterNotify, LeaveNotify \ 



When Generated 

EnterNotify and LeaveNotify events occur when the pointer enters or leaves a window. 

When the pointer crosses a window border, a LeaveNotify event occurs in the window 
being left and an EnterNotify event occurs in the window being entered. Whether or not 
each event is queued for any application depends on whether any application selected the right 
event on the window in which it occurred. 

In addition, EnterNotify and LeaveNotify events are delivered to windows that are 
virtually crossed. These are windows that are between the origin and destination windows in 
the hierarchy but not necessarily on the screen. Further explanation of virtual crossing is pro 
vided two pages following. 

Select With 

Each of these events can be selected separately with XEnterWindowMask and XLeave- 
WindowMask. 

XEvent Structure Name 

typedef union _XEvent { 

XCrossingEvent xcrossing; 
} XEvent; 

Event Structure 

typedef struct { 

int type; /* of event */ 

unsigned long serial; /* # of last request processed by server */ 

Bool send_event; /* True if this came from SendEvent request */ 

Display *display; /* Display the event was read from */ 

Window window; /* event window it is reported relative to */ 

Window root; /* root window that the event occurred on */ 

Window subwindow; /* child window */ 

Time time; /* milliseconds */ 

int x, y; /* pointer x,y coordinates in receiving 

* window */ 

int x_root, y_root; /* coordinates relative to root */ 

int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab */ 

int detail; /* NotifyAncestor, Notifylnferior, 

* NotifyNonLinear, NotifyNonLinearVirtual, 

* NotifyVirtual */ 

Bool same_screen; /* same screen flag */ 
Bool focus; /* boolean focus */ 

unsigned int state; /* key or button mask */ 

} XCrossingEvent; 

typedef XCrossingEvent XEnterWindowEvent; 

typedef XCrossingEvent XLeaveWindowEvent; 



616 Xlib Reference Manual 



xcrossing 



(continued) 



EnterNotify, LeaveNotify 



Event Structure Members 

The following list describes the members of the XGrossingEvent structure. 

subwindow In a LeaveNotify event, if the pointer began in a child of the receiv 

ing window, then the child member is set to the window ID of the 
child. Otherwise, it is set to None. For an EnterNotify event, if the 
pointer ends up in a child of the receiving window, then the child 
member is set to the window ID of the child. Otherwise, it is set to 
None. 



time 



The server time when the crossing event occurred, in milliseconds. 
Time is declared as unsigned long, so it wraps around when it 
reaches the maximum value of a 32-bit number (every 49.7 days). 

x, y The point of entry or exit of the pointer relative to the event window. 

x_root , y_root The point of entry or exit of the pointer relative to the root window. 

mode Normal crossing events or those caused by pointer warps have mode 

NotifyNormal, events caused by a grab have mode NotifyGrab, 
and events caused by a released grab have mode Not if yUngrab. 

detail The value of the detail member depends on the hierarchical relation 

ship between the origin and destination windows and the direction of 
pointer transfer. Determining which windows receive events and with 
which detail members is quite complicated. This topic is described in 
the next section. 

same_screen Indicates whether the pointer is currently on the same screen as this win 
dow. This is always True unless the pointer was actively grabbed 
before the automatic grab could take place. 

focus If the receiving window is the focus window or a descendant of the focus 

window, the focus member is True; otherwise, it is False. 

state The state of all the buttons and modifier keys just before the event, 

represented by a mask of the button and modifier key symbols: 

ButtonlMask, Button2Mask, ButtonSMask, Button4Mask, 
ButtonSMask, ControlMask, LockMask, ModlMask, Mod2- 
Mask, ModSMask, Mod4Mask, ModSMask, and Shif tMask. 

Virtual Crossing and the detail Member 

Virtual crossing occurs when the pointer moves between two windows that do not have a 
parent-child relationship. Windows between the origin and destination windows in the hierar 
chy receive EnterNotify and LeaveNotify events. The detail member of each of 
these events depends on the hierarchical relationship of the origin and destination windows and 
the direction of pointer transfer. 



Xlib Reference Manual 



617 



EnterNotify, LeaveNotify (continued) xcrossing 

Virtual crossing is an advanced topic that you should not spend time figuring out unless you 
have an important reason to use it We have never seen an application that uses this feature, 
and we know of no reason for its extreme complexity. With that word of warning, proceed. 

Let s say the pointer has moved from one window, the origin, to another, the destination. First, 
we ll specify what types of events each window gets and then the detail member of each of 
those events. 

The window of origin receives a LeaveNotify event and the destination window receives an 
EnterNotify event, if they have requested this type of event If one is an inferior of the 
other, the detail member of the event received by the inferior is Notif yAncestor and the 
detail of the event received by the superior is Notif y inferior. If the crossing is between 
parent and child, these are the only events generated. 

However, if the origin and destination windows are not parent and child, other windows are 
virtually crossed and also receive events. If neither window is an ancestor of the other, 
ancestors of each window, up to but not including the least common ancestor, receive Leave- 
Notif y events, if they are in the same branch of the hierarchy as the origin, and Enter- 
Notify events, if they are in the same branch as the destination. These events can be used to 
track the motion of the pointer through the hierarchy. 

In the case of a crossing between a parent and a child of a child, the middle child receives a 

LeaveNotify with detail Notif yVirtual. 

In the case of a crossing between a child and the parent of its parent, the middle child 
receives an EnterNotify with detail Notif yVirtual. 

In a crossing between windows whose least common ancestor is two or more windows 
away, both the origin and destination windows receive events with detail Not if y- 
Nonlinear. The windows between the origin and the destination in the hierarchy, up to 
but not including their least common ancestor, receive events with detail Not if y- 
NonlinearVirtual. The least common ancestor is the lowest window from which both 
are descendants. 

If the origin and destination windows are on separate screens, the events and details gen 
erated are the same as for two windows not parent and child, except that the root windows 
of the two screens are considered the least common ancestor. Both root windows also 
receive events. 



6 18 Xlib Reference Manual 



xcrossing 



(continued) 



EnterNotify, LeaveNotify 



Table E-l shows the event types generated by a pointer crossing from window A to window B 
when window C is the least common ancestor of A and B. 

Table E-1. Border Crossing Events and Window Relationship 



LeaveNotify 



Origin window (A) 

Windows between A and B, 
exclusive, if A is inferior 

Windows between A and C, 
exclusive 

Root window on screen of 
origin if different from 
screen of destination 



EnterNotify 



Destination window (5) 

Windows between A and B, exclusive, if B is inferior 

Windows between B and C, exclusive, 

Root window on screen of destination if different 
from screen of origin 



Table E-2 lists the detail members in events generated by a pointer crossing from window A 
to window B. 

Table E-2. Event detail Member and Window Relationship 
de t a i 1 Rag Window Delivered To 



NotifyAncestor 
Notify Inferior 
NotifyVirtual 

NotifyNonlinear 
NotifyNonlinearVirtual 



Origin or destination when either is descendant 
Origin or destination when either is ancestor 

Windows between A and B, exclusive, if either is 
descendant 

Origin and destination when A and B are two or more 
windows distant from least common ancestor C 

Windows between A and C, exclusive, and between 
B and C, exclusive, when A and B have least common 
ancestor C; also on both root windows if A and B are 
on different screens 



Xlib Reference Manual 



619 



EnterNotify, LeaveNotify 



(continued) 



xcrossing 



For example, Figure E-l shows the events that are generated by a movement from a window 
(window A) to a child (window Bl) of a sibling (window B). This would generate three events: 
a LeaveNotify with detail Notif yNonlinear for the window A, an EnterNotify with 
detail Notif yNonlinearVirtual for its sibling window 5, and an EnterNotify with 
detail Notif yNonlinear for the child (window Bl). 













Root Window 

(no event) 


I I 


\ 







w 




~~l 


A 

LeaveNotify event with detail 

Not if yNonlinear 


B 

EnterNotify event with detail 

Not if yNonlinearVirtual 


1 








I 




A1 

no event 




B1 

EnterNc 
Notify! 


3tify event with detail 

Nonlinear 













Figure E-1. Events generated by a move between windows 

EnterNotify and LeaveNotify events are also generated when the pointer is grabbed, if 
the pointer was not already inside the grabbing window. In this case, the grabbing window 
receives an EnterNotify and the window containing the pointer receives a LeaveNotify 
event, both with mode Notif yUngrab. The pointer position in both events is the position 
before the grab. The result when the grab is released is exactly the same, except that the two 
windows receive EnterNotify instead of LeaveNotify and vice versa. 



620 



Xlib Reference Manual 



xcrossing 



(continued) 



EnterNotify, Leave Notify 



Figure E-2 demonstrates the events and details caused by various pointer transitions, indicated 
by heavy arrows. 



LeaveNotify 
Ancestor 







Figure E-2. Border crossing events and detail member for pointer movement from 
window A to window B, for various window relationships 



Xlib Reference Manual 



621 



Expose X 



x ex pose 



When Generated 

An Expose event is generated when a window becomes visible or a previously invisible part 
of a window becomes visible. Only inputOutput windows generate or need to respond to 
Expose events; inputOnly windows never generate or need to respond to them. The 
Expose event provides the position and size of the exposed area within the window and a 
rough count of the number of remaining exposure events for the current window. 

Select With 

This event is selected with ExposureMask. 

XEvent Structure Name 

typedef union _XEvent { 

XExposeEvent xexpose; 
} XEvent; 

Event Structure 

typedef struct { 

int type; 

unsigned long serial; /* # of last request processed by server */ 

Bool send_event; /* True if this came from SendEvent request */ 

Display ^display; /* Display the event was read from */ 

Window window; 

int x, y; 

int width, height; 

int count; /* If nonzero, at least this many more */ 

} XExposeEvent; 

Event Structure Members 

x, y The coordinates of the upper-left corner of the exposed region relative to 

the origin of the window. 

width, height The width and height in pixels of the exposed region. 

count The approximate number of remaining contiguous Expose events that 

were generated as a result of a single function call. 

Notes 

A single action such as a window movement or a function call can generate several exposure 
events on one window or on several windows. The server guarantees that all exposure events 
generated from a single action will be sent contiguously, so that they can all be handled before 
moving on to other event types. This allows an application to keep track of the rectangles 
specified in contiguous Expose events, set the clip_mask in a GC to the areas specified in 



622 Xlib Reference Manual 



xexpose (continued) Expose 

the rectangle using XSetRegion or XSetClipRectangles, and then finally redraw the 
window clipped with the GC in a single operation after all the Expose events have arrived. 
The last event to arrive is indicated by a count of 0. In Release 2, XUnionRectwith- 
Region can be used to add the rectangle in Expose events to a region before calling XSet 
Region. 

If your application is able to redraw partial windows, you can also read each exposure event in 
turn and redraw each area. 



Xlib Reference Manual 623 



Focusln, FocusOut \ 



xfocus 



When Generated 

Focusln and FocusOut events occur when the keyboard focus window changes as a result 
of an XSetlnputFocus call. They are much like EnterNotify and LeaveNotify 
events except that they track the focus rather than the pointer. 

When a focus change occurs, a FocusOut event is delivered to the old focus window and a 
Focusln event to the window which receives the focus. In addition, windows in between 
these two windows in the window hierarchy are virtually crossed and receive focus change 
events, as described below. Some or all of the windows between the window containing the 
pointer at the time of the focus change and the root window also receive focus change events, 
as described below. 

Select With 

Focusln and FocusOut events are selected with FocusChangeMask. They cannot be 
selected separately. 

XEvent Structure Name 

typedef union _XEvent { 

XFocusChangeEvent xfocus; 
(... 
} XEvent; 

Event Structure 

typedef struct { 

int type; /* Focusln or FocusOut */ 

unsigned long serial; /* # of last request processed by server */ 

Bool send_event; /* True if this came from SendEvent request */ 

Display ^display; /* Display the event was read from */ 

Window window; /* Window of event */ 

int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab */ 

int detail; /* NotifyAncestor, NotifyDetailNone, 

* Notifylnferior, NotifyNonLinear, 

* NotifyNonLinearVirtual, NotifyPointer, 

* NotifyPointerRoot, NotifyVirtuaW 
} XFocusChangeEvent; 

typedef XFocusChangeEvent XFocusInEvent; 
typedef XFocusChangeEvent XFocusOutEvent; 

Event Structure Members 

mode For events generated when the keyboard is not grabbed, mode is Notify 

Normal; when the keyboard is grabbed, mode is NotifyGrab; and when a 
keyboard is ungrabbed, mode is NotifyUngrab. 

detail The detail member identifies the relationship between the window that 
receives the event and the origin and destination windows. It will be described 
in detail after the description of which windows get what types of events. 



624 



Xlib Reference Manual 



xfocus (continued) Focusln, FocusOut 

Notes 

The keyboard focus is a window that has been designated as the one to receive all keyboard 
input irrespective of the pointer position. Only the keyboard focus window and its descendants 
receive keyboard events. By default, the focus window is the root window. Since all windows 
are descendants of the root, the pointer controls the window that receives input. 

Most window managers allow the user to set a focus window to avoid the problem where the 
pointer sometimes gets bumped into the wrong window and your typing does not go to the 
intended window. If the pointer is pointing at the root window, all typing is usually lost, since 
there is no application for this input to propagate to. Some applications may set the keyboard 
focus so that they can get all keyboard input for a given period of time, but this practice is not 
encouraged. 

Focus events are used when an application wants to act differently when the keyboard focus is 
set to another window or to itself. Focus ChangeMask is used to select Focusln and 
FocusOut events. 

When a focus change occurs, a FocusOut event is delivered to the old focus window and a 
Focusln event is delivered to the window which receives the focus. Windows in between in 
the hierarchy are virtually crossed and receive one focus change event each depending on the 
relationship and direction of transfer between the origin and destination windows. Some or all 
of the windows between the window containing the pointer at the time of the focus change and 
that window s root window can also receive focus change events. By checking the detail 
member of Focusln and FocusOut events, an application can tell which of its windows can 
receive input. 

The detail member gives clues about the relationship of the event receiving window to the 
origin and destination of the focus. The detail member of Focus in and FocusOut events 
is analogous to the detail member of EnterNotif y and LeaveNotif y events but with 
even more permutations to make life complicated. 

Virtual Focus Crossing and the detail Member 

We will now embark on specifying the types of events sent to each window and the detail 
member in each event, depending on the relative position in the hierarchy of the origin window 
(old focus), destination window (new focus), and the pointer window (window containing 
pointer at time of focus change). Don t even try to figure this out unless you have to. 



Xlib Reference Manual 625 



Focusln, FocusOut 



(continued) 



xfocus 



Table E-3 shows the event types generated by a focus transition from window A to window B 
when window C is the least common ancestor of A and B. This table includes most of the 
events generated, but not all of them. It is quite possible for a single window to receive more 
than one focus change event from a single focus change. 

Table E-3. Focusln and FocusOut Events and Window Relationship 



FocusOut 



Origin window (A) 

Windows between A and 5, 
exclusive, if A is inferior 

Windows between A and C, 
exclusive 

Root window on screen of 
origin if different from 
screen of destination 

Pointer window up to but 
not including origin window 
if pointer window is descen 
dant of origin 

Pointer window up to and 
including pointer window s 
root if transfer was from 

PointerRoot 



Focusln 



Destination window (B) 

Windows between A and 5, exclusive, if B is inferior 

Windows between B and C, exclusive 

Root window on screen of destination if different 
from screen of origin 

Pointer window up to but not including destination 
window if pointer window is descendant of destina 
tion 

Pointer window up to and including pointer win 
dow s root if transfer was to PointerRoot 



Xlib Reference Manual 



xfocus 



(continued) 



Focusln, FocusOut 



Table E-4 lists the detail members in events generated by a focus transition from window A 
to window B when window C is the least common ancestor of A and B, with P being the win 
dow containing the pointer. 

Table E-4. Event detail Member and Window Relationship 



detail Flag 



NotifyAncestor 
Notifylnferior 
NotifyVirtual 

NotifyNonlinear 
NotifyNonlinearVirtual 

NotifyPointer 
NotifyPointerRoot 

NotifyDetailNone 



Window Deli vered To 



Origin or destination when either is descendant 
Origin or destination when either is ancestor 

Windows between A and B, exclusive, if either is 
descendant 

Origin and destination when A and B are two or more 
windows distant from least common ancestor C 

Windows between A and C, exclusive, and between 
B and C, exclusive, when A and B have least common 
ancestor C; also on both root windows if A and B are 
on different screens 

Window P and windows up to but not including the 
origin or destination windows 

Window P and all windows up to its root, and all 
other roots, when focus is set to or from Pointer- 
Root 

All roots, when focus is set to or from None 



Figure E-3 shows all the possible combinations of focus transitions and of origin, destination, 
and pointer windows and shows the types of events that are generated and their detail mem 
ber. Solid lines indicate branches of the hierarchy. Dotted arrows indicate the direction of 
transition of the focus. At each end of this arrow are the origin and destination windows, win 
dows A to B. Arrows ending in a bar indicate that the event type and detail described are 
delivered to all windows up to the bar. 

In any branch, there may be windows that are not shown. Windows in a single branch between 
two boxes shown will get the event types and details shown beside the branch. 



Xlib Reference Manual 



627 



Focusln, FocusOut 



(continued) 



xfocus 



LeaveNotify, 




If window P is between A 
and B, windows from P up 
to but not including B get 
FOCUS in with detail 

Notifylnterior 





FocusOut, 

Nonlinear-Virtual 



1 



Roots of other Screens: 
FOCUS:.-, with Detail :;or.f 




Root Window 

FOCUS: None 




FocusOut, 

y 



Figure E-3. Focusln and FocusOut event schematics 



628 



Xlib Reference Manual 



xfocus 



(continued) 



Focusln, FocusOut 



Roots of other Screens: 
isOut with Detail PointerRoot 



Focus: 

PointerP.cot I 




1 

T 



Roots of other Screens: 

"ocusGut with Detail ; n< 



Root Window 
FOCUS: Kone 







Focus change from PointerRoot to : 

All Root Windows: 
2ui with Detail E int erF 



Pointer s 
Root Window 



1 _J 



Focus change from PointerRoot to ::.:. 



All Root Windows: 
: - with Detail No. 



Pointer s 
Root Window 



Figure E-3. Focusln and FocusOut event schematics (cont.) 

Focusln and FocusOut events are also generated when the keyboard is grabbed, if the focus 
was not already assigned to the grabbing window. In this case, all windows receive events as if 
the focus was set from the current focus to the grab window. When the grab is released, the 
events generated are just as if the focus was set back. 



Xlib Reference Manual 



629 



GraphicsExpose, NoExpose \ 



xnoexpose 



When Generated 

GraphicsExpose events indicate that the source area for a XCopyArea or XCopyPlane 
request was not available because it was outside the source window or obscured by a window. 
NoExpose events indicate that the source region was completely available. 

Select With 

These events are not selected with xselect Input but are sent if the GC in the XCopyArea 
or XCopyPlane request had its graphics_exposures flag set to True. If 
graphics_exposures is True in the GC used for the copy, either one NoExpose event 
or one or more GraphicsExpose events will be generated for every XCopyArea or 
XCopyPlane call made. 

XEvent Structure Name 

typedef union _XEvent { 

XNoExposeEvent xnoexpose; 
XGraphicsExposeEvent xgraphicsexpose ; 

} XEvent; 



Event Structure 

typedef struct { 

int type; 

unsigned long serial, 

Bool send_event; 

Display *display; 

Drawable drawable; 

int x, y; 

int width, height; 

int count; 

int major_code; 

int minor_code; 
} XGraphicsExposeEvent; 

typedef struct { 

int type; 

unsigned long serial; 

Bool send_event; 

Display *display; 

Drawable drawable; 

int ma jor_code; 

int minor_code; 
} XNoExposeEvent; 



/* # of last request processed by server */ 
/* True if this came from SendEvent request 
/* Display the event was read from */ 



/* if nonzero, at least this many more */ 
/* core is CopyArea or CopyPlane */ 
/* not defined in the core */ 



/* # of last request processed by server */ 
/* True if this came from SendEvent request */ 
/* Display the event was read from */ 

/* core is CopyArea or CopyPlane */ 
/* not defined in the core */ 



Xlib Reference Manual 



(continued) 



GraphicsExpose, NoExpose 



xnoexpose 



Event Structure Members 

drawable A window or an off-screen pixmap. This specifies the destination of the 

graphics request that generated the event 

x, y The coordinates of the upper-left corner of the exposed region relative to 

the origin of the window. 

width, height The width and height in pixels of the exposed region. 

count The approximate number of remaining contiguous GraphicsExpose 

events that were generated as a result of the xcopyArea or XGopy- 
P lane call. 

ma jor_code The graphics request used. This may be one of the symbols CopyArea 

or CopyPlane or a symbol defined by a loaded extension. 

minor_code Zero unless the request is part of an extension. 

Notes 

Expose events and GraphicsExpose events both indicate the region of a window that was 
actually exposed (x, y, width, and height). Therefore, they can often be handled similarly. 



Xlib Reference Manual 



631 



GravityNotify \ 



xgravity 



When Generated 

A GravityNotify event reports when a window is moved because of a change in the size of 
its parent This happens when the win_gravity attribute of the child window is something 
other than StaticGravity or UnmapGravity. 

Select With 

This event is selected for a single window by specifying the window ID of that window with 
St ructureNotif yMask. To receive notification of movement due to gravity for a group of 
siblings, specify the parent window ID with SubstructureNotif yMask. 

XEvent Structure Name 

typedef union _XEvent { 

XGravityEvent xgravity; 
} XEvent; 

Event Structure 

typedef struct { 

int type; 

unsigned long serial; /* # of last request processed by server */ 

Bool send_event; /* True if this came from SendEvent request */ 

Display *display; /* Display the event was read from */ 

Window event; 

Window window; 

int x, y; 
} XGravityEvent; 

Event Structure Members 

event The window that selected the event 

window The window that was moved. 

x, y The new coordinates of the window relative to its parent 



632 



Xlib Reference Manual 



xkeymap- 



KeymapNotify 



When Generated 

A KeymapNotify event reports the state of the keyboard and occurs when the pointer or 
keyboard focus enters a window. KeymapNotify events are reported immediately after 
EnterNotify or Focusln events. This is a way for the application to read the keyboard 
state as the application is "woken up," since the two triggering events usually indicate that the 
application is about to receive user input. 

Select With 

This event is selected with KeymapStateMask. 

XEvent Structure Name 

typedef union _XEvent { 

XKeymapEvent xkeymap; 
} XEvent; 



Event Structure 

typedef struct { 

int type; 

unsigned long serial, 

Bool send_event; 

Display *display; 

Window window; 

char key_vector[32] ; 
} XKeymapEvent; 



/* # of last request processed by server */ 
/* True if this came from SendEvent request */ 
/* Display the event was read from */ 



Event Structure Members 

window Reports the window which was reported in the window member of the pre 

ceding EnterNotify or Focusln event 

key_vector A bit vector or mask, each bit representing one physical key, with a total of 
256 bits. For a given key, its keycode is its position in the keyboard vector. 
You can also get this bit vector by calling XQueryKeymap. 

Notes 

The serial member of KeymapNotify does not contain the serial number of the most 
recent protocol request processed, because this event always follows immediately after 
EnterNotify or Focusln events in which the serial member is valid. 



Xlib Reference Manual 



633 



KeyPress, KeyRelease 



X 



xkey 



When Generated 

KeyPress and KeyRelease events are generated for all keys, even those mapped to 
modifier keys such as Shift or Control. 

Select With 

Each type of keyboard event may be selected separately with KeyPressMask and Key- 
ReleaseMask. 

XEvent Structure Name 

typedef union _XEvent { 

XKeyEvent xkey; 
} XEvent; 



Event Structure 

typedef struct { 
int type; 

unsigned long serial, 
Bool send_event; 
Display *display; 
Window window; 
Window root; 
Window subwindow; 
Time time; 
int x, y; 



int x_root, y_root; 

unsigned int state; 

unsigned int keycode; 

Bool same_screen; 
} XKeyEvent; 

typedef XKeyEvent XKeyPressedEvent; 
typedef XKeyEvent XKeyReleasedEvent; 



/* of event */ 

/* # of last request processed by server */ 

/* True if this came from SendEvent request */ 

/* Display the event was read from */ 

/* event window it is reported relative to */ 

/* root window that the event occurred on */ 

/* child window */ 

/* milliseconds */ 

/* pointer coordinates relative to receiving 

* window */ 

/* coordinates relative to root */ 

/* modifier key and button mask */ 

/* server-dependent code for key */ 

/* same screen flag */ 



Event Structure Members 

subwindow If the source window is the child of the receiving window, then the 

subwindow member is set to the ID of that child. 



time 



x,y 



The server time when the button event occurred, in milliseconds. Time 
is declared as unsigned long, so it wraps around when it reaches the 
maximum value of a 32-bit number (every 49.7 days). 

If the receiving window is on the same screen as the root window speci 
fied by root, then x and y are the pointer coordinates relative to the 
receiving window s origin. Otherwise, x and y are zero. 



634 



Xlib Reference Manual 



xkey 



(continued) 



KeyPress, KeyRelease 



When active button grabs and pointer grabs are in effect (see Section 9.4 
of Volume One, Xlib Programming Manual), the coordinates relative to 
the receiving window may not be within the window (they may be nega 
tive or greater than window height or width). 

xjcoot, y_root The pointer coordinates relative to the root window which is an ancestor 
of the event window. If the pointer was on a different screen, these ?~e 
zero. 

state The state of all the buttons and modifier keys just before the event, 

represented by a mask of the button and modifier key symbols: 

ButtonlMask, Button2Mask, ButtonSMask, Button4Mask, 
ButtonSMask, ControlMask, LockMask, ModlMask, Mod2- 
Mask, ModSMask, Mod4Mask, ModSMask, and Shif tMask. 

keycode The keycode member contains a server-dependent code for the key that 

changed state. As such, it should be translated into the portable symbol 
called a keysym before being used. It can also be converted directly into 
ASCII with XLookupString. For a description and examples of how 
to translate keycodes, see Volume One, Section 9.1.1. 

Notes 

Remember that not all hardware is capable of generating release events and that only the main 
keyboard (a-z, A-Z, 0-9), Shift, and Control keys are always found. 

Keyboard events are analogous to button events, though, of course, there are many more keys 
than buttons and the keyboard is not automatically grabbed between press and release. 

All the structure members have the same meaning as described for ButtonPress and 
ButtonRelease events, except that button is replaced by keycode. 



Xlib Reference Manual 



635 



MapNotlfy, UnmapNotify 



X 



xmap, xunmap 



When Generated 

The X server generates MapNotif y and UnmapNotify events when a window changes state 
from unmapped to mapped or vice versa. 

Select With 

To receive these events on a single window, use StructureNotifyMask in the call to 
XSelect Input for the window. To receive these events for all children of a particular 
parent, specify the parent window ID and use SubstructureNotif yMask. 

XEvent Structure Name 

typedef union _XEvent { 

XMapEvent xmap; 
XUnmapEvent xunmap; 

} XEvent; 



Event Structure 

typedef struct { 

int type; 

unsigned long serial; 

Bool send_event; 

Display *display; 

Window event; 

Window window; 

Bool override_redirect, 
} XMapEvent; 

typedef struct { 

int type; 

unsigned long serial; 

Bool send_event; 

Display *display; 

Window event; 

Window window; 

Bool from_conf igure; 
} XUnmapEvent; 



/* # of last request processed by server */ 
/* True if this came from SendEvent request */ 
/* Display the event was read from */ 



/* boolean, is override set */ 



/* # of last request processed by server */ 
/* True if this came from SendEvent request */ 
/* Display the event was read from */ 



Event Structure Members 

event The window that selected this event 



The window that was just mapped or unmapped. 
override_redirect (XMapEvent only) 

True or False. The value of the override_redirect attribute of the 
window that was just mapped. 



636 



Xlib Reference Manual 



xmap, xunmap 



(continued) 



MapNotify, UnmapNotify 



f rom_conf igure (XUnmapEvent only) 

True if the event was generated as a result of a resizing of the window s parent 
when the window itself had a win_gravity of UnmapGravity. See the 
description of the win_gravity attribute in Section 4.3.4 of Volume One, 
Xlib Programming Manual. False otherwise. 



Xlib Reference Manual 



637 



MappingNotify 



X 



xmapping 



When Generated 

A MappingNotify event is sent when any of the following is changed by another client: the 
mapping between physical keyboard keys (keycodes) and keysyms, the mapping between 
modifier keys and logical modifiers, or the mapping between physical and logical pointer 
buttons. These events are triggered by a call to XSetModifierMapping or XSet- 
PointerMapping, if the return status is MappingSuccess, or by any call to XChange- 
Keyboa rdMapping. 

This event type should not be confused with the event that occurs when a window is mapped; 
that is a MapNotify event Nor should it be confused with the KeymapNotify event, 
which reports the state of the keyboard as a mask instead of as a keycode. 

Select With 

The X server sends MappingNotify events to all clients. It is never selected and cannot be 
masked with the window attributes. 

XEvent Structure Name 

typedef union _XEvent { 

XMappingEvent xmapping; 
} XEvent; 



/* # of last request processed by server */ 

/* True if this came from SendEvent request */ 

/* Display the event was read from */ 

/* unused */ 

/* one of MappingMapping, MappingKeyboard, 

* MappingPointer */ 

/* first keycode */ 

/* range of change with f irst_keycode*/ 



Event Structure 

typedef struct { 
int type; 

unsigned long serial 
Bool send_event; 
Display *display; 
Window window; 
int request; 

int f irst_keycode; 
int count; 
} XMappingEvent; 

Event Structure Members 

request The kind of mapping change that occurred: MappingModif ier for a 

successful XSetModifierMapping (keyboard Shift, Lock, Control, 
Meta keys), MappingKeyboard for a successful XChange- 
Keyboa rdMapping (other keys), and MappingPointer for a suc 
cessful XSetPointerMapping (pointer button numbers). 

first_keycode If the request member is MappingKeyboard or Mapping- 
Modifier, then f irst_keycode indicates the first in a range of key- 
codes with altered mappings. Otherwise, it is not set 



Xlib Reference Manual 



xmapplng (continued) MappingNotify 

count If the request member is MappingKeyboard or Mapping- 

Modifier, then count indicates the number of keycodes with altered 
mappings. Otherwise, it is not set 

Notes 

If the request member is MappingKeyboard, clients should call XRef reshKeyboard