(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 of the X Window System"

The Definitive Guides 
to the X Wi 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. 



Table of Contents 

Page 

Preface .................................................................................................................................. ix 

About This Manual ................................................................................................................. ix 
Summary of Contents ............................................................................................................... x 
How to Use This Manual ......................................................................................................... x 
Assumptions ........................................................................................................................... xii 
Font Conventions Used in This Manual ................................................................................ xii 
Related Documents ............................................................................................................... xiii 
Requests For Comments ....................................................................................................... xiii 
Licensing Information ........................................................................................................... xiii 
Acknowledgements ............................................................................................................... xiv 

Permuted Index ................................................................................................................. 1 

Xlib Function Reference .............................................................................................. 29 

Appendix A: Function Group Summary .......................................................... 499 
Group Listing with Brief Descriptions ................................................................................ 499 
Alphabetical Listing of Routines ......................................................................................... 514 

Appendix B: Error Messages and Protocol Requests ................................. 523 

Appendix C: Macros ................................................................................................. 531 

Display Macros ..................................................................................................................... 531 
Image Format Macros .......................................................................................................... 535 
Keysym Classification Macros ............................................................................................. 535 
Resource Manager Macros ................................................................................................... 536 

Appendix D: The Color Database ....................................................................... 537 



Appendix E: Event Reference ............................................................................... 539 

Meaning of Common Structure Elements ............................................................................ 541 
ButtonPress, ButtonRelease ................................................................................................. 543 
CirculateNotify ..................................................................................................................... 545 
CirculateRequest ................................................................................................................... 546 
ClientMessage ....................................................................................................................... 547 
ColormapNotify .................................................................................................................... 548 
ConfigureNotify .................................................................................................................... 549 
ConfigureRequest ................................................................................................................. 551 
CreateNotify ......................................................................................................................... 553 
DestroyNotify ....................................................................................................................... 554 
EnterNotify, LeaveNotify ..................................................................................................... 555 
Expose ................................................................................................................................... 561 
Focusln, FocusOut ................................................................................................................ 563 
GraphicsExpose, NoExpose ................................................................................................. 569 
GravityNotify ........................................................................................................................ 571 
KeymapNotify ...................................................................................................................... 572 
KeyPress, KeyRelease .......................................................................................................... 573 
MapNotify, UnmapNotify .................................................................................................... 575 
MappingNotify ..................................................................................................................... 577 
MapRequest .......................................................................................................................... 579 
MotionNotify ........................................................................................................................ 580 
PropertyNotify ...................................................................................................................... 582 
ReparentNotify ..................................................................................................................... 583 
ResizeRequest ....................................................................................................................... 584 
SelectionClear ....................................................................................................................... 585 
SelectionNotify ..................................................................................................................... 586 
SelectionRequest ................................................................................................................... 587 
VisibilityNotify ..................................................................................................................... 588 

Appendix F: Structure Reference ........................................................................ 591 

Description of Contents ........................................................................................................ 591 
Resource Types ..................................................................................................................... 592 
Structure Definitions ............................................................................................................. 592 
Depth ................................................................................................................................. 592 
Display .............................................................................................................................. 593 
GC ..................................................................................................................................... 594 
Screen ................................................................................................................................ 594 
ScreenFormat .................................................................................................................... 595 
Visual ................................................................................................................................ 595 
XArc .................................................................................................................................. 596 
XChar2b ............................................................................................................................ 596 
XCharStruct ....................................................................................................................... 596 
XClassHint ........................................................................................................................ 597 



XColor ............................................................................................................................... 597 
XComposeStatus ............................................................................................................... 597 
XExtCodes ........................................................................................................................ 598 
XExtData ........................................................................................................................... 598 
XFontProp ......................................................................................................................... 598 
XFontStruct ....................................................................................................................... 599 
XGCValues ....................................................................................................................... 599 
XHostAddress ................................................................................................................... 600 
XlconSize .......................................................................................................................... 600 
Xlmage .............................................................................................................................. 600 
XKeyboardControl ............................................................................................................ 601 
XKeyBoardState ............................................................................................................... 601 
XModifierKeymap ............................................................................................................ 602 
XPoint ............................................................................................................................... 602 
XRectangle ........................................................................................................................ 602 
XSegment .......................................................................................................................... 602 
XSetWindowAttributes ..................................................................................................... 603 
XSizeHints ........................................................................................................................ 603 
XStandardColormap .......................................................................................................... 604 
XTextltem ......................................................................................................................... 604 
XTextltem 16 ..................................................................................................................... 604 
XTimeCoord ..................................................................................................................... 605 
XVisuallnfo ....................................................................................................................... 605 
XWMHints ........................................................................................................................ 605 
XWindowAttributes .......................................................................................................... 606 
XWindowChanges ............................................................................................................ 606 

Appendix G: Symbol Reference ........................................................................... 607 

Appendix H: Keysyms .............................................................................................. 623 

Appendix I: The Cursor Font ............................................................................... 641 

Appendix J: Fonts ...................................................................................................... 643 



Appendix K: Xlib Release 3 Update ................................................................... 699 

New Routines .................................................................................................................... 699 
Command Line Options .................................................................................................... 701 
Fonts .................................................................................................................................. 701 
Internal and Invisible Changes to Xlib ............................................................................. 702 
Small Interface Changes ................................................................................................... 702 
Server Fixes ...................................................................................................................... 703 
The Xmu library ............................................................................................................... 703 
Release 3 Protocol Clarifications ...................................................................................... 704 

Window Attributes At-a-glance ............................................................................. 707 

GC At-a-glance .............................................................................................................. 709 

ooo 
VIII 



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 foun- 
dation they are based on, and illustrates how they are most often used in writing applications 
(or in the case of the last chapter, window managers). Volume One is structured so as to be 
useful as a tutorial and also as a task-oriented reference. 
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 Volume 
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 X11 Protocol documentation pro- 
vided by MIT, as well as from other documents provided on the MIT release tape. This 
volume is based heavily on these sources, although it has also been extensively edited and 
added to. We have done our best to incorporate all of the useful information from the MIT 
documentation, to correct code 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 documentation. 
Those of you familiar with the MIT documentation will recognize that each reference page 
in this volume includes the detailed description of the routine found in Gettys, Newman, and 
Scheitler'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. 



Related Documents 

The C Programming Language by B. W. Kernighan and D. M. Ritchie 
The following documents are included on the X11 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 
The following book on the X Window System from O'Reilly and Associates, Inc., is 
currendy in its second printing: 
Volume Three -- X Window System User's Guide 
Two more books on the X Window System are now being developed at O'Reilly & Associ- 
ates, Inc., and are expected to be published in the Summer of 1989: 
Volume Four m Xt Toolkit Programming Manual 
Volume Five -- Xt Toolkit Reference Manual 

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 phone number are as follows: 
O'Reilly & Associates, Inc. 
632 Petaluma Avenue 
Sebastopol, CA 95472 
(800) 338-6887 

UUCP: uunet!ora!adrian 

ARPA: adrian@ora.UU.NET 

Licensing Information 

This manual has been designed for licensing and customization by manufacturers or distri- 
butors of systems supporting X11. As of this writing, it has been licensed by Masscomp, 
Motorola, Apollo Computer, Silicon Graphics, and Stellar Computer. For information on 
licensing, call O'Reilly & Associates, Inc. at (800) 338-6887, or send e-mad to 
tim@ora.UU.NET. 

Preface xiii 



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 
software 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'd 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 worksta- 
tion manufacturer, and later to another company to write a manual for X Version 11, from 
which this book began. I've 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 reorgan- 
ize 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 & 
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 
Release 2 resource manager and wrote the 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; Linda Walsh updated the index of the book; Valerie Quercia, 
Tom Van Raalte, and Donna Woonteiler 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. A special thanks to everyone at 
O'Reilly & Associates for putting up with my habits of printer and terminal hogging, lug- 
ging X books around, recycling paper, and for generally being good at what they do and 
good-natured to boot. 
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, and Jeffrey Vroom of Stel- 
lar Computer; Oliver Jones of Apollo Computer; Sam Black, Jeff Graber, and Janet Egan of 
Masscomp; A1 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 Solu- 
tions. Despite the efforts of the reviewers and everyone else, any errors that remain are my 
own. 
m Adrian Nye 



turn the screen saver on or 
two regions have the same size. 
XOffsetRegion: change 
8-bit text string, foreground 
/set the bitwise logical 
for program name and 
/circulate the stacking 
/change the stacking 
to the top of the stacking 
to the bottom of the stacking 
size, border width, or stacking 
lower a window in the stacking 
to the top of the stacking 
XSetCllpOrigin: set the clip 
/set the tile/stipple 
XDrawRectangle: draw an 
XDrawRectangles: draw the 
number of/XPending: flush the 
events and/XSync: flush the 
queued/XFlush: flush the 
XGetSelectionOwner: return the 
XSetSelectionOwner: set the 
grab. /change the 
XSetScreenSaver: set the 
get the current screen saver 
return a list of children, 
between another window and its 
create a subimage from 
matching both passed window and 
/the next event matching both 
get the current font search 
set the font search 
buffer and return the number of 
/set the background 
/attribute to the specified 
XGetPixel: obtain a single 
context. /set the background 
context. /set the foreground 
/add a constant value to every 
XPutPixel: set a 
and flags for a specified 
a drawable with depth, applying 
RGB values for an array of 
XTextWidthl6: get the width in 
XTextWidth: get the width in 
XFreePixmap: free a 
XSetClipMask: set clip_mask 
data. /create a 
XCreatePixmap: create a 
image on a window or 
from drawable into/XGetImage: 
XSetPlaneMask: set the 
context. /logical function, and 
XCopyPlane: copy a single 
read/write (nonshareable) color 
free colormap cells or 
XPointInRegion: determine if a 

off. XForceScreenSaver: ........................ XForceScreenSaver 
offset, and shape. /if ............................... XEqualRegion 
offset of a region ..................................... XOffsetRegion 
only. XDrawString: draw an .................. XDrawString 
operation in a graphics/ ........................... XSetFunction 
options. /the user preferences ................. XGetDefault 
order of children up or down .................. XCirculateSubwindows 
order of siblings ...................................... XRestackWindows 
order. /the bottom child .......................... XCirculateSubwindowsDown 
order. /circulate the top child ................. XCirculateSubwindowsUp 
order. /the window position, . ................. XConfigureWindow 
order. XLowerWindow: ......................... XLowerWindow 
order. /raise a window ............................ XRaiseWindow 
origin in a graphics context .................... XSetClipOrigin 
origin in a graphics context .................... XSetTSOrigin 
outline of a rectangle .............................. XDrawRectangle 
outlines of multiple/ ................................ XDrawRectangles 
output buffer and return the .................... XPending 
output buffer and wait for all .................. XSync 
output buffer (display all ........................ XFlush 
owner of a selection ................................ XGetSelectionOwner 
owner of a selection ................................ XSetSelectionOwner 
parameters of an active pointer ............... XChangeActivePointerGrab 
parameters of the screen saver. ............... XSetScreenSaver 
parameters. XGetScreenSaver: ............... XGetScreenSaver 
parent, and root. XQueryTree: ............... XQueryTree 
parent. /insert a window ......................... XReparentWindow 
part of an image. XSubImage: ............... XSublmage 
passed mask: don't wait. /event ............. XCheckWindowEvent 
passed window and passed mask:/ ......... XCheckWindowEvent 
path. XGetFomPath: ............................... XGetFontPath 
path. XSetFontPath: ............................... XSetFomPath 
pending input events. /output ................. XPending 
pixel attribute of a window ..................... XSetWindowBackground 
pixel value and repaint the/ ..................... XSetWindowBorder 
pixel value from an image ...................... XGetPixel 
pixel value in a graphics ......................... XSetBackground 
pixel value in a graphics ......................... XSetForeground 
pixel value in an image ........................... XAddPixel 
pixel value in an image ........................... XPutPixel 
pixel value. /the RGB values ................. XQueryColor 
pixel values. /a drawable into ................ XCopyPlane 
pixel values. /obtain ............................... XQueryColors 
pixels of a 16-bit character/ .................... XTextWidthl6 
pixels of an 8-bit character/ .................... XTextWidth 
pixmap ID ............................................... XFreePixmap 
pixrnap in a graphics context .................. XSetClipMask 
pixmap with depth from bitmap ............. XCreatePixmapFromBitmapData 
pixmap ..................................................... XCreatePixmap 
pixmap. /draw a rectangular ................... XPutImage 
place contents of a rectangle ................... XGetImage 
plane mask in a graphics/ ....................... XSetPlaneMask 
plane mask in a graphics ......................... XSetState 
plane of a drawable into a/ ..................... XCopyPlane 
planes. /allocate ...................................... XAllocColorPlanes 
planes. XFreeColors: .............................. XFreeColors 
point is inside a region ............................ XPointInRegion 

18 Xlib Reference Manual 



/get the standard colormap 
read the window manager hints 
of the XA_WM_ICON_SIZE 
/change the standard colormap 
set a window manager hints 
queue. XPutBackEvent: 
string to a binding list and a 
/convert a key string to a 
XrmQuarkToString: convert a 
convert a string to a 
XrmUniqueQuark: allocate a new 
resource from name and class as 
resource into a database using 
value to a database using 
font/XQueryTextExtentsl 6: 
font/XQueryTextExtents: 
without removing it from the 
XCheckIfEvent: check the event 
/return the next event in 
don't//return the next event in 
number of events in the event 
without removing it from the 
push an event back on the input 
the output buffer (display all 
the stacking/XRaiseWindow: 
XReadBitmapFile: 
XGetSizetlints: 
a zoomed/XGetZoomHints: 
property. XGetWMHints: 
XAllocNamedColor: allocate a 
XAllocColor: allocate a 
XStoreNamedColor: allocate a 
XStoreColors: set or change 
XStoreColor: set or change a 
XAllocColorPlanes: allocate 
XAllocColorCells: allocate 
client. XRebindKeysym: 
XClipBox: generate the smallest 
XGetImage: place contents of a 
location/XGetSubImage: copy a 
XRectInRegion: determine if a 
XUnionRectWithRegion: add a 
draw an arc fiuing inside a 
draw an outline of a 
draw the outlines of multiple 
graphics context to the list of 
XClearArea: clear a 
XFillRectangle: fill a 
XFilIRectangles: fill multiple 
or pixmap. XPutImage: draw a 
region. XShrinkRegion: 
XSubtractRegion: subtract one 
XPolygonRegion: generate a 
XEmptyRegion: determine if a 
smallest rectangle enclosing a 
create a new empty 
storage associated with a 

property ................................................... XGetStandardColormap 
property. XGetWMHints: ....................... XGetWMHints 
property. /set the value ........................... XSetIconSizes 
property ................................................... XSetStandardColormap 
property. XSetWMHints: ....................... XSetWMHints 
push an event back on the input ............. XPutBackEvent 
quark list. /convert a key ........................ XrmStringToBindingQuarkList 
quark list .................................................. XrmStringToQuarkList 
quark to a string ...................................... XrmQuarkToString 
quark. XrmStringToQuark: .................... XrmStringToQuark 
quark ........................................................ XrmUniqueQuark 
quarks. XrmQGetResource: get a .......... XrmQGetResource 
quarks. /store a ....................................... XrmQPutResource 
quarks. /add a string resource ................. XrmQPutStringResource 
query the server for string and ................ XQueryTextExtentsl6 
query the server for string and ................ XQueryTextExtents 
queue; do not wait. /an event ................. XPeeklfEvent 
queue for a matching event ..................... XChecklfEvent 
queue matching type and window .......... XCheckTypedWindowEvent 
queue that matches event type; ............... XCheckTypedEvent 
queue. /check the .................................... XEventsQueued 
queue. /get an event ................................ XPeekEvent 
queue. XPutBackEvent: ......................... XPutBackEvent 
queued requests). /flush .......................... XFlush 
raise a window to the top of ................... XRaiseWindow 
read a bitmap from disk .......................... XReadBitmapFile 
read any property of type/ ....................... XGetSizeHints 
read the size hints property of ................ XGetZoomHints 
read the window manager hints .............. XGetWMHints 
read-only colorcell from color/ ............... XAllocNamedColor 
read-only colormap cell with/ ................. XAllocColor 
read/write colorcell by English/ .............. XStoreNamedColor 
read/write colorcells to the/ ..................... XStoreColors 
read/write entry of a colormap/ .............. XStoreColor 
read/write (nonshareable) color/ ............. XAllocColorPlanes 
read/write (nonshared)/ ........................... XAllocColorCells 
rebind a keysym to a string for ............... XRebindKeysym 
rectangle enclosing a region ................... XClipBox 
rectangle from drawable into an/ ............ XGetlmage 
rectangle in drawable to a ....................... XGetSublmage 
rectangle resides in a region ................... XRectlnRegion 
rectangle to a region ................................ XUnionRectWithRegion 
rectangle. XDrawArc: ............................ XDrawArc 
rectangle. XDrawRectangle: ................... XDrawRectangle 
rectangles. XDrawRectangles: ............... XDrawRectangles 
rectangles. /clip_mask in a ..................... XSetClipRectangles 
rectangular area in a window .................. XClearArea 
rectangular area ....................................... XFillRectangle 
rectangular areas ...................................... XFillRectangles 
rectangular image on a window .............. XPutImage 
reduce or expand the size of a ................ XShrinkRegion 
region from another ................................ XSubtractRegion 
region from points ................................... XPolygonRegion 
region is empty ....................................... XEmptyRegion 
region. XClipBox: generate the ............. XClipBox 
region. XCreateRegion: .......................... XCreateRegion 
region. /deallocate .................................. XDestroyRegion 

20 Xlib Reference Manual 



change offset of a 
if a point is inside a 
if a rectangle resides in a 
context to the specified 
reduce or expand the size of a 
add a rectangle to a 
XEqualRegion: determine if two 
compute the intersection of two 
compute the union of two 
union and intersection of two 
XUngrabButton: 
XUngrabKey: 
XUngrabKeyboard: 
XUngrabPointer: 
XUngrabServer: 
/destroy a client or its 
control list. XRemoveltost: 
XChangeSaveSet: add or 
the] XRemoveFromSaveSet: 
access control/XRemoveHosts: 
both passed/XCheckWindowEvent: 
mask and window. XWindowEvent: 
matches mask;/XCheckMaskEvent: 
matches mask. XMaskEvent: 
not wait. /get an event without 
/get an event without 
the specified pixel value and 
border tile attribute and 
connection to a/XDisplayName: 
to allow or deny connection 
buffer (display all queued 
XResetScreenSaver: 
/determine ff a rectangle 
line/XrmParseCommand: load a 
XrmQGetSearchResource: search 
XrmPutLineResource: add a 
quarks. XrmQGetResource: get a 
strings. XrmGetResource: get a 
the//obtain the GContext 
XrmQPutResource: store a 
XrmPutResource: store a 
Xrmlnitialize: initialize the 
XrmPutStringResource:. add a 
using quarks. /add a string 
database levels for a given 
/and pointer events when these 
a client or its remaining 
file. XrmGetFileDatabase: 
to X/XListExtensions: 
parent, and root. XQueryTree: 
levels. XrmQGetSearchList: 
font names. XListFonts: 
/copy a colormap and 
string. XlntemAtom: 
XFetchB uffer: 
XFetchBytes: 
loaded font. XQueryFont: 

region. 
region. 
region. 
region. 
region. 
region. 
regions 
regions. 
regions. 

XOffsetRegion: .......................... XOffsetRegion 
/determine ................................... XPointInRegion 
/determine ................................... XRectInRegion 
/of the graphics ........................... XSetRegion 
XShrinkRegion: ......................... XShrinkRegion 
XUnionRectWithRegion: ........... XUnionRectWithRegion 
have the same size,/ ................... XEqualRegion 
Xl.ntersectRegion: ..................... XlntersectRegion 
XUnionRegion: ......................... XUnionRegion 

regions. /between the .............................. XXorRegion 
release a button from grab ...................... XUngrabButton 
release a key from grab ........................... XUngrabKey 
release the keyboard from grab .............. XUngrabKeyboard 
release the pointer from grab .................. XUngrabPointer 
release the server from grab .................... XUngrabServer 
remaining resources ................................ XKillClient 
remove a host from the access ................ XRemovelIost 
remove a subwindow from the/ .............. XChangeSaveSet 
remove a window's children from .......... XRemoveFromSaveSet 
remove multiple hosts from the .............. XRemoveHosts 
remove the next event matching ............. XCheckWindowEvent 
remove the next event matching ............. XWindowEvent 
remove the next event that ...................... XChecLMaskEvent 
remove the next event that ...................... XMaskEvent 
removing it from the queue; do .............. XPeeklfEvent 
removing it from the queue .................... XPeekEvent 
repaint the border. /to ............................. XSetWindowBorder 
repaint the border. /a window ................ XSetWindowBorderP/xrnap 
report the display name when ................. XDisplayName 
requests. /access control list ................... XEnableAccessControl 
requests). /flush the output ..................... XFlush 
reset the screen saver .............................. XResetScreenSaver 
resides in a region ................................... XRectInRegion 
resource database from command ........... XrmParseCommand 
resource database levels for a/ ................ XrmQGetSearchResource 
resource entry given as a/ ....................... XrmPutLineResource 
resource from name and class as ............ XrmQGetResource 
resource from name and class as ............ XrmGetResource 
(resource ID) associated with ................. XGContextFromGC 
resource into a database using/ ............... XrmQPutResource 
resource into a database .......................... XrmPutResource 
resource manager. ................................... Xrmlnitialize 
resource that is specified as a/ ................ XrmPutStringResource 
resource value to a database ................... XrmQPutStringResource 
resource. /search resource ....................... XrmQGetSearchResource 
resources are grabbed .............................. XAllowEvents 
resources. /destroy .................................. XKillClient 
retrieve a database from a ....................... XrmGetFileDatabase 
return a list of all extensions ................... XListExtensions 
return a list of children ........................... XQueryTree 
return a list of database ........................... XrmQGetSearchList 
return a list of the available .................... XListFonts 
return a new colormap ID ....................... XCopyColormapAndFree 
return an atom for a given name ............ XlnternAtom 
return data from a cut buffer ................... XFetchBuffer 
return data from cut buffer 0 .................. XFetchBytes 
return information about a ...................... XQueryFont 

Perm uted Index 21 



XDrawStringl6: draw two-byte 
border. /change a window border 
/change the background 
XSetTile: set the fill 
the "best" supported cursor, 
obtain the best supported fill 
graphics/XSetTSOrigin: set the 
stacking order. /circulate the 
XMapRaised: map a window on 
/the bottom child to the 
/raise a window to the 
color/XParseColor: look up or 
auto-repeat/XAutoRepeatOff: 
auto-repeat/XAutoRepeatOn: 
off. XForceScreenSaver: 
/create a cursor from 
XDrawLine: draw a line between 
XEqualRegion: determine if 
compute the intersection of 
compute the union of 
the union and intersection of 
XDrawString 16: draw 
window. /obtain the atom 
next event in queue matching 
in queue that matches event 
/to a window and context 
get the next event of any 
/read any property of 
/the value of any property of 
entry for a given window and 
XSelectInput: select the event 
default if/XUninstallColormap: 
[the difference between the 
XUnionRegion: compute the 
for the font/XFreeFont: 
X UnloadFont: 
XUnmapWindow: 
window. XUnmapSubwindows: 
all/XDestroyWindow: 
XCreateSimpleWindow: create an 
the stacking order of children 
ASCII color/XParscColor: look 
XRefreshKeyboardMapping: 
ControlJ/set keycodes to be 
/calculate window geometry given 
name and/XGetDefault: scan the 
a resource into a database 
resource value to a database 
/to the specified pixel 
and/XSaveContext: save a data 
/obtain a single pixel 
/set the background pixel 
/set the foreground pixel 
a constant value to every pixel 
XPutPixel: set a pixel 
XConvertSelection: use the 
XSetSizeltints: set the 

text strings ............................................... XDrawString 16 
tile attribute and repaint the .................... XSetWindowBorderPixmap 
tile attribute of a window ........................ XSetWindowBackgroundPixmap 
tile in a graphics context ......................... XSetTile 
tile, or stipple size. /obtain ..................... XQueryBestSize 
tile shape. XQueryBestTile: ................... XQueryBestTile 
tile/stipple origin in a .............................. XSetTSOrigin 
top child to the bottom of the ................. XCirculateSubwindowsUp 
top of its siblings .................................... XMapRaised 
top of the stacking order. ........................ XCirculateSubwindowsDown 
top of the stacking order ......................... XRaiseWindow 
translate RGB values from ASCII .......... XParseColor 
tum off the keyboard .............................. XAutoRepeatOff 
turn on the keyboard ............................... XAutoRepeatOn 
turn the screen saver on or ...................... XForceScreenSaver 
two bitmaps ............................................. XCreatePixmapCursor 
two points ................................................ XDrawLine 
two regions have the same sized ............ XEqualRegion 
two regions. XIntersectRegion: .............. XIntersectRegion 
two regions. XUnionRegion: ................. XUnionRegion 
two regions. /between ............................. XXorRegion 
two-byte text strings ................................ XDrawStringl6 
type and property format for a ................ XGetWindowProperty 
type and window. /return the ................. XCheckTypedWindowEvent 
type; don't wait. /next event .................. XCheckTypedEvent 
type (not graphics context) ..................... XSaveContext 
type or window. XNextEvent: ............... XNextEvent 
type XA_SIZE_I IINq'S .............................. XGetSizeHints 
type XA_SIZE_INq'S .............................. XSetSizeHints 
type. ]delete a context ............................. XDdeteContext 
types to be sent to a window .................. XSelectInput 
uninstall a colormap; install .................... XUninstallColormap 
union and intersection of two/ ................ XXorRegion 
union of two regions ............................... XUnionRegion 
unload a font and free storage ................ XFreeFont 
unload a font ........................................... XUnloadFont 
unmap a window ..................................... XUnmapWindow 
unmap all subwindows of a given .......... XUnmapSubwindows 
unmap and destroy a window and .......... XDestroyWindow 
unmapped InputOutput window ............. XCreateSimpleWindow 
up or down. /circulate ............................ XCirculateSubwindows 
up or translate RGB values from ............ XParseColor 
update the stored modifier and/ .............. XRefreshKeyboardMapping 
used as modifiers (Shift .......................... XSetModifierMapping 
user geometry string and/ ........................ XGeometry 
user preferences for program .................. XGetDefauh 
using quarks. /store ................................. XrmQPutResource 
using quarks. /add a string ..................... XrmQPutStringResource 

value 
value 
value 
value 
value 
value 
value 
value 
value 

and repaint the border. .................. XSetWindowBorder 
corresponding to a window ........... XSaveContext 
from an image ............................... XGetPixel 
in a graphics context ..................... XSetBackground 
in a graphics context ..................... XSetForeground 
in an image. /add .......................... XAddPixel 
in an image .................................... XPutPixel 
of a selection ................................. XConvertSelection 
of any property of type/ ................ XSetSizeHints 

26 Xlib Reference Manual 



--Xlib- Function Group 

Introduction 

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

Name 
FunctionName -- 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 
sons 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." 

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 Func- 
tionName as arguments or return values. It also contains definitions of important constants 
used by the function. Additional structures not shown can be found in Appendix F, Structure 
Reference. 

July 26, 1988 29 



Introduction (continued) Xlib - Function Group 

Errors 
The Errors section contains a list of the error event types that XFunctionName can generate. 
The general description of the error types is contained in Appendix B, Error Messages and 
Protocol Requests. Some functions generate errors due to function-specific interpretation of 
arguments. Where appropriate, these function-specific causes have been listed along with the 
error event types they generate. 

Related Commands 
The Related Commands secdon lists the Xlib functions and macros related to XFunction- 
Name. 

30 July 26, 1988 



XAddHost 

Xlib - Host Access-- 

Name 
XAddHost -- add a host to the access control list. 

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

Arguments 
display 

Specifies a pointer to the Display structure returned from XOpenDisplay. 

host 

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

Description 
XAdcIHost adds the specified host to the access control list for the server specified by 
display. 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 called letc/X?.hosts, where ? is the number of the display. 

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 
operates, as specified in the faraily member. Internet, DECnet and ChaosNet networks are 
currently 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 
contains 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; 
int length; 
char *address; 
} XHostAddress; 

/* for example FamilyInternet */ 
/* length of address, in bytes */ 
/* pointer to where to find the bytes */ 

/* The following constants for family member */ 
#define FamilyInternet 0 
#define FamilyDECnet 1 
#define FamilyChaos 2 

Errors 
BadAccess 
BadValue 

32 July 26, 1988 



Xlib- Host Access (continued) XAddHost 

Related Commands 
XAddHosts, XListHosts, XRemoveHost, XRemoveHosts, XDisableAccess- 
Control, XEnableAccessControl, XSetAccessControl. 

July 26, 1988 33 



Xlib - Host Access (continued) XAddHosts 

Errors 
BadAccess 
BadValue 

Related Commands 
XAddHost, XListHosts, XRemoveHost, XRemoveHosts, XDisableAccess- 
Control, XEnableAccessControl, XSetAccessControl. 

July 26, 1988 35 



XAddPixel k 

Xlib - Images-- 

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

Synopsis 
int XAddPixel(ximage, value) 
XImage *ximage; 
unsigned long value; 

Arguments 
ximage 

value 

Specifies a pointer to the image to be modified. 

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 _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 */ 
/* quantity 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 object routines to hang on */ 
/* image manipulation routines */ 

36 July 26, 1988 



Xlib -Images (continued) XAddPixel 

Related Commands 
XDestroyImage, XPutImage, XGetImage, XCreateImage, XSubImage, XGetSub- 
Image, XPutPixel, XGetPixel, ImageByteOrder. 

July 26, 1988 3 7 



XAddToSaveSet 

Xlib - Save Set m 

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

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

w) 

Arguments 
di spl ay 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the ID of the window whose children you want to add to the 
client's save-set. 

Description 
XAddToSaveSet adds the children of 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 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. See Volume One, Chapter 13, Other Programming Tech- 
niques, for more information about save-sets. 

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

Errors 
BadMatch 
BadWindow 

w not created by some other client. 

Related Commands 
XRemoveFromSaveSet, XChangeSaveSet. 

38 July 26 1988 



XAIIocColor (continued) Xlib - Color Cells 

Related Commands 
XAllocColorCells, XAllocColorPlanes, XAllocNamedColor, XLookupColor, 
XParseColor, XQueryColor, XQueryColors, XStoreColor, XStoreColors, 
XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel. 

40 July 26, 1988 



XAIIocColorCells (continued) Xlib - Color Cells 

Errors 
BadColor 
BadValue 

nplanes is negative. 
ncolors is not positive. 

Related Commands 
XAllocColorPlanes, XAllocColor, XAllocNamedColor, XLookupColor, 
XParseColor, XQueryColor, XQueryColors, XStoreColor, XStoreColors, 
XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel. 

42 July 26, 1988 



XAIIocColorPlanes (continued) Xlib - Color Cells 

or XStoreNarnedColor, the pixel is decomposed according to rmask, gmask, and bmask 
and the corresponding pixel subfield entries are updated. 
Seat:us is 0 on failure. 
For more information, see Volume One, Chapter 7, Color. 

Errors 
BadColor 
BadVa lue 

ncolors is not positive. 
At least one of nreds, ngreens, nblues is negative. 

Related Commands 
XAllocColorCells, XAllocColor, XAllocNamedColor, XLookupColor, 
XParseColor, XQueryColor, XQueryColors, XStoreColor, XStoreColors, 
XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel. 

44 July 26, 1988 



--Xlib - Color Cells 

XAIIocNamedColor 

Name 
XAllocNamedColor -- allocate a read-only colorcell from color name. 
Synopsis 
Status XAllocNamedColor ( display, cmap, colorname, 
colorcell_def , rgb_db_def) 

Display *display; 
Colormap cmap; 
char *colorname; 
XColor *colorcell def; 
XColor * rgb_db_def ; 

Arguments 
display 

cmap 
colorname 

/* RETURN */ 
/* RETURN */ 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the ID of the colormap in which the colorcell will be allocated. 
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 
CO1 orn ame supplied. 
Description 
XAllocNamedColor 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, XAllocNamedColor returns 
the closest read-only colorcell already allocated, and does not actually create or set any new 
colorcell. 
XAllocNamedColor returns a Status of 0 when it encounters an error or 1 when it 
succeeds. 
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 */ 

Xlib Reference Manual 45 



XAIIocNamedColor (continued) Xlib - Color Cells 

char pad; 
} XColor; 

Errors 
BadColor 

Related Commands 
XAllocColorCells, XAllocColorPlanes, XAllocColor, XLookupColor, 
XParseColor, XQueryColor, XQueryColors, XStoreColor, XStoreColors, 
XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel. 

46 July 26, 1988 



--Xlib - Input Handling 

XAIIowEvents 

Name 
XAllowEvents -- control the behavior of keyboard and pointer events when these resources 
are grabbed. 

Synopsis 
XAllowEvents(display, event mode, 
Display *display; 
int event mode; 
Time time; 

time) 

Arguments 
display 

event mode 

time 

Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the event mode. Pass one of these constan[s: AsyncPointer, 
SyncPointer, AsyncKeyboard, SyncKeyboard, ReplayPointer, 
ReplayKeyboard, AsyncBoth, or SyncBoth. 
Specifies the time when the grab should take place. Pass either a timestamp, 
expressed in milliseconds, or the constant CurrentTime. 

XAllowEvents releases the events queued in the server since the last XAllowEvents 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 XAllowEvents is called with AsyncPointer while the 
pointer is frozen by the client, pointer event processing resumes 
normally, 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 XAllowEvents is called with AsyncKeyboard while the 
keyboard 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 keyboard is not frozen by the client, but the keyboard need not 
be grabbed by the client. 
SyncPointer If XAllowEvents is called with SyncPointer while the 
pointer is frozen by the client, normal pointer event processing con- 
tinues until the next ButtonPress or ButtonRelease event is 
reported to the client. At this time, the pointer again appears to 

July26, 1988 47 



XAIIowEvents (continued) Xlib - Input Handling 

SyncKeyboard 

ReplayPointer 

ReplayKeyboard 

SyncBoth 

freeze. However, if the reported event causes the pointer grab to be 
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 
button is released. SyncPointer has no effect if the pointer is 
not frozen or not grabbed by the client. 

If XAllowEvents is called with SyncKeyboard while the key- 
board is frozen by the client, normal keyboard event processing 
continues 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 XAllowEvents 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 hierarchy (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 
client and if the keyboard is frozen as the result of an event. In 
other words, XGrabKey must have been called and the selected 
key combination pressed, or a previous XAllowEvents 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 
frozen twice by the client on behalf of two separate grabs, Sync- 
Both "thaws" for both (but a subsequent freeze for SyncBoth 
will only freeze each device once). 

48 July 26, 1988 



mXlib - User Preferences 

XAutoRepeatOn 

Name 
XAuRepeatOnmturn onthekeyboardauto-peatkeys. 
Synopsis 
XAutoRepeatOn(display) 
Display *display; 

Arguments 
display 

Specifies a pointer to the Display structure; returned from X0pen- 
Display. 

Description 
XAutoRepeat0n 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 
XGetDefault, XAutoRepeatOff, XBell, XGetKeyboardControl, XChange- 
KeyboardControl, XGetPointerControl. 

July 26, 1988 51 



XBell 

Xlib - User Preferences-- 

Name 
XBell -- ring the bell (Conlxol G). 
Synopsis 
XBell (display, percent) 
Display *display; 
int percent ; 

Arguments 
display 

percent 

Description 

Specifies a pointer to the Display sucture; returned from XOpenDisplay. 
Specifies the volume for the bell, relative to the base volume set with 
XChangeKeyboardControl. Possible values are -100 (off), through 0 
(base volume), to 100 (loudest) inclusive. 

Rings the bell on the keyboard at a volume relative to the base volume for the keyboard, 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) / i00] + percent 
and when percent is negative: 
volume = base + [ (base * percent) / i00] 
To change the base volume of the bell, set the bell_percent variable of XChange- 
Keyboa rdCont re i. 

Errors 
BadValue 

percent <-I00 or percent >I00. 

Related Commands 
XGetDefault, XAutoRepeatOff, XAutoRepeatOn, XGetKeyboardControl, 
XChangeKeyboardControl, XGetPointerControl. 

52 July 26, 1988 



XChangeGC 

Xlib - Graphics Context B 

Name 
XChangeGC m change the components of a given graphics context. 

Synopsis 
XChangeGC (display, gc, valuemask, 
Display *display; 
GC gc ; 
unsigned long valuemask; 
XGCValues * values ; 

val ues ) 

Arguments 
display 

gc 
valuemask 

val ues 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the graphics context. 
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. 

Specifies a pointer to the XGCValues structure. 

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 sym- 
bols 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_offset 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; 
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, LineOnOffDash, LineDoubleDash */ 
/* CapNotLast, CapButt, CapRound, CapProjecting */ 
/* JoinMiter, JoinRound, JoinBevel */ 
/* FillSolid, FillTiled, FillStippled */ 
/* EvenOddRule, WindingRule */ 

54 Ju26 1988 



Xlib - Graphics Context (continued) XChangeGC 

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; 
} XGCValues; 

#define GCFunction 
#define GCPlaneMask 
#define GCForeground 
#define GCBackground 
#define GCLineWidth 
#define GCLineStyle 
#define GCCapStyle 
#define GCJoinStyle 
#define GCFillStyle 
#define GCFilIRule 
#define GCTile 
#define GCStipple 
#define GCTileStipXOrigin 
#define GCTileStipYOrigin 
#define GCFont 
#define GCSubwindowMode 
#define GCGraphicsExposures 
#define GCClipXOrigin 
#define GCClipYOrigin 
#define GCClipMask 
#define GCDashOffset 
#define GCDashList 
#define GCArcMode 

Errors 
BadAlloc 
BadFont 
BadGC 
BadMatch 
BadP ixmap 
BadValue 

/* ArcChord, ArcPieSlice */ 
/* tile pixmap for tiling operations */ 
/* stipple 1 plane pixmap for stipping */ 
/* offset for tile or stipple operations */ 

/* default text font for text operations */ 
/* ClipByChildren, IncludeInferiors */ 
/* generate events on XCopy, Area, XCopyPlane*/ 
/* origin for clipping */ 

/* bitmap clipping; other calls for rects */ 
/* patterned/dashed line information */ 

(IL<<0) 
(IL<<I) 
(IL<<2) 
(IL<<3) 
(IL<<4) 
(IL<<5) 
(IL<<6) 
(IL<<7) 
(IL<<8) 
(IL<<9) 
(IL<<I0) 
(IL<<II) 
(IL<<I2) 
(IL<<I3) 
(IL<<I4) 
(IL<<I5) 
(IL<<I6) 
(IL<<I7) 
(IL<<I8) 
(IL<<I9) 
(IL<<20) 
(IL<<21) 
(IL<<22) 

July 26, 1988 55 



XChangeGC (continued) Xlib - Graphics Context 

Related Commands 
XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, XSet- 
TSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFill- 
Rule, XSetFillStyle, XSetForeground, XSetBackground, XSetFunction, 
XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, 
XSetClipRectangles, XSetRegion, XSetState, XSetSubwindowMode, 
DefaultGC. 

56 July 26 1988 



XChangeKeyboardMapping (continued) Xlib- Keyboard 

Errors 
BadAlloc 
BadValue first, keycode less an display->min_keycode. 
di sp I ay->ma x_ke yc ode exceeded (see above). 
Related Commands 
XDe leteModi fie rmapEnt ry, XInse rtModi fie rmapEnt ry, XF reeModi fie rmap, 
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifier- 
Map, XQueryKeymap, XStringToKeysym, XLookupKeysym, XRebindKeySym, 
XGetKeyboa rdMapping, XRe f re shKeyboa rdMapping, XLookupSt ring, XSet- 
Modi fie rMapping, XGetModi fie rMapping. 

60 July 26, 1988 



XChangePointerControl (continued) Xlib - Pointers 

Related Commands 
XQueryPointer, XWarpPointer, XGrabPointer, XChangeActivePointerGrab, 
XUngrabPointer, XGetPointerMapping, XSetPointerMapping, XGetPointer- 
Control. 

62 July 26, 1988 



mXlib - Window Save Set 

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 pointer D the Display sucture; returned from XOpen- 
Display. 

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 constant: SetModeInsert (adds 
the window to this client's save-set) or SetModeDelete (deletes the win- 
dow from this client's save-set). 

Description 
XChangeSaveSet controls the longevity of subwindows, which are normally destroyed 
when the parent is destroyed. 
The save-set of a client is a list of other client's windows which, if they are inferiors of one of 
the client's windows at connection close, should not be destroyed and should be remapped if 
they are unmapped. For example, a window manager which wants to add decoration to a win- 
dow by adding a "frame," might reparent an application's window to the "frame window." 
When the frame is destroyed, the application's window should not also be destroyed, but 
should be returned to its previous place in the window hierarchy. 

Windows are removed automatically from the save-set by the server when they are destroyed. 
For each window in the client's save-set, if the window is an inferior of a window created by 
the client, the save-set window is reparented to the closest ancestor such that the save-set win- 
dow is not an inferior of a window created by the client. If the save-set window is unmapped, 
a MapWindow request is performed on it. After save-set processing, all windows created by 
the client are destroyed. -For each nonwindow resource created by the client, the appropriate 
Free request is performed. All colors and colormap entries allocated by the client are freed. 
For more information on save-sets, see Volume One, Chapter 13, Other Programming Tech- 
niques. 

Errors 
BadMatch 

BadValue 
BadWindow 

w not created by some other client. 

Related Commands 
XAddToSaveSet, XRemoveFromSaveSet. 

July 26, 1988 65 



XChangeWindowAttributes 

Xlib - Window Attributes m 

Name 
XChangeWindowAttdbutes m set window attributes. 

Synopsis 
XChangeWindowAttributes(display, w, valuemask, 
Display *display; 
Window w; 
unsigned long valuemask; 
XSetWindowAttributes *attributes; 

attributes) 

Arguments 
di spl ay 

Specifies a pointer to the Display structure; returned from X0pen- 
Display. 
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 0, the rest 
is ignored, and attributes is not referenced. The values and restrictions 
are the same as for XCreateWindow. 
attributes Window attributes to be changed. The valuemask indicates which 
members 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 
Attributes. 
Changing the background does not cause the window contents to be changed. Use XClear- 
Window to cause the background to be repainted. Setting the border or changing the back- 
ground such that the border tile origin changes causes the border to be repainted. Changing 
the background of a root window to None or ParentRelative restores the default back- 
ground 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_planes, 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 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 Substructure- 
RedirectMask, ReSizeRedirectMask, and ButtonPressMask on any one window. 
If a client attempts to select on SubtructureRedirectMask, ResizeRedirectMask, 

66 July26, 1988 



Xlib - Window Attributes (continued) XChangeWindowAttributes 

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 ColormapNotify event. Chang- 
ing the colormap attribute of a visible window may have no immediate effect on the screen 
(because the map may not be installed until the window manager or client calls XTnstall- 
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; /* 
unsigned long background_pixel; /* 
Pixmap border_pixmap; /* 
unsigned long border_pixel; /* 
int bit_gravity; /* 
int win_gravity; /* 
int backing_store; /* 
unsigned long backing_planes; /* 
unsigned long backing_pixel; /* 
Bool save under; /* 
-- 
long event mask; /* 
-- 
long do_not_propagate_mask; /* 
Bool override redirect; /* 
-- 
Colormap colormap; /* 
Cursor cursor; /* 
} XSetWindowAttributes; 

pixmap, None, or ParentRelative */ 
background pixel */ 
pixmap, None, or CopyFromParent */ 
border pixel value */ 
one of bit gravity values */ 
one of the window gravity values */ 
NotUseful, WhenMapped, Always */ 
planes to be preseved if possible */ 
value to use in restoring planes */ 
should bits under be saved (popups) */ 
set of events that should be saved */ 
set of events that should not propagate 
override redirected config request */ 
colormap to be associated with window */ 
cursor to be displayed (or None) */ 

/* Definitions for valuemask argument of CreateWindow and ChangeWindowAttributes *j 

#define'CWBackPixmap (IL<<0) 
#define CWBackP ixel (IL<<I) 
#define CWBorderP ixmap (IL<<2) 
#define CWBorderP ixel (IL<<3) 
#define CWBitGravity (IL<<4) 
#define CWWinGravity (IL<<5) 
#define CWBackingStore (IL<<6) 
#define CWBackingPlanes (IL<<7) 
#define CWBackingPixel (IL<<8) 
#define CWOverrideRedirect (IL<<9) 
#define CWSaveUnder (IL<<I0) 
#define CWEventMask (IL<<II) 
#define CWDontPropagate (IL<<I2) 
#define CWColormap (IL<<I3) 
#define CWCursor (IL<<I4) 

July 26, 1988 67 



XChangeWindowAttributes (continued) Xlib - Window Attributes 

Errors 
BadAccess 
BadColor 
BadCursor 
BadMatch 
BadP ixmap 
BadValue 
BadWindow 

Related Commands 
XGetWindowAtt ributes, XSetWindowBackground, XSetWindowBackground- 
P ixmap, XS etWindowBo rde r, XS etWindowBo rde rP ixmap, XGetGeomet ry. 

68 July 26, 1988 



--Xlib - Input Handling 

XChecklfEvent 

Name 
XChecklfEvent -- check the event queue for a matching event. 

Synopsis 
Bool XCheckIfEvent (display, 
Display *display; 
XEvent *event ; 
Bool (*predicate) () ; 
char *args; 

event, predicate, args) 
/* RETURN */ 

Arguments 
display 

e ven t 

predicate 

arg 

Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Returns the matched event. 

Specifies the procedure that is called to determine if the next event matches 
your criteria. 
Specifies the user-specified argument that will be passed to the predicate pro- 
cedure. 

XCheckIfEvent 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, XCheckIfEvent returns False and flushes the output 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. 
In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the 
output buffer is flushed only if no matching events are found on the queue. This change is 
compatible with applications written for Release 1. 

For more information, see Volume One, Chapter 8, Events. 

Related Commands 
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheck- 
WindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, 
XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotion- 
Events, XIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending, 
XSynchronize, XSendEvent, QLength. 

July 26, 1988 69 



mXlib - Input Handling 

XCheckTypedEvent 

Name 
XCheckTypedEvent m return the next event in queue that matches event type; don't wait. 

Synopsis 
Bool XCheckTypedEvent(display, 
Display *display; 
int event_type; 
XEvent *report; 

event_type, report ) 

/* RETURN */ 

Arguments 
display 

e yen t_ type 
report 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the event type to be compared. 
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 event_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 out- 
put 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. 

In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the 
output buffer is flushed only if no matching events are found on the queue. This change is 
compatible with applications written for Release 1. 

For more information, see Volume One, Chapter 8, Events. 

Related Commands 
XSelectInput, XSetIputFocus, XGetInputFocus, XWindowEvent, XCheck- 
WindowEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMaskEvent, 
XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, XIfEvent, 
XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending, 
XSynchronize, XSendEvent, QLength. 

July 26, 1988 71 



XCheckTypedWindowEvent 

Xlib - Input Handling-- 

Name 
XCheckTypedWindowEvent -- return the next event in queue matching type and window. 

Synopsis 
BOO1 XCheckTypedWindowEvent (display, w, event_type, report) 
Display *display; 
Window w; 
int event_type ; 
XEvent *report ; /* RETURN */ 

Arguments 
display 

w 
e ve t_ t ype 
report 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the window ID. 
Specifies the event type to be compared. 
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 output 
buffer and returns False if the event is not found. 
In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the 
output buffer is flushed only if no matching events are found on the queue. This change is 
compatible with applications written for Release 1. 
For more information, see Volume One, Chapter 8, Events. 

Related Commands 
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheck- 
WindowEvent, XCheckTypedEvent, XMaskEvent, XCheckMaskEvent, XNext- 
Event, XEventsQueued, XAllowEvents, XGetMotionEvents, XIfEvent, 
XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending, 
XSynchronize, XSendEvent, QLength. 

72 July 26, 1988 



XCirculateSubwindows 

Xlib - Window Manipulation 

Name 
XCirculateSubwindows -- circulate the slacking order of children up or down. 
Synopsis 
XCirculateSubwindows (display, w, direction) 
Display *display; 
Window w; 
int direction; 

Arguments 
display 

w 
direction 

Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the window ID of the parent of the subwindows to be circulated. 
Specifies the direction (up or down) that you want to circulate the children. 
Pass either RaiseLowest or LowerHighest. 

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 slack. If you specify LowerHighest, this function lowers the highest mapped 
child (if any) that occludes another child to the bottom of the slack. Exposure processing is 
performed on formerly obscured windows. 

For more information, see Volume One, Chapter 14, Window Management. 

Errors 
BadValue 
BadWindow 

Related Commands 
XLowerWindow, XRaiseWindow, XCirculateSubwindowsDown, XCirculate- 
SubwindowsUp, XRestackWindows, XMoveWindow, XResizeWindow, XMove- 
ResizeWindow, XReparentWindow, XConfigureWindow, XQueryTree. 

74 July 26, 1988 



mXlib - Window Manipulation 

XCirculateSubwindowsDown 

Name 
XCirculateSubwindowsDown -- circulate the bottom child to the top of the stacking order. 
Synopsis 
XCirculateSubwindowsDown ( display, w) 
Display *display; 
Window w; 

Arguments 
display 

w 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the window ID of the parent of the windows to be circulated. 

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 
(display, w, LowerHighest). 

If some other client has selected SubstructureRedirectMask on the window, then a 
CirculateRequest event is generated, and no further processing is performed. 

For more information, see Volume One, Chapter 14, Window Management. 

Errors 
BadWindow 

Related Commands 
XLowerWindow, XRaiseWindow, XCirculateSubwindows, XCirculate- 
SubwindowsUp, XRestackWindows, XMoveWindow, XResizeWindow, XMove- 
ResizeWindow, XReparentWindow, XConfigureWindow, XQueryTree. 

July 26, 1988 75 



XCirculateSubwindowsUp 

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 pointer to the Display structure; returned from XOpen- 
Display. 

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. 

For more information, see Volume One, Chapter 14, Window Management. 

Errors 
BadWindow 

Related Commands 
XLowerWindow, XRaiseWindow, XCirculateSubwindows, XCirculate- 
SubwindowsDown, XRestackWindows, XMoveWindow, XResizeWindow, XMove- 
ResizeWindow, XReparentWindow, XConfigureWindow, XQueryTree. 

76 July 26 1988 



XClearArea (continued) Xlib - Drawing Primitives 

Window 

Window 

[x,y] width 
. 

[x, y] width = 0 

Errors 
BadMatch 

BadValue 
BadWindow 

Window 

Ix, y] width 

Window 

[x,y] width=O 
0 

Window is an InputOnly class window. 

Related Commands 
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDraw- 
Point, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, 
XCopyArea, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFill- 
Rectangle, XFillRectangles, XClearWindow. 

78 July 26, 1988 



mXlib- Drawing Primitives 

XClearWindow 

Name 
XClearWindow -- clear an entire window. 

Synopsis 
XClearWindow(display, 
Display *display; 
Window w; 

w) 

Arguments 
display 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the ID of the window to be cleared. 

Description 
XClearWindow clears a window, but does not cause exposure events. This function is 
equivalent to XClearArea ( display, w, O, O, O, O, False) . 
If the window has a defined 5ackground file or it is ParentRelative, the rectangle is filed 
with a plane_mask of all l's and function of GXcopy. If the window has 5ackground 
None, the contents of the window are not changed. 
For more information, see Volume One, Chapter 6, Drawing Graphics and Text. 

Errors 
BadMatch 
BadValue 
BadWindow 

If w is an InputOnly class window. 

Related Commands 
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDraw- 
Point, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, 
XCopyArea, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFill- 
Rectangle, XFillRecgangles, XClearArea. 

July 26, 1988 79 



Xlib - Window Manipulation (continued) XConfigureWindow 

Exposure processing is performed on formerly obscured windows, including the window itself 
and its inferiors, if regions of them were obscured but now are not. As a result of increasing 
the width or height, exposure processing is also performed on any new regions of the window 
and any regions where window contents are lost. 

The members of XWindowChanges that you specify in values are: 

x 
Y 
width 
height 

Specify the x and y coordinates of the upper-left outer corner of the window 
relative to the parent's origin. 

Specify the inside size of the window in pixels, not including the border. 
These arguments must be positive. 

border width 
-- 
Specifies the width of the border in pixels. 

sibling 

stack mode 
-- 

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. 

The stack mode can be any ofthese constants: Above, Below, TopIf, 
BottomIf, orOpposite. 

The computation for the BottomIf, TopIf, and Opposite stacking modes is performed 
with respect to window w's final size and position (as conxolled 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 

Above 
Below 
TopIf 

BottomIf 

Opposite 

Position 

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 th6 stack 
if sibling occludes w, then w is placed at the top 
of the stack, else if w occludes sibling, then w is 
placed at the bottom of the stack 

July 26, 1988 83 



XConfigureWindow (continued) Xlib - Window Manipulation 

If a stack_mode is specified but no sibling is specified, the window is restacked as follows: 

Stacking Flag 

Above 
Below 
TopIf 

BottomIf 

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 

Structures 
typedef struct { 
int x, y; 
int width, height; 
int border width; 
-- 
Window sibling; 
int stack mode; 
-- 
} XWindowChanges; 

/* ConfigureWindow structure */ 
/* ChangeWindow value bits definitions for valuemask */ 

#define CWX (I<<0) 
#define CWY (I<<I) 
#define CWWidth (1<<2) 
#define CWHeight (1<<3) 
#define CWBorderWidth (1<<4) 
#define CWSibling (1<<5) 
#define CWStackMode (1<<6) 

Errors 
BadMatch 

BadValue 
BadWindow 

Nonzero border_width of InputOnly window. 
sibling specified without a stack mode. 
-- 
The sibling window is not actually a sibling. 

width or height is O. 

Related Commands 
XLowerWindow, XRaiseWindow, XCirculateSubwindows, XCirculate- 
SubwindowsDown, XCirculateSubwindowsUp, XRestackWindows, XMove- 
Window, XResizeWindow, XMoveResizeWindow, XReparentWindow, XQuery- 
Tree. 

84 July 26, 1988 



XConvertSelection (continued) Xlib - Selections 

Related Commands 
XSetSelectionOwner, XGetSelect ionOwner. 

86 July 26, 1988 



mXlib- Drawing Primitives 

XCopyArea 

Name 
XCopyArea -- copy an area of a drawable. 

Synopsis 
XCopyArea(display, src, 
height, dest x, 
-- 
Display *display; 
Drawable src, dest; 
GC gc; 
int src_x, src_y; 
unsigned int width, height; 
int dest_x, dest_y; 

dest , gc, src_x, src_y, width, 
de s t_y ) 

Arguments 
display 

src 
dest 
gc 
src x 
-- 
src_y 
width 
height 
dest x 
-- 
dest_y 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specify the source and destination rectangles to be combined, src and 
dest must have the same root and depth. 
Specifies the graphics context. 
Specify the x and y coordinates of the upper-left comer of the source rectan- 
gle relative to the origin of the source drawable. 
Specify the dimensions in pixels of both the source and destination rectan- 
gles. 
Specify the x and y coordinates within the destination window. 

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 regio.ns of the source rectangle are obscured and have not been retained in 
backing_store, or if regions outside the boundaries of the source drawable are specified, 
then those regions are not copied. Instead, the following occurs on all corresponding destina- 
tion 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 l's and function GXcopy) with that background. Regardless of til- 
ing, if the destination is a window and graphics_exposure in gc is True, then 
GraphicsExpose events for all corresponding destination regions are generated. If 
graphics_exposure is True but no regions are exposed, then a NoExpose event is gen- 
erated. 
If regions of the source rectangle are not obscured and graphics_exposure is False, 
one NoExpose event is generated on the destination. 

July 26, 1988 8 7 



--Xlib - Colormaps 

XCopyColormapAndFree 

Name 
XCopyColormapAndFree -- copy a colormap and return a new colormap ID. 
Synopsis 
Colormap XCopyColormapAndFree ( display, cmap) 
Display *display; 
Colormap cmap ; 

Arguments 
display 

cmap 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the colormap you are moving out of. 

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. Values in other entries of the new 
colormap are undefined. 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 alloc argument set to AllocAll, 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. 

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

Errors 
BadAlloc 
BadColor 

Related Commands 
XCreateColormap, XFreeColormap, XGetStandardColormap, XInstall- 
Colormap, XUninstallColormap, XSetStandardColormap, XListInstalled- 
Colormaps, XSetWindowColormap, DefaultColormap, DisplayCells. 

July 26, 1988 89 



XCopyGC 

Xlib - Graphics Context-- 

Name 
XCopyGC -- copy a graphics context. 

Synopsis 
XCopyGC(display, src, valuemask, 
Display *display; 
GC src, dest; 
unsigned long valuemask; 

dest) 

Arguments 
display 

src 
valuemask 

dest 

Specifies a pointer to the Display sucture; retumed from XOpen- 
Display. 

Specifies the components of the source graphics context. 
Specifies the components in the source GC structure to be copied into the 
destination GC. va2uemask is made by combining any number of the 
mask symbols listed in the Structures section using bitwise OR (1). 
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; 
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; 
int ts_y_origin; 
Font font; 
int subwindow_mode; 

/* logical operation */ 
/* plane mask */ 
/* foreground pixel */ 
/* background pixel */ 
/* line width */ 
/* Solid, OnOffDash, DoubleDash */ 
/* NotLast, Butt, Round, Projecting */ 
/* Miter, Round, Bevel */ 
/* Solid, Tiled, Stippled */ 
/* EvenOdd, Winding */ 
/* PieSlice */ 
/* tile pixmap for tiling operations */ 
/* stipple 1 plane pixmap for stipping */ 
/* offset for tile or stipple operations */ 

/* default text font for text operations */ 
/* ClipByChildren, IncludeInferiors */ 

90 July 26, 1988 



XCopyPlane 

Xlib- Drawing Primitives m 

Name 
XCopyPlane -- copy a single plane of a drawable into a drawable with depth, applying pixel 
values. 

Synopsis 
XCopyPlane (display, src, dest, go, src_x, src_y, wldth, 
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 
di spl ay 

src 
dest 
gc 
src x 
-- 
src_y 
width 
height 
dest x 
-- 
dest_y 
plane 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specify the source and destination drawables. 

Specifies the graphics context. 
Specify the x and y coordinates of the upper-left corner of the source rectan- 
gle relative to the origin of the drawable. 
Specify the width and height in pixels. These are the dimensions of both the 
source and destination rectangles. 
Specify the x and y coordinates at which the copied area will be placed rela- 
tive to the origin of the destination drawable. 
Specifies the source bit-plane. You must set exactly one bit. 

XCopyPlane copies a single plane of a rectangle in the source into the entire depth of a 
corresponding rectangle in the destination. The plane of the source drawable and the 
foreground/background pixel values in gc are combined to form a pixmap of the same 
depth as the destination drawable, and the equivalent of an XCopyArea is performed, with all 
the same exposure semantics. 

XCopyPlane uses these graphics context component: function, plane_mask, 
foreground, background, subwindow_mode, graphics_exposures, 
clip x origin, clip_y_origin, and clip_mask. 

src and dest must have the same root, but need not have the same depth. 

For more information, see Volume One, Chapter 5, The Graphics Context. 

92 July 26, 1988 



Xlib- Drawing Primitives (continued) XCopyPlane 

Errors 
BadDrawable 
BadGC 
BadMatch 
BadValue 

src and dest do not have the same root. 
plane does not have exactly one bit set. 

Related Commands 
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDraw- 
Point, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, 
XCopyArea, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFill- 
Rectangles, XClearArea, XClearWindow. 

July 26, 1988 93 



XCreateAssocTable 

Xlib - Association Tables m 

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/XIO.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, Chapter 13, Other Programming 
Techniques. 

Structures 
typedef struct { 
XAssoc *buckets; 
int size; 
} XAssocTable; 

/* pointer to first bucket in array */ 
/* table size (number of buckets) */ 

Related Commands 
XDeleteAssoc, XDestroyAssocTable, XLookUpAssoc, XMakeAssoc. 

94 July26, 1988 



mXlib - Pixmaps and Tiles 

X Crea te B it m ap F rom Data 

Name 
XCreateBitmapFromData -- create a bitmap from X11 bitmap format data. 

Synopsis 
Pixmap XCreateBitmapFromData ( display, 
width, height) 
Display *display; 
Drawable drawable ; 
char *data; 
unsigned int width, height ; 

dra wabl e, da t a, 

Arguments 
di spl ay 

dra wabl e 

data 
wi dth 
height 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the drawable. This determines which screen to create the bitmap 
on. 
Specifies the location of the bitmap data. 
Specify the dimensions in pixels of the created bitmap. If smaller than the 
original bitmap, the upper-left corner 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 
version 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: 

format=XYPixmap 
bit order=LSBFirst 
byte_order=LSBFirst 
bitmap_unit=8 
bitap_pad=8 
xoffset=0 
no extra bytes per line 

XCreateBitmapFromData creates an image with the spifi data and copies it into the 
created pixmap. The following is an example of creating a bitmap: 

July 26, 1988 95 



XCreateBitmapFromData (continued) Xlib - Pixmaps and Tiles 

#define gray_width 16 
#define gray_height 16 
#define gray. x hot 8 
#define gray_y_hot 8 
static char gray_bits [ ] -- 
{ 
0xf81f, 0xe3c7, 0xcff3, 0x9ff9, 
0xbffd, 0x33cc, 0x7ffe, 0x7ffe, 
0x7e7e, 0x7ffe, 0x37ec, 0xbbdd, 
0x9c39, 0xcff3, 0xe3c7, 0xf81f 
}; 

Pixmap XCreateBitmapFromData (display, window, gray_bits, 
gray_width, gray_height) ; 
If insufficient working storage was ]located, XCreateBitmapFromData returns NULL. 
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 

Related Commands 
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindow- 
BackgroundPixmap, XCreatePixmap, XCreatePixmapFromBitmapData, XFree- 
Pixmap, XQueryBestSize, XQueryBestStipple, XWriteBitmapFile, XRead- 
BitmapFile, XCreatePixmapFromBitmapData. 

96 July 26 1988 



mXlib - Colormaps 

XCreateColormap 

Name 
XCreateColormap -- create a colormap. 

Synopsis 
Colormap XCreateColormap(display, 
Display *display; 
Window w; 
Visual *visual; 
int alloc; 

w, visual, alloc) 

Arguments 
di spl ay 

visual 

a!loc 

Description 

Specifies a pointer to the Display structure; returned from X0pen- 
Display. 
Specifies a window ID. The colormap created will be associated with the 
same screen as the window. 

Specifies a pointer to the visual structure for the colormap. The visual 
class and depth must be supported by the screen. 
Specifies how many colormap entries to allocate. Pass either AllocNone 
or AIIocAII. 

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 X11 proto- 
col. In these cases, alloc must be specified as AllocNone (else a BadNatch 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 ini- 
tial 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 AllocAII, this function 
simulates many calls to the function XAIIocColor returning all pixel values from 1 tO 
(map_entries - 1). For a visual class of DirectColor, the processing for Alloc- 
All simulates a call to the function XAllocColorPlanes, returning a pixel value of 0 and 
mask values the same as the red mask, green, mask, and blue. mask members in 
-- 
visual. 

July 26, 1988 97 



XCreateColormap (continued) Xlib- Colormaps 

The visual structure should be as returned from the DefaultVisual macro, XMatch- 
VisualInfo, or XGetVisualInfo. The red_mask, green_mask, and blue_mask 
members specify which bits of the pixel value are allocated to each primary color. The 
rnap_ent ries member specifies the number of colormap entries. 

For more information on creating colormaps, see Volume One, Chapter 7, Color. 

Errors 
BadAlloc 
BadMatch 

BadValue 
BadWindow 

Didn't use AllocNone for StaticColor, 
TrueColor. 
visual type not supported on screen. 

StaticGray, or 

Related Commands 
XCopyColormapAndFree, XFreeColormap, XGetStandardColormap, XInstall- 
Colormap, XUninstallColormap, XSetStandardColormap, XListInstalled- 
Colormaps, XSetWindowColormap, DefaultColormap, DisplayCells. 

98 July 26, 1988 



mXlib - Cursors 

XCreateFontCursor 

Name 
XCreateFontCursor -- create a cursor from the standard cursor font. 

Synopsis 
#include <Xll/cursorfont.h> 
Cursor XCreateFontCursor(display, shape) 
Display *display; 
unsigned int shape; 

Arguments 
display 

shape 

Specifies a pointer to the Display structure; returned from XOpenDisplay. 
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 swapped between clients. 

The hotspot comes from the information stored in the font. The initial colors of the cursor are 
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. 

July 26, 1988 99 



XCreateFontCursor (continued) Xlib - Cursors 

Errors 
BadAlloc 
BadMatch 
BadValue 

Related Commands 
XDefineCursor, XUndefineCursor, XCreateGlyphCursor, XCreatePixmap- 
Cursor, XFreeCursor, XRecolorCursor, XQueryBestCursor, XQueryBest- 
Size. 

1 O0 July 26, 1988 



DXlib - 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 
display 

dra wabl e 
valuemask 

values 

Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the 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 com- 
ponents for the new GC. 

This function creates a new GC, replacing the old one if there was one. The specified com- 
ponents of the new graphics context in valuetask are set to the values passed in the 
values argument. Unset components default as follows: 

Component 
function 
plane_mask 
foreground 
background 
line width 
-- 
line.style 
cap_style 
join_style 
fill_style 
fill rule 
-- 
arc mode 
-- 
tile 
stipple 
ts x origin 
ts_y_origin 

Value 

GXcopy 
all l's 
0 
0 
LineSoiid 
CapButt 
JoinMiter 
FillSolid 
EvenOddRule 
ArcPieSlice 
Pixmap filled with reground pixel 
Pixmap filled with l's 
0 
0 

July 26, 1988 101 



XCreateGC (continued) Xlib - Graphics Context 

Component 

font 
subwindow mode 
-- 
graphic s_expo su re s 
clip_x_origin 
clip_y_origin 
clip_mask 
dash offset 
dash list 
-- 

Value 

(implementation dependent) 
ClipByChildren 
True 
0 
0 
None 
0 
4 (i.e., the list [4, 4]) 

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; 
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; 

/* logical operation */ 
/* plane mask */ 
/* foreground pixel */ 
/* background pixel */ 
/* line width */ 
/* LineSolid, LineOnOffDash, LineDoubleDash */ 
/* CapNotLast, CapButt, CapRound, CapProjecting */ 
/* JoinMiter, JoinRound, JoinBevel */ 
/* Fill$olid, FillTiled, FillStippled */ 
/* EvenOddRule, WindingRule */ 
/* 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, IncludeInferiors */ 
/* generate events on XCopyArea, XCopyPlane */ 
/* origin for clipping */ 

/* bitmap clipping; other calls for rects */ 
/* patterned/dashed line information */ 

#define GCFunction 
#define GCPlaneMask 
#define GCForeground 
#define GCBackground 
#define GCLineWidth 
#define GCLineStyle 
#define GCCapStyle 
#define GCJoinStyle 
#define GCFillStyle 
#define GCFilIRule 
#define GCTile 

(IL<<0) 
(IL<<I) 
(IL<<2) 
(IL<<3) 
(IL<<4) 
(IL<<5) 
(IL<<6) 
(IL<<7) 
(IL<<8) 
(IL<<9) 
(IL<<I0 

102 July 26, 1988 



Xlib - Graphics Context (continued) XCreateGC 

#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 

GCStipple 
GCTileStipXOrigin 
GCTileStipYOrigin 
GCFont 
GCSubwindowMode 
GCGraphicsExposures 
GCClipXOrigin 
GCClipYOrigin 
GCClipMask 
GCDashOffset 
GCDashList 
GCArcMode 

IL<<II) 
IL<<I2) 
IL<<I3) 
IL<<I4) 
IL<<I5) 
IL<<I6) 
IL<<I7) 
IL<<I8) 
IL<<I9) 
IL<<20) 
IL<<21) 
IL<<22) 

Errors 
BadAlloc 
BadDrawable 
BadFont 
BadMatch 
BadPixmap 
BadValue 

Related Commands 
XChangeGC, XCopyGC, XFreeGC, XGContextFromGC, XSetStipple, XSet- 
TSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFill- 
Rule, XSetFillStyle, XSetForeground, XSetBackground, XSetFunction, 
XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, 
XSetClipRectangles, XSetState, XSetSubwindowMode, DefaultGC. 

July 26, 1988 103 



XCreateGlyphCursor 

Xlib - Cursors 

Name 
XCreateGlyphCursor -- create a cursor from font glyphs. 
Synopsis 
Cursor XCreateGlyphCursor (display, source_font, 
source_char, mask_char, foreground_color, 
ba ckground_col or) 
Display *display; 
Font source font, mask font; 
__ -- 
unsigned int source_char, mask_char; 
XColor *foreground_color; 
XColor *background_color; 

mask font, 
-- 

Arguments 
display 

source font 
-- 

mask font 
-- 

source char 
-- 

mask char 
-- 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the font from which a character is to be used for the cursor. 
Specifies the mask font. Optional; specify 0 if not needed. 
Specifies the index into the cursor shape font. 
Specifies the index into the mask shape font. Optional; specify 0 if not 
needed. 

foreground_color 
Specifiesthered, green, andblue(RGB) values rthe reground. 

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 rectan- 
gle 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, the 16-bit value should be formed with the bytel 
member in the most significant byte and the byte2 member in the least significant byte. 

104 July 26, 1988 



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; 
char pad; 
} XColor; 

/* DoRed, DoGreen, DoBlue */ 

Errors 
BadAlloc 
BadFont 
BadValue 

source char not defined in source font. 
-- -- 
mask char not defined in mask font (if mask font defined). 

Related Commands 
XDefineCursor, XUndefineCursor, XCreateFontCursor, XCreatePixmap- 
Cursor, XFreeCursor, XRecolorCursor, XQueryBestCursor, XQueryBest- 
Size. 

July 26, 1988 105 



XCreatelmage 

Xlib - Images m 

Name 
XCreatelmage m allocate memory for an XImage structure. 

Synopsis 
#include <Xll/Xutil .h> 
XImage *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 

visual 

depth 
format 

offset 

data 
width 
height 
bitmap_pad 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies a pointer to a visual that should match the visual of the window the 
image is to be displayed in. 
Specifies the depth of the image. 
Specifics the format for the image. Pass one of these constants: xYPixmap, 
or ZPixmap. 
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. 
Specifies a pointer to the image data. 
Specify the width and height in pixels of the image. 

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, 
16, or 32. 

bytes__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 0 here, Xlib 
assumes that the scan lines are contiguous in memory and thus calculates the 
value of bytes, per_line itself. 

106 July 26, 1988 



XCreatePixmap 

Xlib - Pixmaps and Tiles m 

Name 
XCreatePixmap -- create a pixmap. 
Synopsis 
Pixmap XCreatePixmap (display, drawable, 
Display *display; 
Drawable drawable; 
unsigned int width, height ; 
unsigned int depth; 

width, height, 

depth) 

Arguments 
display 

dra wabl e 
width 
height 
depth 

Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the drawable. May be an InputOnly window. 
Specify the width and height in pixels of the pixmap. The values must be 
nonzero. 
Specifies the depth of the pixmap. The depth must be supported by the 
screen of the specified drawable. 

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 used with other draw- 
ables 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 systems 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 O. 
depth is not supported by root window. 

Related Commands 
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindow- 
BackgroundPixmap, XCreatePixmapFromBitmapData, XFreePixmap, XQuery- 
BestSize, XQueryBestStipple, XWriteBitmapFile, XReadBitmapFile, 
XCreateBitmapFromData. 

108 July 26, 1988 



XCreatePixmapCursor (continued) Xlib - Pixmaps and Tiles 

Structures 
typedef struct { 
unsigned long pixel; 
unsigned short red, green, blue; 
char flags; 
char pad; 
} XColor; 

/* DoRed, DoGreen, DoBlue */ 

Related Commands 
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindow- 
BackgroundPixmap, XCreatePixmap, XFreePixmap, XQueryBestSize, XQuery- 
BestStipple, XWriteBitmapFile, XReadBitmapFile, XCreateBitmapFrom- 
Data. 

110 July 26, 1988 



mXIIb - Pixmaps and Bitmaps 

XCreatePixmapFromBitmapData 

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 
di spl ay 

dra wahl e 

data 
wi dth 
height 
fg 
bg 
depth 

Description 

Specifies a pointer to the Display structure, returned from XOpen- 
Display. 
Specifies a drawable ID which indicates which screen the pixmap is to be 
used on. 

Specifies the data in bitmap format. 
Specify the width and height in pixels of the pixmap to create. 

Specify the foreground and background pixel values to use. 

Specifies the depth of the pixmap. Must be valid on the screen specified by 
dra wahl e. 

XCreatePixmapFromBitmapData creates a pixmap of the given depth using biunap data 
and foreground and background pixel values. 
The following format for the data is assigned by default, where the variables are members of 
the x.Iraage structure described in Volume One, Chapter 6, Drawing Graphics and Text: 
format=XYPixmap 
bit order=LSBFirst 
byte order=LSBFirst 
bitmap_unit =8 
bitmap_2ad=8 
xoffset=0 
no extra bytes per line 

XCreatePixmapFromBitmapData creates an image from the data and uses xPutImage 
to place the data into the pixmap. For example: 

July 26, 1988 111 



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 [ ] = 
{ 
0xf81f, 0xe3c7, 0xcff3, 0x9ff9, 
0xbffd, 0x33cc, 0x7ffe, 0x7ffe, 
0x7e7e, 0x7ffe, 0x37ec, 0xbbdd, 
0x9c39, 0xcff3, 0xe3c7, 0xf81f/* example data */ 
}; 
unsigned long foreground, background; 
unsigned int depth; 

/* open display, determine colors and depth */ 

Pixmap XCreatePixmapFromBitmapData (display, window, gray_bit s, 
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 systems have limits on the 
amount of off-screen memory available. 

Errors 
BadAlloc 
BadMatch 

Related Commands 
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindow- 
BackgroundPixmap, XCreatePixmap, XFreePixmap, XQueryBestSize, XQuery- 
BestStipple, XWriteBitmapFile, XReadBitmapFile, XCreateBitmapFrom- 
Data. 

112 July 26 1988 



--Xlib- Regions 

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 opera- 
dons on regions can also create regions. 

For a description of regions, see Volume One, Chapter 6, Drawing Graphics and Text. 

Structures 
typedef struct 

_XREGION *Region;/* opaque reference to region type */ 

Related Commands 
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion, 
XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPoint- 
InRegion, XOffsetRegion, XIntersectRegion, XEmptyRegion, XDestroy- 
Region, XEqualRegion, XClipBox. 

July 26, 1988 113 



XCreateSimpleWindow 

Xlib - Window Existence-- 

Name 
XCreateSimpleWindow -- create an unmapped Inputoutput window. 

Synopsis 
Window XCreateSimpleWindow(display, parent, x, y, 
height, border width, border, background) 
-- 
Display *display; 
Window parent; 
int x, y; 
unsigned int width, height, border_width; 
unsigned long border; 
unsigned long background; 

width, 

Arguments 
di spl ay 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
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 width 
-- 
Specifies the width, in pixels, of the new window's border. 
Specifies the pixel value for the border of the window. 
Specifies the pixel value for the background of the window. 

border 
ba ckgroun d 
Description 

XCreateSimpleWindow creates an unmapped InputOutput subwindow of the specified 
parent window. Use XCreateWindow to set the attributes to create an InputOnly win- 
dow while creating a window. 
XCreateSirnpleWindow 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 XMapWindow to display it. This function generates a CreateNotify 
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. 

114 July 26, 1988 



XCreateWindow 

Xlib - Window Existence-- 

Name 
XCreateWindow -- create a window and set atibutes. 

Synopsis 
Window XCreateWindow (display, parent, x, y, 
border width, depth, class, visual, 
-- 
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 ; 

width, height, 
valuemask, 

Arguments 
di spl ay 

Specifies a pointer to the Display structure; returned from XOpenDisplay. 

pa ren t 

Specifies the parent window. Parent must be InputOutput if class of win- 
dow created is to be InputOutput. 

Specify the x and y coordinates of the upper-left pixel of the new window's 
border relative to the origin of the parent (upper left inside the parent's border). 

width 
height 

Specify the width and height, in pixels, of the window. These are the new 
window's inside dimensions. These dimensions do not include the new 
window's borders, which are entirely outside of the window. Must be nonzero, 
otherwise XCreateWindow generates a BadValue error. 

border width 
-- 
Specifies the width, in pixels, of the new window's border. Must be 0 for 
InputOnly windows, otherwise a BadMatch error is returned. 

depth 

Specifies the depth of the window, which is not necessarily the same as the 
parent's depth. A depth of 0 for class InputOutput or CopyFromParent 
means the depth is taken from the parent. 

class 

Specifies the new window's class. Pass one of these constants: Input- 
0utput, InputOnly, orCopyFromParent. 

visual 

Specifies a pointer to the visual structure describing the colormaps to be used 
with this window. CopyFromParent is valid. 

valuemask 

Specifies which window attributes are defined in the attributes argument. 
If valuemask is 0, the rest is ignored, and attributes is not referenced. 
This mask is the inclusive OR of the valid attribute mask bits. 

116 July 26, 1988 



XCreateWindow (continued) Xlib - Window Existence 

#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 

CWBitGravity (IL<<4) 
CWWinGravity (IL<<5) 
CWBackingStore (IL<<6) 
CWBackingPlanes (IL<<7) 
CWBackingPixel (IL<<8) 
CWOverrideRedirect (IL<<9) 
CWSaveUnder (IL<<I0) 
CWEventMask (IL<<II) 
CWDontPropagate (IL<<I2) 
CWColormap (IL<<I3) 
CWCursor (IL<<I4) 

Errors 
BadAlloc 

BadColor 
BadCursor 
BadMatch 
BadPixmap 
BadValue 
BadWindow 

A[ibu[e besides win_gravity, event_mask, do_not_propagate_ 
mask, override redirect or cursor specied for InputOnly. 
-- 
depth nonzero for InputOnly. 
Pren[ of InputOutput Js InputOnly. 
border width is nonzero for InputOnly. 
-- 
depth no[ suppor[ed on screen for InputOutput. 
width or height is O. 
visual [ype no[ supported on screen (eider InputOnly or Input- 
Output). 

Related Commands 
XCreateSimpleWindow, XDestroySubwindows, XDestroyWindow. 

118 July 26 1988 



XDeleteAssoc 

Xlib - Association Tables m 

Name 
XDeleteAssoc -- delete an entry from an association table. 

Synopsis 
XDeleteAssoc(display, table, 
Display *display; 
XAssocTable *table; 
XID x id; 

Arguments 
display 

x id) 
-- 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies one of the association tables created by XCreateAssocTable. 
Specifies the X resource ID of the association to be deleted. 

table 
x id 
-- 
Description 
This function is provided for compatibility with X Version 10. To use it you must include the 
file <X11/X10.h> and link with the library -loldX. 
XDeleteAssoc deletes an association in an XAssocTable keyed on its XlD. Redundant 
deletes (and deletes of nonexistent XlD'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, Chapter 13, Other Programming 
Techniques. 

Structures 
typedef struct { 
XAs soc *buckets; 
int size; 
} XAs s ocTable; 

/* pointer to first bucket in array */ 
/* table size (number of buckets) */ 

Related Commands 
XCreateAssocTable, XDestroyAssocTable, XLookUpAssoc, XMakeAssoc. 

120 July 26, 1988 



XDeleteModifiermapEntry 

Xlib - Resource Manager m 

Name 
XDeleteModifiermapEntry- delete an enlxy from an XModifierKeymap structure. 

Synopsis 
XModifierKeymap *XDeleteModifiermapEntry (modmap, 
keysym_entry, modifier) 
XModifierKeymap *modmap ; 
KeyCode keysym_en try ; 
int modifier; 

Arguments 
modmap Specifies a pointer to an XModifierKeymap Sucture. 
k eysym_ en try 
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: ShiftMap- 
Index, LockMapIndex, Cont rolMapIndex, ModlMapIndex, Mod2- 
MapIndex, Mod3MapIndex, Mod4MapIndex, or Mod5MapIndex. 

Description 
XDeleteModifiermapEntry returns an XModifierKeymap structure suitable for cal- 
ling XSetModifierMapping, in which the specified keycode is deleted from the set of 
keycodes that is mapped to [he specified modifier (like Shift or Control). XDelete- 
ModifierraapEnt ry does not change the mapping itself. 

This function is normally used by calling XGetModifierMapping to get a pointer to the 
current XModifierKeymap S'ucture for use as the modmap argument to XDelete- 
Modi fie rmapEnt ry. 

Note that the sucture pointed to by modmap is freed by XDeleteModifiermapEntry. 
It should not be freed or otherwise used by applications. 

For a description of the modifier map, see XSetModifierMapping. 

Structures 
typedef struct { 
int max_keypermod; 
KeyCode *modifiermap; 

} XModifierKeymap; 

/* server's max number of keys per modifier */ 
/* an 8 by max_keypermod array of 
* keycodes to be used as modifiers */ 

#define ShiftMapIndex 
#define LockMapIndex 
#define ControlMapIndex 
#define ModlMapIndex 
#define Mod2MapIndex 
#define Mod3MapIndex 

122 July 26 1988 



Xlib - Resource Manager (continued) XDeleteModifiermapEntry 

#define Mod4MapIndex 6 
#define Mod5MapIndex 7 

Reled Commands 
InsertModifiermapEntry, XGetModifierMapping, XSetModifierMapping, 
XNewModifiermap, XFreeModifiermap, XKeycodeToKeysym, XKeysym- 
ToKeycode, XKeysymToString, XQueryKeymap, XStringToKeysym, XLookup- 
Keysym, XRebindKeySynAXGetKeyboardMapping, XRefreshKeyboardMapping, 
XLookupString. 

July 26, 1988 123 



XDeleteProperty 

Xlib- Properties n 

Name 
XDeleteProperty m delete a window property. 

Synopsis 
XDeleteProperty (display, w, property) 
Display *display; 
Window w; 
Atom property; 

Arguments 
display 

w 
property 
Description 

Specifies a pointer D the Display sUmcture; returned from XOpen- 
Display. 
Specifies the ID of the window whose property you want to delete. 
Specifies the atom of the property to be deleted. 

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 that knows the ID of the window the property is defined on. 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. 

E rro rs 
BadAtom 
BadWindow 

Related Commands 
XSetStandardProperties, XGetFontProperty, XRotateWindowProperties, 
XChangeProperty, XGetWindowProperty, XListProperties, XGetAtomName, 
XInternAtom. 

124 July 26, 1988 



mXlib - Association Tables 

XDestroyAssocTable 

Name 
XDestroyAssocTable -- free the memory allocated for an association table. 

Synopsis 
XDestroyAssocTable(table) 
XAssocTable *table; 

Arguments 
table 

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/XIO.h> and link with the library -loldX. 

Using an XAssocTable after it has been destroyed will have unpredictable and probably 
disastrous consequences. 

For more information on association tables, see Volume One, Chapter 13, Other Programming 
Techniques. 

Structures 
typedef struct { 
XAssoc *buckets; 
int size; 
}XAssocTable; 

/* pointer to first bucket in array */ 
/* table size (number of buckets) */ 

Related Commands 
XCreateAssocTable, XDeleteAssoc, XLookUpAssoc, XMakeAssoc. 

July 26, 1988 125 



mXlib- Regions 

XDestroyRegion 

Name 
XDestroyRegion -- deallocate storage associated with a region. 

Synopsis 
XDestroyRegion(r) 
Region r; 

Arguments 

Specifies the region to be destroyed. 

Description 
XDest royRegion frees the memory associated with a region. 
See Volume One, Chapter 6, Drawing Graphics and Text, for a description of regions. 

Related Commands 
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion, 
XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPoint- 
InRegion, X0ffsetRegion, XIntersectRegion, XEmptyRegion, XCreate- 
Region, XEqualRegion, XClipBox. 

July 26, 1988 127 



XDestroySubwindows 

Xlib - Window Existence m 

Name 
XDestroySubwindows -- destroy all subwindows of a window. 
Synopsis 
XDestroySubwindows ( display, w) 
Display *display; 
Window w; 

Arguments 
display 

w 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the ID of the window whose subwindows are to be destroyed. 

This function destroys all descendants of the specified window, in bottom to top stacking 
order. 
XDestroySubwindows generates exposure events on window w, if any mapped subwin- 
dows 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. 
XCloseDisplay automatically destroys all windows that have been created by that client on 
the specified display (unless called after a fork system call). 

E rro rs 
BadWindow 

Related Commands 
XCreateSimpleWindow, XCreateWindow, XDestroyWindow. 

128 July 26, 1988 



--Xlib - Window Existence 

XDestroyWindow 

Name 
XDestroyWindow -- unmap and destroy a window and all subwindows. 
Synopsis 
XDestroyWindow ( display, window) 
Display *display; 
Window window; 

Arguments 
di spl ay 

window 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 

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 are then destroyed, and a DestroyNotify event is generated for each win- 
dow. The ordering of the DestroyNotify events is such that for any given window, 
DestroyNotify is generated on all inferiors of the window before being generated on the 
w,.'ndow 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- 
Window 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. 

July 26 1988 129 



XDisableAccessControl 

Xlib - Host Access m 

Name 
XDisableAccessControl m allow access from any host. 
Synopsis 
XDisableAccessControl (display) 
Display *display; 

Arguments 
display 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 

Description 
XDisableAccessControl instructs the server to allow access from clients on any host. 
This overrides 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, XListHosts, XRemoveHost, XRemoveHosts, XEnable- 
AccessControl, XSetAccessControl. 

130 July 26, 1988 



--Xlib- Error Handling 

XDisplayName 

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 OpenDisplay. This is necessary because X error handling begins only after the 
connection to the server succeeds. If a NULL string is specified, XDisplayNarae looks in 
the environment for the display and returns the display name that the user was requesting. 
Otherwise, XDisplayNarae returns its own argument. This makes it easier to report to the 
user precisely which display the program attempted to open. 
For more information, see Volume One, Chapter 3, Basic Window Program. 

Related Commands 
XGetErrorDatabaseText, XGetErrorText, XSetErrorHandler, XSetIOError- 
Handler, XSynchronize, XSetAfterFunction. 

July 26, 1988 131 



Xlib- Drawing Primitives (continued) XDraw 

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. 
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 algo- 
rithmo 
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_offset, and dash_list. 
A Status of 0 is returned on failure. 
For more information, see Volume One, Appendix B, XIO Compatibility. 

Structures 
typedef struct Vertex { 
-- 
short x,y; 
unsigned short flags; 
} Vertex; 

/* defined constants for use as flags */ 
#define VertexRelative 0x0001 
#define VertexDontDraw 0x0002 
#define VertexCurved 0x0004 
#define VertexStartClosed 0x0008 
#define VertexEndClosed 0x0010 

/* else absolute */ 
/* else draw */ 
/* else straight */ 
/* else not */ 
/* else not */ 

Related Commands 
XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, 
XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopy- 
Area, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, 
XFillRectangles, XClearArea, XClearWindow. 

July 26, 1988 133 



XDrawArc 

Xlib - Drawing Primitives D 

Name 
XDrawArc -- draw an arc fitting inside a rectangle. 

Synopsis 
XDrawArc (display, drawable, gc, x, y, 
anglel , angle2) 
Display *display; 
Drawable drawable ; 
GC gc ; 
int x, y; 
unsigned int width, height ; 
int anglel , angle2; 

width, height, 

Arguments 
display 

dra wabl e 
gc 
x 
y 
wi dth 
height 
anglel 

angle2 

Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the drawable. 
Specifies the graphics context. 
Specify the x and y coordinates of the upper-left corner of the rectangle that 
contains the arc, relative to the origin of the specified drawable. 
Specify the width and height in pixels of the major and minor axes of the 
arC. 
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). 
Specifies the path and extent of the arc relative to the start of the arc. 
Angles are specified in 64ths of a degree, (360 * 64 is a complete circle). 

XI)rawArc 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 corner of the rectangle. The center of the circle or ellipse is the center of the rectan- 
gle, 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 counter- 
clockwise 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 0, a horizontal or vertical line can be drawn. 
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 0 and angle2 

134 July 26, 1988 



Xlib - Drawing Primitives (continued) XDrawArc 

is (45x64), a point drawn from the center of the bounding box through the endpoint of the arc 
will not pass through the comer of the rectangle. 

XD rawArc uses these graphics context components: funct ion, plane_ma s k, 
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, and dash_list. XDraw- 
Arc is not affected by the tile or stipple in the GC. 

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

(x,y) 

9 o'clock 
Angle = 180x64 
Angle = -(180x64) 

width 
12 o'clock 
. Center of 
Angle = 90x64 
Bou,,u,,,y 
Angle = - (270x64) 
 Rectangle 
'"<-... i 
............... ;'-'-':' - .................. t Angle= 
 // 

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 

Example 2: 
Arc from B1 to B2, Clockwise 
A1 = 270 x 64 
A2 = -(45 x 64) 

Errors 
BadDrawable 
BadGC 
BadMatch 

Xlib Reference Manual 135 



XDrawArc (continued) Xlib- Drawing Primitives 

Related Commands 
XDraw, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, 
XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopy- 
Area, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, 
XFillRectangles, XClearArea, XClearWindow. 

136 July 26, 1988 



nXlib- Drawing Primitives 

XDrawArcs 

Name 
XDrawArcs -- draw multiple arcs. 

Synopsis 
XDrawArcs (display, drawable, 
Display *display; 
Drawable drawable ; 
GC gc ; 
XArc *arcs; 
int narcs ; 

gc, arcs, narcs) 

Arguments 
di spl ay 

dra wabl e 
gc 
arcs 
narcs 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the drawable. 
Specifies the graphics context. 
Specifies a pointer to an array of arcs. 
Specifies the number of arcs in the array. 

(x,y) 

9 o'clock 
Angle = 180x64 
Angle = -(180x64) 

width 
12 o'clock 
A , -- Center of 
ngJ.e = 904x64 / Bounding 
Angle = - ( 0 ) . / Rectangle 
.....- , Angle 
. 

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 

Example 2: 
Arc from 81 to 82, Clockwise 
A1 = 270 x 64 
A2 = -(45 x 64) 

Xlib Reference Manual 137 



Xlib- Drawing Primitives (continued) XDrawArcs 

[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) 
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*PT], and where atan returns a value in the range [-PT/2, PT/2], and 
where adgust is: 
0 for normal-angle in the range [0,PI/2] 
PI for normal-angle in the range [PI/2, (3"PI)/2] 
2*PI for normal-angle in the range [(3*PI)/2,2*PI] 
For more information, see Volume One, Chapter 6, Drawing Graphics and Text. 

Structures 
typedef struct { 
short x, y; 
unsigned short width, height; 
short anglel, angle2; 
} XArc; 

/* Degrees * 64 */ 

Errors 
BadDZawable 
BadGC 
BadMatch 

Related Commands 
XDraw, XDrawArc, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDraw- 
Points, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea, 
XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFill- 
Rectangles, XClearArea, XClearWindow. 

July 26, 1988 139 



XDrawFilled 

Xlib- Drawing Primitives-- 

Name 
XDrawFilled m draw a filled polygon or curve from vertex list (from X10). 

Synopsis 
Status XDrawFilled ( display, 
Display *display; 
Drawable drawable ; 
GC gc ; 
Vertex *vlist ; 
int vcount ; 

drawable, gc, vlist, 

vcount ) 

Arguments 
display 

dra wabl e 
gc 
vlist 
vcount 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the drawable. 
Specifies the graphics context. 
Specifies a pointer to the list of vertices. 
Specifies how many vertices are in vlist. 

This function is provided for compatibility with X Version 10. To use it you must include the 
file <X11/X10.h> and link with the library -loldX. XDrawFilled achieves the effects of the 
X Version I0 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 func- 
tion also uses these graphics context mode-dependent components: foreground, back- 
ground, tile, stipple, ts x origin, ts_y_origin, dash_offset, dash_ 
list, fill_style and fill_rule. 
XDrawFilled returns a Status of 0 on failure. 
For more information, see Volume One, Appendix B, XIO Compatibility. 

Related Commands 
XDraw, XDrawArc, XDrawArcs, XDrawLine, XDrawLines, XDrawPoint, XDraw- 
Points, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea, 
XCopyPlane, XFilIArc, XFilIArcs, XFillPolygon, XFillRectangle, XFill- 
Rectangles, XClearArea, XClearWindow. 

140 July 26, 1988 



XDrawlmageString (continued) Xlib - Text 

Errors 
BadDrawable 
BadGC 
BadMatch 

Related Commands 
XQueryTextExtents, XQueryTextExtentsl6, XDrawImageStringl6, XDraw- 
String, XDrawStringl6, XDrawText, XDrawTextl6, XTextExtents, XText- 
Extentsl6, XTextWidth, XTextWidthl6. 

142 July 26 1988 



--Xlib - Text 

XDrawlmageStringl 6 

Name 
XDrawlmageStringl6 m draw 16-bit image text characters. 

Synopsis 
XDrawImageStringl6(display, 
Display *display; 
Drawable drawable; 
GC gc; 
int x, y; 
XChar2b *string; 
int length; 

drawable, gc, x, y, string, length) 

Arguments 
display 

dra wabl e 
gc 
x 
Y 
string 
length 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the drawable. 
Specifies the graphics context. 
Specify the x and y coordinates of the baseline starting position for the 
image text character, relative to the origin of the specified drawable. 
Specifies the character s'ing. 
Specifies the number of characters in the string argument. 

XDrawImageStzingl6 draws a suSng, but unle XDrawStringl 6 it can draw both the 
foreground and the background of the characters, if the GC is set accordingly. 

XDrawImageStringl6 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 fill_style defined in gc are ignored; 
the effective function is GXcopy and the effective fill_style is FillSolid. 
XDra'wImageStringl6 first fills a destination rectangle with the background pixel 
defined hn gc, and then pJn the text with the foreground pixel. The upper-left corner of 
the filled recqngle is at Ix, y - font_ascent], the width is overall->width and 
the height is ascent + descent. 
The overall->width, ascent, and descent are as would be returned by XQuery- 
TextExtentsl6 using gc and string. 
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter 
5, The Graphics Context. 

July 26, 1988 143 



XDrawlmageStri ng 16 (continued) Xlib - Text 

Structures 
typedef struct { 
unsigned char bytel; 
unsigned char byte2; 
} XChar2b; 

Errors 
BadDrawable 
BadGC 
BadMatch 

Related Commands 
XQueryTextExtents, XQueryTextExtentsl6, XDrawImageString, XDraw- 
String, XDrawStringl6, XDrawText, XDrawTextl6, XTextExtents, XText- 
Extentsl6, XTextWidth, XTextWidthl6. 

144 July 26, 1988 



mXlib - Drawing Primitives 

XDrawLine 

Name 
XDrawLine -- draw a line between two points. 
Synopsis 
XDrawLine(display, drawable, gc, xl, yl, x2, y2) 
Display *display; 
Drawable drawable ; 
GC gc ; 
int xl, yl, x2, y2; 

Arguments 
di spl ay 

dra wabl e 

gc 
yl 
x2 
y2 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the drawable. 
Specifies the graphics context. 
Specify the coordinates of the endpoints of the line relative to the drawable 
origin. XLine connects point (xl, yl) to point (x2, y2). 

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 
context mode-dependent components: foreground, background, tile, stipple, 
ts x origin, ts_y_origin, dash_offset, and dash_list. 
XDrawLine is not affected by tile or stipple in the GC. 

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

Errors 
BadDrawable 
BadGC 
BadMatch 

Related Commands 
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLines, XDrawPoint, XDraw- 
Points, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea, 
XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFill- 
Rectangles, XClearArea, XClearWindow. 

July 26, 1988 145 



Xlib- Drawing Primitives (continued) XDrawLines 

XDrawLines is not affected by the tile or stipple in the GC. 
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 
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawPoint, XDraw- 
Points, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea, 
XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFill- 
Rectangles, XClearArea, XClearWindow. 

July 26, 1988 147 



XDrawPoint 

Xlib - Drawing Primitives m 

Name 
XDrawPoint  draw a point. 
Synopsis 
XDrawPoint (display, drawable, go, x, y) 
Display *display; 
Drawable drawable ; 
GC gc ; 
int x, y; 

Arguments 
di spl ay 

dra wabl e 
gc 
x 
Y 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the drawable. 
Specifies the graphics context. 
Specify the x and y coordinates of the point, relative to the corner of the 
drawable. 

XDrawPoint uses the foreground pixel and function components of the graphics con- 
text to draw a single point into the specified drawable. XDrawPoint uses these graphics 
context components: function, plane_mask, foreground, subwindow_mode, 
clip x origin, clip_y_origin, and clip_mask. Use XDrawPoints tO draw mul- 
tiple 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 
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDraw- 
Points, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea, 
XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFill- 
Rectangles, XClearArea, XClearWindow. 

148 July 26, 1988 



XDrawPoints (continued) Xlib - Drawing Primitives 

Related Commands 
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDraw- 
Points, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea, 
XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFill- 
Rectangles, XClearArea, XClearWindow. 

150 July 26, 1988 



XDrawRectangle (continued) Xlib- Drawing Primitives 

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

Structure 
typedef struct { 
short x, y; 
unsigned short width, height; 
} XRectangle; 

Errors 
BadDrawable 
BadGC 
BadMatch 

Related Commands 
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDraw- 
Point, XDrawPoints, XDrawRectangles, XDrawSegments, XCopyArea, XCopy- 
Plane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFill- 
Rectangles, XClearArea, XClearWindow. 

152 Xlib Reference Manual 



nXlib - Drawing Primitives 

XDrawRectangles 

Name 
XDrawRectangles -- draw the outlines of multiple rectangles. 

Synopsis 
XDrawRectangles (display, drawable, 
Display *display; 
Drawable drawable ; 
GC gc ; 
XRectangle rectangles[] ; 
int nrectangles ; 

Arguments 
display 

dra wabl e 
gc 
rectangles 

gc, rectangles, nrectangles) 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the drawable. 
Specifies the graphics context. 
Specifies a pointer to an array of rectangles containing position and size 
information. 

nrectangles Specifies the number of rectangles ;n the array. 

XrawRecta:zle(dls._a, drawat  ., =-- . .... .  , , 
[]llllllllllllllll [ 
|11111111111111111111 IllllltllltIl|lll|ll I 
1111111111111111111[| Itlllltllltlltllltll I 
IIIllllllllllll 12 itlltltlillIl|lilllll.- 
|llllllllllllllll I1 p,xels lz p,xels 
i1111111111111111[[[| 1 1 
i111111111111111111[1 
|llllllllllllllllll|..I 
111111111111111111111  
|ltlttltiil|ll|[ll, l,[] 
 20 p=xels   20 p,xels  

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. This function uses 
these graphics context components: function, plane_mask, line_width, 
line_style, cap_style, join_style, fill_style, s ubwindow_mode, 
clip x origin, clip_y_origin, and clip_mask. XDrawRectangles also uses 
these graphics context mode-dependent components: foreground, background, tile, 
stipple, ts x origin, ts_y_origin, dash_offset, and dash_list. 
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. 
XDrawRectangles is not affected by tile or stipple in the GC. 

Xlib Reference Manual 153 



XDrawRectangles (continued) Xlib- Drawing Primitives 

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; 
unsigned short width, height; 
} XRectangle; 

Errors 
BadDrawable 
BadGC 
BadMatch 

Related Commands 
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDraw- 
Point, XDrawPoints, XDrawRectangle, XDrawSegments, XCopyArea, XCopy- 
Plane, XFilIArc, XFilIArcs, XFillPolygon, XFillRectangle, XFill- 
Rectangles, XClearArea, XClearWindow. 

154 Xlib Reference Manual 



DXlib- Drawing Primitives 

XDrawSegments 

Name 
XDrawSegrnents -- draw multiple disjoint lines. 

Synopsis 
XDrawSegments(display, 
Display *display; 
Drawable drawable; 
GC gc; 
XSegment *segments; 
int nsegments; 

drawable, 

gc, segments, nsegments) 

Arguments 
display 

dra wabl e 
gc 
s egmen t s 
nsegments 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the drawable. 
Specifies the graphics context. 
Specifies a pointer to an array of line segments. 
Specifies the number of segments in the array. 

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 
separately, without regard to the join_style. 

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__6rigin, dash_offset, and dash_list. 
XDrawSegments is not affected by the tile or stipple in the GC. 
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; 

July 26, 1988 155 



XDrawSegments (continued) Xlib- Drawing Primitives 

Errors 
BadDrawable 
BadGC 
BadMatch 

Related Commands 
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDraw- 
Point, XDrawPoints, XDrawRectangle, XDrawRectangles, XCopyArea, XCopy- 
Plane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFill- 
Rectangles, XClearArea, XClearWindow. 

156 July 26, 1988 



mXlib - Text 

XDrawString 

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 
di spl ay 

dra wahl e 
gc 
x 
Y 
string 
length 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the drawable. 
Specifies the graphics context. 
Specify the x and y coordinates of the baseline starting position for the char- 
acter, relative to the origin of the specified drawable. 
Specifies the character string. 
Specifies the number of characters in the string argument. 

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 for 
measuring the ibearing, rbearing, and width from. 
XDrawString uses these graphics context component: 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-dcpendent 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 

July 26, 1988 157 



XDrawString (continued) Xlib - Text 

Related Commands 
XQueryTextExtents, XQueryTextExtentsl6, XDrawImageString, XDraw- 
ImageStringl6, XDrawStringl6, XDrawText, XDrawTextl6, XTextExtents, 
XTextExtentsl6, XTextWidth, XTextWidthl6. 

158 July 26, 1988 



mXlib - Text, 

XDrawString16 

Name 
XDrawStringl6- draw two-byte text strings. 
Synopsis 
XDrawStringl6 (display, drawable, 
Display *display; 
Drawable drawable ; 
GC gc ; 
int x, y; 
XChar2b *string; 
int length; 

gc, x, y, string, length) 

Arguments 
display 

drawable 
gc 
x 
Y 
string 
length 
Description 

Specifies a pointer to the Display s[ructure; re[urned from XOpen- 
Display. 
Specifies the drawable. 
Specifies the graphics context. 
Specify the x and y coordinates of the baseline starting position for the char- 
acter, relative to the origin of the specified drawable. 
Specifies the character string. Characters are two bytes wide. 
Specifies the number of characters in the str'ng argument. 

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 for 
measuring the lbearing, rbearing, and width from. For more information on text 
placement, see Volume One, Chapter 6, Drawing Graphics and Text. 
XDrawStringl6 uses these graphics context components: function, plane_mask, 
fil_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; 

July 26, 1988 159 



XDrawStringl 6 (continued) Xlib - Text 

Errors 
BadDrawable 
BadFont 
BadGC 
BadMatch 

Related Commands 
XQueryTextExtents, XQueryTextExtentsl6, XDrawImageString, XDraw- 
ImageStringl6, XDrawString, XDrawText, XDrawTextl6, XTextExtents, 
XTextExtentsl6, XTextWidth, XTextWidthl6. 

160 July 26, 1988 



XDrawText (continued) Xlib - Text 

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

Structures 
typedef struct { 
char *chars; 
int nchars; 
int delta; 
Font font; 
} XTextItem; 

/* pointer to string */ 
/* number of characters */ 
/* delta between strings */ 
/* font to print it in, None don't change */ 

Errors 
BadDrawable 
BadFont 
BadGC 
BadMatch 

Related Commands 
XQueryTextExtents, XQueryTextExtentsl6, XDrawImageString, XDraw- 
ImageStringl6, XDrawString, XDrawStringl6, XDrawTextl6, XTextExtents, 
XTextExtentsl6, XTextWidth, XTextWidthl6. 

162 July 26, 1988 



mXlib - Text 

XDrawText16 

Name 
XDrawTextl6 -- draw 16-bit polytext strings. 
Synopsis 
XDrawTextl6 (display, drawable, gc, x, y, items, 
Display *display; 
Drawable drawable ; 
GC gc ; 
int x, y; 
XText Iteml 6 *items; 
int nitems; 

ni t ems ) 

Arguments 
di spl ay 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 

dra wabl e Specifies the drawable. 

gc 

Specifies the graphics context. 

x 
Y 
items 
nitems 
Description 

Specify the x and y coordinates of the baseline starting position for the initial 
string, relative to the origin of the specified drawable. 
Specifies a pointer to an array of text items using two-byte characters. 
Specifies the number of text items in the array. 

XDrawTextl6 is capable of drawing multiple strings and changing fonts between strings. 
Each XTextItem structure contains a sla'ing, the number of characters in the string, the 
delta offset from the starting position for the string, and the font. Each text item is pro- 
cessed in turn. The font in each XText Item is stored in the specified GC and used for sub- 
sequent text. If the XText Iteml 6. 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 XTextTtem 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- 
ing 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). 

XDrawTextl6 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 nlso uses these graphics context mode-dependent com- 
ponents: foreground, tile, stipple, ts x origin, and ts_y_origin. 

July 26, 1988 163 



XDrawTextl 6 (continued) Xlib - Text 

Note that the chars member of the XTextIteml6 structure is of type XChar2b, rather 
than of type char as it is in the XTextItem structure. For fonts defined with linear index- 
ing 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. 

Structures 
typedef struct { 
XChar2b *chars; 
int nchars; 
int delta; 
Font font; 
} XTextIteml6; 

/* 2 byte characters */ 
/* number of characters */ 
/* delta between strings */ 
/* font to print it in, None don't change */ 

typedef struct { 
unsigned char bytel; 
unsigned char byte2; 
} XChar2b; 

/* normal 16 bit characters are two bytes */ 

Errors 
BadDrawable 
BadFont 
BadGC 
BadMatch 

Related Commands 
XQueryTextExtents, XQueryTextExtentsl6, XDrawImageString, XDraw- 
ImageStringl6, XDrawString, XDrawStringl6, XDrawText, XTextExtents, 
XTextExtentsl6, XTextWidth, XTextWidthl6. 

164 July 26, 1988 



mXlib- Regions 

XEmptyRegion 

Name 
XEmptyRegion -- determine if a region is empty. 

Synopsis 
int XEmptyRegion(r) 
Region r; 

Arguments 
r Specifies the region to be checked. 
Description 
XEmptyRegion will return True if the specified region is empty. 
Structures 
/* 
* opaque reference to Region data type. 
* user won't need contents, only pointer. 
*/ 
typedef struct _XRegion *Region; 
Related Commands 
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion, 
XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPoint- 
InRegion, XOffsetRegion, XIntersectRegion, XCreateRegion, XDestroy- 
Region, XEqualRegion, XClipBox. 

July 26, 1988 165 



XEnableAccessControl 

Xlib - Host Access m 

Name 
XEnableAccessControl--useaccesscontrollist  glow ordenyconnectionrequests. 
Synopsis 
XEnableAccessControl(display) 
Display *display; 

Arguments 
display 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 

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. 

Related Commands 
XAddHost, XAddHosts, XListHosts, XRemoveHost, XRemoveHosts, XDisable- 
AccessControl, XSetAccessControl. 

166 July 26, 1988 



mXlib- Regions 

XEqualRegion 

Name 
XEqualRegion -- determine if two regions have the same size, offset, and shape. 
Synopsis 
int XEqualRegion (rl, r2) 
Region rl , r2 ; 

Arguments 
r] 
r2 

Specify the two regions you want to compare. 

Description 
XEqualRegion returns True if the o regions are identical; i.e., they have the same offset, 
size and shape. 

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 
/. 
* opaque reference to Regiondata type. 
* user won't need contents, only pointer. 
*/ 
typedef struct _XRegion *Region; 

Related Commands 
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion, 
XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPoint- 
InRegion, XOffsetRegion, XIntersectRegion, XEmptyRegion, XCreate- 
Region, XDestroyRegion, XClipBox. 

July 26, 1988 167 



XEventsQueued 

Xlib - Resource Manager m 

Name 
XEventsQueued m check the number of events in the event queue. 

Synopsis 
int XEventsQueued(display, 
Display *display; 
int mode; 

mode ) 

Arguments 
display 

Specifies a pointer to the Display structure, returned from XOpen- 
Display. 

mode 

Specifies whether the output buffer is flushed if there are no events in Xlib's 
queue. You can specify one of these constants: QueuedAlready, 
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 0 (it does not flush the output 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 output buffer, attempts to read more events out of the 
application's connection, and returns the number read. 

If mode is QueuedAfterReading, and there are no events in the queue, 
XEventsQueued attcmpts to read more events out of the application's connection 
without flushing the output buffer and rctums 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 
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheck- 
WindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, 
XCheckMaskEvent, XNextEvent, XAllowEvents, XGetMotionEvents, 
XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, 
XSynchronize, XSendEvent, QLength, XPending. 

168 July 26, 1988 



--Xlib - Cut Buffers 

XFetchBuffer 

Name 
XFetchBuffer -- return data from a cut buffer. 

Synopsis 
char *XFetchBuffer(display, 
Display *display; 
int *nbytes; 
int buffer; 

nbytes, buffer) 
/* RETURN */ 

Arguments 
display 

nbytes 

buffer 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Returns the number of bytes in buffer returned by XFetchBuffer. If 
there is no data in the buffer, nbytes is set to 0. 
Specifies which buffer you want data from. Specify an integer from 0 to 7. 

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 nbyte3, 
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. 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 the preferred communication scheme. 
For more information on cut buffers, see Volume One, Chapter 13, Other Programming Tech- 
niques. 

Errors 
BadValue 

Related Commands 
XSt'oreBuffer, XStoeBytes, XFetchBytes, XRotateBuffers. 

July 26, 1988 169 



XFetchBytes 

Xlib - Cut Buffers D 

Name 
XFetchBytes -- return data from cut buffer 0. 
Synopsis 
char *XFetchBytes (display, nbytes) 
Display *display; 
int *nbytes; /* RETURN */ 

Arguments 
display 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 

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 0 of the 8 buffers provided for interclient com- 
munication. 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 allocated 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 XFetchBuffer tO fetch data from any specified cut buffer. 

Selections are the preferred communication method. 

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

Related Commands 
XStoreBuffer, XStoreBytes, XFetchBuffer, XRotateBuffers. 

170 July 26, 1988 



XFillArc 

Xlib- Drawing Primitives-- 

Name 
XFillArc -- fill an arc. 

Synopsis 
XFillArc (display, drawable, gc, 
anglel , angle2) 
Display *display; 
Drawable drawable ; 
GC gc ; 
int x, y; 
unsigned int width, height ; 
int anglel , angle2; 

x, y, width, height, 

Arguments 
display 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 

dra wabl e Specifies the drawable. 

gc 
x 

Specifies the graphics context. 
Specify the x and y coordinates of the upper-left corner of the bounding box 
containing the arc, relative to the origin of the drawable. 

width 
height 

Specify the width and height in pixels. These are the major and minor axes 
of the arc. 

anglel 

Specifies the start of the arc relative to the three-o'clock position from the 
center. Angles are specified in degrees, multiplied by 64. 

angle2 Specifies the path and extent of the arc relative to the start of the arc. Angles 
are specified in degrees, multiplied by 64. 
Description 
XFillArc fills an arc according to the arc mode in the GC. 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 compute the arc. Some, but not all, of the pixels drawn 
with XDrawArc will be drawn by XFilIArc with the same arguments. 
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. 

XFilIArc uses these graphics context components: function, plane_mask, 
fill_style, arc_mode, subwindow_mode, clip x origin, clip_y_origin, 
and clip_mask. This function also uses these graphics context mode-dependent com- 
ponents: foreground, background, tile, stipple, ts x origin, and ts_y_ 
origin. 

172 July 26, 1988 



Xlib- Drawing Primitives (continued) XFillArc 

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

Errors 
BadDrawable 
BadGC 
BadMatch 

Related Commands 
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDraw- 
Point, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, 
XCopyArea, XCopyPlane, XFillArcs, XFillPolygon, XFillRectangle, XFill- 
Rectangles, XClearArea, XClearWindow. 

July 26, 1988 173 



XFillArcs 

Xlib - Drawing Primitives-- 

Name 
XFillArcs B fill multiple arcs. 

Synopsis 
XFilIArcs (display, drawable, go, 
Display *display; 
Drawable drawable; 
GC gc; 
XArc *arcs; 
int narcs; 

arcs, narcs) 

Arguments 
display 

Specifies a pointer to the Display structure; returned from XOpenDisplay. 

drawable 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 regions intersect, pixels will be 
drawn multiple times. 

XFillArcs use these graphics context components: function, plane, mask, 
fill_style, arc_mode, subwindow_mode, clip x origin, clip_y_origin, 
and clip_mask. This function slso uses these graphics context mode-dependent com- 
ponents: 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; 
unsigned short width, height; 
short anglel, anglel; 
} XArc; 

/* Degrees * 64 */ 

174 July 26, 1988 



Xlib - Drawing Primitives (continued) XFillArcs 

Errors 
BadDrawable 
BadGC 
BadMatch 

Related Commands 
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDraw- 
Point, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, 
XCopyArea, XCopyPlane, XFillArc, XFillPolygon, XFillRectangle, XFill- 
Rectangles, XClearArea, XClearWindow. 

July 26, 1988 

175 



XFillRectangle 

Xlib- Drawing Primitives-- 

Name 
XFillRectangle m fill a rectangular area. 

Synopsis 
XFillRectangle(display, drawable, 
Display *display; 
Drawable drawable; 
GC gc; 
int x, y; 
unsigned int width, height; 

gc, x, y, 

width, height) 

Arguments 
di splay 
dra wabl e 
gc / 
X 
Y 
wi dt h 
height 

Specifies a pointer to the Display structure; 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 origin of the drawable. 
Specify the dimensions in pixels of the rectangle to be filled. 

"(i, rawRectangle (display, drawable, gc, 0, - 19, iII; 
12 pixels 
 20 p,xels  

XFzllRectangle(dzsplay, drawable, gc, , 0, 19, II); 
12 pixels 
 20 pixels  

Description 
XFillRectangle fills the rectangular area in the specified drawable using the x and y 
coordinates, 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 us 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. 

178 Xlib Reference Manual 



Xlib- Drawing Primitives (continued) XFillRectangle 

Errors 
BadDrawable 
BadGC 
BadMatch 

Related Commands 
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDraw- 
Point, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, 
XCopyArea, XCopyPlane, XFilIArc, XFilIArcs, XFillPolygon, XFill- 
Rectangles, XClearArea, XClearWindow. 

July 26, 1988 179 



XFillRectangles 

Xlib- Drawing Primitives-- 

Name 
XFillRectangles -- fill multiple rectangular areas. 

Synopsis 
XFillRectangles(display, drawable, 
Display *display; 
Drawable drawable; 
GC gc; 
XRectangle *rectangles; 
int nrectangles; 

gc, rectangles, nrectangles) 

Arguments 
display 

drawable 
gc 
rectangles 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the drawable. 
Specifies the graphics context. 
Specifies a pointer to an array of rectangles. 

nrectangles Specifies the number of rectangles in the array. 

rawRerangle(dzsplay, drawable, gc, , " 
1:1 I1 III I I.I ] ! ! 1.1 ! ! [ [ !12 pixels 
[,,J 1 [ [ I I I I I 11 I I I 1 II ] II 
i]lllllllllllllllll|l 
 20 p,xels  

111; 

XFillRectangle(display, drawable, gc, 0, , t9, II); 
|[|lllIlltlltllltlll 
t[llltI[[ttlllll|ttl 
1111111111111111111112 pixels 
tlt|ltllltlltllltltl $ 
tllttllilltlllilI|ll 
Ilttttltlttt|lllttll 
Ilttltlllttlillltlll 
1[111111111111111111 
 20 p,xels  

Description 
XFillRectangles fills multiple rectangular areas in the specified drawable using the 
graphics 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. 

XFillRectangles usesthese graphics contextcomponents: function, plane_mask, 
fill_style, subwindow_mode, clip x origin, clip_y_origin, and clip_ 
mask. This nction so usesthesegraphicscontextcomponen depending on the fill 
-- 
style: foreground, background, tile, stipple, ts x origin, and ts_y_ 
origin. 

180 Xlib Reference Manual 



XFindContext 

Xlib - Context Manager-- 

Name 
XFindContext -- get data from the context manager (not graphics context). 

Synopsis 
int XFindContext(display, 
Display *display; 
Window w; 
XContext context; 
caddr t *data; 
-- 

w, context, data) 
/* RETURN */ 

Arguments 
display 

w 
context 
data 
Description 

Specifies a pointer to the Display sl/ucture; returned from XOpen- 
Display. 
Specifies the window with which the data is associated. 
Specifies the context type to which the data corresponds. 
Returns the data. 

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. 

182 July 26, 1988 



--Xlib - Output Buffer 

XFlush 

Name 
XFlush -- flush the output buffer (display all queued requests). 

Synopsis 
XFlush(display) 
Display *display; 

Arguments 
display 

Specifies a pointer D the Display sucture; retumed om XOpen- 
Display. 

Description 
XFlush sends to the display ("flushes") all output 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, XNextEvent, or XWindowEvent), or when a call is made that gets 
information from the server (such as XQueryPointer, XGetFontInfo) so XFlush is 
seldom 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 Win- 
dow Program. 

Related Commands 
XSync 

July 26, 1988 

183 



--Xlib- HouseKeeping 

Name 
XFree -- free specified in-memory data created 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 data allocated by Xlib calls. 
Related Commands 
XOpenDisplay, XCloseDisplay, XNoOp, DefaultScreen. 

XFree 

July 26, 1988 

185 



XFreeColormap 

Xlib - Colormaps m 

Name 
XFreeColormap -- delete a colormap and install the default colormap. 

Synopsis 
XFreeColormap(display, cmap) 
Display *display; 
Colormap cmap; 

Arguments 
display 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 

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 crnap 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 
XCha ngeWindowAt t r ibut e s), it changes the colormap associated with the window 
to the constant None, generates a ColormapNotify event, and frees the colormap. 
The colors displayed with a colormap of None are server-dependent, since the default 
colormap is normally used. 

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

Errors 
BadColor 

Related Commands 
XCopyColormapAndFree, XCreateColormap, XGetStandardColormap, 
XInstallColormap, XUninstallColormap, XSetStandardColormap, XList- 
InstalledColormaps, XSetWindowColormap, DefaultColormap, Display- 
Cells. 

186 July 26, 1988 



--Xlib - Color Cells 

XFreeColors 

Name 
XFreeColors--free colormapcellsorplanes. 
Synopsis 
XFreeColors (display, cmap, pixels, npixels, planes) 
Display *display; 
Colormap cmap; 
unsigned long pixels[]; 
int npixels; 
unsigned long planes; 

Arguments 
display 

cmap 
pixels 

npixels 
planes 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the colormap. 
Specifies an array of pixel values. These pixel values map to the cells in the 
specified colormap. 
Specifies the number of pixels. 
Specifies the planes you want to free. 

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 muse, unless they were allocated with 
XAllocColorPlanes, in which case all the related pixcls 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 allo- 
cated those shared cells. 
For more information, see Volume One, Chapter 7, Color. 

Errors" 
BadAccess 

A colorcell allocated by client (either unallocated or allocated by another 
client). 
BadColor 
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 
XAllocColorCells, XAllocColorPlanes, XAllocColor, XAllocNamedColor, 
XLookupColor, XParseColor, XQueryColor, XQueryColors, XStoreColor, 
XStoreColors, XStoreNamedColor, BlackPixel, WhitePixel. 

July 26, 1988 187 



XFreeCursor 

Xlib - Cursors m 

Name 
XFreeCursor -- destroy a cursor. 
Synopsis 
XFreeCursor (display, cursor) 
Display *display; 
Cursor cursor; 

Arguments 
display 

cursor 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the ID of the cursor to be affected. 

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 be changed to None (which implies CopyFromParent). The 
specified cursor ID should not be referred to again. 

Errors 
BadCursor 

Related Commands 
XDefineCursor, XUndefineCursor, XCreateFontCursor, XCreateGlyph- 
Cursor, XCreatePixmapCursor, XRecolorCursor, XQueryBestCursor, 
XQueryBestSize. 

188 July 26, 1988 



mXlib- Extensions 

XFreeExtensionList 

Name 
XFreeExtensionList m free memory allocated for a list of installed extensions to X. 

Synopsis 
XFreeExtensionList(list) 
char **list; 

Arguments 
list 

Specifies a pointer to e list of extensions retued om XList- 
Extensions. 

Description 
XFreeExtensionList frees e memory allocated by XListExtensions. 
For more information, see Volume One, Chapter 13, Other Programming Techniques. 
Related Commands 
XListExtensions, XQueryExtension. 

July 26, 1988 189 



XFreeFont 

Xlib- Fonts-- 

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 pointer to the Display structure; returned from XOpen- 
Display. 
fon_struct Specifies the storage associated with the font. 
Description 
XFreeFont frees the memory located for e font struct font information sucture 
(XFontStruct) filled by XQueryFont or XLoadQueryFont. XFreeFont frees aH 
storage associated with the fon_struct argument. Neither the data nor the font should be 
referenced again. 
The font itself is unloaded 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; /* 
-- 
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 */ 

Errors 
BadFont 

Related Commands 
XLoadFont, XLoadQueryFont, XFreeFontinfo, XListFonts, XListFontsWith- 
Info, XFreeFontNames, XFreeFontPath, XGetFontPath, XQueryFont, XSet- 
Font, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor. 

190 July 26, 1988 



XFreeFontNames 

Xlib - Fonts m 

Name 
XFreeFontNames -- free the font name array. 

Synopsis 
XFreeFontNames (list) 
char *list[]; 

Arguments 
list 

Specifies the array of font name strings to be freed. 

Description 
XFreeFontNames frees e aay of strings returned by XListFonts. 

Related Commands 
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts, 
XListFontsWithInfo, XFreeFontPath, XGetFontPath, XQueryFont, XSet- 
Font, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor. 

192 July 26, 1988 



nXlib - Fonts 

XFreeFontPath 

Name 
XFreeFontPath -- free the memory allocated by XGetFontPath. 

Synopsis 
XFreeFontPath(list) 
char **list; 
Arguments 
list Specifiesanarrayofsngsallocadby XGetFontPath. 

Description 
XFreeFontPath frees the dam used by the aay of panames returned by XGetFont- 
Path. 

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

Reled Commands 
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts, 
XListFontsWithInfo, XFreeFontNames, XGetFontPath, XQueryFont, XSet- 
Font, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor. 

July 26, 1988 

193 



--Xlib- Keyboard 

XFreeModifiermap 

Name 
XFreeModifiermap -- destroy and free a keyboard modifier mapping structure. 

Synopsis 
XF reeModi f ie rmap ( modmap ) 
XModi fierKeymap *modmap; 

Arguments 
modmap 

Specifies a pointer to the XModifierKeymap sucture to be freed. 

Description 
XFreeModifiermap frees the specified XModifierKeymap structure. 
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 *modifiermap; /* an 8 by max_keypermod array of 
* keycodes to be used as modifiers */ 

} XModifierKeymap; 

Related Commands 
XDeleteModifiermapEntry, XInsertModifiermapEntry, XKeycodeToKeysym, 
XKeysymToKeycode, XKeysymToString, XNewModifierMap, XQueryKeymap, 
XStringToKeysym, XLookupKeysym, XRebindKeySym, XGetKeyboardMapping, 
XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookupString, 
XSetModifierMapping, XGetModifierMapping. 

July 26, 1988 195 



XFreePixmap 

Xlib - Pixmaps and Tiles-- 

Name 
XFreePixmap m free a pixmap ID. 
Synopsis 
XFreePixmap ( display, pixmap) 
Display *display; 
Pixmap pixmap ; 

Arguments 
di spl ay 

pixmap 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the pixmap whose ID should be freed. 

XFreePixmap disassociates a pixmap ID from its resource. If no other client has an ID for 
that resource, it is freed. The P ixmap should never be referenced again by this client. If it 
is, the ID will be unknown and a BadPixmap error will result. 

Errors 
BadPixmap 

Reined Commands 
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindow- 
BackgroundPixmap, XCreatePixmap, XCreatePixmapFromBitmapData, 
XQueryBestSize, XQueryBestStipple, XWriteBitmapFile, XReadBitmap- 
File, XCreateBitmapFromData. 

196 July 26, 1988 



mXlib - Graphics Context 

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. Using the gc argu- 
ment, gc->gid does the same thing, except that applications shouldn't reference members of 
the gc structure directly. 

Related Commands 
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XSetStipple, XSetTSOrigin, 
XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillRule, XSet- 
FillStyle, XSetForeground, XSetBackground, XSetFunction, XSet- 
GraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSet- 
ClipRectangles, XSetState, XSetSubwindowMode, DefaultGC. 

July 26, 1988 19 7 



Xlib - Standard Geometry (continued) XGeometry 

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 (bwidth), size of the width and height increments (typ- 
ically fwidth and fheight), and any additional interior space (xadder and yadder) are 
passed in to make it easy to compute the resulting size. 

Related Commands 
XParseGeomet ry, XT rans lateCoo rdinates. 

July 26, 1988 199 



XGetDefault 

Xlib- User Preferences-- 

Name 
XGetDefault -- scan the user preferences for program name and options. 

Synopsis 
char *XGetDefault (display, program, option) 
Display *display; 
char *program; 
char *option; 

Arguments 
display 

program 

opt i on 

Description 

Specifies a pointer to the Display structure; returned from XOpenDisplay. 
Specifies the program name to be looked for in the user's resource database. 
The program name is usually a rgv [ 0 ], the first argument on the UNIX com- 
mand line. 
Specifies the option name or keyword. Lines containing both the program 
name and the option name will be matched. 

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 XrraGet- 
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: #c0c0ff 
xterm, geometry : =81x28 
xterm, saveLines : 256 
xterm, font : 8x13 
xterm, keyMapFil e : /usr/black/. keymap 
xterm, act iveI con : on 
xmh. header, font 9xl 5 
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. In some programs the standard is to capitalize only the 
second and successive words in each option, if any. In others, the first word is also capital- 
ized. 
Defaults 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 system, this file is $HOMEI.Xdefaults. After loading these defaults, XGetDefault 
merges additional defaults specified by the XENVIRONMENT environment variable. If XEN- 
VIRONMENT is defined, it contains a full path name for the additional resource file. If XEN- 
VIRONMENT is not defined, XGetDefault looks for $HOMEIgfdefaults-name, where 
name specifies the name of the machine on which the application is running. 

202 July 26, 1988 



Xlib- User Preferences (continued) XGetDefault 

The first invocation of XGetDefault reads the defaults into memory so that subsequent 
requests are fast. Therefore, changes to the defaults files from the program will not be felt 
until the next invocation. 

For more information, see Volume One, Chapter 11, Managing User Preferences. 

Related Commands 
XAutoRepeatOff, XAutoRepeatOn, XBell, XGetKeyboardControl, XChange- 
KeyboardControl, XGetPointerControl. 

July 26, 1988 203 



XGetErrorText 

Xlib- Error Handling-- 

Name 
XGetErrorText -- obtain a description of error code. 

Synopsis 
XGetErrorText(display, 
Display *display; 
int code; 
char *buffer; 
int length; 

code, buffer, length) 

/* RETURN */ 

Arguments 
di splay 

code 
buffer 
length 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the error code for which you want to obtain a description. 
Returns a pointer to the error description text. 
Specifies the size of the buffer. 

XGetErrorText obtains textual descriptions of errors. XGetErrorText returns a pointer 
to a null-terminated string describing the specified error code with length 2ength. 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, which can be accessed easily. 

For more information, see Volume One, Chapter 3, Basic Window Program. 

Related Commands 
XDisplayName, XGetErrorDatabaseText, XSetErrorHandler, XSetIOError- 
Handler, XSynchronize, XSetAfterFunction. 

206 July 26, 1988 



mXlib- Fonts 

XGetFontPath 

Name 
XGetFontPath -- get the current font search path. 
Synopsis 
char **XGetFontPath ( display, 
Display *display; 
int *npaths; 
Arguments 
display 

npaths ) 
/* RETURN number of elements */ 
Specifies a pointer to the Display sucture; returned from XOpen- 
Display. 
Returns the number of strings in the font path army. 

npaths 
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 
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts, 
XListFontsWithInfo, XFreeFontNames, XFreeFontPath, XQueryFont, XSet- 
Font, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor. 

July 26, 1988 20 7 



XGetFontProperty 

Xlib- Properties m 

Name 
XGetFontProperty -- get a font property given its atom. 

Synopsis 
Bool XGetFontProperty (font_struct, atom, value) 
XFontStruct *font struct ; 
-- 
Atom atom; 
unsigned long *value; /* RETURN */ 

Arguments 
font struct Specifies the storage associated with the font. 
-- 
atom Specifies the atom associated with the property name you want returned. 

value 

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 0 if the atom was not defined, or 1 if was defined. 
There are a set of predefined atoms for font properties which can be found in <Xll/Xatom.h>. 
These atoms are listed and described in Volume One, Chapter 6, Drawing Graptu'cs and Text. 
This set contains the standard properties associated with a font. The predefined font properties 
are likely but not guaranteed to be present on any given server. 

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 
XSetStandardProperties, XRotateWindowProperties, XDeleteProperty, 
XChangeP rope rt y, XGetWindowP rope rt y, XListP rope rt ie s, XGetAt omName, 
XInte rnAt om. 

208 July 26, 1988 



mXlib - Window Attributes 

XGetGeometry 

Name 
XGetGeometry m obtain the current geometry of drawable. 
Synopsis 
Status XGetGeometry (display, drawable, root, 
width, height, border_width, depth) 
Display *display; 
Drawable drawable ; 
Window *root ; 
int *x, *y; 
unsigned int *width, *height; 
unsigned int *border width; 
-- 
unsigned int *depth ; 

X, 

/* RETURN */ 
/* RETURN */ 
/* RETURN */ 
/* RETURN */ 
/* RETURN */ 

Y, 

Arguments 
display 
drawable 
root 
X 
Y 
width 
height 

Specifies a pointer to the Display sucte; returned from XOpenDisplay. 
Specifies the drawable, either a window or a pixmap. 
Returns the root window ID of the specified window. 
Return the coordinates of the upper-left pixel of the window's border, relative 
to its parent's origin. For pixmaps, these coordinates are always 0. 
Return the dimensions of the drawable. For a window, these return the inside 
size (not including the border). For a pixmap, they just return the size. 

border width 
-- 
Returns the borderwidth, in pixels, of the window's border, if the drawable is a 
window. Returns 0 if the drawable is a pixmap. 

depth 

Returns the depth of the pixmap (bits per pixel for the object). The depth must 
be supported by the root of the specified drawable. 

Description 
This. function gets complete information about the root window and the current geometry of a 
drawable. 
XGetGeometry returns a Status of 0 on failure, or 1 on success. 

Errors 
BadDrawable 

Related Commands 
XGetWindowAttributes, XMoveWindow, XMoveResizeWindow, XResizeWindow, 
XConfigureWindow. 

Xlib Reference Manual 209 



XGetlconName 

Xlib - Window Manager Hints B 

Name 
XGetIconName -- get the name to be displayed in an icon. 
Synopsis 
Status XGetIconName (display, w, icon__name) 
Display *display; 
Window w; 
char **icon name; /* RETURN */ 

Arguments 
di splay 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 

W 
icon name 
-- 

Specifies the ID of the window whose icon name you want to learn. 
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, XGetIconName sets this argument to NULL. When finished 
with it, a client must free the icon name sxing using XFree. 

Description 
XGetIconName reads the icon name property of a window. This function is primarily used 
by window managers to get the name to be written in that window's icon when they need to 
display that icon. 

XGetIconName returns a nonzero Status if it succeeds, and 0 if no icon name has been 
set for the argument window. 

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

Errors 
BadWindow 

Related Commands 
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGet- 
WMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, 
XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetch- 
Name, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSet- 
Command. 

210 July 26, 1988 



mXlib - Window Manager Hints. 

XGetlconSizes 

Name 
XGetlconSizes -- get preferred icon sizes. 

Synopsis 
Status XGetIconSizes(display, w, size_list, count) 
Display *display; 
Window w; 
XIconSize **size_list; /* RETURN */ 
int *count; /* RETURN */ 

Arguments 
display 
w 
size list 
-- 
count 
Description 

Specifies a pointer to the Display structure; returned from XOpenDisplay. 
Specifies the window ID (usually of the root window). 
Returns a pointer to the size list. 
Returns the number of items in the size list. 

XGetIconSizes reads the XA_WM_ICON_SIZE property that should be set by the window 
manager to specify its desired icon sizes. XGetIconSizes returns a Status of 0 if a win- 
dew 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 managcr. 
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, lnterclient Communication. 

Structures 
typedef struct { 
int min_width, min_height; 
int max_width, max_height; 
int width_inc, height_inc; 
} MIconSize; 

/* 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 

Related Commands 
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGet- 
WMHints, XSetWMHints, XGetZoornHints, XSetZoornHints, XGetNormalHints, 
XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetch- 
Name, XGetIconName, XStoreName, XSetIconSizes, XSetCommand. 

July 26, 1988 211 



Xlib -Images (continued) XGetlmage 

If the drawable is a window, the window must be mapped, 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 will occur. The returned image 
will include any visible portions of inferiors or overlapping windows contained in the rectan- 
gle. 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. 
For XYFormat format data, the bit order member of XImage specifies the bit order in 
-- 
which your server expects the data. 
For more information, see Volume One, Chapter 6, Drawing Graphics and Text. 

Errors 
BadDrawable 
BadMatch 
BadValue 

See Description above. 

Related Commands 
XDestroyImage, XPutImage, XCreateImage, XSubImage, XGetSubImage, XAdd- 
Pixel, XPutPixel, XGetPixel, ImageByteOrder. 

July 26, 1988 

213 



XGetlnputFocus 

Xlib - Input Handling-- 

Name 
XGednpuocus--retum thecurrentkeybod cus window. 
Synopsis 
XGetInputFocus (display, focus, revert_to) 
Display *display; 
Window *focus; /* RETURN */ 
int *revert to; /* RETURN */ 
-- 

Arguments 
di spl ay 

focus 

revert to 
-- 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Returns the ID of the focus window, or one of the constants PointerRoot 
or None. 

Returns the window to which the focus would revert if the focus window 
became invisible. This is one of these constants: RevertToParent, 
RevertToPointerRoot, or RevertToNone. Must not be a window 
ID. 

Description 
XGetInputFocus returns the current focus window and the window to which the focus 
would revert if the focus window became invisible. 

XGet InputFocus does not report the last focus change time. This is available only from 
events. 

Related Commands 
XSelectInput, XSetInputFocus, XWindowEvent, XCheckWindowEvent, 
XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMask- 
Event, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, 
XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, 
XPending, XSynchronize, XSendEvent, QLength. 

214 July 26, 1988 



Xlib - Keyboard (continued) XG etKeyboard Ma p p i n g 

Related Commands 
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, 
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifier- 
Map, XQueryKeymap, XStringToKeysynXLookupKeysyXRebindKeySym, 
XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookupString, 
XSetModifierMapping, XGetModifierMapping. 

July26, 1988 217 



XGetModifierMapping 

X Programming Library m 

Name 
XGetModifierMapping -- obtain a mapping of modifier keys (Shift, Control, etc.). 
Synopsis 
XModifierKeymap *XGetModifierMapping (display) 
Display *display; 

Arguments 
display 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 

Description 
XGetModifierMapping returns the keycodes of the keys being used as modifiers. 

There are eight modifiers, represented by the symbols ShiftMapIndex, LockMapIndex, 
ControlMapIndex, ModlMapIndex, Mod2MapIndex, Mod3MapIndex, Mod4Map- 
Index, and Mod5MapIndex. The modifiermap member of the XModifierKeymap 
structure contains eight sets of keycodes, each set containing max_keypermod keycodes. 
Zero keycodes are not meaningful. If an entire raodifierraap is filled with O's, the 
corresponding 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 *modifiermap; /* an 8 by max_keypermod array of 
* keycodes to be used as modifiers */ 

} XModifierKeymap; 

/* modifier names. Used to build a SetModifierMapping request or 
to read a GetModifierMapping request. These correspond to the 
masks defined above. */ 

#define ShiftMapIndex 0 
#define LockMapIndex 1 
#define ControlMapIndex 2 
#define ModlMapIndex 3 
#define Mod2MapIndex 4 
#define Mod3MapIndex 5 
#define Mod4MapIndex 6 
#define Mod5MapIndex 7 

Related Commands 
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, 
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifier- 
Map, XQueryKeymap, XStringToKeysym, XLookupKeysym, XRebindKeySym, 
XGetKeyboardMapping, XChangeKeyboardMapping, XRefreshKeyboard- 
Mapping, XLookupString, XSetModifierMapping. 

218 July 26, 1988 



XGetMotionEvents (continued) Xlib -Input Handling 

Related Commands 
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheck- 
WindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, 
XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XIfEvent, 
XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending, 
XSynchronize, XSendEvent, QLength. 

220 July 26, 1988 



XGetNormalHints (continued) Xlib - Window Manager Hints 

#define PResizeInc (IL << 6)/* program specified resize increments */ 
#define PAspect (IL << 7)/* program specified min/max aspect ratios */ 
#define PAllHints (PPositionlPSizelPMinSizelPMaxSizelPResizeInclPAspect) 

Errors 
BadWindow 

Related Commands 
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGet- 
WMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XSetNormalHints, 
XGetTransientForHint, XSetTransientForHint, XFetchName, XGetIcon- 
Name, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSet- 
Command. 

222 July 26, 1988 



XGetPixel (continued) Xlib -Images 

Related Commands 
XDestroyImage, XPutImage, XGetImage, XCreateImage, XSubImage, XGetSub- 
Image, XAddPixel, XPutPixel, ImageByteOrder. 

224 July 26, 1988 



--Xlib- Pointer 

XGetPointerControl 

Name 
XGetPointerControl -- get the current pointer preferences. 
Synopsis 
XGetPointerControl ( display, accel_numerator, 
threshold) 
Display *display; 
int *accel_numerator, *accel denominator; 
-- 
int *threshold; 

accel denominator, 
-- 

/* RETURN */ 
/* RETURN */ 

Arguments 
di spl ay 

Specifies a point to the Display structure; retumed om XOpen- 
Display. 

accel numerator 
-- 
Returns the numerar r the acceleration multiplier. 

accel denominator 
-- 
Remmsthedenominator rtheacceleration 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/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 
XQueryPointer, XWarpPointer, XGrabPointer, XChangeActivePointerGrab, 
XUngrabPointer, XGetPointerMapping, XSetPointerMapping, XChange- 
PointerControl. 

July 26, 1988 225 



XGetPointerMapping 

Xlib- Pointer 

Name 
XGetPointerMapping -- get the pointer button mapping. 

Synopsis 
int XGetPointerMapping(display, map, nmap) 
Display *display; 
unsigned char map[] ; /* RETURN */ 
int nmap; 

Arguments 
display 
map 
nmap 

Specifies a pointer to the Display structure; returned from XOpenDisplay. 
Returns the mapping list. Array begins with map [ ]. 
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 
XQueryPointer, XWarpPointer, XGrabPointer, XChangeActivePointerGrab, 
XUngrabPointer, XSetPointerMapping, XGetPointerControl, XChange- 
PointerControl. 

226 July 26, 1988 



XGetSelectionOwner 

Xlib - Selections m 

Name 
XGetSelectionOwnermretumtheownerofaselection. 
Synopsis 
Window XGetSelectionOwner(display, selection) 
Display *display; 
Atom selection; 

Arguments 
display 

selection 
Descriion 

Specifies a pointer  the Display structu; remrned from XOpen- 
Display. 

Specifies the selection atom whose owner you want returned. 

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 10, lnterclient Communication. 

Errors 
BadAtom 

Related Commands 
XSetSelectionOwner, XConvertSelection. 

228 July 26, 1988 



XGetSizeHints (continued) Xlib - Window Manager Hints 

#define USSize (IL << I) /* user specified width, height */ 

#define PPosition (IL << 2) /* program specified 
#define PSize (IL << 3) /* program specified 
#define PMinSize (IL << 4) /* program specified 
#define PMaxSize (IL << 5) /* program specified 
#define PResizeInc (IL << 6) /* program specified 
#define PAspect (IL << 7) /* program specified 

position */ 
size */ 
minimum size */ 
maximum size */ 
resize increments */ 
min/max aspect ratios *! 

#define PAllHints (PPositionlPSizelPMinSizelPMaxSizelPResizeInclPAspect) 

E rro rs 
BadAtom 
BadWindow 

Related Commands 
XGetClassHint, XSetClassHint, XSetSizeHints, XGetWMHints, XSet- 
WMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, XSetNormal- 
Hints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGet- 
IconName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, 
XSetCommand. 

230 July 26, 1988 



Xlib - Colormaps 

XGetStandardColormap 

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 
display 

cmap_info 
property 

Specifics a pointer to the Display structure; returned from XOpen- 
Display. 

Specifies the ID of the window on which the property is set. This is nor- 
mally the root window. 

Returns the filled colormap information structure. 

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_B LUE_MAP, 
XA_RGB_DEFAULT_MAP, and XA_RGB_GRAY_MAP. 

Description 
XGetStandardColormap gets a property on a window (normally the root window) that 
describes a standard colormap. 

This call does not load 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. The application can then 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 xInstallColormap, in coopera- 
tion with the window manager. Any of these steps could fail, and the application should be 
prepped. 

If the server 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, 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 
XStandardColormap 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: 

July26, 1988 231 



XGetStandardColormap (continued) Xlib - Colormaps 

pixel = base_pixel 
+ ( (unsigned long) 
+ ( (unsigned long) 
+ ( (unsigned long) 

(0.5 + r * red_max)) * red_mult 
(0.5 + g * green_max)) * green_mult 
(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. 

See Volume One, Chapter 7, Color, for a complete description of standard colormaps. 

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; 
} XStandardColormap; 

Errors 
BadAtom 
BadWindow 

Related Commands 
XCopyColormapAndFree, XCreateColormap, XFreeColormap, XInstall- 
Colormap, XUninstallColormap, XSetStandardColormap, XListInstalled- 
Colormaps, XSetWindowColormap, DefaultColormap, DisplayCells. 

232 July 26, 1988 



XGetSublmage (continued) Xlib - Images 

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. 

XSubImage extracts a subimage from an image, instead of from a drawable like XGetSub- 
Image. 

For more information on images, see Volume One, Chapter 6, Drawing Graptu'cs and Text. 

Errors 
BadDrawable 
BadGC 
BadMatch 

BadValue 

Depth of dest_image is not the same as depth of drawable. See so 
Description. 

Related Commands 
XDestroyImage, XPutImage, XGetImage, XCreateImage, XSubImage, XAdd- 
Pixel, XPutPixel, XGetPixel, ImageByteOrder. 

234 July 26, 1988 



--Xlib - Window Manager Hints 

XGetTransientForHint 

Name 
XGetTransientForHint -- get the XA_WM_TRANS IENT_FOR property of a window. 

Synopsis 
Status XGetTransientForHint (display, w, prop_window) 
Display *display; 
Window w; 
Window *prop_window; /* RETURN */ 

Arguments 
display Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
w Specifies the ID of the window to be queried. 
prop_window Returns the XA_WM_TRANS IENT_FOR property of the specified window. 

Description 
XGetTransientForHint obfins 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 
menus and dialog boxes. 

XGetTransientForHint returns a Status of 0 on failure, and nonzero on success. 

For more information on using hints, see Volume One, Chapter 10, lnterclient Communica- 
tion. 

Errors 
BadWindow 

Related Commands 
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGet- 
WMHnts, XSetWMHins, XGetZoomHints, XSetZoomHints, XGetNormalHints, 
XSetNormalHints, XSetTransientForHint, XFetchName, XGetIconName, 
XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSetCommand. 

July 26, 1988 235 



Xlib - Visuals (continued) XGetVisuallnfo 

#define VisualDepthMask 
#define VisualClassMask 
#define VisualRedMaskMask 
#define VisualGreenMaskMask 
#define VisualBlueMaskMask 
#define VisualColormapSizeMask 
#define VisualBitsPerRGBMask 
#define VisualAllMask 

0x4 
0x8 
0xl0 
0x20 
0x40 
0x80 
0xl00 
0xlFF 

Related Commands 
XMatchVisualInfo, DefaultVisual. 

July 26, 1988 

237 



XGetWi ndowAttri butes (continued) Xlib - Window Attributes 

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; 

/* 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, XSetWindowBackground, XSetWindow- 
BackgroundPixmap, XSetWindowBorder, XSetWindowBorderPixmap, XGet- 
Geometry. 

240 July 26, 1988 



Xlib - Properties (continued) XGetWi ndowProperty 

Errors 
BadAtom 
BadMatch 
BadVa lue 
BadWindow 

Value of long_offset caused L to be negative above. 

Related Commands 
XSetStandardProperties, XGetFontProperty, XRotateWindowProperties, 
XDeleteProperty, XChangeProperty, XListProperties, XGetAtomName, 
XInternAtom. 

July 26, 1988 

243 



--Xlib - Window Manager Hints , 

XGetZoomHints 

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 
display 

Specifies a poinr to the Display sucture; returned from XOpenDisplay. 
Specifies the ID of the window to be queried. 
Returns a pointer to the zoom hints. 

zhints 
Description 
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 0 if the 
application did not specify zoom size hints for this window. 
For more information on using hints, see Volume One, Chapter 10, lnterclient Communica- 
tion. 

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 */ 
nt y; /* denominator */ 
} min_aspect, max_aspect; 
} XSizeHints; 

/* flags argument in size hints */ 
#define USPosition (IL << 0) /* user specified x, y */ 
#define USSize (IL << I) /* user specified width, height */ 

#define PPosition (IL << 2) 
#define PSize (IL << 3) 
#define PMinSize (IL << 4) 
#define PMaxSize (IL << 5) 
#define PResizeInc (IL << 6) 
#define PAspect (IL << 7) 
#define PAllHints (PPosition 

/* program specified position */ 
/* program specified size */ 
/* program specified minimum size */ 
/* program specified maximum size */ 
/* program specified resize increments */ 
/* program specified min/max aspect ratios 
IPSizelPMinSizelPMaxSizelPResizeInclPAspect) 

July 26, 1988 

245 



XGetZoomHints (continued) Xlib - Window Manager Hints 

Errors 
BadWindow 

Related Commands 
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGet- 
WMHints, XSetWMHints, XSetZoomHints, XGetNormalHints, XSetNormal- 
Hints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGet- 
IconName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, 
XSetCommand. 

246 July 26, 1988 



BXlib - Grabbing 

/ XGrabButton 

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 pointer_mode, keyboard_mode ; 
Window confine to; 
Cursor cursor; 

Arguments 
di spl ay 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
button Specifies the mouse button. Mmy be Buttonl, Button2, Button3, But- 
ton4, Button5, 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, Mod3Mask, Mod4Mask, Mod5Mask, or AnyModifier. 
AnyModifier is equivalent to issng the grab key request for all possible 
modifier combinations (including no modifiers). 
gra_window Specifies the ID of the window you want to grab. 
owner events 
-- Specifies a boolean value of either True or False. See Description below. 
event mask Specifies the event mask. This mask is the bitwise OR of one or more of the 
-- 
event masks listed on the reference page for xSelect Input. 
pointer_mode 
Controls further processing of pointer events. Pass one of these constants: 
GrabModeSync or GrabModeAsync. 
keyboard_mode 
Controls further processing of keyboard events. 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. 

July 26, 1988 24 7 



XGrab Button (continued) Xlib - Grabbing 

cursor 

Specifies the cursor to be displayed during the grab. One possible value you 
can pass is the constant None. 

Description 
XGrabButton establishes a passive grab, such that an active grab may take place when the 
specified key/button combination is pressed. After this call, if 

1) 

3) 

the specified button is pressed when the specified modifier keys are down (and no other 
buttons or modifier keys are down), 

grab_window contains the pointer, 

4) 

the confine_to window (if any) is viewable, and 

these constraints are not satisfied for any ancestor, 

then the pointer is actively grabbed as described in GrabPointer, the 
last_pointer_grab time is set to the time at which the button was pressed, and the 
But t onP re s s 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 AnyModifier 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). 
The request fails if some other client has already issued a GrabButton with the same 
button/key combination on the same window. When using AnyModifier or AnyButton, 
the request fails completely (no grabs are established) if there is a conflicting grab for any 
combination. The request has no effect on an active grab. 
The owner_events argument specifies whether the grab window should receive all events 
(True) or whether the grabbing application should receive all events normally (False). 
The pointer_mode and keyboard_mode control the processing of events during the 
grab. If either is GrabModeSync, events for that device are not queued for applications until 
XAllowEvents is called to release the events. If either is GrabModeAsync, events for 
that device are processed normally. 
An automatic grab takes place between a ButtonPress and a ButtonRelease, SO this 
call is not necessary in some of the most common situations. 

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

248 July 26, 1988 



XGrabKey 

Xlib - Grabbing 

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 pointer to the Display structure; returned from X0pen- 
Display. 
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, Mod5Mask, or AnyModifier. 
AnyModifier is equivalent to issuing the grab key request for all possible 
modifier combinations (including no modifiers). A specified modifiers do 
not need to have currently assigned keycodes. 
9tab_window Specifies the window from which you want to receive input from the 
grabbed key combination. 
owner events 
Specifies whether the grab window should receive all events (True) or 
whether the grabbing application should receive all events normally 
(False). 
pointer_mode 
Controls further processing of pointer events. Pass one of these constants: 
GrabModeSync or GrabModeAsync. 
keyboard_mode 
Controls further processing of keyboard events. 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 is grabbed, and all keyboard events are sent 
to this application. More formally: 

250 Ju26, 1988 



XGrabPointer 

Xlib - Grabbing 

Name 
XGrabPointer -- grab the pointer. 

Synopsis 
int XGrabPointer (display, grab_window, owner_events, 
event_mask, pointer_mode, keyboard_mode, confine_to, 
cursor, time) 
Display *display; 
Window grab_window; 
Bool owner events; 
unsigned int event mask; 
-- 
int pointer_mode, keyboard_mode ; 
Window confine to; 
-- 
Cursor cursor; 
Time time ; 

Arguments 
display Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
grab_window Specifies the ID of the window that should grab the pointer input indepen- 
dent of pointer location. 
owner events 
-- 
Specifies if the pointer events are to be reported normally within this applica- 
tion (pass True) or only to the grab window if selected by the event mask 
asS False). 
event_mask Specifies the event mask. See XSelectInput for a complete Hst of event 
masks. 
pointer_mode 
Controls funher processing of pointer events. Pass either GrabModeSync 
or GrabModeAsync. 
keyboard_mode 
Controls further processing of keyboard events. Pass either GrabMode- 
Sync 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 pat- 
tern. 
time Specifies the time when the grab request took place. Pass either a times- 
tamp, expressed in milliseconds (from an event), or the constant Current- 
Time. 

254 July 26, 1988 



XGrabPointer (continued) Xlib - Grabbing 

If the specified time is earlier than the last-pointer-grab time or later than the current X 
server time, GrabTnvalidTirrte is returned. (If the call succeeds, the last pointer 
grab time is set to the specified time, with the constant CurrentTirae replaced by the 
current X server time.) 

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

Errors 
BadCursor 
BadValue 
BadWindow 

Related Commands 
XGrabKey, XUngrabKey, XGrabKeyboard, XUngrabKeyboard, XGrabButton, 
XUngrabButton, XUngrabPointer, XChangeActivePointerGrab, XGrab- 
Server, XUngrabServer. 

256 July 26, 1988 



--Xlib - Grabbing 

XGrabServer 

Name 
XGrabServer -- grab the server. 
Synopsis 
XGrabServer (display) 
Display *display; 

Arguments 
display Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
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. 

Reled Commands 
XGrabKey, XUngrabKey, XGrabKeyboard, XUngrabKeyboard, XGrabButton, 
XUngrabButton, XGrabPointer, XUngrabPointer, XChangeActivePointer- 
Grab, XUngrabServer. 

July 26, 1988 257 



--Xlib - Resource Manager 

XlnsertModifiermapEntry 

Name 
XlnsertModifiermapEntry -- add a new envy to an XModifierKeymap structure. 

Synopsis 
XModifierKeymap *XInsertModifiermapEntry (modmap, 
keysym_entry, modifier) 
XModifierKeymap *modmap ; 
KeyCode keysym_entry; 
int modifier ; 

Arguments 
modmap Specifies a pointer to an XModifierKeymap sucture. 
keysym_en t ry 
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: ShiftMapIndex, 
LockMapIndex, ControlMapIndex, ModlMapIndex, Mod2Map- 
Index, Mod3MapIndex, Mod4MapIndex, or Mod5MapIndex. 

Description 
XInsertModifiermapEntry returns an XModifierKeymap structure suitable for cal- 
ling XSetModifierMapping, in which the specified keycode is deleted from the set of 
kcycodcs that is mapped to the specified modifier (like Shift or Control). XInsert- 
ModifiermapEntry does not change the mapping itself. 

This function is normally used by calling XGetModifierMapping to get a pointer to the 
current XModifierKeymap structure for use as the modmap argument to XInsert- 
ModifiermapEnt ry. 

Note that the structure pointed to by modmap is freed by XInsertModifiermapEntry. 
It should not be freed or otherwise used by applications. 

For a description of the modifier map, see XSetModifierMapping. 

Structures 
typedef struct { 
int max_keype rmod; 
KeyCode *modifiermap; 

} XModifierKeymap; 

/* server's max number of keys per modifier */ 
/* an 8 by max_keypermod array of 
* keycodes to be used as modifiers */ 

#define ShiftMapIndex 0 
#define LockMapIndex 1 
#define ControlMapIndex 2 
#define ModlMapIndex 3 
#define Mod2MapIndex 4 
#define Mod3MapIndex 5 

July 26, 1988 259 



XlnsertModifiermapEntry (continued) Xlib- Resource Manager 

#define Mod4MapIndex 6 
#define Mod5MapIndex 7 

Related Commands 
XDeleteModifiermapEntry, XGetModifierMapping, XSetModifierMapping, 
XNewModifierMap, XFreeModifiermap, XKeycodeToKeysym, XKeysym- 
ToKeycode, XKeysymToString, XQueryKeymap, XStringToKeysym, XLookup- 
Keysym, XRebindKeySym, XGetKeyboardMapping, XRefreshKeyboardMapping, 
XLookupString. 

260 July 26, 1988 



XlnstallColormap (continued) Xlib - Colormaps 

Related Commands 
XCopyColormapAndFree, XCreateColormap, XFreeColormap, XGetStandard- 
Colormap, XUninstallColormap, XSetStandardColormap, XListInstalled- 
Colormaps, XSetWindowColormap, DefaultColormap, DispIayCells. 

262 July 26, 1988 



--Xlib- Properties 

XlnternAtom 

Name 
XlnternAtom -- return an atom for a given name string. 
Synopsis 
Atom XInternAtom (display, property_name, 
Display *display; 
char *property_name ; 
Bool only_if_exists ; 

only_if_exists ) 

Arguments 
display Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
property_name 
Specifies the name associated with the property you want the atom for. 
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 that indicates whether XInternAtom should 
return None or should create the atom if no such property_name exists. 
Description 
X I nt e rnAt om returns the atom identifier corresponding to property_n ame. 
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 ASCII string. 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. 
This. function is the oppo.site of XGetAtoraName, which returns the atom name when given 
an atom ID. 
Predefined atoms are defined in <X11/Xatom.h> and begin with the prefix "XA_" 

Errors 
BadAlloc 
BadValue 

Related Commands 
XS et S t a nda rdP rope rt ie s, XGet Font P rope rt y, XRot at eWindowP rope rt ie s, 
XDe let eP rope rt y, XChangeP rope rt y, XGet Windo wP rope rt y, XLi s t - 
P ropert ies, XGetAtomName. 

Xlib Reference Manual 263 



XlntersectRegion 

Xlib - Regions 

Name 
XlntersectRegion -- compute the intersection of two regions. 
Synopsis 
XIntersectRegion(sra, srb, dr) 
Region sra , srb ; 
Region dr; /* RETURN */ 

Arguments 

dr 

Specify the two regions with which to perform the computation. 

Returns the result of the computation. 

Description 
XIntersectRegion generates a region that is the intersection of two regions. 

Structures 
/, 
* opaque reference to Regiondata type. 
* user won't need contents, only pointer. 
*/ 
typedef struct _XRegion *Region; 

Related Commands 
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion, 
XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPoint- 
InRegion, XOffsetRegion, XEmptyRegion, XCreateRegion, XDestroyRegion, 
XEqualRegion, XClipBox. 

264 July 26, 1988 



XKeysymToKeycode 

Xlib - Keyboard-- 

Name 
XKeysymToKeycode m convert a keysym to the appropriate keycode. 

Synopsis 
KeyCode XKeysymToKeycode (display, 
Display *display; 
Keysym keysym_kcode; 

keysym_kcode) 

Arguments 
display Specifies a pointer 0 the Display sucture; returned from XOpen- 
Display. 
keysym_kcode 
Specifies the keysym that is to be searched for. 

Description 
XKeysymToKeycode turns the keycode coesponding to the spified keysym symbol in 
the current mapping. If the spified keysym is not defined r any keycode, XKeysyra- 
ToKeycode turns0. 
Related Commands 
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, 
XKeycodeToKeysym, XKeysymToString, XNewModifierMap, XQueryKeymap, 
XStringToKeysym, XLookupKeysym, XRebindKeySym, XGetKeyboardMapping, 
XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookupString, 
XSetModifierMapping, XGetModifierMapping, IsKeypadKey, IsCursorKey, 
IsPFKey, IsFunctionKey, IsMiscFunctionKey, IsModifierKey. 

266 July 26, 1988 



mXlib - Keyboard 

XKeysymToString 

Name 
XKeysymToString -- convert a keysym symbol to a string. 

Synopsis 
char *XKeysymToString (keysym_str) 
KeySym keysym_str; 

Arguments 
keysym_str 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 F1 key is mapped to the 
string "STOP" using XRebindKeysym, XKeysymToString still returns "FI" 
XLookupString, however, would return "STOP". 

Related Commands 
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, 
XKeycodeToKeysym, XKeysymToKeycode, XNewModifierMap, XQueryKeymap, 
XStringToKeysym, XLookupKeysym, XRebindKeysym, XGetKeyboardMapping, 
XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookupString, 
XSetModifierMapping, XGetModifierMapping, IsKeypadKey, IsCursorKey, 
IsPFKey, IsFunctionKey, IsMiscFunctionKey, IsModifierKey. 

July 26, 1988 26 7 



--Xlib- Extensions 

XListExtensions 

Name 
XListExtensions -- return a list of all extensions to X supported by the server. 

Synopsis 
char **XListExtensions(display, nextensions) 
Display *display; 
int *nextensions; /* RETURN */ 

Arguments 
display Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
nextensions Returns the number of extensions in the returned list. 
Description 
XListExtensions lists all the X extensions supported by the current server. Upper or 
lower case is important. 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 western languages other than English. 
For more information on extensions, see Volume One, Chapter 13, Other Programming Tech- 
niques. 

Related Commands 
XQueryExtension, XFreeExtensionList. 

July 26, 1988 

269 



XListFonts 

Xlib- Fonts 

Name 
XListFonts -- return a list of the available font names. 
Synopsis 
char **XListFonts (display, pattern, maxnames, 
Display *display; 
char *pattern; 
int maxnames ; 
int *actual count; /* RETURN */ 
Arguments 
di spl ay 

pattern 

maxnames 

actual count) 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the string associated with the font names you want returned. You 
can specify any string, an asterisk (*), or a question mark. The asterisk indi- 
cates a wildcard for any number of characters and the question mark indi- 
cates a wildcard for a single character. 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. 
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 string is ter- 
minated by NULL. The maximum number of names returned in the list depends on the value 
you passed to maxnames. The function returns the actual number of font names in 
actual count. The client should call XFreeFontNames when done with this list to free 
the memory. 
The font search path (the order in which font names are compared to pattern) is set by 
XSetFontPath. 
For more information on fonts, see Volume One, Chapter 6, Drawing Graphics and Text. 

Related Commands 
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFontsWith- 
Info, XFreeFontNames, XFreeFontPath, XGetFontPath, XQueryFont, XSet- 
Font, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor. 

270 July 26, 1988 



--Xlib - Fonts 

X List Fonts With Info 

Name 
XListFontsWithlnfo -- obtain the names and information about loaded fonts. 

Synopsis 
char **XListFontsWithInfo(display, pattern, maxnames, 
count, info) 
Display *display; 
char *pattern; /* null-terminated */ 
int maxnames; 
int *count; /* RETURN */ 
XFontStruct **info; /* RETURN */ 

Arguments 
dlsplay 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
pattern Specifies the string associated with the font names you want returned. You 
can specify any string, an asterisk (*), or a question mark. The asterisk indi- 
cates a wildcard on any number of characters and the question mark indi- 
cates a wildcard on a single character. 
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 the font information. XListFontsWithInfo provides enough 
space for maxnames pointers. 
Description 
XListFontsWithInfo returns a list of font names that match the specified pattern and a 
list of their associated font information. The list of names is limited to a size specified by the 
maxnames argument. To free the allocated name array, the client should call XFreeFont- 
Names. To free the font information army, the client should call XFreeFontInfo. 
The information returned for each font is identical to what XQueryFont would return, except 
that the per-character mecs (ibearing, rbearing, width, ascent, descent for sin- 
gle characters) are not returned. 
XListFontsWithInfo returns NULL on faile. 
For more information on fonts, see Volume One, Chapter 6, Drawing Graphics and Text. 

Structures 
typedef struct { 
XExtData *ext data; /* hook for extension to hang data */ 
_ 
Font lid; /* 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 minbytel; /* first row that exists */ 
unsigned max_bytel; /* last row that exists */ 

Xlib Reference Manual 271 



XListFontsWithlnfo (continued) Xlib - Fonts 

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; 

/* 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 
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts, 
XFreeFontNames, XFreeFontPath, XGetFontPath, XQueryFont, XSetFont, 
XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor. 

272 Xlib Reference Manual 



XListlnstalledColormaps 

Xlib - Colormaps 

Name 
XListlnstalledColormaps -- get a list of installed colormaps. 
Synopsis 
Colorrnap *XListInstalledColorrnaps (display, 
display *display; 
Window w; 
int *num; /* RETURN */ 

w, n um) 

Arguments 
di spl ay 

hum 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the ID of the window for whose screen you want the list of 
currently installed colormaps. 
Returns the number of currently installed colormaps in the returned list. 

XListInstalledColormaps returns a list of the currently installed colormaps for the 
screen of the specified window. The order in the list is not significant. There is no distinction 
in the list between colormaps actually being used by windows and colormaps no longer in use 
which have not yet been freed or desloyed. The allocated list should be freed using XFree 
when it is no longer needed. XListInstalledColormaps returns None on failure and 
sets n um to O. 

For more information on installing colormaps, see Volume One, Chapter 7, Color. 

Errors 
BadWindow 

Related Commands 
XCopyColormapAndFree, XCreateColormap, XFreeColormap, XGetStandard- 
Colormap, XInstallColormap, XUninstallColormap, XSetStandard- 
Colormap, XSetWindowColormap, DefaultColormap, DisplayCells. 

274 Xlib Reference Manual 



mXlib- Properties 

XListProperties 

Name 
XListProperties -- get the property list for a window. 
Synopsis 
Atom *XListProperties (display, w, num__prop) 
Display *display; 
Window w; 
int *num__prop; /* RETURN */ 

Arguments 
di splay 

w 
n um__p rop 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the window whose property list you want. 
Returns the length of the properties array. 

XListProperties returns a pointer to an array of atom properties that are defined for the 
specified window. To free the memory allocated by this function, use XFree. XList- 
Properties returns NULL on failure and sets hum_prop to O. 
For more information, see Volume One, Chapter 10, lnterclient Communication. 

Errors 
BadWindow 

Related Commands 
XSetStandardProperties, XGetFontProperty, XRotateWindowProperties, 
XDeleteProperty, XChangeProperty, XGetWindowProperty, XGetAtomName, 
XInternAtom. 

Xlib Reference Manual 275 



XLoadFont k 

Xlib- Fonts-- 

Name 
XLoadFont -- load a font if not already loaded; get font ID. 
Synopsis 
Font XLoadFont ( display, name) 
Display *display; 
char *name; 

Arguments 
display 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
name Specifies the name of the font in a null terminated siring. 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, returns a 0 and generates a Bad- 
Name 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 XLoadFontWithInfo 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 
BadName 

name specifies an unavailable font. 

Related Commands 
XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts, XListFontsWith- 
Info, XFreeFontNames, XFreeFontPath, XGetFontPath, XQueryFont, XSet- 
Font, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor. 

276 Xlib Reference Manual 



XLoadQueryFont (continued) Xlib- Fonts 

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) */ 

Errors 
BadAlloc 

Related Commands 
XLoadFont, XFreeFont, XFreeFontInfo, XListFonts, XListFontsWithinfo, 
XFreeFontNames, XFreeFontPath, XGetFontPath, XQueryFont, XSetFont, 
XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor. 

278 Xhb Reference Manual 



mXlib - Association Tables 

XLookUpAssoc 

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 poinr to the Display structu; retumed from XOpen- 
Display. 

table 

Specifies the association table. 

x id 
-- 

Specifies the X resource ID. 

Description 
This function is provided for compatibility with X Version 10. To use it you must include the 
fil <X111X10.h> and link with the library -loldX. 

Association tables provide a way of storing data and accessing by ID. This information is 
available to all clients. XLookUpAssoc 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, Chapter 13, Other Programming 
Techniques. 

Structures 
typedef struct { 
XAssoc *buckets; 
int size; 
} XAssocTable; 

/* pointer to first bucket in bucket array */ 
/* table size (number of buckets) */ 

typeef struct XAssrc { 
-- 
struct XAs soc *next; 
-- 
struct XAs soc *prev; 
Display *display; 
XID x id; 
char *data; 
} XAssoc; 

/* next object in this bucket */ 
/* previous object in this bucket */ 
/* display which owns the ID */ 
/* X Window System ID */ 
/* pointer to untyped memory */ 

Related Commands 
XCreateAssocTable, XDeleteAssoc, XDestroyAssocTable, XMakeAssoc- 

July 26, 1988 279 



XLookupColor 

Xlib - Color Cells-- 

Name 
XLookupColor m get database RGB values and closest hardware-supported RGB values from 
color name. 

Synopsis 
Status XLookupColor (display, cmap, colorname, rgb_db_def, 
hardware def) 
Display *display; 
Colormap cmap; 
char *colorname; 
XColor *rgb_db_def, *hardware_def; /* RETURN */ 

Arguments 
display 

cmap 
colorname 

hardware def 
-- 
Description 

Specifies a pointer to the Display structure; returned from X0pen- 
Display. 

Specifies the colormap. 

Specifies the color name string (for example "red"). Upper or lower 
case does not matter. The string should be in ISO LATIN1 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. 

Returns the exact RGB values for the specified color name from the 
/usr/liblrgb database. 

Returns the closest RGB values possible on the hardware. 

XLookupColor looks up the string name of a color with respect to the screen associated 
with the specified cmap and returns both the exact color values and the closest values possible 
on that screen. 
XLookupColor returns 1 if colorname exists in the RGB database or 0 if it does not 
exist. 
To determine the exact RGB values, XLookupColor uses a database on the X server. On 
UNIX, this database is lusrlliblrgb. To read the colors provided by the database on a UNIX 
system, see/usrlliblrgb.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. 

280 Xlib Reference Manual 



Xlib - Color Cells (continued) XLookupColor 

Structures 
typedef struct { 
unsigned long pixel; 
unsigned short red, green, blue; 
char flags; 
char pad; 
} XColor; 

/* DoRed, DoGreen, DoBlue */ 

Related Commands 
XAllocColorCells, XAllocColorPlanes, XAllocColor, XAllocNamedColor, 
XParseColor, XQueryColor, XQueryColors, XStoreColor, XStoreColors, 
XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel. 

July 26, 1988 

281 



XLookupKeysym 

Xlib - Keyboard 

Name 
XLookupKeysym -- get the keysym corresponding to a keycode in structure. 
Synopsis 
KeySym XLookupKeysym ( event, index) 
XKeyEvent *event ; 
int index; 

Arguments 
e ven t 
index 

Specifies the KeyPress or KeyRelease event that is to be used. 
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- 
MapIndex, Mod3MapIndex, Mod4MapIndex, 8nd Mod5MapIndex csn 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 
interpret 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 
specified event structure. 
Note that some hardware can't support KeyRelease events for every key. You may wish to 
avoid using them in your code. 

Structures 
typedef struct { 
int type; 
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; 

/* of event */ 
/* display the event was read from */ 
/* "event" window it is reported relative to */ 
/* root window that the event occured on */ 
/* child window */ 
/* milliseconds */ 
/* pointer x, y coordinates in event window */ 
/* coordinates relative to root */ 
/* key or button mask */ 
/* detail */ 
/* same screen flag */ 

282 July 26, 1988 



Xlib- Keyboard (continued) XLookupKeysym 

Related Commands 
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, 
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifier- 
Map, XQueryKeymap, XStringToKeysyrXRebindKeysym, XGetKeyboard- 
Mapping, XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookup- 
String, XSetModifierMapping, XGetModifierMapping. 

July 26, 1988 

283 



XLookupString 

Xlib - Keyboard-- 

Name 
XLookupString -- map a key event to ASCII string, keysym, and ComposeStatus. 

Synopsis 
int XLookupString(event, buffer, num_bytes, keysym, 
XKeyEvent *event; 
char *buffer; /* RETURN */ 
int num_bytes; 
KeySym *keysym; /* RETURN */ 
XComposeStatus *status; /* not implemented */ 

status) 

Arguments 
e ven t 
buffer 
n um_byt es 

keysym 

status 

Description 

Specifies the key event to be used. 
Returns the resulting string. 
Specifies the length of the buffer. No more than num_bytes of translation 
are returned. 
If this argument is not NULL, it specifies the keysym ID computed from the 
event. 
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 Release 1 or 2. 

XLookupString gets an ASCII string and a keysym that are currently mapped to the key- 
code 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 the user's 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 Release 1 or 2. 

Structures 
/. 
* Compose sequence status structure, used in calling XLookupString. 
*/ 
typedef struct _XComposeStatus { 
char *compose_ptr; /* state table pointer */ 
int chars matched; /* match state */ 
-- 
} XComposeStatus; 

typedef struct { 
int type; 
Display *display; 
Window window; 

/* of event */ 
/* Display the event was read from */ 
/* "event" window it is reported relative to */ 

284 July 26, 1988 



Xlib - Keyboard (continued) X Looku pString 

Window root; 
Window subwindow; 
Time time; 
int x, y; 
int x_root, y_root; 
unsigned int state; 

/* root window that the event occured on */ 
/* child window */ 
/* milliseconds */ 
/* pointer x, y coordinates in event window */ 
/* coordinates relative to root */ 
/* key or button mask */ 

unsigned int keycode;/* detail */ 
Bool same screen; /* same screen flag */ 
-- 
} XKeyEvent; 

Related Commands 
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, 
XKeycodeToKeysyn%XKeysymToKeycode, XKeysymToString, XNewModifier- 
Map, XQueryKeymap, XStringToKeysyn%XLookupKeysym, XRebindKeySyn% 
XGetKeyboardMapping, XChangeKeyboardMapping, XRefreshKeyboard- 
Mapping, XSetModifierMapping, XGetModifierMapping. 

July 26, 1988 

285 



XLowerWindow 

Xlib - Window Manipulation 

Name 
XLowerWindow -- lower a window in the stacking order. 
Synopsis 
XLowerWindow (display, w) 
Display *display; 
Window w; 

Arguments 
display 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 

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 win- 
dow 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 some other client has selected SubstructureRedirectMask on the parent, 
then a ConfigureRequest event is generated, and no further processing 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 
EnterNotify events are sent to the window which was immediately below the lowered 
window at the pointer position. 

For more information, see Volume One, Chapter 14, Window Management. 

Errors 
BadWindow 

Related Commands 
XRaiseWindow, XCirculateSubwindows, XCirculateSubwindowsDown, 
XCirculateSubwindowsUp, XRestackWindows, XMoveWindow, XResizeWindow, 
XMoveResizeWindow, XReparentWindow, XConfigureWindow, XQueryTree. 

286 July 26, 1988 



mXlib - Association Tables 

XMakeAssoc 

Name 
XMakeAssoc -- create an entry in an association table. 

Synopsis 
XMakeAssoc(display, table, 
Display *display; 
XAssocTable *table; 
XID x id; 
caddr t data; 

x_id, data) 

Arguments 
display 
table 
x id 
-- 
data 
Description 

Specifies a pointer to the Display sucte; returned from XOpenDisplay. 
Specifies the association table in which an entry is to be made. 
Specifies the X resource ID. 
Specifies the data to be associated with the X resource ID. 

XMakeAssoc insets data into an XAssocTable keyed on an XID. Association tables 
allow you to easily associate data with resource ID's for later retrieval by any application. 
This function is provided for compatibility with X Version 10. To use it you must include the 
file <X11/X10.h> and link with the library -loldX. 
Data is inserted into the table only once. Redundant inserts are meaningless and cause no 
problems. The queue in each association bucket is sorted from the lowest XTD tO the highest 
XID. 
For more information, see Volume One, Chapter 13, Other Programming Techniques. 

Structure 
typedef struct { 
XAssoc *buckets; 
int size; 
} XAsocTable; 

/* pointer to first bucket in bucket array */ 
/* table size (number of buckets) */ 

typedef struct XAssoc { 
-- 
struct XAssoc *next; 
-- 
struct _XAssoc *prev; 
Display *display; 
XID x_id; 
char *data; 
} XAssoc; 

/* next object in this bucket */ 
/* previous object in this bucket */ 
/* display which owns the ID */ 
/* X Window System ID */ 
/* pointer to untyped memory */ 

Related Commands 
XCreateAssocTable, XDeleteAssoc, XDestroyAssocTable, XLookUpAssoc. 

July 26, 1988 28 7 



mXlib - Window Mapping 

XMapSubwindows 

Name 
XMapSubwindows m map all subwindows. 

Synopsis 
XMapSubwindows(display, 
Display *display; 
Window w; 

w) 

Arguments 
display 

Specifies a pointer to the Display structure; returned from XOpenDisplay. 
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. 

For more information, see Volume One, Chapter 14, Window Management. 

Errors 
BadWindow 

Related Commands 
XMapRa i s ed, XMapWindow, XUnmapS ubwindows, XUnmapWindow. 

July 26, 1988 289 



XMapWindow 

Xlib - Window Mapping-- 

Name 
XMapWindow -- map a window. 

Synopsis 
XMapWindow(display, w) 
Display *display; 
Window w; 

Arguments 
display 

Specifies a pointer to the Display structure; 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 win- 
dow has no effect (it does not raise the window). 

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 win- 
dow, then begins processing input events, the window is painted twice. To avoid this, the 
client should use either of two strategies: 

Map the window, call XSelect Input for exposure events, wait for the first Expose 
event, and repaint each window explicitly. 

2. Call XSelectInput 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 
managers that intercept the request. 

Errors 
BadWindow 

Related Commands 
XMapRaised, XMapSubwindows, XUnmapSubwindows, XUnmapWindow. 

290 July 26, 1988 



mXlib - Input Handling 

XMaskEvent 

Name 
XMaskEvent -- remove the next event that matches mask. 

Synopsis 
XMaskEvent (display, event_mask, rep) 
Display *display; 
unsigned long event mask; 
XEvent *rep; /* RETURN */ 

Arguments 
display 

event mask 

rep 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the event mask. See XSelectInput for a complete fist of event 
masks. 
Returns the event removed from the input queue. 

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 dis- 
carded. If no such event has been queued, XMaskEvent flushes the output buffer and waits 
until one is received. Use XCheckMaskEvent if you do not wish to wait. 

In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the 
output buffer is flushed only if no matching events are found on the queue. This change is 
compatible with applications written for Release 1. 

Reled Commands 
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheck- 
WindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XCheckMask- 
Event, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, 
XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, 
XPending, XSynchronize, XSendEvent, QLength. 

July 26, 1988 291 



DXlib - Keyboard 

XNewModifiermap 

Name 
XNewModifiermap -- create a keyboard modifier mapping structure. 

Synopsis 
XModifierKeymap *XNewModifiermap(max_keys_per_mod) 
int max_keys__per_mod; 

Arguments 
max_keys__per_mod 
Specifies the maximum number of keycodes assigned to any of the modifiers in the 
map. 

Description 
XNewModifierrnap returns a XModifierKeymap sucture and locates the needed 
space. This funcdon is used when more than one XModifierKeymap s[ructure is needed. 
max_keys_.per_mod depends on the server and should be gotten from the XModifier- 
Keymap returned by XGetModifierMapping. 
For more information on keyboard preferences, see Volume One, Chapter 9, The Keyboard 
and Pointer. 

Structures 
typedef struct { 
int max__keypermod; 
KeyCode *modifiermap; 

} XModifierKeymap; 

/* server's max number of keys per modifier */ 
/* An 8 by max_keypermod array 
* of the modifiers */ 

Related Commands 
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, 
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XQueryKeymap, 
XStringToKeysym, XLookupKeysym, XRebindKeysym, XGetKeyboardMapping, 
XChageKeyboardMapping, XRefreshKeyboardMapping, XLookupString, 
XSetModifierMapping, XGetModifierMapping. 

July 26, 1988 295 



XNextEvent 

Xlib - Input Handling 

Name 
XNextEvent -- get the next event of any type or window. 

Synopsis 
XNextEvent(display, report) 
Display *display; 
XEvent *report ; 

/* RETURN */ 

Arguments 
display 

report 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Returns the event removed from the input queue. 

XNextEvent removes an input event from the head of the event queue and copies it into an 
XEvent supplied by the caller. If the event queue is empty, XNextEvent flushes the output 
buffer and waits (blocks) until an event is received. Use XCheckNextEvent if you do not 
want to wait. 
In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the 
output buffer is flushed only if no matching events are found on the queue. This change is 
compatible with applications written for Release 1. 
For more information, see Volume One, Chapter 8, Events. 

Related Commands 
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheck- 
WindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, 
XCheckMaskEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, 
XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, 
XPending, XSynchronize, XSendEvent, QLength. 

296 July 26, 1988 



--Xlib - HouseKeeping 

XNoOp 

Name 
XNoOp -- send a NoOp to exercise connection with the server. 

Synopsis 
XNoOp(display) 
Display *display; 

Arguments 
display Specifies a pointer to the Display structure; returned from X0pen- 
Display. 
Description 
XNo0p sends a No0peration request to the X server, thereby exercising the connection. 
This request can be used to measure the response time of the network connection, xNo0p 
does not flush the output buffer. 

Related Commands 
XFree, XOpenDisplay, XCloseDisplay, DefaultScreen. 

July 26, 1988 

297 



XOffsetRegion 

Xlib - Regions-- 

Name 
XOffsetRegion--changeoffsetofaregion. 
Synopsis 
XOffsetRegion(r, dx, dy) 
Region r; 
int dx, dy; 

Arguments 

dx 

Specifies the region. 
Specify the amount to move the specified region relative to the origin of all 
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 clip_mask by calling XSetRegion, the upper-left comer of 
the region relative to the drawable used in the graphics request will be at (xoffset + 
clip x origin, yoffset + clip_y_origin), where xoffset and yoffset are 
the offset of the region and clip x origin and clip y origin are elements of the GC 
used in the graphics request. 

Structures 
/. 
* opaque reference to Regiondata type. 
* user won't need contents, only pointer. 
*/ 
typedef struct _XRegion *Region; 

Related Commands 
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion, 
XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPoint- 
InRegion, XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroy- 
Region, XEqualRegion, XClipBox. 

298 July 26, 1988 



XOpenDisplay (continued) Xlib - HouseKeeping 

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 
display by a single user. screen merely sets an internal variable that is 
returned by the DefaultScreen 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 DefaultScreen macro. After opening the 
display, you can use the ScreenCount macro to determine how many screens are available. 
Then you can reference each screen with integer values between 0 and the value returned by 
ScreenCount. 
For more information, see Volume One: Chapter 2, X Concepts; and Chapter 3, Basic Win- 
dow Program. 

Structures 
/. 
* Display datatype maintaining display specific data. 

./ 
typedef struct _XDisplay { 
XExtData *ext data; 
-- 
struct _XDisplay *next; 
int fd; 
int lock; 
int proto_major_version; 
int proto_minor_version; 
char *vendor; 
long resource base; 
-- 
long resource mask; 
-- 
long resource id; 
-- 
int resource shift; 
-- 
XID (*resource alloc) () ; 
-- 
int byte_order; 
int bitmap_unit; 
int bitmap_pad; 
int bitmap_bit_order; 
int nformats; 
ScreenFormat *pixmap_format; / 
int vnumber; / 
int release; / 
struct XSQEvent *head, *tail; 
-- 
int qlen; 
int last_request_read; 
int request; 
char *last_req; 
char *buffer; 
char *bufptr; 

/* hook for extension to hang data */ 
/* next open Display on list */ 
/* network socket */ 
/* is someone in critical section */ 
/* major version of server's X protocol */ 
/* minor version of server's X protocol */ 
/* vendor of the server hardware */ 
/* resource ID base */ 
/* resource ID mask bits */ 
/* allocator current ID */ 
/* allocator shift to correct bits */ 
/* allocator function */ 
/* screen byte order, LSBFirst, MSBFirst */ 
/* padding and data requirements */ 
/* padding requirements on bitmaps */ 
/* LeastSignificant or MostSignificant */ 
/* number of pixmap formats in list */ 
* pixmap format list */ 
* Xlib's X protocol version number */ 
* release of the server */ 
/* input event queue */ 
/* length of input event queue */ 
/* sequence number of last event read */ 
/* sequence number of last request */ 
/* beginning of last request, or dummy */ 
/* output buffer starting address */ 
/* output buffer index pointer */ 

300 July 26 1988 



Xlib - HouseKeeping (continued) XOpenDisplay 

char *bufmax; 
unsigned max_request_size; 
struct XrmHashBucketRec *db; 
-- 
int (*synchandler) (); 
char *display_name; 
int default screen; 
-- 
int nscreens; 
Screen *screens; 
int motion buffer; 
-- 
Window current; 
int min_keycode; 
int max_keycode; 
KeySym *keysyms; 
XModifierKeymap *modifiermap; 
int keysyms_per_keycode; 
char *xdefaults; 
char *scratch buffer; 
-- 
unsigned long scratch_length; 
int ext number; 
_ 
XExtension *ext_procs; 
-- 
/* 

/* output buffer maximum+l address */ 
/* maximum number 32 bit words in request*/ 

/* synchronization handler */ 
/* "host:display" string used on this connect*/ 
/* default screen for operations */ 
/* number of screens on this server*/ 
/* pointer to list of screens */ 
/* size of motion buffer */ 
/* for use internally for KeymapNotify */ 
/* minimum defined keycode */ 
/* maximum defined keycode */ 
/* this server's keysyms */ 
/* this server's modifier keymap */ 
/* number of rows */ 
/* contents of defaults from server */ 
/* place to hang scratch buffer */ 
/* length of scratch buffer */ 
/* extension number on this display */ 
/* extensions initialized on this display */ 

* The following can be fixed size, as the protocol defines how much 
* address space is available. While this could be done using the 
* extension vector, there may be MANY events processed, so a search 
* through the extension list to find the right procedure for each 
* event might be expensive if many extensions are being used. 
*/ 
Bool (*event vec[128]) (); /* vector for wire to event */ 
-- 
Status (*wire vec[128]) (); /* vector for event to wire */ 
-- 
} Display; 

/* 
* Information about the screen 
*/ 
typedef struct { 
XExtData *ext data; 
-- 
struct _XDisplay *display; 
indow root; 
int width, height; 
int mwidth, mheight; 
int ndepths; 
Depth *depths; 
int root_depth; 
Visual *root visual; 
-- 
GC default_gc; 
Colormap cmap; 
unsigned long white_pixel; 
unsigned long black_pixel; 
int max_maps, min_maps; 
int backing_store; 
Bool save unders; 
-- 
long root_input_mask; 
} Screen; 

/* hook for extension to hang data */ 
/* back pointer to display structure */ 
/* root window ID */ 
/* width and height of screen */ 
/* width and height of in millimeters */ 
/* number of depths possible */ 
/* list of allowable depths on the screen 
/* bits per pixel */ 
/* root visual */ 
/* GC for the root root visual */ 
/* default colormap */ 
/* white and black pixel values */ 
/* max and min colormaps */ 
/* Never, WhenMapped, Always */ 
/* initial root input mask */ 

301 



XOpenDisplay (continued) Xlib- HouseKeeping 

* Format structure; describes ZFormat data the screen will understand. 
*/ 
typedef struct { 
XExtData *ext_data; /* hook for extension to hang data */ 
int depth; /* depth of this image format */ 
int bits_per_pixel; /* bits/pixel at this depth */ 
int scanline_pad; /* scan line must padded to this multiple */ 
} ScreenFormat; 

Related Commands 
XFree, XCloseDisplay, XNoOp, DefaultScreen. 

302 July 26, 1988 



mXlib - Color Cells 

XParseColor 

Name 
XParseColor -- look up or transla RGB values from ASCII color name or 
hexadecimal value. 
Synopsis 
Status XParseColor(display, colormap, 
Display *display; 
Colormap colormap; 
char *spec; 
XColor *rgb_db_def; /* RETURN */ 

spec, rgb_db_def) 

Arguments 
display 

cmap 

spec 

Specifies a pointer to the Display structe; tumed from XOpen- 
Display. 

Specifies a colormap. This argument is required but is not used. The same 
code is used to process xparseColor and XLookupColor, but only 
XLookupColor retums actual values from the colormap. 
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 character 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 hexa- 
decimal 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 XGetDefault 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 
significant bits of the value. For example, #3a7 is the same as #3000a0007000. The 
colormap is used to determine which screen to look up the color on. The screen's default 
colormap is a reliable choice. 

Xlib Reference Manual 303 



XParseColor (continued) Xlib - Color Cells 

This routine will fail and return a Status of 0 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 0 on failure, 1 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 
BadColor 

Related Commands 
XAllocColorCells, XAllocColorPlanes, XAllocColor, XAllocNamedColor, 
XLookupColor, XQueryColor, XQueryColors, XStoreColor, XStoreColors, 
XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel. 

304 Xlib Reference Manual 



XPeekEvent 

Xlib - Input Handling m 

Name 
XPeekEvent -- get an event without removing it from the queue. 

Synopsis 
XPeekEvent(display, report) 
Display *display; 
XEvent *report; 

/* RETURN */ 

Arguments 
display 

report 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Returns the event peeked from the input queue. 

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 output 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 XPeekIfEvent. In Release 2, XEventsQueued can perform the function 
of either QLength or XPending and more. 

In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the 
output buffer is flushed only if no matching events are found on the queue. This change is 
compatible with applications written for Release 1. 

For more information, see Volume One, Chapter 8, Events. 

Related Commands 
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheck- 
WindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, 
XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotion- 
Events, XIfEvent, XCheckIfEvent, XPeekIfEvent, XPutBackEvent, 
XPending, XSynchronize, XSendEvent, QLength. 

306 July26 1988 



XPending 

Xlib - Input Handling m 

Name 
XPending -- flush the output buffer and return the number of pending input events. 

Synopsis 
int XPending(display) 
Display *display; 

Arguments 
display Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Description 
XPending returns the number of input events that have been received from the server, but 
not yet removed from the queue. If there are no events on the queue, xPending flushes the 
output 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 out- 
put buffer first. 
For more information, see Volume One, Chapter 8, Events. 

Related Commands 
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheck- 
WindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, 
XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotion- 
Events, XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBack- 
Event, XSynchronize, XSendEvent, QLength. 

308 July 26, 1988 



--Xlib - Resource Manager 

Xpermalloc 

Name 
Xpermalloc -- allocate memory never to be freed. 

Synopsis 
char *Xpermalloc (size) 
unsigned int size; 

Arguments 
size 

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. 

July 26, 1988 

309 



XPointlnRegion 

Xlib - Regions m 

Name 
XPoinflnRegion--dermineifapointisinsidea gn. 
Synopsis 
int XPointInRegion(r, x, y) 
Region r; 
int x, y; 

Arguments 

Specifies the region. 
Specify the x and y coordinates of the point relative to the region's origin. 

Description 
XPointInRegion 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 
/. 
* opaque reference to Regiondata type. 
* user won't need contents, only pointer. 
*/ 
typedef struct _XRegion *Region; 

Related Commands 
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion, 
XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XOffset- 
Region, XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroy- 
Region, XEqualRegion, XClipBox. 

310 July 26, 1988 



XPolygonRegion (continued) Xlib- Regions 

Structures 
typedef struct { 
short x,y; 
} XPoint; 

/* 
* opaque reference to Regiondata type. 
* user won't need contents, only pointer. 
*/ 
typedef struct _XRegion *Region; 

Related Commands 
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion, 
XShrinkRegion, XSetRegion, XRectInRegion, XPointInRegion, XOffset- 
Region, XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroy- 
Region, XEqualRegion, XClipBox. 

312 July26, 1988 



XPutlmage 

Xlib - Images m 

Name 
XPutImage m draw a rectangular image on a window or pixmap. 
Synopsis 
XPutImage (display, drawable, gc, image, src_x, src_y, 
dst_x, dst_y, width, height) 
Display *display; 
Drawable drawable ; 
GC gc ; 
XImage *image ; 
int src_x, src_y; 
int dst_x, dst_y; 
unsigned int width, height ; 

Arguments 
display 

dra wabl e 
gc 
image 
src x 
-- 
s rc_y 
dst x 
-- 
dst_y 
width 
height 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the drawable. 
Specifies the graphics context. 
Specifies the image you want combined with the rectangle. 
Specify the coordinates of the upper-left corner of the rectangle to be copied, 
relative to the origin of the image. 
Specify the x and y coordinates, relative to the origin of the drawable, where 
the upper-left corner of the copied rectangle will be placed. 
Specify the width and height in pixels of the rectangular area to be copied. 

Description 
xPut Image 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. 
XPutImage uses these graphics context components: function, plane_mask, 
subwindow_mode, clip x origin, clip_y_origin, and clip_mask. This func- 
tion also uses these graphics context mode-dependent components: foreground and back- 
ground. 
If an XYBitmap format image is used, then the depth of drawable must be 1 and the image 
must be XYFormat, otherwise a BadMatch error is generated. The foreground pixel in 
gc defines the source for set bits in the image, and the background pixel defines the source 
for the bits set to 0. 
For xYPixmap and zPixmap format images, the depth of the image must match the depth of 
drawable. For xYPixmap, the image must be sent in XYFormat. For ZPixmap, the 
image must be sent in the ZFormat defined for the given depth. 

314 July 26, 1988 



Xlib - Images (continued) XPutlmage 

Structures 
typedef struct _XImage ( 
int width, height; 
int xoffset; 
int format; 
char *data; 
int byte_order; 
int bitmap_unit; 

/* 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 */ 

int bitmap_bit_order; /* LSBFirst, MSBFirst */ 

int bitmap_pad; 
int depth; 
int bytes_per_line; 
int bits_per_pixel; 
char *obdata; 
struct funcs { 

/* 8, 16, 32 either XY or ZPixmap */ 
/* depth of image */ 
/* accelerator to next line */ 
/* bits per pixel (ZPixmap) */ 
/* hook for the object routines to hang on */ 
/* 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; 

Errors 
BadDrawable 
BadGC 
BadMatch 
BadValue 

See Description above. 

Related Commands 
XDesroyImage, XGetImage, XCreateImage, XSubImage, XGetSubImage'XAdd- 
Pixel, XPutPixel, XGetPixel, ImageByteOrder- 

July 26, 1988 

315 



Xlib -Images (continued) XPutPixel 

Related Commands 
XDestroyImage, XPutImage, XGetImage, XCreateImage, XSubImage, XGetSub- 
Image, XAddPixel, XGetPixel, ImageByteOrder. 

July26, 1988 

317 



XQueryBestCursor 

Xlib - Cursors-- 

Name 
XQueryBestCursor -- get the closest supported cursor sizes. 

Synopsis 
Status XQueryBestCursor (display, drawable, width, height, 
rwidth, rheight) 
Display *display; 
Drawable drawable ; 
unsigned int width, height ; 
unsigned int *rwidth, *rheight; /* RETURN */ 

Arguments 
display 

dra wabl e 

width 
height 
rwidth 
rheight 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies a drawable that indicates which screen the cursor is to be used on. 
The best cursor may be different on different screens. 
Specify the preferred width and height, in pixels. 

Return pointers to the closest supported cursor dimensions, in pixels, on the 
display 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. XQueryBest- 
Cursor 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 1 if the call succeeded in getting a supported size (may be the 
same or different from the specified size), or 0 if the call failed. 

Errors 
BadDrawable 

Related Commands 
XDefineCursor, XUndefineCursor, XCreateFontCursor, XCreateGlyph- 
Cursor, XCreatePixmapCursor, XFreeCursor, XRecolorCursor, XQueryBest- 
Size. 

318 Xlib Reference Manual 



XQueryBestSize (continued) Xlib - Pixmaps and Tiles 

Related Commands 
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindow- 
BackgroundPixmap, XCreatePixmap, XCreatePixmapFromBitmapData, XFree- 
Pixmap, XQueryBestStipple, XWriteBitmapFile, XReadBitmapFile, 
XCreateBitmapFromData. 

320 July 26, 1988 



--Xlib - Pixmaps and Tiles 

X Que ry BestSti p pie 

Name 
XQueryBestStipple -- obtain the best 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 

dra wabl e 

width 
height 
rwidth 
rheight 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies a drawable that tells the server which screen you want the best size 
for. 

Specify the preferred width and height in pixels. 

Return the width and height, in pixels, of the stipple best supported by the 
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 rnputOnly window 
cannot be used as the drawable (else a BadMatch error occurs). 
XQueryBestStipple returns 1 if the call succeeded in getting a supported size (may be 
the same or different from the specified size), or 0 if the call failed. 
For more information on stipples, see Volume One, Chapter 5, The Graphics Context. 

Errors 
BadDrawable 
BadMatch 

InputOnly window. 

Related Commands 
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindow- 
BackgroundP ixmap, XCreateP ixmap, XCreatePixmapFromBitmapData, XFree- 
Pixmap, XQueryBestSize, XWriteBitmapFile, XReadBitmapFile, XCreate- 
BitmapFromData. 

Xlib Reference Manual 321 



DXlib - Color Cells 

XQueryColor 

Name 
XQueryColor m obtain the RGB values and flags for a specified pixel value. 
Synopsis 
XQueryColor (display, cmap, colorcell def) 
-- 
Display *display; 
Colormap cmap; 
XColor *colorcell def; /* SEND and RETURN */ 

Arguments 
display 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 

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 same structure, 
and the flags member of that structure is set to (DoRed I DoGreen I 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 
BadColor 
BadValue 

Pixel not valid index into cmap. 

Related Commands 
XAIIocColorCelIs, XAllocColorPlanes, XAIIocColor, XAllocNamedColor, 
XLookupColor, XParseColor, XQueryColors, XStoreColor, XStoreColors, 
XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel. 

July 26, 1988 323 



XQueryColors 

Xlib - Color Cells-- 

Name 
XQueryColors m obtain RGB values for an army of pixel values. 
Synopsis 
XQueryColors (display, cmap, colorcell_defs, ncolors) 
Display *display; 
Colormap cmap; 
XColor colorcell defs[ncolors] ; /* SEND and RETURN */ 
int ncolors ; 

Arguments 
display 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 

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. 

n col ors Specifies the number of xCo 1 o r 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 craap 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 I 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 
BadColor 
BadValue Pixel not valid index into cmap. 
Note: if more than one pixel value is in error, the one reported is arbitrary. 

Related Commands 
XAllocColorCells, XAllocColorPlanes, XAllocColor, XAllocNamedColor, 
XLookupColor, XParseColor, XQueryColor, XStoreColor, XStoreColors, 
XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel. 

324 July 26, 1988 



XQueryExtension (continued) Xlib- Extensions 

Related Commands 
XListExtensions, XFreeExtensionList. 

326 July 26, 1988 



XQueryFont (continued) Xlib - Fonts 

int ascent; 
int descent; 
} XFontStruct; 

/* logical extent above baseline for spacing */ 
/* logical descent below baseline for spacing */ 

Related Commands 
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts, 
XListFontsWithInfo, XFreeFontNames, XFreeFontPath, XGetFontPath, 
XSetFont, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFont- 
Cursor. 

328 Xlib Reference Manual 



XQueryPointer 

Xlib - Pointer-- 

Name 
XQueryPointer -- get the current pointer location. 
Synopsis 
Bool XQueryPointer (display, w, root, 
win_x, win_y, keys_buttons) 
Display *display; 
Window w; 
Window *root, *child; 
int *root_x, *root_y; 
int *win_x, *win_y; 
unsigned int *keys_buttons; 

child, 

/* RETURN */ 
/* RETURN */ 
/* RETURN */ 
/* RETURN */ 

root_x, root_y, 

Arguments 
display 

root 
child 

root x 
root_y 

win x 
-- 
win_y 

Specifies a pointer to the Display sVucte; returned from XOpenDisplay. 
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. 
Returns the root window ID the pointer is currently on. 
Returns the ID of the child of w the pointer is located in, or 0 if it not in a 
child. 
Return the x and y coordinates of the pointer relative to the root's origin. 

Return the x and y coordinates of the pointer relative to the origin of window 
W. 

key3_buttons 
Returnsthe currentsmte ofthe modifier keys and pointerbuttons. Thisisa 
mask composedofthe OR ofanynumberofthe llowingsymbols: Shift- 
Mask, LockMask, ControlMask, ModlMask, ModlMask, Mod3Mask, 
Mod4Mask, Mod5Mask, ButtonlMask, ButtonlMask, Button3Mask, 
Button4Mask, Button5Mask. 

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 w, 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 w, 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. 

330 July 26, 1988 



Xlib - Pointer (continued) XQue ryPoi nter 

Errors 
BadWindow 

Related Commands 
XWarpPointer, XGrabPointer, XChangeActivePointerGrab, XUngrab- 
Pointer, XGetPointerMapping, XSetPointerMapping, XGetPointerControl, 
XChangePointerControl. 

July 26, 1988 

331 



X Que ryTe xt Exte n ts 

Xlib - Text-- 

Name 
XQueryTextExtents -- query the server for string and font metrics 

Synopsis 
int XQueryTextExtents (display, font_ID, string, nchars, 
direction, ascent, descent, overall) 
Display *display; 
XID font ID; 
-- 
char *string; 
int nchars ; 
int *direction; /* RETURN */ 
int *ascent, *descent; /* RETURN */ 
XCharStruct *overall; /* RETURN */ 

Arguments 
display 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 

font ID 
-- 

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 the character string. 

direction 

Returns the direction the string would be drawn using the specified font. 
Either FontLeftToRight or FontRightToLeft. 

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 lbearing added to the width of all characters up 
to the character with the smallest lbearing, 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 it does not require a filled XFontInfo structure. 
The returned ascent and descent should usually be used to calculate the line spacing, 
while the width, rbearing, and lbearing 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. 

332 Xlib Reference Manual 



Xlib - Text (continued) XQueryTextExtents 

overall, ascent is the maximum of the ascent metrics of all characters in the string. The 
overa22, descent is the maximum of the descent metrics. The overa22, width is the 
sum of the character-width metrics of all characters in the string. The overa22.2bearing 
is the lbearing of the character in the string with the smallest lbearing plus the width of all the 
characters up to but not including that character. The overa22, rbearing is the rbearing 
of the character in the string with the largest lbearing 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. 
XQueryTextExtents returns 1 on success, 0 on failure. 

Structures 
typedef struct { 
short ibearing; 
short rbearing; 
short width; 
short ascent; 
short descent; 

/* 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 */ 

unsigned short attributes;/* per char flags (not predefined) */ 
} XCharStruct; 

Errors 
BadFont 
BadGC 

Related Commands 
XQueryTextExtentsl6, XDrawImageString, XDrawImageStringl6, XDraw- 
String, XDrawStringl6, XDrawText, XDrawTextl6, XTextExtents, XText- 
Extentsl6, XTextWidth, XTextWidthl6. 

333 
Xlib Reference Manual 



XReadBitmapFile 

Xlib - Pixmaps and Tiles E 

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 
di spl ay 

dra wabl e 
f i i en ame 

wi d t h 
height 
bi tmap 
x hot 
-- 
y_hot 
Description 

Specifies a pointer to the Display structure; rcturned from XOpen- 
Display. 
Specifies the drawable. 
Specifies the filename to use. The format of the filename is operating system 
specific. 
Return the dimensions in pixels of the bitmap that is read. 

Returns the pixmap resource ID that is created. 
Return the hotspot coordinates in the file (or -1,-1 if none present). 

XReadBitmapFile reads in a file containing a pixmap of depth 1 (a bitmap). The file can 
be either in the standard X Version 10 format or in the newer X Version 11 bitmap format 
(which is only slightly different). 

XReadBitmapFile creates a pixmap of the appropriate size, reads the bitmap data from the 
file into the pixmap. The caller must free the bitmap using XFreePixmap when done. 
If the file cannot be opened, XReadBitraapFile returns BitraapOpenFailed. If the file 
can be opened but does not contain valid bitmap data, XReadBitraapFile returns Bitmap- 
FileInvalid. If insufficient working storage is allocated, XReadBitmapFile returns 
BitmapNoMemory. If the file is readable and valid, XReadBitmapFile returns Bitmap- 
Success. 

338 July 26, 1988 



Xlib - Pixmaps and Tiles (continued) XReadBitmapFile 

Here is an X Version 11 example bitmap file: 
#define name width 16 
-- 
#define name_height 16 
#define name x hot 8 
#define name y hot 8 
static char name_bits[] = { 
0xf8, 0xlf, 0xe3, 0xc7, 0xcf, 0xf3, 0x9f, 0xf9, 0xbf, 0xfd, 0x33, 0xcc, 
0x7f, 0xfe, 0x7f, 0xfe, 0x7e, 0x7e, 0x7f, 0xfe, 0x37, 0xec, 0xbb, 0xdd, 
0x9c, 0x39, 0xcf, 0xf3, 0xe3, 0xc7, 0xf8, 0xlf}; 
For more information, see Volume One, Chapter 6, Drawing Graphics and Text. 

Related Commands 
XSet Tile, XQue ryBe st Tile, XSetWindowBo rde rP ixmap, XSetWindow- 
BackgroundP ixmap, XCreateP ixmap, XCreateP ixmapF romBitmapDat a, XF ree- 
Pixmap, XQueryBestSize, XQueryBestStipple, XWriteBitmapFile, XCreate- 
BitmapFromData. 

July 26, 1988 

339 



XRebindKeysym 

Xlib - Keyboard-- 

Name 
XRebindKeysym -- rebind a keysym to a string for client. 
Synopsis 
XRebindKeysym ( display, keysym, mod_list, 
n um_byt es ) 
Display *display; 
KeySym keysym; 
KeySym *mod list; 
int mod count; 
unsigned char *string; 
int num_bytes ; 

rood_count, string, 

Arguments 
display 

keysym 
mod list 
-- 
rood count 
string 

num_bytes 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the keysym to be rebound. 
Specifies a pointer to an array of keysyms that are being used as modifiers. 
Specifies the number of modifiers in the modifier list. 
Specifies a pointer to the string that is to be copied and returned by 
XLookupSt ring. 
Specifies the length of the string. 

XRebindKeysym binds the ASCII string to the specified keysym, so that string and 
keysym arc returned when that key is pressed and the modifiers specified 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 
keyboard mapping. 

Related Commands 
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, 
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifier- 
Map, XQueryKeymap, XStringToKeysym, XLookupKeysym, XGetKeyboard- 
Mapping, XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookup- 
String, XSetModifierMapping, XGetModifierMapping. 

340 July 26, 1988 



XRemoveFromSaveSet 

Xlib - Save Set D 

Name 
XRemoveFromSaveSet -- remove a window's children from the client's save-set. 

Synopsis 
XRemoveFromSaveSet ( display, 
Display *display; 
Window w; 

w) 

Arguments 
display 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the window whose children 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's children from the save-set of the calling appli- 
cation. Usually, this call is invoked by a window manager, using the RootWindow macro 
for w, to remove all top-level windows on a screen from the save-set. 

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 desla'oyed windows are automati- 
cally removed from the save-set. See Volume One, Chapter 14, Window Management, for 
more information about save-sets. 

Errors 
BadMatch 
BadWindow 

w not created by some other client. 

Related Commands 
XAddToSaveSet, XChangeSaveSet. 

344 July 26, 1988 



--Xlib - Host Access 

XRemoveHost 

Name 
XRemoveHost--removeahostfrom theaccessconollist. 
Synopsis 
XRemoveHost(display, host) 
Display *display; 
XHostAddress *host; 

Arguments 
di spl ay 

Specifies a point to the Display structu; tumed om XOpen- 
Display. 

host 

Specifies the network address of the machine to be removed. 

Description 
XRemoveHost removes the specified host from the access control list on the host running the 
server controlling the current display. The display hardware must be on the same host as the 
calling process 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 and reset the server. 

The address dam must be a valid address for the type of network in which the server 
operates, 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 
contains 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 Program- 
ming Techniques. 

Structures 
typedef struct { 
int family; 
int length; 
char *address; 
} XHostAddress; 

/* for example Family Internet */ 
/* length of address, in bytes */ 
/* pointer to where to find the bytes */ 

/* constants used for family member of XHostAddress */ 
#define FamilyInternet 0 
#define FamilyDECnet 1 
#define FamilyChaos 2 

Errors 
BadAccess 
BadValue 

July 26, 1988 345 



XRemoveHost (contue Xlib - Host Access 
Related Commands 
XAddHost, XAddHosts, XListHosts, XRemoveHosts, XDisableAccessControl, 
XEnableAccessControl, XSetAccessControl. 

346 July 26, 1988 



--Xlib - Host Access 

XRemoveHosts 

Name 
XRemoveHosts m remove multiple hosts from the access conol list. 
Synopsis 
XRemoveHosts (display, hosts, num hosts) 
-- 
Display *display; 
XHostAddress *hosts; 
int num hosts; 
-- 

Arguments 
di spl ay 

hosts 

num hosts 
-- 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the list of hosts that are to be removed. 
Specifies the number of hosts that are to be removed. 

Description 
XRemoveHosts removes each specified host from the access control list on the local 
machine running the server. The display hardware must be on the same host as the client pro- 
cess, in order to change the access control list. 

If you remove your machine from the access conol list, you can no longer connect to that 
server, and there is no way back from this call except to log out and reset the server. 

The address data must be a valid address for the type of network in which the server 
operates, 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 
contains 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 Program- 
ming Techniques. 

Structures 
typedef struct { 
int family; 
int length; 
char *address; 
} XHostAddress; 

/* for example Family Internet */ 
/* length of address, in bytes */ 
/* pointer to where to find the bytes */ 

/* constants used for family member of XHostAddress */ 
#define FamilyInternet 0 
#define FamilyDECnet 1 
#define FamilyChaos 2 

July 26, 1988 34 7 



X Rem oveHosts (continued) Xlib - Host Access 

Errors 
BadAccess 
BadValue 

Related Commands 
XAddHost, XAddHosts, XListHosts, XRemoveHost, XDisableAccessControl, 
XEnableAccessControl, XSetAccessControl. 

348 July 26, 1988 



NXlib - Window Manipulation 

XReparentWindow 

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, y; 

Arguments 
display 

win 
pa ren t 
x 
y 
Description 

Specifies a pointer to the Display structure; returned from X0pen- 
Display. 
Specifies the ID of the window to be reparented. 
Specifies the window ID of the new parent window. 
Specify the coordinates of the window relative to the new parent. 

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 dccoration 
window behind application windows. 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 ReparentNotify 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 
normally should ignore this event if this member is set to True. 
Finally, if the window was originally mapped, an XMapWindow request is performed 
automatically. 
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. 

July 26, 1988 349 



XReparentWindow (continued) Xlib - Window Manipulation 

Errors 
BadMatch 

BadWindow 

parent not on same screen as old parent of win. 
win has a ParentRelative background and parent is not [he same 
dep[h as win. 
parent is win or an infeor of win. 

Related Commands 
XLowerWindow, XRaiseWindow, XCirculateSubwindows, XCirculate- 
SubwindowsDown, XCirculateSubwindowsUp, XRestackWindows, XMove_ 
Window, XResizeWindow, XMoveResizeWindow, XConfigureWindow, XQuery_ 
Tree. 

350 July 26, 1988 



mXlib - Screen Saver 

X Re se tSc ree n Sa ve r 

Name 
XResetScreenSaver n reset the screen saver. 

Synopsis 
XResetScreenSaver(display) 
Display *display; 

Arguments 
display 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 

Description 
XResetScreenSaver redisplays the screen ff 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 
XForceScreenSaver, XActivateScreenSaver, XGetScreenSaver, XSet- 
ScreenSaver. 

July 26, 1988 

351 



--Xlib - Window Manipulation-. 

XRestackWindows 

Name 
XRestackWindows -- change the stacking order of siblings. 
Synopsis 
XRestackWindows (display, windows, nwindows ) ; 
Display *display; 
Window windows [] ; 
int nwindows ; 

Arguments 
display 

windows 

nwindows 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies an array containing the windows to be restacked. All the windows 
must have a common parent. 
Specifies the number of windows to be restacked. 

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 win- 
dows will be stacked underneath it in the order of the array. Note that other siblings may not 
be included in the windows array and so the top window in that 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 Bad- 
Match error will be generated. If the override redirect attribute of the window is 
-- 
False and some other client has selected SubstructureRedirectMask on the parent, 
then ConfigureRequest events are generated for each window whose 
override_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 
XLowerWindow, XRaiseWindow, XCirculateSubwindows, XCirculate- 
SubwindowsDown, XCirculateSubwindowsUp, XMoveWindow, XResizeWindow, 
XMoveResizeWindow, XReparentWindow, XConfigureWindow, XQueryTree. 

July 26, 1988 353 



XrmGetFileDatabase 

Xlib - Resource Manager-- 

Name 
XrmGetFileDatabase m retrieve a database from a file. 

Synopsis 
XrmDatabase XrmGetFileDatabase(filename) 
char *filename; 

Arguments 
f i i en ame 

Specifies the resource database filename. 

Description 
XrmGetFileDatabase opens the specified file, creates a new resource database, and loads 
it with the data read in from the file. The return value of the function is subsequently used as 
a pointer to the created database. 

The specified file must contain lines in the format accepted by XrmPutLineResource. If 
it cannot open the specified file, XrmGetFileDatabase returns NULL. 

For more information, see Volume One, Chapter 11, Managing User Preferences. 

Structures 
XrmDatabase is a pointer to an opaque data type. 

Related Commands 
XrmGetResource, XrmGetStringDatabase, XrmInitialize, XrmMerge- 
Databases, XrmParseCommand, XrmPutFileDatabase, XrmPutLineResource, 
XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGet- 
SearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutString- 
Resource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmString- 
ToQuarkList, XrmStringToQuark, XrmUniqueQuark. 

354 July 26, 1988 



mXlib - Resource Manager- 

XrmGetResource 

Name 
XrmGetResource -- get a resource from name and class as stnngs. 

Synopsis 
Bool XrmGetResource ( database, 
str_type, value) 
XrmDatabase database; 
char *str name; 
-- 
char *str class; 
-- 
char **str_type; 
XrmValue *value; 

str_name, str class, 
-- 
/* RETURN */ 
/* RETURN */ 

Arguments 
database 

str name 

str class 

str_type 

value 

Specifies the database that is to be used. 
Specifies the fully qualified name of the value being retrieved (as a string). 
str_name is an instance of a name retrieval key as described below. 
Specifies the fully qualified class of the value being retrieved (as a string). 
str_c2ass is an instance of a class retrieval key as described below. 
Returns a pointer to the representation type of the destination. In this func- 
tion, the representation type is itself represented as a string, not as an Xrm- 
Representation. 
Returns the value in the database. Do not modify or free this data. 

Description 
The resource manager manages databases of resources consisting of lines containing resource 
name/class strings followed by a colon and the value of the resource. XrmGetResource 
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; therefore, 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. 

July 26, 1988 355 



Xrmlnitialize 

Xlib - Resource Manager m 

Name 
Xrmlnitialize -- initialize the resource manager. 

Synopsis 
void XrmInitialize(); 

Description 
xrmInitialize initializes the resource manager, and should be called once before using 
any other resource manager functions. All it does is to create a representation type of 
"String" for values defined as strings. This representation type is used by XrmPutString- 
Resource and XrmQPutStringResource, which require a value as a string. See Xrm- 
QPutResource for a descption of representation types. 
For more information, see Volume One, Chapter 11, Managing User Preferences. 
Related Commands 
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, XrmMerge- 
Databases, XrmParseCommand, XrmPutFileDatabase, XrmPutLineResource, 
XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGet- 
SearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutString- 
Resource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmString- 
ToQuarkList, XrmSt ringToQuark, XrmUniqueQuark. 

360 July 26, 1988 



Xlib - Resource Manager (continued) Xrm ParseCom mand 

static XrmOptionDescRec opTable[ ] = { 
{"-background", "*background", 
{"-bd", "*borderColor", 
{"-bg", "*background", 
{"-borderwidth", "*TopLevelShell.borderWidth", 
{"-bordercolor", "*borderColor", 
{"-bw", "*TopLevelShell.borderWidth", 

{ "-display", ".display", 
{ "-fg", "* foreground", 
{ "- fn", " * font", 
{"-font", "*font", 
{ "- foreground", " * foreground", 
{ "-geomet ry", ".TopLeve iShe i i. geomet ry", 
{ "- icon ic", ".TopLeve iShe 11. iconic", 
{ "-name", ".name", 
{ "- reve rse", " * reve rseVideo", 
{ "- rv", "* reve r seVideo", 

{"-synchronous", ".synchronous", 
{ "-title", ".TopLevelShe ii. title", 
{ "-xrm", 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}, 
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- 
l,evelShell (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 dam type. 

typedef enum { 
XrmoptionNoArg, 
XrmoptionIsArg, 
XrmoptionStickyArg, 
XrmoptionSepArg, 
XrmoptionResArg, 
XrmoptionSkipArg, 
XrmoptionSkipLine 
} XrmOptionKind; 

/* 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 */ 

typedef struct { 
char *Option; /* option specification string in argv */ 
char *resourceName; /* binding & resource name (w/out application name) */ 
XrmOptionKind argKind; /* which style of option it is */ 
caddr t value; /* value to provide if XrmoptionNoArg */ 
_ 
} XrmOptionDescRec, *XrmOptionDescList; 

July 26, 1988 

363 



XrmParseCom mand (continued) Xlib - Resource Manager 

Related Commands 
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm- 
Initialize, XrmMergeDatabases, XrmPutFileDatabase, XrmPutLine- 
Resource, XrmPutResource, XrmPutStringResource, XrmQGetResource, Xrm- 
QGetSearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPut- 
StringResource, XrmQuarkToString, XrmStringToBindingQuarkList, Xrm- 
StringToQuarkList, XrmStringToQuark, XrmUniqueQuark. 

364 July 26, 1988 



mXlib - Resource Manager 

XrmPutFileDatabase 

Name 
XrmPutFileDatabase -- store a database in a file. 

Synopsis 
void XrmPutFileDatabase(database, stored db) 
XrmDatabase database; 
char *stored db; 
-- 

Arguments 
database 

stored db 

Specifies the database that is to be saved. 
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 Xrm- 
PutLineResource. 
For more information, see Volume One, Chapter 11, Managing User Preferences. 

Structures 
XrmDatabase is a pointer to an opaque data type. 

Related Commands 
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm- 
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutLineResource, 
XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGet- 
SearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutString- 
Resource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmString- 
ToQuarkList, XrmStringToQuark, XrmUniqueQuark. 

July 26, 1988 

365 



Xlib - Resource Manager (continued) Xrm PutLi neResource 

Related Commands 
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm- 
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, 
XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGet- 
SearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutString- 
Resource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmString- 
ToQuarkList, XrmStringToQuark, XrmUniqueQuark. 

July 26, 1988 

367 



XrmPutResource 

Xlib - Resource Manager m 

Name 
XrmPutResource -- store a resource into a database. 

Synopsis 
void XrmPutResource (database, specifier, type, value) 
XrmDatabase *database; /* SEND, and if NULL, RETURN */ 
char *specifier; 
char *type; 
XrmValue *value; 

Arguments 
database 

specifier 
type 
val ue 
Description 

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 data- 
base. 
Specifies a complete or partial specification of the resource. 
Specifies the type of the resource. 
Specifies the value of the resource. 

XrmPutResource is one of several functions which store data into a database. 
XrraQPutResource first converts specifier into a binding list and a quark list by calling 
XrmStringToBindingQuarkList, and converts type into an XrmRepresentation 
by calling XrmStringToRepresentat ion. Finally, it puts the data into the database. 
XrmPutResource, XrmQPutResource, XrmPut St ringRes ource, 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 11, Managing User Preferences. 

Structures 
XrmDatabase is a pointer to an opaque dam type. 

typedef struct { 
unsigned int size; 
caddr t addr; 
-- 
} XrmValue, *XrmValuePtr; 

368 July 26 1988 



Xlib- Resource Manager (continued) XrmPutResource 

Related Commands 
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm- 
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, 
XrmPutLineResource, XrmPutStringResource, XrmQGetResource, XrmQGet- 
SearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutString- 
Resource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmString- 
ToQuarkList, XrmStringToQuark, XrmUniqueQuark. 

July 26, 1988 

369 



--Xlib - Resource Manager 

XrmQGetResource 

Name 
XrmQGetResource -- get a resource from name and class as quarks. 

Synopsis 
BOO1 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 
database 

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 destination. In this func- 
tion, the representation type is itself 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; therefore, 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- 
HergeDatabases, 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 cquiva|ent 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 11, Managing User Preferences. 

July 26, 1988 371 



XrmQGetResource (continued) Xlib- Resource Manager 

Structures 
XrmDatabase is a pointer to an opaque dam type. 

typedef XrmQuarkList XrmNameList; 
typedef XrmQuarkList XrmClassList; 
typedef XrmQuark XrmRepresentation; 

typedef struct { 
unsigned int size; 
caddr t addr; 
-- 
} XrmValue, *XrmValuePtr; 

Related Commands 
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm- 
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, 
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet- 
SearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutString- 
Resource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmString- 
ToQuarkList, XrmStringToQuark, XrmUniqueQuark. 

372 July 26 1988 



mXlib - Resource Manager 

XrmQGetSearch List 

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 that is to be used. 
names Specifies a list of resource names. 
cl asses 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 list. 

Description 
XrmQGetSearchList is a tool for searching the database more efficiently. It is used in 
combination with XrmGetSearchResource. Often, one searches the database for many 
similar resources which differ only in their final component (e.g. xmh. toc. foreground, 
xmh.toc.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", 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 XrraQGetSearchResource requires that name represent a single com- 

July 26, 1988 373 



XrmQGetSearchList (continued) Xlib- Resource Manager 

ponent 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 dam type. 

typedef XrmQuarkList XrmNameList; 
typedef XrmQuarkList XrmClassList; 
typedef XrmQuark XrmRepresentation; 

XrmSearchList is a pointer to an opaque dam type. 

Related Commands 
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm- 
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, 
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet- 
Resource, XrmQGetSearchResource, XrmQPutResource, XrmQPutString- 
Resource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmString- 
ToQuarkList, XrmStringToQuark, XrmUniqueQuark. 

374 July 26, 1988 



--Xlib- Resource Manager. 

XrmQGetSearch Resource 

Name 
XrmQGetSearchResource m search resource database levels 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 in the database. 

Description 
XrmQGetSearchResource is a tool for searching the database more efficiently. It is used 
in combination with XrmGetSearchList. Often, one searches the database for many simi- 
lar resources which differ only in their final component (e.g., xmh.toc, foreground, 
xmh. toc. 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. 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 XrrnQGetSearchList with a name and class list containing all but the last com- 
ponent of a resource name followed by a call to XrrnQGetSearchResource with the last 
component name and class returns the same database entry as XrraGetResource or Xrra- 
QGetResource would with the fully qualified name and class. 
For more information, see Volume One, Chapter 11, Managing User Preferences. 

July 26. 1988 375 



XrmQGetSearchResource (continued) Xlib- Resource Manager 

Structures 
XrmDatabase is a pointer to an opaque dam 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 dam type. 

Related Commands 
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm- 
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, 
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet- 
Resource, XrmQGetSearchList, XrmQPutResource, XrmQPutStringResource, 
XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuark- 
List, XrmStringToQuark, XrmUniqueQuark. 

376 July 26 1988 



nXlib - Resource Manager- 

XrmQPutResource 

Name 
XrmQPutResource -- store a resource 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 

bindings 
quarks 
type 
va i ue 

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. 
Specifies a list of bindings for binding together the quarks argument. 
Specifies the complete or partial name or class list of the resource to be stored. 
Specifies the type of the resource. 
Specifies the value of the resource. 

Description 
XrmQPutResource stores a resource into the database. 
database can be a previously defined database, as returned by XrmGetString- 
Database, XrmGetFileDatabase, or om 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 XrnaGetResource 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 
different representations of the same information. Representation types are user defined char- 
acter strings describing the way the data is represented. For example, a color may be specificd 
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. 
val ue is the value of the resource, specified as an xrnaValue. 
XrnaGetResource contains the complete description of how data is accessed from the data- 
base, and so provides a good perspective on how it is stored. 

July 26, 1988 377 



XrmQPutResource (continued) Xlib- Resource Manager 

For more information, see Volume One, Chapter 11, Managing User Preferences. 
Structures 
Xrrrd3atabase 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 
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm- 
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, 
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet- 
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutString- 
Resource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmString- 
ToQuarkList, XrmStringToQuark, XrmUniqueQuark. 

378 July 26, 1988 



mXlib - Resource Manager 

XrmQPutStringResource 

Name 
XrmQPutStringResource -- add a string resource value to a database using quarks. 
Synopsis 
void XrmQPutStringResource (database, bindings, quarks, value) 
XrmDatabase *database; /* SEND, and if NULL, RETURN */ 
XrmBindingList bindings ; 
XrrnQuarkList quarks ; 
char *value; 

Arguments 
database 

bindings 
quarks 
val ue 

Description 

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. 
Specifies a list of bindings for binding together the quarks argument. 
Specifies the complete or partial name or class list of the resource to be stored. 
Specifies the value of the resource as a string. 

XrmQPutStringResource stores a resource into the specified database. 
XrmQPutStringResource is a cross between XrmQPutResource and XrmPut- 
StringResource. Like XrrnQPutResource, it specifies the resource by quarks and 
bindings, two lists that together make a name/class list with loose and tight bindings. Like 
XarmPutStaringResouarce, it specifies the value to be stored as a string, that value is con- 
vened into an xarrnValue, and the default representation type Staring is used. 

XrmPutResource, XrmQPutResource, XrmPut St ringResource, 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 
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm- 
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, 
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet- 
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, 
XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuark- 
List, XrmStringToQuark, XrmUniqueQuark. 

July 26, 1988 379 



XrmQuarkToString 

Xlib- Resource Manager m 

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 
XrrnQuarkToString returns the string for which the quark is serving as a shorthand sym- 
bol. 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, 
these routines return NULL. 
Quarks are used by the resource manager to represent strings. 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 #define 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/resource.h> */ 
#define XrmNameToString (name) XrmQuarkToString (name) 
#define XrmClassToString (class) XrmQuarkToString (class) 
#define XrmRepresentationToString (type) XrmQuarkToString (type) 

Related Commands 
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm- 
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, 
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet- 
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, 
XrmQPutStringResource, XrmStringToBindingQuarkList, XrmString- 
ToQuarkList, XrmStringToQuark, XrmUniqueQuark. 

380 July 26, 1988 



uXlib - Resource Manager 

XrmStringToBindingQuarkList 

Name 
XrmStringToBindingQuarkList m 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 

bindings 

quark 

Description 

Specifies the string for which the list of quarks and list of bindings are to be 
generated. Must be NULL terminated. 
Returns the binding list. The caller must allocate sufficient space for the 
binding list before the call. 
Returns the list of quarks. The caller must allocate sufficient space for the 
quarks list before the call. 

XrmStringToBindingQuarkList convers the sing into two liss--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 XrrnGetResource for a full description of lookup rules. 
For example, *a. b*c becomes: 
quarks bindings 
"a" XrmBindLoosely 
"b" XrmBindTight ly 
"C" XrmBindLoosely 

For more information, see Volume One, Chapter 11, Managing User Preferences. 

Structures 
typedef int XrmQuark, *XrmQuarkList; 
typedef enum (XrmBindLoosely, XrmBindTightly) XrmBinding, *XrmBindingList; 

July 26, 1988 381 



XrmStringToBindingQuarkList (continued) Xlib- Resource Manager 

Related Commands 
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm- 
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, 
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet- 
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, 
XrmQPutStringResource, XrmQuarkToString, XrmStringToQuarkList, Xrm- 
St ringToQua rk, XrmUniqueQua rk. 

382 July 26, 1988 



Xlib- Resource Manager (continued) XrmStringToQuarkList 

Related Commands 
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm- 
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, 
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet- 
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, 
XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuark- 
List, XrmStringToQuark, XrmUniqueQuark. 

July 26, 1988 

385 



XrmUniqueQuark 

Xlib - Resource Manager m 

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, XrraStringToQuark 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 com- 
parisons. Quarks are presently represented as ints. Simple comparisons of quarks can be per- 
formed 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 
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm- 
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, 
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet- 
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, 
XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuark- 
List, XrmStringToQuarkList, XrmStringToQuark. 

386 July 26, 1988 



--Xlib - Cut Buffers 

XRotateBuffers 

Name 
XRotateBuffers -- rotate the cut buffers. 
Synopsis 
XRotateBuffers (display, rotate) 
Display *display; 
int rotate; 

Arguments 
display 

rotate 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies how many positions to rotate the cut buffers. 

XRotateBuffers rotates the 8 cut buffers the amount specified by rotate. Buffer 0 
becomes buffer rotate, buffer 1 becomes buffer rotate+l mod 8, buffer 2 becomes buffer 
rotate+2 mod 8, and so on. This cut buffer numbering is global to the display. This rou- 
tine will not work if any of the buffers have not been stored into with XStoreBuffer. 

See the description of cut buffers in Volume One, Chapter 13, Other Programming Tech- 
niques. 

E rro rs 
BadAtom 
BadMatch 
BadWindow 

Related Commands 
XStoreBuffer, XStoreBytes, XFetchBuffer, XFetchBytes. 

July 26, 1988 38 7 



Xlib - Properties (continued) X RotateWi ndowProperties 

Related Commands 
XSet S t anda rdP rope rt ie s, XGetF ontP rope rt y, XDe leteP rope rt y, XChange- 
Property, XGetWindowProperty, XListProperties, XGetAtomName, XIntern- 
Atom. 

July 26, 1988 

389 



XSaveContext 

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 pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the ID of the window with which the data is associated. 
Specifies the context type to which the data corresponds. 
Specifies the data to be associated with the window and type. 

w 
context 
data 
Description 
XSaveContext saves data to the context manager database, according to the specified 
window 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. 

390 July 26, 1988 



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, Button5MotionMask is selected, 
MotionNotify events will be generated only when one or more of the specified buttons is 
depressed. 

XOpenDisplay sets the event_mask attribute; this attribute can also be set directly with 
XChangeWindowAtt ributes. 

For more information, see Volume One, Chapter 8, Events. 

Errors 
BadValue 
BadWindow 

Related Commands 
XSetInputFocus, XGetInputFocus, XWindowEvent, XCheckWindowEvent, 
XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMask- 
Event, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, 
XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, 
XPending, XSynchronize, XSendEvent, QLength. 

392 July 26, 1988 



uXlib - Input Handling 

XSendEvent 

Name 
XSendEvent -- send an event. 
Synopsis 
Status XSendEvent (display, w, propagate, 
Display *display; 
Window w; 
Bool propagate; 
unsigned long event mask; 
-- 
XEvent *event ; 

event mask, event) 
-- 

Arguments 
display 

propa ga t e 

event mask 
-- 

e yen t 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the ID of the window where you want to send the event. Pass the 
window resource ID, PointerWindow, or InputFocus. 
Specifies how the sent event should propagate depending on event mask. 
-- 
See description below. May be True or False. 
Specifies the event mask. See XSelectInput for a detailed list of the 
event masks. 
Specifies a pointer to the event to be sent. 

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 
specified 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 pro- 
pagates 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 except that in Release 1 the most 
significant bit of XEvent. type is set to 1. In Release 2, the high bit is no longer scL 
Instead, a new flag send event has been added to each event, which if True indicates that 
-- 
the event was sent with XSendEvent. 

July 26, 1988 393 



XSendEvent (continued) Xlib- Input Handling 

Under Release 1, if a client wants to read events sent by XSendEvent as normal events, it 
must ignore the high bit by ORing the event type with the following expression: 

XEvent report; 
XNextEvent(display, &report) ; 
report.type &= 0x7f; 
/* now sent event looks like any other */ 
This function is often used in selection processing. For example, the owner of a selection 
should use XSendEvent to send a SelectionNotify 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. Along with changes in the extensions mechan- 
ism, this makes merging of two wire events into a single user-visible event possible. 

Structures 
See Appendix F, Structure Reference, for the contents of specific event structures. 

Related Commands 
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheck- 
WindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, 
XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotion- 
Events, XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBack- 
Event, XPending, XSynchronize, QLength. 

394 July 26, 1988 



Xllb - Host Access 

XSetAccessControl 

Name 
XSetAccessControl -- disable or enable access control. 
Synopsis 
XSetAccessControl (display, mode) 
Display *display; 
int mode ; 

Arguments 
di spl ay 

mode 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies whether you want to enable or disable the access control. Pass one 
of these constants: EnableAccess or DisableAccess. 

Description 
XSetAccessControl specifies whether to 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 Program- 
ming Techniques. 

Errors 
BadAccess 
BadValue 

Related Commands 
XAddHost, XAddHosts, XListHosts, XRemoveHost, XRemoveHosts, XDisable- 
AccessControl, XEnableAccessControl. 

July 26, 1988 395 



--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 
di spl ay 

gc 
arc mode 

Specifies a pointer to the Display structure; returned from X0pen- 
Display. 
Specifies the graphics context. 
Specifies the arc mode for the specified graphics context. Possible values are 
ArcChord or ArcPieSlice. 

Description 
XSetArcMode sets the arc mode member of the GC, which conlxols filling in the XFilI- 
-- 
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 rectan- 
gle defining the arc. 

ArcChord 

ArcPieSlice 

July 26, 1988 

397 



XSetArcMode (continued) Xlib - Graphics Context 

Errors 
BadAlloc 
BadGC 
BadValue 

Related Commands 
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, 
XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSet- 
FillRule, XSetFillStyle, XSetForeground, XSetBackground, XSet- 
Function, XSetGraphicsExposures, XSetClipMask, XSetClipOrigin, XSet- 
ClipRectangles, XSetState, XSetSubwindowMode, DefaultGC. 

398 July 26, 1988 



mXlib - Graphics Context 

XSetBackground 

Name 
XSetBackground m set the background pixel value in a graphics context. 
Synopsis 
XSetBackground (display, go, background) 
Display *display; 
GC gc ; 
unsigned long background; 

Arguments 
di spl ay 

gc 
background 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the graphics context. 
Specifies the background you want to set for the specified graphics context. 

Description 
XSetBackground sets the background pixel value for graphics requests. Note that this 
is different from the background of a window, which can be set with either XSetWindow- 
Background or XSetWindowBackgroundPixmap. 

Errors 
BadAlloc 
BadGC 

Related Commands 
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, 
XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSet- 
FillRule, XSetFillStyle, XSetForeground, XSetFunction, XSetGraphics- 
Exposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClip- 
Rectangles, XSetState, XSetSubwindowMode, DefaultGC- 

July 26, 1988 

399 



mXlib - Graphics Context 

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 
di spl ay 

gc 
clip_mask 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the graphics context. 
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 member of a GC to a pixmap. The clip mask 
-- 
filters which pixels in the destination are drawn. If clip_mask is set to None, the pixels arc 
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 
BadAlloc 
BadGe 
BadMatch 
BadValue 

Related Commands 
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, 
XSetTOrigin, XSetPlaheMask, XSetDashes, XSetLineAttributes, XSet- 
FillRule, XSetFillStyle, XSetForeground, XSetBackground, XSet- 
Function, XSetGraphicsExposures, XSetArcMode, XSetClipOrigin, XSet- 
ClipRectangles, XSetState, XSetSubwindowMode, DefaultGC. 

July 26, 1988 401 



XSetClipOrigin 

Xlib - Graphics Context m 

Name 
XSetClipOrigin -- set the clip origin in a graphics context. 
Synopsis 
XSetClipOrigin (display, gc, clip x origin, 
Display *display; 
GC gc ; 
int clip x origin, clip_y_origin; 

clip_y_origin ) 

Arguments 
di splay 

gc 
clip x origin 
clip_y_origin 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the graphics context. 
Specify the coordinates of the clip origin relative to the window 
specified in the GC. 

Description 
XSetClipOrigin se the clip x origin and clip_y_origin members of the GC. 
The clip origin controls the position of the clip_mask hl the GC, which filters which pixels 
in the destination are drawn. 

For more information, see Volume One, Chapter 5, The Graphics Context. 

Errors 
BadAlloc 
BadGC 

Related Commands 
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, 
XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSet- 
FillRule, XSetFillStyle, XSetForeground, XSetBackground, XSet- 
Function, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClip- 
Rectangles, XSetState, XSetSubwindowMode, DefaultGC. 

402 July26 1988 



XSetCli p Recta ng les (continued) Xlib - Grap h ics Context 

To cancel the effect of this command, so that there is no clipping, pass None as the 
clip_mask in XChangeGC or XSetClipMask. 
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 
BadValue 

Incorrect ordering (error message sewer-dependent). 

Related Commands 
XChangeGC, XCopyGC, XCreateGC, XF reeGC, XGContextF romGC, XSet St ipple, 
XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSet- 
FillRule, XSetFillStyle, XSetForeground, XSetBackground, XSet- 
Function, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClip- 
Origin, XSetState, XSetSubwindowMode, DefaultGC. 

404 July 26, 1988 



mXlib - Client Connections 

X SetC I o se Down Mo de 

Name 
XSetCloseDownModechange eclosedown mode ofacfient. 
Synopsis 
XSetCloseDownMode(display, close mode) 
-- 
Display *display; 
int close mode; 
-- 

Arguments 
display 

Specifies a pointer to the Display structu; retumed om XOpen- 
Display. 

close mode 
-- 

Specifiestheclientclosedown mode you want. Passone of theseconsmnts: 
DestroyAll, RetainPermanent, orRetainTemporary. 

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 XKill- 
Client can be used to specify which client to kill, or it may be the constant All- 
Temporary, in which case XKillClient kills all resources of all clients that have ter- 
minated 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 

July 26, 1988 405 



XSetCommand 

Xlib - Window Manager Hints-- 

Name 
XSetCommand -- set the XA_WM_COMMAND atom (command line arguments). 

Synopsis 
XSetCommand ( display, 
Display *display; 
Window w; 
char **argv; 
int argc ; 

w, argv, argc) 

Arguments 
display 

argv 

a rgc 
Description 

Specifies a pointer to the Display sucture; returned from XOpenDisplay. 
Specifies the ID of the window whose atom is to be set. 
Specifies a pointer to the command and arguments used to start the application. 
The application is an army of pointers to null-terminated strings. 
Specifies the number of arguments. 

XSetCommand is used by the application to set the XA_WM_COMMAND property for the win- 
dow manager with the UNIX shell command and its arguments used to invoke the application. 

Use this command only if not calling xSet St anda rdP rope rt ie s. 

Errors 
BadAlloc 
BadWindow 

Related Commands 
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGet- 
WMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, 
XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetch- 
Name, XGetIconName, XSetIconName, XStoreName, XGetIconSizes, XSetIcon- 
Sizes. 

406 July 26, 1988 



XSetDashes (continued) Xlib - Graphics Context 

Description 
XSetDashes sets the dashes member of the GC. The initial and alternating elements of 
the dash_list are the dashes, the others are the gaps. All of the elements must be nonzero. 
The dash_offset 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. 
The unit of measure for dashes is the same as in the ordinary coordinate system. 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 
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, 
XSetTSOrigin, XSetPlaneMask, XSetLineAttributes, XSetFillRule, XSet- 
FillStyle, XSetForeground, XSetBackground, XSetFunction, XSet- 
GraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSet- 
ClipRectangles, XSetState, XSetSubwindowMode, DefaultGC. 

408 July 26, 1988 



mXlib - Error Handling 

XSetErrorHandler 

Name 
XSetErrorHandler -- set a nonfatal error event handler. 

Synopsis 
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. It 
is acceptable for this procedure to return, though the default handler simply prints a message 
and exits. However, the error handler should NOT perform any operations (directly or 
indirectly) on the Display. 
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 roufne wod 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 BadNarae errors from OpenFont, LookupColor, 
AllocNamedColor, protocol requests, on BadFont errors from a QueryFont protocol 
request, or on BadAlloc or BadAccess errors. These errors are all indicated by a 0 return 
value in the corresponding Xlib routines, and can be caught and handled by the application. 
Use XIOErrorHandler to to provide a handler for fatal errors. 
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>. 

Xlib Reference Manual 409 



XSetErrorHandler (continued) Xlib- Error Handling 

For more information, see Volume One, Chapter 3, Basic Window Program. 

Structures 
typedef struct { 
int type 
Display *display; 
unsigned long serial; 
char error code; 
-- 
char request_code; 
char minor code; 
-- 
XID resourceid; 
} XErrorEvent ; 

/* display the event was read from */ 
/* serial number of failed request */ 
/* error code of failed request */ 
/* major opcode of failed request */ 
/* minor opcode of failed request */ 
/* resource ID */ 

Related Commands 
XDisplayName, XGetErrorDatabaseText, XGetErrorText, XSetIOError- 
Handler, XSynchronize, XSetAfterFunction. 

410 July 26, 1988 



--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 
di spl ay 

gc 
fill rule 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the graphics context. 
Specifies the fill rule you want to set for the specified graphics context. Pos- 
sible values are EvenOddRule or WindingRule. 

Description 
XSetFillRule sets the fill rule member 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 arbiary 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. 

EvenOddRule 

Outline of polygon 
to fill 

WindingRule 

July 26, 1988 411 



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 
BadAlloc 
BadGC 
BadValue 

Related Commands 
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, 
XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSet- 
FillStyle, XSetForeground, XSetBackground, XSetFunction, XSet- 
GraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSet- 
ClipRectangles, XSetState, XSetSubwindowMode, DefaultGC. 

412 July 26, 1988 



XSetFillStyle (continued) Xlib - Grap h ics Context 

Errors 
BadAlloc 
BadGC 
BadValue 

Related Commands 
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, 
XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSet- 
FillRule, XSetForeground, XSetBackground, XSetFunction, XSetGraphics- 
Exposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClip- 
Rectangles, XSetState, XSetSubwindowMode, DefaultGC. 

414 July 26, 1988 



mXlib- Fonts 

XSetFont 

Name 
XSetFont B set the current font in a graphics contexL 
Synopsis 
XSetFont (display, gc, font) 
Display *display; 
GC gc ; 
Font font ; 

Arguments 
display 

gc 
fon t 

Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the graphics context. 
Specifies the ID of the font to be used. 

XSetFont sets the font in the GC. Text drawing requests using this GC will use this font 
only if it is loaded. Otherwise, the text will not be drawn. 
For more information, see Volume One, Chapter 5, The Graphics Context. 
Errors 
BadAlloc 
BadFont 
BadGC 

Related Commands 
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts, 
XListFontsWithInfo, XFreeFontNames, XFreeFontPath, XGetFontPath, 
XQueryFont, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFont- 
Cursor. 

July 26, 1988 415 



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 pointer to the Display structure; returned from XOpen- 
Display. 
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. 
ndirs 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. 
As a side-effect of executing this request, the server is guaranteed to flush all cached informa- 
tion about fonts for which there are currently no explicit resource IDs allocated. The meaning 
of errors from this request is system specific. 

E rro rs 
BadValue 

Related Commands 
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts, 
XListFontsWithInfo, XFreeFontNames, XFreeFontPath, XGetFontPath, 
XQueryFont, XSetFont, XUnloadFont, XGetFontProperty, XCreateFont- 
Cursor. 

416 July 26, 1988 



mXlib - Graphics Context 

XSetForeground 

Name 
XSeogroundmsetthe groundpixelvaluein a graphicscontext. 
Synopsis 
XSetForeground(display, gc, foreground) 
Display *display; 
GC gc; 
unsigned long foreground; 

Arguments 
display 

gc 
foreground 

Specifies a pointer to e Display sucture; returned from XOpen- 
Display. 
Specifies the graphics context. 
Specifies the foreground pixel value you want for the specified graphics con- 
text. 

Description 
XSetForeground sets the foreground member in a GC. This pixel value is used for sct 
bits in the source according to the fill_style. 
See Volume One, Chapter 5, The Graphics Context, for more information on the GC. 

Errors 
BadAlloc 
BadGC 

Related Commands 
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, 
XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSet- 
FillRule, XSetFillStyle, XSetBackground, XSetFunction, XSetGraphics- 
Exposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClip- 
Rectangles, XSetState, XSetSubwindowMode, DefaultGC. 

July 26, 1988 417 



Xlib - Graphics Context (continued) XSetFunction 

Errors 
BadAlloc 
BadGC 
BadValue 

Related Commands 
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, 
XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSet- 
FillRule, XSetFillStyle, XSetForeground, XSetBackground, XSet- 
GraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSet- 
ClipRectangles, XSetState, XSetSubwindowMode, DefaultGC. 

July 26, 1988 419 



XSetGraphicsExposures 

Xlib - Graphics Context-- 

Name 
XSetGraphicsExposures m set 9 r aphic s_expo s u re s in a graphics context. 
Synopsis 
XSetGraphicsExposures (display, go, graphics_exposures) 
Display *display; 
GC gc ; 
Bool graphics_exposures ; 

Arguments 
display 

gc 

Specifies a pointer to the Display structure; returned from XOpenDisplay. 
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 the GC. If 
graphics_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 
satisfied. If graphics_exposures is False, these events are not generated. 
These events are not selected in the normal way with XSelectTnput. Setting the 
9raphics_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 
BadAlloc 
BadGC 
BadValue 

Related Commands 
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, 
XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSet- 
FillRule, XSetFillStyle, XSetForeground, XSetBackground, XSet- 
Function, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClip- 
Rectangles, XSetState, XSetSubwindowMode, DefaultGC. 

420 July 26, 1988 



mXlib - Window Manager Hints 

XSetlconName 

Name 
XSetIconName m set the name to be displayed in a window's icon. 

Synopsis 
XSetIconName(display, 
Display *display; 
Window w; 
char *icon name; 
-- 

w, icon name) 
-- 

Arguments 
display 

W 
icon name 

Specifies a pointer to the Display structu'e; returned from XOpen- 
Display. 
Specifies the ID of the window whose icon name is being set. 
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 
XGet I c onName. 

Description 
XSetIconName 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 also sets this property. 

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

Errors 
BadAlloc 
BadWindow 

Related Commands 
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGet- 
WMHiAts, XSetWMHintsXGetZoomHints, XSetZoomHints, XGetNormalHints, 
XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetch- 
Name, XGetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSet- 
Command. 

July 26, 1988 421 



XSetlconSizes 

Xlib - Window Manager Hints m 

Name 
XSetlconSizes -- set the value of the XA WM ICON_SIZE property. 

Synopsis 
XSetIconSizes (display, w, 
Display *display; 
Window w; 
XIconSize *size list; 
int count ; 

size list, count) 

Arguments 
display 

size list 
-- 
count 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the ID of the window whose icon size property is to be set. Nor- 
mally the root window. 
Specifies a pointer to the size list. 
Specifies the number of items in the size list. 

XSetIconSizes is normally used by a window manager to set the range of preferred icon 
sizes in the XA_e_TCON_S T ZE property of the root window. 

Applications can then read the property with XGetIconSizes. 

Structures 
typedef struct { 
int min_width, min_height; 
int max_width, max_height; 
int width_inc, height_inc; 
} XIconSize; 

E rro rs 
BaclAIIoc 
BadWindow 

Related Commands 
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGet- 
WMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, 
XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetch- 
Name, XGetIconName, XSetIconName, XStoreName, XGeticonSizes, XSet- 
Command. 

422 July 26, 1988 



XSetlnputFocus (continued) Xlib - Input Handling 

If the focus window later becomes not viewable, XSetInputFocus 
revert to argument to determine the new focus window: 

evaluates the 

If you assign RevertToParent, the focus reverts to the parent (or the closest view- 
able ancestor) automatically with a new revert_to argument of RevertToName. 
If you assign RevertToPointerRoot or RevertToNone, the focus reverts to that 
value automatically. FocusIn and FocusOut events are generated when the focus 
reverts, but the last_focus_change_t ime is not affected. 

Errors 
BadMatch 
BadValue 
BadWindow 

focus window not viewable when xSet InputFocus called. 

Related Commands 
XSelectInput, XGetInputFocus, XWindowEvent, XCheckWindowEvent, 
XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMask- 
Event, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, 
XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, 
XPending, XSynchronize, XSendEvent, QLength. 

424 July26, 1988 



mXlib - Error Handling 

XSetlOErrorHandler 

Name 
XSetIOErrorHandler- handle fatal I/0 errors. 

Synopsis 
XSet IOErrorHandler (handler) 
int (*handler) (Display *) ; 

Arguments 
handler Specifies a pointer to a user-defined fatal error handling routine. If NULL, 
reinvoke the default fatal error handler. 
Description 
XSetIOErrorHandler 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 reinvoked. The default I/O error 
handler prints an error message and exits. 
For more information, see Volume One, Chapter 3, Basic Window Program. 

Related Commands 
XDisplayName, XGetErrorDatabaseText, XGetErrorText, XSetError- 
Handler, XSynchronize, XSetAfterFunction. 

July 26, 1988 425 



Xlib - Graphics Context (continued) XSetLineAttributes 

line width 
-- 

line_style 

cap_style 

join_style 

Specifies the line width you want to set for the specified graphics context. 
Specifies the line style you want to set for the specified graphics context. 
Possible values are LineSolid, LineOnOffDash, or LineDouble- 
Dash. 
Specifies the line and cap style you want to set for the specified graphics 
context. Possible values are CapNotLast, CapButt, CapRound, or 
CapPro jecting. 
Specifies the line-join style you want to set for the specified graphics con- 
text. Possible values are JoinMiter, JoinRound, or JoinBevel. 

Description 
XSetLineAttributes se 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 1 or more. 

Errors 
BadGC 
BadValue 

Related Commands 
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, 
XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetFillRule, XSetFillStyle, 
XSetForeground, XSetBackground, XSetFunction, XSetGraphicsExposures, 
XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSet- 
State, XSetSubwindowMode, DefaultGC. 

July 26, 1988 427 



XSetModifierMapping 

Xlib - Keyboard 

Name 
XSetModifierMapping -- set keycodes to be used as modifiers (Shift, Control, etc.). 
Synopsis 
int XSetModifierMapping ( display, mod_map) 
Display *display; 
XModifierKeymap *mod_map ; 

Arguments 
display Specifies a pointer to the Display structure; returned from XOpenDisplay. 
mod_map Specifies a pointer to the XModifierKeymap structure. 
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- 
ModifiermapEntry and XDeleteModifiermapEntry, 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 XModifierKeymap struc- 
ture pointed to by mod_map. This requires you to know how the XModifierKeymap struc- 
ture is defined and organized, as described in the next three paragraphs. 
The XModifierKeymap structure for the rood_map argument should be created using 
XNewModifierMap or XGetModifierMapping. 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 modifiermap 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 
modifier. 
The eight modifiers are represented by the constants ShiftMapIndex, LockMapIndex, 
ControlMapIndex, ModlMapIndex, ModlMapIndex, Mod3MapIndex, Mod4Map- 
Index, and Mod5MapIndex. These are not actually used as arguments, but they are con- 
venient for referring to each row in the modifiermap structure while filling it. The 
definitions of these constants are shown in the Structures section below. 
Now you can interpret the modifiermap array. For each modifier in a given modifier- 
map, the keycodes which correspond are from modifiermap [index * 
max_keypermod] to modifiermap[ [ (index + i) * max_keyspermod] -i] 
where index is the appropriate modifier index definition (ShiftMapIndex, LockMap- 
Index, etc.). You must set the rood_map array up properly before calling XSetModifier- 
Mapping. Now you know why XInsertModifierMapEntry and XDelete- 
ModifierMapEntry were created! 
Zero keycodes are ignored. No keycode may appear twice anywhere in the map (otherwise, a 
BadVa lue error is generated). In addition, all of the nonzero keycodes must be in the range 

428 Xhb 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 reslrictions on how modifiers can be changed. For example, certain keys 
may not generate up transitions in hardware, or multiple modifier keys may not be supported. 
If a restriction is violated, then the status reply is MappingFailed, and none of the 
modifiers are changed. 
If the new keycodes specified for a modifier differ from those currently defined and any 
(current or new) keys for that modifier are in the down state, then the status reply is 
MappingBusy, and none of the modifiers are changed. 
XSetModifierMapping generates a MappingNotify event on a MappingSuccess 
status. 
A value of 0 for raodifiermap indicates that no keys are valid as any modifier. 

Structures 
typedef struct { 
int max_keypermod; 
KeyCode *modifiermap; 
} XModifierKeymap; 

/* server's max # of keys per modifier */ 
/* an 8 by max_keypermod array */ 

/* modifier names. Used to build a SetModifierMapping request or 
to read a GetModifierMapping request. These correspond to the 
masks defined above. */ 

#define ShiftMapIndex 0 
#define LockMapIndex 1 
#define ControlMapIndex 2 
#define ModlMapIndex 3 
#define Mod2MapIndex 4 
#define Mod3MapIndex 5 
#define Mod4MapIndex 6 
#define Mod5MapIndex 7 

Errors 
BadAlloc 
BadValue 

Keycode appears twice  the map. 
Keycode < display->min_keycode or 
keycode > displ ay->max_keycode. 

Related Commands 
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, 
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifier- 
Map, XQueryKeymap, XStringToKeysyn%XLookupKeysym, XRebindKeysym, 
XGetKeyboardMapping, XChangeKeyboardMapping, XRefreshKeyboard- 
Mapping, XLookupString, XGetModifierMapping, XInsertModifiermap- 
Entry, XDeleteModifiermapEntry. 

July 26, 1988 429 



XSetNormalHints 

Xlib - Window Manager Hints-- 

Name 
XSetNormalHints -- set the size hints property of a window in normal state (not zoomed or 
iconified). 

Synopsis 
void XSetNormalHints(display, 
Display *display; 
Window w; 
XSizeHints *hints; 

w, hints) 

Arguments 
display 

w 
hints 
Description 

Specifies a pointer to the Display structure; returned from X0pen- 
Display. 
Specifies the window ID. 
Specifies a pointer to the sizing hints for the window in its normal state. 

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 win- 
dow configuration requests, but ignore the resulting events and pay attention to property 
changes instead. 

To set size hints, an application must not only assign values to the appropriate elements in the 
hints structure, but also must 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 10, Interclient Communica- 
tion. 

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; 
st ruct { 
int x; /* numerator */ 
int y; /* denominator */ 
} rain_aspect, max_aspect ; 
} XSizeHints; 

430 July 26, 1988 



Xlib - Window Manager Hints (continued) XSetNormalHints 

/* flag argument in size hints */ 
#define USPosition (IL << 0) /* user specified x, y */ 
#define USSize (IL << I) /* user specified width, height */ 

#define PPosition (IL << 2) /* program specified 
#define PSize (IL << 3) /* program specified 
#define PMinSize (IL << 4) /* program specified 
#define PMaxSize (IL << 5) /* program specified 
#define PResizeInc (IL << 6) /* program specified 
#define PAspect (IL << 7) /* program specified 
#define PAllHints 

position */ 
size */ 
minimum size */ 
maximum size */ 
resize increments */ 
min/max aspect ratios */ 
(PPositionlPSizelPMinSizelPMaxSizelPResizeInclPAspect) 

Errors 
BadAlloc 
BadWindow 

Reled Commands 
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGet- 
WMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, 
XGetTransientForHint, XSetTransientForHint, XFetchName, XGetIcon- 
Name, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSet- 
Command. 

July 26, 1988 431 



XSetPlaneMask 

Xlib - Graphics Context m 

Name 
XSelaneMaskmsettheplane maskinagraphicsconxt. 
Synopsis 
XSetPlaneMask(display, gc, plane_mask) 
Display *display; 
GC gc; 
unsigned long plane_mask; 

Arguments 
display 

go 
plane_mask 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the graphics context. 
Specifies the plane mask. You can use the macro AllPlanes if desired. 

Description 
XSetPlaneMask se the plane_mask member 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 
BadAlloc 
BadGC 

Relined Commands 
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, 
XSetTSOrigin, XSetDashes, XSetLineAttributes, XSetFillRule, XSetFill- 
Style, XSetForeground, XSetBackground, XSetFunction, XSetGraphics- 
Exposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClip- 
Rectangles, XSetState, XSetSubwindowMode, DefaultGC. 

432 July26, 1988 



mXlib- Pointer 

XSetPointerMapping 

Name 
XSetPointerMapping -- set the pointer button mapping. 

Synopsis 
int XSetPointerMapping(display, map, nmap) 
Display *display; 
unsigned char map[]; 
int nmap; 

Arguments 
display 

map 
nmap 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the mapping list. 
Specifies the number of items in the mapping list. 

XSetPointerMapping se the mapping of the pointer. Elemen of the map list are 
indexed starting from 1. The length of the list nmap must be the same as XGetPointer- 
Mapping returns (you must call that first). The index is a physical button number, and the 
element 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 
ButtonlMask 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. A value of 0 for an element of map dis- 
ables 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 status reply is 
MappingBusy and the mapping is not changed. 
This function returns either MappingSuccess or MappingBusy. XSetPointer- 
Mapping generates a MappingNotify event on a status of MappingSuccess. 

Errors 
BadValue 

Two elemems of map [ ] have same nonzero value. 
nmap not equal to XGetPointerMapping return value. 

Related Commands 
XQueryPointer, XWarpPointer, XGrabPointer, XChangeActivePointerGrab, 
XUngrabPointer, XGetPointerMapping, XGetPointerControl, XChange- 
PointerControl. 

July 26, 1988 433 



XSetRegion 

Xlib - Regions-- 

Name 
XSetRegion -- set c i ip_ma s k of the graphics context to the specified region. 
Synopsis 
XSetRegion ( display, gc, r) 
Display *display; 
GC gc ; 
Region r; 

Arguments 
display 

gc 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the graphics context. 
Specifies the region. 

Description 
XSetRegion sets the clip_mask of the GC to the specified region. Thereafter, all output 
requests made with gc will be confined to 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. 
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 (xoffset + 
clip x origin, yoffset + clip_y_origin), where xoffset and yoffset 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 
/. 
* opaque reference to Regiondata type. 
* user won't need contents, only pointer. 
*/ 
typedef struct _XRegion *Region; 

Related Commands 
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion, 
XShrinkRegion, XRectInRegion, XPolygonRegion, XPointInRegion, 
XOffsetRegion, XIntersectRegion, XEmptyRegion, XCreateRegion, 
XDestroyRegion, XEqualRegion, XClipBox. 

434 July 26, 1988 



XSetScreenSaver (continued) Xlib - Screen Saver 

Errors 
BadValue timeout <-|. 

Related Commands 
XForceScreenSaver, XActivateScreenSaver, XResetScreenSaver, XGet- 
ScreenSaver. 

436 July 26, 1988 



--Xlib - Selections 

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 

selection 

owner 

time 

Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the selection atom. Predefined atoms are XA PRIMARY and 
XA SECONDARY. 
Specifies the present owner of the specified selection atom. This value is 
either a window ID or None. 
Specifies the time when the grab should take place. Pass either a timesmmp, 
expressed in milliseconds, or the constant CurrentTime. 

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 SelectionRequest 
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 
selection 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 the new owner of the selection is None. Otherwise, the 
new offner 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 SelectionClear event. This indicates to 
that window 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 CurrentTirne replaced by the current 
server time. If the X server reverts a selection owner to None, the last-change time is not 
affected. 

July 26, 1988 437 



XSetSelectionOwner (continued) Xlib - Selections 

For more information on selections, see Volume One, Chapter 10, lnterclient Communication. 

Errors 
BadAtom 
BadWindow 

Related Commands 
XGet Select ionOwne r, XConve rt Select ion. 

438 July 26, 1988 



XSetSizeHints (continued) Xlib - Window Manager Hints 

#define PSize (IL << 3)/* program specified size */ 
#define PMinSize (IL << 4)/* program specified minimum size */ 
#define PMaxSize (IL << 5)/* program specified maximum size */ 
#define PResizeInc (IL << 6)/* program specified resize increments */ 
#define PAspect (IL << 7)/* program specified min/max aspect ratios */ 
#define PAllHints (PPositionlPSizelPMinSizelPMaxSizelPResizeInclPAspect) 

Errors 
BadAlloc 
BadAtom 
BadWindow 

Related Commands 
XGetClassHint, XSetClassHint, XGetSizeHints, XGetWMHints, XSet- 
WMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, XSetNormal- 
Hints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGet- 
IconName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, 
XSetCommand. 

440 July 26, 1988 



XSetStandardColormap (continued) Xlib - Colormaps 

Errors 
BadAlloc 
BadAtom 
BadWindow 

Structures 
typedef struct { 
Colormap colormap; 
unslgned long red max; 
-- 
unslgned long red mult; 
-- 
unslgned 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 */ 

Related Commands 
XCopyColormapAndFree, XCreateColormap, XFreeColormap, XGetStandard- 
Colormap, XInstallColormap, XUninstallColormap, XListInstalled- 
Colormaps, XSetWindowColormap, DefaultColormap, DisplayCells. 

442 July 26, 1988 



XSetStandardProperties (continued) Xlib- Properties 

int x; /* numerator */ 
int y; /* denominator */ 
} min_aspect, max_aspect; 
} XSizeHints; 

/* flags argument in size hints */ 
#define USPosition (IL << 0)/* user specified x, y */ 
#define USSize (IL << I)/* 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 PResizeInc (IL << 6)/* program specified resize increments */ 
#define PAspect (IL << 7)/* program specified min and max aspect ratios */ 
#define PAllHints (PPositionlPSizelPMinSizelPMaxSizelPResizeInclPAspect) 

Errors 
BadAlloc 
BadWindow 

Related Commands 
XGetFontProperty, XRotateWindowProperties, XDeleteProperty, XChange- 
Property, XGetWindowProperty, XListProperties, XGetAtomName, XIntern- 
Atom. 

444 July 26, 1988 



XSetStipple k 

Xlib - Graphics Context-- 

Name 
XSetStipple -- set the stipple in a graphics context. 
Synopsis 
XSetStipple (display, gc, stipple) 
Display *display; 
GC gc ; 
P ixmap stipple; 

Arguments 
display 
gc 
stipple 

Specifies a pointer to the Display sucture; returned from XOpenDisplay. 
Specifies the graphics context. 
Specifies the stipple you want to set for the specified graphics context. 

Description 
xsetstipple sets the stipple member of the GC. The stipple is a pixmap of depth 
1. 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 fill_style is FillTiled or FillSolid, the stipple is not used. 
For more information, see Volume One, Chapter 5, The Graphics Context. 

Errors 
BadAlloc 
BadGC 
BadMatch 
BadP ixmap 

Related Commands 
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetTSOrigin, 
XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillRule, XSet- 
FillStyle, XSetForeground, XSetBackground, XSetFunction, XSet- 
GraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSet- 
ClipRectangles, XSetState, XSetSubwindowMode, DefaultGC. 

446 July 26, 1988 



--Xlib - Graphics Context 

X SetSu bwi ndow Mode 

Name 
XSetSubwindowMode -- set the subwindow mode in a graphics context. 
Synopsis 
XSetSubwindowMode ( display, gc, subwindow mode) 
Display *display; 
GC gc; 
int subwindow mode ; 

Arguments 
di spl ay 

Specifies a pointer to the Display structure; 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 IncludeInferiors. 

Description 
XSetSubwindowMode sets the subwindow mode member of the GC. Clip- 
ByChildren means that graphics requests will be clipped by all viewable children. 
IncludeInferiors means draw through all subwindows. 

For more information, see Volume One, Chapter 5, The Graphics Context. 

Errors 
BadAlloc 
BadGC 
BadValue 

Related Commands 
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, 
XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSet- 
FillRule, XSetFillStyle, XSetForeground, XSetBackground, XSet- 
Functlon, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClip- 
Origin, XSetClipRectangles, XSetState, DefaultGC. 

July 26, 1988 44 7 



XSetTile 

Xlib - Pixmaps and Tiles-- 

Name 
XSetTile -- set the fill tile in a graphics context. 
Synopsis 
XSetTile (display, gc, tile) 
Display *display; 
GC gc; 
Pixmap tile ; 

Arguments 
display 
gc 
tile 

Specifics a pointer to the Display sUmcturc; returned from XOpenDisplay. 
Specifies the graphics context. 
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 pix- 
map used to tile areas. The tile must have the same depth as the destination drawable. 
For more information, see Volume One, Chapter 5, The Graphics Context. 
Errors 
BadAlloc 
BadGC 
BadMatch 
BadP ixmap 

Related Commands 
XQueryBestTile, XSetWindowBorderPixmap, XSetWindowBackgroundPixmap, 
XCreatePixmap, XCreatePixmapFromBitmapData, XFreePixmap, XQueryBest- 
Size, XQueryBestStipple, XWriteBitmapFile, XReadBitmapFile, XCreate- 
BitmapFromData. 

448 July 26, 1988 



--Xlib - Window Attributes 

XSetWindowBackground 

Name 
XSetWindowBackground--tthebackgroundpixelatbuteofa window. 
Synopsis 
XSetWindowBackground(display, w, background_pixel) 
Display *display; 
Window w; 
unsigned long background_pixel; 

Arguments 
display Specifies a pointer to the Display structure; 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. 

Description 
XSetWindowBackground sets the background attribute of a window, setting the pixel 
value to be used to fill the background. The current window contents are not changed. The 
background is automatically repainted after Expose events, in the area affected by the expo- 
sure. 
When XSetWindowBackground and XSetWindowBackgroundPixmap are both used 
on a window, whichever is called last will control the current background. Trying to change 
the background of an rnputOnly window will generate a BadHatch error. 
For more information, see Volume One, Chapter 4, Window Attributes. 

Errors 
BadMatch 
BadWindow 

Related Commands 
XGetWindowAttributes, XChangeWindowAttributes, XSetWindow- 
BackgroundPixmap, XSetWindowBorder, XSetWindowBorderPixmap, XGet- 
Geometry. 

July 26, 1988 451 



XSetWindowBorderPixmap 

Xlib - Pixmaps and Tiles-- 

Name 
XSetWindowBorderPixmap -- change a window border tile atlibute and repaint the border. 
Synopsis 
XSetWindowBorderPixmap (display, w, border tile) 
-- 
Display *display; 
Window w; 
Pixmap border tile; 
-- 

Arguments 
display 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 

Specifies the ID of an InputOutput window whose border is to be 
changed. 

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 TnputOutput window. 

Errors 
BadMatch 
BadPixmap 
BadWindow 

Related Commands 
XSetTile, XQueryBestTile, XSetWindowBackgroundPixmap, XCreatePixmap, 
XCreatePixmapFromBitmapData, XFreePixmap, XQueryBestSize, XQuery- 
BestStipple, XWriteBitmapFile, XReadBitmapFile, XCreateBitmapFrom- 
Data. 

454 

July 26, 1988 



mXlib - Window Manipulation 

XSetWindowBorderWidth 

Name 
XSetWindowBorderWidth -- change the border width of a window. 
Synopsis 
XSetWindowBorderWidth (display, w, width) 
Display *display; 
Window w; 
unsigned int width; 

Arguments 
display 
w 
width 

Specifies a poinr to the Display sucture; returned from XOpenDisplay. 
Specifies the ID of the window whose border is to be changed. 
Specifies the width of the window border. 

Description 
XSetWindowBorderWidth changes the border width of a window. This request is often 
used by the window manager as an indication of the current input focus window, so other 
clients should not change it. 

Errors 
BadWindow 

Related Commands 
XLowerWindow, XRaiseWindow, XCirculateSubwindows, XCirculate- 
SubwindowsDown, XCirculateSubwindowsUp, XRestackWindows, XMove- 
Window, XResizeWindow, XMoveResizeWindow, XReparentWindow, 
XConfigureWindow, XQueryTree. 

July 26, 1988 455 



XSetWindowColormap 

Xlib - Window Attributes-- 

Name 
XSetWindowColormap m set the colormap for a specified window. 
Synopsis 
XSetWindowColormap (display, w, cmap ) 
Display *display; 
Window w; 
Colormap cmap ; 

Arguments 
di spl ay 

cmap 

Specifies a pointer to the Display structure; returned from XOpenDisplay. 
Specifies the ID of the window for which you want to set the colormap. 
Specifies the colormap. 

Description 
XSetWindowColorrnap sets the colorrnap 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. 

Eventually, window managers will install and uninstall the proper colormaps according to this 
attribute and the pointer position or some other convention. For now, applications Rust install 
their own colormaps if they cannot use the default colormap. 
The colormap must have the same visual as the window. 

Errors 
BadColor 
BaclMatch 
BadWindow 

Related Commands 
XGetWindowAttributes, XChangeWindowAttributes, XSetWindow- 
Background, XSetWindowBackgroundPixmap, XSetWindowBorder, XSet- 
WindowBorderPixmap, XGetGeometry. 

456 July 26, 1988 



--Xlib - Window Manager Hints 

XSetWMHints 

Name 
XSetWMHints m set a window manager hints property. 

Synopsis 
XSetWMHints (display, w, 
Display *display; 
Window w; 
XWMHint s *wmhints; 
Arguments 
display 
w 
wmhi n t s 
Description 

wmhint s ) 

Specifies a pointer to the Display structure; returned from XOpenDisplay. 
Specifies the ID for which window manager hints are to be set. 
Specifies a pointer to the window manager hints. 

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 gct 
keyboard input. See Volume One, Chapter 10, Interclient Communication, for a description of 
each XWMHint s structure member. 

Structures 
typedef struct { 
long flags; 
Bool input; 

int initial state; 
_ 
Pixmap icon_pixmap; 
Window icon window; 
_ 
int icon_x, icon_y; 
Pixmap icon mask; 
_ 
XID window_group; 

/* marks defined fields in structure */ 
/* does application need window manager for 
* keyboard input */ 
/* see below */ 
/* pixmap to be used as icon */ 
/* window to be used as icon */ 
/* initial position of icon */ 
/* icon mask bitmap */ 
/* ID of related window group */ 

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

/* definitions for the flags field: */ 

#define InputHint 
#define StateHint 
#define IconPixmapHint 
#define IconWindowHint 
#define IconPositionHint 
#define IconMaskHint 
#define WindowGroupHint 

(IL << 0) 
(IL << I) 
(IL << 2) 
(IL << 3) 
(IL << 4) 
(IL << 5) 
(IL << 6) 

#define AllHints (InputHintlStateHintlIconPixmapHintIIconWindowHintl \ 
IconPositionHintIIconMaskHintlWindowGroupHint) 

July 26, 1988 457 



XSetWMHints (continued) Xlib - Window Manager Hints 

/* definitions for the initial state flag: */ 
#define DontCareState 0 /* don't know or care */ 
#define NormalState 1 /* most applications want to start this way */ 
#define ZoomState 2 /* application wants to start zoomed */ 
#define IconicState 3 /* application wants to start as an icon */ 
#define InactiveState 4 /* application believes it is seldom used; 
some wm's may put it on inactive menu */ 

Errors 
BadAlloc 
BadWindow 

Related Commands 
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGet- 
WMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, XSetNormal- 
Hints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGet- 
IconName, XSetIconName, XStoreName, XGetIconSizes, XSeticonSizes, 
XSetCommand. 

458 July 26, 1988 



XSetZoom Hints (continued) Xlib - Window Manager Hints 

/* flags argument in size hints */ 
#define USPosition (IL << 0) /* user specified x, y */ 
#define USSize (IL << i) /* 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 PResizeInc (IL << 6) /* program specified resize increments */ 
#define PAspect (IL << 7) /* program specified min/max aspect ratios */ 
#define PAllHints (PPositionlPSizelPMinSizelPMaxSizeIPResizeInclPAspect) 
} XSizeHints; 

Errors 
BadAlloc 
BadWindow 

Related Commands 
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGet- 
WMHints, XSetWMHints, XGetZoomHints, XGetNormalHints, XSetNormal- 
Hints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGet- 
IconName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, 
XSetCommand. 

460 July 26, 1988 



XStoreBuffer 

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 

bytes 

nbytes 
buffer 

Specifies a pointer to the Display stcture; returned om XOpenDisplay. 
Specifies the string of bytes you want stored. The byte string is not necessarily 
ASCII or null-terminated. 
Specifies the number of bytes in the string. 
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 one of the eight cut buffers. All eight buffers 
must be stored into before they can be circulated with XRotateBuffers. The cut buffers 
are numbered 0 through 7. Use XFetchBuffer 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, Interclient Com- 
munication. 

Errors 
BadAlloc 
BadAtom 

Related Commands 
XStoreBytes, XFetchBuffer, XFetchBytes, XRotateBuffers. 

462 July 26, 1988 



--Xlib - Cut Buffers 

XStoreBytes 

Name 
XSmreBytes--storedam in cutbuffer0. 
Synopsis 
XStoreBytes(display, bytes, nbytes) 
Display *display; 
char bytes[]; 
int nbytes; 

Arguments 
display 

Specifies a pointer to the Display structure; 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 that you want stored. 
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 XStoreBuffer 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, Interclient Com- 
munication. 
Errors 
BadAlloc 
Related Commands 
XStQreBuffer, XFetchBuffer, XFetchBytes, XRotateBuffers. 

July 26, 1988 463 



XStoreColor 

Xlib - Color Cells-- 

Name 
XStoreColor -- set or change a read/write entry of a colormap to the closest available 
hardware color. 
Synopsis 
XStoreColor (display, cmap, colorcell def) 
-- 
Display *display; 
Colormap cmap ; 
XColor *colorcell def; 
Arguments 
di spl ay 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the colormap. 
Specifies a pixel value and the desired RGB values. 

cmap 
colorcell def 
-- 
Description 
XSt o reCo lor changes the RGB values of a colormap entry specified by 
colorcell_def.pixel to the closest values available on the hardware. This pixel value 
must be a read/write cell and a valid index into craap, 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. 

/* DoRed, DoGreen, DoBlue */ 

Structures 
typedef struct { 
unsigned long pixel; 
unsigned short red, green, blue; 
char flags; 
char pad; 
} XColor; 

Errors 
BadColor 
BadValue 

pixel not valid index into cmap. 

Related Commands 
XAllocColorCells, XAllocColorPlanes, XAllocColor, XAllocNamedColor, 
XLookupColor, XParseColor, XQueryColor, XQueryColors, XStoreColors, 
XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel. 

464 July 26, 1988 



mXlib - Window Manager Hints 

X Store NamedColo r 

Name 
XStoreNamedColor m allocate a read/write colorcell by English color name 
Synopsis 
XStoreNamedColor (display, cmap, colorname, pixel, flags) 
Display *display; 
Colormap cmap ; 
char *colorname; 
unsigned long pixel ; 
int flags ; 

Arguments 
display 
cmap 
colorname 

pixel 
fl a gs 
Description 

Specifies a pointer to the Display structure; returned from XOpenDisplay. 

Specifies the colormap. 

Specifies the color name string (for example, "red"). This cannot be in hex 
format (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 
character codes are ASCII, and the second 128 character codes are for special 
characters needed in western languages other than English. 
Specifies the entry in the colormap to store color in. 

Specifies which red, green, and blue indexes are set. 

XStoreNamedColor looks up the named color in the database, with respect to the screen 
associated with cmap, then stores the result in the cell 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 
Badccess 
BadColor 
BadName 
BadValue 

pixel is unallocated or read-only. 

pixel is not a valid index into cmap. 

Related Commands 
XCopyColormapAndFree, XCreateColormap, XFreeColormap, XGetStandard- 
ColormapXInstallColormap, XUninstallColormap, XSetStandard- 
Colormap, XListInstalledColormaps, XSetWindowColormap, Default- 
Colormap, DisplayCells. 

July 26, 1988 467 



XStringToKeysym 

Xlib - Keyboard-- 

Name 
XStringToKeysym m 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 
<X11/keysymdef.h>. If the specified string does not match a valid keysym, XString- 
ToKeysym retums NoSymbol. 

This string is not the string returned in the buffer argument of XLookupString, which 
can be set with XRebindKeysym. If that string is used, XStringToKeysym will return 
NoSymbol except by coincidence. 

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

Related Commands 
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, 
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifier- 
Map, XQueryKeymap, XLookupKeysym, XRebindKeysym, XGetKeyboardMapping, 
XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookupString, 
XSetModifierMapping, XGetModifierMapping. 

468 July 26, 1988 



--Xlib - Images 

XSublmage 

Name 
XSubImage -- create a subimage from part of an image. 

Synopsis 
XImage *XSubImage(ximage, x, y, subimage_width, 
subimage_height) 
XImage *ximage; 
int x; 
int y; 
unsigned int subimage_width; 
unsigned int subimage_height; 

Arguments 
ximage Specifies a pointer to the image. 
x Specify the x and y coordinates of the origin of the subimage. 
Y 
subimage_width 
s ubima ge_h ei gh t 
Specify the width and height (in pixels) of the new subimage. 

Description 
XSubImage creates a new image that is a subsection of an existing one. It allocates the 
memory necessary for the new >:Image 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 XGetSublmage extracts an image 
from a drawable. 
For more information on images, see Volume One, Chapter 6, Drawing Graph'cs and Text. 

Related Commands 
XDetroyImage, XPutlmage, XGetImage, XCreateImage, XGetSubImage, XAdd- 
Pixel, XPutPixel, XGetPixel, ImageByteOrder. 

July 26, 1988 469 



XSubtractRegion 

Xlib - Regions-- 

Name 
XSubacegion--subtractoneregion omanother. 
Synopsis 
XSubtractRegion(sra, srb, dr) 
Region sra, srb; 
Region dr; /* RETURN */ 

Arguments 

dr 

Specify the two regions in which you want to perform the computation. 

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 
/, 
* opaque reference to Regiondata type. 
* user won't need contents, only pointer. 
*/ 
typedef struct _XRegion *Region; 

Related Commands 
XXorRegion, XUnionRegion, XUnionRectWithRegion, XShrinkRegion, XSet- 
Region, XRectInRegion, XPolygonRegion, XPointinRegion, XOffsetRegion, 
XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroyRegion, 
XEqualRegion, XClipBox. 

470 

July26, 1988 



XTextExtents (continued) Xlib - Text 

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; /* 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; 

Related Commands 
XQueryTextExtents, XQueryTextExtentsl6, XDrawimageString, XDraw- 
ImageStringl6, XDrawString, XDrawStringl6, XDrawText, XDrawTextl6, 
XTextExtentsl6, XTextWidth, XTextWidthl6. 

474 

July 26, 1988 



mXlib - Text 

XTextExtentsl 6 

Name 
XTextExtentsl6 m get string and font metrics of a 16-bit character string. 
Synopsis 
XTextExtentsl6 (font struct, string, nchars, 
ascent, descent, overall) 
XFontStruct *font struct; 
-- 
XChar2b *string; 
int nchars ; 
int *direction; /* RETURN */ 
int *ascent, *descent; /* RETURN */ 
XCharStruct *overall; /* RETURN */ 

Arguments 
font struct 
string 

nchars 

direction 

ascent 

de s c en t 

overall 

direction, 

Specifies a pointer to the XFontSt ruct structure. 
Specifies the character string made up of XChar2 6 structures. 
Specifies the number of characters in the character string. 
Returns the value of the direction element of the XFontStruct. Font- 
RightToLeft of FontLeftToRight. 
Returns the font ascent element of the XFontStruct. This is the overall 
maximum ascent for the font. 

Returns the font descent element of the XFontStruct. This is the overall 
maximum descent for the font. 

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 lbearing added to the width of all characters up 
to the character with the smallest lbearing, and the maximum rbearing 
added to the width of all characters up to the character with the largest 
rbearing. 

Description 
XTextExtents16 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 XQueryTextExtent s 16, but it requires a filled xFontSt ruct. 

ascent and descent return information about the font, while overall returns informa- 
tion about the given string. The returned ascent and descent should usually be used to 
calculate the line spacing, while the width, rbearing, and lbearing 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, lbearing 

July 26, 1988 4 75 



XTextExtentsl 6 (continued) Xlib - Text 

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; /* per char flags (not predefined) */ 
} 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 */ 

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 { 
unsigned char bytel; 
unsigned char byte2; 
} XChar2b; 

/* normal 16 bit characters are two bytes */ 

Related Commands 
XQueryTextExtent s, XQueryTextExtent s 1 6, XDrawImageSt ring, XDraw- 
ImageSt ringl 6, XDrawSt ring, XDrawSt ringl 6, XDrawText, XDrawText 1 6, 
XTextExtents, XTextWidth, XTextWidthl 6. 

476 

July 26, 1988 



mXlib - Text 

XTextWidth 

Name 
XTextWidth m get the width in pixels of an 8-bit character string. 
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 string. 

Description 
XTextWidth 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 
eqivzlent to the vzlue of overall, width returned by XQueryTextExtents or XText- 
Extents. The characters in string are 8-bit characters. 

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 car; 
-- 
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 
XQueryTextExtents, XQueryTextExtentsl6, XDrawImageString, XDraw- 
ImageStringl6, XDrawString, XDrawStringl6, XDrawText, XDrawTextl6, 
XTextExtents, XTextExtentsl6, XTextWidthl6. 

July 26, 1988 477 



mXlib - Standard Geometry 

XTra ns lateCo o rd i n ates 

Name 
XTranslateCoordinates m change the coordinate system from one window to another. 
Synopsis 
Bool XTranslateCoordinates (display, src_w, dest_w, src_x, 
src_y, dest_x, dest_y, child) 
Display *display; 
Window src_w, dest_w; 
int src_x, src_y; 
int *dest_x, *dest_y; /* RETURN */ 
Window *child; /* RETURN */ 

Arguments 
di spl ay 
src w 
dest w 
src x 
src_y 
dest x 
dest_y 

child 

Description 

Specifies a pointer to the Display structure; returned from XOpenDisplay. 
Specifies the ID of the source window. 
Specifies the ID of the destination window. 
Specify the x and y coordinates within the source window. 

Return the translated x and y coordinates within the destination window. 

If the point is contained in a mapped child of the destination window, then that 
child ID is returned in chi2d. 

XTranslateCoordinates translates coordinates from the frame of reference of one win- 
dow to another. 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. 

XTranslateCoordinates returns False and *dest_x and *dest_y are set to 0 if 
src w and dest w are on different screens. In addition, if the coordinates are contained in 
a malSped child of dest_w, then that child is returned in the child argument. Otherwise, 
XTranslateCoordinates returns True, sets *dest_x and *dest_y to the location of 
the point relative to dest_w, and sets child to None. 
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 479 



XUndefineCursor 

Xlib - Cursors-- 

Name 
XUndefineCursor -- disassociate a cursor from a window. 
Synopsis 
XUndefineCursor (display, w) 
Display *display; 
Window w; 

Arguments 
di spl ay 

w 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 

Specifies the ID of the window whose cursor is to be undefined. 

XUndefineCursor sets the cursor for a window to its parent's cursor, undoing the effect of 
a previous XDefineCursor for this window. On the root window, with no cursor specified, 
the default cursor is restored. 

Errors 
BadWindow 

Related Commands 
XDefineCursor, XCreateFontCursor, XCreateGlyphCursor, XCreateixmap- 
Cursor, XFreeCursor, XRecolorCursor, XQueryBestCursor, XQueryBest- 
Size. 

480 

July 26, 1988 



wXlib - Grabbing 

XUngrabButton 

Name 
XUngrabButton -- release a button from grab. 
Synopsis 
XUngrabButton (display, button, modifiers, 
Display *display; 
unsigned int button; 
unsigned int modifiers; 
Window w; 

w) 

Arguments 
display 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
button Specifies the mouse button to be released from grab. Specify Buttonl, 
Button2, Button3, Button4, Button5, or the cons[ant 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, Mod3Mask, Mod4Mask, Mod5Mask, or AnyModifier. 
AnyModifier is equivalent to issuing the ungrab button request for all 
possible 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 
buttons. This call has no effect on an active grab. 
For more information, see Volume One, Chapter 9, The Keyboard and Pointer. 
Errors 
BadWindow 

Related Commands 
XGrabKey, XUngrabKey, XGrabKeyboard, XUngrabKeyboard, XGrabButton, 
XGrabPointer, XUngrabPointer, XChangeActivePointerGrab, XGrabServer, 
XUngrabServer. 

July 26, 1988 481 



XUngrabKey 

Xlib - Grabbing-- 

Name 
XUngrabKey m release a key from grab. 
Synopsis 
XUngrabKey (display, keycode, modifiers, 
Display *display; 
int keycode ; 
unsigned int modifiers; 
Window w; 

w) 

Arguments 
di splay 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
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, Mod3Mask, Mod4Mask, Mod5Mask, or AnyModifier. 
AnyModifier is equivalent to issuing the ungrab key request for all possi- 
ble 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 

Related Commands 
XGrabKey, XGrabKeyboard, XUngrabKeyboard, XGrabButton, XUngrabButton, 
XGrabPointer, XUngrabPointer, XChangeActivePointerGrab, XGrabServer, 
XUngrabServer. 

482 July 26, 1988 



XUninstallColormap 

Xlib - Colormaps 

Name 
XUninsmllColormap--uninsmHacolormap;installdeultifnotaeadyinstalled. 
Synopsis 
XUninstallColormap(display, cmap) 
Display *display; 
Colormap cmap; 

Arguments 
display 

cmap 
Description 

Specifies a pointer m the Display sucture; remed om XOpen- 
Display. 

Specifies the colormap to be uninstalled. 

If cmap is an installed map for its screen, it is uninstalled. If the screen's default colormap is 
not installed, it is installed. 
If cmap is an installed map, a ColorraapNotify event is generated on every window hav- 
ing this colormap as an attribute. If a colormap is installed as a result of the uninstall, a 
ColorraapNot i fy 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 rain raaps specified for each 
screen in the Display structure. When a colormap is installed w-h XInstallColorraap 
it is added to the head of the required list and the last colormap in the list is removed if neces- 
sary to keep the length of the list at rain__maps. When a colormap is uninstalled with 
xuninstallColorraap 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, rain_maps is likely to be 1. 
For more information on installing and uninstalling colormaps, see Volume One, Chapter 7, 
Color. 

Related Commands 
XCopyColorraapAndFree, XCreateColormap, XFreeColormap, XGetStandard- 
Colormap, XInstallColormap, XSetStandardColormap, XListinstalled- 
Colormaps, XSetWindowColormap, DefaultColormap, DisplayCells. 

486 



mXlib - Resource Manager 

XUnion RectWith Region 

Name 
XUnionRectWithRegion -- add a rectangle to a region. 

Synopsis 
XUnionRectWithRegion (rectangle, src_region, dest_region) 
XRectangle *rectangle ; 
Region src_region ; 
Region dest_region ; 
Arguments 
rectangle Specifies the rectangle to add to the region. 
src__region 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 
specified in 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; 
The Region type is a pointer to an opaque data type. Its definition is not needed by pro- 
grams. 

Related Commands 
XClipBox, XDestroyRegion, XEmptyRegion, XEqualRegion, XIntersect- 
Region, XOffsetRegion, XPointInRegion, XPolygonRegion, XRectInRegion, 
XSetRegion, XShrinkRegion, XSubtractRegion, XUnionRegion, XXorRegion. 

Juy 26. e88 4az 



XUnionRegion 

Xlib - Regions m 

Name 
XUnionRegion m compute the union of two regions. 
Synopsis 
XUnionRegion (sra, srb, dr) 
Region sra , srb ; 
Region dr; 

Arguments 

dr 

Specify the two regions in which you want to perform the computation. 

Returns the result of the computation. 

Description 
XUnionRegion computes the union of two regions and places the result in dr. The result- 
ing 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 
/, 
* opaque reference to Regiondata type. 
* user won't need contents, only pointer. 
*/ 
typedef struct _XRegion *Region; 

Related Commands 
XXorRegion, XUnionRectWithRegion, XSubtractRegion, XShrinkRegion, 
XSetRegion, XRectInRegion, XPolygonRegion, XPointinRegion, XOffset- 
Region, XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroy- 
Region, XEqualRegion, XClipBox. 

488 

July 26, 1988 



--Xlib - Context Manager 

XUniqueContext 

Name 
XUniqueContext D 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 
an instance of the xContext structure with a unique resource ID that will be used in subse- 
quent 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. 

July 26, 1988 489 



XUnloadFont 

Xlib- Fonts m 

Name 
XUnloadFont -- unload a font. 

Synopsis 
XUnloadFont (display, font) 
Display *display; 
Font font; 

Arguments 
display 

fon t 
Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the ID of the font to be unloaded. 

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 X 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 
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontinfo, XListFonts, 
XListFontsWithInfo, XFreeFontNames, XFreeFontPath, XGetFontPath, 
XQueryFont, XSetFont, XSetFontPath, XGetFontProperty, XCreateFont- 
Cursor. 

490 

July 26, 1988 



mXlib - Mapping 

XUnmapSubwindows 

Name 
XUnmapSubwindows--unmap allsubwindowsofa ven window. 
Synopsis 
XUnmapSubwindows(display, w) 
Display *display; 
Window w; 

Arguments 
display 

w 
Description 

Specifies a pointer to the Display structure; returned from X0pen- 
Display. 
Specifies the ID of the window whose subwindows are to be unmapped. 

XUnmapSubwindows performs an XUnmapWindow on all mapped children of w, in bottom 
to top stacking order. 
XUnmapSubwindows also generates an UnmapNotify event on each subwindow and gen- 
erates exposure events on formerly obscured windows. This is much more efl%ient 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. 

July 26, 1988 491 



--Xlib - Pointer 

XWarpPointer 

Name 
XWarpPointer m move the pointer to another point on the screen. 

Synopsis 
XWarpPointer(display, src_w, dest_w, src_x, src_y, 
src_width, 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 pointer to the Display structure; returned from XOpen- 
Display. 

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. 

szc x 
src_y 

src width 
src_height 

Specify the x and y coordinates within the source window. These are uscd 
with src_width and src_height to determine the rectangle the 
pointer must be in. They are not the present pointer position. If src_y is 
None, these coordinates are relative to the root window of src w. 
-- 

Specify the width and height in pixels of the source window. Used with 
src_x and src_y. 

dest_x Specify the destination x and y coordinates within the destination window. 
dest_y If dest_y 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 des.t_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 betwecn 
src_y and the bottom edge of the window to be moved. 

XWarpPointer cannot be used to move the pointer outside the confine to window of an 
-- 
active pointer grab. If this is attempted the pointer will be moved to the point on the border of 
the confine_to window nearest the requested destination. 

July 26, 1988 493 



XWarpPointer (continued) Xlib - Pointer 

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 
XQueryPointer, XGrabPointer, XChangeActivePointerGrab, XUngrab- 
Pointer, XGetPointerMapping, XSetPointerMapping, XGetPointerControl, 
XChangePointerControl. 

44 

July 26, 1988 



nXlib - Input Handling 

XWindowEvent 

Name 
XWindowEvent m remove the next event matching mask and window. 

Synopsis 
XWindowEvent (display, w, event_mask, rep) 
Display *display; 
Window w; 
long event mask; 
-- 
XEvent *rep; /* RETURN */ 

Arguments 
di spl ay 

event mask 

rep 

Description 

Specifies a pointer to the Display structure; returned from XOpen- 
Display. 
Specifies the ID of the window whose next matched event you want to 
remove. 
Specifies the event mask. See XSelectInput for a complete list of event 
masks. 
Specifies the event removed from the input queue. XWindowEvent returns 
this event to this argument. 

XWindowEvent searches the event queue for specific event types from the specified window. 
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 supplied by the caller. Other 
events in the queue are not discarded. If no such event has been queued, XWindowEvent 
flushes the output buffer and waits until one is received. 

In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the 
output buffer is flushed only if no matching events are found on the queue. This change is 
compatible with applications written for Release 1. 

Structures 
See individual event structures described in Volume One, Chapter 8, Events, and Appendix F, 
Structure Reference in this volume. 

Related Commands 
XSelectInput, XSetInputFocus, XGetInputFocus, XCheckWindowEvent, 
XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMask- 
Event, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, 
XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, 
XPending, XSynchronize, XSendEvent, QLength. 

July 26, 1988 495 



XWriteBitmapFile 

Xlib - Pixmaps and Tiles-- 

Name 
XWriteBitmapFile m write a bitmap to a file. 
Synopsis 
int XWriteBitmapFile ( display, filename, bitmap, 
height, x_hot, y_hot ) 
Display *display; 
char *filename; 
Pixmap bitmap; 
unsigned int width, height ; 
int x_hot, y_hot ; 

width, 

Arguments 
display 

filename 

bi tmap 
width 
height 
x hot 
y_hot 

Specifies a pointer to the Display sucture; returned om XOpen- 
Display. 

Specifies the filename to use. The format of the filename is operating system 
specific. 

Specifies the bitmap to be written. 
Specify the width and height in pixels of the bitmap to be written. 

Specify where to place the hotspot coordinates (or -1,-1 if none present) in 
the file. 

Description 
XWriteBitmapFile writes a bitmap to a file. The file is written out in X version 11 bit- 
map format, which is the format created by the X version 11 bitmap program. Refer to that 
program's reference pages for details. While XReadBitmapFile Can read in either X Ver- 
sion 10 format or X Version 11 format, XWriteBitraapFile always writes out X Version 
11 format only. The difference between these formats is slight. 
If the file cannot be opened for writing, XWriteBitraapFile 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 -I, -I, 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 filenarae after the last "/". 

496 July 26, 1988 



Xlib - Pixmaps and Tiles (continued) XWriteBitmapFile 

#define gray_width 16 
#define gray_height 16 
#define gray x hot 8 
#define gray y hot 8 
static char gray_bits[] = ( 
0xfS, 0xlf, 0xe3, 0xc7, 0xcf, 0xf3, 0x9f, 0xf9, 0xbf, 0xfd, 0x33, 0xcc, 
0x7f, 0xfe, 0x7f, 0xfe, 0x7e, 0x7e, 0x7f, 0xfe, 0x37, 0xec, 0xbb, 0xdd, 
0x9c, 0x39, 0xcf, 0xf3, 0xe3, 0xc7, 0xfS, 0xlf}; 

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

Errors 
BadDrawable 
BadMatch 

Related Commands 
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindow- 
BackgroundPixmap, XCreatePixmap, XCreatePixmapFromBitmapData, XFree- 
Pixmap, XQueryBestSize, XQueryBestStipple, XReadBitmapFile, XCreate- 
BitmapFromData. 

July 26, 1988 49 7 



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 

dr 

Specify the two regions on which you want to perform the computation. 

Returns the result of the computation. 

Description 
XXorRogion 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 
/* 
* opaque reference to Regiondata type. 
* user won't need contents, only pointer. 
*/ 
typedef struct _XRegion *Region; 

Related Commands 
XUnionRegion, XUnionRectWithRegion, XSubtractRegion, XShrinkRegion, 
XSetRegion, XRectInRegion, XPolygonRegion, XPointinRegion, XOffset- 
Region, XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroy- 
Region, XEqualRegion, XClipBox. 

4@8 

July 26, 1988 



Colorcells 

XAllocColor 

XAllocColorCells 
XAllocColorPlanes 
XAllocNamedColor 
XLookupColor 

XParseColor 

XQueryColor 
XQueryColors 

XStoreColor 

XStoreColors 

XStoreNamedColor 
XFreeColors 
BlackPixel 

WhitePixel 

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. 
Get database RGB values and closest hardware- 
supported RGB values from color name. 
Look up or translate RGB values from color name or 
hexadecimal 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 avail- 
able 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 color- 
map. 

Colormaps 

XCopyColormapAndFree 
XCreateColormap 
XFreeColormap 
XGetStandardColormap 
XSetStandardColormap 
XSetWindowColormap 
XInstallColormap 
XUninstallColormap 

XListInstalledColormaps 
DefaultColormap 
DefaultColormapOfScreen 
DisplayCells 

Context Manager 

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 
connected display. 

XDeleteContext 
XFindContext 

Delete a context entry for a given window and type. 
Get data from the context manager (not graphics context). 

500 Xlib Reference Manual 



Context Manager (continued) 

XSaveContext 

XUniqueContext 

Cursors 

Save a data value corresponding to a window and context type 
(not graphics context). 
Create a new context ID (not graphics context) 

XDefineCursor 
XUndefineCursor 
XCreateFontCursor 
XCreateGlyphCursor 
XCreatePixmapCursor 
XFreeCursor 
XRecolorCursor 
XQueryBestCursor 
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 

DefaultScreen 

DefaultVisual 
DisplayCells 

DisplayHeight 

DisplayHeightMM 
DisplayPlanes 
DisplayString 

DisplayWidth 
DisplayWidthMM 
RootWindow 
ScreenCount 

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 connected 
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. 

Drawing Primitives 

XDraw 
XDrawArc 
XDrawArcs 
XDrawFilled 
XDrawLine 

Draw a polyline or curve between vertex list (from X 10). 
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. 

Appendix A: Function Group Summary 501 



Drawing Primitives (continued) 

XDrawLine s Draw 
XDrawPoint Draw 
XDrawPoint s Draw 
XDrawRect angle Draw 
XDrawRectangles Draw 
XDrawSegment s Draw 
XCopyArea Copy 
XCopyPlane 

XFillArc 
XFillArcs 
XFillPolygon 
XFillRectangle 
XFillRectangles 
XClearArea 
XClearWindow 

multiple connected lines. 
a point. 
multiple points. 
an outline of a rectangle. 
the outlines of multiple rectangles. 
multiple disjoint lines. 
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 
XSetIOErrorHandler 
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 

XSelectInput 
XSendEvent 
XSetInputFocus 
XGetInputFocus 
XWindowEvent 
XCheckWindowEvent 

XCheckTypedEvent 

XCheckTypedWindowEvent 
XMaskEvent 
XCheckMaskEvent 
XIfEvent 
XCheckIfEvent 

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 
passed 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. 
Wait for matching event. 
Check the event queue for a matching event. 

502 Xlib Reference Manual 



Events (continued) 

XPeekEvent 
XPeekIfEvent 

XAllowEvents 

XGetMotionEvents 
XNextEvent 
XPutBackEvent 
XEventsQueued 
XPending 

XSynchronize 
QLength 

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. 
Flush the output 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 
XListExtensions 
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 
XFreeFontInfo 
XFreeFontNames 
XFreeFontPath 
XListFonts 
XListFontsWithInfo 
XQueryFont 
XSetFont 
XSetFntPath 
XGetFontPath 
XGetFontProperty 
XCreateFontCursor 

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 

Grab a key. 
Release a key from grab. 
Grab the keyboard. 
Release the keyboard from grab. 

Appendix A: Function Group Summary 503 



Grabbing (continued) 

XGrabButton 
XUngrabButton 
XGrabPointer 
XUngrabPointer 
XGrabServer 
XUngrabServer 
XChangeActivePointerGrab 

Grab a pointer button. 
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 

XGContextFromGC 

XCreateGC 

XChangeGC 
XCopyGC 
XFreeGC 
XSetArcMode 
XSetClipMask 
XSetClipOrigin 
XSetClipRectangles 

XSetRegion 

XSetDashes 

XSetLineAttributes 
XSetFillRule 
XSetFillStyle 
XSetTile 
XSetStipple 
XSetTSOrigin 
XSetGraphicsExposures 
XSetForeground 
XSetBackground 
XSetFunction 
XSetPlaneMask 
XSetState 

XSetSubwindowMode 
DefaultGC 

Obtain the GContext (resource ID) associated with the 
specified graphics context. 
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. 
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 rec- 
tangles. 
Set clip_mask of the graphics context to the specified 
region. 
Set dash_offset and dashes (for lines) in a graph- 
ics 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. 

504 Xlib Reference Manual 



Host Access 

XAddHost 
XAddHosts 
XListHosts 
XRemoveHost 
XRemoveHosts 
XDisableAccessControl 
XEnableAccessControl 

XSetAcces sCont rol 

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 
DefaultScreen 

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. 
Return the screen integer; the last segment of a string 
passed to XOpenDisplay, or the DISPLAY environment 
variable if NULL was used. 

Images 

XCreateImage 
XDestroyImage 
XPutImage 
XSubImage 
XGetImage 
XGetSubImage 

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 locadon 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 
ZFormat. Returns either LSBFirst or MSBFirst. 

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. 

Appendix A: Function Group Summary 505 



Keyboard (continued) 

XLookupString 

XQueryKeymap 
XGetKeyboardMapping 
XChangeKeyboardMapping 
XRefreshKeyboardMapping 
XSetModifierMapping 
XGetModifierMapping 
XDeleteModifiermapEntry 
XInsertModifiermapEntry 
XNewModifiermap 
XFreeModifiermap 

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 XModifierKeymap stnacture. 
Add a new entry to an XModifierKeymap stnacture. 
Create a keyboard modifier mapping structure. 
Destroy and free a keyboard modifier mapping structure. 

AllPlanes 
BlackPixel 

BlackPixelOfScreen 

CellsOfScreen 

ConnectionNumber 
DefaultColormap 
DefaultColormapOfScreen 
DefaultDepth 
DefaultDepthOfScreen 
DefaultGC 

DefaultGCOfScreen 

DefaultRootWindow 
DefaultScreen 

DefaultScreenOfDisplay 
DefaultVisual 
DefaultVisualOfScreen 
DisplayCells 

DisplayHeight 

DisplayHeightMM 
DisplayOfScreen 
DisplayPlanes 

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 
tem). 
Return 
Return 
Return 
Return 

the connection number (file descriptor on UNIX sys- 

the default colormap on the specified screen. 
the default colormap of the specified screen. 
the depth of the default root window for a screen. 
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 XOpenDisplay, or the DISPLAY environment 
variable if NULL was used. 
Return the default screen of the specified display. 

Return 
Return 
Return 
nected 
Return 
pixels. 
Return 
Return 
Return 

the default visual structure for a screen. 
the default visual of the specified screen. 
the maximum number of colormap cells on the con- 
display. 
an integer that describes the height of the screen in 

the height of the specified screen in millimeters. 
the display of the specified screen. 
the number of planes on the connected display. 

506 Xlib Reference Manual 



Macros, Image Format 

BitmapBitOrder 

BitmapPad 

BitmapUnit 

ByteOrder 

ImageByteOrder 

Retum LeastSignificant or MostSignificant. 
Indicates e bit order in BitmapUnit. 
Each scan line is padded to a multiple of bits specified by 
the value returned by this macro. 
The scan line is quantized (calculated) in multiples of this 
value. 
Specifies the required byte order for images for each scan 
line unit in XYFormat (bitmap) or for each pixel value 
in ZFormat. Possible values are LSBFirst or 
MSBFirst. 
Specifies the required byte order for images for each scan 
line unit in XYFormat (bitmap) or for each pixel value 
in ZFormat. Return either LSBFirst or MSBFirst. 

Macros, Keysym Classification 

IsCursorKey 
IsFunctionKey 
IsKeypadKey 
IsMiscFunctionKey 

IsModifierKey 
IsPFKey 

Return T rue if the keysym is on the cursor key. 
Return True if the keysym is on the function keys. 
Return True if the keysym is on the key pad. 
Return True if the keysym is on the miscellaneous func- 
tion keys. 
Return T rue if the keysym is on the modifier keys. 
Return T rue if the keysym is on the PF keys. 

Mapping 

(see Window Mapping, Keyboard, or Pointer) 

Output Buffer 

XFlush 
XSync 

Pointers 

Flush the output buffer. 
Flush the output buffer and wait for all events to be pro- 
cessed by the server. 

XQueryPointer 
XWarpPointer 
XGrabPointer 
XUngrabPointer 
XGetPointerMapping 
XSetPointerMapping 
XGetPointerControl 
XChangePointerControl 
XChangeActivePointerGrab 

Get the current pointer location. 
Move the pointer to another point on the screen. 
Grab the pointer. 
Release the pointer from grab. 
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. 

508 Xlib Reference Manual 



Properties 

XListProperties 
XDeleteProperty 
XChangeProperty 
XSetStandardProperties 

XRotateWindowProperties 
XGetAtomName 
XGetFontProperty 
XGetWindowProperty 
XInternAtom 

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. 

Regions 

XCreateRegion 
XDestroyRegion 
XEmptyRegion 
XPolygonRegion 
XPointInRegion 
XRectInRegion 
XUnionRectWithRegion 
XClipBox 
XOffsetRegion 
XShrinkRegion 
XEqualRegion 

XSetRegion 

XSubtractRegion 
XlntersectRegion 
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. 

Resource Manager and DataBase (Release 2 only) 

XrmGetFileDatabase 
XrmGetResource 
XrmGetStringDatabase 
XrmInitialize 
XrmMergeDatabases 
XrmParseCommand 
XrmPutFileDatabase 
XrmPutLineResource 
XrmPutResource 
XrmPutStringResource 

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. 

Appendix A: Function Group Summary 509 



Resource Manager and DataBase (Release 2 only) (continued) 

XrmQGetResource 
XrmQGetSearchList 
XrmQGetSearchResource 
XrmQPutResource 
XrmQPutStringResource 
XrmQuarkToString 
XrmStringToBinding- 
QuarkList 
XrmStringToQuarkList 
XrmStringToQuark 
XrmUniqueQuark 
Xpermalloc 

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. 

Save Set 

XAddToSaveSet 
XRemoveFromSaveSet 
XChangeSaveSet 

Add a window's children to the client's save-set. 
Remove a window's children from the client's save-set. 
Add or remove a subwindow from the client's save-set. 

Screen Saver 

XActivateScreenSaver 
XForceScreenSaver 
XResetScreenSaver 
XGetScreenSaver 
XSetScreenSaver 

Selections 

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. 

XGetSelectionOwner 
XSetSelectionOwner 
XConvertSelection 

Return the owner of a selection. 
Set the owner of a selection. 
Use the value of a selection. 

Standard Geometry 

XGeomet ry 

XParseGeometry 

XTranslateCoordinates 

Text 

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. 

XDrawImageString 
XDrawImageStringl6 
XDrawString 

Draw 8-bit image text characters. 
Draw 16-bit image text characters. 
Draw an 8-bit text string, foreground only. 

510 Xlib Reference Manual 



Text (continued) 

XDrawStringl6 
XDrawText 
XDrawTextl6 
XQueryTextExtents 
XQueryTextExtentsl6 

XTextExtents 
XTextExtentsl6 
XTextWidth 
XTextWidthl6 

Draw two-byte text strings. 
Draw 8-bit polytext strings. 
Draw 16-bit polytext slrings. 
Query the server for string and font metrics. 
Query the server for string and font metrics of a 16-bit 
character siring. 
Get siring 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 
XQueryBestStipple 
XQueryBestTile 
XSetTile 
XSetWindowBorderPixmap 

XSetWindowBackgroundPixmap 
XReadBitmapFile 
XWriteBitmapFile 
XCreateBitmapFromData 
XCreatePixmapFromBitmapData 

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 X 11 bitmap format data. 
Create a pixmap with depth from bitmap data. 

User Preferences 

XAutoRepeatOff 
XAutoRepeatOn 
XBell 
XGetDefault 

XGetPointerControl 
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 

XGetVisualInfo 

XMat chVi sual Info 

DefaultVisual 

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. 

Appendix A: Function Group Summary 511 



Window Attributes 

XGetWindowAttributes 
XChangeWindowAttributes 
XSetWindowBackground 
XSetWindowBackgroundPixmap 
XSetWindowBorder 

XSetWindowBorderPixmap 

XSetWindowColormap 
XDefineCursor 
XGetGeometry 
XSelectInput 

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 

Window Existence 

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. 

XCreateSimpleWindow 
XCreateWindow 
XDestroySubwindows 
XDestroyWindow 

Window Manager Hints 

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. 

XGetClassHint 
XSetClassHint 
XGetNormalHints 

XSetNormalHints 

XGetSizeHints 
XSetSizeHints 

XGetTransientForHint 

Get the XA._WM_CLASS property of a window. 
Set the XA_WM_CLAS S property of a window. 
Get the size hints property of a window in normal 
state (not zoomed or iconified). 
Set the size hints property of a window in normal 
state (not zoomed or iconified). 
Read any property of type XA WM SIZE HINTS. 
Set the value of any property of type XA WM 
-- __ 
SIZE HINTS. 
Get the XA_WM_TRANSIENT_FOR property of a 
window. 

512 Xlib Reference Manual 



Window Manager Hints (continued) 

XSetTransientForHint 

XGetWMHints 
XSetWMHints 
XGetZoomHints 
XSetZoomHints 
XFetchName 
XStoreName 
XGetIconName 
XSetIconName 
XGetIconSizes 
XSetIconSizes 
XSetCommand 

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. 
Set the size hints property of a zoomed window. 
Get a window's name (XA_WM_NAME property). 
Assign a name to a window for the window manager. 
Get the name to be displayed in an icon. 
Set the name to be displayed in a window's icon. 
Get preferred icon sizes. 
Set the value of the XA_WM_ICON_S IZE property. 
Set the XA WM COMMAND atom (command line 
arguments). 

Window Manipulation 

XLowerWindow 
XRaiseWindow 
XCirculateSubwindows 

XCirculateSubwindowsDown 

XCirculateSubwindowsUp 

XQueryTree 
XReparentWindow 
XMoveWindow 
XResizeWindow 
XMoveResizeWindow 
XSetWindowBorderWidth 
XRestackWindows 
XConfigureWindow 

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 stack- 
ing order. 
Circulate the top child to the bottom of the stack- 
ing 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. 

Window Mapping 

XMapRaised 
XMapSubwindows 
XMapWindow 
XUnmapSubwindows 
XUnmapWindow 

Map a window on top of its siblings. 
Map all subwindows. 
Map a window. 
Unmap all subwindows of a given window. 
Unmap a window. 

Appendix A: Function Group Summary 513 



Alphabetical Listing of Routines 

Table A- 1. Alphabetical Listing of Routines 

Routine 

XActivateScreenSaver 
XAddHost 
XAddHosts 
XAddPixel 
XAddToSaveSet 
XAllocColor 

XAllocColorCells 
XAllocColorPlanes 
XAllocNamedColor 
XAllowEvents 

XAutoRepeatOff 
XAutoRepeatOn 
XBell 
XChangeActivePointerGrab 
XChangeGC 
XChangeKeyboardControl 
XChangeKeyboardMapping 
XChangePointerControl 
XChangeProperty 
XChangeSaveSet 
XChangeWindowAttributes 
XCheckIfEvent 
XCheckMaskEvent 
XCheckTypedEvent 

XCheckTypedWindowEvent 

XCheckWindowEvent 

XCirculateSubwindows 
XCirculateSubwindowsDown 

XCirculateSubwindowsUp 

XClearArea 
XClearWindow 
XClipBox 

Description 

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's children to the client's save-set. 
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 subwindow 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. 
Return the next event in queue that matches event type; 
don't wait. 
Return the next event in queue matching type and win- 
dow. 
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. 

514 Xlib Reference Manual 



Table A- 1. Alphabetical Listing of Routines (continued) 

Routine 

XCloseDisplay 
XConfigureWindow 

XConvertSelection 
XCopyArea 
XCopyColormapAndFree 
XCopyGC 
XCopyPlane 

XCreateAssocTable 
XCreateBitmapFromData 
XCreateColormap 
XCreateFontCursor 
XCreateGC 

XCreateGlyphCursor 
XCreateImage 
XCreatePixmap 
XCreatePixmapCursor 
XCreatePixmapFrom- 
BitmapData 
XCreateRegion 
XCreateSimpleWindow 
XCreateWindow 
XDefineCursor 
XDeleteAssoc 
XDeleteContext 
XDeleteModifiermapEntry 
XDeleteProperty 
XDestroyAssocTable 
XDestroyImage 
XDestroyRegion 
XDestroySubwindows 
XDestroyWindow 
XDisableAccessControl 
XDisplayName 

XDraw 
XDrawArc 
XDrawArcs 
XDrawFilled 

XDrawImageString 

Description 

Disconnect a client program from an X server and display. 
Change the window position, size, border width, or stack- 
ing 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 X11 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 XErrlage 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 XModifierKeymap 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. 
Destroy all subwindows of a window. 
Unmap and destroy a window and all subwindows. 
Allow access from any host. 
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 
XlO). 
Draw 8-bit image text characters. 

Appendix A: Function Group Summary 515 



Table A-1. Alphabetical Listing of Routines (continued) 

Routine 

XDrawImageStrngl6 
XDrawLine 
XDrawLines 
XDrawPoint 
XDrawPoints 
XDrawRectangle 
XDrawRectangles 
XDrawSegment s 
XDrawSt ring 
XDrawStringl6 
XDrawText 
XDrawTextl6 
XEmptyRegion 
XEnableAccessControl 
XEqualRegion 

XEventsQueued 
XFetchBuffer 
XFetchBytes 
XFetchName 
XFillArc 
XFillArcs 
XFillPolygon 
XFillRectangle 
XFillRectangles 
XFindContext 
XFlush 
XForceScreenSaver 
XFree 
XFreeColormap 
XFreeColors 
XFreeCursor 
XFreeExtensionList 
XFreeFont 
XFreeFontInfo 
XFreeFontNames 
XFreeFontPath 
XFreeGC 
XFreeModifiermap 
XFreePixmap 
XGContextFromGC 

Description 

Draw 
Draw 
Draw 
Draw 
Draw 
Draw 
Draw 
Draw 
Draw 
Draw 
Draw 

16-bit image text characters. 
a line between two points. 
multiple connected lines. 
a point. 
multiple points. 
an outline of a rectangle. 
the outlines of multiple rectangles. 
multiple disjoint lines. 
an 8-bit text string, foreground only. 
two-byte text strings. 
8-bit polytext strings. 

Draw 16-bit polytext strings. 
Determine if a region is empty. 
Use access conu'ol 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 output 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. 
Desu'oy a cursor. 
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. 
Desu'oy and free a keyboard modifier mapping su'ucture. 
Free a pixmap ID. 
Obtain the GContext (resource ID) associated with the 
specified graphics context. 

516 Xlib Reference Manual 



Table A-1. Alphabetical Listing of Routines (continued) 

Routine 

XIn sertModi fiermapEnt ry 
XInstallColormap 
XInternAtom 
XIntersectRegion 
XKeycodeToKeysym 
XKeysymToKeycode 
XKeysymToString 
XKillClient 
XListExtensions 

XListFonts 
XListFontsWithInfo 
XListHosts 
XListInstalledColormaps 
XListProperties 
XLoadFont 
XLoadQueryFont 
XLookUpAssoc 
XLookupColor 

XLookupKeysym 
XLookupString 

XLowerWindow 
XMakeAssoc 
XMapRaised 
XMapSubwindows 
XMapWindow 
XMaskEvent 
XMatchVisualInfo 

XMoveResizeWindow 
XMoveWindow 
XNewModifiermap 
XNextEvent 
XNoOp 
XOffsetRegion 
XOpenDisplay 
XParseColor 

XParseGeometry 

XPeekEvent 

Description 

Add a new envy to an XModifierKeymap structure. 
Insl a colonnap. 
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 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. 
Get the property list for a window. 
Load a font if not already loaded; get font ID. 
Load a font and fill information smacture. 
Obtain data from an association table. 
Get database RGB values and closest hardware-supported 
RGB values from color name. 
Get the keysym corresponding to a keycode in structure. 
Map a key event to ASCII string, keysym, and 
ComposeStatus. 
Lower a window in the stacking order. 
Create an entry in an association table. 
Map a window on top of its siblings. 
Map all subwindows. 
Map a window. 
Remove the next event that matches mask. 
Obtain the visual information that matches the desired 
depth and class. 
Change the size and position of a window. 
Move a window. 
Create a keyboard modifier mapping smacture. 
Get the next event of any type or window. 
Send a NoOp to exercise connection with the server. 
Change offset of a region. 
Connect a client program to an X server. 
Look up or translate RGB values from ASCII color name 
or hexadecimal value. 
Generate position and size from standard window 
geometry string. 
Get an event without removing it from the queue. 

518 Xlib Reference Manual 



Table A- 1. Alphabetical Listing of Routines (continued) 

Routine 

XPeekIfEvent 

XPending 

Xpermalloc 
XPointInRegion 
XPolygonRegion 
XPutBackEvent 
XPutImage 
XPutPixel 
XQueryBestCursor 
XQueryBestSize 
XQueryBestStipple 
XQueryBestTile 
XQueryColor 

XQueryColors 
XQueryExtension 
XQueryFont 
XQueryKeymap 
XQueryPointer 
XQueryTextExtents 
XQueryTextExtentsl6 

XQueryTree 
XRaiseWindow 
XReadBitmapFile 
XRebindKeysym 
XRecolorCursor 
XRectInRegion 
XRefreshKeyboardMapping 
XRemoeFromSaveSet 
XRemoveHost 
XRemoveHosts 
XReparentWindow 
XResetScreenSaver 
XResizeWindow 
XRestackWindows 
XrmGetFileDatabase 
XrmGetResource 
XrmGetStringDatabase 
XrmInitialize 
XrmMergeDatabases 

Description 

Get an event without removing it from the queue; do not 
wait. 
Flush the output buffer and return the number of pending 
input events. 
Allocate memory never to be freed. 
Determine if a point is inside a region. 
Generate a region from points. 
Push an event back on the input queue. 
Draw a rectangular image on a window or pixmap. 
Set a pixel value in an image. 
Get the closest supported cursor sizes. 
Obtain the "best" supported cursor, tile, or sdpple size. 
Obtain the best supported stipple shape. 
Obtain the best supported fill tile shape. 
Obtain the RGB values and flags for a specified pixel 
value. 
Obtain RGB values for an array of pixel values. 
Get extension information. 
Return information about a loaded font. 
Obtain a bit vector for the current state of the keyboard. 
Get the current pointer location. 
Query the server for string and font meu'ics. 
Query the server for string and font metrics of a 16-bit 
character string. 
Return a list of children, parent, and root. 
Raise a window to the top of the stacking order. 
Read a bitmap from disk. 
Rebind a keysym to a string for client. 
Change the color of a cursor. 
Determine if a rectangle resides in a region. 
Update the stored modifier and keymap information. 
Remove a window's children from the client's save-set. 
Remove a host from the access control list. 
Remove multiple hosts from the access control list. 
Change a window's parent. 
Reset the screen saver. 
Change a window's size. 
Change the stacking order of siblings. 
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. 

Appendix A: Function Group Summary 519 



Table A- 1. Alphabetical Listing of Routines (continued) 

Routine 

XrmParseCommand 

XrmPutFileDatabase 
XrmPutLineResource 

XrmPutResou rce 
XrmPutSt ringResource 
XrmQGetResource 
X rmQGet SearchLi st 
XrmQGet SearchRe source 
XrmQPut Re source 
XrmQPut St ringRe source 

XrmQuarkToString 
XrmStringToBindingQuarkList 

XrmStringToQuark 
XrmStringToQuarkList 
XrmUniqueQuark 
XRotateBuffers 
XRotateWindowProperties 
XSaveContext 

XSelectInput 
XSendEvent 
XSetAccessControl 
XSetAfterFunction 
XSetArcMode 
XSetBackground 
XSetClassHint 
XSetClipMask 
XSetClipOrigin 
XSetClipRectangles 

XSetCloseDownMode 
XSetCommand 

XSetDashes 

XSetErrorHandler 
XSetFillRule 
XSetFillStyle 
XSetFont 

Description 

Load a resource database from command line argu- 
ments. 
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 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_offset 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. 

520 Xlib Reference Manual 



Table A- 1. Alphabetical Listing of Routines (continued) 

Routine 

XSetFontPath 
XSetForeground 
XSetFunction 
XSetGraphicsExposures 
XSetIconName 
XSetIconSizes 
XSetInputFocus 
XSetIOErrorHandler 
XSetLineAttributes 
XSetModifierMapping 

XSetNormalHints 

XSetPlaneMask 
XSetPointerMapping 
XSetRegion 

XSetScreenSaver 
XSetSelectionOwner 
XSetSizeHints 

XSetStandardColormap 
XSetStandardProperties 

XSetState 

XSetStipple 
XSetSubwindowMode 
XSetTile 
XSetTransientForHint 

XSetTSOrigin 
XSetWindowBackground 
XSetWindowBackgroundPixmap 
XSetWindowBorder 

XSetWindowBorderPixmap 

XSetWindowBorderWidth 
XSetWindowColormap 
XSetWMHints 
XSetZoomHints 

Description 

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  a graphics context. 
Set the name to be displayed in a window's icon. 
Set the value of the xA WM TCON STZ. 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. 
Set clip_mask of the graphics context to the 
specified region. 
Set the parameters of the screen saver. 
Set the owner of a selection. 
Set the value of any property of type 
XA WM SIZE HINTS. 
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. 
Set the fill tile in a graphics context. 
Set the XA WM TRANSIENT FOR property of a win- 
dow. 
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. 
Set a window manager hints property. 
Set the size hints property of a zoomed window. 

Appendix A: Function Group Summary 521 



Table A-1. Alphabetical Listing of Routines (continued) 

Routine 

XShrinkRegion 
XStoreBuffer 
XStoreBytes 
XStoreColor 

XStoreColors 

XStoreName 
XStoreNamedColor 
XStringToKeysym 
XSubImage 
XSubtractRegion 
XSync 

XSynchronize 
XTextExtents 
XTextExtentsl6 
XTextWidth 
XTextWidthl6 
XTranslateCoordinates 

XUndefineCursor 
XUngrabButton 
XUngrabKey 
XUngrabKeyboard 
XUngrabPointer 
XUngrabServer 
XUninstallColormap 

XUnionRectWithRegion 
XUnionRegion 
XUniqueContext 
XUnloadFont 
XUnmapSubwindows 
XUnmapWindow 
XWarpPointer 
XWindowEvent 
XWriteBitmapFile 
XXorRegion 

Description 

Reduce or expand the size of a region. 
Store data in a cut buffer. 
S tore 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 avail- 
able hardware colors. 
Assign a name to a window for the window manager. 
Allocate a read/write colorcell by English color name. 
Convert a keysym name string to a keysym. 
Create a subimage from part of an image. 
Subtract one region from another. 
Flush the output 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 pixcls 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. 
Write a bitmap to a file. 
Calculate the difference between the union and intersec- 
tion of two regions. 

522 Xlib Reference Manual 



B 
Error Messages and Protocol Requests 

This appendix contains two tables: Table B-1 describes the standard error ctdes (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 
volume 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 gen- 
eral. 

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 con- 
venience routines for the more general XConfigureWindow. Both of these Xlib routines 
use the protocol request X_ConfigureWindow. 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 ocurred, 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 requiting 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 

BadAccess 

BadAlloc 

Possible Cause 

Client attempted to grab a key/button combination that is already 
grabbed by another client. 
Client attempted to free a colormap entry that is not allocated by the 
client. 
Client attempted to store into a read-only colormap entry. 
Client attempted to modify the access conuol list from other than the 
local (or otherwise authorized) host. 
Client attempted to select an event type that only one client can select at 
a time, when another client has already selected it. 
The server failed to allocate the requested resource. 

Appendix B: Error Messages and Protocol Requests 523 



Table B-1. Error Messages (continued) 

Error Codes: 

BadAtom 
BadColor 

BadCursor 
BadDrawable 

BadFont 

BadGC 

BadIDChoice 

BadImplemen 
-tation 

BadLength 

BadMatch 

BadName 
BadPixmap 
BadRequest 
BadValue 

BadWindow 

Possible Cause 

A value for an Atom argument does not name a defined Atom. 
A value for a Colormap argument does not name a defined Color- 
map. 
A value for a Cursor argument does not name a defined Cursor. 
A value for a Drawable argument does not name a defined Window 
or P ixmap. 
A value for a Font or GContext argument does not name a defined 
Font. 
A value for a GContext argument does not name a defined GCon- 
text. 
The value chosen for a resource identifier is either not included in the 
range assigned to the client, or is already in use. 

The server does not implement some aspect of the request. A server 
that generates this error for a core request is deficient. Clients should 
be prepared to receive such errors and either handle or discard them. 

The length of a request is shorter or longer than that required to 
minimally contain the arguments. This usually indicates an internal 
Xlib error. 

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. 
A font or color of the specified name does not exist. 
A value for a pixmap argument does not name a defined pixmap. 
The major or minor opcode does not specify a valid request. 
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. 
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 
set of fixed alternatives (for example, a window ID, PointerRoot, or None) and some 
other constant or variable is used. 

524 Xlib Reference Manual 



Table B-2. Xlib Functions and Protocol Requests 

Protocol Request 
X_AllocColor 
X_AllocColorCells 
X_AllocColorPlanes 
X_AllocNamedColor 
X_AllowEvents 
X_Bell 
X_ChangeActivePointerGrab 
X_ChangeGC 

X_ChangeHosts 

X_ChargeKeyboardControl " 

X_ChangeKeyboardMapping 
X_ChangePointerControl 
X_ChangeProperty 

Xlib Function 

XAllocColor 
XAllocColorCells 
XAllocColorPlanes 
XAllocNamedColor 
XAllowEvents 
XBell 
XChangeActivePointerGrab 
XChangeGC 
XSetArcMode 
XSetBackground 
XSetClipMask 
XSetClipOrigin 
XSetFillRule 
XSetFillStyle 
XSetFont 
XSetForeground 
XSetFunction 
XSetGraphicsExposures 
XSetLineAttributes 
XSetPlaneMask 
XSetState 
XSetStipple 
XSetSubwindowMode 
XSetTile 
XSetTSOrigin 
XAddHost 
XAddHosts 
XRemoveHost 
XRemoveHosts 
XAutoRepeatOff 
XAutoRepeatOn 
XChangeKeyboardControl 
XChangeKeyboardMapping 
XChangePointerControl 
XChangeProperty 
XSetCommand 
XSetIconSizes 
XSetIconWindow 
XSetNormalHints 
XSetResizeHint 
XSetSizeHints 

Appendix B: Error Messages and Protocol Requests 525 



Table B-2. Xlib Functions and Protocol Requests (continued) 

Protocol Request 

X_ChangeSaveSet 

X_ChangeWindowAtu'ibutes 

X_CirculateWindow 

X_ClearArea 

X_CloseFont 

X_ConfigureWindow 

X_ConvertSelection 
X_CopyArea 
X_CopyColormapAndFree 
X_CopyGC 
X_CopyPlane 
X_CreateColormap 
X_CreateCursor 

Xlib Function 

XSet St anda rdP rope rt ie s 
XSetWMHint s 
XSetZoomHint s 
XStoreBuffer 
XStoreBytes 
XStoreName 

XAddToSaveSet 
XChangeSaveSet 
XRemoveFromSaveSet 

XChangeWindowAttributes 
XDefineCursor 
XSelectInput 
XSetWindowBackground 
XSetWindowBackgroundPixmap 
XSetWindowBorder 
XSetWindowBorderPixmap 
XSetWindowColormap 
XUndefineCursor 

XCirculateSubwindows 
XCirculateSubwindowsDown 
XCirculateSubwindowsUp 
XClearArea 
XClearWindow 

XFreeFont 
XUnloadFont 

XConfigureWindow 
XLowerWindow 
XMapRaised 
XMoveResizeWindow 
XMoveWindow 
XRaiseWindow 
XResizeWindow 
XRestackWindows 
XSetWindowBorderWidth 

XConvertSelection 

XCopyArea 
XCopyColormapAndFree 
XCopyGC 
XCopyPlane 
XCreateColormap 
XCreatePixmapCursor 

526 Xlib Reference Manual 



Table B-2. Xlib Functions and Protocol Requests (continued) 

Protocol Request 
X_CreateGC 

X_CreateGlyphCursor 

X_CreatePixmap 
X_CreateWindow 

X_DeleteProperty 
X_DestroySubwindows 
X_DestroyWindow 
X_FillPoly 
X_ForceScreenSaver 

X_FreeColormap 
X_FreeColors 
X_FreeCursor 
X_FreeGC 
X_FreePixmap 
X_GetAtomName 
X_GetFontPath 
X_GetGeometry 

X_GetImage 
X_GetInputFocus 

X_GetKeyboardControl 
X_GetKeyboardMapping 
X_GetModifierMapping 
X_GetMotionEvents 
X_GetPointerControl 
X_GetPointerMapping 
X_GetProperty 

Xlib Function 

XCreateGC 
XOpen D i splay 
XCreateFontCursor 
XCreateGlyphCu rsor 
XCreatePixmap 
XC reat eS impl eWin dow 
XCreateWindow 
XDeleteProperty 
XDestroySubwindows 
XDestroyWindow 
XFillPolygon 
XAct ivateScreenSaver 
XForceScreenSaver 
XResetScreenSaver 
XFreeColormap 
XFreeColors 
XFreeCursor 
XFreeGC 
XFreePixmap 
XGetAt omName 
XGetFontPath 
XGetGeomet ry 
XGetWindowAt t ribut es 
XGet Image 
XGet InputFocus 
XSync 
XGetKeyboardCont rol 
XGetKeyboardMapping 
XGet Mo di f i e rMappi n g 
XGet Mot i onEvent s 
XGetPointerControl 
XGetPonterMapping 
XClearIconWindow 
XFet chByt e s 

Appendix B: Error Messages and Protocol Requests 527 



Table B-2. Xlib Functions and Protocol Requests (continued) 

Protocol Request 

X_GetScreenSaver 
X_GetSelectionOwner 
X_GetWindowAtibutes 
X_GrabButton 
X_GrabKey 
X_GrabKeyboard 
X_GrabPointer 
X_GrabServer 
X_ImageText8 
X_ImageTextl6 
X_InstallColormap 
X_InternAtom 
X_KillClient 
X_ListExtensions 
X_ListFonts 
X_ListFontsWithI.fo 
X_ListHosts 
X_ListInstalledColormaps 
X_ListProperties 
X_LookupColor 

X_MapSubwindows 
X_MapWindow 

X_NoOperation 
X_OpenFont 

Xlib Function 

XFetchName 
XGetIconSizes 
XGetIconWindow 
XGetNormalHints 
XGetSizeHints 
XGetWindowProperty 
XGetWMHints 
XGetZoomHints 
XGetScreenSaver 
XGetSelectionOwner 
XGetWindowAttributes 
XGrabButton 
XGrabKey 
XGrabKeyboard 
XGrabPointer 
XGrabServer 
XDrawImageString 
XDrawImageStringl6 
XInstallColormap 
XInternAtom 
XKillClient 
XListExtensions 
XListFonts 
XListFontsWithInfo 
XListHosts 
XListInstalledColormaps 
XListProperties 
XLookupColor 
XParseColor 
XMapSubwindows 
XMapRaised 
XMapWindow 
XNoOp 
XLoadFont 
XLoadQueryFont 

528 

Xlib Reference Manual 



Table B-2. Xlib Functions and Protocol Requests (continued) 

Protocol Request 
X_PolyArc 

X_PolyFillArc 

X_PolyFillRectangle 

X_PolyLine 
X_PolyPoint 

X_PolyRectangle 

X_PolySegment 

X_PolyText8 

X_PolyTextl6 

X_PutImage 
X_QueryBestSize 

X_QueryColors 

X_QueryExtension 

X_QuerFont 
X_QueryKeymap 
X_QueryPointer 
X_QueryTextExtents 

X_QueryTree 
X_RecolorCursor 
X_ReparentWindow 
X_RotateProperties 

Xlib Function 

XDrawArc 
XDrawArcs 
XFillArc 
XFillArcs 
XFillRectangle 
XFillRectangles 
XDrawLines 
XDrawPoint 
XDrawPoints 
XDrawRectangle 
XDrawRectangles 
XDrawLine 
XDrawSegments 
XDrawString 
XDrawText 
XDrawStringl6 
XDrawTextl6 
XPutImage 
XQueryBestCursor 
XQueryBestSize 
XQueryBestStipple 
XQueryBestTile 
XQueryColor 
XQueryColors 
XInitExtension 
XQueryExtension 
XLoadQueryFont 
XQueryKeymap 
XQueryPointer 
XQueryTextExtents 
XQueryTextExtentsl6 
XQueryTree 
XRecolorCursor 
XReparentWindow 
XRotateBuffers 
XRotateWindowProperties 

Appendix B: Error Messages and Protocol Requests 529 



Table B-2. Xlib Functions and Protocol Requests (continued) 

Protocol Request 

X_SendEvent 
X_S etAccessControl 

X_S etClipRectangles 
X_SetCloseDownMode 
X_SetDashes 
X_SetFontPath 
X_SetlnputFocus 
X_SetModifierMapping 
X_SetPointerMapping 
X_SetScreenSaver 
X_S etSelectionOwner 
X_StoreColors 

X_StoreNamedColor 
X_TranslateCoords 
X_UngrabButton 
X_UngrabKey 
X_UngrabKeyboard 
X_UngrabPointer 
X_UngrabServer 
X_UninstallColormap 
X_UnmapSubwindows 
X_UnmapWindow 
X_WarpPointer 

Xlib Function 

XSendEvent 
XDisableAccessControl 
XEnableAccessControl 
XSetAccessControl 
XSetClipRectangles 
XSetCloseDownMode 
XSetDashes 
XSetFontPath 
XSetInputFocus 
XSetModifierMapping 
XSetPointerMapping 
XSetScreenSaver 
XSetSelectionOwner 
XStoreColor 
XStoreColors 
XStoreNamedColor 
XTranslateCoordinates 
XUngrabButton 
XUngrabKey 
XUngrabKeyboard 
XUngrabPointer 
XUngrabServer 
XUninstallColormap 
XUnmapSubWindows 
XUnmapWindow 
XWarpPointer 

530 Xlib Reference Manual 



D e f au it Co 1 o rmap ( di spl ay, s cr_n urn) 

DefaultColormapOfScreen(scr_pnt) 

DefaultDepth(di splay, scr_num) 

DefaultDepthOfScreen(scr_pnt) 
DefaultGC(display, scr_num) 

DefaultGCOfScreen(scr_pnt) 

DefaultRootWindow(display) 

DefaultScreen(display) 

Default ScreenOfDi splay(di splay) 

DefaultVisual(display, scr_num) 

DefaultVisualOfScreen(scr_pnt) 
DisplayCells(display, scr_num) 

D i s pl ayHe i ght ( di spl ay, s cr_n urn) 

DisplayHeightMM(display, scr_num) 

Return the default colormap for the specified 
screen. Most routine allocations of color should 
be made out of this colormap. 
Return the default colormap of the specified 
screen. 
Return the depth (number of planes) of the root 
window for the specified screen. Other depths 
may also be supported on this screen. See 
Volume One, Chapter 7, Color, or the reference 
pages for XMatchVisualInfo and XGet- 
VisualInfo 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 
specified 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 : 0.1 then 
DefaultScreen would return 1. 
Return the default screen of the specified 
display. 
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 ScreenCells. 
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 S c reenHeightMM. 

532 Xlib Reference Manual 



I s Modi f i e rK ey (k eysym) 
I sPFKey(keysym) 

Return T rue if the keysym represents a modifier key. 
Return T rue if the keysym represents a PF key. 

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. 
XrmSt ringToName (string) 

XrmSt ringToCla s s (string) 

XrmStringToRepresentation 
(string) 

XrmNameToSt ring (name) 

XrmClassToString(class) 

XrmRepresentationToString 
(type) 

Convert sng to XrmName. Same  XStringTo- 
Quark. 
Convertsngto XrmClass. Same  XStringTo- 
Quark. 
Convert sng  XrmRepresentation. Same 
XStringToQuark. 
Convert XrmName  sng. Same  XrmQuarkTo- 
String. 
Convt xrmClass  sng. Same  XrmQuark- 
ToString. 
Convert XrmRepresentation to sng. Same 
XrmQuarkToString. 

536 Xhb Reference Manual 



D 
The Color Database 

The color database is used by XParseColor, XLookupColor, and XStoreNamed- 
Color. 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 
/usr/lib/X1 l /rgb.txt. 
It should be noted that while these color names are present in the standard X 11 distribution, 
they are not specified by the Xll Protocol or Xlib. Therefore, it is permissible for server 
vendors to change the color names, though most will probably only add colors rather than 
take them away. Furthermore, hardware vendors must 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 standard file are for the DEC 
VR290 display. The color that appears on a Sun system given these RGB values for 
"pink," for example, looks more like light burgundy. 
Each color in Table D-1 (see next page) may be used in the form shown or in mixed case, 
with initial capitals and all spaces eliminated. 

Appendix D: Colors 537 



E 
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-1 lists each event mask, its associated event types, and the associated structure 
definition. See Volume One, Chapter 8, Events for more information on events. 

Table E-1. Event Masks, Event Types, and Event Structures 

Event Mask 

KeyPressMask 
KeyReleaseMask 
ButtonPressMask 

ButtonReleaseMask 

OwnerGrabButtonMask 

KeymapStateMask 
PointerMotionMask 
PointerMotionHintMask 
ButtonMotionMask 
ButtonlMotionMask 
Button2MotionMask 
Button3MotionMask 
Button4MotionMask 
Button5MotionMask 

Event Type 

KeyP re s s 
KeyRelease 
ButtonPress 
ButtonRelease 
n/a 
Keyma pNot i fy 
Mot ionNot i fy 

S tructure 

XKeyPressedEvent 
XKeyReleasedEvent 
XButtonPressedEvent 
XButtonReleasedEvent 
n 
XKeymapEvent 
XPointerMovedEvent 

EnterWindowMask 
LeaveWindowMask 
FocusChangeMask 

ExposureMask 

EnterNotify 
LeaveNotify 
FocusIn 
FocusOut 
Expose 

XEnterWindowEvent 
XLeaveWindowEvent 
XFocusInEvent 
XFocusOutEvent 
XExposeEvent 

Appendix E: Event Reference 539 



Table E-1. Event Masks, Event Types, and Event Structures (continued) 

Event Mask 

selected  GC by 
graphics_expose member) 
ColormapChangeMask 
PropertyChangeMask 
VisibilityChangeMask 
ResizeRedirectMask 
StructureNotifyMask 

SubstructureNotifyMask 

SubstructureRedirectMask 

(always selected) 
(always selected) 
(always selected) 
(always selected) 
(always selected) 

Event Type 

GraphicsExpose 
NoExpose 
ColormapNotify 
PropertyNotify 
VisibilityNotify 
ResizeRequest 
CirculateNotify 
ConfigureNotify 
DestroyNotify 
GravityNotify 
MapNotify 
ReparentNotify 
UnmapNotify 
CirculateNotify 
ConfigureNotify 
CreateNotify 
DestroyNotify 
GravityNotify 
MapNotify 
ReparentNotify 
UnmapNotify 
CirculateRequest 
ConfigureRequest 
MapRequest 
MappingNotify 
ClientMessage 
SelectionClear 
SelectionNotify 
SelectionRequest 

Structure 

XGraphicsExposeEvent 
XNoExposeEvent 

XColormapEvent 

XP rope rt yEvent 

XVisibilityEvent 

XResizeRequestEvent 

XCirculateEvent 
XConfigureEvent 
XDestroyWindowEvent 
XGravityEvent 
XMapEvent 
XReparentEvent 
XUnmapEvent 

XCirculateEvent 
XConfigureEvent 
XCreateWindowEvent 
XDestroyWindowEvent 
XGravityEvent 
XMapEvent 
XReparentEvent 
XUnmapEvent 

XCirculateRequestEvent 
XConfigureRequestEvent 
XMapRequestEvent 

XMappingEvent 

XClientMessageEvent 
XSetSelectClearEvent 

XSelectionEvent 

XSelectionRequestEvent 

540 

Xlib Reference Manual 



Meaning of Common Structure Elements 

Example E-1 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 
Volume One, Section 8.2.2). 

Example E- 1. XEvent union and XAnyEvent structure 

typedef union XEvent { 
int type; /* must not be changed; first member */ 
XAnyEvent xany; 
XButtonEvent xbutton; 
XCirculateEvent xcirculate; 
XCirculateRequestEvent xcirculaterequest; 
XClientMessageEvent xclient; 
XColormapEvent xcolormap; 
XConfigureEvent xconfigure; 
XConfigureRequestEvent xconfigurerequest; 
XCreateWindowEvent xcreatewindow; 
XDestroyWindowEvent xdestroywindow; 
XCrossingEvent xcrossing; 
XExposeEvent xexpose; 
XFocusChangeEvent xfocus; 
XNoExposeEvent xnoexpose; 
XGraphicsExposeEvent xgraphicsexpose; 
XGravityEvent xgravity; 
XKeymapEvent xkeymap; 
XKeyEvent xkey; 
XMapEvent xmap; 
XUnmapEvent xunmap; 
XMappingEvent xmapping; 
XMapRequestEvent xmaprequest; 
XMotionEvent xmotion; 
XPropertyEvent xproperty; 
XReparentEvent xreparent; 
XResizeRequestEvent xresizerequest; 
XSelectionClearEvent xselectionclear; 
XSelectionEvent xselection; 
XelectionRequestEvent xselectionrequest; 
XVisibilityEvent xisibility; 
} XEvent; 

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; /* window on which event was requested in 
* event mask */ 
} XAnyEvent; 

Appendix E: Event Reference 541 



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'll 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 don't are selection 
events (SelectionNotify, SelectionRequest, and SelectionClear) 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 Volume One, Section 8.3.2. 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 pro- 
grams only use a single screen and therefore don't 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 number 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 alpha- 
betical 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 
programming 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. 

542 Xlib Reference Manual 



CirculateRequest 

xcirculaterequest-- 

When Generated 

CirculateRequest events report when another client calls XCirculateSubwindows, 
XCirculateSubwindowsUp or XCirculateSubwindowsDown for a specified parent 
window, and the stacking order is actually changed. If this event type is selected, the window 
is not moved in the stacking order. This gives the client that selects this event (usually the 
window manager) the opportunity to review the request in the light of its window management 
policy, before executing the circulate request itself, or deny the request. 

Select With 
This event type is selected for the parent window with the SubstructureRedirectMask. 

XEvent Structure Name 
typedef union XEvent { 
-- 
.oo 
XCirculateRequestEvent xcirculaterequest; 
o o . 
} 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 
pa rent 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 top or on the bottom of the stacking order. 

546 Xhb Reference Manual 



EnterNotify, LeaveNotify (continued) xcrossing 

Table E-2 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-2. 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 (B) 
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-3 lists the detail members in events generated by a pointer crossing from window 
A to window B. 

Table E-3. Event detail Member and Window Relationship 

detail Fla 
NotifyAncestor 
NotifyInferior 
NotifyVirtual 

NotifyNonlinear 

NotifyNonlinearVirtual 

Window Delivered To 

Origin or destination when either is descendant 
Origin or destination when either is ancestor 
Windows between A and B exclusive if either is des- 
cendant 
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. 

558 Xlib Reference Manual 



xcrossing (continued) EnterNotify, LeaveNotify 

For example, Figure E-1 shows the events that are generated by a movement from a window 
(window A) to a child (window B1) of a sibling (window B). This would generate three 
events: a LeaveNotify with detail NotifyNonlinear for the window A, an EnterNo- 
tify with detail NotifyNonlinearVirtual for its sibling window B, and an Enter- 
Notify with detail NotifyNonlinear for the child (window BI). 

RootWindow 
(no event) 

A 
LeaveNotify event with 
detail NotifyNonlinear 

AI 
no event 

EnterNotify event with 
ietail Not i fyNonlinearVirtual 
LeaveNotify event with 
detail Not ifyNonlinear 

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 EnterNot i fy and the window containing the pointer receives a LeaveNot i fy 
event, both with mode NotifyUngrab. 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 Ente rNot i fy instead of LeaveNot i fy and vice versa. 

Appendix E: Event Reference 559 



EnterNotify, LeaveNotify (continued) xcrossing 

Figure E-2 demonstrates the events and details caused by various pointer transitions, indicated 
by heavy arrows. 

Notify  
:.ferxor  '! -- _ _ Inferl* 

Root of A Root of B 

Y_ 
=r 

Figure E-2. Border crossing events and detail member for pointer movement 
from window A to window B, for various window relationships 

56O 

Xlib Reference Manual 



Expose (continued) xexpose 

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. 

562 

Xlib Reference Manual 



Focusln, FocusOut (continued) xfocus 

Table E-5 lists the detail members in events generated by a focus transition from window A 
to window B, with P being the window containing the pointer. 

Table E-5. Event detail Member and Window Relationship 

detail ag 
NotifyAncestor 
Notifylnferior 
NotifyVirtual 

NotifyNonlinear 

NotifyNonlinearVirtual 

NotifyPointer 

NotifyPointerRoot 

NotifyNone 

Window Delivered To 

Origin or destination when either is descendant 
Origin or destination when either is ancestor 
Windows between A and B exclusive if either is des- 
cendant 
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 

The following two pages show 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 member. 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, windows 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. 

566 Xlib Reference Manual 



--xgravity 

GravityNotify 

When Generated 

GravityNotify events report 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 UnraapGravity. 

Select With 
To receive this event type for a single window, specify the window ID of that window and use 
StructureNotifyMask as pa of the event_mask argument to XSelectInput. To 
receive notification of movement due to gravity for a group of siblings, specify the parent win- 
dow ID and use SubstructureNotifyMask. 

XEvent Structure Name 
typedef union XEvent { 
XGravityEvent xgravity; 
o . o 
} XEvent; 

Event Structure 

typedef struct { 
int type; 
unsigned long serial;/* # of last request processed by server */ 
Bool send event; 
Display *display; 
Window event; 
Window window; 
int x, y; 
} XGravityEvent; 

/* true if this came from SendEvent request */ 
/* display the event was read from */ 

Event Structure Members 
event The window that selected the event. 
winow The window that was moved. 
x, y The new coordinates of the window relative to its parent 

Appendix E: Event Reference 571 



MapNotify, UnmapNotify (continued) xmap, xunmap 

from_configure (XUnmapEvent only) 
True  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 Volume One, Section 4.3.4. 
False otherwise. 

576 

Xlib Reference Manual 



MappingNotify (continued) xmapping 

first_keycode 
If the request member is MappingKeyboard or MappingModifier, then 
first_keycode indicates the first in a range of keycodes with altered map- 
pings. Otherwise it is not set. 

count 

If the request member is MappingKeyboard or MappingModifier, then 
count indicates the number of keycodes with altered mappings. Otherwise it is 
not set. 

Notes 

If the request member is MappingKeyboa rd, clients should call XRe f re shKeyboa rd- 
Mapping. 

The normal response to a request member of MappingPointer or MappingModifier 
is no action. This is because the clients should use the logical mapping of the buttons and 
modifiers to allow the user to customize the keyboard if desired. If the application requires a 
particular mapping regardless of the user's prefcrences, it should call XGetModifierMap- 
ping or XGetPointerMapping to find out about the new mapping. 

578 

Xlib Reference Manual 



xmotion (continued) MotionNotify 

When active button grabs and pointer grabs are in effect (see Volume One, Sec- 
tion 9.4), the coordinates relative to the receiving window may not be within 
the window (they may be negative 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, Button3Mask, Button4Mask, Button5Mask, Shift- 
Mask, ControlMask, LockMask, ModlMask, Mod2Mask, Mod3Mask, 
Mod4Mask, and Mod5Mask. 
is hint Either the constant NotifyNormal or NotifyHint. NotifyHint indi- 
cates that the PointerMotionHintMask was selected. In this case, just 
one event is sent when the mouse moves, and the current position can be found 
by calling XQueryPointer, or by examining the motion history buffer with 
XGetMotionEvents, if a motion history buffer is available on the server. 
NotifyNormal indicates that the event is real, but it may not be up to date 
since there may be many more later motion events on the queue. 
same screen 
-- 
Indicates whether the pointer is currently on the same screen as this window. 
This is always True unless the pointer was actively grabbed before the 
automatic grab could take place. 

Notes 
If the processing you have to do for every motion event is fast, you can probably handle all of 
them without requiring motion hints. However, if you have extensive processing to do for 
each one, you might be better off using the hints and calling XQueryPointer or using the 
history buffer if it exists. XQueryPointer is a round-trip request, so it can be slow. 
EnterNotify and LeaveNotify events are generated instead of MotionEvents if the 
poin{er starts and stops in different windows. 

Appendix E: Event Reference 581 



xvisibility (continued) VisibilityNotify 

Table E-6. The State Element of the XVisibilityEvent Structure 

Visibility Status Before 
Partially obscured, 
fully obscured, 
or not viewable 
Viewable and 
completely unobscured, 
or not viewable 
Viewable and 
completely unobscured, 
or viewable and 
partially obscured, 
or not viewable 

Visibility Status After 
Viewable and com- 
pletely unobscured 

Viewable and partially 
obscured 

Viewable and partially 
obscured 

State Member 

Visibility- 
Unobscured 

VisibilityPartially- 
Obscured 

VisibilityPartially- 
Obscured 

Appendix E: Event Reference 589 



F 
Structure Reference 

This appendix describes the contents of the include files for Xlib. 

Description of Contents 

All include files are normally located in lusr/include/Xll. All Xlib programs require 
<Xll/Xlib.h>, which includes <Xll/X.h>. <Xll/Xlib.h> contains most of the structure 
declarations, while <Xll/X.h> contains most of the defined constants. Virtually all pro- 
grams will also require <Xll/Xutil.h>, which include structure types and declarations appli- 
cable to window manager hints, colors, visuals, regions, standard geometry strings, and 

images. 
Here is a summary of 
<Xl l /Xlib.h> 
<Xll/X.h> 
<Xl l /Xutil.h> 

<Xl l lXatom.h> 
<Xl l /cursorfont.h> 

<Xl l /keysym.h> 

<X11/Xreso urce. h > 

the contents of the include files: 
structure declarations for core Xlib functions. 
constant definitions for Xlib functions. 
additional structure types and constant definitions for miscellaneous 
Xlib functions. 
the predefined atoms for properties, types, and font characteristics. 
the constants used to select a cursor shape from the standard cursor 
font. 
predefined key symbols corresponding to keycodes. It includes 
<Xl l /keysymdef .h>. 
resource manager structure definitions and function declarations. 

Appendix F: Structure Reference 591 



Resource Types 

The following types are defined in <Xll/X.h>: 

unsigned long XID 
XID Colormap 
XID Cursor 
XID Drawable 
XID Font 
XID GCont ext 
XID KeySym 
XID Pixmap 
XID Window 
unsigned long Atom 
unsigned char KeyCode 
unsigned long Mask 
unsigned long Time 
unsigned long VisualID 

Structure Definitions 

This section lists all Xlib structure definitions in xlib.h and xutil .h, in alphabetical 
order, except the event structures which are listed separately in the next section. 

Note that the first few structure types do not begin with X. These structures are intended to 
be opaque, so that Xlib's authors are free to change them in later releases. You are 
discouraged from accessing their members directly. However, only the GC structure is 
dangerous to access, because of the way GCs are implemented. 

Before each structure is a description of what the structure is used for and a list of the Xlib 
routines that use the structure. 

Depth 

Depth defines a valid depth and list of associated visuals. A list of these structures is con- 
mined in the Screen structure, which is itself a member of the Display structure. Not 
used directly in any Xlib function. This structure should not be accessed directly, but 
instead through XGetVisualInfo and XMatchVisualInfo. 

typedef struct { 
int depth; 
int nvisuals; 
Visual *visuals; 
} Depth; 

/* this depth (Z) of the depth */ 
/* number of Visual types at this depth */ 
/* list of visuals possible at this depth */ 

592 Xlib Reference Manual 



Display 

Display describes the connection to the X server. A pointer to a structure of this type is 
returned by XOpenDisplay, and is subsequently the first argument to nearly every Xlib 
routine. Macros are provided to access most members of this structure. 

* Display datatype maintaining display specific data. 

*/ 
typedef struct _XDisplay { 
XExtData *ext data; /* 
-- 
struct _XDisplay *next; /* 
int fd; /* 
int lock; /* 
int proto_major_version; /* 
int proto_minor_version; /* 
char *vendor; /* 
long resource base; /* 
-- 
long resource mask; /* 
-- 
long resource id; /* 
-- 
int resource shift; /* 
-- 
XID (*resource alloc) (); /* 
-- 
int byte_order; /* 
int bitmap_unit; /* 
int bitmap_pad; /* 
int bitmap_bit_order; /* 
int nformats; /* 
ScreenFormat *pixmap_format; /* 
int vnumber; /* 
int release; /* 
struct XSQEvent *head, *tail;/* 
-- 
int qlen; /* 
int last_request_read; /* 
int request; /* 
char *last_req; /* 
char *buffer; /* 
char *bufptr; /* 
char *bufmax; /* 
unsigned max_request_size; /* 
struct XrmHashBucketRec *db; 
-- 
int (*synchandler) (); /* 
char *display_name; /* 
int default screen; /* 
-- 
int nscreens; /* 
Screen *screens; /* 
int motion buffer; /* 
-- 
Window current; /* 
int min_keycode; /* 
int max_keycode; /* 
KeySym *keysyms; /* 
XModifierKeymap *modifiermap;/* 
int keysyms_per_keycode; /* 
char *xdefaults; /* 
char *scratch buffer; /* 
-- 
unsigned long scratch_length;/* 
int ext number; /* 
-- 

hook for extension to hang data */ 
next open Display on list */ 
network socket */ 
is someone in critical section? */ 
major version of server's X protocol */ 
minor version of servers X protocol */ 
vendor of the server hardware */ 
resource ID base */ 
resource ID mask bits */ 
allocator current ID */ 
allocator shift to correct bits */ 
allocator function */ 
screen byte order, LSBFirst, MSBFirst */ 
padding and data requirements */ 
padding requirements on bitmaps */ 
LeastSignificant or MostSignificant */ 
number of pixmap formats in list */ 
pixmap format list */ 
Xlib's X protocol version number */ 
release of the server */ 
input event queue */ 
length of input event queue */ 
sequence number of last event read */ 
sequence number of last request */ 
beginning of last request, or dummy */ 
output buffer starting address */ 
output buffer index pointer */ 
output buffer maximum+l address */ 
maximum number 32 bit words in request*/ 

synchronization handler */ 
"host:display" string used on this connect*/ 
default screen for operations */ 
number of screens on this server*/ 
pointer to list of screens */ 
size of motion buffer */ 
for use internally for Keymap notify */ 
minimum defined keycode */ 
maximum defined keycode */ 
this server's keysyms */ 
this server's modifier keymap */ 
number of rows */ 
contents of defaults from server */ 
place to hang scratch buffer */ 
length of scratch buffer */ 
extension number on this display */ 

Appendix F: Structure Reference 593 



XExtension *ext_procs; /* extensions initialized on this display */ 
-- 
/* 
* the following can be fixed size, as the protocol defines how 
* much address space is available. 
* While this could be done using the extension vector, there 
* may be MANY events processed, so a search through the extension 
* list to find the right procedure for each event might be 
* expensive if many extensions are being used. */ 

Bool (*event vec[128]) () ; 
-- 
Status (*wire vec[128]) (); 
-- 
} Display; 

/* vector for wire to event */ 
/* vector for event to wire */ 

GC 

GC describes a graphics context. A pointer to a structure of this type is returned by 
XCreateGC and subsequently used in all routines that draw or modify the GC. The 
members of this structure must not be accessed directly. 

typedef struct XGC { 
-- 
XExtData *ext data; 
-- 
GContext gid; 
Bool rects; 
Bool dashes; 
unsigned long dirty; 
XGCValues values; 
} *GC; 

/* hook for extension to hang data */ 
/* protocol ID for graphics context */ 
/* Boolean: TRUE if clipmask is list of rectangles */ 
/* Boolean: TRUE if dash-list is really a list */ 
/* cache dirty bits */ 
/* shadow structure of values */ 

Screen 

Screen describes the characteristics of a screen. A pointer to a list of these structures is a 
member of the Display structure. A pointer to a structure of this type is returned by 
XGetWindowAttributes. Macros are provided to access most members of this struc- 
ture. 

typedef struct { 
XExtData *ext_data; 
struct _XDisplay *display; 
Window root; 
int width, height; 
int mwidth, mheight; 
int ndepths; 
Depth *depths; 
int root_depth; 
Visual *root_visual; 
GC default_gc; 
Colormap cmap; 
unsigned long white_pixel; 
unsigned long black_pixel; 

/* hook for extension to hang data */ 
/* back pointer to display structure */ 
/* root window ID */ 
/* width and height of screen */ 
/* width and height of in millimeters */ 
/* number of depths possible */ 
/* list of allowable depths on the screen */ 
/* bits per pixel */ 
/* root visual */ 
/* GC for the root root visual */ 
/* default colormap */ 

/* white and black pixel values */ 

594 
Xlib Reference Manual 



XArc 

XArc specifies the bounding box for an arc and two angles indicating the extent of the arc 
within the box. A list of these structures is used in XDrawArcs and XFillArcs. 

typedef struct { 
short x, y; 
unsigned short width, height; 
short anglel, angle2; 
} XArc; 

XChar2b 

XChar2b specifies a character in a two-byte font. A list of structures of this type is an 
argument to XDrawlmageStringl6, XDrawStringl6, XDrawTextl6, XQuery- 
TextExtentsl6, XTextExtentsl6, and XTextWidthl6. The only two-byte font 
currently available is Kanji (Japanese). 

typedef struct { 
unsigned char bytel; 
unsigned char byte2; 
} XChar2b; 

/* normal 16 bit characters are two bytes */ 

XCharStruct 

XCharStruct describes the metrics of a single character in a font, or the overall charac- 
teristics of a font. This structure is the type of several of members of XFontStruct, and 
is used to return the overall characteristics of a string in XQueryTextExtents* and 
XText Extent s *. 

typedef struct { 
short ibearing; 
short rbearing; 
short width; 
short ascent; 
short descent; 
unsigned short attributes; 
} XCharStruct; 

/* origin to left edge of raster */ 
/* origin to right edge of raster */ 
/* advance to next char's origin */ 
/* baseline to top edge of raster */ 
/* baseline to bottom edge of raster */ 
/* per char flags (not predefined) */ 

596 Xlib Reference Manual 



XExtCodes 

XExtCodes is a smacture used by the extension mechanism. This structure is returned by 
xInitExtension which is not a standard Xlib routine but should be called within the 
extension code. Its contents are not normally accessible to the application. 

typedef struct { 
int extension; 
int major_opcode; 
int first event; 
int first error; 
} XExtCodes; 

/* public to extension, cannot be changed */ 
/* extension number */ 
/* major opcode assigned by server */ 
/* first event number for the extension */ 
/* first error number for the extension */ 

XExtData 

XExtData provides a way for extensions to attach private data to the existing structure 
types GC, Visual, Screen, Display, and XFontStruct. This structure is not used in 
normal Xlib programming. 

typedef struct XExtData { 
int number; 
struct XExtData *next; 
int (*free_private) (); 
char *private_data; 
} XExtData; 

/* number returned by XRegisterExtension */ 
/* next item on list of data for structure */ 
/* called to free private storage */ 
/* data private to this extension */ 

XFontProp 

XFontProp is used in XFontStruct. This structure allows the application to find out 
the names of additional font properties beyond the predefined set, so that they too can be 
accessed with XGetFontProperty. This structure is not used as an argument or return 
value for any core Xlib function. 
typedef struct { 
Atom name; 
unsigned long card32; 
} XFontProp; 

598 Xlib Reference Manual 



XFontStruct 

XFontStruct specifies metric information for an entire font. This structure is filled with 
the XLoadQueryFont and XQueryFont routines. ListFontsWithInfo also fills it 
but with metric information for the entire font only, not for each character. A pointer to this 
sucture is used in the routines XFreeFont, XFreeFontInfo, XGetFontProp, 

XTextExtents*, and XTextWidth*. 

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; 
} XFontStz-uct; 

/* hook for extension to hang data */ 
/* font ID for this font */ 
/* 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 */ 

XGCValues 

XGCValues is used to set or change members of the GC by the routines XCreateGC and 

XChangeGC. 
typedef struct ( 
int function; 
unsigned long plane_mask; 
unsigned long foreground; 
usigned long backgrgund; 
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; 
int ts_y_origin; 
Font font; 
int subwindow mode; 
-- 
Bool graphics_exposures; 
int clip_x_origin; 

/* logical operation */ 
/* plane mask */ 
/* foreground pixel */ 
/* background pixel */ 
/* line width */ 
/* LineSolid, LineOnOffDash, LineDoubleDash */ 
/* CapNotLast, CapButt, CapRound, CapProjecting */ 
/* JoinMiter, JoinRound, JoinBevel */ 
/* FillSolid, FillTiled, FillStippled */ 
/* EvenOddRule, WindingRule */ 
/* ArcPieSlice, ArcChord */ 
/* tile pixmap for tiling operations */ 
/* stipple 1 plane pixmap for stippling */ 
/* offset for tile or stipple operations */ 

/* default text font for text operations */ 
/* ClipByChildren, IncludeInferiors */ 
/* Boolean, should exposures be generated */ 
/* origin for clipping */ 

Appendix F: Structure Reference 599 



int clip y origin; 
Pixmap clip_mask; 
int dash offset; 
-- 
char dashes; 
} XGCValues; 

/* bitmap clipping; other calls for rects */ 
/* patterned/dashed line information */ 

XHostAddress 

XHostAddress specifies the address of a host machine that is to be added or removed 
from the host access list for a server. Used in XAddHost, XAddHosts, XListHosts, 
XRemoveHost, and XRemoveHosts. 
typedef struct { 
int family; /* for example FAMILY INTERNET */ 
-- 
int length; /* length of address, in bytes */ 
char *address; /* pointer to where to find the bytes */ 
} XostAddress ; 

XlconSize 

XlconSize is used to set or read the XA_WM_ICON_SIZE property. This is normally set 
by the window manager with xSetrconSizes arid read by each application with XGet- 
IconSizes. 

typedef struct { 
int min_width, min_height; 
int max_width, max_height; 
int width_inc, height_inc; 
} XIconSize; 

Xlmage 

Xlmage describes an area of the screen. As you can tell from the funcs member, this 
structure is used in XCreatelmage, XDestroyImage, XGetPixel, XPutPixel, 
XSubImage, and XAddPixel. It is also used in XGetImage, XGetSubImage and 
XPut Image. 

typedef struct _XImage { 
int width, height; 
int xoffset; 
int format; 
char *data; 
int byte_order; 
int bitmap_unit; 
int bitmap_bit_order; 

/* 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 */ 

600 

Xlib Reference Manual 



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 ( 

/* 8, 16, 32 either XY or ZPixmap */ 
/* depth of image */ 
/* accelerator to next line */ 
/* bits per pixel (ZPixmap) */ 
/* bits in z arrangement */ 

/* hook for the object routines to hang on */ 
/* 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; 

XKeyboardControl 

XKeyboardControl is used to set user preferences with XChangeKeyboard- 
Control. 

typedef struct 
int key_click_percent; 
int bell_percent; 
int bell_pitch; 
int bell duration; 
-- 
int led; 
int led mode; 
-- 
int key; 
int auto_repeat_mode; 

} XKeyboardControl; 

/* AutoRepeatModeOn, AutoRepeatModeOff, 
* AutoRepeatModeDefault */ 

xKeyboardState 

XKeyboardState is used to return the current settings of user preferences with XGet- 
Keyboa rdCont ro i. 
t ypede f 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; 

Appendix F: Structure Reference 601 



XModifierKeymap 

XModifierKeymap specifies which physical keys are mapped to modifier functions. This 
structure is returned by XGetModifierMapping, and is an argument to XDelete- 
ModifiermapEntry, XFreeModifiermap, InsertModifiermapEntry, XNew- 
Modifiermap, and XSetModifierMapping. 
typedef struct { 
int max_keypermod; /* server's max # of keys per modifier */ 
KeyCode *modifiermap; /* an 8 by max_keypermod array of modifiers */ 
} XModifierKeymap; 

XPoint 

XPoint specifi the coordinates of a point. Used in XDrawPoints, XDrawLines, 
XFillPolygon, and XPolygonRegion. 
typedef struct { 
short x, y; 
} XPoint; 

XRectangle 

XRectangle specifies a rectangle. Used in XClipBox, XDrawRectangles, XFill- 
Rectangles, XSetClipRectangles, and XUnionRectWithRegion. 
typedef struct { 
short x, y; 
unsigned short width, height; 
} XRectangle; 

XSegment 

XSegment specifies two poinm. Used in XDrawSegments. 
typedef struct { 
short xl, yl, x2, y2; 
} XSegment; 

602 

Xlib Reference Manual 



XSetWindowAttributes 

XSetWindowAttributes contains all the attributes that can be set without window 
manager inenfion. Used in XChangeWindowAttributes and XCreatewindow. 

typedef struct { 
Pixmap background_pixmap; /* 
unsigned long background_pixel;/* 
Pixmap border_pixmap; /* 

unsigned long border_pixel; 
int bit_gravity; 
int win_gravity; 
int backing_store; 
unsigned long backing_planes; 
unsigned long backing_pixel; 
Bool save under; 
long event mask; 
long do_not_propagate_mask; 

Bool override redirect; 
Colormap colormap; 
Cursor cursor; 
} XSetWindowAttributes; 

background or None or ParentRelative */ 
background pixel */ 
border of the window */ 
/* border pixel value */ 
/* one of bit gravity values */ 
/* one of the window gravity values */ 
/* NotUseful, WhenMapped, Always */ 
/* planes to be preserved if possible */ 
/* value to use in restoring planes */ 
/* should bits under be saved? (popups) */ 
/* set of events that should be saved */ 
/* set of events that should not */ 
* propagate */ 
/* Boolean value for override-redirect */ 
/* colormap to be associated with window */ 
/* cursor to be displayed (or None) */ 

XSizeHints 

XSizeHints describes a range of preferred sizes and aspect ratios. Used to set the 
XA WM NORMAL HINTS and XA WM ZOOM HINTS properties for the window manager 
with XSetNormalHints, XSetZoomHints, XSetStandardProperties or XSet- 
SizeHints. A|so used in reading these properties with XGetSizeHints, XGet- 
NormalHints, or XGetZoomHints. 

typedef struct { 
long flags; 
int x, y; 
int width, height; 
iDt min_width, min_hight; 
int max_width, max_height; 
int width_inc, height_inc; 
struct 
int x; 
int y; 
} min_aspect, max_aspect; 
} XSizeHints; 

/* marks defined fields in structure */ 

/* numerator */ 
/* denominator */ 

Appendix F: Structure Reference 603 



XStandardColormap 

XStandardColormap describes a standard colormap, giving its ID and its color charac- 
teristics. This is the format of the standard colormap properties set on the root window, 
which can be changed with XSetStandardProperties and changed with XGet- 
St anda rdP ropert ies. 

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; 

XTextltem 

XTextItem describes a string, the font to print it in, and the horizontal offset from the pre- 
vious string drawn or from the location specified by the drawing command. Used in 
XDrawText. 

typedef struct { 
char *chars; 
int nchars; 
int delta; 
Font font; 
} XTextItem; 

/* pointer to string */ 
/* number of characters */ 
/* delta between strings */ 
/* font to print it in, None don't change */ 

X'l'extltem16 

XTextItem16 describes a string in a two-byte font, the font to print it in, and the horizon- 
tal offset from the previous string drawn or from the location specified by the drawing com- 
mand. Used in XDrawText 16. 

typedef struct { 
XChar2b *chars; 
int nchars; 
int delta; 
Font font; 
} XTextIteml6; 

/* two-byte characters */ 
/* number of characters */ 
/* delta between strings */ 
/* font to print it in, None don't change */ 

604 

Xlib Reference Manual 



XWindowAttributes 

XWindowAttributes describes the complete set of window attributes, including those 
that can't be set without window manager interaction. This structure is returned by XGet- 
WindowAttributes. It is not used by XChangeWindowAttributes or XCreate- 
Window. 

typedef struct { 
int x, y; 
int width, height; 
int border width; 
-- 
int depth; 
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; 

/* location of window */ 
/* width and height of window */ 
/* border width of window */ 
/* depth of window */ 
/* 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 */ 
/* events all people have interest in*/ 
/* my event mask */ 
/* set of events that should not propagate */ 
/* Boolean value for override-redirect */ 

XWindowChanges 

XWindowChanges descfbes a configuration for a window. Used in XConfigure- 
Window, which can change the screen layout and therefore can be intercepted by the win- 
dow manager. This se some of the remaining members of XWindowAttributes that 
cannot be set with XChangeWindowAttributes or XCreateWindow. 
typedef struct { 
int x, y; 
int width, height; 
int border_width; 
Window sibling; 
int stack_mode; 
} XWindowChanges; 

606 

Xlib Reference Manual 



G 
Symbol Reference 

This appendix presents an alphabetical listing of the symbols used in X. The routines in 
parentheses following the descriptions indicate the routines associated with those symbols. 

A 
_Above 
AllHints 

AllTemporary 
AllValues 
AllocAll 
AllocNone 
AllowExposures 
AlreadyGrabbed 
Always 

AnyButton 

AnyKey 
AnyModifier 

AnyPropertyType 
ArcChord 
ArcPieSlice 

AsyncBoth 
AsyncKeyboard 
AsyncPointer 
AutoRepeatModeDefault 

AutoRepeatModeOff 

AutoRepeatModeOn 

stocking method (XConfigureWindow) 
XA WM HINTS propeny, all membes set 
(XGetWMHint s, XSetWMHint s) 
resource ID passed to XKillClient 
mask used by XParseGeometry, returns those set by user 
allocate entire map writable (XCreateColormap) 
create map with no entries (XCreateColormap) 
screen saver (XSet SreenSave r, XGet Sc reenSave r) 
XGrabPointer, XGrabKeyboard return Status 
ba eking_st ore attribute 
(XCreateWindow, XChangeWindowAt t ribut e s) 
button name for XGrabButton, or for ButtonPress or 
ButtonRelease del 
keycode for XGrabKey 
modifier key mask for XGrabButton, XGrabKey, results of 
XQueryPointer, event state 
atom for XGetProperty 
arc_mode in GC, join endpoints of arc (XFillArcs) 
arc mode  GC, join endpoints to center of arc 
-- 
(XFillArcs) 
XA 11 owEvent s mode 
XA 11 owEvent s mode 
XAI 1 owEvent s mode 
keyboard preferences 
(XChangeKeyboardCont rol, XGetKeyboardCont rol) 
keyboard preferences 
(XChangeKeyboardCont rol, XGetKeyboa rdCont rol) 
keyboard preferences 
(XChangeKeyboardCont rol, XGetKeyboardCont rol) 

Appendix G: Symbol Reference 607 



B 
BadAccess 
BadAlloc 
BadAtom 
BadColor 
BadCursor 
BadDrawable 
BadFont 
BadGC 
BadIDChoice 
BadImplementation 
BadLength 
BadMatch 
BadName 
BadPixmap 
BadRequest 
BadValue 
BadWindow 
Below 
BitmapFileInvalid 
BitmapNoMemory 
BitmapOpenFailed 
BitmapSucces 
BottomIf 
Buttonl 
ButtonlMask 
ButtonlMotionMask 
Button2 
Button2Mask 
Button2MotionMask 
Button3 
Button3Mask 
Button3MotionMask 
Button4 
Button4Mask 
Button4MotionMask 
Button5 
Button5Mask 
Button5MotionMask 

used by 
used by 
used by 
used by 
used by 
used by 
used by 
used by 
used by 
used by 
used by 
used by 
used by 
used by 
used by 
used by 
used by 
stacking 
returned 
returned 
returned 
returned 

extensions 
extensions 
extensions 
extensions 
extensions 
extensions 
extensions 
extensions 
extensions 
extensions 
extensions 
extensions 
extensions 
extensions 
extensions 
extensions 

only, 
only, 
only, 
only, 
only, 
only, 
only, 
only, 
only, 
only, 
only, 
only, 
only, 
only, 
only, 
only, 

depending on context 
insufficient resources 
parameter not an At om 
no such colormap 
parameter not a Cursor 
parameter not a Pixmap or Window 
parameter not a Font 
parameter not a GC 
choice not in range or already used 
server is defective 
request length incorrect 
parameter mismatch 
font or color name doesn't exist 
parameter not a Pixmap 
bad request code 
integer parameter out of range 

extensions only, 
method, XConfigureWindow 
Status for XReadBitmapFile, 
Status for XReadBitmapFile, 
Status for XReadBitmapFile, 
Status for XReadBitmapFile, 

parameter not a Window 

XWriteBitmapFile 
XWriteBitmapFile 
XWrit eBitmapFile 
XWriteBitmapFile 

stacking method (XConfigureWindow) 
button name in event detail (XGrabButton) 
button mask (XQue ryPointe r) 
event mask 
button name in event detail (XGrabButton) 
button mask (XQueryPointer) 
event mask 
button name in event detail (XGrabButton) 
button mask (XQueryPointer) 
event mask 
button name in event detail (XGrabButton) 
button mask (XQueryPointe r) 
event mask 
button name in event detail (XGrabButton) 
button mask (XQue ryPointe r) 
event mask 

608 

Xlib Reference Manual 



ButtonMotionMask 
ButtonPress 
ButtonPressMask 
ButtonRelease 
ButtonReleaseMask 
C 
CapButt 
CapNot La st 
CapPro jecting 
CapRound 
CenterGravity 
CirculateNotify 
CirculateRequest 
ClientMessage 
ClipByChildren 

ColormapChangeMask 
ColormapInstalled 
ColormapNotify 
ColormapUninstalled 
Complex 
ConfigureNotify 
ConfigureRequest 
ControlMapIndex 

ControlMask 

Convex 
CoordModeOrigin 

CoordModePrevious 

CopyFromParent 

CreateNotify 
CurrentTime 
CursorShape 

CWBackPixel 

event mask 
event type 
event mask 
event type 
event mask 

line cap_style of GC (XSetLineAttributes) 
IMe cap_style of GC (XSetLineAttributes) 
line cap_style of OC (XSetLineAttributes) 
line cap_style of OC (XSetLineAttributes) 
bit_gravity and win_gravity atibute c0nsmnt 
event type 
event type 
event type 
subwindow mode of GC, don't draw through children 
-- 
(XS et Su bw indowMode) 
event mask 
ColormapNot i fy event state 
event type 
ColormapNot i fy event state 
polygon shapes, paths may intersect (XFillPolygon) 
event type 
event type 
modifier names for XSetModifierMapping, 
XGet Modi fierMapping 
modifier key mask for XGrabButton, XGrabKey, results of 
XQueryPointer, event state 
polygon shapes, wholly convex (XFillPolygon) 
interpret points relative to origin 
(XDrawLines, XDrawPoint s) 
interpret points relative to previous point 
(XDrawLines, XDrawPoint s) 
border pixmap, visual ID, window class 
(XCreateWindow, XChangeWindowAt t ribut e s) 
event type 
most time arguments 
largest displayable size 
(XQueryBest Si ze, XQueryBestCursor) 
window attribute mask 
(XCreateWindow, XChangeWindowAt t ribut es) 

Appendix G: Symbol Reference 609 



InputFocus 
InputHint 

InputOnly 
InputOutput 
IsCursorKey 
IsFunctionKey 
IsKeypadKey 
IsMiscFunctionKey 
IsModifierKey 
IsPFKey 
IsUnmapped 

IsUnviewable 

IsViewable 

JoinBevel 
JoinMiter 
JoinRound 

KL 
KBAut oRepeatMode 

KBBellDuration 

KBBellPercent 

KBBellPitch 

KBKey 

KBKeyClickPercent 

KBLed 

KBLedMode 

KeyPress 
KeyPressMask 
KeyRelease 
KeyReleaseMask 

window in XSendEvent 
XA WM HINTS property, input member mask 
(XGetWMHints, XSetWMHint s) 
window class (XCreateWindow) 
window class (XCreateWindow) 
keysym class macro 
keysym class macro 
keysym class macro 
keysym class macro 
keysym class macro 
keysym class macro 
map_state member of XWindowAttributes 
(XGet WindowAtt ribut e s) 
map_state member of XWindowAttributes 
(XGet Win dowAtt ribut e s) 
map_state member of XWindowAttributes 
(XGet WindowAt t ribut e s) 
line join_style of GC (XSetLineAttributes) 
line join_style of GC (XSetLineAttributes) 
line join_style of GC (XSetLineAttributes) 

mask for setting keyboard preferences 
(XChangeKeyboa rdCont rol, XGetKeyboardControl) 
mask for setting keyboard preferences 
(XChangeKeyboa rdCont ro i, XGetKeyboardCont rol) 
mask for setting keyboard preferences 
(XChangeKeyboardCont ro i, XGetKeyboardControl) 
mask for setting keyboard preferences 
(XChangeKeyboa rdCont ro i, XGetKeyboardCont rol) 
mask for setting keyboard preferences 
(XChan geKeyboa rdCont ro i, XGetKeyboa rdCont ro i) 
mask for setting keyboard preferences 
(XChan geKeyboa rdCont ro i, XGetKeyboa rdCont ro i) 
mask for setting keyboard preferences 
(XChangeKeyboa rdCont ro i, XGetKeyboardControl) 
mask for setting keyboard preferences 
(XChangeKeyboa rdCont rol, XGetKeyboardControl) 
event type 
event mask 
event type 
event mask 

614 

Xlib Reference Manual 



KeymapNotify 
KeymapStateMask 
LASTEvent 
LastExtensionError 
LeaveNotify 
LeaveWindowMask 
LedModeOff 

LedModeOn 

LineDoubleDash 
LineOnOffDash 
LineSolid 
LockMapIndex 

LockMask 

LowerHighest 
LSBFirst 

M 
MapNot i fy 
MapReque st 
MappingBusy 

MappingFailed 

MappingKeyboard 
MappingModifier 
MappiagNotify 
MappingPointer 
MappingSuccess 

ModlMapIndex 

Mo dl Ma s k 

Mod2MapIndex 

Mod2 Ma s k 

event type 
event mask 
bigger than any event type value 
use if writing extension 
event type 
event mask 
keyboard preferences 
(XChangeKeyboa rdCont rol, XGetKeyboa rdCont rol) 
keyboard preferences 
(XChangeKeyboa rdCont rol, XGetKeyboa rdCont rol) 
line_style of OC (XSetLineAttributes) 
line_style of OC (XSetLineAttributes) 
line_style of OC (XSetLineAttributes) 
modifier names for XSetModi f ie rMapping, 
XGetModifierMapping 
modifier key mask for XGrabButton, XGrabKey, results of 
XQueryPointer, event state 
circulation direcfi0n, XCirculateSubwindows 
byte order, used in image structure 
(XCreateImage, ImageByteOrder) 

event type 
event type 
pointer or modifier mapping status 
(XSet Modi fierMapping, XSetPointerMapping) 
pointer or modifier mapping Status 
(XSet Modi fierMapping, XSetPointerMapping) 
MappingNot ify event 
MappingNot i fy event 
event type 
MappingNot i fy event 
pointer or modifier mapping Status 
(XSetModi fierMapping, XSetPointerMapping) 
modifier names for XSetModifierMapping, 
XGet Modi fierMapping 
modifier key mask for XGrabButton, XGrabKey, results of 
XQue ryPointe r, event state 
modifier names for XSetModifierMapping, 
XGet Modi fierMapping 
modifier key mask for XGrabButton, XGrabKey, resul of 
XQueryPointer, event state 

Appendix G: Symbol Reference 615 



Mod3MapIndex 

Mod3Mask 

Mod4MapIndex 

Mod4Mask 

Mod5MapIndex 

Mod5Mask 

MotionNotify 
MSBFirst 

N 
NoEventMask 
NoExpose 
NoSymbol 
NoValue 
Nonconvex 

None 
NormalState 

NorthEastGravity 
NorthGravity 
NorthWestGravity 
NotUseful 

NotifyAncestor 
NotifyDetailNone 
NotifyGrab 
NotifyHint 
NotifyInferior 
NotifyNonlinear 
NotifyNonlinear- 
Virtual 
NotifyNormal 
NotifyPointer 
NotifyPointerRoot 

modifier names for XSetModifierMapping, 
XGetModifierMapping 
modifier key mask for XGrabButton, XGrabKey, results 
XQueryPointer, event state 
modifier names for XSetModifierMapping, 
XGetModi fierMapping 
modifier key mask for XGrabButton, XGrabKey, results 
XQueryPointer, event state 
modifier names for XSetModifierMapping, 
XGetModifierMapping 
modifier key mask for XGrabButton, XGrabKey, results 
XQueryPointer, event state 
event type 
byte order, used in image structure 
(XCreateImage, ImageByteOrder) 

event mask 
event type 
keysym for no symbol 
mk usa by XParseGeometry, returns those set by user 
polygon shapes, no paths intersect, but not convex 
(XFillPolygon) 
universal null resource or null atom 
window state, not iconified or zoomed 
(value for member of xwrtints) 
bit_gravity and win_gravity attribute constant 
bit_gravity and win_gravity attribute constant 
bit_gravity and win_gravity attribute constant 
backing_store attribute 
(XCreateWindow, XChangeWindowAtt ribute s) 
FocusIn, FocusOut, EnterNotify, LeaveNotify detail 

FocusIn, FocusOut, 
FocusIn, FocusOut, 
MotionNoti fy event 
FocusIn, FocusOut, 
FocusIn, FocusOut, 
FocusIn, FocusOut, 

FocusIn, FocusOut, 
FocusIn, FocusOut, 
FocusIn, FocusOut, 

EnterNotify, LeaveNotify detail 
EnterNotify, LeaveNotify mode 
hint 
EnterNotify, LeaveNotify detail 
EnterNotify, LeaveNotify detail 
EnterNotify, LeaveNotify detail 

EnterNotify, LeaveNotify mode 
EnterNotify, LeaveNotify detail 
EnterNotify, LeaveNotify detail 

616 

Xlib Reference Manual 



RectangleOut 
RectanglePart 
ReparentNotify 
ReplayKeyboard 
ReplayPointer 
ResizeRedirectMask 
ResizeRequest 
RetainPern%nent 
RetainTemporary 
RevertToNone 

RevertToParent 

RevertToPointerRoot 

rectangle is outside region (XRectInRegion) 
rectangle is part inside region (XRect InRegion) 
event type 
XAllowEvents mode 
XAllowEvent s mode 
event mask 
event type 
mode in XSetCloseDownMode 
mode in XSetCloseDownMode 
backup keybod focus window 
(XSet InputFocus, XGet InputFocus) 
backup keybod focus window 
(XSet InputFocu s, XGet InputFocu s) 
backup keybod focus window 
(XSet InputFocus, XGet InputFocus) 

S 
ScreenSaverActive 
ScreenSaverReset 
SelectionClear 
SelectionNotify 
SelectionRequest 
SetModeDelete 
SetModeInsert 
ShiftMapIndex 

Shi ftMask 

SouthEastGravity 
SouthGravity 
SouthWestGravity 
StateHint 

StaticColor 

StaticGravity 
StaticGray 

StippleShape 
StructureNotifyMask 

tum screen saver on (XForceScreenSaver) 
tum screen saver off (XForceScreenSaver) 
event type 
event type 
event type 
change_mode argument of XChangeSave Set 
change_mode argument of XChangeSaveSet 
modifier names for XSetModifierMapping, 
XGet Modi fi erMappin g 
modifier key mask for XGrabButton, XGrabKey, results of 
XQueryPointer, event state 
bit_gravity and win_gravity atibute constant 
bit_gravity and win_gravity atibute constant 
bit_gravity and win_gravity atibute constant 
XA WM HINTS property, window state mask 
(XGetWMHints, XSetWMHint s) 
visual class, read-only 
(XGetVisualInfo, XMat chVisualInfo) 
bit_gravity and win_gravity atibute constant 
visual class, read-only 
(XGetVisualInfo, XMat chVisualInfo) 
size filed fastest (XQue ryBe st Si ze, XQue ryBe st St ipple) 
event mask 

Subst ru ctureNot ifyMas k event mask 

618 

Xlib Reference Manual 



VisualNoMask 

VisualRedMaskMask 

VisualScreenMask 

WestGravity 
WhenMapped 

WidthValue 
WindingRule 

WindowGroupHint 

X 
XA ARC 
-- 
XA ATOM 
-- 
XA BITMAP 
-- 
XA CAP HEIGHT 
-- _ 
XA CARDINAL 
XA COLORMAP 
-- 
XA COPYRIGHT 
-- 
XA CURSOR 
XA CUT BUFFER0 
XA_CUT_BUFFERI 
X_CU_BUFFER2 
XA_CUT_BUFFER3 
XA_CUT_UFFER4 
XA_CUT_UFFER5 
XA_CUT_BUFFER 6 
XA_CUT_BUFFER7 
XA_DRAWABLE 
XA END SPACE 
XA FAMILY NAME 
XA FONT 
XA FONT NAME 
XA FULL NAME 
XA_INTEGER 
XA_ITALIC ANGLE 
XA_LAST_PREDEFI NED 

mask for determining desired visual structure 
(XGetVisual Info, Mat chVi sual In fo) 
mask for determining desired visual structure 
(XGetVisual Info, Mat chVi sual In fo) 
mask for determining desired visual structure 
(XGetVisualInfo, MatchVi sual Info) 
bit_gravity and win_gravity attribu constant 
backing_store attribute 
(XCreateWindow, XChangeWindowAtt ribute s) 
mask used by XParseGeometry, returns ose set by user 
fill_rule of OC, for po|ygons 
(XSetFillRule, XPolygonRegion) 
XA WM HINTS property, group property mask 
(XGetWMHints, XSetWMHint s) 

predefined type atom 
predefined type atom 
predefined type atom 
predefined font atom 
predefined type atom 
predefined type atom 
predefined font atom 
predefined type atom 
predefined cut buffer atom 
predefined cut buffer atom 
predefined cut buffer atom 
predefined cut buffer atom 
predefined cut buffer atom 
predefined cut buffer atom 
predefined cut buffer atom 
predefined cut buffer atom 
predefined type atom 
predefined font atom 
predefined font atom 
predefined type atom 
predefined font atom 
predefined font atom 
predefined type atom 
predefined font atom 
predefined font atom 

62O 

Xlib Reference Manual 



XA MAX SPACE 
XA MIN SPACE 
XA NORM SPACE 
-- -- 
XA NOTICE 
-- 
XA PIXMAP 
-- 
XA POINT 
-- 
XA POINT SIZE 
-- -- 
XA PRIMARY 
-- 
XA_QUAD_WIDTH 
XA RECTANGLE 
-- 
XA RESOLUTION 
-- 
XA RESOURCE MANAGER 
-- -- 
XA RGB BEST MAP 
-- -- -- 
XA RGB BLUE MAP 
-- -- -- 
XA RGB COLOR MAP 
-- -- -- 
XA RGB DEFAULT MAP 
-- -- -- 
XA RGB GRAY MAP 
XA RGB GREEN MAP 
-- -- -- 
XA RGB RED MAP 
-- -- -- 
XA SECONDARY 
-- 
XA STRIKEOUT ASCENT 
-- -- 
XA STRIKEOUT DESCENT 
XA STRING 
-- 
XA SUBSCRIPT X 
-- -- 
XA SUBSCRIPT Y 
-- -- 
XA SUPERSCRIPT X 
-- -- 
XA SUPERSCRIPT Y 
-- -- 
XA UNDERLINE POSITION 
-- -- 
XA UNOERLINE THICKNESS 
XA VISUALID 
-- 
XAWEIGHT 
-- 
XAWINDOW 
-- 
XAWM CLASS 
XA WM CLIENT MACHINE 
-- 
XA WM COMMAND 
XA WM HINTS 
XA WM ICON NAME 
XA WM ICON SIZE 
XAWM NAME 

predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predcfined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 
predefined 

font atom 
font atom 
font atom 
font atom 
type atom 
type atom 
font atom 
selection atom 
font atom 
type atom 
font atom 
resource manager atom 
colormap atom 
colormap atom 
type atom 
colormap atom 
colormap atom 
colormap atom 
colormap atom 
selection atom 
font atom 
font atom 
type atom 
font atom 
font atom 
font atom 
font atom 
font atom 
font atom 
type atom 
font atom 
type atom 
font atom 
string atom 
window manager hints atom 
window manager hints atom 
window manager hints atom 
window manager hints atom 
window manager hints atom 

Appendix G: Symbol Reference 621 



Table H-2. MISCELLANY 

Keysym 

XK_BackSpace 
XK Tab 
-- 
XK Linefeed 
XK Clear 
-- 
XK Return 
-- 
XK Pause 
XK_Escape 
XK Delete 
XK_Mult i_key 
XK_Kan j i 
XK Home 
-- 
XK Left 
-- 
x_up 
XK_Right 
XK Down 
XK Prior 
XK Next 
XK End 
-- 
XK_Begin 
XK Select 
XK Print 
-- 
XK Execute 
-- 
XK Insert 
-- 
XK Undo 
XK Redo 
-- 
XK Menu 
-- 
XK Find 
-- 
XK Cancel 
XK_Help 
XK Break 
-- 
XK Mode switch 

XK_script_switch 

XK Num Lock 
-- __ 
XK KP Space 
XK KP Tab 
XK KP Enter 
XK KP F1 
XK KP F2 
XK KP F3 
XK KP F4 
XK KP Equal 
XK KP Multiply 
XK KP Add 

Description 

Backspace, Back Space, Back Char 
Tab 
Linefeed, LF 
Clear 
Retum, Enter 
Pause, Hold, Scroll Lock 
Escape 
Delete, Rubout 
Multi-key character preface 
Kanji, Kanji convert 
Home 
Left, move left, left arrow 
Up, move up, up arrow 
Right, move right, right arrow 
Down, move down, down arrow 
Prior, previous 
Next 
End, EOL 
Begin, BOL 
Select, mark 
Print 
Execute, run, do 
Insert, insert here 
Undo, oops 
Redo, again 
Menu 
Find, search 
Cancel, stop, abort, exit 
Help, question mark 
Break 
Mode switch, script switch, 
character set switch 
Alias for mode switch, script switch, 
character set switch 
Num Lock 
Keypad Space 

Keypad Tab 
Keypad Enter 
Keypad F1, PF1, a 
Keypad F2, PF2, b 
Keypad F3, PF3, c 
Keypad F4, PF4, d 
Keypad equals sign 
Keypad multiplication sign, asterisk 
Keypad plus sign 

Appendix H: Keysyms 625 



Table H-2. MISCELLANY (continued) 

Ke),s),m 
XK_KP_geparat or 
XK KP Subtract 
XK KP Decimal 
XK KP Divide 
XK KP 0 
XK KP 1 
XK KP 2 
XK KP 3 
XK KP 4 
XK KP 5 
XK KP 6 
XK KP 7 
XK KP 8 
XK KP 9 
XK F1 
XK F2 
XK F3 
XK F4 
XK F5 
XK F6 
XK F7 
XK F8 
XK F9 
XK FI0 
XK FII 
XK L1 
-- 
XK FI2 
XK L2 
XK FI3 
-- 
XK L3 
XK FI4 
XK L4 
XK FI5 
XK L5 
XK FI6 
XK L6 
XK FI7 
XK L7 
XK FI8 
XK L8 
XK FI9 
XK L9 
XK F20 
XK LI0 
XK F21 

)ton 
Keypad separator, comma 
Keypad minus sign, hyphen 
Keypad decimal point, full stop 
Keypad division sign, solidus 
Keypad digit zero 
Keypad digit one 
Keypad digit two 
Keypad digit three 
Keypad digit four 
Keypad digit five 
Keypad digit six 
Keypad digit seven 
Keypad digit eight 
Keypad digit nine 
F1 function key 
F2 function key 
F3 function key 
F4 function key 
F5 function key 
F6 function key 
F7 function key 
F8 function key 
F9 function key 
F10 function key 
F11 function key 
L1 function key 
F12 function key 
L2 function key 
F13 function key 
L3 function key 
F14 function key 
L4 function key 
F15 function key 
L5 function key 
F16 function key 
L6 function key 
F17 function key 
L7 function key 
F18 function key 
L8 function key 
F19 function key 
L9 function key 
F20 function key 
L10 function key 
F21 function key 

66 

Xlib Reference Manual 



Table H-2. MISCELLANY (continued) 

Keysym 

XK R1 
-- 
XK F22 
-- 
XK R2 
-- 
XK F23 
-- 
XK R3 
XK F24 
-- 
XK R4 
XK F25 
-- 
XK R5 
-- 
XK F26 
-- 
XK R6 
-- 
XK F27 
-- 
XK R7 
-- 
XK F28 
-- 
XK R8 
XK F29 
-- 
XK R9 
-- 
XK F30 
-- 
XK RI0 
XK F31 
-- 
XK RII 
-- 
XK F32 
-- 
XK RI2 
-- 
XK RI3 
-- 
XK F33 
-- 
XK F34 
-- 
XK RI4 
-- 
XK F35 
-- 
XK RI5 
-- 
XK Shift L 
XK Shift R 
XK C6ntrol L 
XK Control R 
-- __ 
XK_Caps_Lock 
XK Shift Lock 
XK Meta L 
XK Meta R 
XK Alt L 
-- __ 
XK Alt R 
-- -- 
XK_Super_L 
XK_Super_R 
XK_Hyper_L 
XK_Hyper_R 

Description 

R1 function key 
F22 function key 
R2 function key 
F23 function key 
R3 function key 
F24 function key 
R4 function key 
F25 function key 
R5 function key 
F26 function key 
R6 function key 
F27 function key 
R7 function key 
F28 function key 
R8 function key 
F29 function key 
R9 function key 
F30 function key 
RI0 function key 
F31 function key 
R11 function key 
F32 function key 
R12 function key 
F33 function key 
R 13 function key 
F34 function key 
R14 function key 
F35 function key 
R15 function key 
Left Shift 
Right Shift 
Left Control 
Right Control 
Caps Lock 
S hift Lock 
Left Meta 
Right Meta 
Left Alt 
Right Alt 
Left Super 
Right Super 
Left Hyper 
Right Hyper 

Appendix H: Keysyms 627 



Table H-3. LA TINI 

Keysym 

XK_space 
XK exclam 
-- 
XK_quot edbl 
XK_number sign 
XK dollar 
-- 
XK_pe rcen t 
XK_ampersand 
XK_quoteright 
XK_pa renleft 
XK_parenright 
XK asterisk 
-- 
XK_plus 
XK comma 
-- 
XK minus 
-- 
XK_period 
XK slash 
-- 
XK 0 
-- 
XK 1 
-- 
XK 2 
-- 
XK 3 
XK 4 
-- 
XK 5 
XK 6 
-- 
XK 7 
XK 8 
-- 
XK 9 
XK colon 
-- 
XK_semi colon 
XK less 
XK_equal 
XK_greater 
XK_question 
XK at 
XK A 
XK B 
XK C 
XK D 
XK E 

Description 

Space 
Exclamation point 
Quotation mark 
Number sign 
Dollar sign 
Percent sign 
Ampersand 
Apostrophe 
Left parenthesis 
Right parenthesis 
Asterisk 
Plus sign 
Comma 
Hyphen, minus sign 
Full stop 
Solidus 
Digit zero 
Digit one 
Digit two 
Digit three 
Digit four 
Digit five 
Digit six 
Digit seven 
Digit eight 
Digit nine 
Colon 
Semicolon 
Less than sign 
Equals sign 
Greater than sign 
Question mark 
Commercial at 
Latin capital A 
Latin capital B 
Latin capital C 
Latin capital D 
Latin capital E 

Character 

/ 
0 
1 
2 
3 
4 
5 
6 
7 
8 
9 
; 
< 
? 
@ 
A 
B 
C 
D 
E 

628 

Xlib Reference Manual 



Table H-3. LATIN1 (continued) 

Keysym 

XK F 
-- 
XK G 
-- 
XK H 
-- 
XK I 
-- 
XK J 
-- 
XK K 
-- 
XK L 
-- 
XK M 
-- 
XK N 
-- 
XK 0 
XK P 
XK Q 
XK R 
XK S 
XK T 
XK U 
-- 
XK V 
-- 
XK W 
XK X 
-- 
XK Y 
-- 
XK Z 
XK bracketleft 
-- 
XK backslash 
-- 
XK_bracketright 
XK asciicircum 
XK underscore 
XK_qubteleft 
XK a 
-- 
XK b 
-- 
XK c 
-- 
XK d 
-- 
XK e 
-- 
XK f 
XK_g 
XK h 
-- 
XK i 
-- 

Descdpdon 

Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 

capital F 
capital G 
capital H 
capital I 
capital J 
capital K 
capital L 
capital M 
capital N 
capital O 
capital P 
capital Q 
capital R 
capital S 
capital T 
capital U 
capital V 
capital W 
capital X 
capital Y 

Latin capital Z 
Left square bracket 
Reverse solidus 
Right square bracket 
Circumflex accent 
Low line 
Grave accent 
Latin small a 

Latin small b 
Latin small c 
Latin small d 
Latin small e 
Latin small f 
Latin small g 
Latin small h 
Latin small i 
Latin small j 

Character 

F 
G 
H 
I 
J 
K 
L 
M 
N 
O 
P 
Q 
R 
S 
T 
U 
V 
W 
X 
Y 
Z 
[ 
\ 
] 
^ 

Appendix H: Keysyms 629 



Table H-3. LATIN1 (continued) 

Keysym 

XK k 
XK 1 
XK m 
XK n 
-- 
XK o 
-- 
XK_p 
XK_q 
XK r 
-- 
XK s 
XK t 
XK u 
-- 
XK v 
-- 
XK w 
-- 
XK x 
-- 
XK_y 
XK z 
-- 
XK braceleft 
-- 
XK bar 
-- 
XK_braceright 
XK asciitilde 
XK_nobreakspace 
XK_exclamdown 
XK cent 
XK_sterling 
XK_currency 
XK_yen 
XK_brokenbar 
XK_section 
XK diaeresis 
XK_copyright 
XK_ordfeminine 
XK_guillemotleft 
XK_notsign 
XK_hyphen 
XK_regi stered 
XK_macron 
XK_degree 

Description 

Latin small k 
Latin small 1 
Latin small m 
Latin small n 
Latin small o 
Latin small p 
Latin small q 
Latin small r 
Latin small s 
Latin small t 
Latin small u 
Latin small v 
Latin small w 
Latin small x 
Latin small y 
Latin small z 
Left brace 
Vertical line 
Right brace 
Tilde 

No-break space 
Inverted exclamation mark 
Cent sign 
Pound sign 
Currency sign 
Yen sign 
Broken vertical bar 
Paragraph sign, section sign 
Diaeresis 
Copyright sign 
Feminine ordinal indicator 
Left angle quotation mark 
Not sign 
Short horizontal hyphen 
Registered trade mark sign 
Macron 
Degree sign, ring above 

Character 

k 
1 
u 
v 
w 
x 
Y 
z 
{ 
I 
} 

63O 

Xlib Reference Manual 



Table H-3. LATIN1 (continued) 

Keysym 

XK Odiaeresis 
XK_mu It iply 
XK Oobl ique 
XK_Ugrave 
XK Uacute 
XK Ucircumflex 
XK Udiaeresis 
XK Yacute 
XK Thorn 
XK_s s ha rp 
XK_agrave 
XK aacute 
-- 
XK acircumflex 
XK atilde 
XK adiaeresis 
XK_aring 
XK ae 
XK ccedilla 
XK_egrave 
XK eacute 
XK_ecircumflex 
XK_ediaeres is 
XK_igrave 
XK iacute 
XK_icircumflex 
XK idiaeresis 
XK eth 
XK ntilde 
XK_ograve 
XK oacute 
XK_oc ircumflex 
XK otilde 
XK_odiaeresis 
XK_divi sion 
XK_oslash 
XK_ugrave 
XK uacute 

Description 

Latin capital 0 with diaeresis 
Multiplication sign 
Latin capital 0 with oblique stroke 
Latin capital U with grave accent 
Latin capital U with acute accent 
Latin capital U with circumflex accent 
Latin capital U with diaeresis 
Latin capital Y with acute accent 
Icelandic capital THORN 
German small sharp s 
Latin small a with grave accent 
Latin small a with acute accent 
Latin small a with circumflex accent 
Latin small a with tilde 
Latin small a with diaeresis 
Latin small a with ring above 
Latin small diphthong ae 
Latin small c with cedilla 
Latin small e with grave accent 
Latin small e with acute accent 
Latin small e with circumflex accent 
Latin small e with diaeresis 
Latin small i with grave accent 
Latin small i with acute accent 
Latin small i with circumflex accent 
Latin small i with diaeresis 
Icelandic small eth 
Latin small n with tilde 
Latin small o with grave accent 
Latin small o with acute accent 
Latin small o with circumflex accent 

Latin small o with tilde 
Latin small o with diaeresis 
Division sign 
Latin small o with oblique stroke 
Latin small u with grave accent 
Latin small u with acute accent 

Character 

0 

632 

Xlib Reference Manual 



Table H-3. LATIN1 (continued) 

Keysym 

XK ucircumflex 
XK udiaeresis 
XK_yacut e 
XK t ho rn 
XK_ydiaeresis 

Description 

Latin small u with circumflex accent 
Latin small u with diaeresis 
Latin small y with acute accent 
Icelandic small thorn 
Latin small y with diaeresis 

Character 

Appendix H: Keysyms 633 



Table H-4. LATIN2 

Keysym 

XK_Aogonek 
XK breve 
XK Lstroke 
-- 
XK Lcaron 
XK Sacute 
XK Scaron 
XK Scedilla 
-- 
XK Tcaron 
-- 
XK Zacute 
-- 
XK Zcaron 
-- 
XK Zabovedot 
-- 
XK_aogonek 
XK_ogonek 
XK istroke 
-- 
XK icaron 
XK sacute 
-- 
XK caron 
-- 
XK scaron 
-- 
XK scedilla 
-- 
XK tcaron 
-- 
XK zacute 
-- 
XK_doubleacute 
XK zcaron 
-- 
XK_zabovedot 
XK Racute 
-- 
XK Abreve 
-- 
XK Cacute 
-- 
XK Ccaron 
XK_Eogonek 
XK_Ecaron 
XK Dcaron 
XK Nacute 
XK_Ncaron 
XK_Odoubleacute 
XK_Rcaron 
XK_Uring 
XK_Udoubleacute 
XK_Tcedilla 

634 

Description 

Latin capital A with ogonek 

Breve 
Latin capital 
Latin capital 
Latin capital 
Latin capital 
Latin capital 
Latin capital 
Latin capital 
Latin capital 

L with stroke 
L with caron 
S with acute accent 
S with caron 
S with cedilla 
T with caron 
Z with acute accent 
Z with caron 

Latin capital Z with dot above 
Latin small a with ogonek 
Ogonek 
Latin small I with stroke 
Latin small I with caron 
Latin small s with acute accent 
Caron 
Latin small s with caron 
Latin small s with cedilla 
Latin small t with caron 
Latin small z with acute accent 
Double acute accent 
Latin small z with caron 

Latin small z with dot above 
Latin capital R with acute accent 
Latin capital A with breve 
Latin capital C with acute accent 
Latin capital C with caron 
Latin capital E with ogonek 
Latin capital E with caron 
Latin capital D with caron 
Latin capital N with acute accent 
Latin capital N with caron 
Latin capital O with double acute accent 
Latin capital R with caron 
Latin capital U with ring above 
Latin capital U with double acute accent 
Latin capital T with cedilla 

Character 

15 
6 
T 

Xlib Reference Manual 



Table H-4. LATIN2 (continued) 

Keysym 

XK racute 
-- 
XK abreve 
-- 
XK cacute 
XK ccaron 
-- 
XK_eogonek 
XK ecaron 
XK dcaron 
-- 
XK nacute 
-- 
XK ncaron 
XK odoubleacute 
-- 
XK rcaron 
-- 
XK_uring 
XK udoubleacute 
-- 
XK tcedilla 
XK abovedot 
-- 

Description 

Latin small 
Latin small 
Latin small 
Latin small 
Latin small 
Latin small 
Latin small 
Latin small 
Latin small 
Latin small 
Latin small 
Latin small 
Latin small 
Latin small 
Dot above 

r with acute accent 
a with breve 
c with acute accent 
c with caron 
e with ogonek 
e with caron 
d with caron 
n with acute accent 
n with caron 
o with double acute accent 
r with caron 
u with ring above 
u with double acute accent 
t with cedilla 

Character 

Appendix H: Keysyms 635 



Table H-6. LATIN4 

Keysym 

XK_kappa 
XK Rcedilla 
-- 
XK Itilde 
-- 
XK Lcedilla 
-- 
XK Emacron 
-- 
XK Gcedilla 
XK Tslash 
-- 
XK rcedilla 
-- 
XK itilde 
-- 
XK icedilla 
-- 
XK emacron 
-- 
XK_gacute 
XK tslash 
-- 
XK ENG 
-- 
XK_eng 
XK Amacron 
-- 
XK_Iogonek 
XK Eabovedot 
-- 
XK Imacron 
-- 
XK Ncedilla 
-- 
XK Omacron 
-- 
XK Kcedilla 
-- 
XK_Uogonek 
XK Utilde 
-- 
XK Umacron 
-- 
XK amacron 
-- 
XK_iogonek 
XK eabovedot 
-- 
XK imacron 
-- 
XK ncedilla 
-- 
XK omacron 
-- 
XK kcedilla 
-- 
XK_uogonek 
XK utilde 
XK umacron 
-- 

Description 

Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 

small kappa 
capital R with cedilla 

capital I with tilde 
capital L with cedilla 
capital E with macron 
capital G with cedilla 
capital T with oblique slxoke 
small r with cedilla 
small i with tilde 
small I with cedilla 
small e with macron 
small g with acute accent 

Latin small t with oblique stroke 
Lappish capital ENG 
Lappish small eng 
Latin capital A with macron 

Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 
Latin 

capital 
capital 
capital 
capital 
capital 
capital 
capital 
capital 
capital 
small 
small 
small 
small 
small 
small 
small 
small 
small 
small 

I with ogonek 
E with dot above 
I with macron 
N with cedilla 
O with macron 
K with cedilla 
U with ogonck 
U with tilde 
U with macron 
a with macron 
i with ogonek 
e with dot above 
i with macron 
n with cedilla 
o with macron 
k with cedilla 
u with ogonek 
u with tilde 
u with macron 

Character 

O 
K. 
i 

Appendix H: Keysyms 637 



Table H-7. GREEK 

Keysym 

XK Greek ALPHAaccent 
-- _ 

XK Greek EPSILONaccent 
-- _ 

XK Greek ETAaccent 
-- _ 

XK Greek IOTAaccent 
-- _ 

XK Greek IOTAdiaeresis 
-- _ 

XK Greek IOTAaccentdiaeresis 
-- _ 

XK Greek OMICRONaccent 
-- _ 

XK Greek UPSILONaccent 
-- _ 

XK Greek UPSILONdieresis 
-- _ 

XK Greek UPSILONaccentdieresis 
-- _ 

XK Greek OMEGAaccent 
-- _ 

XK_Greek_alphaaccent 

XK_Greek_epsilonaccent 

XK Greek etaaccent 
-- _ 

XK Greek iotaaccent 
-- _ 

XK Greek iotadieresis 
-- _ 

XK_Greek_iotaaccentdieresis 

XK Greek omicronaccent 
-- 
-- 

XK_Greek_upsilonaccent 

XK_Greek_upsilondieresis 

XK_Greek_upsilonaccentdieresis 

XK_Greek_omegaaccent 

XK Greek ALPHA 
-- 
-- 

XK Greek BETA 
-- 
-- 

XK Greek GAMMA 
-- 
-- 

XK Greek DELTA 
-- 
-- 

XK Greek EPSILON 
-- 
-- 

XK Greek ZETA 
-- 
-- 

XK Greek ETA 
-- 
-- 

XK Greek THETA 
-- 
-- 

XK Greek IOTA 
-- 
-- 

XK Greek KAPPA 
-- 
-- 

XK Greek LAMBDA 
-- 
-- 

XK Greek MU 
-- 
-- 

XK Greek NU 
-- 
-- 

XK Greek XI 
-- 
-- 

XK_Greek OMICRON 
-- 

XK Greek PI 
-- 
-- 

638 

Description 

Greek capital alpha with accent 
Greek capital epsilon with accent 
Greek capital eta with accent 
Greek capital iota with accent 
Greek capital iota with diaeresis 
Greek capital iota with accent+dieresis 
Greek capital omicron with accent 
Greek capital upsilon with accent 
Greek capital upsilon with dieresis 
Greek capital upsilon with accent+dieresis 
Greek capital omega with accent 
Greek small alpha with accent 

Greek small epsilon with accent 
Greek small eta with accent 
Greek small iota with accent 
Greek small iota with dieresis 
Greek small iota with accent+dieresis 
Greek small omicron with accent 
Greek small upsilon with accent 
Greek small upsilon with dieresis 
Greek small upsilon with accent+dieresis 
Greek small omega with accent 
Greek capital alpha 
Greek capital beta 
Greek capital gamma 
Greek capital delta 
Greek capital epsilon 
Greek capital zeta 
Greek capital eta 
Greek capital theta 
Greek capital iota 
Greek capital kappa 
Greek capital lambda 
Greek capital mu 
Greek capital nu 
Greek capital xi 
Greek capital omicron 
Greek capital pi 

Character 

A 
B 
F 
A 
E 
Z 
H 
O 
I 
K 
A 
M 
N 
O 
H 

Xlib Reference Manual 



Table I- 1. Standard Cursor Symbols 

Symbol Value 

Row I 
XC X cursor 0 
XC arrow 2 
-- 
XC based arrow down 4 
XC_ba sed_arrow_up 6 
XC boat 8 
-- 
XC_bogosity I0 
XC bottom left corner 12 
-- _ _ 
XC_bot t om_right_corne r 14 
XC bottom side 16 
-- _ 
XC bottom tee 18 
-- _ 
XC_box_spiral 20 
XC_cent er_pt r 22 

Row 2 
XC__c i rc le 24 
XC__clock 26 
XC_coffee_mug 28 
XC_cross 30 
XC_cros s reverse 32 
-- 
XC_cros shair 34 
XC_diamond_cros s 36 
XC_dot 38 
XC_dotbox 40 
XC_double_arrow 42 
XC_draft_large 44 
XC_draft_small 46 

Row 3 
XC_draped_box 48 
XC_exchange 50 
XC_fleur 52 
XC_gobble r 54 
XC_gumby 56 
XC_handl 58 
XC_hand2 60 
XC_heart 62 
XC_icon 64 
XC_iron_cro s s 66 
XC_Ie ft_pt r 68 
XC_Ie ft_s ide 70 

Symbol 

Value 

Row 4 
XC left tee 
-- _ 
XC left button 
-- _ 
XC ii angle 
XC ir angle 
-- _ 
XC man 
-- 
XC middlebutt on 
-- 
XC mouse 
-- 
XC_pencil 
XC_pi rate 
XC_pI u s 
XC_qu e s t i on_a rrow 
XC_ri ght_pt r 
Row 5 
XC_right_side 
XC_right_tee 
XC_rightbutton 
XC_rt l_logo 
XC sailboat 
XC sb down arrow 
-- 
XC sb h double arrow 
-- 
XC sb left arrow 
-- 
XC_sb_right_arrow 
XC_sb_up_arrow 
XC sb v double arrow 
-- 
XC shuttle 
-- 

Row 6 
XC_sizing 
XC_spider 
XC_spraycan 
XC star 
XC_target 
XC tcross 
XC_top_le ft_arrow 
XC_top_le ft corner 
-- 
XC_top_right_corner 
XC_top_side 
XC_top_tee 
XC trek 
-- 

Row 7 
XC ul angle 
XC_umbr e i i a 
XC_ur_angle 
XC watch 
XC xterm 
XC_num_glyphs 

72 
74 
76 
78 
80 
82 
84 
86 
88 
90 
92 
94 
96 
98 
100 
102 
104 
106 
108 
110 
112 
114 
116 
118 

120 
122 
124 
126 
128 
130 
132 
134 
136 
138 
140 
142 

144 
146 
148 
150 
152 
154 

642 

Xlib Reference Manual 



Table J-2 describes the maximum metrics for each font. These are the values of the 
max bounds member of XFontStruct (which is an XCharStruct structure with the 
-- 
members shown in the table). Note that it is unlikely that any single character will be the 
biggest in all the measurements simultaneously; these describe the largest lbearing of 
any character in the font, the largest rbearing for any character in the font, and so on. 
For a description of each of the character measurements, see Volume One, Section 6.2.3. 

Table J-2. Maximum Font Metrics 

Font Name 

6x10 
6x12 
6x13 
8x13 
8xl3bold 
9x15 
a14 
apl-s25 
arrow3 
chp-s25 
chs-s50 
crturz 
cursor 
cyr-s25 
cyr-s30 
cyr-s38 
dancer 
ent 
fcor-20 
fg-13 
fg-16 
fg-18 
fg-20 
fg-22 
fg-25 
fg-30 
fg-40 
fgl-25 
fgb-13 
fgb-25 
fgbl-25 
fgbl-30 
fgi-2o 
fgil-25 
fgs-22 
fixed 

ibearing rbearing ascent descent width 

0 6 8 2 6 
0 6 8 4 6 
0 6 10 3 6 
0 8 10 3 8 
0 8 10 3 8 
0 9 12 3 9 
0 7 12 2 7 
0 27 20 5 27 
0 59 8 18 59 
0 34 23 2 34 
0 50 40 10 50 
0 100 0 155 100 
1 16 15 16 17 
0 28 24 5 28 
0 37 30 8 37 
0 37 30 8 37 
0 47 36 10 47 
0 640 0 170 640 
0 16 16 4 16 
0 9 11 2 9 
0 10 11 5 10 
0 12 13 5 12 
0 12 15 5 12 
0 13 17 5 13 
0 16 20 5 16 
0 19 25 5 19 
0 25 33 7 25 
0 14 20 5 14 
0 10 11 2 10 
0 17 20 5 17 
0 16 20 5 16 
0 16 20 10 16 
0 12 15 5 12 
0 16 20 5 16 
0 13 17 5 13 
0 6 10 3 6 

644 

Xlib Reference Manual 



Table J-2. Maximum Font Metrics (continued) 

Font Name 

fqxb-25 
fr-25 
fr-33 
frl-25 
fr2-25 
fr3-25 
frb-32 
fri-33 
fril-25 
ger-s35 
grk-s25 
grk-s30 
hbr-s25 
hbr-s40 
ipa-s25 
kanal4 
krivo 
lat-s30 
met25 
micro 
mit 
oldera 
plunk 
r14 
rot-sl6 
runlen 
sansl2 
sansbl2 
sansil2 
serifl0 
serifl2 
serifbl0 
serifbl2 
serifil0 
serifil2 
stan 
stempl 
sub 
subsub 
sup 
supsup 
swd-s30 
sym-s25 
sym-s53 

Ibearing rbearing 

ascent 

descent 

width 

0 22 20 5 22 
0 17 20 5 17 
0 23 23 10 23 
0 16 20 5 16 
0 16 20 5 16 
0 16 20 5 16 
0 19 24 8 19 
0 26 24 9 26 
0 17 20 5 17 
0 32 30 5 32 
0 27 20 5 27 
0 35 26 5 35 
0 20 32 13 20 
0 29 50 14 29 
0 16 20 5 16 
0 7 12 2 7 
0 49 50 50 49 
0 16 25 5 16 
0 7 21 9 7 
0 4 5 0 4 
0 161 143 2 161 
0 15 9 6 15 
0 26 21 9 26 
0 7 12 2 7 
0 25 16 0 25 
0 96 3 0 96 
0 11 11 3 11 
0 11 11 3 11 
0 11 11 3 11 
0 8 10 3 8 
0 11 11 3 11 
0 8 10 3 8 
0 11 11 3 11 
0 8 10 3 8 
0 11 11 3 11 
0 225 108 108 225 
0 28 28 0 28 
0 20 9 12 20 
0 13 0 14 13 
0 20 28 -7 20 
0 13 36 -22 13 
0 16 25 5 16 
0 24 20 5 24 
0 34 35 18 34 

Appendix J: Fonts 645 



Table J-2. Maximum Font Metrics (continued) 

Font Name 

variable 
vbee-36 
vctl-25 
vg-13 
vg-20 
vg-25 
vg-31 
vg-40 
vgb-25 
vgb-31 
vgbc-25 
vgh-25 
vgi-20 
vgi-25 
vgi-31 
vgl-40 
vgvb-31 
vmic-25 
vply-36 
vr-20 
vr-25 
vr-27 
vr-30 
vr-31 
vr-40 
vrb-25 
vrb-30 
vrb-31 
vrb-35 
vrb-37 
vri-25 
vri-30 
vri-31 
vri-40 
vsg- 114 
vsgn-57 
vshd-40 
vtbold 
vtsingle 
vxms-37 
vxms-43 
xif-s25 

Ibearing rbearing ascent descent width 

16 16 
0 38 
0 25 
0 13 
0 20 
0 23 
0 31 
0 37 
0 23 
0 32 
0 22 
0 23 
0 20 
0 23 
0 31 
0 37 
0 32 
0 28 
0 16 
0 24 
0 25 
0 28 
0 31 
0 28 
0 38 
0 25 
0 30 
0 30 
0 35 
0 51 
0 27 
0 30 
0 28 
0 43 
0 189 
0 95 
0 38 
0 8 
0 9 
0 44 
0 56 
0 16 

11 
29 
19 
11 
16 
20 
24 
32 
20 
24 
20 
20 
16 
20 
24 
32 
24 
20 
27 
15 
21 
20 
22 
25 
30 
20 
22 
25 
26 
27 
20 
22 
25 
33 
100 
50 
32 
10 
12 
28 
35 
20 

3 
7 
6 
2 
4 
5 
7 
8 
5 
7 
5 
5 
4 
5 
7 
8 
7 
5 
9 
5 
4 
7 
8 
6 
10 
5 
8 
6 
9 
10 
5 
8 
6 
7 
12 
7 
8 
3 
3 
9 
8 
5 

16 
38 
25 
13 
20 
23 
31 
37 
23 
32 
22 
23 
20 
23 
31 
37 
32 
28 
16 
24 
25 
28 
31 
28 
38 
25 
30 
30 
35 
51 
27 
30 
28 
43 
189 
95 
38 
8 
9 
44 
56 
16 

646 

Xlib Reference Manual 



The remaining pages of this appendix show the characters in each font, actual size, as they 
would appear on a 900 x 1180 pixel, 10" x 13.5" screen (Sun). On a screen with different 
pixel density, these fonts would appear a proportionally different size. 

For most fonts, the entire character set is shown. For very large fonts, we have sometimes 
shown just a few characters to save space. Also, fonts that begin with many blank charac- 
ters are shown with most leading blanks removed. Therefore, you can't always get the char- 
acter number of each cell in the font by counting from the first cell we have shown. Use xfd 
to quickly determine the code for a particular cell. 

Appendix J: Fonts 647 



6x10 
< => ? A' CIEFO H I 3 KLh NO pQIRST U/WX y 
Z [,N ] ^_"abc de(gh ilj k lnoprstuvw 

6x12 

8x13 

648 

Xlib Reference Manual 



cyr-s25 

E F,XM K 
PCTUB 
, a 6 a e 

lIIAfi /1 
JI MHOFI 
I3  
 r :x lj K 

FXH 
3 

cyr-s30 
KJIMHO 
PCTYB 
)KRa 6 
H 

p c r yB 

Appendix J: Fonts 651 



fr2-25 

n o p t !vwxyz {  [ 

fr3-25 

frb-32 
ABCDEFGHI JK 
LMNOPORSUVWXYZ 
abcdefghi j kl mnopq 
rstuvwxyz 

Appendix J: Fonts 653 



fri-33 
:v ! ",X,&" ()+, 
-. Cf 2S4 56789: 

fril-25 

abe g' 
l rnno , 

654 Xlib Reference Manual 



fgs-22 

fixed 

/j012 45 B789 : ; <=> ?eIFBC DE'FGH I.IIKLN NO PQ RS TU!VI, I'X YZ [ \ ] 
"l-,'abcdef9hlijklnopJqrs:tulvwxyzi{I ]-~[111 IIIIIIII]11]1 

656 

Xlib Reference Manual 



fqxb-25 

" #$.&" ( ) +, -. /Ell 

:-< ? 
e h--klg 1 j mnopqrstuv 

wxyz{I i  

fr-25 

? @ ABC:DEFGHI JKLMNOPQRS 

L j m:no s uvwxyz 

Appendix J: Fonts 657 



fcor-20 

 .v ,,#$&, ( ) 
*+, --. /01 23456789: ; < => 
? @ABCDEFGHI JKLM:NOPQRS 
TUVWXYZ[ \] ^_ abcdefgh 
ij kl mnopqrs tuvwxyz 

fg-13 

#S&' ( )+,-. /81Z3q55?S9: 
FGHIJK_MNOPQRSTUVWXY[\]^_'aBcdef9 
i jklnopqrstuvxz{I}- 

fg-16 
{"#$,& ' ( )*+ ,-. /01,23456,2'89 - ;(=>? 
OABCDE F GHIJKLHNOPQRSTUVW)YZ[ ] 
abcdefgh1j klmnopqrstuvwxlYzl{ I }~ 

fg-18 
! "' #$%& ( ) * +, -. /01234567 
89- ; !<: > ?@ABCDEF GHI JK_MNOPQiRS 
TUVWXYZ[ \] ^ " abcdefghi jk mno 
pqrstuvwxyz- I }- 

Appendix J: Fonts 661 



hbr-s25 

hbr-s40 

664 

Xlib Reference Manual 



ipa-s25 

-./ 1 4  8 ,<-->  

BCDEFGHII JKLrlNOPQRSTUVI4 
XYZ [\] 1'e 'abcd!e f ghi j k lm 
,nopqr s tuvxgz { I } ~ 

Appendix J: Fonts 665 



sym-s53 

674 

Xlib Reference Manual 



vgb-25 

qr s t uvwxyz ~ 

vgb-31 

678 Xlib Reference Manual 



vgvb-31 
 i V- TI 
" -'   " I " 

<-> CD 
!' a c deaf g h I k 
I mnopqr s t uvw 
xyz{'j 

vmic-25 

bc e f ghi i I mn 13 
pq r st uv wx y z { I } 
,N 

682 Xlib Reference Manual 



vr-25 

Z[\]^_ abcde'fgh 
i j 'k 1 m n o p q r s t u v w 

vr-27 

_< '> = v ! " , $ y. &' ( ) 
* +, - f 01 23t5'67 
89 : ; : - > ?  A!BCDE 
11U V W YZ  _ a 

b c de f g hi j k 1 mn o 
pqr s t uvwxy z { } 

684 Xlib Reference Manual 



vr-30 

r  Y 6 T + 

NOP Q. RS TUVWXYZ 
[ \ ] "_' abc de fg 
hi j kl mnopq r s t 
u vwxy z { } ~f 

T 

.<>.-v ! ",%&' () 
*+,-. /01234567 
89: ; <-- >? @ABCDE 

F 6HI J KL NNOP QRS 

TUVyXYZI jk" ' 
_ a 
bcd f,gh 1 mno 

p q !r s t u v w x y z { } 

N 

Appendix J: Fonts 685 



vr-40 

,-. /01,2 

uV3 

E G I JK 

MNOP QRS TUVW 
:XYZ[ \ ]  a b 
c de f ghi ] kl m 

nopqrs 
'{ ,,, 
yz I } 

tuvwx 

686 

Xlib Reference Manual 



vrb-31 

45678 
AB CDE 

- 
9: ; <=>?@ 

FGHI J K L 1VI 

NOPQRS TUVWXYZ 

[hi! ' abcdefg 
] ki-mnop q r s t 

{ 
uvwxyz } 

688 Xlib Reference Manual 



vri-40 

 < > -- V ! " 
,  DE=FG 

HI JKLMNOP 
QRSTUVWXY 

1 mn o p q r s t 

Appendix J: Fonts 693 



vsg-114 

vsgn-57 

vshd-40 

694 

Xlib Reference Manual 



vxms-43 

696 

Xlib Reference Manual 



xif-s25 

,-. /012345B789: ; <=>?cA 
BCDEFGHI JK _tINOPQRST JVkl 
XYZ[ \] A_, abcdef ghi j kl m 
nopqr s t iuvxgz{ I } ~ 1111 

Appendix J: Fonts 697 



K 
Xlib Release 3 Update 

This appendix is an update to Volume Two, Xlib Reference Manual. It describes the 
changes to Xlib, and to application writing standards in general, that took place in Release 
3. Next, there is a description of corrections to the book based on Release 3 protocol clarifi- 
cations. Some of these apply to Release 2 as well. 

New Routines 

Five new routines have been added to Xlib in Release 3. They are all very simple, and in 
fact four of them could actually have been simple macros. Here are their definitions: 

Example K- 1. Code for routines added to Xlib in ReAease 3 Update 

long XMaxRequestSize(dpy) 
Display *dpy; 
{ 
return dpy->max_request_size; 
} 

char *XResourceManagerString(dpy) 
Display *dpy; 
{ 
return dpy->xdefaults; 
} - 

unsigned long XDisplayMotionBufferSize(dpy) 
Display *dpy; 
{ 
return dpy->motion_buffer; 
) 

XDisplayKeycodes(dpy, min_keycode_return, max_keycode_return) 
Display *dpy; 
int *min_keycode_return, *max_keycode_return; 
*min_keycode_return = dpy->min_keycode; 
*max_keycode_return = dpy->max_keycode; 

Appendix K: Xlib Release 3 Update 699 



Command Line Options 

The convention until Release 3 has been that any command line argument containing : was a 
display specification and any argument beginning with = was a geometry specification. 
These no longer hold, and none of the core clients now operate this way. Applications 
should require an explicit -display or -geometry option. The = in the geometry 
specification is now optional. 

Fonts 

There is no standard that specifies the fonts a server must provide. However, this should not 
be a portability problem for properly written applications, because fonts should be resources 
that can be specified by the user or system administrator. You'll probably want to "build 
in" default font names, either in an app-defaults file or in your code, but your code ought to 
be robust enough to fall back on the default font in the GC if all else fails. 
We bring this up because the font environment provided in the MIT distribution has 
changed substantially since Release 2. In Release 3, a unified family of fonts has been 
donated by Adobe, Inc. and BitStream, Inc. These include fonts of various sizes in the 
Courier, Times Roman, Helvetica, New Century Schoolbook, and Bitstream Charter families 
in regular weight, bold, and italic, and symbol fonts in various sizes from Adobe/DEC are 
also provided. Furthermore, font aliasing has been added so that font names in code and 
resource files can be long enough to fully describe a font, but the actual files containing the 
fonts may be 14 characters or less for compatibility with System V. An organized font- 
naming scheme has also been instituted. 
The new font names look like this:* 
-adobe-cou rie r-bo id-o-no rma i--I 0-10 0-7 5-7 5-m- 6 0-i so 8 8 5 9-1 
Because the font names that applications and users must specify are now so long, wildcards 
are now permitted as arguments to the Xlib routines XLoadFont, XQueryFont, and 
XLoadQueryFont. They were already permitted for the routines XListFonts and 
XL-i stFont sWith In f-o. 
To specify a font, you specify only the fields that are important to you. For example, if you 
wanted to use a 12 point Roman Courier font for an xterm, you could use the either of the 
following names: 
-adobe- cou rie r-medium- r-norma i-- 12-12 0- 7 5-7 5-m- 7 0-i so 8 8 5 9-1 
*-courier-*-r-*-I 2 0-* 
Note that you should match the point size field which is measured in tenths of a point (the 
120 in this example) rather than the pixel size field (the 12). This allows your defaults to 

*Most of this description of the new font-naming scheme was provided by Jim Fulton of the X Consortium. 

Appendix K: Xlib ReAease 3 Update 701 



work properly on tubes of different resolution. For example, to specify a 24 point, normal 
italic Charter, 
*-cha rt e r-medium-i-* -240-* 
will match either: 
-bit st ream-cha rt er-medium-i-normal--25-240- 75- 75-p- 136-i s o 8859-1 
-bit st ream-cha rt er-medium-i-no rma i--33-240-I 00-I 00-p-I 79-i so 8859-1 
depending on whether the 75 dpi or 100 dpi font directory comes first in your font path. 
This example also demonsates why the pixel size should not be used when wildcarding. 
On a 75 dpi monitor, a 24 point font will be 25 pixels tall; on a 100 dpi monitor, it will be 
33 pixels tall. 
If your application depends on the Release 2 fonts, they can be used with a Release 3 server 
by placing the Release 2 fonts in a directory and allowing users to add it to their font path 
(see the mkfontdir man page). If you have particular fonts that you want to use, and you 
have them in source (BDF) form, then most server vendors should supply a font compiler 
with their server, allowing you to import fonts. 

Internal and Invisible Changes to Xlib 

Xlib has been modified internally so that it will compile and run on Cray machines. This 
does not change the programming interface. Untested support for Mips computers has also 
been contributed. 

Other internal changes include improvements to Graphics Context cache flushing. The 
region code was improved, including fix for overflow on complex regions. 

Small Interface Changes 

The routines XChangeProperty and XGetWindowProperty now rake care of con- 
verting arrays of chars, shorts, and longs to and from the formats required by the protocol 
(8-bit, 16-bit, and 32-bit signed integers respectively). XGetWindowProperty now 
always mallocs space for its return data even if the data has zero elements. 
XLookupString now has list of key bindings per display, can cope with modifier map- 
ping changes, handles upper and lower case of all Latin-1 keysyms, doesn't convert non- 
Latin-1 keysyms, understands Control 2-8 and/, and uses the preferred protocol definition 
for CapsLock. 
XrmPutFileDatabase will write file with proper special char quoling. 

702 

Xlib Reference Manual 



Server Fixes 

Some problems that existed in sample server code affected application programming under 
Release 2. You may wish to inspect programs for workarounds for these problems. We 
cannot list and explain all the bugs that were found and fixed; see the CHANGES file in the 
appropriate directory of the X distribution. However, the following changes to the device- 
independent (dix) part of the server were among the most likely to affect client program- 
ming: 

The AllocColorPlanes request has been fixed to allow allocation of all planes at 
once. 
Delayed/Buffered writes for client events implemented. Delayed writes are simply a per- 
formance improvement; the server now queues all events generated by a single request 
for greater network efficiency. Buffered writes fix a bug that appeared when reading 
long properties from the server. Client connections would be severed when the client 
refused or was slow in reading a long message from the server. 
SelectionClear events are now sent to the selection owner (set by xSet- 
SelectionOwner, not the window creator. 
Font routines and color name lookup routines now fold upper case in names to lower 
case. Case is no longer significant in the color database, and items in the database 
differing only in case have been removed. 
Save under support has been added to the device-independent portion of the server. This 
code supplies save unders to any server which has backing store but not save unders 
implemented in the device-dependent portion. 
Mixing window gravity and bit gravity has been fixed. 
Many other specious requests also generate Value errors now. 

The Xmu library 

A new miscellaneous utilities library has been placed on the X distribution tape. This 
library is not part of the Xlib standard. It contains routines which only use public interfaces 
so that it may be layered on top of any proprietary implementation of Xlib or Xt. 
It is intended to support clients in the MIT distribution; vendors may choose not to distri- 
bute this library if they wish. Therefore, applications developers who depend on this library 
should be prepared to treat it as part of their software base when porting. 
The following routines apply to Xlib (there are a few not described here that are for use with 
the X Toolkit): 

Routines to cache atoms, avoiding multiple server round-trips. XmuMakeAtom creates 
and initializes an opaque AtomRec. XmuInternAtora fetches an atom from cache or 
server. XmuInternStrings fetches multiple atoms as strings. XmuGetAtomNarae 
returns name of an atom. XmuNameOfAtora returns name from an AtomPtr. 

Appendix K: Xlib Release 3 Update 703 



XmuCreatePixmapFromBitmap routine converts a bitmap to a pixmap. The routine 
uses xc opyP i ane). 
XmuConvertStandardSelection converts a known selection into the appropriate 
target type. 
XmuPrintDefaultErrorMessage prints a nice error that looks like the usual mes- 
sage. Returns 1 if the caller should consider exiting, else 0. 
.XmuDrawRoundedRectangle draws a rounded rectangle, x, y, w, h are the dimen- 
sions of the rectangle, ew and eh are the sizes of a bounding boxes that each corner is 
drawn inside of. 

XmuReadBitmapDataFromFile reads X10 or Xll format bitmap files and return 
data. 

Release 3 Protocol Clarifications 

The following changes are not errors, per se. They reflect clarifications of the protocol 
specification made in Release 3. These changes, where noted, were also true in Release 2. 
Page 36 
The return type from XAddPixel is deleted. XAddPixel has its value argument 
changed from int to long. 
Page 53 
XChangeActivePointerGrab is capable of generating a BadValue error. 
Page 70 
XCheckMaskEvent has its mask argument changed from unsigned long to long. 
Page 73 
XCheckWindowEvent has its mask argument changed from int to long. 
Page 77 
On the XClearArea page, the first sentence of the third paragraph should end: "... the 
rectangle is tiled with a plane__mask of all l's, a function of GXcopy, and a 
subwindow._mode or ClipByChildren." This should be true in Release 2. 
Page 90 
XCopyGC now generates a BadValue error when bits outside the set of valid GC mask 
bits are set. 
Page 92 
The plane argument of XCopyPlane must be a plane that exists in the source drawable, 
or a BadValue error is generated. 

7O4 

Xlib Reference Manual 



Page 213 
On the second page of XGet Image, the first sentence should say that the source window 
must be viewable, not just mapped (all its ancestors also must be mapped). The page should 
also mention that the pointer cursor is not included in the image. This is also true in 
Release 2. 
Page 219 
The XTimeCoord structure has its x and y members changed from type unsigned 
short tO short. 
Page 248 
The XGrabButton page should mention that the call overrides all previous passive grabs 
by the same client on the same key/button combinations on the same window. This is also 
true in Release 2. 
Page 255 
For XGrabPointer, the constant GrabNotViewable is returned for the reasons given 
at the bottom of the page, but also if the confine_to window is completely outside the 
root window. This was true in Release 2. 
Page 284 
The string that XLookupString returns in the buffer argument is in Latin-1 encoding, 
not necessarily in ASCII. (Latin-1 uses codes 128 to 255 to specify foreign characters, 
while ASCII uses only up to 127. ASCII is a subset of Latin-1.) 
Page 291 
The event_mask argument of XMaskEvent changes from unsigned long tO long. 
Page 349 
The XReparentWindow page should say that the reparenting leaves unchanged the abso- 
lute coordinates (relative tO the root window) of the upper-left outer comer of the window. 
This was true in Release 2. 
Page 391 
The event mask argument of XSelectInput changes from type unsigned long to 
type long. 
Page 393 
Th'e event_mask argument of XSendEvent changes from type unsigned long to 
type long. dso, XSendEvent can now generate a BadValue error if the event type 
sent is not valid in the core or an extension. 
Page 410 
The error_code, request_code, and minor_code members of XErrorEvent 
have been changed from type char to type unsigned char. 
Page 429 
In the paragraph about server restrictions on the XSetModifierMapping page, it should 
mention that one restriction may be that it might not be possible tO disable autO-repeat on 
certain keys. This is also true in Release 2. 

Appendix K: Xlib Release 3 Update 705 



0 
0 
0 

At-a-glance 707 



At-a-glance 709 



About the Editor 

Adrian Nye is a senior technical writer at O'Reilly and Associates. In addition 
to the X Window System programming manuals, he has written user's manuals 
for data acquisition products, and customized UNIX documentation for Sun 
Microsystems and Prime. Adrian has also worked as a programmer writing 
educational software in C, and as a mechanical engineer designing offshore oil- 
spill cleanup equipment. He has long-term interests in using his technical 
writing skills to promote recycling and other environmentally-sound 
technologies. He graduated from the Massachusetts Institute of Technology in 
1984 with a B.S. in Mechanical Engineering. 



[--] Please send me the information 
I have asked for on the reverse 
side of this card. 

PLACE 
STAMP 
HERE 

Name 

Company __ 

Address _ 

City __ 

State. ZIP 
(Fill out or tape 
business card here) 

Nutshell Handbooks 
.u+s.ELL, O'Reilly & Associates. Inc. 
I I 632 Petaluma Avenue 
,+mt3BOOKS Sebastopol CA 95472 

1] Please send me the information 
I have asked for on the reverse 
side of this card. 

PLACE 
STAMP 
HERE 

Name 

Company 

Address 

City 

State. ZIP 
(Fill out or tape 
business card here) 

Nutshell Handbooks 
,o+s.ELL O'Reilly & Associates. Inc. 
I I 632 Petaluma Avenue 
.A,DBOO,S Sebastopol CA 95472 



Volume Two: Xlib Reference Manual 

This book provides a complete reference to the X library, which is the lowest 
level of programming interface to X. It provides: 

Reference pages for each Xlib function 
A permuted index to the Xlib functions 
Reference pages for each event type 
Description of macros 
A listing of the standard color name database 
Alphabetical index and description of structures 
Alphabetical index and description of defined symbols 
Alist ofkeysyms and their meanings, including sample characters 
A list and illustration of the standard cursor font 
A list of standard fonts with illustration of each font 
A function group index, for finding the right routine for a 
particular task 
Single-page reference aids for the GC and window attributes 

The Xlib Programming Manual and Xlib Reference Manual have been licensed and 
customized by major system vendors, including Apollo, Silicon Graphics, Stellar, 
Masscomp and Motorola. Other companies, including Intergraph, Sequent, 
Pyramid, and Graphics Software Systems, are planning to ship the generic version 
of the manuals with their systems. 

723 pages 

Volume 2: ISBN 0-937175-28-5 Set: ISBN 0-937175-26-9 

O'Reilly & Associates, Inc. 
I