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

The Definitive Guides
to the X Window System

Volume Two

Xlib Reference
Manual

for Version 11

O Reilly & Associates, Inc.

Volume Two

Xlib Reference
Manual

for Version 11 of the
X Window System

edited by Adrian Nye

O Reilly & Associates, Inc.

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

Revision and Printing History

August 1988: First Printing.

November 1988: Second Printing. Minor revisions.

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

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

July 1990: Fifth Printing. Minor revisions.

Small Print

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

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

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

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

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

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

The X Window System

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

Volume 0:

X Protocol Reference Manual

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

Volumes 1 and 2:

Xlib Programming Manual

Xlib Reference Manual

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

Volume 3:

X Window System User s Guide

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

Volumes 4 and 5:

X Toolkit Intrinsics Programming Manual

X Toolkit Intrinsics Reference Manual

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

Volume 7:

XView Programming Manual

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

The X Window System in a Nutshell

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

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

O Reilly & Associates, Inc.

Creators and Publishers of Nutshell Handbooks

632 Petaluma Avenue. Sebastopol. CA 95472

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

Table of Contents

Page

Preface xvii

About This Manual xvii

Summary of Contents xvii

How to Use This Manual xviii

Example Programs xix

Assumptions xx

Font Conventions Used in This Manual xx

Related Documents

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

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

Xt Toolkit Widgets by Ralph Swick and Terry Weissman

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

X Window System Protocol, Version 11 by Robert Scheifler

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

Volume Zero X Protocol Reference Manual

Volume Three X Window System User s Guide

Volume Four X Toolkit Intrinsics Programming Manual

Volume Five X Toolkit Intrinsics Reference Manual

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

Volume Seven XView Programmer s Guide

Quick Reference The X Window System in a Nutshell

Requests for Comments

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

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

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

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

Preface xxi

Bulk Sales Information

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

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

Acknowledgements

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

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

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

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

xxii Xlib Reference Manual

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

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

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

Adrian Nye

Preface

Permuted Index

How to Use the Permuted Index

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

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

The Permuted Index

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

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

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

XDrawImageStringl6: draw 16-bit image text characters XDrawImageStringl6

XDrawTextl6: draw 16-bit polytext strings XDrawTextl6

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

XDrawImageString: draw 8-bit image text characters XDrawImageString

XDrawText: draw 8-bit polytext strings XDrawText

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

/disable or enable access control XSetAccessControl

XAddHost: add a host to the access control list XAddHost

add multiple hosts to the access control list XAddHosts: XAddHosts

/remove a host from the access control list XRemoveHost

/remove multiple hosts from the access control list XRemoveHosts

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

XDisableAccessControl: allow access from any host XDisableAccessControl

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

XActivateScreenSaver: activate screen blanking XActivateScreenSaver

release the keyboard from an active grab XUngrabKeyboard: XUngrabKeyboard

release the pointer from an active grab XUngrabPointer: XUngrabPointer

/change the parameters of an active pointer grab XChangeActivePointerGrab

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

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

Permuted Index

XInsertModifiermapEntry: add a new entry to an/ XInsertModifiermapEntry

XUnionRectWithRegion: add a rectangle to a region XUnionRectWithRegion

a/ XrmQPutStringResource: add a resource specification to XrmQPutStringResource

a resource/ XrmPutLineResource: add a resource specification to XrmPutLineResource

with/ XrmPutStringResource: add a resource specification XrmPutStringResource

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

control list XAddHosts: add multiple hosts to the access XAddHosts

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

XrmUniqueQuark: allocate a new quark XrmUniqueQuark

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

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

XAllocClassHint: allocate an XClassHint structure XAUocClassHint

XAllocIconSize: allocate an XlconSize structure XAllocIconSize

XAllocSizeHints: allocate an XSizeHints structure XAllocSizeHints

XAllocStandardColormap: allocate an XStandardColormap/ XAllocStandardColormap

XAllocWMHints: aUocate an XWMHints structure XAllocWMHints

structure XCreatelmage: allocate memory for an Xlmage XCreatelmage

freed Xpermalloc: allocate memory never to be Xpermalloc

XAllocColorPlanes: aUocate read/write/ XAUocColorPlanes

colorceUs XAUocColorCeUs: aUocate read/write (nonshared) XAUocColorCeUs

XFree: free specified memory aUocated by an Xlib function XFree

XFreeFontPath: free the memory aUocated by XGetFontPath XFreeFontPath

XFreeFontNames: free the memory aUocated by XListFonts XFreeFontNames

XFreeFontlnfo: free the memory aUocated by XListFonts Withlnfo XFreeFontlnfo

XFreeExtensionList: free memory aUocated for a list of/ XFreeExtensionList

table, /free the memory aUocated for an association XDestroyAssocTable

XDisableAccessControl: aUow access from any host XDisableAccessControl

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

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

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

contents of one database into another /merge the XrmMergeDatabases

subtract one region from another XSubtractRegion: XSubtractRegion

system from one window to another /change the coordinate XTranslateCoordinates

/move the pointer to another point on the screen XWarpPointer

/insert a window between another window and its parent XReparentWindow

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

/convert a keysym to the appropriate keycode XKeysymToKeycode

XFiUArc: fdl an arc XFiUArc

XDrawArc: draw an arc fitting inside a rectangle XDrawArc

XSetArcMode: set the arc mode in a graphics context XSetArcMode

XDrawArcs: draw multiple arcs XDrawArcs

XFiUArcs: fiU multiple arcs XFiUArcs

fiU a rectangular area XFiURectangle: XFillRectangle

XClearArea: clear a rectangular area in a window XClearArea

XCopyArea: copy an area of a drawable XCopyArea

fiU multiple rectangular areas XFillRectangles: XFillRectangles

database from command line arguments /load a resource XrmParseCommand

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

properties in the properties array /rotate XRotateWindowProperties

/obtain RGB values for an array of colorceUs XQueryColors

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

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

XDefineCursor: assign a cursor to a window XDefineCursor

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

/deaUocate storage associated with a region XDestroyRegion

/change a property associated with a window XChangeProperty

XDestroylmage: deallocate memory associated with an image XDestroylmage

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

Xlib Reference Manual

/the XStandardColoimap structure associated with the specified/ XGetRGBColormaps

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

/delete an entry from an association table XDeleteAssoc

/free the memory allocated for an association table XDestroyAssocTable

obtain data from an association table XLookUpAssoc: XLookUpAssoc

create an entry in an association table XMakeAssoc: XMakeAssoc

XCreateAssocTable: create a new association table (X10) XCreateAssocTable

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

get a font property given its atom XGetFontProperty: XGetFontProperty

/set the XA_WM_COMMAND atom (command line arguments) XSetCommand

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

XGetWindowProperty: obtain the atom type and property format/ XGetWindowProperty

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

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

/set the colormap attribute for a window XSetWindowColormap

/set the background pixel value attribute of a window XSetWindowBackground

/change the background tile attribute of a window XSetWindowBackgroundPixmap

/set window attributes XChangeWindow Attributes

create a window and set attributes XCreateWindow: XCreate Window

/obtain the current attributes of window XGetWindow Attributes

/turn off the keyboard auto-repeat keys X AutoRepeatOff

turn on the keyboard auto-repeat keys XAutoRepeatOn: XAutoRepeatOn

XPutBackEvent: push an event back on the input queue XPutBackEvent

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

XSetWindowBackground: set the background pixel value attribute/ XSetWindowBackground

XSelBackground: set the background pixel value in a/ XSetBackground

window /change the background tile attribute of a XSetWindowBackgroundPixmap

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

XBell: ring the bell (Control G) XBell

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

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

/calculate the difference between the union and/ XXorRegion

XDrawLine: draw a line between two points XDrawLine

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

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

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

/create a pixmap with depth from bitmap data XCreatePixmapFromBitmapData

/create a bitmap from XI 1 bitmap format data XCreateBitmapFromData

XReadBitmapFile: read a bitmap from disk XReadBitmapFile

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

XWriteBitmapFile: write a bitmap to a file XWriteBitmapFile

create a cursor from two bitmaps XCreatePixmapCursor: XCreatePixmapCursor

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

activate screen blanking XActivateScreenSaver: XActivateScreenSaver

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

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

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

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

/change the border width of a window XSetWindowBorderWidth

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

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

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

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

return data from a cut buffer XFetchBuffen XFetchBuffer

from pointer motion history buffer /get events XGetMotionEvents

store data in a cut buffer XStoreBuffer: XStoreBuffer

return data from cut buffer XFetchBytes: XFetchBytes

XStoreBytes: store data in cut buffer XStoreBytes

Permuted Index

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

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

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

XRotateBuffers: rotate the cut buffers XRotateBuffers

XGrabButton: grab a pointer button XGrabButton

XUngrabButton: release a button from a passive grab XUngrabButton

/get the pointer button mapping XGetPointerMapping

/set the pointer button mapping XSetPointerMapping

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

the union and/ XXorRegion: calculate the difference between XXorRegion

user geometry string/ XGeometry: calculate window geometry given XGeometry

/set a function called after all Xlib functions XSetAfterFunction

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

with a window XChangeProperty: change a property associated XChangeProperty

value/ XSetWindowBorder: change a window border pixel XSetWindowBorder

XSetWindowBorderPixmap: change a window border tile/ XSetWindowBorderPixmap

XResize Window: change a window s size XResize Window

context to/ XSetClipRectangles: change clip_mask in a graphics XSetClipRectangles

XOffsetRegion: change offset of a region XOffsetRegion

XSetWindowBackgroundPixmap: change the background tile/ XSetWindowBackgroundPixmap

window XSetWindowBorderWidth: change the border width of a XSetWindowBorderWidth

client XSetCloseDownMode: change the close down mode of a XSetCloseDownMode

XRecolorCursor: change the color of a cursor XRecolorCursor

graphics context XChangeGC: change the components of a given XChangeGC

from one/ XTranslateCoordinates: change the coordinate system XTranslateCoordinates

XChangeKeyboardMapping: change the keyboard mapping XChangeKeyboardMapping

such as/ XChangeKeyboardControl: change the keyboard preferences XChangeKeyboardControl

XChangeActivePointerGrab: change the parameters of an/ XChangeActivePointerGrab

XChangePointerControl: change the pointer preferences XChangePointerControl

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

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

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

siblings XRestack Windows: change the stacking order of XRestack Windows

property XSetStandardColormap: change the standard colormap XSetStandardColormap

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

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

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

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

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

draw 8-bit image text characters XDrawImageString: XDrawImageString

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

matching event XChecklfEvent: check the event queue for a XChecklfEvent

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

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

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

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

/circulate the stacking order of children up or down XCirculateSubwindows

the/ XCirculateSubwindowsDown: circulate the bottom child to XCirculateSubwindowsDown

children/ XCirculateSubwindows: circulate the stacking order of XCirculateSubwindows

bottom/ XCirculateSubwindowsUp: circulate the top child to the XCirculateSubwindowsUp

matches the desired depth and class /visual information that XMatchVisuallnfo

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

/get a resource from name and class as strings XrmGetResource

window XClearArea: clear a rectangular area in a XClearArea

XClearWindow: clear an entire window XClearWindow

keyboard preferences such as key click /change the XChangeKeyboardControl

rebind a keysym to a string for client XRebindKeysym: XRebindKeysym

change the close down mode of a client XSetCloseDownMode: XSetCloseDownMode

Xlib Reference Manual

XKillClient: destroy a client or its remaining/ XKillClient

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

XOpenDisplay: connect a client program to an X server XOpenDisplay

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

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

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

context XSetClipOrigin: set the clip origin in a graphics XSetClipOrigin

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

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

context XSetClipMask: set clip_mask pixmap in a graphics XSetClipMask

XSetaoseDownMode: change the close down mode of a client XSetCloseDownMode

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

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

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

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

XQueryBestCursor: get the closest supported cursor sizes XQueryBestCursor

obtain a description of error code XGetErrorText: XGetErrorText

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

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

a read-only colorcell from color name /allocate XAllocNamedColor

RGB values from color name /hardware-supported XLookupColor

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

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

XRecolorCursor: change the color of a cursor XRecolorCursor

read/write (nonshareable) color planes /allocate XAllocColorPlanes

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

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

/allocate a read-only colorcell from color name XAllocNamedColor

allocate read/write (nonshared) colorcells XAllocColorCells: XAllocColorCells

RGB values for an array of colorcells XQueryColors: obtain XQueryColors

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

XCreateColormap: create a colormap XCreateColormap

colormap and install the default colormap /delete a XFreeColormap

XInstallColormap: install a colormap XlnstallColormap

XFreeColormap: delete a colormap and install the default/ XFreeColormap

XCopyColonmapAndFree: copy a colormap and return a new/ XCopyColormapAndFree

XSetWindowColormap: set the colormap attribute for a window XSetWindowColormap

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

XFreeColors: free colormap cells or planes XFreeColors

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

/copy a colormap and return a new colormap ID XCopyColormapAndFree

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

/get the standard colormap property XGetStandardColormap

/change the standard colormap property XSetStandardColormap

/get a list of installed colormaps XListlnstalledColormaps

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

/load a resource database from command line arguments XrmParseCommand

/set the XA_WM_COMMAND atom (command line arguments) XSetCommand

/set the graphics_exposures component in a graphics context XSetGraphicsExposures

/set the line drawing components in a graphics context XSetLineAttributes

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

context XChangeGC: change the components of a given graphics XChangeGC

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

regions XIntersectRegion: compute the intersection of two XIntersectRegion

XUnionRegion: compute the union of two regions XUnionRegion

server XOpenDisplay: connect a client program to an X XOpenDisplay

XDrawLines: draw multiple connected lines XDrawLines

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

Permuted Index

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

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

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

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

XrmMcrgeDatabases: merge the contents of one database into/ XnmMcrgcDatahascs

components of a given graphics context XChangeGC: change the XChangcGC

XCopyGC: copy a graphics context XCopyGC

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

XFreeGC: free a graphics context XFreeGC

with the specified graphics context /ID) associated XGContextFromGC

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

set the arc mode in a graphics context XSetArcMode: XSetArcMode

pixel value in a graphics context /set the background XSetBackground

clipjmask pixmap in a graphics context XSetClipMask: set XSetClipMask

the clip origin in a graphics context XSetClipOrigin: set XSetClipOrigin

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

set the fill rule in a graphics context XSetFillRule: XSetFillRule

set the fill style in a graphics context XSetFillStyle: XSetFillStyle

the current font in a graphics context XSetFont: set XSetFont

pixel value in a graphics context /set the foreground XSetForeground

logical operation in a graphics context /set the bitwise XSetFunction

component in a graphics context /the graphics_exposures XSetGraphicsExposures

drawing components in a graphics context /set the line XSetLJneAttributes

set the plane mask in a graphics context XSetPlaneMask: XSetPlaneMask

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

set the stipple in a graphics context XSetStipple: XSetStipple

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

set the fill tile in a graphics context XSetTile: XSetTile

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

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

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

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

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

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

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

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

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

disable or enable access control XSetAccessControl: XSetAccessControl

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

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

XBell: ring the bell (Control G) XBell

add a host to the access control list XAddHost: XAddHost

add multiple hosts to the access control list XAddHosts: XAddHosts

remove a host from the access control list XRemoveHost: XRemoveHost

multiple hosts from the access control list /remove XRemoveHosts

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

and pointer/ XAllowEvents: control the behavior of keyboard XAllowEvents

XrmStringToBindingQuarkList: convert a key string to a/ XrmStringToBindingQuarkList

list XrmStringToQuarkList: convert a key string to a quark XrmStringToQuarkUst

XKeycodeToKeysym: convert a keycode to a keysym XKeycodeToKeysym

a keysym XStringToKeysym: convert a keysym name string to XStringToKeysym

string XKeysymToString: convert a keysym symbol to a XKeysymToString

appropriate/ XKeysymToKeycode: convert a keysym to the XKeysymToKeycode

XrmQuarkToString: convert a quark to a string XrmQuarkToString

XrmStringToQuark: convert a string to a quark XrmStringToQuark

window to another /change the coordinate system from one XTranslateCoordinates

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

XCopyGC: copy a graphics context XCopyGC

Xlib Reference Manual

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

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

XCopyArea: copy an area of a drawable XCopyArea

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

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

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

XCreateColormap: create a colormap XCreateColormap

XCreateGlyphCursor: create a cursor from font glyphs XCreateGlyphCursor

standard/ XCreateFontCursor: create a cursor from the XCreateFontCursor

XCreatePixmapCursor: create a cursor from two bitmaps XCreatePixmapCursor

XrmGetStringDatabase: create a database from a string XrmGetStringDatabase

mapping/ XNewModifiermap: create a keyboard modifier XNewModifiermap

(X10) XCreateAssocTable: create a new association table XCreateAssocTable

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

XCreateRegion: create a new empty region XCreateRegion

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

XCreatePixmap: create a pixmap XCreatePixmap

XCreatePixmapFromBitmapData: create a pixmap with depth from/ XCreatePixmapFromBitmapData

an image XSublmage: create a subimage from part of XSublmage

attributes XCreateWindow: create a window and set XCreate Window

association table XMakeAssoc: create an entry in an XMakeAssoc

window XCreateSimple Window: create an unmapped InputOutput XCreateSimple Window

XGetWindow Attributes: obtain the current attributes of window XGetWindow Attributes

context XSetFont: set the current font in a graphics XSetFont

XGetFontPath: get the current font search path XGetFontPath

XGetGeometry: obtain the current geometry of drawable XGetGeometry

XGetlnputFocus: return the current keyboard focus window XGetlnputFocus

/obtain a list of the current keyboard preferences XGetKeyboardControl

XQueryPointer: get the current pointer location XQueryPointer

XGetPointerControl: get the current pointer preferences XGetPointerControl

XGetScreenSaver: get the current screen saver parameters XGetScreenSaver

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

XFreeCursor: release a cursor XFreeCursor

change the color of a cursor XRecolorCursor: XRecolorCursor

a cursor from the standard cursor font /create XCreateFontCursor

XUndefineCursor: disassociate a cursor from a window XUndefineCursor

XCreateGlyphCursor: create a cursor from font glyphs XCreateGlyphCursor

XCreateFontCursor: create a cursor from the standard cursor/ XCreateFontCursor

XCreatePixmapCursor: create a cursor from two bitmaps XCreatePixmapCursor

get the closest supported cursor sizes XQueryBestCursor: XQueryBestCursor

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

XDefineCursor: assign a cursor to a window XDefineCursor

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

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

XFetchBuffer: return data from a cut buffer XFetchBuffer

XStoreBuffer: store data in a cut buffer XStoreBuffer

XFetchBytes: return data from cut buffer XFetchBytes

XStoreBytes: store data in cut buffer XStoreBytes

XRotateBuffers: rotate the cut buffers XRotateBuffers

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

a bitmap from XI 1 bitmap format data /create XCreateBitmapFromData

a pixmap with depth from bitmap data, /create XCreatePixmapFromBitmapData

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

XFetchBuffer: return data from a cut buffer XFetchBuffer

XLookUpAssoc: obtain data from an association table XLookllpAssoc

XFetchBytes: return data from cut buffer XFetchBytes

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

XStoreBuffer: store data in a cut buffer XStoreBuffer

Permuted Index

XStoreBytes: store

window and/ XSaveContext: save a

option value from the resource

error messages from the error

destroy a resource

specification to a resource

specification into a resource

XrmGetFileDatabase: retrieve a

XrmGetStringDatabase: create a

XrmParseCommand: load a resource

/store a resource

/merge the contents of one

/return a list of

XLookupColor: get

/a resource specification to a

a resource specification into a

with an image XDestroylmage:

with a region XDestroyRegion:

or disable synchronization for

a colormap and install the

given user geometry string and

/uninstall a colormap; install

the default/ XFreeColormap:

given window/ XDeleteContext:

XDeleteProperty:

association/ XDeleteAssoc:

XDeleteModifiermapEntry:

access control list to allow or

that matches the desired

a drawable into a drawable with

/create a pixmap with

/for a given screen with the

XListDepths: determine the

XGetErrorText: obtain a

information that matches the

remaining/ XKillClient:

XrmDestroyDatabase:

XDestroyWindow: unmap and

window XDestroySubwindows:

modifier/ XFreeModifiermap:

region XPointlnRegion:

in a region XRectlnRegion:

XEmptyRegion:

the same size,/ XEqualRegion:

on a given screen XListDepths:

XXorRegion: calculate the

XSetAccessControl:

XSynchronize: enable or

window XUndefineCursor:

an X server and/ XCloseDisplay:

XDrawSegments: draw multiple

read a bitmap from

program from an X server and

of hosts having access to this

XFlush: flush the request buffer

name (when connection to a

a/ XDisplayName: report the

XSetlconName: set the name to be

data in cut buffer

data value corresponding to a

database /extract an

database /obtain

XStoreBytes

XSaveContext

XGetDefault

XGetErrorDatabaseText

database. XrmDestroyDatabase: XrmDestroyDatabase

database /add a resource XrmPutLineResource

database /store a resource XrmPutResource

database from a file XrmGetFileDatabase

database from a string XrmGetStringDatabase

database from command line/ XrmParseCommand

database in a file XrmPutFileDatabase

database into another XrmMergeDatabases

database levels XrmQGetSearchList

database RGB values and closest/ XLookupColor

database using a quark resource/ XrmQPutStringResource

database using quarks /store XrmQPutResource

deallocate memory associated XDestroylmage

deallocate storage associated XDestroyRegion

debugging XSynchronize: enable XSynchronize

default colormap /delete XFreeColormap

default geometry /geometry XGeometry

default if not already installed XUninstallColormap

delete a colormap and install XFreeColormap

delete a context entry for a XDeleteContext

delete a window property XDeleteProperty

delete an entry from an XDeleteAssoc

delete an entry from an/ XDeleteModifiermapEntry

deny connection requests /use XEnableAccessControl

depth and class /information XMatchVisuallnfo

depth, applying pixel values /of XCopyPlane

depth from bitmap data XCreatePixmapFromBitmapData

depth of the specified drawable XCreateGC

depths available on a given/ XListDepths

description of error code XGetErrorText

desired depth and class /visual XMatchVisuallnfo

destroy a client or its XKillClient

destroy a resource database XrmDestroyDatabase

destroy a window and all/ XDestroyWindow

destroy all subwindows of a XDestroySubwindows

destroy and free a keyboard XFreeModifiermap

determine if a point is inside a XPointlnRegion

determine if a rectangle resides XRectlnRegion

determine if a region is empty XEmptyRegion

determine if two regions have XEqualRegion

determine the depths available XListDepths

difference between the union and/ XXorRegion

disable or enable access control XSetAccessControl

disable synchronization for/ XSynchronize

disassociate a cursor from a XUndefineCursor

disconnect a client program from

disjoint lines

disk XReadBitmapFile:

display /disconnect a client

display /obtain a list

... XCloseDisplay
XDrawSegments
XReadBitmapFile
XCloseDisplay
XlistHosts
XFlush
XDisplayName

(display all queued requests)

display fails) /the display

display name (when connection to XDisplayName

displayed in a window s icon XSetlconName

Xlib Reference Manual

XGetlconName: get the name to be

next event that matches mask;

queue that matches event type;

passed window and passed mask;

stacking order of children up or

/change the close

characters XDrawImageStringl6:

XDrawTextl6:

XDrawImageString :

XDrawText:

from vertex list/ XDrawFilled:
XDrawLine:
XDrawPoint:

vertex list (from X10) XDraw:

foreground only XDrawString:

rectangle XDrawArc:

pixmap XPutlmage:

XDrawRectangle:

XDraw Arcs:

XDrawUnes:

XDra wSegments :

XDrawPoints:

rectangles XDrawRectangles:

XDrawStringl6:

XCopyArea: copy an area of a

with the depth of the specified

obtain the current geometry of

depth J /copy a single plane of a

contents of a rectangle from

the/ /copy a rectangle in

/plane of a drawable into a

XSetLine Attributes: set the line

determine if a region is

XCreateRegion: create a new

XSetAccessControl: disable or

synchronization/ XSynchronize:

generate the smallest rectangle

XClearWindow: clear an

XDeleteContext: delete a context

XDeleteAssoc: delete an

structure /delete an

XMakeAssoc: create an

structure /add a new

/values of a read/write colormap

obtain a description of

/obtain error messages from the

XSetErrorHandler: set a nonfatal

XGetErrorDatabaseText: obtain

/and wait for all events and

modifier keys (Shift, Control,

as modifiers (Shift, Control,

the event queue for a matching

XSendEvent: send an

XPutBackEvent: push an

set a nonfatal error

window /return the next

event type;/ /return the next

procedure/ XPeeklfEvent: get an

displayed in an icon

don t wait /remove the

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

don t wait /event matching both
down /circulate the

down mode of a client

draw 16-bit image text

draw 1 6-bit polytext strings

draw 8 -bit image text characters

draw 8-bit polytext strings

draw a filled polygon or curve

draw a line between two points

draw a point

draw a polyline or curve between ....

draw an 8-bit text string

draw an arc fitting inside a

draw an image on a window or

draw an outline of a rectangle

draw multiple arcs

draw multiple connected lines

draw multiple disjoint lines

draw multiple points

draw the outlines of multiple

draw two-byte text strings

drawable

drawable /for a given screen

drawable XGetGeometry:

drawable into a drawable with

drawable into an image /place

drawable to a location within

drawable with depth, applying/

drawing components in a graphics/ .

empty XEmptyRegion:

empty region

enable access control

enable or disable

enclosing a region XQipBox:

entire window

entry for a given window and/

entry from an association table

entry from an XModifierKeymap ....

entry in an association table

entry to an XModifierKeymap

entry to the closest possible/

error code XGetErrorText:

error database

error event handler

error messages from the error/

errors to be processed by the/

etc.) /obtain a mapping of

etc.) /set keycodes to be used

event XChecklfEvent: check

event back on the input queue

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

event in queue that matches

event matched by predicate

, XGetlconName

, XCheckMaskEvent

, XCheckTypedEvent

, XCheckWindowEvent

, XCirculateSubwindows

, XSetCloseDownMode

, XDrawImageString 16

,XDrawTextl6

, XDrawImageString

, XDrawText

, XDrawFilled

.XDrawLine

, XDrawPoint

.XDraw

. XDrawString

. XDrawArc

. XPutlmage

. XDrawRectangle

. XDrawArcs

. XDrawLines

. XDrawSegments

. XDrawPoints

. XDrawRectangles

.XDrawString 16

. XCopyArea

. XCreateGC

. XGetGeometry

. XCopyPlane

. XGetlmage

. XGetSublmage

. XCopyPlane

: XSetLineAttributes

. XEmptyRegion

. XCreateRegion

. XSetAccessControl

. XSynchronize

. XClipBox

. XClearWindow

. XDeleteContext

. XDeleteAssoc

. XDeleteModifiermapEntry

. XMakeAssoc

. XInsertModifiermapEntry

. XStoreColor

. XGetErrorText

. XGetErrorDatabaseText

. XSetErrorHandler

. XGetErrorDatabaseText

.XSync

. XGetModifierMapping

. XSetModifierMapping

. XChecklfEvent

. XSendEvent

, XPutBackEvent

, XSetErrorHandler

, XCheckTypedWindowEvent

, XCheckTypedEvent

, XPeeklfEvent

Permuted Index

procedure XlfEvent: wait for

window and/ /remove the next

XNextEvent: get the next

the number of events in the

XChecklfEvent: check the

XMaskEvent: remove the next

XCheckMaskEvent: remove the next

XWindowEvent: remove the next

and/ XLookupString: map a key

next event in queue that matches

window XSelectlnput: select the

the queue XPeekEvent: get an

the number of pending input

request buffer and wait for all

history/ XGetMotionEvents: get

/check the number of

/behavior of keyboard and pointer

server XNoOp: send a NoOp to

XShrinkRegion: reduce or

XQueryExtension: get

for a list of installed

Xlib and/ /return a list of all

resource database XGetDefault:

(when connection to a display

XQueryBestTile: obtain the

XQueryBestStipple: obtain the

retrieve a database from a

store a resource database in a

write a bitmap to a

XFillPolygon:

XFillRectangle:

XFillArc:

XLoadQueryFont: load a font and

XFillArcs:

XFillRectangles:

XSetFillRule:setthe

XSetFillStyle: set the

XSetTilersetthe

obtain the fastest supported

vertex list/ XDrawFilled: draw a

structures that/ XGetVisuallnfo:

XDrawArc: draw an arc

/obtain the RGB values and

return the number of/ XPending:

wait for all events and/ XSync:

(display all queued/ XFlush:

return the current keyboard

XSetlnputFocus: set the keyboard

cursor from the standard cursor

information about a loaded

XUnloadFont: unload a

XLoadQueryFont: load a

font/ XFreeFont: unload a

create a cursor from

font if not already loaded; get

font ID XLoadFont: load a

XSetFont: set the current

query the server for string and

event matched in predicate

event matching both passed

event of any type or window

event queue /check

event queue for a matching event

event that matches mask

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

event type; don t wait /the

event types to be sent to i

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

events /buffer and return

events and errors to be/ /the

events from pointer motion

events in the event queue

events when these resources are/ ....

exercise connection with the

expand the size of a region

extension information

extensions /memory allocated

extensions to X supported by

extract an option value from the

fails) /report the display name

fastest supported fill tile/

fastest supported stipple shape

file XrmGetFileDatabase:

file XrmPutFileDatabase:

file XWriteBitmapFile:

fill a polygon

fill a rectangular area

fill an arc

fill information structure

fill multiple arcs

fill multiple rectangular areas

fill rule in a graphics context

fill style in a graphics context

fill tile in a graphics context

fill tile shape XQueryBestTile:

filled polygon or curve from

find the visual information

fitting inside a rectangle

flags for a specified colorcell

flush the request buffer and

flush the request buffer

focus window XGetlnputFocus: ...

focus window

font /create a

font XQueryFont: return

font and fill information/

font and free storage for the

font glyphs XCreateGlyphCursor:

font ID XLoadFont: load a

font if not already loaded; get

font in a graphics context

font metrics XQueryTextExtents: .

. XlfEvent

. XCheckWindowEvent

. XNextEvent

. XEventsQueued

. XChecklfEvent

.XMaskEvent

. XCheckMaskEvent

. XWindowEvent

. XLookupString

. XCheckTypedEvent

, XSelectlnput

. XPeekEvent

. XPending

.XSync

. XGetMotionEvents

. XEventsQueued

. XAllowEvents

.XNoOp

. XShrinkRegion

. XQueryExtension

. XFreeExtensionList

. XListExtensions

.XGetDefault

. XDisplayName

. XQueryBestTile

. XQueryBestStipple

. XrmGetFileDatabase

. XrmPutFileDatabase

. XWriteBitmapFile

. XFillPolygon

. XFillRectangle

. XFillArc

, XLoadQueryFont

, XFillArcs

, XFillRectangles

.XSetFillRule

, XSetFillStyle

.XSetTile

, XQueryBestTile

, XDrawFilled

, XGetVisuallnfo

, XDrawArc

, XQueryColor

, XPending

, XSync

, XFlush

, XGetlnputFocus

, XSetlnputFocus

, XCreateFontCursor

, XQueryFont

, XUnloadFont

, XLoadQueryFont

, XFreeFont

, XCreateGlyphCursor

, XLoadFont

, XSetFont

, XQueryTextExtents

Xlib Reference Manual

XTextExtents: get string and font metrics locally XTextExtents

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

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

return a list of the available font names XlistFonts: XUstFonts

XGetFontProperty: get a font property given its atom XGetFontProperty

XGetFontPath: get the current font search path XGetFontPath

XSetFontPath: set the font search path XSetFontPath

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

and information about loaded fonts /obtain the names XListFontsWithlnfo

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

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

XSetForeground: set the foreground pixel value in a/ XSetForeground

/create a bitmap from XI 1 bitmap format data XCreateBitmapFromData

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

/obtain the supported pixmap formats for a given server XUstPixmapFormats

XFreeGC: free a graphics context XFreeGC

XFreeModifiermap: destroy and free a keyboard modifier mapping/ XFreeModifiermap

XFreePixmap: free a pixmap ID XFreePixmap

XFreeColors: free colormap cells or planes XFreeColors

of/ XFreeExtensionList: free memory allocated for a list XFreeExtensionUst

by an Xlib function XFree: free specified memory allocated XFree

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

associated/ XFreeStringlist: free the in-memory data XFreeStringList

XGetFontPath XFreeFontPath: free the memory allocated by XFreeFontPath

XUstFonts. XFreeFontNames: free the memory allocated by XFreeFontNames

XFreeFontlnfo: free the memory allocated by/ XFreeFontlnfo

association/ XDestroyAssocTable: free the memory allocated for an XDestroyAssocTable

allocate memory never to be freed Xpermalloc: Xpermalloc

memory allocated by an Xlib function XFree: free specified XFree

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

XSetAfterFunction: set a function called after all Xlib/ XSetAfterFunction

a function called after all Xlib functions /set XSetAfterFunction

XBell: ring the bell (Control G) XBell

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

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

XGContextFromGC: obtain the GContext (resource ID)/ XGContextFromGC

XPolygonRegion: generate a region from points XPolygonRegion

standard window/ XParseGeometry: generate position and size from XParseGeometry

enclosing a region XClipBox: generate the smallest rectangle XClipBox

user geometry string and default geometry /window geometry given XGeometry

XGeometry: calculate window geometry given user geometry/ XGeometry

XWMGeometry: obtain a window s geometry information XWMGeometry

XGetGeometry: obtain the current geometry of drawable XGetGeometry

and size from standard window geometry string /position XParseGeometry

/window geometry given user geometry string and default/ XGeometry

atom XGetFontProperty: get a font property given its XGetFontProperty

XListlnstalledColormaps: get a list of installed/ XListlnstaUedColormaps

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

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

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

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

predicate/ XPeeklfEvent: get an event matched by XPeeklfEvent

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

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

closest/ XLookupColor: get database RGB values and XLookupColor

history/ XGetMotionEvents: get events from pointer motion XGetMotionEvents

XQuery Extension: get extension information XQuery Extension

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

Permuted Index 1 1

XGetlconSizes: get preferred icon sizes XGetlconSizes

locally XTextExtents: get string and font metrics XTextExtents

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

sizes XQueryBestCursor: get the closest supported cursor XQueryBestCursor

XGetFontPath: get the current font search path XGetFontPath

XQueryPointer: get the current pointer location XQueryPointer

preferences XGetPointerControl: get the current pointer XGetPointerControl

parameters XGetScreenSaver: get the current screen saver XGetScreenSaver

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

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

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

XGetPointerMapping: get the pointer button mapping XGetPointerMapping

window XListProperties: get the property list for a XListProperties

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

property XGetStandardColormap: get the standard colormap XGetStandardColormap

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

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

a window XGetClassHint: get the XA_WM_CLASS property of XGelClassHint

property/ XGetTransientForHint: get the XA_WM_TRANSIENT_FOR XGetTransientForHint

create a cursor from font glyphs XCreateGlyphCurson XCreateGlyphCursor

parameters of an active pointer grab /change the XChangeActivePointerGrab

release a button from a passive grab XUngrabButton: XUngrabButton

release a key from a passive grab XUngrabKey: XUngrabKey

the keyboard from an active grab XUngrabKeyboard: release XUngrabKeyboard

the pointer from an active grab XUngrabPointer: release XUngrabPointer

release the server from grab XUngrabServer: XUngrabServer

XGrabKey: grab a key XGrabKey

XGrabButton: grab a pointer button XGrabButton

XGrabKeyboard: grab the keyboard XGrabKeyboard

XGrabPointer: grab the pointer XGrabPointer

XGrabServer: grab the server XGrabServer

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

change the components of a given graphics context XChangeGC: XChangeGC

XCopyGC: copy a graphics context XCopyGC

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

XFreeGC: free a graphics context XFreeGC

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

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

set the arc mode in a graphics context XSetArcMode: XSetArcMode

the background pixel value in a graphics context /set XSetBackground

set clip_mask pixmap in a graphics context XSetClipMask: XSetClipMask

/set the clip origin in a graphics context XSetClipOrigin

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

set the fill rule in a graphics context XSetFillRule: XSetFillRule

set the fill style in a graphics context XSetFillStyle: XSetFUlStyle

set the current font in a graphics context XSetFont: XSetFont

the foreground pixel value in a graphics context /set XSetForeground

bitwise logical operation in a graphics context /set the XSetFunction

/component in a graphics context XSetGraphicsExposures

the line drawing components in a graphics context /set XSetLineAttributes

set the plane mask in a graphics context XSetPlaneMask: XSetPlaneMask

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

set the stipple in a graphics context XSetStipple: XSetStipple

/set the subwindow mode in a graphics context XSetSubwindowMode

XSetTile: set the fill tile in a graphics context XSetTile

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

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

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

12 Xlib Reference Manual

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

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

XSetGraphicsExposures: set the graphics_exposures component in/ XSetGraphicsExposures

set a nonfatal error event handler XSetErrorHandlen XSetErrorHandler

entry to the closest possible hardware color /colormap XStoreColor

to the closest possible hardware colors /colorcells XStoreColors

/colormap cell with closest hardware-supported color XAllocColor

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

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

ASCII color name or translate hexadecimal value /values from XParseColor

read the window manager hints property XGetWMHints: XGetWMHints

set a window manager hints property XSetWMHints: XSetWMHints

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

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

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

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

/get events from pointer motion history buffer XGetMotionEvents

allow access from any host XDisableAccessControl: XDisableAccessControl

list XRemoveHosl: remove a host from the access control XRemoveHost

XAddHost: add a host to the access control list XAddHost

XRemoveHosts: remove multiple hosts from the access control/ XRemoveHosts

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

XAddHosts: add multiple hosts to the access control list XAddHosts

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

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

XGetlconSizes: get preferred icon sizes XGetlconSizes

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

that a top-level window be iconified /request XlconifyWindow

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

and return a new colormap ID /copy a colormap XCopyColormapAndFree

XFreePixmap: free a pixmap ID XFreePixmap

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

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

/obtain the visual ID from a Visual XVisuallDFrom Visual

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

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

memory associated with an image XDestroylmage: deallocate XDestroylmage

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

a single pixel value from an image XGetPixel: obtain XGetPixel

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

set a pixel value in an image XPutPixel: XPutPixel

a subimage from part of an image XSublmage: create XSublmage

XPutlmage: draw an image on a window or pixmap XPutlmage

XDrawImageString: draw 8-bit image text characters XDrawImageString

XDrawImageStringl6: draw 16-bit image text characters XDrawImageString 16

XQueryExtension: get extension information XQueryExtension

obtain a window s geometry information XWMGeometry: XWMGeometry

XQueryFont: return information about a loaded font XQueryFont

/obtain the names and information about loaded fonts XListFontsWithlnfo

/load a font and fill information structure XLoadQueryFont

XGetVisuallnfo: find the visual information structures that/ XGetVisuallnfo

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

Xrmlnitialize: initialize the resource manager Xrmlnitialize

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

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

push an event back on the input queue XPutBackEvent: XPutBackEvent

/create an unmapped InputOutput window XCreateSimple Window

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

Permuted Index 13

XDrawArc: draw an arc fitting inside a rectangle XDrawArc

determine if a point is inside a region XPointlnRegion: XPointlnRegion

XInstallColormap: install a colormap XListallColormap

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

/delete a colormap and install the default colormap XFreeColormap

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

/get a list of installed colormaps XListlnstalledColormaps

memory allocated for a list of installed extensions /free XFreeExtensionList

XIntersectRegion: compute the intersection of two regions XIntersectRegion

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

XGrabKey: grab a key XGrabKey

the keyboard preferences such as key click /change XChangeKeyboardControl

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

XUngrabKey: release a key from a passive grab XUngrabKey

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

XrrnStringToQuarkList: convert a key string to a quark list XrmStringToQuarkList

XGrabKeyboard: grab the keyboard XGrabKeyboard

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

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

XAutoRepeatOff : turn off the keyboard auto-repeat keys XAutoRepeatOff

XAutoRepeatOn: turn on the keyboard auto-repeat keys XAutoRepeatOn

/return the current keyboard focus window XGetlnputFocus

XSetlnputFocus: set the keyboard focus window XSetlnputFocus

XUngrabKeyboard: release the keyboard from an active grab XUngrabKeyboard

/change the keyboard mapping XChangeKeyboardMapping

structure /destroy and free a keyboard modifier mapping XFreeModifiermap

XNewModifiermap: create a keyboard modifier mapping/ XNewModifiermap

/obtain a list of the current keyboard preferences XGetKeyboardControl

click /change the keyboard preferences such as key XChangeKeyboardControl

a keysym to the appropriate keycode /convert XKeysymToKeycode

the keysym corresponding to a keycode in structure /get XLookupKeysym

XKeycodeToKeysym: convert a keycode to a keysym XKeycodeToKeysym

XRefreshKeyboardMapping: read keycode-keysym mapping from/ XRefreshKeyboardMapping

return symbols for keycodes XGetKeyboardMapping: XGetKeyboardMapping

/obtain the range of legal keycodes for a server XDisplayKeycodes

XSetModifierMapping: set keycodes to be used as modifiers/ XSetModifierMapping

off the keyboard auto-repeat keys XAutoRepeatOff: turn XAutoRepeatOff

turn on the keyboard auto-repeat keys XAutoRepeatOn: XAutoRepeatOn

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

convert a keycode to a keysym XKeycodeToKeysym: XKeycodeToKeysym

a keysym name string to a keysym XStringToKeysym: convert XStringToKeysym

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

keycode/ XLookupKeysym: get the keysym corresponding to a XLookupKeysym

XStringToKeysym: convert a keysym name string to a keysym XStringToKeysym

XKeysymToString: convert a keysym symbol to a string XKeysymToString

XRebindKeysym: rebind a keysym to a string for client XRebindKeysym

XKeysymToKeycode: convert a keysym to the appropriate/ XKeysymToKeycode

/obtain the range of legal keycodes for a server XDisplayKeycodes

return a list of database levels XrmQGetSearchList: XrmQGetSearchList

a resource database from command line arguments /load XrmParseCommand

the XA_WM_COMMAND atom (command line arguments) /set XSetCommand

XDrawLine: draw a line between two points XDrawLine

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

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

draw multiple connected lines. XDrawLines: XDrawLines

draw multiple disjoint lines XDrawSegments: XDrawSegments

add a host to the access control list XAddHost: XAddHost

hosts to the access control list XAddHosts: add multiple XAddHosts

14 Xlib Reference Manual

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

a host from the access control list XRemoveHost: remove XRemoveHost

hosts from the access control list /remove multiple XRemoveHosts

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

convert a key string to a quark list XrmStringToQuarkList: XrmStringToQuarkList

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

/search prepared list for a given resource XrmQGetSearchResource

/get the property list for a window XListProperties

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

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

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

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

XrmQGetSearchList: return a list of database levels XrmQGetSearchList

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

XListlnstalledColormaps: get a list of installed colormaps XListlnstalledColormaps

/free memory allocated for a list of installed extensions XFreeExtensionUst

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

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

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

XListFonts: return a list of the available font names XListFonts

XGetKeyboardControl: obtain a list of the current keyboard/ XGetKeyboardControl

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

structure XLoadQueryFont: load a font and fill information XLoadQueryFont

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

command line/ XrmParseCommand: load a resource database from XrmParseCommand

return information about a loaded font XQueryFont: XQueryFont

the names and information about loaded fonts /obtain XListFonts Withlnfo

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

get string and font metrics locally XTextExtents: XTextExtents

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

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

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

get the current pointer location XQueryPointer: XQueryPointer

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

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

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

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

order XLowerWindow: lower a window in the stacking XLowerWindow

initialize the resource manager Xrmlnitialize: Xrmlnitialize

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

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

XGetWMHints: read the window manager hints property XGetWMHints

XSetWMHints: set a window manager hints property XSetWMHints

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

/set a window s standard window manager properties XSetWMProperties

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

XMapWindow: map a window XMap Window

siblings XMapRaised: map a window on top of its XMapRaised

XMapSub windows: map all subwindows of window XMapSubwindows

change the keyboard mapping XChangeKeyboardMapping: ... XChangeKeyboardMapping

get the pointer button mapping XGetPointerMapping: XGetPointerMapping

set the pointer button mapping XSetPointerMapping: XSetPointerMapping

/read keycode-keysym mapping from server into Xlib XRefreshKeyboardMapping

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

and free a keyboard modifier mapping structure /destroy XFreeModifiermap

/create a keyboard modifier mapping structure XNewModifiermap

the next event that matches mask XMaskEvent: remove XMaskEvent

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

Permuted Index 15

the next event that matches

both passed window and passed

XSetPlaneMask: set the plane

/logical function, and plane

/information structures that

XPeeklfEvent: get an event

XlfEvent: wait for event

/the next event in queue that

remove the next event that

/remove the next event that

/the visual information that

/remove the next event that

passed/ /remove the next event

check the event queue for a

/return the next event in queue

function XFree: free specified

XFreeFontPath: free the

XFreeFontNames: free the

XFreeFontlnfo: free the

XFreeExtensionList: free

XDestroyAssocTable: free the

XDestroy Image: deallocate

XCreatelmage: allocate

Xpermalloc: allocate

database/ XrmMergeDatabases:

/obtain error

the server for string and font

get string and font

/the server for string and font

stringy /get string and font

XSetStandardProperties: set the

XSetArcMode: set the arc

/set the subwindow

/change the close down

etc.) /obtain a mapping of

/destroy and free a keyboard

/create a keyboard

/set keycodes to be used as

/get events from pointer

XMoveWindow:

point on the/ XWarpPointer:

XDrawArcs: draw

XFillArcs: fill

XDrawLines: draw

XDrawSegments: draw

control/ XRemoveHosts: remove

control list XAddHosts: add

XDrawPoints: draw

/draw the outlines of

XFillRectangles: fill

a read-only colorcell from color

RGB values from color

a read/write colorcell by color

/get a resource value using

/get a resource from

database using a quark resource

with separate resource

Uom XGetAtomName: get a string

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

mask in a graphics context

match the specified template ,

matched by predicate procedure/ ,

matched in predicate procedure

matches event type; don t wait

matches mask XMaskEvent: ,

matches mask; don t wait

matches the desired depth and/ ,

matches the specified mask and/

matching both passed window and ....

matching event XChecklfEvent:

matching type and window

memory allocated by an Xlib

memory allocated by XGetFontPath .

memory allocated by XUstFonts

memory allocated by/

memory allocated for a list of/

memory allocated for an/

memory associated with an image

memory for an Xlmage structure

memory never to be freed

merge the contents of one

messages from the error database

metrics /Query

metrics locally XTextExtents:

metrics of a 16-bit character/

metrics of a 16-bit character

minimum set of properties for/

mode in a graphics context

mode of a client

modifier keys (Shift, Control,

modifier mapping structure

modifiers (Shift, Control, etc.)

motion history buffer

move a window

move the pointer to another

multiple arcs

multiple connected lines

multiple disjoint lines

multiple hosts from the access

multiple hosts to the access

multiple points

multiple rectangles

multiple rectangular areas

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

name /set RGB values of

name and class as quarks

name and class as strings

name and string value Ao a

name and value /specification

name for a property given its

, XCheckMaskEvent

. XCheckWindowEvent

. XSetPlaneMask

.XSetState

.XGetVisuallnfo

. XPeeklfEvent

. XlfEvent

. XCheckTypedEvent

. XMaskEvent

. XCheckMaskEvent

. XMatchVisuallnfo

. XWindowEvent

.XCheckWindowEvent

. XChecklfEvent

. XCheckTypedWindowEvent

.XFree

. XFreeFontPath

. XFreeFontNames

. XFreeFontlnfo

. XFreeExtensionList

. XDestroyAssocTable

. XDestroylmage

. XCreatelmage

. Xpermalloc

. XrmMergeDatabases

. XGetErrorDatabaseText

. XQueryTextExtents

. XTextExtents

. XQueryTextExtents 1 6

.XTextExtents 16

. XSetStandardProperties

. XSetArcMode

. XSetSubwindowMode

. XSetCloseDownMode

. XGetModifierMapping

. XFreeModifiermap

, XNewModifiermap

. XSetModifierMapping

, XGetMotionEvents

. XMoveWindow

. XWarpPointer

. XDrawArcs

. XFillArcs

, XDrawLines

. XDrawSegments

. XRemoveHosts

. XAddHosts

. XDrawPoints

, XDrawRectangles

. XFillRectangles

. XAllocNamedColor

. XLookupColor

. XStoreNamedColor

. XrmQGetResource

. XrmGetResource

. XrmQPutStringResource

, XrmPutStringResource

, XGetAtomName

Xlib Reference Manual

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

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

/convert a keysym name string to a keysym XStringToKeysym

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

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

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

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

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

a list of the available font names XlistFonts: return XUstFonts

XUstFontsWithlnfo: obtain the names and information about/ XListFontsWithlnfo

Xpermalloc: allocate memory never to be freed Xpermalloc

XCreateAssocTable: create a new association table (X10) XCreateAssocTable

/copy a colormap and return a new colormap ID XCopyColormapAndFree

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

XCreateRegion: create a new empty region XCreateRegion

XInsertModifiermapEntry: add a new entry to an XModifierKeymap/ XlnsertModifiermapEntry

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

XrmUniqueQuark: allocate a new quark XrmUniqueQuark

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

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

XCheckWindowEvent: remove the next event matching both passed/ XCheckWindowEvent

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

XMaskEvent: remove the next event that matches mask XMaskEvent

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

XWindowEvent: remove the next event that matches the/ XWindowEvent

XSetErrorHandler: set a nonfaial error event handler XSetErrorHandler

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

/allocate read/write (nonshared) colorcells XAllocColorCells

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

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

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

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

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

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

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

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

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

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

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

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

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

code XGetErrorText: obtain a description of error XGetErrorText

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

XTextPropertyToStringLJst: obtain a list of strings from a/ XTextPropertyToStringLJst

keyboard/ XGetKeyboardControl: obtain a list of the current XGetKeyboardControl

keys/ XGetModifierMapping: obtain a mapping of modifier XGetModifierMapping

an image XGetPixel: obtain a single pixel value from XGetPixel

information XWMGeometry: obtain a window s geometry XWMGeometry

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

table XLookUpAssoc: obtain data from an association XLookUpAssoc

error/ XGetErrorDatabaseText: obtain error messages from the XGetErrorDatabaseText

of colorcells XQueryColors: obtain RGB values for an array XQueryColors

property/ XGetWindowProperty: obtain the atom type and XGetWindowProperty

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

window XGetWindow Attributes: obtain the current attributes of XGetWindow Attributes

drawable XGetGeometry: obtain the current geometry of XGetGeometry

fill tile shape XQueryBestTile: obtain the fastest supported XQueryBestTile

stipple/ XQueryBestStipple: obtain the fastest supported XQueryBestStipple

Permuted Index

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

about/ XlistFontsWithlnfo: obtain the names and information XListFontsWithlnfo

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

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

formats for/ XListPixmapFormats: obtain the supported pixmap XListPixmapFormats

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

that matches/ XMatchVisuallnfo: obtain the visual information XMatchVisuallnfo

structure/ XGetRGBColormaps: obtain the XStandardColormap XGetRGBColormaps

turn the screen saver on or off XForceScreenSaver: XForceScreenSaver

keys XAutoRepeatOff : turn off the keyboard auto-repeat XAutoRepeatOff

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

XOffsetRegion: change offset of a region XOffsetRegion

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

/set the bitwise logical operation in a graphics context XSetFunction

XGetDefault: extract an option value from the resource/ XGetDefault

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

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

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

lower a window in the stacking order XLowerWindow: XLowerWindow

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

/circulate the stacking order of children up or down XCirculateSubwindows

/change the stacking order of siblings XRestack Windows

XSetClipOrigin: set the clip origin in a graphics context XSetClipOrigin

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

XDrawRectangle: draw an outline of a rectangle XDrawRectangle

XDrawRectangles: draw the outlines of multiple rectangles XDrawRectangles

XGetSelectionOwner: return the owner of a selection XGetSelectionOwner

XSetSelectionOwner: set the owner of a selection XSetSelectionOwner

get the current screen saver parameters XGetScreenSaver: XGetScreenSaver

grab /change the parameters of an active pointer XChangeActivePointerGrab

XSetScreenSaver: set the parameters of the screen saver XSetScreenSaver

between another window and its parent /insert a window XReparentWindow

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

create a subimage from part of an image XSublmage: XSuhlmage

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

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

release a button from a passive grab XUngrabButton: XUngrabButton

XUngrabKey: release a key from a passive grab XUngrabKey

get the current font search path XGetFontPath: XGetFontPath

set the font search path XSetFontPath: XSetFontPath

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

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

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

window /set the background pixel value attribute of a XSetWindowBackground

XGetPixel: obtain a single pixel value from an image XGetPixel

context /set the background pixel value in a graphics XSetBackground

context /set the foreground pixel value in a graphics XSetForeground

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

XPutPixel: set a pixel value in an image XPutPixel

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

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

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

XCreatePixmap: create a pixmap XCreatePixmap

draw an image on a window or pixmap XPutlmage: XPutlmage

server /obtain the supported pixmap formats for a given XListPixmapFormats

XFreePixmap: free a pixmap ID XFreePixmap

XSetClipMask: set clip_mask pixmap in a graphics context XSetClipMask

data, /create a pixmap with depth from bitmap XCreatePixmapFromBitmapData

18 Xlib Reference Manual

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

XSetPlaneMask: set the plane mask in a graphics context XSetPlaneMask

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

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

read/write (nonshareable) color planes /allocate XAllocColorPlanes

free colormap cells or planes XFreeColors: XFreeColors

XDrawPoint: draw a point XDrawPoint

XPointlnRegion: determine if a point is inside a region XPointlnRegion

/move the pointer to another point on the screen XWarpPointer

XGrabPointer: grab the pointer XGrabPointer

XGrabButton: grab a pointer button XGrabButton

XGetPointerMapping: get the pointer button mapping XGetPointerMapping

XSetPointerMapping: set the pointer button mapping XSetPointerMapping

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

XUngrabPointer: release the pointer from an active grab XUngrabPointer

the parameters of an active pointer grab /change XChangeActivePointerGrab

XQueryPointer: get the current pointer location XQueryPointer

/get events from pointer motion history buffer XGetMotionEvents

/change the pointer preferences XChangePointerControl

/get the current pointer preferences XGetPointerControl

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

draw a line between two points XDrawLine: XDrawLJne

XDrawPoints: draw multiple points XDrawPoints

generate a region from points XPolygonRegion: XPolygonRegion

XFillPolygon: fill a polygon XFillPolygon

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

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

XDrawText: draw 8-bit polylext strings XDrawText

XDrawTextl6: draw 16-bit polytext strings XDrawTextl6

window/ XParseGeometry: generate position and size from standard XParseGeometry

/change the size and position of a window XMoveResize Window

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

/colormap entry to the closest possible hardware color XStoreColor

/colorcells to the closest possible hardware colors XStoreColors

wait for event matched in predicate procedure XlfEvent: XlfEvent

/get an event matched by predicate procedure without/ XPeeklfEvent

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

/change the pointer preferences XChangePointerControl

a list of the current keyboard preferences /obtain XGetKeyboardControl

get the current pointer preferences XGetPointerControl: XGetPointerControl

/change the keyboard preferences such as key click XChangeKeyboardControl

XGetlconSizes: get preferred icon sizes XGetlconSizes

XrmQGetSearchResource: search prepared list for a given/ XrmQGetSearchResource

for event matched in predicate procedure XlfEvent: wait XlfEvent

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

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

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

XOpenDisplay: connect a client program to an X server XOpenDisplay

read one of a window s text properties XGetTextProperty: XGetTextProperty

set one of a window s text properties XSetTextProperty: XSetTextProperty

window s standard window manager properties /set a XSetWMProperties

/rotate properties in the properties array XRotateWindowProperties

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

XRotateWindowProperties: rotate properties in the properties/ XRotateWindowProperties

XDeleteProperty: delete a window property XDeleteProperty

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

associated with the specified property /structure XGetRGBColormaps

get the standard colormap property XGetStandardColormap: XGetStandardColormap

Permuted Index 19

read the window manager hints

read a window s XA_WM_ICON_NAME

read a window s XA_WM_NAME

a window s XA_WM_NORMAL_HINTS

read a window s XA_WM_SEE_fflNTS

the value of the XA_WM_ICON_SIZE

change the standard colormap

set a window s WM_CLffiNT_MACHINE

a window s WM_COLORMAP_WINDOWS

set a window manager hints

set a window s XA_WM_ICON_NAME

set a window s XA_WM_NAME

a window s XA_WM_NORMAL_fflNTS

set a window s WM_PROTOCOLS

set a window s WM_SEE_HINTS

XChangeProperty: change a

/set the XA_WM_TRANSIENT_FOR

/obtain the atom type and

/get a string name for a

XGetFontProperty: get a font

XUstProperries: get the

/return an atom for a given

/gettheXA_WM_CLASS

/gettheXA_WM TRANSffiNT_FOR

/settheXA_WM_CLASS

state (not/ /get the size hints

state (not/ /set the size hints

/read the size hints

/set the size hints

XGetSizeHints: read any

/set the value of any

queue XPutBackEvent:

convert a string to a

XrmUniqueQuark: allocate a new

string to a binding list and a

/convert a key string to a

value Ao a database using a

XrmQuarkToString: convert a

value using name and class as

into a database using

font metrics XQueryTextExtents:

font/ XQueryTextExtents 16:

number of events in the event

without removing it from the

push an event back on the input

XChecklfEvent: check the event

/return the next event in

don t/ /return the next event in

the request buffer (display all

stacking order XRaiseWindow:

XDisplayKeycodes: obtain the

XReadBitmapFile:

property XGetWMIconName:

property XGetWMName:

XGetWMNormalHints:

property XGetWMSizeHints:

XA_SIZE_HINTS XGetSizeHints:

property XGetWMHints:

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

property /read

property XGetWMSizeHints:

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

property XSetStandardColormap: .
property XSetWMClientMachine:
property /set

.XGetWMHints

.XGetWMIconName

.XGetWMName

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

property XSetWMHints:

property XSetWMIconName:

property. XSetWMName:

property XSetWMNormalHints: set

property XSetWMProtocols:

property XSetWMSizeHints: XSetWMSizeHints

property associated with a/ XChangeProperty

property for a window XSetTransientForHint

property format for a window XGetWindowProperty

property given its atom XGetAtomName

property given its atom XGelFontProperty

property list for a window XListProperties

property name string XIntemAtom

property of a window XGetClassHint

property of a window XGetTransientForHint

property of a window XSetClassHint

property of a window in normal XGetNormalHints

property of a window in normal XSetNormalHints

property of a zoomed window XGetZoomHints

property of a zoomed window XSetZoomHints

property of type XA_SIZE_HINTS XGetSizeHints

property of type XA_SEE_HINTS XSetSizeHints

push an event back on the input XPutBackEvent

quark XrmStringToQuark: XrmStringToQuark

Quark XrmUniqueQuark

quark list /convert a key XrmStringToBindingQuarkList

quark list XrmStringToQuarkList

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

quark resource name and string

quark to a string

quarks /get a resource

quarks /a resource specification

query the server for string and

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

queue XEventsQueued: check the ...

queue XPeekEvent: get an event XPeekEvent

queue /by predicate procedure XPeeklfEvent

queue XPutBackEvent: XPutBackEvent

queue for a matching event XChecklfEvent

queue matching type and window XCheckTypedWindowEvent

queue that matches event type; XCheckTypedEvent

queued requests) XFlush: flush XFlush

raise a window to the top of the XRaiseWindow

range of legal keycodes for a/ XDisplayKeycodes

read a bitmap from disk XReadBitmapFile

read a window s XA_WM_ICON_NAME XGetWMIconName

read a window s XA_WM_NAME XGetWMName

read a window s/ XGetWMNormalHints

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

Xlib Reference Manual

server/ XRefreshKeyboardMapping: read keycode-keysym mapping from XRefreshKeyboardMapping

properties XGetTextProperty: read one of a window s text XGetTextProperty

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

property XGetWMHints: read the window manager hints XGetWMffints

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

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

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

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

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

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

XAllocColorCells: allocate read/write (nonshared)/ XAllocColorCells

client XRebindKeysym: rebind a keysym to a string for XRebindKeysym

that a top-level window be reconfigured /request XReconfigureWMWindow

draw an arc fitting inside a rectangle XDrawArc: XDrawArc

draw an outline of a rectangle XDrawRectangle: XDrawRectangle

XClipBox: generate the smallest rectangle enclosing a region XClipBox

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

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

XRectlnRegion: detemune if a rectangle resides in a region XRectlnRegion

XUnionRectWithRegion: add a rectangle to a region XUnionRectWithRegion

draw the outlines of multiple rectangles XDrawRectangles: XDrawRectangles

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

XFillRectangle: fill a rectangular area XFillRectangle

XClearArea: clear a rectangular area in a window XClearArea

XFillRectangles: fill multiple rectangular areas XFillRectangles

region XShrinkRegion: reduce or expand the size of a XShrinkRegion

smallest rectangle enclosing a region XClipBox: generate the XClipBox

create a new empty region XCreateRegion: XCreateRegion

storage associated with a region /deallocate XDestroyRegion

change offset of a region XOffsetRegion: XOffsetRegion

determine if a point is inside a region XPointlnRegion: XPointlnRegion

if a rectangle resides in a region XRectlnRegion: determine XRectlnRegion

context to the specified region /of the graphics XSetRegion

reduce or expand the size of a region XShrinkRegion: XShrinkRegion

add a rectangle to a region XUnionRectWithRegion: XUnionRectWithRegion

XSubtractRegion: subtract one region from another XSubtraciRegion

XPolygonRegion: generate a region from points XPolygonRegion

XFjnptyRegion: determine if a region is empty XEmptyRegion

compute the intersection of two regions XIntersectRegion: XIntersectRegion

compute the union of two regions XUnionRegion: XUnionRegion

union and intersection of two regions /difference between the XXorRegion

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

grab XUngrabButton: release a button from a passive XUngrabButton

XFreeCursor: release a cursor XFreeCursor

grab XUngrabKey: release a key from a passive XUngrabKey

active grab XUngrabKeyboard: release the keyboard from an XUngrabKeyboard

active grab XUngrabPointer: release the pointer from an XUngrabPointer

XUngrabServer: release the server from grab XUngrabServer

/destroy a client or its remaining resources XKillClient

control list XRemoveHost: remove a host from the access XRemoveHost

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

client s/ XRemoveFromSaveSet: remove a window from the XRemoveFromSaveSet

access control/ XRemoveHosts: remove multiple hosts from the XRemoveHosts

both passed/ XCheckWindowEvent: remove the next event matching XCheckWindowEvent

matches mask XMaskEvent: remove the next event that XMaskEvent

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

matches the/ XWindowEvent: remove the next event that XWindowEvent

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

Permuted Index 21

/by predicate procedure without

border pixel value attribute and

window border tile attribute and

connection to a/ XDisplayName:

number of/ XPending: flush the

events and/ XSync: flush the

queued/ X Flush: flush the

be iconified Xlconify Window:

be/ XReconfigureWMWindow:

be withdrawn XWithdraw Window:

list to allow or deny connection

buffer (display all queued

XResetScreenSaver:

/determine if a rectangle

search prepared list for a given

extract an option value from the

XrmDestroyDatabase: destroy a

a resource specification to a

a resource specification into a

line/ XrmParseCommand: load a

XrmPutFileDatabase: store a

strings XrmGetResource: get a

the/ /obtain the GContext

Xrmlnitialize: initialize the

Ao a database using a quark

/specification with separate

XrmQPutResource: store a

XrmPutResource: store a

XrmQPutStringResource: add a

XrmPutLineResource: add a

XrmPutStringResource: add a

class as/ XrmQGetResource: get a

a client or its remaining

and pointer events when these

XrmGetFileDatabase:

to X supported/ XListExtensions:

parent, and root XQueryTree:

XrmQGetSearchList:

font names XListFonts:

/copy a colormap and

property name/ XInternAtom:

XFetchBuffer:

XFetchBytes:

loaded font XQueryFont:

XGetKeyboardMapping:

focus window XGetlnputFocus:

XCheckTypedWindowEvent:

that matches/ XCheckTypedEvent:

/flush the request buffer and

XGetSelectionOwner:

XLookupColor: get database

XQueryColor: obtain the

colorcells XQueryColors: obtain

or/ XParseColor: look up

/and closest hardware-supported

colorcelV XStoreNamedColor: set

XStoreColor: set or change the

XStoreColors: set or change the

removing it from the queue ,

repaint the border /a window ,

repaint the border /change a ,

report the display name (when ,

request buffer and return the ,

request buffer and wait for all

request buffer (display all

request that a top-level window

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

requests /use access control

requests) /flush the request

reset the screen saver

resides in a region

resource XrmQGetSearchResource:

resource database XGetDefault:

resource database

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

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

(resource ID) associated with

resource manager

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

return a list of children,

return a list of database levels

return a list of the available

return a new colormap ID

return an atom for a given

return data from a cut buffer

return data from cut buffer

return information about a

return symbols for keycodes

return the current keyboard

return the next event in queue/

return the next event in queue

return the number of pending/

return the owner of a selection

RGB values and closest/

RGB values and flags for a/

RGB values for an array of

RGB values from ASCII color name .

RGB values from color name

RGB values of a read/write

RGB values of a read/write/

RGB values of read/write/

.XPeeklfEvent

, XSetWindowBorder

, XSetWindowBorderPixmap

, XDisplayName

, XPending

, XSync

, XFlush

, Xlconify Window

, XReconfigureWMWindow

, XWithdrawWindow

, XEnableAccessControl

, XFlush

, XResetScreenSaver

, XRectlnRegion

, XrmQGetSearchResource

. XGetDefault

. XrmDestroyDatabase

, XrmPutLineResource

, XrmPutResource

, XrmParseCommand

. XrmPutFileDatabase

. XrmGetResource

. XGContextFromGC

, Xrmlnitialize

, XrmQPutStringResource

, XrmPutStringResource

, XrmQPutResource

. XrmPutResource

. XrmQPutStringResource

. XrmPutLineResource

, XrmPutStringResource

, XrmQGetResource

. XKillClient

. XAllowEvents

. XrmGetFileDatabase

, XListExtensions

, XQueryTree

, XrmQGetSearchList

, XListFonts

, XCopyColormapAndFree

, XInternAtom

, XFetchBuffer

, XFetchBytes

, XQueryFont

. XGetKeyboardMapping

. XGetlnputFocus

. XCheckTypedWindowEvent

. XCheckTypedEvent

. XPending

. XGetSelectionOwner

. XLookupColor

. XQueryColor

. XQueryColors

. XParseColor

. XLookupColor

.XStoreNamedColor

. XStoreColor

. XStoreColors

Xlib Reference Manual

XBell:

a list of children, parent, and

XRotateWindowProperties :

XRotateBuffers:

XSetFillRule: set the fill

fif two regions have the

to a window and/ XSaveContext:

reset the screen

set the parameters of the screen

/turn the screen

/get the current screen

add a window to the client s

a subwindow from the client s

a window from the client s

the depths available on a given

pointer to another point on the

XActivateScreenSaver: activate

XResetScreenSaver: reset the

set the parameters of the

XForceScreenSaver: turn the

XGetScreenSaver: get the current

. new graphics context for a given

get the current font

XSetFontPath: set the font

resource XrmQGetSearchResource:

sent to a window XSelectlnput:

use the value of a

return the owner of a

set the owner of a

connection with the/ XNoOp:

XSendEvent:

select the event types to be

/a resource specification with

range of legal keycodes for a

XGrabServer: grab the

to X supported by Xh b and the

pixmap formats for a given

to exercise connection with the

connect a client program to an X

errors to be processed by the

a client program from an X

XQueryTextExtents: query the

XQueryTextExtentsl6: query the

XUngrabServer: release the

/read keycode-keysym mapping from

Xlib/ XSetAfterFunction:

handler XSetErrorHandler:

a graphics context XSetDashes:

XPutPixel:

property XSetWMHints:

manager/ XSetWMProperties:

property XSetWMClientMachine:

XSetWMColormapWindows:

property XSetWMProtocols:

property XSetWMSizeHints:

property XSetWMIconName:

property. XSetWMName:

XSetWMNormalHints :

XBell

XQueryTree

, XRotateWindowProperties

ring the bell (Control G)

root XQueryTree: return

rotate properties in the/

rotate the cut buffers XRotateBuffers

rule in a graphics context XSetFillRule

same size, offset, and shape XEqualRegion

save a data value corresponding XSaveContext

saver XResetScreenSaver: XResetScreenSaver

saver XSetScreenSaver: XSetScreenSaver

saver on or off XForceScreenSaver

saver parameters XGetScreenSaver

save-set XAddToSaveSet: XAddToSaveSet

save-set /add or remove XChangeSaveSet

save-set /remove XRemoveFromSaveSet

screen XUstDepths: determine XListDepths

screen XWarpPointer: move the XWarpPointer

screen blanking XActivateScreenSaver

screen saver XResetScreenSaver

screen saver XSetScreenSaver: XSetScreenSaver

screen saver on or off XForceScreenSaver

screen saver parameters XGetScreenSaver

screen with the depth of the/ /a XCreateGC

search path XGetFontPath: XGetFontPath

search path XSetFontPath

search prepared list for a given

select the event types to be

selection XConvertSelection:

selection XGetSelectionOwner: ....

selection XSetSelectionOwner:

send a NoOp to exercise

send an event

sent to a window XSelectlnput: XSelectlnput

separate resource name and value XrmPutStringResource

server /obtain the XDisplayKeycodes

server XGrabServer

server /a list of all extensions XListExtensions

server /obtain the supported XListPixmapFormats

server XNoOp: send a NoOp XNoOp

server XOpenDisplay: XOpenDisplay

server /wait for all events and XSync

server and display /disconnect XCloseDisplay

server for string and font/ XQueryTextExtents

server for string and font/ XQueryTextExtents 16

server from grab XUngrabServer

server into Xlib XRefreshKeyboardMapping

set a function called after all XSetAfterFunction

set a nonfatal error event XSetErrorHandler

set a pattern of line dashes in XSetDashes

set a pixel value in an image XPutPixel

set a window manager hints XSetWMHints

set a window s standard window XSetWMProperties

set a window s WM_CLIENT_MACHINE XSetWMClientMachine

set a window s/ XSetWMColormapWindows

set a window s WM.PROTOCOLS XSetWMProtocols

set a window s WM_SEE_HINTS XSetWMSizeHints

set a window s XA_WM_ICON_NAME XSetWMIconName

set a window s XA_WM_NAME XSetWMName

set a window s/ XSetWMNormalHints

XrmQGetSearchResource

XSelectlnput

XConvertSelection

XGetSelectionOwner

XSetSelectionOwner

XNoOp

XSendEvent

Permuted Index

structure XSetRGBColormaps:

create a window and

context to the/ XSetRegion:

graphics context XSetClipMask:

modifiers/ XSetModifierMapping:

manager /set the minimum

properties XSetTextProperty:

a read/write/ XStoreColor:

read/write/ XStoreColors:

colorcell by/ XStoreNamedColor:

context XSetArcMode:

attribute/ XSetWindowBackground:

in a graphics/ XSetBackground:

operation in a/ XSetFunction:

graphics/ XSetClipOrigin:

window XSetWindowColormap:

graphics context XSetFont:

context XSetFillRule:

context XSetFillStyle:

context XSetTile:

XSetFontPath:

logical function,/ XSetState:

in a graphics/ XSetForeground:

XSetGraphicsExposures:

XSetlnputFocus:

in a/ XSetLine Attributes:

XSetStandardProperties :

a window s icon XSetlconName:

XSetSelectionOwner:

saver XSetScreenSaver:

context XSetPlaneMask:

XSetPointerMapping :

window in/ XSetNormalHints:

zoomed window XSetZoomHints:

XStringListToTextProperty:

context XSetStipple:

graphics/ XSetSubwindowMode:

graphics context XSetTSOrigin:

type/ XSetSizeHints:

XA_WM_ICON_SIZE/ XSetlconSizes:

a window XSelClassHint:

(command line/ XSetCommand:

property/ XSetTransientForHint:

XChangeWindow Attributes :

have the same size, offset, and

the fastest supported stipple

the fastest supported fill tile

a mapping of modifier keys

keycodes to be used as modifiers

map a window on top of its

change the stacking order of

XGetPixel: obtain a

a drawable/ XCopyPlane: copy a

cursor, tile, or stipple

XResize Window: change a window s

XMoveResize Window: change the

/change the window position,

geometry/ /generate position and

set an XStandardColormap

set attributes XCreate Window:

set clip_mask of the graphics

set clip_mask pixmap in a

set keycodes to be used as

set of properties for the window

set one of a window s text

set or change the RGB values of

set RGB values of a read/write

set the arc mode in a graphics ,

set the background pixel value ,

set the bitwise logical ,

set the clip origin in a ,

set the colormap attribute for a ,

set the current font in a ,

set the fill rule in a graphics ,

set the fill style in a graphics ,

set the fill tile in a graphics ,

set the font search path ,

set the foreground, background, ,

set the foreground pixel value

set the graphics_exposures/

set the keyboard focus window ,

set the line drawing components ,

set the minimum set of/

set the name to be displayed in

set the owner of a selection

set the parameters of the screen

set the plane mask in a graphics

set the pointer button mapping

set the size hints property of a

set the specified list of/

set the stipple in a graphics

set the subwindow mode in a

set the tile/stipple origin in a

set the value of any property of

set the value of the

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

set window attributes

shape /determine if two regions

shape XQueryBestStipple: obtain

shape XQueryBestTile: obtain

(Shift, Control, etc.) /obtain

(Shift, Control, etc.) /set

siblings XMapRaised:

siblings XRestackWindows:

single pixel value from an image

single plane of a drawable into

size /the "best" supported

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

size and position of a window

size, border width, or stacking/ ,

size from standard window ,

.XSetRGBColormaps

. XCreateWindow

, XSetRegion

. XSetClipMask

. XSetModifierMapping

. XSetStandardProperties

. XSetTextProperty

. XStoreColor

. XStoreColors

. XStoreNamedColor

. XSetArcMode

. XSetWindowBackground

. XSetBackground

. XSetFunction

. XSetClipOrigin

. XSetWindowColormap

. XSetFont

. XSetFillRule

. XSetFillStyle

. XSetTile

. XSetFontPath

.XSetState

. XSetForeground

. XSetGraphicsExposures

. XSetlnputFocus

. XSetLineAttributes

. XSetStandardProperties

. XSetlconName

. XSetSelectionOwner

. XSetScreenSaver

. XSetPlaneMask

. XSetPointerMapping

. XSetNormalHints

. XSetZoomHints

. XStringListToTextProperty

. XSetStipple

. XSetSubwindowMode

. XSetTSOrigin

. XSetSizeHints

. XSetlconSizes

. XSetClassHint

. XSetCommand

. XSetTransientForHint

. XChangeWindow Attributes

. XEqualRegion

. XQueryBestStipple

. XQueryBestTile

. XGetModifierMapping

. XSetModifierMapping

.XMapRaised

. XRestackWindows

.XGetPixel

.XCopyPlane

. XQueryBestSize

. XResizeWindow

. XMoveResize Window

. XConfigure Window

. XParseGeometry

Xlib Reference Manual

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

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

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

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

reduce or expand the size of a region XShrinkRegion: XShrinkRegion

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

get preferred icon sizes XGetlconSizes: XGetlconSizes

get the closest supported cursor sizes XQueryBestCurson XQueryBestCursor

region XClipBox: generate the smallest rectangle enclosing a XClipBox

using quarks /store a resource specification into a database XrmQPutResource

XrmPutResource: store a resource specification into a resource/ XrmPutResource

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

database /add a resource specification to a resource XrmPutLJneResource

resource name/ /add a resource specification with separate XrmPutStringResource

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

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

/ID) associated with the specified graphics context XGContextFromGC

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

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

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

/structure associated with the specified property XGetRGBColormaps

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

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

structures that match the specified template /information XGetVisuallnfo

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

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

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

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

lower a window in the stacking order XLowerWindow: XLowerWindow

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

down /circulate the stacking order of children up or XCirculateSubwindows

XRestack Windows: change the stacking order of siblings XRestack Windows

XGetStandardColormap: get the standard colormap property XGetStandardColormap

XSetStandardColormap: change the standard colormap property XSetStandardColormap

/create a cursor from the standard cursor font XCreateFontCursor

/generate position and size from standard window geometry string XParseGeometry

XSetWMProperties: set a window s standard window manager/ XSetWMProperties

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

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

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

XSetStipple: set the stipple in a graphics context XSetStipple

/obtain the fastest supported stipple shape XQueryBestStipple

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

XDestroyRegion: deallocate storage associated with a region XDestroyRegion

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

file XrmPutFileDatabase: store a resource database in a XrmPutFileDatabase

into a/ XrmQPutResource: store a resource specification XrmQPutResource

into a resource/ XrmPutResource: store a resource specification XrmPutResource

XStoreBuffer: store data in a cut buffer XStoreBuffer

XStoreBytes: store data in cut buffer XStoreBytes

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

convert a keysym symbol to a string XKeysymToString: XKeysymToString

from standard window geometry string /position and size XParseGeometry

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

create a database from a string XrmGetStringDatabase: XrmGetStringDatabase

convert a quark to a string XrmQuarkToString: XrmQuarkToString

/geometry given user geometry string and default geometry XGeometry

/query the server for string and font metrics XQueryTextExtents

Permuted Index 25

XTextExtents: get string and font metrics locally XTextExtents

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

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

/rebind a keysym to a string for client XRebindKeysym

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

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

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

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

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

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

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

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

/convert a keysym name string to a keysym XStringToKeysym

XrmStringToQuark: convert a string to a quark XrmStringToQuark

/convert a key string to a quark list XrmStringToQuarkList

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

draw two-byte text strings XDrawString 16: XDrawString 16

XDrawText: draw 8-bit polytext strings XDrawText

draw 16-bit polytext strings XDrawTextl6: XDrawTextl6

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

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

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

allocate an XClassHint structure XAllocClassHint: XAllocClassHint

allocate an XlconSize structure XAllocIconSize: XAllocIconSize

allocate an XSizeHints structure XAllocSizeHints: XAllocSizeHints

/allocate an XStandardColormap structure XAllocStandardColormap

allocate an XWMHints structure XAllocWMHints: XAllocWMHints

allocate memory for an Xlmage structure XCreatelmage: XCreatelmage

an entry from an XModifierKeymap structure /delete XDeleteModifiermapEntry

and free storage for the font structure Ainload a font XFreeFont

free a keyboard modifier mapping structure /destroy and XFreeModifiermap

new entry to an XModifierKeymap structure /add a XlnsertModifiermapEntry

load a font and fill information structure XLoadQueryFont: XLoadQueryFont

corresponding to a keycode in structure /get the keysym XLookupKeysym

a keyboard modifier mapping structure /create XNewModifiermap

set an XStandardColormap structure XSetRGBColormaps: XSetRGBColormaps

of strings to an XTextProperty structure /the specified list XStringListToTextProperty

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

/obtain the XStandardColormap structure associated with the/ XGetRGBColormaps

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

XSetFillStyle: set the fill style in a graphics context XSetFillStyle

XSublmage: create a subimage from part of an image XSublmage

XSubtractRegion: subtract one region from another XSubtractRegion

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

XSetSubwindowMode: set the subwindow mode in a graphics/ XSetSubwindowMode

and destroy a window and all subwindows. Ainmap XDestroy Window

XUnmapSubwindows: unmap all subwindows of a given window XUnmapSubwindows

XDestroySubwindows: destroy all subwindows of a window XDestroySubwindows

XMapSubwindows: map all subwindows of window XMapSubwindows

/change the keyboard preferences such as key click XChangeKeyboardControl

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

/get the closest supported cursor sizes XQueryBestCursor

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

/obtain the fastest supported fill tile shape XQueryBestTile

XlistPixmapFormats: obtain the supported pixmap formats for a/ XlistPixmapFormats

/obtain the fastest supported stipple shape XQueryBestStipple

/convert a keysym symbol to a string XKeysymToString

XGetKeyboardMapping: return symbols for keycodes XGetKeyboardMapping

26 Xlib Reference Manual

XSynchronize: enable or disable synchronization for debugging XSynchronize

another /change the coordinate system from one window to XTranslateCoordinates

an entry from an association table. XDeleteAssoc: delete XDeleteAssoc

allocated for an association table, /free the memory XDestroyAssocTable

obtain data from an association table XLookUpAssoc: XLookUpAssoc

an entry in an association table XMakeAssoc: create XMakeAssoc

create a new association table (X10) XCreateAssocTable: XCreateAssocTable

that match the specified template /information structures XGetVisuallnfo

/draw 8-bit image text characters XDrawImageString

/draw 16-bit image text characters XDrawImageString 16

/read one of a window s text properties XGetTextProperty

/set one of a window s text properties XSetTextProperty

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

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

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

/change the background tile attribute of a window XSetWindowBackgroundPixmap

XSelTile: set the fill tile in a graphics context XSetTile

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

the fastest supported fill tile shape /obtain XQueryBestTile

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

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

XMapRaised: map a window on top of its siblings XMapRaised

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

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

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

/request that a top-level window be reconfigured XReconfigureWMWindow

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

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

auto-repeat/ XAutoRepeatOff : turn off the keyboard XAutoRepeatOff

keys XAutoRepeatOn: turn on the keyboard auto-repeat XAutoRepeatOn

XForceScreenSaver: turn the screen saver on or off XForceScreenSaver

/create a cursor from two bitmaps XCreatePixmapCursor

XDrawLine: draw a line between two points XDrawLine

compute the intersection of two regions XInterseclRegion: XIntersectRegion

compute the union of two regions XUnionRegion: XUnionRegion

the union and intersection of two regions /difference between XXorRegion

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

XDrawStringl6: draw two-byte text strings XDrawStringl6

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

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

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

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

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

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

/read any property of type XA_SEE_fflNTS XGetSizeHints

/set the value of any property of type XA_SEE_HINTS XSetSizeHints

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

default if/ XUninstallColormap: uninstall a colormap; install XUninstallColormap

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

XUnionRegion: compute the union of two regions XUnionRegion

XUnloadFont: unload a font XUnloadFont

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

XUnmapWindow: unmap a window XUnmapWindow

window XUnmapSubwindows: unmap all subwindows of a given XUnmapSubwindows

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

XCreateSimple Window: create an unmapped InputOutput window XCreateSimple Window

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

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

Permuted Index 27

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

specification into a database using quarks /store a resource XrmQPutResource

name or translate hexadecimal value /values from ASCII color XParseColor

with separate resource name and value /a resource specification XrmPutStringResource

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

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

/set the background pixel value attribute of a window XSetWindowBackground

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

XGetPixel: obtain a single pixel value from an image XGetPixel

XGetDefault: extract an option value from the resource database XGetDefault

/set the background pixel value in a graphics context XSetBackground

/set the foreground pixel value in a graphics context XSetForeground

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

XPutPixel: set a pixel value in an image XPutPixel

XConvertSelection: use the value of a selection XConvertSelection

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

property XSetlconSizes: set the value of the XA_WM_ICON_SIZE XSetlconSizes

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

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

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

XLookupColor: get database RGB values and closest/ XLookupColor

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

XQueryColors: obtain RGB values for an array of/ XQueryColors

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

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

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

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

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

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

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

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

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

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

that/ XGetVisuallnfo: find the visual information structures XGetVisuallnfo

XMatchVisuallnfo: obtain the visual information that matches/ XMatchVisuallnfo

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

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

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

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

predicate procedure XlfEvent: wait for event matched in XlfEvent

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

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

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

/change the border width of a window XSetWindowBorderWidth

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

a property associated with a window XChangeProperty: change XChangeProperty

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

clear a rectangular area in a window XClearArea: XClearArea

XClearWindow: clear an entire window XClearWindow

create an unmapped InputOutput window XCreateSimple Window: XCreateSimpleWindow

assign a cursor to a window XDefineCursor: XDefineCursor

destroy all subwindows of a window XDestroySubwindows: XDestroySubwindows

the XA_WM_CLASS property of a window XGetClassHint: get XGetClassHint

the current keyboard focus window XGetlnputFocus: return , XGetlnputFocus

property of a window /the XA_WM_TRANSIENT_FOR XGetTransientForHint

obtain the current attributes of window XGetWindow Attributes: XGetWindow Attributes

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

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

28 Xlib Reference Manual

get the property list for a window XListProperties: XListProperties

map all subwindows of window XMapSub windows: XMapSubwindows

XMapWindow: map a window XMap Window

the size and position of a window /change XMoveResize Window

XMove Window: move a window XMoveWindow

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

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

the XA_WM_CLASS property of a window XSetClassHint: set XSetClassHint

set the keyboard focus window XSetlnputFocus: XSetlnputFocus

property for a window /the XA_WM_TRANSIENT_FOR XSetTransientForHint

pixel value attribute of a window /set the background XSetWindowBackground

background tile attribute of a window /change the XSetWindowBackgroundPixmap

change the border width of a window XSetWindowBorderWidth: XSetWindowBorderWidth

set the colormap attribute for a window XSetWindowColormap: XSetWindowColormap

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

disassociate a cursor from a window XUndefineCursor: XUndefineCursor

unmap all subwindows of a given window XUnmapSubwindows: XUnmapSubwindows

XUnmapWindow: unmap a window XUnmapWindow

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

/unmap and destroy a window and all subwindows XDestroy Window

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

/insert a window between another window and its parent XReparentWindow

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

XCreate Window: create a window and set attributes XCreate Window

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

XChangeWindow Attributes: set window attributes XChangeWindow Attributes

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

/request that a top-level window be reconfigured XReconfigureWMWindow

/request that a top-level window be withdrawn XWithdrawWindow

and/ XReparentWindow: insert a window between another window XReparentWindow

XSetWindowBorder: change a window border pixel value/ XSetWindowBorder

XSetWindowBorderPixmap: change a window border tile attribute and/ XSetWindowBorderPixmap

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

XRemoveFromSaveSet: remove a window from the client s/ XRemoveFromSaveSet

geometry/ XGeometry: calculate window geometry given user XGeometry

position and size from standard window geometry string /generate XParseGeometry

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

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

XLowerWindow: lower a window in the stacking order XLowerWindow

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

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

XGetWMHints: read the window manager hints property XGetWMHints

XSetWMHints: set a window manager hints property XSetWMHints

/set a window s standard window manager properties XSetWMProperties

XMapRaised: map a window on top of its siblings XMapRaised

XPutlmage: draw an image on a window or pixmap XPutlmage

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

XDeleteProperty: delete a window property XDeleteProperty

the coordinate system from one window to another /change XTranslateCoordinates

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

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

XWMGeometry: obtain a window s geometry information XWMGeometry

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

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

XResize Window: change a window s size XResizeWindow

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

XGetTextProperty: read one of a window s text properties XGetTextProperty

XSetTextProperty: set one of a window s text properties XSetTextProperty

Permuted Index 29

XSetWMCIientMachine: set a

XSetWMColoimap Windows: set a

XSetWMProtocols: set a

XSetWMSizeHints: set a

property XGetWMIconName: read a

property XSetWMIconName: set a

XGetWMName: read a

XSetWMName:seta

XGetWMNormalHints: read a

XSetWMNormalHints: set a

XGetWMSizeHints: read a

that a top-level window be

/set a window s

XSetWMProtocols: set a window s

XSetWMSizeHints: set a window s

XWriteBitmapFile:

connect a client program to an

a client program from an

/a list of all extensions to

create a new association table

curve between vertex list (from

or curve from vertex list (from

/create a bitmap from

read any property of type

value of any property of type

XGetClassHint: get the

XSetClassHint: set the

arguments) XSetCommand: set the

XGetWMIconName: read a window s

XSetWMIconName: set a window s

/set the value of the

XFetchName: get a window s name

XGetWMName: read a window s

XSetWMName: set a window s

/read a window s

/set a window s

XGetWMSizeHints: read a window s

a/ XSetTransientForHint: set the

a/ XGetTransientForHint: get the

XAllocClassHint: allocate an

free the memory allocated by

XAllocIconSize: allocate an

allocate memory for an

components of a given GC from

free the memory allocated by

/free the memory allocated by

/delete an entry from an

/add a new entry to an

XAllocSizeHints: allocate an

/allocate an

XSetRGBColormaps: set an

XGetRGBColormaps: obtain the

specified list of strings to an

list of strings from a specified

XAllocWMHints: allocate an

of a window in normal state (not

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

window s XA_WMJCON_NAME XGetWMIconName

window s XA_WM_ICON_NAME XSetWMIconName

window s XA_WM_NAME property XGetWMName

window s XA_WM_NAME property XSetWMName

window s XA_WM_NORMAL_HINTS/ XGetWMNormalHints
window s XA_WM_NORMAL_HINTS/ XSetWMNormalHints

window s XA_WM_SEE_fflNTS/ XGetWMSizeHints

withdrawn /request XWithdrawWindow

WM_CLIENT_MACHINE property XSetWMCIientMachine

WM_COLORMAP_WINDOWS property XSetWMColormapWindows

WM_PROTOCOLS property XSetWMProtocols

WM_SEE_fflNTS property XSetWMSizeHints

write a bitmap to a file XWriteBitmapFile

X server XOpenDisplay: XOpenDisplay

X server and display /disconnect XCloseDisplay

X supported by Xlib and the/ XListExtensions

(X10) XCreateAssocTable: XCreateAssocTable

X10) XDraw: draw a polyline or XDraw

X10) /draw a filled polygon XDrawFilled

XI 1 bitmap format data XCreateBitmapFromData

XA_SEE_fflNTS XGetSizeHints: XGetSizeHints

XA_SEE_HINTS /set the XSetSizeHints

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

XA_WM_ICON_NAME property XGetWMIconName

XA_WM_ICON_NAME property XSetWMIconName

XA_WM_ICON_SIZE property XSetlconSizes

(XA_WM_NAME property) XFetchName

XA_WM_NAME property XGetWMName

XA_WM_NAME property XSetWMName

XA_WM_NORMAL_fflNTS property .. XGetWMNormalHints
XA_WM_NORMAL_HINTS property .. XSetWMNormalHints

XA_WM_SEE_HINTS property XGetWMSizeHints

XA_WM_TRANSIENT_FOR property for XSetTransientForHint
XA_WM_TRANSIENT_FOR property of XGetTransientForHint

XClassHint structure

XGetFontPath XFreeFontPath: ...

XlconSize structure

Xlmage structure XCreatelmage:

Xlib s GC cache /obtain

XListFonts. XFreeFontNames: ....

XListFontsWithlnfo

XModifierKeymap structure

XSizeHints structure

XStandardColormap structure

XStandardColormap structure/

XTextProperty structure /set the

XTextProperty structure /a

XWMHints structure

zoomed or iconified) /property

XAllocClassHint

XFreeFontPath

XAllocIconSize

XCreatelmage

XGetGCValues

XFreeFontNames

XFreeFontlnfo

XDeleteModifiermapEntry

XlnsertModifiermapEntry

XAllocSizeHints

XAllocStandardColormap

XSetRGBColormaps

XGetRGBColormaps

XStringListToTextProperty

XTextPropertyToStringList

XAllocWMHints

XGetNormalHints

XSetNormalHints

Xlib Reference Manual

the size hints property of a zoomed window /read XGetZoomHints

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

Permuted Index 31

-xiib- Function Group / Introduction

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

Name

XFunctionName brief description of the function.

Synopsis

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

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

type2 *arg2; /* RETURN */

type3 *arg3; /* SEND and RETURN */

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

Arguments

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

argl Specifies information for XFunctionName. The description of arguments that

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

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

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

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

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

Availability

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

Description

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

Structures

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

Xlib Reference Manual 33

Introduction (continued) Xlib - Function Group

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

Errors

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

Related Commands

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

34 Xlib Reference Manual

Xlib - Screen Saver-

J XActivateScreenSaver

Name

XActivateScreenSaver activate screen blanking.
Synopsis

XActivateScreenSaver (display)
Display *di splay;

Arguments

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

Description

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

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

Related Commands

XForceScreenSaver, XGetScreenSaver, XResetScreenSaver, XSetScreen
Saver.

Xlib Reference Manual 35

XAddHOSt Xnb-Hos.Accsss-

Name

XAddHost add a host to the access control list.

Synopsis

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

Arguments

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

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

Description

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

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

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

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

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

Structures

typedef struct {

int family; /* for example Familylnternet */

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

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

} XHostAddress;

/* The following constants for family member */

#define Familylnternet

ttdefine FamilyDECnet 1

#define FamilyChaos 2

Errors

BadAccess
BadValue

36 XHb Reference Manual

Xlib - Host Access (continued) XAddHost

Related Commands

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

Xlib Reference Manual

XAddHOStS X,, b -Hos, Access-

Name

XAddHosts add multiple hosts to the access control list.

Synopsis

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

Arguments

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

hosts Specifies each host that is to be added.

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

Description

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

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

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

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

Structures

typedef struct {

int family; /* for example Family Internet */

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

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

} XHostAddress;

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

38 Xlib Reference Manual

Xlib - Host Access (continued) XAddHostS

Errors

BadAccess
BadValue

Related Commands

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

Xlib Reference Manual 39

XAddPixel \ Xlib _ lmages _

Name

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

Synopsis

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

Arguments

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

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

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

Description

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

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

typedef struct Xlmage {

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

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

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

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

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

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

int bitmap_bit_order; /* LSBFirst, MSBFirst */

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

int depth; /* depth of image */

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

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

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

unsigned long green mask;

unsigned long blue_mask;

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

struct funcs { /* image manipulation routines */

struct _XImage * (*create_image) ();

int (*destroy_image) ();

unsigned long (*get_pixel) ( ) ;

int (*put_pixel) () ;

struct _XImage * (*sub_image) ();

int (*add_pixel) ();

} f;

} Xlmage;

40 Xlib Reference Manual

Xlib- Images (continued) XAddPixel

Related Commands

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

Xlib Reference Manual 41

XAddToSaveSet "\

XI ib- Save Set

Name

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

Synopsis

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

Arguments

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

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

Description

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

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

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

Errors

BadMat ch w not created by some other client.

BadWindow

Related Commands

XChangeSaveSet, XRemoveFromSaveSet.

42 Xlib Reference Manual

-XHb- W,ndow Manager Him, / XAIIOCCIaSSHint

Name

XAllocClassHint allocate an XClassHint structure.

Synopsis

XClassHint *XAllocClassHint ( )

Availability

Release 4 and later.

Description

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

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

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

typedef struct {

char *res_name;

char *res_class;
} XClassHint;

Related Commands

XGetClassHint, XSetClassHint, XSetWMProperties.

XHb Reference Manual

XANocColor "\ Yll

v Xlib - Color Cells-
Name

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

Synopsis

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

Arguments

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

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

col or eel l_def

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

Description

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

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

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

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

Structures

typedef struct {

unsigned long pixel;

unsigned short red, green, blue;

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

char pad;
} XColor;

Errors

BadColormap

44 Xlib Reference Manual

Xlib - Color Cells (continued) XAIIOCColor

Related Commands

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

Xlib Reference Manual 45

XAIIocColorCells

Xlib- Color Cells-

Name

XAIIocColorCells allocate read/write (nonshared) colorcells.

Synopsis

Status XAIIocColorCells (display, cmap,

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

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

contig, plane_masks,

/* RETURN

/* RETURN pixel values */

Arguments

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

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

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

False if the planes need not be contiguous.

plane_mask Returns an array of plane masks.

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

be nonnegative.

pixels Returns an array of pixel values.

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

positive.

Description

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

Status is zero on failure, and nonzero on success.

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

Xlib Reference Manual

Xlib - Color Cells (continued) XAIIOCColorCellS

Errors

BadColormap

BadValue npl an es is negative.

n colors is not positive.

Related Commands

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

Xlib Reference Manual

XAIIocColorPlanes X v,,

v XHb - Color Cells-
Name

XAIIocColorPlanes allocate read/write (nonshareable) color planes.

Synopsis

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

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

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

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

Arguments

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

cmap Specifies the ID of the colormap to be used.

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

pixels Returns an array of pixel values.

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

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

ngreens tive.

nblues

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

gmask

bmask

Description

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

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

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

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

48 Xlib Reference Manual

Xlib - Color Cells (continued) XAHocColorPlaneS

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

Status is zero on failure, and nonzero on success.

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

Errors

BadColormap

BadValue n colors is not positive.

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

Related Commands

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

Xlib Reference Manual 49

XAIIoclconSize V VI1I

v Xlib - Window Manager Hints-
Name

XAllocIconSize allocate anxiconSize structure.

Synopsis

XlconSize *XAllocIconSize ( )

Availability

Release 4 and later.

Description

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

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

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

typedef struct {

int min_width, min_height;

int max_width, max_height;

int width_inc, heigh t_inc;
} XlconSize;

Related Commands

XGetlconSizes, XSetlconSizes.

50 Xlib Reference Manual

Xlib -Color Cells-

J XAIIocNamedColor

Name

XAIIocNamedColor allocate a read-only colorcell from color name.

Synopsis

Status XAIIocNamedColor (display, cmap, colorname ,

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

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

Arguments

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

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

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

colorcell_def

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

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

Description

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

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

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

Xlib Reference Manual 51

X AllocNamedColor (continued) Xlib - Color Cells

Errors

BadColormap
BadName

Structures

typedef struct {

unsigned long pixel;

unsigned short red, green, blue;

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

char pad;
} XColor;

Related Commands

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

52 Xlib Reference Manual

-XMb-WmdowManager Him, XAIIOCSizeHintS

Name

XAllocSizeHints allocate an XSizeHints structure.

Synopsis

XSizeHints *XAllocSizeHints ( )

Availability

Release 4 and later.

Description

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

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

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

typedef struct {

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

int x, y; /* Obsolete */

int width, height; /* Obsolete */

int min_width, min_height;

int max_width, max_height;

int width_inc, height_inc;

struct {

int x; /* numerator */

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

Related Commands

XGetWMNormalHints, XSetWMNormalHints, XSetWMProperties.

Xlib Reference Manual 53

XAIIocStandardColormap V Vl .

v Xhb - Window Manager Hints-
Name

XAIIocStandardColormap allocate an XStandardColormap structure.

Synopsis

XStandardColormap *XAllocStandardColormap ( )

Availability

Release 4 and later.

Description

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

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

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

/* value for killid field */

#define ReleaseByFreeingColormap ( (XID) 1L)

typedef struct {

Colormap colormap;

unsigned long red_max;

unsigned long red_mult;

unsigned long green_max;

unsigned long green_mult ;

unsigned long blue__max;

unsigned long blue_mult;

unsigned long base_pixel;

VisuallD visualid;

XID killid;
} XStandardColormap;

Related Commands

XGetRGBColormaps, XSetRGBColormaps.

54 Xlib Reference Manual

-Xlib- Window Manager Hints XAIIOCWMHmtS

Name

XAllocWMHints allocate an XWMHints structure.

Synopsis

XWMHints *XAllocWMHints ( )

Availability

Release 4 and later.

Description

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

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

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

typedef struct {

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

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

to get keyboard input? */

int initial_state; /* see below */

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

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

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

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

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

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

Related Commands

XGetWMHints, XSetWMHints, XSetWMProperties.

Xlib Reference Manual

XAIIowEvents

Xlib- Input Handling-

Name

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

Synopsis

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

Arguments

display
event mode

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

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

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

expressed in milliseconds, or the constant Cur rent Time.

Description

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

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

AsyncPointer If XAIIowEvents is called with AsyncPointer while the

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

AsyncKeyboard If XAIIowEvents is called with AsyncKeyboard while the key

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

SyncPointer If XAIIowEvents is called with SyncPointer while the pointer

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

Xlib Reference Manual

Xlib - Input Handling

(continued)

XAIIowEvents

SyncKeyboard

ReplayPointer

ReplayKeyboard

SyncBoth

AsyncBoth

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

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

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

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

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

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

Xlib Reference Manual

XAHowEventS (continued) Xlib- Input Handling

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

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

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

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

Errors

BadValue Invalid mode constant.

Related Commands

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

58 Xlib Reference Manual

Xllb - User Preferences-

J XAutoRepeatOff

Name

XAutoRepeatOff turn off the keyboard auto-repeat keys.

Synopsis

XAutoRepeatOff (display)
Display *display;

Arguments

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

Description

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

Related Commands

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

Xlib Reference Manual

XAutoRepeatOn \.

v Xlib - User Preferences-
Name

XAutoRepeatOn turn on the keyboard auto-repeat keys.

Synopsis

XAutoRepeatOn (display)
Display *display;

Arguments

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

Description

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

Related Commands

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

60 Xlib Reference Manual

Xlib - User Preferences-

f XBell

Name

XBell ring the bell (Control G).

Synopsis

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

Arguments

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

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

Description

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

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

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

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

Errors

BadValue percent &lt; -100 or percent &gt;100.

Related Commands

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

Xlib Reference Manual 61

XChangeActivePointerGrab v^

Xlib- Pointer-

Name

XChangeActivePointerGrab change the parameters of an active pointer grab.

Synopsis

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

Arguments

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

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

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

cursor.

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

expressed in milliseconds, or the constant CurrentTime.

Description

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

event_mask is always augmented to include ButtonPress and ButtonRelease.

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

Errors

BadCursor

BadValue The event_mask argument is invalid.

Related Commands

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

62 Xlib Reference Manual

Xlib - Graphics Context-

f XChangeGC

Name

XChangeGC change the components of a given graphics context.

Synopsis

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

unsigned long valuemask;
XGCValues * values;

Arguments

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

gc Specifies the graphics context.

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

val ues Specifies a pointer to the XGCValues structure.

Description

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

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

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

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

Structures

typedef struct {

int function; /* logical operation */

unsigned long plane_mask; /* plane mask */

unsigned long foreground; /* foreground pixel */

unsigned long background; /* background pixel */

int line_width; /* line width */

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

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

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

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

int fill_rule; /* EvenOddRule, WindingRule */

int arc_mode; /* ArcChord, ArcPieSlice */

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

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

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

Xlib Reference Manual 63

XChangeGC

(continued)

Xlib- Graphics Context

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

/* default text font for text operations */

/* ClipByChildren, Includelnferiors */

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

/* origin for clipping */

/* bitmap clipping; other calls for rects */

/* patterned/dashed line information */

#define

GCFunction (1L0)

#define

GCPlaneMask (1L1)

#define

GCForeground (1L2)

#define

GCBackground (1L3)

#define

GCLineWidth (1L4)

#def ine

GCLineStyle (1L5)

#define

GCCapStyle (1L6)

#def ine

GCJoinStyle (1L7)

#define

GCFillStyle (1L8)

#define

GCFillRule (1L9)

#define

GCTile (1L10)

#define

GCStipple (1L11)

#define

GCTileStipXOrigin (1L12)

#def ine

GCTileStipYOrigin (1L13)

#define

GCFont (1L14)

#def ine

GCSubwindowMode (1L15)

#define

GCGraphicsExposures (1L16)

#def ine

GCClipXOrigin (1L17)

#define

GCClipYOrigin (1L18)

#define

GCClipMask (1L19)

#def ine

GCDashOffset (1L20)

#define

GCDashList (1L21)

#def ine

GCArcMode (1L22)

Errors

BadAlloc

BadFont

BadGC

BadMatch

BadPixmap

BadValue

Related Commands

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

Xlib Reference Manual

Xlib - User Preferences-

J XChangeKeyboardControl

Name

XChangeKeyboardControl change the keyboard preferences such as key click.

Synopsis

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

Arguments

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

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

values Specifies the settings for the keyboard preferences.

Description

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

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

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

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

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

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

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

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

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

Xlib Reference Manual

XChangeKey boardControl (continued) Xlib - User Preferences

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

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

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

Structures

/* masks for ChangeKeyboardControl */

#define KBKeyClickPercent (1L0)

#define KBBellPercent (1L1)

#define KBBellPitch (1L2)

#define KBBellDuration (1L3)

#define KBLed (1L4)

#define KBLedMode (1L5)

tdefine KBKey (1L6)

tdefine KBAutoRepeatMode (1L7)

/* structure for ChangeKeyboardControl */

typedef struct {

int key_click_percent;

int bell_percent;

int bell_pitch;

int bell_duration;

int led;

int led_mode; /* LedModeOn or LedModeOff */

int key;

int auto_repeat_mode; /* AutoRepeatModeOf f , AutoRepeatModeOn,

AutoRepeatModeDefault */
} XKeyboardControl;

Errors

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

BadValue values. key_click_percent &lt; -1.

values. be ll_percent &lt; -1.
values. bell_j3itch &lt; -I.
values.bell_duration &lt; -1.

Related Commands

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

Xlib Reference Manual

XI ib- Keyboard -

J XChangeKeyboardMapping

Name

XChangeKeyboardMapping change the keyboard mapping.
Synopsis

XChangeKeyboardMapping (display, first_code, keysyms_per_code,

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

Arguments

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

fi rs t_keycode

Specifies the first keycode that is to be changed.

key syms_per_key code

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

keysyms Specifies a pointer to the list of keysyms.

num_key codes

Specifies the number of keycodes that are to be changed.

Description

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

max_keycode &gt;= first_keycode + (num_keycodes / key syms_per_key code) - 1

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

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

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

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

Xlib Reference Manual 67

XChangeKeyboardMapping (continued) Xlib - Keyboard

Errors

BadAlloc

BadValue first . keycode less than display-&gt;min_keycode.

display-&gt;max_keycode exceeded (see above).

Related Commands

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

68 Xlib Reference Manual

Xlib -Pointers-

J XChangePointerControl

Name

XChangePointerControl change the pointer preferences.

Synopsis

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

Arguments

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

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

do_ thresh old

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

accel_numerator

Specifies the numerator for the acceleration multiplier.

accel_denominator

Specifies the denominator for the acceleration multiplier.

threshold Specifies the acceleration threshold.

Description

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

The fraction may be rounded arbitrarily by the server.
Errors

BadValue accel_de/iomiriator isO.

Negative value for do_accel or do_threshold.

Xlib Reference Manual

XChangePolnterControl (continued) Xlib - Pointers

Related Commands

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

70 Xlib Reference Manual

Xlib -Properties-

J XChangeProperty

Name

XChangeProperty change a property associated with a window.

Synopsis

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

data, nelements)
Display * display;
Window w;

Atom property, type;
int format;
int mode ;

unsigned char *data;
int nelements;

Arguments

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

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

property Specifies the property atom.

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

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

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

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

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

Replace, PropModePrepend, PropModeAppend, or no value.

data Specifies the property data.

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

Description

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

XChangeProperty does the following according to the mode argument:

PropModeReplace

Discards the previous property value and stores the new data.

PropModePrepend

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

Xlib Reference Manual 71

XChangeProperty (continued) Xlib - Properties

PropMode Append

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

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

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

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

Errors

BadAlloc

BadAtom

BadMatch

BadValue

BadWindow

Related Commands

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

72 Xlib Reference Manual

Xlib - Window Save Set-

J XChangeSaveSet

Name

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

Synopsis

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

Arguments

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

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

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

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

Description

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

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

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

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

Errors

BadMat ch w not created by some other client.

BadValue
BadWindow

Related Commands

XAddToSaveSet,XRemoveFromSaveSet.

Xlib Reference Manual 73

XChangeWindowAttributes

Xlib - Window Attributes-

Name

XChangeWindowAttributes set window attributes.

Synopsis

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

unsigned long valuemask;
XSetWindowAttributes * attributes;

Arguments

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

w Specifies the window ID.

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

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

Description

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

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

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

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

74 Xlib Reference Manual

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

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

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

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

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

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

Structures

* Data structure for setting window attributes.

*/
typedef struct {

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

unsigned long background_pixel; /* background pixel */

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

unsigned long border_pixel; /* border pixel value */

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

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

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

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

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

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

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

long do not propagate_mask; /* set of events that should not propagate */

Bool override_redirect; /* override redirected config request */

Colormap colormap; /* colormap to be associated with window */

Cursor cursor; /* cursor to be displayed (or None) */
} XSetWindowAttributes;

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

#define CWBackPixmap (1L0)

#define CWBackPixel (1L1)

#define CWBorderPixmap (1L2)

#define CWBorderPixel (1L3)

#define CWBitGravity (1L4)

#define CWWinGravity (1L5)

#define CWBackingStore (1L6)

#define CWBackingPlanes (1L7)

#define CWBackingPixel (1L8)

#define CWOverrideRedirect (1L9)

#define CWSaveUnder (1L10)

#define CWEventMask (1L11)

#define CWDontPropagate (1L12)

fdefine CWColormap (1L13)

#define CWCursor (1L14)

Xlib Reference Manual 7S

XChangeWindOW Attributes (continued) Xlib - Window Attributes

Errors

BadAccess

BadColormap

BadCursor

BadMatch

BadPixmap

BadValue

BadWindow

Related Commands

XGet Geometry, XGetWindowAttributes, XSetWindowBackground, XSet-
WindowBackgroundPixmap, XSetWindowBorder, XSetWindowBorderPixmap.

76 Xlib Reference Manual

-X,ib - input Handling / XCheCklfEvent

Name

XChecklfEvent check the event queue for a matching event.

Synopsis

Bool XChecklfEvent (display, event, predicate, arg)
Display *display;

XEvent * event; /* RETURN */

Bool (*predicate) () ;
char *arg;

Arguments

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

event Returns the matched event.

predicate Specifies the procedure that is called to determine if the next event matches
your criteria.

arg Specifies the user- specified argument that will be passed to the predicate pro

cedure.

Description

XChecklfEvent returns the next event in the queue that is matched by the specified predi
cate procedure. If found, that event is removed from the queue, and True is returned. If no
match is found, XChecklfEvent returns False and flushes the request buffer. No other
events are removed from the queue. Later events in the queue are not searched.

The predicate procedure is called with the arguments display, event, and arg.
For more information, see Volume One, Chapter 8, Events.

Related Commands

QLength, XAllowEvents, XCheckMaskEvent, XCheckTypedEvent, XCheck-
TypedWindowEvent, XCheckWindowEvent, XEventsQueued, XGetlnputFocus,
XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeek-
If Event, XPending, XPutBackEvent,XSelectInput,XSendEvent,XSet Input-
Focus, XSynchronize, XWindowEvent.

Xlib Reference Manual 77

XCheckMaskEvent \ xnb _ lnputH and,,n g -

Name

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

Synopsis

Bool XCheckMaskEvent ( display, event_mask, event)
Display * display;
long event_mask;
XEvent * event; /* RETURN */

Arguments

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

even t_mask Specifies the event types to be returned. See list under XSelect Input.
event Returns a copy of the matched event s XEvent structure.

Description

XCheckMaskEvent removes the next event in the queue that matches the passed mask. The
event is copied into an XEvent supplied by the caller and XCheckMaskEvent returns
True. Other events earlier in the queue are not discarded. If no such event has been queued,
XCheckMaskEvent flushes the request buffer and immediately returns False, without wait
ing.

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

QLength, XAllowEvents, XChecklf Event, XCheckTypedEvent, XCheckTyped-
WindowEvent, XCheckWindowEvent, XEvent sQueued, XGetlnputFocus, XGet-
MotionEvents, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeek-
If Event, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSetlnput-
Focus, XSynchronize, XWindowEvent.

78 Xlib Reference Manual

Xlib -Input Handling-

J XCheckTypedEvent

Name

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

Synopsis

Bool XCheckTypedEvent (display, event_type, report)
Display *display;
int event_type ;
XEvent * report; /* RETURN */

Arguments

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

event_type Specifies the event type to be compared.
report Returns a copy of the matched event structure.

Description

XCheckTypedEvent searches first the event queue, then the events available on the server
connection, for the specified even t_ type. If there is a match, it returns the associated event
structure. Events searched but not matched are not discarded. XCheckTypedEvent returns
True if the event is found. If the event is not found, XCheckTypedEvent flushes the
request buffer and returns False.

This command is similar to XCheckMaskEvent, but it searches through the queue instead of
inspecting only the last item on the queue. It also matches only a single event type instead of
multiple event types as specified by a mask.

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

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped-
WindowEvent, XCheckWindowEvent, XEventsQueued, XGetlnputFocus, XGet-
MotionEvents, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeek-
If Event, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSetlnput-
Focus, XSynchronize, XWindowEvent.

Xlib Reference Manual 79

XCheckTypedWindowEvent \

x ,ib-

Name

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

Synopsis

Bool XCheckTypedWindowEvent ( display, w, event _ty pe , report)
Display * display;
Window w;
int event_type;
XEvent * report; /* RETURN */

Arguments

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

w Specifies the window ID.

even t_ type Specifies the event type to be compared.

report Returns the matched event s associated structure into this client-supplied

structure.

Description

XCheckTypedWindowEvent searches first the event queue, then any events available on
the server connection, for an event that matches the specified window and the specified event
type. Events searched but not matched are not discarded.

XCheckTypedWindowEvent returns True if the event is found; it flushes the request buffer
and returns False if the event is not found.

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

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped-
Event, XCheckWindowEvent, XEventsQueued, XGetlnputFocus, XGetMotion-
Events, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeeklf Event,
XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSetlnputFocus,
XSynchronize, XWindowEvent.

80 Xlib Reference Manual

-Xllb- Input Handling / XCheCkWIndOWEvent

Name

XCheckWindowEvent remove the next event matching both passed window and passed
mask; don t wait.

Synopsis

Bool XCheckWindowEvent (display, w, event_mask r event)
Display * display;
Window w;
long event_mask;
XEvent * event; /* RETURN */

Arguments

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

w Specifies the window ID. The event must match both the passed window and

the passed event mask.

even t_mask Specifies the event mask. See XSelect Input for a list of mask elements.
event Returns the XEvent structure.

Description

XCheckWindowEvent removes the next event in the queue that matches both the passed
window and the passed mask. If such an event exists, it is copied into an XEvent supplied by
the caller. Other events earlier in the queue are not discarded.

If a matching event is found, XCheckWindowEvent returns True. If no such event has been
queued, it flushes the request buffer and returns False, without waiting.

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

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped-
Event, XCheckTypedWindowEvent, XEvent sQueued, XGetlnputFocus, XGet-
MotionEvents, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeek-
If Event, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSetlnput-
Focus, XSynchronize, XWindowEvent.

Xlib Reference Manual

XCirculateSubwindows

Xlib - Window Manipulation-
Name

XCirculateSubwindows circulate the stacking order of children up or down.

Synopsis

XCirculateSubwindows ( display, w, direction)
Display *display;
Window w;
int direction;

Arguments

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

w Specifies the window ID of the parent of the subwindows to be circulated.

direction Specifies the direction (up or down) that you want to circulate the children.
Pass either RaiseLowest or LowerHighest.

Description

XCirculateSubwindows circulates the children of the specified window in the specified
direction, either RaiseLowest or LowerHighest. If some other client has selected
SubstructureRedirectMask on the specified window, then a CirculateRequest
event is generated, and no further processing is performed. If you specify RaiseLowest, this
function raises the lowest mapped child (if any) that is occluded by another child to the top of
the stack. If you specify LowerHighest, this function lowers the highest mapped child (if
any) that occludes another child to the bottom of the stack. Exposure processing is performed
on formerly obscured windows.

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

Errors

BadValue
BadWindow

Related Commands

XCirculateSubwindowsDown, XCirculateSubwindowsUp, XConf igureWindow,
XLowerWindow, XMoveResizeWindow, XMoveWindow, XQueryTree, XRaise-
Window, XReparentWindow, XResizeWindow, XRestackWindows.

82 Xlib Reference Manual

-x..b-w,ndowMan. pu .at,on XCirculateSubwindowsDown

Name

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

Synopsis

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

Arguments

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

w Specifies the window ID of the parent of the windows to be circulated.

Description

XCirculateSubwindowsDown lowers the highest mapped child of the specified window
that partially or completely obscures another child. The lowered child goes to the bottom of the
stack. Completely unobscured children are not affected.

This function generates exposure events on any window formerly obscured. Repeated execu
tions lead to round-robin lowering. This is equivalent to XCirculateSubwindows (dis
play, w, LowerHighest).

If some other client has selected SubstructureRedirectMask on the window, then a
CirculateRequest event is generated, and no further processing is performed. This allows
the window manager to intercept this request when w is the root window. Usually, only the
window manager will call this on the root window.

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

Errors

BadWindow

Related Commands

XCirculateSubwindows, XCirculateSubwindowsUp, XConf igureWindow,
XLowerWindow, XMoveResizeWindow, XMoveWindow, XQueryTree, XRaise-
Window, XReparentWindow, XResizeWindow, XRestackWindows.

Xlib Reference Manual

XCirculateSubwindowsUp , vn

v Xlib - Window Manipulation

Name

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

Synopsis

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

Arguments

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

w Specifies the window ID of the parent of the windows to be circulated.

Description

XCirculateSubwindowsUp raises the lowest mapped child of the specified window that is
partially or completely obscured by another child. The raised child goes to the top of the stack.
Completely unobscured children are not affected. This generates exposure events on the raised
child (and its descendents, if any). Repeated executions lead to round robin-raising. This is
equivalent to XCirculateSubwindows (display, w, RaiseLowest).

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

Errors

BadWindow

Related Commands

XCirculateSubwindows, XCirculateSubwindowsDown, XConf igureWindow,
XLowerWindow, XMoveResizeWindow, XMoveWindow, XQueryTree, XRaise-
Window, XReparentWindow, XResizeWindow, XRestackWindows.

84 Xlib Reference Manual

Xllb - Drawing Primitives

Name

XClearArea clear a rectangular area in a window.
Synopsis

XClearArea (display, w, x, y, width, height, exposures)
Display *display;
Window w;
int x f y;

unsigned int width, height;
Bool exposures;

Arguments

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

w Specifies the ID of an input Output window.

x Specify the x and y coordinates of the upper-left corner of the rectangle to be

y cleared, relative to the origin of the window.

wi dth Specify the dimensions in pixels of the rectangle to be cleared.

height

exposures Specifies whether exposure events are generated. Must be either True or
False.

Description

XClearArea clears a rectangular area in a window.

If width is zero, the window is cleared from x to the right edge of the window. If height is
zero, the window is cleared from y to the bottom of the window. See figure above..

If the window has a defined background tile or it is ParentRelative, the rectangle is tiled
with a plane_mask of all 1 s, a function of GXcopy, and a subwindow_mode of
ClipByChildren. If the window has background None, the contents of the window are not
changed. In either case, if exposures is True, then one or more exposure events are gen
erated for regions of the rectangle that are either visible or are being retained in a backing store.

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

Xlib Reference Manual

XCIearArea

(continued)

Xlib - Drawing Primitives

Window

[x,y] width

Window

[x,y] width

Window

[x,y] width =

Window

[x,y] width =

Errors

BadMatch
BadValue
BadWindow

Window is an inputOnly class window.

Related Commands

XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc, XDrawArcs, XDraw-
Filled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle,
XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFillPolygon,
XFillRectangle, XFillRectangles.

Xlib Reference Manual

-Xlib- Drawing Primitives /

Name

XClearWindow clear an entire window.

Synopsis

XClearWindow (display, w)
Display *display;
Window W,

Arguments

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

w Specifies the ID of the window to be cleared.

Description

XClearWindow clears a window, but does not cause exposure events. This function is equiv
alent to XClearArea (display, w, 0, 0, 0, 0, False).

If the window has a defined background tile or it is ParentRelative, the rectangle is tiled
with a plane_mask of all 1 s and function of GXcopy. If the window has background
None, the contents of the window are not changed.

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

Errors

BadMatch If vis an InputOnly class window.

BadValue
BadWindow

Related Commands

XClearArea, XCopyArea, XCopyPlane, XDraw, XDrawArc, XDrawArcs, XDraw-
Filled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle,
XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFillPolygon,
XFillRectangle, XFillRectangles.

Xlib Reference Manual 87

XCIipBox ~\

X Xlib - Regions-
Name

XCIipBox generate the smallest rectangle enclosing a region.

Synopsis

XCIipBox (r, rect)
Region r;
XRect angle *rect ; /* RETURN */

Arguments

r Specifies the region.

rect Returns the smallest rectangle enclosing region r.

Description

XCIipBox returns the smallest rectangle that encloses the given region.

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

Structures

Region is a pointer to an opaque structure type.

Related Commands

XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion,
XIntersectRegion, XOf f setRegion, XPointlnRegion, XPolygonRegion,
XRect InRegion, XSetRegion, XShrinkRegion, XSubtractRegion, XUnion-
RectWithRegion, XUnionRegion, XXorRegion.

Xlib Reference Manual

Xlib-HouseKeeping-

J XCIoseDisplay

Name

XCIoseDisplay disconnect a client program from an X server and display.

Synopsis

XCIoseDisplay (display)
Display *display;

Arguments

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

Description

XCIoseDisplay closes the connection between the current client and the X server specified
by the Display argument.

The XCIoseDisplay routine destroys all windows, resource IDs (Window, Font, Pixmap,
Colormap, Cursor, and GContext), or other resources (GCs) that the client application
has created on this display, unless the close down mode of the client s resources has been
changed by XSetCloseDownMode. Therefore, these windows, resource IDs, and other
resources should not be referenced again. In addition, this routine discards any requests that
have been buffered but not yet sent to the server.

Although these operations automatically (implicitly) occur when a process exits under UNIX,
you should call XCIoseDisplay anyway.

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

Def aultScreen, XFree, XNoOp, XOpenDisplay.

Xlib Reference Manual 89

XConfigureWindow . V|

v Xlib - Window Manipulation

Name

XConfigureWindow change the window position, size, border width, or stacking order.

Synopsis

XConf igureWindow ( display, i/, value_mask , values)
Display * display;
Window w;

unsigned int value_mask;
XWindowChanges * values;

Arguments

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

w Specifies the ID of the window to be reconfigured.

value_mask Specifies which values are to be set using information in the values struc
ture, val ue_mask is the bitwise OR of any number of symbols listed in the
Structures section below.

val ues Specifies a pointer to the XWindowChanges structure containing new confi

guration information. See the Structures section below.

Description

XConfigureWindow changes the window position, size, border width, and/or the stacking
order. If selected, a Conf igureNot if y event is generated to announce any changes.

If the window to be reconfigured is a top-level window, there will be interaction with the win
dow manager if the override_redirect attribute of the window is False. In this case,
the X server sends a Conf igureRequest event to the window manager and does not recon
figure the window. The window manager receives this event and then makes the decision
whether to allow the application to reconfigure its window. The client should wait for the
Conf igureNot if y event to find out the size and position of the window.

In Release 4, XReconf igureWMWindow should be used instead of XConfigureWindow
for top-level windows. This routine handles restacking of top-level windows properly.

If a window s size actually changes, the window s subwindows may move according to their
window gravity. If they do, GravityNotif y events will be generated for them. Depending
on the window s bit gravity, the contents of the window also may be moved. See Volume One,
Chapter 4, Window Attributes for further information.

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

The members of XWindowChanges that you specify in val ues are:

go Xlib Reference Manual

Xlib - Window Manipulation

(continued)

XConfigureWindow

x Specify the x and y coordinates of the upper-left outer comer of the window

y relative to the parent s origin.

width Specify the inside size of the window in pixels, not including the border.

height These arguments must be positive.

horde r_width

Specifies the width of the border in pixels.

sibling Specifies the sibling window for stacking operations. If not specified, no

change in the stacking order will be made. If specified, stack_mode must
also be specified.

stack_mode The stack mode can be any of these constants: Above, Below, Toplf ,
Bottomlf , or Opposite.

The computation for the Bottomlf, Toplf, and Opposite stacking modes is performed
with respect to window i/s final size and position (as controlled by the other arguments to
XConfigureWindow, not its initial position.) It is an error if sibling is specified without
stack_mode. If sibling and stack_mode are specified, the window is restacked as fol
lows:

Stacking Flag Position

Above
Below
Toplf

Bottomlf
Opposite

w is placed just above sibling
w is placed just below sibling

if sibling obscures w, then w is placed at the top
of the stack

if w obscures sibling, then w is placed at the bot
tom of the stack

if sibling occludes v/, then w is placed at the top
of the stack. If w occludes sibling, then w is
placed at the bottom of the stack. If wand sibling
do not overlap, no change is made.

Xlib Reference Manual

XConfigureWindOW (continued) Xlib - Window Manipulation

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

Stacking Flag

Above
Below
Toplf

Bottomlf
Opposite

Position

w is placed at the top of the stack
w is placed at the bottom of the stack

if any sibling obscures w, then w is placed at the top
of the stack

if w obscures any sibling, then window is placed at
the bottom of the stack

if any sibling occludes w, then w is placed at the top
of the stack, else if w occludes any sibling, then w is
placed at the bottom of the stack

Under Release 4, use XReconf igureWMWindow to configure a top-level window.
Structures

typedef struct {

int x, y;

int width, height;

int border_width;

Window sibling;

int stack_mode;
} XWindowChanges;

/* Conf igureWindow structure */

/* ChangeWindow value bits definitions for valuemask */

tdefine CWX (10)

#define CWY (11)

#define CWWidth (12)

tdefine CWHeight (13)

#define CWBorderWidth (14)

#define CWSibling (15)

#define CWStackMode (16)

Errors

BadMatch

Attempt to set any invalid attribute of InputOnly window.
sibling specified without a stack_mode.
The sibling window is not actually a sibling.

BadValue width or height isO.
BadWindow

Xlib Reference Manual

Xlib - Window Manipulation (continued) XConf IgureWlndOW

Related Commands

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate-
SubwindowsUp, XLowerWindow, XMoveResizeWindow, XMoveWindow, XQuery-
Tree, XReconf igureWMWindow, XRaiseWindow, XReparentWindow, XResize-
Window, XRestackWindows.

Xlib Reference Manual 9S

XConvertSelection A

Name

XConvertSelection use the value of a selection.

Synopsis

XConvertSelection ( display, selection, target, property,

requestor, time)
Display * display;
Atom selection, target;

Atom property; /* may be None */

Window requestor;
Time time;

Arguments

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

selection Specifies the selection atom. XA_PRIMARY and XA_SECONDARY are the stan
dard selection atoms.

target Specifies the atom of the type property that specifies the desired format for

the data.

property Specifies the property in which the requested data is to be placed. None is
also valid, but current conventions specify that the requestor is in a better
position to select a property than the selection owner.

requestor Specifies the requesting window.

time Specifies the time when the conversion should take place. Pass either a

timestamp, expressed in milliseconds, or the constant CurrentTime.

Description

XConvertSelection causes a SelectionRequest event to be sent to the current selec
tion owner if there is one, specifying the property to store the data in (selection), the format
to convert that data into before storing it (target), the property to place the information in
(property), the window that wants the information (requestor), and the time to make the
conversion (time).

The selection owner responds by sending a SelectionNotify event, which confirms the
selected atom and type. If no owner for the specified selection exists, or if the owner could not
convert to the type specified by requestor, the X server generates or the owner sends a
SelectionNotify event to the requestor with property None. Whether or not the owner
exists, the arguments are passed unchanged. See Volume One, Chapter I0,lnterclient Commu
nication, for a description of selection events and selection conventions.

Errors

BadAtom
BadWindow

Related Commands

XGet Select ionOwner, XSetSelectionOwner.

94 Xlib Reference Manual

Xlib - Drawing Primitives-

J XCopyArea

Name

XCopyArea copy an area of a drawable.

Synopsis

XCopyArea (display, src, dest , gc , src_x, src_y, width,

height, dest_x, dest_y)
Display *display;
Drawable src, dest;
GC gc;

int src_x, src_y;
unsigned int width, height;
int dest_x, dest_y ;

Arguments

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

src Specify the source and destination rectangles to be combined, src and

dest dest must have the same root and depth.

gc Specifies the graphics context.

src_x Specify the x and y coordinates of the upper- left corner of the source rectan-

src_y gle relative to the origin of the source drawable.

width Specify the dimensions in pixels of both the source and destination rectan-

height gles.

dest_x Specify the x and y coordinates within the destination window.

dest_y

Description

XCopyArea combines the specified rectangle of src with the specified rectangle of dest.
src and dest must have the same root and depth.

If regions of the source rectangle are obscured and have not been retained in back-
ing_store, or if regions outside the boundaries of the source drawable are specified, then
those regions are not copied. Instead, the following occurs on all corresponding destination
regions that are either visible or are retained in backing_store. If dest is a window with
a background other than None, the corresponding regions of the destination are tiled (with
plane_mask of all 1 s and function GXcopy) with that background. Regardless of tiling, if
the destination is a window and graphics_exposures in gc is True, then Graphics -
Expose events for all corresponding destination regions are generated. If graph-
ics_exposures is True but no regions are exposed, then a NoExpose event is generated.

If regions of the source rectangle are not obscured and graphics_exposures is False,
one NoExpose event is generated on the destination.

Xlib Reference Manual 95

XCopyArea (continued) Xlib - Drawing Primitives

XCopyArea uses these graphics context components: function, plane_mask,
subwindow_mode, graphics_exposures, clip_x_origin, clip_y_origin, and
clip_mask.

Errors

BadDrawable

BadGC

BadMatch The src and dest rectangles do not have the same root and depth.

Related Commands

XClearArea, XClearWindow, XCopyPlane, XDraw, XDrawArc, XDrawArcs,
XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDraw-
Rectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFill-
Polygon, XFillRectangle, XFillRectangles.

96 Xlib Reference Manual

Xlib-Colormaps-

j XCopyColormapAndFree

Name

XCopyColormapAndFree copy a colormap and return a new colormap ID.

Synopsis

Colormap XCopyColormapAndFree ( display f cmap)
Display *display;
Colormap cmap;

Arguments

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

cmap Specifies the colormap you are moving out of.

Description

XCopyColormapAndFree is used to obtain a new virtual colormap when allocating color-
cells out of a previous colormap has failed due to resource exhaustion (that is, too many cells or
planes were in use in the original colormap).

XCopyColormapAndFree moves all of the client s existing allocations from cmap to the
returned Colormap and frees those entries in cmap. The visual type and screen for the new
colormap is the same as for the old.

If cmap was created by the client with the all oc argument set to All oc All, the new color-
map is also created with AllocAll, all color values for all entries are copied from cmap, and
then all entries in cmap are freed.

If cmap was created by the client with AllocNone, the allocations to be moved are all those
pixels and planes that have been allocated by the client using XAllocColor, XAlloc-
NamedColor, XAllocColorCells, or XAllocColorPlanes and that have not been
freed since they were allocated. Values in other entries of the new Colormap are undefined.

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

Errors

BadAlloc
BadColormap

Related Commands

Def aultColormap, DisplayCells, XCreateColormap, XFreeColormap, XGet-
StandardColormap, XInstallColormap, XListlnstalledColormaps, XSet-
StandardColormap, XSetWindowColormap, XUninstallColormap.

Xlib Reference Manual

Py V xiib - Graphics Context-

Name

XCopyGC copy a graphics context.

Synopsis

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

Arguments

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

src Specifies the components of the source graphics context.

valuemask Specifies the components in the source GC structure to be copied into the des
tination GC. valuemask is made by combining any number of the mask
symbols listed in the Structures section using bitwise OR (|).

dest Specifies the destination graphics context.

Description

XCopyGC copies the selected elements of one graphics context to another. See Volume One,
Chapter 5, The Graphics Context, for a description of the graphics context.

Structures

The GC structure contains the following elements:

* Data structure for setting graphics context.

*/
typedef struct {

int function; /* logical operation */

unsigned long plane_mask; /* plane mask */

unsigned long foreground; /* foreground pixel */

unsigned long background; /* background pixel */

int line_width; /* line width */

int line_style; /* Solid, OnOffDash, DoubleDash */

int cap_style; /* NotLast, Butt, Round, Projecting */

int join_style; /* Miter, Round, Bevel */

int fill_style; /* Solid, Tiled, Stippled */

int fill_rule; /* EvenOdd, Winding */

int arc_mode; /* PieSlice */

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

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

int ts_x_origin; /* offset for tile or stipple operations */

int ts_y_origin;

Font font; /* default text font for text operations */

int subwindow_mode; /* ClipByChildren, Includelnf eriors */

Bool graphics_exposures; /* boolean, should exposures be generated */

int clip_x_origin; /* origin for clipping */

98 Xlib Reference Manual

Xlib -Graphics Context (continued) XCopyGC

int clip_y_origin;

Pixmap clip_mask; /* bitmap clipping; other calls for rects */
int dash_offset; /* patterned/dashed line information */

char dashes;
} XGCValues;

#define GCFunction

#define GCPlaneMask

tdefine GCForeground

#define GCBackground

#define GCLineWidth

#define GCLineStyle

#define GCCapStyle

tdefine GCJoinStyle

tdefine GCFillStyle

tdefine GCFillRule

#define GCTile

#define GCStipple

#define GCTileStipXOrigin

tdefine GCTileStipYOrigin

tdefine GCFont

tdefine GCSubwindowMode

tdefine GCGraphicsExposures

tdefine GCClipXOrigin

tdefine GCClipYOrigin

tdefine GCClipMask

tdefine GCDashOffset (1L20)

tdefine GCDashList (1L21)

tdefine GCArcMode (1L22)

Errors

BadAlloc

BadGC

BadMatch src and dest do not have the same root and depth.

Related Commands

Def aultGC, XChangeGC, XCreateGC, XFreeGC, XGContextFromGC, XGet-
GCValues, XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin,
XSetClipRectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSet-
Foreground, XSetFunction, XSetGraphicsExposures, XSetLineAttributes,
XSetPlaneMask, XSetState, XSetStipple, XSetSubwindowMode, XSet-
TSOrigin.

Xlib Reference Manual 99

XCopyPlane \ xnb _ Drawlng

Name

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

Synopsis

XCopyPlane ( display, src, dest , gc , src_x r src_y r width,

height, dest_x , dest_y, plane)
Display *display;
Drawable src, dest ,
GC gc;

int src_x, src_y;
unsigned int width, height;
int dest_x, dest_y;
unsigned long plane;

Arguments

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

src Specify the source and destination drawables.

dest

gc Specifies the graphics context.

src_x Specify the x and y coordinates of the upper-left corner of the source rectan-

src_y gle relative to the origin of the drawable.

width Specify the width and height in pixels. These are the dimensions of both the

height source and destination rectangles.

dest_x Specify the x and y coordinates at which the copied area will be placed rela-

dest_y live to the origin of the destination drawable.

plane Specifies the source bit-plane. You must set exactly one bit, and the bit must

specify a plane that exists in src.

Description

XCopyPlane copies a single plane of a rectangle in the source into the entire depth of a corre
sponding rectangle in the destination. The plane of the source drawable and the f ore-
ground/background pixel values in gc are combined to form a pixmap of the same depth
as the destination drawable, and the equivalent of an XGopyArea is performed, with all the
same exposure semantics.

XCopyPlane uses these graphics context components: function, plane_mask,
foreground, background, subwindow_mode, graphics_exposures,
clip_x_origin, clip_y_origin, and clip_mask.

The src and dest drawables must have the same root, but need not have the same depth.
For more information, see Volume One, Chapter 5, The Graphics Context.

100 Xlib Reference Manual

Xlib - Drawing Primitives (continued) XCopyPlane

Errors

BadDrawable

BadGC

BadMatch src and dest do not have the same root

BadValue plane does not have exactly one bit set, or bit specified in plane is not a
plane in src.

Related Commands

XClearArea, XClearWindow, XCopyArea, XDraw, XDrawArc, XDrawArcs, XDraw-
Filled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle,
XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFillPolygon,
XFillRectangle, XFillRectangles.

Xlib Reference Manual 1 1

XCreateAssocTable

Xlib - Association Tables

Name

XCreateAssocTable create a new association table (X10).

Synopsis

XAssocTable *XCreateAssocTable (size)
int size;

Arguments

si ze Specifies the number of buckets in the hashed association table.

Description

XCreateAssocTable creates an association table, which allows you to associate your own
structures with X resources in a fast lookup table. This function is provided for compatibility
with X Version 10. To use it you must include the file &lt;Xll/X10.h&gt; and link with the library
-loldX.

The size argument specifies the number of buckets in the hash system of XAssocTable.
For reasons of efficiency the number of buckets should be a power of two. Some size sugges
tions might be: use 32 buckets per 100 objects; a reasonable maximum number of object per
buckets is 8.

If there is an error allocating memory for the XAssocTable, a NULL pointer is returned.
For more information on association tables, see Volume One, Appendix E,X10 Compatibility.

Structures

typedef struct {

XAssoc *buckets; /* pointer to first bucket in array */
int size; /* table size (number of buckets) */

} XAssocTable;

Related Commands

XDeleteAssoc, XDestroyAssocTable, XLookUpAssoc, XMakeAssoc.

102 Xlib Reference Manual

Xlib - Pixmaps and Tiles-

J XCreateBitmapFromData

Name

XCreateBitmapFromData create a bitmap from xil bitmap format data.

Synopsis

Pixmap XCreateBitmapFromData ( display, drawable, data,

width, height)
Display *display;
Drawable drawable;
char *data;
unsigned int width, height;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenDi splay.

drawable Specifies a drawable. This determines which screen to create the bitmap on.
data Specifies the bitmap data, in XI 1 bitmap file format.

width Specify the dimensions in pixels of the created bitmap. If smaller than the

height bitmap data, the upper-left corner of the data is used.

Description

XCreateBitmapFromData creates a single-plane pixmap from an array of hexadecimal
data. This data may be defined in the program or included. The bitmap data must be in X ver
sion 11 format as shown below (it cannot be in X10 format). The following format is assumed
for the data, where the variables are members of the ximage structure described in Volume
One, Chapter 6, Drawing Graphics and Text:

f ormat=XYP ixmap

bit_order=LSBFirst

byte_order=LSBFirst

bitmap_unit=8

bitmap_pad=8

xof fset=0

no extra bytes per line

XCreateBitmapFromData creates an image with the specified data and copies it into the
created pixmap. The following is an example of creating a bitmap:

tdefine gray__width 16

tdefine gray_height 16

tdefine gray_x_hot 8

tdefine gray_y_hot 8

static char gray_bits [] = {

Oxf8, Oxlf, Oxe3, Oxc7, Oxcf, Oxf3, Ox9f, Oxf9,
Oxbf, Oxfd, 0x33, Oxcc, Oxlf, Oxfe, Oxlf, Oxfe,

Xlib Reference Manual 103

XCreateBitmapFromData (continued) Xlib - Pixmaps and Tiles

Ox7e, Ox7e, Ox7f, Oxfe, 0x37, Oxec, Oxbb, Oxdd,
Ox9c, 0x39, Oxcf, Oxf3, Oxe3, Oxc7, Oxf8, Oxlf};

Pixmap XCreateBitmapFromData (display, window, gray_bits,
gray_width, gray_height) ;

If the call could not create a pixmap of the requested size on the server, XCreateBitmap
FromData returns (zero), and the server generates a BadAlloc error. If the requested
depth is not supported on the screen of the specified drawable, the server generates a Bad-
Match error.

The user should free the bitmap using XFreePixmap when it is no longer needed.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.

Errors

BadAlloc Server has insufficient memory to create bitmap.

BadDrawable

BadValue Specified bitmap dimensions are zero.
Related Commands

XCreatePixmap, XCreatePixmapFromBitmapData, XCreatePixmapFrom-
BitmapData, XFreePixmap, XQueryBestSize, XQueryBestStipple, XQuery-
BestTile, XReadBitmapFile, XSetTile, XSetWindowBackgroundPixmap,
XSetWindowBorderPixmap, XWriteBitmapFile.

104 Xlib Reference Manual

Xlib - Colormaps -

J XCreateColormap

Name

XCreateColormap create a colormap.

Synopsis

Colormap XCreateColormap ( display, w, visual, alloc)
Display *display;
Window w;
Visual *visual;
int alloc;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

w Specifies a window ID. The colormap created will be associated with the

same screen as the window.

visual Specifies a pointer to the visual structure for the colormap. The visual

class and depth must be supported by the screen.

alloc Specifies how many colormap entries to allocate. Pass either AllocNone or

AllocAll.

Description

XCreateColormap creates a colormap of the specified visual type and allocates either none
or all of its entries, and returns the colormap ID.

It is legal to specify any visual class in the structure pointed to by the visual argument. If the
class is StaticColor, StaticGray, or TrueColor, the colorcells will have pre-allocated
read-only values defined by the individual server but unspecified by the XI 1 protocol. In these
cases, alloc must be specified as AllocNone (else a BadMatch error).

For the other visual classes, Pseudocolor, DirectColor, and Grayscale, you can pass
either AllocAll or AllocNone to the alloc argument. If you pass AllocNone, the
colormap has no allocated entries. This allows your client programs to allocate read-only
colorcells with XAllocColor or read/write cells with XAllocColorCells, Alloc-
ColorPlanes and XStoreColors. If you pass the constant AllocAll, the entire color-
map is allocated writable (all the entries are read/write, nonshareable and have undefined initial
RGB values), and the colors can be set with XStoreColors. However, you cannot free these
entries with XFreeColors, and no relationships between the entries are defined.

If the visual class is Pseudocolor or Grayscale and alloc is AllocAll, this function
simulates a call to the function XAllocColor cells returning all pixel values from 1 to
(map_entries - 1) . For a visual class of DirectColor, the processing for AllocAll
simulates a call to the function XAllocColorPlanes, returning a pixel value of and mask
values the same as the red__mask, green_mask, and blue_mask members in visual.

Xlib Reference Manual 105

XCreateColormap (continued) Xlib - Colormaps

The visual argument should be as returned from the Def aultvisual macro, XMatch-
Visuallnf o, or XGetVisuallnf o.

If the hardware colormap on the server is immutable, and therefore there is no possibility that a
virtual colormap could ever be installed, XCreateColormap returns the default colormap.
Code should check the returned ID against the default colormap to catch this situation.

For more information on creating colormaps, see Volume One, Chapter 7, Color.

Errors

BadAlloc

BadMatch Didn t use AllocNone for StaticColor, StaticGray, or True-
Color,
visual type not supported on screen.

BadValue
BadWindow

Related Commands

Def aultColormap, DisplayCells, XCopyColormapAndFree, XFreeColormap,
XGetStandardColormap, XInstallColormap, XListlnstalledColormaps,
XSetStandardColormap, XSetWindowColormap, XUninstallColormap.

106 Xlib Reference Manual

Xlib- Cursors-

XCreateFontCursor

Name

XCreateFontCursor create a cursor from the standard cursor font.

Synopsis

#include &lt;Xll/cursorf ont .h&gt;
Cursor XCreateFontCursor ( display,

Display * display ;

unsigned int shape;

shape)

Arguments

display Specifies a connection to an X server; returned from xopenDisplay.

shape Specifies which character in the standard cursor font should be used for the cur

sor.

Description

X provides a set of standard cursor shapes in a special font named "cursor." Programs are
encouraged to use this interface for their cursors, since the font can be customized for the indi
vidual display type and shared between clients.

The hotspot comes from the information stored in the font. The initial colors of the cursor arc
black for the foreground and white for the background. XRecolorCursor can be
used to change the colors of the cursor to those desired.

For more information about cursors and their shapes in fonts, see Appendix I, The Cursor Font.

X//6 Reference Manual

107

XCreateFontCursor (continued) Xlib - Cursors

Errors

BadAlloc

BadFont

BadValue The shape argument does not specify a character in the standard cursor font.

Related Commands

XCreateGlyphCursor, XCreatePixmapCursor, XDef ineCursor, XFreeCursor,
XQueryBestCursor, XQueryBestSize, XRecolorCursor, XUndef ineCursor.

108 Xlib Reference Manual

Xlib - Graphics Context-

XCreateGC

Name

XCreateGC create a new graphics context for a given screen with the depth of the specified
drawable.

Synopsis

GC XCreateGC (display, drawable, valuemask, values)
Display *display;
Drawable drawable;
unsigned long valuemask;
XGCValues * values ;

Arguments

di spl ay
drawable

valuemask
values

Specifies a connection to an X server; returned from xopenDisplay.

Specifies a drawable. The created GC can only be used to draw in drawables
of the same depth as this drawable.

Specifies which members of the GC are to be set using information in the
values structure, valuemask is made by combining any number of the
mask symbols listed in the Structures section.

Specifies a pointer to an XGCValues structure which will provide compo
nents for the new GC.

Description

XCreateGC creates a new graphics context resource in the server. The returned GC can be
used in subsequent drawing requests, but only on drawables on the same screen and of the same
depth as the drawable specified in the drawable argument.

The specified components of the new graphics context in valuemask are set to the values
passed in the val ues argument. Unset components default as follows:

Component Value

plane_mask

foreground

background

line_width

line_style

cap_style

join_style

fill_style

fill_rule

arc_mode

tile

stipple

alll s

LineSolid

CapButt

JoinMiter

FillSolid

EvenOddRule

ArcPieSlice

Pixmap filled with foreground pixel

Pixmap filled with 1 s

Xlib Reference Manual

109

XCreateGC

(continued)

Xlib - Graphics Context

Component

Value

ts_x_origin

ts y origin

font

(implementation

dependent)

subwindow mode

ClipByChildren

graphics_exposures

True

clip x origin

clip_y_origin

clip_mask

None

dash offset

dash list

4 (i.e., the list [4

,4])

An application should minimize the number of GCs it creates, because some servers cache a
limited number of GCs in the display hardware, and can attain better performance with a small
number of GCs.

For more information, see Volume One, Chapter 5, The Graphics Context.

Errors

BadAlloc Server could not allocate memory for GC.

BadDrawable Specified drawable is invalid.

BadFont Font specified for font component of GC has not been loaded.

BadMatch Pixmap specified for tile component has different depth or is on different
screen from the specified drawable. Or pixmap specified for stipple or
clip_mask component has depth other than 1.

BadPixmap Pixmap specified for tile, stipple, or clip_mask components is inva
lid.

BadValue Values specified for function, line_style, cap_style,
join_style, f ill_style, f ill_rule, subwindow_mode, graph-
ics_exposures, dashes, or arcjmode are invalid, or invalid mask
specified for valuemask argument.

Structures

typedef struct {

int function; /*

unsigned long plane mask; /*

unsigned long foreground; /*

unsigned long background; /*

int line_width; /*

int line_style; /*

int cap_style; /*

int join_style; /*

int fill_style; /*

int fill rule; /*

logical operation */

plane mask */

foreground pixel */

background pixel */

line width */

LineSolid, LineOnOf f Dash, LineDoubleDash */

CapNotLast, CapButt, CapRound, CapPro jecting */

JoinMiter, JoinRound, JoinBevel */

FillSolid, FillTiled, FillStippled */

EvenOddRule, WindingRule */

110

Xlib Reference Manual

Xlib - Graphics Context

(continued)

XCreateGC

int arc_mode;
Pixmap tile;
Pixmap stipple;
int ts_x_origin;
int ts_y_origin;
Font font;
int subwindow_mode;
Bool graphics_exposures;
int clip_x_origin;
int clip_y_origin;
Pixmap clip_mask;
int dash_offset;
char dashes;
} XGC Value s;

#define GCFunction
#define GCPlaneMask
#define GCForeground
#define GCBackground
#define GCLineWidth
#define GCLineStyle
#define GCCapStyle
#define GCJoinStyle
#define GCFillStyle
#define GCFillRule
#define GCTile
#define GCStipple
#define GCTileStipXOrigin
#define GCTileStipYOrigin
#define GCFont
#define GCSubwindowMode
#define GCGraphicsExposures
#define GCClipXOrigin
#define GCClipYOrigin
tdefine GCClipMask
#define GCDashOffset
#define GCDashList
#define GCArcMode

/* ArcPieSlice, ArcChord */

/* tile pixmap for tiling operations */

/* stipple 1 plane pixmap for stipping */

/* offset for tile or stipple operations */

/* default text font for text operations */

/* ClipByChildren, Includelnferiors */

/* generate events on XCopyArea, XCopyPlane */

/* origin for clipping */

/* bitmap clipping; other calls for rects */

/* patterned/dashed line information */

(1L20)
(1L22)

Related Commands

Def aultGC, XChangeGC, XCopyGC, XFreeGC, XGContextFromGC, XGetGCValues,
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip-
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground,
XSetFunction, XSetGraphicsExposures, XSetLineAttributes, XSetPlane-
Mask, XSetState, XSetStipple, XSetSubwindowMode, XSetTSOrigin.

Xlib Reference Manual

111

XCreateGlyphCursor \

v Xlib - Cursors-
Name

XCreateGlyphCursor create a cursor from font glyphs.

Synopsis

Cursor XCreateGlyphCursor ( display, source_font , mask_font,
source_char r mask_char , foreground_color, back-
ground_color)

Display * display ;

Font source_font , mask_font;

unsigned int source_char, mask_char;

XColor * foreground_color;

XColor *background_color;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

source_font Specifies the font from which a character is to be used for the cursor.
mask_font Specifies the mask font. Optional; specify if not needed.
source_char Specifies the index into the cursor shape font.

mask_char Specifies the index into the mask shape font. Optional; specify if not
needed.

foreground_color

Specifies the red, green, and blue (RGB) values for the foreground.

background_color

Specifies the red, green, and blue (RGB) values for the background.

Description

XCreateGlyphCursor is similar to XCreatePixmapCursor, but the source and mask
bitmaps are obtained from separate font characters, perhaps in separate fonts. The mask font
and character are optional. If mask_char is not specified, all pixels of the source are
displayed.

The x offset for the hotspot of the created cursor is the left-bearing for the source character, and
the y offset is the ascent, each measured from the upper-left corner of the bounding rectangle of
the character.

The origins of the source and mask (if it is defined) characters are positioned coincidently and
define the hotspot. The source and mask need not have the same bounding box metrics, and
there is no restriction on the placement of the hotspot relative to the bounding boxes.

Note that source_char and mask_char are of type unsigned int, not of type
XChar2b. For two-byte matrix fonts, source_char and mask_char should be formed
with the bytel member in the most significant byte and the byte2 member in the least signif
icant byte.

1 12 Xlib Reference Manual

Xlib- Cursors (continued) XCreateGlyphCursor

You can free the fonts with XFreeFont if they are no longer needed after creating the glyph
cursor.

For more information on fonts and cursors, see Volume One, Chapter 6, Drawing Graphics and
Text.

Structures

typedef struct {

unsigned long pixel;

unsigned short red, green, blue;

char flags; /* DoRed, DoGreen, DoBlue */

char pad;
} XColor;

Errors

BadAlloc

BadFont

BadValue source_charnot defined in source_font.

mask_ch a mot defined in mask_font (if mas k_ font defined).

Related Commands

XCreateFontCursor, XCreatePixmapCursor, XDef ineCursor, XFreeCursor,
XQueryBestCursor, XQueryBestSize, XRecolorCursor, XUndef ineCursor.

Xlib Reference Manual 1 13

XCreatelmage \ X|jb _ |mages _

Name

XCreatelmage allocate memory for an Xlmage structure.

Synopsis

tfinclude &lt;Xll/Xutil.h&gt;

Xlmage *XCreateImage (display, visual, depth, format, offset,
data, width, height, bitmap_pad, bytes_per_line)

Display * display;

Visual *visual;

unsigned int depth;

int format;

int offset;

char *data;

unsigned int width;

unsigned int height;

int bitmap_pad;

int bytes_per_line;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

visual Specifies a pointer to a visual that should match the visual of the window the

image is to be displayed in.

depth Specifies the depth of the image.

format Specifies the format for the image. Pass one of these constants: XYPixmap,

or ZPixmap.

offset Specifies the number of pixels beyond the beginning of the data (pointed to

by data) where the image actually begins. This is useful if the image is not
aligned on an even addressable boundary.

da t a Specifies a pointer to the image data.

wi dth Specify the width and height in pixels of the image.

height

bi t/nap_pad Specifies the quantum of a scan line. In other words, the start of one scan line
is separated in client memory from the start of the next scan line by an integer
multiple of this many bits. You must pass one of these values: 8 , 1 6 , or 3 2 .

jbytes_per_line

Specifies the number of bytes in the client image between the start of one
scan line and the start of the next. If you pass a value of here, Xlib assumes
that the scan lines are contiguous in memory and thus calculates the value of
bytes_per_line itself.

7 14 Xlib Reference Manual

Xlib- Images (continued) XCreatelmage

Description

XCreatelmage allocates the memory needed for an Xlmage structure for the specified dis
play and visual.

This function does not allocate space for the image itself. It initializes the structure with byte
order, bit order, and bitmap unit values, and returns a pointer to the Xlmage structure. The red,
green, and blue mask values are defined for ZPixmap format images only and are derived from
the visual structure passed in.

For a description of images, see Volume One, Chapter 6, Drawing Graphics and Text.
Related Commands

ImageByteOrder, XAddPixel, XDestroylmage, XGetlmage, XGetPixel, XGet-
Sublmage, XPutlmage, XPutPixel, XSublmage.

Xlib Reference Manual

115

XCreatePixmap

Xlib - Pixmaps and Tiles-
Name

XCreatePixmap create a pixmap.

Synopsis

Pixmap XCreatePixmap ( display, drawable , width, height, depth)
Display * display;
Drawable drawable;
unsigned int width, height;
unsigned int depth;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenDi spl ay.

drawable Specifies the drawable. May be an inputOnly window.

width Specify the width and height in pixels of the pixmap. The values must be

height nonzero.

depth Specifies the depth of the pixmap. The depth must be supported by the screen

of the specified drawable. (Use XListDepths if in doubt.)

Description

XCreatePixmap creates a pixmap resource and returns its pixmap ID. The initial contents
of the pixmap are undefined.

The server uses the drawable argument to determine which screen the pixmap is stored on.
The pixmap can only be used on this screen. The pixmap can only be drawn drawn into with
GCs of the same depth, and can only be copied to drawables of the same depth, except in
XCopyPlane.

A bitmap is a single-plane pixmap. There is no separate bitmap type in X Version 11.

Pixmaps should be considered a precious resource, since many servers have limits on the
amount of off-screen memory available.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text.

Errors

BadAlloc

BadDrawable

BadValue width or height is 0.

depth is not supported on screen.

Related Commands

XCreateBitmapFromData, XCreatePixmapFromBitmapData, XFreePixmap,
XListDepths, XListPixmapFormat, XQueryBestCursor, XQueryBestSize,
XQueryBestStipple, XQueryBestTile, XReadBitmapFile, XSetTile, XSet-
WindowBackgroundPixmap, XSetWindowBorderPixmap, XWriteBitmapFile.

1 16 Xlib Reference Manual

Xlib - Pixmaps and Tiles-

J XCreatePixmapCursor

Name

XCreatePixmapCursor create a cursor from two bitmaps.

Synopsis

Cursor XCreatePixmapCursor ( display, source, mask,

foreground_color, background_color, x_hot , y_hot)
Display * display;
Pixmap source;
Pixmap mask;

XColor * foreground_color;
XColor *background_color;
unsigned int x_hot , y_hot ;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenDi spl ay.

source Specifies the shape of the source cursor. A pixmap of depth 1.

mask Specifies the bits of the cursor that are to be displayed (the mask or stipple).

A pixmap of depth 1.

-foreground_color

Specifies the red, green, and blue (RGB) values for the foreground.

jbacJegrour!d_co-Zor

Specifies the red, green, and blue (RGB) values for the background.

x_hot Specify the coordinates of the cursor s hotspot relative to the source s origin.

y_hot Must be a point within the source.

Description

XCreatePixmapCursor creates a cursor and returns a cursor ID. Foreground and back
ground RGB values must be specified using oreground_color and back-
ground_color, even if the server only has a monochrome screen. The fore-
ground_color is used for the 1 bits in the source, and the background is used for the bits.
Both source and mask (if specified) must have depth 1, but can have any root. The mask pix
map defines the shape of the cursor; that is, the 1 bits in the mask define which source pixels
will be displayed. If no mask is given, all pixels of the source are displayed. The mask, if
present, must be the same size as the source.

The pixmaps can be freed immediately if no further explicit references to them are to be made.
For more information on cursors, see Volume One, Chapter 6, Drawing Graphics and Text.

Structures

typedef struct {

unsigned long pixel;

unsigned short red, green, blue;

char flags; /* DoRed, DoGreen, DoBlue */

Xlib Reference Manual 1 1 7

XCreatePixmapCursor (continued) Xlib - Pixmaps and Tiles

char pad;
} XColor;

Errors

BadAlloc

BadMatch Mask bitmap must be the same size as source bitmap.
BadPixmap

Related Commands

XCreateBitmapFromData, XDef ineCursor, XCreateFontCursor, XCreate-
Pixmap, XCreatePixmapCursor, XFreeCursor, XFreePixmap, XQueryBest-
Cursor, XQueryBestCursor, XQueryBestSize, XQueryBestSize, XRead-
BitmapFile, XRecolorCursor, XUndef ineCursor.

1 18 Xlib Reference Manual

Xlib - Pixmaps and Bitmaps -

XCreatePixmapFromBJtmapData

Name

XCreatePixmapFromBitmapData create a pixmap with depth from bitmap data.

Synopsis

Pixmap XCreatePixmapFromBitmapData ( display, drawable, data,

width, height, fg, bg, depth)
Display * display;
Drawable drawable;
char *data;

unsigned int width, height;
unsigned long fg, bg;
unsigned int depth;

Arguments

display Specifies a connection to an Display structure, returned from XOpen-

Display.

drawable Specifies a drawable ID which indicates which screen the pixmap is to be
used on.

data Specifies the data in bitmap format.

width Specify the width and height in pixels of the pixmap to create.

height

fg Specify the foreground and background pixel values to use.

depth Specifies the depth of the pixmap. Must be valid on the screen specified by

drawable.

Description

XCreatePixmapFromBitmapData creates a pixmap of the given depth using bitmap data
and foreground and background pixel values.

The following format for the data is assigned, where the variables are members of the XI mage
structure described in Volume One, Chapter 6, Drawing Graphics and Text:

format =XYP ixmap

bit_order=LSBFirst

byte_order=LSBFirst

bitmap_unit=8

bitmap_pad=8

xoffset=0

no extra bytes per line

XCreatePixmapFromBitmapData creates an image from the data and uses XPutlmage
to place the data into the pixmap. For example:

Xlib Reference Manual 1 19

XCreatePixmapFromBitmapData (continued)

Xlib - Pixmaps and Bitmaps

#define gray_width 16

#define gray_height 16

#define gray_x_hot 8

#define gray_y_hot 8

static char gray_bits[] =
Oxf8, Oxlf, Oxe3, Oxc7,
Oxfd, 0x33, Oxcc, Ox7f,
Ox7f, Oxfe, 0x37, Oxec,
Oxf3, Oxe3, Oxc7, Oxf8,

Oxcf,
Oxfe,
Oxbb,

Oxlf}

Oxf3,
Ox7f,
Oxdd,

Ox9f,
Oxfe,
Ox9c,

Oxf9,
Ox7e,
0x39,

Oxbf,
Ox7e,
Oxcf,

unsigned long foreground, background;
unsigned int depth;

/* open display, determine colors and depth */

Pixmap XCreatePixmapFromBitmapData (display, window, gray_bits,

gray_width, gray_height, foreground, background, depth) ;

If you want to use data of a different format, it is straightforward to write a routine that does
this yourself, using images.

Pixmaps should be considered a precious resource, since many servers have limits on the
amount of off-screen memory available.

Errors

BadAlloc
BadDrawable

BadValue The width or height of pixmap are zero, or depth is not a valid depth on
the screen specified by drawable.

Related Commands

XCreateBitmapFromData, XCreateFontCursor, XCreatePixmap, XCreate-
PixmapCursor, XDef ineCursor, XFreeCursor, XFreePixmap, XListPixmap-
Formats, XQueryBestCursor, XQueryBestSize, XReadBitmapFile, XRecolor-
Cursor, XUndef ineCursor.

120

Xlib Reference Manual

Xlib- Regions-

J XCreateRegion

Name

XCreateRegion create a new empty region.

Synopsis

Region XCreateRegion ()

Description

XCreateRegion creates a new region of undefined size. XPolygonRegion can be used to
create a region with a defined shape and size. Many of the functions that perform operations on
regions can also create regions.

For a description of regions, see Volume One, Chapter 6, Drawing Graphics and Text.

Structures

Region is a pointer to an opaque structure type.

Related Commands

XClipBox, XDestroyRegion, XEmptyRegion, XEqualRegion, Xlntersect-
Region, XOf f setRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion,
XSetRegion, XShrinkRegion, XSubtractRegion, XUnionRectWithRegion,
XUnionRegion, XXorRegion.

Xlib Reference Manual 121

XCreateSimpleWindow . vr .

v Xlib - Window Existence

Name

XCreateSimpleWindow create an unmapped InputOutput window.

Synopsis

Window XCreateSimpleWindow (display, parent, x, y, width, height,
border_width, border, background)

Display * display;

Window parent;

int x, y;

unsigned int width, height, border_width;

unsigned long border;

unsigned long background;

Arguments

di spl ay Specifies a pointer to the Di spl ay structure; returned from XOpenDi spl ay.

parent Specifies the parent window ID. Must be an InputOutput window.

x Specify the x and y coordinates of the upper-left pixel of the new window s

y border relative to the origin of the parent (inside the parent window s border).

width Specify the width and height, in pixels, of the new window. These are the

height inside dimensions, not including the new window s borders, which are entirely

outside of the window. Must be nonzero. Any part of the window that extends

outside its parent window is clipped.

border_wi dth

Specifies the width, in pixels, of the new window s border.

border Specifies the pixel value for the border of the window.

background Specifies the pixel value for the background of the window.

Description

XCreateSimpleWindow creates an unmapped InputOutput subwindow of the specified
parent window. Use XCreateWindow if you want to set the window attributes while creating
a window. (After creation, XChangeWindowAttributes can be used.)

XCreateSimpleWindow returns the ID of the created window. The new window is placed
on top of the stacking order relative to its siblings. Note that the window is unmapped when it
is created use Mapwindow to display it. This function generates a XCreateNotify event.

The initial conditions of the window are as follows:

The window inherits its depth, class, and visual from its parent. All other window attributes
have their default values.

All properties have undefined values.

The new window will not have a cursor defined; the cursor will be that of the window s parent
until the cursor attribute is set with XDefineCursor or XChangeWindowAttributes.

122 Xlib Reference Manual

Xlib- Window Existence (continued) XCreateSimpleWindOW

If no background or border is specified, CopyFromParent is implied.

For more information, see Volume One, Chapter 2, X Concepts, and Volume One, Chapter 3,
Basic Window Program.

Errors

BadAlloc

BadMatch

BadValue width or height is zero.

Badwindow Specified parent is an Input Only window.

Related Commands

XCreateWindow, XDestroySubwindows, XDestroyWindow.

Xlib Reference Manual 123

XCreateWindow "\

v Xlib - Window Existence

Name

XCreateWindow create a window and set attributes.

Synopsis

Window XCreateWindow (display, parent, x, y, width, height,
border_width, depth, class, visual, valuemask,
attributes)

Display * display;

Window parent;

int x, y;

unsigned int width, height;

unsigned int border_width;

int depth;

unsigned int class;

Visual ^visual

unsigned long valuemask;

XSetWindowAttributes * attributes;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

parent Specifies the parent window. Parent must be inputOutput if class of win

dow created is to be InputOutput.

x Specify the x and y coordinates of the upper-left pixel of the new window s

y border relative to the origin of the parent (upper left inside the parent s border).

width Specify the width and height, in pixels, of the window. These are the new win-

height dow s inside dimensions. These dimensions do not include the new window s

borders, which are entirely outside of the window. Must be nonzero, otherwise

the server generates a BadValue error.

border_ width

Specifies the width, in pixels, of the new window s border. Must be for
inputOnly windows, otherwise a BadMatch error is generated.

depth Specifies the depth of the window, which is less than or equal to the parent s

depth. A depth of CopyFromParent means the depth is taken from the par
ent. Use XListDepths is choosing an unusual depth. The specified depth
paired with the visual argument must be supported on the screen.

class Specifies the new window s class. Pass one of these constants: Input-

Output, InputOnly, or CopyFromParent.

visual Specifies a connection to an visual structure describing the style of colormap to

be used with this window. CopyFromParent is valid.

valuemask Specifies which window attributes are defined in the attributes argument.
If valuemask is 0, attributes is not referenced. This mask is the bitwise
OR of the valid attribute mask bits listed in the Structures section below.

124 Xlib Reference Manual

Xlib - Window Existence (continued) XCreateWindOW

attributes Attributes of the window to be set at creation time should be set in this struc
ture. The value/nasJt should have the appropriate bits set to indicate which
attributes have been set in the structure.

Description

To create an unmapped subwindow for a specified parent window use XCreateWindow or
XCreateSimpleWindow. XCreateWindow is a more general function that allows you to
set specific window attributes when you create the window. If you do not want to set specific
attributes when you create a window, use XCreateSimpleWindow, which creates a window
that inherits its attributes from its parent. XCreateSimpleWindow creates only Input-
Output windows that use the default depth and visual.

XCreateWindow returns the ID of the created window. XCreateWindow causes the X
server to generate a CreateNotif y event. The newly created window is placed on top of its
siblings in the stacking order.

Extension packages may define other classes of windows.

The visual should be Def aultvisual or one returned by XGetvisuallnf o or XMatch-
Visuallnfo. The depth should be DefaultDepth, 1, or a depth returned by XList-
Depths. In current implementations of Xlib, if you specify a visual other than the one used by
the parent, you must first find (using XGetRGBColormaps) or create a colormap matching
this visual and then set the colormap window attribute in the attributes and valuemask
arguments. Otherwise, you will get a BadMatch error.

For more information, see Volume One, Chapter 4, Window Attributes.

Structures

* Data structure for setting window attributes.

*/
typedef struct {

Pixmap background_pixmap; /* background or None or ParentRelative */

unsigned long background_pixel; /* background pixel */

Pixmap border_pixmap; /* border of the window */

unsigned long border_pixel; /* border pixel value */

int bit_gravity; /* one of bit gravity values */

int win gravity; /* one of the window gravity values */

int backing store; /* NotUseful, WhenMapped, Always */

unsigned long backing_planes; /* planes to be preseved if possible */

unsigned long backing_pixel; /* value to use in restoring planes */

Bool save_under; /* should bits under be saved (popups) */

long event mask; /* set of events that should be saved */

long do not propagate_mask; /* set of events that should not propagate i

Bool override_redirect; /* boolean value for override-redirect */

Colormap colormap; /* colormap to be associated with window */

Cursor cursor; /* cursor to be displayed (or None) */
} XSetWindowAttributes;

Xlib Reference Manual 125

XCreateWindOW (continued) Xlib - Window Existence

/* Definitions for valuemask argument */

tdefine CWBackPixmap (1L0)

tdefine CWBackPixel (1L1)

tdefine CWBorderPixmap (1L2)

#define CWBorderPixel (1L3)

#define CWBitGravity (1L4)

#define CWWinGravity (1L5)

#define CWBackingStore (1L6)

tdefine CWBackingPlanes (1L7)

#define CWBackingPixel (1L8)

tdefine CWOverrideRedirect (1L9)

tdefine CWSaveUnder (1L10)

#define CWEventMask (1L11)

tdefine CWDontPropagate (1L12)

tdefine CWColormap (1L13)

tdefine CWCursor (1L14)

Errors

BadAlloc Attribute besides win_gravity, event_mask, do_not_propagate
mask, override_redirect or cursor specified for InputOnly win
dow.

BadColormap depth nonzero for InputOnly.
BadCursor Parent of InputOutput is InputOnly.
BadMatch border_width is nonzero for InputOnly.
BadPixmap depth not supported on screen for InputOutput.
BadValue width or height is 0.
Badwindow visual not supported on screen.

Related Commands

XCreateSimpleWindow, XDestroySubwindows, XDestroyWindow, XList-
Depths.

126 xiib Reference Manual

-x,,b - cursors / XDefineCursor

Name

XDefineCursor assign a cursor to a window.

Synopsis

XDefineCursor (display, w, cursor)
Display * display;
Window w;
Cursor cursor;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

w Specifies the ID of the window in which the cursor is to be displayed.

cursor Specifies the cursor to be displayed when the pointer is in the specified win

dow. Pass None to have the parent s cursor displayed in the window, or for
the root window, to have the default cursor displayed.

Description

Sets the cursor attribute of a window, so that the specified cursor is shown whenever this win
dow is visible and the pointer is inside. If XDefineCursor is not called, the parent s cursor
is used by default.

For more information on available cursors, see Appendix I, The Cursor Font.
Errors

BadCursor
BadWindow

Related Commands

XCreateFontCursor, XCreateGlyphCursor, XCreatePixmapCursor, XFree-
Cursor, XQueryBestCursor, XQueryBestSize, XRecolorCursor, XUndef ine-
Cursor.

Xlib Reference Manual 127

XDeleteAssoc , vr .

v Xlib - Association Tables-
Name

XDeleteAssoc delete an entry from an association table.

Synopsis

XDeleteAssoc ( display, table , x_id)
Display * display ;
XAssocTable * table;
XID x_id;

Arguments

display Specifies a connection to an X server; returned from XQpenDi splay.

table Specifies one of the association tables created by XCreateAssocTable.

x_i d Specifies the X resource ID of the association to be deleted.

Description

This function is provided for compatibility with X Version 10. To use it you must include the
file &lt;XlllX10.h&gt; and link with the library -loldX.

XDeleteAssoc deletes an association in an XAssocTable keyed on its XID. Redundant
deletes (and deletes of nonexistent X ID S) are meaningless and cause no problems. Deleting
associations in no way impairs the performance of an XAssocTable.

For more information on association tables, see Volume One, Appendix R,X10 Compatibility.
Structures

typedef struct {

XAssoc ^buckets; /* pointer to first bucket in array */
int size; /* table size (number of buckets) */

} XAssocTable;

Related Commands

XCreateAssocTable, XDestroyAssocTable, XLookUpAssoc, XMakeAssoc.

128 Xlib Reference Manual

-XHb - Conttxt Manager - /

Name

XDeleteContext delete a context entry for a given window and type.

Synopsis

int XDeleteContext { display, w r context)
Display * display;
Window w;
XContext context;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

w Specifies the window with which the data is associated.

context Specifies the context type to which the data belongs.

Description

XDeleteContext deletes the entry for the given window and type from the context data
structure defined in &lt;Xll/Xutil.h&gt;. This function returns XCNOENT if the context could not be
found, or zero if it succeeds. XDeleteContext does not free the memory allocated for the
data whose address was saved.

See Volume One, Chapter 13, Other Programming Techniques, for a description of context
management.

Structures

typedef int XContext;

Related Commands

XFindContext, XSaveContext, XUniqueContext.

Xlib Reference Manual 129

XDeleteModifiermapEntry \ X|lb _ ResourM Manager _

Name

XDeleteModifiermapEntry delete an entry from an XModif ierKeymap structure.

Synopsis

XModif ierKeymap *XDeleteModif iermapEntry (/nod/nap,

keysym_entry, modifier)
XModif ierKeymap * modmap;
KeyCode keysym_entry;
int modifier;

Arguments

modmap Specifies a pointer to an XModif ierKeymap structure.

k eysym_ entry

Specifies the keycode of the key to be deleted from modmap.

modifier Specifies the modifier you no longer want mapped to the keycode specified in
keysym_entry. This should be one of the constants: Shif tMaplndex,
LockMapIndex, ControlMapIndex, ModlMapIndex, Mod2Map-
Index, ModSMapIndex, Mod4MapIndex, or ModSMapIndex.

Description

XDeleteModifiermapEntry returns an XModif ierKeymap structure suitable for cal
ling XSetModif ierMapping, in which the specified keycode is deleted from the set of key-
codes that is mapped to the specified modifier (like Shift or Control). XDelete
ModifiermapEntry itself does not change the mapping.

This function is normally used by calling XGetModif ierMapping to get a pointer to the
current XModif ierKeymap structure for use as the modmap argument to XDelete
ModifiermapEntry.

Note that the structure pointed to by modmap is freed by XDeleteModifiermapEntry. It
should not be freed or otherwise used by applications after this call.

For a description of the modifier map, see XSetModif ierMapping.
Structures

typedef struct {

int max_keypermod; /* server s max number of keys per modifier */
KeyCode *modif iermap; /* an 8 by max_keypermod array of

* keycodes to be used as modifiers */

} XModif ierKeymap;

#define ShiftMapIndex

#define LockMapIndex 1

tdefine ControlMapIndex 2

#define ModlMapIndex 3

#define Mod2MapIndex 4

tdefine ModSMapIndex 5

130 Xlib Reference Manual

Xlib - Resource Manager (continued) XDeleteModif iermapEntry

tdefine Mod4MapIndex 6
tdefine ModSMapIndex

Related Commands

XFreeModif iermap, XGetKeyboardMapping, XGetModif ierMapping,
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym,
XLookupString, XNewModif iermap, XQueryKeymap, XRebindKeySym,
XRef reshKeyboardMapping, XSetModif ierMapping, XStringToKeysym,
I nsertModif iermapEntry.

Xlib Reference Manual 131

XDeleteProperty V

Name

XDeleteProperty delete a window property.

Synopsis

XDeleteProperty ( display, w, property)
Display * display ;
Window w;
Atom property;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window whose property you want to delete.

property Specifies the atom of the property to be deleted.

Description

XDeleteProperty deletes a window property, so that it no longer contains any data. Its
atom, specified by property, still exists after the call so that it can be used again later by any
application to set the property once again. If the property was defined on the specified window,
XDeleteProperty generates a PropertyNotify event.

See the introduction to properties in Volume One, Chapter 2, X Concepts, or more detailed
information in Volume One, Chapter 10, Interclient Communication.

Errors

BadAtom
BadWindow

Related Commands

XChangeProperty, XGetAtomName, XGetFontProperty, XGetWindowProperty,
XInternAtom, XListProperties, XRotateWindowProperties, XSetStandard-
Properties.

132 xiib Reference Manual

Xlib - Association Tables-

J XDestroyAssocTable

Name

XDestroyAssocTable free the memory allocated for an association table.

Synopsis

XDestroyAssocTable (table)
XAssocTable *table;

Arguments

tabl e Specifies the association table whose memory is to be freed.

Description

This function is provided for compatibility with X Version 10. To use it you must include the
file &lt;Xll/X10.h&gt; and link with the library -loldX.

Using an XAssocTable after it has been destroyed will have unpredictable consequences.
For more information on association tables, see Volume One, Appendix B, XI Compatibility.

Structures

typedef struct {

XAssoc ^buckets; /* pointer to first bucket in array */
int size; /* table size (number of buckets) */

} XAssocTable;

Related Commands

XCreateAssocTable, XDeleteAssoc, XLookUpAssoc, XMakeAssoc.

Xlib Reference Manual 133

XDestroylmage \ x,,b-,ma ge s-

Name

XDestroylmage deallocate memory associated with an image.

Synopsis

int XDestroylmage (ximage)
Xlmage * ximage;

Arguments

ximage Specifies a pointer to the image.

Description

XDestroylmage deallocates the memory associated with an Ximage structure. This mem
ory includes both the memory holding the ximage structure, and the memory holding the
actual image data. (If the image data is statically allocated, the pointer to the data in the
Ximage structure must be set to zero before calling XDestroylmage.)

For more information on images, see Volume One, Chapter 6, Drawing Graphics and Text.
Related Commands

ImageByteOrder, XAddPixel, XCreatelmage, XGet Image, XGetPixel, XGet-
Sublmage, XPut Image, XPutPixel, XSub Image.

134 Xlib Reference Manual

-x,, b - Regions / XDestroyRegion

Name

XDestroyRegion deallocate storage associated with a region.

Synopsis

XDestroyRegion ( r)
Region r;

Arguments

r Specifies the region to be destroyed.

Description

XDestroyRegion frees the memory associated with a region and invalidates pointer r.

See Volume One, Chapter 6, Drawing Graphics and Text, for a description of regions.

Related Commands

XClipBox, XCreateRegion, XEmptyRegion, XEqualRegion, Xlntersect-
Region, XOf f setRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion,
XSetRegion, XShrinkRegion, XSubtractRegion, XUnionRectWithRegion,
XUnionRegion, XXorRegion.

Xlib Reference Manual 135

XDestroySubwindows

Xlib - Window Existence

Name

XDestroySubwindows destroy all subwindows of a window.

Synopsis

XDestroySubwindows ( display, w)
Display * display ;
Window w;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

w Specifies the ID of the window whose subwindows are to be destroyed.

Description

This function destroys all descendants of the specified window (recursively), in bottom to top
stacking order.

XDestroySubwindows generates exposure events on window /, if any mapped subwindows
were actually destroyed. This is much more efficient than deleting many subwindows one at a
time, since much of the work need only be performed once for all of the windows rather than
for each window. It also saves multiple exposure events on the windows about to be destroyed.
The subwindows should never again be referenced.

xcioseDisplay automatically destroys all windows that have been created by that client on
the specified display (unless called after a fork system call).

Never call XDestroySubwindows with the window argument set to the root window! This
will destroy all the applications on the screen, and if there is only one screen, often the server
as well.

Errors

BadWindow

Related Commands

XCreateSimpleWindow, XCreateWindow, XDestroyWindow.

136 Xlib Reference Manual

Xlib - Window Existence-

J XDestroyWindow

Name

XDestroyWindow unmap and destroy a window and all subwindows.

Synopsis

XDestroyWindow ( display, window)
Display *display;
Window window;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

window Specifies the ID of the window to be destroyed.

Description

If window is mapped, an UnmapWindow request is performed automatically. The window
and all inferiors (recursively) are then destroyed, and a DestroyNotif y event is generated
for each window. The ordering of the DestroyNotif y events is such that for any given win
dow, DestroyNotif y is generated on all inferiors of the window before being generated on
the window itself. The ordering among siblings and across subhierarchies is not otherwise con
strained.

The windows should never again be referenced.

Destroying a mapped window will generate exposure events on other windows that were
obscured by the windows being destroyed. XDestroyWindow may also generate Enter-
Notify events if window was mapped and contained the pointer.

No windows are destroyed if you try to destroy the root window.

Errors

BadWindow

Related Commands

XCreateSimpleWindow, XCreateWindow, XDestroySubwindows.

Xlib Reference Manual 137

XDisableAccessControl \ X||b _ Host Accass _

Name

XDisableAccessControl allow access from any host.

Synopsis

XDisableAccessControl (display)
Display * display;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

Description

XDisableAccessControl instructs the server to allow access from clients on any host.
This disables use of the host access list.

This routine can only be called from a client running on the same host as the server.

For more information on access control, see Volume One, Chapter 13, Other Programming
Techniques.

Errors

BadAccess

Related Commands

XAddHost, XAddHosts, XEnableAccessControl, XListHosts, XRemoveHost,
XRemoveHosts, XSetAccessControl.

138 Xlib Reference Manual

Xlib - Window Manager Hints-

XDisplayKeycodes

Name

XDisplayKeycodes obtain the range of legal keycodes for a server.

Synopsis

XDisplayKeycodes (display, min_keycodes , max_keycodes)
Display *display;
int *min_keycode r *max_keycode; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

min_keycode Returns the minimum keycode.
max_keycode Returns the maximum keycode.

Description

XDisplayKeycodes returns the min_keycode and max_keycode supported by the
specified server. The minimum keycode returned is never less than 8, and the maximum key-
code returned is never greater than 255. Not all keycodes in this range are required to have cor
responding keys.

For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Related Commands

XKeycodeToKeysym, XKeysymToKeycode, XLookupString.

Xlib Reference Manual 139

XDisplayName \

Xlib- Error Handling-

Name

XDisplayName report the display name (when connection to a display fails).

Synopsis

char *XDisplayName ( string)
char *string;

Arguments

string Specifies the character string.

Description

XDisplayName is normally used to report the name of the display the program attempted to
open with xopenDisplay. This is necessary because X error handling begins only after the
connection to the server succeeds. If a NULL string is specified, XDisplayName looks in the
DISPLAY environment variable and returns the display name that the user was requesting.
Otherwise, XDisplayName returns its own argument. This makes it easier to report to the
user precisely which server the program attempted to connect to.

For more information, see Volume One, Chapter 3, Basic Window Program.
Related Commands

XGetErrorDatabaseText, XGetErrorText, XSetAf terFunction, XSetError-
Handler, XSetlOErrorHandler, XSynchronize.

140 Xlib Reference Manual

Xlib - Drawing Primitives

Name

XDraw draw a polyline or curve between vertex list (from XI ) .
Synopsis

Status XDraw ( display, drawable, gc f vllst, vcount)
Display *dlsplay;
Drawable drawable;
GC gc;

Vertex *vllst;
int vcount ;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

drawable Specifies the drawable.

gc Specifies the graphics context.

vllst Specifies a pointer to the list of vertices that indicates what to draw.

vcount Specifies how many vertices are in vllst.

Description

This function is provided for compatibility with X Version 10. To use it you must include the
file &lt;Xll/X10.h&gt; and link with the library -loldX. Its performance is likely to be low.

XDraw draws an arbitrary polygon or curve. The figure drawn is defined by the specified list of
vertices (vllst). The points are connected by lines as specified in the flags each the Vertex
structure.

The Vertex structure contains an x,y coordinate and a bitmask called flags that specifies
the drawing parameters.

The x and y elements of Vertex are the coordinates of the vertex that are relative to either the
previous vertex (if VertexRelative is 1) or the upper-left inside corner of the drawable (if
VertexRelative is 0). If VertexRelative is the coordinates are said to be absolute.
The first vertex must be an absolute vertex.

If the VertexDontDraw bit is 1, no line or curve is drawn from the previous vertex to this
one. This is analogous to picking up the pen and moving to another place before drawing
another line.

If the VertexCurved bit is 1, a spline algorithm is used to draw a smooth curve from the pre
vious vertex, through this one, to the next vertex. Otherwise, a straight line is drawn from the
previous vertex to this one. It makes sense to set VertexCurved to 1 only if a previous and
next vertex are both defined (either explicitly in the array, or through the definition of a closed
curve see below.)

It is permissible for VertexDontDraw bits and VertexCurved bits to both be 1. This is
useful if you want to define the previous point for the smooth curve, but you do not want an
actual curve drawing to start until this point.

Xlib Reference Manual 14 1

XDraw (continued) Xlib - Drawing Primitives

If VertexStartClosed bit is 1, then this point marks the beginning of a closed curve. This
vertex must be followed later in the array by another vertex whose absolute coordinates are
identical and which has VertexEndClosed bit of 1. The points in between form a cycle for
the purpose of determining predecessor and successor vertices for the spline algorithm.

XDraw achieves the effects of the X10 XDraw, XDrawDashed, and XDrawPatterned
functions.

XDraw uses the following graphics context components: function, plane_mask,
line_width, line_style, cap_style, join_style, fill_style, subwindow_
mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses
these graphics context mode-dependent components: foreground, background, tile,
stipple, ts_x_origin, ts_y_origin, dash_of f set, and dash_list.

A Status of zero is returned on failure, and nonzero on success.

For more information, see Volume One, Appendix B, XI Compatibility.

Structures

typedef struct _Vertex {

short x,y;

unsigned short flags;
} Vertex;

/* defined constants for use as flags */

#define VertexRelative 0x0001 /* else absolute */

#define VertexDontDraw 0x0002 /* else draw */

#define VertexCurved 0x0004 /* else straight */

#define VertexStartClosed 0x0008 /* else not */

#define VertexEndClosed 0x0010 /* else not */

Related Commands

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDrawArc, XDrawArcs,
XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDraw-
Rectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFill-
Polygon, XFillRectangle, XFillRectangles.

Xlib Reference Manual

. . J XDrawArc

Xlib - Drawing Primitives *

Name

XDrawArc draw an arc fitting inside a rectangle.

Synopsis

XDrawArc (display, drawable, gc , x f y, width, height,

anglel , angle2)
Display *display;
Drawable drawable ;
GC gc;
int x r y;

unsigned int width, height;
int anglel, angle2 ;

Arguments

display Specifies a connection to an X server; returned from xopenoi splay.

drawa&le Specifies the drawable.

gc Specifies the graphics context.

x Specify the x and y coordinates of the upper-left corner of the rectangle that

y contains the arc, relative to the origin of the specified drawable.

width Specify the width and height in pixels of the major and minor axes of the arc.

height

anglel Specifies the start of the arc relative to the three-o clock position from the

center. Angles are specified in 64ths of a degree (360 * 64 is a complete
circle).

angle2 Specifies the end of the arc relative to the start of the arc. Angles are speci

fied in 64ths of a degree (360 * 64 is a complete circle).

Description

XDrawArc draws a circular or elliptical arc. An arc is specified by a rectangle and two angles.
The x and y coordinates are relative to the origin of the drawable, and define the upper-left cor
ner of the rectangle. The center of the circle or ellipse is the center of the rectangle, and the
major and minor axes are specified by the width and height, respectively. The angles are
signed integers in 64ths of a degree, with positive values indicating counterclockwise motion
and negative values indicating clockwise motion, truncated to a maximum of 360 degrees. The
start of the arc is specified by anglel relative to the three-o clock position from the center,
and the path and extent of the arc is specified by angle2 relative to the start of the arc.

By specifying one axis to be zero, a horizontal or vertical line is drawn (inefficiently).

Angles are computed based solely on the coordinate system and ignore the aspect ratio. In
other words, if the bounding rectangle of the arc is not square and anglel is zero and
angle2 is (45x64), a point drawn from the center of the bounding box through the endpoint
of the arc will not pass through the corner of the rectangle.

Xlib Reference Manual 143

XDrawArc

(continued)

Xlib - Drawing Primitives

For any given arc, no pixel is drawn more than once, even if angle2 is greater than anglel
by more than 360 degrees.

XDrawArc uses these graphics context components: function, plane_mask,
line_width, line_style, cap_style, join_style, f ill_style, subwindow_
mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses
these graphics context mode-dependent components: foreground, background, tile,
stipple, ts_x_origin, ts_y_origin, dash_of f set, and dash_list.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text,

width

6 o clock

Angle = 270x64=17280
Angle = -( 90x64 ) =5760

12 o clock

(x,y) v Angle = 90x64

\ Angle = - (270x64)

X -4(&lt;A2

A1 r "**--. %

9 o clock

/ }

Angle = 180x64

__,-

Angle = - (180x64)

,. K^_

81 ,--

Center of bounding
rectangle.

3 o clock

Angle =

Example 1:

Arc from A1 to A2, Counterclockwise

A1 = 90 X 64

A2 = 45 X 64

Example 2:

Arc from B1 to B2, Clockwise

B1 = 270 X 64

B2 = -(45X64)

Errors

BadDrawable

BadGC

BadMatch

144

Xlib Reference Manual

Xlib - Drawing Primitives (continued) XDrawArc

Related Commands

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArcs,
XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDraw-
Rectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFill-
Polygon, XFillRectangle, XFillRectangles.

Xlib Reference Manual 145

XDrawArcs

Xlib - Drawing Primitives-

Name

XDrawArcs draw multiple arcs.

Synopsis

XDrawArcs ( display, drawable ,
Display * display ;
Drawable drawable;
GC gc;
XArc *arcs;
int r&gt;arcs;

gc, arcs, narcs)

Arguments

di spl ay

drawable

arcs

narcs

Specifies a connection to an X server; returned from XOpenDisplay.
Specifies the drawable.
Specifies the graphics context.
Specifies a pointer to an array of arcs.
Specifies the number of arcs in the array.

width

6 o clock

Angle = 270x64=17280
Angle = - (90x64)=5760

Example 1 :

Arc from A1 to A2, Counterclockwise

A1 = 90 X 64

A2 = 45 X 64

12 o clock

(x,y) v Angle = 90x64
\ Angle = -(270x64)

height

9 o clock

Angle = 180x64
Angle = -(180x64)

*^Jf 2

A1 "" *--,,

^ s """*-- - -.

Center of bounding
rectangle.

3 o clock

Angle =

Example 2:

Arc from 81 to B2, Clockwise

B1 = 270 X 64

B2 = -(45X64)

146

Xlib Reference Manual

Xlib - Drawing Primitives (continued) XDrawArcs

Description

This is the plural version of XDrawArc. See XDrawArc for details of drawing a single arc.

There is a limit to the number of arcs that can be drawn in a single call. It varies according to
the server. To determine how many arcs you can draw in a single call, find out your server s
maximum request size using XMaxRequestSize. Subtract 3 and divide by three: this is the
maximum number of arcs you can draw in a single XDrawArcs call.

The arcs are drawn in the order listed in the arcs array.

By specifying one axis to be zero, a horizontal or vertical line can be drawn. Angles are com
puted based solely on the coordinate system, ignoring the aspect ratio.

For any given arc, no pixel is drawn more than once. If the last point in one arc coincides with
the first point in the following arc, the two arcs will join correctly. If the first point in the first
arc coincides with the last point in the last arc, the two arcs will join correctly. If two arcs join
correctly and if line_width is greater than and the arcs intersect, no pixel is drawn more
than once. Otherwise, the intersecting pixels of intersecting arcs are drawn multiple times.
Specifying an arc with one endpoint and a clockwise extent draws the same pixels as specifying
the other endpoint and an equivalent counterclockwise extent, except as it affects joins.

XDrawArcs uses these graphics context components: function, plane_mask,
line_width, line_style, cap_style, join_style, fill_style, subwindow_
mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses
these graphics context mode-dependent components: foreground, background, tile,
stipple, ts_x_origin, ts_y_origin, dash_of f set, and dash_list.

The following is a technical explanation of the points drawn by XDrawArcs. For an arc speci
fied as [x, y, width, height, anglel, angle2 ] , the origin of the major and minor axes is
at [x+ (width/2 ) , y+ (height 12 ) ] , and the infinitely thin path describing the entire circle
or ellipse intersects the horizontal axis at [x, y+ (height /2) ] and [x+width,
y+ (height/2) ] and intersects the vertical axis at [x+ (width/2) ,y] and
[x+ (width/2) , y+height] . These coordinates can be fractional. That is, they are not
truncated to discrete coordinates. The path should be defined by the ideal mathematical path.
For a wide line with line width line_width, the bounding outlines for filling are given by
the infinitely thin paths describing the arcs:

[x+dx/2, y+dy/2, width-dx, height-dy, anglel, angle2]

and

[x-line_width/2, y-line_width/2, width+line_width, height+line_width,
anglel, angle2]

where

dx=min(line_width, width)
dy=min(line width, height)

Xlib Reference Manual 147

XDraw Arcs (continued) Xlib - Drawing Primitives

If (height ! = width) the angles must be specified in the effectively skewed coordinate
system of the ellipse (for a circle, the angles and coordinate systems are identical). The rela
tionship between these angles and angles expressed in the normal coordinate system of the
screen (as measured with a protractor) is as follows:

skewed-angle = atan (tan (normal-angle) * width/height) + adjust

The skewed-angle and normal-angle are expressed in radians (rather than in 64ths of a degree)
in the range [0,2*PI], and where atan returns a value in the range [-PI/2, PI/2] ,and
where adjust is:

for normal-angle in the range [0,PI/2]

PI for normal-angle in the range [PI/2, (3*PI) /2]

2*PI for normal-angle in the range [ (3*PI) /2, 2*PI]

For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures

typedef struct {

short x, y;

unsigned short width, height;

short anglel, angle2; /* Start and end of arc, in */

/* 64ths of degrees */
} XArc;

Errors

BadDrawable

BadGC

BadMatch

Related Commands

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc,
XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDraw-
Rectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFill-
Polygon, XFillRectangle, XFillRectangles.

148 Xlib Reference Manual

-Xlib - Drawing Primmv.s / XDrawFilted

Name

XDrawFilled draw a filled polygon or curve from vertex list (from X10 ) .

Synopsis

Status XDrawFilled (display, drawable, gc, vlist, vcount)
Display *display;
Drawable drawable ;
GC gc;

Vertex *vlist;
int vcount ;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

dra wabl e Specifies the drawable.

gc Specifies the graphics context.

vl i s t Specifies a pointer to the list of vertices.

vcount Specifies how many vertices are in v 1 i s t .

Description

This function is provided for compatibility with X Version 10. To use it you must include the
file &lt;XlllX10.h&gt; and link with the library -loldX. XDrawFilled achieves the effects of the
X Version 10 XDrawTiled and XDrawFilled functions.

XDrawFilled draws arbitrary polygons or curves, according to the same rules as XDraw, and
then fills them.

XDrawFilled uses the following graphics context components: function, plane_mask,
line_width, line_style, cap_style, join_style, fill_style,
subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function
also uses these graphics context mode-dependent components: foreground, background,
tile, stipple, ts_x_origin, ts_y_origin, dash_offset, dash_list,
f ill_style and f ill_rule.

XDrawFilled returns a Status of zero on failure, and nonzero on success.
For more information, see Volume One, Appendix B,X10 Compatibility.

Related Commands

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc,
XDrawArcs, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDraw-
Rectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFill-
Polygon, XFillRectangle, XFillRectangles.

Xlib Reference Manual 149

XDrawlmageString \

Xlib- Text-

Name

XDrawlmageString draw 8-bit image text characters.

Synopsis

XDrawlmageString ( display, drawable , gc , x, y, string, length)
Display *display;
Drawable drawable ;
GC gc;
int x f y;
char *string;
int length;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

drawable Specifies the drawable.

gc Specifies the graphics context.

x Specify the x and y coordinates of the baseline starting position for the image

y text character, relative to the origin of the specified drawable.

string Specifies the character string.

length Specifies the number of characters in the s t ri n g argument.

Description

XDrawlmageString draws a string, but unlike XDrawString it draws both the foreground
and the background of the characters. It draws the characters in the foreground and fills the
bounding box with the background.

XDrawlmageString uses these graphics context components: plane_mask, fore
ground, background, font, subwindow_mode, clip_x_origin, clip_y_
origin, and clip_mask. The function and f ill_style defined in gc are ignored;
the effective function is GXcopy and the effective f ill_style is FillSolid.

XDrawlmageString first fills a destination rectangle with the background pixel defined
in gc, and then paints the text with the foreground pixel. The upper-left corner of the filled
rectangle is at [x, y - font_ascent], the width is overall-&gt;width and the height is
ascent + descent, where overall-&gt;width, ascent, and descent are as would be
returned by XQueryTextExtents using gc and string.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5,
The Graphics Context.

Errors

BadDrawable

BadGC

BadMatch

150 Xlib Reference Manual

xiib - Text (continued) XDrawlmageString

Related Commands

XDrawImageStringlS, XDrawString, XDrawStringl6, XDrawText, XDraw-
Textl6, XQueryTextExtents, XQueryTextExtentsl6, XTextExtents, XText-
Extentsl6,XTextWidth,XTextWidthl6.

Xlib Reference Manual 151

XDrawlmageStri ng1 6 \

Xlib-Text

Name

XDrawImageStringl6 draw 16-bit image text characters.

Synopsis

XDrawImageStringl 6 (display, drawable, gc , x, y, string, length)
Display * display;
Drawable drawable;
GC gc;
int x r y;
XChar2b *string;
int length;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

drawable Specifies the drawable.

gc Specifies the graphics context.

x Specify the x and y coordinates of the baseline starting position for the image

y text character, relative to the origin of the specified drawable.

string Specifies the character string.

length Specifies the number of characters in the string argument.

Description

XDrawlmageStringl6 draws a string, but unlike XDrawStringl6 it draws both the fore
ground and the background of the characters. It draws the characters in the foreground and fills
the bounding box with the background.

XDrawlmageStringl6 uses these graphics context components: plane_mask, fore
ground, background, font, subwindow_mode, clip_x_origin, clip_y_
origin, and clip_mask. The function and f ill_style defined in gc are ignored;
the effective function is GXcopy and the effective f ill_style is FillSolid.

XDrawlmageStringlG first fills a destination rectangle with the background pixel
defined in gc, and then paints the text with the foreground pixel. The upper-left corner of
the filled rectangle is at [x, y - font_ascent], the width is overall-&gt;width and the
height is ascent + descent, where overall-&gt;width, ascent, and descent are as
would be returned by XQueryTextExtentslG using gc and string.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5,
The Graphics Context.

Structures

typedef struct {

unsigned char bytel;

unsigned char byte2;
} XChar2b;

152 Xlib Reference Manual

- Text (continued) XDrawlmageStringl 6

Errors

BadDrawable

BadGC

BadMatch

Related Commands

XDrawImageString,XDrawString,XDrawStringl6,XDrawText,XDrawTextl6 :

XQueryTextExtents,XQueryTextExtentsl6,XTextExtents,XText-

Extentsl6,XTextWidth,XTextWidthl6.

Xlib Reference Manual 153

XDrawLine \ _ Xllb _ Drawlng Pr|m|tives _

Name

XDrawLine draw a line between two points.

Synopsis

XDrawLine ( display, drawable, gc, xl , yl , x2 , y2)
Display * display;
Drawable dravrable;
GC gc;
int xl r yl r x2, y2 ;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

dra wabl e Specifies the drawable.

gc Specifies the graphics context.

xl Specify the coordinates of the endpoints of the line relative to the drawable

yl origin. XLine connects point (xl , yl) to point (x2, y2).

Description

XDrawLine uses the components of the specified graphics context to draw a line between two
points in the specified drawable. No pixel is drawn more than once.

XDrawLine uses these graphics context components: function, plane_mask,
line_width, line_style, cap_style, fill_style, subwindow_mode, clip_
x_origin, clip_y_origin, and clip_mask. XDrawLine also uses these graphics con
text mode-dependent components: foreground, background, tile, stipple,
ts_x_origin, ts_y_origin, dash_of f set, and dash_list.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5,
The Graphics Context.

Errors

BadDrawable Specified drawable is invalid.

BadGC Specified GC is invalid, or does not match the depth of drawable.

BadMatch Specified drawable is an inputOnly window.

Related Commands

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc,
XDrawArcs, XDrawFilled, XDrawLines, XDrawPoint, XDrawPoints, XDraw-
Rectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFill-
Polygon, XFillRectangle, XFillRectangles.

154 Xlib Reference Manual

-X..b - Drawing Primitives - /

Name

XDrawLines draw multiple connected lines.

Synopsis

XDrawLines ( display, drawable, gc , points, npoints, mode)
Display *display;
Drawable drawable;
GC gc;

XPoint *points;
int npoints;
int mode ;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

drawable Specifies the drawable.

gc Specifies the graphics context.

point s Specifies a pointer to an array of points.

npoints Specifies the number of points in the array.

mode Specifies the coordinate mode. Pass either CoordModeOrigin or Coord-

ModePrevious.

Description

XDrawLines draws a series of lines joined end-to-end.

It draws lines connecting each point in the list (points array) to the next point in the list. The
lines are drawn in the order listed in the points array. For any given line, no pixel is drawn
more than once. If thin (zero line width) lines intersect, pixels will be drawn multiple times. If
the first and last points coincide, the first and last lines will join correctly. If wide lines inter
sect, the intersecting pixels are drawn only once, as though the entire multiline request were a
single filled shape.

There is a limit to the number of lines that can be drawn in a single call, that varies according to
the server. To determine how many lines you can draw in a single call, you find out your
server s maximum request size using XMaxRequestSize. Subtract 3 and divide by two, and
this is the maximum number of lines you can draw in a single XDrawLines call.

The mode argument may have two values:

CoordModeOrigin indicates that all points are relative to the drawable s origin.

CoordModePrevious indicates that all points after the first are relative to the previ
ous point. (The first point is always relative to the drawable s origin.)

XDrawLines uses the following components of the specified graphics context to draw multi
ple connected lines in the specified drawable: function, plane_mask, line_width,
line_style, cap_style, join_style, fill_style, subwindow_mode,

Xlib Reference Manual 155

XDrawLlnes (continued) Xlib - Drawing Primitives

clip_x_origin, clip_y_ origin, and clip_mask. This function also uses these
graphics context mode-dependent components: foreground, background, tile,
stipple, ts_x_origin, ts_y_origin, dash_of f set, and dash_list.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5,
The Graphics Context.

Structures

typedef struct {
short x, y;
} XPoint;

Errors

BadDrawable Specified drawable is invalid.

BadGC Specified GC is invalid, or does not match the depth of drawable.

BadMatch Specified drawable is an InputOnly window.
BadValue Invalid coordinate_mode.

Related Commands

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc,
XDrawArcs, XDrawFilled, XDrawLine, XDrawPoint, XDrawPoints, XDraw-
Rectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFill-
Polygon, XFillRectangle, XFillRectangles.

156 Xlib Reference Manual

-X,,b - Drawing Primitives / XDrawPoint

Name

XDrawPoint draw a point.

Synopsis

XDrawPoint ( display, drawable, gc , x r y)
Display *display;
Drawable drawable;
GC gc;
int x r y;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

drawable Specifies the drawable.

gc Specifies the graphics context.

x Specify the x and y coordinates of the point, relative to the origin of the draw-

y able.

Description

XDrawPoint draws a single point into the specified drawable. XDrawPoint uses these
graphics context components: function, plane_mask, foreground, subwin-
dow_mode, clip_x_origin, clip_y_origin, and clip_mask. Use XDrawPoints
to draw multiple points.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5,
The Graphics Context.

Errors

BadDrawable

BadGC

BadMatch

Related Commands

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc,
XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoints, XDraw-
Rectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFill-
Polygon, XFillRectangle, XFillRectangles.

Xlib Reference Manual 157

XDrawPoints \ Xllb _ Drawing Pr|m|tives _

Name

XDrawPoints draw multiple points.

Synopsis

XDrawPoints ( display, drawable, gc , points, npoints, mode)
Display ^display;
Drawable drawable;
GC gc;

XPoint *points;
int npoints;
int mode ;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

dra wabl e Specifies the drawable.

gc Specifies the graphics context.

points Specifies a pointer to an array of XPoint structures containing the positions

of the points.

npoints Specifies the number of points to be drawn.

mode Specifies the coordinate mode. CoordModeOrigin treats all coordinates as

relative to the origin, while CoordModePrevious treats all coordinates
after the first as relative to the previous point, while the first is still relative to
the origin.

Description

XDrawPoints draws one or more points into the specified drawable.

There is a limit to the number of points that can be drawn in a single call, that varies according
to the server. To determine how many points you can draw in a single call, you find out your
server s maximum request size using XMaxRequestSize. Subtract 3 and this is the maxi
mum number of points you can draw in a single XDrawPoints call.

XDrawPoints uses these graphics context components: function, plane_mask, fore
ground, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5,
The Graphics Context.

Structures

typedef struct {
short x, y;
} XPoint;

758 Xlib Reference Manual

Xlib - Drawing Primitives (continued) XDrawPointS

Errors

BadDrawable
BadGC
BadMatch
BadValue

Related Commands

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc,
XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPointS, XDraw-
Rectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFill-
Polygon, XFillRectangle, XFillRectangles.

Xlib Reference Manual 159

XDrawRectangle

Xllb - Drawing Primitives

Name

XDrawRectangle draw an outline of a rectangle.

Synopsis

XDrawRectangle (display, drawable, gc, x, y, width, height)
Display * display;
Drawable drawable;
GC gc;
int x r y;
unsigned int width, height;

Arguments

di spl ay

drawable

width
height

Specifies a connection to an X server; returned from XOpenDisplay.
Specifies the drawable.
Specifies the graphics context.

Specify the x and y coordinates of the upper-left corner of the rectangle, rela
tive to the drawable s origin.

Specify the width and height in pixels. These dimensions define the outline
of the rectangle.

20 pixels

Description

XDrawRectangle draws the outline of the rectangle by using the x and y coordinates,
width and height, and graphics context you specify. Specifically, XDrawRectangle uses
these graphics context components: function, plane_mask, line_width,
line_style, cap_style, join_style, fill_style, subwindow_mode, clip_
x_origin, clip_y_origin, and clip_mask. This function also uses these graphics con
text mode-dependent components: foreground, background, tile, stipple,
ts_x_origin, ts_y_origin, dash_of f set, and dash_list.

For the specified rectangle, no pixel is drawn more than once.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5,
The Graphics Context.

160

Xlib Reference Manual

Xlib - Drawing Primitives (continued) X Draw Rectangle

Structure

typedef struct {

short x, y;

unsigned short width, height;
} XRectangle;

Errors

BadDrawable

BadGC

BadMatch

Related Commands

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc,
XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints,
XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFillPolygon,
XFillRectangle, XFillRectangles.

Xlib Reference Manual 16 1

XDrawRectangles

Xlib - Drawing Primitives-

Name

XDrawRectangles draw the outlines of multiple rectangles.

Synopsis

XDrawRectangles (display, drawable, gc , rectangles, nrectangles)
Display *display;
Drawable drawa&le;
GC gc;

XRectangle rectangles [] ;
int nrectangles;

Arguments

di spl ay Specifies a connection to an X server; returned from xopenD isplay.

dra wabl e Specifies the drawable.

gc Specifies the graphics context.

rectangles Specifies a pointer to an array of rectangles containing position and size
information.

nrectangles Specifies the number of rectangles in the array.

20 pixels

Description

XDrawRectangles draws the outlines of the specified rectangles by using the position and
size values in the array of rectangles. The x and y coordinates of each rectangle are relative to
the drawable s origin, and define the upper-left corner of the rectangle.

The rectangles are drawn in the order listed. For any given rectangle, no pixel is drawn more
than once. If rectangles intersect, pixels are drawn multiple times.

There is a limit to the number of rectangles that can be drawn in a single call. It varies accord
ing to the server. To determine how many rectangles you can draw in a single call, find out
your server s maximum request size using XMaxRequestSize. Subtract 3 and divide by
two. This is the maximum number of rectangles you can draw in a single XDraw
Rectangles call.

This function uses these graphics context components: function, plane_mask,
line_width, line_style, cap_style, join_style, fill_style, subwin-
dow_mode, clip_x_origin, clip_y_origin, and clip_mask. XDrawRectangles

162

Xlib Reference Manual

Xlib - Drawing Primitives (continued) XDrawRectangles

also uses these graphics context mode-dependent components: foreground, background,
tile, stipple, ts_x_origin, ts_y_origin, dash_of f set, and dash_list.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5,
The Graphics Context.

Structures

typedef struct {

short x, y;

unsigned short width, height;
} XRectangle;

Errors

BadDrawable

BadGC

BadMatch

Related Commands

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc,
XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints,
XDrawRectangle, XDrawSegments, XFillArc, XFillArcs, XFillPolygon,
XFillRectangle, XFillRectangles.

Xlib Reference Manual 163

XDrawSegments \

Xlib - Drawing Primitives-

Name

XDrawSegments draw multiple disjoint lines.

Synopsis

XDrawSegments ( display, drawable, gc, segments, nsegments)
Display *display;
Drawable drawable;
GC gc;

XSegment * segments;
int nsegments;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

drawable Specifies the drawable.

gc Specifies the graphics context.

segments Specifies a pointer to an array of line segments.

nse gmen ts Specifies the number of segments in the array.

Description

XDrawSegments draws multiple line segments into the specified drawable. Each line is
specified by a pair of points, so the line may be connected or disjoint.

For each segment, XDrawSegments draws a line between (xl, yl) and (x2, y2). The
lines are drawn in the order listed in segments. For any given line, no pixel is drawn more
than once. If lines intersect, pixels will be drawn multiple times. The lines will be drawn sepa
rately, without regard to the join_style.

There is a limit to the number of segments that can be drawn in a single call. It varies accord
ing to the server. To determine how many segments you can draw in a single call, find out your
server s maximum request size using XMaxRequestSize. Subtract 3 and divide by two.
This is the maximum number of segments you can draw in a single XDrawSegments call.

XDrawSegments uses these graphics context components: function, plane_mask,
line_width, line_style, cap_style, fill_style, subwindow__mode, clip_
x_origin, clip_y_origin, and clip_mask. XDrawSegments also uses these graph
ics context mode-dependent components: foreground, background, tile, stipple,
ts_x_origin, ts_y_origin, dash_of f set, and dash_list.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5,
The Graphics Context.

Structures

typedef struct {

short xl, yl, x2, y2;
} XSegment;

164 Xlib Reference Manual

Xlib - Drawing Primitives (continued) XDrawSegmentS

Errors

BadDrawable Specified drawable is invalid.

BadGC Specified GC is invalid, or does not match the depth of drawable.

BadMatch Specified drawable is an InputOnly window.

Related Commands

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc,
XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints,
XDrawRectangle, XDrawRectangles, XFillArc, XFillArcs, XFillPolygon,
XFillRectangle, XFillRectangles.

Xlib Reference Manual 165

XDrawString \

Xlib-Text

Name

XDrawString draw an 8-bit text string, foreground only.

Synopsis

XDrawString ( display, drawable , gc , x, y, string, length)
Display *display;
Drawable drawable ;
GC gc;
int x, y;
char *string;
int length;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

dr a wai&gt;l e Specifies the drawable.

gc Specifies the graphics context.

x Specify the x and y coordinates of the baseline starting position for the char-

y acter, relative to the origin of the specified drawable.

string Specifies the character string.

length Specifies the number of characters in s t ri n g.

Description

XDrawString draws the given string into a drawable using the foreground only to draw
set bits in the font. It does not affect any other pixels in the bounding box for each character.

The y coordinate defines the baseline row of pixels while the x coordinate is the point from
which Ibearing, rbearing, and width are measured.

XDrawString uses these graphics context components: function, plane_mask,
fill_style, font, subwindow_mode, clip_x_origin, clip_y_origin, and
clip_mask. This function also uses these graphics context mode-dependent components:
foreground, tile, stipple, ts_x_origin, and ts_y_origin. Each character
image, as defined by the font in gc, is treated as an additional mask for a fill operation on the
drawable.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5,
The Graphics Context.

Errors

BadDrawable
BadFont
BadGC
BadMatch

166 Xlib Reference Manual

Xiib-Text (continued) XDrawString

Related Commands

XDrawImageString, XDrawImageStringl6, XDrawStringl6, XDrawText,
XDrawTextl6, XQueryTextExtents, XQueryTextExtentslG, XTextExtents,
XTextExtentsl6, XTextWidth, XTextWidthlG.

Xlib Reference Manual 167

XDrawString16 , xnb _ Text _

Name

XDrawStringl 6 draw two-byte text strings.

Synopsis

XDrawStringl 6 (display, drawable, gc , x, y f string, length)
Display * display;
Drawable drawable;
GC gc ;
int x, y;
XChar2b *string;
int length;

Arguments

di splay Specifies a connection to an X server; returned from XOpenDisplay.

draw-able Specifies the drawable.

gc Specifies the graphics context.

x Specify the x and y coordinates of the baseline starting position for the char-

y acter, relative to the origin of the specified drawable.

string Specifies the character string. Characters are two bytes wide.

length Specifies the number of characters in string.

Description

XDrawStringl 6 draws a string in the foreground pixel value without drawing the surround
ing pixels.

The y coordinate defines the baseline row of pixels while the x coordinate is the point from
which Ibearing, rbearing, and width are measured. For more information on text
placement, see Volume One, Chapter 6, Drawing Graphics and Text.

XDrawStringl 6 uses these graphics context components: function, plane_mask,
fill_style, font, subwindow_mode, clip_x_origin, clip_y_origin, and
clip_mask. This function also uses these graphics context mode-dependent components:
foreground, tile, stipple, ts_x_origin, and ts_y_origin. Each character
image, as defined by the font in gc, is treated as an additional mask for a fill operation on the
drawable.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5,
The Graphics Context.

Structures

typedef struct {

unsigned char bytel;

unsigned char byte2;
} XChar2b;

Xlib Reference Manual

Xiib-Text (continued) XDrawString16

Errors

BadDrawable
BadFont
BadGC
BadMatch

Related Commands

XDrawImageString, XDrawImageStringlG, XDrawString, XDrawText, XDraw-
Textl6,XQueryTextExtents,XQueryTextExtentsl6,XTextExtents,XText-
Extentsl6,XTextWidth, XTextWidthl6.

Xlib Reference Manual

XDrawText \ X ,ib-Tex-

Name

XDrawText draw 8-bit polytext strings.

Synopsis

XDrawText ( display, drawable, gc , x, y, Items, nltems)
Display *dlsplay;
Drawable drawable;
GC gc ;
int x, y;
XTextltem * Items;
int nltems;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

drawable Specifies the drawable.

gc Specifies the graphics context.

x Specify the x and y coordinates of the baseline starting position for the initial

y string, relative to the origin of the specified drawable.

i t ems Specifies a pointer to an array of text items.

nl terns Specifies the number of text items in the Items array.

Description

XDrawText is capable of drawing multiple strings on the same horizontal line and changing
fonts between strings. Each XTextltem structure contains a string, the number of characters
in the string, the delta offset from the starting position for the string, and the font. Each text
item is processed in turn. The font in each XTextltem is stored in the specified GC and used
for subsequent text. If the XTextltem. font is None, the font in the GC is used for drawing
and is not changed. Switching between fonts with different drawing directions is permitted.

The delta in each XTextltem specifies the change in horizontal position before the string is
drawn. The delta is always added to the character origin and is not dependent on the draw
direction of the font. For example, if x = 40, y = 20, and items [0] .delta = 8, the
string specified by items [0] .chars would be drawn starting at x = 48, y = 20. The
delta for the second string begins at the rbearing of the last character in the first string. A
negative delta would tend to overlay subsequent strings on the end of the previous string.

Only the pixels selected in the font are drawn (the background member of the GC is not used
to fill the bounding box).

There is a limit to the number and size of strings that can be drawn in a single call, that varies
according to the server. To determine how much text you can draw in a single call, you find out
your server s maximum request size using XMaxRequestSize. Subtract four, and then sub
tract ( (strlen (string) +2) / 4) for each string. This is the maximum amount of
text you can draw in a single XDrawText call.

1 70 Xlib Reference Manual

Xlib-Text (continued) XDrawText

XDrawText uses the following elements in the specified GC: function, plane_mask,
fill_style, font, subwindow_mode, clip_x_origin, clip_y_origin, and
clip_mask. This function also uses these graphics context mode-dependent components:
foreground, tile, stipple, ts_x_origin, and ts_y_origin.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5,
The Graphics Context.

Structures

typedef struct {

char *chars; /* pointer to string */

int nchars; /* number of characters */

int delta; /* delta between strings */

Font font; /* font to print it in, None don t change */

} XTextltem;

Errors

BadDrawable
BadFont
BadGC
BadMatch

Related Commands

XDrawImageString, XDrawImageStringl6, XDrawString, XDrawStringlS,
XDrawTextlS, XQueryTextExtents, XQueryTextExtentslS, XTextExtents,
XTextExtentsl6, XTextWidth, XTextWidthlG.

Xlib Reference Manual 1 71

XDrawText16 \ X|ib Tex( _

Name

XDrawTextl6 draw 16-bit poly text strings.

Synopsis

XD r a wTextlS ( display, drawable, gc, x, y, items, nitems)
Display * display ;
Drawable drawable;
GC gc;
int x r y;

XTextIteml6 * items;
int nitems;

Arguments

display Specifies a connection to an X server; returned from xopenDisplay.

drawable Specifies the drawable.

gc Specifies the graphics context.

x Specify the x and y coordinates of the baseline starting position for the initial

y string, relative to the origin of the specified drawable.

items Specifies a pointer to an array of text items using two-byte characters,

nit ems Specifies the number of text items in the array.

Description

XDrawTextlG is capable of drawing multiple strings on the same horizontal line and chang
ing fonts between strings. Each XTextltem structure contains a string, the number of charac
ters in the string, the delta offset from the starting position for the string, and the font. Each
text item is processed in turn. The font in each XTextltem is stored in the specified GC and
used for subsequent text. If the XTextIteml6 . font is None, the font in the GC is used for
drawing and is not changed. Switching between fonts with different drawing directions is per
mitted.

The delta in each XTextltem specifies the change in horizontal position before the string is
drawn. The delta is always added to the character origin and is not dependent on the drawing
direction of the font. For example, if x = 40,y = 20, and items [0] .delta = 8, the
string specified by items [0] .chars would be drawn starting at x = 48, y = 20. The
delta for the second string begins at the rbearing of the last character in the first string. A
negative delta would tend to overlay subsequent strings on the end of the previous string.

Only the pixels selected in the font are drawn (the background member of the GC is not used
to fill the bounding box).

1 72 Xlib Reference Manual

Xlib - Text

(continued)

XDrawText16

XDrawText 16 uses the following elements in the specified GC: function, plane_mask,
fill_style, font, subwindow_mode, clip_x_origin, clip_y_origin, and
clip_mask. This function also uses these graphics context mode-dependent components:
foreground, tile, stipple, ts_x_origin, and ts_y_origin.

Note that the chars member of the XText Iteml 6 structure is of type XChar2b, rather than
of type char as it is in the XText Item structure. For fonts defined with linear indexing
rather than two-byte matrix indexing, the X server will interpret each member of the XChar2b
structure as a 16-bit number that has been transmitted most significant byte first. In other
words, the bytel member of the XChar2b structure is taken as the most significant byte.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5,
The Graphics Context.

/* 2 byte characters */

/* number of characters */

/* delta between strings */

/* font to print it in, None don t change

/* normal 16 bit characters are two bytes */

Structures

typedef struct {

XChar2b *chars;
int nchars;
int delta;

Font font;
} XTextltemlG;

typedef struct {

unsigned char bytel;

unsigned char byte2;
} XChar2b;

Errors

BadDrawable
BadFont
BadGC
BadMatch

Related Commands

XDrawImageString, XDrawImageStringl6, XDrawString, XDrawStringl6,
XDrawText, XQueryTextExtents, XQueryTextExtentsl6, XTextExtents,
XTextExtentslG, XTextWidth, XTextWidthl6.

Xlib Reference Manual

173

XEmptyRegion \

-Xlib- Regions-

Name

XEmptyRegion determine if a region is empty.

Synopsis

Bool XEmptyRegion ( r)
Region r;

Arguments

r Specifies the region to be checked.

Description

XEmptyRegion will return True if the specified region is empty, or False otherwise.

Structures

Region is a pointer to an opaque structure type.

Related Commands

XClipBox, XCreateRegion, XDestroyRegion, XEqualRegion, Xlntersect-
Region, XOf f setRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion,
XSetRegion, XShrinkRegion, XSubtractRegion, XUnionRectWithRegion,
XUnionRegion, XXorRegion.

174 Xlib Reference Manual

-x,,b - HO, Access / XEnableAccessControl

Name

XEnableAccessControl use access control list to allow or deny connection requests.

Synopsis

XEnableAccessControl (display)
Display * display ;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

Description

XEnableAccessControl instructs the server to use the host access list to determine
whether access should be granted to clients seeking a connection with the server.

By default, the host access list is used. If access has not been disabled with XDisable-
AccessControl or XSetAccessControl, this routine does nothing.

This routine can only be called by clients running on the same host as the server.
For more information, see Volume One, Chapter 13, Other Programming Techniques.

Errors

BadAccess

Related Commands

XAddHost, XAddHosts, XDisableAccessControl, XListHosts, XRemoveHost,
XRemoveHosts, XSetAccessControl.

Xlib Reference Manual 1 75

XEqualRegion

Xlib - Regions-
Name

XEqualRegion determine if two regions have the same size, offset, and shape.

Synopsis

Bool XEqualRegion (rl, r2)
Region rl , r2 ;

Arguments

rl Specify the two regions you want to compare.

Description

XEqualRegion returns True if the two regions are identical; i.e., they have the same offset,
size and shape, or False otherwise.

Regions are located using an offset from a point (the region origin) which is common to all
regions. It is up to the application to interpret the location of the region relative to a drawable.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text.

Structures

Region is a pointer to an opaque structure type.

Related Commands

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, Xlntersect-
Region, XOf f setRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion,
XSetRegion, XShrinkRegion, XSubtractRegion, XUnionRectWithRegion,
XUnionRegion, XXorRegion.

176 Xlib Reference Manual

-Xlib - Resource Manager /

Name

XEventsQueued check the number of events in the event queue.

Synopsis

int XEventsQueued ( display, mode)
Display * display;
int mode ;

Arguments

display Specifies a connection to a Display structure, returned from XOpen-

Display.

mode Specifies whether the request buffer is flushed if there are no events in Xlib s

queue. You can specify one of these constants: QueuedAl ready,
QueuedAfterFlush, QueuedAfterReading.

Description

XEventsQueued checks whether events are queued. If there are events in Xlib s queue, the
routine returns immediately to the calling routine. Its return value is the number of events
regardless of mode.

mode specifies what happens if no events are found on Xlib s queue.

If mode is QueuedAlready, and there are no events in the queue, XEvents
Queued returns zero (it does not flush the request buffer or attempt to read more
events from the connection).

If mode is QueuedAfterFlush, and there are no events in the queue, XEvents
Queued flushes the request buffer, attempts to read more events out of the applica
tion s connection, and returns the number read.

If mode is QueuedAfterReading, and there are no events in the queue,
XEventsQueued attempts to read more events out of the application s connection
without flushing the request buffer and returns the number read.

Note that XEventsQueued always returns immediately without I/O if there are events
already in the queue.

XEventsQueued with mode QueuedAfterFlush is identical in behavior to XPending.
XEventsQueued with mode QueuedAlready is identical to the QLength macro (see
Appendix C, Macros).

For more information, see Volume One, Chapter 8, Events.
Related Commands

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped-
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XGetlnputFocus,
XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeek-
If Event, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSetlnput-
Focus, XSynchronize, XWindowEvent.

Xlib Reference Manual 1 77

XFetchBuffer "\

Xlib -Cut Buffers

Name

XFetchBuffer return data from a cut buffer.

Synopsis

char *XFetchBuffer (display, nbytes , buffer)
Display * display ;

int * nbytes; /* RETURN */
int buffer;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

nbytes Returns the number of bytes in buffer returned by XFetchBuffer. If

there is no data in the buffer, * nbytes is set to 0.

buffer Specifies which buffer you want data from. Specify an integer from to 7

inclusive.

Description

XFetchBuffer returns data from one of the 8 buffers provided for interclient communica
tion. If the buffer contains data, XFetchBuffer returns the number of bytes in nbytes,
otherwise it returns NULL and sets *nbytes to 0. The appropriate amount of storage is allo
cated and the pointer returned; the client must free this storage when finished with it by calling
XFree. Note that the cut buffer does not necessarily contain text, so it may contain embedded
null bytes and may not terminate with a null byte.

Selections are preferred over cut buffers as a communication scheme.

For more information on cut buffers, see Volume One, Chapter 13, Other Programming Tech
niques.

Errors

BadValue buffer not an integer between and 7 inclusive.

Related Commands

XFetchBytes, XRotateBuf f ers, XStoreBuf f er, XStoreBytes.

1 78 Xlib Reference Manual

Xlib -Cut Buffers-

J XFetch Bytes

Name

XFetchBytes return data from cut buffer 0.

Synopsis

char *XFetchBytes ( display, nbytes)
Display ^display;
int * nbytes; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

nbytes Returns the number of bytes in the string returned by XFetchBytes. If

there is no data in the buffer, * nbytes is set to 0.

Description

XFetchBytes returns data from cut buffer of the 8 buffers provided for interclient commu
nication. If the buffer contains data, XFetchBytes returns the number of bytes in nbytes,
otherwise it returns NULL and sets * nbytes to 0. The appropriate amount of storage is allo
cated and the pointer returned; the client must free this storage when finished with it by calling
XFree. Note that the cut buffer does not necessarily contain text, so it may contain embedded
null bytes and may not terminate with a null byte.

Use XFetchBuf f er to fetch data from any specified cut buffer.
Selections are preferred over cut buffers as a communication method.

For more information on cut buffers, see Volume One, Chapter 13, Other Programming Tech
niques.

Related Commands

XFetchBuf fer, XRotateBuf f ers, XStoreBuf f er, XStoreBytes.

Xlib Reference Manual 1 79

XFetChName V xm&gt;-W.ndow Manager Hints-

Name

XFetchName get a window s name (XA_WM_NAME property).

Synopsis

Status XFetchName ( display, w, window_name)
Display * display;
Window w;
char **window_name; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XQpenDisplay.

w Specifies the ID of the window whose name you want a pointer set to.

window_name Returns a pointer to the window name, which will be a null-terminated string.
If the XA_WM_NAME property has not been set for this window, XFetchName
sets windowname to NULL. When finished with it, a client can free the name
string using XFree.

Description

XFetchName is superseded by XGetWMName in Release 4. XFetchName returns the current
value of the XA_WM_NAME property for the specified window. XFetchName returns nonzero if
it succeeds, and zero if the property has not been set for the argument window.

For more information, see Volume One, Chapter 10, Interdient Communication, and Chapter
14, Window Management.

Errors

BadWindow

Related Commands

XGetClassHint, XGetlconName, XGetlconSizes, XGetNormalHints, XGet-
SizeHints, XGetTransientForHint, XGetWMHints, XGetZoomHints, XSet-
ClassHint, XSetCommand, XSetlconName, XSetlconSizes, XSetNormalHints,
XSetSizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints,
XStoreName.

180 Xlib Reference Manual

-Xllb - Drawing Primitives XFlll Arc

Name

XFillArc fill an arc.

Synopsis

XFillArc (display, draw-able, gc , x, y, width, height,

anglel , angle2)
Display * display ;
Drawable drawable;
GC gc;
int x , y ;

unsigned int width, height;
int anglel, angle2 ;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

dra wabl e Specifies the drawable.

gc Specifies the graphics context.

x Specify the x and y coordinates of the upper-left corner of the bounding box

y containing the arc, relative to the origin of the drawable.

width Specify the width and height in pixels. These are the major and minor axes of

height the arc.

anglel Specifies the start of the arc relative to the three-o clock position from the

center. Angles are specified in 64ths of degrees.

angle 2 Specifies the path and extent of the arc relative to the start of the arc. Angles

are specified in 64ths of degrees.

Description

XFillArc draws a filled arc. The x, y, width, and height arguments specify the bounding
box for the arc. See XDrawArc for the description of how this bounding box is used to com
pute the arc. Some, but not all, of the pixels drawn with XDrawArc will be drawn by XFill
Arc with the same arguments. See XFillRectangle for an example of the differences in
pixels drawn by the draw and fill routines.

XFillArc uses these graphics context components: function, plane_mask,
f ill_style, arc_mode, subwindow_mode, clip_x_origin, clip_y_origin, and
clip_mask. This function also uses these graphics context mode-dependent components:
foreground, background, tile, stipple, ts_x_origin, and ts_y_ origin.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5,
The Graphics Context.

Xlib Reference Manual 18 1

XFIIIArc (continued) Xlib - Drawing Primitives

Errors

BadDrawable

BadGC

BadMatch

Related Commands

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc,
XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints,
XDrawRectangle, XDrawRectangles, XDrawSegments, XFillArcs, XFill-
Polygon, XFillRectangle, XFillRectangles.

Xlib Reference Manual

-Xlib - Drawing Primitives XFIIIArCS

Name

XFillArcs fill multiple arcs.

Synopsis

XFillArcs ( display, drawable , gc , arcs, narcs)
Display *display;
Drawable drawable;
GC gc;
XArc *arcs;
int narcs;

Arguments

display Specifies a connection to an X server; returned from xopenDisplay.

dra viable Specifies the drawable.

gc Specifies the graphics context.

arcs Specifies a pointer to an array of arc definitions.

narcs Specifies the number of arcs in the array.

Description

For each arc, XFillArcs fills the region closed by the specified arc and one or two line seg
ments, depending on the arc_mode specified in the GC. It does not draw the complete out
lines of the arcs, but some pixels may overlap.

The arc forms one boundary of the area to be filled. The other boundary is determined by the
arc_mode in the GC. If the arc_mode in the GC is ArcChord, the single line segment
joining the endpoints of the arc is used. If ArcPieSlice, the two line segments joining the
endpoints of the arc with the center point are used. The arcs are filled in the order listed in the
array. For any given arc, no pixel is drawn more than once. If filled arcs intersect, pixels will
be drawn multiple times.

There is a limit to the number of arcs that can be filled in a single call, that varies according to
the server. To determine how many arcs you can fill in a single call, you find out your server s
maximum request size using XMaxRequestSize. Subtract 3 and divide by three, and this is
the maximum number of arcs you can fill in a single XFillArcs call.

XFillArcs use these graphics context components: function, plane_mask,
f ill_style, arc_mode, subwindow_mode, clip_x_origin, clip_y_origin, and
clipjmask. This function also uses these graphics context mode-dependent components:
foreground, background, tile, stipple, ts_x__origin, and ts_y_ origin.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5,
The Graphics Context.

Structures

typedef struct {
short x, y;
unsigned short width, height;

Xlib Reference Manual 183

XFillArcs

(continued)

Xlib - Drawing Primitives

short anglel, angle2; /* 64ths of Degrees */

} XArc;

Errors

BadDrawable

BadGC

BadMatch

Related Commands

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc,
XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints,
XDrawRectangle, XDrawRectangles, XDrawSegments, XFillArc, XFill-
Polygon, XFillRectangle, XFillRectangles.

184

Xlib Reference Manual

Xlib - Drawing Primitives-

f XFillPolygon

Name

XFillPolygon fill a polygon.

Synopsis

XFillPolygon (display, draw-able, gc , points, npoints, shape, mode)
Display * display;
Drawable draw-able;
GC gc;

XPoint * points;
int npoints;
int shape;
int mode ;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

dr a wabl e Specifies the drawable.

gc Specifies the graphics context.

points Specifies a pointer to an array of points.

npoin t s Specifies the number of points in the array.

shape Specifies an argument that helps the server to improve performance. Pass the

last constant in this list that is valid for the polygon to be filled: Complex,
Nonconvex, or Convex.

mode Specifies the coordinate mode. Pass either CoordModeOrigin or Coord-

ModePrevious.

Description

XFillPolygon fills the region closed by the specified path. Some but not all of the path
itself will be drawn. The path is closed automatically if the last point in the list does not coin
cide with the first point. No pixel of the region is drawn more than once.

The mode argument affects the interpretation of the points that define the polygon:

CoordModeOrigin indicates that all points are relative to the drawable s origin.

CoordModePrevious indicates that all points after the first are relative to the previ
ous point. (The first point is always relative to the drawable s origin.)

The shape argument allows the fill routine to optimize its performance given tips on the confi
guration of the area.

Complex indicates the path may self-intersect. The f ill_rule of the GC must be
consulted to determine which areas are filled. See Volume One, Chapter 5, The Graphics
Context, for a discussion of the fill rules EvenOddRule and WindingRule.

Xlib Reference Manual 185

XFMIPolygon (continued) Xlib - Drawing Primitives

None on vex indicates the path does not self-intersect, but the shape is not wholly con
vex. If known by the client, specifying Nonconvex instead of Complex may improve
performance. If you specify Nonconvex for a self-intersecting path, the graphics
results are undefined.

Convex means that for every pair of points inside the polygon, the line segment con
necting them does not intersect the path. This can improve performance even more, but
if the path is not convex, the graphics results are undefined.

Contiguous coincident points in the path are not treated as self-intersection.

XFillPolygon uses these graphics context components when filling the polygon area:

function, plane_mask, fill_style, fill_rule, subwindow_mode, clip_
x_origin, clip_y_origin, and clip_mask. This function also uses these mode-depen
dent components of the GC: foreground, background, tile, stipple,
ts_x_origin, and ts_y_origin.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5,
The Graphics Context.

Structures

typedef struct {

short x, y;
} XPoint;

Errors

BadDrawable
BadGC
BadMatch
BadValue

Related Commands

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc,
XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints,
XDrawRectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs,
XFillRectangle, XFillRectangles.

186 xiib Reference Manual

Xllb - Drawing Primitives-

XFillRectangle

Name

XFillRectangle fill a rectangular area.

Synopsis

XFillRectangle (display, drawable, gc, x, y, width, height)
Display *display;
Drawable drawable;
GC gc;
int x , y ;
unsigned int width, height;

Arguments

display Specifies a connection to an X server; returned from XQpenDisplay.

drawable Specifies the drawable.

gc Specifies the graphics context.

x Specify the x and y coordinates of the upper-left corner of the rectangle, rela-

y live to the origin of the drawable.

wi dth Specify the dimensions in pixels of the rectangle to be filled.

height

20 pixels 20 pixels

Description

XFillRectangle fills the rectangular area in the specified drawable using the x and y coor
dinates, width and height dimensions, and graphics context you specify. XFill
Rectangle draws some but not all of the path drawn by XDrawRectangle with the same
arguments.

XFillRectangle uses these graphics context components: function, plane_mask,

fill_style, subwindow_mode, clip_x_origin, clip_y_origin, and clip_

mask. This function also uses these graphics context components depending on the

fill_style: foreground, background tile, stipple, ts_x_origin, and

ts_y_origin.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5,

The Graphics Context.

Xlib Reference Manual

187

XFillRectangle (continued) Xlib - Drawing Primitives

Errors

BadDrawable

BadGC

BadMatch

Related Commands

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc,
XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints.
XDrawRectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs,
XFillPolygon, XFillRectangles.

188

Xlib Reference Manual

Xlib - Drawing Primitives-

XFMIRectangles

Name

XFillRectangles fill multiple rectangular areas.

Synopsis

XFillRectangles (display, drawable, gc , rectangles, nrectangles)
Display * display ;
Drawable drawable;
GC gc ;

XRectangle * rectangles;
int nrectangles;

Arguments

di spl ay
drawable

Specifies a connection to an X server; returned from xopenDisplay.

Specifies the drawable.
gc Specifies the graphics context.

rectangles Specifies a pointer to an array of rectangles.
nrectangles Specifies the number of rectangles in the array.

20 pixels

Description

XFillRectangles fills multiple rectangular areas in the specified drawable using the graph
ics context.

The x and y coordinates of each rectangle are relative to the drawable s origin, and define the
upper left corner of the rectangle. The rectangles are drawn in the order listed. For any given
rectangle, no pixel is drawn more than once. If rectangles intersect, the intersecting pixels will
be drawn multiple times.

There is a limit to the number of rectangles that can be filled in a single call, that varies accord
ing to the server. To determine how many rectangles you can fill in a single call, you find out
your server s maximum request size using XMaxRequestSize. Subtract 3 and divide by
two, and this is the maximum number of rectangles you can fill in a single XD raw-
Rectangles call.

XFillRectangles uses these graphics context components: function, plane_mask,
fill style, subwindow_mode, clip_x_origin, clip_y_origin, and clip_

Xlib Reference Manual

189

XFillRectangles (continued) Xlib - Drawing Primitives

mask. This function also uses these graphics context components depending on the f ill_
style: foreground, background, tile, stipple, ts_x_origin, and ts_y_
origin.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5,
The Graphics Context.

Structures

typedef struct {

short x, y;

unsigned short width, height;
} XRectangle;

Errors

BadDrawable

BadGC

BadMatch

Related Commands

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc,
XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints,
XDrawRectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs,
XFillPolygon, XFillRectangle, XFillRectangles.

1QO Xlib Reference Manual

XFindContext

Xlib - Context Manager

Name

XFindContext get data from the context manager (not graphics context).

Synopsis

int XFindContext ( display, w, context, data)
Display * display;
Window w;
XContext context;
caddr_t *data; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the window with which the data is associated.

context Specifies the context type to which the data corresponds.

data Returns the data.

Description

XFindContext gets data that has been assigned to the specified window and context ID. The
context manager is used to associate data with windows for use within an application.

This application should have called XUniqueContext to get a unique ID, and then xsave-
Context to save the data into the array. The meaning of the data is indicated by the context
ID, but is completely up to the client.

XFindContext returns XCNOENT (a nonzero error code) if the context could not be found and
zero (0) otherwise.

For more information on the context manager, see Volume One, Chapter 13, Other Program
ming Techniques.

Structures

typedef int XContext/

Related Commands

XDeleteContext, XSaveContext, XUniqueContext.

Xlib Reference Manual 19 1

XFIush v xnb . Output Bu((er _

Name

XFIush flush the request buffer (display all queued requests).

Synopsis

XFIush (display)

Display *display;

Arguments

display Specifies a connection to an X server; returned from xopenoi splay.

Description

XFIush sends to the server ("flushes") all requests that have been buffered but not yet sent.

Flushing is done automatically when input is read if no matching events are in Xlib s queue
(with XPending, XNext Event, or XWindowEvent, etc.), or when a call is made that gets
information from the server (such as XQueryPointer, XGetFontlnf o) so XFIush is sel
dom needed. It is used when the buffer must be flushed before any of these calls are reached.

For more information, see Volume One, Chapter 2, X Concepts, and Chapter 3, Basic Window
Program.

Related Commands

XSync.

192 Xlib Reference Manual

-Mb - screen saver / XForceScreenSaver

Name

XForceScreenSaver turn the screen saver on or off.

Synopsis

XForceScreenSaver ( display, mode)
Display * display;
int mode ;

Arguments

display Specifies a connection to an X server; returned from xopenDisplay.

mode Specifies whether the screen saver is active or reset. The possible modes are:

ScreenSaverActive or ScreenSaverReset.

Description

XForceScreenSaver resets or activates the screen saver.

If the specified mode is ScreenSaverActive and the screen saver currently is disabled, the
screen saver is activated, even if the screen saver had been disabled by calling xset Screen-
Saver with a timeout of zero (0). This means that the screen may go blank or have some ran
dom change take place to save the phosphors.

If the specified mode is ScreenSaverReset and the screen saver currently is enabled, the
screen is returned to normal, the screen saver is deactivated and the activation timer is reset to
its initial state (as if device input had been received). Expose events may be generated on all
visible windows if the server cannot save the entire screen contents.

For more information on the screen saver, see Volume One, Chapter 13, Other Programming
Techniques.

Errors

BadValue

Related Commands

XActivateScreenSaver, XGetScreenSaver, XResetScreenSaver, XSet-
ScreenSaver.

Xlib Reference Manual 193

^ Xlib - HouseKeeping

Name

XFree free specified memory allocated by an Xlib function.

Synopsis

XFree (data)

caddr_t data;

Arguments

data Specifies a pointer to the data that is to be freed.

Description

XFree is a general purpose routine for freeing memory allocated by Xlib calls.

Related Commands

Def aultScreen, XCloseDisplay, XNoOp, XOpenDisplay.

194 Xlib Reference Manual

-X. - co,ormaps / XFreeColormap

Name

XFreeColormap delete a colormap and install the default colormap.

Synopsis

XFreeColormap ( display, cmap)
Display *display;
Colo r map cmap ;

Arguments

display Specifies a connection to an X server; returned from xopenDisplay.

cmap Specifies the colormap to delete.

Description

XFreeColormap destroys the specified colormap, unless it is the default colormap for a
screen. That is, it not only uninstalls cmap from the hardware colormap if it is installed, but
also frees the associated memory including the colormap ID.

XFreeColormap performs the following processing:

If cmap is an installed map for a screen, it uninstalls the colormap and installs the default
if not already installed.

If cmap is defined as the colormap attribute for a window (by XCreateWindow or
XChangeWindowAttributes), it changes the colormap attribute for the window to
the constant None, generates a ColormapNotif y event, and frees the colormap. The
colors displayed with a colormap of None are server-dependent, since the default color-
map is normally used.

For more information, see Volume One, Chapter 7, Color.
Errors

BadColormap

Related Commands

Def aultColormap, DisplayCells, XCopyColormapAndFree, XCreate-
Colormap, XGetStandardColormap, XInstallColormap, XListlnstalled-
Colormaps, XSetStandardColormap, XSetWindowColormap, XUninstall-
Colormap.

Xlib Reference Manual 195

XFreeColors \

Xlib- Color Cells-

Name

XFreeColors free colormap cells or planes.

Synopsis

XFreeColors ( display, cmap , pixels, npixels, planes)
Display *display;
Colormap cmap;
unsigned long pixels [];
int npixels;
unsigned long planes;

Arguments

display Specifies a connection to an X server; returned from XQpenDisplay.

cmap Specifies the colormap.

pixels Specifies an array of pixel values.

npixels Specifies the number of pixels.

pi anes Specifies the planes you want to free.

Description

XFreeColors frees the cells whose values are computed by ORing together subsets of the
planes argument with each pixel value in the pixels array.

If the cells are read/write, they become available for reuse, unless they were allocated with
XAllocColorPlanes, in which case all the related pixels may need to be freed before any
become available.

If the cells were read-only, they become available only if this is the last client to have allocated
those shared cells.

For more information, see Volume One, Chapter 7, Color.

Errors

BadAccess Attempt to free a colorcell not allocated by this client (either unallocated or
allocated by another client).

BadColormap

BadValue A pixel value is not a valid index into cmap.

Note: if more than one pixel value is in error, the one reported is arbitrary.

Related Commands

BlackPixel, WhitePixel, XAllocColor, XAllocColorCells, XAllocColor
Planes, XAllocNamedColor, XLookupColor, XParseColor, XQueryColor,
XQueryColors, XStoreColor, XStoreColors, XStoreNamedColor.

196 Xlib Reference Manual

Xlib -Cursors-

J XFreeCursor

Name

XFreeCursor release a cursor.

Synopsis

XFreeCursor ( display, cursor)
Display * display;
Cursor cursor;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

cursor Specifies the ID of the cursor to be affected.

Description

XFreeCursor deletes the association between the cursor ID and the specified cursor. The
cursor storage is freed when all other clients have freed it. Windows with their cursor attribute
set to this cursor will have this attribute set to None (which implies CopyFromParent). The
specified cursor ID should not be referred to again.

Errors

BadCursor

Related Commands

XCreateFontCursor, XCreateGlyphCursor, XCreatePixmapCursor, XDef ine-
Cursor, XQueryBestCursor, XQueryBestSize, XRecolorCursor, XUndef ine-
Cursor.

Xlib Reference Manual 197

XFreeExtensionList \ XMb _ Extensions _

Name

XFreeExtensionList free memory allocated for a list of installed extensions.

Synopsis

XFreeExtensionList ( list)
char **Iist;

Arguments

list Specifies a pointer to the list of extensions returned from XList-

Extensions.

Description

XFreeExtensionList frees the memory allocated by XListExt ens ions.

For more information, see Volume One, Chapter 13, Other Programming Techniques.

Related Commands

XListExt ens ions, XQueryExtension.

198 XHb Reference Manual

XFreeFont

Name

XFreeFont unload a font and free storage for the font structure.

Synopsis

XFreeFont ( display, font_struct )
Display * display;
XFontStruct *font_struct ;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

f ont_struct Specifies the storage associated with the font.

Description

XFreeFont frees the memory allocated for the font_struct font information structure
(XFontStruct) filled by XQueryFont or XLoadQueryFont. XFreeFont frees all stor
age associated with the font_struct argument. Neither the data nor the font should be ref
erenced again.

The server unloads the font itself if no other client has loaded it.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text.

Structures

typedef struct {

XExtData *ext_data; /* hook for extension to hang data */

Font fid; /* Font ID for this font */

unsigned direction; /* hint about direction the font is painted */

unsigned min_char_or_byte2; /* first character */

unsigned max_char_or_byte2; /* last character */

unsigned min_bytel; /* first row that exists */

unsigned max_bytel; /* last row that exists */

Bool all_chars_exist; /* flag if all characters have nonzero size*/

unsigned def ault_char; /* char to print for undefined character */

int n_properties; /* how many properties there are */

XFontProp *properties; /* pointer to array of additional properties*/

XCharStruct min_bounds; /* minimum bounds over all existing char*/

XCharStruct max_bounds; /* minimum bounds over all existing char*/

XCharStruct *per_char; /* first_char to last_char information */

int ascent; /* logical extent above baseline for spacing */

int descent; /* logical descent below baseline for spacing */

} XFontStruct;

Errors

BadFont

Related Commands

XCreateFontCursor, XFreeFontlnf o, XFreeFontNames, XFreeFontPath,
XGetFontPath, XGetFontProperty, XListFonts, XListFontsWithlnf o,
XLoadFont, XLoadQueryFont, XQueryFont, XSetFont, XSetFontPath,
XUnloadFont.

Xlib Reference Manual

XFreeFontlnfo \ XIlb _ Fonts _

Name

XFreeFontlnfo free the memory allocated by XListFontsWithlnf o.

Synopsis

XFreeFontlnfo (names, info, actual_count)
char ** names;
XFontStruct *info;
int actual_count ;

Arguments

names Specifies a pointer to the list of font names that were returned by XList-

FontsWithlnfo.

info Specifies a pointer to the list of font information that was returned by

XListFontsWithlnf o.

actual_count

Specifies the number of matched font names returned by XLis t Fonts -
Withlnfo.

Description

XFreeFontlnfo frees the list of font information structures allocated by XListFonts
Withlnf o. It does not unload the specified fonts themselves.

Structures

typedef struct {

XExtData *ext_data; /* hook for extension to hang data */

Font fid; /* Font ID for this font */

unsigned direction; /* hint about direction the font is painted */

unsigned min_char_or_byte2; /* first character */

unsigned max char or byte2; /* last character */

unsigned min_bytel; /* first row that exists */

unsigned max bytel; /* last row that exists */

Bool all_chars_exist; /* flag if all characters have nonzero size*/

unsigned default_char; /* char to print for undefined character */

int n_properties; /* how many properties there are */

XFontProp *properties; /* pointer to array of additional properties*/

XCharStruct min_bounds; /* minimum bounds over all existing char*/

XCharStruct max bounds; /* minimum bounds over all existing char*/

XCharStruct *per_char; /* first_char to last_char information */

int ascent; /* logical extent above baseline for spacing */

int descent; /* logical descent below baseline for spacing */

} XFontStruct;

Related Commands

XCreateFontCursor, XFreeFont, XFreeFontNames, XGetFontPath, XGetFont-
Property, XListFonts, XListFontsWithlnf o, XLoadFont, XLoadQueryFont,
XQueryFont, XSetFont, XSetFontPath, XUnloadFont.

200 Xlib Reference Manual

Xlib -Fonts

J XFreeFontNames

Name

XFreeFontNames free the memory allocated by XListFonts.
Synopsis

XFreeFontNames (list)
char *list [ ] ;

Arguments

list Specifies the array of font name strings to be freed.

Description

XFreeFontNames frees the array of strings returned by XListFonts.

Related Commands

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontPath, XGetFont-
Path, XGetFontProperty, XListFonts, XListFontsWithlnf o, XLoadFont,
XLoadQueryFont, XQueryFont, XSetFont, XSetFontPath, XUnloadFont.

Xlib Reference Manual 201

XFreeFontPath \ x,, b -Fon,s-

Name

XFreeFontPath free the memory allocated by XGetFontPath.

Synopsis

XFreeFontPath (list)
char **list;

Arguments

list Specifies an array of strings allocated by XGetFontPath.

Description

XFreeFontPath frees the data used by the array of pathnames returned by XGetFont
Path.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Related Commands

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XGet
FontPath, XGetFontProperty, XListFonts, XListFontsWithlnf o, XLoad-
Font, XLoadQueryFont, XQueryFont, XSetFont, XSetFontPath, XUnloadFont.

202 Xlib Reference Manual

-Xlib - Graphics Context XFreeGC

Name

XFreeGC free a graphics context.

Synopsis

XFreeGC (display, gc)
Display * display;
GC gc ;

Arguments

display Specifies a connection to an X server; returned from xopenDisplay.

gc Specifies the graphics context to be freed.

Description

XFreeGC frees all memory associated with a graphics context, and removes the GC from the
server and display hardware.

For more information, see Volume One, Chapter 5, The Graphics Context.

Errors

BadGC

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XGContextFromGC, XSetArcMode,
XSetBackground, XSetClipMask, XSetClipOrigin, XSetClipRectangles,
XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground, XSet-
Function, XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask,
XSetState, XSetStipple, XSetSubwindowMode, XSetTSOrigin.

Xlib Reference Manual 203

XFreeModifiermap \

X|lb _

Name

XFreeModifiermap destroy and free a keyboard modifier mapping structure.

Synopsis

XF r eeModi f ie rmap ( modmap )

XModif ierKeymap * modmap;

Arguments

modmap Specifies a pointer to the XModif ierKeymap structure to be freed.

Description

XFreeModifiermap frees an XModif ierKeymap structure originally allocated by XNew-
Modif ierMap or XGetModif ierMapping.

For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Structures

typedef struct {

int max_keypermod; /* server s max number of keys per modifier */
KeyCode *modif iermap; /* an 8 by max_keypermod array of

* keycodes to be used as modifiers */

} XModif ierKeymap;

Related Commands

XChangeKeyboardMapping, XDeleteModif iermapEntry, XGetKeyboard-
Mapping, XGetModif ierMapping, XInsertModif iermapEntry, XKeycode-
ToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym, XLookup-
String, XNewModif ierMap, XQueryKeymap, XRebindKeySym, XRef resh-
KeyboardMapping, XSetModif ierMapping, XStringToKeysym.

204 Xlib Reference Manual

-Mb - Pixmaps and TNes /

Name

XFreePixmap free a pixmap ID.

Synopsis

XFreePixmap ( display, pixmap)
Display * display;
Pixmap pixmap;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

pixmap Specifies the pixmap whose ID should be freed.

Description

XFreePixmap disassociates a pixmap ID from its resource. If no other client has an ID for
that resource, it is freed. The Pixmap should never be referenced again by this client. If it is,
the ID will be unknown and a BadPixmap error will result.

Errors

BadPixmap

Related Commands

XCreateBitmapFromData, XCreatePixmap, XCreatePixmapFromBitmapData,
XQueryBestSize, XQueryBestStipple, XQueryBestTile, XReadBitmapFile,
XSetTile, XSetWindowBackgroundPixmap, XSetWindowBorderPixmap,
XWriteBitmapFile.

Xlib Reference Manual 205

XFreeStringList V Vl]

^ Xlib - Window Manager Hints-
Name

XFreeStringList free the in-memory data associated with the specified string list.

Synopsis

void XFreeStringList (list)
char **Iist;

Arguments

list Specifies the list of strings to be freed.

Availability

Release 4 and later.

Description

XFreeStringList releases memory allocated by XTextPropertyToStringList.

Related Commands

XGetTextProperty, XSetTextProperty, XStringListToTextProperty,
XTextPropertytoStringList.

206 Xlib Reference Manual

-xub - Graphic, con, 8 x / XGContextFromGC

Name

XGContextFromGC obtain the GContext (resource ID) associated with the specified
graphics context.

Synopsis

GContext XGContextFromGC ( gc)
GC gc;

Arguments

gc Specifies the graphics context of the desired resource ID.

Description

XGContextFromGC extracts the resource ID from the GC structure. The GC structure is
Xlib s local cache of GC values and contains a field for the GContext ID. This function is
essentially a macro that accesses this field, since the GC structure is intended to be opaque.

A GContext is needed to set a field of the xvisuallnf o structure prior to calling XGet-
Visuallnf o.

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XSetArcMode, XSet-
Background, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSet-
Dashes, XSetFillRule, XSetFillStyle, XSetForeground, XSetFunction,
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, XSetState,
XSetStipple, XSetSubwindowMode, XSetTSOrigin.

Xlib Reference Manual 207

XGeometry v ^

v Xlib - Standard Geometry-
Name

XGeometry calculate window geometry given user geometry string and default geometry.

Synopsis

int XGeometry ( display, screen, user_geom, default_geom r bwidth,

fwidth r f height , xadder , yadder f x, y, width, height)
Display *display;
int screen;

char *user_geom r *default_geom;
unsigned int bwidth;
unsigned int f width r f height ;
int xadder, yadder;
int *x r *y, * width, *height;/* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

screen Specifies which screen the window is on.

user_geom Specifies the user or program supplied geometry string, perhaps incomplete.

de fa u 1 1_ ge om

Specifies the default geometry string and must be complete.

bwi dth Specifies the border width.

f height Specify the font height and width in pixels (increment size).

f width

xadder Specify additional interior padding in pixels needed in the window,

yadder

x Return the user-specified or default coordinates of the window.

wi dth Return the window dimensions in pixels.

height

Description

XGeometry has been superseded by XWMGeometry as of Release 4.

XGeometry returns the position and size of a window given a user-supplied geometry
(allowed to be partial) and a default geometry. Each user-supplied specification is copied into
the appropriate returned argument, unless it is not present, in which case the default specifica
tion is used. The default geometry should be complete while the user-supplied one may not be.

XGeometry is useful for processing command line options and user preferences. These geom
etry strings are of the form:

=&lt;width&gt;x&lt;height&gt; { +- } &lt;xoffset&gt; ( +- } &lt;yoffset&gt;

208 Xlib Reference Manual

Xlib - Standard Geometry (continued) XGeometry

The "=" at the beginning of the string is now optional. (Items enclosed in &lt;&gt; are integers, and
items enclosed in {} are a set from which one item is to be chosen. Note that the brackets
should not appear in the actual string.)

The XGeometry return value is a bitmask that indicates which values were present in
user_geom. This bitmask is composed of the exclusive OR of the symbols XValue,
YValue, WidthValue, HeightValue, XNegative, or YNegative.

If the function returns either xvalue or YValue, you should place the window at the
requested position. The border width (bwidtti), size of the width and height increments (typi
cally fwidth and f height), and any additional interior space (xadder and yadder) are
passed in to make it easy to compute the resulting size.

Related Commands

XParseGeometry, XTranslateCoordinates, XWMGeometry.

Xlib Reference Manual 209

XGetAtomName V

^ Xlib - Properties-
Name

XGetAtomName get a string name for a property given its atom.

Synopsis

char *XGetAtomName ( display, atom)
Display *display;
Atom atom;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

atom Specifies the atom whose string name you want returned.

Description

An atom is a number identifying a property. Properties also have a string name. XGetAtom
Name returns the string name that was specified in the original call to xinternAtom that
returned this atom, or, for predefined atoms, a string version of the symbolic constant without
the XA_ is returned. If the specified atom is not defined, XGetAtomName returns NULL, and
generates a BadAtom error.

For example, XGetAtomName returns "XA_WM_CLASS" (a string) when passed the prede
fined atom XA_WM_CLASS (a defined constant).

You should free the resulting string with XFree when it is no longer needed.
XinternAtom performs the inverse function, returning the atom given the string.

Errors

BadAtom

Related Commands

XChangeProperty, XDeleteProperty, XGetFontProperty, XGetWindow-
Property, XinternAtom, XListProperties, XRotateWindowProperties,
XSetStandardProperties.

210 Xlib Reference Manual

-X.ib-W.ndowManagerH.n,, / XGetClaSSHint

Name

XGetClassHint get the XA_WM_CLASS property of a window.

Synopsis

Status XGetClassHint (display, v, class_hints)
Display *display;
Window w;
XClassHint *class_hints ; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window for which the property is desired.

class_hints Returns the XClassHints structure.

Description

XGetClassHint obtains the XA_WM_CLASS property for the specified window. This property
stores the resource class and instance name, that the window manager uses to get any resource
settings that may control how the window manager manages the application that set this prop
erty. XGetClassHint returns a Status of zero on failure, nonzero on success.

The XClassHint structure returned contains res_class, which is the name of the client
such as "emacs", and res_name, which should be the first of the following that applies:

command line option (-rn name)

a specific environment variable (e.g., RESOURCE_NAME)

the trailing component of argv [ ] (after the last /)

To free res_name and res_class when finished with the strings, use XFree.
For more information on using hints, see Volume One, Chapter W,Interclient Communication.

Structures

typedef struct {

char *res_name;

char *res_class;
} XClassHint;

Errors

BadWindow

Related Commands

XAllocClassHint, XFetchName, XGetlconName, XGetlconSizes, XGetNormal-
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XGetZoom-
Hints, XSetClassHint, XSetCommand, XSetlconName, XSetlconSizes, XSet-
NormalHints, XSetSizeHints, XSetTransientForHint, XSetWMHints, XSet-
ZoomHints, XStoreName, XSetWMProperties, XSetWMProperties.

Xlib Reference Manual 21 1

XGetCommand I

v Xllb - Window Manager Hints-
Name

XGetCommand get the XA_WM_COMMAND property (command line arguments).

Synopsis

Status XGetCommand (display, w, argv_return, argc_return)
Display ^display;
Window w;

char ***argv_return;
int *argc_return;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the window.

argv_return Returns the application s argument list.
argc_return Returns the number of arguments returned.

Description

XGetCommand reads the XA_WM_COMMAND property from the specified window and returns a
string list. If the XA_WM_COMMAND property exists, it is of type XA_STRING and format 8. If suf
ficient memory can be allocated to contain the string list, XGetCommand fills in the
argv_return and argc_return arguments and returns a non-zero status. Otherwise, it
returns a zero status. To free the memory allocated to the string list, use XFreeStringList.

Errors

BadWindow

Related Commands

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal-
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XGetZoom-
Hints, XSetClassHint, XSetlconName, XSetlconSizes, XSetNormalHints,
XSetSizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints,
XStoreName.

212 Xlib Reference Manual

XGetDefault

Name

XGetDefault extract an option value from the resource database.

Synopsis

char *XGetDefault (display, program, option)
Display * display ;
char * program;
char * opt ion;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

program Specifies the program name to be looked for in the resource database. The pro
gram name is usually argv [ ] , the first argument on the UNIX command line.

option Specifies the option name or keyword. Lines containing both the program

name and the option name, separated only by a period or asterisk, will be
matched.

Description

XGetDefault returns a character string containing the user s default value for the specified
program name and option name. XGetDefault returns NULL if no key can be found that
matches option and program. For a description of the matching rules, see XrmGet-
Resource.

The strings returned by XGetDefault are owned by Xlib and should not be modified or freed
by the client.

Lines in the user s resource database look like this:

xterm. foreground: #cOcOff

xterm. geometry : =81x28

xterm. saveLines : 256

xterm. font: 8x13

xterm. keyMapFile: /usr/black/ .keymap

xterm. activelcon: on

xmh. header. font 9x15

The portion on the left is known as a key; the portion on the right is the value. Upper or lower
case is important in keys. The convention is to capitalize only the second and successive words
in each option, if any.

Resource specifications are usually loaded into the XA_RESOURCE_MANAGER property on the
root window at login. If no such property exists, a resource file in the user s home directory is
loaded. On a UNIX-based system, this file is $HOMEIXdefoults. After loading these defaults,
XGetDefault merges additional defaults specified by the XENVIRONMENT environment
variable. If XENVIRONMENT is defined, it contains a full path name for the additional resource
file. If XENVIRONMENT is not defined, XGetDefault looks for $HOMEI Xdefoults-name,
where name specifies the name of the machine on which the application is running.

Xlib Reference Manual 213

XGetDefault (continued) Xlib - User Preferences

The first invocation of XGetDefault reads and merges the various resource files into Xlib so
that subsequent requests are fast Therefore, changes to the resource files from the program
will not be felt until the next invocation of the application.

For more information, see Volume One, Chapter 11, Managing User Preferences.
Related Commands

XAutoRepeatOf f , XAutoRepeatOn, XBell, XChangeKeyboardControl, XGet-
KeyboardControl.XGetPointerControl.

214 Xlib Reference Manual

-xnb - Error Handling / XGetErrorDatabaseText

Name

XGetErrorDatabaseText obtain error messages from the error database.

Synopsis

XGetErrorDatabaseText ( display, name, message,

default_string, buffer, length)
Display display;
char *name, *message;
char *default_string;

char * buffer; /* RETURN */

int length;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpe nD i s p 1 a y .

name Specifies the name of the application.

message Specifies the type of the error message. One of XProtoError, xiib-
Message, or XRequestMa jor (see Description below).

default_string

Specifies the default error message.

buffer Returns the error description.
length Specifies the size of the return buffer.

Description

XGetErrorDatabaseText returns a message from the error message database. Given
name and message as keys, XGetErrorDatabaseText uses the resource manager to
look up a string and returns it in the buffer argument. Xlib uses this function internally to look
up its error messages. On a UNIX-based system, the error message database is usually
lusrlliblXl 1 IXErrorDB .

The name argument should generally be the name of your application. The message argu
ment should indicate which type of error message you want. Three predefined message types
are used by Xlib to report errors:

XProtoError The protocol error number is used as a string for the message argument.
xlibMessage These are the message strings that are used internally by Xlib.
XReque s tMa jor The major request protocol number is used for the message argument.

If no string is found in the error database, XGetErrorDatabaseText returns the
def ault_string that you specify to the buffer. The string in buffer will be of length
length. For more information, see Volume One, Chapter 3, Basic Window Program.

Related Commands

XDisplayName, XGetErrorText, XSetAf terFunction, XSetErrorHandler,
XSetlOErrorHandler, XSynchronize.

Xlib Reference Manual 215

XGetErrorText \ Xllb _ Error Handnng _

Name

XGetErrorText obtain a description of error code.

Synopsis

XGetErrorText ( display, code, buffer, length)
Display *display;
int code ;

char * buffer; /* RETURN */

int length;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

code Specifies the error code for which you want to obtain a description.

buffer Returns a pointer to the error description text.

length Specifies the size of the buffer.

Description

XGetErrorText obtains textual descriptions of errors. XGetErrorText returns a pointer
to a null-terminated string describing the specified error code with length length. This string
is copied from static data and therefore may be freed. This routine allows extensions to the
Xlib library to define their own error codes and error strings that can be accessed easily.

For more information, see Volume One, Chapter 3, Basic Window Program.
Related Commands

XDisplayName, XGetErrorDatabaseText, XSetAf terFunction, XSetError-
Handler, XSetlOErrorHandler, XSynchronize.

21 6 Xlib Reference Manual

XI ib- Fonts-

J XGetFontPath

Name

XGetFontPath get the current font search path.

Synopsis

char **XGetFontPath ( display, npaths)
Display ^display;
int * npaths; /* RETURN number of elements */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

npaths Returns the number of strings in the font path array.

Description

XGetFontPath allocates and returns an array of strings containing the search path for fonts.
The data in the font path should be freed when no longer needed.

Related Commands

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XFree-
FontPath, XGetFontProperty, XListFonts, XListFontsWithlnf o, XLoad-
Font, XLoadQueryFont, XQueryFont, XSetFont, XSetFontPath, XUnloadFont.

Xlib Reference Manual 217

XGetFontProperty

Xlib- Properties-

Name

XGetFontProperty get a font property given its atom.

Synopsis

Bool XGetFontProperty (font_struct f atom, value)
XFontStruct *f ont_struct ;
Atom atom;
unsigned long *value; /* RETURN */

Arguments

font struct Specifies the storage associated with the font.

atom
value

Specifies the atom associated with the property name you want returned.

Returns the value of the font property.

Description

XGetFontProperty returns the value of the specified font property, given the atom for that
property. The function returns False if the atom was not defined, or True if was defined.

There are a set of predefined atoms for font properties which can be found in &lt;XlllXatom.h&gt;.
These atoms are listed and described in Volume One, Chapter 6, Drawing Graphics and Text.
This set contains the standard properties associated with a font. The predefined font properties
are likely but not guaranteed to be present for any given font.

See Volume One, Appendix I, Logical Font Description Conventions, for more information on
font properties.

Structures

typedef struct {

XExtData *ext_data;
Font fid;

unsigned direction;
unsigned min_char_or_byte2;
unsigned max_char_or_byte2;
unsigned min_bytel;
unsigned max_bytel;
Bool all_chars_exist;
unsigned def ault_char;
int n_properties;
XFontProp ^properties;
XCharStruct min_bounds;
XCharStruct max bounds;

XCharStruct
int ascent;
int descent;
} XFontStruct;

per_char;

/* hook for extension to hang data */

/* Font ID for this font */

/* hint about direction the font is painted */

/* first character */

/* last character */

/* first row that exists */

/* last row that exists */

/* flag if all characters have nonzero size*/

/* char to print for undefined character */

/* how many properties there are */

/* pointer to array of additional properties*/

/* minimum bounds over all existing char*/

/* first_char to last__char information */

/* logical extent above baseline for spacing */

/* logical descent below baseline for spacing */

Related Commands

XChangeProperty, XDeleteProperty, XGetAtomName, XGetWindowProperty,
XInternAtom, XListProperties, XRotateWindowProperties, XSetStandard-
Properties.

218

Xlib Reference Manual

Xlib - Window Manager Hints-

XGetGCValues

Name

XGetGCValues obtain components of a given GC from Xlib s GC cache.

Synopsis

Status XGetGCValues (display, gc, valuemask, values)
Display ^display;
GC gc;

unsigned long valuemask;
XGCValues * values;

Arguments

di sp 1 ay

valuemask

values

/* RETURN */

Specifies a connection to an X server; returned from XOpenDisplay.
Specifies the GC.

Specifies which components in the GC are to be returned in the values
argument. This argument is the bitwise inclusive OR of one or more of the
valid GC component mask bits.

Returns the GC values in the specified XGCValues structure.

Availability

Release 4 and later.

Description

XGetGCValues returns the components specified by valuemask for the specified GC. Note
that the clip mask and dash list (represented by the GCClipMask and GCDashList bits,
respectively, in the valuemask) cannot be requested. If the valuemask contains a valid set of
GC mask bits (any of those listed in the Structures section with the exception of GCClipMask
and GCDashList) and no error occur, XGetGCValues sets the requested components in
values and returns a nonzero status. Otherwise, it returns a zero status.

For more information, see Volume One, Chapter 5, The Graphics Context.

Structures

typedef struct {

int function; /*

unsigned long plane_mask; /*

unsigned long foreground; /*

unsigned long background; /*

int line_width; /*

int line_style; /*

int cap_style; /*

int join_style; /*

int fill_style; /*

int fill_rule; /*

int arc_mode; /*

Pixmap tile; /*

Pixmap stipple; /*

int ts_x_origin; /*

logical operation */

plane mask */

foreground pixel */

background pixel */

line width */

LineSolid, LineOnOf fDash, LineDoubleDash */

CapNotLast, CapButt, CapRound, CapPro jecting */

JoinMiter, JoinRound, JoinBevel */

FillSolid, Fill-Tiled, FillStippled */

EvenOddRule, WindingRule */

ArcPieSlice, ArcChord */

tile pixmap for tiling operations */

stipple 1 plane pixmap for stipping */

offset for tile or stipple operations */

Xlib Reference Manual

219

XGetGCValues

(continued)

Xlib - Window Manager Hints

int ts_y_origin;
Font font;
int subwindow mode;
Bool graphics_exposures;
int clip_x_origin;
int clip_y_origin;
Pixmap clip_mask;
int dash_offset;
char dashes;
} XGCValues;

/* default text font for text operations */

/* ClipByChildren, Includelnferiors */

/* generate events on XCopyArea, XCopyPlane */

/* origin for clipping */

/* bitmap clipping; other calls for rects */

/* patterned/dashed line information */

#define

GCFunction (1L0)

#define

GCPlaneMask (1L1)

#define

GCForeground (1L2)

#define

GCBackground (1L3)

#define

GCLineWidth (1L4)

#define

GCLineStyle (1L5)

#define

GCCapStyle (1L6)

#define

GCJoinStyle (1L7)

#define

GCFillStyle (1L8)

#define

GCFillRule (1L9)

fdefine

GCTile (1L10)

#define

GCStipple (1L11)

#define

GCTileStipXOrigin (1L12)

#def ine

GCTileStipYOrigin (1L13)

tdefine

GCFont (1L14)

#def ine

GCSubwindowMode (1L15)

#define

GCGraphicsExposures (1L16)

#define

GCClipXOrigin (1L17)

#define

GCClipYOrigin (1L18)

#def ine

GCClipMask (1L19)

tdefine

GCDashOffset (1L20)

#def ine

GCDashList (1L21)

#define

GCArcMode (1L22)

/* not valid in this call */
/* not valid in this call */

Related Commands

XChangeGC, XCopyGC, XCreateGC.

220

Xlib Reference Manual

Xlib - Window Attributes-

J XGetGeometry

Name

XGetGeometry obtain the current geometry of drawable.

Synopsis

Status XGetGeometry (display, drawable, root, x, y,

width, height, border_ width, depth)
Display ^display;
Drawable drawable;

Window *root; /* RETURN */

int *x, *y; /* RETURN */

unsigned int *width, *height; /* RETURN */

unsigned int *border_width ; /* RETURN */

unsigned int * depth; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

drawabl e Specifies the drawable, either a window or a pixmap.
root Returns the root window ID of the specified window.

x Return the coordinates of the upper- left pixel of the window s border, relative

y to its parent s origin. For pixmaps, these coordinates are always zero.

width Return the dimensions of the drawable. For a window, these return the inside

height size (not including the border).

border_width

Returns the borderwidth, in pixels, of the window s border, if the drawable is a
window. Returns zero if the drawable is a pixmap.

depth Returns the depth of the pixmap or window (bits per pixel for the object).

Description

This function gets the current geometry of a drawable, plus the ID of the root window of the
screen the window is on.

XGetGeometry returns a Status of zero on failure, or nonzero on success.

Errors

BadDrawable

Related Commands

XConf igureWindow, XGetWindowAttributes, XMoveResizeWindow, XMove-
Window, XResizeWindow.

Xlib Reference Manual 221

XGetlconName V Xlib _ Wlndow Manager Hln , s _

Name

XGetlconName get the name to be displayed in an icon.

Synopsis

Status XGetlconName ( display, w, icon_name)
Display *display;
Window w;
char **icon_name; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window whose icon name you want to leam.

icon_name Returns a pointer to the name to be displayed in the window s icon. The
name should be a null-terminated string. If a name hasn t been assigned to
the window, XGetlconName sets this argument to NULL. When finished
with it, a client must free the icon name string using XFree.

Description

XGetlconName is superseded by XGetWMlconName in Release 4. XGetlconName reads
the icon name property of a window. This function is primarily used by window managers to
get the name to be written in a window s icon when they need to display that icon.

XGetlconName returns a nonzero Status if it succeeds, and zero if no icon name has been
set for the argument window.

For more information, see Volume One, Chapter WJnterclient Communication.
Errors

BadWindow

Related Commands

XFetchName, XGetClassHint, XGetlconSizes, XGetNormalHints, XGetSize-
Hints, XGetTransientForHint, XGetWMHints, XGetZoomHints, XSetClass-
Hint, XSetCommand, XSetlconName, XSetlconSizes, XSetNormalHints, XSet-
SizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints, XStore-
Name.

222 Xlib Reference Manual

-XHb-W.ndowM.n.g.rH.n., / XGetlCOnSizeS

Name

XGetlconSizes get preferred icon sizes.

Synopsis

Status XGetlconSizes (display, w, size_list, count)
Display *display;
Window w;

XlconSize **size_list; /* RETURN */
int * count; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the window ID (usually of the root window).

si ze_l 1st Returns a pointer to the size list.

count Returns the number of items in the size list.

Description

XGetlconSizes reads the XA_WM_ICON_SIZE property that should be set by the window
manager to specify its desired icon sizes. XGetlconSizes returns a Status of zero if a
window manager has not set icon sizes, and a nonzero Status otherwise. This function
should be called by all programs to find out what icon sizes are preferred by the window man
ager. The application should then use XSetWMHints to supply the window manager with an
icon pixmap or window in one of the supported sizes. To free the data allocated in
size_list, use XFree.

For more information, see Volume One, Chapter 10, Interclient Communication.
Structures

typedef struct {

int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
} XlconSize;

/* width_inc and height_inc provide the preferred

* increment of sizes in the range from min_width

* to max_width and min_height to max_height. */

Errors

BadWindow

Xlib Reference Manual 223

XGetlconSizes (continued) Xlib - Window Manager Hints

Related Commands

XAllocIconSize, XFetchName, XGetClassHint, XGetlconName, XGetNormal-
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XGetZoom-
Hints, XSetClassHint, XSetCommand, XSetlconSizes, XSetNormalHints,
XSetSizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints,
XStoreName .

Xlib Reference Manual

-X.ib-.mage, /

Name

XGetlmage place contents of a rectangle from drawable into an image.

Synopsis

Xlmage * XGet Image ( display, drawable, x, y, width, height,

plan e_ma sk , forma t )
Display * display;
Drawable drawable;
int x , y ;

unsigned int width, height;
unsigned long plane_mask;
int format;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

drawable Specifies the drawable to get the data from.

x Specify the x and y coordinates of the upper-left corner of the rectangle, rela-

y live to the origin of the drawable.

wi dth Specify the width and height in pixels of the image.

height

plane_mask Specifies a plane mask that indicates which planes are represented in the
image.

format Specifies the format for the image. Pass either XYPixmap or ZPixmap.

Description

XGetlmage dumps the contents of the specified rectangle, a drawable, into a client-side Xlm
age structure, in the format you specify. Depending on which format you pass to the format
argument, the function does the following:

If the format is XYP ixmap

Gets only the bit planes you passed to the plane_mask argument.
If the format is ZP ixmap

Sets to the bits in all planes not specified in the plane_mask argument. The function
performs no range checking on the values in plane_mask, and ignores extraneous bits.

XGetlmage returns the depth of the image to the depth member of the ximage structure.
This depth is as specified when the drawable was created.

If the drawable is a pixmap, the specified rectangle must be completely inside the pixmap, or a
BadMatch error will occur, and the visual field in the image will be None. If XGetlmage
fails, it returns NULL. If the drawable is a window, the window must be viewable, and the speci
fied rectangle must not go off the edge of the screen. Otherwise, a BadMatch error will occur.
If the drawable is a window, the visual argument will return the visual specified when the
drawable was created.

Xlib Reference Manual 225

XGetlmage (continued) Xlib - Images

The returned image will include any visible portions of inferiors or overlapping windows con
tained in the rectangle. The image will not include the cursor. The specified area can include
the borders. The returned contents of visible regions of inferiors of different depth than the
specified window are undefined.

If the window has a backing-store, the backing-store contents are returned for regions of the
window that are obscured by noninferior windows. Otherwise, the return contents of such
obscured regions are undefined. Also undefined are the returned contents of visible regions of
inferiors of different depth than the specified window.

The data in the image structure is stored in the server s natural byte- and bit-order.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.

Errors

BadDrawable

BadMatch See Description above.

BadValue

Related Commands

ImageByteOrder, XAddPixel, XCreatelmage, XDestroy Image, XGetPixel,
XGetSublmage, XPutlmage, XPutPixel, XSub Image.

Xlib Reference Manual

Xllb -Input Handling-

J XGetlnputFocus

Name

XGetlnputFocus return the current keyboard focus window.

Synopsis

XGetlnputFocus (display, focus, revert_to)
Display *display;

window * focus; /* RETURN */

int *revert_to; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

focus Returns the ID of the focus window, or one of the constants PointerRoot

or None.

revert_to Returns the window to which the focus would revert if the focus window
became invisible. This is one of these constants: Re vert TOP a rent,
RevertToPointerRoot, or RevertToNone. Must not be a window ID.

Description

XGetlnputFocus returns the current keyboard focus window and the window to which the
focus would revert if the focus window became invisible.

XGetlnputFocus does not report the last focus change time. This is available only from
Focus In and FocusOut events.

Related Commands

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped-
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued,
XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeek-
If Event, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSetlnput-
Focus, XSynchronize, XWindowEvent.

Xlib Reference Manual 227

XGetKeyboardControl

Xlib - User Preferences

Name

XGetKeyboardControl obtain a list of the current keyboard preferences.

Synopsis

XGetKeyboardControl (display, values)
Display *display;
XKeyboardState *values; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

values Returns filled XKeyboardState structure.

Description

XGetKeyboardControl returns the current control values for the keyboard. For the LEDs
(light emitting diodes), the least significant bit of led_jnask corresponds to LED 1, and each
bit that is set to 1 in led_mask indicates an LED that is lit. auto_repeats is a bit vector;
each bit that is set to 1 indicates that auto-repeat is enabled for the corresponding key. The vec
tor is represented as 32 bytes. Byte N (from 0) contains the bits for keys 8N to 8N+7, with the
least significant bit in the byte representing key 8N. global_auto_repeat is either
AutoRepeatModeOn or AutoRepeatModeOf f .

For the ranges of each member of XKeyboardState, see the description of XChange-
PointerControl.

For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Structures

typedef struct {

int key_click_percent;

int bell_percent;

unsigned int bell_pitch, bell_duration;

unsigned long led_mask;

int global_auto_repeat ;

char auto_repeats [32] ;
} XKeyboardState;

Related Commands

XAutoRepeatOf f , XAutoRepeatOn, XBell, XChangeKeyboardControl, XGet-
Def ault, XGetPointerControl.

Xlib Reference Manual

Xlib- Keyboard

/ XGetKeyboardMapping

Name

XGetKeyboardMapping return symbols for keycodes.
Synopsis

KeySym *XGetKeyboardMapping ( display, first_keycode,

keycode_count , keysyms_per_keycode)
Display * display ;
KeyCode first_keycode;
int keycode_count ;
int *keysyms_per_keycode; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.
first_keycode

Specifies the first keycode that is to be returned.

keycode_count

Specifies the number of keycodes that are to be returned.

eysyms_per_.keycode

Returns the number of keysyms per keycode.

Description

Starting with first_keycode, XGetKeyboardMapping returns the symbols for the
specified number of keycodes. The specified first_keycode must be greater than or equal
to min_keycode as returned by XDisplayKeycodes, otherwise a BadValue error
occurs. In addition, the following expression must be less than or equal to max_keycode
(also returned by XDisplayKeycodes) as returned in the Display structure, otherwise a
BadValue error occurs:

first_keycode + keycode_count - 1
The number of elements in the keysyms list is:

keycode_count * keysyms_per_keycode

Then, keysym number N (counting from 0) for keycode K has an index (counting from 0) of the
following (in keysyms):

(K - first_keycode) * keysyms_per_keycode + N

The keysyms_per_keycode value is chosen arbitrarily by the server to be large enough to
report all requested symbols. A special KeySym value of NoSymbol is used to fill in unused
elements for individual keycodes.

Use XFree to free the returned keysym list when you no longer need it.

For more information, see Volume One, Chapter 9, The Keyboard and Pointer.

Xlib Reference Manual 229

XGetKeyboardMapping (continued) Xlib - Keyboard

Errors

BadValue first_keycode less than display-&gt;min_keycode .

display-&gt;max_keycode exceeded.

Related Commands

XChangeKeyboardMapping, XDeleteModif iermapEntry, XFreeModif iermap,
XGetModif ierMapping, XInsertModif iermapEntry, XKeycodeToKeysym,
XKeysymToKeycode, XKeysymToString, XLookupKeysym, XLookupString,
XNewModif ierMap, XQueryKeymap, XRebindKeySym, XRef reshKeyboard-
Mapping, XSetModif ierMapping, XStringToKeysym.

230 Xlib Reference Manual

X Programming Library-

J XGetModifierMapping

Name

XGetModifierMapping obtain a mapping of modifier keys (Shift, Control, etc.).
Synopsis

XModifierKeymap *XGetModif ierMapping (display)
Display *display;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

Description

XGetModifierMapping returns the keycodes of the keys being used as modifiers.

There are eight modifiers, represented by the symbols Shif tMapindex, LockMapindex,
ControlMapIndex, ModlMapIndex, Mod2MapIndex, ModSMapIndex, Mod4Map-
Index, and ModSMapIndex. The modif iermap member of the XModifierKeymap
structure contains eight sets of keycodes, each set containing max_keypermod keycodes.
Zero keycodes are not meaningful. If an entire modif iermap is filled with zero s, the corre
sponding modifier is disabled. No keycode will appear twice anywhere in the map.

Structures

typedef struct {

int max keypermod; /* server s max number of keys per modifier */
KeyCode *modif iermap; /* an 8 by max_keypermod array of

* keycodes to be used as modifiers */

} XModifierKeymap;

/* modifier names. Used to build a SetModif ierMapping request or

to read a GetModif ierMapping request. */
#define ShiftMapIndex
#define LockMapindex 1

#define ControlMapIndex 2

#define ModlMapIndex 3
#define Mod2MapIndex 4
#define ModSMapIndex 5
tdefine ModSMapIndex 6
#define ModSMapIndex 7

Related Commands

XChangeKeyboardMapping, XDeleteModifiermapEntry, XFreeModif iermap,
XGetKeyboardMapping, XInsertModif iermapEntry, XKeycodeToKeysym,
XKeysymToKeycode, XKeysymToString, XLookupKeysym, XLookupString,
XNewModif ierMap, XQueryKeymap, XRebindKeySym, XRef reshKeyboard-
Mapping, XSetModif ierMapping, XStringToKeysym.

Xlib Reference Manual

XGetMotionEvents \ xlib . lnputH and,,n g -

Name

XGetMotionEvents get events from pointer motion history buffer.

Synopsis

XTimeCoord *XGetMotionEvents ( display, w, start, stop, nevents)
Display *display;
Window w;
Time start, stop;
int * nevents; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

vf Specifies the ID of the window whose associated pointer motion events will be

returned.

start Specify the time interval for which the events are returned from the motion his-

stop tory buffer. Pass a time stamp (in milliseconds) or Cur rent Time.

nevents Returns the number of events returned from the motion history buffer.

Description

XGetMotionEvents returns all events in the motion history buffer that fall between the
specified start and stop times (inclusive) and that have coordinates that lie within (including
borders) the specified window at its present placement. The x and y coordinates of the
XTimeCoord return structure are reported relative to the origin of w.

XGetMotionEvent returns NULL if the server does not support a motion history buffer
(which is common), or if the start time is after the stop time, or if the start time is in the future.
A motion history buffer is supported if XDisplayMotionBuf f erSize (display) &gt; 0. The
pointer position at each pointer hardware interrupt is then stored for later retrieval.

If the start time is later than the stop time, or if the start time is in the future, no events are
returned. If the stop time is in the future, it is equivalent to specifying the constant Cur rent -
Time, since the server does not wait to report future events.

Use XFree to free the returned XTimeCoord structures when they are no longer needed.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer.

Structures

typedef struct _XTimeCoord {

Time time;

short x, y;
} XTimeCoord;

Errors

BadWindow

232 Xlib Reference Manual

Xlib - Input Handling (continued) XGetMotionEventS

Related Commands

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped-
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued,
XGetlnputFocus, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeek-
If Event, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSetlnput-
Focus, XSynchronize, XWindowEvent.

Xlib Reference Manual 233

XGetNormalHints V X1|b _ Window Manager Hlms _

Name

XGetNormalHints get the size hints property of a window in normal state (not zoomed or
iconified).

Synopsis

Status XGetNormalHints (display, w, hints)
Display *display;
Window w;
XSizeHints *hints; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window to be queried.

hints Returns the sizing hints for the window in its normal state.

Description

XGetNormalHints has been superseded by XGetWMNormalHints as of Release 4,
because new interclient communication conventions are now standard.

XGetNormalHints returns the size hints for a window in its normal state by reading the
XA_WM_NORMAL_HINTS property. This function is normally used only by a window manager. It
returns a nonzero Status if it succeeds, and zero if it fails (e.g., the application specified no
normal size hints for this window.)

For more information on using hints, see Volume One, Chapter W, Interclient Communication.
Structures

typedef struct {

long flags; /* which fields in structure are defined */

int x, y;

int width, height;

int min_width, min_height;

int max_width, max_height;

int width_inc, height_inc;

struct {

int x; /* numerator */

int y; /* denominator */
} min_aspect, max_aspect;
} XSizeHints;

/* flags argument in size hints */

ttdefine USPosition (1L O)/* user specified x, y */

#define USSize (1L I)/* user specified width, height */

#define PPosition (1L 2)/* program specified position */

#define PSize (1L 3)/* program specified size */

#define PMinSize (1L 4)/* program specified minimum size */

tdefine PMaxSize (1L 5)/* program specified maximum size */

234 Xlib Reference Manual

Xlib - Window Manager Hints (continued) XGetNormalHintS

tdefine PResizelnc (1L 6)/* program specified resize increments */
#define PAspect (1L 7)/* program specified min/max aspect ratios */
#def ine PAllHints (PPosition | PSize I PMinSize I PMaxSize | PResizelnc I PAspect)

Errors

BadWindow

Related Commands

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetSize-
Hints, XGetTransientForHint, XGetWMHints, XGetZoomHints, XSetClass-
Hint, XSetCommand, XSetlconName, XSetlconSizes, XSetNormalHints, XSet-
SizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints, XStore-
Name.

Xlib Reference Manual 235

XGetPixel

-Xlib- Images-

Name

XGetPixel obtain a single pixel value from an image.

Synopsis

unsigned long XGetPixel (ximage, x, y)
Xlmage * ximage;
int x;
int y;

Arguments

ximage

Specifies a pointer to the image.

Specify the x and y coordinates of the pixel whose value is to be returned.

Description

XGetPixel returns the specified pixel from the named image. The x and y coordinates are
relative to the origin (upper left [0,0]) of the image). The pixel value is returned in the clients
bit- and byte-order. The x and y coordinates must be contained in the image.

For more information, see Volume One, Chapter 6, Drawing Graphics and Text.

Structures

typedef struct _XImage {
int width, height;
int xoffset;
int format;
char *data;
int byte_order;
int bitmap_unit;
int bitmap bit order;
int bitmap_pad;
int depth;
int bytes_per_line;
int bits_per_pixel;
unsigned long red_mask;
unsigned long green_mask;
unsigned long blue mask;
char *obdata;
struct funcs {

struct _XImage * (*create_image) () ;

int (*destroy_image) () ;

unsigned long (*get_pixel) () ;

int (*put_pixel) () ;

struct _XImage * (*sub_image) () ;

int (*add_pixel) () ;
} f;
} Ximage;

size of image */

number of pixels offset in X direction */

/* XYBitmap, XYPixmap, ZPixmap */

pointer to image data */

data byte order, LSBFirst, MSBFirst */

quant, of scan line 8, 16, 32 */

LSBFirst, MSBFirst */

8, 16, 32 either XY or ZPixmap */

depth of image */

accelerator to next line */

bits per pixel (ZPixmap) */

bits in z arrangment */

/* hook for the object routines to hang on
/* image manipulation routines */

Xlib Reference Manual

Xlib - Images (continued) XGetPixel

Related Commands

ImageByteOrder, XAddPixel, XCreate Image, XDestroy Image, XGetlmage,
XGetSublmage, XPutlmage, XPutPixel, XSublmage.

Xlib Reference Manual 237

XGetPointerControl "\

Xlib- Pointer-

Name

XGetPointerControl get the current pointer preferences.

Synopsis

XGetPointerControl (display, accel_numerator, accel_denominator ,

threshold)
Display * display ;

int *accel_numerator f *accel_denominator; /* RETURN */
int * threshold; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

accel_numerator

Returns the numerator for the acceleration multiplier.

accel_denominator

Returns the denominator for the acceleration multiplier.

threshold Returns the acceleration threshold in pixels. The pointer must move more
than this amount before acceleration takes effect.

Description

XGetPointerControl gets the pointer acceleration parameters.

accel_numerator divided by accel_denominator is the number of pixels the cursor
moves per unit of motion of the pointer, applied only to the amount of movement over
threshold.

Related Commands

XChangeActivePointerGrab, XChangePointerControl, XGetPointer-
Mapping, XGrabPointer, XQueryPointer, XSetPointerMapping, XUngrab-
Pointer, XWarpPointer.

Xlib Reference Manual

Xlib -Pointer

J XGetPointerMapping

Name

XGetPointerMapping get the pointer button mapping.

Synopsis

int XGetPointerMapping ( display, map, nmap)
Display * display;

unsigned char map [ ] ; /* RETURN */
int nmap ;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenDisplay.

map Returns the mapping list. Array begins with map [ ] .

nmap Specifies the number of items in mapping list.

Description

XGetPointerMapping returns the current mapping of the pointer buttons. Information is
returned in both the arguments and the function s return value, map is an array of the numbers
of the buttons as they are currently mapped. Elements of the list are indexed starting from 1.
The nominal mapping for a pointer is the identity mapping: map[i]=i. If map [3] =2, it
means that the third physical button triggers the second logical button.

nmap indicates the desired number of button mappings.

The return value of the function is the actual number of elements in the pointer list, which may
be greater or less than nmap.

Related Commands

XChangeActivePointerGrab, XChangePointerControl, XGetPointer-
Control, XGrabPointer, XQueryPointer, XSetPointerMapping, XUngrab-
Pointer, XWarpPointer.

Xlib Reference Manual 239

XGetRGBColOrmapS \ x,, b -W,ndow Manages-

Name

XGetRGBColormaps obtain the XStandardColormap structure associated with the
specified property.

Synopsis

Status XGetRGBColormaps ( display, w, std_colormap, count,

property)
Display *display;
Window w;

XStandardColormap **std_col ormap; /* RETURN */
int * count; /* RETURN */

Atom property;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the window.

std_col ormap

Returns the XStandardColormap structure.

count Returns the number of colormaps .

property Specifies the property name.

Availability

Release 4 and later.

Description

XGetRGBColormaps returns the RGB colormap definitions stored in the specified property
on the named window. If the property exists, is of type RGB_COLOR_MAP , is of format 32, and is
long enough to contain a colormap definition, XGetRGBColormaps allocates and fills in
space for the returned colormaps, and returns a non-zero status. Otherwise, none of the fields
are set, and XGetRGBColormaps returns a zero status. If the visualid field is not present,
XGetRGBColormaps assumes the default visual for the screen on which the window is
located; if the killid field is not present, it is assumed to have a value of None, which indicates
that the resources cannot be released. Note that it is the caller s responsibility to honor the
ICCCM restriction that only RGB_DEFAULT_MAP contain more than one definition.

XGetRGBColormaps supersedes XGetStandardColormap.
For more information, see Volume One, Chapter 7, Color.

Structures

typedef struct {

Colormap colormap;
unsigned long red_max;
unsigned long red_mult;
unsigned long green max;

Xlib Reference Manual

Xlib - Window Manager Hints (continued) XGetRGBColormaps

unsigned long green_mult;
unsigned long blue_max;
unsigned long blue_mult;
unsigned long base_pixel;

VisuallD visualid; /* added by ICCCM version 1 */

XID killid; /* added by ICCCM version 1 */

} XStandardColormap;

Errors

BadAtom
BadWindow

Related Commands

XAllocStandardColormap, XSetRGBColormaps.

Xlib Reference Manual 24 1

XGetScreenSaver \.

Xllb - Screen Saver

Name

XGetScreenSaver get the current screen saver parameters.

Synopsis

XGetScreenSaver ( display, timeout, interval, prefer_blanking,

allow_exposures)
Display * display;

int *timeout, * interval ; /* RETURN */
int *prefer_blanking; /* RETURN */

int *allow_exposures; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XQpenDisplay.

timeout Returns the idle time, in seconds, until the screen saver turns on.

interval Returns the interval between screen changes, in seconds.

prefer_blanking

Returns the current screen blanking preference, one of these constants:
DontPref erBlanking, Pref erBlanking, or Def aultBlanking.

allotvr_exposures

Returns the current screen save control value, either DontAl low-
Exposures, AllowExposures, or Def aultExposures.

Description

XGetScreenSaver returns the current settings of the screen saver, which may be set with

XSet ScreenSaver.

A positive timeout indicates that the screen saver is enabled. A timeout of zero indicates
that the screen saver is disabled.

If the server-dependent screen saver method supports periodic change, interval serves as a
hint about the length of the change period, and zero serves as a hint that no periodic change
will be made. An interval of zero indicates that random pattern motion is disabled.

For more information on the screen saver, see Volume One, Chapter 13, Other Programming
Techniques.

Related Commands

XActivateScreenSaver, XForceScreenSaver, XResetScreenSaver, XSet-
ScreenSaver.

242 Xlib Reference Manual

Xlib -Selections-

J XGetSelectionOwner

Name

XGetSelectionOwner return the owner of a selection.

Synopsis

Window XGetSelectionOwner ( display, selection)
Display * display;
Atom selection;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

select i on Specifies the selection atom whose owner you want returned.
Description

XGetSelectionOwner returns the window ID of the current owner of the specified selec
tion. If no selection was specified, or there is no owner, the function returns the constant None,

For more information on selections, see Volume One, Chapter WJnterclient Communication.
Errors

BadAtom

Related Commands

XConvert Select ion, XSet Select ionOwner.

Xlib Reference Manual 243

X,,b-W,ndowMan ag er ,,-

Name

XGetSizeHintS read any property of type XA_SIZE_HINTS.

Synopsis

Status XGetSizeHintS ( display, w, hints, property)
Display *display;
Window w;

XSizeHints *hints; /* RETURN */
Atom property;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenD i sp 1 ay .

w Specifies the ID of the window for which size hints will be returned.

hints Returns the size hints structure.

property Specifies a property atom of type XA_WM_SIZE_HINTS. May be
XA_WM_NORMAL_HINTS, XA_WM_ZOOM_HINTS (in Release 3), or a property
defined by an application.

Description

XGetSizeHintS has been superseded by XGetWMSizeHints as of Release 4, because the
interclient communication conventions are now standard.

XGetSizeHintS returns the XSizeHints structure for the named property and the speci
fied window. This is used by XGetNormalHints and XGetZoomHints, and can be used to
retrieve the value of any property of type XA_WM_SIZE_HINTS; thus, it is useful if other proper
ties of that type get defined. This function is used almost exclusively by window managers.

XGetSizeHintS returns a nonzero Status if a size hint was defined, and zero otherwise.
For more information on using hints, see Volume One, Chapter 10, Interclient Communication.

Structures

typedef struct {

long flags; /* which fields in structure are defined */

int x, y;

int width, height;

int min_width, min_height;

int max_width, max_height;

int width_inc, height_inc;

struct {

int x; /* numerator */

int y; /* denominator */
} min_aspect, max_aspect;
} XSizeHints;

/* flags argument in size hints */

#define USPosition (1L 0) /* user specified x, y */

#define USSize (1L 1) /* user specified width, height */

244 Xlib Reference Manual

Xlib - Window Manager Hints

(continued)

XGetSizeHints

#define PPosition (1L 2) /* program specified position */

#define PSize (1L 3) A

tdefine PMinSize (1L 4) /

#define PMaxSize (1L 5) /

tfdefine PResizelnc (1L 6) /

#define PAspect (1L 7) /

program specified size */
program specified minimum size */
program specified maximum size */
program specified resize increments */
program specified min/max aspect ratios */

tdefine PAllHints (PPosition | PSize I PMinSize I PMaxSize I PResizelnc I PAspect)

Errors

BadAtom
BadWindow

Related Commands

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal-
Hints, XGetTransientForHint, XGetWMHints, XGetZoomHints, XSetClass-
Hint, XSet Command, XSetlconName, XSetlconSizes, XSetNormalHints, XSet-
SizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints, XStore-
Name.

Xlib Reference Manual

245

XGetStandardColormap \ X1|b _ Colormaps _

Name

XGetStandardColormap get the standard colormap property.

Synopsis

Status XGetStandardColormap ( display, w, cmap_info, property)
Display * display;
Window w;

XStandardColormap *cmap_info; /* RETURN */
Atom property;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenD i sp 1 ay .

w Specifies the ID of the window on which the property is set. This is normally

the root window.

cmap_info Returns the filled colormap information structure.

property Specifies the atom indicating the type of standard colormap desired. The
predefined standard colormap atoms are XA_RGB_BEST_MAP,

XA_RGB_RED_MAP, XA_RGB_GREEN_MAP, XA_RGB_BLUE_MAP ,
XA_RGB_DEFAULT_MAP, and XA_RGB_GRAY_MAP .

Description

XGetStandardColormap is superseded by XGetWMColormap in Release 4.

XGetStandardColormap gets a property on the root window that describes a standard
colormap.

This call does not install the colormap into the hardware colormap, it does not allocate entries,
and it does not even create a virtual colormap. It just provides information about one design of
colormap and the ID of the colormap if some other client has already created it. The applica
tion can otherwise attempt to create a virtual colormap of the appropriate type, and allocate its
entries according to the information in the XStandardColormap structure. Installing the
colormap must then be done with XlnstallColormap, in cooperation with the window
manager. Any of these steps could fail, and the application should be prepared.

If the server or another client has already created a standard colormap of this type, then its ID
will be returned in the colormap member of the XStandardColormap structure. Some
servers and window managers, particular on high-performance workstations, will create some
or all of the standard colormaps so they can be quickly installed when needed by applications.

An application should go through the standard colormap creation process only if it needs the
special qualities of the standard colormaps. For one, they allow the application to convert RGB
values into pixel values quickly because the mapping is predictable. Given an XStandard
Colormap structure for an XA_RGB_BEST_MAP colormap, and floating point RGB coefficients
in the range 0.0 to 1.0, you can compose pixel values with the following C expression:

246 Xlib Reference Manual

xiib - coiormaps (continued) XGetStandardColormap

pixel = base_pixel

+ ((unsigned long) (0.5 + r * red_max) ) * red_mult

+ ((unsigned long) (0.5 + g * green_max) ) * greenjmult

+ ((unsigned long) (0.5 + b * blue_max) ) * blue_mult;

The use of addition rather than logical-OR for composing pixel values permits allocations
where the RGB value is not aligned to bit boundaries.

XGetStandardColormap returns zero if it fails, or nonzero if it succeeds.

See Volume One, Chapter 7, Color, for a complete description of standard coiormaps.

Structures

typedef struct {

Colormap colormap; /* ID of colormap created by XCreateColormap */

unsigned long red_max;

unsigned long red_mult;

unsigned long green_max;

unsigned long green_mult;

unsigned long blue_max;

unsigned long blue_mult;

unsigned long base_pixel;

/* new fields here in R4 */
} XStandardColormap;

Errors

BadAtom
BadWindow

Related Commands

Def aultColormap, Display-Cells, XCopyColormapAndFree, XCreate
Colormap, XFreeColormap, XInstallColormap, XListlnstalledColormaps,
XSetStandardColormap, XSetWindowColormap, XUninstallColormap.

Xlib Reference Manual 247

XGetSublmage \ xnt &gt;. tmages -

Name

XGetSublmage copy a rectangle in drawable to a location within the pre-existing image.
Synopsis

Xlmage *XGetSubImage ( display, drawable , x, y, width, height,

plane_mask, format, dest_image, dest_x, dest_y)
Display * display;
Drawable drawable;
int x, y;

unsigned int width, height;
unsigned long plane_mask;
int format;
Xlmage *dest_image;
int dest_x, dest_y;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

drawabl e Specifies the drawable from which the rectangle is to be copied.

x Specify the x and y coordinates of the upper-left corner of the rectangle, rela-

y live to the origin of the drawable.

width Specify the width and height in pixels of the subimage taken.

height

plane_mask Specifies which planes of the drawable are transferred to the image.
format Specifies the format for the image. Either XYPixmap or ZPixmap.

dest_image Specifies the the destination image.

dest_x Specify the x and y coordinates of the destination rectangle s upper left cor-

dest_y ner, relative to the image s origin.

Description

XGetSublmage updates the dest_image with the specified subimage in the same manner
as XGet image, except that it does not create the image or necessarily fill the entire image. If
format is XYPixmap, the function transmits only the bit planes you specify in
plane_mask. If format is ZPixmap, the function transmits as zero the bits in all planes
not specified in plane_mask. The function performs no range checking on the values in
plane_mask and ignores extraneous bits.

The depth of the destination x image structure must be the same as that of the drawable.
Otherwise, a BadMatch error is generated. If the specified subimage does not fit at the speci
fied location on the destination image, the right and bottom edges are clipped. If the drawable
is a window, the window must be mapped or held in backing store, and it must be the case that,
if there were no inferiors or overlapping windows, the specified rectangle of the window would
be fully visible on the screen. Otherwise, a BadMatch error is generated.

248 Xlib Reference Manual

Xlib - Images (continued) XGetSublmage

If the window has a backing store, the backing store contents are returned for regions of the
window that are obscured by noninferior windows. Otherwise, the return contents of such
obscured regions are undefined. Also undefined are the returned contents of visible regions of
inferiors of different depth than the specified window.

XSub Image extracts a subimage from an image, instead of from a drawable like XGetSub
lmage.

For more information on images, see Volume One, Chapter 6, Drawing Graphics and Text.

Errors

BadDrawable

BadMatch Depth of dest_i/nage is not the same as depth of drawable.
BadValue

Related Commands

ImageByteOrder, XAddPixel, XCreate Image, XDestroy Image, XGet Image,
XGetPixel, XPutlmage, XPutPixel, XSublmage.

Xlib Reference Manual 249

XGetTeXtPrOperty \ x,,b-W,ndow Manager H,n,s-

Name

XGetTextProperty read one of a window s text properties.

Synopsis

Status XGetTextProperty ( display, w r text_prop f property)
Display ^display;
Window w;

XTextProperty *text_prop; /* RETURN */
Atom property;

Arguments

display Specifies a connection to an X server; returned from XQpenDisplay.

w Specifies the window.

text_prop Returns the XTextProperty structure.

property Specifies the property name.

Availability

Release 4 and later.

Description

XGetTextProperty reads the specified property from the window and stores the data in the
returned XTextProperty structure. It stores the data in the value field, the type of the data
in the encoding field, the format of the data in the format field, and the number of items of
data in the nit ems field. The particular interpretation of the property s encoding and data as
"text" is left to the calling application. If the specified property does not exist on the window,
XGetTextProperty sets the value field to NULL, the encoding field to None, the format
field to zero, and the nit ems field to zero.

If it was able to set these files in the XTextProperty structure, XGetTextProperty
returns a non-zero status; otherwise, it returns a zero status.

For more information, see Volume One, Chapter 10, Interclient Communication.
Structures

typedef struct {

unsigned char *value; /* same as Property routines */

Atom encoding; /* prop type */

int format; /* prop data format: 8, 16, or 32 */

unsigned long nitems; /* number of data items in value */
} XTextProperty;

Errors

BadAtom
BadWindow

250 xiib Reference Manual

Xlib - Window Manager Hints (continued) XGetTextPfOperty

Related Commands

XFreeStringList, XSetTextProperty, XStringListToTextProperty, XText-
PropertytoStringList.

Xlib Reference Manual 25 1

XGetTransientForHint

Name

XGetTransientForHint get the XA_WM_TRANSIENT_FOR property of a window.

Synopsis

Status XGetTransientForHint ( display, w, prop_window)
Display * display;
Window w;
Window *prop_nrindow; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

w Specifies the ID of the window to be queried.

prop_window Returns the window contained in the XA_WM_TRANSIENT_FOR property of the
specified window.

Description

XGetTransientForHint obtains the XA_WM_TRANSIENT_FOR property for the specified
window. This function is normally used by a window manager. This property should be set for
windows that are to appear only temporarily on the screen, such as pop-up dialog boxes. The
window returned is the main window to which this popup window is related. This lets the win
dow manager decorate the popup window appropriately.

XGetTransientForHint returns a Status of zero on failure, and nonzero on success.
For more information on using hints, see Volume One, Chapter W,Interclient Communication.

Errors

BadWindow

Related Commands

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal-
Hints, XGetSizeHints, XGetWMHints, XGetZoomHints, XSetClassHint, XSet-
Command, XSetlconName, XSetlconSizes, XSetNormalHints, XSetSizeHints,
XSetTransientForHint, XSetWMHints, XSetZoomHints, XStoreName.

252 Xlib Reference Manual

-xiib-visuais / XGetVisuallnfo

Name

XGetVisuallnfo find the visual information structures that match the specified template.

Synopsis

XVisuallnfo *XGetVisualInfo ( display, vinfo_mask,

vinfo_template, nitems)
Display * display ;
long vinfo_mask;
XVisuallnfo *vinfo_template;
int * nitems; /* RETURN */

Arguments

di splay Specifies a connection to an X server; returned from XOpenDisplay.

vinfo_mask Specifies the visual mask value. Indicates which elements in template are to
be matched.

vi n f o_ t empl a t e

Specifies the visual attributes that are to be used in matching the visual struc
tures.

nitems Returns the number of matching visual structures.

Description

XGetVisuallnfo returns a list of visual structures that describe visuals supported by the
server and that match the attributes specified by the vinfo_ template argument. If no
visual structures match the template, XGetVisuallnfo returns a NULL. To free the data
returned by this function, use XFree.

For more information, see Volume One, Chapter 7, Color.
Structures

typedef struct {

Visual *visuai;

VisuallD visualid;

int screen;

unsigned int depth;

int class;

unsigned long red_mask;

unsigned long green_mask;

unsigned long blue_mask;

int colormap_size;

int bits_per_rgb;
} XVisuallnfo";

/* The symbols for the vinfo_mask argument are: */

tdefine VisualNoMask 0x0

#define VisuallDMask Oxl

tfdefine VisualScreenMask 0x2

Xlib Reference Manual

XGetViSUallnfO (continued) Xlib- Visuals

#define VisualDepthMask 0x4

#define VisualClassMask 0x8

#define VisualRedMaskMask 0x10

tdefine VisualGreenMaskMask 0x20

#define VisualBlueMaskMask 0x40

#define VisualColormapSizeMask 0x80

#define VisualBitsPerRGBMask 0x100

tdefine VisualAllMask OxlFF

Related Commands

Def aultVisual, XVisuallDFromVisual, XMatchVisuallnf o, XListDepths.

254 Xlib Reference Manual

-Xlib- Window Manager Hints XGetWMICOnName

Name

XGetWMIconName read a window s XA_WM_ICON_NAME property.

Synopsis

Status XGetWMIconName ( display, w, text_prop)
Display *display;
Window w;
XTextProperty *text_prop; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XQpenDisplay.

w Specifies the window.

text_prop Returns the XTextProperty structure.

Availability

Release 4 and later.

Description

XGetWMIconName performs an XGet Text Property on the XA_WM_ICON_NAME property
of the specified window. XGetWMIconName supersedes XGetlconName.

This function is primarily used by window managers to get the name to be written in a win
dow s icon when they need to display that icon.

For more information, see Volume One, Chapter WJnterclient Communication.
Structures

typedef struct {

unsigned char *value; /* same as Property routines */

Atom encoding; /* prop type */

int format; /* prop data format: 8, 16, or 32 */

unsigned long nitems; /* number of data items in value */
} XTextProperty;

Related Commands

XGetWMName, XSetWMIconName, XSetWMName, XSetWMProperties.

Xlib Reference Manual 255

XGetWMName V

v Xlib - Window Manager Hints-
Name

XGetWMName read a window s XA_WM_NAME property.

Synopsis

Status XGetWMName ( display r w, text_prop)
Display * display;
Window w;
XTextProperty *text_prop; /* RETURN */

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenD i splay.

w Specifies the window.

text_prop Returns the XTextProperty structure.

Availability

Release 4 and later.

Description

XGetWMName performs an XGetTextProperty on the XA_WM_NAME property of the speci
fied window. XGetWMName supersedes XFetchName.

XGetWMName returns nonzero if it succeeds, and zero if the property has not been set for the
argument window.

For more information, see Volume One, Chapter WJnterclient Communication.
Structures

typedef struct {

unsigned char *value; /* same as Property routines */

Atom encoding; /* prop type */

int format; /* prop data format: 8, 16, or 32 */

unsigned long nitems; /* number of data items in value */
} XTextProperty;

Related Commands

XGetWMIconName, XSetWMIconName, XSetWMName, XSetWMProperties.

256 xiib Reference Manual

-XHb-WindowManager Hints XGetWMNormalHintS

Name

XGetWMNormalHintS read a window s XA_WM_NORMAL_HINTS property.

Synopsis

Status XGetWMNormalHintS (display, w, hints, supplied)
Display *display;
Window w;

XSizeHints *hints;/* RETURN */
long * supplied;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the window.

hints Returns the size hints for the window in its normal state.

supplied Returns the hints that were supplied by the user.

Availability

Release 4 and later.

Description

XGetWMNormalHintS returns the size hints stored in the XA_WM_NORMAL_HINTS property on
the specified window. If the property is of type XA_WM_SIZE_HINTS, of format 32, and is long
enough to contain either an old (pre-ICCCM) or new size hints structure, XGetWMNormal
HintS sets the various fields of the XSizeHints structure, sets the supplied argument to
the list of fields that were supplied by the user (whether or not they contained defined values)
and returns a non-zero status. XGetWMNormalHintS returns a zero status if the application
specified no normal size hints for this window.

XGetWMNormalHintS supersedes XGetNormalHints.

If XGetWMNormalHintS returns successfully and a pre-ICCCM size hints property is read,
the supplied argument will contain the following bits:

If the property is large enough to contain the base size and window gravity fields as well, the
supplied argument will also contain the following bits:

(PBaseSize | PWinGravity)

This function is normally used only by a window manager.

For more information, see Volume One, Chapter lOJnterclient Communication.

Structures

typedef struct {

long flags; /* marks which fields in this structure are defined */
int x, y; /* obsolete for new window mgrs, but clients */

Xlib Reference Manual 257

XGetWMNormalHintS (continued) Xlib - Window Manager Hints

int width, height; /* should set so old wm s don t mess up */
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
struct {

int x; /* numerator */

int y; /* denominator */
} min_aspect, max_aspect;

int base_width, base_height; /* added by ICCCM version I */

int win_gravity; /* added by ICCCM

version 1 */
} XSizeHints;

Errors

BadWindow

Related Commands

XAllocSizeHints, XGetWMSizeHints, XSetWMNormalHints, XSet-
WMProperties, XSetWMSizeHints.

255 Xlib Reference Manual

-Xllb- Window Manager Hints / XGetWMSizeHintS

Name

XGetWMSizeHintS read a window s XA_WM_SIZE_HINTS property.

Synopsis

Status XGetWMSizeHintS (display, w, hints, supplied, property)
Display * display;
Window w;

XSizeHints *hints; /* RETURN */

long * supplied; /*RETURN */

Atom property;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

w Specifies the window.

hints Returns the XSizeHints structure.

supplied Returns the hints that were supplied by the user.

property Specifies the property name.

Availability

Release 4 and later.

Description

XGetWMSizeHintS returns the size hints stored in the specified property on the named win
dow. If the property is of type XA_WM_SIZE_HINTS, of format 32, and is long enough to con
tain either an old (pre-ICCCM) or new size hints structure, XGetWMSizeHintS sets the vari
ous fields of the XSizeHints structure, sets the supplied argument to the list of fields that
were supplied by the user (whether or not they contained defined values), and returns a non
zero status. If the hint was not set, it returns a zero status. To get a window s normal size hints,
you can use the XGetWMNormalHints function instead.

XGetWMSizeHintS supersedes XGetSizeHints.

If XGetWMSizeHintS returns successfully and a pre-ICCCM size hints property is read, the
supplied argument will contain the following bits:

(USPosition I USSize IPPosition I P Size IPMinSize I PMaxSize I PResizelnc I P Aspect)

If the property is large enough to contain the base size and window gravity fields as well, the
supplied argument will also contain the following bits:

(PBaseSize I PWinGravity)

This function is used almost exclusively by window managers.

For more information, see Volume One, Chapter W,Interclient Communication.

Xlib Reference Manual 259

XGetWMSizeHintS (continued) Xlib - Window Manager Hints

Structures

typedef struct {

long flags; /* marks which fields in this structure are defined */

int x, y; /* obsolete for new window mgrs, but clients */

int width, height; /* should set so old wm s don t mess up */

int min_width, min_height;

int max_width, max_height;

int width_inc, height_inc;

struct {

int x; /* numerator */

int y; /* denominator */
} min_aspect, max_aspect;

int base_width, base_height; /* added by ICCCM version 1 */

int win_gravity; /* added by ICCCM version 1 */

} XSizeHints;

Errors

BadAtom
BadWindow

Related Commands

XAllocSizeHints, XGetWMNormalHints, XSetWMNormalHints, XSetWMSize-
Hints.

260 Xlib Reference Manual

XGetWindowAtlributes

Name

XGetWindow Attributes obtain the current attributes of window.
Synopsis

Status XGetWindowAt tributes (display, w, window_attributes)
Display *display;
Window w;
XWindowAttributes *window_attributes ; /* RETURN */

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the window whose current attributes you want.

window_at tributes

Returns a filled XWindowAttributes structure, containing the current attri
butes for the specified window.

Description

XGetwindowAttributes returns the XWindowAttributes structure containing the cur
rent window attributes.

While w is defined as type window, a Pixmap can also be used, in which case all the returned
members will be zero except width, height, depth, and screen.

XGetwindowAttributes returns a Status of zero on failure, or nonzero on success.
However, it will only return zero if you have defined an error handler that does not exit, using
xSetErrorHandler. The default error handler exits, and therefore XGetwindow
Attributes never gets a chance to return. (This is relevant only if you are writing a window
manager or other application that deals with windows that might have been destroyed.)

The following list briefly describes each member of the XWindowAttributes structure. For
more information, see Volume One, Chapter 4, Window Attributes.

x, y The current position of the upper-left pixel of the window s border, relative

to the origin of its parent.

width, height The current dimensions in pixels of this window.

border_width The current border width of the window.

depth The number of bits per pixel in this window.

visual The visual structure.

root The root window ID of the screen containing the window.

class The window class. One of these constants: InputOutput or Input-

Only.

bit_gravity The new position for existing contents after resize. One of the constants
ForgetGravity, StaticGravity, or CenterGravity, or one of
the compass constants (NorthWestGravity, NorthGravity, etc.).

Xlib Reference Manual 26 1

X Get Window Attributes (continued) Xlib - Window Attributes

win_gravity The new position for this window after its parent is resized. One of the
constants CenterGravity, UnmapGravity, StaticGravity, or
one of the compass constants.

backing_store When to maintain contents of the window. One of these constants: Not-
Usef ul, WhenMapped, or Always.

backing_jplanes

The bit planes to be preserved in a backing store.

backing_jpixel The pixel value used when restoring planes from a partial backing store.

save_under A boolean value, indicating whether saving bits under this window would
be useful.

colormap The colormap ID being used in this window, or None.

map_installed A boolean value, indicating whether the colormap is currently installed. If
True, the window is being displayed in its chosen colors.

map_state The window s map state. One of these constants: isUnmapped, Is-

Unviewable, or IsViewable. IsUnviewable indicates that the
specified window is mapped but some ancestor is unmapped.

a 1 l_e ve n t_ma s k s

The set of events any client have selected. This member is the bitwise
inclusive OR of all event masks selected on the window by all clients.

your_event_mask

The bitwise inclusive OR of all event mask symbols selected by the query
ing client.

do_not_propagate_mask

The bitwise inclusive OR of the event mask symbols that specify the set of
events that should not propagate. This is global across all clients.

override_redirect

A boolean value, indicating whether this window will override structure
control facilities. This is usually only used for temporary pop-up windows
such as menus. Either True or False.

screen A pointer to the Screen structure for the screen containing this window.

Errors

BadWindow

Structures

The xwindowAttributes structure contains:

typedef struct {

int x, y; /* location of window */

int width, height; /* width and height of window */

int border_width; /* border width of window */

int depth; /* depth of window */

262 Xlib Reference Manual

Xlib - Window Attributes

(continued)

XGetWindowAttributes

Visual *visual; /*

Window root; /*

int class; /*

int bit_gravity; /*

int win_gravity; /*

int backing_store; /*
unsigned long backing_planes; /*

unsigned long backing_pixel; /*

Bool save_under; /*

Colormap colormap; /*

Bool map_installed; /*

int map_state; /*

long all_event_masks; /*

long your_event_mask; /*

long do_not_propagate_mask; /*

Bool override_redirect; /*

Screen *screen; /*
} XWindowAttributes;

the associated visual structure */
root of screen containing window */
InputOutput, InputOnly*/
one of bit gravity values */
one of the window gravity values */
NotUseful, WhenMapped, Always */
planes to be preserved if possible */
value to be used when restoring planes */
boolean, should bits under be saved */
colormap to be associated with window */
boolean, is colormap currently installed*/
IsUnmapped, IsUnviewable, IsViewable */
set of events all people have interest in*/
my event mask */

set of events that should not propagate */
boolean value for override-redirect */
pointer to correct screen */

Related Commands

XChangeWindowAttributes, XGetGeometry, XSetWindowBackground, XSet-
WindowBackgroundPixmap, XSetWindowBorder, XSetWindowBorderPixmap.

Xlib Reference Manual

263

XGetWindowProperty \ X)|b _ Propartl8s _

Name

XGetWindowProperty obtain the atom type and property format for a window.

Synopsis

int XGetWindowProperty ( display, w, property, long_offset,

long_length, delete, req_type, actual_type, actual_for-
mat , nit ems , bytes_after , prop)
Display *display;
Window w;
Atom property;

long long_offset , long_length;
Bool delete;
Atom req_type;

Atom *actual_type; /* RETURN */

int *actual_format; /* RETURN */

unsigned long *nitems; /* RETURN */

unsigned long *bytes_after; /* RETURN */
unsigned char **prop; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window whose atom type and property format you

want to obtain.

property Specifies the atom of the desired property.

1 ong_offset Specifies the offset in 32-bit quantities where data will be retrieved.

1 ong_length Specifies the length in 32-bit multiples of the data to be retrieved.

delete Specifies a boolean value of True or False. If you pass True and a prop

erty is returned, the property is deleted from the window after being read and
a PropertyNotif y event is generated on the window.

req_type Specifies an atom describing the desired format of the data. If Any-
Proper tyType is specified, returns the property from the specified window
regardless of its type. If a type is specified, the function returns the property
only if its type equals the specified type.

actual_type Returns the actual type of the property.

actual_for/nat

Returns the actual data type of the returned data.

ni terns Returns the actual number of 8-, 16-, or 32-bit items returned in prop.

bytes_after Returns the number of bytes remaining to be read in the property if a partial
read was performed.

264 Xlib Reference Manual

xiib - Properties (continued) XGetWindowProperty

prop Returns a pointer to the data actually returned, in the specified format.

XGetWindowProperty always allocates one extra byte after the data and
sets it to NULL. This byte is not counted in nit ems.

Description

XGetWindowProperty gets the value of a property if it is the desired type. XGetwindow-
P rope rt y sets the return arguments acccording to the following rules:

If the specified property does not exist for the specified window, then: act ual_ type is
None; act ual_format = 0; and bytes_af ter = 0. delete is ignored in this
case, and nit ems is empty.

If the specified property exists, but its type does not match req_type, then:
actual_type is the actual property type; actual_format is the actual property
format (never zero); and bytes_after is the property length in bytes (even if
actual_format is 16 or 32). delete is ignored in this case, and ni terns is empty.

If the specified property exists, and either recj_type is AnyPropertyType or the
specified type matches the actual property type, then: actual_type is the actual prop
erty type; and actual_format is the actual property format (never zero).
jbytes_ar"ter and nit ems are defined by combining the following values:

N = actual length of stored property in bytes (even if act ual_format is 16 or 3 2)
1 = 4* 1 on g_off set (convert offset from longs into bytes)
L = MINIMUM* (N - I), 4 * long_length) (BadValue if L &lt; 0)
bytes_after = N - (I + L) (number of trailing unread bytes in stored property)

The returned data (in prop) starts at byte index I in the property (indexing from 0). The
actual length of the returned data in bytes is L. L is converted into the number of 8-, 16-,
or 32-bit items returned by dividing by 1, 2, or 4 respectively and this value is returned in
nitems. The number of trailing unread bytes is returned in by t es_aft er.

If delete == True and bytes_after == the function deletes the property
from the window and generates a PropertyNotif y event on the window.

When XGetWindowProperty executes successfully, it returns Success. The Success
return value and the undocumented value returned on failure are the opposite of all other rou
tines that return int or Status. The value of Success is undocumented, but is zero (0) in
the current sample implementation from MIT. The failure value, also undocumented, is cur
rently one (1). Therefore, comparing either value to True or False, or using the syntax "if
( ! XGetWindowProperty ( . . . ))" is not allowed.

To free the resulting data, use XFree.

For more information, see Volume One, Chapter WJnterdient Communication.

Xlib Reference Manual 265

XGetWindOwProperty (continued) Xlib - Properties

Errors

BadAtom

BadVa lue Value of I ong_offset caused L to be negative above.
BadWindow

Related Commands

XChangeProperty, XGetAtomName, XGetFontProperty, XListProperties,
XRotateWindowProperties,XSetStandardProperties.

Xlib Reference Manual

-Xllb- Window Manager Hints / XGetWMHintS

Name

XGetWMHintS read the window manager hints property.

Synopsis

XWMHints *XGetWMHints (display, w)
Display * display;
Window w;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window to be queried.

Description

This function is primarily for window managers. XGetWMHintS returns NULL if no
XA_WM_HINTS property was set on window w, and returns a pointer to an XWMHints structure
if it succeeds. Programs must free the space used for that structure by calling XFree.

For more information on using hints, see Volume One, Chapter 10, Inter -client Communication.
Structures

typedef struct {

long flags; /* marks which fields in this structure are defined */

Bool input; /* does application need window manager for input */

int initial_state; /* see below */

Pixmap icon_pixmap; /* pixmap to be used as icon */

Window icon_window; /* window to be used as icon */

int icon x, icon y; /* initial position of icon */

Pixmap icon_mask; /* icon mask bitmap */

XID window group; /* ID of related window group */

/* this structure may be extended in the future */
} XWMHints;

/* initial state flag: */

#define DontCareState

#define NormalState 1

#define ZoomState 2

#define IconicState 3

#define InactiveState 4

Errors

BadWindow

Related Commands

XAllocWMHints, XFetchName, XGetClassHint, XGetlconName, XGetlcon-
Sizes, XGetNormalHints, XGetSizeHints, XGetTransientForHint, XGet-
ZoomHints, XSetClassHint, XSetCommand, XSetlconName, XSetlconSizes,
XSetNormalHints, XSetSizeHints, XSetTransientForHint, XSetWMHints,
XSetZoomHints, XStoreName, XSetWMProperties.

Xlib Reference Manual 267

XGetZoomHints V V1

N Xlib - Window Manager Hints-
Name

XGetZoomHints read the size hints property of a zoomed window.

Synopsis

Status XGetZoomHints (display, w, zhints)
Display *display;
Window w;
XSizeHints *zhints; /* RETURN */

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenD i sp 1 ay .

w Specifies the ID of the window to be queried.

zhints Returns a pointer to the zoom hints.

Description

XGetZoomHints is obsolete beginning in Release 4, because zoom hints are no longer
defined in the ICCCM.

XGetZoomHints is primarily for window managers. XGetZoomHints returns the size
hints for a window in its zoomed state (not normal or iconified) read from the
XA_WM_ZOOM_HINTS property. It returns a nonzero Status if it succeeds, and zero if the
application did not specify zoom size hints for this window.

For more information on using hints, see Volume One, Chapter WJnterclient Communication.
Structures

typedef struct {

long flags; /* which fields in structure are defined */

int x, y;

int width, height;

int min_width, min__height;

int max_width, max_height;

int width_inc, height_inc;

struct {

int x; /* numerator */

int y; /* denominator */
} min_aspect, max_aspect;
} XSizeHints;

/* flags argument in size hints */

tdefine USPosition (1L 0) /* user specified x, y */

#define USSize (1L 1) /* user specified width, height */

#define PPosition (1L 2) /* program specified position */

tdefine PSize (1L 3) /* program specified size */

tdefine PMinSize (1L 4) /* program specified minimum size */

#define PMaxSize (1L 5) /* program specified maximum size */

#define PResizelnc (1L 6) /* program specified resize increments */

268 Xlib Reference Manual

Xlib - Window Manager Hints (continued) XGetZoom Hints

#define PAspect (1L 7) /* program specified min/max aspect ratios */
#def ine PAllHints (PPosition I PSize I PMinSize | PMaxSize I PResizelnc I PAspect)

Errors

BadWindow

Related Commands

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal-
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XSetClass-
Hint, XSetCommand, XSetlconName, XSetlconSizes, XSetNormalHints, XSet-
SizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints, XStore-
Name.

Xlib Reference Manual

269

XGrabButton V

Name

XGrabButton grab a pointer button.

Synopsis

XGrabButton ( display, button, modifiers, grab_window,

owner_events , event_mask, pointer_mode, keyboard_mode ,
confine_to, cursor)

Display *display;

unsigned int button;

unsigned int modifiers;

Window grab_window;

Bool owner_events ;

unsigned int event_mask;

int point er_mode , keyboard_mode ;

Window confine_to;

Cursor cursor;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

button Specifies the mouse button. May be Buttonl, Button2, Buttons, But-

ton4, Buttons, or AnyButton. The constant AnyButton is equivalent
to issuing the grab request for all possible buttons. The button symbols can
not be ORed.

modifiers Specifies a set of keymasks. This is a bitwise OR of one or more of the fol
lowing symbols: ShiftMask, LockMask, ControlMask, ModlMask,
Mod2Mask, ModSMask, Mod4Mask, ModSMask, or AnyModifier.
AnyModif ier is equivalent to issuing the grab key request for all possible
modifier combinations (including no modifiers).

grab_window Specifies the ID of the window you want to the grab to occur in.

owner_e vents

Specifies a boolean value of either True or False. See Description below.

event_mask Specifies the event mask to take effect during the grab. This mask is the bit
wise OR of one or more of the event masks listed on the reference page for
XSelectlnput.

point er_mode

Controls processing of pointer events during the grab. Pass one of these con
stants: GrabModeSync or GrabModeAsync.

keyboa rd_mode

Controls processing of keyboard events during the grab. Pass one of these
constants: GrabModeSync or GrabModeAsync.

confine_to Specifies the ID of the window to confine the pointer. One possible value is
the constant None, in which case the pointer is not confined to any window.

270 Xlib Reference Manual

Xlib- Grabbing (continued) XGrabButton

cursor Specifies the cursor to be displayed during the grab. One possible value you

can pass is the constant None, in which case the existing cursor is used.

Description

XGrabButton establishes a passive grab, such that an active grab may take place when the
specified key/button combination is pressed in the specified window. After this call, if

1) the specified button is pressed when the specified modifier keys are down (and no other
buttons or modifier keys are down),

2) grab_window contains the pointer,

3) the confne_to window (if any) is viewable, and

4) these constraints are not satisfied for any ancestor,

then the pointer is actively grabbed as described in XGrabPointer, the last pointer grab time
is set to the time at which the button was pressed, and the ButtonPress event is reported.

The interpretation of the remaining arguments is as for XGrabPointer. The active grab is
terminated automatically when all buttons are released (independent of the state of modifier
keys).

A modifier of AnyModif ier is equivalent to issuing the grab request for all possible modifier
combinations (including no modifiers). A button of AnyButton is equivalent to issuing the
request for all possible buttons (but at least one).

XGrabButton overrides all previous passive grabs by the same client on the same key/button
combination on the same window, but has no effect on an active grab. The request fails if some
other client has already issued an XGrabButton with the same button/key combination on the
same window. When using AnyModif ier or AnyButton, the request fails completely (no
grabs are established) if there is a conflicting grab for any combination.

The owner_e vents argument specifies whether the grab window should receive all events
(False) or whether the grabbing application should receive all events normally (True).

The pointer_mode and keyboard_mode control the processing of events during the grab.
If either is GrabModeSync, events for that device are not sent from the server to Xlib until
XAllowEvent s is called to release the events. If either is GrabModeAsync, events for that
device are sent normally.

An automatic grab takes place between a ButtonPress event and the corresponding
ButtonRelease event, so this call is not necessary in some of the most common situations.
But this call is necessary for certain styles of menus.

For more information on grabbing, see Volume One, Chapter 9, The Keyboard and Pointer.

Xlib Reference Manual 271

XGrabButton

(continued)

Xlib- Grabbing

Errors

BadAccess When using AnyModif ier or AnyButton and there is a conflicting grab
by another client. No grabs are established.

Another client has already issued an XGrabButton request with the same
key/button combination on the same window.

BadCursor

BadValue

BadWindow

Related Commands

XChangeActivePointerGrab, XGrabKey, XGrabKeyboard, XGrabPointer,
XGrabServer, XUngrabButton, XUngrabKey, XUngrabKeyboard, XUngrab-
Pointer, XUngrabServer.

272

Xlib Reference Manual

-xiib- Grabbing / XGrabKey

Name

XGrabKey grab a key.

Synopsis

XGrabKey (display, keycode, modifiers, grab_window ,
owner_events, pointer_mode , keyboard_mode)
Display *display;
int keycode ;
unsigned int modifiers;
Window grab_window;
Bool owner_events ;
int pointer_mode , keyboard_mode ;

Arguments

display Specifies a connection to an X server; returned from xopenDisplay.

keycode Specifies the keycode to be grabbed. It may be a modifier key. Specifying

AnyKey is equivalent to issuing the request for all key codes.

modifiers Specifies a set of keymasks. This is a bitwise OR of one or more of the fol
lowing symbols: ShiftMask, LockMask, ControlMask, ModlMask,
Mod2Mask, Mod3Mask, Mod4Mask, ModSMask, or AnyModifier.
AnyModif ier is equivalent to issuing the grab key request for all possible
modifier combinations (including no modifiers). All specified modifiers do
not need to have currently assigned keycodes.

gr a &gt;_ window Specifies the window in which the specified key combination will initiate an
active grab.

owner_events

Specifies whether the grab window should receive all events (True) or
whether the grabbing application should receive all events normally
(False).

point er_mode

Controls processing of pointer events during the grab. Pass one of these con
stants: GrabModeSync or GrabModeAsync.

keyboa rd_mode

Controls processing of keyboard events during the grab. Pass one of these
constants: GrabModeSync or GrabModeAsync.

Description

XGrabKey establishes a passive grab on the specified keys, such that when the specified
key/modifier combination is pressed, the keyboard may be grabbed, and all keyboard events
sent to this application. More formally, once an XGrabKey call has been issued on a particular
key /button combination:

Xlib Reference Manual 273

XGrabKey (continued) Xlib - Grabbing

IF the keyboard is not already actively grabbed,

AND the specified key, which itself can be a modifier key, is logically pressed when the
specified modifier keys are logically down,

AND no other keys or modifier keys are logically down,

AND EITHER the grab window is an ancestor of (or is) the focus window OR the grab
window is a descendent of the focus window and contains the pointer,

AND a passive grab on the same key combination does not exist on any ancestor of the
grab window,

THEN the keyboard is actively grabbed, as for XGrabKeyboard, the last keyboard grab
time is set to the time at which the key was pressed (as transmitted in the KeyPress
event), and the KeyPress event is reported.

The active grab is terminated automatically when the specified key is released (independent of
the state of the modifier keys).

The pointer_mode and keyboard_mode control the processing of events during the grab.
If either is GrabModeSync, events for that device are not sent from the server to Xlib until
XAllowEvents is called to send the events. If either is GrabModeAsync, events for that
device are sent normally.

For more information on grabbing, see Volume One, Chapter 9, The Keyboard and Pointer.

Errors

BadAccess When using AnyModif ier or AnyKey and another client has grabbed any
overlapping combinations. In this case, no grabs are established.

Another client has issued XGrabKey for the same key combination in

grab_window.

BadValue key code is not in the range between min_keycode and max_keycode
as returned by XDisplayKeycodes.

BadWindow

Related Commands

XChangeActivePointerGrab, XGrabButton, XGrabKeyboard, XGrabPointer,
XGrabServer, XUngrabButton, XUngrabKey, XUngrabKeyboard, XUngrab-
Pointer, XUngrabServer.

274 Xlib Reference Manual

Xlib -Grabbing-

J XGrabKeyboard

Name

XGrabKeyboard grab the keyboard.

Synopsis

int XGrabKeyboard (display, grab_window, owner_events,

point er_mode, keyboard_mode, time)
Display *display;
Window grab_window;
Bool o wner_e vents;
int pointer_mode, keyboard_mode ;
Time time;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

grab_window Specifies the ID of the window that requires continuous keyboard input.

owner_e vents

Specifies a boolean value of either True or False. See Description below.

point er_mode

Controls processing of pointer events during the grab. Pass either Grab-
ModeSync or GrabModeAsync.

k eyb oard_mode

Controls processing of keyboard events during the grab. Pass either Grab-
ModeSync or GrabModeAsync.

time Specifies the time when the grab should take place. Pass either a timestamp,

expressed in milliseconds, or the constant Cur rent Time.

Description

XGrabKeyboard actively grabs control of the main keyboard. Further key events are
reported only to the grabbing client. This request generates Focus In and FocusOut events.

XGrabKeyboard processing is controlled by the value in the cw/jer_ events argument:
If owner_events is False, all generated key events are reported to grab_window.

If owner_events is True, then if a generated key event would normally be reported
to this client, it is reported normally. Otherwise the event is reported to grab_window.

Both KeyPress and KeyRelease events are always reported, independent of any
event selection made by the client.

XGrabKeyboard processing of pointer events and keyboard events are controlled by
poir7ter_modeand A:eyboard_/node:

If the pointer_mode or keyboard_mode is GrabModeAsync, event processing
for the respective device continues normally.

For keyboard_mode GrabModeAsync only: if the keyboard was currently frozen
by this client, then processing of keyboard events is resumed.

Xlib Reference Manual 275

XGrabKeyboard (continued) Xlib - Grabbing

If the ponter_mode or keyboard_mode is GrabModeSync, events for the
respective device are queued by the server until a releasing XAllowE vents request
occurs or until the keyboard grab is released as described above.

If the grab is successful, XGrabKeyboard returns the constant GrabSuccess. XGrab
Keyboard fails under the following conditions and returns the following:

If the keyboard is actively grabbed by some other client, it returns AlreadyGrabbed.
If grab_window is not viewable, it returns GrabNotViewable.

If time is earlier than the last keyboard grab time or later than the current server time, it
returns GrablnvalidTime.

If the pointer is frozen by an active grab of another client, the request fails with a status
GrabFrozen.

If the grab succeeds, the last keyboard grab time is set to the specified time, with Current-
Time replaced by the current X server time.

For more information on grabbing, see Volume One, Chapter 9, The Keyboard and Pointer.

Errors

BadValue
Badwindow

Related Commands

XChangeActivePointerGrab, XGrabButton, XGrabKey, XGrabPointer, XGrab-
Server, XUngrabButton, XUngrabKey, XUngrabKeyboard, XUngrabPointer,
XUngrabServer.

276 Xlib Reference Manual

-x -tabbing / XGrabPointer

Name

XGrabPointer grab the pointer.

Synopsis

int XGrabPointer (display, grab_window, owner_e vents,

event_mask r pointer_mode , keyboard_mode , confine_to,
cursor, time)
Display *display;
Window grab_window;
Bool owner_events ;
unsigned int event_mask;
int point er_mode, keyboard_mode;
Window confine_to;
Cursor cursor;
Time time;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

grab_window Specifies the ID of the window that should grab the pointer input independent
of pointer location.

owner_e vents

Specifies if the pointer events are to be reported normally within this applica
tion (pass True) or only to the grab window (pass False).

event_mask Specifies the event mask symbols that can be ORed together. Only events
selected by this mask, plus ButtonPress and ButtonRelease, will be
delivered during the grab. See XSelect Input for a complete list of event
masks.

point er_mode

Controls further processing of pointer events. Pass either GrabModeSync

or GrabModeAsync.

k eyb o a rd_m ode

Controls further processing of keyboard events. Pass either GrabModeSync
or GrabModeAsync.

confine_to Specifies the ID of the window to confine the pointer. One option is None, in
which case the pointer is not confined to any window.

cursor Specifies the ID of the cursor that is displayed with the pointer during the

grab. One option is None, which causes the cursor to keep its current pattern.

time Specifies the time when the grab request took place. Pass either a timestamp,

expressed in milliseconds (from an event), or the constant Cur rent Time.

Xlib Reference Manual 277

XGrabPointer (continued) Xlib- Grabbing

Description

XGrabPointer actively grabs control of the pointer. Further pointer events are only reported
to the grabbing client until XUngrabPo inter is called.

event_mask is always augmented to include ButtonPressMask and ButtonRelease-
Mask. If owner_events is False, all generated pointer events are reported to
grab_window, and are only reported if selected by event_mask. If owner_e vents is
True, then if a generated pointer event would normally be reported to this client, it is reported
normally; otherwise the event is reported with respect to the grrab_window, and is only
reported if selected by event_mask. For either value of owner_e vents, unreported events
are discarded.

point er_mode controls processing of pointer events during the grab, and keyboard_mode
controls further processing of main keyboard events. If the mode is GrabModeAsync, event
processing continues normally. If the mode is GrabModeSync, events for the device are
queued by the server but not sent to clients until the grabbing client issues a releasing
XAllowE vents request or an XUngrabPo inter request.

If a cursor is specified, then it is displayed regardless of which window the pointer is in. If no
cursor is specified, then when the pointer is in gra&gt;_window or one of its subwindows, the
normal cursor for that window is displayed. When the pointer is outside grab_window, the
cursor for grab_ window is displayed.

If a con fin e_ to window is specified, then the pointer will be restricted to that window. The
confine_to window need have no relationship to the graJb_window. If the pointer is not
initially in the confine_to window, then it is warped automatically to the closest edge (and
enter/leave events generated normally) just before the grab activates. If the conf~ine_to
window is subsequently reconfigured, the pointer will be warped automatically as necessary to
keep it contained in the window.

The time argument lets you avoid certain circumstances that come up if applications take a
long while to respond or if there are long network delays. Consider a situation where you have
two applications, both of which normally grab the pointer when clicked on. If both applica
tions specify the timestamp from the ButtonPress event, the second application will suc
cessfully grab the pointer, while the first will get a return value of AlreadyGrabbed, indicat
ing that the other application grabbed the pointer before its request was processed. This is the
desired response because the latest user action is most important in this case.

XGrabPointer generates EnterNotif y and LeaveNotif y events.

If the grab is successful, it returns the constant GrabSuccess. The XGrabPointer func
tion fails under the following conditions, with the following return values:

If grab_window or conf~ine_to window is not viewable, or if the conf ine_to
window is completely off the screen, GrabNotviewable is returned.

If the pointer is actively grabbed by some other client, the constant AlreadyGrabbed
is returned.

If the pointer is frozen by an active grab of another client, GrabFrozen is returned.

278 Xlib Reference Manual

Xllb - Grabbing (continued) XGrabPointer

If the specified time is earlier than the last-pointer-grab time or later than the current X
server time, GrablnvalidTime is returned. (If the call succeeds, the last pointer grab
time is set to the specified time, with the constant CurrentTime replaced by the cur
rent X server time.)

For more information on grabbing, see Volume One, Chapter 9, The Keyboard and Pointer.

Errors

BadCursor

BadValue

BadWindow

Related Commands

XChangeActivePointerGrab, XGrabButton, XGrabKey, XGrabKeyboard,
XGrabServer, XUngrabButton, XUngrabKey, XUngrabKeyboard, XUngrab-
Pointer, XUngrabServer.

Xlib Reference Manual 279

XGrabServer

Xllb - Grabbing

Name

XGrabServer grab the server.

Synopsis

XGrabServer (display)
Display * display ;

Arguments

display Specifies a connection to an X server; returned from xopenDisplay.

Description

Grabbing the server means that only requests by the calling client will be acted on. All others
will be queued in the server until the next XUngrabServer call. The X server should not be
grabbed any more than is absolutely necessary.

Related Commands

XChangeActivePointerGrab, XGrabButton, XGrabKey, XGrabKeyboard,
XGrabPointer, XUngrabButton, XUngrabKey, XUngrabKeyboard, XUngrab-
Pointer, XUngrabServer.

Xlib Reference Manual

-Xlib - Window Manager Hints / XlCOPify WindOW

Name

XlconifyWindow request that a top-level window be iconified.

Synopsis

Status XlconifyWindow (display, w, screen_number)
Display * display;
Window w;
int screen_n umber;

Arguments

display Specifies a connection to an X server; returned from xopenDisplay.

w Specifies the window.

s c r e en_n umbe r

Specifies the appropriate screen number on the server.

Availability

Release 4 and later.

Description

XlconifyWindow sends a WM_CHANGE_STATE ClientMessage event with a format of 32
and a first data element of Iconics t ate (as described in Section 4.1.4 of the Inter-Client
Communication Conventions Manual in Volume Zero, X Protocol Reference Manual), to the
root window of the specified screen. Window managers may elect to receive this message and,
if the window is in its normal state, may treat it as a request to change the window s state from
normal to iconic. If the WM_CHANGE_STATE property cannot be interned, XlconifyWindow
does not send a message and returns a zero status. It returns a nonzero status if the client mes
sage is sent successfully; otherwise, it returns a zero status.

For more information, see Volume One, Chapter WJnterclient Communication.

Errors

BadWindow

Related Commands

XReconfigureWindow, XWithdrawWindow.

Xlib Reference Manual 28 1

Xlf EVent V xilb - input Hand.ing-

Name

XlfEvent wait for event matched in predicate procedure.

Synopsis

XlfEvent ( display , event, predicate, args)
Display *dsplay;

XEvent * event; /* RETURN */

Bool (*predicate) () ;
char *args;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

event Returns the matched event.

predicate Specifies the procedure to be called to determine if the next event satisfies
your criteria.

args Specifies the user- specified arguments to be passed to the predicate proce

dure.

Description

XlfEvent checks the event queue for events, uses the user-supplied routine to check if one
meets certain criteria, and removes the matching event from the input queue. XlfEvent
returns only when the specified predicate procedure returns True for an event. The specified
predicate is called once for each event on the queue until a match is made, and each time an
event is added to the queue, with the arguments display, event, and arg.

If no matching events exist on the queue, XlfEvent flushes the request buffer and waits for an
appropriate event to arrive. Use XChecklf Event if you don t want to wait for an event.

For more information, see Volume One, Chapter 8, Events.
Related Commands

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped-
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEvent sQueued,
XGetlnputFocus, XGetMotionEvents, XMaskEvent, XNextEvent, XPeekEvent,
XPeeklf Event, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSet-
InputFocus, XSynchronize, XWindowEvent.

282 Xlib Reference Manual

Xlib - Resource Manager-

J XlnsertModifiermapEntry

Name

XlnsertModifiermapEntry add a new entry to an XModif ierKeymap structure.
Synopsis

XModif ierKeymap *XInsertModif iermapEntry (modmap,

keysym_entry, modifier)
XModif ierKeymap * modmap;
KeyCode keysym_entry ;
int modifier;

Arguments

modmap Specifies a pointer to an XModif ierKeymap structure.

ey sym_ entry

Specifies the keycode of the key to be added to modmap.

modifier Specifies the modifier you want mapped to the keycode specified in
keysym_entry. This should be one of the constants: Shif tMaplndex,
LockMapIndex, ControlMapIndex, ModlMapIndex, Mod2Map-
Index, ModSMapIndex, Mod4MapIndex, or ModSMapIndex.

Description

XlnsertModifiermapEntry returns an XModif ierKeymap structure suitable for cal
ling xsetModif ierMapping, in which the specified keycode is deleted from the set of key-
codes that is mapped to the specified modifier (like Shift or Control). Xlnsert
ModifiermapEntry does not change the mapping itself.

This function is normally used by calling XGetModif ierMapping to get a pointer to the

current XModif ierKeymap structure for use as the modmap argument to Xlnsert-

Modi f ie rmapEnt r y .

Note that the structure pointed to by modmap is freed by XlnsertModifiermapEntry. It

should not be freed or otherwise used by applications.

For a description of the modifier map, see XSetModif ierMapping.

Structures

typedef struct {

int max_keypermod; /* server s max number of keys per modifier */
KeyCode *modif iermap; /* an 8 by max_keypermod array of

* keycodes to be used as modifiers */

} XModif ierKeymap;

#define ShiftMapIndex

#define LockMapIndex 1

#define ControlMapIndex 2
#define ModlMapIndex

#define Mod2MapIndex 4

#define ModSMapIndex 5

Xlib Reference Manual

283

XlnsertModif iermapEntry (continued) Xlib - Resource Manager

fdefine Mod4MapIndex 6

tdefine ModSMapIndex 7

Related Commands

XDeleteModif iermapEntry, XFreeModif iermap, XGetKeyboardMapping,
XGetModif ierMapping, XKeycodeToKeysym, XKeysymToKeycode, XKeysymTo-
String, XLookupKeysym, XLookupString, XNewModif ierMap, XQueryKeymap,
XRebindKeySym, XRef reshKeyboardMapping, XSetModif ierMapping,
XStringToKeysym.

284 Xlib Reference Manual

Xlib- Colormaps-

j XlnstallColormap

Name

XlnstallColormap install a colormap.

Synopsis

XlnstallColormap ( display, cmap)
Display * display;
Colormap cmap;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

cmap Specifies the colormap to install.

Description

XlnstallColormap installs a virtual colormap into a hardware company. If there is only
one hardware colormap, XlnstallColormap loads a virtual colormap into the hardware
colormap. All windows associated with this colormap immediately display with their chosen
colors. Other windows associated with the old colormap will display with false colors.

If additional hardware colormaps are possible, XlnstallColormap loads the new hardware
map and keeps the existing ones. Other windows will then remain in their true colors unless the
limit for colormaps has been reached. If the maximum number of allowed hardware colormaps
is already installed, an old colormap is swapped out The MinCmapsOf Screen (screen)
and MaxCmapsOf Screen (screen) macros can be used to determine how many hardware
colormaps are supported.

If cmap is not already an installed map, a ColormapNotify event is generated on every
window having cmap as an attribute. If a colormap is uninstalled as a result of the install, a
ColormapNotify event is generated on every window having that colormap as an attribute.

Colormaps are usually installed and uninstalled by the window manager, not by clients.

At any time, there is a subset of the installed colormaps, viewed as an ordered list, called the
"required list." The length of the required list is at most the min_maps specified for each
screen in the Display structure. When a colormap is installed with XlnstallColormap it
is added to the head of the required list and the last colormap in the list is removed if necessary
to keep the length of the list at mim_maps. When a colormap is uninstalled with
XUninstallColormap and it is in the required list, it is removed from the list. No other
actions by the server or the client change the required list. It is important to realize that on all
but high-performance workstations, min_maps is likely to be 1.

If the hardware colormap is immutable, and therefore installing any colormap is impossible,
XlnstallColormap will work but not do anything.

For more information, see Volume One, Chapter 7, Color.
Errors

BadColormap

Xlib Reference Manual 285

XlnstallColormap (continued) Xlib - Colormaps

Related Commands

Def aultColormap, DisplayCells, XCopyColormapAndFree, XCreate-
Colormap, XFreeColormap, XGetStandardColormap, XListlnstalled-
Colormaps, XSetStandardColormap, XSetWindowColormap, XUninstall-
Colormap.

286

Xlib Reference Manual

-Xllb - Properties / XlntelTlAtOm

Name

XInternAtom return an atom for a given property name string.

Synopsis

Atom XInternAtom (display, property_name, only_if_exists)
Display * display;
char *property_name ;
Bool only_if_exists ;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

property_name

Specifies the string name of the property for which you want the atom. Upper
or lower case is important. The string should be in ISO LATIN- 1 encoding,
which means that the first 128 character codes are ASCII, and the second 128
character codes are for special characters needed in western languages other
than English.

only_if_exists

Specifies a boolean value: if no such property_name exists Xlntern-
Atom will return None if this argument is set to True or will create the atom
if it is set to False.

Description

XInternAtom returns the atom identifier corresponding to string proper ty_name.

If the atom does not exist, then XInternAtom either returns None (if only_if_exists is
True) or creates the atom and returns its ID (if only_if_exists is False).

The string name should be a null-terminated. Case matters: the strings "thing," "Thing," and
"thinG" all designate different atoms.

The atom will remain defined even after the client that defined it has exited. It will become
undefined only when the last connection to the X server closes. Therefore, the number of atoms
interned should be kept to a minimum.

This function is the opposite of XGetAtomName, which returns the atom name when given an
atom ID.

Predefined atoms require no call to XInternAtom. Predefined atoms are defined in
&lt;Xll/Xatom.h&gt; and begin with the prefix "XA_". Predefined atoms are the only ones that do
not require a call to XInternAtom.

Errors

BadAlloc
BadValue

Xlib Reference Manual 287

Xlntern Atom (continued) Xlib - Properties

Related Commands

XChangeProperty, XDeleteProperty, XGetAtomName, XGetFontProperty,
XGetWindowProperty, XListProperties, XRotateWindowProperties, XSet-
StandardProperties.

Xlib Reference Manual

Xlib -Regions-

/ XlntersectRegion

Name

XlntersectRegion compute the intersection of two regions.
Synopsis

XlntersectRegion (sra, srb, dr)
Region sra, srb;
Region dr; /* RETURN */

Arguments

sra Specify the two regions with which to perform the computation.

srb

dr Returns the result of the computation.

Description

XlntersectRegion generates a region that is the intersection of two regions.

Structures

Region is a pointer to an opaque structure type.

Related Commands

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion,
XOf f setRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion, XSet-
Region, XShrinkRegion, XSubtractRegion, XUnionRectWithRegion, XUnion-
Region, XXorRegion.

Xlib Reference Manual 289

XKeycodeToKeysym \ X||b Keyboard _

Name

XKeycodeToKeysym convert a key code to a keysym.

Synopsis

KeySym XKeycodeToKeysym ( display, keycode, index)
Display *display;
KeyCode keycode ;
int index;

Arguments

di spl ay Specifies a connection to an X server; returned from xopenD i sp 1 ay .

keycode Specifies the keycode.

index Specifies which keysym in the list for the keycode to return.

Description

XKeycodeToKeysym returns one of the keysyms defined for the specified keycode.
XKeycodeToKeysym uses internal Xlib tables, index specifies which keysym in the array
of keysyms corresponding to a keycode should be returned. If no symbol is defined,
XKeycodeToKeysym returns NoSymbol.

Related Commands

IsCursorKey, IsFunctionKey, IsKeypadKey, IsMiscFunctionKey, Is-
Modif ierKey, IsPFKey, XChangeKeyboardMapping, XDeleteModif iermap-
Entry, XDisplayKeycodes, XFreeModif iermap, XGetKeyboardMapping, XGet-
Modif ierMapping, XInsertModif iermapEntry, XKeysymToKeycode, XKeysym-
ToString, XLookupKeysym, XLookupString, XNewModif ierMap, XQuery-
Keymap, XRebindKeySym, XRef reshKeyboardMapping, XSetModif ierMapping,
XStringToKeysym.

290 Xlib Reference Manual

Xlib -Keyboard-

J XKeysymToKeycode

Name

XKeysymToKeycode convert a keysym to the appropriate keycode.

Synopsis

KeyCode XKeysymToKeycode (display, keysym)
Display *display;
Keysym keysym;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

keysym Specifies the keysym that is to be searched for.

Description

XKeysymToKeycode returns the keycode corresponding to the specified keysym in the cur
rent mapping. If the specified keysym is not defined for any keycode, XKeysymToKeycode
returns zero.

Related Commands

IsCursorKey, IsFunctionKey, IsKeypadKey, IsMiscFunctionKey, Is-
Modif ierKey, IsPFKey, XChangeKeyboardMapping, XDeleteModif iermap-
Entry, XDisplayKeycodes, XFreeModif iermap, XGetKeyboardMapping, XGet-
Modif ierMapping, XInsertModif iermapEntry, XKeycodeToKeysym, XKeysym-
ToString, XLookupKeysym, XLookupString, XNewModif ierMap, XQuery-
Keymap, XRebindKeySym, XRef reshKeyboardMapping, XSetModif ierMapping,
XSt r ingToKeysym.

Xlib Reference Manual 291

XKeysymToString \ XB&gt; _ Keyboard _

Name

XKeysymToString convert a keysym symbol to a string.

Synopsis

char *XKeysymToSt ring (keysym)
KeySym keysym;

Arguments

keysym Specifies the keysym that is to be converted.

Description

XKeysymToString converts a keysym symbol (a number) into a character string. The
returned string is in a static area and must not be modified. If the specified keysym is not
defined, XKeysymToString returns NULL. For example, XKeysymToString converts
XK_Shift to "Shift".

Note that XKeysymString does not return the string that is mapped to the keysym, but only a
string version of the keysym itself. In other words, even if the Fl key is mapped to the string "-
STOP" using XRebindKeysym, XKeysymToString still returns "Fl". XLookupString,
however, would return "STOP".

In Release 4, XKeysymToString can process keysyms that are not defined by the Xlib stan
dard. Note that the set of keysyms that are available in this manner and the mechanisms by
which Xlib obtains them is implementation dependent. (In the MIT sample implementation,
the resource file lusrlliblXl 1 IXKeysymDB is used starting in Release 4. The keysym name is
used as the resource name, and the resource value is the keysym value in uppercase hexade
cimal.)

Related Commands

IsCursorKey, IsFunctionKey, IsKeypadKey, IsMiscFunctionKey, Is-
Modif ierKey, IsPFKey, XChangeKeyboardMapping, XDeleteModif iermap-
Entry, XFreeModif iermap, XGetKeyboardMapping, XGetModif ierMapping,
XInsertModif iermapEntry, XKeycodeToKeysym, XKeysymToKeycode,
XLookupKeysym, XLookupString, XNewModif ierMap, XQueryKeymap, XRebind
Keysym, XRef reshKeyboardMapping, XSetModif ierMapping, XStringTo-
Keysym.

292 Xlib Reference Manual

XKIIICIient

Name

XKillClient destroy a client or its remaining resources.

Synopsis

XKillClient (display, resource)
Display * display;
XID resource;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

resource Specifies any resource created by the client you want to destroy, or the con
stant AllTemporary.

Description

If a valid resource is specified, XKillClient forces a close-down of the client that created
the resource. If the client has already terminated in either RetainPermanent or Retain-
Temporary mode, all of the client s resources are destroyed. If AllTemporary is specified
in the resource argument, then the resources of all clients that have terminated in Retain-
Temporary are destroyed.

For more information, see Volume One, Chapter 13, Other Programming Techniques.

Errors

BadValue

Related Commands

XSetCloseDownMode.

Xlib Reference Manual 293

XLiStDepthS \ x,ib-W,ndowM a na g erH,ms-

Name

XListDepths determine the depths available on a given screen.

Synopsis

int *XListDepths (display, screen_n umber, count)
Display *display;
int screen_n umber;
int * count; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

s c r e en_n umb e r

Specifies the appropriate screen number on the host server.

count Returns the number of depths.

Availability

Release 4 and later.

Description

XListDepths returns the array of depths that are available on the specified screen. If the
specified screen_n umber is valid and sufficient memory for the array can be allocated,
XListDepths sets count to the number of available depths. Otherwise, it does not set
count and returns NULL. To release the memory allocated for the array of depths, use XFree.

Related Commands

DefaultDepthOf Screen macro, Def aultDepth macro, XListPixmapFormats.

294 Xlib Reference Manual

-Xlib- Extensions / XLiStExtensiOHS

Name

XListExtensions return a list of all extensions to X supported by Xlib and the server.

Synopsis

char **XListExtensions ( display, nextensions)
Display *disp_Zay;
int *nextensions; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

nextensions Returns the number of extensions in the returned list.

Description

XListExtensions lists all the X extensions supported by Xlib and the current server. The
returned strings will be in ISO LATIN- 1 encoding, which means that the first 128 character
codes are ASCII, and the second 128 character codes are for special characters needed in west
ern languages other than English.

For more information on extensions, see Volume One, Chapter 13, Other Programming Tech
niques.

Related Commands

XFreeExtensionList, XQueryExtension.

Xlib Reference Manual 295

XListFonts "\

Xlib- Fonts-

Name

XListFonts return a list of the available font names.

Synopsis

char **XListFonts ( display, pattern, maxnames, actual_count)
Display * display;
char * pattern;
int maxnames ;
int * actual_count ; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

pattern Specifies the string associated with the font names you want returned. You

can specify any string, including asterisks (*), and question marks. The aster
isk indicates a wildcard for any number of characters and the question mark
indicates a wildcard for a single character. Upper or lower case is not impor
tant. The string should be in ISO LATIN- 1 encoding, which means that the
first 128 character codes are ASCII, and the second 128 character codes are
for special characters needed in western languages other than English.

maxnames Specifies the maximum number of names that are to be in the returned list.

actual_count

Returns the actual number of font names in the list.

Description

XListFonts returns a list of font names that match the string pattern. Each returned font
name string is terminated by NULL and is lower case. The maximum number of names returned
in the list is the value you passed to maxnames. The function returns the actual number of
font names in actual_count.

If no fonts match the specified names, XListFonts returns NULL.

The client should call XFreeFontNames when done with the font name list.

The font search path (the order in which font names in various directories are compared to
pat tern) is set by XSetFontPath.

For more information on fonts, see Volume One, Chapter 6, Drawing Graphics and Text.
Related Commands

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XFree-
FontPath, XGetFontPath, XGetFontProperty, XListFontsWithlnf o, XLoad-
Font, XLoadQueryFont, XQueryFont, XSetFont, XSetFontPath, XUnloadFont.

296 Xlib Reference Manual

-xnb- Fonts J XListFontsWithlnfo

Name

XListFontsWithlnfo obtain the names and information about loaded fonts.

Synopsis

char **XListFontsWithInfo( display, pattern, maxnames,

count, info)
Display *disp_Zay;

char *pattern; /* null-terminated */

int maxnames;

int * count; /* RETURN */

XFontStruct **info; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

pattern Specifies the string associated with the font names you want returned. You

can specify any string, including asterisks (*) and question marks. The aster
isk indicates a wildcard on any number of characters and the question mark
indicates a wildcard on a single character. Upper or lower case is not impor
tant. The string should be in ISO LATIN- 1 encoding, which means that the
first 128 character codes are ASCII, and the second 128 character codes are
for special characters needed in western languages other than English.

maxnames Specifies the maximum number of names that are to be in the returned list.
count Returns the actual number of matched font names.

info Returns a pointer to a list of font information structures. XListFonts

Withlnfo provides enough space for maxnames pointers.

Description

XListFontsWithlnfo returns a list of font names that match the specified pattern and a
also returns limited information about each font that matches. The list of names is limited to
the size specified by the maxnames argument The list of names is in lower case.

XListFontsWithlnfo returns NULL if no matches were found.

To free the allocated name array, the client should call XFreeFont Names. To free the font
information array, the client should call XFreeFont Info.

The information returned for each font is identical to what XQueryFont would return, except
that the per-character metrics (Ibearing, rbearing, width, ascent, descent for
single characters) are not returned.

The font search path (the order in which font names in various directories are compared to
pattern) is set by XSetFontPath. XListFonts returns NULL if no matches were found.

For more information on fonts, see Volume One, Chapter 6, Drawing Graphics and Text.

Xlib Reference Manual 297

XListFontsWithlnfo

(continued)

Xlib - Fonts

Structures

typedef struct {

XExtData *ext_data; /*

Font fid; /*

unsigned direction; /*
unsigned min_char_or_byte2; /*
unsigned max_char_or_byte2; /*

unsigned min bytel; /*

unsigned max_bytel; /*

Bool all_chars exist; /*

unsigned default_char; /*

int n_properties; /*

XFontProp *properties; /*

XCharStruct min bounds; /*

XCharStruct max_bounds; /*

XCharStruct *per_char; /*

int ascent; /*

int descent; /*

} XFontStruct;

hook for extension to hang data */

Font ID for this font */

hint about direction the font is painted */

first character */

last character */

first row that exists */

last row that exists */

flag if all characters have nonzero size*/

char to print for undefined character */

how many properties there are */

pointer to array of additional properties*/

minimum bounds over all existing char*/

first_char to last_char information */

logical extent above baseline for spacing */

logical descent below baseline for spacing */

Related Commands

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XFree-
FontPath, XGetFontPath, XGetFontProperty, XListFonts, XLoadFont,
XLoadQueryFont, XQueryFont, XSetFont, XSetFontPath, XUnloadFont.

298

Xlib Reference Manual

_X,ib - Host Access / XLJStHOStS

Name

XListHosts obtain a list of hosts having access to this display.

Synopsis

XHost Address *XListHosts (display, nhosts, state)
Display * display ;

int *nhosts; /* RETURN */

Bool *state; /* RETURN */

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenD i sp 1 ay .

nhosts Returns the number of hosts currently in the access control list.

state Returns whether the access control list is currently being used by the server to

process new connection requests from clients. True if enabled, False if
disabled.

Description

XListHosts returns the current access control list as well as whether the use of the list is
enabled or disabled. XListHosts allows a program to find out what machines make connec
tions, by looking at a list of host structures. This XHost Address list should be freed when it
is no longer needed. XListHosts returns NULL on failure.

For more information on access control lists, see Volume One, Chapter 13, Other Programming
Techniques,

Structures

typedef struct {

int family;

int length;

char *address;
} XHostAddress;

Related Commands

XAddHost, XAddHosts, XDisableAccessControl, XEnableAccessControl,
XRemoveHost, XRemoveHosts, XSetAccessControl.

Xlib Reference Manual 2 "

XListlnstalledColormaps \ X|lb _ Colormaps _

Name

XListlnstalledColormaps get a list of installed colormaps.

Synopsis

Colormap *XListInstalledColormaps ( display, w, num)
display * display ;
Window w;
int *num; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window for whose screen you want the list of currently

installed colormaps.

num Returns the number of currently installed colormaps in the returned list.

Description

XListlnstalledColormaps returns a list of the currently installed colormaps for the
screen containing the specified window. The order in the list is not significant. There is no dis
tinction in the list between colormaps actually being used by windows and colormaps no longer
in use which have not yet been freed or destroyed.

XListlnstalledColormaps returns None and sets num to zero on failure.

The allocated list should be freed using XFree when it is no longer needed.

For more information on installing colormaps, see Volume One, Chapter 7, Color.

Errors

BadWindow

Related Commands

Def aultColormap, DisplayCells, XCopyColormapAndFree, XCreate-
Colormap, XFreeColormap, XGetStandardColormap, XInstallColormap,
XSetStandardColormap, XSetWindowColormap, XUninstallColormap.

300 Xlib Reference Manual

-Xllb- Window Manager Hints / XLJStPixmapFormatS

Name

XListPixmapFormats obtain the supported pixmap formats for a given server.

Synopsis

XPixmapFormat Values *XListPixmapFormats { display, count)
Display ^display;
int * count; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

count Returns the number of pixmap formats that are supported by the server.

Availability

Release 4 and later.

Description

XListPixmapFormats returns an array of XPixmapFormatValues structures that
describe the types of Z format images that are supported by the specified server. If insufficient
memory is available, XListPixmapFormats returns NULL. To free the allocated storage for
the XPixmapFormatValues structures, use XFree.

Structures

typedef struct {

int depth;

int bits_per_pixel;

int scanline_pad;
} XPixmapFormatValues;

Related Commands

XListDepths.

Xlib Reference Manual 30 1

XListProperties \,

^ Xlib - Properties-
Name

XListProperties get the property list for a window.

Synopsis

Atom *XListProperties ( display, w, num_prop)
Display *display;
Window w;
int *num_jprop; /* RETURN */

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenD i sp 1 ay .

w Specifies the window whose property list you want.

num_prop Returns the length of the properties array.

Description

XListProperties returns a pointer to an array of atoms for properties that are defined for
the specified window. XListProperties returns NULL on failure (when window w is inva
lid).

To free the memory allocated by this function, use XFree.

For more information, see Volume One, Chapter IQJnterclient Communication.

Errors

BadWindow

Related Commands

XChangeProperty, XDeleteProperty, XGetAtomName, XGetFontProperty,
XGetWindowProperty, XInternAtom, XRotateWindowProperties, XSet-
StandardProperties.

302 Xlib Reference Manual

-xiib - Fonts / XLoadFont

Name

XLoadFont load a font if not already loaded; get font ID.

Synopsis

Font XLoadFont (display, name)
Display *display;
char *name;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenD i splay.

name Specifies the name of the font in a null terminated string. As of Release 4, the

* and ? wildcards are allowed and may be supported by the server. Upper or
lower case is not important. The string should be in ISO LATIN- 1 encoding,
which means that the first 128 character codes are ASCII, and the second 128
character codes are for special characters needed in western languages other
than English.

Description

XLoadFont loads a font into the server if it has not already been loaded by another client.
XLoadFont returns the font ID or, if it was unsuccessful, generates a BadName error. When
the font is no longer needed, the client should call xunloadFont. Fonts are not associated
with a particular screen. Once the font ID is available, it can be set in the font member of any
GC, and thereby used in subsequent drawing requests.

Font information is usually necessary for locating the text. Call XLoadFontwithinf o to
get the info at the time you load the font, or call XQueryFont if you used XLoadFont to
load the font.

For more information on fonts, see Volume One, Chapter 6, Drawing Graphics and Text.

Errors

BadAlloc Server has insufficient memory to store font.

BadName name specifies an unavailable font

Related Commands

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XFree-
FontPath, XGetFontPath, XGetFontProperty, XListFonts, XListFontsWith-
Inf o, XLoadQueryFont, XQueryFont, XSetFont, XSetFontPath, XUnloadFont.

Xlib Reference Manual 303

XLoadQueryFont , x,,b- F on,s-

Name

XLoadQueryFont load a font and fill information structure.

Synopsis

XFontStruct *XLoadQueryFont ( display, name)
Display *display;
char *name;

Arguments

display Specifies a connection to an X server; returned from xopenDisplay.

name Specifies the name of the font. This name is a null terminated string. As of

Release 4, the * and ? wildcards are allowed and may be supported by the
server. Upper or lower case is not important.

Description

XLoadQueryFont performs an XLoadFont and XQueryFont in a single operation. XLoad
QueryFont provides the easiest way to get character-size tables for placing a proportional font.
That is, XLoadQueryFont both opens (loads) the specified font and returns a pointer to the
appropriate XFontStruct structure. If the font does not exist, XLoadQueryFont returns NULL.

The XFontStruct structure consists of the font-specific information and a pointer to an array
of xchar struct structures for each character in the font.

For more information on fonts, see Volume One, Chapter 6, Drawing Graphics and Text.

Errors

BadAl loc server has insufficient memory to store font

BadName name specifies an unavailable font

Structures

typedef struct {

XExtData *ext_data; /* hook for extension to hang data */

Font fid; /* Font ID for this font */

unsigned direction; /* hint about direction the font is painted */

unsigned min_char_or_byte2; /* first character */

unsigned max_char_or_byte2; /* last character */

unsigned min_bytel; /* first row that exists */

unsigned max_bytel; /* last row that exists */

Bool all_chars_exist; /* flag if all characters have nonzero size*/

unsigned default_char; /* char to print for undefined character */

int n_properties; /* how many properties there are */

XFontProp *properties; /* pointer to array of additional properties*/

XCharStruct min_bounds; /* minimum bounds over all existing char*/

XCharStruct max_bounds; /* minimum bounds over all existing char*/

XCharStruct *per_char; /* first_char to last_char information */

int ascent; /* logical extent above baseline for spacing */

int descent; /* logical descent below baseline for spacing */

} XFontStruct;

304 Xlib Reference Manual

Xlib - Fonts

(continued)

XLoadQueryFont

typedef struct {

short Ibearing; /*

short rbearing; /*

short width; /*

short ascent; /*

short descent; /*
unsigned short attributes; /*

} XCharStruct;

origin to left edge of character */
origin to right edge of character */
advance to next char s origin */
baseline to top edge of character */
baseline to bottom edge of character
per char flags (not predefined) */

Related Commands

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XFree-
FontPath, XGetFontPath, XGetFontProperty, XListFonts, XListFontsWith-
Info, XLoadFont, XQueryFont, XSetFont, XSetFontPath, XUnloadFont.

Xlib Reference Manual

305

XLookllpAssoc A

XI ib - Association Tables

Name

XLookUpAssoc obtain data from an association table.

Synopsis

caddr_t XLookUpAssoc ( display, table, x_id)
Display *display;
XAssocTable * table;
XID x_id;

Arguments

di spl ay Specifies a connection to an X server; returned from XQpenD i sp 1 ay .

t abl e Specifies the association table.

x_i d Specifies the X resource ID.

Description

This function is provided for compatibility with X Version 10. To use it you must include the
file &lt;XlllX10.h&gt; and link with the library -loldX.

Association tables provide a way of storing data locally and accessing by ID. XLookUp
Assoc retrieves the data stored in an XAssocTable by its XID. If the matching XID can be
found in the table, the routine returns the data associated with it. If the x_i d cannot be found
in the table the routine returns NULL.

For more information on association tables, see Volume One, Appendix B,X10 Compatibility.
Structures

typedef struct {

XAssoc ^buckets; /* pointer to first bucket in bucket array */
int size; /* table size (number of buckets) */

} XAssocTable;

typedef struct _XAssoc {

struct _XAssoc *next; /* next object in this bucket */

struct _XAssoc *prev; /* previous object in this bucket */

Display *display; /* display which owns the ID */

XID x_id; /* X Window System ID */

char *data; /* pointer to untyped memory */

} XAssoc;

Related Commands

XCreateAssocTable, XDeleteAssoc, XDestroyAssocTable, XMakeAssoc.

306 Xlib Reference Manual

Xllb- Color Cells-

j XLookupColor

Name

XLookupColor get database RGB values and closest hardware-supported RGB values from
color name.

Synopsis

Status XLookupColor ( display, cmap f colorname, rgb_db_def f

hardware_def)
Display ^display;
Colormap cmap ;
char * colorname ;
XColor *rgb_db_def r *hardware_def ; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

cmap Specifies the colormap.

colorname Specifies a color name string (for example "red"). Upper or lower case

does not matter. The string should be in ISO LATIN 1 encoding, which
means that the first 128 character codes are ASCII, and the second 128
character codes are for special characters needed in western languages
other than English.

rgb_db_def Returns the exact RGB values for the specified color name from the
lusrlliblXlllrgb database.

hardware_def Returns the closest RGB values possible on the hardware.

Description

XLookupColor looks up RGB values for a color given the colorname string. It returns both
the exact color values and the closest values possible on tthe screen specified by cmap.

XLookupColor returns nonzero if colorname exists in the RGB database or zero if it does
not exist.

To determine the exact RGB values, XLookupColor uses a database on the X server. On
UNIX, this database is lusrlliblXlllrgb, To read the colors provided by the database on a
UNIX-based system, see lusrlliblXlllrgb.txt. The location, name, and contents of this file are
server-dependent.

For more information see Volume One, Chapter 7, Color, and Appendix D, The Color Data
base, in this volume.

Xlib Reference Manual

307

XLOQkupColor (continued) Xlib - Color Cells

Errors

BadName Color name not in database.

BadColormap Specified colormap invalid.
Structures

typedef struct {

unsigned long pixel;

unsigned short red, green, blue;

char flags; /* DoRed, DoGreen, DoBlue */

char pad;
} XColor;

Related Commands

BlackPixel, WhitePixel, XAllocColor, XAllocColorCells, XAllocColor-
Planes, XAllocNamedColor, XFreeColors, XParseColor, XQueryColor,
XQueryColors, XStoreColor, XStoreColors, XStoreNamedColor.

308 Xlib Reference Manual

Xlib -Keyboard

J XLookupKeysym

Name

XLookupKeysym get the keysym corresponding to a keycode in structure.

Synopsis

KeySym XLookupKeysym ( event, index)
XKeyEvent * event ;
int index;

Arguments

event Specifies the KeyPress or KeyRelease event that is to be used.

index Specifies which keysym from the list associated with the keycode in the event to

return. These correspond to the modifier keys, and the symbols ShiftMap-
Index, LockMapIndex, ControlMapIndex, ModlMapIndex, Mod2-
Maplndex, ModSMapIndex, Mod4MapIndex, and ModSMapIndex can be
used.

Description

Given a keyboard event and the index into the list of keysyms for that keycode, XLookup
Keysym returns the keysym from the list that corresponds to the keycode in the event. If no
keysym is defined for the keycode of the event, XLookupKeysym returns NoSymbol.

Each keycode may have a list of associated keysyms, which are portable symbols representing
the meanings of the key. The index specifies which keysym in the list is desired, indicating
the combination of modifier keys that are currently pressed. Therefore, the program must inter
pret the state member of the XKeyEvent structure to determine the index before calling
this function. The exact mapping of modifier keys into the list of keysyms for each keycode is
server-dependent beyond the fact that the first keysym corresponds to the keycode without
modifier keys, and the second corresponds to the keycode with Shift pressed.

XLookupKeysym simply calls XKeycodeToKeysym, using arguments taken from the speci
fied event structure.

Structures

typedef struct {

int type; /* of event */

unsigned long serial; /* # of last request processed by server */

Bool send_event; /* true if this came from a SendEvent request */

Display ^display; /* display the event was read from */

Window window; /* "event" window it is reported relative to */

Window root; /* root window that the event occured on */

Window subwindow; /* child window */

Time time; /* milliseconds */

int x, y; /* pointer x, y coordinates in event window */

int x root, y root; /* coordinates relative to root */

unsigned int state; /* key or button mask */

unsigned int keycode; /* detail */

Bool same_screen; /* same screen flag */

} XKeyEvent;

Xlib Reference Manual 309

XLOQkupKeysym (continued) Xlib - Keyboard

Related Commands

XChangeKeyboardMapping, XDeleteModif iermapEntry, XFreeModif iermap,
XGetKeyboardMapping, XGetModif ierMapping, XInsertModif iermapEntry,
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupString,
XNewModif ierMap, XQueryKeymap, XRebindKeysym, XRef reshKeyboard-
Mapping, XSetModif ierMapping, XStringToKeysym.

310 Xlib Reference Manual

Xlib -Keyboard

J XLookupString

Name

XLookupString map a key event to ASCH string, keysym, and ComposeStatus.

Synopsis

int XLookupString ( event, buffer, num_bytes, keysym, status)
XKeyEvent *event;

char * buffer; /* RETURN */

int num_bytes ;

KeySym * keysym; /* RETURN */

XComposeStatus *status; /* not implemented */

Arguments

event Specifies the key event to be used.

buffer Returns the resulting string.

num_bytes Specifies the length of the buffer. No more than num_bytes of translation
are returned.

keysym If this argument is not NULL, it specifies the keysym ID computed from the

event.

status Specifies the XCompose structure that contains compose key state informa

tion and that allows the compose key processing to take place. This can be
NULL if the caller is not interested in seeing compose key sequences. Not
implemented in X Consortium Xlib through Release 4.

Description

XLookupString gets an ASCH string and a keysym that are currently mapped to the keycode
in a KeyPress or KeyRelease event, using the modifier bits in the key event to deal with
shift, lock and control. The XLookupString return value is the length of the translated
string and the string s bytes are copied into buffer. The length may be greater than 1 if the
event s keycode translates into a keysym that was rebound with XRebindKeysym.

The compose status is not implemented in any release of the X Consortium version of Xlib
through Release 4.

In Release 4, XLookupString implements the new concept of keyboard groups. Keyboard
groups support having two complete sets of keysyms for a keyboard. Which set will be used
can be toggled using a particular key. This is implemented by using the first two keysyms in
the list for a key as one set, and the next two keysyms as the second set. For more information
on keyboard groups, see Volume One, Appendix G, Release Notes.

For more information on using XLookupString in general, see Volume One, Chapter 9, The
Keyboard and Pointer.

Structures

* Compose sequence status structure, used in calling XLookupString.
*/

Xlib Reference Manual 3 1 1

XLOQkupString (continued) Xlib - Keyboard

typedef struct _XComposeStatus {

char *compose_ptr; /* state table pointer */

int chars_matched; /* match state */
} XComposeStatus;

typedef struct {

int type; /* of event */

unsigned long serial; /* # of last request processed by server */

Bool send_event; /* true if this came from a SendEvent request */

isplay display; /* Display the event was read from */

Window window; /* "event" window it is reported relative to */

Window root; /* roo t window that the event occured on */

Window subwindow; /* child window */

Time time; /* milliseconds */

L x/ y; /* Pointer x, y coordinates in event window */

int x_root, y_root; /* coordinates relative to root */

unsigned int state; /* key or button mask */

unsigned int keycode; /* detail */

Bool same_screen; /* same screen flag */
} XKeyEvent;

Related Commands

XChangeKeyboardMapping,XDeleteModifiermapEntry,XFreeModifiermap

XGetKeyboardMapping,XGetModifierMa P ping,XInsertModifierma P Entry

&lt;eycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym

f ierMap, XQueryKeymap, XRebindKeySym, XRef reshKeyboard-
Mapping, XSetModif ierMapping, XStringToKeysym.

312

Xlib Reference Manual

-Xlib- Window Manipulation XLOWerWilldOW

Name

XLowerWindow lower a window in the stacking order.

Synopsis

XLowerWindow ( display, w)
Display *display;
Window w;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

w Specifies the ID of the window to be lowered.

Description

XLowerWindow lowers a window in the stacking order of its siblings so that it does not
obscure any sibling windows. If the windows are regarded as overlapping sheets of paper
stacked on a desk, then lowering a window is analogous to moving the sheet to the bottom of
the stack, while leaving its x and y location on the desk constant. Lowering a mapped window
will generate exposure events on any windows it formerly obscured.

If the override_redirect attribute of the window (see Chapter 4, Window Attributes) is
False and the window manager has selected SubstructureRedirectMask on the par
ent, then a Conf igureRequest event is sent to the window manager, and no further pro
cessing is performed. Otherwise, the window is lowered to the bottom of the stack.

LeaveNotify events are sent to the lowered window if the pointer was inside it, and
EnterNotif y events are sent to the window which was immediately below the lowered win
dow at the pointer position.

For more information, see Volume One, Chapter 14, Window Management.

Errors

BadWindow

Related Commands

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate-
SubwindowsUp, XConf igureWindow, XMoveResizeWindow, XMoveWindow,
XQueryTree, XRaiseWindow, XReparentWindow, XResizeWindow, XRestack-
Windows.

Xlib Reference Manual 313

XMakeAssoc \ X||b _ Assoc|atlon Tab|es _

Name

XMakeAssoc create an entry in an association table.

Synopsis

XMakeAssoc ( display, table, x_id f data)
Display * display;
XAssocTable * table;
XID x_id;
caddr_t data;

Arguments

display Specifies a connection to an X server; returned from xopenDi splay.

tabl e Specifies the association table in which an entry is to be made.

x_i d Specifies the X resource ID.

data Specifies the data to be associated with the X resource ID.

Description

XMakeAssoc inserts data into an XAssocTable keyed on an XID. Association tables allow
you to easily associate data with resource ID s for later retrieval. Association tables are local,
accessible only by this client.

This function is provided for compatibility with X Version 10. To use it you must include the
file &lt;Xll/X10.h&gt; and link with the library -loldX.

Data is inserted into the table only once. Redundant inserts are meaningless and cause no prob
lems. The queue in each association bucket is sorted from the lowest XID to the highest XID.

For more information, see Volume One, Appendix B,X70 Compatibility.
Structure

typedef struct {

XAssoc *buckets; /* pointer to first bucket in bucket array */
int size; /* table size (number of buckets) */

} XAssocTable;

typedef struct _XAssoc {

struct _XAssoc *next; /* next object in this bucket */

struct _XAssoc *prev; /* previous object in this bucket */

Display *display; /* display which owns the ID */

XID x_id; /* X Window System ID * /

char *data; /* pointer to untyped memory */

} XAssoc;

Related Commands

XCreateAssocTable, XDeleteAssoc, XDestroyAssocTable, XLookUpAssoc.

3 14 Xlib Reference Manual

Xlib - Window Mapping

J XMapRaised

Name

XMapRaised map a window on top of its siblings.

Synopsis

XMapRaised ( display, w)
Display * display ;
Window w;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenD i sp 1 ay .

w Specifies the window ID of the window to be mapped and raised.

Description

XMapRaised marks a window as eligible to be displayed. It will actually be displayed if its
ancestors are mapped, it is on top of sibling windows, and it is not obscured by unrelated win
dows. XMapRaised is similar to XMapWindow, except it additionally raises the specified
window to the top of the stack among its siblings. Mapping an already mapped window with
XMapRaised raises the window. See XMapWindow for further details.

For more information, see Volume One, Chapter 14, Window Management.
Errors

BadWindow

Related Commands

XMapSubwindows, XMapWindow, XUnmapSubwindows, XUnmapWindow.

Xlib Reference Manual

315

XMapSubwindows

Xlib - Window Mapping-
Name

XMapSubwindows map all subwindows of window.

Synopsis

XMapSubwindows ( display, w)
Display * display;
Window w;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

w Specifies the ID of the window whose subwindows are to be mapped.

Description

XMapSubwindows maps all subwindows of a window in top-to-bottom stacking order.
XMapSubwindows also generates an Expose event on each newly displayed window. This
is much more efficient than mapping many windows one at a time, as much of the work need
only be performed once for all of the windows rather than for each window. XMap
Subwindows is not recursive it does not map the subwindows of the subwindows.

For more information, see Volume One, Chapter 14, Window Management.
Errors

BadWindow

Related Commands

XMapRaised, XMapWindow, XUnmapSubwindows, XUnmapWindow.

316 Xlib Reference Manual

-Xlib - Window Mapping XMapWindOW

Name

XMapWindow map a window.

Synopsis

XMapWindow (display, w)
Display * display ;
Window w;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window to be mapped.

Description

XMapWindow maps a window, making it eligible for display depending on its stacking order
among its siblings, the mapping status of its ancestors, and the placement of other visible win
dows. If all the ancestors are mapped, and it is not obscured by siblings higher in the stacking
order, the window and all of its mapped subwindows are displayed.

Mapping a window that has an unmapped ancestor does not display the window but marks it as
eligible for display when its ancestors become mapped. Mapping an already mapped window
has no effect (it does not raise the window).

Note that for a top-level window, the window manager may intervene and delay the mapping of
the window. The application must not draw until it has received an Expose event on the win
dow.

If the window is opaque, XMapWindow generates Expose events on each opaque window
that it causes to become displayed. If the client first maps the window, then paints the window,
then begins processing input events, the window is painted twice. To avoid this, the client
should use either of two strategies:

1. Map the window, call XSelect Input for exposure events, wait for the first Expose
event, and repaint each window explicitly.

2. Call XSelect Input for exposure events, map, and process input events normally.
Exposure events are generated for each window that has appeared on the screen, and the
client s normal response to an Expose event should be to repaint the window.

The latter method is preferred as it usually leads to simpler programs. If you fail to wait for the
Expose event in the first method, it can cause incorrect behavior with certain window manag
ers that intercept the request.

Errors

BadWindow

Related Commands

XMapRaised, XMapSubwindows, XUnmapSubwindows, XUnmapWindow.

Xlib Reference Manual 3 1 7

XMaskEvent \ X|lb _ |nput Hand||ng _

Name

XMaskEvent remove the next event that matches mask.

Synopsis

XMaskEvent ( display, event_mask, rep)
Display *display;
long event_mask;
XEvent *rep; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

even t_mask Specifies the event mask. See XSelect Input for a complete list of the
event mask symbols that can be ORed together.

rep Returns the event removed from the input queue.

Description

XMaskEvent removes the next event in the queue which matches the passed mask. The event
is copied into an XEvent supplied by the caller. Other events in the queue are not discarded.
If no such event has been queued, XMaskEvent flushes the request buffer and waits until one
is received. Use XCheckMaskEvent if you do not wish to wait.

XMaskEvent never returns MappingNotify, SelectionClear, SelectionNotify,
or SelectionRequest events. When you specify ExposureMask it will return
GraphicsExpose or NoExpose events if those occur.

Related Commands

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped-
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued,
XGetlnputFocus, XGetMotionEvents, Xlf Event, XNextEvent, XPeekEvent,
XPeeklf Event, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSet-
InputFocus, XSynchronize, XWindowEvent.

318 Xlib Reference Manual

-x,,b-v,,ua, s / XMatchVisuallnfo

Name

XMatchVisuallnfo obtain the visual information that matches the desired depth and class.

Synopsis

Status XMatchVisuallnfo ( display, screen, depth, class, vinfo)
Display *display;
int screen ;
int depth;
int class;
XVisuallnfo *vinfo; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

screen Specifies the screen.

depth Specifies the desired depth of the visual.

class Specifies the desired class of the visual, such as Pseudocolor or True-

Color.

vinfo Returns the matched visual information.

Description

XMatchVisuallnfo returns the visual information for a visual supported on the screen that
matches the specified depth and class. Because multiple visuals that match the specified
depth and class may be supported, the exact visual chosen is undefined.

If a visual is found, this function returns a nonzero value and the information on the visual is
returned to vinfo. If a visual is not found, it returns zero.

For more information on visuals, see Volume One, Chapter 7, Color.
Structures

typedef struct {

Visual *visual;

VisuallD visualid;

int screen;

unsigned int depth;

int class;

unsigned long red_mask;

unsigned long green_mask;

unsigned long blue_mask;

int colormap_size;

int bits_per_rgb;
} XVisuallnfo;

Related Commands

Default Visual, XGetVisuallnf o.

Xlib Reference Manual

319

XMOVeReSizeWindOW . .xpb-nda. Manipulation-

Name

XMoveResizeWindow change the size and position of a window.

Synopsis

XMoveResizeWindow ( display, w, x, y, width, height)
Display *display;
Window w;
int x, y;
unsigned int width, height;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

w Specifies the ID of the window to be reconfigured.

x Specify the new x and y coordinates of the upper-left pixel of the window s bor-

y der, relative to the window s parent.

width Specify the new width and height in pixels. These arguments define the interior

height size of the window.

Description

XMoveResizeWindow moves or resizes a window or both. XMoveResizeWindow does
not raise the window. Resizing a mapped window may lose its contents and generate an
Expose event on that window depending on the bit_gravity attribute. Configuring a win
dow may generate exposure events on windows that the window formerly obscured, depending
on the new size and location parameters.

If the override_redirect attribute of the window is False (see Volume One, Chapter 4,
Window Attributes) and the window manager has selected SubstructureRedirectMasJc
on the parent, then a Conf igureRequest event is sent to the window manager, and no fur
ther processing is performed.

If the client has selected StructureNotifyMask on the window, then a Conf igure-
Notify event is generated after the move and resize takes place, and the event will contain
the final position and size of the window.

Errors

BadValue
BadWindow

Related Commands

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate-
SubwindowsUp, XConf igureWindow, XLowerWindow, XMoveWindow, XQuery-
Tree, XRaiseWindow, XReparentWindow, XResizeWindow, XRestackWindows.

320 Xlib Reference Manual

-Xlib -Window Manipulation XMOVeWindOW

Name

XMoveWindow move a window.

Synopsis

XMoveWindow (display, w, x, y)
Display * display;
Window w;
int x, y;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window to be moved.

x Specify the new x and y coordinates of the upper-left pixel of the window s bor-

y der (or of the window itself, if it has no border), relative to the window s parent.

Description

XMoveWindow changes the position of the origin of the specified window relative to its par
ent. XMoveWindow does not change the mapping state, size, or stacking order of the window,
nor does it raise the window. Moving a mapped window will lose its contents if:

Its background_pixmap attribute is ParentRelative.

The window is obscured by nonchildren and no backing store exists.

If the contents are lost, exposure events will be generated for the window and any mapped
subwindows. Moving a mapped window will generate exposure events on any formerly
obscured windows.

If the override_redirect attribute of the window is False (see Volume One, Chapter 4,
Window Attributes) and the window manager has selected SubstructureRedirectMask
on the parent, then a Conf igureRequest event is sent to the window manager, and no fur
ther processing is performed.

If the client has selected StructureNotifyMask on the window, then a Conf igure-
Notif y event is generated after the move takes place, and the event will contain the final posi
tion of the window.

Errors

BadWindow

Related Commands

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate-
SubwindowsUp, XConf igureWindow, XLowerWindow, XMoveResizeWindow,
XQueryTree, XRaiseWindow, XReparentWindow, XResizeWindow, XRestack-
Windows.

Xlib Reference Manual 321

XNewModifiermap \ m _ Keyboard _

Name

XNewModifiermap create a keyboard modifier mapping structure.

Synopsis

XModif ierKeymap * XNewModifiermap (max_keys_per_mod)
int max_keys_per_mod;

Arguments

max_keys_jper_mod

Specifies the maximum number of keycodes assigned to any of the modifiers in the
map.

Description

XNewModifiermap returns a XModif ierKeymap structure and allocates the needed space.
This function is used when more than one XModif ierKeymap structure is needed.
max_keys_per_mod depends on the server and should be gotten from the XModif ier
Keymap returned by XGetModif ierMapping.

For more information on keyboard preferences, see Volume One, Chapter 9, The Keyboard and
Pointer.

Structures

typedef struct {

int max_keypermod; /* server s max number of keys per modifier */
KeyCode *modif iermap; /* An 8 by max_keypermod array
* of the modifiers */

} XModifierKeymap;

Related Commands

XChangeKeyboardMapping, XDeleteModifiermapEntry, XFreeModif iermap,
XGetKeyboardMapping, XGetModif ierMapping, XInsertModif iermapEntry,
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym,
XLookupString, XQueryKeymap, XRebindKeysym, XRef reshKeyboardMapping,
XSetModif ierMapping, XStringToKeysym.

322 Xlib Reference Manual

-Xllb - input HandHng / XNeXtEvent

Name

XNextEvent get the next event of any type or window.

Synopsis

XNextEvent ( display, report)
Display * display;
XEvent * report; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

report Returns the event removed from the event queue.

Description

XNextEvent removes an event from the head of the event queue and copies it into an
XEvent structure supplied by the caller. If the event queue is empty, XNextEvent flushes
the request buffer and waits (blocks) until an event is received. Use XGheckMaskEvent or
XChecklf Event if you do not want to wait.

For more information, see Volume One, Chapter 8, Events.
Related Commands

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped-
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued,
XGetlnputFocus, XGetMotionEvents, Xlf Event, XMaskEvent, XPeekEvent,
XPeeklf Event, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSet-
InputFocus, XSynchronize, XWindowEvent.

Xlib Reference Manual 323

^ Xlib - HouseKeeping

Name

XNoOp send a NoOp to exercise connection with the server.

Synopsis

XNoOp (display)

Display * display;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

Description

XNoOp sends a NoOperation request to the X server, thereby exercising the connection.
This request can be used to measure the response time of the network connection. XNoOp does
not flush the request buffer.

Related Commands

Def aultScreen, XCloseDisplay, XFree, XOpenDisplay.

324 Xlib Reference Manual

Xlib -Regions-

J XOffsetReglon

Name

XOffsetRegion change offset of a region.

Synopsis

XOffsetRegion (r, dx , dy)
Region r;
int dx f dy ;

Arguments

r Specifies the region.

dx Specify the amount to move the specified region relative to the origin of all

dy regions.

Description

XOffsetRegion changes the offset of the region the specified amounts in the x and y direc
tions.

Regions are located using an offset from a point (the region origin) which is common to all
regions. It is up to the application to interpret the location of the region relative to a drawable.
If the region is to be used as a clipjmask by calling XSetRegion, the upper-left corner of
the region relative to the drawable used in the graphics request will be at (xof fset +
clip_x_origin, yof f set + clip_y_origin) , where xof fset and yof f set are
the offset of the region and clip_x_origin and clip_y_origin are components of the
GC used in the graphics request.

Structures

Region is a pointer to an opaque structure type.

Related Commands

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion,
XIntersectRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion,
XSetRegion, XShrinkRegion, XSubtractRegion, XUnionRectWithRegion,
XUnionRegion, XXorRegion.

Xlib Reference Manual 325

XOpenDisplay

Xlib-HouseKeeping

Name

XOpenDisplay connect a client program to an X server.

Synopsis

Display *XOpenDisplay ( display_name)
char *display_name;

Arguments

di spl ay_name

Specifies the display name, which determines the server to connect to and the
communications domain to be used. See Description below.

Description

The XOpenDisplay routine connects the client to the server controlling the hardware display
through TCP, or UNIX or DECnet streams.

If display_name is NULL, the value defaults to the contents of the DISPLAY environment
variable on UNIX-based systems. On non-UNIX-based systems, see that operating system s
Xlib manual for the default display_name. The display_name or DISPLAY environment
variable is a string that has the format hostname: server or host
name: server. screen. For example, frog : . 2 would specify screen 2 of server on the
machine frog.

hostname Specifies the name of the host machine on which the display is physically con
nected. You follow the hostname with either a single colon (:) or a double colon
(::), which determines the communications domain to use. Any or all of the
communication protocols can be used simultaneously on a server built to sup
port them (but only one per client).

If hostname is a host machine name and a single colon (:) separates the
hostname and display number, XOpenDisplay connects the hardware
display to TCP streams. In Release 4 and later, the string "unix" is no
longer required and the string ":o" connects the local server.

If hostname is "unix" and a single colon (:) separates it from the display
number, XOpenDisplay connects the hardware display to UNIX domain
IPC streams. In Release 4, the string "unix" should be omitted.

If hostname is a host machine name and a double colon (::) separates
the hostname and display number, XOpenDisplay connects with the
server using DECnet streams. To use DECnet, however, you must build
all software for DECnet. A single X server can accept both TCP and
DECnet connections if it has been built for DECnet.

server Specifies the number of the server on its host machine. This display number
may be followed by a period (.). A single CPU can have more than one display;
the displays are numbered starting from 0.

Xlib Reference Manual

Xlib - HouseKeepIng (continued) XOpenDiSplay

screen Specifies the number of the default screen on server. Multiple screens can be
connected to (controlled by) a single X server, but they are used as a single dis
play by a single user, screen merely sets an internal variable that is returned
by the Def aultScreen macro. If screen is omitted, it defaults to 0.

If successful, XOpenDisplay returns a pointer to a Display. This structure provides many
of the specifications of the server and its screens. If XOpenDisplay does not succeed, it
returns a NULL.

After a successful call to XOpenDisplay, all of the screens on the server may be used by the
application. The screen number specified in the display_name argument serves only to
specify the value that will be returned by the Def aultScreen macro. After opening the dis
play, you can use the ScreenCount macro to determine how many screens are available.
Then you can reference each screen with integer values between and the value returned by
(ScreenCount -1).

For more information, see Volume One, Chapter 2, X Concepts, and Chapter 3, Basic Window
Program.

Related Commands

Def aultScreen, XCloseDisplay, XFree, XNoOp.

Xlib Reference Manual 327

XParseColor x ,,b-co,orc e ,,s-

Name

XParseColor look up RGB values from ASCII color name or translate hexadecimal value.

Synopsis

Status XParseColor ( display, colormap, spec, rgb_db_def)
Display ^display;
Colormap colormap;
char *spec;
XColor *rgb_db_def; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XQpenDisplay.

colormap Specifies a colormap. This argument is required but is not used. The same
code is used to process XParseColor and XLookupColor, but only
XLookupColor returns the closest values physically possible on the screen
specified by colormap.

spec Specifies the color specification, either as a color name or as hexadecimal

coded in ASCII (see below). Upper or lower case does not matter. The string
must be null-terminated, and should be in ISO LATIN- 1 encoding, which
means that the first 128 character codes are ASCII, and the second 128 char
acter codes are for special characters needed in western languages other than
English.

rgb_db_def Returns the RGB values corresponding to the specified color name or hexade
cimal specification, and sets its DoRed, DoGreen and DoBlue flags.

Description

XParseColor returns the RGB values corresponding to the English color name or hexade
cimal values specified, by looking up the color name in the color database, or translating the
hexadecimal code into separate RGB values. It takes a string specification of a color, typically
from a command line or XGet Default option, and returns the corresponding red, green, and
blue values, suitable for a subsequent call to XAllocColor or XStoreColor. spec can be
given either as an English color name (as in XAllocNamedColor) or as an initial sharp sign
character followed by a hexadecimal specification in one of the following formats:

#RGB (one character per color)

#RRGGBB (two characters per color)

#RRRGGGBBB (three characters per color)

#RRRRGGGGBBBB (four characters per color)

where R, G, and B represent single hexadecimal digits (upper or lower case).

The hexadecimal strings must be null-terminated so that XParseColor knows when it has
reached the end. When fewer than 16 bits each are specified, they represent the most signifi
cant bits of the value. For example, # 3 a 7 is the same as#3000a0007000.

Xlib Reference Manual

Xlib - Color Cells (continued) XParseColor

This routine will fail and return aStatusof zero if the initial character is a sharp sign but the
string otherwise fails to fit one of the above formats, or if the initial character is not a sharp sign
and the named color does not exist in the server s database.

Status is zero on failure, nonzero on success.

For more information, see Volume One, Chapter 7, Color.

Structures

typedef struct {

unsigned long pixel;

unsigned short red, green, blue;

char flags; /* DoRed, DoGreen, DoBlue */

char pad;
} XColor;

Errors

BadColormap

Related Commands

BlackPixel, WhitePixel, XAllocColor, XAllocColorCells, XAllocColor-
Planes, XAllocNamedColor, XFreeColors, XLookupColor, XQueryColor,
XQueryColors, XStoreColor, XStoreColors, XStoreNamedColor.

Xlib Reference Manual 329

XParseGeometry . Vll

v Xlib - Standard Geometry

Name

XParseGeometry generate position and size from standard window geometry string.

Synopsis

int XParseGeometry (parsestring, x, y, width, height)
char *parsestring;

int *x, *y; /* RETURN */

unsigned int * width, *height; /* RETURN */

Arguments

parsestring Specifies the string you want to parse.

x Return the x and y coordinates (offsets) from the string.

wi dth Return the width and height in pixels from the string.

height

Description

By convention, X applications provide a geometry command line option to indicate window
size and placement. XParseGeometry makes it easy to conform to this standard because it
allows you to parse the standard window geometry string. Specifically, this function lets you
parse strings of the form:

= &lt; wi dth&gt;x&lt;height&gt; { +- } &lt;xoffset&gt; { +- } &lt;yoffset&gt;

The items in this string map into the arguments associated with this function. (Items enclosed
in o are integers and items enclosed in { } are a set from which one item is allowed. Note that
the brackets should not appear in the actual string.)

XParseGeometry returns a bitmask that indicates which of the four values (width,
height, xoffset, and yoffset) were actually found in the string, and whether the x and y
values are negative. The bits are represented by these constants: XValue, YValue, width-
Value, Height Value, XNegative, and YNegative, and are defined in &lt;Xll/Xutil.h&gt;.
For each value found, the corresponding argument is updated and the corresponding bitmask
element set; for each value not found, the argument is left unchanged, and the bitmask element
is not set.

For more information, see Volume One, Chapter 11, Managing User Preferences.
Related Commands

XGeometry, XTranslateCoordinates, XWMGeometry.

330 Xlib Reference Manual

-X.ib - input Handling

Name

XPeekEvent get an event without removing it from the queue.

Synopsis

XPeekEvent ( display, report)
Display * display;
XEvent * report; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

report Returns the event peeked from the input queue.

Description

XPeekEvent peeks at an input event from the head of the event queue and copies it into an
XEvent supplied by the caller, without removing it from the input queue. If the queue is
empty, XPeekEvent flushes the request buffer and waits (blocks) until an event is received.
If you do not want to wait, use the QLength macro to determine if there are any events to peek
at, or use XPeeklf Event. XEventsQueued can perform the function of either QLength
or XPending and more.

For more information, see Volume One, Chapter 8, Events.
Related Commands

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped-
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued,
XGetlnputFocus, XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent,
XPeeklf Event, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSet-
InputFocus, XSynchronize, XWindowEvent.

Xlib Reference Manual 33 1

XPeeklfEvent \ X|lb _ |nput Hand|lng _

Name

XPeeklfEvent get an event matched by predicate procedure without removing it from the
queue.

Synopsis

XPeeklfEvent ( display , event, predicate, args)
Display *display;

XEvent *event; /* RETURN */

Bool (^predicate) () ;
char *args;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

event Returns the matched event.

predicate Specifies the procedure to be called to determine if each event that arrives in
the queue is the desired one.

args Specifies the user- specified arguments that will be passed to the predicate

procedure.

Description

XPeeklfEvent returns an event only when the specified predicate procedure returns True
for the event. The event is copied into event but not removed from the queue. The specified
predicate is called each time an event is added to the queue, with the arguments display,
event, and arg.

XPeeklfEvent flushes the request buffer if no matching events could be found on the queue,
and then waits for the next matching event.

For more information, see Volume One, Chapter 8, Events.
Related Commands

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped-
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued,
XGetlnputFocus, XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent,
XPeekEvent, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSet-
InputFocus, XSynchronize, XWindowEvent.

332 Xlib Reference Manual

Xlib -Input Handling-

J XPending

Name

XPending flush the request buffer and return the number of pending input events.

Synopsis

int XPending ( display)
Display *display;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

Description

XPending returns the number of input events that have been received by Xlib from the server,
but not yet removed from the queue. If there are no events on the queue, XPending flushes
the request buffer, and returns the number of events transferred to the input queue as a result of
the flush.

The QLength macro returns the number of events on the queue, but without flushing the
request buffer first.

For more information, see Volume One, Chapter 8, Events.
Related Commands

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped-
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued,
XGetlnputFocus, XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent,
XPeekEvent, XPeeklf Event, XPutBackEvent, XSelectlnput, XSendEvent,
XSetlnputFocus, XSynchronize, XWindowEvent.

Xlib Reference Manual 333

Xpermalloc \ Vll

v Xlib - Resource Manager

Name

Xpermalloc allocate memory never to be freed.

Synopsis

char *Xpermalloc ( size)
unsigned int size;

Arguments

si ze Specifies the size in bytes of the space to be allocated. This specification is

rounded to the nearest 4-byte boundary.

Description

Xpermalloc allocates some memory that will not be freed until the process exits. Xperm
alloc is used by some toolkits for permanently allocated storage and allows some perfor
mance and space savings over the completely general memory allocator.

334 Xlib Reference Manual

Xlib -Regions-

J XPointlnRegion

Name

XPointlnRegion determine if a point is inside a region.

Synopsis

Bool XPointlnRegion (r, x, y)
Region r;
int x, y;

Arguments

r Specifies the region.

x Specify the x and y coordinates of the point relative to the region s origin.

Description

XPointlnRegion returns True if the point x, y is contained in the region r. A point
exactly on the boundary of the region is considered inside the region.

Regions are located using an offset from a point (the region origin) which is common to all
regions. It is up to the application to interpret the location of the region relative to a drawable.

For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text.

Structures

Region is a pointer to an opaque structure type.

Related Commands

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion,
XIntersectRegion, XOf f setRegion, XPolygonRegion, XRectlnRegion, XSet-
Region, XShrinkRegion, XSubtractRegion, XUnionRectWithRegion, XUnion-
Region, XXorRegion.

Xlib Reference Manual 335

XPolygonRegion \.

xi|b

Name

XPolygonRegion generate a region from points.

Synopsis

Region XPolygonRegion (points , n, fill_rule)
XPoint points [] ;
int n;
int fill_rule;

Arguments

points Specifies a pointer to an array of points.

n Specifies the number of points in the polygon.

fill_rule Specifies whether areas overlapping an odd number of times should be part of
the region (windingRule) or not part of the region (EvenOddRule). See
Volume One, Chapter 5, The Graphics Context, for a description of the fill
rule.

Description

XPolygonRegion creates a region defined by connecting the specified points, and returns a
pointer to be used to refer to the region.

Regions are located relative to a point (the region origin) which is common to all regions. In
XPolygonRegion, the coordinates specified in points are relative to the region origin. By
specifying all points relative to the drawable in which they will be used, the region origin can
be coincident with the drawable origin. It is up to the application whether to interpret the loca
tion of the region relative to a drawable or not.

If the region is to be used as a clip_mask by calling XSetRegion, the upper-left corner of
the region relative to the drawable used in the graphics request will be at (xof f set +
clip_x_origin, yof f set + clip_y_origin) , where xof f set and yof f set are
the offset of the region (if any) and clip_x_origin and clip_y_origin are elements of
the GC used in the graphics request. The fill_rule can be either of these values:

EvenOddRule Areas overlapping an odd number of times are not part of the region.

windingRule Overlapping areas are always filled.

For more information on structures, see Volume One, Chapter 6, Drawing Graphics and Text.

Structures

Region is a pointer to an opaque structure type.

Related Commands

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion,
XIntersectRegion, XOf f setRegion, XPointlnRegion, XRectlnRegion, XSet
Region, XShrinkRegion, XSubtractRegion, XUnionRectWithRegion, XUnion-
Region, XXorRegion.

336 Xlib Reference Manual

-XMb - ,npu, Hand,ing

Name

XPutBackEvent push an event back on the input queue.

Synopsis

XPutBackEvent (display , event)
Display ^display;
XEvent * event;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

even t Specifies a pointer to the event to be requeued.

Description

XPutBackEvent pushes an event back onto the head of the current display s input queue (so
that it would become the one returned by the next XNextEvent call). This can be useful if
you have read an event and then decide that you d rather deal with it later. There is no limit to
how many times you can call XPutBackEvent in succession.

For more information, see Volume One, Chapter 8, Events.
Related Commands

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped-
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued,
XGetlnputFocus, XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent,
XPeekEvent, XPeeklf Event, XPending, XSelectlnput, XSendEvent, XSet-
InputFocus, XSynchronize, XWindowEvent.

Xlib Reference Manual 337

XPutlma 9 e x,,b -

Name

XPutlmage draw an image on a window or pixmap.

Synopsis

XPutlmage ( display, drawable, gc , image, src_x, src_y,

dst_x, dst_y, width, height)
Display ^display;
Drawable drawable;
GC gc ;

Xlmage * image;
int src_x, src_y;
int dst_x, dst_y ;
unsigned int width, height;

Arguments

display Specifies a connection to an X server; returned from XQpenDisplay.

drawable Specifies the drawable.

gc Specifies the graphics context.

image Specifies the image you want combined with the rectangle.

src_x Specify the coordinates of the upper-left corner of the rectangle to be copied,

src_y relative to the origin of the image.

dst_x Specify the x and y coordinates, relative to the origin of the drawable, where

dst_y the upper-left corner of the copied rectangle will be placed.

wi dth Specify the width and height in pixels of the rectangular area to be copied.

height

Description

XPutlmage draws a section of an image on a rectangle in a window or pixmap. The section
of the image is defined by src_x, src_y, width and height.

There is no limit to the size of image that can be sent to the server using XPutlmage. XPut
lmage automatically decomposes the request to make sure that the maximum request size of
the server is not exceeded.

XPutlmage uses these graphics context components: function, plane_mask, subwin-
dow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also
uses these graphics context mode-dependent components: foreground and background.

If an XYBitmap format image is used, then the depth of drawable must be 1, otherwise a
BadMatch error is generated. The foreground pixel in gc defines the source for bits set to
one in the image, and the background pixel defines the source for the bits set to zero.

For XYPixmap and ZPixmap format images, the depth of the image must match the depth of

drawable.

338 Xlib Reference Manual

Xlib - Images (continued) XPutlmage

Structures

typedef struct _XImage {

int width, height; /* size of image */

int xoffset; /* number of pixels offset in x direction */

int format; /* XYBitmap, XYPixmap, ZPixmap */

char *data; /* pointer to image data */

int byte_order; /* data byte order, LSBFirst, MSBFirst */

int bitmap_unit; /* quant, of scan line 8, 16, 32 */

int bitmap_bit_order; /* LSBFirst, MSBFirst */

int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */

int depth; /* depth of image */

int bytes_per_line; /* accelerator to next line */

int bits_per_pixel; /* bits per pixel (ZPixmap) */

char *obdata; /* hook for the object routines to hang on */

struct funcs { /* image manipulation routines */

struct _XImage * (*create_image) ();

int { *destroy_image) ();

unsigned long ( *get_pixel) () ;

int (*put_pixel) () ;

struct __XImage * (*sub_image) ();

int (*add_pixel) () ;
} f;
} X Image;

Errors

BadDrawable

BadGC

BadMatch See Description above.

BadValue

Related Commands

ImageByteOrder, XAddPixel, XCreatelmage, XDestroy Image, XGet Image,
XGetPixel, XGetSublmage, XPutPixel, XSublmage.

Xlib Reference Manual 339

XPutPixel "\ v,

v Xlib - Images-
Name

XPutPixel set a pixel value in an image.

Synopsis

int XPutPixel (ximage f x f y, pixel)
Xlmage * ximage;
int x;
int y;
unsigned long pixel;

Arguments

ximage Specifies a pointer to the image to be modified.

x Specify the x and y coordinates of the pixel to be set, relative to the origin of

y the image.

pixel Specifies the new pixel value.

Description

XPutPixel overwrites the pixel in the named image with the specified pixel value. The x
and y coordinates are relative to the origin of the image. The input pixel value must be in same
bit- and byte-order as the machine in which the client is running (that is, the Least Significant
Byte (LSB) of the long is the LSB of the pixel). The x and y coordinates must be contained in
the image.

Structures

typedef struct Ximage {

int width, height; /* size of image */

int xoffset; /* number of pixels offset in x direction */

int format; /* XYBitmap, XYPixmap, ZPixmap */

char *data; /* pointer to image data */

int byte_order; /* data byte order, LSBFirst, MSBFirst */

int bitmap_unit; /* quant, of scan line 8, 16, 32 */

int bitmap_bit_order; /* LSBFirst, MSBFirst */

int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */

int depth; /* depth of image */

int bytes_per_line; /* accelerator to next line */

int bits_per_pixel; /* bits per pixel (ZPixmap) */

unsigned long red_mask; /* bits in z arrangment */

unsigned long green_mask;

unsigned long blue_mask;

char *obdata; /* hook for the object routines to hang on */

struct funcs { /* image manipulation routines */

struct _XImage * (*create_image) ( ) ;

int (*destroy_image) ();

unsigned long (*get_pixel)( ) ;

int (*put_pixel) () ;

struct Ximage * (*sub image) ();

int (*add_pixel) () ;
} f;
} Ximage;

340 Xlib Reference Manual

Xlib- Images (continued) XPutPixel

Related Commands

ImageByteOrder, XAddPixel, XCreate Image, XDestroy Image, XGetlmage,
XGetPixel, XGetSublmage, XPutlmage, XSublmage.

Xlib Reference Manual 34 1

XQueryBestCursor v^

-Xlib- Cursors-

Name

XQueryBestCursor get the closest supported cursor sizes.

Synopsis

Status XQueryBestCursor (display, draw-able, width, height,

rwidth, rheight)
Display * display ;
Drawable drawable;
unsigned int width, height;
unsigned int * rwidth, * rheight / /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

draw-able Specifies a drawable that indicates which screen the cursor is to be used on.
The best cursor may be different on different screens.

width Specify the preferred width and height, in pixels.

height

rwidth Returns the closest supported cursor dimensions, in pixels, on the display

rh ei gh t hardware.

Description

XQueryBestCursor returns the closest cursor dimensions actually supported by the display
hardware to the dimensions you specify.

Call this function if you wish to use a cursor size other than 16 by 16. XQueryBestCursor
provides a way to find out what size cursors are actually possible on the display. Applications
should be prepared to use smaller cursors on displays which cannot support large ones.

XQueryBestCursor returns nonzero if the call succeeded in getting a supported size (which
may be the same or different from the specified size), or zero if the call failed.

Errors

BadDrawable

Related Commands

XCreateFontCursor, XCreateGlyphCursor, XCreatePixmapCursor, XDef ine-
Cursor, XFreeCursor, XQueryBestSize, XRecolorCursor, XUndef ineCursor.

342 Xlib Reference Manual

Xlib - Pixmaps and Tiles -

J XQueryBestSize

Name

XQueryBestSize obtain the "best" supported cursor, tile, or stipple size.

Synopsis

Status XQueryBestSize (display, class, drawable, width,

height, rwidth, rheight)
Display * display ;
int class;
Drawable drawable;
unsigned int width, height;
unsigned int * rwidth, * rheight; /* RETURN */

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenDi splay.

class Specifies the class that you are interested in. Pass one of these constants:

TileShape, CursorShape, or StippleShape.

drawable Specifies a drawable ID that tells the server which screen you want the best
size for.

width Specify the preferred width and height in pixels.

height

rwidth Return the closest supported width and height, in pixels, available for the

rheight object on the display hardware.

Description

XQueryBestSize returns the "fastest" or "closest" size to the specified size. For class of
CursorShape, this is the closest size that can be fully displayed on the screen. For Tile-
Shape and StippleShape, this is the closest size that can be tiled or stippled "fastest."

For CursorShape, the drawable indicates the desired screen. For TileShape and
StippleShape, the drawable indicates the screen and possibly the visual class and depth
(server-dependent). An inputOnly window cannot be used as the drawable for TileShape
or StippleShape (else a BadMatch error occurs).

XQueryBestSize returns nonzero if the call succeeded in getting a supported size (may be
the same or different from the specified size), or zero if the call failed.

Errors

BadDrawable

BadMatch InputOnly drawable for class TileShape or StippleShape.
BadValue

Xlib Reference Manual 343

XQueryBeStSize (continued) Xlib - Pixmaps and Tiles

Related Commands

XCreateBitmapFromData, XCreatePixmap, XCreatePixmapFromBitmapData,
XFreePixmap, XQueryBestStipple, XQueryBestTile, XReadBitmapFile,
XSetTile, XSetWindowBackgroundPixmap, XSetWindowBorderPixmap,
XWriteBitmapFile.

344 Xlib Reference Manual

Xlib - Pixmaps and Tiles -

J XQueryBestStipple

Name

XQueryBestStipple obtain the fastest supported stipple shape.

Synopsis

Status XQueryBestStipple (display, drawable, width, height,

rwidth, rheight)
Display * display;
Drawable drawable;
unsigned int width, height;
unsigned int *rwidth, * rheight; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

drawable Specifies a drawable that tells the server which screen you want the best size
for.

width Specify the preferred width and height in pixels.

height

rwidth Return the width and height, in pixels, of the stipple best supported by the

rh ei gh t display hardware.

Description

XQueryBestStipple returns the closest stipple size that can be stippled fastest. The draw-
able indicates the screen and possibly the visual class and depth. An inputOnly window
cannot be used as the drawable (else a BadMatch error occurs).

XQueryBestStipple returns nonzero if the call succeeded in getting a supported size (may
be the same or different from the specified size), or zero if the call failed.

For more information on stipples, see Volume One, Chapter 5, The Graphics Context.

Errors

BadDrawable

BadMatch InputOnly window.

Related Commands

XCreateBitmapFromData, XCreatePixmap, XCreatePixmapFromBitmapData,
XFreePixmap, XQueryBestSize, XQueryBestTile, XReadBitmapFile, XSet-
Tile, XSetWindowBackgroundPixmap, XSetWindowBorderPixmap, XWrite-
BitmapFile.

Xlib Reference Manual 345

XQueryBestTile \ X||b _ pixmaps and T||es _

Name

XQueryBestTile obtain the fastest supported fill tile shape.

Synopsis

Status XQueryBestTile ( display, drawable, width, height,

rwidth, rheight)
Display * display;
Drawable drawable ;
unsigned int width, height;
unsigned int * rwidth, * rheight ; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

drawable Specifies a drawable that tells the server which screen you want the best size
for.

wi dth Specify the preferred width and height in pixels.

height

rwidth Return the width and height, in pixels, of the tile best supported by the dis-

r height play hardware.

Description

XQueryBestTile returns the closest size that can be tiled fastest. The drawable indicates
the screen and possibly the visual class and depth. An Input Only window cannot be used as
the drawable.

XQueryBestTile returns nonzero if the call succeeded in getting a supported size (may be
the same or different from the specified size), or zero if the call failed.

For more information on tiles, see Volume One, Chapter 5, The Graphics Context.
Errors

BadDrawable

BadMatch InputOnly drawable specified.

Related Commands

XCreateBitmapFromData, XCreatePixmap, XCreatePixmapFromBitmapData,
XFreePixmap, XQueryBestSize, XQueryBestStipple, XReadBitmapFile,
XSetTile, XSetWindowBackgroundPixmap, XSetWindowBorderPixmap,
XWriteBitmapFile.

346 Xlib Reference Manual

Xlib- Color Cells-

J XQueryColor

Name

XQueryColor obtain the RGB values and flags for a specified colorcell.

Synopsis

XQueryColor ( display f cmap, colorcell_def)
Display ^display;
Colormap cmap;
XColor *colorcell_def; /* SEND and RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

cmap Specifies the ID of the colormap from which RGB values will be retrieved.

colorcell_def

Specifies the pixel value and returns the RGB contents of that colorcell.

Description

XQueryColor returns the RGB values in colormap cmap for the colorcell corresponding to
the pixel value specified in the pixel member of the XColor structure colorcell_def .
The RGB values are returned in the red, green, and blue members of that structure, and the
flags member of that structure is set to (DoRed I DoGreen | DoBlue) . The values
returned for an unallocated entry are undefined.

For more information, see Volume One, Chapter 7, Color.
Structures

typedef struct {

unsigned long pixel;

unsigned short red, green, blue;

char flags; /* DoRed, DoGreen, DoBlue */

char pad;
} XColor;

Errors

BadColormap

BadValue Pixel not valid index into cmap.

Related Commands

BlackPixel, WhitePixel, XAllocColor, XAllocColorCells, XAllocColor-
Planes, XAllocNamedColor, XFreeColors, XLookupColor, XParseColor,
XQueryColors, XStoreColor, XStoreColors, XStoreNamedColor.

Xlib Reference Manual 347

XQueryColors

Xlib- Color Cells-

Name

XQueryColors obtain RGB values for an array of colorcells.

Synopsis

XQueryColors (display, cmap, colorcell_defs , ncolors)
Display *display;
Colormap cmap;

XColor color cell_defs [ncolors] ; /* SEND and RETURN */
int ncolors;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

cmap Specifies the ID of the colormap from which RGB values will be retrieved.

colorcell_defs

Specifies an array of XColor structures. In each one, pixel is set to indi
cate which colorcell in the colormap to return, and the RGB values in that
colorcell are returned in red, green, and blue.

ncol ors Specifies the number of XColor structures in the color definition array.

Description

XQueryColors is similar to XQueryColor, but it returns an array of RGB values. It
returns the RGB values in colormap cmap for the colorcell corresponding to the pixel value
specified in the pixel member of the XColor structure colorcell_def . The RGB values
are returned in the red, green, and blue members of that same structure, and sets the
flags member in each XColor structure to (DoRed I DoGreen | DoBlue).

For more information, see Volume One, Chapter 7, Color.
Structures

typedef struct {

unsigned long pixel;

unsigned short red, green, blue;

char flags; /* DoRed, DoGreen, DoBlue */

char pad;
} XColor;

Errors

BadColormap Specified colormap does not exist.

BadValue Pixel not valid index into cmap.

Note: if more than one pixel value is in error, the one reported is arbitrary.

Related Commands

BlackPixel, WhitePixel, XAllocColor, XAllocColorCells, XAllocColor-
Planes, XAllocNamedColor, XFreeColors, XLookupColor, XParseColor,
XQueryColor, XStoreColor, XStoreColors, XStoreNamedColor.

348 Xlib Reference Manual

Xlib - Extensions-

J XQueryExtension

Name

XQueryExtension get extension information.

Synopsis

Bool XQueryExtension ( display, name, major_opcode f

first_event r first_error)
Display ^display;
char *name;

int *major_opcode; /* RETURN */

int *first_event ; /* RETURN */

int *first_error; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

name Specifies the name of the desired extension. Upper or lower case is impor

tant. The string should be in ISO LATIN- 1 encoding, which means that the
first 128 character codes are ASCII, and the second 128 character codes are
for special characters needed in western languages other than English.

major_opcode

Returns the major opcode of the extension, for use in error handling routines.

first_event Returns the code of the first custom event type created by the extension.
f irst_error Returns the code of the first custom error defined by the extension.

Description

XQueryExtension determines if the named extension is present, and returns True if it is.
If so, the routines in the extension can be used just as if they were core Xlib requests, except
that they may return new types of events or new error codes. The available extensions can be
listed with XListExtensions.

The major_opcode for the extension is returned, if it has one. Otherwise, zero is returned.
This opcode will appear in errors generated in the extension.

If the extension involves additional event types, the base event type code is returned in
first__event. Otherwise, zero is returned in first_event. The format of the events is
specific to the extension.

If the extension involves additional error codes, the base error code is returned in
first_error. Otherwise, zero is returned. The format of additional data in the errors is
specific to the extension.

See Volume One, Chapter 13, Other Programming Techniques, for more information on using
extensions, and Volume One, Appendix C, Writing Extensions to X, for information on writing
them.

Related Commands

XFreeExtensionList, XListExtensions.

Xlib Reference Manual 349

XQueryFont , X|ib FOM&gt; _

Name

XQueryFont return information about a loaded font.

Synopsis

XFontStruct *XQueryFont ( display, font_ID)
Display * display;
XID font_ID;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

font_io Specifies either the font ID or the graphics context ID. You can declare the

data type for this argument as either Font or GContext (both X IDs). If
GContext, the font in that GC will be queried.

Description

XQueryFont returns a pointer to an XFontStruct structure containing information
describing the specified font. This call is needed if you loaded the font with XLoadFont, but
need the font information for multiple calls to determine the extent of text. XLoadQuery-
Font combines these two operations.

If the font hasn t been loaded (or the font ID passed is invalid), XQueryFont returns NULL.

If font_lD is declared as data type GContext (also a resource ID), this function queries the
font specified by the font component of the GC specified by this ID. This is useful for getting
information about the default font, whose ID is stored in the default GC. However, in this case
the GContext ID will be the ID stored in the fid field of the returned XFontStruct, and
you can t use that ID in XSetFont or XUnloadFont, since it is not itself the ID of the font.

Use XFreeFont to free this data.

For more information on fonts, see Volume One, Chapter 6, Drawing Graphics and Text.

Errors

BadFont

Structures

typedef struct {

XExtData *ext_data; /* hook for extension to hang data */

Font fid; /* font ID for this font */

unsigned direction; /* hint about direction font is painted */

unsigned min_char_or_byte2; /* first character */

unsigned max_char_or_byte2; /* last character */

unsigned min_bytel; /* first row that exists */

unsigned max_bytel; /* last row that exists */

Bool all_chars_exist; /* flag if all characters have nonzero size*/

unsigned default_char; /* char to print for undefined character */

int n_properties; /* how many properties there are */

XFontProp *properties; /* pointer to array of additional properties*/

XCharStruct min_bounds; /* minimum bounds over all existing char*/

XCharStruct max__bounds; /* minimum bounds over all existing char*/

350 Xlib Reference Manual

Xllb - Fonts

(continued)

XQueryFont

XCharStruct
int ascent;
int descent;

XFontStruct;

per char;

/* first_char to last_char information */

/* logical extent above baseline for spacing */

/* logical descent below baseline for spacing */

Related Commands

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XFree-
FontPath, XGetFontPath, XGetFontProperty, XListFonts, XListFontsWith-
Inf o, XLoadFont, XLoadQueryFont, XSetFont, XSetFontPath, XUnloadFont.

Xlib Reference Manual

351

XQueryKeymap \ X|ib _ Keyboard _

Name

XQueryKeymap obtain a bit vector for the current state of the keyboard.

Synopsis

XQue r yKeymap ( di spl ay, keys )
Display * display;
char keys [32] ; /* RETURN */

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenD i sp 1 ay .

keys Returns an array of bytes that identifies which keys are pressed down. Each

bit represents one key of the keyboard.

Description

XQueryKeymap returns a bit vector for the logical state of the keyboard, where each bit set to
1 indicates that the corresponding key is currently pressed down. The vector is represented as
32 bytes. Byte N (from 0) contains the bits for keys 8N to 8N+7 with the least significant bit in
the byte representing key 8N. Note that the logical state may lag the physical state if device
event processing is frozen due to a grab.

Related Commands

XChangeKeyboardMapping, XDeleteModif iermapEntry, XFreeModif iermap,
XGetKeyboardMapping, XGetModif ierMapping, XInsertModif iermapEntry,
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym,
XLookupString, XNewModif ierMap, XRebindKeysym, XRef reshKeyboard-
Mapping, XSetModif ierMapping, XStringToKeysym.

352 Xlib Reference Manual

Xlib-Pointer-

J XQueryPointer

Name

XQueryPointer get the current pointer location.

Synopsis

Bool XQueryPointer (display, w, root, child, root_x , root_y ,

win_x, win_y, keys_buttons)
Display *display;
Window w;

Window *root, *child; /* RETURN */

int *root_x, *root_y; /* RETURN */

int *win_x, *win_y; /* RETURN */

unsigned int *keys_buttons / /* RETURN */

Arguments

display Specifies a connection to an X server; returned from xopenDisplay.

w Specifies a window which indicates which screen the pointer position is

returned for, and child will be a child of this window if pointer is inside a
child.

root Returns the root window ID the pointer is currently on.

child Returns the ID of the child of w the pointer is located in, or zero if it not in a

child.

root_x Return the x and y coordinates of the pointer relative to the root s origin.
root_y

win_x Return the x and y coordinates of the pointer relative to the origin of window w.

win_y

keys_buttons

Returns the current state of the modifier keys and pointer buttons. This is a
mask composed of the OR of any number of the following symbols: Shift -
Mask, LockMask, ControlMask, ModlMask, Mod2Mask, ModSMask,
Mod4Mask, ModSMask, ButtonlMask, Button2Mask, ButtonSMask,
Button4Mask, ButtonSMask.

Description

XQueryPointer gets the pointer coordinates relative to a window and relative to the root
window, the root window ID and the child window ID (if any) the pointer is currently in,
and the current state of modifier keys and buttons.

If XQueryPointer returns False, then the pointer is not on the same screen as v, child is
None, and win_x and win_y are zero. However, root, root_x, and root_y are still
valid. If XQueryPointer returns True, then the pointer is on the same screen as the win
dow v/, and all return values are valid.

The logical state of the pointer buttons and modifier keys can lag behind their physical state if
device event processing is frozen due to a grab.

Xlib Reference Manual 353

XQueryPointer (continued) Xllb - Pointer

Errors

BadWindow

Related Commands

XChangeActivePointerGrab, XChangePointerControl, XGetPointer-
Control, XGetPointerMapping, XGrabPointer, XSetPointerMapping,
XUngrabPointer, XWarpPointer.

354 Xlib Reference Manual

Xlib-Text-

J XQueryTextExtents

Name

XQueryTextExtents query the server for string and font metrics.
Synopsis

XQueryTextExtents ( display, font_ID, string, nchars,

direction, ascent, descent, overall)
Display *display;
XID font_ID;
char *string;
int nchars;

int * direct ion; /* RETURN */

int * ascent, * descent; /* RETURN */
XCharStruct *overall; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

font_lD Specifies the appropriate font ID previously returned by XLoadFont, or the

GContext that specifies the font.

string Specifies the character string for which metrics are to be returned.

nchars Specifies the number of characters in string.

direction Returns the direction the string would be drawn using the specified font.
Either FontLef tToRight or FontRightToLef t.

ascent Returns the maximum ascent for the specified font.

descent Returns the maximum descent for the specified font.

overall Returns the overall characteristics of the string. These are the sum of the

width measurements for each character, the maximum ascent and
descent, the minimum Ibearing added to the width of all characters up
to the character with the smallest Ibearing, and the maximum rbearing
added to the width of all characters up to the character with the largest
rbearing.

Description

XQueryTextExtents returns the dimensions in pixels that specify the bounding box of the
specified string of characters in the named font, and the maximum ascent and descent for the
entire font. This function queries the server and, therefore, suffers the round trip overhead that
is avoided by XTextExtents, but XQueryTextExtents does not require a filled XFont-
Inf o structure stored on the client side. Therefore, this would be used when memory is pre
cious, or when just a small number of text width calculations are to be done.

The returned ascent and descent should usually be used to calculate the line spacing,
while the width, rbearing, and Ibearing members of overall should be used for hori
zontal measures. The total height of the bounding rectangle, good for any string in this font, is

ascent + descent.

Xlib Reference Manual 355

XQueryTextExtentS (continued) Xlib - Text

overall . ascent is the maximum of the ascent metrics of all characters in the string. The
overall . descent is the maximum of the descent metrics. The overall . width is the
sum of the character-width metrics of all characters in the string. The overall . Ibearing
is usually the Ibearing of the first character in the string, and overall . rbearing is the
rbearing of the last character in the string plus the sum of the widths of all the characters up to
but not including the last character. More technically, here is the X protocol definition: For
each character in the string, let W be the sum of the character-width metrics of all characters
preceding it in the string, let L be the Ibearing metric of the character plus W, and let R be the
rbearing metric of the character plus W. The overall . Ibearing is the minimum L of all
characters in the string, and the overall . rbearing is the maximum R.

For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and
Text.

Structures

typedef struct {

short Ibearing; /* origin to left edge of character */

short rbearing; /* origin to right edge of character */

short width; /* advance to next char s origin */

short ascent; /* baseline to top edge of character */

short descent; /* baseline to bottom edge of character */
unsigned short attributes; /* per char flags (not predefined) */

} XCharStruct;

Errors

BadFont

Related Commands

XDrawImageString, XDrawImageStringl6, XDrawString, XDrawStringl6,
XDrawText, XDrawTextl6, XQueryTextExtentS 16, XTextExtents, XText-
Extentsl6, XTextWidth, XTextWidthlG.

356 Xlib Reference Manual

Xlib-Text-

J XQueryTextExtentsI 6

Name

XQueryTextExtentsI 6 query the server for string and font metrics of a 16-bit character
string.

Synopsis

XQueryTextExtentsI 6 (display, font_ID, string, nchars,

direction, ascent, descent, overall)
Display * display;
XID font_ID;
XChar2b *string;
int nchars;

int * direct ion; /* RETURN */

int *ascent, *descent; /* RETURN */
XCharStruct * overall; /* RETURN */

Arguments

di spl ay Specifies a connection to an X server; returned from xopenD i splay.

font_TD Specifies the appropriate font ID previously returned by XLoadFont, or the

GContext that specifies the font.

string Specifies the character string for which metrics are to be returned.

nchars Specifies the number of characters in string.

direction Returns the direction of painting in the specified font. Either FontLef tto-

Right or FontRighttoLef t.

a scent Returns the maximum ascent in pixels for the specified font.

descent Returns the maximum descent in pixels for the specified font.

overall Returns the overall characteristics of the string. These are the sum of the

Description

XQueryTextExtentsI 6 returns the dimensions in pixels that specify the bounding box of
the specified string of characters in the named font, and the maximum ascent and descent for
the entire font. This function queries the server and, therefore, suffers the round trip overhead
that is avoided by XTextExtentslG, but XQueryTextExtents does not require a filled
XFontlnf o structure.

ascent + descent.

Xlib Reference Manual 357

XQueryTextExtentSl 6 (continued) Xlib - Text

overall . ascent is the maximum of the ascent metrics of all characters in the string. The
overall . descent is the maximum of the descent metrics. The overall . width is the
sum of the character-width metrics of all characters in the string. The overall . Ibearing
is usually the Ibearing of the first character in the string, and overall . rbearing is the
rbearing of the last character in the string plus the sum of the widths of all the characters up to
but not including the last character. More technically, here is the X protocol definition: For
each character in the string, let W be the sum of the character-width metrics of all characters
preceding it in the string, let L be the Wearing metric of the character plus W, and let R be the
rbearing metric of the character plus W. The overall . Ibearing is the minimum L of all
characters in the string, and the overall . rbearing is the maximum R.

For fonts defined with linear indexing rather than two-byte matrix indexing, the server inter
prets each XChar2b as a 16-bit number that has been transmitted with the most significant
byte first. That is, byte one of the XChar2b is taken as the most significant byte.

If the font has no defined default character, then undefined characters in the string are taken to
have all zero metrics.

Structures

typedef struct { /* normal 16-bit characters are two bytes */

unsigned char bytel;

unsigned char byte2;
} XChar2b;

typedef struct {

short Ibearing; /* origin to left edge of character */

short rbearing; /* origin to right edge of character */

short width; /* advance to next char s origin */

short ascent; /* baseline to top edge of character */

short descent; /* baseline to bottom edge of character */
unsigned short attributes; /* per char flags (not predefined) */

} XCharStruct;

Errors

BadFont

Related Commands

XDrawImageString, XDrawImageStringlG, XDrawString, XDrawStringlG,
XDrawText, XDrawTextlS, XQueryTextExtents, XTextExtents, XText-
Extentsl6, XTextWidth, XTextWidthl6.

358 Xlib Reference Manual

Xlib - Window Manipulation-
Name

XQueryTree return a list of children, parent, and root.

Synopsis

Status XQueryTree ( display, w

nchildren)
Display *display;
Window w;

Window *root; /* RETURN

Window *parent ; /* RETURN

Window ** children; /* RETURN
unsigned int * nchildren; /* RETURN

XQueryTree

root, parent, children,

*/
*/
*/
*/

Arguments

display

Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window to be queried. For this window, XQuery

Tree will list its children, its root, its parent, and the number of children.

root Returns the root ID for the specified window.

parent Returns the parent window of the specified window.

children Returns the list of children associated with the specified window.
nchildren Returns the number of children associated with the specified window.
Description

XQueryTree uses its last four arguments to return the root ID, the parent ID, a pointer to a list
of children and the number of children in that list, all for the specified window w. The chil
dren are listed in current stacking order, from bottommost (first) to topmost (last). XQuery
Tree returns zero if it fails, nonzero if it succeeds.

You should deallocate the list of children with XFree when it is no longer needed.

Errors

BadWindow

Related Commands

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate-
SubwindowsUp, XConf igureWindow, XLowerWindow, XMoveResizeWindow,
XMoveWindow, XRaiseWindow, XReparentWindow, XResizeWindow, XRestack-
Windows.

Xlib Reference Manual

359

XRaiseWindow

Xlib - Window Manipulation

Name

XRaiseWindow raise a window to the top of the stacking order.

Synopsis

XRaiseWindow (display, v/)
Display *display;
Window w;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window to be raised to the top of the stack.

Description

XRaiseWindow moves a window to the top of the stacking order among its siblings. If the
windows are regarded as overlapping sheets of paper stacked on a desk, then raising a window
is analogous to moving the sheet to the top of the stack, while leaving its x and y location on
the desk constant.

Raising a mapped window may generate exposure events for that window and any mapped
subwindows of that window that were formerly obscured.

If the override_redirect attribute of the window (see Volume One, Chapter 4, Window
Attributes) is False and the window manager has selected SubstructureRedirectMask
on the parent, then a Conf igureRequest event is sent to the window manager, and no fur
ther processing is performed.

Errors

BadWindow

Related Commands

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate-
SubwindowsUp, XConf igureWindow, XLowerWindow, XMoveResizeWindow,
XMoveWindow, XQueryTree, XRepa rent Window, XResizeWindow, XRestack-
Windows.

360 Xlib Reference Manual

Xlib - Pixmaps and Tiles-

j XReadBitmapFlle

Name

XReadBitmapFile read a bitmap from disk.

Synopsis

int XReadBitmapFile (display, drawable, filename, width,

height, bitmap, x_hot, y_hot)
Display * display ;
Drawable drawable;
char * filename;

unsigned int * width, * height; /* RETURN */
Pixmap * bitmap; /* RETURN */

int *x_hot, *y_hot; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

dr a wabl e Specifies the drawable.

filename Specifies the filename to use. The format of the filename is operating system
specific.

width Return the dimensions in pixels of the bitmap that is read.

height

bi tmap Returns the pixmap resource ID that is created.

x_hot Return the hotspot coordinates in the file (or -1,-1 if none present).

y_hot

Description

XReadBitmapFile reads in a file containing a description of a pixmap of depth 1 (a bitmap)
in X Version 1 1 bitmap format.

XReadBitmapFile creates a pixmap of the appropriate size and reads the bitmap data from
the file into the pixmap. The caller should free the pixmap using XFreePixmap when fin
ished with it.

If the file cannot be opened, XReadBitmapFile returns BitmapOpenFailed. If the file
can be opened but does not contain valid bitmap data, XReadBitmapFile returns Bitmap-
Filelnvalid. If insufficient working storage is allocated, XReadBitmapFile returns
BitmapNoMemory. If the file is readable and valid, XReadBitmapFile returns Bitmap-
Success.

Xlib Reference Manual 361

XReadBitmapFile (continued) Xlib - Pixmaps and Tiles

Here is an example X Version 1 1 bitmap file:

tdefine name_width 16

#define name_height 16

#define name_x_hot 8

#define name y hot 8

static char name_bits[] = {

Oxf8, Oxlf, Oxe3, Oxc7, Oxcf, Oxf3, Ox9f, Oxf9, Oxbf, Oxfd, 0x33, Oxcc,

Ox7f, Oxfe, Ox7f, Oxfe, Ox7e, Ox7e, Ox7f, Oxfe, 0x37, Oxec, Oxbb, Oxdd,

Ox9c, 0x39, Oxcf, Oxf3, Oxe3, Oxc7, Oxf8, Oxlf};

For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Errors

BadDrawable

Related Commands

XCreateBitmapFromData, XCreatePixmap, XCreatePixmapFromBitmapData,
XFreePixmap, XQueryBestSize, XQueryBestStipple, XQueryBestTile, XSet-
Tile, XSetWindowBackgroundPixmap, XSetWindowBorderPixmap, XWrite-
BitmapFile.

362 Xlib Reference Manual

Xlib -Keyboard-

J XRebindKeysym

Name

XRebindKeysym rebind a keysym to a string for client.

Synopsis

XRebindKeysym (display, keysym, mod_list, mod_count, string,

num_bytes)
Display * display ;
KeySym keysym;
KeySym *mod_list ;
int mod_count;
unsigned char *string;
int num_bytes;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

keysym Specifies the keysym to be rebound.

mod_list Specifies a pointer to an array of keysyms that are being used as modifiers.

mod_ count Specifies the number of modifiers in the modifier list.

string Specifies a pointer to the string that is to be copied and returned by

XLookupString in response to later events.

num_bytes Specifies the length of the string.
Description

XRebindKeysym binds the ASCII string to the specified keysym, so that string and
keysym are returned by XLookukpSt ring when that key is pressed and the modifiers speci
fied in mod_list are also being held down. This function rebinds the meaning of a keysym
for a client. It does not redefine the keycode in the server but merely provides an easy way for
long strings to be attached to keys. Note that you are allowed to rebind a keysym that may not
exist.

See Volume One, Chapter 9, The Keyboard and Pointer, for a description of keysyms and key
board mapping.

Related Commands

XChangeKeyboardMapping, XDeleteModif iermapEntry, XFreeModif iermap,
XGetKeyboardMapping, XGetModif ierMapping, XInsertModif iermapEntry,
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym,
XLookupString, XNewModif ierMap, XQueryKeymap, XRef reshKeyboard-
Mapping, XSetModif ierMapping, XStringToKeysym.

Xlib Reference Manual 363

XRecolorCursor \ xHb-cu.r.-

Name

XRecolorCursor change the color of a cursor.

Synopsis

XRecolorCursor ( display, cursor, foreground_color r

background_color)
Display * display;
Cursor cursor;
XColor *foreground_color f *background_color ;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

cursor Specifies the cursor ID.

foreground_col or

Specifies the red, green, and blue (RGB) values for the foreground.

background_color

Specifies the red, green, and blue (RGB) values for the background.

Description

XRecolorCursor applies a foreground and background color to a cursor. Cursors are nor
mally created using a single plane pixmap, composed of O s and 1 s, with one pixel value
assigned to 1 s and another assigned to O s. XRecolorCursor changes these pixel values. If
the cursor is being displayed on a screen, the change is visible immediately. On some servers,
these color selections are read/write cells from the colormap, and can t be shared by applica
tions.

Structures

typedef struct {

unsigned long pixel;

unsigned short red, green, blue;

char flags; /* DoRed, DoGreen, DoBlue */

char pad;
} XColor;

Errors

BadCursor

Related Commands

XCreateFontCursor, XCreateGlyphCursor, XCreatePixmapCursor, XDef ine-
Cursor, XFreeCursor, XQueryBestCursor, XQueryBestSize, XUndef ine-
Cursor.

364 Xlib Reference Manual

-X,.b-W.ndowManager Hints / XReCOHfigureWMWindOW

Name

XReconfigureWMWindow request that a top-level window be reconfigured.

Synopsis

Status XReconf igureWMWindow ( display, w, screen_n umber,

value_mask, values)
Display *display;
Window w;

int screen_n umber;
unsigned int value_mask;
XWindowChanges * values;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the window.

screen_n umber

Specifies the appropriate screen number on the host server.

value_mask Specifies which values are to be set using information in the values structure.
This mask is the bitwise inclusive OR of the valid configure window values
bits.

values Specifies a pointer to the XWindowChanges structure.

Availability

Release 4 and later.

Description

XReconfigureWMWindow issues a Conf igurewindow request on the specified top-level
window. If the stacking mode is changed and the request fails with a BadMatch error, the
error event is trapped and a synthetic Conf igureRequest event containing the same confi
guration parameters is sent to the root of the specified window. Window managers may elect to
receive this event and treat it as a request to reconfigure the indicated window.

For more information, see Volume One, Chapter 10, Interclient Communication.
Structures

typedef struct {
int x, y;

int width, height;
int border_width;
Window sibling;
int stack_mode;
} XWindowChanges;

Xlib Reference Manual 365

XReCOPf igureWMWindOW (continued) Xlib - Window Manager Hints

Errors

BadValue
BadWindow

Related Commands

Xlconif yWindow, XWithdrawWindow.

366 Xlib Reference Manual

Xlib -Regions-

J XRectlnRegion

Name

XRectlnRegion determine if a rectangle resides in a region.

Synopsis

int XRectlnRegion (r, x, y, width, height)
Region r;
int x r y;
unsigned int width, height;

Arguments

r Specifies the region.

x Specify the x and y coordinates of the upper-left corner of the rectangle, rela-

y live to the region s origin.

width Specify the width and height in pixels of the rectangle.

height

Description

XRectlnRegion returns Rectangleln if the rectangle is completely contained in the
region r, RectangleOut if it is completely outside, and RectanglePart if it is partially
inside.

Regions are located using an offset from a point (the region origin) which is common to all
regions. It is up to the application to interpret the location of the region relative to a drawable.
If the region is to be used as a clip_mask by calling xsetRegion, the upper-left corner of
region relative to the drawable used in the graphics request will be at (xoffset +
clip_x_origin, yof f set + clip_y_origin) , where xoffset and yof f set are
the offset of the region and clip_x_origin and clip_y_origin are the clip origin in the
GC used.

For this function, the x and y arguments are interpreted relative to the region origin; no draw-
able is involved.

Structures

Region is a pointer to an opaque structure type.

Related Commands

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion,
XIntersectRegion, XOf f setRegion, XPointlnRegion, XPolygonRegion,
XSetRegion, XShrinkRegion, XSubtractRegion, XUnionRectWithRegion,
XUnionRegion, XXorRegion.

Xlib Reference Manual 367

XRefreshKeyboardMapping \ X||b _ Keyboard _

Name

XRefreshKeyboardMapping read keycode-keysym mapping from server into Xlib.

Synopsis

XRefreshKeyboardMapping ( event )
XMappingEvent *event;

Arguments

event Specifies the mapping event that triggered this call.

Description

XRefreshKeyboardMapping causes Xlib to update its knowledge of the mapping between
keycodes and keysyms. This updates the application s knowledge of the keyboard.

The application should call XRefreshKeyboardMapping when a MappingNot if y event
occurs. MappingNotify events occur when some client has called XChangeKeyboard-
Mapping.

For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Structures

typedef struct {

int type;

unsigned long serial; /* # of last request processed by server */

Bool send_event; /* true if this came from a SendEvent request */

Display ^display; /* display the event was read from */

Window window; /* unused */

int request; /* one of MappingModif ier, MappingKeyboard,
MappingPointer */

int f irst_keycode; /* first keycode */

int count; /* defines range of change with f irst_keycode*/

} XMappingEvent;

Related Commands

XChangeKeyboardMapping, XDeleteModif iermapEntry, XFreeModif iermap,
XGetKeyboardMapping, XGetModif ierMapping, XInsertModif iermapEntry,
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym,
XLookupString, XNewModif ierMap, XQueryKeymap, XRebindKeysym, XSet-
Modif ierMapping, XStringToKeysym.

368 Xlib Reference Manual

-xnb- save set XRemoveFromSaveSet

Name

XRemoveFromSaveSet remove a window from the client s save-set.

Synopsis

XRemoveFromSaveSet (display, w)
Display * display ;
Window v/;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the window you want to remove from this client s save-set. This

window must have been created by a client other than the client making this
call.

Description

XRemoveFromSaveSet removes a window from the save-set of the calling application.

The save-set is a safety net for windows that have been reparented by the window manager,
usually to provide a shadow or other background for each window. When the window manager
dies unexpectedly, the windows in the save-set are reparented to their closest living ancestor, so
that they remain alive.

This call is not necessary when a window is destroyed since destroyed windows are automati
cally removed from the save-set. Therefore, many window managers get away without ever
calling XRemoveFromSaveSet. See Volume One, Chapter 14, Window Management, for
more information about save-sets.

Errors

BadMatch wnot created by some other client.

BadWindow

Related Commands

XAddToSaveSet, XChangeSaveSet.

Xlib Reference Manual 369

XRemoveHost , . XIib -Hos, Access-

Name

XRemoveHost remove a host from the access control list.

Synopsis

XRemoveHost ( display, host)
Display ^display;
XHostAddress *host ;

Arguments

display Specifies a connection to an X server; returned from XQpenDisplay.

host Specifies the network address of the machine to be removed.

Description

XRemoveHost removes the specified host from the access control list of the connected server.
The server must be on the same host as the process that calls XRemoveHost in order to
change the access control list.

If you remove your own machine from the access control list, you can no longer connect to that
server, and there is no way back from this call other than to log out, edit the access control file,
and reset the server.

The address data must be a valid address for the type of network in which the server oper
ates, as specified in the family member.

For more information on access control lists, see Volume One, Chapter 13, Other Programming
Techniques.

Structures

typedef struct {

int family; /* for example Family Internet */

int length; /* length of address, in bytes */

char ^address; /* pointer to where to find the bytes */

} XHostAddress;

/* constants used for family member of XHostAddress */
#define Familylnternet
#define FamilyDECnet 1
#define FamilyChaos 2

Errors

BadAccess
BadValue

370 Xlib Reference Manual

Xlib - Host Access (continued) X Re move Host

Related Commands

XAddHost, XAddHosts, XDisableAccessControl, XEnableAccessControl,
XListHosts, XRemoveHosts, XSetAccessControl.

Xlib Reference Manual 371

XRemoveHosts A Vl

v Xlib - Host Access-
Name

XRemoveHosts remove multiple hosts from the access control list.

Synopsis

XRemoveHosts ( display, hosts, num_hosts)
Display * display;
XHostAddress *hosts;
int num_hosts;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

hosts Specifies the list of hosts that are to be removed.

n um_h osts Specifies the number of hosts that are to be removed.

Description

XRemoveHosts removes each specified host from the access control list of the connected
server. The server must be on the same host as the process that call XRemoveHosts, in order
to change the access control list.

If you remove your machine from the access control list, you can no longer connect to that
server, and there is no way back from this call except to log out, edit the access control file, and
reset the server.

The address data must be a valid address for the type of network in which the server oper
ates, as specified in the family member.

For more information on access control lists, see Volume One, Chapter 13, Other Programming
Techniques.

Structures

typedef struct {

int family; /* for example Family Internet */

int length; /* length of address, in bytes */

char *address; /* pointer to where to find the bytes */

} XHostAddress;

/* constants used for family member of XHostAddress */

tdefine Familylnternet

#define FamilyDECnet 1

#define FamilyChaos 2

372 Xlib Reference Manual

Xllb - Host Access (continued) XRemOveHoStS

Errors

BadAccess
BadValue

Related Commands

XAddHost, XAddHosts, XDisableAccessControl, XEnableAccessConti
XListHosts, XRemoveHost, XSetAccessControl.

Xlib Reference Manual

XReparentWindow , XMb . wlndowHanlpulatIon _

Name

XReparentWindow insert a window between another window and its parent.

Synopsis

XReparentWindow (display, win, parent, x, y)
Display * display ;
Window win ;
Window parent;
int x r y;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

win Specifies the ID of the window to be reparented.

pa ren t Specifies the window ID of the new parent window.

x Specify the coordinates of the window relative to the new parent.

y
Description

XReparentWindow modifies the window hierarchy by placing window win as a child of
window parent. This function is usually used by a window manager to put a decoration win
dow behind each application window. In the case of the window manager, the new parent win
dow must first be created as a child of the root window.

If win is mapped, an XUnmapWindow request is performed on it automatically, win is then
removed from its current position in the hierarchy, and is inserted as a child of the specified
parent, win is placed on top in the stacking order with respect to siblings.

A ReparentNotif y event is then generated. The override_redirect member of the
structure returned by this event is set to either True or False . Window manager clients nor
mally should ignore this event if this member is set to True.

Finally, if the window was originally mapped, an XMapWindow request is performed automati
cally.

Descendants of win remain descendants of win; they are not reparented to the old parent of

win.

Normal exposure processing on formerly obscured windows is performed. The server might
not generate exposure events for regions from the initial unmap that are immediately obscured
by the final map. The request fails if the new parent is not on the same screen as the old parent,
or if the new parent is the window itself or an inferior of the window.

374 Xlib Reference Manual

Xlib - Window Manipulation (continued) XRepa rent Window

Errors

BadMatch parent not on same screen as old parent of win.

win has a ParentRelative background and parent is not the same
depth as win.

parent is win or an inferior of win.
BadWindow

Related Commands

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate-
SubwindowsUp, XConf igureWindow, XLowerWindow, XMoveResizeWindow,
XMoveWindow, XQueryTree, XRaiseWindow, XResizeWindow, XRestack-
Windows.

Xlib Reference Manual 375

XResetScreenSaver \,

^ Xlib - Screen Saver

Name

XResetScreenSaver reset the screen saver.

Synopsis

XResetScreenSaver (display)
Display * display ;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

Description

XResetScreenSaver redisplays the screen if the screen saver was activated. This may
result in exposure events to all visible windows if the server cannot save the screen contents. If
the screen is already active, nothing happens.

For more information on the screen saver, see Volume One, Chapter 13, Other Programming
Techniques.

Related Commands

XActivateScreenSaver, XForceScreenSaver, XGetScreenSaver, XSet-
ScreenSaver.

376 xiib Reference Manual

Xllb- Window Manipulation XReSJZeWmdOW

Name

XResizeWindow change a window s size.

Synopsis

XResizeWindow ( display, w, width, height)
Display ^display;
Window w;
unsigned int width, height;

Arguments

display Specifies a connection to an X server; returned from xopenDi splay.

w Specifies the ID of the window to be resized.

width Specify the new dimensions of the window in pixels.

height

Description

XResizeWindow changes the inside dimensions of the window. The border is resized to
match but its border width is not changed. XResizeWindow does not raise the window, or
change its origin. Changing the size of a mapped window may lose its contents and generate an
Expose event, depending on the bit_gravity attribute (see Volume One, Chapter 4, Win
dow Attributes). If a mapped window is made smaller, exposure events will be generated on
windows that it formerly obscured.

If the override_redirect attribute of the window is False and the window manager has
selected SubstructureRedirectMask on the parent, then a Conf igureRequest event
is sent to the window manager, and no further processing is performed.

If the client has selected StructureNotifyMask on the window, then a Conf igure-
Notif y event is generated after the move takes place, and the event will contain the final size
of the window.

Errors

BadValue
BadWindow

Related Commands

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate-
SubwindowsUp, XConf igureWindow, XLowerWindow, XMoveResizeWindow,
XMoveWindow, XQueryTree, XRaiseWindow, XReparentWindow, XRestack-
Windows.

Xlib Reference Manual 377

XRestack Windows

Xlib - Window Manipulation

Name

XRestackWindows change the stacking order of siblings.

Synopsis

XRestackWindows ( display, windows, nwlndows) ;
Display * display;
Window windows [] ;
int nwlndows;

Arguments

display Specifies a connection to an X server; returned from XQpenDisplay.

windows Specifies an array containing the windows to be restacked. All the windows

must have a common parent.

nwlndows Specifies the number of windows in the windows array.

Description

XRestackWindows restacks the windows in the order specified, from top to bottom. The
stacking order of the first window in the windows array will be on top, and the other windows
will be stacked underneath it in the order of the array. Note that you can exclude other siblings
from the windows array so that the top window in the array will not move relative to these
other siblings.

For each window in the window array that is not a child of the specified window, a BadMatch
error will be generated. If the override_redirect attribute of the window is False and
the window manager has selected SubstructureRedirectMask on the parent, then
Conf igureRequest events are sent to the window manager for each window whose over-
ride_redirect is not set, and no further processing is performed. Otherwise, the windows
will be restacked in top to bottom order.

Errors

BadMatch
BadWindow

Related Commands

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate-
SubwindowsUp, XConf igureWindow, XLowerWindow, XMoveResizeWindow,
XMoveWindow, XQueryTree, XRaiseWindow, XReparentWindow, XResize-
Window.

378 Xlib Reference Manual

-x..b - wmdow Manager H.nts / XrmDestroyDatabase

Name

XrmDestroyDatabase destroy a resource database.

Synopsis

void XrmDestroyDatabase ( database)
XrmDatabase database;

Arguments

da t abase Specifies the resource database.

Availability

Release 4 and later.

Description

XrmDestroyDatabase destroys a resource database and frees its allocated memory. The
destroyed resource database should not be referenced again. If database is NULL, Xrm
DestroyDatabase returns immediately.

For more information, see Volume One, Chapter 1 1, Managing User Preferences.
Related Commands

XrmMergeDat abases.

Xlib Reference Manual 379

XrmGetFileDatabase y

N Xlib - Resource Manager

Name

XrmGetFileDatabase retrieve a database from a file.

Synopsis

XrmDatabase XrmGetFileDatabase (filename)
char * filename;

Arguments

filename Specifies the resource database filename.

Description

XrmGetFileDatabase opens the specified file, creates a new resource database, and loads
the database with the data read in from the file. The return value of the function is as a pointer
to the created database.

The specified file must contain lines in the format accepted by XrmPutLineResource. If
XrmGetFileDatabase cannot open the specified file, it returns NULL.

For more information, see Volume One, Chapter II, Managing User Preferences.

Structures

XrmDatabase is a pointer to an opaque data type.

Related Commands

XrmDestroyDatabase, XrmGetResource, XrmGetStringDatabase, Xrm-
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase,
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet-
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource,
XrmQPutStringResource,XrmQuarkToString, XrmStringToBindingQuark-
List, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.

380 Xlib Reference Manual

-X,ib - Resource Manager /

Name

XrmGetResource get a resource from name and class as strings.

Synopsis

Bool XrmGetResource ( database, str_name, str_class,

str_type, value)
XrmDatabase database;
char *str_name;
char *str_class;

char **str__type; /* RETURN */
XrmValue * value; /* RETURN */

Arguments

database Specifies the database that is to be used.

st r_name Specifies the fully specified name of the value being retrieved.
str_class Specifies the fully specified class of the value being retrieved.

str_type Returns a pointer to the representation type of the destination. In this func
tion, the representation type is represented as a string, not as an Xrm-

Representation.

val ue Returns the value in the database. Do not modify or free this data.

Description

The resource manager manages databases of resource specifications consisting of lines contain
ing resource name/class strings followed by a colon and the value of the resource. XrmGet
Resource retrieves a resource from the specified database. It takes fully specified name and
class strings, and returns the representation and value of the matching resource. The value
returned points into database memory; you must not modify that data. If a resource was found,
XrmGetResource returns True. Otherwise, it returns False.

Currently, the database only frees or overwrites entries when new data is stored with Xrm-
MergeDatabases, or XrmPutResource and related routines. A client that avoids these
functions should be safe using the address passed back at any time until it exits.

XrmGetResource is very similar to XrmQGetResource, except that in XrmQGet-
Resource, the equivalent arguments to str_name, str_class, and str_type are
quarks instead of strings.

To understand how data is stored and retrieved from the database, you must understand:

1) The basic components that make up the storage key and retrieval keys.

2) How keys are made up from components.

3) The two ways that components can be bound together.

4) What sort of keys are used to store and retrieve data.

Xlib Reference Manual 38 1

XrmGet Resource (continued) Xlib - Resource Manager

5) How the storage key and retrieval keys are compared to determine whether they match.

6) If there are multiple matches, how the best match is chosen so only one value is returned.
Each will be covered in turn.

1) The storage key and retrieval keys are composed of a variable number of components,
bound together. There are two types of components: names and classes. By convention,
names begin with a lower case character and classes begin with an upper case character.
Therefore, xmh, background, and toe are examples of names, while Xmh, Box, and
Command are examples of classes. A name key (like str_name) consists purely of
name components. A class key (like str_class ) consists purely of class components.
The retrieval keys are a pair of keys, one composed of purely name components, the
other of purely class components. A storage key (like specifier in XrmPut-
Resource) consists of a mixture of name and class components.

2) A key is composed of multiple components bound together in sequence. This allows you
to build logical keys for your application. For example, at the top level, the application
might consist of a paned window (that is, a window divided into several sections) named
toe. One pane of the paned window is a button box window named buttons filled with
command buttons. One of these command buttons is used to retrieve (include) new
mail and has the name include. This window has a fully qualified name xmh . toe . but
tons, include and a fully qualified class Xmh.VPaned. BOX. Command. Its fully quali
fied name is the name of its parent, xmh . toe .buttons, followed by its name include.
Its class is the class of its parent, Xmh.VPaned. BOX, followed by its particular class,

Command.

3) The components in a key can be bound together in two ways: by a tight binding (a dot
".") or by a loose binding (an asterisk "*"). Thus xmh. toe. background has three
name components tightly bound together, while Xmh*Command. foreground uses both a
loose and a tight binding. Bindings can also precede the first component (but may not
follow the last component). By convention, if no binding is specified before the first
component, a tight binding is assumed. For example, xmh. background and
.xmh. background both begin with tight bindings before the xmh, while
*xmh . background begins with a loose binding.

The difference between tight and loose bindings comes when comparing two keys. A
tight binding means that the components on either side of the binding must be sequential.
A loose binding is a sort of wildcard, meaning that there may be unspecified components
between the two components that are loosely bound together. For example,

xmh. toe. background would match xmh*background and Background but not
xmh . background or background.

4) A key used to store data into the database can use both loose and tight bindings. This
allows you to specify a data value which can match to many different retrieval keys. In
contrast, keys used to retrieve data from the database can use only tight bindings. You
can only look up one item in the database at a time. Remember also that a storage key

382 XHb Reference Manual

Xlib - Resource Manager (continued) XrmGetResOUrce

can mix name and class components, while the retrieval keys are a pair of keys, one con
sisting purely of name (first character lower case) components and one consisting purely
of class (capitalized) components.

5) The resource manager must solve the problem of how to compare the pair of retrieval
keys to a single storage key. (Actually, to many single storage keys, since the resource
manager will compare the retrieval keys against every key in the database, but one at a
time.) The solution of comparing a pair of keys to a single key is simple. The resource
manager compares component by component, comparing a component from the storage
key against both the corresponding component from the name retrieval key, and the cor
responding component from the class retrieval key. If the storage key component
matches either retrieval key component, then that component is considered to match. For
example, the storage key xmh. toe. Foreground matches the name key
xmh .toe . foreground with the class key Xmh. Box. Foreground. This is why
storage keys can mix name and class components, while retrieval keys cannot.

6) Because the resource manager allows loose bindings (wildcards) and mixing names and
classes in the storage key, it is possible for many storage keys to match a single
name/class retrieval key pair. To solve this problem, the resource manager uses the fol
lowing precedence rules to determine which is the best match (and only the value from
that match will be returned). The precedence rules are, in order of preference:

1. The attribute of the name and class must match. For example, queries for

xterm. scrollbar. background (name)
XTerm. Scrollbar. Background (class)

will not match the following database entry:

xterm. scrollbar: on

because background does not appear in the database entry.

2. Database entries with name or class prefixed by a dot ( . ) are more specific than those
prefixed by an asterisk (*). For example, the entry xterm . geometry is more specific
than the entry xterm*geometry.

3. Names are more specific than classes. For example, the entry *scrollbar.-
background is more specific than the entry * Scrollbar . Background.

4. A name or class is more specific than omission. For example, the entry
Scrollbar*Background is more specific than the entry *Background.

5. Left components are more specific than right components. For example, to query for
.xterm. scrollbar .background, the entry xterm*background is more spe
cific than the entry scrollbar*background.

Xlib Reference Manual

383

XrmGetResource (continued) Xlib - Resource Manager

Names and classes can be mixed. As an example of these rules, assume the following user pref
erence specification:

xmh*background: red

* command. font : 8x13

*command. background: blue

*Command. Foreground : green

xmh. toc*Command. activeForeground: black

A query for the name xmh. toe .messagef unctions . include .activeForeground
and class Xmh.VPaned. Box. Command. Foreground would match xmh.toc*-
Command. activeForeground and return black. However, it also matches *Com-
mand . Foreground but with lower preference, so it would not return green.

For more information, see Volume One, Chapter 11, Managing User Preferences, and Volume
Four, X Toolkit Intrinsics Programming Manual, Chapter 9, Resource Management and Type
Conversion.

Structures

XrmDatabase is a pointer to an opaque data type.

typedef struct {

unsigned int size;

caddr_t addr;
} XrmValue;

Related Commands

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetStringDatabase, Xrm-
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase,
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet-
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource,
XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuark-
List, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.

384 Xlib Reference Manual

-xi,b - Resource Manager / XrmGetStringDatabase

Name

XrmGetStringDatabase create a database from a string.

Synopsis

XrmDatabase XrmGetStringDatabase (data)
char *data;

Arguments

data Specifies the database contents using a string.

Description

XrmGetStringDatabase creates a new database and stores in it the resources specified in
data. The return value is subsequently used to refer to the created database. XrmGet
StringDatabase is similar to XrmGetFileDatabase, except that it reads the informa
tion out of a string instead of a file. Each line in the string is separated by a new line character
in the format accepted by XrmPutLineResource.

For more information, see Volume One, Chapter 11, Managing User Preferences.

Structures

XrmDatabase is a pointer to an opaque data type.

Related Commands

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, Xrm-
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase,
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet-
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource,
XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuark-
List, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.

Xlib Reference Manual 385

Xrmlnitialize

Xlib - Resource Manager

Name

Xrmlnitialize initialize the resource manager.

Synopsis

void Xrmlnitialize ( ) ;

Description

Xrmlnitialize initializes the resource manager, and should be called once before using
any other resource manager functions. It just creates a representation type of "String" for val
ues defined as strings. This representation type is used by XrmPutStringResource and
XrmQPutStringResource, which require a value as a string. See XrmQPutResource
for a description of representation types.

For more information, see Volume One, Chapter 11, Managing User Preferences.
Related Commands

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet-
StringDatabase, XrmMergeDatabases, XrmParseCommand, XrmPutFile-
Database, XrmPutLineResource, XrmPutResource, XrmPutStringResource,
XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPut
Resource, XrmQPutStringResource, XrmQuarkToString, XrmString-
ToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, Xrm-
UniqueQuark.

Xlib Reference Manual

Xlib - Resource Manager-

J XrmMergeDatabases

Name

XrmMergeDatabases merge the contents of one database into another.

Synopsis

void XrmMergeDatabases ( source_db, target _db)
XrmDat abase source_db, *target_db;

Arguments

source_db Specifies the resource database to be merged into the existing database.

targe t_db Specifies a pointer to the resource database into which the source_db data
base will be merged.

Description

XrmMergeDatabases merges source_db into target_db. This procedure is used to
combine databases, for example, an application specific database of defaults and a database of
user preferences. The merge is destructive; it destroys the original source_db database and
modifies the original targe t_db.

For more information, see Volume One, Chapter II, Managing User Preferences.

Structures

XrmDatabase is a pointer to an opaque data type.

Related Commands

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet-
StringDatabase, Xrmlnitialize, XrmParseCommand, XrmPutFileDatabase,
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet-
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource,
XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuark-
List, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.

Xlib Reference Manual 387

XrmParseCommand \.

v Xlib - Resource Manager-
Name

XrmParseCommand load a resource database from command line arguments.

Synopsis

void XrmParseCommand ( db, table, table_count , name, argc,

argv)

XrmDatabase *db; /* SEND and if NULL, RETURN */

XrmOptionDescList table;
int table_count /
char *name;

int *argc; /* SEND and RETURN */

char **argv; /* SEND and RETURN */

Arguments

database Specifies a pointer to the resource database. If database contains NULL, a
new resource database is created and a pointer to it is returned in database.

t abl e Specifies table of command line arguments to be parsed.

table_count Specifies the number of entries in the table.
name Specifies the application name.

argc Before the call, specifies the number of arguments. After the call, returns the

number of arguments not parsed.

argv Before the call, specifies a pointer to the command line arguments. After the

call, returns a pointer to a string containing the command line arguments that
could not be parsed.

Description

XrmParseCommand parses an (argc, argv) pair according to the specified option table,
loads recognized options into the specified database, and modifies the (argc, argv) pair to
remove all recognized options.

The specified table is used to parse the command line. Recognized entries in the table are
removed from argv, and entries are made in the specified resource database. The table entries
contain information on the option string, the option name, which style of option and a value to
provide if the option kind is XrmoptionNoArg. See the example table below.

argc specifies the number of arguments in argv and is set to the remaining number of argu
ments that were not parsed, name should be the name of your application for use in building
the database entry, name is prepended to the resourceName in the option table before stor
ing the specification. No separating (binding) character is inserted. The table must contain
either a dot (".") or an asterisk ("*") as the first character in each resourceName entry. The
resourceName entry can contain multiple components.

The following is a typical options table:

static XrmOptionDescRec opTable[ ] = {

{"-background", "*background", XrmoptionSepArg, (caddr_t) NULL},

358 Xlib Reference Manual

Xlib - Resource Manager

(continued)

XrmParseCommand

{"-bg",

{"-borderwidth 1

{ "-bordercolor 1

{"-bw",

{ "-display",

{"-fg",

{"-fn",

{ "-font",

{ "-foreground",

{ "-geometry",

{ "-iconic" ,

{ "-name",

{ "-reverse" ,

-rv",

-synchronous

-title",

-xrm",

"*borderColor",

"* background" ,

"*TopLevelShell . borderWidth",

"*borderColor " ,

"*TopLevelShell.borderWidth",

".display",

"^foreground",

"*font",

"*foreground",

" .TopLevelShell .geometry",

" .TopLevelShell . iconic",

" .name",

"*reverseVideo" ,

"*reverseVideo",

11 . synchronous",

11 . TopLevelShell . title" ,

NULL,

XrmoptionSepArg,

(caddr_t)

NULL}

XrmoptionSepArg,

(caddr_t)

NULL}

XrmoptionSepArg,

(caddr_t)

NULL}

XrmoptionSepArg,

(caddr_t)

NULL}

XrmoptionSepArg,

(caddr t)

NULL}

XrmoptionSepArg,

(caddr_t)

NULL}

XrmoptionSepArg,

(caddr t)

NULL}

XrmoptionSepArg,

(caddr_t)

NULL}

XrmoptionSepArg,

(caddr_t)

NULL}

XrmoptionSepArg,

(caddr_t)

NULL}

XrmoptionSepArg,

(caddr t)

NULL}

XrmoptionNoArg,

(caddr_t)

"on" }

XrmoptionSepArg,

(caddr t)

NULL}

XrmoptionNoArg,

(caddr_t)

"on" }

XrmoptionNoArg,

(caddr t)

"on" }

XrmoptionNoArg,

(caddr_t)

"on"}

XrmoptionSepArg,

(caddr t)

NULL}

XrmoptionResArg,

(caddr t)

NULL}

In this table, if the -background (or -bg) option is used to set background colors, the stored
resource specifier will match all resources of attribute background. If the -borderwidth option
is used, the stored resource specifier applies only to border width attributes of class Top
LevelShell (that is, outermost windows, including pop-up windows). If the -title option is
used to set a window name, only the topmost application windows receive the resource.

When parsing the command line, any unique unambiguous abbreviation for an option name in
the table is considered a match for the option. Note that upper case and lower case matter.

For more information, see Volume One, Chapter 11, Managing User Preferences.

Structures

XrmDatabase is a pointer to an opaque data type.

typedef enum {

XrmoptionNoArg,

XrmoptionlsArg,

XrmoptionStickyArg,

XrmoptionSepArg,

XrmoptionResArg,

Xrmopt ionSkipArg,

XrmoptionSkipLine,

XrmoptionSkipNArgs

} XrmOptionKind;

typedef struct {

char *option;
char *resourceName;
XrmOptionKind argKind;
caddr t value;

/* value is specified in OptionDescRec. value */

/* value is the option string itself */

/* value is chars immediately following option */

/* value is next argument in argv */

/* resource and value in next argument in argv */

/* ignore this option and next argument in argv */

/* ignore this option and the rest of argv */

/* new in R4 : ignore this option, skip

number specified in next argument */

/* option specification string in argv */

/* binding & resource name (w/out application name)

/* which style of option it is */

/* value to provide if XrmoptionNoArg */

XrmOptionDescRec, *XrmOptionDescList;

Xlib Reference Manual

XrmParseCommand (continued) Xlib - Resource Manager

Related Commands

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet-
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmPutFile-
Database, XrmPutLineResource, XrmPutResource, XrmPutStringResource,
XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPut-
Resource, XrmQPutStringResource, XrmQuarkToString, XrmString-
ToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, Xrm-
UniqueQuark.

390 Xlib Reference Manual

-XHb - Resource Manager / XrmPutFileDatabaSe

Name

XrmPutFileDatabase store a resource database in a file.

Synopsis

void XrmPutFileDatabase ( database, stored_db)
XrmDatabase database;
char *stored_db;

Arguments

database Specifies the resource database that is to be saved.

stored_db Specifies the filename for the stored database.
Description

XrmPutFileDatabase stores a copy of the application s current database in the specified
file. The file is an ASCII text file that contains lines in the format that is accepted by XrmPut-
LineResource.

For more information, see Volume One, Chapter 11, Managing User Preferences.

Structures

XrmDatabase is a pointer to an opaque data type.

Related Commands

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet-
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand,
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet-
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource,
XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuark-
List, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.

XHb Reference Manual 391

XrmPutLineResource \,

v Xlib - Resource Manager

Name

XrmPutLineResource add a resource specification to a resource database.

Synopsis

void XrmPutLineResource (database, line)

XrmDatabase *database; /* SEND, and if NULL, RETURN */
char *line;

Arguments

database Specifies a pointer to the resource database. If database contains NULL, a
new resource database is created and a pointer to it is returned in database.

line Specifies the resource name (possibly with multiple components) and value

pair as a single string, in the format resource : value.

Description

XrmPutLineResource adds a single resource entry to the specified database.

XrmPutLineResource is similar to XrmPutStringResource, except that instead of
having separate string arguments for the resource and its value, XrmPutLineResource
takes a single string argument (line) which consists of the resource name, a colon, then the
value. Since the value is a string, it is stored into the database with representation type

String.

Any whitespace before or after the name or colon in the line argument is ignored. The value
is terminated by a new-line or a NULL character. The value may contain embedded new-line
characters represented by the "\" and "n" two character pair (not the single "\n" character),
which are converted into a single linefeed character. In addition, the value may run over onto
the next line, this is indicated by a "\" character at the end of each line to be continued.

Null-terminated strings without a new line are also permitted. XrmPutResource, Xrm-
QPutResource, XrmPutStringResource, XrmQPutStringResource and Xrm
PutLineResource all store data into a database. See XrmQPutResource for the most
complete description of this process.

For more information, see Volume One, Chapter 11, Managing User Preferences.

Structures

XrmDatabase is a pointer to an opaque data type.

392 Xlib Reference Manual

Xlib - Resource Manager (continued) XrmPutLineResOurce

Related Commands

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet-
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand,
XrmPutFileDatabase, XrmPutResource, XrmPutStringResource, XrmQGet-
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPut Re source,
XrmQPutStringRe source, XrmQuarkToString, XrmStringToBindingQuark-
List, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.

Xlib Reference Manual 393

XrmPutResource \

v Xhb - Resource Manager

Name

XrmPutResource store a resource specification into a resource database.

Synopsis

void XrmPutResource ( database, specifier, type, value)

XrmDatabase * database; /* SEND, and if NULL, RETURN */
char * specifier;
char *type;
XrmValue * value;

Arguments

database Specifies a pointer to the resource database. If database contains NULL, a new
resource database is created and a pointer to it is returned in database.

sped fier Specifies a complete or partial specification of the resource.
type Specifies the type of the resource.

value Specifies the value of the resource.

Description

XrmPutResource is one of several functions which store data into a database.

XrmQPutResource first converts specifier into a binding list and a quark list by calling
XrmStringToBindingQuarkList, and converts type into an XrmRepresentation
by calling XrmStringToRepresentation. Finally, it puts the data into the database.

XrmPutResource, XrmQPutResource, XrmPutStringResource, XrmQPut-
StringResource and XrmPutLineResource all store data into a database. See the
description of XrmQPutResource for the most complete description of this process.

For more information, see Volume One, Chapter II, Managing User Preferences.

Structures

XrmDatabase is a pointer to an opaque data type.

typedef struct {

unsigned int size;

caddr_t addr;
} XrmValue, *XrmValuePtr;

Related Commands

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet-
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand,
XrmPutFileDatabase, XrmPutLineResource, XrmPutStringResource, Xrm-
QGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPut
Resource, XrmQPutStringResource, XrmQuarkToString, XrmString
ToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, Xrm-
UniqueQuark.

394 Xlib Reference Manual

-X,,b- Resource Manager XrmPutStringResource

Name

XrmPutStringResource add a resource specification with separate resource name and value.

Synopsis

void XrmPutStringResource (database, resource, ^alue)

XrmDatabase * database; /* SEND, and if NULL, RETURN */
char * resource;
char * value;

Arguments

database Specifies a pointer to the resource database. If database contains NULL, a
new resource database is created and a pointer to it is returned in database.

resource Specifies the resource, as a string.

val ue Specifies the value of the resource, as a string.

Description

XrmPutStringResource adds a resource specification with the specified resource and
value to the specified database. The resource string may contain both names and classes,
bound with either loose (*) or tight (.) bindings. See the description of XrmGetResource for
more information about bindings.

The representation type used in the database is String.

XrmPutResource, XrmQPutResource, XrmPutStringResource, XrmQPut-
StringResource and XrmPutLineResource all store data into a database. See Xrm
QPutResource for the most complete description of this process.

For more information, see Volume One, Chapter II, Managing User Preferences.

Structures

XrmDatabase is a pointer to an opaque data type.

Related Commands

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet-
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand,
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmQGet-
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource,
XrmQPutStringRe source, XrmQuarkToString, XrmStringToBindingQuark-
List, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.

Xlib Reference Manual 395

XrmQGetResource

Xllb - Resource Manager

Name

XrmQGetResource get a resource value using name and class as quarks.

Synopsis

Bool XrmQGetResource (database, quark_name, quark_class,

quark_type, value)
XrmDatabase database;
XrmNameList quark_name ;
XrmClassList quark_class ;

XrmRepresentation *quark_type; /* RETURN */
XrmValue * value; /* RETURN */

Arguments

da t abase Specifies the database that is to be used.

quark_name Specifies the fully qualified name of the value being retrieved (as a list of
quarks).

quark_class Specifies the fully qualified class of the value being retrieved (as a list of
quarks).

quark_type Returns a pointer to the representation type of the value. In this function, the
representation type is represented as a quark.

value Returns a pointer to the value in the database. Do not modify or free this

data.

Description

XrmQGetResource retrieves a resource from the specified database. It takes fully qualified
name and class strings, and returns the representation and value of the matching resource. The
value returned points into database memory; you must not modify that data. If a resource was
found, XrmQGetResource returns True. Otherwise, it returns False.

XrmQGetResource is very similar to XrmGetResource, except that in XrmGet-
Resource, the equivalent arguments to quark_name, quark_class, and quark_type
arguments are strings instead of quarks.

See XrmGetResource for a full description of how data is looked up in the database.
For more information, see Volume One, Chapter II, Managing User Preferences.

396 Xlib Reference Manual

Xlib - Resource Manager (continued) XrmQGetResource

Structures

XrmDatabase is a pointer to an opaque data type.

typedef XrmQuarkList XrmNameList;
typedef XrmQuarkList XrmClassList;
typedef XrmQuark XrmRepresentation;

typedef struct {

unsigned int size;

caddr_t addr;
} XrmValue, *XrmValuePtr;

Related Commands

XrmDestroyDatabase, XrmGetFileDatabase, XrmGet Re source, XrmGet-
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand,
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut-
StringResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPut-
Resource, XrmQPutStringResource, XrmQuarkToString, XrmString-
ToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, Xrm-
UniqueQuark.

Xlib Reference Manual 397

XrmQGetSearch List "\

&gt; Xllb - Resource Manager

Name

XrmQGetSearchList return a list of database levels.

Synopsis

Bool XrmQGetSearchList ( database, names, classes,

search_list, list_length)
XrmDatabase database;
XrmNameList names;
XrmClassList classes;

XrmSearchList search_list; /* RETURN */
int list_length;

Arguments

database Specifies the database to be searched.

names Specifies a list of resource names.

classes Specifies a list of resource classes.

search_list Returns a search list for further use. The caller must allocate sufficient space
for the list before calling XrmQGetSearchList.

list_length Specifies the number of entries (not the byte size) allocated for

search_list.

Description

XrmQGetSearchList is a tool for searching the database more efficiently. It is used in
combination with XrmQGetSearchResource. Often, one searches the database for many
similar resources which differ only in their final component (e.g., xmh.toc . foreground,
xmh .toe .background, etc). Rather than looking for each resource in its entirety, Xrm-
GetSearchList searches the database for the common part of the resource name, returning
a whole list of items in the database that match it. This list is called the search list. This search
list is then used by XrmQGetSearchList, which searches for the last components one at a
time. In this way, the common work of searching for similar resources is done only once, and
the specific part of the search is done on the much shorter search list.

XrmQGetSearchList takes a list of names and classes and returns a list of database levels
where a match might occur. The returned list is in best-to-worst order and uses the same algo
rithm as XrmGetResource for determining precedence. If search_list was large
enough for the search list, XrmQGetSearchList returns True. Otherwise, it returns
False.

The size of the search list that must be allocated by the caller is dependent upon the number of
levels and wildcards in the resource specifiers that are stored in the database. The worst case
length is 3 n , where n is the number of name or class components in names or classes.

Only the common prefix of a resource name should be specified in the name and class list to
XrmQGetSearchList. In the example above, the common prefix would be xmh.toc.
However, note that XrmQGetSearchResource requires that name represent a single

398 Xlib Reference Manual

Xlib - Resource Manager (continued) XrmQGetSearchList

component only. Therefore, the common prefix must be all but the last component of the name
and class.

For more information, see Volume One, Chapter 11, Managing User Preferences.

Structures

XrmDatabase is a pointer to an opaque data type.

typedef XrmQuarkList XrmNameList ;
typedef XrmQuarkList XrmClassList ;
typedef XrmQuark XrmRepresentation;

XrmSearchList is a pointer to an opaque data type.
Related Commands

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet-
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand,
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut-
StringResour.ee, XrmQGetResource, XrmQGetSearchResource, XrmQPut-
Resource, XrmQPutStringResource, XrmQuarkToString, XrmString-
ToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, Xrm-
UniqueQuark.

Xlib Reference Manual 399

XrmQGetSearchResource \ X1|b _ Resource Manager _

Name

XrmQGetSearchResource search prepared list for a given resource.

Synopsis

Bool XrmQGetSearchResource ( search_list, name, class,

type, value)

XrmSearchList search_list ;
XrmName name ;
XrmClass class;

XrmRepresentation *type; /* RETURN */
XrmValue * value; /* RETURN */

Arguments

search_list Specifies the search list returned by XrmQGetSearchList.

name Specifies the resource name.

class Specifies the resource class.

type Returns the data representation type.

value Returns the value from the database.

Description

XrmQGetSearchResource is a tool for searching the database more efficiently. It is used
in combination with XrmQGetSearchList. Often, one searches the database for many simi
lar resources which differ only in their final component (e.g., xmh. toe . foreground,
xmh. toe .background, etc). Rather than looking for each resource in its entirety, Xrm
QGetSearchList searches the database for the common part of the resource name, returning
a whole list of items in the database that match it. This list is called the search list. Xrm
QGetSearchResource searches the search list for the resource that is fully identified by
name and class. The search stops with the first match. XrmQGetSearchResource
returns True if the resource was found; otherwise, it returns False.

A call to XrmQGetSearchList with a name and class list containing all but the last compo
nent of a resource name followed by a call to XrmQGetSearchResource with the last com
ponent name and class returns the same database entry as XrmQGet Re source or XrmQGet-
Re source would with the fully qualified name and class.

For more information, see Volume One, Chapter 1 1, Managing User Preferences.

400 Xlib Reference Manual

Xllb - Resource Manager (continued) XrmQGetSearchResource

Structures

XrmDat abase is a pointer to an opaque data type.

typedef XrmQuark XrmName;

typedef XrmQuark XrmClass;

typedef XrmQuark XrmRepresentation;

typedef struct {

unsigned int size;

caddr_t addr;
} XrmValue, *XrmValuePtr;

XrmSearchList is a pointer to an opaque data type.

Related Commands

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet-
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand,
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut-
StringResource, XrmQGetResource, XrmQGetSearchList, XrmQPutResource,
XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuark-
List, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.

Xlib Reference Manual 40 1

XrmQPutReSOUrce \ x ,,b- Resource Manager-

Name

XrmQPutResource store a resource specification into a database using quarks.

Synopsis

void XrmQPutResource (database, bindings, quarks, type, value)
XrmDatabase *database; /* SEND, and if NULL, RETURN */
XrmBindingList bindings;
XrmQuarkList quarks;
XrmRepresentation type;
XrmValue * value;

Arguments

database Specifies a pointer to the resource database. If database contains NULL, a new
resource database is created and a pointer to it is returned in database.

bindings Specifies a list of bindings for binding together the guards argument.

quarks Specifies the complete or partial name or class list of the resource to be stored,

type Specifies the type of the resource.

val ue Specifies the value of the resource.

Description

XrmQPutResource stores a resource specification into the database.

database can be a previously defined database, as returned by XrmGetStringDatabase,
XrmGetFileDatabase, or from XrmMergeDatabases. If database is NULL, a new
database is created and a pointer to it returned in database.

bindings and quarks together specify where the value should be stored in the database.
See XrmStringToBindingQuarkList for a brief description of binding and quark lists.
See XrmGetResource for a description of the resource manager naming conventions and
lookup rules.

type is the representation type of value. This provides a way to distinguish between differ
ent representations of the same information. Representation types are user defined character
strings describing the way the data is represented. For example, a color may be specified by a
color name ("red"), or be coded in a hexadecimal string ("#4f6c84") (if it is to be used as an
argument to XParseColor.) The representation type would distinguish between these two.
Representation types are created from simple character strings by using the macro Xrm-
StringToRepresentation. The type XrmRepresentation is actually the same type
as XrmQuark, since it is an ID for a string. The representation is stored along with the value
in the database, and is returned when the database is accessed.

value returns the value of the resource, specified as an XrmValue.

XrmGetResource contains the complete description of how data is accessed from the data
base, and so provides a good perspective on how it is stored.

402 Xlib Reference Manual

Xlib - Resource Manager (continued) XrmQPutResOUrce

For more information, see Volume One, Chapter 11, Managing User Preferences.

Structures

XrmDatabase is a pointer to an opaque data type.

typedef enum {

XrmBindTightly, XrmBindLoosely
} XrmBinding, *XrmBindingList ;

typedef int XrmQuark, *XrmQuarkList;
typedef XrmQuarkList XrmNameList;
typedef XrmQuark XrmRepresentation;

typedef struct {

unsigned int size;

caddr_t addr;
} XrmValue, *XrmValuePtr;

Related Commands

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet-
StringDatabase, Xrmlnitialize, XrmMergeDat abases, XrmParseCommand,
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut-
StringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearch-
Resource, XrmQPutStringResource, XrmQuarkToString, XrmString-
ToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, Xrm-
UniqueQuark.

Xlib Reference Manual 403

XrmQPutStringResource \ Xllb _ Resource Manager _

Name

XrmQPutStringResource add a resource specification to a database using a quark resource
name and string value.

Synopsis

void XrmQPutStringResource ( database, bindings, quarks, value)
XrmDatabase *database; /* SEND, and if NULL, RETURN */
XrmBindingList bindings;
XrmQuarkList quarks;
char * value;

Arguments

database Specifies a pointer to the resource database. If database contains NULL, a new
resource database is created and a pointer to it is returned in database.

bindings Specifies a list of bindings for binding together the guards argument.
guards Specifies the complete or partial name or class list of the resource to be stored.

val ue Specifies the value of the resource as a string.

Description

XrmQPutStringResource stores a resource specification into the specified database.

XrmQPutStringResource is a cross between XrmQPutResource and XrmPut-
StringResource. Like XrmQPutResource, it specifies the resource by guards and
bindings, two lists that together make a name/class list with loose and tight bindings. Like
XrmPutStringResource, it specifies the value to be stored as a string, that value is con
verted into an XrmValue, and the default representation type String is used.

XrmPutResource, XrmQPutResource, XrmPutStringResource, XrmQPut
StringResource and XrmPutLineResource all store data into a database. See Xrm
QPutResource for the most complete description of this process.

For more information, see Volume One, Chapter 11, Managing User Preferences.

Structures

XrmDatabase is a pointer to an opaque data type.

typedef enum {

XrmBindTightly, XrmBindLoosely
} XrmBinding, *XrmBindingList ;

typedef int XrmQuark, *XrmQuarkList ;

Related Commands

404 Xlib Reference Manual

Xlib - Resource Manager (continued) XrmQPutStringResource

Resource, XrmQPutResource, XrmQuarkToString, XrmStringToBinding-
QuarkList, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.

Xlib Reference Manual 405

XrmQuarkToString \ X||b _ Resource Managar _

Name

XrmQuarkToString convert a quark to a string.

Synopsis

char *XrmQuarkToString ( quark)
XrmQuark quark;

Arguments

quark Specifies the quark for which the equivalent string is desired.

Description

XrmQuarkToString returns the string for which the specified quark is serving as a short
hand symbol. The quark was earlier set to represent the string by XrmStringToQuark. The
string pointed to by the return value must not be modified or freed, because that string is in the
data structure used by the resource manager for assigning quarks. If no string exists for that
quark, XrmQuarkToString returns NULL.

Since the resource manager needs to make many comparisons of strings when it gets data from
the database, it is more efficient to convert these strings into quarks, and to compare quarks
instead. Since quarks are represented by integers, comparing quarks is trivial.

The three #def ine statements in the Structures section provide an extra level of abstraction.
They define macros so that names, classes and representations can also be represented as
quarks.

For more information, see Volume One, Chapter II, Managing User Preferences.
Structures

typedef int XrmQuark;

/* macro definitions from &lt;Xll/Xresource ,h&gt; */

#define XrmNameToString (name) XrmQuarkToString (name)
#define XrmClassToString (class) XrmQuarkToString (class)
#define XrmRepresentationToString (type) XrmQuarkToString (type)

Related Commands

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet-
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand,
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut-
StringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearch-
Resource, XrmQPutResource, XrmQPutStringResource, XrmString-
ToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, Xrm-
UniqueQuark.

406 Xlib Reference Manual

Xlib - Resource Manager-

J XrmStringToBindingQuarkList

Name

XrmStringToBindingQuarkList convert a key string to a binding list and a quark list.
Synopsis

XrmStringToBindingQuarkList (string, bindings, quarks)
char *string;

XrmBindingList bindings; /* RETURN */
XrmQuarkList quarks; /* RETURN */

Arguments

string Specifies the string for which the list of quarks and list of bindings are to be

generated. Must be NULL terminated.

bindings Returns the binding list. The caller must allocate sufficient space for the
binding list before the call.

quark Returns the list of quarks. The caller must allocate sufficient space for the

quarks list before the call.

Description

XrmStringToBindingQuarkList converts a resource specification string into two lists
one of quarks and one of bindings. Component names in the list are separated by a dot (".")
indicating a tight binding or an asterisk ("*") indicating a loose binding. If the string does not
start with dot or asterisk, a dot (".") is assumed.

A tight binding means that the quarks on either side of the binding are consecutive in the key.
A loose binding, on the other hand, is a wildcard that can match any number of unspecified
components in between the two quarks separated by the binding. Tight and loose bindings are
used in the match rules, which compare multicomponent strings to find matches and determine
the best match. See XrmGet Re source for a full description of lookup rules.

For example, *a . b*c becomes:

quarks bindings

"a" XrmBindLoosely
"b" XrmBindTightly
"c" XrmBindLoosely

For more information, see Volume One, Chapter II, Managing User Preferences.
Structures

typedef int XrmQuark, *XrmQuarkList ;
typedef enum (

XrmBindLoosely, XrmBindTightly
) XrmBinding, *XrmBindingList ;

Xlib Reference Manual 407

XrmStrlngToBlndingQuarkLiSt (continued) Xlib - Resource Manager

Related Commands

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet-
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand,
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut-
StringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearch-
Resource, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString,
XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.

408 Xlib Reference Manual

Xlib - Resource Manager-

J XrmStringToQuark

Name

XrmStringToQuark convert a string to a quark.

Synopsis

XrmQuark XrmStringToQuark (string)
char *string;

Arguments

string Specifies the string for which a quark is to be allocated.

Description

XrmStringToQuark returns a quark that will represent the specified string. If a quark
already exists for the string, that previously existing quark is returned. If no quark exists for the
string, then a new quark is created, assigned to the string, and string is copied into the quark
table. (Since string is copied, it may be freed. However, the copy of the string in the quark
table must not be modified or freed.) XrmQuarkToString performs the inverse function.

Since the resource manager needs to make many comparisons of strings when it gets data from
the database, it is more efficient to convert these strings into quarks, and to compare quarks
instead. Since quarks are presently represented by integers, comparing quarks is trivial.

The three #def ine statements in the Structures section provide an extra level of abstraction.
They define macros so that names, classes, and representations can also be represented as
quarks.

For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures

typedef int XrmQuark;

/* macro definitions from &lt;Xll/Xresource ,h&gt; */

tdefine XrmStringToName (string) XrmStringToQuark (string)

#define XrmStringToClass (string) XrmStringToQuark (string)

#def ine XrmStringToRepresentation (string) XrmStringToQuark (string)

Related Commands

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet-
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand,
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut-
StringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearch-
Resource, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString,
XrmStringToBindingQuarkList, XrmStringToQuarkList, XrmUniqueQuark.

Xlib Reference Manual 409

XrmStringToQuarkList \ XMb _ Resource Manager _

Name

XrmStringToQuarkList convert a key string to a quark list.

Synopsis

void XrmStringToQuarkList ( string, quarks)
char *string;
XrmQuarkList quarks; /* RETURN */

Arguments

string Specifies the string for which a list of quarks is to be generated. Must be null-

terminated. The components may be separated by the "." character (tight
binding) or the "*" character (loose binding).

quarks Returns the list of quarks.

Description

XrmStringToQuarkList converts string (generally a fully qualified name/class string)
to a list of quarks. Components of the string may be separated by a tight binding (the "." char
acter) or a loose binding ("*"). Use XrmStringToBindingQuarkList for lists which
contain both tight and loose bindings. See XrmGetResource for a description of tight and
loose binding.

Each component of the string is individually converted into a quark. See XrmString-
ToQuark for information about quarks and converting strings to quarks, quarks is a null-
terminated list of quarks.

For example, xmh . toe . command . background is converted into a list of four quarks: the
quarks for xmh, toe, command, and background, in that order. A NULLQUARK is appended
to the end of the list.

Note that XrmStringToNameList and XrmStringToClassList are macros that per
form exactly the same function as XrmStringToQuarkList. These may be used in cases
where they clarify the code.

For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures

typedef int XrmQuark *XrmQuarkList;

#define XrmStringToNameList (str, name) XrmStringToQuarkList ( (str) , (name))
tdefine XrmStringToClassList (str, class) XrmStringToQuarkList ( (str) , (class))

410 Xlib Reference Manual

Xlib - Resource Manager (continued) XrmStringToQuarkList

Related Commands

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase,
Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, Xrm-
PutLineResource, XrmPutResource, XrmPutStringResource, XrmQGetResource, Xrm-
QGetSearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutString-
Resource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuark,
XrmStringToRepresentation.XrmUniqueQuark.

Xlib Reference Manual 411

XrmUniqueQuark v.

v Xlib - Resource Manager-
Name

XrmUniqueQuark allocate a new quark.

Synopsis

XrmQuark XrmUniqueQuark ( )

Description

XrmUniqueQuark allocates a quark that is guaranteed not to represent any existing string.
For most applications, XrmStringToQuark is more useful, as it binds a quark to a string.
However, on some occasions, you may want to allocate a quark that has no string equivalent.

The shorthand name for a string is called a quark and is the type XrmQuark. Quarks are used
to improve performance of the resource manager, which must make many string comparisons.
Quarks are presently represented as integers. Simple comparisons of quarks can be performed
rather than lengthy string comparisons.

A quark is to a string what an atom is to a property name in the server, but its use is entirely
local to your application.

For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures

typedef int XrmQuark;

Related Commands

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet-
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand,
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut-
StringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearch-
Resource, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString,
XrmStringToBindingQuarkList, XrmStringToQuarkList, XrmStringTo
Quark.

4 12 Xlib Reference Manual

D J XRotateBuffers

Xlib - Cut Buffers

Name

XRotateBuffers rotate the cut buffers.

Synopsis

XRotateBuffers (display, rotate)
Display * display;
int rotate;

Arguments

display Specifies a connection to an X server; returned from xopenDisplay.

rotate Specifies how many positions to rotate the cut buffers.

Description

XRotateBuffers rotates the 8 cut buffers the amount specified by rotate. The contents

of buffer moves to buffer rotate, contents of buffer 1 moves to buffer (rotate+1) mod 8,

contents of buffer 2 moves to buffer (rotate+2) mod 8, and so on.

This routine will not work if any of the buffers have not been stored into with xstoreBuf f er

orXStoreBytes.

This cut buffer numbering is global to the display.

See the description of cut buffers in Volume One, Chapter 13, Other Programming Techniques.

Related Commands

XFetchBuf f er, XFetchBytes, XStoreBuf f er, XStoreBytes.

Xlib Reference Manual 4 1 3

XRotateWindowProperties

Xlib- Properties-

Name

XRotateWindowProperties rotate properties in the properties array.

properties, num_jprop,

Synopsis

XRotateWindowProperties ( display,

npositions)
Display * display;
Window w;

Atom properties [] ;
int num_prop;
int npositions;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window whose properties are to be rearranged.

properties Specifies the list of properties to be rotated.
num_prop Specifies the length of the properties array.

npositions Specifies the number of positions to rotate the property list. The sign controls
the direction of rotation.

Description

XRotateWindowProperties rotates the contents of an array of properties on a window. If
the property names in the properties array are viewed as if they were numbered starting
from and if there are num_prop property names in the list, then the value associated with
property name / becomes the value associated with property name (/ + npositions) mod
num_prop, for all / from to num_prop - 1. Therefore, the sign of npositions controls
the direction of rotation. The effect is to rotate the states by npositions places around the
virtual ring of property names (right for positive npositions, left for negative nposi-
tion).

If npositions mod num_j&gt;rop is nonzero, a PropertyNotify event is generated for
each property, in the order listed.

If a BadAtom, BadMatch, or Badwindow error is generated, no properties are changed.

Error

BadAtom

BadMatch
Badwindow

Atom occurs more than once in list for the window.
No property with that name for the window.

An atom appears more that once in the list or no property with that name is
defined for the window.

414

Xlib Reference Manual

Xlib - Properties (continued) XRotateWindOWPrOpertieS

Related Commands

XChangeProperty, XDeleteProperty, XGetAtomName, XGetFontProperty,
XGetWindowProperty, XInternAtom, XListProperties, XSetStandard-
Properties.

Xlib Reference Manual 415

XSaveContext \ Vll

N Xlib - Context Manager

Name

XSaveContext save a data value corresponding to a window and context type (not graphics
context).

Synopsis

int XSaveContext ( display, w, context, data)
Display * display;
Window w;
XContext context;
caddr_t data;

Arguments

display Specifies a connection to an X server; returned from xopenDisplay.

w Specifies the ID of the window with which the data is associated.

context Specifies the context type to which the data corresponds.

data Specifies the data to be associated with the window and context.

Description

XSaveContext saves data to the context manager database, according to the specified win
dow and context ID. The context manager is used for associating data with windows within
an application. The client must have called XUniqueContext to get the context ID
before calling this function. The meaning of the data is indicated by the context ID, but is
completely up to the client.

If an entry with the specified window and context ID already exists, XSaveContext writes
over it with the specified data.

The XSaveContext function returns XCNOMEM (a nonzero error code) if an error has occurred
and zero (0) otherwise. For more information, see the description of the context manager in
Volume One, Chapter 13, Other Programming Techniques.

Structures

typedef int XContext;

Related Commands

XDeleteContext, XFindContext, XUniqueContext.

4 16 Xlib Reference Manual

-X,,b - ,npu, Hand,,ng

Name

XSelectlnput select the event types to be sent to a window.

Synopsis

XSelectlnput (display, w, event_mask)
Display * display ;
Window w;
long event_mask;

Arguments

display Specifies a connection to an X server; returned from xopenDisplay.

w Specifies the ID of the window interested in the events.

event_mask Specifies the event mask. This mask is the bitwise OR of one or more of the
valid event mask bits (see below).

Description

XSelectlnput defines which input events the window is interested in. If a window is not
interested in a device event (button, key, motion, or border crossing), it propagates up to the
closest ancestor unless otherwise specified in the do_not_propagate_mask attribute.

The bits of the mask are defined in &lt;Xll/X.h&gt; :

ButtonPressMask NoEventMask

ButtonReleaseMask KeyPressMask

EnterWindowMask KeyReleaseMask

LeaveWindowMask ExposureMask

Point erMotionMask VisibilityChangeMask
PointerMotionHintMask StructureNotifyMask

ButtonlMotionMask ResizeRedirectMask

Button2MotionMask SubstructureNotifyMask

ButtonSMotionMask SubstructureRedirectMask

Button4MotionMask FocusChangeMask

ButtonSMotionMask PropertyChangeMask

ButtonMotionMask ColormapChangeMask

KeymapStateMask OwnerGrabButtonMask

A call on XSelectlnput overrides any previous call on XSelectlnput for the same win
dow from the same client but not for other clients. Multiple clients can select input on the same
window; their event_mask window attributes are disjoint. When an event is generated it will
be reported to all interested clients. However, only one client at a time can select for each of
SubstructureRedirectMask, ResizeRedirectMask, and ButtonPress.

If a window has both ButtonPressMask and ButtonReleaseMask selected, then a
ButtonPress event in that window will automatically grab the mouse until all buttons are
released, with events sent to windows as described for XGrabPointer. This ensures that a

Xlib Reference Manual 4 1 7

XSeleCtlnpUt (continued) Xlib - Input Handling

window will see the ButtonRelease event corresponding to the ButtonPress event,
even though the mouse may have exited the window in the meantime.

If PointerMotionMask is selected, events will be sent independent of the state of the
mouse buttons. If instead, one or more of ButtonlMotionMask, Button2MotionMask,
Button3MotionMask, Button4MotionMask, ButtonSMotionMask is selected,
MotionNotif y events will be generated only when one or more of the specified buttons is
depressed.

XCreateWindow and XChangeWindowAt tributes can also set the event_mask attri
bute.

For more information, see Volume One, Chapter 8, Events.

Errors

Badva lue Specified event mask invalid.

BadWindow

Related Commands

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped-
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued,
XGetlnputFocus, XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent,
XPeekEvent, XPeeklf Event, XPending, XPutBackEvent, XSendEvent, XSet-
InputFocus, XSynchronize, XWindowEvent.

41 Q Xlib Reference Manual

-xiib - input Handling / XSendEvent

Name

XSendEvent send an event

Synopsis

Status XSendEvent (display, w, propagate, event_mask r event)
Display *display;
Window w;
Bool propagate;
long event_mask /
XEvent *event;

Arguments

di spl ay Specifies a connection to an X server; returned from XQpenD i sp 1 ay.

w Specifies the ID of the window where you want to send the event Pass the

window resource ID, PointerWindow, or InputFocus.

propagate Specifies how the sent event should propagate depending on event_mask.
See description below. May be True or False.

event_mask Specifies the event mask. See XSelect Input for a detailed list of the
event masks.

event Specifies a pointer to the event to be sent.

Errors

BadValue Specified event is not a valid core or extension event type, or event mask is
invalid.

BadWindow

Description

XSendEvent sends an event from one client to another (or conceivably to itself). This func
tion is used for communication between clients using selections, for simulating user actions in
demos, and for other purposes.

The specified event is sent to the window indicated by w regardless of active grabs.

If w is set to PointerWindow, the destination of the event will be the window that the pointer
is in. If w is InputFocus is specified, then the destination is the focus window, regardless of
pointer position.

If propagate is False, then the event is sent to every client selecting on the window speci
fied by w any of the event types in event_mask. If propagate is True and no clients have
been selected on w any of the event types in event_mask, then the event propagates like any
other event.

The event code must be one of the core events, or one of the events defined by a loaded exten
sion, so that the server can correctly byte swap the contents as necessary. The contents of the
event are otherwise unaltered and unchecked by the server. The send_event field in every
event type, which if True indicates that the event was sent with XSendEvent.

Xlib Reference Manual 4 19

XSendEvent (continued) Xlib- Input Handling

This function is often used in selection processing. For example, the owner of a selection
should use XSendEvent to send a Select ionNot if y event to a requestor when a selec
tion has been converted and stored as a property. See Volume One, Chapter 10, Interclient
Communication for more information.

The status returned by XSendEvent indicates whether or not the given XEvent structure was
successfully converted into a wire event. This value is zero on failure, or nonzero on success.
Along with changes in the extensions mechanism, this makes merging of two wire events into a
single user-visible event possible.

Structures

See Appendix E, Event Reference, for the contents of each event structure.

Related Commands

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped-
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued,
XGetlnputFocus, XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent,
XPeekEvent, XPeeklf Event, XPending, XPutBackEvent, XSelectlnput, XSet-
InputFocus, XSynchronize, XWindowEvent.

420 Xlib Reference Manual

-x,ib - HO* Acce,, / XSetAccessControl

Name

XSetAccessControl disable or enable access control.

Synopsis

XSetAccessControl (display, mode)
Display * display ;
int mode ;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

mode Specifies whether you want to enable or disable the access control. Pass one

of these constants: EnableAccess orDisableAccess.

Description

XSetAccessControl specifies whether the server should check the host access list before
allowing access to clients running on remote hosts. If the constant used is DisableAccess,
clients from any host have access unchallenged.

This routine can only be called from a client running on the same host as the server.

For more information on access control lists, see Volume One, Chapter 13, Other Programming
Techniques.

Errors

BadAccess
BadValue

Related Commands

XAddHost, XAddHosts, XDisableAccessControl, XEnableAccessControl,
XListHosts, XRemoveHost, XRemoveHosts.

Xlib Reference Manual 42 1

XSet After Function "\ VI1

v Xlib - Error Handling-
Name

XSetAfterFunction set a function called after all Xlib functions.

Synopsis

int (*XSetAfterFunct ion (display, func))()
Display * display;
int (*func) () ;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

func Specifies the user-defined function to be called after each Xlib function. This

function is called with one argument, the display pointer.

Description

All Xlib functions that generate protocol requests can call what is known as an after function
after completing their work (normally, they don t). XSetAfterFunction allows you to
write a function to be called.

XSynchronize sets an after function to make sure that the input and request buffers are
flushed after every Xlib routine.

For more information, see Volume One, Chapter 13, Other Programming Techniques.
Related Commands

XDisplayName, XGetErrorDatabaseText, XGetErrorText, XSetError-
Handler, XSetlOErrorHandler, XSynchronize.

422 Xlib Reference Manual

Xlib - Graphics Context-

XSetArcMode

Name

XSetArcMode set the arc mode in a graphics context.

Synopsis

XSetArcMode ( display, gc , arc_mode)
Display * display;
GC gc;
int arc mode;

Arguments

display

arc mode

Specifies a connection to an X server; returned from XOpenDi splay.
Specifies the graphics context.

Specifies the arc mode for the specified graphics context. Possible values are
ArcChordorArcPieSli.ee.

Description

XSetArcMode sets the arc_mode component of a GC, which controls filling in the XFill-
Arcs function. ArcChord specifies that the area between the arc and a line segment joining
the endpoints of the arc is filled. ArcPieSlice specifies that the area filled is delimited by
the arc and two line segments connecting the ends of the arc to the center point of the rectangle
defining the arc.

ArcChord

ArcPieSlice

Xlib Reference Manual

423

XSetArcMode (continued) Xlib - Graphics Context

Errors

BadGC
BadValue

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC,
XSetBackground, XSetClipMask, XSetClipOrigin, XSetClipRectangles,
XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground, XSet-
Function, XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask,
XSetState, XSetStipple, XSetSubwindowMode, XSetTSOrigin.

424 Xlib Reference Manual

Xlib - Graphics Context-

J XSetBackground

Name

XSetBackground set the background pixel value in a graphics context.

Synopsis

XSetBackground (display, gc , background)
Display * display;
GC gc;
unsigned long background;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

gc Specifies the graphics context.

background Specifies the background component of the GC.

Description

XSetBackground sets the background pixel value component of a GC. Note that this is
different from the background of a window, which can be set with either XSetwindow-

Background or XSetWindowBackgroundPixmap.

The specified pixel value must be returned by BlackPixel, WhitePixel, or one of the rou
tines that allocate colors.

Errors

BadGC

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC,
XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSet-
Dashes, XSetFillRule, XSetFillStyle, XSetForeground, XSetFunction,
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, XSetState,
XSetStipple, XSetSubwindowMode, XSetTSOrigin.

Xlib Reference Manual 425

XSetClaSSHint V X,,b- Window Manager Hints-

Name

XSetClassHint set the XA_WM_CLASS property of a window.

Synopsis

XSetClassHint ( display, w, class_hints)
Display * display;
Window w;
XClassHint *class_hints ;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenDi spl ay .

w Specifies the ID of the window for which the class hint is to be set.

class_hints Specifies the XClassHint structure that is to be used.

Description

XSetClassHint sets the XA_WM_CLASS property for the specified window. The window
manager may (or may not) read this property, and use it to get resource defaults that apply to
the window manager s handling of this application.

The XClassHint structure set contains res_class, which is the name of the client such as
"emacs", and res_name, which is the first of the following that applies:

command line option (-rn name)

a specific environment variable (e.g., RESOURCE_NAME)

the trailing component of argv [ ] (after the last /)

For more information, see Volume One, Chapter 10, Inter client Communication.

Errors

BadAlloc
BadWindow

Structures

typedef struct {

char *res_name;

char *res_class;
} XClassHint;

Related Commands

XAllocClassHint,XFetchName,XGetClassHint,XGetIconName,XGet Icon-
Sizes, XGetNormalHints, XGetSizeHints, XGetTransientForHint, XGet-
WMHints, XGetZoomHints, XSetCommand, XSet IconName, XSetlconSizes,
XSetNormalHints, XSetSizeHints, XSetTransientForHint, XSetWMHints,
XSetZoomHints, XStoreName, XSetWMProperties.

426 Xlib Reference Manual

-XHb - Graphics Con,x, XSetClipMask

Name

XSetClipMask set clip_mask pixmap in a graphics context.

Synopsis

XSetClipMask (display , gc, clip_mask)
Display *display;
GC gc;
Pixmap clip_mask;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

gc Specifies the graphics context.

clip_jnas;c Specifies a pixmap of depth 1 to be used as the clip mask. Pass the constant
None if no clipping is desired.

Description

XSetClipMask sets the clip_mask component of a GC to a pixmap. The clip_mask fil
ters which pixels in the destination are drawn. If clip_mask is set to None, the pixels are
always drawn, regardless of the clip origin. Use XSetClipRectangles to set clip_mask
to a set of rectangles, or XSetRegion to set clip_mask to a region.

For more information, see Volume One, Chapter 5, The Graphics Context.
Errors

BadGC

BadMatch

BadPixmap

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC,
XSetArcMode, XSetBackground, XSetClipOrigin, XSetClipRectangles,
XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground, XSet-
Function, XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask,
XSetState, XSetStipple, XSetSubwindowMode, XSetTSOrigin.

Xlib Reference Manual 427

XSetClipOrigin \ X1|b _ Graph|cs Contexl _

Name

XSetClipOrigin set the clip origin in a graphics context.

Synopsis

XSetClipOrigin (display, gc , clip_x_origin, clip_y_origin)
Display * display;
GC gc;
int clip_x_origin f cl ip_y_ origin ;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

gc Specifies the graphics context.

clip_x_origin Specify the coordinates of the clip origin (interpreted later relative to the
clip_y_origin window drawn into with this GC).

Description

XSetClipOrigin sets the clip_x_origin and clip_y_origin components of a GC.
The clip origin controls the position of the clip_mask in the GC, which filters which pixels
are drawn in the destination of a drawing request using this GC.

For more information, see Volume One, Chapter 5, The Graphics Context.
Errors

BadGC

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC,
XSetArcMode, XSetBackground, XSetClipMask, XSetClipRectangles, XSet-
Dashes, XSetFillRule, XSetFillStyle, XSetForeground, XSetFunction,
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, XSetState,
XSetStipple, XSetSubwindowMode, XSetTSOrigin.

428 Xlib Reference Manual

Xlib - Graphics Context -

J XSetClipRectangles

Name

XSetClipRectangles change clip_mask in a graphics context to a list of rectangles.

Synopsis

XSetClipRectangles (display, gc , clip_x_orlgin,

clip_y_origin, rectangles, nrects , ordering)
Display * display;
GC gc;

int clip_x_origin r clip_y_ origin;
XRectangle rectangles [] ;
int nrects;
int ordering;

Arguments

di splay Specifies a connection to an X server; returned from XOpenDi splay.

gc Specifies the graphics context.

clip_x_ origin Specify the x and y coordinates of the clip origin (interpreted later rela-
clip_y_ origin live to the window drawn into with this GC).

rectangles Specifies an array of rectangles. These are the rectangles you want draw

ing clipped to.

nrects Specifies the number of rectangles.

ordering Specifies the ordering relations of the rectangles. Possible values are

Unsorted, YSorted, YXSorted, or YXBanded.

Description

XSetClipRectangles changes the clip_mask component in the specified GC to the
specified list of rectangles and sets the clip origin to clip_x_origin and clip_y_ori-
gin. The rectangle coordinates are interpreted relative to the clip origin. The output from
drawing requests using that GC are henceforth clipped to remain contained within the rectan
gles. The rectangles should be nonintersecting, or the graphics results will be undefined. If the
list of rectangles is empty, output is effectively disabled as all space is clipped in that GC. This
is the opposite of a clip_mask of None in XCreateGC, XChangeGC, or XSetClipMask.

If known by the client, ordering relations on the rectangles can be specified with the order
ing argument This may provide faster operation by the server. If an incorrect ordering is
specified, the X server may generate a BadMatch error, but it is not required to do so. If no
error is generated, the graphics results are undefined. Unsorted means the rectangles are in
arbitrary order. YSorted means that the rectangles are nondecreasing in their y origin.
YXSorted additionally constrains YSorted order in that all rectangles with an equal y origin
are nondecreasing in their x origin. YXBanded additionally constrains YXSorted by requir
ing that, for every possible horizontal y scan line, all rectangles that include that scan line have
identical y origins and y extents.

Xlib Reference Manual 429

XSetClip Rectangles (continued) Xlib - Graphics Context

To cancel the effect of this command, so that there is no clipping, pass None as the
clip_mask in XChangeGC orXSetClipMask.

For more information, see Volume One, Chapter 5, The Graphics Context.
Structures

typedef struct {

short x,y;

unsigned short width, height;
} XRectangle;

Errors

BadAlloc

BadGC

BadMatch Incorrect ordering (error message server-dependent).

BadValue

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC,
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSet-
Dashes, XSetFillRule, XSetFillStyle, XSetForeground, XSetFunction,
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, XSetState,
XSetStipple, XSetSubwindowMode, XSetTSOrigin.

430 Xlib Reference Manual

-XHb-C,ien, Connections / XSetCIOSeDOWnMOde

Name

XSetCloseDownMode change the close down mode of a client.

Synopsis

XSetCloseDownMode (display, cl ose_mode )
Display * display;
int close_mode;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

close_mode Specifies the client close down mode you want. Pass one of these constants:

DestroyAll, RetainPermanent, or RetainTemporary.

Description

XSetCloseDownMode defines what will happen to the client s resources at connection close.
A connection between a client and the server starts in DestroyAll mode, and all resources
associated with that connection will be freed when the client process dies. If the close down
mode is RetainTemporary or RetainPermanent when the client dies, its resources live
on until a call to XKillClient. The resource argument of XKillClient can be used to
specify which client to kill, or it may be the constant AllTemporary, in which case XKill
Client kills all resources of all clients that have terminated in RetainTemporary mode.

One use of RetainTemporary or RetainPermanent might be to allow an application to
recover from a failure of the network connection to the display server. After restarting, the
application would need to be able to identify its own resources and reclaim control of them.

Errors

BadValue

Related Commands

XKillClient.

Xlib Reference Manual

^-Window Manager Hints-

Name

XSetCommand set the XA_WM_COMMAND atom (command line arguments).

Synopsis

XSetCommand (display, w, argv, argc)
Display * display ;
Window w;
char **argv;
int argc;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenDi spl ay .

w Specifies the ID of the window whose atom is to be set.

argv Specifies a pointer to the command and arguments used to start the application.

argc Specifies the number of arguments.

Description

XSetCommand is superseded by XSetWMCommand in Release 4.

XSetCommand is used by the application to set the XA_WM_COMMAND property for the window
manager with the command and its arguments used to invoke the application.

XSetCommand creates a zero-length property if argc is zero.

Use this command only if not calling XSetStandardProperties or XSet-
WMProperties.

Errors

BadAlloc
BadWindow

Related Commands

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal-
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XGetZoom-
Hints,XSetClassHint,XSetIconName,XSetIconSizes,XSetNormalHints,
XSetSizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints,
XStoreName.

432 Xlib Reference Manual

Xlib - Graphics Context-

XSetDashes

Name

XSetDashes set a pattern of line dashes in a graphics context.

Synopsis

XSetDashes (display, gc , dash_offset, dash_list, n)
Display * display ;
GC gc;

int dash_offset ;
char dash_list[] ;
int n;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenD i spl ay .

gc Specifies the graphics context.

dash_offset Specifies the phase of the pattern for the dashed line style.

dasi_list Specifies the dash list for the dashed line style. An odd-length list is equiva
lent to the same list concatenated with itself to produce an even-length list.

n Specifies the length of the dash list argument.

First pixel
in line

Last pixel
in line

dotted (3,1)
dot_dashed (3,4,3,1)
short_dashed (4,4)
long_dashed (4,7)
odd dashed (1, 2, 3)

1 2345678 910111213141516171819202122

Pixels

Xlib Reference Manual

433

XSetDasheS (continued) Xlib - Graphics Context

Description

XSetDashes sets the dashes component of a GC. The initial and alternating elements of
the dash_list argument are the dashes, the others are the gaps. All of the elements must be
nonzero, with lengths measured in pixels. The dash_offset argument defines the phase of
the pattern, specifying how many pixels into the dash_list the pattern should actually begin
in the line drawn by the request.

n specifies the length of dash_list. An odd value for n is interpreted as specifying the
dash_list concatenated with itself to produce twice as long a list.

Ideally, a dash length is measured along the slope of the line, but server implementors are only
required to match this ideal for horizontal and vertical lines. Failing the ideal semantics, it is
suggested that the length be measured along the major axis of the line. The major axis is
defined as the x axis for lines drawn at an angle of between -45 and +45 degrees or between
315 and 225 degrees from the x axis. For all other lines, the major axis is the y axis.

See Volume One, Chapter 5, The Graphics Context, for further information.

Errors

BadAlloc

BadGC

BadValue No values in dash_list.
Element in dash_list is 0.

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC,
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip-
Rectangles, XSetFillRule, XSetFillStyle, XSetForeground, XSet-
Function, XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask,
XSetState, XSetStipple, XSetSubwindowMode, XSetTSOrigin.

434 Xlib Reference Manual

-x.ib - Error Hand.ing / XSetErrorHandler

Name

XSetErrorHandler set a nonfatal error event handler.

Synopsis

In Release 3:

XSetErrorHandler (handler)

int (* handler) (Display *, XErrorEvent *)
InRelease4: int (*XSetErrorHandler (handler) )()

int (* handler) (Display *, XErrorEvent *)

Arguments

handler The user-defined function to be called to handle error events. If a NULL

pointer, reinvoke the default handler, which prints a message and exits.

Description

The error handler function specified in handler will be called by Xlib whenever an XError
event is received. These are nonfatal conditions, such as unexpected values for arguments, or a
failure in server memory allocation. It is acceptable for this procedure to return, though the
default handler simply prints a message and exits. However, the error handler should NOT per
form any operations (directly or indirectly) on the server.

In Release 4, XSetErrorHandler returns a pointer to the previous error handler.

The function is called with two arguments, the display variable and a pointer to the XError
Event structure. Here is a trivial example of a user-defined error handler:

int myhandler (display, myerr)
Display *display;
XErrorEvent *myerr;
{

char msg[80] ;

XGetErrorText (display, myerr-&gt;error_code, msg, 80);

fprintf (stderr, "Error code %s\n", msg);
}

This is how the example routine would be used in XSetErrorHandler.
XSetErrorHandler (myhandler) /

Note that XSetErrorHandler is one of the few routines that does not require a display
argument. The routine that calls the error handler gets the display variable from the XError
Event structure.

The error handler is not called on BadName errors from OpenFont, LookupColor, and
AllocNamedColor protocol requests, on BadFont errors from a QueryFont protocol
request, or on BadAlloc or BadAccess errors. These errors are all indicated by Status
return value of zero in the corresponding Xlib routines, which must be caught and handled by
the application.

Use XlOErrorHandler to provide a handler for I/O errors such as network failures or server
host crashes.

Xlib Reference Manual 435

XSetErrorHandler (continued) Xlib - Error Handling

In the XErrorEvent structure shown below, the serial member is the number of requests
(starting from 1) sent over the network connection since it was opened. It is the number that
was the value of the request sequence number immediately after the failing call was made. The
request_code member is a protocol representation of the name of the procedure that failed
and is defined in &lt;Xll/X.h&gt;.

For more information, see Volume One, Chapter 3, Basic Window Program.
Structures

typedef struct {
int type

Display *display; /* display the event was read from */

XID resourceid; /* resource ID */

unsigned long serial; /* serial number of failed request */
unsigned char error_code; /* error code of failed request */
unsigned char request_code; /* major opcode of failed request */
unsigned char minor_code; /* minor opcode of failed request */

} XErrorEvent;

Related Commands

XDisplayName, XGetErrorDatabaseText, XGetErrorText, XSetAf ter-
Function, XSetlOErrorHandler, XSynchronize.

436 Xlib Reference Manual

Xlib - Graphics Context-

XSetFillRule

Name

XSetFillRule set the fill rule in a graphics context.

Synopsis

XSetFillRule (display, gc, fill_rule)
Display * display;
GC gc;
int fill_rule;

Arguments

display Specifies a connection to an X server; returned from XQpenDi splay.

gc Specifies the graphics context.

fill_rule Specifies the fill rule you want to set for the specified graphics context. Pos
sible values are EvenOddRule orWindingRule.

Description

XSetFillRule sets the fill_rule component of a GC. The fill_rule member of the
GC determines what pixels are drawn in XFillPolygon requests. Simply put, Winding-
Rule fills overlapping areas of the polygon, while EvenOddRule does not fill areas that
overlap an odd number of times. Technically, EvenOddRule means that the point is drawn if
an arbitrary ray drawn from the point would cross the path determined by the request an odd
number of times. WindingRule indicates that a point is drawn if a point crosses an unequal
number of clockwise and counterclockwise path segments, as seen from the point.

Outline of polygon to fill

EvenOddRul&lt;

WindingRule

Xlib Reference Manual

437

XSetFillRule (continued) Xlib - Graphics Context

A clockwise-directed path segment is one which crosses the ray from left to right as observed
from the point. A counterclockwise segment is one which crosses the ray from right to left as
observed from the point. The case where a directed line segment is coincident with the ray is
uninteresting because you can simply choose a different ray that is not coincident with a seg
ment

All calculations are performed on infinitely small points, so that if any point within a pixel is
considered inside, the entire pixel is drawn. Pixels with centers exactly on boundaries are con
sidered inside only if the filled area is to the right, except that on horizontal boundaries, the
pixel is considered inside only if the filled area is below the pixel.

See Volume One, Chapter 5, The Graphics Context, for more information.

Errors

BadGC
BadValue

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC,
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip-
Rectangles, XSetDashes, XSetFillStyle, XSetForeground, XSetFunction,
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, XSetState,
XSetStipple, XSetSubwindowMode, XSetTSOrigin.

438 Xlib Reference Manual

Xlib - Graphics Context-

XSetFillStyle

Name

XSetFillStyle set the fill style in a graphics context.

Synopsis

XSetFillStyle (display, gc , fill_style)
Display * display;
GC gc;
int fill_style;

Arguments

display

Specifies a connection to an X server; returned from xopenDi splay.

gc Specifies the graphics context.

fill_style Specifies the fill style for the specified graphics context. Possible values are

FillSolid, Fill-Tiled, FillStippled, or FillOpaque-
Stippled.

GC foreground
GC background
Undrawn Pixels M

Tile

Stipple

FillSolid

FillTiled

FillStippled FillOpaqueStippled

Description

XSetFillStyle sets the fill_style component of a GC. The fill_style defines the
contents of the source for line, text, and fill requests. FillSolid indicates that the pixels rep
resented by set bits in the source are drawn in the foreground pixel value, and unset bits in
the source are not drawn. FillTiled uses the tile specified in the GC to determine the
pixel values for set bits in the source. FillOpaqueStippled specifies that bits set in the
stipple are drawn in the foreground pixel value and unset bits are drawn in the back
ground. FillStippled draws bits set in the source and set in the stipple in the fore
ground color, and leaves unset bits alone.

Xlib Reference Manual

439

XSetFillStyle (continued) Xlib - Graphics Context

For more information, see Volume One, Chapter 5, The Graphics Context.
Errors

BadGC
BadValue

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC,
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip-
Rectangles, XSetDashes, XSetFillRule, XSetForeground, XSetFunction,
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, XSetState,
XSetStipple, XSetSubwindowMode, XSetTSOrigin.

Xlib Reference Manual

- XI ,-Pon,s

Name

XSetFont set the current font in a graphics context.

Synopsis

XSetFont (display, gc, font)
Display * display;
GC gc;
Font font;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenDi spl ay.

gc Specifies the graphics context.

f on t Specifies the ID of the font to be used.

Description

XSetFont sets the font in the GC. Text drawing requests using this GC will use this font
only if the font is loaded. Otherwise, the text will not be drawn.

For more information, see Volume One, Chapter 5, The Graphics Context.
Errors

BadFont
BadGC

Related Commands

Xlib Reference Manual 44 1

XSetFontPath ~\

Xlib- Fonts-

Name

XSetFontPath set the font search path.

Synopsis

XSetFontPath ( display, directories, ndirs)
Display * display;
char ** directories;
int ndirs;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

directories Specifies the directory path used to look for the font. Setting the path to the
empty list restores the default path defined for the X server.

ndi rs Specifies the number of directories in the path.

Description

XSetFontPath defines the directory search path for font lookup for all clients. Therefore the
user should construct a new directory search path carefully by adding to the old directory
search path obtained by XGetFontPath. Passing an invalid path can result in preventing the
server from accessing any fonts. Also avoid restoring the default path, since some other client
may have changed the path on purpose.

The interpretation of the strings is operating system dependent, but they are intended to specify
directories to be searched in the order listed. Also, the contents of these strings are operating
system specific and are not intended to be used by client applications.

The meaning of errors from this request is system specific.

Errors

BadValue

Related Commands

442 Xlib Reference Manual

-x, lb -Graph,c,con,, / XSetForeground

Name

XSetForeground set the foreground pixel value in a graphics context.

Synopsis

XSetForeground (display, gc, foreground)
Display * display ;
GC gc;
unsigned long foreground;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

gc Specifies the graphics context.

foreground Specifies the foreground pixel value you want for the specified graphics con
text

Description

XSetForeground sets the foreground component in a GC. This pixel value is used for
set bits in the source according to the f ill_style. This pixel value must be returned by
BlackPixel, whitePixel, or a routine that allocates colors.

See Volume One, Chapter 5, The Graphics Context, for more information on the GC.

Errors

BadGC

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC,
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip-
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetFunction,
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, XSetState,
XSetStipple, XSetSubwindowMode, XSetTSOrigin.

Xlib Reference Manual 443

XSetFu notion

Xlib - Graphics Context

Name

XSetFunction set the bitwise logical operation in a graphics context.

Synopsis

XSetFunction (display, gc, function)
Display *display;
GC gc;
int function;

Arguments

display

function

Specifies a connection to an X server; returned from XOpenDi splay.
Specifies the graphics context.

Specifies the logical operation you want for the specified graphics context. See
Description for the choices and their meanings.

Description

XSetFunction sets the logical operation applied between the source pixel values (generated
by the drawing request) and existing destination pixel values (already in the window or pix-
map) to generate the final destination pixel values in a drawing request (what is actually drawn
to the window or pixmap). Of course, the plane_mask and clip_mask in the GC also
affect this operation by preventing drawing to planes and pixels respectively. GXcopy, GXin-
vert, and GXxor are the only logical operations that are commonly used.

See Volume One, Chapter 5, The Graphics Context, for more information about the logical
function.

The function syn
Symbol

ibolsar
Bit

d their logical definitions are:
Meaning

GXclear

0x0

GXand

Oxl

src AND dst

GXandReverse

0x2

srcAND(NOTdst)

GXcopy

0x3

src

GXandlnverted

0x4

(NOT src) AND dst

GXnoop

0x5

dst

GXxor

0x6

src XOR dst

GXor

0x7

src OR dst

GXnor

0x8

(NOT src) AND (NOT dst)

GXequiv

0x9

(NOT src) XOR dst

GXinvert

Oxa

(NOT dst)

GXorReverse

Oxb

src OR (NOT dst)

GXcopy Inverted

Oxc

(NOT src)

GXorlnverted

Oxd

(NOT src) OR dst

GXnand

Oxe

(NOT src) OR (NOT dst)

GXset

Oxf

444

Xlib Reference Manual

Xlib - Graphics Context (continued) XSetFunctlon

Errors

BadGC
BadValue

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC,
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip-
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground,
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, XSetState,
XSetStipple, XSetSubwindowMode, XSetTSOrigin.

Xlib Reference Manual 445

XSetGraphicsExposures \

Xlib - Graphics Context-

Name

XSetGraphicsExposures set the graphics_exposures component in a graphics context.

Synopsis

XSetGraphicsExposures ( display, gc , graph! cs_exposures)
Display *display;
GC gc;
Bool graphics_exposures ;

Arguments

display Specifies a connection to an X server; returned from XQpenDisplay.

gc Specifies the graphics context.

graphi cs_exposures

Specifies whether you want GraphicsExpose and NoExpose events when
calling XCopyArea and XCopyPlane with this graphics context.

Description

XSetGraphicsExposure sets the graphics_exposures member of a GC. If
graphi cs_exposures is True, GraphicsExpose events will be generated when
XCopyArea and XCopyPlane requests cannot be completely satisfied because a source
region is obscured, and NoExpose events are generated when they can be completely satis
fied. If graphi cs_exposures is False, these events are not generated.

These events are not selected in the normal way with XSelect Input. Setting the
graphi cs_exposures member of the GC used in the CopyArea or CopyPlane request
is the only way to select these events.

For more information, see Volume One, Chapter 5, The Graphics Context.
Errors

BadGC
BadValue

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC,
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip-
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground,
XSetFunction, XSetLineAttributes, XSetPlaneMask, XSetState, XSet-
Stipple, XSetSubwindowMode, XSetTSOrigin.

446 Xlib Reference Manual

-X,, b -W,ndowMana g erH,n,s XSetlCOnNaiTie

Name

XSetlconName set the name to be displayed in a window s icon.

Synopsis

XSetlconName (display, w, icon_name)
Display * display ;
Window w;
char *icon_name;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenDi splay.

w Specifies the ID of the window whose icon name is being set.

i con_name Specifies the name to be displayed in the window s icon. The name should be
a null-terminated string. This name is returned by any subsequent call to
XGetlconName.

Description

XSetlconName is superseded by XSetWMlconName in Release 4.

XSetlconName sets the XA_WM_ICON_NAME property for a window. This is usually set by an
application for the window manager. The name should be short, since it is to be displayed in
association with an icon.

XSetStandardProperties (in Release 4) or XSetWMProperties (in Release 4) also
set this property.

For more information, see Volume One, Chapter IQJnterclient Communication.
Errors

BadAlloc
BadWindow

Related Commands

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal-
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XGetZoom-
Hints, XSetClassHint, XSetCorranand, XSetlconSizes, XSetNormalHints,
XSetSizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints,
XStoreName.

Xlib Reference Manual 447

XSetlconSizes V XIib _ Window Manager Hints _

Name

XSetlconSizes set the value of the XA_WM_ICON_SIZE property.

Synopsis

XSetlconSizes (display, w, size_list, count)
Display * display ;
Window ur;

XlconSize *size_list;
int count;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenDi spl ay .

w Specifies the ID of the window whose icon size property is to be set. Nor

mally the root window.

si ze_l i s t Specifies a pointer to the size list.

count Specifies the number of items in the size list.

Description

XSetlconSizes is normally used by a window manager to set the range of preferred icon
sizes in the XA_WM_ICON_SIZE property of the root window.

Applications can then read the property with XGetlconSizes.
Structures

typedef struct {

int min_width, min_height;

int max_width, max_height;

int width_inc, height_inc;
} XlconSize;

Errors

BadAlloc
BadWindow

Related Commands

XAllocIconSize, XFetchName, XGetClassHint, XGetlconName, XGetlcon
Sizes, XGetNormalHints,XGetSizeHints,XGetTransientForHint,XGet-
WMHints, XGetZoomHints, XSetClassHint, XSetCommand, XSetlconName,
XSetNormalHints, XSetSizeHints, XSetTransientForHint, XSetWMHints,
XSetZoomHints, XStoreName.

448 XIib Reference Manual

J XSetlnputFocus

Xlib - Input Handling

Name

XSetlnputFocus set the keyboard focus window.

Synopsis

XSetlnputFocus (display, focus, revert_to, time)
Display *display;
Window focus;
int revert_to;
Time time;

Arguments

display Specifies a connection to an X server; returned from XQpenDisplay.

focus Specifies the ID of the window you want to be the keyboard focus. Pass the

window ID, PointerRoot, or None.

revert_to Specifies which window the keyboard focus reverts to if the focus window
becomes not viewable. Pass one of these constants: RevertToParent,
RevertToPointerRoot, or RevertToNone. Must not be a window ID.

time Specifies the time when the focus change should take place. Pass either a

timestamp, expressed in milliseconds, or the constant CurrentTime. Also
returns the time of the focus change when CurrentTime is specified.

Description

XSetlnputFocus changes the keyboard focus and the last-focus-change time. The function
has no effect if time is earlier than the current last-focus-change time or later than the current
X server time. Otherwise, the last-focus-change time is set to the specified time, with
CurrentTime replaced by the current X server time.

XSetlnputFocus generates Focusln and FocusOut events if focus is different from
the current focus.

XSetlnputFocus executes as follows, depending on what value you assign to the focus
argument:

If you assign None, all keyboard events are discarded until you set a new focus window.
In this case, revert_to is ignored.

If you assign a window ID, it becomes the main keyboard s focus window. If a generated
keyboard event would normally be reported to this window or one of its inferiors, the
event is reported normally; otherwise, the event is reported to the focus window. The
specified focus window must be viewable at the time of the request (else a BadMatch
error). If the focus window later becomes not viewable, the focus window will change to
the re vert_ to argument

If you assign PointerRoot, the focus window is dynamically taken to be the root win
dow of whatever screen the pointer is on at each keyboard event In this case,
revert_to is ignored. This is the default keyboard focus setting.

If the focus window later becomes not viewable, XSetlnputFocus evaluates the
re vert_ to argument to determine the new focus window:

Xlib Reference Manual 449

XSetlnpUtFOGUS (continued) Xlib - Input Handling

If you assign RevertToParent, the focus reverts to the parent (or the closest viewable
ancestor) automatically with a new revert_to argument of Revert ToName.

If you assign RevertToPointerRoot or RevertToNone, the focus reverts to that
value automatically. Focus in and FocusOut events are generated when the focus
reverts, but the last focus change time is not affected.

Errors

BadMatch focus window not viewable when XSetlnputFocus called.

BadValue
BadWindow

Related Commands

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped-
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued,
XGetlnputFocus.XGetMotionEvents, XI f Event, XMaskEvent,XNextEvent,
XPeekEvent, XPeeklf Event, XPending, XPutBackEvent, XSelectlnput,
XSendEvent , XSynchroni ze, XWindowEvent.

450 Xlib Reference Manual

f XSetlOErrorHandler

Xlib - Error Handling

Name

XSetErrorHandler set a nonfatal error event handler.

Synopsis

In Release 3:

XSetlOErrorHandler (ha/idler)

int (* handler) (Display *, XErrorEvent *)
I n Release 4:
int (*XSetIOErrorHandler (handler) ) ()

int (* handler) (Display *, XErrorEvent *)

Arguments

handler Specifies user-defined fatal error handling routine. If NULL, reinvoke the

default fatal error handler.

Description

XSetlOErrorHandler specifies a user-defined error handling routine for fatal errors. This
error handler will be called by Xlib if any sort of system call error occurs, such as the connec
tion to the server being lost. The called routine should not return. If the I/O error handler does
return, the client process will exit.

If handler is a NULL pointer, the default error handler is reinstated. The default I/O error
handler prints an error message and exits.

In Release 4, XSetlOErrorHandler returns a pointer to the previous error handler.
For more information, see Volume One, Chapter 3, Basic Window Program.

Related Commands

XDisplayName, XGetErrorDatabaseText, XGetErrorText, XSetAf ter-
Function, XSetErrorHandler, XSynchronize.

Xlib Reference Manual 451

XSetLineAttributes

Xlib - Graphics Context-

Name

XSetLineAttributes set the line drawing components in a graphics context.

Synopsis

XSetLineAttributes (display, gc, line_width, line_style,

cap_style , join_style)
Display *display;
GC gc;

unsigned int li/ie_v/idth;
int li/ie_style;
int cap_style;
int join_style;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

gc Specifies the graphics context.

line_style

LineSolid

LineOnOffDash

Line/Double Dash

cap_style

CapNotLast CapButt

join_style

CapRound

CapPro jecting

JoinRound

JoinMiter

JoinBevel

fill_style

Ti| e GC foreground | GC background Q Undrawn Pixels [x]

FillSolid FillTiled FillStippled FillOpaqueStippled

Stipple

Xlib Reference Manual

Xlib - Graphics Context (continued) XSetLineAttributes

line_width Specifies the line width in the specified graphics context.

line_style Specifies the line style in the specified graphics context. Possible values are

LineSolid, LineOnOf f Dash, or LineDoubleDash.

cap_style Specifies the line and cap style in the specified graphics context. Possible
values are CapNotLast, CapButt, CapRound, or CapPro jecting.

join_style Specifies the line-join style in the specified graphics context. Possible values
are JoinMiter, JoinRound, or JoinBevel. If you specify Join-
Mitre, JoinBevel is used instead if the angle separating the two lines is
less than 1 1 degrees.

Description

XSetLineAttributes sets four types of line characteristics in the GC: line_width,
line_style, cap_style, and join_style.

See the description of line and join styles in Volume One, Chapter 5, The Graphics Context.
See also XSetDashes.

A line_width of zero (0) means to use the fastest algorithm for drawing a line of one pixel
width. These lines may not meet properly with lines specified as width one or more.

Errors

BadGC
BadValue

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC,
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip-
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground,
XSetFunction, XSetGraphicsExposures, XSetPlaneMask, XSetState, XSet-
Stipple, XSetSubwindowMode, XSetTSOrigin.

Xlib Reference Manual 453

XSetModifierMapping \ x ,, b - Keyboard-

Name

XSetModifierMapping set keycodes to be used as modifiers (Shift, Control, etc.).

Synopsis

int XSetModif ierMapping ( display, mod_map)
Display *display;
XModif ierKeymap *mod_map;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

mod_map Specifies the XModif ierKeymap structure containing the desired modifier
key codes.

Description

XSetModifierMapping is one of two ways to specify the keycodes of the keys that are to
be used as modifiers (like Shift, Control, etc.). XSetModifierMapping specifies all the
keycodes for all the modifiers at once. The other, easier, way is to use xinsert-
Modif iermapEntry and XDeleteModif iermapEntry, which add or delete a single
keycode for a single modifier key. XSetModifierMapping does the work in a single call,
but the price of this call is that you need to manually set up the XModif ierKeymap structure
pointed to by mod_map. This requires you to know how the XModif ierKeymap structure is
defined and organized, as described in the next three paragraphs.

The XModif ierKeymap structure for the mod_map argument should be created using
XNewModif ierMap or XGetModif ierMapping. The Max_keypermod element of the
structure specifies the maximum number of keycodes that can be mapped to each modifier. You
define this number but there may be an upper limit on a particular server.

The modif iermap element of the structure is an array of keycodes. There are eight by
max_keypermod keycodes in this array: eight because there are eight modifiers, and
max_keypermod because that is the number of keycodes that must be reserved for each mod
ifier.

The eight modifiers are represented by the constants ShiftMaplndex, LockMaplndex,
ControlMapIndex, ModlMapIndex, Mod2MapIndex, ModSMapIndex, Mod4Map-
Index, and ModSMapIndex. These are not actually used as arguments, but they are conve
nient for referring to each row in the modif iermap structure while filling it. The definitions
of these constants are shown in the Structures section below.

Now you can interpret the modif iermap array. For each modifier in a given modifier-
map, the keycodes which correspond are from modif iermap [index *
max_keypermod] to modif iermap [( (index + 1) * max_keyspermod) -1]
where index is the appropriate modifier index definition (ShiftMaplndex, LockMap
lndex, etc.). You must set the mod_map array up properly before calling XSetModifier
Mapping. Now you know why XInsertModif ierMapEntry and XDeleteModif ier-
MapEntry were created!

Zero keycodes are ignored. No keycode may appear twice anywhere in the map (otherwise, a
BadValue error is generated). In addition, all of the nonzero keycodes must be in the range

454 Xlib Reference Manual

Xlib - Keyboard (continued) XSetModifierMapping

specified by min_keycode and max_keycode in the Display structure (otherwise a
BadValue error occurs).

A server can impose restrictions on how modifiers can be changed. For example, certain keys
may not generate up transitions in hardware, certain keys may always auto-repeat and therefore
be unsuitable for use as modifiers, or multiple modifier keys may not be supported. If a restric
tion is violated, then the status reply is MappingFailed, and none of the modifiers are
changed.

XSetModifierMapping returns MappingSuccess or MappingBusy. The server gen
erates a MappingNotif y event on a MappingSuccess status. If the new keycodes speci
fied for a modifier differ from those currently defined and any (current or new) keys for that
modifier are in the down state, then the status reply is MappingBusy, and none of the modifi
ers are changed.

A value of zero for modif iermap indicates that no keys are valid as any modifier.
Structures

typedef struct {

int max_keypermod; /* server s max # of keys per modifier */
KeyCode *modif iermap; /* an 8 by max_keypermod array */

} XModifierKeymap;

c c

/* Modifier name symbols. Used to build a SetModif ierMapping request

to read a GetModif ierMapping request. */

#define ShiftMapIndex

#define LockMapIndex 1

#define ControlMapIndex 2

#define ModlMapIndex 3

#define Mod2MapIndex 4

tdefine Mod3MapIndex 5

#define ModlMapIndex 6

#define ModSMapIndex 7

Errors

BadAlloc

BadValue Keycode appears twice in the map.

Keycode &lt; disp-Zay-&gt;min_keycode or
keycode &gt; display-&gt;max_keycode.

Related Commands

XChangeKeyboardMapping, XDeleteModif iermapEntry, XDelete-
Modif iermapEntry, XFreeModif iermap, XGetKeyboardMapping, XGet-
Modif ierMapping, XInsertModif iermapEntry, XInsertModif iermapEntry,
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym,
XLookupString, XNewModif ierMap, XQueryKeymap, XRebindKeysym,
XRefreshKeyboardMapping, XStringToKeysym.

Xlib Reference Manual 455

XSetNormalHints V Xlib _ Wlndow Manager Hlnts _

Name

XSetNormalHints set the size hints property of a window in normal state (not zoomed or
iconified).

Synopsis

void XSetNormalHints (display, w, hints)
Display *display;
Window w,
XSizeHints *hints;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the window ID.

hints Specifies a pointer to the sizing hints for the window in its normal state.

Description

XSetNormalHints has been superseded by XSetWMNormalHints as of Release 4.

XSetNormalHints sets the XA_WM_NORMAL_HINTS property for the specified window.
Applications use XSetNormalHints to inform the window manager of the size or position
desirable for that window. In addition, an application wanting to move or resize itself should
call XSetNormalHints specifying its new desired location and size, in addition to making
direct X calls to move or resize. This is because some window managers may redirect window
configuration requests, but ignore the resulting events and pay attention to property changes
instead.

To set size hints, an application must assign values to the appropriate elements in the hints
structure, and also set the flags field of the structure to indicate which members have
assigned values and the source of the assignment These flags are listed in the Structures sec
tion below.

For more information on using hints, see Volume One, Chapter WJnterclient Communication.
Structures

typedef struct {

long flags; /* which fields in structure are defined */

int x, y;

int width, height;

int min_width, min_height;

int max_width, max_height;

int width_inc, height_inc;

struct {

int x; /* numerator */

int y; /* denominator */
} min_aspect, max_aspect;
} XSizeHints; /*~new fields in R4 here */

456 Xlib Reference Manual

Xlib - Window Manager Hints (continued) XSetNormalHints

#define USPosition (1L 0) /* user specified x, y */

#define USSize (1L 1) /* user specified width, height */

tdefine PPosition (1L 2) /* program specified position */

#define PSize (1L 3) /* program specified size */

tdefine PMinSize (1L 4) /* program specified minimum size */

tdefine PMaxSize (1L 5) /* program specified maximum size */

tdefine PResizelnc (1L 6) /* program specified resize increments */

tdefine PAspect (1L 7) /* program specified min/max aspect ratios */

tdefine PAllHints (PPosition I PSize | PMinSize I PMaxSize I PResizelnc | PAspect)

Errors

BadAlloc
BadWindow

Related Commands

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal-
Hints,XGetSizeHints,XGetTransientForHint,XGetWMHints,XGetZoom-
Hints,XSetClassHint,XSetCommand,XSetIconName,XSetIconSizes,XSet-
SizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints, XStore-
Name.

Xlib Reference Manual 457

XSetPlaneMask \ Xlib _ Graphlcs Comext _

Name

XSetPlaneMask set the plane mask in a graphics context.

Synopsis

XSetPlaneMask (display, gc, plane_mask)
Display * display ;
GC gc;
unsigned long plane_mask;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

gc Specifies the graphics context.

plane_mask Specifies the plane mask. You can use the macro AllPlanes if desired.

Description

XSetPlaneMask sets the plane_mask component of the specified GC. The plane_mask
determines which planes of the destination drawable are affected by a graphics request.

For more information, see Volume One, Chapter 5, The Graphics Context.

Errors

BadGC

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC,
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip-
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground,
XSetFunction, XSetGraphicsExposures, XSetLineAttributes, XSetState,
XSetStipple, XSetSubwindowMode, XSetTSOrigin.

458 Xlib Reference Manual

Xlib -Pointer

j XSetPointerMapping

Name

XSetPointerMapping set the pointer button mapping.

Synopsis

int XSetPointerMapping (display, map, nmap)
Display * display;
unsigned char map[] ;
int nmap;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

map Specifies the mapping list.

nmap Specifies the number of items in the mapping list.

Description

XSetPointerMapping sets the mapping of the pointer buttons. Elements of the map list
are indexed starting from 1. The length of the list nmap must be the same as XGet Pointer-
Mapping returns (you must call that first). The index is a physical button number, and the ele
ment of the list defines the effective button number. In other words, if map [2] is set to 1,
when the second physical button is pressed, a ButtonPress event will be generated if But-
tonlMask was selected but not if Button2Mask was selected. The button member in the
event will read Buttonl.

No two elements can have the same nonzero value (else a BadValue error). A value of zero
for an element of map disables a button, and values for elements are not restricted in value by
the number of physical buttons. If any of the buttons to be altered are currently in the down
state, the returned value is MappingBusy and the mapping is not changed.

This function returns either MappingSuccess or MappingBusy. XSetPointer
Mapping generates a MappingNotif y event when it returns MappingSuccess.

Errors

BadValue Two elements of map [ ] have same nonzero value.

nmap not equal to XGetPointerMapping return value.

Related Commands

XChangeActivePointerGrab, XChangePointerControl, XGetPointer-
Control, XGetPointerMapping, XGrabPointer, XQueryPointer, XUngrab-
Pointer, XWarpPointer.

Xlib Reference Manual 459

XSetRGBColormaps \ X1|b _ W|ndow Hanager H|ms _

Name

XSetRGBColormaps set an XStandardColormap structure.
Synopsis

void XSetRGBColormaps ( display, w, std_colormap, count, prop
erty)

Display *display;
Window w;

XStandardColormap * std_col or/nap;
int count;
Atom property;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

w Specifies the window.

std_col or/nap

Specifies the XStandardColormap structure to be used.

count Specifies the number of colormaps .

property Specifies the property name.

Availability

Release 4 and later.

Description

XSetRGBColormaps replaces the RGB colormap definition in the specified property on the
named window. If the property does not already exist, XSetRGBColormaps sets the RGB
colormap definition in the specified property on the named window. The property is stored with
a type of RGB_COLOR_MAP and a format of 32. Note that it is the caller s responsibility to honor
the ICCCM restriction that only RGB_DEFAULT_MAP contain more than one definition.

XSetRGBColormaps supersedes XSetStandardColormap.
For more information, see Volume One, Chapter 7, Color.

Structures

typedef struct {

Colormap colormap;
unsigned long red_max;
unsigned long red_mult;
unsigned long green_max;
unsigned long green_mult;
unsigned long blue_max;
unsigned long blue mult;

460 Xlib Reference Manual

Xlib - Window Manager Hints (continued) XSetRG BColormapS

unsigned long base_jpixel;

VisuallD visualid; /* added by ICCCM version 1 */

XID killid; /* added by ICCCM version 1 */

} XStandardColormap;

Errors

BadAlloc

BadAtom

BadWindow

Related Commands

XAllocStandardColormap, XGetRGBColormaps, XVisuallDFromVisual.

Xlib Reference Manual 461

XSetRegion V,

Xlib- Regions-

Name

XSetRegion set clip_mask of the graphics context to the specified region.

Synopsis

XSetRegion (display, gc, r)
Display * display;
GC gc;
Region r;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

gc Specifies the graphics context.

r Specifies the region.

Description

XSetRegion sets the clip_mask component of a GC to the specified region. Thereafter, all
drawing made with gc will be confined to the the area of intersection of the region and the
drawable.

Regions are located using an offset from a point (the region origin) which is common to all
regions. It is up to the application to interpret the location of the region relative to a drawable.
When the region is to be used as a clip_mask by calling XSetRegion, the upper-left corner
of region relative to the drawable used in the graphics request will be at (xof f set +
clip_x_origin, yof f set + clip_y_origin) , where xof f set and yof f set are
the offset of the region and clip_x_origin and clip_y_origin are elements of the GC
used in the graphics request

For more information on regions, see Volume One, Chapter 5, The Graphics Context, and
Chapter 6, Drawing Graphics and Text.

Structures

Region is a pointer to an opaque structure type.

Related Commands

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion,
XIntersectRegion, XOf f setRegion, XPointlnRegion, XPolygonRegion,
XRectlnRegion, XShrinkRegion, XSubtractRegion, XUnionRectWithRegion,
XUnionRegion, XXorRegion.

462 Xlib Reference Manual

j XSetScreenSaver

Xlib - Screen Saver

Name

XSetScreenSaver set the parameters of the screen saver.

Synopsis

XSetScreenSaver ( display, timeout , interval ,

prefer_blanking, allow_exposures)
Display *display;
int timeout, interval;
int prefer_blanking;
int allov_exposures;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

timeout Specifies the time of inactivity, in seconds, before the screen saver turns on.

interval Specifies the interval, in seconds, between screen saver invocations. This is
for intermittent changes to the display, not blanking.

prefer_bl anking

Specifies whether to enable screen blanking. Possible values are Dont-
Pref erBlanking, Pref erBlanking, or Def aultBlanking.

allow_exposures

Specifies the current screen saver control values. Possible values are Dont-
AllowExposures, AllowExposures, or Def aultExposures.

Description

XSetScreenSaver sets the parameters that control the screen saver, timeout and
interval are specified in seconds. A positive timeout enables the screen saver. A
timeout of zero (0) disables the screen saver, while a timeout of -1 restores the default. An
interval of zero (0) disables the random pattern motion. If no input from devices (key
board, mouse, etc.) is generated for the specified number of timeout seconds, the screen saver is
activated.

For each screen, if blanking is preferred and the hardware supports video blanking, the screen
will simply go blank. Otherwise, if either exposures are allowed or the screen can be regen
erated without sending exposure events to clients, the screen is tiled with the root window
background tile, with a random origin, each interval seconds. Otherwise, the state of the
screen does not change. All screen states are restored at the next input from a device.

If the server-dependent screen saver method supports periodic change, interval serves as a
hint about how long the change period should be, and a value of zero (0) hints that no periodic
change should be made. Examples of ways to change the screen include scrambling the color
map periodically, moving an icon image about the screen periodically, or tiling the screen with
the root window background tile, randomly reoriginated periodically.

For more information on the screen saver, see Volume One, Chapter 13, Other Programming
Techniques.

Xlib Reference Manual 463

XSetScreenSaver (continued) Xlib - Screen Saver

Errors

BadValue timeout &lt; -I.

Related Commands

XActivateScreenSaver, XForceScreenSaver, XGetScreenSaver, XReset-
ScreenSaver.

Xlib Reference Manual

_x,ib - s,,ec,,on, / XSetSelectionOwner

Name

XSetSelectionOwner set the owner of a selection.

Synopsis

XSetSelectionOwner ( display, selection, owner, time)
Display *display;
Atom selection;
Window owner;
Time time;

Arguments

display Specifies a connection to an X server; returned from xopenDisplay.

selection Specifies the selection atom. Predefined atoms are XA PRIMARY and

XA_SECONDARY.

owner Specifies the desired owner of the specified selection atom. This value is

either a window ID or None.

time Specifies the time when the selection should take place. Pass either a times-

tamp, expressed in milliseconds, or the constant CurrentTime.

Description

XSetSelectionOwner sets the owner and last-change time of a selection property. This
should be called by an application that supports cutting and pasting between windows (or at
least cutting), when the user has made a selection of any kind of text, graphics, or data. This
makes the information available so that other applications can request the data from the new
selection owner using xconvertselection, which generates a SeiectionRequest event
specifying the desired type and format of the data. Then the selection owner sends a
SelectionNotify using xsendEvent, which notes that the information is stored in the selec
tion property in the desired format or indicates that it couldn t do the conversion to the desired
type.

If owner is specified as None, then this client is giving up ownership voluntarily. Otherwise,
the new owner is the client executing the request

If the new owner is not the same as the current owner of the selection, and the current owner is
a window, then the current owner is sent a SeiectionClear event. This indicates to the old
owner that the selection should be unhighlighted.

If the selection owner window is later destroyed, the owner of the selection automatically
reverts to None.

The value you pass to the time argument must be no earlier than the last-change time of the
specified selection, and no later than the current time, or the selection is not affected. The new
last-change time recorded is the specified time, with CurrentTime replaced by the current
server time. If the X server reverts a selection owner to None, the last-change time is not
affected.

For more information on selections, see Volume One, Chapter 10, Inter client Communication.

Xlib Reference Manual 465

XSetSeleCtionOwner (continued) Xlib - Selections

Errors

BadAtom
BadWindow

Related Commands

XConve rt Select! on, XGet Select ionOwner.

466

Xlib Reference Manual

-X,,b-W,ndowManag e rH,n,, XSetSizeHitltS

Name

XSetSizeHints set the value of any property of type XA_SIZE_HINTS.

Synopsis

XSetSizeHints (display, w, hints, property)
Display *display;
Window w;

XSizeHints *hints;
Atom property;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenDi spl ay .

v Specifies the window ID.

hints Specifies a pointer to the size hints.

property Specifies the property atom.

Description

XSetSizeHints has been superseded by XSetWMSizeHints as of Release 4.

XSetSizeHints sets the named property on the specified window to the specified XSize
Hints structure. This routine is useful if new properties of type XA_WM_SIZE_HINTS are
defined. The predefined properties of that type have their own set and get functions, XSet-
NormalHints and XSetZoomHints (XSetWMHints in Release 4 zoom hints are obso
lete).

The flags member of XSizeHints must be set to the OR of the symbols representing each
member to be set

For more information on using hints, see Volume One, Chapter IQJnterclient Communication.
Structures

typedef struct {

long flags; /* which fields in structure are defined */

int x, y;

int width, height;

int min_width, min_height;

int max_width, max_height;

int width_inc, height_inc;

struct {

int x; /* numerator */

int y; /* denominator */
} min_aspect, max_aspect;
} XSizeHints;

/* flags argument in size hints */

#define USPosition (1L 0) /* user specified x, y */

tdefine USSize (1L 1) /* user specified width, height */

#define PPosition (1L 2) /* program specified position */

#define PSize (1L 3) /* program specified size */

Xlib Reference Manual 467

XSetSlzeHintS (continued) Xlib - Window Manager Hints

tdefine PMinSize (1L 4) /* program specified minimum size */

tdefine PMaxSize (1L 5) /* program specified maximum size */

#define PResizelnc (1L 6) /* program specified resize increments */

tdefine PAspect (1L 7) /* program specified min/max aspect ratios */

tdefine PAllHints (PPosit ion I PSize I PMinSize I PMaxSize | PResizelnc | PAspect)

Errors

BadAlloc

BadAtom

BadWindow

Related Commands

XFetchName,XGetClassHint,XGetIconName,XGetIconSizes,XGetNormal-
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XGetZoom-
Hints, XSetClassHint, XSetCommand, XSetlconName, XSetlconSizes, XSet-
NormalHints, XSetTransientForHint, XSetWMHints, XSetZoomHints,
XStoreName.

Xlib Reference Manual

Xlib - Colormaps-

J XSetStandardColormap

Name

XSetStandardColormap change the standard colormap property.

Synopsis

void XSetStandardColormap ( display, w, cmap_info, property)
Display * display;
Window w;

XStandardColormap *cmap_info;
Atom property;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenDi spl ay .
w Specifies the ID of the window with which this colormap will be associated.

cmap_info Specifies the filled colormap information structure.

property Specifies the standard colormap property to set. The predefined standard color-
maps are: XA_RGB_BEST_MAP, XA_RGB_RED_MAP, XA_RGB_GREEN_ MAP,

XA_RGB_BLUE_MAP, XA_RGB_DEFAULT_MAP, and XA_RGB_ GRAY_MAP.

Description

XSetStandardColormap has been superseded by XSetRGBColormap as of Release 4.

XSetStandardColormap defines a standard colormap property. To create a standard color-
map, follow this procedure:

1. Open a new connection to the same server.

2. Grab the server.

3. See if property is on the property list of the root window for the display, using XGet -
StandardColormap. If so, see if the colormap field is nonzero. If it is, the color-
map already exists.

4. If the desired property is not present, do the following:

Determine the color capabilities of the display. Choose a visual.
Create a colormap (not required for XA_RGB_DEFAULT_MAP).

Call XAllocColorPlanes or XAllocColorCells to allocate cells in the
colormap.

Call xstoreColors to store appropriate color values in the colormap.
Fill in the descriptive fields in the structure.

Call XSetStandardColormap to set the property on the root window.
Use XSetCloseDownMode to make the resource permanent.

Close the new connection to the server.

Xlib Reference Manual

XSetStandardColormap

(continued)

Xlib - Colormaps

5. Ungrab the server.

6. Close the new connection to the server.

See description of standard colormaps in Volume One, Chapter 7, Color.

Errors

BadAlloc

BadAtom

BadWindow

Structures

typedef struct {

Colormap colormap;

unsigned long red_max;

unsigned long red_mult;

unsigned long green_max;

unsigned long green_mult,

unsigned long blue_max;

unsigned long blue_mult;

unsigned long base_pixel,
} XStandardColormap;

ID of colormap made by XCreateColormap */

/* new fields in R4 */

Related Commands

Def aultColormap, DisplayCells, XCopyColormapAndFree, XCreate
Colormap, XFreeColormap, XGetStandardColormap, XInstallColormap,
XListlnstalledColormaps.XSetWindowColormap, XUninstallColormap.

470

Xlib Reference Manual

-x,, b -Prop.res / XSetStandardProperties

Name

XSetStandardProperties set the minimum set of properties for the window manager.

Synopsis

XSetStandardProperties ( display, w f window_name, icon_name,

icon_pixmap, argv, argc, hints)
Display * display;
Window w;

char *window_name;
char *icon_name;
Pixmap icon_pixmap;
char **argv;
int argc;
XSizeHints *hints

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenDi splay .

w Specifies the window ID.

window_name Specifies the name of the window.

i con_name Specifies the name to be displayed in the window s icon.

icon_pixmap Specifies the pixmap that is to be used for the icon, or None. This pixmap
must be of depth 1.

argv Specifies a pointer to the command and arguments used to start the applica

tion.

argc Specifies the number of arguments.

hints Specifies a pointer to the size hints for the window in its normal state.

Description

XSetStandardProperties is superceded by XSetWMProperties in Release 4.

XSetStandardProperties sets in a single call the most essential properties for a quickie
application. XSetStandardProperties gives a window manager some information about
your program s preferences; it probably will not be sufficient for complex programs.

See Volume One, Chapter 10, Interclient Communication for a description of standard proper
ties.

Structures

typedef struct {

long flags; /* which fields in structure are defined */

int x, y;

int width, height;

int min_width, min_height;

int max_width, max_height;

int width_inc, height_inc;

Xlib Reference Manual 471

XSetStandardProperties

(continued)

Xlib - Properties

struct {

int x;
int y;

} min_aspect
} XSizeHints;

/* numerator */
/* denominator */
max aspect; /* new fields in R4 */

/* flags argument in size hints */

#define USPosition (1L O)/* user specified x, y */

tdefine USSize (1L I)/* user specified width, height */

tdefine PPosition
#define PSize
#define PMinSize
#define PMaxSize
#define PResizelnc
#define PAspect

(1L 2) /* program specified position */

(1L 3)/* program specified size */

(1L 4)/* program specified minimum size */

(1L 5)/* program specified maximum size */

(1L 6) /* program specified resize increments */

(1L 7)/* program specified min and max aspect ratios */

Errors

BadAlloc
BadWindow

Related Commands

XChangeProperty, XDeleteProperty, XGetAtomName, XGetFontProperty,
XGetWindowProperty, XInternAtom, XListProperties, XRotateWindow-
Properties.

472

Xlib Reference Manual

-X,,b- G raph,cs Context / XSetState

Name

XSetState set the foreground, background, logical function, and plane mask in a graphics
context.

Synopsis

XSetState (display, gc , foreground, background, function,

plane_mask)
Display * display;
GC gc;

unsigned long foreground, background;
int function;
unsigned long plane_mask;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

gc Specifies the graphics context.

foreground Specifies the foreground for the specified graphics context.

background Specifies the background for the specified graphics context.

function Specifies the logical function for the specified graphics context,

pi ane_mask Specifies the plane mask for the specified graphics context.

Description

XSetState sets the foreground and background pixel values, the logical function,
and the plane_mask in a GC. See XSetForeground, XSetBackground, XSet-
Function, and XSetPlaneMask for what these members do and appropriate values.

See Volume One, Chapter 5, The Graphics Context, for more information.
Errors

BadGC
BadValue

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC,
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip-
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground,
XSetFunction, XSetGraphicsExposures, XSetLineAttributes, XSetPlane
Mask, XSetStipple, XSetSubwindowMode, XSetTSOrigin.

Xlib Reference Manual 473

XSetStipple ~\

Xlib- Graphics Context-

Name

XSetStipple set the stipple in a graphics context.

Synopsis

XSetStipple (display, gc , stipple)
Display * display;
GC gc;
Pixmap stipple;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

gc Specifies the graphics context.

stipple Specifies the stipple for the specified graphics context.

Description

XSetStipple sets the stipple component of a GC. The stipple is a pixmap of depth
one. It is laid out like a tile. Set bits in the stipple determine which pixels in an area are drawn
in the foreground pixel value. Unset bits in the stipple determine which pixels are drawn in
the background pixel value if the fill_style is FillOpaqueStippled. If
fill_style is FillStippled, pixels overlayed with unset bits in the stipple are not
drawn. If f ill_style is FillTiled or FillSolid, the stipple is not used.

For more information, see Volume One, Chapter 5, The Graphics Context.
Errors

BadGC

BadMatch

BadPixmap

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC,
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip-
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground,
XSetFunction, XSetGraphicsExposures, XSetLineAttributes, XSetPlane-
Mask, XSetState, XSetSubwindowMode, XSetTSOrigin.

474 Xlib Reference Manual

-x,, b - Graph.cs con,t XSetSubwindowMode

Name

XSetSubwindowMode set the subwindow mode in a graphics context.

Synopsis

XSetSubwindowMode (display, gc , subwindow_mode)
Display * display;
GC gc ;
int subwindow_mode ;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

gc Specifies the graphics context.

subwindow_mode

Specifies the subwindow mode you want to set for the specified graphics con
text. Possible values are ClipByChildren or Includelnf eriors.

Description

XSetSubwindowMode sets the subwindow_mode component of a GC. Clip
ByChildren means that graphics requests will be clipped by all viewable children.
Includelnf eriors means draw through all subwindows.

For more information, see Volume One, Chapter 5, The Graphics Context.
Errors

BadGC
BadValue

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC,
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip-
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground,
XSetFunction, XSetGraphicsExposures, XSetLineAttributes, XSetPlane-
Mask, XSetState, XSetStipple, XSetTSOrigin.

Xlib Reference Manual 475

XSetTeXtPrOperty \ x,,b -Window Managers-

Name

XSetTextProperty set one of a window s text properties.
Synopsis

void XSetTextProperty (display, w, text_prop, property)
Display * display;
Window w;

XTextProperty *text_prop;
Atom property;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the window.

text_prop Specifies the XTextProperty structure to be used.

property Specifies the property name.

Availability

Release 4 and later.

Description

XSetTextProperty sets the specified property for the named window with the data, type,
format, and number of items determined by the value field, the encoding field, the format
field, and the nitems field, respectively, of the specified XTextProperty structure.

Structures

typedef struct {

unsigned char *value; /* same as Property routines */

Atom encoding; /* prop type */

int format; /* prop data format: 8, 16, or 32 */

unsigned long nitems; /* number of data items in value */
} XTextProperty;

Errors

BadAlloc
BadAtom
BadValue
BadWindow

Related Commands

XFreeStringList, XGetTextProperty, XStringListToTextProperty, XText-
PropertytoStringList.

476 Xlib Reference Manual

-Xllb - Plxmaps and Tiles XSetTHe

Name

XSetTile set the fill tile in a graphics context.

Synopsis

XSetTile (display, gc , tile)
Display * display;
GC gc;
Pixmap tile;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

gc Specifies the graphics context.

tile Specifies the desired tile for the specified graphics context.

Description

XSetTile sets the tile member of the GC. This member of the GC determines the pixmap
used to tile areas. The tile must have the same depth as the destination drawable. This tile will
only be used in drawing if the fill-style is Fill riled.

For more information, see Volume One, Chapter 5, The Graphics Context.
Errors

BadGC

BadMatch

BadPixmap

Related Commands

XCreateBitmapFromData, XCreatePixmap, XCreatePixmapFromBitmapData,
XFreePixmap, XQueryBestSize, XQueryBestStipple, XQueryBestTile,
XReadBitmapFile, XSetWindowBackgroundPixmap, XSetWindowBorder-
Pixmap, XWriteBitmapFile.

Xlib Reference Manual 477

XSetTransientForHint V X,ib- Window Manager H,ms-

Name

XSetTransientForHint set the XA_WM_TRANSIENT_FOR property for a window.

Synopsis

XSetTransientForHint ( display, w, prop_window)
Display * display;
Window w;
Window prop_window;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the window ID, normally of a dialog box popup.

prop_window Specifies the window ID that the XA_WM_TRANSIENT_FOR property is to be
set to. This is usually the main window of the application.

Description

XSetTransientForHint sets the XA_WM_TRANSIENT_FOR property of the specified win
dow. This should be done when the window w is a temporary child (for example, a dialog box)
and the main top-level window of its application is prop_window. Some window managers
may use this information to unmap an application s dialog boxes (for example, when the main
application window gets iconified).

For more information, see Volume One, Chapter 10, Inter -client Communication.
Errors

BadAlloc
BadWindow

Related Commands

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal-
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XGetZoom-
Hints, XSetClassHint, XSetCommand, XSetlconName, XSetlconSizes, XSet-
NormalHints, XSetSizeHints, XSetWMHints, XSetZoomHints, XStoreName.

478 Xlib Reference Manual

f XSetTSOrigin

Xlib - Graphics Context

Name

XSetTSOrigin set the tile/stipple origin in a graphics context.

Synopsis

XSetTSOrigin ( display, gc, ts_x_origin f ts_y_origin)
Display * display ;
GC gc;
int ts_x_origin, ts_y_origin;

Arguments

display Specifies a connection to an X server; returned from xopenoisplay.

gc Specifies the graphics context.

ts_x_origin Specify the x and y coordinates of the tile/stipple origin.

ts_y_ origin

Description

XSetTSOrigin sets the ts_x_origin and ts_y_origin components in a GC, which
are measured relative to the origin of the drawable specified in the drawing request that uses the
GC. This controls the placement of the tile or the stipple pattern that patterns an area. To tile
or stipple a child so that the pattern matches the parent, you need to subtract the current posi
tion of the child window from ts_x_ origin and ts_y_origin.

For more information, see Volume One, Chapter 5, The Graphics Context.

Errors

BadGC

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC,
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip-
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground,
XSetFunction, XSetGraphicsExposures, XSetLineAttributes, XSetPlane-
Mask, XSetState, XSetStipple, XSetSubwindowMode.

Xlib Reference Manual 479

XSetWMCIientMachine V xlib . wlndow M ,n ag er nu-

Name

XSetWMCIientMachine set a window s WM_CLIENT_MACHINE property.

Synopsis

void XSetWMCIientMachine (display, w, text_prop)
Display *display;
Window w;
XText Property *text_prop;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the window.

text_jprop Specifies the XText Property structure to be used.

Availability

Release 4 and later.

Description

XSetWMCIientMachine performs an XSetTextProperty to set the
WM_CLIENT_MACHINE property of the specified window. This property should contain the
name of the host machine on which this client is being run, as seen from the server.

For more information, see Volume One, Chapter 10, Interclient Communication.
Structures

typedef struct {

unsigned char *value; /* same as Property routines */

Atom encoding; /* prop type */

int format; /* prop data format: 8, 16, or 32 */

unsigned long nitems; /* number of data items in value */
} XTextProperty;

Related Commands

XGetWMClientMachine.

480 Xlib Reference Manual

Xlib - Window Manager Hints -

XSetWMColormapWindows

Name

XSetWMColormapWindows set a window s WM_COLORMAP_WINDOWS property.

Synopsis

Status XSetWMColormapWindows (display, w, colormap_windows ,

count)

Display * display;
Window w;

Window *colormap_windows ;
int count ;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

w Specifies the window.

col ormap_windows

Specifies the list of windows.

count Specifies the number of windows in the list.

Availability

Release 4 and later.

Description

XSetWMColormapWindows sets the WM_cOLORMAP_wiNDOWS property on the specified win
dow to the list of windows specified by the colormap_windows argument. The property is
stored with a type of WINDOW and a format of 32. If it cannot intern the
WM_COLORMAP_WINDOWS atom, XSetWMColormapWindows returns a zero status. Other
wise, it returns a non-zero status.

This property tells the window manager that subwindows of this application need to have their
own colormaps installed.

For more information, see Volume One, Chapter WJnterclient Communication.

Errors

BadAlloc
BadWindow

Related Commands

XGetWMColormapWindows.

Xlib Reference Manual 48 1

XSetWMIconName V Xllb _ Wlndow Manager Hlnts _

Name

XSetWMIconName set a window s XA_WM_ICON_NAME property.

Synopsis

void XSetWMIconName ( display f w, text_prop)
Display ^display;
Window w;
XTextProperty *text_prop;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the window.

text_j&gt;rop Specifies the XTextProperty structure to be used.

Availability

Release 4 and later.

Description

XSetWMIconName performs an XSetTextProperty to set the XA_WM_ICON_NAME prop
erty of the specified window. XSetWMIconName supersedes XSetlconName.

This is usually called by an application to set the property for the window manager. The name
should be short, since it is to be displayed in association with an icon.

XSetStandardProperties (in Release 4) or XSetWMProperties (in Release 4) also
set this property.

For more information, see Volume One, Chapter WJnterclient Communication.
Structures

typedef struct {

unsigned char *value; /* same as Property routines */

Atom encoding; /* prop type */

int format; /* prop data format: 8, 16, or 32 */

unsigned long nitems; /* number of data items in value */
} XTextProperty;

Related Commands

XGetWMIconName, XGetWMName, XSetWMName, XSetWMProperties.

482 Xlib Reference Manual

-X,, b -Window Manag., H,n, / XSetWMName

Name

XSetWMName set a window s XA_WM_NAME property.

Synopsis

void XSetWMName ( display, w, text_prop)
Display * display;
Window w;
XTextProperty *text_propj

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

w Specifies the window.

text_prop Specifies the XTextProperty structure to be used.

Availability

Release 4 and later.

Description

XSetWMName performs a xsetTextProperty to set the XA_WM_NAME property on the
specified window. XSetWMName supersedes XStoreName. This property can also be set
with XSetWMProperties.

XSetWMName be used by the application to communicate a string to the window manager.
According to current conventions, this string should either:

permit the user to identify one of a number of instances of the same client, or
provide the user with noncritical state information.
Clients can assume that at least the beginning of this string is visible to the user.

The XA_WM_CLASS property, on the other hand, has two members which should be used to iden
tify the application s instance and class name, for the lookup of resources. See XSetClass-
Hint for details.

For more information, see Volume One, Chapter 10, Interclient Communication.

Structures

typedef struct {

unsigned char *value;

Atom encoding;

int format;

unsigned long nitems;
} XTextProperty;

/* same as Property routines */

/* prop type */

/* prop data format: 8, 16, or 32 */

/* number of data items in value */

Related Commands

XGetWMIconName, XGetWMName, XSetWMIconName, XSetWMProperties.

Xlib Reference Manual

483

XSetWMNormalHints V Xllb _ Wlndow Manager Hlnts _

Name

XSetWMNormalHints set a window s XA_WM_NORMAL_HINTS property.

Synopsis

void XSetWMNormalHints (display, w, hints)
Display *display;
Window w;
XSizeHints *hints;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenD i spl ay .

w Specifies the window.

hints Specifies the size hints for the window in its normal state.

Availability

Release 4 and later.

Description

XSetWMNormalHints sets the size hints in the XA_WM_NORMAL_HINTS property on the
specified window. The property is stored with a type of WM_SIZE_HINTS and a format of 32.
XSetWMNormalHints supersedes XSetNormalHints. This property can also be set with
XSetWMProperties.

Applications use XSetNormalHints to inform the window manager of the sizes desirable
for that window.

For more information, see Volume One, Chapter 10, Interdient Communication.
Structures

typedef struct {

long flags; /* marks which fields in this structure */

/* are defined */

int x, y; /* obsolete for new window mgrs, but clients */
int width, height; /* should set so old wm s don t mess up */
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
struct {

int x; /* numerator */

int y; /* denominator */
} min_aspect, max_aspect;

int base_width, base_height; /* added by ICCCM version 1 */
int win_gravity; /* added by ICCCM version 1 */

484 Xlib Reference Manual

Xlib - Window Manager Hints

(continued)

XSetWMNormalHints

} XSizeHints;

#define USPosition (1L 0) A
tdefine USSize (1L 1) A

user specified x, y */

user specified width, height */

tdefine PPosition (1L 2) /* program specified position

tdefine PSize (1L 3) /

tdefine PMinSize (1L 4) /

tdefine PMaxSize (1L 5) /

tdefine PResizelnc (1L 6) /

program specified size V
program specified minimum size */
program specified maximum size */
program specified resize increments

tdefine PAspect (1L 7) /* program specified min/max aspect
ratios */

tdefine PAllHints (PPosition I PSize I PMinSize I PMaxSize I PResizelnc I PAspect)
tdefine PBaseSize (1L 8) /* program specified base

for incrementing */

tdefine PWinGravity (1L 9)/* program specified window

gravity */

Errors

BadAlloc
BadWindow

Related Commands

XGetWMNormalHints, XSetWMProperties, XSetWMSizeHints, XGetWMSize-
Hints.

Xlib Reference Manual

485

XSetWMProperties

Xlib - Window Manager Hints-

Name

XSetWMProperties set a window s standard window manager properties.

Synopsis

void XSetWMProperties ( display, w, window_name , icon_name, argv f

argc , normal_hints , wm_hints, class_hints)
Display *display;
Window w;

XTextProperty *window_name ;
XTextProperty *icon_name;
char **argv;
int argc;

XSizeHints *normal_hints ;
XWMHints *wm_hints;
XClassHint *class_hints ;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the window.

window_name Specifies the window name, which should be a null-terminated string.

i con_name Specifies the icon name, which should be a null-terminated string.

argv Specifies the application s argument list.

argc Specifies the number of arguments .

normal_hints

Specifies the size hints for the window in its normal state.

wm_hints Specifies the XWMHints structure to be used.
class_hints Specifies the XClassHint structure to be used.

Availability

Release 4 and later.

Description

XSetWMProperties provides a single programming interface for setting the essential win
dow properties that communicate with window and session managers. XSetWMProperties
supersedes XSetStandardProperties.

If the window_name argument is non-null, XSetWMProperties calls XSetWMName,
which, in turn, sets the WM_NAME property. If the icon_name argument is non-null, XSet
WMProperties calls xsetWMiconName, which sets the WM_ICON_NAME property. If the
argv argument is non-null, XSetWMProperties calls XSetCommand, which sets the
WM_COMMAND property. Note that an argc of is allowed to indicate a zero-length command.
XSetWMProperties stores the hostname of this machine using XSetWMClientMachine.

486 Xlib Reference Manual

Xlib - Window Manager Hints (continued) XSetWMPropertieS

If the normal_hints argument is non-null, XSetWMProperties calls XSetWMNormal-
Hints, which sets the WM_NORMAL_HINTS property. If the wm_hints argument is non-null,
XSetWMProperties calls XSetWMHints, which sets the WM_HINTS property.

If the class_hints argument is non-null, XSetWMProperties calls XSetClassHint,
which sets the WM_CLASS property. If the res_name member in the XClassHint structure
is set to the null pointer and the RESOURCE_NAME environment variable is set, then value of
the environment variable is substituted for res_name. If the res_name member is NULL,
and if the environment variable is not set, and if argvand argv[0] are set, then the value of
a rgv[ 0], stripped of any directory prefixes, is substituted for res_name.

For more information, see Volume One, Chapter WJnterclient Communication.
Structures

typedef struct {

unsigned char *value; /* same as Property routines */

Atom encoding; /* prop type */

int format; /* prop data format: 8, 16, or 32 */

unsigned long nitems; /* number of data items in value */
} XTextProperty;

typedef struct {

long flags; /* marks which fields in this structure */
/* are defined */

int x, y; /* obsolete for new window mgrs, but clients */

int width, height; /* should set so old wm s don t mess up */

int min_width, min_height;

int max_width, max_height;

int width_inc, height_inc;

struct {

int x; /* numerator */
int y; /* denominator */

} min_aspect, max_aspect;

int base_width, base_height; /* added by ICCCM version 1 */

int win_gravity; /* added by ICCCM version 1 */

} XSizeHints;

typedef struct {

long flags; /* marks which fields in this structure */

/* are defined */
Bool input; /* does this application rely on the window */

/* manager to get keyboard input? */
int initial_state; /* see below */

Pixmap icon_pixmap; /* pixmap to be used as icon */
Window icon_window; /* window to be used as icon */
int icon_x, icon_y; /* initial position of icon */
Pixmap icon_mask; /* icon mask bitmap */

Xlib Reference Manual 487

XSetWMProperties (continued) Xlib - Window Manager Hints

XID window_group; /* id of related window group */
/* this structure may be extended in the future */
} XWMHints;

typedef struct {

char *res_name;

char *res_class;
} XClassHint;

Errors

BadAlloc
BadWindow

Related Commands

XGetClassHints, XGetCommand, XGetWMHints, XGetWMIconName, XGetWMName,
XGetWMNormalHints, XSetWMClientMachine, XSetWMColormapWindows, XSet-
WMProtocols.

488 Xlib Reference Manual

J XSetWMProtocols

Xlib - Window Manager Hints

Name

XSetWMProtocols set a window s WM_PROTOCOLS property.

Synopsis

Status XSetWMProtocols (display, w, protocols, count)
Display ^display;
Window w;
Atom ^protocols;
int count;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenD i sp 1 ay .

w Specifies the window.

protocols Specifies the list of protocols.

count Specifies the number of protocols in the list.

Availability

Release 4 and later.

Description

XSetWMProtocols sets the WM_PROTOCOLS property on the specified window to the list of
atoms specified by the protocols argument. The property is stored with a type of ATOM and a
format of 32. If it cannot intern the WM_PROTOCOLS atom, XSetWMProtocols returns a zero
status. Otherwise, it returns a non-zero status.

The list of standard protocols at present is as follows:

WM_TAKE_FOCUS Assignment of keyboard focus

WM_SAVE_YOURSELF Save client state warning

WM_DELETE_UNKNOWN Request to delete top-level window

For more information, see Volume One, Chapter 10, Interclient Communication.

Errors

BadAlloc
BadWindow

Related Commands

XGetWMProtocols.

Xlib Reference Manual 489

XSetWMSizeHints V Xlib _ window Manager Hints -

Name

XSetWMSizeHints set a window s WM_SIZE_HINTS property.

Synopsis

void XSetWMSizeHints (display, w, hints, property)
Display * display;
Window w;

XSizeHints *hints;
Atom property;

Arguments

display Specifies a connection to an X server; returned from xopenDi splay.

w Specifies the window.

hints Specifies the XSizeHints structure to be used.

property Specifies the property name.

Availability

Release 4 and later.

Description

XSetWMSizeHints sets the size hints for the specified property on the named window. The
property is stored with a type of WM_SIZE_HINTS and a format of 32. To set a window s nor
mal size hints, you can use the XSetWMNormalHints function instead. XSetWMSize
Hints supersedes XSetSizeHints.

This routine is useful if new properties of type XA_WM_SIZE_HINTS are defined.

The flags member of XSizeHints must be set to the OR of the symbols representing each
member to be set

For more information, see Volume One, Chapter WJnterclient Communication.
Structures

typedef struct {

long flags; /* marks which fields in this structure are */

/* defined as */

int x; /* numerator */

int y; /* denominator */
} min_aspect, max_aspect;

int base_width, base_height; /* added by ICCCM version 1 */
int win_gravity; /* added by ICCCM version 1 */

490 xiib Reference Manual

Xlib - Window Manager Hints

(continued)

XSetWMSizeHints

} XSizeHints;

#define USPosition (1L 0)
#define USSize (1L 1)

user specified x, y */

user specified width, height */

#define PPosition (1L 2) /* program specified position

tdefine PSize (1L 3) /* program specified size */

#define PMinSize (1L 4) /* program specified minimum size */

#define PMaxSize (1L 5) /* program specified maximum size */

#define PResizelnc (1L 6) /* program specified resize increments *

#define PAspect (1L 7) /* program specified min/max aspect
ratios */

#def ine PAllHints (PPosition | PSize I PMinSize I PMaxSize | PResizelnc I PAspect)
tdefine PBaseSize (1L 8) /* program specified base

for incrementing */
#define PWinGravity (1L 9)/* program specified window

gravity */

Errors

BadAlloc

BadAtom

BadWindow

Related Commands

XAllocSizeHints, XGetWMNormalHints, XGetWMSizeHints, XSetWMNormal-
Hints.

Xlib Reference Manual

491

XSetWindowBackground \

Xlib - Window Attributes-

Name

XSetWindowBackground set the background pixel value attribute of a window.

Synopsis

XSetWindowBackground ( display, w, background_pixel)
Display * display;
Window w;
unsigned long background_pixel ;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the window ID. Must be an inputOutput window.

background_pixel

Specifies which entry in the colormap is used as the background color. The
constant CopyFromParent is NOT valid.

Description

XSetWindowBackground sets the background attribute of a window, setting the pixel
value to be used to fill the background. This overrides any previous call to XSetWindow
Background or XSetWindowBackgroundPixmap on the same window.

XSetWindowBackground does not change the current window contents immediately. The
background is automatically repainted after Expose events. You can also redraw the back
ground without Expose events by calling XClearWindow immediately after.

For more information, see Volume One, Chapter 4, Window Attributes.

Errors

BadMatch Setting background of Input Only window.

BadWindow

Related Commands

XChangeWindowAttributes, XGet Geometry, XGetWindowAttributes, XSet
WindowBackgroundPixmap, XSetWindowBorder, XSetWindowBorderPixmap.

Xlib Reference Manual

XSetWindowBackgroundPixmap

Xlib - Pixmaps and Tiles

Name

XSetWindowBackgroundPixmap change the background tile attribute of a window.

Synopsis

XSetWindowBackgroundPixmap (display, w, background_tile)
Display *display;
Window w;
Pixmap background_tile;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the window ID. Must be an inputOutput class window.

background_tile

Specifies a pixmap ID, None or ParentRelative, to be used as a back
ground.

Description

XSetWindowBackgroundPixmap sets the background_pixmap attribute of a window.
This overrides any previous background_pixel or background_pixmap attribute set
ting set with XSetWindowBackgroundPixmap, XSetWindowBackground, or
XChangeWindowAttributes. Drawing into the pixmap that was set as the background
pixmap attribute has an undefined effect on the window background. The server may or may
not make a copy of the pixmap.

If the background is set to a pixmap, the background is tiled with the pixmap. If the pixmap is
not explicitly referenced again, it can be freed, since a copy is maintained in the server. The
background of the window will not be redrawn with the new tile until the next Expose event
or XClearWindow call.

If the background is set to None, The window background initially will be invisible and will
share the bits of its parent, but only if the background_pixel attribute is not set. When
anything is drawn by any client into the area enclosed by the window, the contents will remain
until the area is explicitly cleared with XClearWindow. The background is not automatically
refreshed after exposure.

If the background is set to ParentRelative, the parent s background is used, and the origin
for tiling is the parent s origin (or the parent s parent if the parent s background_pixmap
attribute is also ParentRelative, and so on). The difference between setting Parent-
Relative and explicitly setting the same pixmap as the parent is the origin of the tiling. The
difference between ParentRelative and None is that for ParentRelative the back
ground is automatically repainted on exposure.

For ParentRelative, the window must have the same depth as the parent, or a BadMatch
error will occur. If the parent has background None, then the window will also have back
ground None. The parent s background is re-examined each time the window background is

Xlib Reference Manual

XSetWindOwBackgroundPixmap (continued) Xlib - Pixmaps and Tiles

required (when it needs to be redrawn due to mapping or exposure). The window s contents
will be lost when the window is moved relative to its parent, and the contents will have to be
redrawn.

Changing the background_pixmap attribute of the root window to None or Parent-
Relative restores the default.

XSetWindOwBackgroundPixmap can only be performed on an Input Output window.
A BadMatch error will result otherwise.

XSetwindowBackground may be used if a solid color instead of a tile is desired.
For more information, see Volume One, Chapter 4, Window Attributes.

Errors

BadMatch

BadPixmap

BadWindow

Related Commands

XCreateBitmapFromData, XCreatePixmap, XCreatePixmapFromBitmapData,
XFreePixmap, XQueryBestSize, XQueryBestStipple, XQueryBestTile,
XReadBitmapFile, XSetTile, XSetWindowBorderPixmap, XWriteBitmapFile.

494 Xlib Reference Manual

f XSetWindowBorder

Xlib - Window Attributes

Name

XSetWindowBorder change a window border pixel value attribute and repaint the border.

Synopsis

XSetWindowBorder (display, w, border^pixel)
Display * display ;
Window v,
unsigned long border_pixel ;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

w Specifies the window ID. Must be an inputOutput window.

border_pixel

Specifies the colormap entry with which the server will paint the border.

Description

XSetWindowBorder sets the border _jpixel attribute of window w to a pixel value, and
repaints the border. The border is also automatically repainted after Expose events.

Use XSetwindowBorderPixmap to create a tiled border. On top-level windows, the win
dow manager often resets the border, so applications should not depend on their settings.

For more information, see Volume One, Chapter 4, Window Attributes.

Errors

BadMatch Setting border of inputOnly window.

BadWindow

Related Commands

XChangeWindowAttributes, XGetGeometry, XGetWindowAttributes, XSet-
WindowBackground, XSetWindowBackgroundPixmap, XSetwindowBorder
Pixmap.

Xlib Reference Manual 495

XSetWindowBorderPixmap

Xlib - Pixmaps and Tiles-

Name

XSetWindowBorderPixmap change a window border tile attribute and repaint the border.

Synopsis

XSetWindowBorderPixmap (display, w, border_tile)
Display * display ;
Window w;
Pixmap jborder_tile;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

w Specifies the ID of an inputOutput window whose border is to be to a file.

border_tile Specifies any pixmap or None.

Description

XSetWindowBorderPixmap sets the border_pixmap attribute of a window and repaints
the border. The border_tile can be freed immediately after the call if no further explicit
references to it are to be made.

This function can only be performed on an InputOutput window. On top-level windows,
the window manager often resets the border, so applications should not depend on their set
tings.

Errors

BadMatch

BadPixmap

BadWindow

Related Commands

XCreateBitmapFromData, XCreatePixmap, XCreatePixmapFromBitmapData,
XFreePixmap, XQueryBestSize, XQueryBestStipple, XQueryBestTile,
XReadBitmapFile, XSetTile, XSetWindowBackgroundPixmap, XWriteBitmap-

File.

496 xiib Reference Manual

XSetWindowBorderWIdth

Xlib - Window Manipulation-

Name

XSetWindowBorderWidth change the border width of a window.

Synopsis

XSetWindowBorderWidth (display, w, width)
Display *display;
Window w;
unsigned int width;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window whose border is to be changed.

wi dth Specifies the width of the window border.

Description

XSetWindowBorderWidth changes the border width of a window. This request is often
used on top-level windows by the window manager as an indication of the current keyboard
focus window, so other clients should not depend on the border width of top-level windows.

Errors

BadMatch Setting border width of an Input Only window.

BadWindow

Related Commands

Xlib Reference Manual 497

XSetWindowColormap

Xlib - Window Attributes-

Name

XSetWindowColormap set the colormap attribute for a window.

Synopsis

XSetWindowColormap ( display, w r cmap)
Display * display;
Window w;
Colormap cmap;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window for which you want to set the colormap.

cmap Specifies the colormap.

Description

XSetWindowColormap sets the colormap attribute of the specified window. The color-
map need not be installed to be set as an attribute, cmap will be used to translate pixel values
drawn into this window when cmap is installed in the hardware, which will be taken care of by
the window manager.

In Release 3, applications must install their own colormaps if they cannot use the default color-
map. In Release 4, they should never do so.

The colormap must have the same visual as the window.

Errors

BadColormap

BadMatch

BadWindow

Related Commands

XChangeWindowAttributes, XGetGeometry, XGetWindowAttributes, XSet-
WindowBackground, XSetWindowBackgroundPixmap, XSetWindowBorder,
XSetWindowBorderPixmap, XSetWMColormapWindows.

Xlib Reference Manual

-X I ,b-W,ndowMan. g erH,n,, / XSetWMHintS

Name

XSetWMHintS set a window manager hints property.

Synopsis

XSetWMHintS (display, w, wmhints)
Display * display;
Window w;
XWMHints * wmhints;

Arguments

display Specifies a connection to an X server; returned from xopenDi splay.

w Specifies the ID for which window manager hints are to be set.

wmh ints Specifies a pointer to the window manager hints.

Description

XSetWMHintS sets the window manager hints that include icon information and location, the
initial state of the window, and whether the application relies on the window manager to get
keyboard input.

This function is unnecessary in Release 4 if you call XSetWMProperties.

See Volume One, Chapter 10, Interclient Communication, for a description of each XWMHints
structure member.

Structures

typedef struct {

long flags; /* marks defined fields in structure */

Bool input; /* does application need window manager for

* keyboard input */

int initial_state; /* see below */

Pixmap icon_pixmap; /* pixmap to be used as icon */

Window icon_window; /* window to be used as icon */

int icon_x, icon_y; /* initial position of icon */

Pixmap icon_mask; /* icon mask bitmap */

XID window_group; /* ID of related window group */

/* this structure may be extended in the future */
} XWMHints;

/* definitions for the flags field: */
#define InputHint (1L 0)
#define StateHint (1L 1)
#define IconPixmapHint (1L 2)
fdefine IconWindowHint (1L 3)
#define IconPositionHint (1L 4)
tdefine IconMaskHint (1L 5)
#define WindowGroupHint (1L 6)

#define AllHints (InputHint | StateHint | IconPixmapHint | IconWindowHint | \
IconPositionHint I IconMaskHint I WindowGroupHint)

Xlib Reference Manual 499

XSetWMHints

(continued)

Xlib - Window Manager Hints

/* definitions for the initial state flag: */

#define DontCareState

#define NormalState 1

#define ZoomState 2

#define IconicState 3

#define InactiveState 4

/* don t know or care */

/* most applications want to start this way
/* application wants to start zoomed */
/* application wants to start as an icon */
/* application believes it is seldom used;
some wm s may put it on inactive menu */

Errors

BadAlloc
BadWindow

Related Commands

XAllocWMHints, XFetchName, XGetClassHint, XGetlconName, XGetlcon-
Sizes, XGetNormalHints, XGetSizeHints, XGetTransientForHint, XGet-
WMHints, XGetZoomHints, XSetClassHint, XSetCommand. XSetlconName,
XSetlconSizes, XSetNormalHints, XSetSizeHints, XSetTransientForHint,
XSetZoomHints, XStoreName, XSetWMProperties.

500

Xlib Reference Manual

-Mb - Window Manager H,n,s XSetZOOITlHintS

Name

XSetZoomHints set the size hints property of a zoomed window.

Synopsis

XSetZoomHints ( display, w, zhints)
Display * display;
Window w;
XSizeHints * zhints;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window for which zoom hints are to be set.

zhints Specifies a pointer to the zoom hints.

Description

XSetZoomHints is no longer used as of Release 3.

XSetZoomHints sets the XA_WM_ZOOM_HINTS property for an application s top-level win
dow in its zoomed state. Many window managers think of windows in three states: iconified,
normal, or zoomed, corresponding to small, medium, and large. Applications use XSetZoom
Hints to inform the window manager of the size or position desirable for the zoomed window.

In addition, an application wanting to move or resize its zoomed window should call XSet
ZoomHints specifying its new desired location and size, in addition to making direct X calls
to move or resize. This is because some window managers may redirect window configuration
requests, but ignore the resulting events and pay attention to property changes instead.

To set size hints, an application must assign values to the appropriate elements in the hints
structure, and set the flags field of the structure to indicate which members have assigned
values and the source of the assignment. These flags are listed in the Structures section below.

For more information on using hints, see Volume One, Chapter WJnterclient Communication.
Structures

typedef struct {

long flags; /* marks defined fields in structure */

int x, y;

int width, height;

int min_width, min_height;

int max_width, max_height;

int width_inc, height_inc;

struct {

int x; /* numerator */

int y; /* denominator */

} min_aspect, max_aspect;

/* new fields in R4 */
} XSizeHints;

Xlib Reference Manual 501

XSetZoom Hints (continued) Xlib - Window Manager Hints

/* flags argument in size hints */

tdefine USPosition (IL 0) /* user specified x, y */

#define USSize (IL 1) /* user specified width, height */

#define PPosition (IL 2) /* program specified position */

#define PSize (IL 3) /* program specified size */

#define PMinSize (IL 4) /* program specified minimum size */

#define PMaxSize (IL 5) /* program specified maximum size */

#define PResizelnc (IL 6) /* program specified resize increments */

#define PAspect (IL 7) /* program specified min/max aspect ratios */
#define PAH Hints (PPosition | PSize | PMinSize | PMaxSize | PResizelnc | PAspect)

Errors

BadAlloc
BadWindow

Related Commands

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal-
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XGetZoom-
Hints, XSetClassHint, XSetCoinmand, XSetlconName, XSetlconSizes, XSet-
NormalHints, XSetSizeHints, XSetTransientForHint, XSetWMHints,
XStoreName.

Xlib Reference Manual

f XShrinkRegion

Xlib - Regions

Name

XShrinkRegion reduce or expand the size of a region.

Synopsis

XShrinkRegion ( r, dx, dy)
Region r;
int dx, dy;

Arguments

r Specifies the region.

dx Specify the amounts by which you want to shrink or expand the specified

dy region. Positive values shrink the region while negative values expand the

region.

Description

XShrinkRegion changes the width and/or height of the specified region. Positive values
shrink the region; negative values expand the region. It is legal to expand the region in one
dimension at the same time as shrinking it in the other dimension. The offset of the region is
changed to keep the center of the resized region near its original position.

The exact amount of shrinkage for a given value for dx or dy is not specified by Xlib.

Structures

Region is a pointer to an opaque structure type.

Related Commands

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion,
XIntersectRegion, XOf f setRegion, XPointlnRegion, XPolygonRegion,
XRectlnRegion, XSetRegion, XSubtractRegion, XUnionRectWithRegion,
XUnionRegion, XXorRegion.

Xlib Reference Manual 503

XStoreBuffer \ V1

v Xlib - Cut Buffers

Name

XStoreBuffer store data in a cut buffer.

Synopsis

XStoreBuffer ( display, bytes, nbytes , buffer)
Display * display ;
char bytes [ ] ;
int nbytes;
int buffer;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

bytes Specifies the string of bytes you want stored. The byte string is not necessarily

ASCII or null-terminated.

nbytes Specifies the number of bytes in the string.

buffer Specifies the cut buffer in which to store the byte string. Must be in the range
0-7.

Description

XStoreBuffer stores the specified data into any one of the eight cut buffers. All eight buf
fers must be stored into before they can be circulated with XRotateBuf f ers. The cut buf
fers are numbered through 7. Use XFetchBuf f er to recover data from any cut buffer.

Note that selections are the preferred method of transferring data between applications.

For more information on cut buffers, see Volume One, Chapter 13, Other Programming Tech
niques. For more information on selections, see Volume One, Chapter 10, Inter client Commu
nication.

Errors

BadAlloc
BadAtom

Related Commands

XFetchBuf fer, XFetchBytes, XRotateBuf f ers, XStoreBytes.

504 Xlib Reference Manual

f~ XStoreBytes

Xlib - Cut Buffers

Name

XStoreBytes store data in cut buffer 0.

Synopsis

XStoreBytes (display, bytes, nbytes)
Display * display;
char bytes[] ;
int nbytes;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

bytes Specifies the string of bytes to store. The byte string is not necessarily ASCII or

null-terminated.

nbytes Specifies the number of bytes to store.

Description

XStoreBytes stores data in cut buffer 0, usually for reading by another client that already
knows the meaning of the contents. Note that the cut buffer s contents need not be text, so null
bytes are not special.

The cut buffer s contents may be retrieved later by any client calling XFetchBytes.

Use XStoreBuf fer to store data in buffers 1-7. Note that selections are the preferred
method of transferring data between applications.

For more information on cut buffers, see Volume One, Chapter 13, Other Programming Tech
niques. For more information on selections, see Volume One, Chapter 10, Inter client Commu
nication.

Errors

BadAlloc

Related Commands

XFetchBuf f er, XFetchBytes, XRotateBuf f ers, XStoreBuf fer.

Xlib Reference Manual 505

XStoreColor X X|lb _ ^ Ce||s _

Name

XStoreColor set or change the RGB values of a read/write colormap entry to the closest pos
sible hardware color.

Synopsis

XStoreColor ( display, cmap, colorcell_def)
Display *display;
Colormap cmap;
XColor *colorcell_def;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

cmap Specifies the colormap.

col orcell_def Specifies a pixel value and the desired RGB values.

Description

XStoreColor changes the RGB values of a colormap entry specified by
col orcell_def. pixel to the closest values possible on the hardware. This pixel value
must be a read/write cell and a valid index into cmap. XStoreColor changes the red, green,
and/or blue color components in the cell according to the colorcell_def .flags member,
which you set by ORing the constants DoRed, DoGreen, and/or DoBlue.

If the colormap is an installed map for its screen, the changes are visible immediately.
For more information, see Volume One, Chapter 7, Color.

Structures

typedef struct {

unsigned long pixel;

unsigned short red, green, blue;

char flags; /* DoRed, DoGreen, DoBlue */

char pad;
} XColor;

Errors

BadAccess A specified pixel is unallocated or read-only.

BadColormap

BadValue pixel not valid index into cmap.

Related Commands

BlackPixel, WhitePixel, XAllocColor, XAllocColorCells, XAllocColor-
Planes, XAllocNamedColor, XFreeColors, XLookupColor, XParseColor,
XQueryColor, XQueryColors, XStoreColors, XStoreNamedColor.

506 Xlib Reference Manual

Xlib -Color Cells-

J XStoreColors

Name

XStoreColors set or change the RGB values of read/write colorcells to the closest possible
hardware colors.

Synopsis

XStoreColors ( display, cmap , colorcell_defs , ncolors)
Display * display;
Colormap cmap;

XColor colorcell_defs [ncolors] ;
int ncolors;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

cmap Specifies the colormap.

colorcell_defs

Specifies an array of color definition structures.

ncolors Specifies the number of XColor structures in colorcell_defs.

Description

XStoreColors changes the RGB values of each colormap entry specified by color-
cell_defs [] .pixel to the closest possible hardware colors. Each pixel value must be a
read/write cell and a valid index into cmap. XStoreColors changes the red, green, and/or
blue color components in each cell according to the colorcell_def s [ ] .flags member,
which you set by ORing the constants DoRed, DoGreen, and/or DoBlue. The specified pix
els are changed if they are writable by any client, even if one or more pixels generates an error.

If the colormap is an installed map for its screen, the changes are visible immediately. For
more information, see Volume One, Chapter 7, Color.

Structures

typedef struct {

unsigned long pixel;

unsigned short red, green, blue;

char flags; /* DoRed, DoGreen, DoBlue */

char pad;
} XColor;

Errors

BadAcce s s A specified pixel is unallocated or read-only.

BadColormap

BadValue A specified pixel is not a valid entry into cmap.

Related Commands

BlackPixel, WhitePixel, XAllocColor, XAllocColorCells, XAllocColor-
Planes, XAllocNamedColor, XFreeColors, XLookupColor, XParseColor,
XQueryColor, XQueryColors, XStoreColor, XStoreNamedColor.

Xlib Reference Manual 507

XStoreName V Xlib _ Window Manager Hlnts _

Name

XStoreName assign a name to a window for the window manager.

Synopsis

XStoreName ( display , w r window_name)
Display * display;
Window w;
char *window_name ;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window to which you want to assign a name.

window_name Specifies the name of the window. The name should be a null-terminated
string. This name is returned by any subsequent call to XFetchName.

Description

XStoreName is superceded in Release 4 by XSetWMName.

XStoreName sets the XA_WM_NAME property, which should be used by the application to com
municate the following information to the window manager, according to current conventions:

To permit the user to identify one of a number of instances of the same client.
To provide the user with noncritical state information.
Clients can assume that at least the beginning of this string is visible to the user.

The XA_WM_CLASS property, on the other hand, has two members which should be used to iden
tify the application s instance and class name, for the lookup of resources. See XSetClass-
Hint for details.

For more information, see Volume One, Chapter 10, Inter -client Communication.

Errors

BadAlloc
BadWindow

Related Commands

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal-
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XGetZoom-
Hints, XSetClassHint, XSetCommand, XSetlconName, XSetlconSizes, XSet-
NormalHints, XSetSizeHints, XSetTransientForHint, XSetWMHints, XSet-
ZoomHints.

Xlib Reference Manual

-x, ib - wmdow Manager H.ms XStoreNamedColor

Name

XStoreNamedColor set RGB values of a read/write colorcell by color name.

Synopsis

XStoreNamedColor (display, cmap, colorname, pixel, flags)
Display *display,
Co lo rmap cmap ;
char * colorname;
unsigned long pixel;
int flags;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

cmap Specifies the colormap.

colorname Specifies the color name string (for example, "red"). This cannot be in hex for
mat (as used in XParseColor). Upper or lower case is not important. The
string should be in ISO LATIN- 1 encoding, which means that the first 128 char
acter codes are ASCII, and the second 128 character codes are for special char
acters needed in western languages other than English.

pixel Specifies the entry in the colormap to store color in.

flags Specifies which red, green, and blue indexes are set.

Description

XStoreNamedColor looks up the named color in the database, with respect to the screen
associated with cmap, then stores the result in the read/write colorcell of cmap specified by
pixel. Upper or lower case in name does not matter. The flags argument, a bitwise OR of
the constants DoRed, DoGreen, and DoBlue, determines which subfields within the pixel
value in the cell are written.

For more information, see Volume One, Chapter 7, Color.

Errors

BadAccess pixel is unallocated or read-only.

BadColormap

BadName col orname is not in server s color database.

BadValue pixel is not a valid index into cmap.

Related Commands

Def aultColormap, DisplayCells, XCopyColormapAndFree, XCreate-
Colormap, XFreeColormap, XGetStandardColormap, XInstallColormap,
XListInstalledColormaps,XSetStandardColormap, XSetWindowColormap,
XUninstallColormap.

Xlib Reference Manual 509

XStringListToTextProperty \ XMb . wlndowManager Hints _

Name

XStringListToTextProperty set the specified list of strings to an XTextProperty struc
ture.

Synopsis

Status XStringListToTextProperty (list, count, text^prop)
char **list;
int count ;
XTextProperty *text_prop; /* RETURN */

Arguments

list Specifies a list of null-terminated character strings.

count Specifies the number of strings.

text_jDrop Returns the XTextProperty structure.

Availability

Release 4 and later.

Description

XStringListToTextProperty fills the specified XTextProperty structure so that it
represents a property of type STRING (format 8) with a value representing the concatenation of
the specified list of null-separated character strings. An extra byte containing NULL (which is
not included in the nit ems member) is stored at the end of the value field of text_prop.
If insufficient memory is available for the new value string, XStringListToText
Property does not set any fields in the XTextProperty structure and returns a zero status.
Otherwise, it returns a non-zero status. To free the storage for the value field, use XFree.

For more information, see Volume One, Chapter IQJnterclient Communication.
Structures

typedef struct {

unsigned char *value; /* same as Property routines */

Atom encoding; /* prop type */

int format; /* prop data format: 8, 16, or 32 */

unsigned long nitems; /* number of data items in value */
} XTextProperty;

Related Commands

XSetTextProperty, XGetTextProperty, XTextPropertyToStringList,
XFreeStringList.

510 xiib Reference Manual

-* - Keyboard / XStringToKeysym

Name

XStringToKeysym convert a keysym name string to a keysym.

Synopsis

KeySym XStringToKeysym ( string)
char *string;

Arguments

string Specifies the name of the keysym that is to be converted.

Description

XStringToKeysym translates the character string version of a keysym name ("Shift") to the
matching keysym which is a constant (XK_Shift). Valid keysym names are listed in
&lt;Xll/keysymdef.h&gt;. If the specified string does not match a valid keysym, XString
ToKeysym returns NoSymbol.

This string is not the string returned in the buffer argument of XLookupSt r ing, which can
be set with XRebindKeysym. If that string is used, XStringToKeysym will return No-
Symbol except by coincidence.

In Release 4, XStringToKeysym can return keysyms that are not defined by the Xlib stan
dard. Note that the set of keysyms that are available in this manner and the mechanisms by
which Xlib obtains them is implementation dependent. (In the MIT sample implementation,
the resource file lusrlliblXHIXKeysymDB is used starting in Release 4. The keysym name is
used as the resource name, and the resource value is the keysym value in uppercase hexade
cimal.)

For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Related Commands

XChangeKeyboardMapping, XDeleteModif iermapEntry, XFreeModif iermap,
XGetKeyboardMapping, XGetModif ierMapping, XInsertModif iermapEntry,
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym,
XLookupString, XNewModif ierMap, XQueryKeymap, XRebindKeysym,
XRefreshKeyboardMapping, XSetModif ierMapping.

Xlib Reference Manual 51 1

XSublmage \ X(|b _ lmages _

Name

XSublmage create a subimage from part of an image.

Synopsis

Xlmage *XSub Image (ximage, x, y, subimage_width, subimage_height)
Xlmage * ximage;
int x;y;
unsigned int subimage_width ; subimage_height ;

Arguments

ximage Specifies a pointer to the image.

x Specify the x and y coordinates in the existing image where the subimage will be

y extracted.

s ubima ge_wi dt h
subimage_height

Specify the width and height (in pixels) of the new subimage.

Description

XSublmage creates a new image that is a subsection of an existing one. It allocates the mem
ory necessary for the new Xlmage structure and returns a pointer to the new image. The data
is copied from the source image, and the rectangle defined by x, y, subimage_width, and
subimage_height must by contained in the image.

XSublmage extracts a subimage from an image, while XGet Sub Image extracts an image
from a drawable.

For more information on images, see Volume One, Chapter 6, Drawing Graphics and Text.
Related Commands

ImageByteOrder, XAddPixel, XCreatelmage, XDestroy Image, XGetlmage,
XGetPixel, XGet Sub Image, XPut Image, XPutPixel.

512 Xlib Reference Manual

J XSubtractRegion

Xlib - Regions

Name

XSubtractRegion subtract one region from another.

Synopsis

XSubtractRegion (sra, srb, dr)
Region sra, srb;
Region dr; /* RETURN */

Arguments

sra Specify the two regions in which you want to perform the computation.

srb

dr Returns the result of the computation.

Description

XSubtractRegion calculates the difference between the two regions specified (sra - srb)
and puts the result in dr.

This function returns a region which contains all parts of sra that are not also in srb.
For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text.

Structures

Region is a pointer to an opaque structure type.

Related Commands

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion,
XIntersectRegion, XOf f setRegion, XPointlnRegion, XPolygonRegion,
XRectlnRegion, XSetRegion, XShrinkRegion, XUnionRectWithRegion,
XUnionRegion, XXorRegion.

Xlib Reference Manual 513

XSync

Xlib- Output Buffer-

Name

XSync flush the request buffer and wait for all events and errors to be processed by the
server.

Synopsis

XSync (display, discard)
Display * display;
int discard;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

discard Specifies whether XSync discards all events on the input queue. This argu

ment is either True or False.

Description

XSync flushes the request buffer, then waits until all events and errors resulting from previous
calls have been received and processed by the X server. Events are placed on the input queue.
The client s XError routine is called once for each error received.

If discard is True, XSync discards all events on the input queue (including those events that
were on the queue before XSync was called).

XSync is sometimes used with window manipulation functions (by the window manager) to
wait for all resulting exposure events. Very few clients need to use this function.

Related Commands

XFlush.

514 Xlib Reference Manual

J XSynchronize

Xlib - Input Handling

Name

XSynchronize enable or disable synchronization for debugging.

Synopsis

int (*XSynchronize ( display, onoff)) ()
Display * display ;
Bool onoff;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

onoff Specifies whether to enable or disable synchronization. You can pass False

(normal asynchronous mode) or True (enable synchronization for debug
ging).

Description

XSynchronize turns on or off synchronous mode for debugging. If onoff is True, it turns
on synchronous behavior; False resets the state to normal mode.

When events are synchronized, they are reported as they occur instead of at some later time, but
server performance is many times slower. This can be useful for debugging complex event
handling routines. Under UNIX, the same result can be achieved without hardcoding by setting
the global variable _xdebug to True from within a debugger.

XSynchronize returns the previous after function.

For more information, see Volume One, Chapter 3, Basic Window Program.

Related Commands

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped-
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued,
XGetlnputFocus, XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent,
XPeekEvent, XPeeklf Event, XPending, XPutBackEvent, XSelectlnput,
XSendEvent, XSetlnputFocus, XWindowEvent.

Xlib Reference Manual 515

XTextExtents \ Xlib _ Text _

Name

XTextExtents get string and font metrics locally.

Synopsis

XTextExtents (font_struct , string, nchars , direction,

ascent, descent, overall)
XFontStruct *font_struct ;
char *string;
int nchars;

int * direction; /* RETURN */

int * ascent, *descent; /* RETURN */

XCharStruct * overall; /* RETURN */

Arguments

f ont_struct Specifies a connection to an XFontStruct structure.

string Specifies the character string for which metrics are to be returned.

nchars Specifies the number of characters in the character string.

direction Returns the value of the direction element of the XFontStruct. Either
Font Right ToLef t or FontLef tToRight.

ascent Returns the font ascent element of the XFontStruct. This is the overall

maximum ascent for the font

descent Returns the font descent element of the XFontStruct. This is the overall

maximum descent for the font

overall Returns the overall characteristics of the string. These are the sum of the

Description

XTextExtents returns the dimensions in pixels that specify the bounding box of the speci
fied string of characters in the named font, and the maximum ascent and descent for the entire
font This function performs the size computation locally and, thereby, avoids the roundtrip
overhead of XQueryTextExtents, but it requires a filled XFontStruct.

ascent and descent return information about the font, while overall returns information
about the given string. The returned ascent and descent should usually be used to calcu
late the line spacing, while the width, rbearing, and Ibearing members of overall
should be used for horizontal measures. The total height of the bounding rectangle, good for
any string in this font, is ascent + descent.

516 Xlib Reference Manual

Xlib - Text

(continued)

XTextExtents

is the Ibearing of the character in the string with the smallest Ibearing plus the width of
all the characters up to but not including that character. The overall . rbearing is the
rbearing of the character in the string with the largest rbearing plus the width of all the
characters up to but not including that character.

For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and
Text.

Structures

typedef struct {

XExtData *ext_data; /*

Font fid; /*

unsigned direction; /*
unsigned min_char_or_byte2; /*
unsigned max_char_or_byte2; /*

unsigned min bytel; /*

unsigned max_bytel; /*

Bool all_chars_exist; /*

unsigned default char; /*

int n_properties; /*

XFontProp *properties; /*

XCharStruct min bounds; /*

XCharStruct max_bounds; /*

XCharStruct *per_char; /*

int ascent; /*

int descent; /*

} XFontStruct;

hook, for extension to hang data */

font ID for this font */

hint about direction the font is painted */

first character */

last character */

first row that exists */

last row that exists */

flag if all characters have nonzero size*/

char to print for undefined character */

how many properties there are */

pointer to array of additional properties*/

minimum bounds over all existing char*/

first_char to last_char information */

logical extent above baseline for spacing */

logical descent below baseline for spacing */

typedef struct {

short Ibearing;

short rbearing;

short width;

short ascent;

short descent;

unsigned short attributes;
} XCharStruct;

/* origin to left edge of character */

/* origin to right edge of character */

/* advance to next char s origin */

/* baseline to top edge of character */

/* baseline to bottom edge of character

/* per char flags (not predefined) */

Related Commands

XDrawImageString, XDrawImageStringl6,XDrawString, XDrawStringlG,
XDrawText, XDrawTextl6, XQueryTextExtents, XQueryTextExtentsl6,
XTextExtent si 6, XTextWidth, XTextWidthl 6.

Xlib Reference Manual

517

XTextExtentsI 6 \ Xllb _ Text _

Name

XTextExtentsl6 get string and font metrics of a 16-bit character string, locally.

Synopsis

XTextExtentsI 6 (font_struct , string, nchars, direction,

ascent, descent, overall)
XFontStruct *font_struct ;
XChar2b *string;
int nchars;

int * direction; /* RETURN */

int * ascent, * descent; /* RETURN */

XCharStruct * overall; /* RETURN */

Arguments

font_struct Specifies a connection to an XFontStruct structure.

string Specifies the character string made up of XChar2 6 structures.

nchars Specifies the number of characters in the character string.

direction Returns the value of the direction element of the XFontStruct. Font-
RightToLeft of FontLeftToRight.

ascent Returns the font ascent element of the XFontStruct. This is the overall

maximum ascent for the font.

descent Returns the font descent element of the XFontStruct. This is the overall

maximum descent for the font.

overall Returns the overall characteristics of the string. These are the sum of the

Description

XTextExtentsI 6 returns the dimensions in pixels that specify the bounding box of the
specified string of characters in the named font, and the maximum ascent and descent for the
entire font. This function performs the size computation locally and, thereby, avoids the
roundtrip overhead of XQueryTextExtentsl 6, but it requires a filled XFontStruct.

518 xiib Reference Manual

Xlib-Text

(continued)

XTextExtents16

For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and
Text.

Structures

typedef struct {

short Ibearing;

short rbearing;

short width;

short ascent;

short descent;

unsigned short attributes;
} XCharStruct;

typedef struct {

XExtData *ext_data;

Font fid;

unsigned direction;

unsigned min_char_or_byte2;

unsigned max_char_or_byte2;

unsigned min_bytel;

unsigned max_bytel;

Bool all_chars_exist;

unsigned default char;

int n_properties;

XFontProp *properties;

XCharStruct min_bounds;

XCharStruct max_bounds;

XCharStruct *per_char;

int ascent;

int descent;
} XFontStruct;

typedef struct {

unsigned char bytel;
unsigned char byte2;

} XChar2b;

/* origin to left edge of character */

/* origin to right edge of character */

/* advance to next char s origin */

/* baseline to top edge of character */

/* baseline to bottom edge of character

/* per char flags (not predefined) */

/* hook for extension to hang data */

/* font ID for this font */

/* hint about direction the font is painted */

/* first character */

/* last character */

/* first row that exists */

/* last row that exists */

/* flag if all characters have nonzero size*/

/* char to print for undefined character */

/* how many properties there are */

/* pointer to array of additional properties*/

/* minimum bounds over all existing char*/

/* first_char to last_char information */

/* logical extent above baseline for spacing */

/* logical descent below baseline for spacing */

/* normal 16 bit characters are two bytes */

Related Commands

XDrawImageString, XDrawImageStringl6,XDrawString, XDrawStringlS,
XDrawText, XDrawText 1 6, XQueryTextExtent s, XQueryTextExtent si 6,
XTextExtents, XTextWidth, XTextWidthl6.

Xlib Reference Manual

519

XTextPropertyToStringList \ X|ib . Wlndow Manager Hints _

Name

XTextPropertyToStringList obtain a list of strings from a specified XText Property struc
ture.

Synopsis

Status XTextPropertyToStringList (text_prop f list, count)
XTextProperty *text_prop;
char ***list; /* RETURN */
int * count; /* RETURN */

Arguments

text_prop Specifies the XTextProperty structure to be used.

list Returns a list of null-terminated character strings.

count Returns the number of strings.

Availability

Release 4 and later.

Description

XTextPropertyToStringList returns a list of strings representing the null-separated
elements of the specified XTextProperty structure. The data in text_prop must be of
type STRING and format 8. Multiple elements of the property (for example, the strings in a dis
joint text selection) are separated by a NULL (encoding 0). The contents of the property are not
null-terminated. If insufficient memory is available for the list and its elements, XText
PropertyToStringList sets no return values and returns a zero status. Otherwise, it
returns a non-zero status. To free the storage for the list and its contents, use XFreeSt ring-
List.

For more information, see Volume One, Chapter 10, Inter -client Communication.
Structures

typedef struct {

unsigned char *value; /* same as Property routines */

Atom encoding; /* prop type */

int format; /* prop data format: 8, 16, or 32 */

unsigned long nitems; /* number of data items in value */
} XTextProperty;

Related Commands

XFreeStringList. XGetTextProperty, XSetTextProperty, XStringListTo-
TextProperty.

Xlib Reference Manual

f XTextWidth

Xlib - Text

Name

XTextWidth get the width in pixels of an 8-bit character string, locally.

Synopsis

int XTextWidth (font_struct , string, count)
XFontStruct *font_struct;
char *string;
int count;

Arguments

font_struct Specifies the font description structure of the font in which you want to draw
the string.

string Specifies the character string whose width is to be returned.

count Specifies the character count in s t r i n g.

Description

XTextWidth returns the width in pixels of the specified string using the specified font This
is the sum of the XCharSt ruct . width for each character in the string. This is also equiva
lent to the value of overall, width returned by XQueryTextExtents or XText-
Extents. The calculation is done assuming 8-bit font indexing.

For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and
Text.

Structures

typedef struct {

XExtData *ext_data; /* hook for extension to hang data */

Font fid; /* font ID for this font */

unsigned direction; /* hint about direction the font is painted */

unsigned min_char_or_byte2; /* first character */

unsigned max_char_or_byte2; /* last character */

unsigned min_bytel; /* first row that exists */

unsigned max_bytel; /* last row that exists */

Bool all_chars_exist; /* flag if all characters have nonzero size*/

unsigned default_char; /* char to print for undefined character */

int n_properties; /* how many properties there are */

XFontProp ^properties; /* pointer to array of additional properties*/

XCharStruct min_bounds; /* minimum bounds over all existing char*/

XCharStruct max_bounds; /* minimum bounds over all existing char*/

XCharStruct *per_char; /* first_char to last_char information */

int ascent; /* logical extent above baseline for spacing */

int descent; /* logical descent below baseline for spacing */

} XFontStruct;

Related Commands

XDrawImageString, XDrawImageStringl6,XDrawString, XDrawStringlS,
XDrawText, XDrawTextl6, XQueryTextExtents, XQueryTextExtentsl 6,
XTextExtents,XTextExtentsl6,XTextWidthl6.

Xlib Reference Manual 521

XTextWidth16 \ XHb . Text _

Name

XTextWidthl6 get the width in pixels of a 16-bit character string, locally.

Synopsis

int XTextWidthl6 (font_struct , string, count)
XFontStruct *font_struct ;
XChar2b *string;
int count;

Arguments

font_struct Specifies the font description structure of the font in which you want to draw
the string.

string Specifies a character string made up of XChar2b structures,

count Specifies the character count in s t ri n g.

Description

XTextwidthl6 returns the width in pixels of the specified string using the specified font.
This is the sum of the XCharStruct .width for each character in the string. This is also
equivalent to the value of overall . width returned by XQueryTextExtentsl6 or
XTextExtentsl6.

The calculation is done assuming 16-bit font indexing.

For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and
Text.

Structures

typedef struct {

XExtData *ext_data; /* hook for extension to hang data */

Font fid; /* font ID for this font */

unsigned direction; /* hint about direction the font is painted */

unsigned min_char_or_byte2; /* first character */

unsigned max_char_or_byte2; /* last character */

unsigned min_bytel; /* first row that exists */

unsigned max_bytel; /* last row that exists */

Bool all_chars_exist; /* flag if all characters have nonzero size*/

unsigned default_char; /* char to print for undefined character */

int n_properties; /* how many properties there are */

XFontProp *properties; /* pointer to array of additional properties*/

XCharStruct min_bounds; /* minimum bounds over all existing char*/

XCharStruct max_bounds; /* minimum bounds over all existing char*/

XCharStruct *per_char; /* first_char to last_char information */

int ascent; /* logical extent above baseline for spacing */

int descent; /* logical descent below baseline for spacing */

} XFontStruct;

Related Commands

XDrawImageString, XDrawImageStringl6,XDrawString, XDrawStringlS,

XDrawText,XDrawTextl6,XQueryTextExtents,XQueryTextExtentsl6,

XTextExtents,XTextExtentsl6,XTextWidth.

522 xiib Reference Manual

j XTranslateCoordinates

Xlib - Standard Geometry

Name

XTranslateCoordinates change the coordinate system from one window to another.

Synopsis

Bool XTranslateCoordinates (display, src_w, frame_w, src_x f

src_y, new_x, new_y, child)
Display * display;
Window src_w r frame_w;
int src_x f src_y;

int *new_x, *nevr_y; /* RETURN */

Window * chi Id; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from xopenDisplay.

src_w Specifies the ID of the source window.

frame_w Specifies the ID of the frame of reference window.

src_x Specify the x and y coordinates within the source window.

src_y

new_x Return the translated x and y coordinates within the frame of reference window.

new_y

child If the point is contained in a mapped child of the destination window, then that

child ID is returned in child.

Description

XTranslateCoordinates translates coordinates from the frame of reference of one win
dow to another.

XTranslateCoordinates returns False and *new_x and *new_y are set to zero if
src_w and frame_w are on different screens. In addition, if the coordinates are contained in
a mapped child of frame_w, then that child is returned in the child argument When src_w
and frame_y are on the same screen, XTranslateCoordinates returns True, sets
*new_x and *new_y to the location of the point relative to f~rame_w, and sets child to
None.

This should be avoided in most applications since it requires a roundtrip request to the server.
Most applications benefit from the window-based coordinate system anyway and don t need
global coordinates. Window managers often need to perform a coordinate transformation from
the coordinate space of one window to another, or unambiguously determine which subwindow
a coordinate lies in. XTranslateCoordinates fulfills this need, while avoiding any race
conditions by asking the server to perform this operation.

Errors

BadWindow

Related Commands

XGeometry, XParseGeometry.

Xlib Reference Manual 523

XUndefineCursor \ Vl

v Xhb - Cursors-
Name

XUndefineCursor disassociate a cursor from a window.

Synopsis

XUndefineCursor (display, w)
Display * display;
Window w;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenD i spl ay .

w Specifies the ID of the window whose cursor is to be undefined.

Description

XUndefineCursor sets the cursor attribute for a window to its parent s cursor, undoing the
effect of a previous XDef ineCursor for this window. On the root window the default cursor
is restored.

Errors

BadWindow

Related Commands

XCreateFontCursor, XCreateGlyphCursor, XCreatePixmapCursor, XDef ine
Cursor, XFreeCursor, XQueryBestCursor, XQueryBestSize, XRecolor-
Cursor.

Xlib Reference Manual

J XUngrabButton

Xlib - Grabbing

Name

XUngrabButton release a button from a passive grab.

Synopsis

XUngrabButton (display, button, modifiers, w)
Display *display;
unsigned int button;
unsigned int modifiers;
Window w;

Arguments

display Specifies a connection to an X server, returned from XOpenDisplay.

button Specifies the mouse button to be released from grab. Specify Buttonl,

Button2, Buttons, Button4, Buttons, or the constant AnyButton,
which is equivalent to issuing the ungrab request for all possible buttons.

modifiers Specifies a set of keymasks. This is a bitwise OR of one or more of the fol
lowing symbols: ShiftMask, LockMask, ControlMask, ModlMask,
Mod2Mask, ModSMask, Mod4Mask, ModSMask, or AnyModifier.
AnyModif ier is equivalent to issuing the ungrab button request for all pos
sible modifier combinations (including no modifiers).

w Specifies the ID of the window you want to release the button grab.

Description

XUngrabButton cancels the passive grab on a button/key combination on the specified win
dow if it was grabbed by this client. A modifiers of AnyModifier is equivalent to issu
ing the ungrab request for all possible modifier combinations (including the combination of no
modifiers). A button of AnyButton is equivalent to issuing the request for all possible but
tons. This call has no effect on an active grab.

For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Errors

BadWindow

BadValue Invalid button or modifiers mask.

Related Commands

XChangeActivePointerGrab, XGrabButton, XGrabKey, XGrabKeyboard,
XGrabPointer, XGrabServer, XUngrabKey, XUngrabKeyboard, XUngrab-
Pointer, XUngrabServer.

Xlib Reference Manual 525

XUngrabKey \

Xlib- Grabbing

Name

XUngrabKey release a key from a passive grab.

Synopsis

XUngrabKey (display, keycode, modifiers, w)
Display * display;
int keycode;
unsigned int modifiers;
Window w;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

keycode Specifies the keycode. This keycode maps to the specific key you want to

ungrab. Pass either a keycode or AnyKey.

modifiers Specifies a set of keymasks. This is a bitwise OR of one or more of the fol
lowing symbols: ShiftMask, LockMask, ControlMask, ModlMask,
Mod2Mask, ModSMask, Mod4Mask, ModSMask, or AnyModifier.
AnyModif ier is equivalent to issuing the ungrab key request for all pos
sible modifier combinations (including no modifiers).

w Specifies the ID of the window for which you want to ungrab the specified

keys.

Description

XUngrabKey cancels the passive grab on the key combination on the specified window if it
was grabbed by this client. A modifiers of AnyModifier is equivalent to issuing the
request for all possible modifier combinations (including the combination of no modifiers). A
keycode of AnyKey is equivalent to issuing the request for all possible nonmodifier key
codes. This call has no effect on an active grab.

For more information, see Volume One, Chapter 9, The Keyboard and Pointer.

Errors

BadWindow

BadValue Invalid keycode or modifiers mask.

Related Commands

XChangeActivePointerGrab, XGrabButton, XGrabKey, XGrabKeyboard,
XGrabPointer, XGrabServer, XUngrabButton, XUngrabKeyboard, XUngrab-
Pointer, XUngrabServer.

526 xiib Reference Manual

-x,,b-Grabb,n g / XUngrabKeyboard

Name

XUngrabKeyboard release the keyboard from an active grab.

Synopsis

XUngrabKeyboard (display, time)
Display * display;
Time time;

Arguments

display Specifies a connection to an X server; returned from xopenDisplay.

time Specifies the time. Pass either a timestamp, expressed in milliseconds, or the

constant CurrentTime. If this time is earlier than the last-keyboard-grab
time or later than the current server time, the keyboard will not be ungrabbed.

Description

XUngrabKeyboard releases any active grab on the keyboard by this client. It executes as
follows:

Releases the keyboard and any queued events if this client has it actively grabbed from
either XGrabKeyboard or XGrabKey.

Does not release the keyboard and any queued events if time is earlier than the last-key
board-grab time or is later than the current X server time.

Generates Focus In and FocusOut events.

The X server automatically performs an UngrabKeyboard if the grab_window (argument
to XGrabkey and XGrabkeyboard) that becomes unviewable.

For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Related Commands

XChangeActivePointerGrab, XGrabButton, XGrabKey, XGrabKeyboard,
XGrabPointer, XGrabServer, XUngrabButton, XUngrabKey, XUngrabPointer,
XUngrabServer.

Xlib Reference Manual 527

XUngrabPointer V.

-Xlib- Pointer-

Name

XUngrabPointer release the pointer from an active grab.

Synopsis

XUngrabPointer (display, time)
Display *display;
Time time;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

time Specifies the time when the grab should take place. Pass either a timestamp,

expressed in milliseconds, or the constant CurrentTime. If this time is
earlier than the last-pointer-grab time or later than current server time, the
pointer will not be grabbed.

Description

XUngrabPointer releases an active grab on the pointer by the calling client. It executes as
follows:

Releases the pointer and any queued events, if this client has actively grabbed the pointer
from XGrabPo inter, XGrabButton, or from a normal button press.

Does not release the pointer if the specified time is earlier than the last-pointer-grab time
or is later than the current X server time.

Generates EnterNotif y and LeaveNotif y events.

The X server performs an XUngrabPointer automatically if the event_window or
confne_to window (arguments of XGrabButton and XGrabPointer) becomes not
viewable, or if the conf ine_to window is moved, completely outside the root window.

For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Related Commands

XChangeActivePointerGrab, XChangePointerControl, XGetPointer-
Control, XGetPointerMapping, XGrabPointer, XQueryPointer, XSet-
PointerMapping, XWarpPointer.

Xlib Reference Manual

XUngrabServer

Name

XUngrabServer release the server from grab.

Synopsis

XUngrabServer (display)
Display * display;

Arguments

display Specifies a connection to an X server; returned from XOpenDi splay.

Description

XUngrabServer releases the grabbed server, and begins execution of all the requests queued
during the grab. XUngrabServer is called automatically when a client closes its connection.

For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Related Commands

XChangeActivePointerGrab, XGrabButton, XGrabKey, XGrabKeyboard,
XGrabPointer, XGrabServer, XUngrabButton, XUngrabKey, XUngrab-
Keyboard, XUngrabPointer.

Xlib Reference Manual 529

XUninstaliColormap \

Xlib- Colormaps

Name

XUninstaliColormap uninstall a colormap; install default if not already installed.

Synopsis

XUninstaliColormap (display, c/nap)
Display * display;
Colo rmap c/nap ;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenDi spl ay .

c/nap Specifies the colormap to be uninstalled.

Description

If c/nap is an installed map for its screen, it is uninstalled. If the screen s default colormap is
not installed, it is installed.

If c/nap is an installed map, a ColormapNotify event is generated on every window having
this colormap as an attribute. If a colormap is installed as a result of the uninstall, a
ColormapNotify event is generated on every window having that colormap as an attribute.

At any time, there is a subset of the installed colormaps, viewed as an ordered list, called the
required list. The length of the required list is at most the min_maps specified for each screen
in the Display structure. When a colormap is installed with XInstallColormap it is
added to the head of the required list and the last colormap in the list is removed if necessary to
keep the length of the list at min_maps. When a colormap is uninstalled with XUninstali
Colormap and it is in the required list, it is removed from the list. No other actions by the
server or the client change the required list. It is important to realize that on all but high-per
formance workstations, min_maps is likely to be one.

For more information on installing and uninstalling colormaps, see Volume One, Chapter 7,
Color.

Errors

BadColormap

Related Commands

Def aultColormap, DisplayCells, XCopyColormapAndFree, XCreate-
Colormap, XFreeColormap, XGetStandardColormap, XInstallColormap,
XListlnstalledColormaps.XSetStandardColormap, XSetWindowColormap.

Xlib Reference Manual

XUnionRectWithRegion

Name

XUnionRectWithRegion add a rectangle to a region.

Synopsis

XUnionRectWithRegion (rectangle, src_region, dest_region)
XRectangle * rectangle;
Region src_regi on ;
Region dest_region;

Arguments

rect angl e Specifies the rectangle to add to the region.

src_regi on Specifies the source region to be used.

dest_region Specifies the resulting region. May be the same as src_region.

Description

XUnionRectWithRegion computes the destination region from a union of the specified
rectangle and the specified source region. The source and destination regions may be the same.

One common application of this function is to simplify the combining of the rectangles speci
fied in contiguous Expose events into a clip_mask in the GC, thus restricting the redrawn
areas to the exposed rectangles. Use XUnionRectWithRegion to combine the rectangle in
each Expose event into a region, then call XSetRegion. XSetRegion sets the
clip_mask in a GC to the region. In this case, src_region and dest_region would be
the same region.

If src_region and dest_region are not the same region, src_region is copied to
dest_region before the rectangle is added to dest_region.

For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures

typedef struct {

short x, y;

unsigned short width, height;
} XRectangle;

Region is a pointer to an opaque data type.
Related Commands

XClipBox, XDestroyRegion, XEmpty Region, XEqualRegion, Xlntersect-
Region, XOf f setRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion,
XSetRegion, XShrinkRegion, XSubtractRegion, XUnionRegion, XXorRegion.

Xlib Reference Manual 531

XUnionRegion \

Xlib- Regions-

Name

XUnionRegion compute the union of two regions.

Synopsis

XUnionRegion (sra, srb, dr)
Region sra, srb;
Region dr;

Arguments

sra Specify the two regions in which you want to perform the computation,

srb

dr Returns the result of the computation.

Description

XUnionRegion computes the union of two regions and places the result in dr. The resulting
region will contain all the area of both the source regions.

For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text.

Structures

Region is a pointer to an opaque structure type.

Related Commands

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion,
XIntersectRegion, XOf f setRegion, XPointlnRegion, XPolygonRegion,
XRectlnRegion, XSetRegion, XShrinkRegion, XSubtractRegion, XUnion-
RectWithRegion, XXorRegion.

Xlib Reference Manual

XUniqueContext

Xlib - Context Manager

Name

XUniqueContext create a new context ID (not graphics context).

Synopsis

XContext XUniqueContext ( )

Description

The context manager allows association of arbitrary data with a resource ID. This call creates a
unique ID that can be used in subsequent calls to XFindContext, XDeleteContext, and
XSaveContext.

For more information on the context manager, see Volume One, Chapter 13, Other Program
ming Techniques.

Structures

typedef int XContext;

Related Commands

XDeleteContext, XFindContext, XSaveContext.

Xlib Reference Manual 533

XUnloadFont \ Xlib . Fonts _

Name

XUnloadFont unload a font

Synopsis

XUnloadFont ( display, font )
Display * display;
Font font;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

fon t Specifies the ID of the font to be unloaded.

Description

XUnloadFont indicates to the server that this client no longer needs the specified font The
font may be unloaded on the X server if this is the last client that needs the font In any case,
the font should never again be referenced by this client because Xlib destroys the resource ID.

For more information on loading and unloading fonts, see Volume One, Chapter 6, Drawing
Graphics and Text.

Errors

BadFont

Related Commands

534

Xlib Reference Manual

J XUnmapSubwindows

Xlib - Mapping

Name

XUnmapSubwindows unmap all subwindows of a given window.

Synopsis

XUnmapSubwindows (display, w)
Display * display ;
Window w;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window whose subwindows are to be unmapped.

Description

XUnmapSubwindows performs an XUnmapWindow on all mapped children of w, in bottom
to top stacking order. (It does not unmap subwindows of subwindows.)

XUnmapSubwindows also generates an UnmapNotify event on each subwindow and gen
erates exposure events on formerly obscured windows. This is much more efficient than
unmapping many subwindows one at a time, since much of the work need only be performed
once for all of the subwindows rather than for each subwindow.

For more information on window mapping, see Volume One, Chapter 2, X Concepts.
Errors

BadWindow

Related Commands

XMapRaised, XMapSubwindows, XMapWindow, XUnmapWindow.

Xlib Reference Manual 535

XUnmapWindow \

Xlib- Mapping-

Name

XUnmapWindow unmap a window.

Synopsis

XUnmapWindow ( di spl ay, w )
Display * display;
Window w;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the window ID.

Description

XUnmapWindow removes w and all its descendants from the screen (but does not unmap the
descendents). If w is already unmapped, XUnmapWindow has no effect. Otherwise, w is
unmapped and an UnmapNotify event is generated. Normal exposure processing on for
merly obscured windows is performed.

Descendants of w will not be visible until w is mapped again. In other words, the subwindows
are still mapped, but are not visible because w is unmapped. Unmapping a window will gener
ate exposure events on windows that were formerly obscured by w.

For more information on window mapping, see Volume One, Chapter 2, X Concepts.

Errors

BadWindow

Related Commands

XMapRaised, XMapSubwindows, XMapWindow, XUnmapSubwindows.

536

Xlib Reference Manual

XVisuallDFromVisual

Xlib - Window Manager Hints-
Name

XVisuallDFromVisual obtain the visual ID from a visual.

Synopsis

VisuallD XVisuallDFromVisual (visual)
Visual * visual;

Arguments

visual Specifies the visual type.

Description

XVisuallDFromVisual returns the visual ID for the specified visual. This is needed when
filling an xvisuallnf o structure template before calling XGetvisuallnf o.
For more information, see Volume One, Chapter 10, Interclient Communication.

Related Commands

XGetvisuallnf o.

Xlib Reference Manual 537

XWMGeometry V Xllb _ window Manager ,_

Name

XWMGeometry obtain a window s geometry information.

Synopsis

int XWMGeometry (display, screen, user_geom r def_geom r bwidth,

hints, x, y, width, height, gravity)
Display *display;
int screen;
char *user_geom;
char *def_geom;
unsigned int bwidth;
XSizeHints *hints;
int *x, *y; /* RETURN */

int * width, *height ; /* RETURN */
int * gravity; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

screen Specifies the screen.

user_geom Specifies the user-specified geometry or NULL.

def_geom Specifies the application s default geometry or NULL.

bwi dth Specifies the border width.

hints Specifies the size hints for the window in its normal state.

y Return the x and y offsets.

width

height Return the width and height determined.

gra vi ty Returns the window gravity.

Availability

Release 4 and later.

Description

XWMGeometry combines possibly incomplete or nonexistent geometry information (given in
the format used by XParseGeometry) specified by the user and by the calling program with
complete program-supplied default size hints (usually the ones to be stored in
WM_NORMAL_HINTS) and returns the position, size, and gravity (NorthWestGravity,
NorthEastGravity, SouthEastGravity or SouthWestGravity) that describe the
window. If the base size is not set in the XSizeHints structure, the minimum size is used if
set Otherwise, a base size of zero is assumed. If no minimum size is set in the hints structure,
the base size is used. A mask (in the form returned by XParseGeometry) that describes

Xlib Reference Manual

Xlib - Window Manager Hints (continued) X WMGeo m et ry

which values came from the user and whether or not the position coordinates are relative to the
right and bottom edges is returned (which will have already been accounted for in the x and y
values).

Note that invalid user geometry specifications can cause a width or height of zero to be
returned. The caller may pass the address of the win_gravity field of the hints argument
as the gravity argument

For more information, see Volume One, Chapter 10, Inter -client Communication.
Structures

typedef struct {

long flags; /* marks which fields in this structure are

/* defined */

int x; /* numerator */

int y; /* denominator */
} min_aspect, max_aspect;

int base_width, base_height; /* added by ICCCM version 1 */
int win_gravity; /* added by ICCCM version 1 */

} XSizeHints

Related Commands

XChangeWindowAttributes, XParseGeometry, XSetWMProperties.

Xlib Reference Manual

XWarpPointer V Xllb _ Polnler _

Name

XWarpPointer move the pointer to another point on the screen.

Synopsis

XWarpPointer (display, src_w, dest_w, src_x, src_y ,

src_width r src_height , dest_x, dest_y)
Display *display;
Window src_w, dest_w;
int src_x, src_y;

unsigned int src_width, src_height ;
int dest_x, dest_y;

Arguments

di splay Specifies a connection to an X server; returned from XOpenDisplay.

src_w Specifies the ID of the source window. You can also pass None.

dest_w Specifies the ID of the destination window. You can also pass None.

src_x Specify the x and y coordinates within the source window. These are used

src_y with src_width and src_height to determine the rectangle the

pointer must be in order to be moved. They are not the present pointer posi
tion. If src_y is None, these coordinates are relative to the root window
of src_w.

src_width Specify the width and height in pixels of the source area. Used with src_x
src_height and src_y.

dest_x Specify the destination x and y coordinates within the destination window.

dest_y If dest_w is None, these coordinates are relative to the root window of

dest_w.

Description

XWarpPointer moves the pointer suddenly from one point on the screen to another.

If dest_w is a window, XWarpPointer moves the pointer to [dest_x, dest_y] relative to
the destination window s origin. If dest_w is None, XWarpPointer moves the pointer
according to the offsets [dest_x, dest_y] relative to the current position of the pointer.

If src_window is None, the move is independent of the current cursor position (dest_x and
dest_y use global coordinates). If the source window is not None, the move only takes place
if the pointer is currently contained in a visible portion of the rectangle of the source window
(including its inferiors) specified by src_x, src_y, src_width and src_height. If
src_width is zero (0), the pointer must be between src_x and the right edge of the window
to be moved. If src_height is zero (0), the pointer must be between src_y and the bottom
edge of the window to be moved.

XWarpPointer cannot be used to move the pointer outside the conf ine_to window of an
active pointer grab. If this is attempted the pointer will be moved to the point on the border of
the conf ine_to window nearest the requested destination.

540 Xlib Reference Manual

Xlib- Pointer (continued) XWarpPointer

XWarpPointer generates events as if the user had (instantaneously) moved the pointer.

This function should not be used unless absolutely necessary, and then only in tightly con
trolled, predictable situations. It has the potential to confuse the user.

Errors

BadWindow

Related Commands

XChangeActivePointerGrab, XChangePointerControl, XGetPointer-
Control, XGetPointerMapping, XGrabPointer, XQueryPointer, XSet-
PointerMapping, XUngrabPointer.

Xlib Reference Manual 54 /

XWindowEvent A XIib _ lnput Ha nd.ing-

Name

XWindowEvent remove the next event that matches the specified mask and window.

Synopsis

XWindowEvent (display, w, event_mask, rep)
Display * display;
Window w;
long event_mask;
XEvent *rep; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window whose next matching event you want.

event_mask Specifies the event mask. See XSelectlnput for a complete list of event
masks.

rep Returns the event removed from the input queue.

Description

XWindowEvent removes the next event in the queue which matches both the passed window
and the passed mask. The event is copied into an XEvent structure supplied by the caller.
Other events in the queue are not discarded. If no such event has been queued, XWindow
Event flushes the request buffer and waits until one is received.

Structures

See individual event structures described in Volume One, Chapter 8, Events, and Appendix F,
Structure Reference in this volume.

Related Commands

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped-
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEvent sQueued,
XGetInputFocus,XGetMotionEvents,XIf Event, XMaskEvent, XNextEvent,
XPeekEvent, XPeeklf Event, XPending, XPutBackEvent, XSelectlnput,
XSendEvent, XSetlnputFocus, XSynchronize.

XIib Reference Manual

J XWithdrawWindow

Xlib - Window Manager Hints *

Name

XWithdrawWindow request that a top-level window be withdrawn.

Synopsis

Status XWithdrawWindow (display, w, screen_n umber)
Display * display;
Window w;
int screen_n umber;

Arguments

di spl ay Specifies a connection to an X server; returned from xopenDi spl ay .

w Specifies the window.

s creen_n umber

Specifies the appropriate screen number on the server.

Availability

Release 4 and later.

Description

XWithdrawWindow informs the window manager that the specified window and its icon
should be unmapped. It unmaps the specified window and sends a synthetic UnmapNotify
event to the root window of the specified screen. Window managers may elect to receive this
message and may treat it as a request to change the window s state to withdrawn. When a win
dow is in the withdrawn state, neither its normal nor its iconic representation is visible.
XWithdrawWindow returns a nonzero status if the UnmapNotify event is successfully sent;
otherwise, it returns a zero status.

For more information, see Volume One, Chapter 10, Inter client Communication.

Errors

BadWindow

Related Commands

XlconifyWindow, XReconf igureWindow.

Xlib Reference Manual 543

XWriteBitmapFile V Xlib _ Pixmaps and Tlles _

Name

XWriteBitmapFile write a bitmap to a file.

Synopsis

int XWriteBitmapFile (display, filename, bitmap, width,

height, x_hot, y_hot)
Display * display ;
char * filename;
Pixmap bitmap;
unsigned int width, height;
int x_hot r y_hot ;

Arguments

display Specifies a connection to an X server; returned from XQpenDisplay.

filename Specifies the filename to use. The format of the filename is operating system
specific.

bi tmap Specifies the bitmap to be written.

wi dth Specify the width and height in pixels of the bitmap to be written.

height

x_hot Specify where to place the hotspot coordinates (or -1,-1 if none present) in

y_hot the file.

Description

XWriteBitmapFile writes a bitmap to a file. The file is written out in X version 11 bitmap
file format, shown below.

If the file cannot be opened for writing, XWriteBitmapFile returns BitmapOpen-
Failed. If insufficient memory is allocated XWriteBitmapFile returns Bitmap-
NoMemory. Otherwise, on no error, XWriteBitmapFile returns BitmapSuccess.

If x_hot and y_hot are not -1, -1, then XWriteBitmapFile writes them out as the
hotspot coordinates for the bitmap.

The following is an example of the contents of a bitmap file created. The name used ("gray" in
this example) is the portion of filename after the last "/".

#define gray_width 16

tdefine gray_height 16

#define gray_x_hot 8

#define gray_y_hot 8

static char gray_bits[] = {

Oxf8, Oxlf, Oxe3, Oxc7, Oxcf, Oxf3, Ox9f, Oxf9, Oxbf, Oxfd, 0x33, Oxcc,
Ox7f, Oxfe, Ox7f, Oxfe, Ox7e, Ox7e, Ox7f, Oxfe, 0x37, Oxec, Oxbb, Oxdd,
Ox9c, 0x39, Oxcf, Oxf3, Oxe3, Oxc7, Oxf8, Oxlf};

For more information on bitmaps, see Volume One, Chapter 6, Drawing Graphics and Text.

544 xiib Reference Manual

Xlib - Pixmaps and Tiles (continued) X WriteBitmapFile

Errors

BadAlloc

BadDrawable

BadMatch The specified width and height did not match dimensions of the specified
jbi tmap.

Related Commands

XCreateBitmapFromData.XCreatePixmap, XCreatePixmapFromBitmapData,
XFreePixmap,XQueryBestSize,XQueryBestStipple,XQueryBestTile,
XReadBitmapFile, XSetTile, XSetWindowBackgroundPixmap, XSetWindow-
BorderPixmap.

Xlib Reference Manual

XXorRegion ~\

Xlib- Regions-

Name

XXorRegion calculate the difference between the union and intersection of two regions.

Synopsis

XXorRegion ( sra, srb, dr)
Region sra, srb;
Region dr; /* RETURN */

Arguments

sra Specify the two regions on which you want to perform the computation,

srb

dr Returns the result of the computation.

Description

XXorRegion calculates the union minus the intersection of two regions, and places it in dr.
Xor is short for "Exclusive OR", meaning that a pixel is included in dr if it is set in either sra
or srb but not in both.

For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text.

Structures

Region is a pointer to an opaque structure type.

Related Commands

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion,
XIntersectRegion, XOf f setRegion, XPointlnRegion, XPolygonRegion,
XRectlnRegion, XSetRegion, XShrinkRegion, XSubtractRegion, XUnion-
RectWithRegion, XUnionRegion.

546 Xlib Reference Manual

Function Group Summary

This quick reference is intended to help you find and use the right function for a particular
task. It supplies two lists:

Listing of Functions by Groups

Alphabetical Listing of Functions

Both functions and macros are listed in all the groups in which they belong. Therefore, sev
eral of them are listed more than once.

Remember that Xlib functions begin with the letter "X"; macros do not

A.1 Group Listing with Brief Descriptions

Association Tables

XCreateAssocTable

XDeleteAssoc

XDestroyAssocTable

XLookUpAssoc

XMakeAssoc

Create a new association table (X10).

Delete an entry from an association table.

Free the memory allocated for an association table.

Obtain data from an association table.

Create an entry in an association table.

Buffers

XStoreBuffer

XStoreBytes

XFetchBuffer

XFetchBytes

XRotateBuffers

Store data in a cut buffer.
Store data in cut buffer 0.
Return data from a cut buffer.
Return data from cut buffer 0.
Rotate the cut buffers.

Function Group Summary

547

Client Connections

XKillClient
XSetCloseDownMode

Destroy a client or its remaining resources.
Change the close down mode of a client.

Colorcells

XAllocColor

XAllocColorCells
XAllocColorPlanes
XAllocNamedColor
XLookupColor

XParseColor

XQueryColor

XQueryColors

XStoreColor

XStoreColors

XStoreNamedColor
XFreeColors
BlackPixel
WhitePixel

Allocate a read-only colormap cell with closest hardware-sup
ported color.

Allocate read/write (nonshared) colorcells.
Allocate read/write (nonshareable) color planes.
Allocate a read-only colorcell from color name.
Get database RGB values and closest hardware-supported
RGB values from color name.

Look up or translate RGB values from color name or hexade
cimal value.

Obtain the RGB values for a specified pixel value.
Obtain RGB values and flags for each specified pixel value.
Set or change a read/write entry of a colormap to the closest
available hardware color.

Set or change read/write colorcells to the closest available
hardware colors.

Allocate a read/write colorcell by English color name.
Free colormap cells or planes.

Return a black pixel value on the default colormap of screen.
Return a pixel value representing white in default colormap.

Colormaps

XCopyColormapAndFree

XCreateColormap

XFreeColormap

XGetStandardColormap

XSetStandardColormap

XSetWindowColormap

XInstallColormap

XUninstallColormap

XListlnstalledColormaps

Default Colormap

DefaultColormapOf Screen

DisplayCells

Copy a colormap and return a new colormap ID.
Create a colormap.

Delete a colormap and install the default colormap.
Get the standard colormap property.
Change the standard colormap property.
Set the colormap for a specified window.
Install a colormap.

Uninstall a colormap; install default if not already installed.
Get a list of installed colormaps.
Return the default colormap on the default screen.
Return the default colormap on the specified screen.
Return the maximum number of colormap cells on the con
nected display.

Context Manager

XDeleteContext
XFindContext

Delete a context entry for a given window and type.
Get data from the context manager (not graphics context).

545

Xlib Reference Manual

Context Manager (continued)

XSaveContext
XUniqueContext

Save a data value corresponding to a window and context type

(not graphics context).

Create a new context ID (not graphics context).

Cursors

XDefineCursor

XUndefineCursor

XCreateFontCursor

XCreateGlyphCursor

XCreatePixmapCursor

XFreeCursor

XRecolorCursor

XQueryBest Cursor

XQueryBestSize

Assign a cursor to a window.

Disassociate a cursor from a window.

Create a cursor from the standard cursor font

Create a cursor from font glyphs.

Create a cursor from two bitmaps.

Destroy a cursor.

Change the color of a cursor.

Get the closest supported cursor sizes.

Obtain the "best" supported cursor, tile, or stipple size.

Display Specifications

DefaultColormap

DefaultDepth

DefaultGC

Default Screen

DefaultVisual
DisplayCells

DisplayHeight

DisplayHeightMM

DisplayPlanes

DisplayString

DisplayWidth

DisplayWidthMM

RootWindow

ScreenCount

XDisplayMotionBufferSize

XListDepths

XListPixmapFormats

XMaxRequestSize

XResourceManager String

Return the default colormap on the specified screen.
Return the depth of the default root window for a screen.
Return the default graphics context for the root window of a
screen.

Return the screen integer; the last segment of a string passed to
XOpenDisplay, or the DISPLAY environment variable if
NULL was used.

Return the default visual structure for a screen.
Return the maximum number of colormap cells on the con
nected display.

Return an integer that describes the height of the screen in pix
els.

Return the height of the specified screen in millimeters.
Return the number of planes on the connected display.
Return the string that was passed to XOpenDisplay or if
that was NULL, the DISPLAY variable.
Return the width of the screen in pixels.
Return the width of the specified screen in millimeters.
Return the ID of the root window.
Return the number of available screens.
Return size of server s motion history buffer.
Return a list of the depths supported on this server.
Return a list of the pixmap formats supported on this server.
Return maximum request size allowed on this server.
Return string containing user s resource database.

Function Group Summary

549

Drawing Primitives

XDraw

XDrawArc

XDrawArcs

XDrawFilled

XDrawLine

XDrawLines

XDrawPoint

XDrawPoints

XDrawRect angle

XDrawRect angles

XDrawSegments

XCopyArea

XCopyPlane

XFillArc

XFillArcs

XFillPolygon

XFillRectangle

XFillRect angles

XClearArea

XClearWindow

Draw a polyline or curve between vertex list (from X10).

Draw an arc fitting inside a rectangle.

Draw multiple arcs.

Draw a filled polygon or curve from vertex list (from X10).

Draw a line between two points.

Draw multiple connected lines.

Draw a point.

Draw multiple points.

Draw an outline of a rectangle.

Draw the outlines of multiple rectangles.

Draw multiple disjoint lines.

Copy an area of a drawable.

Copy a single plane of a drawable into a drawable with depth,

applying pixel values.

Fill an arc.

Fill multiple arcs.

Fill a polygon.

Fill a rectangular area.

Fill multiple rectangular areas.

Clear a rectangular area in a window.

Clear an entire window.

Errors

XGetErrorDatabaseText

XGetErrorText

XSetErrorHandler

XSetlOErrorHandler

XDisplayName

XSetAfterFunction

XSynchronize

Obtain error messages from the error database.

Obtain a description of error code.

Set a nonfatal error event handler.

Handle fatal I/O errors.

Report the display name when connection to a display fails.

Set a function called after all Xlib functions.

Enable or disable synchronization for debugging.

Events

XSelectlnput

XSendEvent

XSetlnputFocus

XGetlnputFocus

XWindowEvent

XCheckWindowEvent

XCheckTypedEvent

XCheckTypedWindowEvent

XMaskEvent

XCheckMaskEvent

Select the event types to be sent to a window.
Send an event

Set the keyboard focus window.
Return the current keyboard focus window.
Remove the next event matching mask and window.
Remove the next event matching both passed window and pas
sed mask; don t wait.

Return the next event in queue that matches event type; don t
wait.

Return the next event in queue matching type and window.
Remove the next event that matches mask.
Remove the next event that matches mask; don t wait.

550

Xlib Reference Manual

Events (continued)

XI f Event

XChecklfEvent

XPeekEvent

XPeeklfEvent

XAllowEvents

XGetMotionEvents

XNextEvent

XPutBackEvent

XEventsQueued

XPending

XSynchronize
QLength

Wait for matching event

Check the event queue for a matching event

Get an event without removing it from the queue.

Get an event without recovering it from the queue; don t wait

Control the behavior of keyboard and pointer events when

these resources are grabbed.

Get pointer motion events.

Get the next event of any type or window.

Push an event back on the input queue.

Check the number of events in the event queue.

Rush the request buffer and return the number of pending

input events.

Enable or disable synchronization for debugging.

Return the current length of the input queue on the connected

display.

Extensions

XFreeExtensionList
XList Ext ens ions
XQueryExtension

Free memory allocated for a list of installed extensions to X.
Return a list of all extensions to X supported by the server.
Get extension information.

Fonts

XLoadFont

XUnloadFont

XFreeFont

XFreeFontlnfo

XFreeFontNames

XFreeFontPath

XListFonts

XListFontsWithlnfo

XQueryFont

XSetFont

XSetFontPath

XGetFontPath

XGetFont Property

XCreateFont Cursor

Load a font if not already loaded; get font ID.

Unload a font

Unload a font and free storage for the font structure.

Free multiple font information arrays.

Free the font name array.

Free the memory allocated by XGetFontPath.

Return a list of the available font names.

Obtain the names and information about loaded fonts.

Return information about a loaded font.

Set the current font in a graphics context.

Set the font search path.

Get the current font search path.

Get a font property given its atom.

Create a cursor from the standard cursor font

Grabbing

XGrabKey

XUngrabKey

XGrabKeyboard

XUngrabKeyboard

XGrabButton

Grab a key.

Release a key from grab.

Grab the keyboard.

Release the keyboard from grab.

Grab a pointer button.

Function Group Summary

551

Grabbing (continued)

XUngrabButton

XGrabPointer

XUngrabPointer

XGrabServer

XUngrabServer

XChangeActivePointerGrab

Release a button from grab.

Grab the pointer.

Release the pointer from grab.

Grab the server grab.

Release the server from grab.

Change the parameters of an active pointer grab.

Graphics Context

XCreateGC

XChangeGC
XCopyGC
XFreeGC
XGContextFromGC

XGetGCValues

XSetArcMode

XSetClipMask

XSetClipOrigin

XSetClipRectangles

XSetRegion

XSetDashes

XSet Line Attributes

XSetFillRule

XSetFillStyle

XSetTile

XSetStipple

XSetTSOrigin

XSetGraphicsExposures

XSetForeground

XSet Background

XSetFunction

XSetPlaneMask

XSetState

XSetSubwindowMode
DefaultGC

Create a new graphics context for a given screen with the

depth of the specified drawable.

Change the components of a given graphics context.

Copy a graphics context.

Free a graphics context.

Obtain the GContext (resource ID) associated with the

specified graphics context.

Get GC component values from Xlib s GC cache.

Set the arc mode in a graphics context.

Set clip_mask pixmap in a graphics context.

Set the clip origin in a graphics context.

Set clip_mask in a graphics context to the list of rectangles.

Set clip_mask of the graphics context to the specified

region.

Set dash_of f set and dashes (for lines) in a graphics

context.

Set the line drawing components in a graphics context.

Set the fill rule in a graphics context.

Set the fill style in a graphics context.

Set the fill tile in a graphics context.

Set the stipple in a graphics context.

Set the tile/stipple origin in a graphics context.

Set graphics_exposures in a graphics context.

Set the foreground pixel value in a graphics context.

Set the background pixel value in a graphics context.

Set the bitwise logical operation in a graphics context.

Set the plane mask in a graphics context.

Set the foreground, background, logical function and plane

mask in a graphics context.

Set the subwindow mode in a graphics context.

Return the default graphics context for the root window of a

screen.

552

Xlib Reference Manual

Host Access

XAddHost

XAddHosts

XListHosts

XRemoveHost

XRemoveHosts

XDisableAccessControl

XEnableAccessControl

XSetAccessControl

Add a host to the access control list.

Add multiple hosts to the access control list.

Obtain a list of hosts having access to this display.

Remove a host from the access control list.

Remove multiple hosts from the access control list.

Allow access from any host

Use access control list to allow or deny connection requests.

Disable or enable access control.

HouseKeeping

XFree

XOpenDisplay
XCloseDisplay
XNoOp

Free specified in-memory data created by an Xlib function.
Connect a client program to an X server.
Disconnect a client program from an X server and display.
Send a NoOp to exercise connection with the server.

Images

XCreate Image
XDes troy Image
XPutlmage
XSublmage
XGet Image
XGetSublmage

XAddPixel
XPutPixel
XGetPixel
ImageByteOrder

Allocate memory for an Xlmage structure.
Deallocate memory associated with an image.
Draw a rectangular image on a window or pixmap.
Create a subimage from part of an image.
Place contents of a rectangle from drawable into an image.
Copy a rectangle in drawable to a location within the pre
existing image.

Add a constant value to every pixel value in an image.
Set a pixel value in an image.
Obtain a single pixel value from an image.
Specify the required byte order for images for each scan line
unit in XYFormat (bitmap) or for each pixel value in ZFor-
mat. Returns either LSBFirst orMSBFirst.

Interclient Communication

(see Window Manager Hints, Selections, and Cut Buffers)

Keyboard

XKeycodeToKeysym

XKeysymToKeycode

XKeysymToString

XStringToKeysym

XLookupKeysym

XRebindKeysym

Convert a keycode to a keysym.

Convert a keysym to the appropriate keycode.

Convert a keysym symbol to a string.

Convert a keysym name string to a keysym.

Get the keysym corresponding to a keycode in a structure.

Rebind a keysym to a string for client.

Function Group Summary

553

Keyboard (continued)

XLookupString

XQueryKeymap

XGetKeyboardMapping

XChangeKeyboardMapping

XRefreshKeyboardMapping

XSe-tModifierMapping

XGetModifierMapping

XDeleteModifiermapEntry

XInsertModifiermapEntry

XNewModifiermap

XFreeModifiermap

XDisplayKeycodes

Macros, Display

Map a key event to ASCII string, keysym, and Compose-

Status.

Obtain a bit vector for the current state of the keyboard.

Return symbols for keycodes.

Change the keyboard mapping.

Update the stored modifier and keymap information.

Set keycodes to be used as modifiers (Shift, Control, etc.).

Obtain modifier key mapping (Shift, Control, etc.).

Delete an entry from an XModif ierKeymap structure.

Add a new entry to an XModif ierKeymap structure.

Create a keyboard modifier mapping structure.

Destroy and free a keyboard modifier mapping structure.

Returns range of keycodes used by server.

AllPlanes
BlackPixel
BlackPixelOf Screen

CellsOfScreen
Connect ionNumber

DefaultColormap
DefaultColormapOf Screen
DefaultDepth
DefaultDepthOf Screen
DefaultGC

DefaultGCOf Screen

DefaultRootWindow
DefaultScreen

DefaultScreenOf Display
DefaultVisual
DefaultVisualOf Screen
DisplayCells

DisplayHeight

DisplayHeightMM
DisplayOf Screen
Display? lanes

Return an unsigned long value with all bits set
Return a black pixel value on the default colormap of screen.
Return the black pixel value in the default colormap of the
specified screen.

Return the number of colormap cells of the specified screen.
Return the connection number (file descriptor on UNIX sys
tem).

Return the default colormap on the specified screen.
Return the default colormap of the specified screen.
Return the depth of the default root window for a screen.
Return the default depth of the specified screen.
Return the default graphics context for the root window of a
screen.

Return the default graphics context (GC) of the specified
screen.

Return the root window for the default screen.
Return the screen integer; the last segment of a string passed to
XOpenDi splay, or the DISPLAY environment variable if
NULL was used.

Return the default screen of the specified display.
Return the default visual structure for a screen.
Return the default visual of the specified screen.
Return the maximum number of colormap cells on the con
nected display.

Return an integer that describes the height of the screen in pix
els.

Return the height of the specified screen in millimeters.
Return the display of the specified screen.
Return the number of planes on the connected display.

554

Xlib Reference Manual

Macros, Display (continued)

DisplayString
DisplayType

DisplayWidth

DisplayWidthMM

DoesBackingStore

DoesSaveUnders

dpyno

EventMaskOf Screen
HeightOfScreen
HeightMMOfScreen
Keyboard

LastKnownRequest-

Processed
MaxCmapsOf Screen

MinCmapsOf Screen

NextRequest
PlanesOf Screen
ProtocolRevision
ProtocolVersion

QLength

RootWindow
RootWindowOf Screen
ScreenCount
XScreenNumberOf Screen

ScreenOf Display
ServerVendor

Vendor Re lease

WhitePixel
WhitePixelOf Screen

WidthOfScreen

WidthMMOfScreen

XDisplayMotionBufferSize

Return the string that was passed to XOpenDisplay or if
that was NULL, the DISPLAY variable.
Return the connected display manufacturer, as defined in
&lt;XlllXvendors.h&gt;.

Return the width of the screen in pixels.
Return the width of the specified screen in millimeters.
Return a value indicating whether the screen supports backing
stores. Return one of WhenMapped, NotUseful, or
Always.

Return whether the screen supports save unders. True or
False.

Return the file descriptor of the connected display.
Return the initial root event mask for the specified screen.
Return the height of the specified screen.
Return the height of the specified screen in millimeters.
Return the device ID for the main keyboard connected to the
display.

Return the serial ID of the last known protocol request to have
been issued.

Return the maximum number of colormaps supported by a
screen.

Return the minimum number of colormaps supported by a
screen.

Return the serial ID of the next protocol request to be issued.
Return the number of planes in a screen.
Return the minor protocol revision number of the X server.
Return the version number of the X protocol on the connected
display.

Return the current length of the input queue on the connected
display.

Return the ID of the root window.
Return the root window of the specified screen.
Return the number of available screens.
Return the integer corresponding to the specified pointer to a
Screen structure.

Return the specified screen of the specified display.
Return a pointer to a null-terminated string giving some identi
fication of the maker of the X server implementation.
Return a number related to the release of the X server by the
vendor.

Return a pixel value representing white in default colormap.
Return the white pixel value in the default colormap of the
specified screen.

Return the width of the specified screen.
Return the width of the specified screen in millimeters.
Return size of server s motion history buffer.

Function Group Summary

555

Macros, Display (continued)

XListDepths Return a list of the depths supported on this server.

XListPixmapFormats Return a list of the pixmap formats supported on this server.

XMaxRequestsize Return maximum request size allowed on this server.

XResourceManagerString Return string containing user s resource database.

Macros, Image Format

BitmapBitOrder Return LeastSignif leant or MostSignif leant.

Indicates the bit order in BitmapUnit.

BitmapPad Each scan line is padded to a multiple of bits specified by the

value returned by this macro.

BitmapUnit The scan line is quantized (calculated) in multiples of this

value.

ByteOrder Specifies the required byte order for images for each scan line

unit in XYFormat (bitmap) or for each pixel value in ZFor-
mat. Possible values are LSBFirst orMSBFirst.

i mage ByteOrder Specifies the required byte order for images for each scan line

unit in XYFormat (bitmap) or for each pixel value in z For
mat. Return either LSBFirst orMSBFirst.

Macros, Keysym Classification

isCursorKey Return True if the keysym is on the cursor key.

isFunctionKey Return True if the keysym is on the function keys.

I sKeypadKey Return T rue if the keysym is on the key pad.

isMiscFunct ionKey Return True if the keysym is on the miscellaneous function keys.

isModif ierKey Return True if the keysym is on the modifier keys.

I sPFKey Return T rue if the keysym is on the PF keys.

Mapping

(see Window Mapping, Keyboard, or Pointer)
Output Buffer

&lt;Flush Rush the request buffer.

xs ync Flush the request buffer and wait for all events to be processed

by the server.

Pointers

XQueryPointer Get the current pointer location.

xwarpPointer Move the pointer to another point on the screen.

XGrabPointer Grab the pointer.

xungrabPointer Release the pointer from grab.

556

Xlib Reference Manual

Pointers (continued)

XGetPointerMapping

XSetPointerMapping

XGetPointerControl

XChangePointerControl

XChangeActivePointerGrab

Get the pointer button mapping.

Set the pointer button mapping.

Get the current pointer preferences.

Change the pointer preferences.

Change the parameters of an active pointer grab.

Properties

XListProperties

XDeleteProperty

XChangeProperty

XSetStandardProperties

XRot a teWindowP roper ties

XGetAtomName

XGet Font Property

XGetWindowProperty

XInternAtom

XGetTextProperty

XSet Text Property

XStringListToText Property

XTextPropertyToStringList

XFreeStringList

Get the property list for a window.

Delete a window property.

Change a property associated with a window.

Set the minimum set of properties for the window manager.

Rotate properties in the properties array.

Get a name for a given atom.

Get a font property given its atom.

Obtain the atom type and property format for a window.

Return an atom for a given name string.

Read a TEXT property.

Write a TEXT property.

Convert a list of strings to an XTextProperty structure.

Convert an XTextProperty to a list of strings.

Free memory allocated by XTextPropertyToStringList.

Regions

XCreateRegion

XDestroyRegion

XEmptyRegion

XPolygonRegion

XPointlnRegion

XRectlnRegion

XUnionRectWithRegion

XClipBox

XOf fsetRegion

XShrinkRegion

XEqualRegion

XSetRegion

XSubtract Region
XInter sect Region
XUnionRegion
XXorRegion

Create a new empty region.

Deallocate storage associated with a region.

Determine if a region is empty.

Generate a region from points.

Determine if a point resides in a region.

Determine if a rectangle resides in a region.

Add a rectangle to a region.

Generate the smallest rectangle enclosing a region.

Change offset of a region.

Reduce the size of a region.

Determine if two regions have the same size, offset, and space.

Set clip_mask of the graphics context to the specified

region.

Subtract one region from another.

Compute the intersection of two regions.

Compute the union of two regions.

Calculate the difference between the union and intersection of

2 regions.

Function Group Summary

557

Resource Manager

XrmDestroyDat abase

XrmGetFileDatabase

XrmGetResource

XrmGetStringDat abase

Xrmlnitialize

XrmMergeDat abases

XrmParseCommand

XrmPutFileDat abase

XrmPutLineResource

XrmPutResource

XrmPutStringResource

XrmQGetResource

XrmQGetSearchList

XrmQGetSearchResource

XrmQPut Resource

XrmQPutStringResource

XrmQuarkToString

XrmStringToBinding-

QuarkList

XrmStringToQuarkList
XrmStringToQuark
XrmUniqueQuark
Xpermalloc
XResourceManager String

Destroy a resource database.

Retrieve a database from a file.

Get a resource from name and class as strings.

Create a database from a string.

Initialize the resource manager.

Merge the contents of one database with another.

Load a resource database from command line arguments.

Store a database in a file.

Add a resource entry given as a string of name and value.

Store a resource into a database.

Add a resource that is specified as a string.

Get a resource from name and class as quarks.

Return a list of database levels.

Search resource database levels for a given resource.

Store a resource into a database using quarks.

Add a string resource value to a database using quarks.

Convert a quark to a string.

Convert a key string to a binding list and a quark list.

Convert a key string to a quark list.

Convert a string to a quark.

Allocate a new quark.

Allocate memory never to be freed.

Get user s database set with xrdb from Display structure.

Save Set

XAddToSaveSet

XRemoveFromSaveSet

XChangeSaveSet

Add a window to the client s save-set.

Remove a window from the client s save-set.

Add or remove a window to or from the client s save-set.

Screen Saver

XActivate Screen Saver

XForceScreenSaver

XResetScreenSaver

XGetScreenSaver

XSetScreenSaver

Activate screen blanking.

Turn the screen saver on or off.

Reset the screen saver.

Get the current screen saver parameters.

Set the parameters of the screen saver.

Selections

XGet Select ionOwner
XSetSelectionOwner
XConvert Select ion

Return the owner of a selection.
Set the owner of a selection.
Use the value of a selection.

555

Xlib Reference Manual

Server Specifications

(see Display Specifications)

Standard Geometry

XGeometry
XWMGeometry
XParseGeometry
XTranslateCoordinates

Calculate window geometry given user geometry string and

default geometry. Superceded in R4 by XWMGeometry.

Calculate window geometry given user geometry string and

default geometry.

Generate position and size from standard window geometry

string.

Change the coordinate system from one window to another.

Text

XDrawImageString
XDrawImageStr ingl 6
XDrawString
XDrawStringlG
XDrawText
XDrawTextl6
XQueryText Extents
XQueryTextExtentsl6

XTextExtents
XTextExtentslG
XTextWidth
XTextWidthlG

Draw 8-bit image text characters.
Draw 16-bit image text characters.
Draw an 8-bit text string, foreground only.
Draw two-byte text strings.
Draw 8-bit polytext strings.
Draw 16-bit polytext strings.
Query the server for string and font metrics.
Query the server for string and font metrics of a 16-bit charac
ter string.

Get string and font metrics.

Get string and font metrics of a 16-bit character string.
Get the width in pixels of an 8-bit character string.
Get the width in pixels of a 16-bit character string.

Tile, Pixmap, Stipple and Bitmap

XCreatePixmap

XFreePixmap

XQueryBestSize

XQueryBest Stipple

XQueryBestTile

XSetTile

XSetWindowBorderP ixmap

XSetWindowBackgroundPixmap

XReadBitmapFile

XWriteBitmapFile

XCreateBitmapFromData

XCreatePixmapFromBitmapData

XListPixmapFormats

Create a pixmap.

Free a pixmap ID.

Obtain the "best" supported cursor, tile, or stipple size.

Obtain the best supported stipple shape.

Obtain the best supported fill tile shape.

Set the fill tile in a graphics context.

Change a window border tile attribute and repaint the border.

Change the background tile attribute of a window.

Read a bitmap from disk.

Write a bitmap to a file.

Create a bitmap from XI 1 bitmap format data.

Create a pixmap with depth from bitmap data.

Read supported pixmap formats from Display structure.

Function Group Summary

559

User Preferences

XAutoRepeatOff

XAutoRepeatOn

XBell

XGetDefault

XGetPointer Control

XGetKeyboardControl

XChangeKeyboardControl

Turn off the keyboard auto-repeat keys.

Turn on the keyboard auto-repeat keys.

Ring the bell (Control G).

Scan the user preferences for program name and options.

Get the current pointer preferences.

Obtain a list of the current keyboard preferences.

Change the keyboard preferences.

Visuals

XGetVisuallnfo
XMatchVisuallnfo

DefaultVisual
XVisuallDFromVisual

Find a visual information structure that matches the specified

template.

Obtain the visual information that matches the desired depth

and class.

Return the default visual structure for a screen.

Get resource ID from a visual structure.

Window Attributes

XGetWindowAt tributes
XChangeWindowAttributes
XSetWindowBackground
XSetWindowBackgroundP ixmap
XSetWindowBorder

XSetWindowBorderP ixmap

XSetWindowColormap

XDefineCursor

XGet Geometry

XSelectlnput

Obtain the current attributes of window.

Set window attributes.

Set the background pixel attribute of a window.

Change the background tile attribute of a window.

Change a window border attribute to the specified pixel value

and repaint the border.

Change a window border tile attribute and repaint the border.

Set the colormap for a specified window.

Assign a cursor to a window.

Obtain the current geometry of drawable.

Select the event types to be sent to a window.

Window Configuration

XMoveWindow

XResizeWindow

XMoveResizeWindow

XSetWindowBorderWidth

XRestackWindows

XConfigureWindow

XGetGeometry
XReconfigureWMWindow

Move a window.

Change a window s size.

Change the size and position of a window.

Change the border width of a window.

Change the stacking order of siblings.

Change the window position, size, border width, or stacking

order.

Obtain the current geometry of drawable.

Change top-level window position, size, border width, or

stacking order.

560

Xlib Reference Manual

Window Existence

XCreateSimpleWindow
XCreateWindow
XDestroySubwindows
XDestroy Window

Create an unmapped inputOutput subwindow.

Create a window and set attributes.

Destroy all subwindows of a window.

Unmap and destroy a window and all subwindows.

Window Manager Hints

XGetClassHint

XSetClassHint

XGetNormalHints

XSetNormalHints

XGetSizeHints

XSetSizeHints

XGet Trans lent ForHint

XSetTransientForHint

XGetWMHints

XSetWMHints

XGetZoomHints

XSetZoomHints

XFetchName

XStoreName

XGetlconName
XSetlconName

XGetlconSizes
XSetlconSizes
XSetCommand

XAllocClassHint

XAllocIconSize

XAllocSizeHints

XAllocStandardColormap

XAllocWMHints

Get the XA_WM_CLASS property of a window. Obsolete in

R4.

Set the XA_WM_CLASS property of a window. Obsolete in

R4.

Get the size hints property of a window in normal state (not

zoomed or iconified). Obsolete in R4.

Set the size hints property of a window in normal state (not

zoomed or iconified). Obsolete in R4.

Read any property of type XA_WM_SIZE_HINTS. Obsolete

inR4.

Set the value of any property of type XA_WM_-

SIZE_HINTS. Obsolete in R4.

Get the XA_WM_TRANSIENT_FOR property of a window.

Set the XA_WM_TRANSIENT_FOR property of a window.

Read a window manager hints property.

Set a window manager hints property.

Read the size hints property of a zoomed window. Obsolete in

R4.

Set the size hints property of a zoomed window. Obsolete in

R4.

Get a window s name (XA_WM_NAME property). Obsolete in

R4.

Assign a name to a window for the window manager. Obsolete

inR4.

Get the name to be displayed in an icon. Obsolete in R4.

Set the name to be displayed in a window s icon. Obsolete in

R4.

Get preferred icon sizes.

Set the value of the XA_WM_ICON_SIZE property.

Set the XA_WM_COMMAND property (command line arguments).

Obsolete in R4.

Allocate and zero fields in XClassHint structure.

Allocate and zero fields in xlconSize structure.

Allocate and zero fields in xsizeHints structure.

Allocate and zero fields in XStandardColormap structure.

Allocate and zero fields in xwMHints structure.

Function Group Summary

561

Window Manager Hints (continued)

XGetRGBColormaps
XSetRGBColormaps

XGetWMClientMachine
XSetWMClientMachine
XGetWMIconName

XSetWMIconName

XGetWMProtocols
XSetWMProtocols
XGetWMNormalHints

XSetWMNormalHints
XSetWMSizeHints

XSetWMColormapWindows
XGetWMColormapWindows
XSetWMProperties

XSetWMName
XGetWMName

Read standard colormap property. Replaces XGetStan-

dardColormap.

Write standard colormap property. Replaces xsetstan-

dardColormap.

Read WM_CLIENT_MACHINE property.

Write WM_CLIENT_MACHINE property.

Read XA_WM_ICON_NAME property. Replaces XGet-

IconName.

Write XA_WM_ICON_NAME property. Replaces xset-

IconName.

Read WM_PROTOCOLS property.

Write WM_PROTOCOLS property.

Read XA_WM_NORMAL_HINTS property. Replaces xGet-

NormalHints.

Write XA_WM_NORMAL_HINTS property. Replaces XSet-

NormalHints.

Write XA_WM_SIZE_HINTS property. Replaces xset-

SizeHints.

Write WM_COLORMAP_WINDOWS property.

Read WM_COLORMAP_WINDOWS property.

Write all standard properties. Replaces XSetStan-

dardProperties.

Write XA_WM_NAME property. Replaces XStoreName.

Read XA_WM_NAME property. Replaces XFetchName.

Window Manipulation

XLowerWindow

XRaiseWindow

XCirculateSubwindows

XCirculateSubwindowsDown

XCirculateSubwindowsUp

XQueryTree

XRepar en t Window

XMoveWindow

XResizeWindow

XMoveResizeWindow

XSetWindowBorderWidth

XRestackWindows

XConfigureWindow

XlconifyWindow

XWithdrawWindow

XReconfigureWMWindow

Lower a window in the stacking order.

Raise a window to the top of the stacking order.

Circulate the stacking order of children up or down.

Circulate the bottom child to the top of the stacking order.

Circulate the top child to the bottom of the stacking order.

Return a list of children, parent, and root.

Change a window s parent

Move a window.

Change a window s size.

Change the size and position of a window.

Change the border width of a window.

Change the stacking order of siblings.

Change the window position, size, border width, or stacking

order.

Inform window manager that a top-level window should be

iconified.

Inform window manager that a top-level window should be

unmapped.

Reconfigure a top-level window.

562

Xlib Reference Manual

Window Mapping

XMapRaised

XMapSubwindows

XMapWindow

XUnmapSubwindows

XUnmapWindow

XlconifyWindow

XWithdrawWindow

Map a window on top of its siblings.

Map all subwindows.

Map a window.

Unmap all subwindows of a given window.

Unmap a window.

Inform window manager that a top-level window should be iconified.

Inform window manager that a top-level window should be unmapped.

A.2 Alphabetical Listing of Routines

Table A-1. Alphabetical Listing of Routines

Routine

Description

XActivateScreenSaver

XAddHost

XAddHosts

XAddPixel

XAddToSaveSet

XAllocClassHint

XAllocIconSize

XAllocSizeHints

XAllocStandardColormap

XAllocWMHints

XAllocColor

XAllocColorCells
XAllocColorPlanes
XAllocNamedColor
XAllowEvents

XAutoRepeatOff

XAutoRepeatOn

XBell

XChangeActivePointerGrab

XChangeGC

XChangeKeyboardControl

XChangeKeyboardMapping

XChangePointerControl

XChangeProperty

XChangeSaveSet

XChangeWindowAttributes

XChecklfEvent

XCheckMaskEvent

Activate screen blanking.
Add a host to the access control list.
Add multiple hosts to the access control list.
Add a constant value to every pixel value in an image.
Add a window to the client s save-set.
Allocate and zero fields in XClassHint structure.
Allocate and zero fields inxiconSize structure.
Allocate and zero fields in XSizeHints structure.
Allocate and zero fields in XStandardColormap structure.
Allocate and zero fields in XWMHints structure.
Allocate a read-only colormap cell with closest hardware-
supported color.

Allocate read/write (nonshared) colorcells.
Allocate read/write (nonshareable) color planes.
Allocate a read-only colorcell from color name.
Control the behavior of keyboard and pointer events when
these resources are grabbed.
Turn off the keyboard auto-repeat keys.
Turn on the keyboard auto-repeat keys.
Ring the bell (Control G).
Change the parameters of an active pointer grab.
Change the components of a given graphics context.
Change the keyboard preferences such as key click.
Change the keyboard mapping.
Change the pointer preferences.
Change a property associated with a window.
Add or remove a window to or from the client s save-set
Set window attributes.

Check the event queue for a matching event.
Remove the next event that matches mask; don t wait.

Function Group Summary

563

Table A-1. Alphabetical Listing of Routines (continued)

Routine

Description

XCheckTypedEvent

XCheckTypedWindowEvent

XCheckWindowEvent

XCirculateSubwindows
XCirculateSubwindowsDown

XCirculateSubwindowsUp

XClearArea
XClearWindow
XClipBox
XCloseDisplay
XConf igureWindow

XConvert Select ion

XCopyArea

XCopyColormapAndFree

XCopyGC

XCopyPlane

XCreateAssocTable
XCreateBitmapFromData
XCreateColormap
XCreateFont Cursor
XCreateGC

XCreateGlyphCursor
XCreate Image
XCreatePixmap
XCreatePixmapCursor
XCreatePixmapFrom-

BitmapData
XCreateRegion
XCreateSimpleWindow
XCreateWindow
XDefineCursor
XDeleteAssoc
XDeleteContext
XDeleteModifiermapEntry
XDeleteProperty
XDestroyAssocTable
XDestroylmage
XDestroyRegion

Return the next event in queue that matches event type;

Return the next event in queue matching type and window.

Remove the next event matching both passed window and

passed mask; don t wait.

Circulate the stacking order of children up or down.

Circulate the bottom child to the top of the

stacking order.

Circulate the top child to the bottom of the

stacking order.

Clear a rectangular area in a window.

Clear an entire window.

Generate the smallest rectangle enclosing a region.

Disconnect a client program from an X server and display.

Change the window position, size, border width, or stacking

order.

Use the value of a selection.

Copy an area of a drawable.

Copy a colormap and return a new colormap ID.

Copy a graphics context.

Copy a single plane of a drawable into a drawable with depth,

applying pixel values.

Create a new association table (X10).

Create a bitmap from XI 1 bitmap format data.

Create a colormap.

Create a cursor from the standard cursor font

Create a new graphics context for a given screen with the depth

of the specified drawable.

Create a cursor from font glyphs.

Allocate memory for an x Image structure.

Create a pixmap.

Create a cursor from two bitmaps.

Create a pixmap with depth from bitmap data.

Create a new empty region.

Create an unmapped inputOutput window.

Create a window and set attributes.

Assign a cursor to a window.

Delete an entry from an association table.

Delete a context entry for a given window and type.

Delete an entry from an XModif ierKeymap structure.

Delete a window property.

Free the memory allocated for an association table.

Deallocate memory associated with an image.

Deallocate storage associated with a region.

564

Xlib Reference Manual

Table A-1. Alphabetical Listing of Routines (continued)

Routine

Description

XDestroySubwindows

XDestroyWindow

XDisableAccessControl

XDisplayKeycodes

XDisplayMotionBuf ferSize

XDisplayName

XDraw

XDrawArc

XDrawArcs

XDrawFilled

XDrawImageString

XDrawImageStringlG

XDrawLine

XDrawLines

XDrawPoint

XDrawPoints

XDrawRect angle

XDrawRect angles

XDrawSegments

XDrawString

XDrawStringl6

XDrawText

XDrawTextlG

XEmptyRegion

XEnableAccessControl

XEqualRegion

XEventsQueued

XFetchBuffer

XFetchBytes

XFetchName

XFillArc

XFillArcs

XFillPolygon

XFillRectangle

XFillRectangles

XFindContext

XFlush

XForceScreenSaver

XFree

XFreeColormap

XFreeColors

XFreeCursor

Destroy all subwindows of a window.

Unmap and destroy a window and all subwindows.

Allow access from any host

Returns range of keycodes used by server.

Return size of server s motion history buffer.

Report the display name when connection to a display fails.

Draw a polyline or curve between vertex list (from X10).

Draw an arc fitting inside a rectangle.

Draw multiple arcs.

Draw a filled polygon or curve from vertex list (from X10).

Draw 8-bit image text characters.

Draw 16-bit image text characters.

Draw a line between two points.

Draw multiple connected lines.

Draw a point.

Draw multiple points.

Draw an outline of a rectangle.

Draw the outlines of multiple rectangles.

Draw multiple disjoint lines.

Draw an 8-bit text string, foreground only.

Draw two-byte text strings.

Draw 8-bit polytext strings.

Draw 16-bit polytext strings.

Determine if a region is empty.

Use access control list to allow or deny connection requests.

Determine if two regions have the same size, offset, and shape.

Check the number of events in the event queue.

Return data from a cut buffer.

Return data from cut buffer 0.

Get a window s name (XA_WM_NAME property).

Fill an arc.

Fill multiple arcs.

Fill a polygon.

Fill a rectangular area.

Fill multiple rectangular areas.

Get data from the context manager (not graphics context).

Flush the request buffer (display all queued requests).

Turn the screen saver on or off.

Free specified in-memory data created by an Xlib function.

Delete a colormap and install the default colormap.

Free colormap cells or planes.

Destroy a cursor.

Function Group Summary

565

Table A-1. Alphabetical Listing of Routines (continued)

Routine

Description

XCheckTypedEvent

XCheckTypedWindowEvent

XCheckWindowEvent

XCirculateSubwindows
XCirculateSubwindowsDown

XCirculateSubwindowsUp

XClearArea

XClearWindow

XClipBox

XCloseDisplay

XConfigureWindow

XConvertSelection

XCopyArea

XCopyColormapAndFree

XCopyGC

XCopyPlane

XCreateAssocTable

XCreateBitmapFromData

XCreateColormap

XCr eat eFont Cursor

XCreateGC

XCreateGlyphCursor
XCr eate Image
XCreatePixmap
XCreatePixmapCursor
XCreatePixmapFrom-

BitmapData
XCreateRegion
XCreateSimpleWindow
XCreateWindow
XDefineCursor
XDeleteAssoc
XDeleteContext
XDeleteModifiermapEntry
XDeleteProperty
XDestroyAssocTable
XDestroylmage
XDestroyRegion

Return the next event in queue that matches event type;

Return the next event in queue matching type and window.

Remove the next event matching both passed window and

passed mask; don t wait.

Circulate the stacking order of children up or down.

Circulate the bottom child to the top of the

stacking order.

Circulate the top child to the bottom of the

stacking order.

Clear a rectangular area in a window.

Clear an entire window.

Generate the smallest rectangle enclosing a region.

Disconnect a client program from an X server and display.

Change the window position, size, border width, or stacking

order.

Use the value of a selection.

Copy an area of a drawable.

Copy a colormap and return a new colormap ID.

Copy a graphics context.

Copy a single plane of a drawable into a drawable with depth,

applying pixel values.

Create a new association table (X10).

Create a bitmap from XI 1 bitmap format data.

Create a colormap.

Create a cursor from the standard cursor font

Create a new graphics context for a given screen with the depth

of the specified drawable.

Create a cursor from font glyphs.

Allocate memory for an X Image structure.

Create a pixmap.

Create a cursor from two bitmaps.

Create a pixmap with depth from bitmap data.

Create a new empty region.

Create an unmapped inputOutput window.

Create a window and set attributes.

Assign a cursor to a window.

Delete an entry from an association table.

Delete a context entry for a given window and type.

Delete an entry from an XModif ierKeymap structure.

Delete a window property.

Free the memory allocated for an association table.

Deallocate memory associated with an image.

Deallocate storage associated with a region.

564

Xlib Reference Manual

Table A-1. Alphabetical Listing of Routines (continued)

Routine

Description

XDestroySubwindows

XDestroyWindow

XDisableAccessControl

XDisplayKeycodes

XDisplayMotionBufferSize

XDisplayName

XDraw

XDrawArc

XDrawArcs

XDrawFilled

XDrawImageString

XDrawImageString 16

XDrawLine

XDrawLines

XDrawPoint

XDrawPoints

XDrawRect angle

XDr a wRect angles

XDrawSegments

XDrawString

XDrawStringlG

XDrawText

XDrawTextl6

XEmptyRegion

XEnableAccessControl

XEqualRegion

XEventsQueued

XFetchBuffer

XFetchBytes

XFetchName

XFillArc

XFillArcs

XFillPolygon

XFillRectangle

XFillRectangles

XFindContext

XFlush

XForceScreenSaver

XFree

XFreeColormap

XFreeColors

XFreeCursor

Destroy all subwindows of a window.

Unmap and destroy a window and all subwindows.

Allow access from any host

Returns range of keycodes used by server.

Return size of server s motion history buffer.

Report the display name when connection to a display fails.

Draw a polyline or curve between vertex list (from X10).

Draw an arc fitting inside a rectangle.

Draw multiple arcs.

Draw a filled polygon or curve from vertex list (from X10).

Draw 8-bit image text characters.

Draw 16-bit image text characters.

Draw a line between two points.

Draw multiple connected lines.

Draw a point.

Draw multiple points.

Draw an outline of a rectangle.

Draw the outlines of multiple rectangles.

Draw multiple disjoint lines.

Draw an 8-bit text string, foreground only.

Draw two-byte text strings.

Draw 8-bit polytext strings.

Draw 16-bit polytext strings.

Determine if a region is empty.

Use access control list to allow or deny connection requests.

Determine if two regions have the same size, offset, and shape.

Check the number of events in the event queue.

Return data from a cut buffer.

Return data from cut buffer 0.

Get a window s name (XA_WM_NAME property).

Fill an arc.

Fill multiple arcs.

Fill a polygon.

Fill a rectangular area.

Fill multiple rectangular areas.

Get data from the context manager (not graphics context).

Flush the request buffer (display all queued requests).

Turn the screen saver on or off.

Free specified in-memory data created by an Xlib function.

Delete a colormap and install the default colormap.

Free colormap cells or planes.

Destroy a cursor.

Function Group Summary

565

Table A-1. Alphabetical Listing of Routines (continued)

Routine

Description

XFreeExtensionList

XFreeFont

XFreeFontlnfo

XFreeFontNames

XFreeFontPath

XFreeGC

XFreeModifiermap

XFreePixmap

XFreeStringList

XGContextFromGC
XGeometry

XGetAtomName

XGetClassHint

XGetDefault

XGetErrorDatabaseText

XGetErrorText

XGetFontPath

XGetFontProperty

XGetGeometry

XGetGCValues

XGetlconName

XGetlconSizes

XGetlmage

XGetlnputFocus

XGetKeyboardControl

XGetKeyboardMapping

XGetModifierMapping

XGetMotionE vents

XGetNormalHints

XGetPixel

XGet Point erControl

XGetPointerMapping

XGetRGBColormaps

XGetScreenSaver
XGet Select ionOwner
XGetSizeHints
XGetStandardColormap

Free memory allocated for a list of installed

extensions to X.

Unload a font and free storage for the font structure.

Free multiple font information arrays.

Free the font name array.

Free the memory allocated by XGetFontPath.

Free a graphics context.

Destroy and free a keyboard modifier mapping structure.

Free a pixmap ID.

Free memory allocated by XTextProperty-

ToStringList.

Obtain the GContext (resource ID) associated

with the specified graphics context.

Calculate window geometry given user geometry string

and default geometry.

Get a name for a given atom.

Get the XA_WM_CLASS property of a window.

Scan the user preferences for program name and options.

Obtain error messages from the error database.

Obtain a description of error code.

Get the current font search path.

Get a font property given its atom.

Obtain the current geometry of drawable.

Get GC component values from Xlib s GC cache.

Get the name to be displayed in an icon.

Get preferred icon sizes.

Place contents of a rectangle from drawable into an image.

Return the current keyboard focus window.

Obtain a list of the current keyboard preferences.

Return symbols for keycodes.

Obtain a mapping of modifier keys (Shift, Control, etc.).

Get pointer motion events.

Get the size hints property of a window in normal state (not

zoomed or iconified).

Obtain a single pixel value from an image.

Get the current pointer preferences.

Get the pointer button mapping.

Read standard colormap property.

Replaces XGetStandardColormap.

Get the current screen saver parameters.

Return the owner of a selection.

Read any property of type XA_WM_SIZE_HINTS.

Get the standard colormap property.

566

Xlib Reference Manual

Table A-1. Alphabetical Listing of Routines (continued)

Routine

Description

XGetSublmage

XGetTextProperty

XGetTransientForHint

XGetVisuallnfo

XGetWindowAttributes

XGetWindowProperty

XGetWMClientMachine

XGetWMColormapWindows

XGetWMHints

XGetWMIconName

XGetWMName
XGetWMNormalHints

XGetWMProtocols
XGetWMSizeHints

XGetZoomHints

XGrabButton

XGrabKey

XGrabKeyboard

XGrabPointer

XGrabServer

XlconifyWindow

XlfEvent

XInsertModifiermapEntry

XInstallColormap

XInternAtom

XIntersectRegion

XKeycodeToKeysym

XKeysymToKeycode

XKeysymToString

XKillClient

XListDepths

XListExtensions

XListFonts

XListFontsWithlnfo

XListHosts

XListlnstalledColormaps

XListPixmapFormats

Copy a rectangle in drawable to a location within the

pre-existing image.

Read a TEXT property.

Get the XA_WM_TRANS IENT_FOR property of a window.

Find a visual information structure that matches the

specified template.

Obtain the current attributes of window.

Obtain the atom type and property format for a window.

Read WM_CLIENT_MACHINE property.

Read WM_COLORMAP_WINDOWS property.

Read a window manager hints property.

Read XA_WM_ICON_NAME property.

Replaces XGetlconName.

Read XA_WM_NAME property. Replaces XFetchName.

Read XA_WM_NORMAL_HINTS property. Replaces

XGetNormalHints.

Read WM_PROTOCOLS property.

Read XA_WM_SIZE_HINTS property. Replaces

XGetSizeHints.

Read the size hints property of a zoomed window.

Grab a pointer button.

Grab a key.

Grab the keyboard.

Grab the pointer.

Grab the server.

Inform window manager that a top-level window should

be iconified.

Wait for matching event

Add a new entry to an XModif ierKeymap structure.

Install a colormap.

Return an atom for a given name string.

Compute the intersection of two regions.

Convert a keycode to a keysym.

Convert a keysym to the appropriate keycode.

Convert a keysym symbol to a string.

Destroy a client or its remaining resources.

Return a list of the depths supported on this server.

Return a list of all extensions to X supported by the server.

Return a list of the available font names.

Obtain the names and information about loaded fonts.

Obtain a list of hosts having access to this display.

Get a list of installed colormaps.

Return a list of the pixmap formats supported on

this server.

Function Group Summary

567

Table A-1. Alphabetical Listing of Routines (continued)

Routine

Description

XrmQuarkToString
XrmStringToBinding-

QuarkList
XrmStringToQuark
XrmStringToQuarkList
XrmUniqueQuark
XRotateBuffers
XRotateWindowProperties
XSaveContext

XSelectlnput

XSendEvent

XSetAccessControl

XSetAfterFunction

XSetArcMode

XSet Background

XSetClassHint

XSetClipMask

XSetClipOrigin

XSetClipRectangles

XSetCloseDownMode

XSetCommand

XSetDashes

XSetErrorHandler

XSetFillRule

XSetFillStyle

XSetFont

XSetFontPath

XSet Foreground

XSetFunction

XSetGraphicsExposures

XSetlconName

XSetlconSizes

XSetlnputFocus

XSetlOErrorHandler

XSetLineAttributes

XSetModifierMapping

XSetNormalHints

XSetPlaneMask
XSet Point erMapping

Convert a quark to a string.

Convert a key string to a binding list and a quark

list.

Convert a string to a quark.

Convert a key string to a quark list.

Allocate a new quark.

Rotate the cut buffers.

Rotate properties in the properties array.

Save a data value corresponding to a window and

context type (not graphics context).

Select the event types to be sent to a window.

Send an event

Disable or enable access control.

Set a function called after all Xlib functions.

Set the arc mode in a graphics context.

Set the background pixel value in a graphics context.

Set the XA_WM_CLASS property of a window.

Set clip_mask pixmap in a graphics context.

Set the clip origin in a graphics context.

Change clip_mask in a graphics context to the

list of rectangles.

Change the close down mode of a client.

Set the XA_WM_COMMAND atom (command line arguments).

Set dash_of f set and dashes (for lines) in a graphics context.

Set a nonfatal error event handler.

Set the fill rule in a graphics context.

Set the fill style in a graphics context.

Set the current font in a graphics context.

Set the font search path.

Set the foreground pixel value in a graphics context.

Set the bitwise logical operation in a graphics context.

Set graphics_exposures in a graphics context.

Set the name to be displayed in a window s icon.

Set the value of the XA_WM_ICON_SIZE property.

Set the keyboard focus window.

Handle fatal I/O errors.

Set the line drawing components in a graphics context.

Set keycodes to be used as modifiers (Shift, Control,

etc.).

Set the size hints property of a window in normal state

(not zoomed or iconified).

Set the plane mask in a graphics context.

Set the pointer button mapping.

570

Xlib Reference Manual

Table A-1. Alphabetical Listing of Routines (continued)

Routine

Description

XSetRegion
XSetRGBColormaps

XSetScreenSaver

XSet Select ionOwner

XSetSizeHints

XSetStandardColormap

XSetStandardProperties

XSetState

XSetStipple

XSetSubwindowMode

XSetTextProperty

XSetTile

XSetTransientForHint

XSetTSOrigin

XSetWindowBackground

XSetWindowBackground-

Pixmap
XSetWindowBorder

XSetWindowBorderP ixmap

XSetWindowBorderWidth

XSetWindowColormap

XSetWMClientMachine

XSetWMColormapWindows

XSetWMHints

XSetWMIconName

XSetWMName

XSetWMNormalHints

XSetWMProperties

XSetWMProtocols
XSetWMSizeHints

XSetZoomHints
XShrinkRegion
XStoreBuffer

Set clip_mask of the graphics context to

the specified region.

Write standard colormap property. Replaces

XSetStandardColormap.

Set the parameters of the screen saver.

Set the owner of a selection.

Set the value of any property of type XA_WM_S I z E_H I N T s .

Change the standard colormap property.

Set the minimum set of properties for the window manager.

Set the foreground, background, logical function, and

plane mask in a graphics context.

Set the stipple in a graphics context.

Set the subwindow mode in a graphics context.

Write a TEXT property using XTextProperty structure.

Set the fill tile in a graphics context.

Set the XA_WM_TRANSIENT_FOR property

of a window.

Set the tile/stipple origin in a graphics context.

Set the background pixel attribute of a window.

Change the background tile attribute of

a window.

Change a window border attribute to the specified

pixel value and repaint the border.

Change a window border tile attribute and repaint

the border.

Change the border width of a window.

Set the colormap for a specified window.

Write WM_CLIENT_MACHINE property.

Write WM_COLORMAP_WINDOWS property.

Set a window manager hints property.

Write XA_WM_ICON_NAME property. Replaces

XSetlconName.

Write XA_WM_NAME property. Replaces

XStoreName.

Write XA_WM_NORMAL_HINTS property.

Replaces XSetNormalHints.

Write all standard properties. Replaces

XSetStandardProperties.

Write WM_PROTOCOLS property.

Write XA_WM_SIZE_HINTS property. Replaces

XSetSizeHints.

Set the size hints property of a zoomed window.

Reduce or expand the size of a region.

Store data in a cut buffer.

Function Group Summary

571

Table A-1. Alphabetical Listing of Routines (continued)

Routine

Description

XStoreBytes
XStoreColor

XStoreColors

XStoreName

XStoreNamedColor

XStringListToTextProperty

XStringToKeysym
XSublmage
XSubtract Region
XSync

XSynchronize

XTextExtents

XTextExtentslG

XTextWidth

XTextWidthlG

XTranslateCoordinates

XUndef ineCursor

XUngrabButton

XUngrabKey

XUngrabKeyboard

XUngrabPointer

XUngrabServer

XUninstallColormap

XUnionRectWithRegion

XUnionRegion

XUniqueContext

XUnloadFont

XUnmapSubwindows

XUnmapWindow

XWarpPointer

XWindowEvent

XWMGeometry

XWriteBitmapFile
XXorRegion

Store data in cut buffer 0.

Set or change a read/write entry of a colormap to the closest

available hardware color.

Set or change read/write colorcells to the closest available

hardware colors.

Assign a name to a window for the window manager.

Allocate a read/write colorcell by English color name.

Convert a list of strings to an XText Property

structure.

Convert a keysym name string to a keysym.

Create a subimage from part of an image.

Subtract one region from another.

Rush the request buffer and wait for all events and errors

to be processed by the server.

Enable or disable synchronization for debugging.

Get string and font metrics.

Get string and font metrics of a 16-bit character string.

Get the width in pixels of an 8-bit character string.

Get the width in pixels of a 16-bit character string.

Change the coordinate system from one window to

another.

Disassociate a cursor from a window.

Release a button from grab.

Release a key from grab.

Release the keyboard from grab.

Release the pointer from grab.

Release the server from grab.

Uninstall a colormap; install default if not

already installed.

Add a rectangle to a region.

Compute the union of two regions.

Create a new context ID (not graphics context).

Unload a font

Unmap all subwindows of a given window.

Unmap a window.

Move the pointer to another point on the screen.

Remove the next event matching mask and window.

Calculate window geometry given user geometry string

and default geometry.

Write a bitmap to a file.

Calculate the difference between the union and intersection

of two regions.

572

Xlib Reference Manual

B
Error Messages and Protocol Requests

This appendix contains two tables: Table B-l describes the standard error codes (the
error_code member of XErrorEvent) and what causes them, and Table B-2 describes
the mapping between protocol requests and Xlib functions. Each reference page in this vol
ume describes in more detail the errors that may occur because of that Xlib routine. Volume
One, Chapter 3, Basic Window Program, describes the handling of errors in general.

A protocol request is the actual network message that is sent from Xlib to the server. Many
convenience functions are provided in Xlib to make programs easier to write and more read
able. When any one of several convenience routines is called it will be translated into one
type of protocol request. For example, XMoveWindow and XResizeWindow are conve
nience routines for the more general XConf igureWindow. Both of these Xlib routines
use the protocol request Configure Window. The protocol request that causes an error, along
with other information about the error is printed to the standard error output by the default
error handlers. In order to find out where in your code the error occurred, you will need to
know what Xlib function to look for. Use Table B-2 to find this function.

Xlib functions that do not appear in Table B-2 do not generate protocol requests. They per
form their function without affecting the display and without requiring information from the
server. If errors can occur in them, the errors are reported in the returned value.

Table B-1. Error Messages

Error Codes:

Possible Cause

BadAccess

BadAlloc
BadAtom

Specifies that the client attempted to grab a key/button combination
that is already grabbed by another client; free a colormap entry that
is not allocated by the client; store into a read-only colormap entry;
modify the access control list from other than the local (or otherwise
authorized) host; or select an event type that only one client can
select at a time, when another client has already selected it.

Specifies that the server failed to allocate the requested resource.

Specifies that a value for an Atom argument does not name a defined
Atom.

Appendix B: Error Messages and Protocol Requests

573

Table B-1. Error Messages (continued)

Error Codes:

Possible Cause

BadColor

BadCursor

BadDrawable

BadFont

BadGC

BadlDChoice

Badlmplement-
ation

BadLength
BadMatch

BadName
BadPixmap

BadRequest
BadValue

BadWindow

Specifies that a value for a Colormap argument does not name a
defined Colormap.

Specifies that a value for a Cursor argument does not name a
defined Cursor.

Specifies that a value for a Drawable argument does not name a
defined Window or Pixmap.

Specifies that a value for a Font or GContext argument does not
name a defined Font.

Specifies that a value for a GContext argument does not name a
defined GContext.

Specifies that the value chosen for a resource identifier either is not
included in the range assigned to the client or is already in use.

Specifies that the server does not implement some aspect of the
request A server that generates this error for a core request is defi
cient. Clients should be prepared to receive such errors and either
handle or discard them.

Specifies that the length of a request is shorter or longer than that
required to minimally contain the arguments. This usually indicates
an internal Xlib error.

Specifies that an inputOnly window is used as a Drawable.

Some argument (or pair of arguments) has the correct type and range
but fails to "match" in some other way required by the request

Specifies that a font or color of the specified name does not exist.

Specifies that a value for a Pixmap argument does not name a
defined Pixmap.

Specifies that the major or minor opcode does not specify a valid
request

Specifies that some numeric value falls outside the range of values
accepted by the request Unless a specific range is specified for an
argument, the full range defined by the argument s type is accepted.
Any argument defined as a set of alternatives can generate this error.

Specifies that a value for a window argument does not name a
defined window.

The BadAtom, BadColor, BadCursor, BadDrawable, BadFont, BadGC, Bad
Pixmap, and BadWindow errors are also used when the argument type should be among a

574

Xlib Reference Manual

set of fixed alternatives (for example, a window ID, PointerRoot, or None) and some
other constant or variable is used.

Table B-2. Xlib Functions and Protocol Requests

Protocol Request

AllocColor

AllocColorCells

AllocColorPlanes

AllocNamedColor

AllowEvents

Bell

ChangeActivePointerGrab

ChangeGC

ChangeHosts

ChangeKeyboardControl

ChangeKeyboardMapping

ChangePointerControl

ChangeProperty

Xlib Function

XAllocColor

XAllocColorCells

XAllocColorPlanes

XAllocNamedColor

XAllowEvents

XBell

XChange Act ivePointer Grab

XChangeGC

XSetArcMode

XSet Background

XSetClipMask

XSetClipOrigin

XSetFillRule

XSetFillStyle

XSetFont

XSet Foreground

XSetFunction

XSetGraphicsExposures

XSetLineAttributes

XSetPlaneMask

XSetState

XSetStipple

XSetSubwindowMode

XSetTile

XSetTSOrigin

XAddHost
XAddHosts
XRemoveHost
XRemoveHosts

XAutoRepeatOff

XAutoRepeatOn

XChangeKeyboardControl

XChangeKeyboardMapping
XChangePointerControl

XChangeProperty

XSetCommand

XSetlconName

XSetlconSizes

XSetNormalHints

Appendix B: Error Messages and Protocol Requests

575

Table B-2. Xlib Functions and Protocol Requests (continued)

Protocol Request

Xlib Function

ChangeSaveSet

Change Window Attributes

CirculateWindow

Clear Area
CloseFont
Configure Window

ConvertSelection
Copy Area

CopyColormapAndFree
CopyGC
CopyPlane

XSetWMProperties

XSetSizeHints

XSetStandardProperties

XSetWMHints

XSetZoomHints

XStoreBuffer

XStoreBytes

XStoreName

XAddToSaveSet

XChangeSaveSet

XRemoveFromSaveSet

XChangeWindowAttributes

XDefineCursor

XSelectlnput

XSetWindowBackground

XSetWindowBackgroundPixmap

XSetWindowBorder

XSetWindowBorderPixmap

XSetWindowColormap

XUndef ineCursor

XCirculateSubwindows

XCirculateSubwindowsDown

XCirculateSubwindowsUp

XClearArea
XClearWindow

XFreeFont
XUnloadFont

XConfigureWindow

XLowerWindow

XMapRaised

XMoveResize Window

XMoveWindow

XRaiseWindow

XReconfigureWMWindow

XResizeWindow

XRestackWindows

XSetWindowBorderWidth

XCon vert Select ion

XCopyArea

XCopyColormapAndFree

XCopyGC

XCopyPlane

576

Xlib Reference Manual

Table B-2. Xlib Functions and Protocol Requests (continued)

Protocol Request

Xlib Function

CreateColormap

CreateCursor

CreateGC

CreateGlyphCursor

CreatePixmap
Create Window

DeleteProperty

DestroySubwindows

DestroyWindow

FillPoly

ForceScreenSaver

FreeColormap

FreeColors

FreeCursor

FreeGC

FreePixmap

GetAtomName

GetFontPath

GetGeometry

Getlmage
GetlnputFocus

GetKeyboardControl

GetKeyboardMapping

GetModifierMapping

GetMotionEvents

GetPointerControl

GetPointerMapping

XCreateColormap
XCreatePixmapCursor

XCreateGC
XOpenDisplay

XCr eat eFont Cursor
XCreateGlyphCursor

XCreatePixmap

XCreateSimpleWindow
XCreateWindow

XDeleteProperty
XDestroySubwindows
XDestroyWindow
XFillPolygon

XActi vat e ScreenSaver
XForceScreenSaver
XRe set ScreenSaver

XFreeColormap

XFreeColors

XFreeCursor

XFreeGC

XFreePixmap

XGetAtomName

XGetFontPath

XGetGeometry
XGetWindowAttributes

XGet Image

XGetlnputFocus
XSync

XGetKeyboardControl

XGetKeyboardMapping

XGetModifierMapping

XGetMotionEvents

XGetPointerControl

XGetPonterMapping

Appendix B: Error Messages and Protocol Requests

577

Table B-2. Xlib Functions and Protocol Requests (continued)

Protocol Request

Xlib Function

GetProperty

GetScreenSaver

GetSelectionOwner

GetWindow Attributes

GrabButton

GrabKey

GrabKeyboard

GrabPointer

GrabServer

ImageTextS

ImageTextl6

InstallColormap

InternAtom

KillClient

ListExtensions

ListFonts

ListFontsWithlnfo

ListHosts

LisanstaUedColormaps

ListProperties

LookupColor

MapS ub windows
MapWindow

NoOperation

XFetchBytes

XFetchName

XGetlconSizes

XGet IconName

XGetNormalHints

XGetSizeHints

XGe tWindowP roperty

XGetWMProperties

XGetWMHints

XGetZoomHints

XGetScreenSaver

XGet Select ionOwner

XGetWindowAttributes

XGrabButton

XGrabKey

XGrabKeyboard

XGrabPointer

XGrabServer

XDrawImageString

XDrawImageStringlG

XInstallColormap

XInternAtom

XKillClient

XList Ext ens ions

XListFonts

XListFontsWithlnfo

XListHosts

XList InstalledColormaps

XListProperties

XLookupColor
XParseColor

XMapSubwindows

XMapRaised
XMapWindow

XNoOp

578

Xlib Reference Manual

Table B-2. Xlib Functions and Protocol Requests (continued)

Protocol Request

Xlib Function

OpenFont
PolyArc
PolyFillArc
PolyFillRectangle

PolyLine
PolyPoint

PolyRectangle
Poly Segment
PolyText8
PolyTextl6

Putlmage
QueryBestSize

QueryColors
QueryExtension

QueryFont
QueryKeymap
QueryPointer
QueryTextExtents

Query Tree
RecolorCursor
ReparentWindow
RotateProperties

XLoadFont
XLoadQueryFont

XDrawArc
XDrawArcs

XFillArc
XFillArcs

XFillRectangle
XFillRectangles

XDrawLines

XDrawPoint
XDrawPoints

XDrawRect angle
XDrawRect angles

XDrawLine
XDrawSegments

XDrawString
XDrawText

XDrawStringl6
XDrawText 16

XPut Image

XQueryBest Cursor
XQueryBestSize
XQueryBest Stipple
XQueryBestTile

XQueryColor
XQueryColors

XInitExtension
XQueryExtension

XLoadQueryFont
XQueryKeymap
XQueryPo inter

XQueryText Extents
XQueryTextExtentsl6

XQueryTree
XRecolor Cursor
XReparentWindow
XRotateBuffers

Appendix B: Error Messages and Protocol Requests

579

Table B-2. Xlib Functions and Protocol Requests (continued)

Protocol Request

Xlib Function

SendEvent
SetAccessControl

SetClipRectangles

SetCloseDownMode

SetDashes

SetFontPath

SetlnputFocus

SetModifierMapping

SetPointerMapping

SetScreenSaver

SetSelectionOwner

StoreColors

StoreNamedColor

TranslateCoords

UngrabButton

UngrabKey

UngrabKeyboard

UngrabPointer

UngrabServer

UninstallColormap

UnmapS ubwindows

UnmapWindow

WarpPointer

XRotateWindowProperties
XSendEvent

XDisableAccessControl

XEnableAccessControl

XSetAccessControl

XSetClipRect angles

XSetCloseDownMode

XSetDashes

XSetFontPath

XSetlnputFocus

XSetModifierMapping

XSetPointerMapping

XSetScreenSaver

XSet Select ionOwner

XStoreColor
XStoreColors

XStoreNamedColor

XTranslateCoordinates

XUngrabButton

XUngrabKey

XUngrabKeyboard

XUngrabPointer

XUngrabServer

XUninstallColormap

XUnmapSubWindows

XUnmapWindow

XWarpPointer

580

Xlib Reference Manual

Macros

Once you have successfully connected your application to an X server, you can obtain data
from the Display structure associated with that display. The Xlib interface provides a
number of useful C language macros and corresponding functions for other language bind
ings which return data from the Display structure.

The function versions of these macros have the same names as the macros except that the
function forms begin with the letter "X." They use the same arguments. Using the macro
versions is slightly more efficient in C because it eliminates function call overhead.

In R3 and R4, a few new functions were added that access members of the Display struc
ture. These are XDisplayMotionBufferSize, XResourceManagerString,
XDisplayKeycodes, and XMaxRequestSize in R3 and XScreenNumber-
OfScreen, XListDepths, and XListPixmapFormats in R4. Also, XVisual-
iDFromVisual was added in R3 to extract the resource ID from a visual structure.
XDisplayMotionBufferSize, XResourceManagerString, XMaxRequest
Size, XScreenNumberOf Screen, and XVisuallDFromVisual are simple enough
to have macro versions, but these were not provided. Nevertheless, we have chosen to cover
them in this macro appendix instead of devoting a reference page to each. XDisplay
Keycodes, XListDepths, and XListPixmapFormats are more complicated and
therefore have their own reference pages; they are not covered here.

For the purposes of this appendix, the macros are divided into four categories: Display mac
ros, Image Format macros, Keysym Classification macros, and Resource Manager macros.
The macros are listed alphabetically within each category.

Note that some macros take as arguments an integer screen (scr_num) while others take a
pointer to a Screen structure (scr_ptr). scr_num is returned by the Default-
Screen macro and scr_ptr is returned by the Default ScreenOf Display macro.

Appendix C: Macros 581

C.1 Display Macros

AllPlanes

BlackPixel(di splay, scr_num)

BlackPixelOf Screen (scr_ptr)

CellsOf Screen (scr_ptr)

Connect ionNumber(disp_Z ay)

Return a value with all bits set suitable for use as
a plane mask argument

Return the black pixel value in the default color-
map that is created by XOpenDisplay.

Return the black pixel value in the default color-
map of the specified screen.

Return the number of colormap cells in the
default colormap of the specified screen.

Return a connection number for the specified
display. On a UNIX system, this is the file
descriptor of the connection.

DefaultColormap(dispJay,scr_/ium) Return the default colormap for the specified

screen. Most routine allocations of color should
be made out of this colormap.

DefauitCoiormapOf Screen (scr_ptr) Return the default colormap of the specified

screen.

DefaultDepth(dJsplay,scr_/iu/n)

DefaultDepthOf Screen (scr_ptr)
DefaultGC(dispJay,scr_/5u/n)

DefaultGCOfScreen(scr ptr)
DefaultRootWindow(dispIay)

DefaultScreen(dispJay)

Return the depth (number of planes) of the root
window for the specified screen. Other depths
may also be supported on this screen. See Vol
ume One, Chapter 7, Color, or the reference
pages for XMatchVisuallnfo and XGet-
visuallnfo to find out how to determine
what depths are available.

Return the default depth of the specified screen.

Return the default graphics context for the speci
fied screen.

Return the default graphics context (GC) of the
specified screen.

Return the ID of the root window on the default
screen. Most applications should use Root-
window instead so that screen selection is sup
ported.

Return the integer that was specified in the last
segment of the string passed to XOpen
Display or from the DISPLAY environment
variable if NULL was used. For example, if the
DISPLAY environment were Ogre : . 1, then
Def aultScreen would return 1.

582

Xlib Reference Manual

DefaultScreenOfDisplay(display) Return the default screen of the specified dis
play.

DefaultVisual(display,scr_/7um)

DefaultVisualOf Screen (scr_ptr)
DisplayCells (display, scr_num)

DisplayHeight(display,scr_r3um)

DisplayHeightMM(display,scr_/iu/n)

DisplayOf Screen (scr_ptr)

Display? lanes (displ ay, scr_n urn)

Display String (display)

DisplayWidth(d-isp_Zay,scr nu/n)

DisplayWidthMM(dispIay,scr num)

DoesBackingStore(scr_ptr)

DoesSaveUnders (scr_ptr)

Return a pointer to the default visual structure
for the specified screen.

Return the default visual of the specified screen.

Return the maximum possible number of color-
map cells on the specified screen. This macro is
misnamed: it should have been Screen-
Cells.

Return the height in pixels of the screen. This
macro is misnamed: it should have been
ScreenHeight.

Return the height in millimeters of the specified
screen. This macro is misnamed: it should have
been ScreenHeightMM.

Return the display associated with the specified
screen.

Return the number of planes on the specified
screen. This macro is misnamed: it should have
been ScreenPlanes.

Return the string that was passed to XOpen-
Di splay when the current display was opened
(or, if that was NULL, the value of the DISPLAY
environment variable). This macro is useful in
applications which invoke the fork system call
and want to open a new connection to the same
display from the child process.

Return the width in pixels of the screen. This
macro is misnamed: it should have been
ScreenWidth.

Return the width in millimeters of the specified
screen. This macro is misnamed: it should have
been ScreenWidthMM.

Return a value indicating whether the screen
supports backing stores. Values are When-
Mapped, NotUsef ul, or Always. See Vol
ume One, Section 4.3.5 for a discussion of the
backing store.

Return a Boolean value indicating whether the
screen supports save unders. If True, the
screen supports save unders. If False, the
screen does not support save unders. See

Appendix C: Macros

583

dpyno( display)

EventMaskOf Screen (scr_ptr)
He ightOf Screen (scr_ptr)
HeightMMOf Screen (scr_ptr)
Keyboard (display)

LastKnownRequestProcessed
(display)

MaxCmapsOf Screen (scr_ptr)
MinCmapsOf Screen(scr ptr)
Next Request (display)

PlanesOf Screen (scr_ptr)
ProtocolRe vision (display)
ProtocolVersion(display)

QLength(display)
RootWindow(display,scr num)

Volume One, Section 4.3.6 for a discussion of
the save under.

Return the file descriptor of the connected dis
play. On a UNIX system, you can then pass this
returned file descriptor to the select(3) system
call when your application program is driving
more than one display at a time.

Return the initial event mask for the root win
dow of the specified screen.

Return the height in pixels of the specified
screen.

Return the height in millimeters of the specified
screen.

Return the device ID for the main keyboard con
nected to the display.

Return the serial ID of the last known protocol
request to have been issued. This can be useful
in processing errors, since the serial number of
failing requests are provided in the XError-
Event structure.

Return the maximum number of installed (hard
ware) colormaps supported by the specified
screen.

Return the minimum number of installed (hard
ware) colormaps supported by the specified
screen.

Return the serial ID of the next protocol request
to be issued. This can be useful in processing
errors, since the serial number of failing requests
are provided in the XErrorEvent structure.

Return the number of planes in the specified
screen.

Return the minor protocol revision number of
the X server.

Return the version number of the X protocol
associated with the connected display. This is
currently 11.

Return the number of events that can be queued
by the specified display.

Return the ID of the root window. This macro is
necessary for routines that reference the root

584

Xlib Reference Manual

RootWindowOf Screen (scr_ptr)
ScreenCount( display)
ScreenOf Display (disp_Zay,scr_/iim?)
ServerVendor( display)

VendorRe lease (display)
WhitePixel(display,scr_/]U/n)
WhitePixelOf Screen (scr_ptr)

WidthOfScreen(scr_ptr)
WidthMMOfScreen(scr_ptr)

XDisplayMotionBufferSize (display)

XMaxRequestSize(dispIay)

XScreenNumberOf Screen (scr_ptr)
XVisualIDFromVisual( visual)

window or create a top-level window for an
application.

Return the ID of the root window of the speci
fied screen.

Return the number of available screens on a
specified display.

Return the specified screen of the specified dis
play.

Return a pointer to a null terminated string giv
ing some identification of the owner of the X
server implementation.

Return a number related to the release of the X
server by the vendor.

Return the white pixel value in the default color-
map that is created by XOpenDi splay.

Return the white pixel value in the default color-
map of the specified screen.

Return the width of the specified screen.

Return the width of the specified screen in milli
meters.

Return an unsigned long value containing
the size of the motion buffer on the server. If
this function returns zero, the server has no
motion history buffer.

Return a long value containing the maximum
size of a protocol request for the specified server,
in units of four bytes.

Return the integer screen number corresponding
to the specified pointer to a Screen structure.

Returns the ID of the server resource associated
with a visual structure. This is useful when stor
ing standard colormap properties.

Appendix C: Macros

585

C.2 Image Format Macros

BitmapBitOrder(display) Within each BitmapUnit, the leftmost bit in the bit
map as displayed on the screen is either the least or the
most significant bit in the unit. Returns LSBFirst or
MSBFirst.

BitmapPad(display) Each scan line must be padded to a multiple of bits speci

fied by the value returned by this macro.

BitmapUnit (display) Returns the size of a bitmap s unit. The scan line is quan

tized (calculated) in multiples of this value.

imageByteOrder(dispiay) Returns the byte order for images required by the server

for each scan line unit in XY format (bitmap) or for each
pixel value in Z format. Values are LSBFirst or
MSBFirst.

C.3 Keysym Classification Macros

You may want to test if a keysym of the defined set (XK_MISCELLANY) is, for example, on
the key pad or the function keys. You can use the keysym macros to perform the following
tests:

I sCursorKey (keysym) Return True if the keysym represents a cursor key.

isFunctionKeyUeysym) Return True if the keysym represents a function key.

isKeypadKeyUeysym) Return True if the keysym represents a key pad.

I sMiscFunctionKey( keysym) Return True if the keysym represents a miscellaneous

function key.

isModif ierKey (keysym) Return True if the keysym represents a modifier key.

i sPFKey (keysym) Return True if the keysym represents a PF key.

C.4 Resource Manager Macros

These macros convert from strings to quarks and quarks to strings. They are used by the
resource manager. Note that they do not follow the normal naming conventions for macros,
since they begin with an X.

XrmStringToName(stri/ig) Convert String to XrmName. Same as XString-

ToQuark.

XrmStringToClass(string) Convert String to XrmClass. Same as XString-

ToQuark.

556 Xlib Reference Manual

XrmStringToRepresentation Convert String to XrmRepresentation. Same as

(string)
XrmNameToString(/ja/ne)

XrmClassToString(class)

XStringToQuark.

Convert XrmName to string. Same as XrmQuark-
ToString.

Convert XrmClass to string. Same as XrmQuark-
ToString.

XrmRepresentationToString Convert XrmRepresentation to String. Same as
(type) XrmQuarkToString.

XResourceManagerString( display)

Return a pointer to the resource database string stored
in the Display structure. This string is read from the
RESOURCE_MANAGER property on the root window;
this property is normally set by the xrdb client.

Appendix C: Macros

587

The Color Database

The color database translates color name strings into RGB values. It is used by XParse-
Color, XLookupColor, and xstoreNamedColor. These routines make it easier to
allow the user to specify color names. Use of these names for routine color allocation of
read-only colorcells is encouraged since this increases the chance of sharing colorcells and
thereby makes the colormap go further before running out of colorcells. The location in the
file system of the text version of the color database is an implementation detail, but by
default on a UNIX system it is lusrlliblXlllrgb.txt.

It should be noted that while a sample color database is provided with the standard XI 1 dis
tribution, it is not specified as an X Consortium standard and is not part of the X Protocol or
Xlib. Therefore, it is permissible for server vendors to change the color names, although they
will probably only add color names. Furthermore, hardware vendors can change the RGB
values for each display hardware to achieve the proper "gamma correction" so that the colors
described by the name really generate that color.

The RGB values in the R3 database were originally tuned for the DEC VT240 display. The
color that appears on a Sun system given these RGB values for "pink," for example, looks
more like light burgundy. In R4 a new RGB color database is provided, which provides
many more color names and provides values that generate colors that match their names on
more monitors.

Each color name in the database may be used in the form shown or in mixed case, with initial
capitals and all spaces eliminated. Table D-l (see next page) shows the R3 database, and
Table D-2 shows the R4 database.

Appendix D: Colors 589

Table D- 1. The R3 Color Database

English Words

Red

Green

Blue

English Words

Red

Green

Blue

English Words

Red

Green

Blue

medium aquamarine

204

153

aquamarine

112

219

147

English Words

Red

Green

Blue

black

medium blue

204

blue

255

medium forest green

107

142

blue violet

159

medium goldenrod

234

173

brown

165

medium orchid

147

112

219

cadet blue

159

medium sea green

111

coral

255

127

medium slate blue

127

255

cornflower blue

111

medium spring green

127

255

cyan

255

medium turquoise

112

219

dark green

medium violet red

219

112

147

dark olive green

midnight blue

dark orchid

153

204

navy

142

dark slate blue

107

142

navy blue

142

dark slate gray

orange

204

dark slate grey

orange red

255

127

dark turquoise

112

147

219

orchid

219

112

219

dim gray

pale green

143

188

143

dim grey

pink

188

143

firebrick

142

plum

234

173

234

forest green

142

purple

176

255

gold

204

127

red

255

goldenrod

219

112

salmon

111

gray

192

sea green

142

107

green

255

sienna

142

107

green yellow

147

219

112

sky blue

153

204

grey

192

slate blue

127

255

indian red

spring green

255

127

khaki

159

steel blue

107

142

light blue

191

216

tan

219

147

112

light gray

168

thistle

216

191

216

light grey

168

turquoise

173

234

light steel blue

143

188

violet

lime green

204

violet red

204

153

magenta

255

wheat

216

191

maroon

142

107

white

252

yellow

255

yellow green

153

204

*Also defined are the color names "grayO" through "graylOO", spelled with an V or an "a". "grayO" is black and
"gray 100" is white.

530

Xlib Reference Manual

Table D-2. The R4 Color Database

English Words

Red

Green

Blue

English Words

Red

Green

Blue

snow

255

250

black

ghost white

248

255

dark slate gray

GhostWhite

248

255

DarkSlateGray

white smoke

245

dark slate grey

WhiteSmoke

245

DarkSlateGrey

gainsboro

220

dim gray

105

floral white

255

250

240

DimGray

105

Floral White

255

250

240

dim grey

105

old lace

253

245

230

DimGrey

105

OldLace

253

245

230

slate gray

112

128

144

linen

250

240

230

SlateGray

112

128

144

antique white

250

235

215

slate grey

112

128

144

AntiqueWhite

250

235

215

SlateGrey

112

128

144

papaya whip

255

239

213

light slate gray

119

136

153

PapayaWhip

255

239

213

LightSlateGray

119

136

153

blanched almond

255

235

205

light slate grey

119

136

153

BlanchedAlmond

255

235

205

LightSlateGrey

119

136

153

bisque

255

228

196

gray

192

peach puff

255

218

185

grey

192

PeachPuff

255

218

185

light grey

211

navajo white

255

222

173

LightGrey

211

NavajoWhite

255

222

173

light gray

211

moccasin

255

228

181

LightGray

211

cornsilk

255

248

220

midnight blue

112

ivory

255

240

MidnightBlue

112

lemon chiffon

255

250

205

navy

128

LemonChiffon

255

250

205

navy blue

128

seasheU

255

245

238

NavyBlue

128

honeydew

240

255

240

cornflower blue

100

149

237

mint cream

245

255

250

ComflowerBlue

100

149

237

MintCream

245

255

250

dark slate blue

139

azure

240

255

DarkSlateBlue

139

alice blue

240

248

255

slate blue

106

205

AliceBlue

240

248

255

SlateBlue

106

205

lavender

230

250

medium slate blue

123

104

238

lavender blush

255

240

245

MediumSlateBlue

123

104

238

LavenderBlush

255

240

245

light slate blue

132

112

255

misty rose

255

228

225

LightSlateBlue

132

112

255

MistyRose

255

228

225

medium blue

205

white

255

MediumBlue

205

Appendix D: Colors

591

Table D-2. The R4 Color Database (continued)

English Words

Red

Green

Blue

English Words

Red

Green

Blue

royal blue

105

225

sea green

139

RoyalBlue

105

225

SeaGreen

139

blue

255

medium sea green

179

113

dodger blue

144

255

MediumSeaGreen

179

113

DodgerBlue

144

255

light sea green

178

170

deep sky blue

191

255

LightSeaGreen

178

170

DeepSkyBlue

191

255

pale green

152

251

152

sky blue

135

206

235

PaleGreen

152

251

152

SkyBlue

135

206

235

spring green

255

127

light sky blue

135

206

250

SpringGreen

255

127

LightSkyBlue

135

206

250

lawn green

124

252

steel blue

130

180

LawnGreen

124

252

SteelBlue

130

180

green

255

light steel blue

176

196

222

chartreuse

127

255

LightS teelBlue

176

196

222

medium spring green

250

154

light blue

173

216

230

MediumSpringGreen

250

154

LightBlue

173

216

230

green yellow

173

255

powder blue

176

224

230

GreenYellow

173

255

PowderBlue

176

224

230

lime green

205

pale turquoise

175

238

LimeGreen

205

PaleTurquoise

175

238

yellow green

154

205

dark turquoise

206

209

YellowGreen

154

205

DarkTurquoise

206

209

forest green

139

medium turquoise

209

204

ForestGreen

139

MediumTurquoise

209

204

olive drab

107

142

turquoise

224

208

OliveDrab

107

142

cyan

255

dark khaki

189

183

107

light cyan

224

255

DarkKhaki

189

183

107

LightCyan

224

255

khaki

240

230

140

cadet blue

158

160

pale goldenrod

238

232

170

CadetBlue

158

160

PaleGoldenrod

238

232

170

medium aquamarine

102

205

170

light goldenrod yellow

250

210

MediumAquamarine

102

205

170

LightGoldenrodYellow

250

210

aquamarine

127

255

212

light yellow

255

224

dark green

100

LightYellow

255

224

DarkGreen

100

yellow

255

dark olive green

107

gold

255

215

DarkOliveGreen

107

light goldenrod

238

221

130

dark sea green

143

188

143

LightGoldenrod

238

221

130

DarkSeaGreen

143

188

143

goldenrod

218

165

Xlib Reference Manual

Table D-2. The R4 Color Database (continued)

English Words

Red

Green

Blue

English Words

Red

Green

Blue

dark goldenrod

184

134

LightPink

255

182

193

DarkGoldenrod

184

134

pale violet red

219

112

147

rosy brown

188

143

PaleVioletRed

219

112

147

RosyBrown

188

143

maroon

176

Indian red

205

medium violet red

199

133

IndianRed

205

MediumVioletRed

199

133

saddle brown

139

violet red

208

144

SaddleBrown

139

VioletRed

208

144

sienna

160

magenta

255

peru

205

133

violet

238

130

238

burlywood

222

184

135

plum

221

160

221

beige

245

220

orchid

218

112

214

wheat

245

222

179

medium orchid

186

211

sandy brown

244

164

MediumOrchid

186

211

SandyBrown

244

164

dark orchid

153

204

tan

210

180

140

DarkOrchid

153

204

chocolate

210

105

dark violet

148

211

firebrick

178

DarkViolet

148

211

brown

165

blue violet

138

226

dark salmon

233

150

122

BlueViolet

138

226

DarkSalmon

233

150

122

purple

160

240

salmon

250

128

114

medium purple

147

112

219

light salmon

255

160

122

MediumPurple

147

112

219

LightS almon

255

160

122

thistle

216

191

216

orange

255

165

snowl

255

250

dark orange

255

140

snow2

238

233

DarkOrange

255

140

snow3

205

201

coral

255

127

snow4

139

137

light coral

240

128

seashelll

255

245

238

LightCoral

240

128

seashel!2

238

229

222

tomato

255

seashelD

205

197

191

orange red

255

seashel!4

139

134

130

OrangeRed

255

AntiqueWhitel

255

239

219

red

255

AntiqueWhite2

238

223

204

hot pink

255

105

180

AntiqueWhite3

205

192

176

HotPink

255

105

180

AntiqueWhite4

139

131

120

deep pink

255

147

bisque 1

255

228

196

DeepPink

255

147

bisque2

238

213

183

pink

255

192

203

bisque3

205

183

158

light pink

255

182

193

bisque4

139

125

107

Appendix D: Colors

593

Table D-2. The R4 Color Database (continued)

English Words

Red

Green

Blue

English Words

Red

Green

Blue

PeachPuffl

255

218

185

LightPink

255

182

193

PeachPuffZ

238

203

173

pale violet red

219

112

147

PeachPufO

205

175

149

PaleVioletRed

219

112

147

PeachPuff4

139

119

101

maroon

176

NavajoWhitel

255

222

173

medium violet red

199

133

NavajoWhite2

238

207

161

MediumVioletRed

199

133

NavajoWhiteS

205

179

139

violet red

208

144

NavajoWhite4

139

121

VioletRed

208

144

LemonChiffonl

255

250

205

magenta

255

LemonChiffon2

238

233

191

violet

238

130

238

LemonChiffonS

205

201

165

plum

221

160

221

LemonChiffon4

139

137

112

orchid

218

112

214

cornsilkl

255

248

220

medium orchid

186

211

cornsilk2

238

232

205

MediumOrchid

186

211

comsilk3

205

200

177

dark orchid

153

204

cornsilk4

139

136

120

DarkOrchid

153

204

ivory 1

255

240

dark violet

148

211

ivory2

238

224

DarkViolet

148

211

ivoryS

205

193

blue violet

138

226

ivory4

139

131

BlueViolet

138

226

honeydewl

240

255

240

purple

160

240

honeydew2

224

238

224

medium purple

147

112

219

honeydewS

193

205

193

MediumPurple

147

112

219

honeydew4

131

139

131

thistle

216

191

216

LavenderBlushl

255

240

245

snowl

255

250

LavenderBlush2

238

224

229

snow2

238

233

LavenderBlushS

205

193

197

snow3

205

201

LavenderBlush4

139

131

134

snow4

139

137

MistyRosel

255

228

225

seashelll

255

245

238

MistyRose2

238

213

210

seashel!2

238

229

222

MistyRose3

205

183

181

seashel!3

205

197

191

MistyRose4

139

125

123

seashel!4

139

134

130

azure 1

240

255

AntiqueWhitel

255

239

219

azure2

224

238

AntiqueWhite2

238

223

204

azureS

193

205

AntiqueWhite3

205

192

176

azure4

131

139

AntiqueWhite4

139

131

120

SlateBluel

131

111

255

bisque 1

255

228

196

SlateBlue2

122

103

238

bisque2

238

213

183

SlateBlueS

105

205

bisque3

205

183

158

SlateBlue4

139

bisque4

139

125

107

Xlib Reference Manual

Table D-2. The R4 Color Database (continued)

English Words

Red

Green

Blue

English Words

Red

Green

Blue

RoyalBluel

118

255

LightCyanl

224

255

RoyalBlue2

110

238

LightCyan2

209

238

RoyalBlueS

205

LightCyan3

180

205

RoyalBlue4

139

LightCyan4

122

139

bluel

255

PaleTurquoisel

187

255

blue2

238

PaleTurquoise2

174

238

blue3

205

PaleTurquoiseS

150

205

blue4

139

PaleTurquoise4

102

139

DodgerBluel

144

255

CadetBluel

152

245

255

DodgerBlue2

134

238

CadetBlue2

142

229

238

DodgerBlueS

116

205

CadetBlue3

122

197

205

DodgerBlue4

139

CadetBlue4

134

139

SteelBluel

184

255

turquoise 1

245

255

SteelBlue2

172

238

turquoise2

229

238

SteelBlueS

148

205

turquoise3

197

205

SteelBlue4

100

139

turquoise4

134

139

DeepSkyBluel

191

255

cyanl

255

DeepSkyBlue2

178

238

cyan2

238

DeepSkyBlue3

154

205

cyan3

205

DeepSkyBlue4

104

139

cyan4

139

SkyBluel

135

206

255

DarkSlateGrayl

151

255

SkyBlue2

126

192

238

DarkSlateGray2

141

238

SkyBlue3

108

166

205

DarkSlateGray3

121

205

SkyBlue4

112

139

DarkSlateGray4

139

LightSkyBluel

176

226

255

aquamarine 1

127

255

212

LightSkyBlue2

164

211

238

aquamarine2

118

238

198

LightSkyBlueS

141

182

205

aquamarines

102

205

170

LightSkyBlue4

123

139

aquamarine4

139

116

SlateGrayl

198

226

255

DarkSeaGreenl

193

255

193

SlateGray2

185

211

238

DarkSeaGreen2

180

238

180

SlateGrayS

159

182

205

DarkSeaGreenS

155

205

155

SlateGray4

108

123

139

DarkSeaGreen4

105

139

105

LightS teelBluel

202

225

255

SeaGreenl

255

159

Lights teelBlue2

188

210

238

ScaGreen2

238

148

LightSteelBlue3

162

181

205

SeaGreen3

205

128

LightS teelBlue4

110

123

139

SeaGreen4

139

LightBluel

191

239

255

PaleGreenl

154

255

154

LightBlue2

178

223

238

PaleGreen2

144

238

144

LightBlueS

154

192

205

PaleGreen3

124

205

124

LightBlue4

104

131

139

PaleGreen4

139

Appendix D: Colors

595

Table D-2. The R4 Color Database (continued)

English Words

Red

Green

Blue

English Words

Red

Green

Blue

SpringGreenl

255

127

goldenrodl

255

193

SpringGreen2

238

118

goldenrod2

238

180

34"

SpringGreenS

205

102

goldenrod3

205

155

SpringGreen4

139

goldenrod4

139

105

green 1

255

DarkGoldenrodl

255

185

green2

238

DarkGoldenrod2

238

173

green3

205

DarkGoldenrod3

205

149

green4

139

DarkGoldenrod4

139

101

chartreuse 1

127

255

RosyBrownl

255

193

chartreuse2

118

238

RosyBrown2

238

180

chartreuse3

102

205

RosyBrown3

205

155

chartreuse4

139

RosyBrown4

139

105

OliveDrabl

192

255

IndianRedl

255

106

OliveDrab2

179

238

IndianRed2

238

OliveDrabS

154

205

IndianRed3

205

OliveDraM

105

139

IndianRed4

139

DarkOliveGreenl

202

255

112

sienna 1

255

130

DarkOliveGreen2

188

238

104

sienna2

238

121

DarkOliveGreenS

162

205

sienna3

205

104

DarkOliveGreen4

110

139

sienna4

139

khaki 1

255

246

143

burly wood 1

255

211

155

khaki2

238

230

133

burlywood2

238

197

145

khakiS

205

198

115

burlywood3

205

170

125

khaki4

139

134

burlywood4

139

115

LightGoldenrodl

255

236

139

wheat 1

255

231

186

LightGoldenrod2

238

220

130

wheat2

238

216

174

LightGoldenrod3

205

190

112

wheat3

205

186

150

LightGoldenrod4

139

129

wheat4

139

126

102

LightYellowl

255

224

tanl

255

165

LightYellow2

238

209

tan2

238

154

LightYellowS

205

180

tan3

205

133

LightYellow4

139

122

tan4

139

yellow 1

255

chocolate 1

255

127

yellow2

238

chocolate2

238

118

yellow3

205

chocolates

205

102

yellow4

139

chocolate4

139

goldl

255

215

firebrickl

255

gold2

238

201

firebrick2

238

gold3

205

173

firebricks

205

gold4

139

117

firebrick4

139

596

Xlib Reference Manual

Table D-2. The R4 Color Database (continued)

English Words

Red

Green

Blue

English Words

Red

Green

Blue

brown 1

255

HotPinkl

255

110

180

brown2

238

HotPink2

238

106

167

brown3

205

HotPink3

205

144

brown4

139

HotPink4

139

salmon 1

255

140

105

pinkl

255

181

197

salmon2

238

130

pink2

238

169

184

salmonS

205

112

pink3

205

145

158

salmon4

139

pink4

139

108

LightSalmonl

255

160

122

LightPinkl

255

174

185

LightS almon2

238

149

114

LightPink2

238

162

173

LightSalmonS

205

129

LightPink3

205

140

149

LightSalmon4

139

LightPink4

139

101

orangel

255

165

PaleVioletRedl

255

130

171

orange2

238

154

PaleVioletRed2

238

121

159

orangeS

205

133

PaleVioletRed3

205

104

137

orange4

139

PaleVioletRed4

139

DarkOrangel

255

127

maroon 1

255

179

DarkOrange2

238

118

maroon2

238

167

DarkOrangeS

205

102

maroon3

205

144

DarkOrange4

139

maroon4

139

coral 1

255

114

VioletRedl

255

150

cora!2

238

106

VioletRed2

238

140

cora!3

205

VioletRed3

205

120

cora!4

139

VioletRed4

139

tomato 1

255

magenta 1

255

tomato2

238

magenta2

238

tomatoS

205

magenta3

205

tomato4

139

magenta4

139

OrangeRedl

255

orchid 1

255

131

250

OrangeRed2

238

orchid2

238

122

233

OrangeRedS

205

orchid3

205

105

201

OrangeRed4

139

orchid4

139

137

redl

255

pluml

255

187

255

red2

238

plum2

238

174

238

red3

205

plum3

205

150

205

red4

139

plum4

139

102

139

DeepPinkl

255

147

MediumOrchidl

224

102

255

DeepPink2

238

137

MediumOrchid2

209

238

DeepPink3

205

118

MediumOrchidS

180

205

DeepPink4

139

MediumOrchid4

122

139

Appendix D: Colors

597

Table D-2. The R&lt;
English Words

t Color L
Red

database*
Green

(continued)
Blue

DarkOrchidl

191

255

DarkOrchid2

178

238

DaikOrchidS

154

205

DarkOrchid4

104

139

purplel

155

255

purple2

145

238

purpleS

125

205

purple4

139

MediumPurplel

171

130

255

MediumPurple2

159

121

238

MediumPurpleS

137

104

205

MediumPurple4

139

thistlcl

255

225

255

thisUe2

238

210

238

thistleS

205

181

205

thistle4

139

123

139

VIV 100,speUedwithdc"or V. "gmyO" black and

595

Xlib Reference Manual

Event Reference

This appendix describes each event structure in detail and briefly shows how each event type
is used. It covers the most common uses of each event type, the information contained in
each event structure, how the event is selected, and the side effects of the event, if any. Each
event is described on a separate reference page.

Table E-l lists each event mask, its associated event types, and the associated structure defi
nition. See Chapter 8, Events, of Volume One, Xlib Programming Manual, for more informa
tion on events.

Table E-1. Event Masks, Event Types, and Event Structures

Event Mask

Event Type

Structure

KeyPressMask

KeyPress

XKeyPressedEvent

KeyReleaseMask

KeyRelease

XKeyReleasedEvent

ButtonPressMask

ButtonPress

XButtonPressedEvent

ButtonReleaseMask

ButtonRe lease

XButtonReleasedEvent

Owner GrabButtonMask

n/a

KeymapStateMask

KeymapNotify

XKeymapEvent

PointerMotionMask

MotionNotify

XPointerMovedEvent

PointerMotionHintMask

ButtonMotionMask

ButtonlMotionMask

Button2MotionMask

ButtonSMotionMask

Button4MotionMask

ButtonSMotionMask

EnterWindowMask

EnterNotify

XEnterWindowEvent

LeaveWindowMask

LeaveNotify

XLeaveWindowEvent

FocusChangeMask

Focusln

XFocusInEvent

FocusOut

XFocusOut Event

Appendix E: Event Reference

599

Table E-1. Event Masks, Event Types, and Event Structures (continued)

Event Mask

Event Type

Structure

ExposureMask
selected in GC by

graphics expose member

Expose

GraphicsExpose
NoExpose

XExposeEvent

XGraphicsExposeEvent
XNoExposeEvent

ColormapChangeMask

ColormapNotify

XColormapEvent

PropertyChangeMask

PropertyNotify

XPropertyEvent

VisibilityChangeMask

VisibilityNotify

XVisibilityEvent

ResizeRedirectMask

ResizeRequest

XResizeRequestEvent

StructureNotifyMask

CirculateNotify
ConfigureNotify
DestroyNotify
GravityNotify
MapNotify
ReparentNotify
UnmapNotify

XCirculateEvent
XConfigureEvent
XDestroyWindowEvent
XGravityEvent
XMapEvent
XReparent Event
XUnmapEvent

SubstructureNotifyMask

CirculateNotify
ConfigureNotify
CreateNotify
DestroyNotify
GravityNotify
MapNotify
ReparentNotify
UnmapNotify

XCirculateEvent
XConfigureEvent
XCreateWindowEvent
XDestroyWindowEvent
XGravityEvent
XMapEvent
XReparentEvent
XUnmapEvent

Subs tructureRedirect Mask

CirculateRequest
Conf igureRequest
MapRequest

XCirculateRequestEvent
XConf igureRequestEvent
XMapRequest Event

(always selected)

MappingNotify

XMappingEvent

(always selected)

ClientMessage

XClientMessageEvent

(always selected)

SelectionClear

XSetSelectClearEvent

(always selected)

SelectionNotify

XSelectionEvent

(always selected)

Select ionRequest

XSelectionRequestEvent

600

Xlib Reference Manual

E.1 Meaning of Common Structure Elements

Example E-l shows the XEvent union and a simple event structure that is one member of
the union. Several of the members of this structure are present in nearly every event struc
ture. They are described here before we go into the event-specific members (see also Sec
tion 8.2.2 of Volume One, Xlib Programming Manual).

Example E-1. XEvent union and XAnyEvent structure

typedef union _XEvent {

int type;

XAnyEvent xany;

XButtonEvent xbutton;

XCirculateEvent xcirculate;

XCirculateRequestEvent xcirculaterequest;

XClientMessageEvent xclient;

XColormapEvent xcolormap;

XConf igureEvent xconfigure;

XConfigureRequestEvent xconf igurerequest;

XCr eat eWindowE vent xcreatewindow;

XDestroyWindowEvent xdestroy window;

XCrossingEvent xcrossing;

XExposeEvent xexpose;

XFocusChangeEvent xfocus;

XNoExposeEvent xnoexpose;

XGraphicsExposeE vent xgraphicsexpose ;

XGravityEvent xgravity;

XKeymapEvent xkeymap;

XKeyEvent xkey;

XMapEvent xmap;

XUnmapEvent xunmap;

XMappingEvent xmapping;

XMapRequestEvent xmaprequest;

XMotionEvent xmotion;

XPropertyEvent xproperty;

XReparentEvent xreparent;

XResizeRequest Event xresizerequest ;

XSelectionClearEvent xselectionclear;

XSelectionEvent xselection;

XSelectionRequest Event xselectionrequest ;

XVisibilityEvent xvisibility;
} XEvent;

typedef struct {
int type;

unsigned long serial;
Bool send_event;

Display *display;
Window window;

} XAnyEvent ;

/* Must not be changed; first member */

/* # of last request processed by server */

/* True if this came from SendEvent

* request */

/* Display the event was read from */

/* window on which event was requested

* in event mask */

Appendix E: Event Reference

601

The first member of the XEvent union is the type of event When an event is received (with
XNextEvent, for example), the application checks the type member in the XEvent
union. Then the specific event type is known and the specific event structure (such as
xbutton) is used to access information specific to that event type.

Before the branching depending on the event type, only the XEvent union is used. After
the branching, only the event structure which contains the specific information for each event
type should be used in each branch. For example, if the XEvent union were called
report, the report .xexpose structure should be used within the branch for Expose
events.

You will notice that each event structure also begins with a type member. This member is
rarely used, since it is an identical copy of the type member in the XEvent union.

Most event structures also have a window member. The only ones that do not are selection
events (SelectionClear, SelectionNotify, and SelectionRequest) and
events selected by the graphics_exposures member of the GC (GraphicsExpose
and NoExpose). The window member indicates the event window that selected and
received the event This is the window where the event arrives if it has propagated through
the hierarchy as described in Section 8.3.2, of Volume One, Xlib Programming Manual. One
event type may have two different meanings to an application, depending on which window
it appears in.

Many of the event structures also have a display and/or root member. The display
member identifies the connection to the server that is active. The root member indicates
which screen the window that received the event is linked to in the hierarchy. Most programs
only use a single screen and therefore do not need to worry about the root member. The
display member can be useful, since you can pass the display variable into routines by
simply passing a pointer to the event structure, eliminating the need for a separate display
argument

All event structures include a serial member that gives the nur " er of the last protocol
request processed by the server. This is useful in debugging, since an error can be detected
by the server but not reported to the user (or programmer) until the next routine that gets an
event That means several routines may execute successfully after the error occurs. The last
request processed will often indicate the request that contained the error.

All event structures also include a send_event flag, which, if True, indicates that the
event was sent by XSendEvent (i.e., by another client rather than by the server).

The following pages describe each event type in detail. The events are presented in alphabet
ical order, each on a separate page. Each page describes the circumstances under which the
event is generated, the mask used to select it, the structure itself, its members, and useful pro
gramming notes. Note that the description of the structure members does not include those
members common to many structures. If you need more information on these members,
please refer to this introductory section.

602 xiib Reference Manual

xbutton-

ButtonPress, ButtonRelease

When Generated

There are two types of pointer button events: ButtonPress and ButtonRelease. Both
contain the same information.

Select With

May be selected separately, using ButtonPressMask and ButtonReleaseMask.

XEvent Structure Name

typedef union _XEvent {

XButtonEvent xbutton;
} XEvent;

Event Structure

typedef struct {
int type;

unsigned long serial;
Bool send_event;
Display ^display;
Window window;
Window root;
Window subwindow;
Time time;
int x, y;

int x_root, y_root;
unsigned int state;
unsigned int button;
Bool same_screen;
} XButtonEvent;
typedef XButtonEvent
typedef XButtonEvent

/* of event */

/* # of last request processed by server */

/* True if this came from a SendEvent request *

/* Display the event was read from */

/* event window it is reported relative to */

/* root window that the event occurred under */

/* child window */

/* when event occurred, in milliseconds */

/* pointer coordinates relative to receiving

* window */

/* coordinates relative to root */

/* mask of all buttons and modifier keys */

/* button that triggered event */

/* same screen flag */

XButtonPressedEvent;
XButtonReleasedEvent ;

Event Structure Members

subwindow If the source window is the child of the receiving window, then the

subwindow member is set to the ID of that child.

time

The server time when the button event occurred, in milliseconds. Time
is declared as unsigned long, so it wraps around when it reaches the
maximum value of a 32-bit number (every 49.7 days).

If the receiving window is on the same screen as the root window speci
fied by root, then x and y are the pointer coordinates relative to the
receiving window s origin. Otherwise, x and y are zero.

Xlib Reference Manual

603

Button Press, Button Release

(continued)

xbutton

When active button grabs and pointer grabs are in effect (see Section 9.4
of Volume One, Xlib Programming Manual), the coordinates relative to
the receiving window may not be within the window (they may be nega
tive or greater than window height or width).

x root, y_root The pointer coordinates relative to the root window which is an ancestor
of the event window. If the pointer was on a different screen, these are
zero.

state The state of all the buttons and modifier keys just before the event,

represented by a mask of the button and modifier key symbols:

ButtonlMask, Button2Mask, ButtonSMask, Button4Mask,
ButtonSMask, ControlMask, LockMask, ModlMask, Mod2-
Mask, ModSMask, Mod4Mask, ModSMask, and ShiftMask. If a
modifier key is pressed and released when no other modifier keys are
held, the ButtonPress will have a state member of and the
ButtonRelease will have a nonzero state member indicating that
itself was held just before the event

button A value indicating which button changed state to trigger this event One

of the constants: Buttonl, Button2, Buttons, Button4, or
Buttons.

same_screen Indicates whether the pointer is currently on the same screen as this win
dow. This is always True unless the pointer was actively grabbed
before the automatic grab could take place.

Notes

Unless an active grab already exists or a passive grab on the button combination that was
pressed already exists at a higher level in the hierarchy than where the ButtonPress
occurred, an automatic active grab of the pointer takes place when a ButtonPress occurs.
Because of the automatic grab, the matching ButtonRelease is sent to the same application
that received the ButtonPress event If OwnerGrabButtonMask has been selected, the
ButtonRelease event is delivered to the window which contained the pointer when the
button was released, as long as that window belongs to the same client as the window in which
the ButtonPress event occurred. If the ButtonRelease occurs outside of the client s
windows or OwnerGrabButtonMask was not selected, the ButtonRelease is delivered
to the window in which the ButtonPress occurred. The grab is terminated when all buttons
are released. During the grab, the cursor associated with the grabbing window will track the
pointer anywhere on the screen.

If the application has invoked a passive button grab on an ancestor of the window in which the
ButtonPress event occurs, then that grab takes precedence over the automatic grab, and the
ButtonRelease will go to that window, or it will be handled normally by that client depend
ing on the owner_events flag in the XGrabButton call.

604

Xlib Reference Manual

xcirculate-

CirculateNotify

When Generated

A CirculateNotify event reports a call to change the stacking order, and it includes
whether the final position is on the top or on the bottom. This event is generated by

XCirculateSubwindows, XCirculateSubwindowsDown, or XCirculate-
SubwindowsUp. See also the CirculateRequest and Conf igureNotify reference
pages.

Select With

This event is selected with StructureNotifyMask in the XSelectlnput call for the
window to be moved or with SubstructureNotif yMask for the parent of the window to
be moved.

XEvent Structure Name

typedef union _XEvent {
. . .

XCirculateEvent xcirculate;

} XEvent;

Event Structure

typedef struct {

int type;

unsigned long serial,

Bool send_event;

Display *display;

Window event;

Window window;

int place;
} XCirculateEvent;

/* # of last request processed by server */
/* True if this came from SendEvent request
/* Display the event was read from */

/* PlaceOnTop, PlaceOnBottom */

Event Structure Members

event The window receiving the event If the event was selected by Structure

NotifyMask, event will be the same as window. If the event was selected
by SubstructureNotif yMask, event will be the parent of window.

window The window that was restacked.

place Either PlaceOnTop or PlaceOnBottom. Indicates whether the window was

raised to the top or bottom of the stack.

Xlib Reference Manual

605

CirculateRequest \

xcirculaterequest

When Generated

A CirculateRequest event reports when XCirculateSubwindows, XCirculate-
SubwindowsDown, XCirculateSubwindowsUp, or XRestackWindows is called to
change the stacking order of a group of children.

This event differs from CirculateNotif y in that it delivers the parameters of the request
before it is carried out This gives the client that selects this event (usually the window man
ager) the opportunity to review the request in the light of its window management policy before
executing the circulate request itself or to deny the request (CirculateNotify indicates
the final outcome of the request)

Select With

This event is selected for the parent window with SubstructureRedirectMask.

XEvent Structure Name

typedef union _XEvent {

XCirculateRequestEvent xcirculaterequest ;
} XEvent;

Event Structure

typedef struct {

int type;

unsigned long serial; /* # of last request processed by server */

Bool send_event; /* True if this came from SendEvent request */

Display ^display; /* Display the event was read from */

Window parent;

Window window;

int place; /* PlaceOnTop, PlaceOnBottom */

} XCirculateRequestEvent;

Event Structure Members

parent The parent of the window that was restacked. This is the window that selected
the event

window The window being restacked.

place PlaceOnTop or PlaceOnBottom. Indicates whether the window was to be

placed on the top or on the bottom of the stacking order.

Xlib Reference Manual

xclient-

J ClientMessage

When Generated

A ClientMessage event is sent as a result of a call to XSendEvent by a client to a particu
lar window. Any type of event can be sent with XSendEvent, but it will be distinguished
from normal events by the send_event member being set to True. If your program wants to
be able to treat events sent with XSendEvent as different from normal events, you can read
this member.

Select With

There is no event mask for ClientMessage events, and they are not selected with
XSelect Input. Instead XSendEvent directs them to a specific window, which is given as
a window ID: the PointerWindow or the inputFocus.

XEvent Structure Name

typedef union _XEvent {

XClientMessageEvent xclient;
} XEvent;

Event Structure

typedef struct {
int type;

unsigned long serial; /* # of last request processed by server */
Bool send_event; /* True if this came from SendEvent request */
Display ^display; /* Display the event was read from */
Window window;
Atom message_type;
int format;
union {

char b[20];

short s[10] ;

long 1[5];
} data;
} XClientMessageEvent;

Event Structure Members

message_type An atom that specifies how the data is to be interpreted by the receiving
client. The X server places no interpretation on the type or the data, but
it must be a list of 8-bit, 16-bit, or 32-bit quantities, so that the X server
can correctly swap bytes as necessary. The data always consists of
twenty 8-bit values, ten 16-bit values, or five 32-bit values, although
each particular message might not make use of all of these values.

format Specifies the format of the property specified by message_type. This

will be on of the values 8, 1 6, or 32.

Xlib Reference Manual 607

ColormapNotify

xcolormap

When Generated

A ColormapNotify event reports when the colormap attribute of a window changes or
when the colormap specified by the attribute is installed, uninstalled, or freed. This event is
generated by XChangeWindowAttributes, XFreeColormap, XInstallColormap,
and XUninstallColormap.

Select With

This event is selected with ColormapChangeMask.

XEvent Structure Name

typedef union _XEvent {

XColormapEvent xcolormap;
} XEvent;

Event Structure

typedef struct {

int type;

unsigned long serial,

Bool send_event;

Display ^display;

Window window;

Colormap colormap;

Bool new;

int state;
} XColormapEvent;

# of last request processed by server */
True if this came from SendEvent request */
Display the event was read from */

a colormap or None */

Colormaplnstalled, ColormapUninstalled */

Event Structure Members

window The window whose associated colormap or attribute changes.

colormap The colormap associated with the window, either a colormap ID or the constant
None. It will be None only if this event was generated due to an XFree
Colormap call.

new True when the colormap attribute has been changed, or False when the color-

map is installed or uninstalled.

state Either Colormaplnstalled or ColormapUninstalled; it indicates

whether the colormap is installed or uninstalled.

Xlib Reference Manual

xconfigure-

ConfigureNotify

When Generated

A ConfigureNotify event announces actual changes to a window s configuration (size,
position, border, and stacking order). See also the CirculateRequest reference page.

Select With

This event is selected for a single window by specifying the window ID of that window with
StructureNotif yMask. To receive this event for all children of a window, specify the
parent window ID with SubstructureNotif yMask.

XEvent Structure Name

typedef union _XEvent {

XConf igureEvent xconfigure;
} XEvent;

Event Structure

typedef struct {

int type;

unsigned long serial

Bool send_event;

Display *display;

Window event;

Window window;

int x, y;

int width, height;

int border_width;

Window above;

Bool override_redirect;
} XConf igureEvent;

/* # of last request processed by server */
/* True if this came from SendEvent request
/* Display the event was read from */

Event Structure Members

event

window

width, height
border_width
above

The window that selected the event The event and window
members are identical if the event was selected with Structure-
Not if yMask.

The window whose configuration was changed.

The final coordinates of the reconfigured window relative to its par
ent.

The width and height in pixels of the window after reconfiguration.
The width in pixels of the border after reconfiguration.

If this member is None, then the window is on the bottom of the
stack with respect to its siblings. Otherwise, the window is immedi
ately on top of the specified sibling window.

Xlib Reference Manual

609

ConfigureNotify (continued) xconflgure

override_redirect The override_redirect attribute of the reconfigured window.
If True, it indicates that the client wants this window to be immune
to interception by the window manager of configuration requests.
Window managers normally should ignore this event if

override redirect is True.

610 Xlib Reference Manual

xconf igurerequest-

ConfigureRequest

When Generated

A ConfigureRequest event reports when another client attempts to change a window s
size, position, border, and/or stacking order.

This event differs from Conf igureNotif y in that it delivers the parameters of the request
before it is carried out This gives the client that selects this event (usually the window man
ager) the opportunity to revise the requested configuration before executing the
XConf igureWindow request itself or to deny the request (Conf igureNotif y indicates
the final outcome of the request)

Select With

This event is selected for any window in a group of children by specifying the parent window
with SubstructureRedirectMask.

XEvent Structure Name

typedef union _XEvent {

XConf igureRequestEvent xconf igurerequest ;
} XEvent;

Event Structure

typedef struct {

int type;

unsigned long serial

Bool send_event;

Display *display;

Window parent;

Window window;

int x, y;

int width, height;

int border_width;

Window above;

int detail;

unsigned long value_mask
} XConf igureRequestEvent;

# of last request processed by server */
True if this came from SendEvent request
Display the event was read from */

/* Above, Below, Bottomlf, Toplf, Opposite */

Event Structure Members

parent The window that selected the event This is the parent of the window

being configured.

window The window that is being configured.

x, y The requested position for the upper-left pixel of the window s border

relative to the origin of the parent window.

width, height The requested width and height in pixels for the window.

Xlib Reference Manual

611

ConfigureRequest

(continued)

xconfigurerequest

border_width The requested border width for the window.

above None, Above, Below, Toplf , Bottomlf , or Opposite. Specifies

the sibling window on top of which the specified window should be
placed. If this member has the constant None, then the specified win
dow should be placed on the bottom.

Notes

The geometry is derived from the XConf igurewindow request that triggered the event.

612

Xlib Reference Manual

xcreatewindow-

CreateNotify

When Generated

A CreateNotify event reports when a window is created.

Select With

This event is selected on children of a window by specifying the parent window ID with
SubstructureNotifyMask. (Note that this event type cannot be selected by

StructureNotifyMask.)

XEvent Structure Name

typedef union _XEvent {

XCreateWindowEvent xcreatewindow;
} XEvent;

Event Structure

typedef struct {
int type;

unsigned long serial; /
Bool send_event; /

Display ^display; /
Window parent;

Window window; /

int x, y; /

int width, height; /

int border_width; /
Bool override_redirect; /
} XCreateWindowEvent;

# of last request processed by server */
True if this came from SendEvent
request */

Display the event was read from */
/* parent of the window */

window ID of window created */

window location */

size of window */

border width */

creation should be overridden */

Event Structure Members

parent
window
x,y

width, height
border_width
override redirect

The ID of the created window s parent

The ID of the created window.

The coordinates of the created window relative to its parent

The width and height in pixels of the created window.

The width in pixels of the border of the created window.

The override_redirect attribute of the created window. If
True, it indicates that the client wants this window to be immune
to interception by the window manager of configuration requests,
managers normally should ignore this event if

Window

override

redirect is True.

Xlib Reference Manual

613

CreateNotify (continued) xcreatewlndow

Notes

For descriptions of these members, see the XCreateWindow function and the XSet-
WindowAttributes structure.

614 Xlib Reference Manual

xdestroywindow

DestroyNotify

When Generated

A DestroyNotify event reports that a window has been destroyed.

Select With

To receive this event type on children of a window, specify the parent window ID and pass
SubstructureNotifyMask as part of the event_mask argument to XSelect Input.
This event type cannot be selected with StructureNotif yMask.

XEvent Structure Name

typedef union _XEvent {

XDestroyWindowEvent xdestroywindow;
} XEvent;

Event Structure

typedef struct {

int type;

unsigned long serial,

Bool send_event;

Display ^display;

Window event;

Window window;
} XDestroyWindowEvent;

/* # of last request processed by server */
/* True if this came from SendEvent request */
/* Display the event was read from */

Event Structure Members

event The window that selected the event

window The window that was destroyed.

Xlib Reference Manual

615

EnterNotify, LeaveNotify \

When Generated

EnterNotify and LeaveNotify events occur when the pointer enters or leaves a window.

When the pointer crosses a window border, a LeaveNotify event occurs in the window
being left and an EnterNotify event occurs in the window being entered. Whether or not
each event is queued for any application depends on whether any application selected the right
event on the window in which it occurred.

In addition, EnterNotify and LeaveNotify events are delivered to windows that are
virtually crossed. These are windows that are between the origin and destination windows in
the hierarchy but not necessarily on the screen. Further explanation of virtual crossing is pro
vided two pages following.

Select With

Each of these events can be selected separately with XEnterWindowMask and XLeave-
WindowMask.

XEvent Structure Name

typedef union _XEvent {

XCrossingEvent xcrossing;
} XEvent;

Event Structure

typedef struct {

int type; /* of event */

unsigned long serial; /* # of last request processed by server */

Bool send_event; /* True if this came from SendEvent request */

Display *display; /* Display the event was read from */

Window window; /* event window it is reported relative to */

Window root; /* root window that the event occurred on */

Window subwindow; /* child window */

Time time; /* milliseconds */

int x, y; /* pointer x,y coordinates in receiving

* window */

int x_root, y_root; /* coordinates relative to root */

int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab */

int detail; /* NotifyAncestor, Notifylnferior,

* NotifyNonLinear, NotifyNonLinearVirtual,

* NotifyVirtual */

Bool same_screen; /* same screen flag */
Bool focus; /* boolean focus */

unsigned int state; /* key or button mask */

} XCrossingEvent;

typedef XCrossingEvent XEnterWindowEvent;

typedef XCrossingEvent XLeaveWindowEvent;

616 Xlib Reference Manual

xcrossing

(continued)

EnterNotify, LeaveNotify

Event Structure Members

The following list describes the members of the XGrossingEvent structure.

subwindow In a LeaveNotify event, if the pointer began in a child of the receiv

ing window, then the child member is set to the window ID of the
child. Otherwise, it is set to None. For an EnterNotify event, if the
pointer ends up in a child of the receiving window, then the child
member is set to the window ID of the child. Otherwise, it is set to
None.

time

The server time when the crossing event occurred, in milliseconds.
Time is declared as unsigned long, so it wraps around when it
reaches the maximum value of a 32-bit number (every 49.7 days).

x, y The point of entry or exit of the pointer relative to the event window.

x_root , y_root The point of entry or exit of the pointer relative to the root window.

mode Normal crossing events or those caused by pointer warps have mode

NotifyNormal, events caused by a grab have mode NotifyGrab,
and events caused by a released grab have mode Not if yUngrab.

detail The value of the detail member depends on the hierarchical relation

ship between the origin and destination windows and the direction of
pointer transfer. Determining which windows receive events and with
which detail members is quite complicated. This topic is described in
the next section.

same_screen Indicates whether the pointer is currently on the same screen as this win
dow. This is always True unless the pointer was actively grabbed
before the automatic grab could take place.

focus If the receiving window is the focus window or a descendant of the focus

window, the focus member is True; otherwise, it is False.

state The state of all the buttons and modifier keys just before the event,

represented by a mask of the button and modifier key symbols:

ButtonlMask, Button2Mask, ButtonSMask, Button4Mask,
ButtonSMask, ControlMask, LockMask, ModlMask, Mod2-
Mask, ModSMask, Mod4Mask, ModSMask, and Shif tMask.

Virtual Crossing and the detail Member

Virtual crossing occurs when the pointer moves between two windows that do not have a
parent-child relationship. Windows between the origin and destination windows in the hierar
chy receive EnterNotify and LeaveNotify events. The detail member of each of
these events depends on the hierarchical relationship of the origin and destination windows and
the direction of pointer transfer.

Xlib Reference Manual

617

EnterNotify, LeaveNotify (continued) xcrossing

Virtual crossing is an advanced topic that you should not spend time figuring out unless you
have an important reason to use it We have never seen an application that uses this feature,
and we know of no reason for its extreme complexity. With that word of warning, proceed.

Let s say the pointer has moved from one window, the origin, to another, the destination. First,
we ll specify what types of events each window gets and then the detail member of each of
those events.

The window of origin receives a LeaveNotify event and the destination window receives an
EnterNotify event, if they have requested this type of event If one is an inferior of the
other, the detail member of the event received by the inferior is Notif yAncestor and the
detail of the event received by the superior is Notif y inferior. If the crossing is between
parent and child, these are the only events generated.

However, if the origin and destination windows are not parent and child, other windows are
virtually crossed and also receive events. If neither window is an ancestor of the other,
ancestors of each window, up to but not including the least common ancestor, receive Leave-
Notif y events, if they are in the same branch of the hierarchy as the origin, and Enter-
Notify events, if they are in the same branch as the destination. These events can be used to
track the motion of the pointer through the hierarchy.

In the case of a crossing between a parent and a child of a child, the middle child receives a

LeaveNotify with detail Notif yVirtual.

In the case of a crossing between a child and the parent of its parent, the middle child
receives an EnterNotify with detail Notif yVirtual.

In a crossing between windows whose least common ancestor is two or more windows
away, both the origin and destination windows receive events with detail Not if y-
Nonlinear. The windows between the origin and the destination in the hierarchy, up to
but not including their least common ancestor, receive events with detail Not if y-
NonlinearVirtual. The least common ancestor is the lowest window from which both
are descendants.

If the origin and destination windows are on separate screens, the events and details gen
erated are the same as for two windows not parent and child, except that the root windows
of the two screens are considered the least common ancestor. Both root windows also
receive events.

6 18 Xlib Reference Manual

xcrossing

(continued)

EnterNotify, LeaveNotify

Table E-l shows the event types generated by a pointer crossing from window A to window B
when window C is the least common ancestor of A and B.

Table E-1. Border Crossing Events and Window Relationship

LeaveNotify

Origin window (A)

Windows between A and B,
exclusive, if A is inferior

Windows between A and C,
exclusive

Root window on screen of
origin if different from
screen of destination

EnterNotify

Destination window (5)

Windows between A and B, exclusive, if B is inferior

Windows between B and C, exclusive,

Root window on screen of destination if different
from screen of origin

Table E-2 lists the detail members in events generated by a pointer crossing from window A
to window B.

Table E-2. Event detail Member and Window Relationship
de t a i 1 Rag Window Delivered To

NotifyAncestor
Notify Inferior
NotifyVirtual

NotifyNonlinear
NotifyNonlinearVirtual

Origin or destination when either is descendant
Origin or destination when either is ancestor

Windows between A and B, exclusive, if either is
descendant

Origin and destination when A and B are two or more
windows distant from least common ancestor C

Windows between A and C, exclusive, and between
B and C, exclusive, when A and B have least common
ancestor C; also on both root windows if A and B are
on different screens

Xlib Reference Manual

619

EnterNotify, LeaveNotify

(continued)

xcrossing

For example, Figure E-l shows the events that are generated by a movement from a window
(window A) to a child (window Bl) of a sibling (window B). This would generate three events:
a LeaveNotify with detail Notif yNonlinear for the window A, an EnterNotify with
detail Notif yNonlinearVirtual for its sibling window 5, and an EnterNotify with
detail Notif yNonlinear for the child (window Bl).

Root Window

(no event)

I I

~~l

LeaveNotify event with detail

Not if yNonlinear

EnterNotify event with detail

Not if yNonlinearVirtual

no event

EnterNc
Notify!

3tify event with detail

Nonlinear

Figure E-1. Events generated by a move between windows

EnterNotify and LeaveNotify events are also generated when the pointer is grabbed, if
the pointer was not already inside the grabbing window. In this case, the grabbing window
receives an EnterNotify and the window containing the pointer receives a LeaveNotify
event, both with mode Notif yUngrab. The pointer position in both events is the position
before the grab. The result when the grab is released is exactly the same, except that the two
windows receive EnterNotify instead of LeaveNotify and vice versa.

620

Xlib Reference Manual

xcrossing

(continued)

EnterNotify, Leave Notify

Figure E-2 demonstrates the events and details caused by various pointer transitions, indicated
by heavy arrows.

LeaveNotify
Ancestor

Figure E-2. Border crossing events and detail member for pointer movement from
window A to window B, for various window relationships

Xlib Reference Manual

621

Expose X

x ex pose

When Generated

An Expose event is generated when a window becomes visible or a previously invisible part
of a window becomes visible. Only inputOutput windows generate or need to respond to
Expose events; inputOnly windows never generate or need to respond to them. The
Expose event provides the position and size of the exposed area within the window and a
rough count of the number of remaining exposure events for the current window.

Select With

This event is selected with ExposureMask.

XEvent Structure Name

typedef union _XEvent {

XExposeEvent xexpose;
} XEvent;

Event Structure

typedef struct {

int type;

unsigned long serial; /* # of last request processed by server */

Bool send_event; /* True if this came from SendEvent request */

Display ^display; /* Display the event was read from */

Window window;

int x, y;

int width, height;

int count; /* If nonzero, at least this many more */

} XExposeEvent;

Event Structure Members

x, y The coordinates of the upper-left corner of the exposed region relative to

the origin of the window.

width, height The width and height in pixels of the exposed region.

count The approximate number of remaining contiguous Expose events that

were generated as a result of a single function call.

Notes

A single action such as a window movement or a function call can generate several exposure
events on one window or on several windows. The server guarantees that all exposure events
generated from a single action will be sent contiguously, so that they can all be handled before
moving on to other event types. This allows an application to keep track of the rectangles
specified in contiguous Expose events, set the clip_mask in a GC to the areas specified in

622 Xlib Reference Manual

xexpose (continued) Expose

the rectangle using XSetRegion or XSetClipRectangles, and then finally redraw the
window clipped with the GC in a single operation after all the Expose events have arrived.
The last event to arrive is indicated by a count of 0. In Release 2, XUnionRectwith-
Region can be used to add the rectangle in Expose events to a region before calling XSet
Region.

If your application is able to redraw partial windows, you can also read each exposure event in
turn and redraw each area.

Xlib Reference Manual 623

Focusln, FocusOut \

xfocus

When Generated

Focusln and FocusOut events occur when the keyboard focus window changes as a result
of an XSetlnputFocus call. They are much like EnterNotify and LeaveNotify
events except that they track the focus rather than the pointer.

When a focus change occurs, a FocusOut event is delivered to the old focus window and a
Focusln event to the window which receives the focus. In addition, windows in between
these two windows in the window hierarchy are virtually crossed and receive focus change
events, as described below. Some or all of the windows between the window containing the
pointer at the time of the focus change and the root window also receive focus change events,
as described below.

Select With

Focusln and FocusOut events are selected with FocusChangeMask. They cannot be
selected separately.

XEvent Structure Name

typedef union _XEvent {

XFocusChangeEvent xfocus;
(...
} XEvent;

Event Structure

typedef struct {

int type; /* Focusln or FocusOut */

unsigned long serial; /* # of last request processed by server */

Bool send_event; /* True if this came from SendEvent request */

Display ^display; /* Display the event was read from */

Window window; /* Window of event */

int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab */

int detail; /* NotifyAncestor, NotifyDetailNone,

* Notifylnferior, NotifyNonLinear,

* NotifyNonLinearVirtual, NotifyPointer,

* NotifyPointerRoot, NotifyVirtuaW
} XFocusChangeEvent;

typedef XFocusChangeEvent XFocusInEvent;
typedef XFocusChangeEvent XFocusOutEvent;

Event Structure Members

mode For events generated when the keyboard is not grabbed, mode is Notify

Normal; when the keyboard is grabbed, mode is NotifyGrab; and when a
keyboard is ungrabbed, mode is NotifyUngrab.

detail The detail member identifies the relationship between the window that
receives the event and the origin and destination windows. It will be described
in detail after the description of which windows get what types of events.

624

Xlib Reference Manual

xfocus (continued) Focusln, FocusOut

Notes

The keyboard focus is a window that has been designated as the one to receive all keyboard
input irrespective of the pointer position. Only the keyboard focus window and its descendants
receive keyboard events. By default, the focus window is the root window. Since all windows
are descendants of the root, the pointer controls the window that receives input.

Most window managers allow the user to set a focus window to avoid the problem where the
pointer sometimes gets bumped into the wrong window and your typing does not go to the
intended window. If the pointer is pointing at the root window, all typing is usually lost, since
there is no application for this input to propagate to. Some applications may set the keyboard
focus so that they can get all keyboard input for a given period of time, but this practice is not
encouraged.

Focus events are used when an application wants to act differently when the keyboard focus is
set to another window or to itself. Focus ChangeMask is used to select Focusln and
FocusOut events.

When a focus change occurs, a FocusOut event is delivered to the old focus window and a
Focusln event is delivered to the window which receives the focus. Windows in between in
the hierarchy are virtually crossed and receive one focus change event each depending on the
relationship and direction of transfer between the origin and destination windows. Some or all
of the windows between the window containing the pointer at the time of the focus change and
that window s root window can also receive focus change events. By checking the detail
member of Focusln and FocusOut events, an application can tell which of its windows can
receive input.

The detail member gives clues about the relationship of the event receiving window to the
origin and destination of the focus. The detail member of Focus in and FocusOut events
is analogous to the detail member of EnterNotif y and LeaveNotif y events but with
even more permutations to make life complicated.

Virtual Focus Crossing and the detail Member

We will now embark on specifying the types of events sent to each window and the detail
member in each event, depending on the relative position in the hierarchy of the origin window
(old focus), destination window (new focus), and the pointer window (window containing
pointer at time of focus change). Don t even try to figure this out unless you have to.

Xlib Reference Manual 625

Focusln, FocusOut

(continued)

xfocus

Table E-3 shows the event types generated by a focus transition from window A to window B
when window C is the least common ancestor of A and B. This table includes most of the
events generated, but not all of them. It is quite possible for a single window to receive more
than one focus change event from a single focus change.

Table E-3. Focusln and FocusOut Events and Window Relationship

FocusOut

Origin window (A)

Windows between A and 5,
exclusive, if A is inferior

Windows between A and C,
exclusive

Root window on screen of
origin if different from
screen of destination

Pointer window up to but
not including origin window
if pointer window is descen
dant of origin

Pointer window up to and
including pointer window s
root if transfer was from

PointerRoot

Focusln

Destination window (B)

Windows between A and 5, exclusive, if B is inferior

Windows between B and C, exclusive

Root window on screen of destination if different
from screen of origin

Pointer window up to but not including destination
window if pointer window is descendant of destina
tion

Pointer window up to and including pointer win
dow s root if transfer was to PointerRoot

Xlib Reference Manual

xfocus

(continued)

Focusln, FocusOut

Table E-4 lists the detail members in events generated by a focus transition from window A
to window B when window C is the least common ancestor of A and B, with P being the win
dow containing the pointer.

Table E-4. Event detail Member and Window Relationship

detail Flag

NotifyAncestor
Notifylnferior
NotifyVirtual

NotifyNonlinear
NotifyNonlinearVirtual

NotifyPointer
NotifyPointerRoot

NotifyDetailNone

Window Deli vered To

Origin or destination when either is descendant
Origin or destination when either is ancestor

Windows between A and B, exclusive, if either is
descendant

Origin and destination when A and B are two or more
windows distant from least common ancestor C

Windows between A and C, exclusive, and between
B and C, exclusive, when A and B have least common
ancestor C; also on both root windows if A and B are
on different screens

Window P and windows up to but not including the
origin or destination windows

Window P and all windows up to its root, and all
other roots, when focus is set to or from Pointer-
Root

All roots, when focus is set to or from None

Figure E-3 shows all the possible combinations of focus transitions and of origin, destination,
and pointer windows and shows the types of events that are generated and their detail mem
ber. Solid lines indicate branches of the hierarchy. Dotted arrows indicate the direction of
transition of the focus. At each end of this arrow are the origin and destination windows, win
dows A to B. Arrows ending in a bar indicate that the event type and detail described are
delivered to all windows up to the bar.

In any branch, there may be windows that are not shown. Windows in a single branch between
two boxes shown will get the event types and details shown beside the branch.

Xlib Reference Manual

627

Focusln, FocusOut

(continued)

xfocus

LeaveNotify,

If window P is between A
and B, windows from P up
to but not including B get
FOCUS in with detail

Notifylnterior

FocusOut,

Nonlinear-Virtual

Roots of other Screens:
FOCUS:.-, with Detail :;or.f

Root Window

FOCUS: None

FocusOut,

Figure E-3. Focusln and FocusOut event schematics

628

Xlib Reference Manual

xfocus

(continued)

Focusln, FocusOut

Roots of other Screens:
isOut with Detail PointerRoot

Focus:

PointerP.cot I

Roots of other Screens:

"ocusGut with Detail ; n&lt;

Root Window
FOCUS: Kone

Focus change from PointerRoot to :

All Root Windows:
2ui with Detail E int erF

Pointer s
Root Window

1 _J

Focus change from PointerRoot to ::.:.

All Root Windows:
: - with Detail No.

Pointer s
Root Window

Figure E-3. Focusln and FocusOut event schematics (cont.)

Focusln and FocusOut events are also generated when the keyboard is grabbed, if the focus
was not already assigned to the grabbing window. In this case, all windows receive events as if
the focus was set from the current focus to the grab window. When the grab is released, the
events generated are just as if the focus was set back.

Xlib Reference Manual

629

GraphicsExpose, NoExpose \

xnoexpose

When Generated

GraphicsExpose events indicate that the source area for a XCopyArea or XCopyPlane
request was not available because it was outside the source window or obscured by a window.
NoExpose events indicate that the source region was completely available.

Select With

These events are not selected with xselect Input but are sent if the GC in the XCopyArea
or XCopyPlane request had its graphics_exposures flag set to True. If
graphics_exposures is True in the GC used for the copy, either one NoExpose event
or one or more GraphicsExpose events will be generated for every XCopyArea or
XCopyPlane call made.

XEvent Structure Name

typedef union _XEvent {

XNoExposeEvent xnoexpose;
XGraphicsExposeEvent xgraphicsexpose ;

} XEvent;

Event Structure

typedef struct {

int type;

unsigned long serial,

Bool send_event;

Display *display;

Drawable drawable;

int x, y;

int width, height;

int count;

int major_code;

int minor_code;
} XGraphicsExposeEvent;

typedef struct {

int type;

unsigned long serial;

Bool send_event;

Display *display;

Drawable drawable;

int ma jor_code;

int minor_code;
} XNoExposeEvent;

/* # of last request processed by server */
/* True if this came from SendEvent request
/* Display the event was read from */

/* if nonzero, at least this many more */
/* core is CopyArea or CopyPlane */
/* not defined in the core */

/* # of last request processed by server */
/* True if this came from SendEvent request */
/* Display the event was read from */

/* core is CopyArea or CopyPlane */
/* not defined in the core */

Xlib Reference Manual

(continued)

GraphicsExpose, NoExpose

xnoexpose

Event Structure Members

drawable A window or an off-screen pixmap. This specifies the destination of the

graphics request that generated the event

x, y The coordinates of the upper-left corner of the exposed region relative to

the origin of the window.

width, height The width and height in pixels of the exposed region.

count The approximate number of remaining contiguous GraphicsExpose

events that were generated as a result of the xcopyArea or XGopy-
P lane call.

ma jor_code The graphics request used. This may be one of the symbols CopyArea

or CopyPlane or a symbol defined by a loaded extension.

minor_code Zero unless the request is part of an extension.

Notes

Expose events and GraphicsExpose events both indicate the region of a window that was
actually exposed (x, y, width, and height). Therefore, they can often be handled similarly.

Xlib Reference Manual

631

GravityNotify \

xgravity

When Generated

A GravityNotify event reports when a window is moved because of a change in the size of
its parent This happens when the win_gravity attribute of the child window is something
other than StaticGravity or UnmapGravity.

Select With

This event is selected for a single window by specifying the window ID of that window with
St ructureNotif yMask. To receive notification of movement due to gravity for a group of
siblings, specify the parent window ID with SubstructureNotif yMask.

XEvent Structure Name

typedef union _XEvent {

XGravityEvent xgravity;
} XEvent;

Event Structure

typedef struct {

int type;

unsigned long serial; /* # of last request processed by server */

Bool send_event; /* True if this came from SendEvent request */

Display *display; /* Display the event was read from */

Window event;

Window window;

int x, y;
} XGravityEvent;

Event Structure Members

event The window that selected the event

window The window that was moved.

x, y The new coordinates of the window relative to its parent

632

Xlib Reference Manual

xkeymap-

KeymapNotify

When Generated

A KeymapNotify event reports the state of the keyboard and occurs when the pointer or
keyboard focus enters a window. KeymapNotify events are reported immediately after
EnterNotify or Focusln events. This is a way for the application to read the keyboard
state as the application is "woken up," since the two triggering events usually indicate that the
application is about to receive user input.

Select With

This event is selected with KeymapStateMask.

XEvent Structure Name

typedef union _XEvent {

XKeymapEvent xkeymap;
} XEvent;

Event Structure

typedef struct {

int type;

unsigned long serial,

Bool send_event;

Display *display;

Window window;

char key_vector[32] ;
} XKeymapEvent;

/* # of last request processed by server */
/* True if this came from SendEvent request */
/* Display the event was read from */

Event Structure Members

window Reports the window which was reported in the window member of the pre

ceding EnterNotify or Focusln event

key_vector A bit vector or mask, each bit representing one physical key, with a total of
256 bits. For a given key, its keycode is its position in the keyboard vector.
You can also get this bit vector by calling XQueryKeymap.

Notes

The serial member of KeymapNotify does not contain the serial number of the most
recent protocol request processed, because this event always follows immediately after
EnterNotify or Focusln events in which the serial member is valid.

Xlib Reference Manual

633

KeyPress, KeyRelease

xkey

When Generated

KeyPress and KeyRelease events are generated for all keys, even those mapped to
modifier keys such as Shift or Control.

Select With

Each type of keyboard event may be selected separately with KeyPressMask and Key-
ReleaseMask.

XEvent Structure Name

typedef union _XEvent {

XKeyEvent xkey;
} XEvent;

Event Structure

typedef struct {
int type;

unsigned long serial,
Bool send_event;
Display *display;
Window window;
Window root;
Window subwindow;
Time time;
int x, y;

int x_root, y_root;

unsigned int state;

unsigned int keycode;

Bool same_screen;
} XKeyEvent;

typedef XKeyEvent XKeyPressedEvent;
typedef XKeyEvent XKeyReleasedEvent;

/* of event */

/* # of last request processed by server */

/* True if this came from SendEvent request */

/* Display the event was read from */

/* event window it is reported relative to */

/* root window that the event occurred on */

/* child window */

/* milliseconds */

/* pointer coordinates relative to receiving

* window */

/* coordinates relative to root */

/* modifier key and button mask */

/* server-dependent code for key */

/* same screen flag */

Event Structure Members

subwindow If the source window is the child of the receiving window, then the

subwindow member is set to the ID of that child.

time

x,y

The server time when the button event occurred, in milliseconds. Time
is declared as unsigned long, so it wraps around when it reaches the
maximum value of a 32-bit number (every 49.7 days).

If the receiving window is on the same screen as the root window speci
fied by root, then x and y are the pointer coordinates relative to the
receiving window s origin. Otherwise, x and y are zero.

634

Xlib Reference Manual

xkey

(continued)

KeyPress, KeyRelease

xjcoot, y_root The pointer coordinates relative to the root window which is an ancestor
of the event window. If the pointer was on a different screen, these ?~e
zero.

state The state of all the buttons and modifier keys just before the event,

represented by a mask of the button and modifier key symbols:

ButtonlMask, Button2Mask, ButtonSMask, Button4Mask,
ButtonSMask, ControlMask, LockMask, ModlMask, Mod2-
Mask, ModSMask, Mod4Mask, ModSMask, and Shif tMask.

keycode The keycode member contains a server-dependent code for the key that

changed state. As such, it should be translated into the portable symbol
called a keysym before being used. It can also be converted directly into
ASCII with XLookupString. For a description and examples of how
to translate keycodes, see Volume One, Section 9.1.1.

Notes

Remember that not all hardware is capable of generating release events and that only the main
keyboard (a-z, A-Z, 0-9), Shift, and Control keys are always found.

Keyboard events are analogous to button events, though, of course, there are many more keys
than buttons and the keyboard is not automatically grabbed between press and release.

All the structure members have the same meaning as described for ButtonPress and
ButtonRelease events, except that button is replaced by keycode.

Xlib Reference Manual

635

MapNotlfy, UnmapNotify

xmap, xunmap

When Generated

The X server generates MapNotif y and UnmapNotify events when a window changes state
from unmapped to mapped or vice versa.

Select With

To receive these events on a single window, use StructureNotifyMask in the call to
XSelect Input for the window. To receive these events for all children of a particular
parent, specify the parent window ID and use SubstructureNotif yMask.

XEvent Structure Name

typedef union _XEvent {

XMapEvent xmap;
XUnmapEvent xunmap;

} XEvent;

Event Structure

typedef struct {

int type;

unsigned long serial;

Bool send_event;

Display *display;

Window event;

Window window;

Bool override_redirect,
} XMapEvent;

typedef struct {

int type;

unsigned long serial;

Bool send_event;

Display *display;

Window event;

Window window;

Bool from_conf igure;
} XUnmapEvent;

/* # of last request processed by server */
/* True if this came from SendEvent request */
/* Display the event was read from */

/* boolean, is override set */

/* # of last request processed by server */
/* True if this came from SendEvent request */
/* Display the event was read from */

Event Structure Members

event The window that selected this event

The window that was just mapped or unmapped.
override_redirect (XMapEvent only)

True or False. The value of the override_redirect attribute of the
window that was just mapped.

636

Xlib Reference Manual

xmap, xunmap

(continued)

MapNotify, UnmapNotify

f rom_conf igure (XUnmapEvent only)

True if the event was generated as a result of a resizing of the window s parent
when the window itself had a win_gravity of UnmapGravity. See the
description of the win_gravity attribute in Section 4.3.4 of Volume One,
Xlib Programming Manual. False otherwise.

Xlib Reference Manual

637

MappingNotify

xmapping

When Generated

A MappingNotify event is sent when any of the following is changed by another client: the
mapping between physical keyboard keys (keycodes) and keysyms, the mapping between
modifier keys and logical modifiers, or the mapping between physical and logical pointer
buttons. These events are triggered by a call to XSetModifierMapping or XSet-
PointerMapping, if the return status is MappingSuccess, or by any call to XChange-
Keyboa rdMapping.

This event type should not be confused with the event that occurs when a window is mapped;
that is a MapNotify event Nor should it be confused with the KeymapNotify event,
which reports the state of the keyboard as a mask instead of as a keycode.

Select With

The X server sends MappingNotify events to all clients. It is never selected and cannot be
masked with the window attributes.

XEvent Structure Name

typedef union _XEvent {

XMappingEvent xmapping;
} XEvent;

/* # of last request processed by server */

/* True if this came from SendEvent request */

/* Display the event was read from */

/* unused */

/* one of MappingMapping, MappingKeyboard,

* MappingPointer */

/* first keycode */

/* range of change with f irst_keycode*/

Event Structure

typedef struct {
int type;

unsigned long serial
Bool send_event;
Display *display;
Window window;
int request;

int f irst_keycode;
int count;
} XMappingEvent;

Event Structure Members

request The kind of mapping change that occurred: MappingModif ier for a

successful XSetModifierMapping (keyboard Shift, Lock, Control,
Meta keys), MappingKeyboard for a successful XChange-
Keyboa rdMapping (other keys), and MappingPointer for a suc
cessful XSetPointerMapping (pointer button numbers).

first_keycode If the request member is MappingKeyboard or Mapping-
Modifier, then f irst_keycode indicates the first in a range of key-
codes with altered mappings. Otherwise, it is not set

Xlib Reference Manual

xmapplng (continued) MappingNotify

count If the request member is MappingKeyboard or Mapping-

Modifier, then count indicates the number of keycodes with altered
mappings. Otherwise, it is not set

Notes

If the request member is MappingKeyboard, clients should call XRef reshKeyboard-
Mapping.

The normal response to a request member of MappingPointer or MappingModif ier
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 preferences, it should call XGetModif ier-
Mapping or XGetPointerMapping to find out about the new mapping.

Xlib Reference Manual 639

MapRequest \ xm ,p r . qu ._

When Generated

A MapRequest event occurs when the functions XMapRaised and XMapWindow are
called.

This event differs from MapNot if y in that it delivers the parameters of the request before it is
carried out This gives the client that selects this event (usually the window manager) the
opportunity to revise the size or position of the window before executing the map request itself
or to deny the request (MapNot i f y indicates the final outcome of the request)

Select With

This event is selected by specifying the window ID of the parent of the receiving window with
SubstructureRedirectMask. (In addition, the override_redirect member of the
XSetwindowAttributes structure for the specified window must be False.)

XEvent Structure Name

typedef union _XEvent {

XMapRequestEvent xmaprequest;
} 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;

} XMapRequestEvent;

Event Structure Members

pa rent The ID of the parent of the window being mapped.
window The ID of the window being mapped.

CAf)

Xlib Reference Manual

xmotion-

MotionNotify

When Generated

A MotionNotify event reports that the user moved the pointer or that a program warped the
pointer to a new position within a single window.

Select With

This event is selected with ButtonMotionMask, ButtonlMotionMask, Button2-
MotionMask, ButtonSMotionMask, Button4MotionMask, ButtonSMotionMask,
PointerMotionHintMask, and PointerMotionMask. These masks determine the spe
cific conditions under which the event is generated.

See Section 8.3.3.3 of Volume One, Xlib Programming Manual, for a description of selecting
button events.

XEvent Structure Name

typedef union _XEvent {

XMotionEvent xmotion;
} XEvent;

Event Structure

typedef struct {
int type;

unsigned long serial,
Bool send_event;
Display *display;
Window window;
Window root;
Window subwindow;
Time time;
int x, y;

int x_root, y_root;
unsigned int state;
char is_hint;
Bool same_screen;
} XMotionEvent;

/* of event */

/* # of last request processed by server */

/* True if this came from SendEvent request */

/* Display the event was read from */

/* event window it is reported relative to */

/* root window that the event occurred on */

/* child window */

/* milliseconds */

/* pointer coordinates relative to receiving

* window */

/* coordinates relative to root */
/* button and modifier key mask */
/* is this a motion hint */
/* same screen flag */

typedef XMotionEvent XPointerMovedEvent;

Event Structure Members

subwindow If the source window is the child of the receiving window, then the

subwindow member is set to the ID of that child.

time

The server time when the button event occurred, in milliseconds. Time
is declared as unsigned long, so it wraps around when it reaches the
maximum value of a 32-bit number (every 49.7 days).

Xlib Reference Manual

641

MotionNotify

(continued)

xmotion

x , y if the receiving window is on the same screen as the root window speci

fied by root, then x and y are the pointer coordinates relative to the
receiving window s origin. Otherwise, x and y are zero.

When active button grabs and pointer grabs are in effect (see Volume
One, Section 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, ButtonSMask, Button4Mask,
ButtonSMask, ControlMask, LockMask, ModlMask, Mod2-
Mask, ModSMask, Mod4Mask, ModSMask, and Shif tMask.

is_hint Either the constant Notif yNormal or Notif yHint. Notif yHint

indicates that the PointerMotionHintMask was selected. In this
case, just one event is sent when the mouse moves, and the current posi
tion can be found by calling XQueryPo inter or by examining the
motion history buffer with XGetMotionEvents, if a motion history
buffer is available on the server. Not if yNormal 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 win
dow. 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 Mot ionE vents if the
pointer starts and stops in different windows.

642

Xlib Reference Manual

xproperty-

PropertyNotify

When Generated

A PropertyNotify event indicates that a property of a window has changed or been
deleted. This event can also be used to get the current server time (by appending zero-length
data to a property). PropertyNotify events are generated by XChangeProperty,
XDeleteProperty, XGetWindowProperty, or XRotateWindowProperties.

Select With

This event is selected with PropertyChangeMask.

XEvent Structure Name

typedef union _XEvent {

XPropertyEvent xproperty;
} XEvent;

Event Structure

typedef struct {

int type;

unsigned long serial;

Bool send_event;

Display *display;

Window window;

Atom atom;

Time time;

int state;
} XPropertyEvent;

/* # of last request processed by server */
/* True if this came from SendEvent request */
/* Display the event was read from */

/* property NewValue, property Deleted */

Event Structure Members

window The window whose property was changed, not the window that selected the
event

atom The property that was changed.

state Either PropertyNewValue or PropertyDelete. Whether the property

was changed to a new value or deleted.

t ime The t ime member specifies the server time when the property was changed.

Xlib Reference Manual

643

ReparentNotify

xreparent

When Generated

A ReparentNotify event reports when a client successfully reparents a window.

Select With