The Definitive Guides
to the X Wi System
Volume Two
Xlib Reference
Manual
for Version 11
O'Reilly & Associates, Inc.
Volume Two
Xlib Reference
Manual
for Version 11 of the
X Window System
edited by Adrian Nye
O'Reilly & Associates, Inc.
Table of Contents
Page
Preface .................................................................................................................................. ix
About This Manual ................................................................................................................. ix
Summary of Contents ............................................................................................................... x
How to Use This Manual ......................................................................................................... x
Assumptions ........................................................................................................................... xii
Font Conventions Used in This Manual ................................................................................ xii
Related Documents ............................................................................................................... xiii
Requests For Comments ....................................................................................................... xiii
Licensing Information ........................................................................................................... xiii
Acknowledgements ............................................................................................................... xiv
Permuted Index ................................................................................................................. 1
Xlib Function Reference .............................................................................................. 29
Appendix A: Function Group Summary .......................................................... 499
Group Listing with Brief Descriptions ................................................................................ 499
Alphabetical Listing of Routines ......................................................................................... 514
Appendix B: Error Messages and Protocol Requests ................................. 523
Appendix C: Macros ................................................................................................. 531
Display Macros ..................................................................................................................... 531
Image Format Macros .......................................................................................................... 535
Keysym Classification Macros ............................................................................................. 535
Resource Manager Macros ................................................................................................... 536
Appendix D: The Color Database ....................................................................... 537
Appendix E: Event Reference ............................................................................... 539
Meaning of Common Structure Elements ............................................................................ 541
ButtonPress, ButtonRelease ................................................................................................. 543
CirculateNotify ..................................................................................................................... 545
CirculateRequest ................................................................................................................... 546
ClientMessage ....................................................................................................................... 547
ColormapNotify .................................................................................................................... 548
ConfigureNotify .................................................................................................................... 549
ConfigureRequest ................................................................................................................. 551
CreateNotify ......................................................................................................................... 553
DestroyNotify ....................................................................................................................... 554
EnterNotify, LeaveNotify ..................................................................................................... 555
Expose ................................................................................................................................... 561
Focusln, FocusOut ................................................................................................................ 563
GraphicsExpose, NoExpose ................................................................................................. 569
GravityNotify ........................................................................................................................ 571
KeymapNotify ...................................................................................................................... 572
KeyPress, KeyRelease .......................................................................................................... 573
MapNotify, UnmapNotify .................................................................................................... 575
MappingNotify ..................................................................................................................... 577
MapRequest .......................................................................................................................... 579
MotionNotify ........................................................................................................................ 580
PropertyNotify ...................................................................................................................... 582
ReparentNotify ..................................................................................................................... 583
ResizeRequest ....................................................................................................................... 584
SelectionClear ....................................................................................................................... 585
SelectionNotify ..................................................................................................................... 586
SelectionRequest ................................................................................................................... 587
VisibilityNotify ..................................................................................................................... 588
Appendix F: Structure Reference ........................................................................ 591
Description of Contents ........................................................................................................ 591
Resource Types ..................................................................................................................... 592
Structure Definitions ............................................................................................................. 592
Depth ................................................................................................................................. 592
Display .............................................................................................................................. 593
GC ..................................................................................................................................... 594
Screen ................................................................................................................................ 594
ScreenFormat .................................................................................................................... 595
Visual ................................................................................................................................ 595
XArc .................................................................................................................................. 596
XChar2b ............................................................................................................................ 596
XCharStruct ....................................................................................................................... 596
XClassHint ........................................................................................................................ 597
XColor ............................................................................................................................... 597
XComposeStatus ............................................................................................................... 597
XExtCodes ........................................................................................................................ 598
XExtData ........................................................................................................................... 598
XFontProp ......................................................................................................................... 598
XFontStruct ....................................................................................................................... 599
XGCValues ....................................................................................................................... 599
XHostAddress ................................................................................................................... 600
XlconSize .......................................................................................................................... 600
Xlmage .............................................................................................................................. 600
XKeyboardControl ............................................................................................................ 601
XKeyBoardState ............................................................................................................... 601
XModifierKeymap ............................................................................................................ 602
XPoint ............................................................................................................................... 602
XRectangle ........................................................................................................................ 602
XSegment .......................................................................................................................... 602
XSetWindowAttributes ..................................................................................................... 603
XSizeHints ........................................................................................................................ 603
XStandardColormap .......................................................................................................... 604
XTextltem ......................................................................................................................... 604
XTextltem 16 ..................................................................................................................... 604
XTimeCoord ..................................................................................................................... 605
XVisuallnfo ....................................................................................................................... 605
XWMHints ........................................................................................................................ 605
XWindowAttributes .......................................................................................................... 606
XWindowChanges ............................................................................................................ 606
Appendix G: Symbol Reference ........................................................................... 607
Appendix H: Keysyms .............................................................................................. 623
Appendix I: The Cursor Font ............................................................................... 641
Appendix J: Fonts ...................................................................................................... 643
Appendix K: Xlib Release 3 Update ................................................................... 699
New Routines .................................................................................................................... 699
Command Line Options .................................................................................................... 701
Fonts .................................................................................................................................. 701
Internal and Invisible Changes to Xlib ............................................................................. 702
Small Interface Changes ................................................................................................... 702
Server Fixes ...................................................................................................................... 703
The Xmu library ............................................................................................................... 703
Release 3 Protocol Clarifications ...................................................................................... 704
Window Attributes At-a-glance ............................................................................. 707
GC At-a-glance .............................................................................................................. 709
ooo
VIII
Summary of Contents
This manual is divided into two volumes. This is the second volume, the Xlib Reference
Manual. It includes reference pages for each of the Xlib functions (organized alphabeti-
cally), a permuted index, and numerous appendices and quick reference aids.
The first volume, the Xlib Programming Manual, provides a conceptual introduction to Xlib,
including tutorial material and numerous programming examples. Arranged by task or
topic, each chapter brings together a group of Xlib functions, describes the conceptual foun-
dation they are based on, and illustrates how they are most often used in writing applications
(or in the case of the last chapter, window managers). Volume One is structured so as to be
useful as a tutorial and also as a task-oriented reference.
Volume One and Volume Two are designed to be used together. To get the most out of the
examples in Volume One, you will need the exact calling sequences of each function from
Volume Two. To understand fully how to use each of the functions described in Volume
Two, all but the most experienced X "hacker" will need the explanation and examples in
Volume One.
Both volumes include material from the original Xlib and X11 Protocol documentation pro-
vided by MIT, as well as from other documents provided on the MIT release tape. This
volume is based heavily on these sources, although it has also been extensively edited and
added to. We have done our best to incorporate all of the useful information from the MIT
documentation, to correct code references we found to be in error, to reorganize and present
it in a more useful form, and to supplement it with conceptual material, tutorials, reference
aids, and examples. In other words, this manual is not only a replacement, but is a superset
of the MIT documentation.
Those of you familiar with the MIT documentation will recognize that each reference page
in this volume includes the detailed description of the routine found in Gettys, Newman, and
Scheitler's Xlib-C Language X Interface, plus in many cases additional text that clarifies
ambiguities and describes the context in which the routine would be used. We have also
added cross-references to related reference pages and to where additional information can be
found in Volume One.
How to Use This Manual
Volume Two is designed to make it as easy and fast as possible to look up virtually any fact
about Xlib. It includes a permuted index, reference pages for each library function, appen-
dices that cover macros, structures, function groups, events, fonts, colors, cursors, keysyms,
and errors, and at-a-glance tables for the graphics context and window attributes.
The permuted index is the standard UNIX way of finding a particular function name given a
keyword. By looking up a word in the second column that you think describes the function
you are looking for, you can find the group of functions that have that word in their descrip-
tion lines. The description line also appears at the top of each reference page. Once you
have found the routine you are looking for, you can look for its reference page.
Related Documents
The C Programming Language by B. W. Kernighan and D. M. Ritchie
The following documents are included on the X11 source tape:
Xt Toolkit Intrinsics, by Joel McCormack, Paul Asente and Ralph Swick
Xt Toolkit Widgets, by Ralph Swick and Terry Weissman
Xlib-C Language X Interface, by Jim Gettys, Ron Newman, and Robert Scheifler
The following book on the X Window System from O'Reilly and Associates, Inc., is
currendy in its second printing:
Volume Three -- X Window System User's Guide
Two more books on the X Window System are now being developed at O'Reilly & Associ-
ates, Inc., and are expected to be published in the Summer of 1989:
Volume Four m Xt Toolkit Programming Manual
Volume Five -- Xt Toolkit Reference Manual
Requests For Comments
Please write to tell us about any flaws you find in this manual or how you think it could be
improved, to help us provide you with the best documentation possible.
Our U.S. mail address, e-mail address, and phone number are as follows:
O'Reilly & Associates, Inc.
632 Petaluma Avenue
Sebastopol, CA 95472
(800) 338-6887
UUCP: uunet!ora!adrian
ARPA: adrian@ora.UU.NET
Licensing Information
This manual has been designed for licensing and customization by manufacturers or distri-
butors of systems supporting X11. As of this writing, it has been licensed by Masscomp,
Motorola, Apollo Computer, Silicon Graphics, and Stellar Computer. For information on
licensing, call O'Reilly & Associates, Inc. at (800) 338-6887, or send e-mad to
tim@ora.UU.NET.
Preface xiii
Acknowledgements
The information contained in this manual is based in part on Xlib-C Language X Interface,
written by Jim Gettys, Ron Newman, and Robert Scheifler, and the X Window System Proto-
col, Version 11, by Robert Scheifler (with many contributors). The X Window System
software and these documents were written under the auspices of Project Athena at MIT. In
addition, this manual includes material from Oliver Jones' Xlib tutorial presentation, which
was given at the MIT X Conference in January 1988, and from David Rosenthal's Inter-
Client Communication Conventions Manual.
I'd like to thank the people who helped this book come into being. It was Tim O'Reilly
who originally sent me out on a contract to write a manual for X Version 10 for a worksta-
tion manufacturer, and later to another company to write a manual for X Version 11, from
which this book began. I've learned most of what I know about computers and technical
writing while working for Tim. For this book he acted as an editor, he helped me reorgan-
ize several chapters, he worked on the Color and Managing User Preferences chapters when
time was too short for me to do it, and he kept my spirits up through this long project.
While I was concentrating on the details, his eye was on the overall presentation, and his
efforts improved the book enormously.
This book would not be as good (and we might still be working on it) had it not been for
Daniel Gilly. Daniel was my production assistant for critical periods in the project. He
dealt with formatting issues, checked for consistent usage of terms and noticed irregularities
in content, and edited files from written corrections by me and by others. His job was to
take as much of the work off me as possible, and with his technical skill and knowledge of
UNIX he did that very well.
This manual has benefitted from the work and assistance of the entire staff of O'Reilly &
Associates, Inc. Susan Willing was responsible for graphics and design, and she proofed
many drafts of the book; Linda Mui tailored the troff macros to the design by Sue Willing
and myself, and was invaluable in the final production process; John Strang figured out the
Release 2 resource manager and wrote the section on that topic; Karen Cakebread edited a
draft of the manual and established some conventions for terms and format. Peter Mui exe-
cuted the "at-a-glance" tables for the inside back cover; Tom Scanlon entered written edits
and performed copy fitting; Linda Walsh updated the index of the book; Valerie Quercia,
Tom Van Raalte, and Donna Woonteiler all contributed in some small ways; and Cathy
Brennan, Suzanne Van Hove, and Jill Berlin fielded many calls from people interested in the
X manual, and saved me all the time that would have taken. A special thanks to everyone at
O'Reilly & Associates for putting up with my habits of printer and terminal hogging, lug-
ging X books around, recycling paper, and for generally being good at what they do and
good-natured to boot.
I would also like to thank the people from other companies that reviewed the book or other-
wise made this project possible: John Posner, Barry Kingsbury, and Jeffrey Vroom of Stel-
lar Computer; Oliver Jones of Apollo Computer; Sam Black, Jeff Graber, and Janet Egan of
Masscomp; A1 Tabayoyon, Paul Shearer, and many others from Tektronix; Robert Scheifler
and Jim Fulton of the X Consortium (who helped with the Color and Managing User
Preferences chapters), and Peter Winston II and Aub Harden of Integrated Computer Solu-
tions. Despite the efforts of the reviewers and everyone else, any errors that remain are my
own.
m Adrian Nye
turn the screen saver on or
two regions have the same size.
XOffsetRegion: change
8-bit text string, foreground
/set the bitwise logical
for program name and
/circulate the stacking
/change the stacking
to the top of the stacking
to the bottom of the stacking
size, border width, or stacking
lower a window in the stacking
to the top of the stacking
XSetCllpOrigin: set the clip
/set the tile/stipple
XDrawRectangle: draw an
XDrawRectangles: draw the
number of/XPending: flush the
events and/XSync: flush the
queued/XFlush: flush the
XGetSelectionOwner: return the
XSetSelectionOwner: set the
grab. /change the
XSetScreenSaver: set the
get the current screen saver
return a list of children,
between another window and its
create a subimage from
matching both passed window and
/the next event matching both
get the current font search
set the font search
buffer and return the number of
/set the background
/attribute to the specified
XGetPixel: obtain a single
context. /set the background
context. /set the foreground
/add a constant value to every
XPutPixel: set a
and flags for a specified
a drawable with depth, applying
RGB values for an array of
XTextWidthl6: get the width in
XTextWidth: get the width in
XFreePixmap: free a
XSetClipMask: set clip_mask
data. /create a
XCreatePixmap: create a
image on a window or
from drawable into/XGetImage:
XSetPlaneMask: set the
context. /logical function, and
XCopyPlane: copy a single
read/write (nonshareable) color
free colormap cells or
XPointInRegion: determine if a
off. XForceScreenSaver: ........................ XForceScreenSaver
offset, and shape. /if ............................... XEqualRegion
offset of a region ..................................... XOffsetRegion
only. XDrawString: draw an .................. XDrawString
operation in a graphics/ ........................... XSetFunction
options. /the user preferences ................. XGetDefault
order of children up or down .................. XCirculateSubwindows
order of siblings ...................................... XRestackWindows
order. /the bottom child .......................... XCirculateSubwindowsDown
order. /circulate the top child ................. XCirculateSubwindowsUp
order. /the window position, . ................. XConfigureWindow
order. XLowerWindow: ......................... XLowerWindow
order. /raise a window ............................ XRaiseWindow
origin in a graphics context .................... XSetClipOrigin
origin in a graphics context .................... XSetTSOrigin
outline of a rectangle .............................. XDrawRectangle
outlines of multiple/ ................................ XDrawRectangles
output buffer and return the .................... XPending
output buffer and wait for all .................. XSync
output buffer (display all ........................ XFlush
owner of a selection ................................ XGetSelectionOwner
owner of a selection ................................ XSetSelectionOwner
parameters of an active pointer ............... XChangeActivePointerGrab
parameters of the screen saver. ............... XSetScreenSaver
parameters. XGetScreenSaver: ............... XGetScreenSaver
parent, and root. XQueryTree: ............... XQueryTree
parent. /insert a window ......................... XReparentWindow
part of an image. XSubImage: ............... XSublmage
passed mask: don't wait. /event ............. XCheckWindowEvent
passed window and passed mask:/ ......... XCheckWindowEvent
path. XGetFomPath: ............................... XGetFontPath
path. XSetFontPath: ............................... XSetFomPath
pending input events. /output ................. XPending
pixel attribute of a window ..................... XSetWindowBackground
pixel value and repaint the/ ..................... XSetWindowBorder
pixel value from an image ...................... XGetPixel
pixel value in a graphics ......................... XSetBackground
pixel value in a graphics ......................... XSetForeground
pixel value in an image ........................... XAddPixel
pixel value in an image ........................... XPutPixel
pixel value. /the RGB values ................. XQueryColor
pixel values. /a drawable into ................ XCopyPlane
pixel values. /obtain ............................... XQueryColors
pixels of a 16-bit character/ .................... XTextWidthl6
pixels of an 8-bit character/ .................... XTextWidth
pixmap ID ............................................... XFreePixmap
pixrnap in a graphics context .................. XSetClipMask
pixmap with depth from bitmap ............. XCreatePixmapFromBitmapData
pixmap ..................................................... XCreatePixmap
pixmap. /draw a rectangular ................... XPutImage
place contents of a rectangle ................... XGetImage
plane mask in a graphics/ ....................... XSetPlaneMask
plane mask in a graphics ......................... XSetState
plane of a drawable into a/ ..................... XCopyPlane
planes. /allocate ...................................... XAllocColorPlanes
planes. XFreeColors: .............................. XFreeColors
point is inside a region ............................ XPointInRegion
18 Xlib Reference Manual
/get the standard colormap
read the window manager hints
of the XA_WM_ICON_SIZE
/change the standard colormap
set a window manager hints
queue. XPutBackEvent:
string to a binding list and a
/convert a key string to a
XrmQuarkToString: convert a
convert a string to a
XrmUniqueQuark: allocate a new
resource from name and class as
resource into a database using
value to a database using
font/XQueryTextExtentsl 6:
font/XQueryTextExtents:
without removing it from the
XCheckIfEvent: check the event
/return the next event in
don't//return the next event in
number of events in the event
without removing it from the
push an event back on the input
the output buffer (display all
the stacking/XRaiseWindow:
XReadBitmapFile:
XGetSizetlints:
a zoomed/XGetZoomHints:
property. XGetWMHints:
XAllocNamedColor: allocate a
XAllocColor: allocate a
XStoreNamedColor: allocate a
XStoreColors: set or change
XStoreColor: set or change a
XAllocColorPlanes: allocate
XAllocColorCells: allocate
client. XRebindKeysym:
XClipBox: generate the smallest
XGetImage: place contents of a
location/XGetSubImage: copy a
XRectInRegion: determine if a
XUnionRectWithRegion: add a
draw an arc fiuing inside a
draw an outline of a
draw the outlines of multiple
graphics context to the list of
XClearArea: clear a
XFillRectangle: fill a
XFilIRectangles: fill multiple
or pixmap. XPutImage: draw a
region. XShrinkRegion:
XSubtractRegion: subtract one
XPolygonRegion: generate a
XEmptyRegion: determine if a
smallest rectangle enclosing a
create a new empty
storage associated with a
property ................................................... XGetStandardColormap
property. XGetWMHints: ....................... XGetWMHints
property. /set the value ........................... XSetIconSizes
property ................................................... XSetStandardColormap
property. XSetWMHints: ....................... XSetWMHints
push an event back on the input ............. XPutBackEvent
quark list. /convert a key ........................ XrmStringToBindingQuarkList
quark list .................................................. XrmStringToQuarkList
quark to a string ...................................... XrmQuarkToString
quark. XrmStringToQuark: .................... XrmStringToQuark
quark ........................................................ XrmUniqueQuark
quarks. XrmQGetResource: get a .......... XrmQGetResource
quarks. /store a ....................................... XrmQPutResource
quarks. /add a string resource ................. XrmQPutStringResource
query the server for string and ................ XQueryTextExtentsl6
query the server for string and ................ XQueryTextExtents
queue; do not wait. /an event ................. XPeeklfEvent
queue for a matching event ..................... XChecklfEvent
queue matching type and window .......... XCheckTypedWindowEvent
queue that matches event type; ............... XCheckTypedEvent
queue. /check the .................................... XEventsQueued
queue. /get an event ................................ XPeekEvent
queue. XPutBackEvent: ......................... XPutBackEvent
queued requests). /flush .......................... XFlush
raise a window to the top of ................... XRaiseWindow
read a bitmap from disk .......................... XReadBitmapFile
read any property of type/ ....................... XGetSizeHints
read the size hints property of ................ XGetZoomHints
read the window manager hints .............. XGetWMHints
read-only colorcell from color/ ............... XAllocNamedColor
read-only colormap cell with/ ................. XAllocColor
read/write colorcell by English/ .............. XStoreNamedColor
read/write colorcells to the/ ..................... XStoreColors
read/write entry of a colormap/ .............. XStoreColor
read/write (nonshareable) color/ ............. XAllocColorPlanes
read/write (nonshared)/ ........................... XAllocColorCells
rebind a keysym to a string for ............... XRebindKeysym
rectangle enclosing a region ................... XClipBox
rectangle from drawable into an/ ............ XGetlmage
rectangle in drawable to a ....................... XGetSublmage
rectangle resides in a region ................... XRectlnRegion
rectangle to a region ................................ XUnionRectWithRegion
rectangle. XDrawArc: ............................ XDrawArc
rectangle. XDrawRectangle: ................... XDrawRectangle
rectangles. XDrawRectangles: ............... XDrawRectangles
rectangles. /clip_mask in a ..................... XSetClipRectangles
rectangular area in a window .................. XClearArea
rectangular area ....................................... XFillRectangle
rectangular areas ...................................... XFillRectangles
rectangular image on a window .............. XPutImage
reduce or expand the size of a ................ XShrinkRegion
region from another ................................ XSubtractRegion
region from points ................................... XPolygonRegion
region is empty ....................................... XEmptyRegion
region. XClipBox: generate the ............. XClipBox
region. XCreateRegion: .......................... XCreateRegion
region. /deallocate .................................. XDestroyRegion
20 Xlib Reference Manual
change offset of a
if a point is inside a
if a rectangle resides in a
context to the specified
reduce or expand the size of a
add a rectangle to a
XEqualRegion: determine if two
compute the intersection of two
compute the union of two
union and intersection of two
XUngrabButton:
XUngrabKey:
XUngrabKeyboard:
XUngrabPointer:
XUngrabServer:
/destroy a client or its
control list. XRemoveltost:
XChangeSaveSet: add or
the] XRemoveFromSaveSet:
access control/XRemoveHosts:
both passed/XCheckWindowEvent:
mask and window. XWindowEvent:
matches mask;/XCheckMaskEvent:
matches mask. XMaskEvent:
not wait. /get an event without
/get an event without
the specified pixel value and
border tile attribute and
connection to a/XDisplayName:
to allow or deny connection
buffer (display all queued
XResetScreenSaver:
/determine ff a rectangle
line/XrmParseCommand: load a
XrmQGetSearchResource: search
XrmPutLineResource: add a
quarks. XrmQGetResource: get a
strings. XrmGetResource: get a
the//obtain the GContext
XrmQPutResource: store a
XrmPutResource: store a
Xrmlnitialize: initialize the
XrmPutStringResource:. add a
using quarks. /add a string
database levels for a given
/and pointer events when these
a client or its remaining
file. XrmGetFileDatabase:
to X/XListExtensions:
parent, and root. XQueryTree:
levels. XrmQGetSearchList:
font names. XListFonts:
/copy a colormap and
string. XlntemAtom:
XFetchB uffer:
XFetchBytes:
loaded font. XQueryFont:
region.
region.
region.
region.
region.
region.
regions
regions.
regions.
XOffsetRegion: .......................... XOffsetRegion
/determine ................................... XPointInRegion
/determine ................................... XRectInRegion
/of the graphics ........................... XSetRegion
XShrinkRegion: ......................... XShrinkRegion
XUnionRectWithRegion: ........... XUnionRectWithRegion
have the same size,/ ................... XEqualRegion
Xl.ntersectRegion: ..................... XlntersectRegion
XUnionRegion: ......................... XUnionRegion
regions. /between the .............................. XXorRegion
release a button from grab ...................... XUngrabButton
release a key from grab ........................... XUngrabKey
release the keyboard from grab .............. XUngrabKeyboard
release the pointer from grab .................. XUngrabPointer
release the server from grab .................... XUngrabServer
remaining resources ................................ XKillClient
remove a host from the access ................ XRemovelIost
remove a subwindow from the/ .............. XChangeSaveSet
remove a window's children from .......... XRemoveFromSaveSet
remove multiple hosts from the .............. XRemoveHosts
remove the next event matching ............. XCheckWindowEvent
remove the next event matching ............. XWindowEvent
remove the next event that ...................... XChecLMaskEvent
remove the next event that ...................... XMaskEvent
removing it from the queue; do .............. XPeeklfEvent
removing it from the queue .................... XPeekEvent
repaint the border. /to ............................. XSetWindowBorder
repaint the border. /a window ................ XSetWindowBorderP/xrnap
report the display name when ................. XDisplayName
requests. /access control list ................... XEnableAccessControl
requests). /flush the output ..................... XFlush
reset the screen saver .............................. XResetScreenSaver
resides in a region ................................... XRectInRegion
resource database from command ........... XrmParseCommand
resource database levels for a/ ................ XrmQGetSearchResource
resource entry given as a/ ....................... XrmPutLineResource
resource from name and class as ............ XrmQGetResource
resource from name and class as ............ XrmGetResource
(resource ID) associated with ................. XGContextFromGC
resource into a database using/ ............... XrmQPutResource
resource into a database .......................... XrmPutResource
resource manager. ................................... Xrmlnitialize
resource that is specified as a/ ................ XrmPutStringResource
resource value to a database ................... XrmQPutStringResource
resource. /search resource ....................... XrmQGetSearchResource
resources are grabbed .............................. XAllowEvents
resources. /destroy .................................. XKillClient
retrieve a database from a ....................... XrmGetFileDatabase
return a list of all extensions ................... XListExtensions
return a list of children ........................... XQueryTree
return a list of database ........................... XrmQGetSearchList
return a list of the available .................... XListFonts
return a new colormap ID ....................... XCopyColormapAndFree
return an atom for a given name ............ XlnternAtom
return data from a cut buffer ................... XFetchBuffer
return data from cut buffer 0 .................. XFetchBytes
return information about a ...................... XQueryFont
Perm uted Index 21
XDrawStringl6: draw two-byte
border. /change a window border
/change the background
XSetTile: set the fill
the "best" supported cursor,
obtain the best supported fill
graphics/XSetTSOrigin: set the
stacking order. /circulate the
XMapRaised: map a window on
/the bottom child to the
/raise a window to the
color/XParseColor: look up or
auto-repeat/XAutoRepeatOff:
auto-repeat/XAutoRepeatOn:
off. XForceScreenSaver:
/create a cursor from
XDrawLine: draw a line between
XEqualRegion: determine if
compute the intersection of
compute the union of
the union and intersection of
XDrawString 16: draw
window. /obtain the atom
next event in queue matching
in queue that matches event
/to a window and context
get the next event of any
/read any property of
/the value of any property of
entry for a given window and
XSelectInput: select the event
default if/XUninstallColormap:
[the difference between the
XUnionRegion: compute the
for the font/XFreeFont:
X UnloadFont:
XUnmapWindow:
window. XUnmapSubwindows:
all/XDestroyWindow:
XCreateSimpleWindow: create an
the stacking order of children
ASCII color/XParscColor: look
XRefreshKeyboardMapping:
ControlJ/set keycodes to be
/calculate window geometry given
name and/XGetDefault: scan the
a resource into a database
resource value to a database
/to the specified pixel
and/XSaveContext: save a data
/obtain a single pixel
/set the background pixel
/set the foreground pixel
a constant value to every pixel
XPutPixel: set a pixel
XConvertSelection: use the
XSetSizeltints: set the
text strings ............................................... XDrawString 16
tile attribute and repaint the .................... XSetWindowBorderPixmap
tile attribute of a window ........................ XSetWindowBackgroundPixmap
tile in a graphics context ......................... XSetTile
tile, or stipple size. /obtain ..................... XQueryBestSize
tile shape. XQueryBestTile: ................... XQueryBestTile
tile/stipple origin in a .............................. XSetTSOrigin
top child to the bottom of the ................. XCirculateSubwindowsUp
top of its siblings .................................... XMapRaised
top of the stacking order. ........................ XCirculateSubwindowsDown
top of the stacking order ......................... XRaiseWindow
translate RGB values from ASCII .......... XParseColor
tum off the keyboard .............................. XAutoRepeatOff
turn on the keyboard ............................... XAutoRepeatOn
turn the screen saver on or ...................... XForceScreenSaver
two bitmaps ............................................. XCreatePixmapCursor
two points ................................................ XDrawLine
two regions have the same sized ............ XEqualRegion
two regions. XIntersectRegion: .............. XIntersectRegion
two regions. XUnionRegion: ................. XUnionRegion
two regions. /between ............................. XXorRegion
two-byte text strings ................................ XDrawStringl6
type and property format for a ................ XGetWindowProperty
type and window. /return the ................. XCheckTypedWindowEvent
type; don't wait. /next event .................. XCheckTypedEvent
type (not graphics context) ..................... XSaveContext
type or window. XNextEvent: ............... XNextEvent
type XA_SIZE_I IINq'S .............................. XGetSizeHints
type XA_SIZE_INq'S .............................. XSetSizeHints
type. ]delete a context ............................. XDdeteContext
types to be sent to a window .................. XSelectInput
uninstall a colormap; install .................... XUninstallColormap
union and intersection of two/ ................ XXorRegion
union of two regions ............................... XUnionRegion
unload a font and free storage ................ XFreeFont
unload a font ........................................... XUnloadFont
unmap a window ..................................... XUnmapWindow
unmap all subwindows of a given .......... XUnmapSubwindows
unmap and destroy a window and .......... XDestroyWindow
unmapped InputOutput window ............. XCreateSimpleWindow
up or down. /circulate ............................ XCirculateSubwindows
up or translate RGB values from ............ XParseColor
update the stored modifier and/ .............. XRefreshKeyboardMapping
used as modifiers (Shift .......................... XSetModifierMapping
user geometry string and/ ........................ XGeometry
user preferences for program .................. XGetDefauh
using quarks. /store ................................. XrmQPutResource
using quarks. /add a string ..................... XrmQPutStringResource
value
value
value
value
value
value
value
value
value
and repaint the border. .................. XSetWindowBorder
corresponding to a window ........... XSaveContext
from an image ............................... XGetPixel
in a graphics context ..................... XSetBackground
in a graphics context ..................... XSetForeground
in an image. /add .......................... XAddPixel
in an image .................................... XPutPixel
of a selection ................................. XConvertSelection
of any property of type/ ................ XSetSizeHints
26 Xlib Reference Manual
--Xlib- Function Group
Introduction
This page describes the format of each reference page in this volume.
Name
FunctionName -- brief description of the function.
Synopsis
The Synopsis section presents the calling syntax for the routine, including the declarations of
the arguments and return type. For example:
returntype XFunctionName(argl, arg2, arg3);
typel argl;
type2 *arg2; /* RETURN */
type3 *arg3; /* SEND and RETURN */
The return type Status is of type int; it returns either True or False tO indicate whether
the routine was successful.
Arguments
The Arguments section describes each of the arguments used by the function. There are three
sons of arguments: arguments that specify data to the function, arguments that return data
from the function, and arguments that do both. An example of each type is shown below:
argl Specifies information for XFunctionName. The description of arguments that
pass data to the function always begins with the word "Specifies," as shown in
this example.
arg2 Returns a pointer to data to be filled in by XFunctionName. The description of
arguments that return data from the function always begins with the word
"Returns."
arg3 Specifies information for XFunctionName, and returns data from the function.
The description of arguments that both pass data to the function and return data
from the function uses both the words "Specifies" and "Returns."
Description
The Description section describes what the function does, what it returns, and what events or
side-effects it causes. It also contains miscellaneous information such as examples of usage,
special error cases, and pointers to related information in both volumes of this manual.
Structures
The Structures section contains the C definitions of the X-specific data types used by Func-
tionName as arguments or return values. It also contains definitions of important constants
used by the function. Additional structures not shown can be found in Appendix F, Structure
Reference.
July 26, 1988 29
Introduction (continued) Xlib - Function Group
Errors
The Errors section contains a list of the error event types that XFunctionName can generate.
The general description of the error types is contained in Appendix B, Error Messages and
Protocol Requests. Some functions generate errors due to function-specific interpretation of
arguments. Where appropriate, these function-specific causes have been listed along with the
error event types they generate.
Related Commands
The Related Commands secdon lists the Xlib functions and macros related to XFunction-
Name.
30 July 26, 1988
XAddHost
Xlib - Host Access--
Name
XAddHost -- add a host to the access control list.
Synopsis
XAddHost(display, host)
Display *display;
XHostAddress *host;
Arguments
display
Specifies a pointer to the Display structure returned from XOpenDisplay.
host
Specifies the network address of the host machine to be added.
Description
XAdcIHost adds the specified host to the access control list for the server specified by
display. The access control list is a primitive security feature that allows access to the
server only by other machines listed in a file on the machine running the server. On UNIX
systems, this file is called letc/X?.hosts, where ? is the number of the display.
The application that calls XAddHost and the server whose list is being updated must be run-
ning on the same host machine.
The address data must be a valid address for the type of network in which the server
operates, as specified in the faraily member. Internet, DECnet and ChaosNet networks are
currently supported.
For TCP/IP, the address should be in network byte order. For the DECnet family, the server
performs no automatic swapping on the address bytes. A Phase IV address is two bytes long.
The first byte contains the least significant eight bits of the node number. The second byte
contains the most significant two bits of the node number in the least significant two bits of
the byte, and the area in the most significant six bits of the byte.
For more information on access control, see Volume One, Chapter 13, Other Programming
Techniques.
Structures
typedef struct {
int family;
int length;
char *address;
} XHostAddress;
/* for example FamilyInternet */
/* length of address, in bytes */
/* pointer to where to find the bytes */
/* The following constants for family member */
#define FamilyInternet 0
#define FamilyDECnet 1
#define FamilyChaos 2
Errors
BadAccess
BadValue
32 July 26, 1988
Xlib- Host Access (continued) XAddHost
Related Commands
XAddHosts, XListHosts, XRemoveHost, XRemoveHosts, XDisableAccess-
Control, XEnableAccessControl, XSetAccessControl.
July 26, 1988 33
Xlib - Host Access (continued) XAddHosts
Errors
BadAccess
BadValue
Related Commands
XAddHost, XListHosts, XRemoveHost, XRemoveHosts, XDisableAccess-
Control, XEnableAccessControl, XSetAccessControl.
July 26, 1988 35
XAddPixel k
Xlib - Images--
Name
XAddPixel -- add a constant value to every pixel value in an image.
Synopsis
int XAddPixel(ximage, value)
XImage *ximage;
unsigned long value;
Arguments
ximage
value
Specifies a pointer to the image to be modified.
Specifies the constant value that is to be added. Valid pixel value ranges
depend on the visual used to create the image. If this value added to the
existing value causes an overflow, extra bits in the result are truncated.
Description
XAddPixel adds a constant value to every pixel value in an image. This function is useful
when you have a base pixel value derived from the allocation of color resources and need to
manipulate an image so that the pixel values are in the same range.
For more information on images, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct _XImage {
int width, height;
int xoffset;
int format;
char *data;
int byte_order;
int bitmap_unit;
int bitmap bit order;
-- _
int bitmap_pad;
int depth;
int bytes_per_line;
int bits_per_pixel;
unsigned long red mask;
--
unsigned long green_mask;
unsigned long blue mask;
--
char *obdata;
struct funcs {
struct _XImage *(*create_image) () ;
int (*destroy_image) () ;
unsigned long (*get_pixel) ();
int (*put_pixel) () ;
struct _XImage *(*sub_image) ();
int (*add_pixel) ();
} f;
} XImage;
/* size of image */
/* number of pixels offset in X direction */
/* XYBitmap, XYPixmap, ZPixmap */
/* pointer to image data */
/* data byte order, LSBFirst, MSBFirst */
/* quantity of scan line 8, 16, 32 */
/* LSBFirst, MSBFirst */
/* 8, 16, 32 either XY or ZPixmap */
/* depth of image */
/* accelerator to next line */
/* bits per pixel (ZPixmap) */
/* bits in z arrangment */
/* hook for object routines to hang on */
/* image manipulation routines */
36 July 26, 1988
Xlib -Images (continued) XAddPixel
Related Commands
XDestroyImage, XPutImage, XGetImage, XCreateImage, XSubImage, XGetSub-
Image, XPutPixel, XGetPixel, ImageByteOrder.
July 26, 1988 3 7
XAddToSaveSet
Xlib - Save Set m
Name
XAddToSaveSet -- add a window's children to the client's save-set.
Synopsis
XAddToSaveSet(display,
Display *display;
Window w;
w)
Arguments
di spl ay
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the ID of the window whose children you want to add to the
client's save-set.
Description
XAddToSaveSet adds the children of the specified window to the client's save-set.
The save-set is a safety net for windows that have been reparented by the window manager,
usually to provide a shadow or other background for each window. When the window
manager dies unexpectedly, the windows in the save-set are reparented to their closest living
ancestor, so that they remain alive. See Volume One, Chapter 13, Other Programming Tech-
niques, for more information about save-sets.
Use XRemoveFromSaveSet to remove a window's children from the client's save-set.
Errors
BadMatch
BadWindow
w not created by some other client.
Related Commands
XRemoveFromSaveSet, XChangeSaveSet.
38 July 26 1988
XAIIocColor (continued) Xlib - Color Cells
Related Commands
XAllocColorCells, XAllocColorPlanes, XAllocNamedColor, XLookupColor,
XParseColor, XQueryColor, XQueryColors, XStoreColor, XStoreColors,
XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel.
40 July 26, 1988
XAIIocColorCells (continued) Xlib - Color Cells
Errors
BadColor
BadValue
nplanes is negative.
ncolors is not positive.
Related Commands
XAllocColorPlanes, XAllocColor, XAllocNamedColor, XLookupColor,
XParseColor, XQueryColor, XQueryColors, XStoreColor, XStoreColors,
XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel.
42 July 26, 1988
XAIIocColorPlanes (continued) Xlib - Color Cells
or XStoreNarnedColor, the pixel is decomposed according to rmask, gmask, and bmask
and the corresponding pixel subfield entries are updated.
Seat:us is 0 on failure.
For more information, see Volume One, Chapter 7, Color.
Errors
BadColor
BadVa lue
ncolors is not positive.
At least one of nreds, ngreens, nblues is negative.
Related Commands
XAllocColorCells, XAllocColor, XAllocNamedColor, XLookupColor,
XParseColor, XQueryColor, XQueryColors, XStoreColor, XStoreColors,
XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel.
44 July 26, 1988
--Xlib - Color Cells
XAIIocNamedColor
Name
XAllocNamedColor -- allocate a read-only colorcell from color name.
Synopsis
Status XAllocNamedColor ( display, cmap, colorname,
colorcell_def , rgb_db_def)
Display *display;
Colormap cmap;
char *colorname;
XColor *colorcell def;
XColor * rgb_db_def ;
Arguments
display
cmap
colorname
/* RETURN */
/* RETURN */
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the ID of the colormap in which the colorcell will be allocated.
Specifies the color name string (for example, "red") you want. Upper or
lower case does not matter. The string should be in ISO LATIN-1 encoding,
which means that the first 128 character codes are ASCII, and the second
128 character codes are for special characters needed in western languages
other than English.
colorcell def
Returns the pixel value and RGB values actually used in the colormap. This
is the closest color supported by the hardware.
rgb_db_def Returns the exact RGB values from the database corresponding to the
CO1 orn ame supplied.
Description
XAllocNamedColor determines the RGB values for the specified colorname from the
color database, and then allocates a read-only colorcell with the closest color available, as
described under XAllocColor. Both the 'exact' database definition of the color, and the
color actually allocated are returned. If the colormap is not full, the RGB values allocated are
the closest supported by the hardware. If the colormap is full, XAllocNamedColor returns
the closest read-only colorcell already allocated, and does not actually create or set any new
colorcell.
XAllocNamedColor returns a Status of 0 when it encounters an error or 1 when it
succeeds.
For more information, see Volume One, Chapter 7, Color.
Structures
typedef struct {
unsigned long pixel;
unsigned short red, green, blue;
char flags;
/* DoRed, DoGreen, DoBlue */
Xlib Reference Manual 45
XAIIocNamedColor (continued) Xlib - Color Cells
char pad;
} XColor;
Errors
BadColor
Related Commands
XAllocColorCells, XAllocColorPlanes, XAllocColor, XLookupColor,
XParseColor, XQueryColor, XQueryColors, XStoreColor, XStoreColors,
XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel.
46 July 26, 1988
--Xlib - Input Handling
XAIIowEvents
Name
XAllowEvents -- control the behavior of keyboard and pointer events when these resources
are grabbed.
Synopsis
XAllowEvents(display, event mode,
Display *display;
int event mode;
Time time;
time)
Arguments
display
event mode
time
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the event mode. Pass one of these constan[s: AsyncPointer,
SyncPointer, AsyncKeyboard, SyncKeyboard, ReplayPointer,
ReplayKeyboard, AsyncBoth, or SyncBoth.
Specifies the time when the grab should take place. Pass either a timestamp,
expressed in milliseconds, or the constant CurrentTime.
XAllowEvents releases the events queued in the server since the last XAllowEvents call
for the same device and by the same client. Events are queued in the server (not released to
Xlib to propagate into Xlib's queues) only when the client has caused a device to "freeze"
(by grabbing the device with mode GrabModeSync). The request has no effect if time is
earlier than the last-grab time or later than the current server time.
The event_mode argument controls what device events are released for and just how and
when they are released. The event mode is interpreted as follows:
--
AsyncPointer If XAllowEvents is called with AsyncPointer while the
pointer is frozen by the client, pointer event processing resumes
normally, even if the pointer is frozen twice by the client on behalf
of two separate grabs. AsyncPointer has no effect if the pointer
is not frozen by the client, but the pointer need not be grabbed by
the client.
AsyncKeyboard If XAllowEvents is called with AsyncKeyboard while the
keyboard is frozen by the client, keyboard event processing resumes
normally, even if the keyboard is frozen twice by the client on
behalf of two separate grabs. AsyncKeyboard has no effect if
the keyboard is not frozen by the client, but the keyboard need not
be grabbed by the client.
SyncPointer If XAllowEvents is called with SyncPointer while the
pointer is frozen by the client, normal pointer event processing con-
tinues until the next ButtonPress or ButtonRelease event is
reported to the client. At this time, the pointer again appears to
July26, 1988 47
XAIIowEvents (continued) Xlib - Input Handling
SyncKeyboard
ReplayPointer
ReplayKeyboard
SyncBoth
freeze. However, if the reported event causes the pointer grab to be
released, then the pointer does not freeze, which is the case when an
automatic grab is released by a ButtonRelease or when XGrab-
Button or XGrabKey has been called and the specified key or
button is released. SyncPointer has no effect if the pointer is
not frozen or not grabbed by the client.
If XAllowEvents is called with SyncKeyboard while the key-
board is frozen by the client, normal keyboard event processing
continues until the next KeyPress or KeyRelease event is
reported to the client. At this time, the keyboard again appears to
freeze. However, if the reported event causes the keyboard grab to
be released, then the keyboard does not freeze, which is the case
when an automatic grab is released by a ButtonRelease or
when XGrabButton or XGrabKey has been called and the
specified key or button is released. SyncKeyboard has no effect
if the keyboard is not frozen or not grabbed by the client.
This symbol has an effect only if the pointer is grabbed by the client
and thereby frozen as the result of an event. In other words,
XGrabButton must have been called and the selected button/key
combination pressed, or an automatic grab (initiated by a Button-
Press) must be in effect, or a previous XAllowEvents must
have been called with mode SyncPointer. If the
pointer_mode of the XGrabPointer was GrabModeSync,
then the grab is released and the releasing event is processed as if it
had occurred after the release, ignoring any passive grabs at or
above in the hierarchy (towards the root) on the grab-window of the
grab just released.
This symbol has an effect only if the keyboard is grabbed by the
client and if the keyboard is frozen as the result of an event. In
other words, XGrabKey must have been called and the selected
key combination pressed, or a previous XAllowEvents must have
been called with mode SyncKeyboard. If the pointer_mode
or keyboard_mode of the XGrabKey was GrabModeSync,
then the grab is released and the releasing event is processed as if it
had occurred after the release, ignoring any passive grabs at or
above in the hierarchy (towards the root).
SyncBoth has the effect described for both SyncKeyboard and
SyncPointer. SyncBoth has no effect unless both pointer and
keyboard are frozen by the client. If the pointer or keyboard is
frozen twice by the client on behalf of two separate grabs, Sync-
Both "thaws" for both (but a subsequent freeze for SyncBoth
will only freeze each device once).
48 July 26, 1988
mXlib - User Preferences
XAutoRepeatOn
Name
XAuRepeatOnmturn onthekeyboardauto-peatkeys.
Synopsis
XAutoRepeatOn(display)
Display *display;
Arguments
display
Specifies a pointer to the Display structure; returned from X0pen-
Display.
Description
XAutoRepeat0n sets the keyboard to auto-repeat; that is, holding any non-modal key down
will result in multiple KeyPress and KeyRelease event pairs with the same keycode
member. Keys such as Shift Lock will still not repeat.
Related Commands
XGetDefault, XAutoRepeatOff, XBell, XGetKeyboardControl, XChange-
KeyboardControl, XGetPointerControl.
July 26, 1988 51
XBell
Xlib - User Preferences--
Name
XBell -- ring the bell (Conlxol G).
Synopsis
XBell (display, percent)
Display *display;
int percent ;
Arguments
display
percent
Description
Specifies a pointer to the Display sucture; returned from XOpenDisplay.
Specifies the volume for the bell, relative to the base volume set with
XChangeKeyboardControl. Possible values are -100 (off), through 0
(base volume), to 100 (loudest) inclusive.
Rings the bell on the keyboard at a volume relative to the base volume for the keyboard, if
possible, percent can range from -100 to 100 inclusive (else a BadValue error). The
volume at which the bell is rung when percent is nonnegative is:
volume = base - [ (base * percent) / i00] + percent
and when percent is negative:
volume = base + [ (base * percent) / i00]
To change the base volume of the bell, set the bell_percent variable of XChange-
Keyboa rdCont re i.
Errors
BadValue
percent <-I00 or percent >I00.
Related Commands
XGetDefault, XAutoRepeatOff, XAutoRepeatOn, XGetKeyboardControl,
XChangeKeyboardControl, XGetPointerControl.
52 July 26, 1988
XChangeGC
Xlib - Graphics Context B
Name
XChangeGC m change the components of a given graphics context.
Synopsis
XChangeGC (display, gc, valuemask,
Display *display;
GC gc ;
unsigned long valuemask;
XGCValues * values ;
val ues )
Arguments
display
gc
valuemask
val ues
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the graphics context.
Specifies the components in the graphics context that you want to change.
This argument is the bitwise OR of one or more of the GC component
masks.
Specifies a pointer to the XGCValues structure.
XChangeGC changes any or all of the components of a GC. The valuemask specifies
which components are to be changed; it is made by combining any number of the mask sym-
bols listed in the Structures section using bitwise OR ([). The values structure contains the
values to be set. These two arguments operate just like they do in XCreateGC. Changing
the clip_mask overrides any previous XSetClipRectangles request for this GC.
Changing the dash_offset or dash_list overrides any previous XSetDashes request
on this GC.
Since consecutive changes to the same GC are buffered, there is no performance advantage to
using this routine over the routines that set individual members of the GC.
Even if an error occurs, a subset of the components may have already been altered.
For more information, see Volume One: Chapter 5, The Graphics Context; and Chapter 6,
Drawing Graphics and Text.
Structures
typedef struct {
int function;
unsigned long plane_mask;
unsigned long foreground;
unsigned long background;
int line width;
--
int line_style;
int cap_style;
int join_style;
int fill_style;
int fill rule;
--
/* logical operation */
/* plane mask */
/* foreground pixel */
/* background pixel */
/* line width */
/* LineSolid, LineOnOffDash, LineDoubleDash */
/* CapNotLast, CapButt, CapRound, CapProjecting */
/* JoinMiter, JoinRound, JoinBevel */
/* FillSolid, FillTiled, FillStippled */
/* EvenOddRule, WindingRule */
54 Ju26 1988
Xlib - Graphics Context (continued) XChangeGC
int arc mode;
--
Pixmap tile;
Pixmap stipple;
int ts x origin;
int ts y origin;
Font font;
int subwindow mode;
--
Bool graphics_exposures;
int clip_x_origin;
int clip y origin;
Pixmap clip_mask;
int dash offset;
--
char dashes;
} XGCValues;
#define GCFunction
#define GCPlaneMask
#define GCForeground
#define GCBackground
#define GCLineWidth
#define GCLineStyle
#define GCCapStyle
#define GCJoinStyle
#define GCFillStyle
#define GCFilIRule
#define GCTile
#define GCStipple
#define GCTileStipXOrigin
#define GCTileStipYOrigin
#define GCFont
#define GCSubwindowMode
#define GCGraphicsExposures
#define GCClipXOrigin
#define GCClipYOrigin
#define GCClipMask
#define GCDashOffset
#define GCDashList
#define GCArcMode
Errors
BadAlloc
BadFont
BadGC
BadMatch
BadP ixmap
BadValue
/* ArcChord, ArcPieSlice */
/* tile pixmap for tiling operations */
/* stipple 1 plane pixmap for stipping */
/* offset for tile or stipple operations */
/* default text font for text operations */
/* ClipByChildren, IncludeInferiors */
/* generate events on XCopy, Area, XCopyPlane*/
/* origin for clipping */
/* bitmap clipping; other calls for rects */
/* patterned/dashed line information */
(IL<<0)
(IL<<I)
(IL<<2)
(IL<<3)
(IL<<4)
(IL<<5)
(IL<<6)
(IL<<7)
(IL<<8)
(IL<<9)
(IL<<I0)
(IL<<II)
(IL<<I2)
(IL<<I3)
(IL<<I4)
(IL<<I5)
(IL<<I6)
(IL<<I7)
(IL<<I8)
(IL<<I9)
(IL<<20)
(IL<<21)
(IL<<22)
July 26, 1988 55
XChangeGC (continued) Xlib - Graphics Context
Related Commands
XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, XSet-
TSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFill-
Rule, XSetFillStyle, XSetForeground, XSetBackground, XSetFunction,
XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin,
XSetClipRectangles, XSetRegion, XSetState, XSetSubwindowMode,
DefaultGC.
56 July 26 1988
XChangeKeyboardMapping (continued) Xlib- Keyboard
Errors
BadAlloc
BadValue first, keycode less an display->min_keycode.
di sp I ay->ma x_ke yc ode exceeded (see above).
Related Commands
XDe leteModi fie rmapEnt ry, XInse rtModi fie rmapEnt ry, XF reeModi fie rmap,
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifier-
Map, XQueryKeymap, XStringToKeysym, XLookupKeysym, XRebindKeySym,
XGetKeyboa rdMapping, XRe f re shKeyboa rdMapping, XLookupSt ring, XSet-
Modi fie rMapping, XGetModi fie rMapping.
60 July 26, 1988
XChangePointerControl (continued) Xlib - Pointers
Related Commands
XQueryPointer, XWarpPointer, XGrabPointer, XChangeActivePointerGrab,
XUngrabPointer, XGetPointerMapping, XSetPointerMapping, XGetPointer-
Control.
62 July 26, 1988
mXlib - Window Save Set
XChangeSaveSet
Name
XChangeSaveSet -- add or remove a subwindow from the client's save-set
Synopsis
XChangeSaveSet ( display, w, change_mode)
Display *display;
Window w;
int change_mode ;
Arguments
display
Specifies a pointer D the Display sucture; returned from XOpen-
Display.
Specifies the ID of the window whose children you want to add or remove
from the client's save-set; it must have been created by some other client.
change_mode Specifies the mode. Pass one of these constant: SetModeInsert (adds
the window to this client's save-set) or SetModeDelete (deletes the win-
dow from this client's save-set).
Description
XChangeSaveSet controls the longevity of subwindows, which are normally destroyed
when the parent is destroyed.
The save-set of a client is a list of other client's windows which, if they are inferiors of one of
the client's windows at connection close, should not be destroyed and should be remapped if
they are unmapped. For example, a window manager which wants to add decoration to a win-
dow by adding a "frame," might reparent an application's window to the "frame window."
When the frame is destroyed, the application's window should not also be destroyed, but
should be returned to its previous place in the window hierarchy.
Windows are removed automatically from the save-set by the server when they are destroyed.
For each window in the client's save-set, if the window is an inferior of a window created by
the client, the save-set window is reparented to the closest ancestor such that the save-set win-
dow is not an inferior of a window created by the client. If the save-set window is unmapped,
a MapWindow request is performed on it. After save-set processing, all windows created by
the client are destroyed. -For each nonwindow resource created by the client, the appropriate
Free request is performed. All colors and colormap entries allocated by the client are freed.
For more information on save-sets, see Volume One, Chapter 13, Other Programming Tech-
niques.
Errors
BadMatch
BadValue
BadWindow
w not created by some other client.
Related Commands
XAddToSaveSet, XRemoveFromSaveSet.
July 26, 1988 65
XChangeWindowAttributes
Xlib - Window Attributes m
Name
XChangeWindowAttdbutes m set window attributes.
Synopsis
XChangeWindowAttributes(display, w, valuemask,
Display *display;
Window w;
unsigned long valuemask;
XSetWindowAttributes *attributes;
attributes)
Arguments
di spl ay
Specifies a pointer to the Display structure; returned from X0pen-
Display.
w Specifies the window ID.
valuemask Specifies which window attributes are defined in the attributes argu-
ment. The mask is made by combining the appropriate mask symbols listed
in the Structures section using bitwise OR ([). If valuemask is 0, the rest
is ignored, and attributes is not referenced. The values and restrictions
are the same as for XCreateWindow.
attributes Window attributes to be changed. The valuemask indicates which
members in this structure are referenced.
Description
XChangeWindowAttributes changes any or all of the window attributes that can be
changed. For descriptions of the window attributes, see Volume One, Chapter 4, Window
Attributes.
Changing the background does not cause the window contents to be changed. Use XClear-
Window to cause the background to be repainted. Setting the border or changing the back-
ground such that the border tile origin changes causes the border to be repainted. Changing
the background of a root window to None or ParentRelative restores the default back-
ground pixmap. Changing the border of a root window to CopyFromParent restores the
default border pixmap.
Changing the win_gravity does not affect the current position of the window. Changing
the backing_store of an obscured window to WhenMapped or Always may have no
immediate effect. Also changing the backing_planes, backing._pixel, or
save_under of a mapped window may have no immediate effect.
Multiple clients can select input on the same window; the event_mask passed are disjoint.
When an event is generated it will be reported to all interested clients. Therefore, the setting of
the event_mask attribute by one client will not affect the event_mask of others on the
same window. However, at most, one client at a time can select each of Substructure-
RedirectMask, ReSizeRedirectMask, and ButtonPressMask on any one window.
If a client attempts to select on SubtructureRedirectMask, ResizeRedirectMask,
66 July26, 1988
Xlib - Window Attributes (continued) XChangeWindowAttributes
or ButtonPressMask and some other client has already selected it on the same window,
the X server generates a BadAccess error.
There is only one do_not_propagate_mask for a window, not one per client.
Changing the colormap attribute of a window generates a ColormapNotify event. Chang-
ing the colormap attribute of a visible window may have no immediate effect on the screen
(because the map may not be installed until the window manager or client calls XTnstall-
Colormap).
Changing the cursor of a root window to None restores the default cursor.
For more information, see Volume One: Chapter 2, X Concepts; and Chapter 4, Window Attri-
butes.
Structures
/.
* Data structure for setting window attributes.
*/
typedef struct {
Pixmap background_pixmap; /*
unsigned long background_pixel; /*
Pixmap border_pixmap; /*
unsigned long border_pixel; /*
int bit_gravity; /*
int win_gravity; /*
int backing_store; /*
unsigned long backing_planes; /*
unsigned long backing_pixel; /*
Bool save under; /*
--
long event mask; /*
--
long do_not_propagate_mask; /*
Bool override redirect; /*
--
Colormap colormap; /*
Cursor cursor; /*
} XSetWindowAttributes;
pixmap, None, or ParentRelative */
background pixel */
pixmap, None, or CopyFromParent */
border pixel value */
one of bit gravity values */
one of the window gravity values */
NotUseful, WhenMapped, Always */
planes to be preseved if possible */
value to use in restoring planes */
should bits under be saved (popups) */
set of events that should be saved */
set of events that should not propagate
override redirected config request */
colormap to be associated with window */
cursor to be displayed (or None) */
/* Definitions for valuemask argument of CreateWindow and ChangeWindowAttributes *j
#define'CWBackPixmap (IL<<0)
#define CWBackP ixel (IL<<I)
#define CWBorderP ixmap (IL<<2)
#define CWBorderP ixel (IL<<3)
#define CWBitGravity (IL<<4)
#define CWWinGravity (IL<<5)
#define CWBackingStore (IL<<6)
#define CWBackingPlanes (IL<<7)
#define CWBackingPixel (IL<<8)
#define CWOverrideRedirect (IL<<9)
#define CWSaveUnder (IL<<I0)
#define CWEventMask (IL<<II)
#define CWDontPropagate (IL<<I2)
#define CWColormap (IL<<I3)
#define CWCursor (IL<<I4)
July 26, 1988 67
XChangeWindowAttributes (continued) Xlib - Window Attributes
Errors
BadAccess
BadColor
BadCursor
BadMatch
BadP ixmap
BadValue
BadWindow
Related Commands
XGetWindowAtt ributes, XSetWindowBackground, XSetWindowBackground-
P ixmap, XS etWindowBo rde r, XS etWindowBo rde rP ixmap, XGetGeomet ry.
68 July 26, 1988
--Xlib - Input Handling
XChecklfEvent
Name
XChecklfEvent -- check the event queue for a matching event.
Synopsis
Bool XCheckIfEvent (display,
Display *display;
XEvent *event ;
Bool (*predicate) () ;
char *args;
event, predicate, args)
/* RETURN */
Arguments
display
e ven t
predicate
arg
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Returns the matched event.
Specifies the procedure that is called to determine if the next event matches
your criteria.
Specifies the user-specified argument that will be passed to the predicate pro-
cedure.
XCheckIfEvent returns the next event in the queue that is matched by the specified predi-
cate procedure. If found, that event is removed from the queue, and True is returned. If no
match is found, XCheckIfEvent returns False and flushes the output buffer. No other
events are removed from the queue. Later events in the queue are not searched.
The predicate procedure is called with the arguments display, event, and arg.
In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the
output buffer is flushed only if no matching events are found on the queue. This change is
compatible with applications written for Release 1.
For more information, see Volume One, Chapter 8, Events.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheck-
WindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent,
XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotion-
Events, XIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending,
XSynchronize, XSendEvent, QLength.
July 26, 1988 69
mXlib - Input Handling
XCheckTypedEvent
Name
XCheckTypedEvent m return the next event in queue that matches event type; don't wait.
Synopsis
Bool XCheckTypedEvent(display,
Display *display;
int event_type;
XEvent *report;
event_type, report )
/* RETURN */
Arguments
display
e yen t_ type
report
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the event type to be compared.
Returns a copy of the matched event structure.
Description
XCheckTypedEvent searches first the event queue, then the events available on the server
connection, for the specified event_type. If there is a match, it returns the associated event
structure. Events searched but not matched are not discarded. XCheckTypedEvent returns
True if the event is found. If the event is not found, XCheckTypedEvent flushes the out-
put buffer and returns False.
This command is similar to XCheckMaskEvent, but it searches through the queue instead of
inspecting only the last item on the queue. It also matches only a single event type instead of
multiple event types as specified by a mask.
In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the
output buffer is flushed only if no matching events are found on the queue. This change is
compatible with applications written for Release 1.
For more information, see Volume One, Chapter 8, Events.
Related Commands
XSelectInput, XSetIputFocus, XGetInputFocus, XWindowEvent, XCheck-
WindowEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMaskEvent,
XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, XIfEvent,
XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending,
XSynchronize, XSendEvent, QLength.
July 26, 1988 71
XCheckTypedWindowEvent
Xlib - Input Handling--
Name
XCheckTypedWindowEvent -- return the next event in queue matching type and window.
Synopsis
BOO1 XCheckTypedWindowEvent (display, w, event_type, report)
Display *display;
Window w;
int event_type ;
XEvent *report ; /* RETURN */
Arguments
display
w
e ve t_ t ype
report
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the window ID.
Specifies the event type to be compared.
Returns the matched event's associated structure into this client-supplied
structure.
Description
XCheckTypedWindowEvent searches first the event queue, then any events available on
the server connection, for an event that matches the specified window and the specified event
type. Events searched but not matched are not discarded.
XCheckTypedWindowEvent returns True if the event is found; it flushes the output
buffer and returns False if the event is not found.
In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the
output buffer is flushed only if no matching events are found on the queue. This change is
compatible with applications written for Release 1.
For more information, see Volume One, Chapter 8, Events.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheck-
WindowEvent, XCheckTypedEvent, XMaskEvent, XCheckMaskEvent, XNext-
Event, XEventsQueued, XAllowEvents, XGetMotionEvents, XIfEvent,
XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending,
XSynchronize, XSendEvent, QLength.
72 July 26, 1988
XCirculateSubwindows
Xlib - Window Manipulation
Name
XCirculateSubwindows -- circulate the slacking order of children up or down.
Synopsis
XCirculateSubwindows (display, w, direction)
Display *display;
Window w;
int direction;
Arguments
display
w
direction
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the window ID of the parent of the subwindows to be circulated.
Specifies the direction (up or down) that you want to circulate the children.
Pass either RaiseLowest or LowerHighest.
XCirculateSubwindows circulates the children of the specified window in the specified
direction, either RaiseLowest or LowerHighest. If some other client has selected
SubstructureRedirectMask on the specified window, then a CirculateRequest
event is generated, and no further processing is performed. If you specify RaiseLowest,
this function raises the lowest mapped child (if any) that is occluded by another child to the
top of the slack. If you specify LowerHighest, this function lowers the highest mapped
child (if any) that occludes another child to the bottom of the slack. Exposure processing is
performed on formerly obscured windows.
For more information, see Volume One, Chapter 14, Window Management.
Errors
BadValue
BadWindow
Related Commands
XLowerWindow, XRaiseWindow, XCirculateSubwindowsDown, XCirculate-
SubwindowsUp, XRestackWindows, XMoveWindow, XResizeWindow, XMove-
ResizeWindow, XReparentWindow, XConfigureWindow, XQueryTree.
74 July 26, 1988
mXlib - Window Manipulation
XCirculateSubwindowsDown
Name
XCirculateSubwindowsDown -- circulate the bottom child to the top of the stacking order.
Synopsis
XCirculateSubwindowsDown ( display, w)
Display *display;
Window w;
Arguments
display
w
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the window ID of the parent of the windows to be circulated.
XCirculateSubwindowsDown lowers the highest mapped child of the specified window
that partially or completely obscures another child. The lowered child goes to the bottom of
the stack. Completely unobscured children are not affected.
This function generates exposure events on any window formerly obscured. Repeated execu-
tions lead to round-robin lowering. This is equivalent to XCirculateSubwindows
(display, w, LowerHighest).
If some other client has selected SubstructureRedirectMask on the window, then a
CirculateRequest event is generated, and no further processing is performed.
For more information, see Volume One, Chapter 14, Window Management.
Errors
BadWindow
Related Commands
XLowerWindow, XRaiseWindow, XCirculateSubwindows, XCirculate-
SubwindowsUp, XRestackWindows, XMoveWindow, XResizeWindow, XMove-
ResizeWindow, XReparentWindow, XConfigureWindow, XQueryTree.
July 26, 1988 75
XCirculateSubwindowsUp
Xlib - Window Manipulation
Name
XCirculateSubwindowsUp -- circulate the top child to the bottom of the stacking order.
Synopsis
XCirculateSubwindowsUp (display, w)
Display *display;
Window w;
Arguments
display
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the window ID of the parent of the windows to be circulated.
Description
XCirculateSubwindowsUp raises the lowest mapped child of the specified window that
is partially or completely obscured by another child. The raised child goes to the top of the
stack. Completely unobscured children are not affected. This generates exposure events on
the raised child (and its descendents, if any). Repeated executions lead to round robin-raising.
This is equivalent to XCirculateSubwindows (display, w, RaiseLowest).
If some other client has selected SubstructureRedirectMask on the window, then a
CirculateRequest event is generated, and no further processing is performed.
For more information, see Volume One, Chapter 14, Window Management.
Errors
BadWindow
Related Commands
XLowerWindow, XRaiseWindow, XCirculateSubwindows, XCirculate-
SubwindowsDown, XRestackWindows, XMoveWindow, XResizeWindow, XMove-
ResizeWindow, XReparentWindow, XConfigureWindow, XQueryTree.
76 July 26 1988
XClearArea (continued) Xlib - Drawing Primitives
Window
Window
[x,y] width
.
[x, y] width = 0
Errors
BadMatch
BadValue
BadWindow
Window
Ix, y] width
Window
[x,y] width=O
0
Window is an InputOnly class window.
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDraw-
Point, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments,
XCopyArea, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFill-
Rectangle, XFillRectangles, XClearWindow.
78 July 26, 1988
mXlib- Drawing Primitives
XClearWindow
Name
XClearWindow -- clear an entire window.
Synopsis
XClearWindow(display,
Display *display;
Window w;
w)
Arguments
display
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the ID of the window to be cleared.
Description
XClearWindow clears a window, but does not cause exposure events. This function is
equivalent to XClearArea ( display, w, O, O, O, O, False) .
If the window has a defined 5ackground file or it is ParentRelative, the rectangle is filed
with a plane_mask of all l's and function of GXcopy. If the window has 5ackground
None, the contents of the window are not changed.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Errors
BadMatch
BadValue
BadWindow
If w is an InputOnly class window.
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDraw-
Point, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments,
XCopyArea, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFill-
Rectangle, XFillRecgangles, XClearArea.
July 26, 1988 79
Xlib - Window Manipulation (continued) XConfigureWindow
Exposure processing is performed on formerly obscured windows, including the window itself
and its inferiors, if regions of them were obscured but now are not. As a result of increasing
the width or height, exposure processing is also performed on any new regions of the window
and any regions where window contents are lost.
The members of XWindowChanges that you specify in values are:
x
Y
width
height
Specify the x and y coordinates of the upper-left outer corner of the window
relative to the parent's origin.
Specify the inside size of the window in pixels, not including the border.
These arguments must be positive.
border width
--
Specifies the width of the border in pixels.
sibling
stack mode
--
Specifies the sibling window for stacking operations. If not specified, no
change in the stacking order will be made. If specified, stack_mode must
also be specified.
The stack mode can be any ofthese constants: Above, Below, TopIf,
BottomIf, orOpposite.
The computation for the BottomIf, TopIf, and Opposite stacking modes is performed
with respect to window w's final size and position (as conxolled by the other arguments to
XConfigureWindow, not its initial position.) It is an error if sibling is specified without
stack mode. If sibling and stack mode are specified, the window is restacked as fol-
-- --
lows:
Stacking Flag
Above
Below
TopIf
BottomIf
Opposite
Position
w is placed just above sibling
w is placed just below sibling
if sibling obscures w, then w is placed at the top
of the stack
if w obscures sibling, then w is placed at the bot-
tom of th6 stack
if sibling occludes w, then w is placed at the top
of the stack, else if w occludes sibling, then w is
placed at the bottom of the stack
July 26, 1988 83
XConfigureWindow (continued) Xlib - Window Manipulation
If a stack_mode is specified but no sibling is specified, the window is restacked as follows:
Stacking Flag
Above
Below
TopIf
BottomIf
Opposite
Position
w is placed at the top of the stack
w is placed at the bottom of the stack
if any sibling obscures w, then w is placed at the top
of the stack
if w obscures any sibling, then window is placed at
the bottom of the stack
if any sibling occludes w, then w is placed at the top
of the stack, else if w occludes any sibling, then w is
placed at the bottom of the stack
Structures
typedef struct {
int x, y;
int width, height;
int border width;
--
Window sibling;
int stack mode;
--
} XWindowChanges;
/* ConfigureWindow structure */
/* ChangeWindow value bits definitions for valuemask */
#define CWX (I<<0)
#define CWY (I<<I)
#define CWWidth (1<<2)
#define CWHeight (1<<3)
#define CWBorderWidth (1<<4)
#define CWSibling (1<<5)
#define CWStackMode (1<<6)
Errors
BadMatch
BadValue
BadWindow
Nonzero border_width of InputOnly window.
sibling specified without a stack mode.
--
The sibling window is not actually a sibling.
width or height is O.
Related Commands
XLowerWindow, XRaiseWindow, XCirculateSubwindows, XCirculate-
SubwindowsDown, XCirculateSubwindowsUp, XRestackWindows, XMove-
Window, XResizeWindow, XMoveResizeWindow, XReparentWindow, XQuery-
Tree.
84 July 26, 1988
XConvertSelection (continued) Xlib - Selections
Related Commands
XSetSelectionOwner, XGetSelect ionOwner.
86 July 26, 1988
mXlib- Drawing Primitives
XCopyArea
Name
XCopyArea -- copy an area of a drawable.
Synopsis
XCopyArea(display, src,
height, dest x,
--
Display *display;
Drawable src, dest;
GC gc;
int src_x, src_y;
unsigned int width, height;
int dest_x, dest_y;
dest , gc, src_x, src_y, width,
de s t_y )
Arguments
display
src
dest
gc
src x
--
src_y
width
height
dest x
--
dest_y
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specify the source and destination rectangles to be combined, src and
dest must have the same root and depth.
Specifies the graphics context.
Specify the x and y coordinates of the upper-left comer of the source rectan-
gle relative to the origin of the source drawable.
Specify the dimensions in pixels of both the source and destination rectan-
gles.
Specify the x and y coordinates within the destination window.
Description
XCopyArea combines the specified rectangle of src with the specified rectangle of dest.
src and dest must have the same root and depth.
If regio.ns of the source rectangle are obscured and have not been retained in
backing_store, or if regions outside the boundaries of the source drawable are specified,
then those regions are not copied. Instead, the following occurs on all corresponding destina-
tion regions that are either visible or are retained in backing_store. If dest is a window
with a background other than None, the corresponding regions of the destination are tiled
(with plane__mask of all l's and function GXcopy) with that background. Regardless of til-
ing, if the destination is a window and graphics_exposure in gc is True, then
GraphicsExpose events for all corresponding destination regions are generated. If
graphics_exposure is True but no regions are exposed, then a NoExpose event is gen-
erated.
If regions of the source rectangle are not obscured and graphics_exposure is False,
one NoExpose event is generated on the destination.
July 26, 1988 8 7
--Xlib - Colormaps
XCopyColormapAndFree
Name
XCopyColormapAndFree -- copy a colormap and return a new colormap ID.
Synopsis
Colormap XCopyColormapAndFree ( display, cmap)
Display *display;
Colormap cmap ;
Arguments
display
cmap
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the colormap you are moving out of.
XCopyColormapAndFree is used to obtain a new virtual colormap when allocating color-
cells out of a previous colormap has failed due to resource exhaustion (that is, too many cells
or planes were in use in the original colormap).
XCopyColormapAndFree moves all of the client's existing allocations from cmap to the
returned Colormap and frees those entries in cmap. Values in other entries of the new
colormap are undefined. The visual type and screen for the new colormap is the same as for
the old.
If cmap was created by the client with the alloc argument set to AllocAll, the new color-
map is also created with AllocAll, all color values for all entries are copied from cmap,
and then all entries in cmap are freed.
If cmap was created by the client with AllocNone, the allocations to be moved are all those
pixels and planes that have been allocated by the client using XAllocColor, XAlloc-
NamedColor, XAllocColorCells, or XAllocColorPlanes and that have not been
freed since they were allocated.
For more information, see Volume One, Chapter 7, Color.
Errors
BadAlloc
BadColor
Related Commands
XCreateColormap, XFreeColormap, XGetStandardColormap, XInstall-
Colormap, XUninstallColormap, XSetStandardColormap, XListInstalled-
Colormaps, XSetWindowColormap, DefaultColormap, DisplayCells.
July 26, 1988 89
XCopyGC
Xlib - Graphics Context--
Name
XCopyGC -- copy a graphics context.
Synopsis
XCopyGC(display, src, valuemask,
Display *display;
GC src, dest;
unsigned long valuemask;
dest)
Arguments
display
src
valuemask
dest
Specifies a pointer to the Display sucture; retumed from XOpen-
Display.
Specifies the components of the source graphics context.
Specifies the components in the source GC structure to be copied into the
destination GC. va2uemask is made by combining any number of the
mask symbols listed in the Structures section using bitwise OR (1).
Specifies the destination graphics context.
Description
XCopyGC copies the selected elements of one graphics context to another. See Volume One,
Chapter 5, The Graphics Context, for a description of the graphics context.
Structures
The GC structure contains the following elements:
/*
* Data structure for setting graphics context.
*/
typedef struct {
int function;
unsigned long plane_mask;
unsigned long foreground;
unsigned long background;
int line width;
_
int line_style;
int cap_style;
int join_style;
int fill_style;
int fill rule;
int arc mode;
Pixmap tile;
Pixmap stipple;
int ts x origin;
int ts_y_origin;
Font font;
int subwindow_mode;
/* logical operation */
/* plane mask */
/* foreground pixel */
/* background pixel */
/* line width */
/* Solid, OnOffDash, DoubleDash */
/* NotLast, Butt, Round, Projecting */
/* Miter, Round, Bevel */
/* Solid, Tiled, Stippled */
/* EvenOdd, Winding */
/* PieSlice */
/* tile pixmap for tiling operations */
/* stipple 1 plane pixmap for stipping */
/* offset for tile or stipple operations */
/* default text font for text operations */
/* ClipByChildren, IncludeInferiors */
90 July 26, 1988
XCopyPlane
Xlib- Drawing Primitives m
Name
XCopyPlane -- copy a single plane of a drawable into a drawable with depth, applying pixel
values.
Synopsis
XCopyPlane (display, src, dest, go, src_x, src_y, wldth,
height, dest_x, dest_y, plane)
Display *display;
Drawable src, dest;
GC gc ;
int src_x, src_y;
unsigned int width, height ;
int dest_x, dest_y;
unsigned long plane;
Arguments
di spl ay
src
dest
gc
src x
--
src_y
width
height
dest x
--
dest_y
plane
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specify the source and destination drawables.
Specifies the graphics context.
Specify the x and y coordinates of the upper-left corner of the source rectan-
gle relative to the origin of the drawable.
Specify the width and height in pixels. These are the dimensions of both the
source and destination rectangles.
Specify the x and y coordinates at which the copied area will be placed rela-
tive to the origin of the destination drawable.
Specifies the source bit-plane. You must set exactly one bit.
XCopyPlane copies a single plane of a rectangle in the source into the entire depth of a
corresponding rectangle in the destination. The plane of the source drawable and the
foreground/background pixel values in gc are combined to form a pixmap of the same
depth as the destination drawable, and the equivalent of an XCopyArea is performed, with all
the same exposure semantics.
XCopyPlane uses these graphics context component: function, plane_mask,
foreground, background, subwindow_mode, graphics_exposures,
clip x origin, clip_y_origin, and clip_mask.
src and dest must have the same root, but need not have the same depth.
For more information, see Volume One, Chapter 5, The Graphics Context.
92 July 26, 1988
Xlib- Drawing Primitives (continued) XCopyPlane
Errors
BadDrawable
BadGC
BadMatch
BadValue
src and dest do not have the same root.
plane does not have exactly one bit set.
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDraw-
Point, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments,
XCopyArea, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFill-
Rectangles, XClearArea, XClearWindow.
July 26, 1988 93
XCreateAssocTable
Xlib - Association Tables m
Name
XCreateAssocTable -- create a new association table (X10).
Synopsis
XAssocTable *XCreateAssocTable(size)
int size;
Arguments
si ze Specifies the number of buckets in the hashed association table.
Description
XCreateAssocTable creates an association table, which allows you to associate your own
structures with X resources in a fast lookup table. This function is provided for compatibility
with X Version 10. To use it you must include the file <Xll/XIO.h> and link with the library
-loldX.
The size argument specifies the number of buckets in the hash system of XAssocTable.
For reasons of efficiency the number of buckets should be a power of two. Some size sugges-
tions might be: use 32 buckets per 100 objects; a reasonable maximum number of object per
buckets is 8.
If there is an error allocating memory for the XAssocTable, a NULL pointer is returned.
For more information on association tables, see Volume One, Chapter 13, Other Programming
Techniques.
Structures
typedef struct {
XAssoc *buckets;
int size;
} XAssocTable;
/* pointer to first bucket in array */
/* table size (number of buckets) */
Related Commands
XDeleteAssoc, XDestroyAssocTable, XLookUpAssoc, XMakeAssoc.
94 July26, 1988
mXlib - Pixmaps and Tiles
X Crea te B it m ap F rom Data
Name
XCreateBitmapFromData -- create a bitmap from X11 bitmap format data.
Synopsis
Pixmap XCreateBitmapFromData ( display,
width, height)
Display *display;
Drawable drawable ;
char *data;
unsigned int width, height ;
dra wabl e, da t a,
Arguments
di spl ay
dra wabl e
data
wi dth
height
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the drawable. This determines which screen to create the bitmap
on.
Specifies the location of the bitmap data.
Specify the dimensions in pixels of the created bitmap. If smaller than the
original bitmap, the upper-left corner is used.
Description
XCreateBitmapFromData creates a single-plane pixmap from an array of hexadecimal
data. This data may be defined in the program or included. The bitmap data must be in X
version 11 format as shown below (it cannot be in X10 format). The following format is
assumed for the data, where the variables are members of the xImage structure described in
Volume One, Chapter 6, Drawing Graphics and Text:
format=XYPixmap
bit order=LSBFirst
byte_order=LSBFirst
bitmap_unit=8
bitap_pad=8
xoffset=0
no extra bytes per line
XCreateBitmapFromData creates an image with the spifi data and copies it into the
created pixmap. The following is an example of creating a bitmap:
July 26, 1988 95
XCreateBitmapFromData (continued) Xlib - Pixmaps and Tiles
#define gray_width 16
#define gray_height 16
#define gray. x hot 8
#define gray_y_hot 8
static char gray_bits [ ] --
{
0xf81f, 0xe3c7, 0xcff3, 0x9ff9,
0xbffd, 0x33cc, 0x7ffe, 0x7ffe,
0x7e7e, 0x7ffe, 0x37ec, 0xbbdd,
0x9c39, 0xcff3, 0xe3c7, 0xf81f
};
Pixmap XCreateBitmapFromData (display, window, gray_bits,
gray_width, gray_height) ;
If insufficient working storage was ]located, XCreateBitmapFromData returns NULL.
The user should free the bitmap using XFreePixmap when it is no longer needed.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Errors
BadAlloc
Related Commands
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindow-
BackgroundPixmap, XCreatePixmap, XCreatePixmapFromBitmapData, XFree-
Pixmap, XQueryBestSize, XQueryBestStipple, XWriteBitmapFile, XRead-
BitmapFile, XCreatePixmapFromBitmapData.
96 July 26 1988
mXlib - Colormaps
XCreateColormap
Name
XCreateColormap -- create a colormap.
Synopsis
Colormap XCreateColormap(display,
Display *display;
Window w;
Visual *visual;
int alloc;
w, visual, alloc)
Arguments
di spl ay
visual
a!loc
Description
Specifies a pointer to the Display structure; returned from X0pen-
Display.
Specifies a window ID. The colormap created will be associated with the
same screen as the window.
Specifies a pointer to the visual structure for the colormap. The visual
class and depth must be supported by the screen.
Specifies how many colormap entries to allocate. Pass either AllocNone
or AIIocAII.
XCreateColormap creates a colormap of the specified visual type and allocates either none
or all of its entries, and returns the colormap ID.
It is legal to specify any visual class in the structure pointed to by the visual argument. If
the class is StaticColor, StaticGray, or TrueColor, the colorcells will have pre-
allocated read-only values defined by the individual server but unspecified by the X11 proto-
col. In these cases, alloc must be specified as AllocNone (else a BadNatch error).
For the other visual classes, PseudoColor, DirectColor, and GrayScale, you can
pass either AllocAll or AllocNone tO the alloc argument. If you pass AllocNone,
the colormap has no allocated entries. This allows your client programs to allocate read-only
colorcells, with XAllocColor or read/write cells with XAllocColorCells, Alloc-
ColorPlanes and xstoreColors. If you pass the constant AllocAll, the entire color-
map is allocated writable (all the entries are read/write, nonshareable and have undefined ini-
tial values), and the colors can be set with xStoreColors. However, you cannot free these
entries with XFreeColors, and no relationships between the entries are defined.
If the visual class is PseudoColor or GrayScale and alloc is AllocAII, this function
simulates many calls to the function XAIIocColor returning all pixel values from 1 tO
(map_entries - 1). For a visual class of DirectColor, the processing for Alloc-
All simulates a call to the function XAllocColorPlanes, returning a pixel value of 0 and
mask values the same as the red mask, green, mask, and blue. mask members in
--
visual.
July 26, 1988 97
XCreateColormap (continued) Xlib- Colormaps
The visual structure should be as returned from the DefaultVisual macro, XMatch-
VisualInfo, or XGetVisualInfo. The red_mask, green_mask, and blue_mask
members specify which bits of the pixel value are allocated to each primary color. The
rnap_ent ries member specifies the number of colormap entries.
For more information on creating colormaps, see Volume One, Chapter 7, Color.
Errors
BadAlloc
BadMatch
BadValue
BadWindow
Didn't use AllocNone for StaticColor,
TrueColor.
visual type not supported on screen.
StaticGray, or
Related Commands
XCopyColormapAndFree, XFreeColormap, XGetStandardColormap, XInstall-
Colormap, XUninstallColormap, XSetStandardColormap, XListInstalled-
Colormaps, XSetWindowColormap, DefaultColormap, DisplayCells.
98 July 26, 1988
mXlib - Cursors
XCreateFontCursor
Name
XCreateFontCursor -- create a cursor from the standard cursor font.
Synopsis
#include <Xll/cursorfont.h>
Cursor XCreateFontCursor(display, shape)
Display *display;
unsigned int shape;
Arguments
display
shape
Specifies a pointer to the Display structure; returned from XOpenDisplay.
Specifies which character in the standard cursor font should be used for the cur-
sor.
Description
X provides a set of standard cursor shapes in a special font named "cursor." Programs are
encouraged to use this interface for their cursors, since the font can be customized for the indi-
vidual display type and swapped between clients.
The hotspot comes from the information stored in the font. The initial colors of the cursor are
black for the foreground and white for the background. XRecolorCursor can be
used to change the colors of the cursor to those desired.
For more information about cursors and their shapes in fonts, see Appendix I, The Cursor
Font.
July 26, 1988 99
XCreateFontCursor (continued) Xlib - Cursors
Errors
BadAlloc
BadMatch
BadValue
Related Commands
XDefineCursor, XUndefineCursor, XCreateGlyphCursor, XCreatePixmap-
Cursor, XFreeCursor, XRecolorCursor, XQueryBestCursor, XQueryBest-
Size.
1 O0 July 26, 1988
DXlib - Graphics Context
XCreateGC
Name
XCreateGC -- create a new graphics context for a given screen with the depth of the
specified drawable.
Synopsis
GC XCreateGC (display, drawable, valuemask, values)
Display *display;
Drawable drawable ;
unsigned long valuemask;
XGCValues *values;
Arguments
display
dra wabl e
valuemask
values
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the drawable.
Specifies which members of the GC are to be set using information in the
values structure, valuemask is made by combining any number of the
mask symbols listed in the Structures section.
Specifies a pointer to an xGCvalues structure which will provide com-
ponents for the new GC.
This function creates a new GC, replacing the old one if there was one. The specified com-
ponents of the new graphics context in valuetask are set to the values passed in the
values argument. Unset components default as follows:
Component
function
plane_mask
foreground
background
line width
--
line.style
cap_style
join_style
fill_style
fill rule
--
arc mode
--
tile
stipple
ts x origin
ts_y_origin
Value
GXcopy
all l's
0
0
LineSoiid
CapButt
JoinMiter
FillSolid
EvenOddRule
ArcPieSlice
Pixmap filled with reground pixel
Pixmap filled with l's
0
0
July 26, 1988 101
XCreateGC (continued) Xlib - Graphics Context
Component
font
subwindow mode
--
graphic s_expo su re s
clip_x_origin
clip_y_origin
clip_mask
dash offset
dash list
--
Value
(implementation dependent)
ClipByChildren
True
0
0
None
0
4 (i.e., the list [4, 4])
For more information, see Volume One, Chapter 5, The Graphics Context.
Structures
typedef struct {
int function;
unsigned long plane_mask;
unsigned long foreground;
unsigned long background;
int line width;
--
int line_style;
int cap_style;
int join_style;
int fill_style;
int fill rule;
--
int arc mode;
--
Pixmap tile;
Pixmap stipple;
int ts x origin;
int ts y origin;
Font font;
int subwindow mode;
--
Bool graphics_exposures;
int clip x origin;
int clip y origin;
Pixmap clip_mask;
int dash offset;
--
char dashes;
} XGCValues;
/* logical operation */
/* plane mask */
/* foreground pixel */
/* background pixel */
/* line width */
/* LineSolid, LineOnOffDash, LineDoubleDash */
/* CapNotLast, CapButt, CapRound, CapProjecting */
/* JoinMiter, JoinRound, JoinBevel */
/* Fill$olid, FillTiled, FillStippled */
/* EvenOddRule, WindingRule */
/* ArcPieSlice, ArcChord */
/* tile pixmap for tiling operations */
/* stipple 1 plane pixmap for stipping */
/* offset for tile or stipple operations */
/* default text font for text operations */
/* ClipByChildren, IncludeInferiors */
/* generate events on XCopyArea, XCopyPlane */
/* origin for clipping */
/* bitmap clipping; other calls for rects */
/* patterned/dashed line information */
#define GCFunction
#define GCPlaneMask
#define GCForeground
#define GCBackground
#define GCLineWidth
#define GCLineStyle
#define GCCapStyle
#define GCJoinStyle
#define GCFillStyle
#define GCFilIRule
#define GCTile
(IL<<0)
(IL<<I)
(IL<<2)
(IL<<3)
(IL<<4)
(IL<<5)
(IL<<6)
(IL<<7)
(IL<<8)
(IL<<9)
(IL<<I0
102 July 26, 1988
Xlib - Graphics Context (continued) XCreateGC
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
GCStipple
GCTileStipXOrigin
GCTileStipYOrigin
GCFont
GCSubwindowMode
GCGraphicsExposures
GCClipXOrigin
GCClipYOrigin
GCClipMask
GCDashOffset
GCDashList
GCArcMode
IL<<II)
IL<<I2)
IL<<I3)
IL<<I4)
IL<<I5)
IL<<I6)
IL<<I7)
IL<<I8)
IL<<I9)
IL<<20)
IL<<21)
IL<<22)
Errors
BadAlloc
BadDrawable
BadFont
BadMatch
BadPixmap
BadValue
Related Commands
XChangeGC, XCopyGC, XFreeGC, XGContextFromGC, XSetStipple, XSet-
TSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFill-
Rule, XSetFillStyle, XSetForeground, XSetBackground, XSetFunction,
XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin,
XSetClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
July 26, 1988 103
XCreateGlyphCursor
Xlib - Cursors
Name
XCreateGlyphCursor -- create a cursor from font glyphs.
Synopsis
Cursor XCreateGlyphCursor (display, source_font,
source_char, mask_char, foreground_color,
ba ckground_col or)
Display *display;
Font source font, mask font;
__ --
unsigned int source_char, mask_char;
XColor *foreground_color;
XColor *background_color;
mask font,
--
Arguments
display
source font
--
mask font
--
source char
--
mask char
--
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the font from which a character is to be used for the cursor.
Specifies the mask font. Optional; specify 0 if not needed.
Specifies the index into the cursor shape font.
Specifies the index into the mask shape font. Optional; specify 0 if not
needed.
foreground_color
Specifiesthered, green, andblue(RGB) values rthe reground.
background_color
Specifies the red, green, and blue (RGB) values for the background.
Description
XCreateGlyphCursor is similar to XCreatePixmapCursor, but the source and mask
bitmaps are obtained from separate font characters, perhaps in separate fonts. The mask font
and character are optional. If mask char is not specified, all pixels of the source are
--
displayed.
The x offset for the hotspot of the created cursor is the left-bearing for the source character,
and the y offset is the ascent, each measured from the upper-left corner of the bounding rectan-
gle of the character.
The origins of the source and mask (if it is defined) characters are positioned coincidently and
define the hotspot. The source and mask need not have the same bounding box metrics, and
there is no restriction on the placement of the hotspot relative to the bounding boxes.
Note that source_char and mask_char are of type unsigned int, not of type
XChar2b. For two-byte matrix fonts, the 16-bit value should be formed with the bytel
member in the most significant byte and the byte2 member in the least significant byte.
104 July 26, 1988
Xlib- Cursors (continued) XCreateGlyphCursor
You can free the fonts with XFreeFont if they are no longer needed after creating the glyph
cursor.
For more information on fonts and cursors, see Volume One, Chapter 6, Drawing Graphics
and Text.
Structures
typedef struct {
unsigned long pixel;
unsigned short red, green, blue;
char flags;
char pad;
} XColor;
/* DoRed, DoGreen, DoBlue */
Errors
BadAlloc
BadFont
BadValue
source char not defined in source font.
-- --
mask char not defined in mask font (if mask font defined).
Related Commands
XDefineCursor, XUndefineCursor, XCreateFontCursor, XCreatePixmap-
Cursor, XFreeCursor, XRecolorCursor, XQueryBestCursor, XQueryBest-
Size.
July 26, 1988 105
XCreatelmage
Xlib - Images m
Name
XCreatelmage m allocate memory for an XImage structure.
Synopsis
#include <Xll/Xutil .h>
XImage *XCreateImage (display, visual, depth, format, offset,
data, width, height, bitmap_pad, bytes per_line)
Display *display;
Visual *visual;
unsigned int depth;
int format ;
int offset ;
char *data;
unsigned int width;
unsigned int height;
int bitmap_pad;
int bytes__per_line ;
Arguments
display
visual
depth
format
offset
data
width
height
bitmap_pad
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies a pointer to a visual that should match the visual of the window the
image is to be displayed in.
Specifies the depth of the image.
Specifics the format for the image. Pass one of these constants: xYPixmap,
or ZPixmap.
Specifies the number of pixels beyond the beginning of the data (pointed to
by data) where the image actually begins. This is useful if the image is not
aligned on an even addressable boundary.
Specifies a pointer to the image data.
Specify the width and height in pixels of the image.
Specifies the quantum of a scan line. In other words, the start of one scan
line is separated in client memory from the start of the next scan line by an
integer multiple of this many bits. You must pass one of these values: 8,
16, or 32.
bytes__per_line
Specifies the number of bytes in the client image between the start of one
scan line and the start of the next. If you pass a value of 0 here, Xlib
assumes that the scan lines are contiguous in memory and thus calculates the
value of bytes, per_line itself.
106 July 26, 1988
XCreatePixmap
Xlib - Pixmaps and Tiles m
Name
XCreatePixmap -- create a pixmap.
Synopsis
Pixmap XCreatePixmap (display, drawable,
Display *display;
Drawable drawable;
unsigned int width, height ;
unsigned int depth;
width, height,
depth)
Arguments
display
dra wabl e
width
height
depth
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the drawable. May be an InputOnly window.
Specify the width and height in pixels of the pixmap. The values must be
nonzero.
Specifies the depth of the pixmap. The depth must be supported by the
screen of the specified drawable.
xCreatePixmap creates a pixmap resource and returns its pixmap ID. The initial contents
of the pixmap are undefined.
The server uses the drawable argument to determine which screen the pixmap is stored on.
The pixmap can only be used on this screen. The pixmap can only be used with other draw-
ables of the same depth, except in xCopyPlane.
A bitmap is a single-plane pixmap. There is no separate bitmap type in X Version 11.
Pixmaps should be considered a precious resource, since many systems have limits on the
amount of off-screen memory available.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Errors
BadAlloc
BadDrawable
BadValue
width or height is O.
depth is not supported by root window.
Related Commands
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindow-
BackgroundPixmap, XCreatePixmapFromBitmapData, XFreePixmap, XQuery-
BestSize, XQueryBestStipple, XWriteBitmapFile, XReadBitmapFile,
XCreateBitmapFromData.
108 July 26, 1988
XCreatePixmapCursor (continued) Xlib - Pixmaps and Tiles
Structures
typedef struct {
unsigned long pixel;
unsigned short red, green, blue;
char flags;
char pad;
} XColor;
/* DoRed, DoGreen, DoBlue */
Related Commands
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindow-
BackgroundPixmap, XCreatePixmap, XFreePixmap, XQueryBestSize, XQuery-
BestStipple, XWriteBitmapFile, XReadBitmapFile, XCreateBitmapFrom-
Data.
110 July 26, 1988
mXIIb - Pixmaps and Bitmaps
XCreatePixmapFromBitmapData
Name
XCreatePixmapFromBitmapData -- create a pixmap with depth from bitmap data.
Synopsis
Pixmap XCreatePixmapFromBitmapData ( display, drawable, data,
width, height, fg, bg, depth)
Display *display;
Drawable drawable ;
char *data;
unsigned int width, height ;
unsigned long fg, bg;
unsigned int depth ;
Arguments
di spl ay
dra wahl e
data
wi dth
height
fg
bg
depth
Description
Specifies a pointer to the Display structure, returned from XOpen-
Display.
Specifies a drawable ID which indicates which screen the pixmap is to be
used on.
Specifies the data in bitmap format.
Specify the width and height in pixels of the pixmap to create.
Specify the foreground and background pixel values to use.
Specifies the depth of the pixmap. Must be valid on the screen specified by
dra wahl e.
XCreatePixmapFromBitmapData creates a pixmap of the given depth using biunap data
and foreground and background pixel values.
The following format for the data is assigned by default, where the variables are members of
the x.Iraage structure described in Volume One, Chapter 6, Drawing Graphics and Text:
format=XYPixmap
bit order=LSBFirst
byte order=LSBFirst
bitmap_unit =8
bitmap_2ad=8
xoffset=0
no extra bytes per line
XCreatePixmapFromBitmapData creates an image from the data and uses xPutImage
to place the data into the pixmap. For example:
July 26, 1988 111
XCreatePixmapFromBitmapData (continued) Xlib- Pixmaps and Bitmaps
#define gray_width 16
#define gray_height 16
#define gray x hot 8
#define gray_y_hot 8
static char gray_bits [ ] =
{
0xf81f, 0xe3c7, 0xcff3, 0x9ff9,
0xbffd, 0x33cc, 0x7ffe, 0x7ffe,
0x7e7e, 0x7ffe, 0x37ec, 0xbbdd,
0x9c39, 0xcff3, 0xe3c7, 0xf81f/* example data */
};
unsigned long foreground, background;
unsigned int depth;
/* open display, determine colors and depth */
Pixmap XCreatePixmapFromBitmapData (display, window, gray_bit s,
gray_width, gray_height, foreground, background, depth);
If you want to use data of a different format, it is straightforward to write a routine that does
this yourself, using images.
Pixmaps should be considered a precious resource, since many systems have limits on the
amount of off-screen memory available.
Errors
BadAlloc
BadMatch
Related Commands
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindow-
BackgroundPixmap, XCreatePixmap, XFreePixmap, XQueryBestSize, XQuery-
BestStipple, XWriteBitmapFile, XReadBitmapFile, XCreateBitmapFrom-
Data.
112 July 26 1988
--Xlib- Regions
XCreateRegion
Name
XCreateRegion -- create a new empty region.
Synopsis
Region XCreateRegion()
Description
XCreateRegion creates a new region of undefined size. XPolygonRegion can be used
to create a region with a defined shape and size. Many of the functions that perform opera-
dons on regions can also create regions.
For a description of regions, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct
_XREGION *Region;/* opaque reference to region type */
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion,
XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPoint-
InRegion, XOffsetRegion, XIntersectRegion, XEmptyRegion, XDestroy-
Region, XEqualRegion, XClipBox.
July 26, 1988 113
XCreateSimpleWindow
Xlib - Window Existence--
Name
XCreateSimpleWindow -- create an unmapped Inputoutput window.
Synopsis
Window XCreateSimpleWindow(display, parent, x, y,
height, border width, border, background)
--
Display *display;
Window parent;
int x, y;
unsigned int width, height, border_width;
unsigned long border;
unsigned long background;
width,
Arguments
di spl ay
Specifies a pointer to the Display structure; returned from XOpen-
Display.
parent Specifies the parent window ID. Must be an InputOutput window.
x Specify the x and y coordinates of the upper-left pixel of the new window's
y border relative to the origin of the parent (inside the parent window's
border).
width Specify the width and height, in pixels, of the new window. These are the
height inside dimensions, not including the new window's borders, which are
entirely outside of the window. Must be nonzero. Any part of the window
that extends outside its parent window is clipped.
border width
--
Specifies the width, in pixels, of the new window's border.
Specifies the pixel value for the border of the window.
Specifies the pixel value for the background of the window.
border
ba ckgroun d
Description
XCreateSimpleWindow creates an unmapped InputOutput subwindow of the specified
parent window. Use XCreateWindow to set the attributes to create an InputOnly win-
dow while creating a window.
XCreateSirnpleWindow returns the ID of the created window. The new window is placed
on top of the stacking order relative to its siblings. Note that the window is unmapped when it
is created--use XMapWindow to display it. This function generates a CreateNotify
event.
The initial conditions of the window are as follows:
The window inherits its depth, class, and visual from its parent. All other window attributes
have their default values.
All properties have undefined values.
114 July 26, 1988
XCreateWindow
Xlib - Window Existence--
Name
XCreateWindow -- create a window and set atibutes.
Synopsis
Window XCreateWindow (display, parent, x, y,
border width, depth, class, visual,
--
attributes)
Display *display;
Window parent ;
int x, y;
unsigned int width, height ;
unsigned int border width;
--
int depth ;
unsigned int class;
Visual *visual
unsigned long valuemask;
XSetWindowAttributes *attributes ;
width, height,
valuemask,
Arguments
di spl ay
Specifies a pointer to the Display structure; returned from XOpenDisplay.
pa ren t
Specifies the parent window. Parent must be InputOutput if class of win-
dow created is to be InputOutput.
Specify the x and y coordinates of the upper-left pixel of the new window's
border relative to the origin of the parent (upper left inside the parent's border).
width
height
Specify the width and height, in pixels, of the window. These are the new
window's inside dimensions. These dimensions do not include the new
window's borders, which are entirely outside of the window. Must be nonzero,
otherwise XCreateWindow generates a BadValue error.
border width
--
Specifies the width, in pixels, of the new window's border. Must be 0 for
InputOnly windows, otherwise a BadMatch error is returned.
depth
Specifies the depth of the window, which is not necessarily the same as the
parent's depth. A depth of 0 for class InputOutput or CopyFromParent
means the depth is taken from the parent.
class
Specifies the new window's class. Pass one of these constants: Input-
0utput, InputOnly, orCopyFromParent.
visual
Specifies a pointer to the visual structure describing the colormaps to be used
with this window. CopyFromParent is valid.
valuemask
Specifies which window attributes are defined in the attributes argument.
If valuemask is 0, the rest is ignored, and attributes is not referenced.
This mask is the inclusive OR of the valid attribute mask bits.
116 July 26, 1988
XCreateWindow (continued) Xlib - Window Existence
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
CWBitGravity (IL<<4)
CWWinGravity (IL<<5)
CWBackingStore (IL<<6)
CWBackingPlanes (IL<<7)
CWBackingPixel (IL<<8)
CWOverrideRedirect (IL<<9)
CWSaveUnder (IL<<I0)
CWEventMask (IL<<II)
CWDontPropagate (IL<<I2)
CWColormap (IL<<I3)
CWCursor (IL<<I4)
Errors
BadAlloc
BadColor
BadCursor
BadMatch
BadPixmap
BadValue
BadWindow
A[ibu[e besides win_gravity, event_mask, do_not_propagate_
mask, override redirect or cursor specied for InputOnly.
--
depth nonzero for InputOnly.
Pren[ of InputOutput Js InputOnly.
border width is nonzero for InputOnly.
--
depth no[ suppor[ed on screen for InputOutput.
width or height is O.
visual [ype no[ supported on screen (eider InputOnly or Input-
Output).
Related Commands
XCreateSimpleWindow, XDestroySubwindows, XDestroyWindow.
118 July 26 1988
XDeleteAssoc
Xlib - Association Tables m
Name
XDeleteAssoc -- delete an entry from an association table.
Synopsis
XDeleteAssoc(display, table,
Display *display;
XAssocTable *table;
XID x id;
Arguments
display
x id)
--
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies one of the association tables created by XCreateAssocTable.
Specifies the X resource ID of the association to be deleted.
table
x id
--
Description
This function is provided for compatibility with X Version 10. To use it you must include the
file <X11/X10.h> and link with the library -loldX.
XDeleteAssoc deletes an association in an XAssocTable keyed on its XlD. Redundant
deletes (and deletes of nonexistent XlD's) are meaningless and cause no problems. Deleting
associations in no way impairs the performance of an XAssocTable.
For more information on association tables, see Volume One, Chapter 13, Other Programming
Techniques.
Structures
typedef struct {
XAs soc *buckets;
int size;
} XAs s ocTable;
/* pointer to first bucket in array */
/* table size (number of buckets) */
Related Commands
XCreateAssocTable, XDestroyAssocTable, XLookUpAssoc, XMakeAssoc.
120 July 26, 1988
XDeleteModifiermapEntry
Xlib - Resource Manager m
Name
XDeleteModifiermapEntry- delete an enlxy from an XModifierKeymap structure.
Synopsis
XModifierKeymap *XDeleteModifiermapEntry (modmap,
keysym_entry, modifier)
XModifierKeymap *modmap ;
KeyCode keysym_en try ;
int modifier;
Arguments
modmap Specifies a pointer to an XModifierKeymap Sucture.
k eysym_ en try
Specifies the KeyCode of the key to be deleted from modmap.
modifier Specifies the modifier you no longer want mapped to the keycode specified
in keysym entry. This should be one of the constants: ShiftMap-
Index, LockMapIndex, Cont rolMapIndex, ModlMapIndex, Mod2-
MapIndex, Mod3MapIndex, Mod4MapIndex, or Mod5MapIndex.
Description
XDeleteModifiermapEntry returns an XModifierKeymap structure suitable for cal-
ling XSetModifierMapping, in which the specified keycode is deleted from the set of
keycodes that is mapped to [he specified modifier (like Shift or Control). XDelete-
ModifierraapEnt ry does not change the mapping itself.
This function is normally used by calling XGetModifierMapping to get a pointer to the
current XModifierKeymap S'ucture for use as the modmap argument to XDelete-
Modi fie rmapEnt ry.
Note that the sucture pointed to by modmap is freed by XDeleteModifiermapEntry.
It should not be freed or otherwise used by applications.
For a description of the modifier map, see XSetModifierMapping.
Structures
typedef struct {
int max_keypermod;
KeyCode *modifiermap;
} XModifierKeymap;
/* server's max number of keys per modifier */
/* an 8 by max_keypermod array of
* keycodes to be used as modifiers */
#define ShiftMapIndex
#define LockMapIndex
#define ControlMapIndex
#define ModlMapIndex
#define Mod2MapIndex
#define Mod3MapIndex
122 July 26 1988
Xlib - Resource Manager (continued) XDeleteModifiermapEntry
#define Mod4MapIndex 6
#define Mod5MapIndex 7
Reled Commands
InsertModifiermapEntry, XGetModifierMapping, XSetModifierMapping,
XNewModifiermap, XFreeModifiermap, XKeycodeToKeysym, XKeysym-
ToKeycode, XKeysymToString, XQueryKeymap, XStringToKeysym, XLookup-
Keysym, XRebindKeySynAXGetKeyboardMapping, XRefreshKeyboardMapping,
XLookupString.
July 26, 1988 123
XDeleteProperty
Xlib- Properties n
Name
XDeleteProperty m delete a window property.
Synopsis
XDeleteProperty (display, w, property)
Display *display;
Window w;
Atom property;
Arguments
display
w
property
Description
Specifies a pointer D the Display sUmcture; returned from XOpen-
Display.
Specifies the ID of the window whose property you want to delete.
Specifies the atom of the property to be deleted.
XDeleteProperty deletes a window property, so that it no longer contains any data. Its
atom, specified by property, still exists after the call so that it can be used again later by
any application that knows the ID of the window the property is defined on. If the property
was defined on the specified window, XDeleteProperty generates a PropertyNotify
event.
See the introduction to properties in Volume One, Chapter 2, X Concepts, or more detailed
information in Volume One, Chapter 10, Interclient Communication.
E rro rs
BadAtom
BadWindow
Related Commands
XSetStandardProperties, XGetFontProperty, XRotateWindowProperties,
XChangeProperty, XGetWindowProperty, XListProperties, XGetAtomName,
XInternAtom.
124 July 26, 1988
mXlib - Association Tables
XDestroyAssocTable
Name
XDestroyAssocTable -- free the memory allocated for an association table.
Synopsis
XDestroyAssocTable(table)
XAssocTable *table;
Arguments
table
Specifies the association table whose memory is to be freed.
Description
This function is provided for compatibility with X Version 10. To use it you must include the
file <Xll/XIO.h> and link with the library -loldX.
Using an XAssocTable after it has been destroyed will have unpredictable and probably
disastrous consequences.
For more information on association tables, see Volume One, Chapter 13, Other Programming
Techniques.
Structures
typedef struct {
XAssoc *buckets;
int size;
}XAssocTable;
/* pointer to first bucket in array */
/* table size (number of buckets) */
Related Commands
XCreateAssocTable, XDeleteAssoc, XLookUpAssoc, XMakeAssoc.
July 26, 1988 125
mXlib- Regions
XDestroyRegion
Name
XDestroyRegion -- deallocate storage associated with a region.
Synopsis
XDestroyRegion(r)
Region r;
Arguments
Specifies the region to be destroyed.
Description
XDest royRegion frees the memory associated with a region.
See Volume One, Chapter 6, Drawing Graphics and Text, for a description of regions.
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion,
XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPoint-
InRegion, X0ffsetRegion, XIntersectRegion, XEmptyRegion, XCreate-
Region, XEqualRegion, XClipBox.
July 26, 1988 127
XDestroySubwindows
Xlib - Window Existence m
Name
XDestroySubwindows -- destroy all subwindows of a window.
Synopsis
XDestroySubwindows ( display, w)
Display *display;
Window w;
Arguments
display
w
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the ID of the window whose subwindows are to be destroyed.
This function destroys all descendants of the specified window, in bottom to top stacking
order.
XDestroySubwindows generates exposure events on window w, if any mapped subwin-
dows were actually destroyed. This is much more efficient than deleting many subwindows
one at a time, since much of the work need only be performed once for all of the windows
rather than for each window. It also saves multiple exposure events on the windows about to
be destroyed. The subwindows should never again be referenced.
XCloseDisplay automatically destroys all windows that have been created by that client on
the specified display (unless called after a fork system call).
E rro rs
BadWindow
Related Commands
XCreateSimpleWindow, XCreateWindow, XDestroyWindow.
128 July 26, 1988
--Xlib - Window Existence
XDestroyWindow
Name
XDestroyWindow -- unmap and destroy a window and all subwindows.
Synopsis
XDestroyWindow ( display, window)
Display *display;
Window window;
Arguments
di spl ay
window
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the ID of the window to be destroyed.
Description
If window is mapped, an UnmapWindow request is performed automatically. The window
and all inferiors are then destroyed, and a DestroyNotify event is generated for each win-
dow. The ordering of the DestroyNotify events is such that for any given window,
DestroyNotify is generated on all inferiors of the window before being generated on the
w,.'ndow itself. The ordering among siblings and across subhierarchies is not otherwise con-
strained.
The windows should never again be referenced.
Destroying a mapped window will generate exposure events on other windows that were
obscured by the windows being destroyed. XDestroyWindow may also generate Enter-
Window events if window was mapped and contained the pointer.
No windows are destroyed if you try to destroy the root window.
Errors
BadWindow
Related Commands
XCreateSimpleWindow, XCreateWindow, XDestroySubwindows.
July 26 1988 129
XDisableAccessControl
Xlib - Host Access m
Name
XDisableAccessControl m allow access from any host.
Synopsis
XDisableAccessControl (display)
Display *display;
Arguments
display
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Description
XDisableAccessControl instructs the server to allow access from clients on any host.
This overrides the host access list.
This routine can only be called from a client running on the same host as the server.
For more information on access control, see Volume One, Chapter 13, Other Programming
Techniques.
Errors
BadAccess
Related Commands
XAddHost, XAddHosts, XListHosts, XRemoveHost, XRemoveHosts, XEnable-
AccessControl, XSetAccessControl.
130 July 26, 1988
--Xlib- Error Handling
XDisplayName
Name
XDisplayName -- report the display name when connection to a display fails.
Synopsis
char *XDisplayName(string)
char *string;
Arguments
string
Specifies the character string.
Description
XDisplayName is normally used to report the name of the display the program attempted to
open with OpenDisplay. This is necessary because X error handling begins only after the
connection to the server succeeds. If a NULL string is specified, XDisplayNarae looks in
the environment for the display and returns the display name that the user was requesting.
Otherwise, XDisplayNarae returns its own argument. This makes it easier to report to the
user precisely which display the program attempted to open.
For more information, see Volume One, Chapter 3, Basic Window Program.
Related Commands
XGetErrorDatabaseText, XGetErrorText, XSetErrorHandler, XSetIOError-
Handler, XSynchronize, XSetAfterFunction.
July 26, 1988 131
Xlib- Drawing Primitives (continued) XDraw
It is permissible for VertexDontDraw bits and VertexCurved bits to both be 1. This is
useful if you want to define the previous point for the smooth curve, but you do not want an
actual curve drawing to start until this point.
If VertexStartClosed bit is 1, then this point marks the beginning of a closed curve.
This vertex must be followed later in the array by another vertex whose absolute coordinates
are identical and which has VertexEndClosed bit of 1. The points in between form a
cycle for the purpose of determining predecessor and successor vertices for the spline algo-
rithmo
XDraw uses the following graphics context components: function, plane_mask,
line_width, line_style, cap_style, join_style, fill_style, subwindow_
mode, clip x origin, clip_y_origin, and clip_mask. This function also uses
these graphics context mode-dependent components: foreground, background, tile,
stipple, ts x origin, ts_y__origin, dash_offset, and dash_list.
A Status of 0 is returned on failure.
For more information, see Volume One, Appendix B, XIO Compatibility.
Structures
typedef struct Vertex {
--
short x,y;
unsigned short flags;
} Vertex;
/* defined constants for use as flags */
#define VertexRelative 0x0001
#define VertexDontDraw 0x0002
#define VertexCurved 0x0004
#define VertexStartClosed 0x0008
#define VertexEndClosed 0x0010
/* else absolute */
/* else draw */
/* else straight */
/* else not */
/* else not */
Related Commands
XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint,
XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopy-
Area, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle,
XFillRectangles, XClearArea, XClearWindow.
July 26, 1988 133
XDrawArc
Xlib - Drawing Primitives D
Name
XDrawArc -- draw an arc fitting inside a rectangle.
Synopsis
XDrawArc (display, drawable, gc, x, y,
anglel , angle2)
Display *display;
Drawable drawable ;
GC gc ;
int x, y;
unsigned int width, height ;
int anglel , angle2;
width, height,
Arguments
display
dra wabl e
gc
x
y
wi dth
height
anglel
angle2
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the drawable.
Specifies the graphics context.
Specify the x and y coordinates of the upper-left corner of the rectangle that
contains the arc, relative to the origin of the specified drawable.
Specify the width and height in pixels of the major and minor axes of the
arC.
Specifies the start of the arc relative to the three-o'clock position from the
center. Angles are specified in 64ths of a degree, (360 * 64 is a complete
circle).
Specifies the path and extent of the arc relative to the start of the arc.
Angles are specified in 64ths of a degree, (360 * 64 is a complete circle).
XI)rawArc draws a circular or elliptical arc. An arc is specified by a rectangle and two
angles. The x and y coordinates are relative to the origin of the drawable, and define the
upper-left corner of the rectangle. The center of the circle or ellipse is the center of the rectan-
gle, and the major and minor axes are specified by the width and height, respectively.
The angles are signed integers in 64ths of a degree, with positive values indicating counter-
clockwise motion and negative values indicating clockwise motion, truncated to a maximum of
360 degrees. The start of the arc is specified by anglel relative to the three-o'clock position
from the center, and the path and extent of the arc is specified by angle2 relative to the start
of the arc.
By specifying one axis to be 0, a horizontal or vertical line can be drawn.
Angles are computed based solely on the coordinate system and ignore the aspect ratio. In
other words, if the bounding rectangle of the arc is not square and anglel is 0 and angle2
134 July 26, 1988
Xlib - Drawing Primitives (continued) XDrawArc
is (45x64), a point drawn from the center of the bounding box through the endpoint of the arc
will not pass through the comer of the rectangle.
XD rawArc uses these graphics context components: funct ion, plane_ma s k,
line_width, line_style, cap_style, join_style, fill_style, subwindow_
mode, clip x origin, clip_y_origin, and clip_mask. This function also uses
these graphics context mode-dependent components: foreground, background, tile,
stipple, ts x origin, ts_y_origin, dash_offset, and dash_list. XDraw-
Arc is not affected by the tile or stipple in the GC.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
(x,y)
9 o'clock
Angle = 180x64
Angle = -(180x64)
width
12 o'clock
. Center of
Angle = 90x64
Bou,,u,,,y
Angle = - (270x64)
Rectangle
'"<-... i
............... ;'-'-':' - .................. t Angle=
//
6 o'clock
Angle = 270x64=17280
Angle = -(90x64)=5760
Example 1 :
Arc from A1 to A2, Counterclockwise
A1 = 90 x 64
A2 = 45 x 64
Example 2:
Arc from B1 to B2, Clockwise
A1 = 270 x 64
A2 = -(45 x 64)
Errors
BadDrawable
BadGC
BadMatch
Xlib Reference Manual 135
XDrawArc (continued) Xlib- Drawing Primitives
Related Commands
XDraw, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint,
XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopy-
Area, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle,
XFillRectangles, XClearArea, XClearWindow.
136 July 26, 1988
nXlib- Drawing Primitives
XDrawArcs
Name
XDrawArcs -- draw multiple arcs.
Synopsis
XDrawArcs (display, drawable,
Display *display;
Drawable drawable ;
GC gc ;
XArc *arcs;
int narcs ;
gc, arcs, narcs)
Arguments
di spl ay
dra wabl e
gc
arcs
narcs
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the drawable.
Specifies the graphics context.
Specifies a pointer to an array of arcs.
Specifies the number of arcs in the array.
(x,y)
9 o'clock
Angle = 180x64
Angle = -(180x64)
width
12 o'clock
A , -- Center of
ngJ.e = 904x64 / Bounding
Angle = - ( 0 ) . / Rectangle
.....- , Angle
.
6 o'clock
Angle = 270x64=17280
Angle = - (90x64) =5760
Example 1 :
Arc from A1 to A2, Counterclockwise
A1 = 90 x 64
A2 = 45 x 64
Example 2:
Arc from 81 to 82, Clockwise
A1 = 270 x 64
A2 = -(45 x 64)
Xlib Reference Manual 137
Xlib- Drawing Primitives (continued) XDrawArcs
[x+dx/2, y+dy/2, width-dx, height-dy, anglel, angle2]
and
[x-line_width/2, y-line_width/2, width+line_width, height+line_width,
anglel, angle2 ]
where
dx=min ( line_width, width)
dy=min ( line_width, height)
If (height != width) the angles must be specified in the effectively skewed coordinate
system of the ellipse (for a circle, the angles and coordinate systems are identical). The rela-
tionship between these angles and angles expressed in the normal coordinate system of the
screen (as measured with a protractor) is as follows:
skewed-angle = atan(tan(normal-angle) * width/height) + adjust
The skewed-angle and normal-angle are expressed in radians (rather than in 64ths of a degree)
in the range [0,2*PT], and where atan returns a value in the range [-PT/2, PT/2], and
where adgust is:
0 for normal-angle in the range [0,PI/2]
PI for normal-angle in the range [PI/2, (3"PI)/2]
2*PI for normal-angle in the range [(3*PI)/2,2*PI]
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct {
short x, y;
unsigned short width, height;
short anglel, angle2;
} XArc;
/* Degrees * 64 */
Errors
BadDZawable
BadGC
BadMatch
Related Commands
XDraw, XDrawArc, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDraw-
Points, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea,
XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFill-
Rectangles, XClearArea, XClearWindow.
July 26, 1988 139
XDrawFilled
Xlib- Drawing Primitives--
Name
XDrawFilled m draw a filled polygon or curve from vertex list (from X10).
Synopsis
Status XDrawFilled ( display,
Display *display;
Drawable drawable ;
GC gc ;
Vertex *vlist ;
int vcount ;
drawable, gc, vlist,
vcount )
Arguments
display
dra wabl e
gc
vlist
vcount
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the drawable.
Specifies the graphics context.
Specifies a pointer to the list of vertices.
Specifies how many vertices are in vlist.
This function is provided for compatibility with X Version 10. To use it you must include the
file <X11/X10.h> and link with the library -loldX. XDrawFilled achieves the effects of the
X Version I0 XDrawTiled and XDrawFilled functions.
XDrawFilled draws arbitrary polygons or curves, according to the same rules as XDraw,
and then fills them.
XDrawFilled uses the following graphics context components: function,
plane_mask, line_width, line_style, cap_style, join_style, fill_style,
subwindow_mode, clip x origin, clip_y_origin, and clip_mask. This func-
tion also uses these graphics context mode-dependent components: foreground, back-
ground, tile, stipple, ts x origin, ts_y_origin, dash_offset, dash_
list, fill_style and fill_rule.
XDrawFilled returns a Status of 0 on failure.
For more information, see Volume One, Appendix B, XIO Compatibility.
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawLine, XDrawLines, XDrawPoint, XDraw-
Points, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea,
XCopyPlane, XFilIArc, XFilIArcs, XFillPolygon, XFillRectangle, XFill-
Rectangles, XClearArea, XClearWindow.
140 July 26, 1988
XDrawlmageString (continued) Xlib - Text
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XQueryTextExtents, XQueryTextExtentsl6, XDrawImageStringl6, XDraw-
String, XDrawStringl6, XDrawText, XDrawTextl6, XTextExtents, XText-
Extentsl6, XTextWidth, XTextWidthl6.
142 July 26 1988
--Xlib - Text
XDrawlmageStringl 6
Name
XDrawlmageStringl6 m draw 16-bit image text characters.
Synopsis
XDrawImageStringl6(display,
Display *display;
Drawable drawable;
GC gc;
int x, y;
XChar2b *string;
int length;
drawable, gc, x, y, string, length)
Arguments
display
dra wabl e
gc
x
Y
string
length
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the drawable.
Specifies the graphics context.
Specify the x and y coordinates of the baseline starting position for the
image text character, relative to the origin of the specified drawable.
Specifies the character s'ing.
Specifies the number of characters in the string argument.
XDrawImageStzingl6 draws a suSng, but unle XDrawStringl 6 it can draw both the
foreground and the background of the characters, if the GC is set accordingly.
XDrawImageStringl6 uses these graphics context components: plane_mask, fore-
ground, background, font, subwindow_mode, clip x origin, clip_y_
origin, and clip_mask. The function and fill_style defined in gc are ignored;
the effective function is GXcopy and the effective fill_style is FillSolid.
XDra'wImageStringl6 first fills a destination rectangle with the background pixel
defined hn gc, and then pJn the text with the foreground pixel. The upper-left corner of
the filled recqngle is at Ix, y - font_ascent], the width is overall->width and
the height is ascent + descent.
The overall->width, ascent, and descent are as would be returned by XQuery-
TextExtentsl6 using gc and string.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter
5, The Graphics Context.
July 26, 1988 143
XDrawlmageStri ng 16 (continued) Xlib - Text
Structures
typedef struct {
unsigned char bytel;
unsigned char byte2;
} XChar2b;
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XQueryTextExtents, XQueryTextExtentsl6, XDrawImageString, XDraw-
String, XDrawStringl6, XDrawText, XDrawTextl6, XTextExtents, XText-
Extentsl6, XTextWidth, XTextWidthl6.
144 July 26, 1988
mXlib - Drawing Primitives
XDrawLine
Name
XDrawLine -- draw a line between two points.
Synopsis
XDrawLine(display, drawable, gc, xl, yl, x2, y2)
Display *display;
Drawable drawable ;
GC gc ;
int xl, yl, x2, y2;
Arguments
di spl ay
dra wabl e
gc
yl
x2
y2
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the drawable.
Specifies the graphics context.
Specify the coordinates of the endpoints of the line relative to the drawable
origin. XLine connects point (xl, yl) to point (x2, y2).
Description
XDrawLine uses the components of the specified graphics context to draw a line between
two points in the specified drawable. No pixel is drawn more than once.
XDrawLine uses these graphics context components: function, plane_mask,
line_width, line_style, cap_style, fill_style, subwindow_mode, clip_
x_origin, clip_y_origin, and clip_mask. XDrawLine also uses these graphics
context mode-dependent components: foreground, background, tile, stipple,
ts x origin, ts_y_origin, dash_offset, and dash_list.
XDrawLine is not affected by tile or stipple in the GC.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter
5, The Graphics Context.
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLines, XDrawPoint, XDraw-
Points, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea,
XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFill-
Rectangles, XClearArea, XClearWindow.
July 26, 1988 145
Xlib- Drawing Primitives (continued) XDrawLines
XDrawLines is not affected by the tile or stipple in the GC.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter
5, The Graphics Context.
Structures
typedef struct {
short x, y;
} XPoint;
Errors
BadDrawable
BadGC
BadMatch
BadValue
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawPoint, XDraw-
Points, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea,
XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFill-
Rectangles, XClearArea, XClearWindow.
July 26, 1988 147
XDrawPoint
Xlib - Drawing Primitives m
Name
XDrawPoint draw a point.
Synopsis
XDrawPoint (display, drawable, go, x, y)
Display *display;
Drawable drawable ;
GC gc ;
int x, y;
Arguments
di spl ay
dra wabl e
gc
x
Y
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the drawable.
Specifies the graphics context.
Specify the x and y coordinates of the point, relative to the corner of the
drawable.
XDrawPoint uses the foreground pixel and function components of the graphics con-
text to draw a single point into the specified drawable. XDrawPoint uses these graphics
context components: function, plane_mask, foreground, subwindow_mode,
clip x origin, clip_y_origin, and clip_mask. Use XDrawPoints tO draw mul-
tiple points.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter
5, The Graphics Context.
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDraw-
Points, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea,
XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFill-
Rectangles, XClearArea, XClearWindow.
148 July 26, 1988
XDrawPoints (continued) Xlib - Drawing Primitives
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDraw-
Points, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea,
XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFill-
Rectangles, XClearArea, XClearWindow.
150 July 26, 1988
XDrawRectangle (continued) Xlib- Drawing Primitives
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter
5, The Graphics Context.
Structure
typedef struct {
short x, y;
unsigned short width, height;
} XRectangle;
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDraw-
Point, XDrawPoints, XDrawRectangles, XDrawSegments, XCopyArea, XCopy-
Plane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFill-
Rectangles, XClearArea, XClearWindow.
152 Xlib Reference Manual
nXlib - Drawing Primitives
XDrawRectangles
Name
XDrawRectangles -- draw the outlines of multiple rectangles.
Synopsis
XDrawRectangles (display, drawable,
Display *display;
Drawable drawable ;
GC gc ;
XRectangle rectangles[] ;
int nrectangles ;
Arguments
display
dra wabl e
gc
rectangles
gc, rectangles, nrectangles)
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the drawable.
Specifies the graphics context.
Specifies a pointer to an array of rectangles containing position and size
information.
nrectangles Specifies the number of rectangles ;n the array.
XrawRecta:zle(dls._a, drawat ., =-- . .... . , ,
[]llllllllllllllll [
|11111111111111111111 IllllltllltIl|lll|ll I
1111111111111111111[| Itlllltllltlltllltll I
IIIllllllllllll 12 itlltltlillIl|lilllll.-
|llllllllllllllll I1 p,xels lz p,xels
i1111111111111111[[[| 1 1
i111111111111111111[1
|llllllllllllllllll|..I
111111111111111111111
|ltlttltiil|ll|[ll, l,[]
20 p=xels 20 p,xels
Description
XDrawRectangles draws the outlines of the specified rectangles by using the position and
size "values in the array of rectangles. The x and y coordinates of each rectangle are relative to
the drawable's origin, and define the upper-left corner of the rectangle. This function uses
these graphics context components: function, plane_mask, line_width,
line_style, cap_style, join_style, fill_style, s ubwindow_mode,
clip x origin, clip_y_origin, and clip_mask. XDrawRectangles also uses
these graphics context mode-dependent components: foreground, background, tile,
stipple, ts x origin, ts_y_origin, dash_offset, and dash_list.
The rectangles are drawn in the order listed. For any given rectangle, no pixel is drawn more
than once. If rectangles intersect, pixels are drawn multiple times.
XDrawRectangles is not affected by tile or stipple in the GC.
Xlib Reference Manual 153
XDrawRectangles (continued) Xlib- Drawing Primitives
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter
5, The Graphics Context.
Structures
typedef struct {
short x, y;
unsigned short width, height;
unsigned short width, height;
} XRectangle;
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDraw-
Point, XDrawPoints, XDrawRectangle, XDrawSegments, XCopyArea, XCopy-
Plane, XFilIArc, XFilIArcs, XFillPolygon, XFillRectangle, XFill-
Rectangles, XClearArea, XClearWindow.
154 Xlib Reference Manual
DXlib- Drawing Primitives
XDrawSegments
Name
XDrawSegrnents -- draw multiple disjoint lines.
Synopsis
XDrawSegments(display,
Display *display;
Drawable drawable;
GC gc;
XSegment *segments;
int nsegments;
drawable,
gc, segments, nsegments)
Arguments
display
dra wabl e
gc
s egmen t s
nsegments
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the drawable.
Specifies the graphics context.
Specifies a pointer to an array of line segments.
Specifies the number of segments in the array.
XDrawSegments draws multiple line segments into the specified drawable. Each line is
specified by a pair of points, so the line may be connected or disjoint.
For each segment, XDrawSegments draws a line between (xl, yl) and (x2, y2). The
lines are drawn in the order listed in segments. For any given line, no pixel is drawn more
than once. If lines intersect, pixels will be drawn multiple times. The lines will be drawn
separately, without regard to the join_style.
XDrawSegments uses these graphics context components: function, plane_mask,
line_width, line_style, cap_style, fill_style, subwindow_mode, clip_
x_origin, clip_y_origin, and clip_mask. XDrawSegments also uses these graph-
ics context mode-dependent components: foreground, background, tile, stipple,
ts x origin, ts_y__6rigin, dash_offset, and dash_list.
XDrawSegments is not affected by the tile or stipple in the GC.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter
5, The Graphics Context.
Structures
typedef struct {
short xl, yl, x2, y2;
} XSegment;
July 26, 1988 155
XDrawSegments (continued) Xlib- Drawing Primitives
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDraw-
Point, XDrawPoints, XDrawRectangle, XDrawRectangles, XCopyArea, XCopy-
Plane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFill-
Rectangles, XClearArea, XClearWindow.
156 July 26, 1988
mXlib - Text
XDrawString
Name
XDrawString -- draw an 8-bit text string, foreground only.
Synopsis
XDrawString ( display, drawable, gc, x, y, string, length)
Display *display;
Drawable drawable ;
GC gc ;
int x, y;
char *string;
int length;
Arguments
di spl ay
dra wahl e
gc
x
Y
string
length
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the drawable.
Specifies the graphics context.
Specify the x and y coordinates of the baseline starting position for the char-
acter, relative to the origin of the specified drawable.
Specifies the character string.
Specifies the number of characters in the string argument.
XDrawString draws the given string into a drawable using the foreground only to draw
set bits in the font. It does not affect any other pixels in the bounding box for each character.
The y coordinate defines the baseline row of pixels while the x coordinate is the point for
measuring the ibearing, rbearing, and width from.
XDrawString uses these graphics context component: function, plane_mask,
fill_style, font, subwindow_mode, clip x origin, clip_y_origin, and
clip_mask. This function also uses these graphics context mode-dcpendent components:
foreground, tile, stipple, ts x origin, and ts_y_origin. Each character
image, as defined by the font in gc, is treated as an additional mask for a fill operation on the
drawable.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter
5, The Graphics Context.
Errors
BadDrawable
BadFont
BadGC
BadMatch
July 26, 1988 157
XDrawString (continued) Xlib - Text
Related Commands
XQueryTextExtents, XQueryTextExtentsl6, XDrawImageString, XDraw-
ImageStringl6, XDrawStringl6, XDrawText, XDrawTextl6, XTextExtents,
XTextExtentsl6, XTextWidth, XTextWidthl6.
158 July 26, 1988
mXlib - Text,
XDrawString16
Name
XDrawStringl6- draw two-byte text strings.
Synopsis
XDrawStringl6 (display, drawable,
Display *display;
Drawable drawable ;
GC gc ;
int x, y;
XChar2b *string;
int length;
gc, x, y, string, length)
Arguments
display
drawable
gc
x
Y
string
length
Description
Specifies a pointer to the Display s[ructure; re[urned from XOpen-
Display.
Specifies the drawable.
Specifies the graphics context.
Specify the x and y coordinates of the baseline starting position for the char-
acter, relative to the origin of the specified drawable.
Specifies the character string. Characters are two bytes wide.
Specifies the number of characters in the str'ng argument.
XDrawStringl 6 draws a string in the foreground pixel value without drawing the surround-
ing pixels.
The y coordinate defines the baseline row of pixels while the x coordinate is the point for
measuring the lbearing, rbearing, and width from. For more information on text
placement, see Volume One, Chapter 6, Drawing Graphics and Text.
XDrawStringl6 uses these graphics context components: function, plane_mask,
fil_style, font, subwindow_mode, clip x origin, clip_y_origin, and
clip_mask. This function also uses these graphics context mode-dependent components:
foreground, tile, stipple, ts x origin, and ts_y_origin. Each character
image, as defined by the font in gc, is treated as an additional mask for a fill operation on the
drawable.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter
5, The Graphics Context.
Structures
typedef struct {
unsigned char bytel;
unsigned char byte2;
} XChar2b;
July 26, 1988 159
XDrawStringl 6 (continued) Xlib - Text
Errors
BadDrawable
BadFont
BadGC
BadMatch
Related Commands
XQueryTextExtents, XQueryTextExtentsl6, XDrawImageString, XDraw-
ImageStringl6, XDrawString, XDrawText, XDrawTextl6, XTextExtents,
XTextExtentsl6, XTextWidth, XTextWidthl6.
160 July 26, 1988
XDrawText (continued) Xlib - Text
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter
5, The Graphics Context.
Structures
typedef struct {
char *chars;
int nchars;
int delta;
Font font;
} XTextItem;
/* pointer to string */
/* number of characters */
/* delta between strings */
/* font to print it in, None don't change */
Errors
BadDrawable
BadFont
BadGC
BadMatch
Related Commands
XQueryTextExtents, XQueryTextExtentsl6, XDrawImageString, XDraw-
ImageStringl6, XDrawString, XDrawStringl6, XDrawTextl6, XTextExtents,
XTextExtentsl6, XTextWidth, XTextWidthl6.
162 July 26, 1988
mXlib - Text
XDrawText16
Name
XDrawTextl6 -- draw 16-bit polytext strings.
Synopsis
XDrawTextl6 (display, drawable, gc, x, y, items,
Display *display;
Drawable drawable ;
GC gc ;
int x, y;
XText Iteml 6 *items;
int nitems;
ni t ems )
Arguments
di spl ay
Specifies a pointer to the Display structure; returned from XOpen-
Display.
dra wabl e Specifies the drawable.
gc
Specifies the graphics context.
x
Y
items
nitems
Description
Specify the x and y coordinates of the baseline starting position for the initial
string, relative to the origin of the specified drawable.
Specifies a pointer to an array of text items using two-byte characters.
Specifies the number of text items in the array.
XDrawTextl6 is capable of drawing multiple strings and changing fonts between strings.
Each XTextItem structure contains a sla'ing, the number of characters in the string, the
delta offset from the starting position for the string, and the font. Each text item is pro-
cessed in turn. The font in each XText Item is stored in the specified GC and used for sub-
sequent text. If the XText Iteml 6. font is None, the font in the GC is used for drawing
and is not changed. Switching between fonts with different drawing directions is permitted.
The. delta in each XTextTtem specifies the change in horizontal position before the string
is drawn. The delta is always added to the character origin and is not dependent on the draw-
ing direction of the font. For example, if x = 40, y = 20, and items [0] .delta = 8,
the string specified by items [0] .chars would be drawn starting at x = 48, y = 20.
The delta for the second string begins at the rbearing of the last character in the first
string. A negative delta would tend to overlay subsequent strings on the end of the previous
string.
Only the pixels selected in the font are drawn (the background member of the GC is not
used).
XDrawTextl6 uses the following elements in the specified GC: function, plane_
mask, fill_style, font, subwindow_mode, clip x origin, clip_y_origin,
and clip_mask. This function nlso uses these graphics context mode-dependent com-
ponents: foreground, tile, stipple, ts x origin, and ts_y_origin.
July 26, 1988 163
XDrawTextl 6 (continued) Xlib - Text
Note that the chars member of the XTextIteml6 structure is of type XChar2b, rather
than of type char as it is in the XTextItem structure. For fonts defined with linear index-
ing rather than two-byte matrix indexing, the X server will interpret each member of the
XChar2b structure as a 16-bit number that has been transmitted most significant byte first. In
other words, the bytel member of the XChar2b structure is taken as the most significant
byte.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter
5, The Graphics Context.
Structures
typedef struct {
XChar2b *chars;
int nchars;
int delta;
Font font;
} XTextIteml6;
/* 2 byte characters */
/* number of characters */
/* delta between strings */
/* font to print it in, None don't change */
typedef struct {
unsigned char bytel;
unsigned char byte2;
} XChar2b;
/* normal 16 bit characters are two bytes */
Errors
BadDrawable
BadFont
BadGC
BadMatch
Related Commands
XQueryTextExtents, XQueryTextExtentsl6, XDrawImageString, XDraw-
ImageStringl6, XDrawString, XDrawStringl6, XDrawText, XTextExtents,
XTextExtentsl6, XTextWidth, XTextWidthl6.
164 July 26, 1988
mXlib- Regions
XEmptyRegion
Name
XEmptyRegion -- determine if a region is empty.
Synopsis
int XEmptyRegion(r)
Region r;
Arguments
r Specifies the region to be checked.
Description
XEmptyRegion will return True if the specified region is empty.
Structures
/*
* opaque reference to Region data type.
* user won't need contents, only pointer.
*/
typedef struct _XRegion *Region;
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion,
XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPoint-
InRegion, XOffsetRegion, XIntersectRegion, XCreateRegion, XDestroy-
Region, XEqualRegion, XClipBox.
July 26, 1988 165
XEnableAccessControl
Xlib - Host Access m
Name
XEnableAccessControl--useaccesscontrollist glow ordenyconnectionrequests.
Synopsis
XEnableAccessControl(display)
Display *display;
Arguments
display
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Description
XEnableAccessControl instructs the server to use the host access list to determine
whether access should be granted to clients seeking a connection with the server.
By default, the host access list is used. If access has not been disabled with XDisable-
AccessControl or XSetAccessControl, this routine does nothing.
This routine can only be called by clients running on the same host as the server.
For more information, see Volume One, Chapter 13, Other Programming Techniques.
Related Commands
XAddHost, XAddHosts, XListHosts, XRemoveHost, XRemoveHosts, XDisable-
AccessControl, XSetAccessControl.
166 July 26, 1988
mXlib- Regions
XEqualRegion
Name
XEqualRegion -- determine if two regions have the same size, offset, and shape.
Synopsis
int XEqualRegion (rl, r2)
Region rl , r2 ;
Arguments
r]
r2
Specify the two regions you want to compare.
Description
XEqualRegion returns True if the o regions are identical; i.e., they have the same offset,
size and shape.
Regions are located using an offset from a point (the region origin) which is common to all
regions. It is up to the application to interpret the location of the region relative to a drawable.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
/.
* opaque reference to Regiondata type.
* user won't need contents, only pointer.
*/
typedef struct _XRegion *Region;
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion,
XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPoint-
InRegion, XOffsetRegion, XIntersectRegion, XEmptyRegion, XCreate-
Region, XDestroyRegion, XClipBox.
July 26, 1988 167
XEventsQueued
Xlib - Resource Manager m
Name
XEventsQueued m check the number of events in the event queue.
Synopsis
int XEventsQueued(display,
Display *display;
int mode;
mode )
Arguments
display
Specifies a pointer to the Display structure, returned from XOpen-
Display.
mode
Specifies whether the output buffer is flushed if there are no events in Xlib's
queue. You can specify one of these constants: QueuedAlready,
QueuedAfterFlush, QueuedAfterReading.
Description
XEventsQueued checks whether events are queued. If there are events in Xlib's queue, the
routine returns immediately to the calling routine. Its return value is the number of events
regardless of mode.
mode specifies what happens if no events are found on Xlib's queue.
If mode is QueuedAlready, and there are no events in the queue, XEvents-
Queued returns 0 (it does not flush the output buffer or attempt to read more events
from the connection).
If mode is QueuedAfterFlush, and there are no events in the queue, XEvents-
Queued flushes the output buffer, attempts to read more events out of the
application's connection, and returns the number read.
If mode is QueuedAfterReading, and there are no events in the queue,
XEventsQueued attcmpts to read more events out of the application's connection
without flushing the output buffer and rctums the number read.
Note that XEventsQueued always returns immediately without I/O if there are events
already in the queue.
XEventsQueued with mode QueuedAfterFlush is identical in behavior to XPending.
XEventsQueued with mode QueuedAlready is identical to the QLength macro (see
Appendix C, Macros).
For more information, see Volume One, Chapter 8, Events.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheck-
WindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent,
XCheckMaskEvent, XNextEvent, XAllowEvents, XGetMotionEvents,
XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent,
XSynchronize, XSendEvent, QLength, XPending.
168 July 26, 1988
--Xlib - Cut Buffers
XFetchBuffer
Name
XFetchBuffer -- return data from a cut buffer.
Synopsis
char *XFetchBuffer(display,
Display *display;
int *nbytes;
int buffer;
nbytes, buffer)
/* RETURN */
Arguments
display
nbytes
buffer
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Returns the number of bytes in buffer returned by XFetchBuffer. If
there is no data in the buffer, nbytes is set to 0.
Specifies which buffer you want data from. Specify an integer from 0 to 7.
XFetchBuffer returns data from one of the 8 buffers provided for interclient communica-
tion. If the buffer contains data, XFetchBuffer returns the number of bytes in nbyte3,
otherwise it returns NULL and sets nbytes to 0. The appropriate amount of storage is allo-
cated and the pointer returned; the client must free this storage when finished with it. Note
that the cut buffer does not necessarily contain text, so it may contain embedded null bytes and
may not terminate with a null byte.
Selections are the preferred communication scheme.
For more information on cut buffers, see Volume One, Chapter 13, Other Programming Tech-
niques.
Errors
BadValue
Related Commands
XSt'oreBuffer, XStoeBytes, XFetchBytes, XRotateBuffers.
July 26, 1988 169
XFetchBytes
Xlib - Cut Buffers D
Name
XFetchBytes -- return data from cut buffer 0.
Synopsis
char *XFetchBytes (display, nbytes)
Display *display;
int *nbytes; /* RETURN */
Arguments
display
Specifies a pointer to the Display structure; returned from XOpen-
Display.
nbytes
Returns the number of bytes in the string returned by XFetchBytes. If
there is no data in the buffer, nbytes is set to 0.
Description
XFetchBytes returns data from cut buffer 0 of the 8 buffers provided for interclient com-
munication. If the buffer contains data, XFetchBytes returns the number of bytes in
nbytes, otherwise it returns NULL and sets nbytes to 0. The appropriate amount of
storage is allocated and the pointer returned; the client must free this storage when finished
with it by calling XFree. Note that the cut buffer does not necessarily contain text, so it may
contain embedded null bytes and may not terminate with a null byte.
Use XFetchBuffer tO fetch data from any specified cut buffer.
Selections are the preferred communication method.
For more information on cut buffers, see Volume One, Chapter 13, Other Programming Tech-
niques.
Related Commands
XStoreBuffer, XStoreBytes, XFetchBuffer, XRotateBuffers.
170 July 26, 1988
XFillArc
Xlib- Drawing Primitives--
Name
XFillArc -- fill an arc.
Synopsis
XFillArc (display, drawable, gc,
anglel , angle2)
Display *display;
Drawable drawable ;
GC gc ;
int x, y;
unsigned int width, height ;
int anglel , angle2;
x, y, width, height,
Arguments
display
Specifies a pointer to the Display structure; returned from XOpen-
Display.
dra wabl e Specifies the drawable.
gc
x
Specifies the graphics context.
Specify the x and y coordinates of the upper-left corner of the bounding box
containing the arc, relative to the origin of the drawable.
width
height
Specify the width and height in pixels. These are the major and minor axes
of the arc.
anglel
Specifies the start of the arc relative to the three-o'clock position from the
center. Angles are specified in degrees, multiplied by 64.
angle2 Specifies the path and extent of the arc relative to the start of the arc. Angles
are specified in degrees, multiplied by 64.
Description
XFillArc fills an arc according to the arc mode in the GC. The x, y, width, and
--
height arguments specify the bounding box for the arc. See XDrawArc for the description
of how this bounding box is used to compute the arc. Some, but not all, of the pixels drawn
with XDrawArc will be drawn by XFilIArc with the same arguments.
The arc forms one boundary of the area to be filled. The other boundary is determined by the
arc_mode in the GC. If the arc_mode in the GC is ArcChord, the single line segment
joining the endpoints of the arc is used. If ArcPieSlice, the two line segments joining the
endpoints of the arc with the center point are used.
XFilIArc uses these graphics context components: function, plane_mask,
fill_style, arc_mode, subwindow_mode, clip x origin, clip_y_origin,
and clip_mask. This function also uses these graphics context mode-dependent com-
ponents: foreground, background, tile, stipple, ts x origin, and ts_y_
origin.
172 July 26, 1988
Xlib- Drawing Primitives (continued) XFillArc
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter
5, The Graphics Context.
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDraw-
Point, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments,
XCopyArea, XCopyPlane, XFillArcs, XFillPolygon, XFillRectangle, XFill-
Rectangles, XClearArea, XClearWindow.
July 26, 1988 173
XFillArcs
Xlib - Drawing Primitives--
Name
XFillArcs B fill multiple arcs.
Synopsis
XFilIArcs (display, drawable, go,
Display *display;
Drawable drawable;
GC gc;
XArc *arcs;
int narcs;
arcs, narcs)
Arguments
display
Specifies a pointer to the Display structure; returned from XOpenDisplay.
drawable Specifies the drawable.
gc
Specifies the graphics context.
arcs
Specifies a pointer to an array of arc definitions.
narcs Specifies the number of arcs in the array.
Description
For each arc, XFillArcs fills the region closed by the specified arc and one or two line seg-
ments, depending on the arc. mode specified in the GC. It does not draw the complete out-
lines of the arcs, but some pixels may overlap.
The arc forms one boundary of the area to be filled. The other boundary is determined by the
arc_mode in the GC. If the arc_mode in the GC is ArcChord, the single line segment
joining the endpoints of the arc is used. If ArcPieSlice, the two line segments joining the
endpoints of the arc with the center point are used. The arcs are filled in the order listed in the
array. For any given arc, no pixel is drawn more than once. If regions intersect, pixels will be
drawn multiple times.
XFillArcs use these graphics context components: function, plane, mask,
fill_style, arc_mode, subwindow_mode, clip x origin, clip_y_origin,
and clip_mask. This function slso uses these graphics context mode-dependent com-
ponents: foreground, background, tile, stipple, ts x origin, and ts_y_
origin.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter
5, The Graphics Context.
Structures
typedef struct {
short x, y;
unsigned short width, height;
unsigned short width, height;
short anglel, anglel;
} XArc;
/* Degrees * 64 */
174 July 26, 1988
Xlib - Drawing Primitives (continued) XFillArcs
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDraw-
Point, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments,
XCopyArea, XCopyPlane, XFillArc, XFillPolygon, XFillRectangle, XFill-
Rectangles, XClearArea, XClearWindow.
July 26, 1988
175
XFillRectangle
Xlib- Drawing Primitives--
Name
XFillRectangle m fill a rectangular area.
Synopsis
XFillRectangle(display, drawable,
Display *display;
Drawable drawable;
GC gc;
int x, y;
unsigned int width, height;
gc, x, y,
width, height)
Arguments
di splay
dra wabl e
gc /
X
Y
wi dt h
height
Specifies a pointer to the Display structure; returned from XOpenDisplay.
Specifies the drawable.
Specifies the graphics context.
Specify the x and y coordinates of the upper-left corner of the rectangle, rela-
tive to the origin of the drawable.
Specify the dimensions in pixels of the rectangle to be filled.
"(i, rawRectangle (display, drawable, gc, 0, - 19, iII;
12 pixels
20 p,xels
XFzllRectangle(dzsplay, drawable, gc, , 0, 19, II);
12 pixels
20 pixels
Description
XFillRectangle fills the rectangular area in the specified drawable using the x and y
coordinates, width and height dimensions, and graphics context you specify. XFill-
Rectangle draws some but not all of the path drawn by XDrawRectangle with the same
arguments.
XFillRectangle uses these graphics context components: function, plane_mask,
fill_style, subwindow_mode, clip x origin, clip_y_origin, and clip_
mask. This function also us these graphics context components depending on the
fill_style: foreground, background tile, stipple, ts x origin, and
ts_y_origin.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter
5, The Graphics Context.
178 Xlib Reference Manual
Xlib- Drawing Primitives (continued) XFillRectangle
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDraw-
Point, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments,
XCopyArea, XCopyPlane, XFilIArc, XFilIArcs, XFillPolygon, XFill-
Rectangles, XClearArea, XClearWindow.
July 26, 1988 179
XFillRectangles
Xlib- Drawing Primitives--
Name
XFillRectangles -- fill multiple rectangular areas.
Synopsis
XFillRectangles(display, drawable,
Display *display;
Drawable drawable;
GC gc;
XRectangle *rectangles;
int nrectangles;
gc, rectangles, nrectangles)
Arguments
display
drawable
gc
rectangles
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the drawable.
Specifies the graphics context.
Specifies a pointer to an array of rectangles.
nrectangles Specifies the number of rectangles in the array.
rawRerangle(dzsplay, drawable, gc, , "
1:1 I1 III I I.I ] ! ! 1.1 ! ! [ [ !12 pixels
[,,J 1 [ [ I I I I I 11 I I I 1 II ] II
i]lllllllllllllllll|l
20 p,xels
111;
XFillRectangle(display, drawable, gc, 0, , t9, II);
|[|lllIlltlltllltlll
t[llltI[[ttlllll|ttl
1111111111111111111112 pixels
tlt|ltllltlltllltltl $
tllttllilltlllilI|ll
Ilttttltlttt|lllttll
Ilttltlllttlillltlll
1[111111111111111111
20 p,xels
Description
XFillRectangles fills multiple rectangular areas in the specified drawable using the
graphics context.
The x and y coordinates of each rectangle are relative to the drawable's origin, and define the
upper left corner of the rectangle. The rectangles are drawn in the order listed. For any given
rectangle, no pixel is drawn more than once. If rectangles intersect, the intersecting pixels will
be drawn multiple times.
XFillRectangles usesthese graphics contextcomponents: function, plane_mask,
fill_style, subwindow_mode, clip x origin, clip_y_origin, and clip_
mask. This nction so usesthesegraphicscontextcomponen depending on the fill
--
style: foreground, background, tile, stipple, ts x origin, and ts_y_
origin.
180 Xlib Reference Manual
XFindContext
Xlib - Context Manager--
Name
XFindContext -- get data from the context manager (not graphics context).
Synopsis
int XFindContext(display,
Display *display;
Window w;
XContext context;
caddr t *data;
--
w, context, data)
/* RETURN */
Arguments
display
w
context
data
Description
Specifies a pointer to the Display sl/ucture; returned from XOpen-
Display.
Specifies the window with which the data is associated.
Specifies the context type to which the data corresponds.
Returns the data.
XFindContext gets data that has been assigned to the specified window and context ID.
The context manager is used to associate data with windows for use within an application.
This application should have called xUniqueContext to get a unique ID, and then xSave-
Context to save the data into the array. The meaning of the data is indicated by the context
ID, but is completely up to the client.
XFindContext returns XCNOENT (a nonzero error code) if the context could not be found
and zero (0) otherwise.
For more information on the context manager, see Volume One, Chapter 13, Other Program-
ming Techniques.
Structures
typedef int XContext
Related Commands
XDeleteContext, XSaveContext, XUniqueContext.
182 July 26, 1988
--Xlib - Output Buffer
XFlush
Name
XFlush -- flush the output buffer (display all queued requests).
Synopsis
XFlush(display)
Display *display;
Arguments
display
Specifies a pointer D the Display sucture; retumed om XOpen-
Display.
Description
XFlush sends to the display ("flushes") all output requests that have been buffered but not
yet sent.
Flushing is done automatically when input is read if no matching events are in Xlib's queue
(with XPending, XNextEvent, or XWindowEvent), or when a call is made that gets
information from the server (such as XQueryPointer, XGetFontInfo) so XFlush is
seldom needed. It is used when the buffer must be flushed before any of these calls are
reached.
For more information, see Volume One: Chapter 2, X Concepts; and Chapter 3, Basic Win-
dow Program.
Related Commands
XSync
July 26, 1988
183
--Xlib- HouseKeeping
Name
XFree -- free specified in-memory data created by an Xlib function.
Synopsis
XFree (data)
caddr t data;
--
Arguments
data Specifies a pointer to the data that is to be freed.
Description
XFree is a general purpose routine for freeing data allocated by Xlib calls.
Related Commands
XOpenDisplay, XCloseDisplay, XNoOp, DefaultScreen.
XFree
July 26, 1988
185
XFreeColormap
Xlib - Colormaps m
Name
XFreeColormap -- delete a colormap and install the default colormap.
Synopsis
XFreeColormap(display, cmap)
Display *display;
Colormap cmap;
Arguments
display
Specifies a pointer to the Display structure; returned from XOpen-
Display.
cmap
Specifies the colormap to delete.
Description
XFreeColormap destroys the specified colormap, unless it is the default colormap for a
screen. That is, it not only uninstalls crnap from the hardware colormap if it is installed, but
also frees the associated memory including the colormap ID.
XFreeColormap performs the following processing:
If cmap is an installed map for a screen, it uninstalls the colormap and installs the
default if not already installed.
If cmap is defined as the colormap attribute for a window (by XCreateWindow or
XCha ngeWindowAt t r ibut e s), it changes the colormap associated with the window
to the constant None, generates a ColormapNotify event, and frees the colormap.
The colors displayed with a colormap of None are server-dependent, since the default
colormap is normally used.
For more information, see Volume One, Chapter 7, Color.
Errors
BadColor
Related Commands
XCopyColormapAndFree, XCreateColormap, XGetStandardColormap,
XInstallColormap, XUninstallColormap, XSetStandardColormap, XList-
InstalledColormaps, XSetWindowColormap, DefaultColormap, Display-
Cells.
186 July 26, 1988
--Xlib - Color Cells
XFreeColors
Name
XFreeColors--free colormapcellsorplanes.
Synopsis
XFreeColors (display, cmap, pixels, npixels, planes)
Display *display;
Colormap cmap;
unsigned long pixels[];
int npixels;
unsigned long planes;
Arguments
display
cmap
pixels
npixels
planes
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the colormap.
Specifies an array of pixel values. These pixel values map to the cells in the
specified colormap.
Specifies the number of pixels.
Specifies the planes you want to free.
XFreeColors frees the cells whose values are computed by ORing together subsets of the
planes argument with each pixel value in the pixels array.
If the cells are read/write, they become available for muse, unless they were allocated with
XAllocColorPlanes, in which case all the related pixcls may need to be freed before any
become available.
If the cells were read-only, they become available only if this is the last client to have allo-
cated those shared cells.
For more information, see Volume One, Chapter 7, Color.
Errors"
BadAccess
A colorcell allocated by client (either unallocated or allocated by another
client).
BadColor
BadValue A pixel value is not a valid index into cmap.
Note: if more than one pixel value is in error, the one reported is arbitrary.
Related Commands
XAllocColorCells, XAllocColorPlanes, XAllocColor, XAllocNamedColor,
XLookupColor, XParseColor, XQueryColor, XQueryColors, XStoreColor,
XStoreColors, XStoreNamedColor, BlackPixel, WhitePixel.
July 26, 1988 187
XFreeCursor
Xlib - Cursors m
Name
XFreeCursor -- destroy a cursor.
Synopsis
XFreeCursor (display, cursor)
Display *display;
Cursor cursor;
Arguments
display
cursor
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the ID of the cursor to be affected.
XFreeCursor deletes the association between the cursor ID and the specified cursor. The
cursor storage is freed when all other clients have freed it. Windows with their cursor attribute
set to this cursor will be changed to None (which implies CopyFromParent). The
specified cursor ID should not be referred to again.
Errors
BadCursor
Related Commands
XDefineCursor, XUndefineCursor, XCreateFontCursor, XCreateGlyph-
Cursor, XCreatePixmapCursor, XRecolorCursor, XQueryBestCursor,
XQueryBestSize.
188 July 26, 1988
mXlib- Extensions
XFreeExtensionList
Name
XFreeExtensionList m free memory allocated for a list of installed extensions to X.
Synopsis
XFreeExtensionList(list)
char **list;
Arguments
list
Specifies a pointer to e list of extensions retued om XList-
Extensions.
Description
XFreeExtensionList frees e memory allocated by XListExtensions.
For more information, see Volume One, Chapter 13, Other Programming Techniques.
Related Commands
XListExtensions, XQueryExtension.
July 26, 1988 189
XFreeFont
Xlib- Fonts--
Name
XFreeFont -- unload a font and free storage for the font structure.
Synopsis
XFreeFont (display, font struct)
--
Display *display;
XFontStruct *font struct;
--
Arguments
display Specifies a pointer to the Display structure; returned from XOpen-
Display.
fon_struct Specifies the storage associated with the font.
Description
XFreeFont frees the memory located for e font struct font information sucture
(XFontStruct) filled by XQueryFont or XLoadQueryFont. XFreeFont frees aH
storage associated with the fon_struct argument. Neither the data nor the font should be
referenced again.
The font itself is unloaded if no other client has loaded it.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct {
XExtData *ext data; /*
--
Font fid; /*
unsigned direction; /*
unsigned min char or byte2; /*
--
unsigned max char or byte2; /*
--
unsigned min_bytel; /*
unsigned max_bytel; /*
Bool all chars exist; /*
-- _
unsigned default char; /*
_
int n_properties; /*
XFontProp *properties; /*
XCharStruct min bounds; /*
--
XCharStruct max bounds; /*
--
XCharStruct *per_char; /*
int ascent; /*
int descent; /*
} XFontStruct;
hook for extension to hang data */
Font ID for this font */
hint about direction the font is painted */
first character */
last character */
first row that exists */
last row that exists */
flag if all characters have nonzero size*/
char to print for undefined character */
how many properties there are */
pointer to array of additional properties*/
minimum bounds over all existing char*/
minimum bounds over all existing char*/
first char to last char information */
-- _
logical extent above baseline for spacing */
logical descent below baseline for spacing */
Errors
BadFont
Related Commands
XLoadFont, XLoadQueryFont, XFreeFontinfo, XListFonts, XListFontsWith-
Info, XFreeFontNames, XFreeFontPath, XGetFontPath, XQueryFont, XSet-
Font, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor.
190 July 26, 1988
XFreeFontNames
Xlib - Fonts m
Name
XFreeFontNames -- free the font name array.
Synopsis
XFreeFontNames (list)
char *list[];
Arguments
list
Specifies the array of font name strings to be freed.
Description
XFreeFontNames frees e aay of strings returned by XListFonts.
Related Commands
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts,
XListFontsWithInfo, XFreeFontPath, XGetFontPath, XQueryFont, XSet-
Font, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor.
192 July 26, 1988
nXlib - Fonts
XFreeFontPath
Name
XFreeFontPath -- free the memory allocated by XGetFontPath.
Synopsis
XFreeFontPath(list)
char **list;
Arguments
list Specifiesanarrayofsngsallocadby XGetFontPath.
Description
XFreeFontPath frees the dam used by the aay of panames returned by XGetFont-
Path.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Reled Commands
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts,
XListFontsWithInfo, XFreeFontNames, XGetFontPath, XQueryFont, XSet-
Font, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor.
July 26, 1988
193
--Xlib- Keyboard
XFreeModifiermap
Name
XFreeModifiermap -- destroy and free a keyboard modifier mapping structure.
Synopsis
XF reeModi f ie rmap ( modmap )
XModi fierKeymap *modmap;
Arguments
modmap
Specifies a pointer to the XModifierKeymap sucture to be freed.
Description
XFreeModifiermap frees the specified XModifierKeymap structure.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Structures
typedef struct {
int max_keypermod; /* server's max number of keys per modifier */
KeyCode *modifiermap; /* an 8 by max_keypermod array of
* keycodes to be used as modifiers */
} XModifierKeymap;
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XKeycodeToKeysym,
XKeysymToKeycode, XKeysymToString, XNewModifierMap, XQueryKeymap,
XStringToKeysym, XLookupKeysym, XRebindKeySym, XGetKeyboardMapping,
XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookupString,
XSetModifierMapping, XGetModifierMapping.
July 26, 1988 195
XFreePixmap
Xlib - Pixmaps and Tiles--
Name
XFreePixmap m free a pixmap ID.
Synopsis
XFreePixmap ( display, pixmap)
Display *display;
Pixmap pixmap ;
Arguments
di spl ay
pixmap
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the pixmap whose ID should be freed.
XFreePixmap disassociates a pixmap ID from its resource. If no other client has an ID for
that resource, it is freed. The P ixmap should never be referenced again by this client. If it
is, the ID will be unknown and a BadPixmap error will result.
Errors
BadPixmap
Reined Commands
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindow-
BackgroundPixmap, XCreatePixmap, XCreatePixmapFromBitmapData,
XQueryBestSize, XQueryBestStipple, XWriteBitmapFile, XReadBitmap-
File, XCreateBitmapFromData.
196 July 26, 1988
mXlib - Graphics Context
XGContextFromGC
Name
XGContextFromGC -- obtain the GContext (resource ID) associated with the specified
graphics context.
Synopsis
GContext XGContextFromGC(gc)
GC gc;
Arguments
gc
Specifies the graphics context of the desired resource ID.
Description
XGContextFromGC extracts the resource ID from the GC structure. Using the gc argu-
ment, gc->gid does the same thing, except that applications shouldn't reference members of
the gc structure directly.
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XSetStipple, XSetTSOrigin,
XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillRule, XSet-
FillStyle, XSetForeground, XSetBackground, XSetFunction, XSet-
GraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSet-
ClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
July 26, 1988 19 7
Xlib - Standard Geometry (continued) XGeometry
and items enclosed in { } are a set from which one item is to be chosen. Note that the brackets
should not appear in the actual string.)
The XGeometry return value is a bitmask that indicates which values were present in
user_geom. This bitmask is composed of the exclusive OR of the symbols XValue,
YValue, WidthValue, HeightValue, XNegative, or YNegative.
If the function returns either XValue or YValue, you should place the window at the
requested position. The border width (bwidth), size of the width and height increments (typ-
ically fwidth and fheight), and any additional interior space (xadder and yadder) are
passed in to make it easy to compute the resulting size.
Related Commands
XParseGeomet ry, XT rans lateCoo rdinates.
July 26, 1988 199
XGetDefault
Xlib- User Preferences--
Name
XGetDefault -- scan the user preferences for program name and options.
Synopsis
char *XGetDefault (display, program, option)
Display *display;
char *program;
char *option;
Arguments
display
program
opt i on
Description
Specifies a pointer to the Display structure; returned from XOpenDisplay.
Specifies the program name to be looked for in the user's resource database.
The program name is usually a rgv [ 0 ], the first argument on the UNIX com-
mand line.
Specifies the option name or keyword. Lines containing both the program
name and the option name will be matched.
XGetDefault returns a character string containing the user's default value for the specified
program name and option name. XGetDefault returns NULL if no key can be found
that matches option and program. For a description of the matching rules, see XrraGet-
Resource.
The strings returned by XGetDefault are owned by Xlib and should not be modified or
freed by the client.
Lines in the user's resource database look like this:
xterm, foreground: #c0c0ff
xterm, geometry : =81x28
xterm, saveLines : 256
xterm, font : 8x13
xterm, keyMapFil e : /usr/black/. keymap
xterm, act iveI con : on
xmh. header, font 9xl 5
The portion on the left is known as a key; the portion on the right is the value. Upper or
lower case is important in keys. In some programs the standard is to capitalize only the
second and successive words in each option, if any. In others, the first word is also capital-
ized.
Defaults are usually loaded into the XA_RESOURCE_MANAGER property on the root window
at login. If no such property exists, a resource file in the user's home directory is loaded. On
a UNIX system, this file is $HOMEI.Xdefaults. After loading these defaults, XGetDefault
merges additional defaults specified by the XENVIRONMENT environment variable. If XEN-
VIRONMENT is defined, it contains a full path name for the additional resource file. If XEN-
VIRONMENT is not defined, XGetDefault looks for $HOMEIgfdefaults-name, where
name specifies the name of the machine on which the application is running.
202 July 26, 1988
Xlib- User Preferences (continued) XGetDefault
The first invocation of XGetDefault reads the defaults into memory so that subsequent
requests are fast. Therefore, changes to the defaults files from the program will not be felt
until the next invocation.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Related Commands
XAutoRepeatOff, XAutoRepeatOn, XBell, XGetKeyboardControl, XChange-
KeyboardControl, XGetPointerControl.
July 26, 1988 203
XGetErrorText
Xlib- Error Handling--
Name
XGetErrorText -- obtain a description of error code.
Synopsis
XGetErrorText(display,
Display *display;
int code;
char *buffer;
int length;
code, buffer, length)
/* RETURN */
Arguments
di splay
code
buffer
length
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the error code for which you want to obtain a description.
Returns a pointer to the error description text.
Specifies the size of the buffer.
XGetErrorText obtains textual descriptions of errors. XGetErrorText returns a pointer
to a null-terminated string describing the specified error code with length 2ength. This
string is copied from static data and therefore may be freed. This routine allows extensions to
the Xlib library to define their own error codes and error strings, which can be accessed easily.
For more information, see Volume One, Chapter 3, Basic Window Program.
Related Commands
XDisplayName, XGetErrorDatabaseText, XSetErrorHandler, XSetIOError-
Handler, XSynchronize, XSetAfterFunction.
206 July 26, 1988
mXlib- Fonts
XGetFontPath
Name
XGetFontPath -- get the current font search path.
Synopsis
char **XGetFontPath ( display,
Display *display;
int *npaths;
Arguments
display
npaths )
/* RETURN number of elements */
Specifies a pointer to the Display sucture; returned from XOpen-
Display.
Returns the number of strings in the font path army.
npaths
Description
XGetFontPath allocates and returns an array of strings containing the search path for fonts.
The data in the font path should be freed when no longer needed.
Related Commands
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts,
XListFontsWithInfo, XFreeFontNames, XFreeFontPath, XQueryFont, XSet-
Font, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor.
July 26, 1988 20 7
XGetFontProperty
Xlib- Properties m
Name
XGetFontProperty -- get a font property given its atom.
Synopsis
Bool XGetFontProperty (font_struct, atom, value)
XFontStruct *font struct ;
--
Atom atom;
unsigned long *value; /* RETURN */
Arguments
font struct Specifies the storage associated with the font.
--
atom Specifies the atom associated with the property name you want returned.
value
Returns the value of the font property.
Description
XGetFontProperty returns the value of the specified font property, given the atom for that
property. The function returns 0 if the atom was not defined, or 1 if was defined.
There are a set of predefined atoms for font properties which can be found in <Xll/Xatom.h>.
These atoms are listed and described in Volume One, Chapter 6, Drawing Graptu'cs and Text.
This set contains the standard properties associated with a font. The predefined font properties
are likely but not guaranteed to be present on any given server.
Structures
typedef struct {
XExtData *ext data;
--
Font fid;
unsigned direction;
unsigned min char or byte2;
--
unsigned max char or byte2;
_
unsigned min_bytel;
unsigned max_bytel;
Bool all chars exist;
-- _
unsigned default char;
--
int n_properties;
XFontProp *properties;
XCharStruct min bounds;
--
XCharStruct max bounds;
_
XCharStruct *per_char;
int ascent;
int descent;
} XFontStruct;
/* hook for extension to hang data */
/* Font ID for this font */
/* hint about direction the font is painted */
/* first character */
/* last character */
/* first row that exists */
/* last row that exists */
/* flag if all characters have nonzero size*/
/* char to print for undefined character */
/* how many properties there are */
/* pointer to array of additional properties*/
/* minimum bounds over all existing char*/
/* minimum bounds over all existing char*/
/* first char to last char information */
_ --
/* logical extent above baseline for spacing */
/* logical descent below baseline for spacing */
Related Commands
XSetStandardProperties, XRotateWindowProperties, XDeleteProperty,
XChangeP rope rt y, XGetWindowP rope rt y, XListP rope rt ie s, XGetAt omName,
XInte rnAt om.
208 July 26, 1988
mXlib - Window Attributes
XGetGeometry
Name
XGetGeometry m obtain the current geometry of drawable.
Synopsis
Status XGetGeometry (display, drawable, root,
width, height, border_width, depth)
Display *display;
Drawable drawable ;
Window *root ;
int *x, *y;
unsigned int *width, *height;
unsigned int *border width;
--
unsigned int *depth ;
X,
/* RETURN */
/* RETURN */
/* RETURN */
/* RETURN */
/* RETURN */
Y,
Arguments
display
drawable
root
X
Y
width
height
Specifies a pointer to the Display sucte; returned from XOpenDisplay.
Specifies the drawable, either a window or a pixmap.
Returns the root window ID of the specified window.
Return the coordinates of the upper-left pixel of the window's border, relative
to its parent's origin. For pixmaps, these coordinates are always 0.
Return the dimensions of the drawable. For a window, these return the inside
size (not including the border). For a pixmap, they just return the size.
border width
--
Returns the borderwidth, in pixels, of the window's border, if the drawable is a
window. Returns 0 if the drawable is a pixmap.
depth
Returns the depth of the pixmap (bits per pixel for the object). The depth must
be supported by the root of the specified drawable.
Description
This. function gets complete information about the root window and the current geometry of a
drawable.
XGetGeometry returns a Status of 0 on failure, or 1 on success.
Errors
BadDrawable
Related Commands
XGetWindowAttributes, XMoveWindow, XMoveResizeWindow, XResizeWindow,
XConfigureWindow.
Xlib Reference Manual 209
XGetlconName
Xlib - Window Manager Hints B
Name
XGetIconName -- get the name to be displayed in an icon.
Synopsis
Status XGetIconName (display, w, icon__name)
Display *display;
Window w;
char **icon name; /* RETURN */
Arguments
di splay
Specifies a pointer to the Display structure; returned from XOpen-
Display.
W
icon name
--
Specifies the ID of the window whose icon name you want to learn.
Returns a pointer to the name to be displayed in the window's icon. The
name should be a null-terminated string. If a name hasn't been assigned to
the window, XGetIconName sets this argument to NULL. When finished
with it, a client must free the icon name sxing using XFree.
Description
XGetIconName reads the icon name property of a window. This function is primarily used
by window managers to get the name to be written in that window's icon when they need to
display that icon.
XGetIconName returns a nonzero Status if it succeeds, and 0 if no icon name has been
set for the argument window.
For more information, see Volume One, Chapter 10, lnterclient Communication.
Errors
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGet-
WMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints,
XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetch-
Name, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSet-
Command.
210 July 26, 1988
mXlib - Window Manager Hints.
XGetlconSizes
Name
XGetlconSizes -- get preferred icon sizes.
Synopsis
Status XGetIconSizes(display, w, size_list, count)
Display *display;
Window w;
XIconSize **size_list; /* RETURN */
int *count; /* RETURN */
Arguments
display
w
size list
--
count
Description
Specifies a pointer to the Display structure; returned from XOpenDisplay.
Specifies the window ID (usually of the root window).
Returns a pointer to the size list.
Returns the number of items in the size list.
XGetIconSizes reads the XA_WM_ICON_SIZE property that should be set by the window
manager to specify its desired icon sizes. XGetIconSizes returns a Status of 0 if a win-
dew manager has not set icon sizes, and a nonzero Status otherwise. This function should
be called by all programs to find out what icon sizes are preferred by the window managcr.
The application should then use XSetWMHints to supply the window manager with an icon
pixmap or window in one of the supported sizes. To free the data allocated in size_list,
use XFree.
For more information, see Volume One, Chapter 10, lnterclient Communication.
Structures
typedef struct {
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
} MIconSize;
/* width_inc and height_inc provide the preferred
* increment of sizes in the range from min width
--
* to max_width and min_height to max_height. */
Errors
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGet-
WMHints, XSetWMHints, XGetZoornHints, XSetZoornHints, XGetNormalHints,
XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetch-
Name, XGetIconName, XStoreName, XSetIconSizes, XSetCommand.
July 26, 1988 211
Xlib -Images (continued) XGetlmage
If the drawable is a window, the window must be mapped, and it must be the case that, if
there were no inferiors or overlapping windows, the specified rectangle of the window would
be fully visible on the screen. Otherwise, a BadMatch error will occur. The returned image
will include any visible portions of inferiors or overlapping windows contained in the rectan-
gle. The specified area can include the borders. The returned contents of visible regions of
inferiors of different depth than the specified window are undefined.
If the window has a backing-store, the backing-store contents are returned for regions of the
window that are obscured by noninferior windows. Otherwise, the return contents of such
obscured regions are undefined. Also undefined are the returned contents of visible regions of
inferiors of different depth than the specified window.
For XYFormat format data, the bit order member of XImage specifies the bit order in
--
which your server expects the data.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Errors
BadDrawable
BadMatch
BadValue
See Description above.
Related Commands
XDestroyImage, XPutImage, XCreateImage, XSubImage, XGetSubImage, XAdd-
Pixel, XPutPixel, XGetPixel, ImageByteOrder.
July 26, 1988
213
XGetlnputFocus
Xlib - Input Handling--
Name
XGednpuocus--retum thecurrentkeybod cus window.
Synopsis
XGetInputFocus (display, focus, revert_to)
Display *display;
Window *focus; /* RETURN */
int *revert to; /* RETURN */
--
Arguments
di spl ay
focus
revert to
--
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Returns the ID of the focus window, or one of the constants PointerRoot
or None.
Returns the window to which the focus would revert if the focus window
became invisible. This is one of these constants: RevertToParent,
RevertToPointerRoot, or RevertToNone. Must not be a window
ID.
Description
XGetInputFocus returns the current focus window and the window to which the focus
would revert if the focus window became invisible.
XGet InputFocus does not report the last focus change time. This is available only from
events.
Related Commands
XSelectInput, XSetInputFocus, XWindowEvent, XCheckWindowEvent,
XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMask-
Event, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents,
XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent,
XPending, XSynchronize, XSendEvent, QLength.
214 July 26, 1988
Xlib - Keyboard (continued) XG etKeyboard Ma p p i n g
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap,
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifier-
Map, XQueryKeymap, XStringToKeysynXLookupKeysyXRebindKeySym,
XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookupString,
XSetModifierMapping, XGetModifierMapping.
July26, 1988 217
XGetModifierMapping
X Programming Library m
Name
XGetModifierMapping -- obtain a mapping of modifier keys (Shift, Control, etc.).
Synopsis
XModifierKeymap *XGetModifierMapping (display)
Display *display;
Arguments
display
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Description
XGetModifierMapping returns the keycodes of the keys being used as modifiers.
There are eight modifiers, represented by the symbols ShiftMapIndex, LockMapIndex,
ControlMapIndex, ModlMapIndex, Mod2MapIndex, Mod3MapIndex, Mod4Map-
Index, and Mod5MapIndex. The modifiermap member of the XModifierKeymap
structure contains eight sets of keycodes, each set containing max_keypermod keycodes.
Zero keycodes are not meaningful. If an entire raodifierraap is filled with O's, the
corresponding modifier is disabled. No keycode will appear twice anywhere in the map.
Structures
typedef struct {
int max_keypermod; /* server's max number of keys per modifier */
KeyCode *modifiermap; /* an 8 by max_keypermod array of
* keycodes to be used as modifiers */
} XModifierKeymap;
/* modifier names. Used to build a SetModifierMapping request or
to read a GetModifierMapping request. These correspond to the
masks defined above. */
#define ShiftMapIndex 0
#define LockMapIndex 1
#define ControlMapIndex 2
#define ModlMapIndex 3
#define Mod2MapIndex 4
#define Mod3MapIndex 5
#define Mod4MapIndex 6
#define Mod5MapIndex 7
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap,
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifier-
Map, XQueryKeymap, XStringToKeysym, XLookupKeysym, XRebindKeySym,
XGetKeyboardMapping, XChangeKeyboardMapping, XRefreshKeyboard-
Mapping, XLookupString, XSetModifierMapping.
218 July 26, 1988
XGetMotionEvents (continued) Xlib -Input Handling
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheck-
WindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent,
XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XIfEvent,
XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending,
XSynchronize, XSendEvent, QLength.
220 July 26, 1988
XGetNormalHints (continued) Xlib - Window Manager Hints
#define PResizeInc (IL << 6)/* program specified resize increments */
#define PAspect (IL << 7)/* program specified min/max aspect ratios */
#define PAllHints (PPositionlPSizelPMinSizelPMaxSizelPResizeInclPAspect)
Errors
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGet-
WMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XSetNormalHints,
XGetTransientForHint, XSetTransientForHint, XFetchName, XGetIcon-
Name, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSet-
Command.
222 July 26, 1988
XGetPixel (continued) Xlib -Images
Related Commands
XDestroyImage, XPutImage, XGetImage, XCreateImage, XSubImage, XGetSub-
Image, XAddPixel, XPutPixel, ImageByteOrder.
224 July 26, 1988
--Xlib- Pointer
XGetPointerControl
Name
XGetPointerControl -- get the current pointer preferences.
Synopsis
XGetPointerControl ( display, accel_numerator,
threshold)
Display *display;
int *accel_numerator, *accel denominator;
--
int *threshold;
accel denominator,
--
/* RETURN */
/* RETURN */
Arguments
di spl ay
Specifies a point to the Display structure; retumed om XOpen-
Display.
accel numerator
--
Returns the numerar r the acceleration multiplier.
accel denominator
--
Remmsthedenominator rtheacceleration multiplier.
threshold
Returns the acceleration threshold in pixels. The pointer must move more
than this amount before acceleration takes effect.
Description
XGetPointerControl gets the pointer acceleration parameters.
accel numerator/accel denominator is the number of pixels the cursor moves per
-- --
unit of motion of the pointer, applied only to the amount of movement over threshold.
Related Commands
XQueryPointer, XWarpPointer, XGrabPointer, XChangeActivePointerGrab,
XUngrabPointer, XGetPointerMapping, XSetPointerMapping, XChange-
PointerControl.
July 26, 1988 225
XGetPointerMapping
Xlib- Pointer
Name
XGetPointerMapping -- get the pointer button mapping.
Synopsis
int XGetPointerMapping(display, map, nmap)
Display *display;
unsigned char map[] ; /* RETURN */
int nmap;
Arguments
display
map
nmap
Specifies a pointer to the Display structure; returned from XOpenDisplay.
Returns the mapping list. Array begins with map [ ].
Specifies the number of items in mapping list.
Description
XGetPointerMapping returns the current mapping of the pointer buttons. Information is
returned in both the arguments and the function's return value, map is an array of the
numbers of the buttons as they are currently mapped. Elements of the list are indexed starting
from 1. The nominal mapping for a pointer is the identity mapping: map [i]=i. If
map [ 3 ] =2, it means that the third physical button triggers the second logical button.
nmap indicates the desired number of button mappings.
The return value of the function is the actual number of elements in the pointer list, which
may be greater or less than nmap.
Related Commands
XQueryPointer, XWarpPointer, XGrabPointer, XChangeActivePointerGrab,
XUngrabPointer, XSetPointerMapping, XGetPointerControl, XChange-
PointerControl.
226 July 26, 1988
XGetSelectionOwner
Xlib - Selections m
Name
XGetSelectionOwnermretumtheownerofaselection.
Synopsis
Window XGetSelectionOwner(display, selection)
Display *display;
Atom selection;
Arguments
display
selection
Descriion
Specifies a pointer the Display structu; remrned from XOpen-
Display.
Specifies the selection atom whose owner you want returned.
XGetSelectionOwner returns the window ID of the current owner of the specified selec-
tion. If no selection was specified, or there is no owner, the function returns the constant
None.
For more information on selections, see Volume One, Chapter 10, lnterclient Communication.
Errors
BadAtom
Related Commands
XSetSelectionOwner, XConvertSelection.
228 July 26, 1988
XGetSizeHints (continued) Xlib - Window Manager Hints
#define USSize (IL << I) /* user specified width, height */
#define PPosition (IL << 2) /* program specified
#define PSize (IL << 3) /* program specified
#define PMinSize (IL << 4) /* program specified
#define PMaxSize (IL << 5) /* program specified
#define PResizeInc (IL << 6) /* program specified
#define PAspect (IL << 7) /* program specified
position */
size */
minimum size */
maximum size */
resize increments */
min/max aspect ratios *!
#define PAllHints (PPositionlPSizelPMinSizelPMaxSizelPResizeInclPAspect)
E rro rs
BadAtom
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XSetSizeHints, XGetWMHints, XSet-
WMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, XSetNormal-
Hints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGet-
IconName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes,
XSetCommand.
230 July 26, 1988
Xlib - Colormaps
XGetStandardColormap
Name
XGetStandardColormap -- get the standard colormap property.
Synopsis
Status XGetStandardColormap ( display, w, cmap_info, property)
Display *display;
Window w;
XStandardColormap *cmap_info;/* RETURN */
Atom property;
Arguments
display
cmap_info
property
Specifics a pointer to the Display structure; returned from XOpen-
Display.
Specifies the ID of the window on which the property is set. This is nor-
mally the root window.
Returns the filled colormap information structure.
Specifies the atom indicating the type of standard colormap desired. The
predefined standard colormap atoms are XA RGB BEST MAP,
-- -- --
XA_RGB_RED_MAP, XA_RGB_GREEN_MAP, XA_RGB_B LUE_MAP,
XA_RGB_DEFAULT_MAP, and XA_RGB_GRAY_MAP.
Description
XGetStandardColormap gets a property on a window (normally the root window) that
describes a standard colormap.
This call does not load the colormap into the hardware colormap, it does not allocate entries,
and it does not even create a virtual colormap. It just provides information about one design
of colormap. The application can then attempt to create a virtual colormap of the appropriate
type, and allocate its entries according to the information in the XStandardColormap
structure. Installing the colormap must then be done with xInstallColormap, in coopera-
tion with the window manager. Any of these steps could fail, and the application should be
prepped.
If the server has already created a standard colormap of this type, then its ID will be returned
in the colormap member of the XStandardColormap structure. Some servers, particular
on high-performance workstations, will create some or all of the standard colormaps so they
can be quickly installed when needed by applications.
An application should go through the standard colormap creation process only if it needs the
special qualities of the standard colormaps. For one, they allow the application to convert
RGB values into pixel values quickly because the mapping is predictable. Given an
XStandardColormap structure for an XA_RGB_BEST_MAP colormap, and floating point
RGB coefficients in the range 0.0 to 1.0, you can compose pixel values with the following C
expression:
July26, 1988 231
XGetStandardColormap (continued) Xlib - Colormaps
pixel = base_pixel
+ ( (unsigned long)
+ ( (unsigned long)
+ ( (unsigned long)
(0.5 + r * red_max)) * red_mult
(0.5 + g * green_max)) * green_mult
(0.5 + b * blue_max)) * blue_mult;
The use of addition rather than logical-OR for composing pixel values permits allocations
where the RGB value is not aligned to bit boundaries.
See Volume One, Chapter 7, Color, for a complete description of standard colormaps.
Structures
typedef struct {
Colormap colormap; /* ID of colormap created by XCreateColormap */
unsigned long red max;
--
unsigned long red mult;
--
unsigned long green_max;
unsigned long green_mult;
unsigned long blue max;
--
unsigned long blue mult;
--
unsigned long base_pixel;
} XStandardColormap;
Errors
BadAtom
BadWindow
Related Commands
XCopyColormapAndFree, XCreateColormap, XFreeColormap, XInstall-
Colormap, XUninstallColormap, XSetStandardColormap, XListInstalled-
Colormaps, XSetWindowColormap, DefaultColormap, DisplayCells.
232 July 26, 1988
XGetSublmage (continued) Xlib - Images
If the window has a backing store, the backing store contents are returned for regions of the
window that are obscured by noninferior windows. Otherwise, the return contents of such
obscured regions are undefined. Also undefined are the returned contents of visible regions of
inferiors of different depth than the specified window.
XSubImage extracts a subimage from an image, instead of from a drawable like XGetSub-
Image.
For more information on images, see Volume One, Chapter 6, Drawing Graptu'cs and Text.
Errors
BadDrawable
BadGC
BadMatch
BadValue
Depth of dest_image is not the same as depth of drawable. See so
Description.
Related Commands
XDestroyImage, XPutImage, XGetImage, XCreateImage, XSubImage, XAdd-
Pixel, XPutPixel, XGetPixel, ImageByteOrder.
234 July 26, 1988
--Xlib - Window Manager Hints
XGetTransientForHint
Name
XGetTransientForHint -- get the XA_WM_TRANS IENT_FOR property of a window.
Synopsis
Status XGetTransientForHint (display, w, prop_window)
Display *display;
Window w;
Window *prop_window; /* RETURN */
Arguments
display Specifies a pointer to the Display structure; returned from XOpen-
Display.
w Specifies the ID of the window to be queried.
prop_window Returns the XA_WM_TRANS IENT_FOR property of the specified window.
Description
XGetTransientForHint obfins the XA_WM_TRANSIENT_FOR property for the
specified window. This function is normally used by a window manager. This property
should be set for windows that are to appear only temporarily on the screen, such as pop-up
menus and dialog boxes.
XGetTransientForHint returns a Status of 0 on failure, and nonzero on success.
For more information on using hints, see Volume One, Chapter 10, lnterclient Communica-
tion.
Errors
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGet-
WMHnts, XSetWMHins, XGetZoomHints, XSetZoomHints, XGetNormalHints,
XSetNormalHints, XSetTransientForHint, XFetchName, XGetIconName,
XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSetCommand.
July 26, 1988 235
Xlib - Visuals (continued) XGetVisuallnfo
#define VisualDepthMask
#define VisualClassMask
#define VisualRedMaskMask
#define VisualGreenMaskMask
#define VisualBlueMaskMask
#define VisualColormapSizeMask
#define VisualBitsPerRGBMask
#define VisualAllMask
0x4
0x8
0xl0
0x20
0x40
0x80
0xl00
0xlFF
Related Commands
XMatchVisualInfo, DefaultVisual.
July 26, 1988
237
XGetWi ndowAttri butes (continued) Xlib - Window Attributes
Bool save under;
--
Colormap colormap;
Bool map_installed;
int map_state;
long all event masks;
-- --
long your_event_mask;
long do_not_propagate_mask;
Bool override redirect;
--
Screen *screen;
} XWindowAttributes;
/* boolean, should bits under be saved */
/* colormap to be associated with window */
/* boolean, is colormap currently installed*/
/* IsUnmapped, IsUnviewable, IsViewable */
/* set of events all people have interest in*/
/* my event mask */
/* set of events that should not propagate */
/* boolean value for override-redirect */
/* pointer to correct screen */
Related Commands
XChangeWindowAttributes, XSetWindowBackground, XSetWindow-
BackgroundPixmap, XSetWindowBorder, XSetWindowBorderPixmap, XGet-
Geometry.
240 July 26, 1988
Xlib - Properties (continued) XGetWi ndowProperty
Errors
BadAtom
BadMatch
BadVa lue
BadWindow
Value of long_offset caused L to be negative above.
Related Commands
XSetStandardProperties, XGetFontProperty, XRotateWindowProperties,
XDeleteProperty, XChangeProperty, XListProperties, XGetAtomName,
XInternAtom.
July 26, 1988
243
--Xlib - Window Manager Hints ,
XGetZoomHints
Name
XGetZoomHints -- read the size hints property of a zoomed window.
Synopsis
Status XGetZoomHints(display, w, zhints)
Display *display;
Window w;
XSizeHints *zhints; /* RETURN */
Arguments
display
Specifies a poinr to the Display sucture; returned from XOpenDisplay.
Specifies the ID of the window to be queried.
Returns a pointer to the zoom hints.
zhints
Description
XGetZoomHints is primarily for window managers. XGetZoomHints returns the size
hints for a window in its zoomed state (not normal or iconified) read from the
XA WM ZOOM HINTS property. It returns a nonzero Status if it succeeds, and 0 if the
application did not specify zoom size hints for this window.
For more information on using hints, see Volume One, Chapter 10, lnterclient Communica-
tion.
Structures
typedef struct {
long flags; /* which fields in structure are defined */
int x, y;
int width, height;
int min width, min_height;
--
int max width, max_height;
--
int width inc, height_inc;
--
struct {
int x; /* numerator */
nt y; /* denominator */
} min_aspect, max_aspect;
} XSizeHints;
/* flags argument in size hints */
#define USPosition (IL << 0) /* user specified x, y */
#define USSize (IL << I) /* user specified width, height */
#define PPosition (IL << 2)
#define PSize (IL << 3)
#define PMinSize (IL << 4)
#define PMaxSize (IL << 5)
#define PResizeInc (IL << 6)
#define PAspect (IL << 7)
#define PAllHints (PPosition
/* program specified position */
/* program specified size */
/* program specified minimum size */
/* program specified maximum size */
/* program specified resize increments */
/* program specified min/max aspect ratios
IPSizelPMinSizelPMaxSizelPResizeInclPAspect)
July 26, 1988
245
XGetZoomHints (continued) Xlib - Window Manager Hints
Errors
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGet-
WMHints, XSetWMHints, XSetZoomHints, XGetNormalHints, XSetNormal-
Hints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGet-
IconName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes,
XSetCommand.
246 July 26, 1988
BXlib - Grabbing
/ XGrabButton
Name
XGrabButton -- grab a pointer button.
Synopsis
XGrabButton(display, button, modifiers, grab_window,
owner_events, event_mask, pointer_mode, keyboard_mode,
confine to, cursor)
Display *display;
unsigned int button;
unsigned int modifiers;
Window grab_window;
Bool owner events;
unsigned int event mask;
int pointer_mode, keyboard_mode ;
Window confine to;
Cursor cursor;
Arguments
di spl ay
Specifies a pointer to the Display structure; returned from XOpen-
Display.
button Specifies the mouse button. Mmy be Buttonl, Button2, Button3, But-
ton4, Button5, or AnyButton. The constant AnyButton is equivalent
to issuing the grab request for all possible buttons. The button symbols can-
not be ORed.
modifiers Specifies a set of keymasks. This is a bitwise OR of one or more of the fol-
lowing symbols: ShiftMask, LockMask, ControlMask, ModlMask,
Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask, or AnyModifier.
AnyModifier is equivalent to issng the grab key request for all possible
modifier combinations (including no modifiers).
gra_window Specifies the ID of the window you want to grab.
owner events
-- Specifies a boolean value of either True or False. See Description below.
event mask Specifies the event mask. This mask is the bitwise OR of one or more of the
--
event masks listed on the reference page for xSelect Input.
pointer_mode
Controls further processing of pointer events. Pass one of these constants:
GrabModeSync or GrabModeAsync.
keyboard_mode
Controls further processing of keyboard events. Pass one of these constants:
GrabModeSync or GrabModeAsync.
confine to Specifies the ID of the window to confine the pointer. One possible value is
-- the constant None, in which case the pointer is not confined to any window.
July 26, 1988 24 7
XGrab Button (continued) Xlib - Grabbing
cursor
Specifies the cursor to be displayed during the grab. One possible value you
can pass is the constant None.
Description
XGrabButton establishes a passive grab, such that an active grab may take place when the
specified key/button combination is pressed. After this call, if
1)
3)
the specified button is pressed when the specified modifier keys are down (and no other
buttons or modifier keys are down),
grab_window contains the pointer,
4)
the confine_to window (if any) is viewable, and
these constraints are not satisfied for any ancestor,
then the pointer is actively grabbed as described in GrabPointer, the
last_pointer_grab time is set to the time at which the button was pressed, and the
But t onP re s s event is reported.
The interpretation of the remaining arguments is as for XGrabPointer. The active grab is
terminated automatically when all buttons are released (independent of the state of modifier
keys).
A modifier of AnyModifier is equivalent to issuing the grab request for all possible
modifier combinations (including no modifiers). A button of AnyButton is equivalent to
issuing the request for all possible buttons (but at least one).
The request fails if some other client has already issued a GrabButton with the same
button/key combination on the same window. When using AnyModifier or AnyButton,
the request fails completely (no grabs are established) if there is a conflicting grab for any
combination. The request has no effect on an active grab.
The owner_events argument specifies whether the grab window should receive all events
(True) or whether the grabbing application should receive all events normally (False).
The pointer_mode and keyboard_mode control the processing of events during the
grab. If either is GrabModeSync, events for that device are not queued for applications until
XAllowEvents is called to release the events. If either is GrabModeAsync, events for
that device are processed normally.
An automatic grab takes place between a ButtonPress and a ButtonRelease, SO this
call is not necessary in some of the most common situations.
For more information on grabbing, see Volume One, Chapter 9, The Keyboard and Pointer.
248 July 26, 1988
XGrabKey
Xlib - Grabbing
Name
XGrabKey -- grab a key.
Synopsis
XGrabKey (display, keycode, modifiers, grab_window,
owner_events, pointer_mode, keyboard_mode)
Display *display;
int keycode ;
unsigned int modifiers;
Window grab_window;
Bool owner events;
--
int pointer_mode, keyboard_mode ;
Arguments
display
Specifies a pointer to the Display structure; returned from X0pen-
Display.
keycode Specifies the keycode to be grabbed. It may be a modifier key. Specifying
AnyKey is equivalent to issuing the request for all key codes.
modifiers Specifies a set of keymasks. This is a bitwise OR of one or more of the fol-
lowing symbols: ShiftMask, LockMask, ControlMask, ModlMask,
Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask, or AnyModifier.
AnyModifier is equivalent to issuing the grab key request for all possible
modifier combinations (including no modifiers). A specified modifiers do
not need to have currently assigned keycodes.
9tab_window Specifies the window from which you want to receive input from the
grabbed key combination.
owner events
Specifies whether the grab window should receive all events (True) or
whether the grabbing application should receive all events normally
(False).
pointer_mode
Controls further processing of pointer events. Pass one of these constants:
GrabModeSync or GrabModeAsync.
keyboard_mode
Controls further processing of keyboard events. Pass one of these constants:
GrabModeSync or GrabModeAsync.
Description
XGrabKey establishes a passive grab on the specified keys, such that when the specified
key/modifier combination is pressed, the keyboard is grabbed, and all keyboard events are sent
to this application. More formally:
250 Ju26, 1988
XGrabPointer
Xlib - Grabbing
Name
XGrabPointer -- grab the pointer.
Synopsis
int XGrabPointer (display, grab_window, owner_events,
event_mask, pointer_mode, keyboard_mode, confine_to,
cursor, time)
Display *display;
Window grab_window;
Bool owner events;
unsigned int event mask;
--
int pointer_mode, keyboard_mode ;
Window confine to;
--
Cursor cursor;
Time time ;
Arguments
display Specifies a pointer to the Display structure; returned from XOpen-
Display.
grab_window Specifies the ID of the window that should grab the pointer input indepen-
dent of pointer location.
owner events
--
Specifies if the pointer events are to be reported normally within this applica-
tion (pass True) or only to the grab window if selected by the event mask
asS False).
event_mask Specifies the event mask. See XSelectInput for a complete Hst of event
masks.
pointer_mode
Controls funher processing of pointer events. Pass either GrabModeSync
or GrabModeAsync.
keyboard_mode
Controls further processing of keyboard events. Pass either GrabMode-
Sync or GrabModeAsync.
confine_to Specifies the ID of the window to confine the pointer. One option is None,
in which case the pointer is not confined to any window.
cursor Specifies the ID of the cursor that is displayed with the pointer during the
grab. One option is None, which causes the cursor to keep its current pat-
tern.
time Specifies the time when the grab request took place. Pass either a times-
tamp, expressed in milliseconds (from an event), or the constant Current-
Time.
254 July 26, 1988
XGrabPointer (continued) Xlib - Grabbing
If the specified time is earlier than the last-pointer-grab time or later than the current X
server time, GrabTnvalidTirrte is returned. (If the call succeeds, the last pointer
grab time is set to the specified time, with the constant CurrentTirae replaced by the
current X server time.)
For more information on grabbing, see Volume One, Chapter 9, The Keyboard and Pointer.
Errors
BadCursor
BadValue
BadWindow
Related Commands
XGrabKey, XUngrabKey, XGrabKeyboard, XUngrabKeyboard, XGrabButton,
XUngrabButton, XUngrabPointer, XChangeActivePointerGrab, XGrab-
Server, XUngrabServer.
256 July 26, 1988
--Xlib - Grabbing
XGrabServer
Name
XGrabServer -- grab the server.
Synopsis
XGrabServer (display)
Display *display;
Arguments
display Specifies a pointer to the Display structure; returned from XOpen-
Display.
Description
Grabbing the server means that only requests by the calling client will be acted on. All others
will be queued in the server until the next XUngrabServer call. The X server should not
be grabbed any more than is absolutely necessary.
Reled Commands
XGrabKey, XUngrabKey, XGrabKeyboard, XUngrabKeyboard, XGrabButton,
XUngrabButton, XGrabPointer, XUngrabPointer, XChangeActivePointer-
Grab, XUngrabServer.
July 26, 1988 257
--Xlib - Resource Manager
XlnsertModifiermapEntry
Name
XlnsertModifiermapEntry -- add a new envy to an XModifierKeymap structure.
Synopsis
XModifierKeymap *XInsertModifiermapEntry (modmap,
keysym_entry, modifier)
XModifierKeymap *modmap ;
KeyCode keysym_entry;
int modifier ;
Arguments
modmap Specifies a pointer to an XModifierKeymap sucture.
keysym_en t ry
Specifies the keycode of the key to be added to modmap.
modifier Specifies the modifier you want mapped to the keycode specified in
keysym_entry. This should be one of the constants: ShiftMapIndex,
LockMapIndex, ControlMapIndex, ModlMapIndex, Mod2Map-
Index, Mod3MapIndex, Mod4MapIndex, or Mod5MapIndex.
Description
XInsertModifiermapEntry returns an XModifierKeymap structure suitable for cal-
ling XSetModifierMapping, in which the specified keycode is deleted from the set of
kcycodcs that is mapped to the specified modifier (like Shift or Control). XInsert-
ModifiermapEntry does not change the mapping itself.
This function is normally used by calling XGetModifierMapping to get a pointer to the
current XModifierKeymap structure for use as the modmap argument to XInsert-
ModifiermapEnt ry.
Note that the structure pointed to by modmap is freed by XInsertModifiermapEntry.
It should not be freed or otherwise used by applications.
For a description of the modifier map, see XSetModifierMapping.
Structures
typedef struct {
int max_keype rmod;
KeyCode *modifiermap;
} XModifierKeymap;
/* server's max number of keys per modifier */
/* an 8 by max_keypermod array of
* keycodes to be used as modifiers */
#define ShiftMapIndex 0
#define LockMapIndex 1
#define ControlMapIndex 2
#define ModlMapIndex 3
#define Mod2MapIndex 4
#define Mod3MapIndex 5
July 26, 1988 259
XlnsertModifiermapEntry (continued) Xlib- Resource Manager
#define Mod4MapIndex 6
#define Mod5MapIndex 7
Related Commands
XDeleteModifiermapEntry, XGetModifierMapping, XSetModifierMapping,
XNewModifierMap, XFreeModifiermap, XKeycodeToKeysym, XKeysym-
ToKeycode, XKeysymToString, XQueryKeymap, XStringToKeysym, XLookup-
Keysym, XRebindKeySym, XGetKeyboardMapping, XRefreshKeyboardMapping,
XLookupString.
260 July 26, 1988
XlnstallColormap (continued) Xlib - Colormaps
Related Commands
XCopyColormapAndFree, XCreateColormap, XFreeColormap, XGetStandard-
Colormap, XUninstallColormap, XSetStandardColormap, XListInstalled-
Colormaps, XSetWindowColormap, DefaultColormap, DispIayCells.
262 July 26, 1988
--Xlib- Properties
XlnternAtom
Name
XlnternAtom -- return an atom for a given name string.
Synopsis
Atom XInternAtom (display, property_name,
Display *display;
char *property_name ;
Bool only_if_exists ;
only_if_exists )
Arguments
display Specifies a pointer to the Display structure; returned from XOpen-
Display.
property_name
Specifies the name associated with the property you want the atom for.
Upper or lower case is important. The string should be in ISO LATIN-1
encoding, which means that the first 128 character codes are ASCII, and the
second 128 character codes are for special characters needed in western
languages other than English.
only_if_exists
Specifies a boolean value that indicates whether XInternAtom should
return None or should create the atom if no such property_name exists.
Description
X I nt e rnAt om returns the atom identifier corresponding to property_n ame.
If the atom does not exist, then XInternAtom either returns None (if only_ if exists
is True ) or creates the atom and returns its ID (if only_if_exists is False ). The
string name should be a null-terminated ASCII string. Case matters: the strings "thing,"
"Thing," and "thinG" all designate different atoms. The atom will remain defined even after
the client that defined it has exited. It will become undefined only when the last connection to
the X server closes.
This. function is the oppo.site of XGetAtoraName, which returns the atom name when given
an atom ID.
Predefined atoms are defined in <X11/Xatom.h> and begin with the prefix "XA_"
Errors
BadAlloc
BadValue
Related Commands
XS et S t a nda rdP rope rt ie s, XGet Font P rope rt y, XRot at eWindowP rope rt ie s,
XDe let eP rope rt y, XChangeP rope rt y, XGet Windo wP rope rt y, XLi s t -
P ropert ies, XGetAtomName.
Xlib Reference Manual 263
XlntersectRegion
Xlib - Regions
Name
XlntersectRegion -- compute the intersection of two regions.
Synopsis
XIntersectRegion(sra, srb, dr)
Region sra , srb ;
Region dr; /* RETURN */
Arguments
dr
Specify the two regions with which to perform the computation.
Returns the result of the computation.
Description
XIntersectRegion generates a region that is the intersection of two regions.
Structures
/,
* opaque reference to Regiondata type.
* user won't need contents, only pointer.
*/
typedef struct _XRegion *Region;
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion,
XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPoint-
InRegion, XOffsetRegion, XEmptyRegion, XCreateRegion, XDestroyRegion,
XEqualRegion, XClipBox.
264 July 26, 1988
XKeysymToKeycode
Xlib - Keyboard--
Name
XKeysymToKeycode m convert a keysym to the appropriate keycode.
Synopsis
KeyCode XKeysymToKeycode (display,
Display *display;
Keysym keysym_kcode;
keysym_kcode)
Arguments
display Specifies a pointer 0 the Display sucture; returned from XOpen-
Display.
keysym_kcode
Specifies the keysym that is to be searched for.
Description
XKeysymToKeycode turns the keycode coesponding to the spified keysym symbol in
the current mapping. If the spified keysym is not defined r any keycode, XKeysyra-
ToKeycode turns0.
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap,
XKeycodeToKeysym, XKeysymToString, XNewModifierMap, XQueryKeymap,
XStringToKeysym, XLookupKeysym, XRebindKeySym, XGetKeyboardMapping,
XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookupString,
XSetModifierMapping, XGetModifierMapping, IsKeypadKey, IsCursorKey,
IsPFKey, IsFunctionKey, IsMiscFunctionKey, IsModifierKey.
266 July 26, 1988
mXlib - Keyboard
XKeysymToString
Name
XKeysymToString -- convert a keysym symbol to a string.
Synopsis
char *XKeysymToString (keysym_str)
KeySym keysym_str;
Arguments
keysym_str Specifies the keysym that is to be converted.
Description
XKeysymToString converts a keysym symbol (a number) into a character string. The
returned string is in a static area and must not be modified. If the specified keysym is not
defined, XKeysymToString returns NULL. For example, XKeysymToString converts
XK Shift to "Shift".
--
Note that XKeysymString does not return the string that is mapped to the keysym, but only
a string version of the keysym itself. In other words, even if the F1 key is mapped to the
string "STOP" using XRebindKeysym, XKeysymToString still returns "FI"
XLookupString, however, would return "STOP".
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap,
XKeycodeToKeysym, XKeysymToKeycode, XNewModifierMap, XQueryKeymap,
XStringToKeysym, XLookupKeysym, XRebindKeysym, XGetKeyboardMapping,
XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookupString,
XSetModifierMapping, XGetModifierMapping, IsKeypadKey, IsCursorKey,
IsPFKey, IsFunctionKey, IsMiscFunctionKey, IsModifierKey.
July 26, 1988 26 7
--Xlib- Extensions
XListExtensions
Name
XListExtensions -- return a list of all extensions to X supported by the server.
Synopsis
char **XListExtensions(display, nextensions)
Display *display;
int *nextensions; /* RETURN */
Arguments
display Specifies a pointer to the Display structure; returned from XOpen-
Display.
nextensions Returns the number of extensions in the returned list.
Description
XListExtensions lists all the X extensions supported by the current server. Upper or
lower case is important. The returned strings will be in ISO LATIN-1 encoding, which means
that the first 128 character codes are ASCII, and the second 128 character codes are for special
characters needed in western languages other than English.
For more information on extensions, see Volume One, Chapter 13, Other Programming Tech-
niques.
Related Commands
XQueryExtension, XFreeExtensionList.
July 26, 1988
269
XListFonts
Xlib- Fonts
Name
XListFonts -- return a list of the available font names.
Synopsis
char **XListFonts (display, pattern, maxnames,
Display *display;
char *pattern;
int maxnames ;
int *actual count; /* RETURN */
Arguments
di spl ay
pattern
maxnames
actual count)
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the string associated with the font names you want returned. You
can specify any string, an asterisk (*), or a question mark. The asterisk indi-
cates a wildcard for any number of characters and the question mark indi-
cates a wildcard for a single character. Upper or lower case is not important.
The string should be in ISO LATIN-1 encoding, which means that the first
128 character codes are ASCII, and the second 128 character codes are for
special characters needed in western languages other than English.
Specifies the maximum number of names that are to be in the returned list.
actual count
--
Returns the actual number of font names in the list.
Description
XListFonts returns a list of font names that match the string pattern. Each string is ter-
minated by NULL. The maximum number of names returned in the list depends on the value
you passed to maxnames. The function returns the actual number of font names in
actual count. The client should call XFreeFontNames when done with this list to free
the memory.
The font search path (the order in which font names are compared to pattern) is set by
XSetFontPath.
For more information on fonts, see Volume One, Chapter 6, Drawing Graphics and Text.
Related Commands
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFontsWith-
Info, XFreeFontNames, XFreeFontPath, XGetFontPath, XQueryFont, XSet-
Font, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor.
270 July 26, 1988
--Xlib - Fonts
X List Fonts With Info
Name
XListFontsWithlnfo -- obtain the names and information about loaded fonts.
Synopsis
char **XListFontsWithInfo(display, pattern, maxnames,
count, info)
Display *display;
char *pattern; /* null-terminated */
int maxnames;
int *count; /* RETURN */
XFontStruct **info; /* RETURN */
Arguments
dlsplay
Specifies a pointer to the Display structure; returned from XOpen-
Display.
pattern Specifies the string associated with the font names you want returned. You
can specify any string, an asterisk (*), or a question mark. The asterisk indi-
cates a wildcard on any number of characters and the question mark indi-
cates a wildcard on a single character.
maxnames Specifies the maximum number of names that are to be in the returned list.
count Returns the actual number of matched font names.
info Returns the font information. XListFontsWithInfo provides enough
space for maxnames pointers.
Description
XListFontsWithInfo returns a list of font names that match the specified pattern and a
list of their associated font information. The list of names is limited to a size specified by the
maxnames argument. To free the allocated name array, the client should call XFreeFont-
Names. To free the font information army, the client should call XFreeFontInfo.
The information returned for each font is identical to what XQueryFont would return, except
that the per-character mecs (ibearing, rbearing, width, ascent, descent for sin-
gle characters) are not returned.
XListFontsWithInfo returns NULL on faile.
For more information on fonts, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct {
XExtData *ext data; /* hook for extension to hang data */
_
Font lid; /* Font ID for this font */
unsigned direction; /* hint about direction the font is painted */
unsigned min_char or byte2; /* first character */
unsigned max char or byte2; /* last character */
unsigned minbytel; /* first row that exists */
unsigned max_bytel; /* last row that exists */
Xlib Reference Manual 271
XListFontsWithlnfo (continued) Xlib - Fonts
Bool all chars exist;
_ --
unsigned default char;
--
int n_properties;
XFontProp *properties;
XCharStruct min bounds;
--
XCharStruct max bounds;
--
XCharStruct *per_char;
int ascent;
int descent;
} XFontStruct;
/* flag if all characters have nonzero size*/
/* char to print for undefined character */
/* how many properties there are */
/* pointer to array of additional properties*/
/* minimum bounds over all existing char*/
/* minimum bounds over all existing char*/
/* first char to last char information */
_ --
/* logical extent above baseline for spacing */
/* logical descent below baseline for spacing */
Related Commands
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts,
XFreeFontNames, XFreeFontPath, XGetFontPath, XQueryFont, XSetFont,
XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor.
272 Xlib Reference Manual
XListlnstalledColormaps
Xlib - Colormaps
Name
XListlnstalledColormaps -- get a list of installed colormaps.
Synopsis
Colorrnap *XListInstalledColorrnaps (display,
display *display;
Window w;
int *num; /* RETURN */
w, n um)
Arguments
di spl ay
hum
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the ID of the window for whose screen you want the list of
currently installed colormaps.
Returns the number of currently installed colormaps in the returned list.
XListInstalledColormaps returns a list of the currently installed colormaps for the
screen of the specified window. The order in the list is not significant. There is no distinction
in the list between colormaps actually being used by windows and colormaps no longer in use
which have not yet been freed or desloyed. The allocated list should be freed using XFree
when it is no longer needed. XListInstalledColormaps returns None on failure and
sets n um to O.
For more information on installing colormaps, see Volume One, Chapter 7, Color.
Errors
BadWindow
Related Commands
XCopyColormapAndFree, XCreateColormap, XFreeColormap, XGetStandard-
Colormap, XInstallColormap, XUninstallColormap, XSetStandard-
Colormap, XSetWindowColormap, DefaultColormap, DisplayCells.
274 Xlib Reference Manual
mXlib- Properties
XListProperties
Name
XListProperties -- get the property list for a window.
Synopsis
Atom *XListProperties (display, w, num__prop)
Display *display;
Window w;
int *num__prop; /* RETURN */
Arguments
di splay
w
n um__p rop
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the window whose property list you want.
Returns the length of the properties array.
XListProperties returns a pointer to an array of atom properties that are defined for the
specified window. To free the memory allocated by this function, use XFree. XList-
Properties returns NULL on failure and sets hum_prop to O.
For more information, see Volume One, Chapter 10, lnterclient Communication.
Errors
BadWindow
Related Commands
XSetStandardProperties, XGetFontProperty, XRotateWindowProperties,
XDeleteProperty, XChangeProperty, XGetWindowProperty, XGetAtomName,
XInternAtom.
Xlib Reference Manual 275
XLoadFont k
Xlib- Fonts--
Name
XLoadFont -- load a font if not already loaded; get font ID.
Synopsis
Font XLoadFont ( display, name)
Display *display;
char *name;
Arguments
display
Specifies a pointer to the Display structure; returned from XOpen-
Display.
name Specifies the name of the font in a null terminated siring. Upper or lower
case is not important. The string should be in ISO LATIN-1 encoding,
which means that the first 128 character codes are ASCII, and the second
128 character codes are for special characters needed in western languages
other than English.
Description
XLoadFont loads a font into the server if it has not already been loaded by another client.
XLoadFont returns the font ID or, if it was unsuccessful, returns a 0 and generates a Bad-
Name error. When the font is no longer needed, the client should call XUnloadFont. Fonts
are not associated with a particular screen. Once the font ID is available, it can be set in the
font member of any GC, and thereby used in subsequent drawing requests.
Font information is usually necessary for locating the text. Call XLoadFontWithInfo to
get the info at the time you load the font, or call XQueryFont if you used XLoadFont tO
load the font.
For more information on fonts, see Volume One, Chapter 6, Drawing Graphics and Text.
Errors
BadAlloc
BadName
name specifies an unavailable font.
Related Commands
XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts, XListFontsWith-
Info, XFreeFontNames, XFreeFontPath, XGetFontPath, XQueryFont, XSet-
Font, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor.
276 Xlib Reference Manual
XLoadQueryFont (continued) Xlib- Fonts
typedef struct {
short ibearing;
short rbearing;
short width;
short ascent;
short descent;
unsigned short attributes;
) XCharStruct;
/* origin to left edge of character */
/* origin to right edge of character */
/* advance to next char's origin */
/* baseline to top edge of character */
/* baseline to bottom edge of character */
/* per char flags (not predefined) */
Errors
BadAlloc
Related Commands
XLoadFont, XFreeFont, XFreeFontInfo, XListFonts, XListFontsWithinfo,
XFreeFontNames, XFreeFontPath, XGetFontPath, XQueryFont, XSetFont,
XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor.
278 Xhb Reference Manual
mXlib - Association Tables
XLookUpAssoc
Name
XLookUpAssoc -- obtain data from an association table.
Synopsis
caddr_t XLookUpAssoc(display, table, x id)
--
Display *display;
XAssocTable *table;
XID x id;
Arguments
di spl ay
Specifies a poinr to the Display structu; retumed from XOpen-
Display.
table
Specifies the association table.
x id
--
Specifies the X resource ID.
Description
This function is provided for compatibility with X Version 10. To use it you must include the
fil <X111X10.h> and link with the library -loldX.
Association tables provide a way of storing data and accessing by ID. This information is
available to all clients. XLookUpAssoc retrieves the data stored in an XAssocTable by its
XID. If the matching XID can be found in the table, the routine returns the data associated
with it. If the x i d cannot be found in the table the routine returns NULL.
For more information on association tables, see Volume One, Chapter 13, Other Programming
Techniques.
Structures
typedef struct {
XAssoc *buckets;
int size;
} XAssocTable;
/* pointer to first bucket in bucket array */
/* table size (number of buckets) */
typeef struct XAssrc {
--
struct XAs soc *next;
--
struct XAs soc *prev;
Display *display;
XID x id;
char *data;
} XAssoc;
/* next object in this bucket */
/* previous object in this bucket */
/* display which owns the ID */
/* X Window System ID */
/* pointer to untyped memory */
Related Commands
XCreateAssocTable, XDeleteAssoc, XDestroyAssocTable, XMakeAssoc-
July 26, 1988 279
XLookupColor
Xlib - Color Cells--
Name
XLookupColor m get database RGB values and closest hardware-supported RGB values from
color name.
Synopsis
Status XLookupColor (display, cmap, colorname, rgb_db_def,
hardware def)
Display *display;
Colormap cmap;
char *colorname;
XColor *rgb_db_def, *hardware_def; /* RETURN */
Arguments
display
cmap
colorname
hardware def
--
Description
Specifies a pointer to the Display structure; returned from X0pen-
Display.
Specifies the colormap.
Specifies the color name string (for example "red"). Upper or lower
case does not matter. The string should be in ISO LATIN1 encoding,
which means that the first 128 character codes are ASCII, and the second
128 character codes are for special characters needed in western
languages other than English.
Returns the exact RGB values for the specified color name from the
/usr/liblrgb database.
Returns the closest RGB values possible on the hardware.
XLookupColor looks up the string name of a color with respect to the screen associated
with the specified cmap and returns both the exact color values and the closest values possible
on that screen.
XLookupColor returns 1 if colorname exists in the RGB database or 0 if it does not
exist.
To determine the exact RGB values, XLookupColor uses a database on the X server. On
UNIX, this database is lusrlliblrgb. To read the colors provided by the database on a UNIX
system, see/usrlliblrgb.txt. The location, name, and contents of this file are server-dependent.
For more information see Volume One, Chapter 7, Color, and Appendix D, The Color Data-
base, in this volume.
280 Xlib Reference Manual
Xlib - Color Cells (continued) XLookupColor
Structures
typedef struct {
unsigned long pixel;
unsigned short red, green, blue;
char flags;
char pad;
} XColor;
/* DoRed, DoGreen, DoBlue */
Related Commands
XAllocColorCells, XAllocColorPlanes, XAllocColor, XAllocNamedColor,
XParseColor, XQueryColor, XQueryColors, XStoreColor, XStoreColors,
XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel.
July 26, 1988
281
XLookupKeysym
Xlib - Keyboard
Name
XLookupKeysym -- get the keysym corresponding to a keycode in structure.
Synopsis
KeySym XLookupKeysym ( event, index)
XKeyEvent *event ;
int index;
Arguments
e ven t
index
Specifies the KeyPress or KeyRelease event that is to be used.
Specifies which keysym from the list associated with the keycode in the event to
return. These correspond to the modifier keys, and the symbols ShiftMap-
Index, LockMapIndex, ControlMapIndex, ModlMapIndex, Mod2-
MapIndex, Mod3MapIndex, Mod4MapIndex, 8nd Mod5MapIndex csn be
used.
Description
Given a keyboard event and the index into the list of keysyms for that keycode, XLookup-
Keysym returns the keysym from the list that corresponds to the keycode in the event. If no
keysym is defined for the keycode of the event, XLookupKeysym returns NoSymbol.
Each keycode may have a list of associated keysyms, which are portable symbols representing
the meanings of the key. The index specifies which keysym in the list is desired, indicating
the combination of modifier keys that are currently pressed. Therefore, the program must
interpret the state member of the XKeyEvent structure to determine the index before
calling this function. The exact mapping of modifier keys into the list of keysyms for each
keycode is server-dependent beyond the fact that the first keysym corresponds to the keycode
without modifier keys, and the second corresponds to the keycode with Shift pressed.
XLookupKeysym simply calls XKeycodeToKeysym, using arguments taken from the
specified event structure.
Note that some hardware can't support KeyRelease events for every key. You may wish to
avoid using them in your code.
Structures
typedef struct {
int type;
Display *display;
Window window;
Window root;
Window subwindow;
Time time;
int x, y;
int x_root, y_root;
unsigned int state;
unsigned int keycode;
Bool same screen;
--
} XKeyEvent;
/* of event */
/* display the event was read from */
/* "event" window it is reported relative to */
/* root window that the event occured on */
/* child window */
/* milliseconds */
/* pointer x, y coordinates in event window */
/* coordinates relative to root */
/* key or button mask */
/* detail */
/* same screen flag */
282 July 26, 1988
Xlib- Keyboard (continued) XLookupKeysym
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap,
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifier-
Map, XQueryKeymap, XStringToKeysyrXRebindKeysym, XGetKeyboard-
Mapping, XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookup-
String, XSetModifierMapping, XGetModifierMapping.
July 26, 1988
283
XLookupString
Xlib - Keyboard--
Name
XLookupString -- map a key event to ASCII string, keysym, and ComposeStatus.
Synopsis
int XLookupString(event, buffer, num_bytes, keysym,
XKeyEvent *event;
char *buffer; /* RETURN */
int num_bytes;
KeySym *keysym; /* RETURN */
XComposeStatus *status; /* not implemented */
status)
Arguments
e ven t
buffer
n um_byt es
keysym
status
Description
Specifies the key event to be used.
Returns the resulting string.
Specifies the length of the buffer. No more than num_bytes of translation
are returned.
If this argument is not NULL, it specifies the keysym ID computed from the
event.
Specifies the xCompose structure that contains compose key state informa-
tion and that allows the compose key processing to take place. This can be
NULL if the caller is not interested in seeing compose key sequences. Not
implemented in Release 1 or 2.
XLookupString gets an ASCII string and a keysym that are currently mapped to the key-
code in a KeyPress or KeyRelease event, using the modifier bits in the key event to deal
with shift, lock and control. The XLookupString return value is the length of the
translated string and the string's bytes are copied into the user's buffer. The length may be
greater than 1 if the event's keycode translates into a keysym that was rebound with
XRebindKeysym.
The compose status is not implemented in Release 1 or 2.
Structures
/.
* Compose sequence status structure, used in calling XLookupString.
*/
typedef struct _XComposeStatus {
char *compose_ptr; /* state table pointer */
int chars matched; /* match state */
--
} XComposeStatus;
typedef struct {
int type;
Display *display;
Window window;
/* of event */
/* Display the event was read from */
/* "event" window it is reported relative to */
284 July 26, 1988
Xlib - Keyboard (continued) X Looku pString
Window root;
Window subwindow;
Time time;
int x, y;
int x_root, y_root;
unsigned int state;
/* root window that the event occured on */
/* child window */
/* milliseconds */
/* pointer x, y coordinates in event window */
/* coordinates relative to root */
/* key or button mask */
unsigned int keycode;/* detail */
Bool same screen; /* same screen flag */
--
} XKeyEvent;
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap,
XKeycodeToKeysyn%XKeysymToKeycode, XKeysymToString, XNewModifier-
Map, XQueryKeymap, XStringToKeysyn%XLookupKeysym, XRebindKeySyn%
XGetKeyboardMapping, XChangeKeyboardMapping, XRefreshKeyboard-
Mapping, XSetModifierMapping, XGetModifierMapping.
July 26, 1988
285
XLowerWindow
Xlib - Window Manipulation
Name
XLowerWindow -- lower a window in the stacking order.
Synopsis
XLowerWindow (display, w)
Display *display;
Window w;
Arguments
display
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the ID of the window to be lowered.
Description
XLowerWindow lowers a window in the stacking order of its siblings so that it does not
obscure any sibling windows. If the windows are regarded as overlapping sheets of paper
stacked on a desk, then lowering a window is analogous to moving the sheet to the bottom of
the stack, while leaving its x and y location on the desk constant. Lowering a mapped win-
dow will generate exposure events on any windows it formerly obscured.
If the override redirect attribute of the window (see Chapter 4, Window Attributes) is
--
False and some other client has selected SubstructureRedirectMask on the parent,
then a ConfigureRequest event is generated, and no further processing is performed.
Otherwise, the window is lowered to the bottom of the stack.
LeaveNotify events are sent to the lowered window if the pointer was inside it, and
EnterNotify events are sent to the window which was immediately below the lowered
window at the pointer position.
For more information, see Volume One, Chapter 14, Window Management.
Errors
BadWindow
Related Commands
XRaiseWindow, XCirculateSubwindows, XCirculateSubwindowsDown,
XCirculateSubwindowsUp, XRestackWindows, XMoveWindow, XResizeWindow,
XMoveResizeWindow, XReparentWindow, XConfigureWindow, XQueryTree.
286 July 26, 1988
mXlib - Association Tables
XMakeAssoc
Name
XMakeAssoc -- create an entry in an association table.
Synopsis
XMakeAssoc(display, table,
Display *display;
XAssocTable *table;
XID x id;
caddr t data;
x_id, data)
Arguments
display
table
x id
--
data
Description
Specifies a pointer to the Display sucte; returned from XOpenDisplay.
Specifies the association table in which an entry is to be made.
Specifies the X resource ID.
Specifies the data to be associated with the X resource ID.
XMakeAssoc insets data into an XAssocTable keyed on an XID. Association tables
allow you to easily associate data with resource ID's for later retrieval by any application.
This function is provided for compatibility with X Version 10. To use it you must include the
file <X11/X10.h> and link with the library -loldX.
Data is inserted into the table only once. Redundant inserts are meaningless and cause no
problems. The queue in each association bucket is sorted from the lowest XTD tO the highest
XID.
For more information, see Volume One, Chapter 13, Other Programming Techniques.
Structure
typedef struct {
XAssoc *buckets;
int size;
} XAsocTable;
/* pointer to first bucket in bucket array */
/* table size (number of buckets) */
typedef struct XAssoc {
--
struct XAssoc *next;
--
struct _XAssoc *prev;
Display *display;
XID x_id;
char *data;
} XAssoc;
/* next object in this bucket */
/* previous object in this bucket */
/* display which owns the ID */
/* X Window System ID */
/* pointer to untyped memory */
Related Commands
XCreateAssocTable, XDeleteAssoc, XDestroyAssocTable, XLookUpAssoc.
July 26, 1988 28 7
mXlib - Window Mapping
XMapSubwindows
Name
XMapSubwindows m map all subwindows.
Synopsis
XMapSubwindows(display,
Display *display;
Window w;
w)
Arguments
display
Specifies a pointer to the Display structure; returned from XOpenDisplay.
Specifies the ID of the window whose subwindows are to be mapped.
Description
XMapSubwindows maps all subwindows of a window in top-to-bottom stacking order.
XMapSubwindows also generates an Expose event on each newly displayed window. This
is much more efficient than mapping many windows one at a time, as much of the work need
only be performed once for all of the windows rather than for each window.
For more information, see Volume One, Chapter 14, Window Management.
Errors
BadWindow
Related Commands
XMapRa i s ed, XMapWindow, XUnmapS ubwindows, XUnmapWindow.
July 26, 1988 289
XMapWindow
Xlib - Window Mapping--
Name
XMapWindow -- map a window.
Synopsis
XMapWindow(display, w)
Display *display;
Window w;
Arguments
display
Specifies a pointer to the Display structure; returned from XOpenDisplay.
w Specifies the ID of the window to be mapped.
Description
XMapWindow maps a window, making it eligible for display depending on its stacking order
among its siblings, the mapping status of its ancestors, and the placement of other visible win-
dows. If all the ancestors are mapped, and it is not obscured by siblings higher in the stacking
order, the window and all of its mapped subwindows are displayed.
Mapping a window that has an unmapped ancestor does not display the window but marks it
as eligible for display when its ancestors become mapped. Mapping an already mapped win-
dow has no effect (it does not raise the window).
If the window is opaque, XMapWindow generates Expose events on each opaque window
that it causes to become displayed. If the client first maps the window, then paints the win-
dow, then begins processing input events, the window is painted twice. To avoid this, the
client should use either of two strategies:
Map the window, call XSelect Input for exposure events, wait for the first Expose
event, and repaint each window explicitly.
2. Call XSelectInput for exposure events, map, and process input events normally.
Exposure events are generated for each window that has appeared on the screen, and the
client's normal response to an Expose event should be to repaint the window.
The latter method is preferred as it usually leads to simpler programs. If you fail to wait for
the Expose event in the first method, it can cause incorrect behavior with certain window
managers that intercept the request.
Errors
BadWindow
Related Commands
XMapRaised, XMapSubwindows, XUnmapSubwindows, XUnmapWindow.
290 July 26, 1988
mXlib - Input Handling
XMaskEvent
Name
XMaskEvent -- remove the next event that matches mask.
Synopsis
XMaskEvent (display, event_mask, rep)
Display *display;
unsigned long event mask;
XEvent *rep; /* RETURN */
Arguments
display
event mask
rep
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the event mask. See XSelectInput for a complete fist of event
masks.
Returns the event removed from the input queue.
XMaskEvent removes the next event in the queue which matches the passed mask. The
event is copied into an XEvent supplied by the caller. Other events in the queue are not dis-
carded. If no such event has been queued, XMaskEvent flushes the output buffer and waits
until one is received. Use XCheckMaskEvent if you do not wish to wait.
In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the
output buffer is flushed only if no matching events are found on the queue. This change is
compatible with applications written for Release 1.
Reled Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheck-
WindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XCheckMask-
Event, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents,
XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent,
XPending, XSynchronize, XSendEvent, QLength.
July 26, 1988 291
DXlib - Keyboard
XNewModifiermap
Name
XNewModifiermap -- create a keyboard modifier mapping structure.
Synopsis
XModifierKeymap *XNewModifiermap(max_keys_per_mod)
int max_keys__per_mod;
Arguments
max_keys__per_mod
Specifies the maximum number of keycodes assigned to any of the modifiers in the
map.
Description
XNewModifierrnap returns a XModifierKeymap sucture and locates the needed
space. This funcdon is used when more than one XModifierKeymap s[ructure is needed.
max_keys_.per_mod depends on the server and should be gotten from the XModifier-
Keymap returned by XGetModifierMapping.
For more information on keyboard preferences, see Volume One, Chapter 9, The Keyboard
and Pointer.
Structures
typedef struct {
int max__keypermod;
KeyCode *modifiermap;
} XModifierKeymap;
/* server's max number of keys per modifier */
/* An 8 by max_keypermod array
* of the modifiers */
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap,
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XQueryKeymap,
XStringToKeysym, XLookupKeysym, XRebindKeysym, XGetKeyboardMapping,
XChageKeyboardMapping, XRefreshKeyboardMapping, XLookupString,
XSetModifierMapping, XGetModifierMapping.
July 26, 1988 295
XNextEvent
Xlib - Input Handling
Name
XNextEvent -- get the next event of any type or window.
Synopsis
XNextEvent(display, report)
Display *display;
XEvent *report ;
/* RETURN */
Arguments
display
report
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Returns the event removed from the input queue.
XNextEvent removes an input event from the head of the event queue and copies it into an
XEvent supplied by the caller. If the event queue is empty, XNextEvent flushes the output
buffer and waits (blocks) until an event is received. Use XCheckNextEvent if you do not
want to wait.
In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the
output buffer is flushed only if no matching events are found on the queue. This change is
compatible with applications written for Release 1.
For more information, see Volume One, Chapter 8, Events.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheck-
WindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent,
XCheckMaskEvent, XEventsQueued, XAllowEvents, XGetMotionEvents,
XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent,
XPending, XSynchronize, XSendEvent, QLength.
296 July 26, 1988
--Xlib - HouseKeeping
XNoOp
Name
XNoOp -- send a NoOp to exercise connection with the server.
Synopsis
XNoOp(display)
Display *display;
Arguments
display Specifies a pointer to the Display structure; returned from X0pen-
Display.
Description
XNo0p sends a No0peration request to the X server, thereby exercising the connection.
This request can be used to measure the response time of the network connection, xNo0p
does not flush the output buffer.
Related Commands
XFree, XOpenDisplay, XCloseDisplay, DefaultScreen.
July 26, 1988
297
XOffsetRegion
Xlib - Regions--
Name
XOffsetRegion--changeoffsetofaregion.
Synopsis
XOffsetRegion(r, dx, dy)
Region r;
int dx, dy;
Arguments
dx
Specifies the region.
Specify the amount to move the specified region relative to the origin of all
regions.
Description
XOffsetRegion changes the offset of the region the specified amounts in the x and y direc-
tions.
Regions are located using an offset from a point (the region origin) which is common to all
regions. It is up to the application to interpret the location of the region relative to a drawable.
If the region is to be used as a clip_mask by calling XSetRegion, the upper-left comer of
the region relative to the drawable used in the graphics request will be at (xoffset +
clip x origin, yoffset + clip_y_origin), where xoffset and yoffset are
the offset of the region and clip x origin and clip y origin are elements of the GC
used in the graphics request.
Structures
/.
* opaque reference to Regiondata type.
* user won't need contents, only pointer.
*/
typedef struct _XRegion *Region;
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion,
XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPoint-
InRegion, XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroy-
Region, XEqualRegion, XClipBox.
298 July 26, 1988
XOpenDisplay (continued) Xlib - HouseKeeping
screen Specifies the number of the default screen on server. Multiple screens can be
connected to (controlled by) a single X server, but they are used as a single
display by a single user. screen merely sets an internal variable that is
returned by the DefaultScreen macro. If screen is omitted, it defaults to
0.
If successful, XOpenDisplay returns a pointer to a Display. This structure provides
many of the specifications of the server and its screens. If XOpenDisplay does not succeed,
it returns a NULL.
After a successful call to XOpenDisplay, all of the screens on the server may be used by
the application. The screen number specified in the display_name argument serves only to
specify the value that will be returned by the DefaultScreen macro. After opening the
display, you can use the ScreenCount macro to determine how many screens are available.
Then you can reference each screen with integer values between 0 and the value returned by
ScreenCount.
For more information, see Volume One: Chapter 2, X Concepts; and Chapter 3, Basic Win-
dow Program.
Structures
/.
* Display datatype maintaining display specific data.
./
typedef struct _XDisplay {
XExtData *ext data;
--
struct _XDisplay *next;
int fd;
int lock;
int proto_major_version;
int proto_minor_version;
char *vendor;
long resource base;
--
long resource mask;
--
long resource id;
--
int resource shift;
--
XID (*resource alloc) () ;
--
int byte_order;
int bitmap_unit;
int bitmap_pad;
int bitmap_bit_order;
int nformats;
ScreenFormat *pixmap_format; /
int vnumber; /
int release; /
struct XSQEvent *head, *tail;
--
int qlen;
int last_request_read;
int request;
char *last_req;
char *buffer;
char *bufptr;
/* hook for extension to hang data */
/* next open Display on list */
/* network socket */
/* is someone in critical section */
/* major version of server's X protocol */
/* minor version of server's X protocol */
/* vendor of the server hardware */
/* resource ID base */
/* resource ID mask bits */
/* allocator current ID */
/* allocator shift to correct bits */
/* allocator function */
/* screen byte order, LSBFirst, MSBFirst */
/* padding and data requirements */
/* padding requirements on bitmaps */
/* LeastSignificant or MostSignificant */
/* number of pixmap formats in list */
* pixmap format list */
* Xlib's X protocol version number */
* release of the server */
/* input event queue */
/* length of input event queue */
/* sequence number of last event read */
/* sequence number of last request */
/* beginning of last request, or dummy */
/* output buffer starting address */
/* output buffer index pointer */
300 July 26 1988
Xlib - HouseKeeping (continued) XOpenDisplay
char *bufmax;
unsigned max_request_size;
struct XrmHashBucketRec *db;
--
int (*synchandler) ();
char *display_name;
int default screen;
--
int nscreens;
Screen *screens;
int motion buffer;
--
Window current;
int min_keycode;
int max_keycode;
KeySym *keysyms;
XModifierKeymap *modifiermap;
int keysyms_per_keycode;
char *xdefaults;
char *scratch buffer;
--
unsigned long scratch_length;
int ext number;
_
XExtension *ext_procs;
--
/*
/* output buffer maximum+l address */
/* maximum number 32 bit words in request*/
/* synchronization handler */
/* "host:display" string used on this connect*/
/* default screen for operations */
/* number of screens on this server*/
/* pointer to list of screens */
/* size of motion buffer */
/* for use internally for KeymapNotify */
/* minimum defined keycode */
/* maximum defined keycode */
/* this server's keysyms */
/* this server's modifier keymap */
/* number of rows */
/* contents of defaults from server */
/* place to hang scratch buffer */
/* length of scratch buffer */
/* extension number on this display */
/* extensions initialized on this display */
* The following can be fixed size, as the protocol defines how much
* address space is available. While this could be done using the
* extension vector, there may be MANY events processed, so a search
* through the extension list to find the right procedure for each
* event might be expensive if many extensions are being used.
*/
Bool (*event vec[128]) (); /* vector for wire to event */
--
Status (*wire vec[128]) (); /* vector for event to wire */
--
} Display;
/*
* Information about the screen
*/
typedef struct {
XExtData *ext data;
--
struct _XDisplay *display;
indow root;
int width, height;
int mwidth, mheight;
int ndepths;
Depth *depths;
int root_depth;
Visual *root visual;
--
GC default_gc;
Colormap cmap;
unsigned long white_pixel;
unsigned long black_pixel;
int max_maps, min_maps;
int backing_store;
Bool save unders;
--
long root_input_mask;
} Screen;
/* hook for extension to hang data */
/* back pointer to display structure */
/* root window ID */
/* width and height of screen */
/* width and height of in millimeters */
/* number of depths possible */
/* list of allowable depths on the screen
/* bits per pixel */
/* root visual */
/* GC for the root root visual */
/* default colormap */
/* white and black pixel values */
/* max and min colormaps */
/* Never, WhenMapped, Always */
/* initial root input mask */
301
XOpenDisplay (continued) Xlib- HouseKeeping
* Format structure; describes ZFormat data the screen will understand.
*/
typedef struct {
XExtData *ext_data; /* hook for extension to hang data */
int depth; /* depth of this image format */
int bits_per_pixel; /* bits/pixel at this depth */
int scanline_pad; /* scan line must padded to this multiple */
} ScreenFormat;
Related Commands
XFree, XCloseDisplay, XNoOp, DefaultScreen.
302 July 26, 1988
mXlib - Color Cells
XParseColor
Name
XParseColor -- look up or transla RGB values from ASCII color name or
hexadecimal value.
Synopsis
Status XParseColor(display, colormap,
Display *display;
Colormap colormap;
char *spec;
XColor *rgb_db_def; /* RETURN */
spec, rgb_db_def)
Arguments
display
cmap
spec
Specifies a pointer to the Display structe; tumed from XOpen-
Display.
Specifies a colormap. This argument is required but is not used. The same
code is used to process xparseColor and XLookupColor, but only
XLookupColor retums actual values from the colormap.
Specifies the color specification, either as a color name or as hexadecimal
coded in ASCII (see below). Upper or lower case does not matter. The
string must be null-terminated, and should be in ISO LATIN-1 encoding,
which means that the first 128 character codes are ASCII, and the second
128 character codes are for special characters needed in western languages
other than English.
rgb_db_def Returns the RGB values corresponding to the specified color name or hexa-
decimal specification, and sets its DoRed, DoGreen and DoBlue flags.
Description
XParseColor returns the RGB values corresponding to the English color name or hexade-
cimal values specified, by looking up the color name in the color database, or translating the
hexadecimal code into separate RGB values. It takes a string specification of a color, typically
from a command line or XGetDefault option, and returns the corresponding red, green, and
blue .values, suitable for a subsequent call to XAllocColor or XStoreColor. spec can
be given either as an English color name (as in XAllocNamedColor) or as an initial sharp
sign character followed by a hexadecimal specification in one of the following formats:
#RGB (one character per color)
#RRGGBB (two characters per color)
#RRRGGGBBB (three characters per color)
#RRRRGGGGBBBB (four characters per color)
where R, G, and B represent single hexadecimal digits (upper or lower case).
The hexadecimal strings must be null-terminated so that XParseColor knows when it has
reached the end. When fewer than 16 bits each are specified, they represent the most
significant bits of the value. For example, #3a7 is the same as #3000a0007000. The
colormap is used to determine which screen to look up the color on. The screen's default
colormap is a reliable choice.
Xlib Reference Manual 303
XParseColor (continued) Xlib - Color Cells
This routine will fail and return a Status of 0 if the initial character is a sharp sign but the
string otherwise fails to fit one of the above formats, or if the initial character is not a sharp
sign and the named color does not exist in the server's database.
Status is 0 on failure, 1 on success.
For more information, see Volume One, Chapter 7, Color.
Structures
typedef struct {
unsigned long pixel;
unsigned short red, green, blue;
char flags; /* DoRed, DoGreen, DoBlue */
char pad;
} XColor;
Errors
BadColor
Related Commands
XAllocColorCells, XAllocColorPlanes, XAllocColor, XAllocNamedColor,
XLookupColor, XQueryColor, XQueryColors, XStoreColor, XStoreColors,
XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel.
304 Xlib Reference Manual
XPeekEvent
Xlib - Input Handling m
Name
XPeekEvent -- get an event without removing it from the queue.
Synopsis
XPeekEvent(display, report)
Display *display;
XEvent *report;
/* RETURN */
Arguments
display
report
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Returns the event peeked from the input queue.
XPeekEvent peeks at an input event from the head of the event queue and copies it into an
XEvent supplied by the caller, without removing it from the input queue. If the queue is
empty, XPeekEvent flushes the output buffer and waits (blocks) until an event is received.
If you do not want to wait, use the QLength macro to determine if there are any events to
peek at, or use XPeekIfEvent. In Release 2, XEventsQueued can perform the function
of either QLength or XPending and more.
In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the
output buffer is flushed only if no matching events are found on the queue. This change is
compatible with applications written for Release 1.
For more information, see Volume One, Chapter 8, Events.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheck-
WindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent,
XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotion-
Events, XIfEvent, XCheckIfEvent, XPeekIfEvent, XPutBackEvent,
XPending, XSynchronize, XSendEvent, QLength.
306 July26 1988
XPending
Xlib - Input Handling m
Name
XPending -- flush the output buffer and return the number of pending input events.
Synopsis
int XPending(display)
Display *display;
Arguments
display Specifies a pointer to the Display structure; returned from XOpen-
Display.
Description
XPending returns the number of input events that have been received from the server, but
not yet removed from the queue. If there are no events on the queue, xPending flushes the
output buffer, and returns the number of events transferred to the input queue as a result of the
flush.
The QLength macro returns the number of events on the queue, but without flushing the out-
put buffer first.
For more information, see Volume One, Chapter 8, Events.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheck-
WindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent,
XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotion-
Events, XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBack-
Event, XSynchronize, XSendEvent, QLength.
308 July 26, 1988
--Xlib - Resource Manager
Xpermalloc
Name
Xpermalloc -- allocate memory never to be freed.
Synopsis
char *Xpermalloc (size)
unsigned int size;
Arguments
size
Specifies the size in bytes of the space to be allocated. This specification is
rounded to the nearest 4-byte boundary.
Description
Xpermalloc allocates some memory that will not be freed until the process exits. Xperm-
alloc is used by some toolkits for permanently allocated storage and allows some perfor-
mance and space savings over the completely general memory allocator.
July 26, 1988
309
XPointlnRegion
Xlib - Regions m
Name
XPoinflnRegion--dermineifapointisinsidea gn.
Synopsis
int XPointInRegion(r, x, y)
Region r;
int x, y;
Arguments
Specifies the region.
Specify the x and y coordinates of the point relative to the region's origin.
Description
XPointInRegion returns True if the point x, y is contained in the region r. A point
exactly on the boundary of the region is considered inside the region.
Regions are located using an offset from a point (the region origin) which is common to all
regions. It is up to the application to interpret the location of the region relative to a drawable.
For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
/.
* opaque reference to Regiondata type.
* user won't need contents, only pointer.
*/
typedef struct _XRegion *Region;
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion,
XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XOffset-
Region, XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroy-
Region, XEqualRegion, XClipBox.
310 July 26, 1988
XPolygonRegion (continued) Xlib- Regions
Structures
typedef struct {
short x,y;
} XPoint;
/*
* opaque reference to Regiondata type.
* user won't need contents, only pointer.
*/
typedef struct _XRegion *Region;
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion,
XShrinkRegion, XSetRegion, XRectInRegion, XPointInRegion, XOffset-
Region, XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroy-
Region, XEqualRegion, XClipBox.
312 July26, 1988
XPutlmage
Xlib - Images m
Name
XPutImage m draw a rectangular image on a window or pixmap.
Synopsis
XPutImage (display, drawable, gc, image, src_x, src_y,
dst_x, dst_y, width, height)
Display *display;
Drawable drawable ;
GC gc ;
XImage *image ;
int src_x, src_y;
int dst_x, dst_y;
unsigned int width, height ;
Arguments
display
dra wabl e
gc
image
src x
--
s rc_y
dst x
--
dst_y
width
height
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the drawable.
Specifies the graphics context.
Specifies the image you want combined with the rectangle.
Specify the coordinates of the upper-left corner of the rectangle to be copied,
relative to the origin of the image.
Specify the x and y coordinates, relative to the origin of the drawable, where
the upper-left corner of the copied rectangle will be placed.
Specify the width and height in pixels of the rectangular area to be copied.
Description
xPut Image draws a section of an image on a rectangle in a window or pixmap. The section
of the image is defined by src_x, src_y, width and height.
XPutImage uses these graphics context components: function, plane_mask,
subwindow_mode, clip x origin, clip_y_origin, and clip_mask. This func-
tion also uses these graphics context mode-dependent components: foreground and back-
ground.
If an XYBitmap format image is used, then the depth of drawable must be 1 and the image
must be XYFormat, otherwise a BadMatch error is generated. The foreground pixel in
gc defines the source for set bits in the image, and the background pixel defines the source
for the bits set to 0.
For xYPixmap and zPixmap format images, the depth of the image must match the depth of
drawable. For xYPixmap, the image must be sent in XYFormat. For ZPixmap, the
image must be sent in the ZFormat defined for the given depth.
314 July 26, 1988
Xlib - Images (continued) XPutlmage
Structures
typedef struct _XImage (
int width, height;
int xoffset;
int format;
char *data;
int byte_order;
int bitmap_unit;
/* size of image */
/* number of pixels offset in x direction */
/* XYBitmap, XYPixmap, ZPixmap */
/* pointer to image data */
/* data byte order, LSBFirst, MSBFirst */
/* quant, of scan line 8, 16, 32 */
int bitmap_bit_order; /* LSBFirst, MSBFirst */
int bitmap_pad;
int depth;
int bytes_per_line;
int bits_per_pixel;
char *obdata;
struct funcs {
/* 8, 16, 32 either XY or ZPixmap */
/* depth of image */
/* accelerator to next line */
/* bits per pixel (ZPixmap) */
/* hook for the object routines to hang on */
/* image manipulation routines */
struct _XImage * (*create_image) () ;
int (*destroy_image) () ;
unsigned long (*get_pixel) () ;
int (*put_pixel) () ;
struct _XImage * (*sub_image) () ;
int (*add_pixel) () ;
} f;
} XImage;
Errors
BadDrawable
BadGC
BadMatch
BadValue
See Description above.
Related Commands
XDesroyImage, XGetImage, XCreateImage, XSubImage, XGetSubImage'XAdd-
Pixel, XPutPixel, XGetPixel, ImageByteOrder-
July 26, 1988
315
Xlib -Images (continued) XPutPixel
Related Commands
XDestroyImage, XPutImage, XGetImage, XCreateImage, XSubImage, XGetSub-
Image, XAddPixel, XGetPixel, ImageByteOrder.
July26, 1988
317
XQueryBestCursor
Xlib - Cursors--
Name
XQueryBestCursor -- get the closest supported cursor sizes.
Synopsis
Status XQueryBestCursor (display, drawable, width, height,
rwidth, rheight)
Display *display;
Drawable drawable ;
unsigned int width, height ;
unsigned int *rwidth, *rheight; /* RETURN */
Arguments
display
dra wabl e
width
height
rwidth
rheight
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies a drawable that indicates which screen the cursor is to be used on.
The best cursor may be different on different screens.
Specify the preferred width and height, in pixels.
Return pointers to the closest supported cursor dimensions, in pixels, on the
display hardware.
Description
XQueryBestCursor returns the closest cursor dimensions actually supported by the display
hardware to the dimensions you specify.
Call this function if you wish to use a cursor size other than 16 by 16. XQueryBest-
Cursor provides a way to find out what size cursors are actually possible on the display.
Applications should be prepared to use smaller cursors on displays which cannot support large
ones.
XQueryBestCursor returns 1 if the call succeeded in getting a supported size (may be the
same or different from the specified size), or 0 if the call failed.
Errors
BadDrawable
Related Commands
XDefineCursor, XUndefineCursor, XCreateFontCursor, XCreateGlyph-
Cursor, XCreatePixmapCursor, XFreeCursor, XRecolorCursor, XQueryBest-
Size.
318 Xlib Reference Manual
XQueryBestSize (continued) Xlib - Pixmaps and Tiles
Related Commands
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindow-
BackgroundPixmap, XCreatePixmap, XCreatePixmapFromBitmapData, XFree-
Pixmap, XQueryBestStipple, XWriteBitmapFile, XReadBitmapFile,
XCreateBitmapFromData.
320 July 26, 1988
--Xlib - Pixmaps and Tiles
X Que ry BestSti p pie
Name
XQueryBestStipple -- obtain the best supported stipple shape.
Synopsis
Status XQueryBestStipple (display, drawable, width, height,
rwidth, rheight )
Display *display;
Drawable drawable;
unsigned int width, height;
unsigned int *rwidth, *rheight; /* RETURN */
Arguments
display
dra wabl e
width
height
rwidth
rheight
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies a drawable that tells the server which screen you want the best size
for.
Specify the preferred width and height in pixels.
Return the width and height, in pixels, of the stipple best supported by the
display hardware.
Description
XQueryBestStipple returns the closest stipple size that can be stippled fastest. The draw-
able indicates the screen and possibly the visual class and depth. An rnputOnly window
cannot be used as the drawable (else a BadMatch error occurs).
XQueryBestStipple returns 1 if the call succeeded in getting a supported size (may be
the same or different from the specified size), or 0 if the call failed.
For more information on stipples, see Volume One, Chapter 5, The Graphics Context.
Errors
BadDrawable
BadMatch
InputOnly window.
Related Commands
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindow-
BackgroundP ixmap, XCreateP ixmap, XCreatePixmapFromBitmapData, XFree-
Pixmap, XQueryBestSize, XWriteBitmapFile, XReadBitmapFile, XCreate-
BitmapFromData.
Xlib Reference Manual 321
DXlib - Color Cells
XQueryColor
Name
XQueryColor m obtain the RGB values and flags for a specified pixel value.
Synopsis
XQueryColor (display, cmap, colorcell def)
--
Display *display;
Colormap cmap;
XColor *colorcell def; /* SEND and RETURN */
Arguments
display
Specifies a pointer to the Display structure; returned from XOpen-
Display.
cmap
Specifies the ID of the colormap from which RGB values will be retrieved.
colorcell def
--
Specifies the pixel value and returns the RGB contents of that colorcell.
Description
XQueryColor returns the RGB values in colormap cmap for the colorcell corresponding to
the pixel value specified in the pixel member of the XColor structure colorcell_def.
The RGB values are returned in the red, green, and blue members of that same structure,
and the flags member of that structure is set to (DoRed I DoGreen I DoBlue). The
values returned for an unallocated entry are undefined.
For more information, see Volume One, Chapter 7, Color.
Structures
typedef struct {
unsigned long pixel;
unsigned short red, green, blue;
char flags; /* DoRed, DoGreen, DoBlue */
char pad;
} XColor;
Errors
BadColor
BadValue
Pixel not valid index into cmap.
Related Commands
XAIIocColorCelIs, XAllocColorPlanes, XAIIocColor, XAllocNamedColor,
XLookupColor, XParseColor, XQueryColors, XStoreColor, XStoreColors,
XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel.
July 26, 1988 323
XQueryColors
Xlib - Color Cells--
Name
XQueryColors m obtain RGB values for an army of pixel values.
Synopsis
XQueryColors (display, cmap, colorcell_defs, ncolors)
Display *display;
Colormap cmap;
XColor colorcell defs[ncolors] ; /* SEND and RETURN */
int ncolors ;
Arguments
display
Specifies a pointer to the Display structure; returned from XOpen-
Display.
cmap
Specifies the ID of the colormap from which RGB values will be retrieved.
colorcell defs
--
Specifies an array of XColor structures. In each one, pixel is set to indi-
cate which colorcell in the colormap to return, and the RGB values in that
colorcell are returned in red, green, and blue.
n col ors Specifies the number of xCo 1 o r structures in the color definition array.
Description
XQueryColors is similar to XQueryColor, but it returns an array of RGB values. It
returns the RGB values in colormap craap for the colorcell corresponding to the pixel value
specified in the pixel member of the XColor structure colorcell def. The RGB
--
values are returned in the red, green, and blue members of that same structure, and sets
the flags member in each XColor structure to (DoRed I DoGreen I DoBlue).
For more information, see Volume One, Chapter 7, Color.
Structures
typedef struct {
unsigned long pixel;
unsigned short red, green, blue;
char flags; /* DoRed, DoGreen, DoBlue */
char pad;
} XColor;
Errors
BadColor
BadValue Pixel not valid index into cmap.
Note: if more than one pixel value is in error, the one reported is arbitrary.
Related Commands
XAllocColorCells, XAllocColorPlanes, XAllocColor, XAllocNamedColor,
XLookupColor, XParseColor, XQueryColor, XStoreColor, XStoreColors,
XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel.
324 July 26, 1988
XQueryExtension (continued) Xlib- Extensions
Related Commands
XListExtensions, XFreeExtensionList.
326 July 26, 1988
XQueryFont (continued) Xlib - Fonts
int ascent;
int descent;
} XFontStruct;
/* logical extent above baseline for spacing */
/* logical descent below baseline for spacing */
Related Commands
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts,
XListFontsWithInfo, XFreeFontNames, XFreeFontPath, XGetFontPath,
XSetFont, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFont-
Cursor.
328 Xlib Reference Manual
XQueryPointer
Xlib - Pointer--
Name
XQueryPointer -- get the current pointer location.
Synopsis
Bool XQueryPointer (display, w, root,
win_x, win_y, keys_buttons)
Display *display;
Window w;
Window *root, *child;
int *root_x, *root_y;
int *win_x, *win_y;
unsigned int *keys_buttons;
child,
/* RETURN */
/* RETURN */
/* RETURN */
/* RETURN */
root_x, root_y,
Arguments
display
root
child
root x
root_y
win x
--
win_y
Specifies a pointer to the Display sVucte; returned from XOpenDisplay.
Specifies a window which indicates which screen the pointer position is
returned for, and child will be a child of this window if pointer is inside a
child.
Returns the root window ID the pointer is currently on.
Returns the ID of the child of w the pointer is located in, or 0 if it not in a
child.
Return the x and y coordinates of the pointer relative to the root's origin.
Return the x and y coordinates of the pointer relative to the origin of window
W.
key3_buttons
Returnsthe currentsmte ofthe modifier keys and pointerbuttons. Thisisa
mask composedofthe OR ofanynumberofthe llowingsymbols: Shift-
Mask, LockMask, ControlMask, ModlMask, ModlMask, Mod3Mask,
Mod4Mask, Mod5Mask, ButtonlMask, ButtonlMask, Button3Mask,
Button4Mask, Button5Mask.
Description
XQueryPointer gets the pointer coordinates relative to a window and relative to the root
window, the root window ID and the child window ID (if any) the pointer is currently in,
and the current state of modifier keys and buttons.
If XQueryPointer returns False, then the pointer is not on the same screen as w, child
is None, and win_x and win_y are zero. However, root, root_x, and root_y are still
valid. If XQueryPointer returns True, then the pointer is on the same screen as the win-
dow w, and all return values are valid.
The logical state of the pointer buttons and modifier keys can lag behind their physical state if
device event processing is frozen due to a grab.
330 July 26, 1988
Xlib - Pointer (continued) XQue ryPoi nter
Errors
BadWindow
Related Commands
XWarpPointer, XGrabPointer, XChangeActivePointerGrab, XUngrab-
Pointer, XGetPointerMapping, XSetPointerMapping, XGetPointerControl,
XChangePointerControl.
July 26, 1988
331
X Que ryTe xt Exte n ts
Xlib - Text--
Name
XQueryTextExtents -- query the server for string and font metrics
Synopsis
int XQueryTextExtents (display, font_ID, string, nchars,
direction, ascent, descent, overall)
Display *display;
XID font ID;
--
char *string;
int nchars ;
int *direction; /* RETURN */
int *ascent, *descent; /* RETURN */
XCharStruct *overall; /* RETURN */
Arguments
display
Specifies a pointer to the Display structure; returned from XOpen-
Display.
font ID
--
Specifies the appropriate font ID previously returned by XLoadFont, or the
GContext that specifies the font.
string
Specifies the character string for which metrics are to be returned.
nchars
Specifies the number of characters in the character string.
direction
Returns the direction the string would be drawn using the specified font.
Either FontLeftToRight or FontRightToLeft.
ascent
Returns the maximum ascent for the specified font.
descent Returns the maximum descent for the specified font.
overall
Returns the overall characteristics of the string. These are the sum of the
width measurements for each character, the maximum ascent and
descent, the minimum lbearing added to the width of all characters up
to the character with the smallest lbearing, and the maximum rbearing
added to the width of all characters up to the character with the largest
rbearing.
Description
XQueryTextExtents returns the dimensions in pixels that specify the bounding box of the
specified string of characters in the named font, and the maximum ascent and descent for the
entire font. This function queries the server and, therefore, suffers the round trip overhead that
is avoided by XTextExtents, but it does not require a filled XFontInfo structure.
The returned ascent and descent should usually be used to calculate the line spacing,
while the width, rbearing, and lbearing members of overall should be used for
horizontal measures. The total height of the bounding rectangle, good for any string in this
font, is ascent + descent.
332 Xlib Reference Manual
Xlib - Text (continued) XQueryTextExtents
overall, ascent is the maximum of the ascent metrics of all characters in the string. The
overa22, descent is the maximum of the descent metrics. The overa22, width is the
sum of the character-width metrics of all characters in the string. The overa22.2bearing
is the lbearing of the character in the string with the smallest lbearing plus the width of all the
characters up to but not including that character. The overa22, rbearing is the rbearing
of the character in the string with the largest lbearing plus the width of all the characters up to
but not including that character.
For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and
Text.
XQueryTextExtents returns 1 on success, 0 on failure.
Structures
typedef struct {
short ibearing;
short rbearing;
short width;
short ascent;
short descent;
/* origin to left edge of character */
/* origin to right edge of character */
/* advance to next char's origin */
/* baseline to top edge of character */
/* baseline to bottom edge of character */
unsigned short attributes;/* per char flags (not predefined) */
} XCharStruct;
Errors
BadFont
BadGC
Related Commands
XQueryTextExtentsl6, XDrawImageString, XDrawImageStringl6, XDraw-
String, XDrawStringl6, XDrawText, XDrawTextl6, XTextExtents, XText-
Extentsl6, XTextWidth, XTextWidthl6.
333
Xlib Reference Manual
XReadBitmapFile
Xlib - Pixmaps and Tiles E
Name
XReadBitmapFile -- read a bitmap from disk.
Synopsis
int XReadBitmapFile ( display, drawable, filename, width,
height, bitmap, x_hot, y_hot)
Display *display;
Drawable drawable ;
char *filename;
unsigned int *width, *height; /* RETURN */
Pixmap *bitmap; /* RETURN */
int *x_hot, *y_hot; /* RETURN */
Arguments
di spl ay
dra wabl e
f i i en ame
wi d t h
height
bi tmap
x hot
--
y_hot
Description
Specifies a pointer to the Display structure; rcturned from XOpen-
Display.
Specifies the drawable.
Specifies the filename to use. The format of the filename is operating system
specific.
Return the dimensions in pixels of the bitmap that is read.
Returns the pixmap resource ID that is created.
Return the hotspot coordinates in the file (or -1,-1 if none present).
XReadBitmapFile reads in a file containing a pixmap of depth 1 (a bitmap). The file can
be either in the standard X Version 10 format or in the newer X Version 11 bitmap format
(which is only slightly different).
XReadBitmapFile creates a pixmap of the appropriate size, reads the bitmap data from the
file into the pixmap. The caller must free the bitmap using XFreePixmap when done.
If the file cannot be opened, XReadBitraapFile returns BitraapOpenFailed. If the file
can be opened but does not contain valid bitmap data, XReadBitraapFile returns Bitmap-
FileInvalid. If insufficient working storage is allocated, XReadBitmapFile returns
BitmapNoMemory. If the file is readable and valid, XReadBitmapFile returns Bitmap-
Success.
338 July 26, 1988
Xlib - Pixmaps and Tiles (continued) XReadBitmapFile
Here is an X Version 11 example bitmap file:
#define name width 16
--
#define name_height 16
#define name x hot 8
#define name y hot 8
static char name_bits[] = {
0xf8, 0xlf, 0xe3, 0xc7, 0xcf, 0xf3, 0x9f, 0xf9, 0xbf, 0xfd, 0x33, 0xcc,
0x7f, 0xfe, 0x7f, 0xfe, 0x7e, 0x7e, 0x7f, 0xfe, 0x37, 0xec, 0xbb, 0xdd,
0x9c, 0x39, 0xcf, 0xf3, 0xe3, 0xc7, 0xf8, 0xlf};
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Related Commands
XSet Tile, XQue ryBe st Tile, XSetWindowBo rde rP ixmap, XSetWindow-
BackgroundP ixmap, XCreateP ixmap, XCreateP ixmapF romBitmapDat a, XF ree-
Pixmap, XQueryBestSize, XQueryBestStipple, XWriteBitmapFile, XCreate-
BitmapFromData.
July 26, 1988
339
XRebindKeysym
Xlib - Keyboard--
Name
XRebindKeysym -- rebind a keysym to a string for client.
Synopsis
XRebindKeysym ( display, keysym, mod_list,
n um_byt es )
Display *display;
KeySym keysym;
KeySym *mod list;
int mod count;
unsigned char *string;
int num_bytes ;
rood_count, string,
Arguments
display
keysym
mod list
--
rood count
string
num_bytes
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the keysym to be rebound.
Specifies a pointer to an array of keysyms that are being used as modifiers.
Specifies the number of modifiers in the modifier list.
Specifies a pointer to the string that is to be copied and returned by
XLookupSt ring.
Specifies the length of the string.
XRebindKeysym binds the ASCII string to the specified keysym, so that string and
keysym arc returned when that key is pressed and the modifiers specified in mod_list are
also being held down. This function rebinds the meaning of a keysym for a client. It does not
redefine the keycode in the server but merely provides an easy way for long strings to be
attached to keys. Note that you are allowed to rebind a keysym that may not exist.
See Volume One, Chapter 9, The Keyboard and Pointer, for a description of keysyms and
keyboard mapping.
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap,
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifier-
Map, XQueryKeymap, XStringToKeysym, XLookupKeysym, XGetKeyboard-
Mapping, XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookup-
String, XSetModifierMapping, XGetModifierMapping.
340 July 26, 1988
XRemoveFromSaveSet
Xlib - Save Set D
Name
XRemoveFromSaveSet -- remove a window's children from the client's save-set.
Synopsis
XRemoveFromSaveSet ( display,
Display *display;
Window w;
w)
Arguments
display
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the window whose children you want to remove from this client's
save-set. This window must have been created by a client other than the
client making this call.
Description
XRemoveFromSaveSet removes a window's children from the save-set of the calling appli-
cation. Usually, this call is invoked by a window manager, using the RootWindow macro
for w, to remove all top-level windows on a screen from the save-set.
The save-set is a safety net for windows that have been reparented by the window manager,
usually to provide a shadow or other background for each window. When the window
manager dies unexpectedly, the windows in the save-set are reparented to their closest living
ancestor, so that they remain alive.
This call is not necessary when a window is destroyed since desla'oyed windows are automati-
cally removed from the save-set. See Volume One, Chapter 14, Window Management, for
more information about save-sets.
Errors
BadMatch
BadWindow
w not created by some other client.
Related Commands
XAddToSaveSet, XChangeSaveSet.
344 July 26, 1988
--Xlib - Host Access
XRemoveHost
Name
XRemoveHost--removeahostfrom theaccessconollist.
Synopsis
XRemoveHost(display, host)
Display *display;
XHostAddress *host;
Arguments
di spl ay
Specifies a point to the Display structu; tumed om XOpen-
Display.
host
Specifies the network address of the machine to be removed.
Description
XRemoveHost removes the specified host from the access control list on the host running the
server controlling the current display. The display hardware must be on the same host as the
calling process in order to change the access control list.
If you remove your own machine from the access control list, you can no longer connect to
that server, and there is no way back from this call other than to log out and reset the server.
The address dam must be a valid address for the type of network in which the server
operates, as specified in the family member.
For TCP/IP, the address should be in network byte order. For the DECnet family, the server
performs no automatic swapping on the address bytes. A Phase IV address is two bytes long.
The first byte contains the least significant eight bits of the node number. The second byte
contains the most significant two bits of the node number in the least significant two bits of
the byte, and the area in the most significant six bits of the byte.
For more information on access control lists, see Volume One, Chapter 13, Other Program-
ming Techniques.
Structures
typedef struct {
int family;
int length;
char *address;
} XHostAddress;
/* for example Family Internet */
/* length of address, in bytes */
/* pointer to where to find the bytes */
/* constants used for family member of XHostAddress */
#define FamilyInternet 0
#define FamilyDECnet 1
#define FamilyChaos 2
Errors
BadAccess
BadValue
July 26, 1988 345
XRemoveHost (contue Xlib - Host Access
Related Commands
XAddHost, XAddHosts, XListHosts, XRemoveHosts, XDisableAccessControl,
XEnableAccessControl, XSetAccessControl.
346 July 26, 1988
--Xlib - Host Access
XRemoveHosts
Name
XRemoveHosts m remove multiple hosts from the access conol list.
Synopsis
XRemoveHosts (display, hosts, num hosts)
--
Display *display;
XHostAddress *hosts;
int num hosts;
--
Arguments
di spl ay
hosts
num hosts
--
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the list of hosts that are to be removed.
Specifies the number of hosts that are to be removed.
Description
XRemoveHosts removes each specified host from the access control list on the local
machine running the server. The display hardware must be on the same host as the client pro-
cess, in order to change the access control list.
If you remove your machine from the access conol list, you can no longer connect to that
server, and there is no way back from this call except to log out and reset the server.
The address data must be a valid address for the type of network in which the server
operates, as specified in the family member.
For TCP/IP, the address should be in network byte order. For the DECnet family, the server
performs no automatic swapping on the address bytes. A Phase IV address is two bytes long.
The first byte contains the least significant eight bits of the node number. The second byte
contains the most significant two bits of the node number in the least significant two bits of
the byte, and the area in the most significant six bits of the byte.
For more information on access control lists, see Volume One, Chapter 13, Other Program-
ming Techniques.
Structures
typedef struct {
int family;
int length;
char *address;
} XHostAddress;
/* for example Family Internet */
/* length of address, in bytes */
/* pointer to where to find the bytes */
/* constants used for family member of XHostAddress */
#define FamilyInternet 0
#define FamilyDECnet 1
#define FamilyChaos 2
July 26, 1988 34 7
X Rem oveHosts (continued) Xlib - Host Access
Errors
BadAccess
BadValue
Related Commands
XAddHost, XAddHosts, XListHosts, XRemoveHost, XDisableAccessControl,
XEnableAccessControl, XSetAccessControl.
348 July 26, 1988
NXlib - Window Manipulation
XReparentWindow
Name
XReparentWindow -- insert a window between another window and its parent.
Synopsis
XReparentWindow (display, win, parent, x, y)
Display *display;
Window win ;
Window parent ;
int x, y;
Arguments
display
win
pa ren t
x
y
Description
Specifies a pointer to the Display structure; returned from X0pen-
Display.
Specifies the ID of the window to be reparented.
Specifies the window ID of the new parent window.
Specify the coordinates of the window relative to the new parent.
XReparentWindow modifies the window hierarchy by placing window win as a child of
window parent. This function is usually used by a window manager to put a dccoration
window behind application windows. In the case of the window manager, the new parent win-
dow must first be created as a child of the root window.
If win is mapped, an XUnmapWindow request is performed on it automatically, win is then
removed from its current position in the hierarchy, and is inserted as a child of the specified
parent, win is placed on top in the stacking order with respect to siblings.
A ReparentNotify event is then generated. The override_redirect member of the
structure returned by this event is set to either True or False. Window manager clients
normally should ignore this event if this member is set to True.
Finally, if the window was originally mapped, an XMapWindow request is performed
automatically.
Descendants of win remain descendants of win; they are not reparented to the old parent of
win.
Normal exposure processing on formerly obscured windows is performed. The server might
not generate exposure events for regions from the initial unmap that are immediately obscured
by the final map. The request fails if the new parent is not on the same screen as the old
parent, or if the new parent is the window itself or an inferior of the window.
July 26, 1988 349
XReparentWindow (continued) Xlib - Window Manipulation
Errors
BadMatch
BadWindow
parent not on same screen as old parent of win.
win has a ParentRelative background and parent is not [he same
dep[h as win.
parent is win or an infeor of win.
Related Commands
XLowerWindow, XRaiseWindow, XCirculateSubwindows, XCirculate-
SubwindowsDown, XCirculateSubwindowsUp, XRestackWindows, XMove_
Window, XResizeWindow, XMoveResizeWindow, XConfigureWindow, XQuery_
Tree.
350 July 26, 1988
mXlib - Screen Saver
X Re se tSc ree n Sa ve r
Name
XResetScreenSaver n reset the screen saver.
Synopsis
XResetScreenSaver(display)
Display *display;
Arguments
display
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Description
XResetScreenSaver redisplays the screen ff the screen saver was activated. This may
result in exposure events to all visible windows if the server cannot save the screen contents.
If the screen is already active, nothing happens.
For more information on the screen saver, see Volume One, Chapter 13, Other Programming
Techniques.
Related Commands
XForceScreenSaver, XActivateScreenSaver, XGetScreenSaver, XSet-
ScreenSaver.
July 26, 1988
351
--Xlib - Window Manipulation-.
XRestackWindows
Name
XRestackWindows -- change the stacking order of siblings.
Synopsis
XRestackWindows (display, windows, nwindows ) ;
Display *display;
Window windows [] ;
int nwindows ;
Arguments
display
windows
nwindows
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies an array containing the windows to be restacked. All the windows
must have a common parent.
Specifies the number of windows to be restacked.
XRestackWindows restacks the windows in the order specified, from top to bottom. The
stacking order of the first window in the windows array will be on top, and the other win-
dows will be stacked underneath it in the order of the array. Note that other siblings may not
be included in the windows array and so the top window in that array will not move relative
to these other siblings.
For each window in the window array that is not a child of the specified window, a Bad-
Match error will be generated. If the override redirect attribute of the window is
--
False and some other client has selected SubstructureRedirectMask on the parent,
then ConfigureRequest events are generated for each window whose
override_redirect is not set, and no further processing is performed. Otherwise, the
windows will be restacked in top to bottom order.
Errors
BadMatch
BadWindow
Related Commands
XLowerWindow, XRaiseWindow, XCirculateSubwindows, XCirculate-
SubwindowsDown, XCirculateSubwindowsUp, XMoveWindow, XResizeWindow,
XMoveResizeWindow, XReparentWindow, XConfigureWindow, XQueryTree.
July 26, 1988 353
XrmGetFileDatabase
Xlib - Resource Manager--
Name
XrmGetFileDatabase m retrieve a database from a file.
Synopsis
XrmDatabase XrmGetFileDatabase(filename)
char *filename;
Arguments
f i i en ame
Specifies the resource database filename.
Description
XrmGetFileDatabase opens the specified file, creates a new resource database, and loads
it with the data read in from the file. The return value of the function is subsequently used as
a pointer to the created database.
The specified file must contain lines in the format accepted by XrmPutLineResource. If
it cannot open the specified file, XrmGetFileDatabase returns NULL.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
XrmDatabase is a pointer to an opaque data type.
Related Commands
XrmGetResource, XrmGetStringDatabase, XrmInitialize, XrmMerge-
Databases, XrmParseCommand, XrmPutFileDatabase, XrmPutLineResource,
XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGet-
SearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutString-
Resource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmString-
ToQuarkList, XrmStringToQuark, XrmUniqueQuark.
354 July 26, 1988
mXlib - Resource Manager-
XrmGetResource
Name
XrmGetResource -- get a resource from name and class as stnngs.
Synopsis
Bool XrmGetResource ( database,
str_type, value)
XrmDatabase database;
char *str name;
--
char *str class;
--
char **str_type;
XrmValue *value;
str_name, str class,
--
/* RETURN */
/* RETURN */
Arguments
database
str name
str class
str_type
value
Specifies the database that is to be used.
Specifies the fully qualified name of the value being retrieved (as a string).
str_name is an instance of a name retrieval key as described below.
Specifies the fully qualified class of the value being retrieved (as a string).
str_c2ass is an instance of a class retrieval key as described below.
Returns a pointer to the representation type of the destination. In this func-
tion, the representation type is itself represented as a string, not as an Xrm-
Representation.
Returns the value in the database. Do not modify or free this data.
Description
The resource manager manages databases of resources consisting of lines containing resource
name/class strings followed by a colon and the value of the resource. XrmGetResource
retrieves a resource from the specified database. It takes fully qualified name and class strings,
and returns the representation and value of the matching resource. The value returned points
into database memory; therefore, you must not modify that data. If a resource was found,
XrmGetResource returns True. Otherwise, it returns False.
Currently, the database only frees or overwrites entries when new data is stored with Xrm-
MergeDatabases, or XrmPutResource and related routines. A client that avoids these
functions should be safe using the address passed back at any time until it exits.
XrmGetResource is very similar to XrmQGetResource, except that in XrmQGet-
Resource, the equivalent arguments to str_name, str_class, and str_type are
quarks instead of strings.
To understand how data is stored and retrieved from the database, you must understand:
1) The basic components that make up the storage key and retrieval keys.
2) How keys are made up from components.
3) The two ways that components can be bound together.
July 26, 1988 355
Xrmlnitialize
Xlib - Resource Manager m
Name
Xrmlnitialize -- initialize the resource manager.
Synopsis
void XrmInitialize();
Description
xrmInitialize initializes the resource manager, and should be called once before using
any other resource manager functions. All it does is to create a representation type of
"String" for values defined as strings. This representation type is used by XrmPutString-
Resource and XrmQPutStringResource, which require a value as a string. See Xrm-
QPutResource for a descption of representation types.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, XrmMerge-
Databases, XrmParseCommand, XrmPutFileDatabase, XrmPutLineResource,
XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGet-
SearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutString-
Resource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmString-
ToQuarkList, XrmSt ringToQuark, XrmUniqueQuark.
360 July 26, 1988
Xlib - Resource Manager (continued) Xrm ParseCom mand
static XrmOptionDescRec opTable[ ] = {
{"-background", "*background",
{"-bd", "*borderColor",
{"-bg", "*background",
{"-borderwidth", "*TopLevelShell.borderWidth",
{"-bordercolor", "*borderColor",
{"-bw", "*TopLevelShell.borderWidth",
{ "-display", ".display",
{ "-fg", "* foreground",
{ "- fn", " * font",
{"-font", "*font",
{ "- foreground", " * foreground",
{ "-geomet ry", ".TopLeve iShe i i. geomet ry",
{ "- icon ic", ".TopLeve iShe 11. iconic",
{ "-name", ".name",
{ "- reve rse", " * reve rseVideo",
{ "- rv", "* reve r seVideo",
{"-synchronous", ".synchronous",
{ "-title", ".TopLevelShe ii. title",
{ "-xrm", NULL,
};
XrmoptionSepArg, (caddr_t) NULL},
XrmoptionSepArg, (caddr_t) NULL},
XrmoptionSepArg, (caddr_t) NULL},
XrmoptionSepArg, (caddr_t) NULL},
XrmoptionSepArg, (caddr_t) NULL},
XrmoptionSepArg, (caddr_t) NULL},
XrmoptionSepArg, (caddr t) NULL},
_
XrmoptionSepArg, (caddr_t) NULL},
XrmoptionSepArg, (caddr_t) NULL},
XrmoptionSepArg, (caddr_t) NULL},
XrmoptionSepArg, (caddr_t) NULL},
XrmoptionSepArg, (caddr_t) NULL},
XrmoptionNoArg, (caddr_t) "on"},
XrmoptionSepArg, (caddr_t) NULL},
XrmoptionNoArg, (caddr_t) "on"},
XrmoptionNoArg, (caddr_t) "on"},
XrmoptionNoArg, (caddr_t) "on"},
XrmoptionSepArg, (caddr_t) NULL},
XrmoptionResArg, (caddr_t) NULL},
In this table, if the -background (or -bg) option is used to set background colors, the stored
resource specifier will match all resources of attribute background. If the -borderwidth option
is used, the stored resource specifier applies only to border width attributes of class Top-
l,evelShell (that is, outermost windows, including pop-up windows). If the -title option is
used to set a window name, only the topmost application windows receive the resource.
When parsing the command line, any unique unambiguous abbreviation for an option name in
the table is considered a match for the option. Note that upper case and lower case matter.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
XrmDatabase is a pointer to an opaque dam type.
typedef enum {
XrmoptionNoArg,
XrmoptionIsArg,
XrmoptionStickyArg,
XrmoptionSepArg,
XrmoptionResArg,
XrmoptionSkipArg,
XrmoptionSkipLine
} XrmOptionKind;
/* value is specified in OptionDescRec.value */
/* value is the option string itself */
/* value is chars immediately following option */
/* value is next argument in argv */
/* resource and value in next argument in argv */
/* ignore this option and next argument in argv */
/* ignore this option and the rest of argv */
typedef struct {
char *Option; /* option specification string in argv */
char *resourceName; /* binding & resource name (w/out application name) */
XrmOptionKind argKind; /* which style of option it is */
caddr t value; /* value to provide if XrmoptionNoArg */
_
} XrmOptionDescRec, *XrmOptionDescList;
July 26, 1988
363
XrmParseCom mand (continued) Xlib - Resource Manager
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm-
Initialize, XrmMergeDatabases, XrmPutFileDatabase, XrmPutLine-
Resource, XrmPutResource, XrmPutStringResource, XrmQGetResource, Xrm-
QGetSearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPut-
StringResource, XrmQuarkToString, XrmStringToBindingQuarkList, Xrm-
StringToQuarkList, XrmStringToQuark, XrmUniqueQuark.
364 July 26, 1988
mXlib - Resource Manager
XrmPutFileDatabase
Name
XrmPutFileDatabase -- store a database in a file.
Synopsis
void XrmPutFileDatabase(database, stored db)
XrmDatabase database;
char *stored db;
--
Arguments
database
stored db
Specifies the database that is to be saved.
Specifies the filename for the stored database.
Description
XrmPutFileDatabase stores a copy of the application's current database in the specified
file. The file is an ASCII text file that contains lines in the format that is accepted by Xrm-
PutLineResource.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
XrmDatabase is a pointer to an opaque data type.
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm-
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutLineResource,
XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGet-
SearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutString-
Resource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmString-
ToQuarkList, XrmStringToQuark, XrmUniqueQuark.
July 26, 1988
365
Xlib - Resource Manager (continued) Xrm PutLi neResource
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm-
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase,
XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGet-
SearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutString-
Resource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmString-
ToQuarkList, XrmStringToQuark, XrmUniqueQuark.
July 26, 1988
367
XrmPutResource
Xlib - Resource Manager m
Name
XrmPutResource -- store a resource into a database.
Synopsis
void XrmPutResource (database, specifier, type, value)
XrmDatabase *database; /* SEND, and if NULL, RETURN */
char *specifier;
char *type;
XrmValue *value;
Arguments
database
specifier
type
val ue
Description
Specifies a pointer to the resource database. If database contains NULL, a
new resource database is created and a pointer to it is returned in data-
base.
Specifies a complete or partial specification of the resource.
Specifies the type of the resource.
Specifies the value of the resource.
XrmPutResource is one of several functions which store data into a database.
XrraQPutResource first converts specifier into a binding list and a quark list by calling
XrmStringToBindingQuarkList, and converts type into an XrmRepresentation
by calling XrmStringToRepresentat ion. Finally, it puts the data into the database.
XrmPutResource, XrmQPutResource, XrmPut St ringRes ource, XrmQPut-
StringResource and XrmPutLineResource all store data into a database. See the
description of XrmQPutResource for the most complete description of this process.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
XrmDatabase is a pointer to an opaque dam type.
typedef struct {
unsigned int size;
caddr t addr;
--
} XrmValue, *XrmValuePtr;
368 July 26 1988
Xlib- Resource Manager (continued) XrmPutResource
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm-
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase,
XrmPutLineResource, XrmPutStringResource, XrmQGetResource, XrmQGet-
SearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutString-
Resource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmString-
ToQuarkList, XrmStringToQuark, XrmUniqueQuark.
July 26, 1988
369
--Xlib - Resource Manager
XrmQGetResource
Name
XrmQGetResource -- get a resource from name and class as quarks.
Synopsis
BOO1 XrmQGetResource (database, quark_name, quark_class,
quark_type, value)
XrmDatabase database ;
XrmNameList quark_name ;
XrmClassList quark_class ;
XrmRepresentation *quark_type; /* RETURN */
XrmValue *value; /* RETURN */
Arguments
database
Specifies the database that is to be used.
quark name Specifies the fully qualified name of the value being retrieved (as a list of
--
quarks).
quark class Specifies the fully qualified class of the value being retrieved (as a list of
quarks).
quark_type Returns a pointer to the representation type of the destination. In this func-
tion, the representation type is itself represented as a quark.
value Returns a pointer to the value in the database. Do not modify or free this
data.
Description
XrmQGetResource retrieves a resource from the specified database. It takes fully qualified
name and class strings, and returns the representation and value of the matching resource. The
value returned points into database memory; therefore, you must not modify that data. If a
resource was found, XrmQGetResource returns True. Otherwise, it returns False.
Currently, the database only frees or overwrites entries when new data is stored with Xrm-
HergeDatabases, or XrmPutResource and related routines. A client that avoids these
functions should be safe using the address passed back at any time until it exits.
XrmQGetResource is very similar to XrmGetResource, except that in XrmGet-
Resource, the cquiva|ent arguments to quark_name, quark_class, and quark_type
arguments are strings instead of quarks.
See XrmGetResource for a full description of how data is looked up in the database.
For more information, see Volume One, Chapter 11, Managing User Preferences.
July 26, 1988 371
XrmQGetResource (continued) Xlib- Resource Manager
Structures
XrmDatabase is a pointer to an opaque dam type.
typedef XrmQuarkList XrmNameList;
typedef XrmQuarkList XrmClassList;
typedef XrmQuark XrmRepresentation;
typedef struct {
unsigned int size;
caddr t addr;
--
} XrmValue, *XrmValuePtr;
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm-
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase,
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet-
SearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutString-
Resource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmString-
ToQuarkList, XrmStringToQuark, XrmUniqueQuark.
372 July 26 1988
mXlib - Resource Manager
XrmQGetSearch List
Name
XrmQGetSearchList -- return a list of database levels.
Synopsis
Bool XrmQGetSearchList (database, names, classes,
search_list, list_length)
XrmDatabase database ;
XrmNameList names ;
XrmClassList classes;
XrmSearchList search list; /* RETURN */
--
int list_length ;
Arguments
database Specifies the database that is to be used.
names Specifies a list of resource names.
cl asses Specifies a list of resource classes.
search_list Returns a search list for further use. The caller must allocate sufficient space
for the list before calling XrmQGetSearchList.
list_length Specifies the number of entries (not the byte size) allocated for list.
Description
XrmQGetSearchList is a tool for searching the database more efficiently. It is used in
combination with XrmGetSearchResource. Often, one searches the database for many
similar resources which differ only in their final component (e.g. xmh. toc. foreground,
xmh.toc.background, etc). Rather than looking for each resource in its entirety, Xrm-
GetSearchList searches the database for the common part of the resource name, returning
a whole list of items in the database that match it. This list is called the search list. This
search list is then used by XrmQGetSearchList, which searches for the last components
one at a time. In this way, the common work of searching for similar resources is done only
once, and the specific part of the search is done on the much shorter search list.
XrmQGetSearchList takes a list of names and classes and returns a list of database levels
where a match might occur. The returned list is in best-to-worst order and uses the same algo-
rithm as XrmGetResource for determining precedence. If search_list was large
enough for the search list, XrmQGetSearchList returns True. Otherwise, it returns
False.
The size of the search list that must be allocated by the caller is dependent upon the number of
levels and wildcards in the resource specifiers that are stored in the database. The worst case
length is 3", where n is the number of name or class components in names or classes.
Only the common prefix of a resource name should be specified in the name and class list to
XrmQGetSearchList. In the example above, the common prefix would be xmh.toc.
However, note that XrraQGetSearchResource requires that name represent a single com-
July 26, 1988 373
XrmQGetSearchList (continued) Xlib- Resource Manager
ponent only. Therefore, the common prefix must be all but the last component of the name
and class.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
XrmDatabase is a pointer to an opaque dam type.
typedef XrmQuarkList XrmNameList;
typedef XrmQuarkList XrmClassList;
typedef XrmQuark XrmRepresentation;
XrmSearchList is a pointer to an opaque dam type.
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm-
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase,
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet-
Resource, XrmQGetSearchResource, XrmQPutResource, XrmQPutString-
Resource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmString-
ToQuarkList, XrmStringToQuark, XrmUniqueQuark.
374 July 26, 1988
--Xlib- Resource Manager.
XrmQGetSearch Resource
Name
XrmQGetSearchResource m search resource database levels for a given resource.
Synopsis
Bool XrmQGetSearchResource (search_list, name, class,
type, value)
XrmSearchList search list;
--
XrmName name ;
XrmClass class;
XrmRepresentation *type; /* RETURN */
XrmValue *value; /* RETURN */
Arguments
search_list Specifies the search list returned by XrmQGetSearchList.
name Specifies the resource name.
class Specifies the resource class.
type Returns the data representation type.
value Returns the value in the database.
Description
XrmQGetSearchResource is a tool for searching the database more efficiently. It is used
in combination with XrmGetSearchList. Often, one searches the database for many simi-
lar resources which differ only in their final component (e.g., xmh.toc, foreground,
xmh. toc. background, etc). Rather than looking for each resource in its entirety, Xrm-
GetSearchList searches the database for the common part of the resource name, returning
a whole list of items in the database that match it. This list is called the search list. Xrm-
QGetSearchResource searches the search list for the resource that is fully identified by
name and class. The search stops with the first match. XrmQGetSearchResource
returns True if the resource was found; otherwise, it returns False.
A call to XrrnQGetSearchList with a name and class list containing all but the last com-
ponent of a resource name followed by a call to XrrnQGetSearchResource with the last
component name and class returns the same database entry as XrraGetResource or Xrra-
QGetResource would with the fully qualified name and class.
For more information, see Volume One, Chapter 11, Managing User Preferences.
July 26. 1988 375
XrmQGetSearchResource (continued) Xlib- Resource Manager
Structures
XrmDatabase is a pointer to an opaque dam type.
typedef XrmQuark XrmName;
typedef XrmQuark XrmClass;
typedef XrmQuark XrmRepresentation;
typedef struct {
unsigned int size;
caddr t addr;
--
} XrmValue, *XrmValuePtr;
XrmSearchList is a pointer to an opaque dam type.
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm-
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase,
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet-
Resource, XrmQGetSearchList, XrmQPutResource, XrmQPutStringResource,
XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuark-
List, XrmStringToQuark, XrmUniqueQuark.
376 July 26 1988
nXlib - Resource Manager-
XrmQPutResource
Name
XrmQPutResource -- store a resource into a database using quarks.
Synopsis
void XrmQPutResource(database, bindings, quarks, type, value)
XrmDatabase *database; /* SEND, and if NULL, RETURN */
XrmBindingList bindings;
XrmQuarkList quarks;
XrmRepresentation type;
XrmValue *value;
Arguments
database
bindings
quarks
type
va i ue
Specifies a pointer to the resource database. If database contains NULL, a new
resource database is created and a pointer to it is returned in database.
Specifies a list of bindings for binding together the quarks argument.
Specifies the complete or partial name or class list of the resource to be stored.
Specifies the type of the resource.
Specifies the value of the resource.
Description
XrmQPutResource stores a resource into the database.
database can be a previously defined database, as returned by XrmGetString-
Database, XrmGetFileDatabase, or om XrmMergeDatabases. If database is
NULL, a new database is created and a pointer to it returned in database.
bindings and quarks together specify where the value should be stored in the database.
See XrmStringToBindingQuarkList for a brief description of binding and quark lists.
See XrnaGetResource for a description of the resource manager naming conventions and
lookup rules.
type.is the representation, type of value. This provides a way to distinguish between
different representations of the same information. Representation types are user defined char-
acter strings describing the way the data is represented. For example, a color may be specificd
by a color name ("red"), or be coded in a hexadecimal string ("#4f6c84") (if it is to be used
as an argument to xParseColor.) The representation type would distinguish between these
two. Representation types are created from simple character strings by using the macro Xrm-
StringToRepresentation. The type XrmRepresentation is actually the same type
as XrmQuark, since it is an ID for a string. The representation is stored along with the value
in the database, and is returned when the database is accessed.
val ue is the value of the resource, specified as an xrnaValue.
XrnaGetResource contains the complete description of how data is accessed from the data-
base, and so provides a good perspective on how it is stored.
July 26, 1988 377
XrmQPutResource (continued) Xlib- Resource Manager
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
Xrrrd3atabase is a pointer to an opaque data type.
typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList
typedef int XrmQuark, *XrmQuarkList;
typedef XrmQuarkList XrmNameList;
typedef XrmQuark XrmRepresentation;
typedef struct {
unsigned int size;
caddr t addr;
} XrmValue, *XrmValuePtr;
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm-
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase,
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet-
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutString-
Resource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmString-
ToQuarkList, XrmStringToQuark, XrmUniqueQuark.
378 July 26, 1988
mXlib - Resource Manager
XrmQPutStringResource
Name
XrmQPutStringResource -- add a string resource value to a database using quarks.
Synopsis
void XrmQPutStringResource (database, bindings, quarks, value)
XrmDatabase *database; /* SEND, and if NULL, RETURN */
XrmBindingList bindings ;
XrrnQuarkList quarks ;
char *value;
Arguments
database
bindings
quarks
val ue
Description
Specifies a pointer to the resource database. If database contains NULL, a new
resource database is created and a pointer to it is returned in database.
Specifies a list of bindings for binding together the quarks argument.
Specifies the complete or partial name or class list of the resource to be stored.
Specifies the value of the resource as a string.
XrmQPutStringResource stores a resource into the specified database.
XrmQPutStringResource is a cross between XrmQPutResource and XrmPut-
StringResource. Like XrrnQPutResource, it specifies the resource by quarks and
bindings, two lists that together make a name/class list with loose and tight bindings. Like
XarmPutStaringResouarce, it specifies the value to be stored as a string, that value is con-
vened into an xarrnValue, and the default representation type Staring is used.
XrmPutResource, XrmQPutResource, XrmPut St ringResource, XrmQPut-
StringResource and XrmPutLineResource all store data into a database. See Xrm-
QPutResource for the most complete description of this process.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
XrmDatabase is a pointer to an opaque data type.
typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList.
typedef int XrmQuark, *XrmQuarkList;
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm-
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase,
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet-
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource,
XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuark-
List, XrmStringToQuark, XrmUniqueQuark.
July 26, 1988 379
XrmQuarkToString
Xlib- Resource Manager m
Name
XrmQuarkToString -- convert a quark to a string.
Synopsis
char *XrmQuarkToString(quark)
XrmQuark quark;
Arguments
quark
Specifies the quark for which the equivalent string is desired.
Description
XrrnQuarkToString returns the string for which the quark is serving as a shorthand sym-
bol. The quark was earlier set to represent the string by XrmStringToQuark. The string
pointed to by the return value must not be modified or freed, because that string is in the data
structure used by the resource manager for assigning quarks. If no string exists for that quark,
these routines return NULL.
Quarks are used by the resource manager to represent strings. Since the resource manager
needs to make many comparisons of strings when it gets data from the database, it is more
efficient to convert these strings into quarks, and to compare quarks instead. Since quarks are
presently represented by integers, comparing quarks is trivial.
The three #define statements in the Structures section provide an extra level of abstraction.
They define macros so that names, classes and representations can also be represented as
quarks.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
typedef int XrmQuark;
/* macro definitions from <Xll/resource.h> */
#define XrmNameToString (name) XrmQuarkToString (name)
#define XrmClassToString (class) XrmQuarkToString (class)
#define XrmRepresentationToString (type) XrmQuarkToString (type)
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm-
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase,
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet-
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource,
XrmQPutStringResource, XrmStringToBindingQuarkList, XrmString-
ToQuarkList, XrmStringToQuark, XrmUniqueQuark.
380 July 26, 1988
uXlib - Resource Manager
XrmStringToBindingQuarkList
Name
XrmStringToBindingQuarkList m convert a key string to a binding list and a quark list.
Synopsis
XrmStringToBindingQuarkList(string, bindings, quarks)
char *string;
XrmBindingList bindings; /* RETURN */
XrmQuarkList quarks; /* RETURN */
Arguments
string
bindings
quark
Description
Specifies the string for which the list of quarks and list of bindings are to be
generated. Must be NULL terminated.
Returns the binding list. The caller must allocate sufficient space for the
binding list before the call.
Returns the list of quarks. The caller must allocate sufficient space for the
quarks list before the call.
XrmStringToBindingQuarkList convers the sing into two liss--one of quarks and
one of bindings. Component names in the list are separated by a dot (".") indicating a tight
binding or an asterisk ("*") indicating a loose binding. If the string does not start with dot or
asterisk, a dot (".") is assumed.
A tight binding means that the quarks on either side of the binding are consecutive in the key.
A loose binding, on the other hand, is a wildcard that can match any number of unspecified
components in between the two quarks separated by the binding. Tight and loose bindings are
used in the match rules, which compare multicomponent strings to find matches and determine
the best match. See XrrnGetResource for a full description of lookup rules.
For example, *a. b*c becomes:
quarks bindings
"a" XrmBindLoosely
"b" XrmBindTight ly
"C" XrmBindLoosely
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
typedef int XrmQuark, *XrmQuarkList;
typedef enum (XrmBindLoosely, XrmBindTightly) XrmBinding, *XrmBindingList;
July 26, 1988 381
XrmStringToBindingQuarkList (continued) Xlib- Resource Manager
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm-
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase,
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet-
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource,
XrmQPutStringResource, XrmQuarkToString, XrmStringToQuarkList, Xrm-
St ringToQua rk, XrmUniqueQua rk.
382 July 26, 1988
Xlib- Resource Manager (continued) XrmStringToQuarkList
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm-
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase,
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet-
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource,
XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuark-
List, XrmStringToQuark, XrmUniqueQuark.
July 26, 1988
385
XrmUniqueQuark
Xlib - Resource Manager m
Name
XrmUniqueQuark -- allocate a new quark.
Synopsis
XrmQuark XrmUniqueQuark()
Description
XrmUniqueQuark allocates a quark that is guaranteed not to represent any existing string.
For most applications, XrraStringToQuark is more useful, as it binds a quark to a string.
However, on some occasions, you may want to allocate a quark that has no string equivalent.
The shorthand name for a string is called a quark and is the type XrmQuark. Quarks are
used to improve performance of the resource manager, which must make many string com-
parisons. Quarks are presently represented as ints. Simple comparisons of quarks can be per-
formed rather than lengthy string comparisons.
A quark is to a string what an atom is to a property name in the server, but its use is entirely
local to your application.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
typedef int XrmQuark;
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, Xrm-
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase,
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet-
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource,
XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuark-
List, XrmStringToQuarkList, XrmStringToQuark.
386 July 26, 1988
--Xlib - Cut Buffers
XRotateBuffers
Name
XRotateBuffers -- rotate the cut buffers.
Synopsis
XRotateBuffers (display, rotate)
Display *display;
int rotate;
Arguments
display
rotate
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies how many positions to rotate the cut buffers.
XRotateBuffers rotates the 8 cut buffers the amount specified by rotate. Buffer 0
becomes buffer rotate, buffer 1 becomes buffer rotate+l mod 8, buffer 2 becomes buffer
rotate+2 mod 8, and so on. This cut buffer numbering is global to the display. This rou-
tine will not work if any of the buffers have not been stored into with XStoreBuffer.
See the description of cut buffers in Volume One, Chapter 13, Other Programming Tech-
niques.
E rro rs
BadAtom
BadMatch
BadWindow
Related Commands
XStoreBuffer, XStoreBytes, XFetchBuffer, XFetchBytes.
July 26, 1988 38 7
Xlib - Properties (continued) X RotateWi ndowProperties
Related Commands
XSet S t anda rdP rope rt ie s, XGetF ontP rope rt y, XDe leteP rope rt y, XChange-
Property, XGetWindowProperty, XListProperties, XGetAtomName, XIntern-
Atom.
July 26, 1988
389
XSaveContext
Xlib - Context Manager--
Name
XSaveContext -- save a data value corresponding to a window and context type (not
graphics context).
Synopsis
int XSaveContext (display, w, context, data)
Display *display;
Window w;
XContext context ;
caddr t data;
--
Arguments
display Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the ID of the window with which the data is associated.
Specifies the context type to which the data corresponds.
Specifies the data to be associated with the window and type.
w
context
data
Description
XSaveContext saves data to the context manager database, according to the specified
window and context ID. The context manager is used for associating data with windows
within an application. The client must have called XUniqueContext to get the context
ID before calling this function. The meaning of the data is indicated by the context ID,
but is completely up to the client.
If an entry with the specified window and context ID already exists, xSaveContext
writes over it with the specified data.
The xSaveContext function returns XCNOMEM (a nonzero error code) if an error has
occurred and zero (0) otherwise. For more information, see the description of the context
manager in Volume One, Chapter 13, Other Programming Techniques.
Structures
typedef int XContext;
Related Commands
XDeleteContext, XFindContext, XUniqueContext.
390 July 26, 1988
XSelectlnput (continued) Xlib- Input Handling
window will see the ButtonRelease event corresponding to the ButtonPress event,
even though the mouse may have exited the window in the meantime.
If PointerMotionMask is selected, events will be sent independent of the state of the
mouse buttons. If instead, one or more of ButtonlMotionMask, Button2MotionMask,
Button3MotionMask, Button4MotionMask, Button5MotionMask is selected,
MotionNotify events will be generated only when one or more of the specified buttons is
depressed.
XOpenDisplay sets the event_mask attribute; this attribute can also be set directly with
XChangeWindowAtt ributes.
For more information, see Volume One, Chapter 8, Events.
Errors
BadValue
BadWindow
Related Commands
XSetInputFocus, XGetInputFocus, XWindowEvent, XCheckWindowEvent,
XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMask-
Event, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents,
XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent,
XPending, XSynchronize, XSendEvent, QLength.
392 July 26, 1988
uXlib - Input Handling
XSendEvent
Name
XSendEvent -- send an event.
Synopsis
Status XSendEvent (display, w, propagate,
Display *display;
Window w;
Bool propagate;
unsigned long event mask;
--
XEvent *event ;
event mask, event)
--
Arguments
display
propa ga t e
event mask
--
e yen t
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the ID of the window where you want to send the event. Pass the
window resource ID, PointerWindow, or InputFocus.
Specifies how the sent event should propagate depending on event mask.
--
See description below. May be True or False.
Specifies the event mask. See XSelectInput for a detailed list of the
event masks.
Specifies a pointer to the event to be sent.
XSendEvent sends an event from one client to another (or conceivably to itself). This func-
tion is used for communication between clients using selections, for simulating user actions in
demos, and for other purposes.
The specified event is sent to the window indicated by w regardless of active grabs.
If w is set to PointerWindow, the destination of the event will be the window that the
pointer is in. If w is InputFocus is specified, then the destination is the focus window,
regardless of pointer position.
If propagate is False, then the event is sent to every client selecting on the window
specified by w any of the event types in event mask. If propagate is True and no
--
clients have been selected on w any of the event types in event_mask, then the event pro-
pagates like any other event.
The event code must be one of the core events, or one of the events defined by a loaded exten-
sion, so that the server can correctly byte swap the contents as necessary. The contents of the
event are otherwise unaltered and unchecked by the server except that in Release 1 the most
significant bit of XEvent. type is set to 1. In Release 2, the high bit is no longer scL
Instead, a new flag send event has been added to each event, which if True indicates that
--
the event was sent with XSendEvent.
July 26, 1988 393
XSendEvent (continued) Xlib- Input Handling
Under Release 1, if a client wants to read events sent by XSendEvent as normal events, it
must ignore the high bit by ORing the event type with the following expression:
XEvent report;
XNextEvent(display, &report) ;
report.type &= 0x7f;
/* now sent event looks like any other */
This function is often used in selection processing. For example, the owner of a selection
should use XSendEvent to send a SelectionNotify event to a requestor when a selec-
tion has been converted and stored as a property. See Volume One, Chapter 10, Interclient
Communication for more information.
The status returned by XSendEvent indicates whether or not the given XEvent structure
was successfully converted into a wire event. Along with changes in the extensions mechan-
ism, this makes merging of two wire events into a single user-visible event possible.
Structures
See Appendix F, Structure Reference, for the contents of specific event structures.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheck-
WindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent,
XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotion-
Events, XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBack-
Event, XPending, XSynchronize, QLength.
394 July 26, 1988
Xllb - Host Access
XSetAccessControl
Name
XSetAccessControl -- disable or enable access control.
Synopsis
XSetAccessControl (display, mode)
Display *display;
int mode ;
Arguments
di spl ay
mode
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies whether you want to enable or disable the access control. Pass one
of these constants: EnableAccess or DisableAccess.
Description
XSetAccessControl specifies whether to check the host access list before allowing access
to clients running on remote hosts. If the constant used is DisableAccess, clients from
any host have access unchallenged.
This routine can only be called from a client running on the same host as the server.
For more information on access control lists, see Volume One, Chapter 13, Other Program-
ming Techniques.
Errors
BadAccess
BadValue
Related Commands
XAddHost, XAddHosts, XListHosts, XRemoveHost, XRemoveHosts, XDisable-
AccessControl, XEnableAccessControl.
July 26, 1988 395
--Xlib - Graphics Context
XSetArcMode
Name
XSetArcMode -- set the arc mode in a graphics context.
Synopsis
XSetArcMode (display, gc, arc mode)
Display *display;
GC gc ;
int arc mode;
Arguments
di spl ay
gc
arc mode
Specifies a pointer to the Display structure; returned from X0pen-
Display.
Specifies the graphics context.
Specifies the arc mode for the specified graphics context. Possible values are
ArcChord or ArcPieSlice.
Description
XSetArcMode sets the arc mode member of the GC, which conlxols filling in the XFilI-
--
Arcs function. ArcChord specifies that the area between the arc and a line segment joining
the endpoints of the arc is filled. ArcPieSlice specifies that the area filled is delimited by
the arc and two line segments connecting the ends of the arc to the center point of the rectan-
gle defining the arc.
ArcChord
ArcPieSlice
July 26, 1988
397
XSetArcMode (continued) Xlib - Graphics Context
Errors
BadAlloc
BadGC
BadValue
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple,
XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSet-
FillRule, XSetFillStyle, XSetForeground, XSetBackground, XSet-
Function, XSetGraphicsExposures, XSetClipMask, XSetClipOrigin, XSet-
ClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
398 July 26, 1988
mXlib - Graphics Context
XSetBackground
Name
XSetBackground m set the background pixel value in a graphics context.
Synopsis
XSetBackground (display, go, background)
Display *display;
GC gc ;
unsigned long background;
Arguments
di spl ay
gc
background
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the graphics context.
Specifies the background you want to set for the specified graphics context.
Description
XSetBackground sets the background pixel value for graphics requests. Note that this
is different from the background of a window, which can be set with either XSetWindow-
Background or XSetWindowBackgroundPixmap.
Errors
BadAlloc
BadGC
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple,
XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSet-
FillRule, XSetFillStyle, XSetForeground, XSetFunction, XSetGraphics-
Exposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClip-
Rectangles, XSetState, XSetSubwindowMode, DefaultGC-
July 26, 1988
399
mXlib - Graphics Context
XSetClipMask
Name
XSetClipMask -- set clip_mask pixmap in a graphics context.
Synopsis
XSetClipMask (display, gc, clip__mask)
Display *display;
GC gc ;
Pixmap clip_mask ;
Arguments
di spl ay
gc
clip_mask
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the graphics context.
Specifies a pixmap of depth 1 to be used as the clip mask Pass the constant
None if no clipping is desired.
Description
XSetClipMask sets the clip_mask member of a GC to a pixmap. The clip mask
--
filters which pixels in the destination are drawn. If clip_mask is set to None, the pixels arc
always drawn, regardless of the clip origin. Use XSetClipRectangles to set
clip_mask to a set of rectangles, or XSetRegion tO set clip_mask to a region.
For more information, see Volume One, Chapter 5, The Graphics Context.
Errors
BadAlloc
BadGe
BadMatch
BadValue
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple,
XSetTOrigin, XSetPlaheMask, XSetDashes, XSetLineAttributes, XSet-
FillRule, XSetFillStyle, XSetForeground, XSetBackground, XSet-
Function, XSetGraphicsExposures, XSetArcMode, XSetClipOrigin, XSet-
ClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
July 26, 1988 401
XSetClipOrigin
Xlib - Graphics Context m
Name
XSetClipOrigin -- set the clip origin in a graphics context.
Synopsis
XSetClipOrigin (display, gc, clip x origin,
Display *display;
GC gc ;
int clip x origin, clip_y_origin;
clip_y_origin )
Arguments
di splay
gc
clip x origin
clip_y_origin
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the graphics context.
Specify the coordinates of the clip origin relative to the window
specified in the GC.
Description
XSetClipOrigin se the clip x origin and clip_y_origin members of the GC.
The clip origin controls the position of the clip_mask hl the GC, which filters which pixels
in the destination are drawn.
For more information, see Volume One, Chapter 5, The Graphics Context.
Errors
BadAlloc
BadGC
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple,
XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSet-
FillRule, XSetFillStyle, XSetForeground, XSetBackground, XSet-
Function, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClip-
Rectangles, XSetState, XSetSubwindowMode, DefaultGC.
402 July26 1988
XSetCli p Recta ng les (continued) Xlib - Grap h ics Context
To cancel the effect of this command, so that there is no clipping, pass None as the
clip_mask in XChangeGC or XSetClipMask.
For more information, see Volume One, Chapter 5, The Graphics Context.
Structures
typedef struct {
short x, y;
unsigned short width, height;
} XRectangle;
Errors
BadAlloc
BadGC
BadMatch
BadValue
Incorrect ordering (error message sewer-dependent).
Related Commands
XChangeGC, XCopyGC, XCreateGC, XF reeGC, XGContextF romGC, XSet St ipple,
XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSet-
FillRule, XSetFillStyle, XSetForeground, XSetBackground, XSet-
Function, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClip-
Origin, XSetState, XSetSubwindowMode, DefaultGC.
404 July 26, 1988
mXlib - Client Connections
X SetC I o se Down Mo de
Name
XSetCloseDownModechange eclosedown mode ofacfient.
Synopsis
XSetCloseDownMode(display, close mode)
--
Display *display;
int close mode;
--
Arguments
display
Specifies a pointer to the Display structu; retumed om XOpen-
Display.
close mode
--
Specifiestheclientclosedown mode you want. Passone of theseconsmnts:
DestroyAll, RetainPermanent, orRetainTemporary.
Description
XSetCloseDownMode defines what will happen to the client's resources at connection
close. A connection between a client and the server starts in DestroyAll mode, and all
resources associated with that connection will be freed when the client process dies. If the
close down mode is RetainTemporary or RetainPermanent when the client dies, its
resources live on until a call to XKillClient. The resource argument of XKill-
Client can be used to specify which client to kill, or it may be the constant All-
Temporary, in which case XKillClient kills all resources of all clients that have ter-
minated in RetainTemporary mode.
One use of RetainTemporary or RetainPermanent might be to allow an application to
recover from a failure of the network connection to the display server. After restarting, the
application would need to be able to identify its own resources and reclaim control of them.
Errors
BadValue
Related Commands
XKillClient
July 26, 1988 405
XSetCommand
Xlib - Window Manager Hints--
Name
XSetCommand -- set the XA_WM_COMMAND atom (command line arguments).
Synopsis
XSetCommand ( display,
Display *display;
Window w;
char **argv;
int argc ;
w, argv, argc)
Arguments
display
argv
a rgc
Description
Specifies a pointer to the Display sucture; returned from XOpenDisplay.
Specifies the ID of the window whose atom is to be set.
Specifies a pointer to the command and arguments used to start the application.
The application is an army of pointers to null-terminated strings.
Specifies the number of arguments.
XSetCommand is used by the application to set the XA_WM_COMMAND property for the win-
dow manager with the UNIX shell command and its arguments used to invoke the application.
Use this command only if not calling xSet St anda rdP rope rt ie s.
Errors
BadAlloc
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGet-
WMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints,
XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetch-
Name, XGetIconName, XSetIconName, XStoreName, XGetIconSizes, XSetIcon-
Sizes.
406 July 26, 1988
XSetDashes (continued) Xlib - Graphics Context
Description
XSetDashes sets the dashes member of the GC. The initial and alternating elements of
the dash_list are the dashes, the others are the gaps. All of the elements must be nonzero.
The dash_offset defines the phase of the pattern, specifying how many pixels into the
dash_list the pattern should actually begin in the line drawn by the request.
n specifies the length of dash list. An odd value for n is interpreted as specifying the
--
dash_list concatenated with itself to produce twice as long a list.
The unit of measure for dashes is the same as in the ordinary coordinate system. Ideally, a
dash length is measured along the slope of the line, but server implementors are only required
to match this ideal for horizontal and vertical lines. Failing the ideal semantics, it is suggested
that the length be measured along the major axis of the line. The major axis is defined as the
x axis for lines drawn at an angle of between -45 and +45 degrees or between 315 and 225
degrees from the x axis. For all other lines, the major axis is the y axis.
See Volume One, Chapter 5, The Graphics Context, for further information.
Errors
BadAlloc
BadGC
BadValue
No values in dash list.
--
Element in dash list is 0.
--
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple,
XSetTSOrigin, XSetPlaneMask, XSetLineAttributes, XSetFillRule, XSet-
FillStyle, XSetForeground, XSetBackground, XSetFunction, XSet-
GraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSet-
ClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
408 July 26, 1988
mXlib - Error Handling
XSetErrorHandler
Name
XSetErrorHandler -- set a nonfatal error event handler.
Synopsis
XSetErrorHandler (handler)
int (* handler) (Display *, XErrorEvent *)
Arguments
handler
The user-defined function to be called to handle error events. If a NULL
pointer, reinvoke the default handler, which prints a message and exits.
Description
The error handler function specified in handler will be called by Xlib whenever an XError
event is received. These are nonfatal conditions, such as unexpected values for arguments. It
is acceptable for this procedure to return, though the default handler simply prints a message
and exits. However, the error handler should NOT perform any operations (directly or
indirectly) on the Display.
The function is called with two arguments, the display variable and a pointer to the XError-
Event structure. Here is a trivial example of a user-defined error handler:
int myhandler (display, myerr)
Display *display;
XErrorEvent *myerr;
char msg[80];
XGetErrorText (display, myerr->error_code, msg, 80) ;
fprintf(stderr, "Error code %s\n", msg) ;
}
This is how the example roufne wod be used in XSetErrorHandler.
XSetErrorHandler (myhandler) ;
Note that XSetErrorHandler is one of the few routines that does not require a display
argument. The routine that calls the error handler gets the display variable from the XError-
Event structure.
The error handler is not called on BadNarae errors from OpenFont, LookupColor,
AllocNamedColor, protocol requests, on BadFont errors from a QueryFont protocol
request, or on BadAlloc or BadAccess errors. These errors are all indicated by a 0 return
value in the corresponding Xlib routines, and can be caught and handled by the application.
Use XIOErrorHandler to to provide a handler for fatal errors.
In the XErrorEvent structure shown below, the serial member is the number of requests
(starting from 1) sent over the network connection since it was opened. It is the number that
was the value of the request sequence number immediately after the failing call was made.
The request_code member is a protocol representation of the name of the procedure that
failed and is defined in <Xll/X.h>.
Xlib Reference Manual 409
XSetErrorHandler (continued) Xlib- Error Handling
For more information, see Volume One, Chapter 3, Basic Window Program.
Structures
typedef struct {
int type
Display *display;
unsigned long serial;
char error code;
--
char request_code;
char minor code;
--
XID resourceid;
} XErrorEvent ;
/* display the event was read from */
/* serial number of failed request */
/* error code of failed request */
/* major opcode of failed request */
/* minor opcode of failed request */
/* resource ID */
Related Commands
XDisplayName, XGetErrorDatabaseText, XGetErrorText, XSetIOError-
Handler, XSynchronize, XSetAfterFunction.
410 July 26, 1988
--Xlib - Graphics Context
XSetFillRule
Name
XSetFillRule -- set the fill rule in a graphics context.
Synopsis
XSetFillRule (display, gc, fill rule)
--
Display *display;
GC gc ;
int fill rule;
--
Arguments
di spl ay
gc
fill rule
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the graphics context.
Specifies the fill rule you want to set for the specified graphics context. Pos-
sible values are EvenOddRule or WindingRule.
Description
XSetFillRule sets the fill rule member of a GC. The fill rule member of the
--
--
GC determines what pixels are drawn in XFillPolygon requests. Simply put, Winding-
Rule fills overlapping areas of the polygon, while EvenOddRule does not fill areas that
overlap an odd number of times. Technically, EvenOddRule means that the point is drawn
if an arbiary ray drawn from the point would cross the path determined by the request an odd
number of times. WindingRule indicates that a point is drawn if a point crosses an unequal
number of clockwise and counterclockwise path segments, as seen from the point.
EvenOddRule
Outline of polygon
to fill
WindingRule
July 26, 1988 411
XSetFillRule (continued) Xlib - Graphics Context
A clockwise-directed path segment is one which crosses the ray from left to right as observed
from the point. A counterclockwise segment is one which crosses the ray from right to left as
observed from the point. The case where a directed line segment is coincident with the ray is
uninteresting because you can simply choose a different ray that is not coincident with a seg-
ment.
All calculations are performed on infinitely small points, so that if any point within a pixel is
considered inside, the entire pixel is drawn. Pixels with centers exactly on boundaries are con-
sidered inside only if the filled area is to the right, except that on horizontal boundaries, the
pixel is considered inside only if the filled area is below the pixel.
See Volume One, Chapter 5, The Graphics Context, for more information.
Errors
BadAlloc
BadGC
BadValue
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple,
XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSet-
FillStyle, XSetForeground, XSetBackground, XSetFunction, XSet-
GraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSet-
ClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
412 July 26, 1988
XSetFillStyle (continued) Xlib - Grap h ics Context
Errors
BadAlloc
BadGC
BadValue
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple,
XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSet-
FillRule, XSetForeground, XSetBackground, XSetFunction, XSetGraphics-
Exposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClip-
Rectangles, XSetState, XSetSubwindowMode, DefaultGC.
414 July 26, 1988
mXlib- Fonts
XSetFont
Name
XSetFont B set the current font in a graphics contexL
Synopsis
XSetFont (display, gc, font)
Display *display;
GC gc ;
Font font ;
Arguments
display
gc
fon t
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the graphics context.
Specifies the ID of the font to be used.
XSetFont sets the font in the GC. Text drawing requests using this GC will use this font
only if it is loaded. Otherwise, the text will not be drawn.
For more information, see Volume One, Chapter 5, The Graphics Context.
Errors
BadAlloc
BadFont
BadGC
Related Commands
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts,
XListFontsWithInfo, XFreeFontNames, XFreeFontPath, XGetFontPath,
XQueryFont, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFont-
Cursor.
July 26, 1988 415
XSetFontPath
Xlib- Fonts--
Name
XSetFontPath -- set the font search path.
Synopsis
XSetFontPath (display, directories, ndirs )
Display *display;
char **directories;
int ndirs ;
Arguments
display Specifies a pointer to the Display structure; returned from XOpen-
Display.
directories Specifies the directory path used to look for the font. Setting the path to the
empty list restores the default path defined for the X server.
ndirs Specifies the number of directories in the path.
Description
XSetFontPath defines the directory search path for font lookup for all clients. Therefore
the user should construct a new directory search path carefully by adding to the old directory
search path obtained by XGetFontPath. Passing an invalid path can result in preventing
the server from accessing any fonts. Also avoid restoring the default path, since some other
client may have changed the path on purpose.
The interpretation of the strings is operating system dependent, but they are intended to
specify directories to be searched in the order listed. Also, the contents of these strings are
operating system specific and are not intended to be used by client applications.
As a side-effect of executing this request, the server is guaranteed to flush all cached informa-
tion about fonts for which there are currently no explicit resource IDs allocated. The meaning
of errors from this request is system specific.
E rro rs
BadValue
Related Commands
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts,
XListFontsWithInfo, XFreeFontNames, XFreeFontPath, XGetFontPath,
XQueryFont, XSetFont, XUnloadFont, XGetFontProperty, XCreateFont-
Cursor.
416 July 26, 1988
mXlib - Graphics Context
XSetForeground
Name
XSeogroundmsetthe groundpixelvaluein a graphicscontext.
Synopsis
XSetForeground(display, gc, foreground)
Display *display;
GC gc;
unsigned long foreground;
Arguments
display
gc
foreground
Specifies a pointer to e Display sucture; returned from XOpen-
Display.
Specifies the graphics context.
Specifies the foreground pixel value you want for the specified graphics con-
text.
Description
XSetForeground sets the foreground member in a GC. This pixel value is used for sct
bits in the source according to the fill_style.
See Volume One, Chapter 5, The Graphics Context, for more information on the GC.
Errors
BadAlloc
BadGC
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple,
XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSet-
FillRule, XSetFillStyle, XSetBackground, XSetFunction, XSetGraphics-
Exposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClip-
Rectangles, XSetState, XSetSubwindowMode, DefaultGC.
July 26, 1988 417
Xlib - Graphics Context (continued) XSetFunction
Errors
BadAlloc
BadGC
BadValue
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple,
XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSet-
FillRule, XSetFillStyle, XSetForeground, XSetBackground, XSet-
GraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSet-
ClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
July 26, 1988 419
XSetGraphicsExposures
Xlib - Graphics Context--
Name
XSetGraphicsExposures m set 9 r aphic s_expo s u re s in a graphics context.
Synopsis
XSetGraphicsExposures (display, go, graphics_exposures)
Display *display;
GC gc ;
Bool graphics_exposures ;
Arguments
display
gc
Specifies a pointer to the Display structure; returned from XOpenDisplay.
Specifies the graphics context.
graphi cs_exposures
Specifies whether you want GraphicsExpose and NoExpose events when
calling XCopyArea and xCopyPlane with this graphics context.
Description
XSetGraphicsExposure sets the graphics__exposures member of the GC. If
graphics_exposures is True, GraphicsExpose events will be generated when
XCopyArea and xCopyPlane requests cannot be completely satisfied because a source
region is obscured, and NoExpose events are generated when they can be completely
satisfied. If graphics_exposures is False, these events are not generated.
These events are not selected in the normal way with XSelectTnput. Setting the
9raphics_exposures member of the GC used in the CopyArea or CopyPlane request
is the only way to select these events.
For more information, see Volume One, Chapter 5, The Graphics Context.
Errors
BadAlloc
BadGC
BadValue
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple,
XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSet-
FillRule, XSetFillStyle, XSetForeground, XSetBackground, XSet-
Function, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClip-
Rectangles, XSetState, XSetSubwindowMode, DefaultGC.
420 July 26, 1988
mXlib - Window Manager Hints
XSetlconName
Name
XSetIconName m set the name to be displayed in a window's icon.
Synopsis
XSetIconName(display,
Display *display;
Window w;
char *icon name;
--
w, icon name)
--
Arguments
display
W
icon name
Specifies a pointer to the Display structu'e; returned from XOpen-
Display.
Specifies the ID of the window whose icon name is being set.
Specifies the name to be displayed in the window's icon. The name should
be a null-terminated string. This name is returned by any subsequent call to
XGet I c onName.
Description
XSetIconName sets the XA_WM_ICON__NAME property for a window. This is usually set
by an application for the window manager. The name should be short, since it is to be
displayed in association with an icon.
XSetStandardProperties also sets this property.
For more information, see Volume One, Chapter 10, lnterclient Communication.
Errors
BadAlloc
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGet-
WMHiAts, XSetWMHintsXGetZoomHints, XSetZoomHints, XGetNormalHints,
XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetch-
Name, XGetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSet-
Command.
July 26, 1988 421
XSetlconSizes
Xlib - Window Manager Hints m
Name
XSetlconSizes -- set the value of the XA WM ICON_SIZE property.
Synopsis
XSetIconSizes (display, w,
Display *display;
Window w;
XIconSize *size list;
int count ;
size list, count)
Arguments
display
size list
--
count
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the ID of the window whose icon size property is to be set. Nor-
mally the root window.
Specifies a pointer to the size list.
Specifies the number of items in the size list.
XSetIconSizes is normally used by a window manager to set the range of preferred icon
sizes in the XA_e_TCON_S T ZE property of the root window.
Applications can then read the property with XGetIconSizes.
Structures
typedef struct {
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
} XIconSize;
E rro rs
BaclAIIoc
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGet-
WMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints,
XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetch-
Name, XGetIconName, XSetIconName, XStoreName, XGeticonSizes, XSet-
Command.
422 July 26, 1988
XSetlnputFocus (continued) Xlib - Input Handling
If the focus window later becomes not viewable, XSetInputFocus
revert to argument to determine the new focus window:
evaluates the
If you assign RevertToParent, the focus reverts to the parent (or the closest view-
able ancestor) automatically with a new revert_to argument of RevertToName.
If you assign RevertToPointerRoot or RevertToNone, the focus reverts to that
value automatically. FocusIn and FocusOut events are generated when the focus
reverts, but the last_focus_change_t ime is not affected.
Errors
BadMatch
BadValue
BadWindow
focus window not viewable when xSet InputFocus called.
Related Commands
XSelectInput, XGetInputFocus, XWindowEvent, XCheckWindowEvent,
XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMask-
Event, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents,
XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent,
XPending, XSynchronize, XSendEvent, QLength.
424 July26, 1988
mXlib - Error Handling
XSetlOErrorHandler
Name
XSetIOErrorHandler- handle fatal I/0 errors.
Synopsis
XSet IOErrorHandler (handler)
int (*handler) (Display *) ;
Arguments
handler Specifies a pointer to a user-defined fatal error handling routine. If NULL,
reinvoke the default fatal error handler.
Description
XSetIOErrorHandler specifies a user-defined error handling routine for fatal errors. This
error handler will be called by Xlib if any sort of system call error occurs, such as the connec-
tion to the server being lost. The called routine should not return. If the I/O error handler
does return, the client process will exit.
If handler is a NULL pointer, the default error handler is reinvoked. The default I/O error
handler prints an error message and exits.
For more information, see Volume One, Chapter 3, Basic Window Program.
Related Commands
XDisplayName, XGetErrorDatabaseText, XGetErrorText, XSetError-
Handler, XSynchronize, XSetAfterFunction.
July 26, 1988 425
Xlib - Graphics Context (continued) XSetLineAttributes
line width
--
line_style
cap_style
join_style
Specifies the line width you want to set for the specified graphics context.
Specifies the line style you want to set for the specified graphics context.
Possible values are LineSolid, LineOnOffDash, or LineDouble-
Dash.
Specifies the line and cap style you want to set for the specified graphics
context. Possible values are CapNotLast, CapButt, CapRound, or
CapPro jecting.
Specifies the line-join style you want to set for the specified graphics con-
text. Possible values are JoinMiter, JoinRound, or JoinBevel.
Description
XSetLineAttributes se four types of line characteristics in the GC: line_width,
line_style, cap_style, and join_style.
See the description of line and join styles in Volume One, Chapter 5, The Graphics Context.
See also XSetDashes.
A line_width of zero (0) means to use the fastest algorithm for drawing a line of one pixel
width. These lines may not meet properly with lines specified as width 1 or more.
Errors
BadGC
BadValue
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple,
XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetFillRule, XSetFillStyle,
XSetForeground, XSetBackground, XSetFunction, XSetGraphicsExposures,
XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSet-
State, XSetSubwindowMode, DefaultGC.
July 26, 1988 427
XSetModifierMapping
Xlib - Keyboard
Name
XSetModifierMapping -- set keycodes to be used as modifiers (Shift, Control, etc.).
Synopsis
int XSetModifierMapping ( display, mod_map)
Display *display;
XModifierKeymap *mod_map ;
Arguments
display Specifies a pointer to the Display structure; returned from XOpenDisplay.
mod_map Specifies a pointer to the XModifierKeymap structure.
Description
XSetModifierMapping is one of two ways to specify the keycodes of the keys that are to
be used as modifiers (like Shift, Control, etc.). XSetModifierMapping specifies all the
keycodes for all the modifiers at once. The other, easier, way is to use XInsert-
ModifiermapEntry and XDeleteModifiermapEntry, which add or delete a single
keycode for a single modifier key. XSetModifierMapping does the work in a single call,
but the price of this call is that you need to manually set up the XModifierKeymap struc-
ture pointed to by mod_map. This requires you to know how the XModifierKeymap struc-
ture is defined and organized, as described in the next three paragraphs.
The XModifierKeymap structure for the rood_map argument should be created using
XNewModifierMap or XGetModifierMapping. The max_keypermod element of the
structure specifies the maximum number of keycodes that can be mapped to each modifier.
You define this number but there may be an upper limit on a particular server.
The modifiermap element of the structure is an array of keycodes. There are eight by
max__keypermod keycodes in this array: eight because there are eight modifiers, and
max_keypermod because that is the number of keycodes that must be reserved for each
modifier.
The eight modifiers are represented by the constants ShiftMapIndex, LockMapIndex,
ControlMapIndex, ModlMapIndex, ModlMapIndex, Mod3MapIndex, Mod4Map-
Index, and Mod5MapIndex. These are not actually used as arguments, but they are con-
venient for referring to each row in the modifiermap structure while filling it. The
definitions of these constants are shown in the Structures section below.
Now you can interpret the modifiermap array. For each modifier in a given modifier-
map, the keycodes which correspond are from modifiermap [index *
max_keypermod] to modifiermap[ [ (index + i) * max_keyspermod] -i]
where index is the appropriate modifier index definition (ShiftMapIndex, LockMap-
Index, etc.). You must set the rood_map array up properly before calling XSetModifier-
Mapping. Now you know why XInsertModifierMapEntry and XDelete-
ModifierMapEntry were created!
Zero keycodes are ignored. No keycode may appear twice anywhere in the map (otherwise, a
BadVa lue error is generated). In addition, all of the nonzero keycodes must be in the range
428 Xhb Reference Manual
Xlib- Keyboard (continued) XSetModifierMapping
specified by min_keycode and max_keycode in the Display structure (otherwise a
BadValue error occurs).
A server can impose reslrictions on how modifiers can be changed. For example, certain keys
may not generate up transitions in hardware, or multiple modifier keys may not be supported.
If a restriction is violated, then the status reply is MappingFailed, and none of the
modifiers are changed.
If the new keycodes specified for a modifier differ from those currently defined and any
(current or new) keys for that modifier are in the down state, then the status reply is
MappingBusy, and none of the modifiers are changed.
XSetModifierMapping generates a MappingNotify event on a MappingSuccess
status.
A value of 0 for raodifiermap indicates that no keys are valid as any modifier.
Structures
typedef struct {
int max_keypermod;
KeyCode *modifiermap;
} XModifierKeymap;
/* server's max # of keys per modifier */
/* an 8 by max_keypermod array */
/* modifier names. Used to build a SetModifierMapping request or
to read a GetModifierMapping request. These correspond to the
masks defined above. */
#define ShiftMapIndex 0
#define LockMapIndex 1
#define ControlMapIndex 2
#define ModlMapIndex 3
#define Mod2MapIndex 4
#define Mod3MapIndex 5
#define Mod4MapIndex 6
#define Mod5MapIndex 7
Errors
BadAlloc
BadValue
Keycode appears twice the map.
Keycode < display->min_keycode or
keycode > displ ay->max_keycode.
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap,
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifier-
Map, XQueryKeymap, XStringToKeysyn%XLookupKeysym, XRebindKeysym,
XGetKeyboardMapping, XChangeKeyboardMapping, XRefreshKeyboard-
Mapping, XLookupString, XGetModifierMapping, XInsertModifiermap-
Entry, XDeleteModifiermapEntry.
July 26, 1988 429
XSetNormalHints
Xlib - Window Manager Hints--
Name
XSetNormalHints -- set the size hints property of a window in normal state (not zoomed or
iconified).
Synopsis
void XSetNormalHints(display,
Display *display;
Window w;
XSizeHints *hints;
w, hints)
Arguments
display
w
hints
Description
Specifies a pointer to the Display structure; returned from X0pen-
Display.
Specifies the window ID.
Specifies a pointer to the sizing hints for the window in its normal state.
XSetNormalHints sets the XA_WM_NORMAL_HINTS property for the specified window.
Applications use XSetNormalHints tO inform the window manager of the size or position
desirable for that window. In addition, an application wanting to move or resize itself should
call XSetNormalHints specifying its new desired location and size, in addition to making
direct X calls to move or resize. This is because some window managers may redirect win-
dow configuration requests, but ignore the resulting events and pay attention to property
changes instead.
To set size hints, an application must not only assign values to the appropriate elements in the
hints structure, but also must set the flags field of the structure to indicate which members
have assigned values and the source of the assignment. These flags are listed in the Structures
section below.
For more information on using hints, see Volume One, Chapter 10, Interclient Communica-
tion.
Structures
typedef struct {
long flags; /* which fields in structure are defined */
int x, y;
int width, height;
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
st ruct {
int x; /* numerator */
int y; /* denominator */
} rain_aspect, max_aspect ;
} XSizeHints;
430 July 26, 1988
Xlib - Window Manager Hints (continued) XSetNormalHints
/* flag argument in size hints */
#define USPosition (IL << 0) /* user specified x, y */
#define USSize (IL << I) /* user specified width, height */
#define PPosition (IL << 2) /* program specified
#define PSize (IL << 3) /* program specified
#define PMinSize (IL << 4) /* program specified
#define PMaxSize (IL << 5) /* program specified
#define PResizeInc (IL << 6) /* program specified
#define PAspect (IL << 7) /* program specified
#define PAllHints
position */
size */
minimum size */
maximum size */
resize increments */
min/max aspect ratios */
(PPositionlPSizelPMinSizelPMaxSizelPResizeInclPAspect)
Errors
BadAlloc
BadWindow
Reled Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGet-
WMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints,
XGetTransientForHint, XSetTransientForHint, XFetchName, XGetIcon-
Name, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSet-
Command.
July 26, 1988 431
XSetPlaneMask
Xlib - Graphics Context m
Name
XSelaneMaskmsettheplane maskinagraphicsconxt.
Synopsis
XSetPlaneMask(display, gc, plane_mask)
Display *display;
GC gc;
unsigned long plane_mask;
Arguments
display
go
plane_mask
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the graphics context.
Specifies the plane mask. You can use the macro AllPlanes if desired.
Description
XSetPlaneMask se the plane_mask member of the specified GC. The plane_mask
determines which planes of the destination drawable are affected by a graphics request.
For more information, see Volume One, Chapter 5, The Graphics Context.
Errors
BadAlloc
BadGC
Relined Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple,
XSetTSOrigin, XSetDashes, XSetLineAttributes, XSetFillRule, XSetFill-
Style, XSetForeground, XSetBackground, XSetFunction, XSetGraphics-
Exposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClip-
Rectangles, XSetState, XSetSubwindowMode, DefaultGC.
432 July26, 1988
mXlib- Pointer
XSetPointerMapping
Name
XSetPointerMapping -- set the pointer button mapping.
Synopsis
int XSetPointerMapping(display, map, nmap)
Display *display;
unsigned char map[];
int nmap;
Arguments
display
map
nmap
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the mapping list.
Specifies the number of items in the mapping list.
XSetPointerMapping se the mapping of the pointer. Elemen of the map list are
indexed starting from 1. The length of the list nmap must be the same as XGetPointer-
Mapping returns (you must call that first). The index is a physical button number, and the
element of the list defines the effective button number. In other words, if map [ 2 ] is set to 1,
when the second physical button is pressed, a ButtonPress event will be generated if
ButtonlMask was selected but not if Button2Mask was selected. The button member
in the event will read Buttonl.
No two elements can have the same nonzero value. A value of 0 for an element of map dis-
ables a button, and values for elements are not restricted in value by the number of physical
buttons. If any of the buttons to be altered are currently in the down state, the status reply is
MappingBusy and the mapping is not changed.
This function returns either MappingSuccess or MappingBusy. XSetPointer-
Mapping generates a MappingNotify event on a status of MappingSuccess.
Errors
BadValue
Two elemems of map [ ] have same nonzero value.
nmap not equal to XGetPointerMapping return value.
Related Commands
XQueryPointer, XWarpPointer, XGrabPointer, XChangeActivePointerGrab,
XUngrabPointer, XGetPointerMapping, XGetPointerControl, XChange-
PointerControl.
July 26, 1988 433
XSetRegion
Xlib - Regions--
Name
XSetRegion -- set c i ip_ma s k of the graphics context to the specified region.
Synopsis
XSetRegion ( display, gc, r)
Display *display;
GC gc ;
Region r;
Arguments
display
gc
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the graphics context.
Specifies the region.
Description
XSetRegion sets the clip_mask of the GC to the specified region. Thereafter, all output
requests made with gc will be confined to the region.
Regions are located using an offset from a point (the region origin) which is common to all
regions. It is up to the application to interpret the location of the region relative to a drawable.
When the region is to be used as a clip_mask by calling XSetRegion, the upper-left
corner of region relative to the drawable used in the graphics request will be at (xoffset +
clip x origin, yoffset + clip_y_origin), where xoffset and yoffset are
the offset of the region and clip x origin and clip_y_origin are elements of the GC
used in the graphics request.
For more information on regions, see Volume One: Chapter 5, The Graphics Context; and
Chapter 6, Drawing Graphics and Text.
Structures
/.
* opaque reference to Regiondata type.
* user won't need contents, only pointer.
*/
typedef struct _XRegion *Region;
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion,
XShrinkRegion, XRectInRegion, XPolygonRegion, XPointInRegion,
XOffsetRegion, XIntersectRegion, XEmptyRegion, XCreateRegion,
XDestroyRegion, XEqualRegion, XClipBox.
434 July 26, 1988
XSetScreenSaver (continued) Xlib - Screen Saver
Errors
BadValue timeout <-|.
Related Commands
XForceScreenSaver, XActivateScreenSaver, XResetScreenSaver, XGet-
ScreenSaver.
436 July 26, 1988
--Xlib - Selections
XSetSelectionOwner
Name
XSetSelectionOwner -- set the owner of a selection.
Synopsis
XSetSelectionOwner (display, selection, owner, time)
Display *display;
Atom selection;
Window owner;
Time time ;
Arguments
display
selection
owner
time
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the selection atom. Predefined atoms are XA PRIMARY and
XA SECONDARY.
Specifies the present owner of the specified selection atom. This value is
either a window ID or None.
Specifies the time when the grab should take place. Pass either a timesmmp,
expressed in milliseconds, or the constant CurrentTime.
XSetSelectionOwner sets the owner and last-change time of a selection property. This
should be called by an application that supports cutting and pasting between windows (or at
least cutting), when the user has made a selection of any kind of text, graphics, or data. This
makes the information available so that other applications can request the data from the new
selection owner using XConvertSelection, which generates a SelectionRequest
event specifying the desired type and format of the data. Then the selection owner sends a
SelectionNotify using XSendEvent, which notes that the information is stored in the
selection property in the desired format or indicates that it couldn't do the conversion to the
desired type.
If owner is specified as None, then the new owner of the selection is None. Otherwise, the
new offner is the client executing the request.
If the new owner is not the same as the current owner of the selection, and the current owner
is a window, then the current owner is sent a SelectionClear event. This indicates to
that window that the selection should be unhighlighted.
If the selection owner window is later destroyed, the owner of the selection automatically
reverts to None.
The value you pass to the time argument must be no earlier than the last-change time of the
specified selection, and no later than the current time, or the selection is not affected. The new
last-change time recorded is the specified time, with CurrentTirne replaced by the current
server time. If the X server reverts a selection owner to None, the last-change time is not
affected.
July 26, 1988 437
XSetSelectionOwner (continued) Xlib - Selections
For more information on selections, see Volume One, Chapter 10, lnterclient Communication.
Errors
BadAtom
BadWindow
Related Commands
XGet Select ionOwne r, XConve rt Select ion.
438 July 26, 1988
XSetSizeHints (continued) Xlib - Window Manager Hints
#define PSize (IL << 3)/* program specified size */
#define PMinSize (IL << 4)/* program specified minimum size */
#define PMaxSize (IL << 5)/* program specified maximum size */
#define PResizeInc (IL << 6)/* program specified resize increments */
#define PAspect (IL << 7)/* program specified min/max aspect ratios */
#define PAllHints (PPositionlPSizelPMinSizelPMaxSizelPResizeInclPAspect)
Errors
BadAlloc
BadAtom
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XGetWMHints, XSet-
WMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, XSetNormal-
Hints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGet-
IconName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes,
XSetCommand.
440 July 26, 1988
XSetStandardColormap (continued) Xlib - Colormaps
Errors
BadAlloc
BadAtom
BadWindow
Structures
typedef struct {
Colormap colormap;
unslgned long red max;
--
unslgned long red mult;
--
unslgned long green_max;
unsigned long green_mult;
unsigned long blue max;
--
unsigned long blue mult;
--
unsigned long base_pixel;
} XStandardColormap;
/* ID of colormap made by XCreateColormap */
Related Commands
XCopyColormapAndFree, XCreateColormap, XFreeColormap, XGetStandard-
Colormap, XInstallColormap, XUninstallColormap, XListInstalled-
Colormaps, XSetWindowColormap, DefaultColormap, DisplayCells.
442 July 26, 1988
XSetStandardProperties (continued) Xlib- Properties
int x; /* numerator */
int y; /* denominator */
} min_aspect, max_aspect;
} XSizeHints;
/* flags argument in size hints */
#define USPosition (IL << 0)/* user specified x, y */
#define USSize (IL << I)/* user specified width, height */
#define PPosition (IL << 2)/* program specified position */
#define PSize (IL << 3)/* program specified size */
#define PMinSize (IL << 4)/* program specified minimum size */
#define PMaxSize (IL << 5)/* program specified maximum size */
#define PResizeInc (IL << 6)/* program specified resize increments */
#define PAspect (IL << 7)/* program specified min and max aspect ratios */
#define PAllHints (PPositionlPSizelPMinSizelPMaxSizelPResizeInclPAspect)
Errors
BadAlloc
BadWindow
Related Commands
XGetFontProperty, XRotateWindowProperties, XDeleteProperty, XChange-
Property, XGetWindowProperty, XListProperties, XGetAtomName, XIntern-
Atom.
444 July 26, 1988
XSetStipple k
Xlib - Graphics Context--
Name
XSetStipple -- set the stipple in a graphics context.
Synopsis
XSetStipple (display, gc, stipple)
Display *display;
GC gc ;
P ixmap stipple;
Arguments
display
gc
stipple
Specifies a pointer to the Display sucture; returned from XOpenDisplay.
Specifies the graphics context.
Specifies the stipple you want to set for the specified graphics context.
Description
xsetstipple sets the stipple member of the GC. The stipple is a pixmap of depth
1. It is laid out like a tile. Set bits in the stipple determine which pixels in an area are drawn
in the foreground pixel value. Unset bits in the stipple determine which pixels are drawn
in the background pixel value if the fill_style is FillOpaqueStippled. If
fill_style is FillStippled, pixels overlayed with unset bits in the stipple are not
drawn. If fill_style is FillTiled or FillSolid, the stipple is not used.
For more information, see Volume One, Chapter 5, The Graphics Context.
Errors
BadAlloc
BadGC
BadMatch
BadP ixmap
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetTSOrigin,
XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillRule, XSet-
FillStyle, XSetForeground, XSetBackground, XSetFunction, XSet-
GraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSet-
ClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
446 July 26, 1988
--Xlib - Graphics Context
X SetSu bwi ndow Mode
Name
XSetSubwindowMode -- set the subwindow mode in a graphics context.
Synopsis
XSetSubwindowMode ( display, gc, subwindow mode)
Display *display;
GC gc;
int subwindow mode ;
Arguments
di spl ay
Specifies a pointer to the Display structure; returned from XOpenDisplay.
gc
Specifies the graphics context.
subwindow mode
Specifies the subwindow mode you want to set for the specified graphics con-
text Possible values are ClipByChildren or IncludeInferiors.
Description
XSetSubwindowMode sets the subwindow mode member of the GC. Clip-
ByChildren means that graphics requests will be clipped by all viewable children.
IncludeInferiors means draw through all subwindows.
For more information, see Volume One, Chapter 5, The Graphics Context.
Errors
BadAlloc
BadGC
BadValue
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple,
XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSet-
FillRule, XSetFillStyle, XSetForeground, XSetBackground, XSet-
Functlon, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClip-
Origin, XSetClipRectangles, XSetState, DefaultGC.
July 26, 1988 44 7
XSetTile
Xlib - Pixmaps and Tiles--
Name
XSetTile -- set the fill tile in a graphics context.
Synopsis
XSetTile (display, gc, tile)
Display *display;
GC gc;
Pixmap tile ;
Arguments
display
gc
tile
Specifics a pointer to the Display sUmcturc; returned from XOpenDisplay.
Specifies the graphics context.
Specifies the desired tile for the specified graphics context.
Description
XSetTile sets the tile member of the GC. This member of the GC determines the pix-
map used to tile areas. The tile must have the same depth as the destination drawable.
For more information, see Volume One, Chapter 5, The Graphics Context.
Errors
BadAlloc
BadGC
BadMatch
BadP ixmap
Related Commands
XQueryBestTile, XSetWindowBorderPixmap, XSetWindowBackgroundPixmap,
XCreatePixmap, XCreatePixmapFromBitmapData, XFreePixmap, XQueryBest-
Size, XQueryBestStipple, XWriteBitmapFile, XReadBitmapFile, XCreate-
BitmapFromData.
448 July 26, 1988
--Xlib - Window Attributes
XSetWindowBackground
Name
XSetWindowBackground--tthebackgroundpixelatbuteofa window.
Synopsis
XSetWindowBackground(display, w, background_pixel)
Display *display;
Window w;
unsigned long background_pixel;
Arguments
display Specifies a pointer to the Display structure; returned from XOpenDisplay.
w Specifies the window ID. Must be an InputOutput window.
background_pixel
Specifies which entry in the colormap is used as the background.
Description
XSetWindowBackground sets the background attribute of a window, setting the pixel
value to be used to fill the background. The current window contents are not changed. The
background is automatically repainted after Expose events, in the area affected by the expo-
sure.
When XSetWindowBackground and XSetWindowBackgroundPixmap are both used
on a window, whichever is called last will control the current background. Trying to change
the background of an rnputOnly window will generate a BadHatch error.
For more information, see Volume One, Chapter 4, Window Attributes.
Errors
BadMatch
BadWindow
Related Commands
XGetWindowAttributes, XChangeWindowAttributes, XSetWindow-
BackgroundPixmap, XSetWindowBorder, XSetWindowBorderPixmap, XGet-
Geometry.
July 26, 1988 451
XSetWindowBorderPixmap
Xlib - Pixmaps and Tiles--
Name
XSetWindowBorderPixmap -- change a window border tile atlibute and repaint the border.
Synopsis
XSetWindowBorderPixmap (display, w, border tile)
--
Display *display;
Window w;
Pixmap border tile;
--
Arguments
display
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the ID of an InputOutput window whose border is to be
changed.
border_tile Specifies any pixmap or None.
Description
XSetWindowBorderPixmap sets the border_pixmap attribute of a window and
repaints the border. The border_tile can be freed immediately after the call if no further
explicit references to it are to be made.
This function can only be performed on an TnputOutput window.
Errors
BadMatch
BadPixmap
BadWindow
Related Commands
XSetTile, XQueryBestTile, XSetWindowBackgroundPixmap, XCreatePixmap,
XCreatePixmapFromBitmapData, XFreePixmap, XQueryBestSize, XQuery-
BestStipple, XWriteBitmapFile, XReadBitmapFile, XCreateBitmapFrom-
Data.
454
July 26, 1988
mXlib - Window Manipulation
XSetWindowBorderWidth
Name
XSetWindowBorderWidth -- change the border width of a window.
Synopsis
XSetWindowBorderWidth (display, w, width)
Display *display;
Window w;
unsigned int width;
Arguments
display
w
width
Specifies a poinr to the Display sucture; returned from XOpenDisplay.
Specifies the ID of the window whose border is to be changed.
Specifies the width of the window border.
Description
XSetWindowBorderWidth changes the border width of a window. This request is often
used by the window manager as an indication of the current input focus window, so other
clients should not change it.
Errors
BadWindow
Related Commands
XLowerWindow, XRaiseWindow, XCirculateSubwindows, XCirculate-
SubwindowsDown, XCirculateSubwindowsUp, XRestackWindows, XMove-
Window, XResizeWindow, XMoveResizeWindow, XReparentWindow,
XConfigureWindow, XQueryTree.
July 26, 1988 455
XSetWindowColormap
Xlib - Window Attributes--
Name
XSetWindowColormap m set the colormap for a specified window.
Synopsis
XSetWindowColormap (display, w, cmap )
Display *display;
Window w;
Colormap cmap ;
Arguments
di spl ay
cmap
Specifies a pointer to the Display structure; returned from XOpenDisplay.
Specifies the ID of the window for which you want to set the colormap.
Specifies the colormap.
Description
XSetWindowColorrnap sets the colorrnap attribute of the specified window. The color-
map need not be installed to be set as an attribute, cmap will be used to translate pixel values
drawn into this window when cmap is installed in the hardware.
Eventually, window managers will install and uninstall the proper colormaps according to this
attribute and the pointer position or some other convention. For now, applications Rust install
their own colormaps if they cannot use the default colormap.
The colormap must have the same visual as the window.
Errors
BadColor
BaclMatch
BadWindow
Related Commands
XGetWindowAttributes, XChangeWindowAttributes, XSetWindow-
Background, XSetWindowBackgroundPixmap, XSetWindowBorder, XSet-
WindowBorderPixmap, XGetGeometry.
456 July 26, 1988
--Xlib - Window Manager Hints
XSetWMHints
Name
XSetWMHints m set a window manager hints property.
Synopsis
XSetWMHints (display, w,
Display *display;
Window w;
XWMHint s *wmhints;
Arguments
display
w
wmhi n t s
Description
wmhint s )
Specifies a pointer to the Display structure; returned from XOpenDisplay.
Specifies the ID for which window manager hints are to be set.
Specifies a pointer to the window manager hints.
XSetWMHints sets the window manager hints that include icon information and location, the
initial state of the window, and whether the application relies on the window manager to gct
keyboard input. See Volume One, Chapter 10, Interclient Communication, for a description of
each XWMHint s structure member.
Structures
typedef struct {
long flags;
Bool input;
int initial state;
_
Pixmap icon_pixmap;
Window icon window;
_
int icon_x, icon_y;
Pixmap icon mask;
_
XID window_group;
/* marks defined fields in structure */
/* does application need window manager for
* keyboard input */
/* see below */
/* pixmap to be used as icon */
/* window to be used as icon */
/* initial position of icon */
/* icon mask bitmap */
/* ID of related window group */
/* this structure may be extended in the future */
} XWMHints;
/* definitions for the flags field: */
#define InputHint
#define StateHint
#define IconPixmapHint
#define IconWindowHint
#define IconPositionHint
#define IconMaskHint
#define WindowGroupHint
(IL << 0)
(IL << I)
(IL << 2)
(IL << 3)
(IL << 4)
(IL << 5)
(IL << 6)
#define AllHints (InputHintlStateHintlIconPixmapHintIIconWindowHintl \
IconPositionHintIIconMaskHintlWindowGroupHint)
July 26, 1988 457
XSetWMHints (continued) Xlib - Window Manager Hints
/* definitions for the initial state flag: */
#define DontCareState 0 /* don't know or care */
#define NormalState 1 /* most applications want to start this way */
#define ZoomState 2 /* application wants to start zoomed */
#define IconicState 3 /* application wants to start as an icon */
#define InactiveState 4 /* application believes it is seldom used;
some wm's may put it on inactive menu */
Errors
BadAlloc
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGet-
WMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, XSetNormal-
Hints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGet-
IconName, XSetIconName, XStoreName, XGetIconSizes, XSeticonSizes,
XSetCommand.
458 July 26, 1988
XSetZoom Hints (continued) Xlib - Window Manager Hints
/* flags argument in size hints */
#define USPosition (IL << 0) /* user specified x, y */
#define USSize (IL << i) /* user specified width, height */
#define PPosition (IL << 2) /* program specified position */
#define PSize (IL << 3) /* program specified size */
#define PMinSize (IL << 4) /* program specified minimum size */
#define PMaxSize (IL << 5) /* program specified maximum size */
#define PResizeInc (IL << 6) /* program specified resize increments */
#define PAspect (IL << 7) /* program specified min/max aspect ratios */
#define PAllHints (PPositionlPSizelPMinSizelPMaxSizeIPResizeInclPAspect)
} XSizeHints;
Errors
BadAlloc
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGet-
WMHints, XSetWMHints, XGetZoomHints, XGetNormalHints, XSetNormal-
Hints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGet-
IconName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes,
XSetCommand.
460 July 26, 1988
XStoreBuffer
Xlib - Cut Buffers
Name
XStoreBuffer -- store data in a cut buffer.
Synopsis
XStoreBuffer(display, bytes, nbytes, buffer)
Display *display;
char bytes[];
int nbytes;
int buffer;
Arguments
display
bytes
nbytes
buffer
Specifies a pointer to the Display stcture; returned om XOpenDisplay.
Specifies the string of bytes you want stored. The byte string is not necessarily
ASCII or null-terminated.
Specifies the number of bytes in the string.
Specifies the cut buffer in which to store the byte string. Must be in the range
0-7.
Description
XStoreBuffer stores the specified data into one of the eight cut buffers. All eight buffers
must be stored into before they can be circulated with XRotateBuffers. The cut buffers
are numbered 0 through 7. Use XFetchBuffer tO recover data from any cut buffer.
Note that selections are the preferred method of transferring data between applications.
For more information on cut buffers, see Volume One, Chapter 13, Other Programming Tech-
niques. For more information on selections, see Volume One, Chapter 10, Interclient Com-
munication.
Errors
BadAlloc
BadAtom
Related Commands
XStoreBytes, XFetchBuffer, XFetchBytes, XRotateBuffers.
462 July 26, 1988
--Xlib - Cut Buffers
XStoreBytes
Name
XSmreBytes--storedam in cutbuffer0.
Synopsis
XStoreBytes(display, bytes, nbytes)
Display *display;
char bytes[];
int nbytes;
Arguments
display
Specifies a pointer to the Display structure; returned from XOpenDisplay.
bytes Specifies the string of bytes you want stored. The byte string is not necessarily
ASCII or null-terminated.
nbytes Specifies the number of bytes that you want stored.
Description
XStoreBytes stores data in cut buffer 0, usually for reading by another client that already
knows the meaning of the contents. Note that the cut buffer's contents need not be text, so
null bytes are not special.
The cut buffer's contents may be retrieved later by any client calling XFetchBytes.
Use XStoreBuffer tO store data in buffers 1-7. Note that selections are the preferred
method of transferring data between applications.
For more information on cut buffers, see Volume One, Chapter 13, Other Programming Tech-
niques. For more information on selections, see Volume One, Chapter 10, Interclient Com-
munication.
Errors
BadAlloc
Related Commands
XStQreBuffer, XFetchBuffer, XFetchBytes, XRotateBuffers.
July 26, 1988 463
XStoreColor
Xlib - Color Cells--
Name
XStoreColor -- set or change a read/write entry of a colormap to the closest available
hardware color.
Synopsis
XStoreColor (display, cmap, colorcell def)
--
Display *display;
Colormap cmap ;
XColor *colorcell def;
Arguments
di spl ay
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the colormap.
Specifies a pixel value and the desired RGB values.
cmap
colorcell def
--
Description
XSt o reCo lor changes the RGB values of a colormap entry specified by
colorcell_def.pixel to the closest values available on the hardware. This pixel value
must be a read/write cell and a valid index into craap, xStoreColor changes the red,
green, and/or blue color components in the cell according to the colorcell def. flags
--
member, which you set by ORing the constants DoRed, DoGreen, and/or DoBlue.
If the colormap is an installed map for its screen, the changes are visible immediately.
For more information, see Volume One, Chapter 7, Color.
/* DoRed, DoGreen, DoBlue */
Structures
typedef struct {
unsigned long pixel;
unsigned short red, green, blue;
char flags;
char pad;
} XColor;
Errors
BadColor
BadValue
pixel not valid index into cmap.
Related Commands
XAllocColorCells, XAllocColorPlanes, XAllocColor, XAllocNamedColor,
XLookupColor, XParseColor, XQueryColor, XQueryColors, XStoreColors,
XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel.
464 July 26, 1988
mXlib - Window Manager Hints
X Store NamedColo r
Name
XStoreNamedColor m allocate a read/write colorcell by English color name
Synopsis
XStoreNamedColor (display, cmap, colorname, pixel, flags)
Display *display;
Colormap cmap ;
char *colorname;
unsigned long pixel ;
int flags ;
Arguments
display
cmap
colorname
pixel
fl a gs
Description
Specifies a pointer to the Display structure; returned from XOpenDisplay.
Specifies the colormap.
Specifies the color name string (for example, "red"). This cannot be in hex
format (as used in xParseColor). Upper or lower case is not important.
The string should be in ISO LATIN-1 encoding, which means that the first 128
character codes are ASCII, and the second 128 character codes are for special
characters needed in western languages other than English.
Specifies the entry in the colormap to store color in.
Specifies which red, green, and blue indexes are set.
XStoreNamedColor looks up the named color in the database, with respect to the screen
associated with cmap, then stores the result in the cell of cmap specified by pixel. Upper
or lower case in name does not matter. The flags argument, a bitwise OR of the constants
DoRed, DoGreen, and DoBlue, determines which subfields within the pixel value in the cell
are written.
For more information, see Volume One, Chapter 7, Color.
Errors
Badccess
BadColor
BadName
BadValue
pixel is unallocated or read-only.
pixel is not a valid index into cmap.
Related Commands
XCopyColormapAndFree, XCreateColormap, XFreeColormap, XGetStandard-
ColormapXInstallColormap, XUninstallColormap, XSetStandard-
Colormap, XListInstalledColormaps, XSetWindowColormap, Default-
Colormap, DisplayCells.
July 26, 1988 467
XStringToKeysym
Xlib - Keyboard--
Name
XStringToKeysym m convert a keysym name string to a keysym.
Synopsis
KeySym XStringToKeysym(string)
char *string;
Arguments
string
Specifies the name of the keysym that is to be converted.
Description
XStringToKeysym translates the character string version of a keysym name ("Shift") to
the matching keysym which is a constant (XK_Shift). Valid keysym names are listed in
<X11/keysymdef.h>. If the specified string does not match a valid keysym, XString-
ToKeysym retums NoSymbol.
This string is not the string returned in the buffer argument of XLookupString, which
can be set with XRebindKeysym. If that string is used, XStringToKeysym will return
NoSymbol except by coincidence.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap,
XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifier-
Map, XQueryKeymap, XLookupKeysym, XRebindKeysym, XGetKeyboardMapping,
XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookupString,
XSetModifierMapping, XGetModifierMapping.
468 July 26, 1988
--Xlib - Images
XSublmage
Name
XSubImage -- create a subimage from part of an image.
Synopsis
XImage *XSubImage(ximage, x, y, subimage_width,
subimage_height)
XImage *ximage;
int x;
int y;
unsigned int subimage_width;
unsigned int subimage_height;
Arguments
ximage Specifies a pointer to the image.
x Specify the x and y coordinates of the origin of the subimage.
Y
subimage_width
s ubima ge_h ei gh t
Specify the width and height (in pixels) of the new subimage.
Description
XSubImage creates a new image that is a subsection of an existing one. It allocates the
memory necessary for the new >:Image structure and returns a pointer to the new image. The
data is copied from the source image, and the rectangle defined by x, y, subimage_width,
and subimage_height must by contained in the image.
XSublmage extracts a subimage from an image, while XGetSublmage extracts an image
from a drawable.
For more information on images, see Volume One, Chapter 6, Drawing Graph'cs and Text.
Related Commands
XDetroyImage, XPutlmage, XGetImage, XCreateImage, XGetSubImage, XAdd-
Pixel, XPutPixel, XGetPixel, ImageByteOrder.
July 26, 1988 469
XSubtractRegion
Xlib - Regions--
Name
XSubacegion--subtractoneregion omanother.
Synopsis
XSubtractRegion(sra, srb, dr)
Region sra, srb;
Region dr; /* RETURN */
Arguments
dr
Specify the two regions in which you want to perform the computation.
Returns the result of the computation.
Description
XSubtractRegion calculates the difference between the two regions specified (sra -
srb) and puts the result in dr.
This function returns a region which contains all parts of sra that are not also in srb.
For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
/,
* opaque reference to Regiondata type.
* user won't need contents, only pointer.
*/
typedef struct _XRegion *Region;
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XShrinkRegion, XSet-
Region, XRectInRegion, XPolygonRegion, XPointinRegion, XOffsetRegion,
XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroyRegion,
XEqualRegion, XClipBox.
470
July26, 1988
XTextExtents (continued) Xlib - Text
is the ibearing of the character in the string with the smallest ibearing plus the width of
all the characters up to but not including that character. The overall, rbearing is the
rbearing of the character in the string with the largest rbearing plus the width of all the
characters up to but not including that character.
For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and
Text.
Structures
typedef struct {
XExtData *ext data;
--
Font fid;
unsigned direction;
unsigned min_char or byte2;
unsigned max_char or byte2;
unsigned min_bytel;
unsigned max_bytel;
Bool all chars exist;
-- _
unsigned default char;
--
int n_properties;
XFontProp *properties;
XCharStruct min_bounds;
XCharStruct max bounds;
--
XCharStruct *per_char;
int ascent;
int descent;
} XFontStruct;
/* hook for extension to hang data */
/* font ID for this font */
/* hint about direction the font is painted */
/* first character */
/* last character */
/* first row that exists */
/* last row that exists */
/* flag if all characters have nonzero size*/
/* char to print for undefined character */
/* how many properties there are */
/* pointer to array of additional properties*/
/* minimum bounds over all existing char*/
/* minimum bounds over all existing char*/
/* first_char to last char information */
--
/* logical extent above baseline for spacing */
/* logical descent below baseline for spacing */
typedef struct {
short ibearing; /* origin to left edge of character */
short rbearing; /* origin to right edge of character */
short width; /* advance to next char's origin */
short ascent; /* baseline to top edge of character */
short descent; /* baseline to bottom edge of character */
unsigned short attributes; /* per char flags (not predefined) */
} XCharStruct;
Related Commands
XQueryTextExtents, XQueryTextExtentsl6, XDrawimageString, XDraw-
ImageStringl6, XDrawString, XDrawStringl6, XDrawText, XDrawTextl6,
XTextExtentsl6, XTextWidth, XTextWidthl6.
474
July 26, 1988
mXlib - Text
XTextExtentsl 6
Name
XTextExtentsl6 m get string and font metrics of a 16-bit character string.
Synopsis
XTextExtentsl6 (font struct, string, nchars,
ascent, descent, overall)
XFontStruct *font struct;
--
XChar2b *string;
int nchars ;
int *direction; /* RETURN */
int *ascent, *descent; /* RETURN */
XCharStruct *overall; /* RETURN */
Arguments
font struct
string
nchars
direction
ascent
de s c en t
overall
direction,
Specifies a pointer to the XFontSt ruct structure.
Specifies the character string made up of XChar2 6 structures.
Specifies the number of characters in the character string.
Returns the value of the direction element of the XFontStruct. Font-
RightToLeft of FontLeftToRight.
Returns the font ascent element of the XFontStruct. This is the overall
maximum ascent for the font.
Returns the font descent element of the XFontStruct. This is the overall
maximum descent for the font.
Returns the overall characteristics of the string. These are the sum of the
width measurements for each character, the maximum ascent and
descent, the minimum lbearing added to the width of all characters up
to the character with the smallest lbearing, and the maximum rbearing
added to the width of all characters up to the character with the largest
rbearing.
Description
XTextExtents16 returns the dimensions in pixels that specify the bounding box of the
specified string of characters in the named font, and the maximum ascent and descent for the
entire font. This function performs the size computation locally and, thereby, avoids the
roundtrip overhead of XQueryTextExtent s 16, but it requires a filled xFontSt ruct.
ascent and descent return information about the font, while overall returns informa-
tion about the given string. The returned ascent and descent should usually be used to
calculate the line spacing, while the width, rbearing, and lbearing members of
overall should be used for horizontal measures. The total height of the bounding rectangle,
good for any string in this font, is ascent + descent.
overall, ascent is the maximum of the ascent metrics of all characters in the string. The
overall, descent is the maximum of the descent metrics. The overall, width is the
sum of the character-width metrics of all characters in the string. The overall, lbearing
July 26, 1988 4 75
XTextExtentsl 6 (continued) Xlib - Text
is the ibearing of the character in the string with the smallest Ibearing plus the width of
all the characters up to but not including that character. The overall, rbearing is the
rbearing of the character in the string with the largest rbearing plus the width of all the
characters up to but not including that character.
For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and
Text.
Structures
typedef struct {
short ibearing;
short rbearing;
short width;
short ascent;
short descent;
unsigned short attributes; /* per char flags (not predefined) */
} XCharStruct;
/* origin to left edge of character */
/* origin to right edge of character */
/* advance to next char's origin */
/* baseline to top edge of character */
/* baseline to bottom edge of character */
typedef struct {
XExtData *ext data;
--
Font fid;
unsigned direction;
unsigned min_char or byte2;
unsigned max_char or byte2;
unsigned min_bytel;
unsigned max_bytel;
Bool all_chars_exist;
unsigned default char;
--
int n_properties;
XFontProp *properties;
XCharStruct min bounds;
--
XCharStruct max bounds;
--
XCharStruct *per_char;
int ascent;
int descent;
} XFontStruct;
/* hook for extension to hang data */
/* font ID for this font */
/* hint about direction the font is painted */
/* first character */
/* last character */
/* first row that exists */
/* last row that exists */
/* flag if all characters have nonzero size*/
/* char to print for undefined character */
/* how many properties there are */
/* pointer to array of additional properties*/
/* minimum bounds over all existing char*/
/* minimum bounds over all existing char*/
/* first_char to last char information */
--
/* logical extent above baseline for spacing */
/* logical descent below baseline for spacing */
typedef struct {
unsigned char bytel;
unsigned char byte2;
} XChar2b;
/* normal 16 bit characters are two bytes */
Related Commands
XQueryTextExtent s, XQueryTextExtent s 1 6, XDrawImageSt ring, XDraw-
ImageSt ringl 6, XDrawSt ring, XDrawSt ringl 6, XDrawText, XDrawText 1 6,
XTextExtents, XTextWidth, XTextWidthl 6.
476
July 26, 1988
mXlib - Text
XTextWidth
Name
XTextWidth m get the width in pixels of an 8-bit character string.
Synopsis
int XTextWidth (font struct, string, count)
XFontStruct *font struct;
--
char *string;
int count ;
Arguments
font._struct Specifies the font description structure of the font in which you want to draw
the string.
string
Specifies the character string whose width is to be returned.
count
Specifies the character count in string.
Description
XTextWidth returns the width in pixels of the specified string using the specified font. This
is the sum of the XCharStruct .width for each character in the string. This is also
eqivzlent to the vzlue of overall, width returned by XQueryTextExtents or XText-
Extents. The characters in string are 8-bit characters.
For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and
Text.
Structures
typedef struct {
XExtData *ext data;
--
Font fid;
unsigned direction;
unsigned min char or byte2;
--
unsigned max char or byte2;
--
unsigned min_bytel;
unsigned max_bytel;
Bool all chars exist;
-- --
unsigned default car;
--
int n_properties;
XFontProp *properties;
XCharStruct min bounds;
--
XCharStruct max bounds;
--
XCharStruct *per_char;
int ascent;
int descent;
} XFontStruct;
/* hook for extension to hang data */
/* font ID for this font */
/* hint about direction the font is painted */
/* first character */
/* last character */
/* first row that exists */
/* last row that exists */
/* flag if all characters have nonzero size*/
/* char to print for undefined character */
/* how many properties there are */
/* pointer to array of additional properties*/
/* minimum bounds over all existing char*/
/* minimum bounds over all existing char*/
/* first char to last char information */
-- --
/* logical extent above baseline for spacing */
/* logical descent below baseline for spacing */
Related Commands
XQueryTextExtents, XQueryTextExtentsl6, XDrawImageString, XDraw-
ImageStringl6, XDrawString, XDrawStringl6, XDrawText, XDrawTextl6,
XTextExtents, XTextExtentsl6, XTextWidthl6.
July 26, 1988 477
mXlib - Standard Geometry
XTra ns lateCo o rd i n ates
Name
XTranslateCoordinates m change the coordinate system from one window to another.
Synopsis
Bool XTranslateCoordinates (display, src_w, dest_w, src_x,
src_y, dest_x, dest_y, child)
Display *display;
Window src_w, dest_w;
int src_x, src_y;
int *dest_x, *dest_y; /* RETURN */
Window *child; /* RETURN */
Arguments
di spl ay
src w
dest w
src x
src_y
dest x
dest_y
child
Description
Specifies a pointer to the Display structure; returned from XOpenDisplay.
Specifies the ID of the source window.
Specifies the ID of the destination window.
Specify the x and y coordinates within the source window.
Return the translated x and y coordinates within the destination window.
If the point is contained in a mapped child of the destination window, then that
child ID is returned in chi2d.
XTranslateCoordinates translates coordinates from the frame of reference of one win-
dow to another. This should be avoided in most applications since it requires a roundtrip
request to the server. Most applications benefit from the window-based coordinate system
anyway and don't need global coordinates.
XTranslateCoordinates returns False and *dest_x and *dest_y are set to 0 if
src w and dest w are on different screens. In addition, if the coordinates are contained in
a malSped child of dest_w, then that child is returned in the child argument. Otherwise,
XTranslateCoordinates returns True, sets *dest_x and *dest_y to the location of
the point relative to dest_w, and sets child to None.
Window managers often need to perform a coordinate transformation from the coordinate
space of one window to another, or unambiguously determine which subwindow a coordinate
lies in. XTranslateCoordinates fulfills this need, while avoiding any race conditions
by asking the server to perform this operation.
Errors
BadWindow
Related Commands
XGeometry. XParseGeometry.
Xlib Reference Manual 479
XUndefineCursor
Xlib - Cursors--
Name
XUndefineCursor -- disassociate a cursor from a window.
Synopsis
XUndefineCursor (display, w)
Display *display;
Window w;
Arguments
di spl ay
w
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the ID of the window whose cursor is to be undefined.
XUndefineCursor sets the cursor for a window to its parent's cursor, undoing the effect of
a previous XDefineCursor for this window. On the root window, with no cursor specified,
the default cursor is restored.
Errors
BadWindow
Related Commands
XDefineCursor, XCreateFontCursor, XCreateGlyphCursor, XCreateixmap-
Cursor, XFreeCursor, XRecolorCursor, XQueryBestCursor, XQueryBest-
Size.
480
July 26, 1988
wXlib - Grabbing
XUngrabButton
Name
XUngrabButton -- release a button from grab.
Synopsis
XUngrabButton (display, button, modifiers,
Display *display;
unsigned int button;
unsigned int modifiers;
Window w;
w)
Arguments
display
Specifies a pointer to the Display structure; returned from XOpen-
Display.
button Specifies the mouse button to be released from grab. Specify Buttonl,
Button2, Button3, Button4, Button5, or the cons[ant AnyButton,
which is equivalent to issuing the ungrab request for all possible buttons.
modifiers Specifies a set of keymasks. This is a bitwise OR of one or more of the fol-
lowing symbols: ShiftMask, LockMask, ControlMask, ModlMask,
Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask, or AnyModifier.
AnyModifier is equivalent to issuing the ungrab button request for all
possible modifier combinations (including no modifiers).
w Specifies the ID of the window you want to release the button grab.
Description
XUngrabButton cancels the passive grab on a button/key combination on the specified win-
dow if it was grabbed by this client. A modifiers of AnyModifier is equivalent to issu-
ing the ungrab request for all possible modifier combinations (including the combination of no
modifiers). A button of AnyButton is equivalent to issuing the request for all possible
buttons. This call has no effect on an active grab.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Errors
BadWindow
Related Commands
XGrabKey, XUngrabKey, XGrabKeyboard, XUngrabKeyboard, XGrabButton,
XGrabPointer, XUngrabPointer, XChangeActivePointerGrab, XGrabServer,
XUngrabServer.
July 26, 1988 481
XUngrabKey
Xlib - Grabbing--
Name
XUngrabKey m release a key from grab.
Synopsis
XUngrabKey (display, keycode, modifiers,
Display *display;
int keycode ;
unsigned int modifiers;
Window w;
w)
Arguments
di splay
Specifies a pointer to the Display structure; returned from XOpen-
Display.
keycode Specifies the keycode. This keycode maps to the specific key you want to
ungrab. Pass either a keycode or AnyKey.
modifiers Specifies a set of keymasks. This is a bitwise OR of one or more of the fol-
lowing symbols: ShiftMask, LockMask, ControlMask, ModlMask,
Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask, or AnyModifier.
AnyModifier is equivalent to issuing the ungrab key request for all possi-
ble modifier combinations (including no modifiers).
w Specifies the ID of the window for which you want to ungrab the specified
keys.
Description
XUngrabKey cancels the passive grab on the key combination on the specified window if it
was grabbed by this client. A modifiers of AnyModifier is equivalent to issuing the
request for all possible modifier combinations (including the combination of no modifiers). A
keycode of AnyKey is equivalent to issuing the request for all possible nonmodifier key
codes. This call has no effect on an active grab.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Errors
BadWindow
Related Commands
XGrabKey, XGrabKeyboard, XUngrabKeyboard, XGrabButton, XUngrabButton,
XGrabPointer, XUngrabPointer, XChangeActivePointerGrab, XGrabServer,
XUngrabServer.
482 July 26, 1988
XUninstallColormap
Xlib - Colormaps
Name
XUninsmllColormap--uninsmHacolormap;installdeultifnotaeadyinstalled.
Synopsis
XUninstallColormap(display, cmap)
Display *display;
Colormap cmap;
Arguments
display
cmap
Description
Specifies a pointer m the Display sucture; remed om XOpen-
Display.
Specifies the colormap to be uninstalled.
If cmap is an installed map for its screen, it is uninstalled. If the screen's default colormap is
not installed, it is installed.
If cmap is an installed map, a ColorraapNotify event is generated on every window hav-
ing this colormap as an attribute. If a colormap is installed as a result of the uninstall, a
ColorraapNot i fy event is generated on every window having that colormap as an attribute.
At any time, there is a subset of the installed colormaps, viewed as an ordered list, called the
required list. The length of the required list is at most the rain raaps specified for each
screen in the Display structure. When a colormap is installed w-h XInstallColorraap
it is added to the head of the required list and the last colormap in the list is removed if neces-
sary to keep the length of the list at rain__maps. When a colormap is uninstalled with
xuninstallColorraap and it is in the required list, it is removed from the list. No other
actions by the server or the client change the required list. It is important to realize that on all
but high-performance workstations, rain_maps is likely to be 1.
For more information on installing and uninstalling colormaps, see Volume One, Chapter 7,
Color.
Related Commands
XCopyColorraapAndFree, XCreateColormap, XFreeColormap, XGetStandard-
Colormap, XInstallColormap, XSetStandardColormap, XListinstalled-
Colormaps, XSetWindowColormap, DefaultColormap, DisplayCells.
486
mXlib - Resource Manager
XUnion RectWith Region
Name
XUnionRectWithRegion -- add a rectangle to a region.
Synopsis
XUnionRectWithRegion (rectangle, src_region, dest_region)
XRectangle *rectangle ;
Region src_region ;
Region dest_region ;
Arguments
rectangle Specifies the rectangle to add to the region.
src__region Specifies the source region to be used.
dest_region Specifies the resulting region. May be the same as src_region.
Description
XUnionRectWithRegion computes the destination region from a union of the specified
rectangle and the specified source region. The source and destination regions may be the
same.
One common application of this function is to simplify the combining of the rectangles
specified in Expose events into a clip_mask in the GC, thus restricting the redrawn areas
to the exposed rectangles. Use xunionRectWithRegion to combine the rectangle in each
Expose event into a region, then call XSetRegion. XSetRegion sets the clip_mask
in a GC to the region. In this case, src_region and dest_region would be the same
region.
If src_region and dest_region are not the same region, src_region is copied to
dest_region before the rectangle is added to dest_region.
For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct {
short x, y;
unsigned short width, height;
} XRectangle;
The Region type is a pointer to an opaque data type. Its definition is not needed by pro-
grams.
Related Commands
XClipBox, XDestroyRegion, XEmptyRegion, XEqualRegion, XIntersect-
Region, XOffsetRegion, XPointInRegion, XPolygonRegion, XRectInRegion,
XSetRegion, XShrinkRegion, XSubtractRegion, XUnionRegion, XXorRegion.
Juy 26. e88 4az
XUnionRegion
Xlib - Regions m
Name
XUnionRegion m compute the union of two regions.
Synopsis
XUnionRegion (sra, srb, dr)
Region sra , srb ;
Region dr;
Arguments
dr
Specify the two regions in which you want to perform the computation.
Returns the result of the computation.
Description
XUnionRegion computes the union of two regions and places the result in dr. The result-
ing region will contain all the area of both the source regions.
For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
/,
* opaque reference to Regiondata type.
* user won't need contents, only pointer.
*/
typedef struct _XRegion *Region;
Related Commands
XXorRegion, XUnionRectWithRegion, XSubtractRegion, XShrinkRegion,
XSetRegion, XRectInRegion, XPolygonRegion, XPointinRegion, XOffset-
Region, XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroy-
Region, XEqualRegion, XClipBox.
488
July 26, 1988
--Xlib - Context Manager
XUniqueContext
Name
XUniqueContext D create a new context ID (not graphics context).
Synopsis
XContext XUniqueContext()
Description
The context manager allows association of arbitrary data with a resource ID. This call creates
an instance of the xContext structure with a unique resource ID that will be used in subse-
quent calls to XFindContext, XDeleteContext, and XSaveContext.
For more information on the context manager, see Volume One, Chapter 13, Other Program-
ming Techniques.
Structures
typedef int XContext;
Related Commands
XDeleteContext, XFindContext, XSaveContext.
July 26, 1988 489
XUnloadFont
Xlib- Fonts m
Name
XUnloadFont -- unload a font.
Synopsis
XUnloadFont (display, font)
Display *display;
Font font;
Arguments
display
fon t
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the ID of the font to be unloaded.
XUnloadFont indicates to the server that this client no longer needs the specified font. The
font may be unloaded on the X server if this is the last client that needs the font. In any case,
the font should never again be referenced by this client because X destroys the resource ID.
For more information on loading and unloading fonts, see Volume One, Chapter 6, Drawing
Graphics and Text.
Errors
BadFont
Related Commands
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontinfo, XListFonts,
XListFontsWithInfo, XFreeFontNames, XFreeFontPath, XGetFontPath,
XQueryFont, XSetFont, XSetFontPath, XGetFontProperty, XCreateFont-
Cursor.
490
July 26, 1988
mXlib - Mapping
XUnmapSubwindows
Name
XUnmapSubwindows--unmap allsubwindowsofa ven window.
Synopsis
XUnmapSubwindows(display, w)
Display *display;
Window w;
Arguments
display
w
Description
Specifies a pointer to the Display structure; returned from X0pen-
Display.
Specifies the ID of the window whose subwindows are to be unmapped.
XUnmapSubwindows performs an XUnmapWindow on all mapped children of w, in bottom
to top stacking order.
XUnmapSubwindows also generates an UnmapNotify event on each subwindow and gen-
erates exposure events on formerly obscured windows. This is much more efl%ient than
unmapping many subwindows one at a time, since much of the work need only be performed
once for all of the subwindows rather than for each subwindow.
For more information on window mapping, see Volume One, Chapter 2, X Concepts.
Errors
BadWindow
Related Commands
XMapRaised, XMapSubwindows, XMapWindow, XUnmapWindow.
July 26, 1988 491
--Xlib - Pointer
XWarpPointer
Name
XWarpPointer m move the pointer to another point on the screen.
Synopsis
XWarpPointer(display, src_w, dest_w, src_x, src_y,
src_width, src_height, dest_x, dest_y)
Display *display;
Window src_w, dest_w;
int src_x, src_y;
unsigned int src width, src height ;
int dest_x , dest_y ;
Arguments
di splay
Specifies a pointer to the Display structure; returned from XOpen-
Display.
src w
--
Specifies the ID of the source window. You can also pass None.
dest w
--
Specifies the ID of the destination window. You can also pass None.
szc x
src_y
src width
src_height
Specify the x and y coordinates within the source window. These are uscd
with src_width and src_height to determine the rectangle the
pointer must be in. They are not the present pointer position. If src_y is
None, these coordinates are relative to the root window of src w.
--
Specify the width and height in pixels of the source window. Used with
src_x and src_y.
dest_x Specify the destination x and y coordinates within the destination window.
dest_y If dest_y is None, these coordinates are relative to the root window of
dest w.
Description
XWarpPointer moves the pointer suddenly from one point on the screen to another.
If des.t_w is a window, xWarpPointer moves the pointer to [dest_x, dest_y] relative
to the destination window's origin. If dest w is None, XWarpPointer moves the pointer
--
according to the offsets [dest_x, dest_y] relative to the current position of the pointer.
If src_window is None, the move is independent of the current cursor position (dest_x
and dest_y use global coordinates). If the source window is not None, the move only takes
place if the pointer is currently contained in a visible portion of the rectangle of the source
window (including its inferiors) specified by src_x, src_y, src_width and
src_height. If src_width is zero (0), the pointer must be between src_x and the right
edge of the window to be moved. If src_height is zero (0), the pointer must be betwecn
src_y and the bottom edge of the window to be moved.
XWarpPointer cannot be used to move the pointer outside the confine to window of an
--
active pointer grab. If this is attempted the pointer will be moved to the point on the border of
the confine_to window nearest the requested destination.
July 26, 1988 493
XWarpPointer (continued) Xlib - Pointer
XWarpPointer generates events as if the user had (instantaneously) moved the pointer.
This function should not be used unless absolutely necessary, and then only in tightly con-
trolled, predictable situations. It has the potential to confuse the user.
Errors
BadWindow
Related Commands
XQueryPointer, XGrabPointer, XChangeActivePointerGrab, XUngrab-
Pointer, XGetPointerMapping, XSetPointerMapping, XGetPointerControl,
XChangePointerControl.
44
July 26, 1988
nXlib - Input Handling
XWindowEvent
Name
XWindowEvent m remove the next event matching mask and window.
Synopsis
XWindowEvent (display, w, event_mask, rep)
Display *display;
Window w;
long event mask;
--
XEvent *rep; /* RETURN */
Arguments
di spl ay
event mask
rep
Description
Specifies a pointer to the Display structure; returned from XOpen-
Display.
Specifies the ID of the window whose next matched event you want to
remove.
Specifies the event mask. See XSelectInput for a complete list of event
masks.
Specifies the event removed from the input queue. XWindowEvent returns
this event to this argument.
XWindowEvent searches the event queue for specific event types from the specified window.
XWindowEvent removes the next event in the queue which matches both the passed window
and the passed mask. The event is copied into an XEvent supplied by the caller. Other
events in the queue are not discarded. If no such event has been queued, XWindowEvent
flushes the output buffer and waits until one is received.
In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the
output buffer is flushed only if no matching events are found on the queue. This change is
compatible with applications written for Release 1.
Structures
See individual event structures described in Volume One, Chapter 8, Events, and Appendix F,
Structure Reference in this volume.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XCheckWindowEvent,
XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMask-
Event, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents,
XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent,
XPending, XSynchronize, XSendEvent, QLength.
July 26, 1988 495
XWriteBitmapFile
Xlib - Pixmaps and Tiles--
Name
XWriteBitmapFile m write a bitmap to a file.
Synopsis
int XWriteBitmapFile ( display, filename, bitmap,
height, x_hot, y_hot )
Display *display;
char *filename;
Pixmap bitmap;
unsigned int width, height ;
int x_hot, y_hot ;
width,
Arguments
display
filename
bi tmap
width
height
x hot
y_hot
Specifies a pointer to the Display sucture; returned om XOpen-
Display.
Specifies the filename to use. The format of the filename is operating system
specific.
Specifies the bitmap to be written.
Specify the width and height in pixels of the bitmap to be written.
Specify where to place the hotspot coordinates (or -1,-1 if none present) in
the file.
Description
XWriteBitmapFile writes a bitmap to a file. The file is written out in X version 11 bit-
map format, which is the format created by the X version 11 bitmap program. Refer to that
program's reference pages for details. While XReadBitmapFile Can read in either X Ver-
sion 10 format or X Version 11 format, XWriteBitraapFile always writes out X Version
11 format only. The difference between these formats is slight.
If the file cannot be opened for writing, XWriteBitraapFile returns BitmapOpen-
Failed. If insufficient memory is allocated XWriteBitmapFile returns Bitmap-
NoMemory. Otherwise, on no error, XWriteBitmapFile returns BitmapSuccess.
If x_hot and y_hot are not -I, -I, then XWriteBitmapFile writes them out as the
hotspot coordinates for the bitmap.
The following is an example of the contents of a bitmap file created. The name used ("gray"
in this example) is the portion of filenarae after the last "/".
496 July 26, 1988
Xlib - Pixmaps and Tiles (continued) XWriteBitmapFile
#define gray_width 16
#define gray_height 16
#define gray x hot 8
#define gray y hot 8
static char gray_bits[] = (
0xfS, 0xlf, 0xe3, 0xc7, 0xcf, 0xf3, 0x9f, 0xf9, 0xbf, 0xfd, 0x33, 0xcc,
0x7f, 0xfe, 0x7f, 0xfe, 0x7e, 0x7e, 0x7f, 0xfe, 0x37, 0xec, 0xbb, 0xdd,
0x9c, 0x39, 0xcf, 0xf3, 0xe3, 0xc7, 0xfS, 0xlf};
For more information on bitmaps, see Volume One, Chapter 6, Drawing Graphics and Text.
Errors
BadDrawable
BadMatch
Related Commands
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindow-
BackgroundPixmap, XCreatePixmap, XCreatePixmapFromBitmapData, XFree-
Pixmap, XQueryBestSize, XQueryBestStipple, XReadBitmapFile, XCreate-
BitmapFromData.
July 26, 1988 49 7
XXorRegion
Xlib - Regions--
Name
XXorRegion -- calculate the difference between the union and intersection of two
regions.
Synopsis
XXorRegion(sra, srb, dr)
Region sra, srb;
Region dr; /* RETURN */
Arguments
dr
Specify the two regions on which you want to perform the computation.
Returns the result of the computation.
Description
XXorRogion calculates the union minus the intersection of two regions, and places it in dr.
Xor is short for "Exclusive OR", meaning that a pixel is included in dr if it is set in either
sra or srb but not in both.
For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
/*
* opaque reference to Regiondata type.
* user won't need contents, only pointer.
*/
typedef struct _XRegion *Region;
Related Commands
XUnionRegion, XUnionRectWithRegion, XSubtractRegion, XShrinkRegion,
XSetRegion, XRectInRegion, XPolygonRegion, XPointinRegion, XOffset-
Region, XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroy-
Region, XEqualRegion, XClipBox.
4@8
July 26, 1988
Colorcells
XAllocColor
XAllocColorCells
XAllocColorPlanes
XAllocNamedColor
XLookupColor
XParseColor
XQueryColor
XQueryColors
XStoreColor
XStoreColors
XStoreNamedColor
XFreeColors
BlackPixel
WhitePixel
Allocate a read-only colormap cell with closest
hardware-supported color.
Allocate read/write (nonshared) colorcells.
Allocate read/write (nonshareable) color planes.
Allocate a read-only colorcell from color name.
Get database RGB values and closest hardware-
supported RGB values from color name.
Look up or translate RGB values from color name or
hexadecimal value.
Obtain the RGB values for a specified pixel value.
Obtain RGB values and flags for each specified pixel
value.
Set or change a read/write entry of a colormap to the
closest available hardware color.
Set or change read/write colorcells to the closest avail-
able hardware colors.
Allocate a read/write colorcell by English color name.
Free colormap cells or planes.
Return a black pixel value on the default colormap of
screen.
Return a pixel value representing white in default color-
map.
Colormaps
XCopyColormapAndFree
XCreateColormap
XFreeColormap
XGetStandardColormap
XSetStandardColormap
XSetWindowColormap
XInstallColormap
XUninstallColormap
XListInstalledColormaps
DefaultColormap
DefaultColormapOfScreen
DisplayCells
Context Manager
Copy a colormap and return a new colormap ID.
Create a colormap.
Delete a colormap and install the default colormap.
Get the standard colormap property.
Change the standard colormap property.
Set the colormap for a specified window.
Install a colormap.
Uninstall a colormap; install default if not already
installed.
Get a list of installed colormaps.
Return the default colormap on the default screen.
Return the default colormap on the specified screen.
Return the maximum number of colormap cells on the
connected display.
XDeleteContext
XFindContext
Delete a context entry for a given window and type.
Get data from the context manager (not graphics context).
500 Xlib Reference Manual
Context Manager (continued)
XSaveContext
XUniqueContext
Cursors
Save a data value corresponding to a window and context type
(not graphics context).
Create a new context ID (not graphics context)
XDefineCursor
XUndefineCursor
XCreateFontCursor
XCreateGlyphCursor
XCreatePixmapCursor
XFreeCursor
XRecolorCursor
XQueryBestCursor
XQueryBestSize
Assign a cursor to a window.
Disassociate a cursor from a window.
Create a cursor from the standard cursor font.
Create a cursor from font glyphs.
Create a cursor from two bitmaps.
Destroy a cursor.
Change the color of a cursor.
Get the closest supported cursor sizes.
Obtain the "best" supported cursor, tile, or stipple size.
Display Specifications
DefaultColormap
DefaultDepth
DefaultGC
DefaultScreen
DefaultVisual
DisplayCells
DisplayHeight
DisplayHeightMM
DisplayPlanes
DisplayString
DisplayWidth
DisplayWidthMM
RootWindow
ScreenCount
Return the default colormap on the specified screen.
Return the depth of the default root window for a screen.
Return the default graphics context for the root window of a
screen.
Return the screen integer; the last segment of a string passed to
XOpenDisplay, or the DISPLAY environment variable if
NULL was used.
Return the default visual structure for a screen.
Return the maximum number of colormap cells on the connected
display.
Return an integer that describes the height of the screen in pix-
els.
Return the height of the specified screen in millimeters.
Return the number of planes on the connected display.
Return the string that was passed to XOpenDisplay or if that
was NULL, the DISPLAY variable.
Return the width of the screen in pixels.
Return the width of the specified screen in millimeters.
Return the ID of the root window.
Return the number of available screens.
Drawing Primitives
XDraw
XDrawArc
XDrawArcs
XDrawFilled
XDrawLine
Draw a polyline or curve between vertex list (from X 10).
Draw an arc fitting inside a rectangle.
Draw multiple arcs.
Draw a filled polygon or curve from vertex list (from X10)
Draw a line between two points.
Appendix A: Function Group Summary 501
Drawing Primitives (continued)
XDrawLine s Draw
XDrawPoint Draw
XDrawPoint s Draw
XDrawRect angle Draw
XDrawRectangles Draw
XDrawSegment s Draw
XCopyArea Copy
XCopyPlane
XFillArc
XFillArcs
XFillPolygon
XFillRectangle
XFillRectangles
XClearArea
XClearWindow
multiple connected lines.
a point.
multiple points.
an outline of a rectangle.
the outlines of multiple rectangles.
multiple disjoint lines.
an area of a drawable.
Copy a single plane of a drawable into a drawable with
depth, applying pixel values.
Fill an arc.
Fill multiple arcs.
Fill a polygon.
Fill a rectangular area.
Fill multiple rectangular areas.
Clear a rectangular area in a window.
Clear an entire window.
Errors
XGetErrorDatabaseText
XGetErrorText
XSetErrorHandler
XSetIOErrorHandler
XDisplayName
XSetAfterFunction
XSynchronize
Obtain error messages from the error database.
Obtain a description of error code.
Set a nonfatal error event handler.
Handle fatal I/O errors.
Report the display name when connection to a display fails.
Set a function called after all Xlib functions.
Enable or disable synchronization for debugging.
Events
XSelectInput
XSendEvent
XSetInputFocus
XGetInputFocus
XWindowEvent
XCheckWindowEvent
XCheckTypedEvent
XCheckTypedWindowEvent
XMaskEvent
XCheckMaskEvent
XIfEvent
XCheckIfEvent
Select the event types to be sent to a window.
Send an event.
Set the keyboard focus window.
Return the current keyboard focus window.
Remove the next event matching mask and window.
Remove the next event matching both passed window and
passed mask; don't wait.
Return the next event in queue that matches event type;
don't wait.
Return the next event in queue matching type and window.
Remove the next event that matches mask.
Remove the next event that matches mask; don't wait.
Wait for matching event.
Check the event queue for a matching event.
502 Xlib Reference Manual
Events (continued)
XPeekEvent
XPeekIfEvent
XAllowEvents
XGetMotionEvents
XNextEvent
XPutBackEvent
XEventsQueued
XPending
XSynchronize
QLength
Get an event without removing it from the queue.
Get an event without recovering it from the queue; don't
wait.
Control the behavior of keyboard and pointer events when
these resources are grabbed.
Get pointer motion events.
Get the next event of any type or window.
Push an event back on the input queue.
Check the number of events in the event queue.
Flush the output buffer and return the number of pending
input events.
Enable or disable synchronization for debugging.
Return the current length of the input queue on the connected
display.
Extensions
XFreeExtensionList
XListExtensions
XQueryExtension
Free memory allocated for a list of installed extensions to X.
Return a list of all extensions to X supported by the server.
Get extension information.
Fonts
XLoadFont
XUnloadFont
XFreeFont
XFreeFontInfo
XFreeFontNames
XFreeFontPath
XListFonts
XListFontsWithInfo
XQueryFont
XSetFont
XSetFntPath
XGetFontPath
XGetFontProperty
XCreateFontCursor
Load a font if not already loaded; get font ID.
Unload a font.
Unload a font and free storage for the font structure.
Free multiple font information arrays.
Free the font name array.
Free the memory allocated by XGetFontPath.
Return a list of the available font names.
Obtain the names and information about loaded fonts.
Return information about a loaded font.
Set the current font in a graphics context.
Set the font search path.
Get the current font search path.
Get a font property given its atom.
Create a cursor from the standard cursor font
Grabbing
XGrabKey
XUngrabKey
XGrabKeyboard
XUngrabKeyboard
Grab a key.
Release a key from grab.
Grab the keyboard.
Release the keyboard from grab.
Appendix A: Function Group Summary 503
Grabbing (continued)
XGrabButton
XUngrabButton
XGrabPointer
XUngrabPointer
XGrabServer
XUngrabServer
XChangeActivePointerGrab
Grab a pointer button.
Release a button from grab.
Grab the pointer.
Release the pointer from grab.
Grab the server grab.
Release the server from grab.
Change the parameters of an active pointer grab.
Graphics Context
XGContextFromGC
XCreateGC
XChangeGC
XCopyGC
XFreeGC
XSetArcMode
XSetClipMask
XSetClipOrigin
XSetClipRectangles
XSetRegion
XSetDashes
XSetLineAttributes
XSetFillRule
XSetFillStyle
XSetTile
XSetStipple
XSetTSOrigin
XSetGraphicsExposures
XSetForeground
XSetBackground
XSetFunction
XSetPlaneMask
XSetState
XSetSubwindowMode
DefaultGC
Obtain the GContext (resource ID) associated with the
specified graphics context.
Create a new graphics context for a given screen with the
depth of the specified drawable.
Change the components of a given graphics context.
Copy a graphics context.
Free a graphics context.
Set the arc mode in a graphics context.
Set clip_mask pixmap in a graphics context.
Set the clip origin in a graphics context.
Set clip_mask in a graphics context to the list of rec-
tangles.
Set clip_mask of the graphics context to the specified
region.
Set dash_offset and dashes (for lines) in a graph-
ics context.
Set the line drawing components in a graphics context.
Set the fill rule in a graphics context.
Set the fill style in a graphics context.
Set the fill tile in a graphics context.
Set the stipple in a graphics context.
Set the tile/stipple origin in a graphics context.
Set graphics_exposures in a graphics context.
Set the foreground pixel value in a graphics context.
Set the background pixel value in a graphics context.
Set the bitwise logical operation in a graphics context.
Set the plane mask in a graphics context.
Set the foreground, background, logical function and
plane mask in a graphics context.
Set the subwindow mode in a graphics context.
Return the default graphics context for the root window
of a screen.
504 Xlib Reference Manual
Host Access
XAddHost
XAddHosts
XListHosts
XRemoveHost
XRemoveHosts
XDisableAccessControl
XEnableAccessControl
XSetAcces sCont rol
Add a host to the access control list.
Add multiple hosts to the access control list.
Obtain a list of hosts having access to this display.
Remove a host from the access control list.
Remove multiple hosts from the access control list.
Allow access from any host.
Use access control list to allow or deny connection
requests.
Disable or enable access control.
HouseKeeping
XFree
XOpenDisplay
XCloseDisplay
XNoOp
DefaultScreen
Free specified in-memory data created by an Xlib function.
Connect a client program to an X server.
Disconnect a client program from an X server and display.
Send a NoOp to exercise connection with the server.
Return the screen integer; the last segment of a string
passed to XOpenDisplay, or the DISPLAY environment
variable if NULL was used.
Images
XCreateImage
XDestroyImage
XPutImage
XSubImage
XGetImage
XGetSubImage
XAddPixel
XPutPixel
XGetPixel
ImageByteOrder
Allocate memory for an Xlmage structure.
Deallocate memory associated with an image.
Draw a rectangular image on a window or pixmap.
Create a subimage from part of an image.
Place contents of a rectangle from drawable into an image.
Copy a rectangle in drawable to a locadon within the pre-
existing image.
Add a constant value to every pixel value in an image.
Set a pixel value in an image.
Obtain a single pixel value from an image.
Specify the required byte order for images for each scan
line unit in XYFormat (bitmap) or for each pixel value in
ZFormat. Returns either LSBFirst or MSBFirst.
Keyboard
XKeycodeToKeysym
XKeysymToKeycode
XKeysymToString
XStringToKeysym
XLookupKeysym
XRebindKeysym
Convert a keycode to a keysym.
Convert a keysym to the appropriate keycode.
Convert a keysym symbol to a string.
Convert a keysym name string to a keysym.
Get the keysym corresponding to a keycode in a structure.
Rebind a keysym to a string for client.
Appendix A: Function Group Summary 505
Keyboard (continued)
XLookupString
XQueryKeymap
XGetKeyboardMapping
XChangeKeyboardMapping
XRefreshKeyboardMapping
XSetModifierMapping
XGetModifierMapping
XDeleteModifiermapEntry
XInsertModifiermapEntry
XNewModifiermap
XFreeModifiermap
Macros, Display
Map a key event to ASCII string, keysym, and Compose-
Status.
Obtain a bit vector for the current state of the keyboard.
Return symbols for keycodes.
Change the keyboard mapping.
Update the stored modifier and keymap information.
Set keycodes to be used as modifiers (Shift, Control, etc.).
Obtain modifier key mapping (Shift, Control, etc.).
Delete an entry from an XModifierKeymap stnacture.
Add a new entry to an XModifierKeymap stnacture.
Create a keyboard modifier mapping structure.
Destroy and free a keyboard modifier mapping structure.
AllPlanes
BlackPixel
BlackPixelOfScreen
CellsOfScreen
ConnectionNumber
DefaultColormap
DefaultColormapOfScreen
DefaultDepth
DefaultDepthOfScreen
DefaultGC
DefaultGCOfScreen
DefaultRootWindow
DefaultScreen
DefaultScreenOfDisplay
DefaultVisual
DefaultVisualOfScreen
DisplayCells
DisplayHeight
DisplayHeightMM
DisplayOfScreen
DisplayPlanes
Return an unsigned long value with all bits set.
Return a black pixel value on the default colormap of
screen.
Return the black pixel value in the default colormap of the
specified screen.
Return the number of colormap cells of the specified
screen.
Return
tem).
Return
Return
Return
Return
the connection number (file descriptor on UNIX sys-
the default colormap on the specified screen.
the default colormap of the specified screen.
the depth of the default root window for a screen.
the default depth of the specified screen.
Return the default graphics context for the root window of
a screen.
Return the default graphics context (GC) of the specified
screen.
Return the root window for the default screen.
Return the screen integer; the last segment of a string
passed to XOpenDisplay, or the DISPLAY environment
variable if NULL was used.
Return the default screen of the specified display.
Return
Return
Return
nected
Return
pixels.
Return
Return
Return
the default visual structure for a screen.
the default visual of the specified screen.
the maximum number of colormap cells on the con-
display.
an integer that describes the height of the screen in
the height of the specified screen in millimeters.
the display of the specified screen.
the number of planes on the connected display.
506 Xlib Reference Manual
Macros, Image Format
BitmapBitOrder
BitmapPad
BitmapUnit
ByteOrder
ImageByteOrder
Retum LeastSignificant or MostSignificant.
Indicates e bit order in BitmapUnit.
Each scan line is padded to a multiple of bits specified by
the value returned by this macro.
The scan line is quantized (calculated) in multiples of this
value.
Specifies the required byte order for images for each scan
line unit in XYFormat (bitmap) or for each pixel value
in ZFormat. Possible values are LSBFirst or
MSBFirst.
Specifies the required byte order for images for each scan
line unit in XYFormat (bitmap) or for each pixel value
in ZFormat. Return either LSBFirst or MSBFirst.
Macros, Keysym Classification
IsCursorKey
IsFunctionKey
IsKeypadKey
IsMiscFunctionKey
IsModifierKey
IsPFKey
Return T rue if the keysym is on the cursor key.
Return True if the keysym is on the function keys.
Return True if the keysym is on the key pad.
Return True if the keysym is on the miscellaneous func-
tion keys.
Return T rue if the keysym is on the modifier keys.
Return T rue if the keysym is on the PF keys.
Mapping
(see Window Mapping, Keyboard, or Pointer)
Output Buffer
XFlush
XSync
Pointers
Flush the output buffer.
Flush the output buffer and wait for all events to be pro-
cessed by the server.
XQueryPointer
XWarpPointer
XGrabPointer
XUngrabPointer
XGetPointerMapping
XSetPointerMapping
XGetPointerControl
XChangePointerControl
XChangeActivePointerGrab
Get the current pointer location.
Move the pointer to another point on the screen.
Grab the pointer.
Release the pointer from grab.
Get the pointer button mapping.
Set the pointer button mapping.
Get the current pointer preferences.
Change the pointer preferences.
Change the parameters of an active pointer grab.
508 Xlib Reference Manual
Properties
XListProperties
XDeleteProperty
XChangeProperty
XSetStandardProperties
XRotateWindowProperties
XGetAtomName
XGetFontProperty
XGetWindowProperty
XInternAtom
Get the property list for a window.
Delete a window property.
Change a property associated with a window.
Set the minimum set of properties for the window
manager.
Rotate properties in the properties array.
Get a name for a given atom.
Get a font property given its atom.
Obtain the atom type and property format for a window.
Return an atom for a given name string.
Regions
XCreateRegion
XDestroyRegion
XEmptyRegion
XPolygonRegion
XPointInRegion
XRectInRegion
XUnionRectWithRegion
XClipBox
XOffsetRegion
XShrinkRegion
XEqualRegion
XSetRegion
XSubtractRegion
XlntersectRegion
XUnionRegion
XXorRegion
Create a new empty region.
Deallocate storage associated with a region.
Determine if a region is empty.
Generate a region from points.
Determine if a point resides in a region.
Determine if a rectangle resides in a region.
Add a rectangle to a region.
Generate the smallest rectangle enclosing a region.
Change offset of a region.
Reduce the size of a region.
Determine if two regions have the same size, offset, and
space.
Set clip_mask of the graphics context to the specified
region.
Subtract one region from another.
Compute the intersection of two regions.
Compute the union of two regions.
Calculate the difference between the union and intersection
of 2 regions.
Resource Manager and DataBase (Release 2 only)
XrmGetFileDatabase
XrmGetResource
XrmGetStringDatabase
XrmInitialize
XrmMergeDatabases
XrmParseCommand
XrmPutFileDatabase
XrmPutLineResource
XrmPutResource
XrmPutStringResource
Retrieve a database from a file.
Get a resource from name and class as strings.
Create a database from a string.
Initialize the resource manager.
Merge the contents of one database with another.
Load a resource database from command line arguments.
Store a database in a file.
Add a resource entry given as a string of name and value.
Store a resource into a database.
Add a resource that is specified as a string.
Appendix A: Function Group Summary 509
Resource Manager and DataBase (Release 2 only) (continued)
XrmQGetResource
XrmQGetSearchList
XrmQGetSearchResource
XrmQPutResource
XrmQPutStringResource
XrmQuarkToString
XrmStringToBinding-
QuarkList
XrmStringToQuarkList
XrmStringToQuark
XrmUniqueQuark
Xpermalloc
Get a resource from name and class as quarks.
Return a list of database levels.
Search resource database levels for a given resource.
Store a resource into a database using quarks.
Add a string resource value to a database using quarks.
Convert a quark to a string.
Convert a key string to a binding list and a quark list.
Convert a key string to a quark list.
Convert a string to a quark.
Allocate a new quark.
Allocate memory never to be freed.
Save Set
XAddToSaveSet
XRemoveFromSaveSet
XChangeSaveSet
Add a window's children to the client's save-set.
Remove a window's children from the client's save-set.
Add or remove a subwindow from the client's save-set.
Screen Saver
XActivateScreenSaver
XForceScreenSaver
XResetScreenSaver
XGetScreenSaver
XSetScreenSaver
Selections
Activate screen blanking.
Turn the screen saver on or off.
Reset the screen saver.
Get the current screen saver parameters.
Set the parameters of the screen saver.
XGetSelectionOwner
XSetSelectionOwner
XConvertSelection
Return the owner of a selection.
Set the owner of a selection.
Use the value of a selection.
Standard Geometry
XGeomet ry
XParseGeometry
XTranslateCoordinates
Text
Calculate window geometry given user geometry string and
default geometry.
Generate position and size from standard window geometry
string.
Change the coordinate system from one window to another.
XDrawImageString
XDrawImageStringl6
XDrawString
Draw 8-bit image text characters.
Draw 16-bit image text characters.
Draw an 8-bit text string, foreground only.
510 Xlib Reference Manual
Text (continued)
XDrawStringl6
XDrawText
XDrawTextl6
XQueryTextExtents
XQueryTextExtentsl6
XTextExtents
XTextExtentsl6
XTextWidth
XTextWidthl6
Draw two-byte text strings.
Draw 8-bit polytext strings.
Draw 16-bit polytext slrings.
Query the server for string and font metrics.
Query the server for string and font metrics of a 16-bit
character siring.
Get siring and font metrics.
Get string and font metrics of a 16-bit character string.
Get the width in pixels of an 8-bit character string.
Get the width in pixels of a 16-bit character string.
Tile, Pixmap, Stipple and Bitmap
XCreatePixmap
XFreePixmap
XQueryBestSize
XQueryBestStipple
XQueryBestTile
XSetTile
XSetWindowBorderPixmap
XSetWindowBackgroundPixmap
XReadBitmapFile
XWriteBitmapFile
XCreateBitmapFromData
XCreatePixmapFromBitmapData
Create a pixmap.
Free a pixmap ID.
Obtain the "best" supported cursor, tile, or stipple size.
Obtain the best supported stipple shape.
Obtain the best supported fill tile shape.
Set the fill tile in a graphics context.
Change a window border tile attribute and repaint the
border.
Change the background tile attribute of a window.
Read a bitmap from disk.
Write a bitmap to a file.
Create a bitmap from X 11 bitmap format data.
Create a pixmap with depth from bitmap data.
User Preferences
XAutoRepeatOff
XAutoRepeatOn
XBell
XGetDefault
XGetPointerControl
XGetKeyboardControl
XChangeKeyboardControl
Turn off the keyboard auto-repeat keys.
Turn on the keyboard auto-repeat keys.
Ring the bell (Control G).
Scan the user preferences for program name and
options.
Get the current pointer preferences.
Obtain a list of the current keyboard preferences.
Change the keyboard preferences.
Visuals
XGetVisualInfo
XMat chVi sual Info
DefaultVisual
Find a visual information structure that matches
the specified template.
Obtain the visual information that matches the
desired depth and class.
Return the default visual structure for a screen.
Appendix A: Function Group Summary 511
Window Attributes
XGetWindowAttributes
XChangeWindowAttributes
XSetWindowBackground
XSetWindowBackgroundPixmap
XSetWindowBorder
XSetWindowBorderPixmap
XSetWindowColormap
XDefineCursor
XGetGeometry
XSelectInput
Obtain the current attributes of window.
Set window attributes.
Set the background pixel attribute of a window.
Change the background tile attribute of a window.
Change a window border attribute to the specified
pixel value and repaint the border.
Change a window border tile attribute and repaint
the border.
Set the colormap for a specified window.
Assign a cursor to a window.
Obtain the current geometry of drawable.
Select the event types to be sent to a window.
Window Configuration
XMoveWindow
XResizeWindow
XMoveResizeWindow
XSetWindowBorderWidth
XRestackWindows
XConfigureWindow
XGetGeometry
Window Existence
Move a window.
Change a window's size.
Change the size and position of a window.
Change the border width of a window.
Change the stacking order of siblings.
Change the window position, size, border width, or
stacking order.
Obtain the current geometry of drawable.
XCreateSimpleWindow
XCreateWindow
XDestroySubwindows
XDestroyWindow
Window Manager Hints
Create an unmapped InputOutput subwindow.
Create a window and set attributes.
Destroy all subwindows of a window.
Unmap and destroy a window and all subwindows.
XGetClassHint
XSetClassHint
XGetNormalHints
XSetNormalHints
XGetSizeHints
XSetSizeHints
XGetTransientForHint
Get the XA._WM_CLASS property of a window.
Set the XA_WM_CLAS S property of a window.
Get the size hints property of a window in normal
state (not zoomed or iconified).
Set the size hints property of a window in normal
state (not zoomed or iconified).
Read any property of type XA WM SIZE HINTS.
Set the value of any property of type XA WM
-- __
SIZE HINTS.
Get the XA_WM_TRANSIENT_FOR property of a
window.
512 Xlib Reference Manual
Window Manager Hints (continued)
XSetTransientForHint
XGetWMHints
XSetWMHints
XGetZoomHints
XSetZoomHints
XFetchName
XStoreName
XGetIconName
XSetIconName
XGetIconSizes
XSetIconSizes
XSetCommand
Set the XA_WM_TRANSIENT_FOR property of a
window.
Read a window manager hints property.
Set a window manager hints property.
Read the size hints property of a zoomed window.
Set the size hints property of a zoomed window.
Get a window's name (XA_WM_NAME property).
Assign a name to a window for the window manager.
Get the name to be displayed in an icon.
Set the name to be displayed in a window's icon.
Get preferred icon sizes.
Set the value of the XA_WM_ICON_S IZE property.
Set the XA WM COMMAND atom (command line
arguments).
Window Manipulation
XLowerWindow
XRaiseWindow
XCirculateSubwindows
XCirculateSubwindowsDown
XCirculateSubwindowsUp
XQueryTree
XReparentWindow
XMoveWindow
XResizeWindow
XMoveResizeWindow
XSetWindowBorderWidth
XRestackWindows
XConfigureWindow
Lower a window in the stacking order.
Raise a window to the top of the stacking order.
Circulate the stacking order of children up or
down.
Circulate the bottom child to the top of the stack-
ing order.
Circulate the top child to the bottom of the stack-
ing order.
Return a list of children, parent, and root.
Change a window's parent.
Move a window.
Change a window's size.
Change the size and position of a window.
Change the border width of a window.
Change the stacking order of siblings.
Change the window position, size, border width, or
stacking order.
Window Mapping
XMapRaised
XMapSubwindows
XMapWindow
XUnmapSubwindows
XUnmapWindow
Map a window on top of its siblings.
Map all subwindows.
Map a window.
Unmap all subwindows of a given window.
Unmap a window.
Appendix A: Function Group Summary 513
Alphabetical Listing of Routines
Table A- 1. Alphabetical Listing of Routines
Routine
XActivateScreenSaver
XAddHost
XAddHosts
XAddPixel
XAddToSaveSet
XAllocColor
XAllocColorCells
XAllocColorPlanes
XAllocNamedColor
XAllowEvents
XAutoRepeatOff
XAutoRepeatOn
XBell
XChangeActivePointerGrab
XChangeGC
XChangeKeyboardControl
XChangeKeyboardMapping
XChangePointerControl
XChangeProperty
XChangeSaveSet
XChangeWindowAttributes
XCheckIfEvent
XCheckMaskEvent
XCheckTypedEvent
XCheckTypedWindowEvent
XCheckWindowEvent
XCirculateSubwindows
XCirculateSubwindowsDown
XCirculateSubwindowsUp
XClearArea
XClearWindow
XClipBox
Description
Activate screen blanking.
Add a host to the access control list.
Add multiple hosts to the access control list.
Add a constant value to every pixel value in an image.
Add a window's children to the client's save-set.
Allocate a read-only colormap cell with closest
hardware-supported color.
Allocate read/write (nonshared) colorcells.
Allocate read/write (nonshareable) color planes.
Allocate a read-only colorcell from color name.
Control the behavior of keyboard and pointer events
when these resources are grabbed.
Turn off the keyboard auto-repeat keys.
Turn on the keyboard auto-repeat keys.
Ring the bell (Control G).
Change the parameters of an active pointer grab.
Change the components of a given graphics context.
Change the keyboard preferences such as key click.
Change the keyboard mapping.
Change the pointer preferences.
Change a property associated with a window.
Add or remove a subwindow from the client's save-set.
Set window attributes.
Check the event queue for a matching event.
Remove the next event that matches mask; don't wait.
Return the next event in queue that matches event type;
don't wait.
Return the next event in queue matching type and win-
dow.
Remove the next event matching both passed window
and passed mask; don't wait.
Circulate the stacking order of children up or down.
Circulate the bottom child to the top of the stacking
order.
Circulate the top child to the bottom of the stacking
order.
Clear a rectangular area in a window.
Clear an entire window.
Generate the smallest rectangle enclosing a region.
514 Xlib Reference Manual
Table A- 1. Alphabetical Listing of Routines (continued)
Routine
XCloseDisplay
XConfigureWindow
XConvertSelection
XCopyArea
XCopyColormapAndFree
XCopyGC
XCopyPlane
XCreateAssocTable
XCreateBitmapFromData
XCreateColormap
XCreateFontCursor
XCreateGC
XCreateGlyphCursor
XCreateImage
XCreatePixmap
XCreatePixmapCursor
XCreatePixmapFrom-
BitmapData
XCreateRegion
XCreateSimpleWindow
XCreateWindow
XDefineCursor
XDeleteAssoc
XDeleteContext
XDeleteModifiermapEntry
XDeleteProperty
XDestroyAssocTable
XDestroyImage
XDestroyRegion
XDestroySubwindows
XDestroyWindow
XDisableAccessControl
XDisplayName
XDraw
XDrawArc
XDrawArcs
XDrawFilled
XDrawImageString
Description
Disconnect a client program from an X server and display.
Change the window position, size, border width, or stack-
ing order.
Use the value of a selection.
Copy an area of a drawable.
Copy a colormap and return a new colormap ID.
Copy a graphics context.
Copy a single plane of a drawable into a drawable with
depth, applying pixel values.
Create a new association table (X10).
Create a bitmap from X11 bitmap format data.
Create a colormap.
Create a cursor from the standard cursor font.
Create a new graphics context for a given screen with the
depth of the specified drawable.
Create a cursor from font glyphs.
Allocate memory for an XErrlage structure.
Create a pixmap.
Create a cursor from two bitmaps.
Create a pixmap with depth from bitmap data.
Create a new empty region.
Create an unmapped InputOutput window.
Create a window and set attributes.
Assign a cursor to a window.
Delete an entry from an association table.
Delete a context entry for a given window and type.
Delete an entry from an XModifierKeymap structure.
Delete a window property.
Free the memory allocated for an association table.
Deallocate memory associated with an image.
Deallocate storage associated with a region.
Destroy all subwindows of a window.
Unmap and destroy a window and all subwindows.
Allow access from any host.
Report the display name when connection to a display
fails.
Draw a polyline or curve between vertex list (from X10).
Draw an arc fitting inside a rectangle.
Draw multiple arcs.
Draw a filled polygon or curve from vertex list (from
XlO).
Draw 8-bit image text characters.
Appendix A: Function Group Summary 515
Table A-1. Alphabetical Listing of Routines (continued)
Routine
XDrawImageStrngl6
XDrawLine
XDrawLines
XDrawPoint
XDrawPoints
XDrawRectangle
XDrawRectangles
XDrawSegment s
XDrawSt ring
XDrawStringl6
XDrawText
XDrawTextl6
XEmptyRegion
XEnableAccessControl
XEqualRegion
XEventsQueued
XFetchBuffer
XFetchBytes
XFetchName
XFillArc
XFillArcs
XFillPolygon
XFillRectangle
XFillRectangles
XFindContext
XFlush
XForceScreenSaver
XFree
XFreeColormap
XFreeColors
XFreeCursor
XFreeExtensionList
XFreeFont
XFreeFontInfo
XFreeFontNames
XFreeFontPath
XFreeGC
XFreeModifiermap
XFreePixmap
XGContextFromGC
Description
Draw
Draw
Draw
Draw
Draw
Draw
Draw
Draw
Draw
Draw
Draw
16-bit image text characters.
a line between two points.
multiple connected lines.
a point.
multiple points.
an outline of a rectangle.
the outlines of multiple rectangles.
multiple disjoint lines.
an 8-bit text string, foreground only.
two-byte text strings.
8-bit polytext strings.
Draw 16-bit polytext strings.
Determine if a region is empty.
Use access conu'ol list to allow or deny connection requests.
Determine if two regions have the same size, offset, and
shape.
Check the number of events in the event queue.
Return data from a cut buffer.
Return data from cut buffer 0.
Get a window's name (XA_WM._NAME property).
Fill an arc.
Fill multiple arcs.
Fill a polygon.
Fill a rectangular area.
Fill multiple rectangular areas.
Get data from the context manager (not graphics context).
Flush the output buffer (display all queued requests).
Turn the screen saver on or off.
Free specified in-memory data created by an Xlib function.
Delete a colormap and install the default colormap.
Free colormap cells or planes.
Desu'oy a cursor.
Free memory allocated for a list of installed extensions to X.
Unload a font and free storage for the font structure.
Free multiple font information arrays.
Free the font name array.
Free the memory allocated by XGetFontPath.
Free a graphics context.
Desu'oy and free a keyboard modifier mapping su'ucture.
Free a pixmap ID.
Obtain the GContext (resource ID) associated with the
specified graphics context.
516 Xlib Reference Manual
Table A-1. Alphabetical Listing of Routines (continued)
Routine
XIn sertModi fiermapEnt ry
XInstallColormap
XInternAtom
XIntersectRegion
XKeycodeToKeysym
XKeysymToKeycode
XKeysymToString
XKillClient
XListExtensions
XListFonts
XListFontsWithInfo
XListHosts
XListInstalledColormaps
XListProperties
XLoadFont
XLoadQueryFont
XLookUpAssoc
XLookupColor
XLookupKeysym
XLookupString
XLowerWindow
XMakeAssoc
XMapRaised
XMapSubwindows
XMapWindow
XMaskEvent
XMatchVisualInfo
XMoveResizeWindow
XMoveWindow
XNewModifiermap
XNextEvent
XNoOp
XOffsetRegion
XOpenDisplay
XParseColor
XParseGeometry
XPeekEvent
Description
Add a new envy to an XModifierKeymap structure.
Insl a colonnap.
Return an atom for a given name string.
Compute the intersection of two regions.
Convert a keycode to a keysym.
Convert a keysym to the appropriate keycode.
Convert a keysym symbol to a string.
Destroy a client or its remaining resources.
Return a list of all extensions to X supported by the
server.
Return a list of the available font names.
Obtain the names and information about loaded fonts.
Obtain a list of hosts having access to this display.
Get a list of installed colormaps.
Get the property list for a window.
Load a font if not already loaded; get font ID.
Load a font and fill information smacture.
Obtain data from an association table.
Get database RGB values and closest hardware-supported
RGB values from color name.
Get the keysym corresponding to a keycode in structure.
Map a key event to ASCII string, keysym, and
ComposeStatus.
Lower a window in the stacking order.
Create an entry in an association table.
Map a window on top of its siblings.
Map all subwindows.
Map a window.
Remove the next event that matches mask.
Obtain the visual information that matches the desired
depth and class.
Change the size and position of a window.
Move a window.
Create a keyboard modifier mapping smacture.
Get the next event of any type or window.
Send a NoOp to exercise connection with the server.
Change offset of a region.
Connect a client program to an X server.
Look up or translate RGB values from ASCII color name
or hexadecimal value.
Generate position and size from standard window
geometry string.
Get an event without removing it from the queue.
518 Xlib Reference Manual
Table A- 1. Alphabetical Listing of Routines (continued)
Routine
XPeekIfEvent
XPending
Xpermalloc
XPointInRegion
XPolygonRegion
XPutBackEvent
XPutImage
XPutPixel
XQueryBestCursor
XQueryBestSize
XQueryBestStipple
XQueryBestTile
XQueryColor
XQueryColors
XQueryExtension
XQueryFont
XQueryKeymap
XQueryPointer
XQueryTextExtents
XQueryTextExtentsl6
XQueryTree
XRaiseWindow
XReadBitmapFile
XRebindKeysym
XRecolorCursor
XRectInRegion
XRefreshKeyboardMapping
XRemoeFromSaveSet
XRemoveHost
XRemoveHosts
XReparentWindow
XResetScreenSaver
XResizeWindow
XRestackWindows
XrmGetFileDatabase
XrmGetResource
XrmGetStringDatabase
XrmInitialize
XrmMergeDatabases
Description
Get an event without removing it from the queue; do not
wait.
Flush the output buffer and return the number of pending
input events.
Allocate memory never to be freed.
Determine if a point is inside a region.
Generate a region from points.
Push an event back on the input queue.
Draw a rectangular image on a window or pixmap.
Set a pixel value in an image.
Get the closest supported cursor sizes.
Obtain the "best" supported cursor, tile, or sdpple size.
Obtain the best supported stipple shape.
Obtain the best supported fill tile shape.
Obtain the RGB values and flags for a specified pixel
value.
Obtain RGB values for an array of pixel values.
Get extension information.
Return information about a loaded font.
Obtain a bit vector for the current state of the keyboard.
Get the current pointer location.
Query the server for string and font meu'ics.
Query the server for string and font metrics of a 16-bit
character string.
Return a list of children, parent, and root.
Raise a window to the top of the stacking order.
Read a bitmap from disk.
Rebind a keysym to a string for client.
Change the color of a cursor.
Determine if a rectangle resides in a region.
Update the stored modifier and keymap information.
Remove a window's children from the client's save-set.
Remove a host from the access control list.
Remove multiple hosts from the access control list.
Change a window's parent.
Reset the screen saver.
Change a window's size.
Change the stacking order of siblings.
Retrieve a database from a file.
Get a resource from name and class as strings.
Create a database from a string.
Initialize the resource manager.
Merge the contents of one database with another.
Appendix A: Function Group Summary 519
Table A- 1. Alphabetical Listing of Routines (continued)
Routine
XrmParseCommand
XrmPutFileDatabase
XrmPutLineResource
XrmPutResou rce
XrmPutSt ringResource
XrmQGetResource
X rmQGet SearchLi st
XrmQGet SearchRe source
XrmQPut Re source
XrmQPut St ringRe source
XrmQuarkToString
XrmStringToBindingQuarkList
XrmStringToQuark
XrmStringToQuarkList
XrmUniqueQuark
XRotateBuffers
XRotateWindowProperties
XSaveContext
XSelectInput
XSendEvent
XSetAccessControl
XSetAfterFunction
XSetArcMode
XSetBackground
XSetClassHint
XSetClipMask
XSetClipOrigin
XSetClipRectangles
XSetCloseDownMode
XSetCommand
XSetDashes
XSetErrorHandler
XSetFillRule
XSetFillStyle
XSetFont
Description
Load a resource database from command line argu-
ments.
Store a database in a file.
Add a resource entry given as a string of name and
value.
Store a resource into a database.
Add a resource that is specified as a string.
Get a resource from name and class as quarks.
Return a list of database levels.
Search resource database levels for a given resource.
Store a resource into a database using quarks.
Add a string resource value to a database using
quarks.
Convert a quark to a string.
Convert a key string to a binding list and a quark
list.
Convert a string to a quark.
Convert a key string to a quark list.
Allocate a new quark.
Rotate the cut buffers.
Rotate properties in the properties array.
Save a data value corresponding to a window and
context type (not graphics context).
Select the event types to be sent to a window.
Send an event.
Disable or enable access control.
Set a function called after all Xlib functions.
Set the arc mode in a graphics context.
Set the background pixel value in a graphics context.
Set the XA_WM_CLASS property of a window.
Set clip_mask pixmap in a graphics context.
Set the clip origin in a graphics context.
Change clip_mask in a graphics context to the
list of rectangles.
Change the close down mode of a client.
Set the XA_WM_COMMAND atom (command line
arguments).
Set dash_offset and dashes (for lines) in a
graphics context.
Set a nonfatal error event handler.
Set the fill rule in a graphics context.
Set the fill style in a graphics context.
Set the current font in a graphics context.
520 Xlib Reference Manual
Table A- 1. Alphabetical Listing of Routines (continued)
Routine
XSetFontPath
XSetForeground
XSetFunction
XSetGraphicsExposures
XSetIconName
XSetIconSizes
XSetInputFocus
XSetIOErrorHandler
XSetLineAttributes
XSetModifierMapping
XSetNormalHints
XSetPlaneMask
XSetPointerMapping
XSetRegion
XSetScreenSaver
XSetSelectionOwner
XSetSizeHints
XSetStandardColormap
XSetStandardProperties
XSetState
XSetStipple
XSetSubwindowMode
XSetTile
XSetTransientForHint
XSetTSOrigin
XSetWindowBackground
XSetWindowBackgroundPixmap
XSetWindowBorder
XSetWindowBorderPixmap
XSetWindowBorderWidth
XSetWindowColormap
XSetWMHints
XSetZoomHints
Description
Set the font search path.
Set the foreground pixel value in a graphics context.
Set the bitwise logical operation in a graphics context.
Set graphics_exposures a graphics context.
Set the name to be displayed in a window's icon.
Set the value of the xA WM TCON STZ. property.
Set the keyboard focus window.
Handle fatal I/O errors.
Set the line drawing components in a graphics context.
Set keycodes to be used as modifiers (Shift, Control,
etc.).
Set the size hints property of a window in normal state
(not zoomed or iconified).
Set the plane mask in a graphics context.
Set the pointer button mapping.
Set clip_mask of the graphics context to the
specified region.
Set the parameters of the screen saver.
Set the owner of a selection.
Set the value of any property of type
XA WM SIZE HINTS.
Change the standard colormap property.
Set the minimum set of properties for the window
manager.
Set the foreground, background, logical function, and
plane mask in a graphics context.
Set the stipple in a graphics context.
Set the subwindow mode in a graphics context.
Set the fill tile in a graphics context.
Set the XA WM TRANSIENT FOR property of a win-
dow.
Set the tile/stipple origin in a graphics context.
Set the background pixel attribute of a window.
Change the background tile attribute of a window.
Change a window border attribute to the specified
pixel value and repaint the border.
Change a window border tile attribute and repaint the
border.
Change the border width of a window.
Set the colormap for a specified window.
Set a window manager hints property.
Set the size hints property of a zoomed window.
Appendix A: Function Group Summary 521
Table A-1. Alphabetical Listing of Routines (continued)
Routine
XShrinkRegion
XStoreBuffer
XStoreBytes
XStoreColor
XStoreColors
XStoreName
XStoreNamedColor
XStringToKeysym
XSubImage
XSubtractRegion
XSync
XSynchronize
XTextExtents
XTextExtentsl6
XTextWidth
XTextWidthl6
XTranslateCoordinates
XUndefineCursor
XUngrabButton
XUngrabKey
XUngrabKeyboard
XUngrabPointer
XUngrabServer
XUninstallColormap
XUnionRectWithRegion
XUnionRegion
XUniqueContext
XUnloadFont
XUnmapSubwindows
XUnmapWindow
XWarpPointer
XWindowEvent
XWriteBitmapFile
XXorRegion
Description
Reduce or expand the size of a region.
Store data in a cut buffer.
S tore data in cut buffer 0.
Set or change a read/write entry of a colormap to the
closest available hardware color.
Set or change read/write colorcells to the closest avail-
able hardware colors.
Assign a name to a window for the window manager.
Allocate a read/write colorcell by English color name.
Convert a keysym name string to a keysym.
Create a subimage from part of an image.
Subtract one region from another.
Flush the output buffer and wait for all events and errors
to be processed by the server.
Enable or disable synchronization for debugging.
Get string and font metrics.
Get string and font metrics of a 16-bit character string.
Get the width in pixcls of an 8-bit character string.
Get the width in pixels of a 16-bit character string.
Change the coordinate system from one window to
another.
Disassociate a cursor from a window.
Release a button from grab.
Release a key from grab.
Release the keyboard from grab.
Release the pointer from grab.
Release the server from grab.
Uninstall a colormap; install default if not already
installed.
Add a rectangle to a region.
Compute the union of two regions.
Create a new context ID (not graphics context).
Unload a font.
Unmap all subwindows of a given window.
Unmap a window.
Move the pointer to another point on the screen.
Remove the next event matching mask and window.
Write a bitmap to a file.
Calculate the difference between the union and intersec-
tion of two regions.
522 Xlib Reference Manual
B
Error Messages and Protocol Requests
This appendix contains two tables: Table B-1 describes the standard error ctdes (the
error code member of XErrorEvent) and what causes them, and Table B-2 describes
--
the mapping between protocol requests and Xlib functions. Each reference page in this
volume describes in more detail the errors that may occur because of that Xlib routine.
Volume One, Chapter 3, Basic Window Program, describes the handling of errors in gen-
eral.
A protocol request is the actual network message that is sent from Xlib to the server. Many
convenience functions are provided in Xlib to make programs easier to write and more read-
able. When any one of several convenience routines is called it will be translated into one
type of protocol request. For example, XMoveWindow and XResizeWindow are con-
venience routines for the more general XConfigureWindow. Both of these Xlib routines
use the protocol request X_ConfigureWindow. The protocol request that causes an error,
along with other information about the error is printed to the standard error output by the
default error handlers. In order to find out where in your code the error ocurred, you will
need to know what Xlib function to look for. Use Table B-2 to find this function.
Xlib functions that do not appear in Table B-2 do not generate protocol requests. They per-
form their function without affecting the display and without requiting information from the
server. If errors can occur in them, the errors are reported in the returned value.
Table B- 1. Error Messages
Error Codes
BadAccess
BadAlloc
Possible Cause
Client attempted to grab a key/button combination that is already
grabbed by another client.
Client attempted to free a colormap entry that is not allocated by the
client.
Client attempted to store into a read-only colormap entry.
Client attempted to modify the access conuol list from other than the
local (or otherwise authorized) host.
Client attempted to select an event type that only one client can select at
a time, when another client has already selected it.
The server failed to allocate the requested resource.
Appendix B: Error Messages and Protocol Requests 523
Table B-1. Error Messages (continued)
Error Codes:
BadAtom
BadColor
BadCursor
BadDrawable
BadFont
BadGC
BadIDChoice
BadImplemen
-tation
BadLength
BadMatch
BadName
BadPixmap
BadRequest
BadValue
BadWindow
Possible Cause
A value for an Atom argument does not name a defined Atom.
A value for a Colormap argument does not name a defined Color-
map.
A value for a Cursor argument does not name a defined Cursor.
A value for a Drawable argument does not name a defined Window
or P ixmap.
A value for a Font or GContext argument does not name a defined
Font.
A value for a GContext argument does not name a defined GCon-
text.
The value chosen for a resource identifier is either not included in the
range assigned to the client, or is already in use.
The server does not implement some aspect of the request. A server
that generates this error for a core request is deficient. Clients should
be prepared to receive such errors and either handle or discard them.
The length of a request is shorter or longer than that required to
minimally contain the arguments. This usually indicates an internal
Xlib error.
An InputOnly window is used as a Drawable.
Some argument (or pair of arguments) has the correct type and range,
but fails to "match" in some other way required by the request.
A font or color of the specified name does not exist.
A value for a pixmap argument does not name a defined pixmap.
The major or minor opcode does not specify a valid request.
Some numeric value falls outside the range of values accepted by the
request. Unless a specific range is specified for an argument, the full
range defined by the argument's type is accepted. Any argument
defined as a set of alternatives can generate this error.
A value for a Window argument does not name a defined Window.
The BadAtom, BadColor, BadCursor, BadDrawable, BadFont, BadGC, Bad-
Pixmap, and BadWindow errors are also used when the argument type should be among a
set of fixed alternatives (for example, a window ID, PointerRoot, or None) and some
other constant or variable is used.
524 Xlib Reference Manual
Table B-2. Xlib Functions and Protocol Requests
Protocol Request
X_AllocColor
X_AllocColorCells
X_AllocColorPlanes
X_AllocNamedColor
X_AllowEvents
X_Bell
X_ChangeActivePointerGrab
X_ChangeGC
X_ChangeHosts
X_ChargeKeyboardControl "
X_ChangeKeyboardMapping
X_ChangePointerControl
X_ChangeProperty
Xlib Function
XAllocColor
XAllocColorCells
XAllocColorPlanes
XAllocNamedColor
XAllowEvents
XBell
XChangeActivePointerGrab
XChangeGC
XSetArcMode
XSetBackground
XSetClipMask
XSetClipOrigin
XSetFillRule
XSetFillStyle
XSetFont
XSetForeground
XSetFunction
XSetGraphicsExposures
XSetLineAttributes
XSetPlaneMask
XSetState
XSetStipple
XSetSubwindowMode
XSetTile
XSetTSOrigin
XAddHost
XAddHosts
XRemoveHost
XRemoveHosts
XAutoRepeatOff
XAutoRepeatOn
XChangeKeyboardControl
XChangeKeyboardMapping
XChangePointerControl
XChangeProperty
XSetCommand
XSetIconSizes
XSetIconWindow
XSetNormalHints
XSetResizeHint
XSetSizeHints
Appendix B: Error Messages and Protocol Requests 525
Table B-2. Xlib Functions and Protocol Requests (continued)
Protocol Request
X_ChangeSaveSet
X_ChangeWindowAtu'ibutes
X_CirculateWindow
X_ClearArea
X_CloseFont
X_ConfigureWindow
X_ConvertSelection
X_CopyArea
X_CopyColormapAndFree
X_CopyGC
X_CopyPlane
X_CreateColormap
X_CreateCursor
Xlib Function
XSet St anda rdP rope rt ie s
XSetWMHint s
XSetZoomHint s
XStoreBuffer
XStoreBytes
XStoreName
XAddToSaveSet
XChangeSaveSet
XRemoveFromSaveSet
XChangeWindowAttributes
XDefineCursor
XSelectInput
XSetWindowBackground
XSetWindowBackgroundPixmap
XSetWindowBorder
XSetWindowBorderPixmap
XSetWindowColormap
XUndefineCursor
XCirculateSubwindows
XCirculateSubwindowsDown
XCirculateSubwindowsUp
XClearArea
XClearWindow
XFreeFont
XUnloadFont
XConfigureWindow
XLowerWindow
XMapRaised
XMoveResizeWindow
XMoveWindow
XRaiseWindow
XResizeWindow
XRestackWindows
XSetWindowBorderWidth
XConvertSelection
XCopyArea
XCopyColormapAndFree
XCopyGC
XCopyPlane
XCreateColormap
XCreatePixmapCursor
526 Xlib Reference Manual
Table B-2. Xlib Functions and Protocol Requests (continued)
Protocol Request
X_CreateGC
X_CreateGlyphCursor
X_CreatePixmap
X_CreateWindow
X_DeleteProperty
X_DestroySubwindows
X_DestroyWindow
X_FillPoly
X_ForceScreenSaver
X_FreeColormap
X_FreeColors
X_FreeCursor
X_FreeGC
X_FreePixmap
X_GetAtomName
X_GetFontPath
X_GetGeometry
X_GetImage
X_GetInputFocus
X_GetKeyboardControl
X_GetKeyboardMapping
X_GetModifierMapping
X_GetMotionEvents
X_GetPointerControl
X_GetPointerMapping
X_GetProperty
Xlib Function
XCreateGC
XOpen D i splay
XCreateFontCursor
XCreateGlyphCu rsor
XCreatePixmap
XC reat eS impl eWin dow
XCreateWindow
XDeleteProperty
XDestroySubwindows
XDestroyWindow
XFillPolygon
XAct ivateScreenSaver
XForceScreenSaver
XResetScreenSaver
XFreeColormap
XFreeColors
XFreeCursor
XFreeGC
XFreePixmap
XGetAt omName
XGetFontPath
XGetGeomet ry
XGetWindowAt t ribut es
XGet Image
XGet InputFocus
XSync
XGetKeyboardCont rol
XGetKeyboardMapping
XGet Mo di f i e rMappi n g
XGet Mot i onEvent s
XGetPointerControl
XGetPonterMapping
XClearIconWindow
XFet chByt e s
Appendix B: Error Messages and Protocol Requests 527
Table B-2. Xlib Functions and Protocol Requests (continued)
Protocol Request
X_GetScreenSaver
X_GetSelectionOwner
X_GetWindowAtibutes
X_GrabButton
X_GrabKey
X_GrabKeyboard
X_GrabPointer
X_GrabServer
X_ImageText8
X_ImageTextl6
X_InstallColormap
X_InternAtom
X_KillClient
X_ListExtensions
X_ListFonts
X_ListFontsWithI.fo
X_ListHosts
X_ListInstalledColormaps
X_ListProperties
X_LookupColor
X_MapSubwindows
X_MapWindow
X_NoOperation
X_OpenFont
Xlib Function
XFetchName
XGetIconSizes
XGetIconWindow
XGetNormalHints
XGetSizeHints
XGetWindowProperty
XGetWMHints
XGetZoomHints
XGetScreenSaver
XGetSelectionOwner
XGetWindowAttributes
XGrabButton
XGrabKey
XGrabKeyboard
XGrabPointer
XGrabServer
XDrawImageString
XDrawImageStringl6
XInstallColormap
XInternAtom
XKillClient
XListExtensions
XListFonts
XListFontsWithInfo
XListHosts
XListInstalledColormaps
XListProperties
XLookupColor
XParseColor
XMapSubwindows
XMapRaised
XMapWindow
XNoOp
XLoadFont
XLoadQueryFont
528
Xlib Reference Manual
Table B-2. Xlib Functions and Protocol Requests (continued)
Protocol Request
X_PolyArc
X_PolyFillArc
X_PolyFillRectangle
X_PolyLine
X_PolyPoint
X_PolyRectangle
X_PolySegment
X_PolyText8
X_PolyTextl6
X_PutImage
X_QueryBestSize
X_QueryColors
X_QueryExtension
X_QuerFont
X_QueryKeymap
X_QueryPointer
X_QueryTextExtents
X_QueryTree
X_RecolorCursor
X_ReparentWindow
X_RotateProperties
Xlib Function
XDrawArc
XDrawArcs
XFillArc
XFillArcs
XFillRectangle
XFillRectangles
XDrawLines
XDrawPoint
XDrawPoints
XDrawRectangle
XDrawRectangles
XDrawLine
XDrawSegments
XDrawString
XDrawText
XDrawStringl6
XDrawTextl6
XPutImage
XQueryBestCursor
XQueryBestSize
XQueryBestStipple
XQueryBestTile
XQueryColor
XQueryColors
XInitExtension
XQueryExtension
XLoadQueryFont
XQueryKeymap
XQueryPointer
XQueryTextExtents
XQueryTextExtentsl6
XQueryTree
XRecolorCursor
XReparentWindow
XRotateBuffers
XRotateWindowProperties
Appendix B: Error Messages and Protocol Requests 529
Table B-2. Xlib Functions and Protocol Requests (continued)
Protocol Request
X_SendEvent
X_S etAccessControl
X_S etClipRectangles
X_SetCloseDownMode
X_SetDashes
X_SetFontPath
X_SetlnputFocus
X_SetModifierMapping
X_SetPointerMapping
X_SetScreenSaver
X_S etSelectionOwner
X_StoreColors
X_StoreNamedColor
X_TranslateCoords
X_UngrabButton
X_UngrabKey
X_UngrabKeyboard
X_UngrabPointer
X_UngrabServer
X_UninstallColormap
X_UnmapSubwindows
X_UnmapWindow
X_WarpPointer
Xlib Function
XSendEvent
XDisableAccessControl
XEnableAccessControl
XSetAccessControl
XSetClipRectangles
XSetCloseDownMode
XSetDashes
XSetFontPath
XSetInputFocus
XSetModifierMapping
XSetPointerMapping
XSetScreenSaver
XSetSelectionOwner
XStoreColor
XStoreColors
XStoreNamedColor
XTranslateCoordinates
XUngrabButton
XUngrabKey
XUngrabKeyboard
XUngrabPointer
XUngrabServer
XUninstallColormap
XUnmapSubWindows
XUnmapWindow
XWarpPointer
530 Xlib Reference Manual
D e f au it Co 1 o rmap ( di spl ay, s cr_n urn)
DefaultColormapOfScreen(scr_pnt)
DefaultDepth(di splay, scr_num)
DefaultDepthOfScreen(scr_pnt)
DefaultGC(display, scr_num)
DefaultGCOfScreen(scr_pnt)
DefaultRootWindow(display)
DefaultScreen(display)
Default ScreenOfDi splay(di splay)
DefaultVisual(display, scr_num)
DefaultVisualOfScreen(scr_pnt)
DisplayCells(display, scr_num)
D i s pl ayHe i ght ( di spl ay, s cr_n urn)
DisplayHeightMM(display, scr_num)
Return the default colormap for the specified
screen. Most routine allocations of color should
be made out of this colormap.
Return the default colormap of the specified
screen.
Return the depth (number of planes) of the root
window for the specified screen. Other depths
may also be supported on this screen. See
Volume One, Chapter 7, Color, or the reference
pages for XMatchVisualInfo and XGet-
VisualInfo to find out how to determine
what depths are available.
Return the default depth of the specified screen.
Return the default graphics context for the
specified screen.
Return the default graphics context (GC) of the
specified screen.
Return the ID of the root window on the default
screen. Most applications should use Root-
Window instead so that screen selection is sup-
ported.
Return the integer that was specified in the last
segment of the string passed to XOpen-
Display, or from the DISPLAY environment
variable if NULL was used. For example, if the
DISPLAY environment were Ogre : 0.1 then
DefaultScreen would return 1.
Return the default screen of the specified
display.
Return a pointer to the default visual structure
for the specified screen.
Return the default visual of the specified screen.
Return the maximum possible number of color-
map cells on the specified screen. This macro is
misnamed: it should have been ScreenCells.
Return the height in pixels of the screen. This
macro is misnamed: it should have been
ScreenHeight.
Return the height in millimeters of the specified
screen. This macro is misnamed: it should have
been S c reenHeightMM.
532 Xlib Reference Manual
I s Modi f i e rK ey (k eysym)
I sPFKey(keysym)
Return T rue if the keysym represents a modifier key.
Return T rue if the keysym represents a PF key.
Resource Manager Macros
These macros convert from strings to quarks and quarks to strings. They are used by the
resource manager. Note that they do not follow the normal naming conventions for macros,
since they begin with an X.
XrmSt ringToName (string)
XrmSt ringToCla s s (string)
XrmStringToRepresentation
(string)
XrmNameToSt ring (name)
XrmClassToString(class)
XrmRepresentationToString
(type)
Convert sng to XrmName. Same XStringTo-
Quark.
Convertsngto XrmClass. Same XStringTo-
Quark.
Convert sng XrmRepresentation. Same
XStringToQuark.
Convert XrmName sng. Same XrmQuarkTo-
String.
Convt xrmClass sng. Same XrmQuark-
ToString.
Convert XrmRepresentation to sng. Same
XrmQuarkToString.
536 Xhb Reference Manual
D
The Color Database
The color database is used by XParseColor, XLookupColor, and XStoreNamed-
Color. These routines make it easier to allow the user to specify color names. Use of
these names for routine color allocation of read-only colorcells is encouraged since this
increases the chance of sharing colorcells and thereby makes the colormap go further before
running out of colorcells. The location in the file system of the text version of the color
database is an implementation detail, but by default on a UNIX system it is
/usr/lib/X1 l /rgb.txt.
It should be noted that while these color names are present in the standard X 11 distribution,
they are not specified by the Xll Protocol or Xlib. Therefore, it is permissible for server
vendors to change the color names, though most will probably only add colors rather than
take them away. Furthermore, hardware vendors must change the RGB values for each
display hardware to achieve the proper "gamma correction" so that the colors described by
the name really generate that color. The RGB values in the standard file are for the DEC
VR290 display. The color that appears on a Sun system given these RGB values for
"pink," for example, looks more like light burgundy.
Each color in Table D-1 (see next page) may be used in the form shown or in mixed case,
with initial capitals and all spaces eliminated.
Appendix D: Colors 537
E
Event Reference
This appendix describes each event structure in detail and briefly shows how each event
type is used. It covers the most common uses of each event type, the information contained
in each event structure, how the event is selected, and the side effects of the event, if any.
Each event is described on a separate reference page.
Table E-1 lists each event mask, its associated event types, and the associated structure
definition. See Volume One, Chapter 8, Events for more information on events.
Table E-1. Event Masks, Event Types, and Event Structures
Event Mask
KeyPressMask
KeyReleaseMask
ButtonPressMask
ButtonReleaseMask
OwnerGrabButtonMask
KeymapStateMask
PointerMotionMask
PointerMotionHintMask
ButtonMotionMask
ButtonlMotionMask
Button2MotionMask
Button3MotionMask
Button4MotionMask
Button5MotionMask
Event Type
KeyP re s s
KeyRelease
ButtonPress
ButtonRelease
n/a
Keyma pNot i fy
Mot ionNot i fy
S tructure
XKeyPressedEvent
XKeyReleasedEvent
XButtonPressedEvent
XButtonReleasedEvent
n
XKeymapEvent
XPointerMovedEvent
EnterWindowMask
LeaveWindowMask
FocusChangeMask
ExposureMask
EnterNotify
LeaveNotify
FocusIn
FocusOut
Expose
XEnterWindowEvent
XLeaveWindowEvent
XFocusInEvent
XFocusOutEvent
XExposeEvent
Appendix E: Event Reference 539
Table E-1. Event Masks, Event Types, and Event Structures (continued)
Event Mask
selected GC by
graphics_expose member)
ColormapChangeMask
PropertyChangeMask
VisibilityChangeMask
ResizeRedirectMask
StructureNotifyMask
SubstructureNotifyMask
SubstructureRedirectMask
(always selected)
(always selected)
(always selected)
(always selected)
(always selected)
Event Type
GraphicsExpose
NoExpose
ColormapNotify
PropertyNotify
VisibilityNotify
ResizeRequest
CirculateNotify
ConfigureNotify
DestroyNotify
GravityNotify
MapNotify
ReparentNotify
UnmapNotify
CirculateNotify
ConfigureNotify
CreateNotify
DestroyNotify
GravityNotify
MapNotify
ReparentNotify
UnmapNotify
CirculateRequest
ConfigureRequest
MapRequest
MappingNotify
ClientMessage
SelectionClear
SelectionNotify
SelectionRequest
Structure
XGraphicsExposeEvent
XNoExposeEvent
XColormapEvent
XP rope rt yEvent
XVisibilityEvent
XResizeRequestEvent
XCirculateEvent
XConfigureEvent
XDestroyWindowEvent
XGravityEvent
XMapEvent
XReparentEvent
XUnmapEvent
XCirculateEvent
XConfigureEvent
XCreateWindowEvent
XDestroyWindowEvent
XGravityEvent
XMapEvent
XReparentEvent
XUnmapEvent
XCirculateRequestEvent
XConfigureRequestEvent
XMapRequestEvent
XMappingEvent
XClientMessageEvent
XSetSelectClearEvent
XSelectionEvent
XSelectionRequestEvent
540
Xlib Reference Manual
Meaning of Common Structure Elements
Example E-1 shows the XEvent union and a simple event structure that is one member of
the union. Several of the members of this structure are present in nearly every event struc-
ture. They are described here before we go into the event-specific members (see also
Volume One, Section 8.2.2).
Example E- 1. XEvent union and XAnyEvent structure
typedef union XEvent {
int type; /* must not be changed; first member */
XAnyEvent xany;
XButtonEvent xbutton;
XCirculateEvent xcirculate;
XCirculateRequestEvent xcirculaterequest;
XClientMessageEvent xclient;
XColormapEvent xcolormap;
XConfigureEvent xconfigure;
XConfigureRequestEvent xconfigurerequest;
XCreateWindowEvent xcreatewindow;
XDestroyWindowEvent xdestroywindow;
XCrossingEvent xcrossing;
XExposeEvent xexpose;
XFocusChangeEvent xfocus;
XNoExposeEvent xnoexpose;
XGraphicsExposeEvent xgraphicsexpose;
XGravityEvent xgravity;
XKeymapEvent xkeymap;
XKeyEvent xkey;
XMapEvent xmap;
XUnmapEvent xunmap;
XMappingEvent xmapping;
XMapRequestEvent xmaprequest;
XMotionEvent xmotion;
XPropertyEvent xproperty;
XReparentEvent xreparent;
XResizeRequestEvent xresizerequest;
XSelectionClearEvent xselectionclear;
XSelectionEvent xselection;
XelectionRequestEvent xselectionrequest;
XVisibilityEvent xisibility;
} XEvent;
typedef struct {
int type;
unsigned long serial;/* # of last request processed by server */
Bool send event; /* true if this came from SendEvent request */
Display *display; /* display the event was read from */
Window window; /* window on which event was requested in
* event mask */
} XAnyEvent;
Appendix E: Event Reference 541
The first member of the XEvent union is the type of event. When an event is received
(with XNextEvent, for example), the application checks the type member in the
XEvent union. Then the specific event type is known, and the specific event structure
(such as xbutton) is used to access information specific to that event type.
Before the branching depending on the event type, only the XEvent union is used. After
the branching, only the event structure which contains the specific information for each
event type should be used in each branch. For example, if the XEvent union were called
report, the report, xexpose structure should be used within the branch for Expose
events.
You'll notice that each event structure also begins with a type member. This member is
rarely used, since it is an identical copy of the type member in the XEvent union.
Most event structures also have a window member. The only ones that don't are selection
events (SelectionNotify, SelectionRequest, and SelectionClear) and
events selected by the graphics_exposures member of the GC (GraphicsExpose
and NoExpose). The window member indicates the event window that selected and
received the event. This is the window where the event arrives if it has propagated through
the hierarchy as described in Volume One, Section 8.3.2. One event type may have two
different meanings to an application, depending on which window it appears in.
Many of the event structures also have a display and/or root member. The display
member identifies the connection to the server that is active. The root member indicates
which screen the window that received the event is linked to in the hierarchy. Most pro-
grams only use a single screen and therefore don't need to worry about the root member.
The display member can be useful since you can pass the display variable into routines
by simply passing a pointer to the event structure, eliminating the need for a separate
display argument.
All event structures include a serial member, that gives the number of the last protocol
request processed by the server. This is useful in debugging, since an error can be detected
by the server but not reported to the user (or programmer) until the next routine that gets an
event. That means several routines may execute successfully after the error occurs. The last
request processed will often indicate the request that contained the error.
All event structures also include a send_event flag, which if True indicates that the
event was sent by XSendEvent (i.e., by another client rather than by the server).
The following pages describe each event type in detail. The events are presented in alpha-
betical order, each on a separate page. Each page describes the circumstances under which
the event is generated, the mask used to select it, the structure itself, its members, and useful
programming notes. Note that the description of the structure members does not include
those members common to many structures. If you need more information on these
members, please refer to this introductory section.
542 Xlib Reference Manual
CirculateRequest
xcirculaterequest--
When Generated
CirculateRequest events report when another client calls XCirculateSubwindows,
XCirculateSubwindowsUp or XCirculateSubwindowsDown for a specified parent
window, and the stacking order is actually changed. If this event type is selected, the window
is not moved in the stacking order. This gives the client that selects this event (usually the
window manager) the opportunity to review the request in the light of its window management
policy, before executing the circulate request itself, or deny the request.
Select With
This event type is selected for the parent window with the SubstructureRedirectMask.
XEvent Structure Name
typedef union XEvent {
--
.oo
XCirculateRequestEvent xcirculaterequest;
o o .
} XEvent;
Event Structure
typedef struct {
int type;
unsigned long serial;/* # of last request processed by server */
Bool send_event; /* true if this came from SendEvent request */
Display *display; /* display the event was read from */
Window parent;
Window window;
int place; /* PlaceOnTop, PlaceOnBottom */
} XCirculateRequestEvent;
Event Structure Members
pa rent The parent of the window that was restacked. This is the window that selected the
event.
window The window being restacked.
place PlaceOnTop or PlaceOnBottom. Indicates whether the window was to be
placed on top or on the bottom of the stacking order.
546 Xhb Reference Manual
EnterNotify, LeaveNotify (continued) xcrossing
Table E-2 shows the event types generated by a pointer crossing from window A to window B
when window C is the least common ancestor of A and B.
Table E-2. Border Crossing Events and Window Relationship
LeaveNotify
Origin window (A)
Windows between A and B
exclusive if A is inferior
Windows between A and C
exclusive
Root window on screen of
origin if different from
screen of destination
EnterNotify
Destination window (B)
Windows between A and B exclusive if B is inferior
Windows between B and C exclusive
Root window on screen of destination if different
from screen of origin
Table E-3 lists the detail members in events generated by a pointer crossing from window
A to window B.
Table E-3. Event detail Member and Window Relationship
detail Fla
NotifyAncestor
NotifyInferior
NotifyVirtual
NotifyNonlinear
NotifyNonlinearVirtual
Window Delivered To
Origin or destination when either is descendant
Origin or destination when either is ancestor
Windows between A and B exclusive if either is des-
cendant
Origin and destination when A and B are two or
more windows distant from least common ancestor
C
Windows between A and C exclusive and between B
and C exclusive when A and B have least common
ancestor C. Also on both root windows if A and B
are on different screens.
558 Xlib Reference Manual
xcrossing (continued) EnterNotify, LeaveNotify
For example, Figure E-1 shows the events that are generated by a movement from a window
(window A) to a child (window B1) of a sibling (window B). This would generate three
events: a LeaveNotify with detail NotifyNonlinear for the window A, an EnterNo-
tify with detail NotifyNonlinearVirtual for its sibling window B, and an Enter-
Notify with detail NotifyNonlinear for the child (window BI).
RootWindow
(no event)
A
LeaveNotify event with
detail NotifyNonlinear
AI
no event
EnterNotify event with
ietail Not i fyNonlinearVirtual
LeaveNotify event with
detail Not ifyNonlinear
Figure E-1. Events generated by a move between windows
EnterNotify and LeaveNotify events are also generated when the pointer is grabbed, if
the pointer was not already inside the grabbing window. In this case, the grabbing window
receives an EnterNot i fy and the window containing the pointer receives a LeaveNot i fy
event, both with mode NotifyUngrab. The pointer position in both events is the position
before the grab. The result when the grab is released is exactly the same except that the two
windows receive Ente rNot i fy instead of LeaveNot i fy and vice versa.
Appendix E: Event Reference 559
EnterNotify, LeaveNotify (continued) xcrossing
Figure E-2 demonstrates the events and details caused by various pointer transitions, indicated
by heavy arrows.
Notify
:.ferxor '! -- _ _ Inferl*
Root of A Root of B
Y_
=r
Figure E-2. Border crossing events and detail member for pointer movement
from window A to window B, for various window relationships
56O
Xlib Reference Manual
Expose (continued) xexpose
The last event to arrive is indicated by a count of 0. In Release 2, XUnionRectWith-
Region can be used to add the rectangle in Expose events to a region before calling XSet-
Region.
If your application is able to redraw partial windows, you can also read each exposure event in
turn and redraw each area.
562
Xlib Reference Manual
Focusln, FocusOut (continued) xfocus
Table E-5 lists the detail members in events generated by a focus transition from window A
to window B, with P being the window containing the pointer.
Table E-5. Event detail Member and Window Relationship
detail ag
NotifyAncestor
Notifylnferior
NotifyVirtual
NotifyNonlinear
NotifyNonlinearVirtual
NotifyPointer
NotifyPointerRoot
NotifyNone
Window Delivered To
Origin or destination when either is descendant
Origin or destination when either is ancestor
Windows between A and B exclusive if either is des-
cendant
Origin and destination when A and B are two or
more windows distant from least common ancestor
C
Windows between A and C exclusive and between B
and C exclusive when A and B have least common
ancestor C. Also on both root windows if A and B
are on different screens
Window P and windows up to but not including the
origin or destination windows
Window P and all windows up to its root, and all
other roots, when focus is set to or from Pointer-
Root
All roots, when focus is set to or from None
The following two pages show all the possible combinations of focus transitions and of origin,
destination, and pointer windows and shows the types of events that are generated and their
detail member. Solid lines indicate branches of the hierarchy. Dotted arrows indicate the
direction of transition of the focus. At each end of this arrow are the origin and destination
windows, windows A to B. Arrows ending in a bar indicate that the event type and detail
described are delivered to all windows up to the bar.
In any branch, there may be windows that are not shown. Windows in a single branch
between two boxes shown will get the event types and details shown beside the branch.
566 Xlib Reference Manual
--xgravity
GravityNotify
When Generated
GravityNotify events report when a window is moved because of a change in the size of
its parent. This happens when the win_gravity attribute of the child window is something
other than StaticGravity or UnraapGravity.
Select With
To receive this event type for a single window, specify the window ID of that window and use
StructureNotifyMask as pa of the event_mask argument to XSelectInput. To
receive notification of movement due to gravity for a group of siblings, specify the parent win-
dow ID and use SubstructureNotifyMask.
XEvent Structure Name
typedef union XEvent {
XGravityEvent xgravity;
o . o
} XEvent;
Event Structure
typedef struct {
int type;
unsigned long serial;/* # of last request processed by server */
Bool send event;
Display *display;
Window event;
Window window;
int x, y;
} XGravityEvent;
/* true if this came from SendEvent request */
/* display the event was read from */
Event Structure Members
event The window that selected the event.
winow The window that was moved.
x, y The new coordinates of the window relative to its parent
Appendix E: Event Reference 571
MapNotify, UnmapNotify (continued) xmap, xunmap
from_configure (XUnmapEvent only)
True the event was generated as a result of a resizing of the window's parent
when the window itself had a win_gravity of UnmapGravity. See the
description of the win_gravity attribute in Volume One, Section 4.3.4.
False otherwise.
576
Xlib Reference Manual
MappingNotify (continued) xmapping
first_keycode
If the request member is MappingKeyboard or MappingModifier, then
first_keycode indicates the first in a range of keycodes with altered map-
pings. Otherwise it is not set.
count
If the request member is MappingKeyboard or MappingModifier, then
count indicates the number of keycodes with altered mappings. Otherwise it is
not set.
Notes
If the request member is MappingKeyboa rd, clients should call XRe f re shKeyboa rd-
Mapping.
The normal response to a request member of MappingPointer or MappingModifier
is no action. This is because the clients should use the logical mapping of the buttons and
modifiers to allow the user to customize the keyboard if desired. If the application requires a
particular mapping regardless of the user's prefcrences, it should call XGetModifierMap-
ping or XGetPointerMapping to find out about the new mapping.
578
Xlib Reference Manual
xmotion (continued) MotionNotify
When active button grabs and pointer grabs are in effect (see Volume One, Sec-
tion 9.4), the coordinates relative to the receiving window may not be within
the window (they may be negative or greater than window height or width).
x_root, y_root
The pointer coordinates relative to the root window which is an ancestor of the
event window. If the pointer was on a different screen, these are zero.
state The state of all the buttons and modifier keys just before the event, represented
by a mask of the button and modifier key symbols: ButtonlMask,
Button2Mask, Button3Mask, Button4Mask, Button5Mask, Shift-
Mask, ControlMask, LockMask, ModlMask, Mod2Mask, Mod3Mask,
Mod4Mask, and Mod5Mask.
is hint Either the constant NotifyNormal or NotifyHint. NotifyHint indi-
cates that the PointerMotionHintMask was selected. In this case, just
one event is sent when the mouse moves, and the current position can be found
by calling XQueryPointer, or by examining the motion history buffer with
XGetMotionEvents, if a motion history buffer is available on the server.
NotifyNormal indicates that the event is real, but it may not be up to date
since there may be many more later motion events on the queue.
same screen
--
Indicates whether the pointer is currently on the same screen as this window.
This is always True unless the pointer was actively grabbed before the
automatic grab could take place.
Notes
If the processing you have to do for every motion event is fast, you can probably handle all of
them without requiring motion hints. However, if you have extensive processing to do for
each one, you might be better off using the hints and calling XQueryPointer or using the
history buffer if it exists. XQueryPointer is a round-trip request, so it can be slow.
EnterNotify and LeaveNotify events are generated instead of MotionEvents if the
poin{er starts and stops in different windows.
Appendix E: Event Reference 581
xvisibility (continued) VisibilityNotify
Table E-6. The State Element of the XVisibilityEvent Structure
Visibility Status Before
Partially obscured,
fully obscured,
or not viewable
Viewable and
completely unobscured,
or not viewable
Viewable and
completely unobscured,
or viewable and
partially obscured,
or not viewable
Visibility Status After
Viewable and com-
pletely unobscured
Viewable and partially
obscured
Viewable and partially
obscured
State Member
Visibility-
Unobscured
VisibilityPartially-
Obscured
VisibilityPartially-
Obscured
Appendix E: Event Reference 589
F
Structure Reference
This appendix describes the contents of the include files for Xlib.
Description of Contents
All include files are normally located in lusr/include/Xll. All Xlib programs require
<Xll/Xlib.h>, which includes <Xll/X.h>. <Xll/Xlib.h> contains most of the structure
declarations, while <Xll/X.h> contains most of the defined constants. Virtually all pro-
grams will also require <Xll/Xutil.h>, which include structure types and declarations appli-
cable to window manager hints, colors, visuals, regions, standard geometry strings, and
images.
Here is a summary of
<Xl l /Xlib.h>
<Xll/X.h>
<Xl l /Xutil.h>
<Xl l lXatom.h>
<Xl l /cursorfont.h>
<Xl l /keysym.h>
<X11/Xreso urce. h >
the contents of the include files:
structure declarations for core Xlib functions.
constant definitions for Xlib functions.
additional structure types and constant definitions for miscellaneous
Xlib functions.
the predefined atoms for properties, types, and font characteristics.
the constants used to select a cursor shape from the standard cursor
font.
predefined key symbols corresponding to keycodes. It includes
<Xl l /keysymdef .h>.
resource manager structure definitions and function declarations.
Appendix F: Structure Reference 591
Resource Types
The following types are defined in <Xll/X.h>:
unsigned long XID
XID Colormap
XID Cursor
XID Drawable
XID Font
XID GCont ext
XID KeySym
XID Pixmap
XID Window
unsigned long Atom
unsigned char KeyCode
unsigned long Mask
unsigned long Time
unsigned long VisualID
Structure Definitions
This section lists all Xlib structure definitions in xlib.h and xutil .h, in alphabetical
order, except the event structures which are listed separately in the next section.
Note that the first few structure types do not begin with X. These structures are intended to
be opaque, so that Xlib's authors are free to change them in later releases. You are
discouraged from accessing their members directly. However, only the GC structure is
dangerous to access, because of the way GCs are implemented.
Before each structure is a description of what the structure is used for and a list of the Xlib
routines that use the structure.
Depth
Depth defines a valid depth and list of associated visuals. A list of these structures is con-
mined in the Screen structure, which is itself a member of the Display structure. Not
used directly in any Xlib function. This structure should not be accessed directly, but
instead through XGetVisualInfo and XMatchVisualInfo.
typedef struct {
int depth;
int nvisuals;
Visual *visuals;
} Depth;
/* this depth (Z) of the depth */
/* number of Visual types at this depth */
/* list of visuals possible at this depth */
592 Xlib Reference Manual
Display
Display describes the connection to the X server. A pointer to a structure of this type is
returned by XOpenDisplay, and is subsequently the first argument to nearly every Xlib
routine. Macros are provided to access most members of this structure.
* Display datatype maintaining display specific data.
*/
typedef struct _XDisplay {
XExtData *ext data; /*
--
struct _XDisplay *next; /*
int fd; /*
int lock; /*
int proto_major_version; /*
int proto_minor_version; /*
char *vendor; /*
long resource base; /*
--
long resource mask; /*
--
long resource id; /*
--
int resource shift; /*
--
XID (*resource alloc) (); /*
--
int byte_order; /*
int bitmap_unit; /*
int bitmap_pad; /*
int bitmap_bit_order; /*
int nformats; /*
ScreenFormat *pixmap_format; /*
int vnumber; /*
int release; /*
struct XSQEvent *head, *tail;/*
--
int qlen; /*
int last_request_read; /*
int request; /*
char *last_req; /*
char *buffer; /*
char *bufptr; /*
char *bufmax; /*
unsigned max_request_size; /*
struct XrmHashBucketRec *db;
--
int (*synchandler) (); /*
char *display_name; /*
int default screen; /*
--
int nscreens; /*
Screen *screens; /*
int motion buffer; /*
--
Window current; /*
int min_keycode; /*
int max_keycode; /*
KeySym *keysyms; /*
XModifierKeymap *modifiermap;/*
int keysyms_per_keycode; /*
char *xdefaults; /*
char *scratch buffer; /*
--
unsigned long scratch_length;/*
int ext number; /*
--
hook for extension to hang data */
next open Display on list */
network socket */
is someone in critical section? */
major version of server's X protocol */
minor version of servers X protocol */
vendor of the server hardware */
resource ID base */
resource ID mask bits */
allocator current ID */
allocator shift to correct bits */
allocator function */
screen byte order, LSBFirst, MSBFirst */
padding and data requirements */
padding requirements on bitmaps */
LeastSignificant or MostSignificant */
number of pixmap formats in list */
pixmap format list */
Xlib's X protocol version number */
release of the server */
input event queue */
length of input event queue */
sequence number of last event read */
sequence number of last request */
beginning of last request, or dummy */
output buffer starting address */
output buffer index pointer */
output buffer maximum+l address */
maximum number 32 bit words in request*/
synchronization handler */
"host:display" string used on this connect*/
default screen for operations */
number of screens on this server*/
pointer to list of screens */
size of motion buffer */
for use internally for Keymap notify */
minimum defined keycode */
maximum defined keycode */
this server's keysyms */
this server's modifier keymap */
number of rows */
contents of defaults from server */
place to hang scratch buffer */
length of scratch buffer */
extension number on this display */
Appendix F: Structure Reference 593
XExtension *ext_procs; /* extensions initialized on this display */
--
/*
* the following can be fixed size, as the protocol defines how
* much address space is available.
* While this could be done using the extension vector, there
* may be MANY events processed, so a search through the extension
* list to find the right procedure for each event might be
* expensive if many extensions are being used. */
Bool (*event vec[128]) () ;
--
Status (*wire vec[128]) ();
--
} Display;
/* vector for wire to event */
/* vector for event to wire */
GC
GC describes a graphics context. A pointer to a structure of this type is returned by
XCreateGC and subsequently used in all routines that draw or modify the GC. The
members of this structure must not be accessed directly.
typedef struct XGC {
--
XExtData *ext data;
--
GContext gid;
Bool rects;
Bool dashes;
unsigned long dirty;
XGCValues values;
} *GC;
/* hook for extension to hang data */
/* protocol ID for graphics context */
/* Boolean: TRUE if clipmask is list of rectangles */
/* Boolean: TRUE if dash-list is really a list */
/* cache dirty bits */
/* shadow structure of values */
Screen
Screen describes the characteristics of a screen. A pointer to a list of these structures is a
member of the Display structure. A pointer to a structure of this type is returned by
XGetWindowAttributes. Macros are provided to access most members of this struc-
ture.
typedef struct {
XExtData *ext_data;
struct _XDisplay *display;
Window root;
int width, height;
int mwidth, mheight;
int ndepths;
Depth *depths;
int root_depth;
Visual *root_visual;
GC default_gc;
Colormap cmap;
unsigned long white_pixel;
unsigned long black_pixel;
/* hook for extension to hang data */
/* back pointer to display structure */
/* root window ID */
/* width and height of screen */
/* width and height of in millimeters */
/* number of depths possible */
/* list of allowable depths on the screen */
/* bits per pixel */
/* root visual */
/* GC for the root root visual */
/* default colormap */
/* white and black pixel values */
594
Xlib Reference Manual
XArc
XArc specifies the bounding box for an arc and two angles indicating the extent of the arc
within the box. A list of these structures is used in XDrawArcs and XFillArcs.
typedef struct {
short x, y;
unsigned short width, height;
short anglel, angle2;
} XArc;
XChar2b
XChar2b specifies a character in a two-byte font. A list of structures of this type is an
argument to XDrawlmageStringl6, XDrawStringl6, XDrawTextl6, XQuery-
TextExtentsl6, XTextExtentsl6, and XTextWidthl6. The only two-byte font
currently available is Kanji (Japanese).
typedef struct {
unsigned char bytel;
unsigned char byte2;
} XChar2b;
/* normal 16 bit characters are two bytes */
XCharStruct
XCharStruct describes the metrics of a single character in a font, or the overall charac-
teristics of a font. This structure is the type of several of members of XFontStruct, and
is used to return the overall characteristics of a string in XQueryTextExtents* and
XText Extent s *.
typedef struct {
short ibearing;
short rbearing;
short width;
short ascent;
short descent;
unsigned short attributes;
} XCharStruct;
/* origin to left edge of raster */
/* origin to right edge of raster */
/* advance to next char's origin */
/* baseline to top edge of raster */
/* baseline to bottom edge of raster */
/* per char flags (not predefined) */
596 Xlib Reference Manual
XExtCodes
XExtCodes is a smacture used by the extension mechanism. This structure is returned by
xInitExtension which is not a standard Xlib routine but should be called within the
extension code. Its contents are not normally accessible to the application.
typedef struct {
int extension;
int major_opcode;
int first event;
int first error;
} XExtCodes;
/* public to extension, cannot be changed */
/* extension number */
/* major opcode assigned by server */
/* first event number for the extension */
/* first error number for the extension */
XExtData
XExtData provides a way for extensions to attach private data to the existing structure
types GC, Visual, Screen, Display, and XFontStruct. This structure is not used in
normal Xlib programming.
typedef struct XExtData {
int number;
struct XExtData *next;
int (*free_private) ();
char *private_data;
} XExtData;
/* number returned by XRegisterExtension */
/* next item on list of data for structure */
/* called to free private storage */
/* data private to this extension */
XFontProp
XFontProp is used in XFontStruct. This structure allows the application to find out
the names of additional font properties beyond the predefined set, so that they too can be
accessed with XGetFontProperty. This structure is not used as an argument or return
value for any core Xlib function.
typedef struct {
Atom name;
unsigned long card32;
} XFontProp;
598 Xlib Reference Manual
XFontStruct
XFontStruct specifies metric information for an entire font. This structure is filled with
the XLoadQueryFont and XQueryFont routines. ListFontsWithInfo also fills it
but with metric information for the entire font only, not for each character. A pointer to this
sucture is used in the routines XFreeFont, XFreeFontInfo, XGetFontProp,
XTextExtents*, and XTextWidth*.
typedef struct {
XExtData *ext data;
Font fid;
unsigned direction;
unsigned min char or byte2;
unsigned max char or byte2;
unsigned min_bytel;
unsigned max_bytel;
Bool all chars exist;
unsigned default char;
int n_properties;
XFontProp *properties;
XCharStruct min bounds;
XCharStruct max bounds;
XCharStruct *per_char;
int ascent;
int descent;
} XFontStz-uct;
/* hook for extension to hang data */
/* font ID for this font */
/* direction the font is painted */
/* first character */
/* last character */
/* first row that exists */
/* last row that exists */
/* flag if all characters have nonzero size*/
/* char to print for undefined character */
/* how many properties there are */
/* pointer to array of additional properties*/
/* minimum bounds over all existing char*/
/* minimum bounds over all existing char*/
/* first char to last char information */
-- _
/* logical extent above baseline for spacing */
/* logical descent below baseline for spacing */
XGCValues
XGCValues is used to set or change members of the GC by the routines XCreateGC and
XChangeGC.
typedef struct (
int function;
unsigned long plane_mask;
unsigned long foreground;
usigned long backgrgund;
int line width;
--
int line_style;
int cap_style;
int join_style;
int fill_style;
int fill rule;
int arc mode;
--
Pixmap tile;
Pixmap stipple;
int ts x origin;
int ts_y_origin;
Font font;
int subwindow mode;
--
Bool graphics_exposures;
int clip_x_origin;
/* logical operation */
/* plane mask */
/* foreground pixel */
/* background pixel */
/* line width */
/* LineSolid, LineOnOffDash, LineDoubleDash */
/* CapNotLast, CapButt, CapRound, CapProjecting */
/* JoinMiter, JoinRound, JoinBevel */
/* FillSolid, FillTiled, FillStippled */
/* EvenOddRule, WindingRule */
/* ArcPieSlice, ArcChord */
/* tile pixmap for tiling operations */
/* stipple 1 plane pixmap for stippling */
/* offset for tile or stipple operations */
/* default text font for text operations */
/* ClipByChildren, IncludeInferiors */
/* Boolean, should exposures be generated */
/* origin for clipping */
Appendix F: Structure Reference 599
int clip y origin;
Pixmap clip_mask;
int dash offset;
--
char dashes;
} XGCValues;
/* bitmap clipping; other calls for rects */
/* patterned/dashed line information */
XHostAddress
XHostAddress specifies the address of a host machine that is to be added or removed
from the host access list for a server. Used in XAddHost, XAddHosts, XListHosts,
XRemoveHost, and XRemoveHosts.
typedef struct {
int family; /* for example FAMILY INTERNET */
--
int length; /* length of address, in bytes */
char *address; /* pointer to where to find the bytes */
} XostAddress ;
XlconSize
XlconSize is used to set or read the XA_WM_ICON_SIZE property. This is normally set
by the window manager with xSetrconSizes arid read by each application with XGet-
IconSizes.
typedef struct {
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
} XIconSize;
Xlmage
Xlmage describes an area of the screen. As you can tell from the funcs member, this
structure is used in XCreatelmage, XDestroyImage, XGetPixel, XPutPixel,
XSubImage, and XAddPixel. It is also used in XGetImage, XGetSubImage and
XPut Image.
typedef struct _XImage {
int width, height;
int xoffset;
int format;
char *data;
int byte_order;
int bitmap_unit;
int bitmap_bit_order;
/* size of image */
/* number of pixels offset in X direction */
/* XYBitmap, XYPixmap, ZPixmap */
/* pointer to image data */
/* data byte order, LSBFirst, MSBFirst */
/* quant, of scan line 8, 16, 32 */
/* LSBFirst, MSBFirst */
600
Xlib Reference Manual
int bitmap_pad;
int depth;
int bytes_per_line;
int bits_per_pixel;
unsigned long red_mask;
unsigned long green_mask;
unsigned long blue_mask;
char *obdata;
struct funcs (
/* 8, 16, 32 either XY or ZPixmap */
/* depth of image */
/* accelerator to next line */
/* bits per pixel (ZPixmap) */
/* bits in z arrangement */
/* hook for the object routines to hang on */
/* image manipulation routines */
struct _XImage * (*create_image) () ;
int (*destroy_image) () ;
unsigned long (*get_pixel) () ;
int (*put_pixel) () ;
struct _XImage * (*sub_image) () ;
int (*add_pixel) () ;
} f;
} XImage;
XKeyboardControl
XKeyboardControl is used to set user preferences with XChangeKeyboard-
Control.
typedef struct
int key_click_percent;
int bell_percent;
int bell_pitch;
int bell duration;
--
int led;
int led mode;
--
int key;
int auto_repeat_mode;
} XKeyboardControl;
/* AutoRepeatModeOn, AutoRepeatModeOff,
* AutoRepeatModeDefault */
xKeyboardState
XKeyboardState is used to return the current settings of user preferences with XGet-
Keyboa rdCont ro i.
t ypede f struct
int key_click_percent ;
int bell_percent;
unsigned int bell_pitch, bell_duration;
unsigned long led mask;
--
int global_auto_repeat ;
char auto_repeats [32] ;
} XKeyboardState;
Appendix F: Structure Reference 601
XModifierKeymap
XModifierKeymap specifies which physical keys are mapped to modifier functions. This
structure is returned by XGetModifierMapping, and is an argument to XDelete-
ModifiermapEntry, XFreeModifiermap, InsertModifiermapEntry, XNew-
Modifiermap, and XSetModifierMapping.
typedef struct {
int max_keypermod; /* server's max # of keys per modifier */
KeyCode *modifiermap; /* an 8 by max_keypermod array of modifiers */
} XModifierKeymap;
XPoint
XPoint specifi the coordinates of a point. Used in XDrawPoints, XDrawLines,
XFillPolygon, and XPolygonRegion.
typedef struct {
short x, y;
} XPoint;
XRectangle
XRectangle specifies a rectangle. Used in XClipBox, XDrawRectangles, XFill-
Rectangles, XSetClipRectangles, and XUnionRectWithRegion.
typedef struct {
short x, y;
unsigned short width, height;
} XRectangle;
XSegment
XSegment specifies two poinm. Used in XDrawSegments.
typedef struct {
short xl, yl, x2, y2;
} XSegment;
602
Xlib Reference Manual
XSetWindowAttributes
XSetWindowAttributes contains all the attributes that can be set without window
manager inenfion. Used in XChangeWindowAttributes and XCreatewindow.
typedef struct {
Pixmap background_pixmap; /*
unsigned long background_pixel;/*
Pixmap border_pixmap; /*
unsigned long border_pixel;
int bit_gravity;
int win_gravity;
int backing_store;
unsigned long backing_planes;
unsigned long backing_pixel;
Bool save under;
long event mask;
long do_not_propagate_mask;
Bool override redirect;
Colormap colormap;
Cursor cursor;
} XSetWindowAttributes;
background or None or ParentRelative */
background pixel */
border of the window */
/* border pixel value */
/* one of bit gravity values */
/* one of the window gravity values */
/* NotUseful, WhenMapped, Always */
/* planes to be preserved if possible */
/* value to use in restoring planes */
/* should bits under be saved? (popups) */
/* set of events that should be saved */
/* set of events that should not */
* propagate */
/* Boolean value for override-redirect */
/* colormap to be associated with window */
/* cursor to be displayed (or None) */
XSizeHints
XSizeHints describes a range of preferred sizes and aspect ratios. Used to set the
XA WM NORMAL HINTS and XA WM ZOOM HINTS properties for the window manager
with XSetNormalHints, XSetZoomHints, XSetStandardProperties or XSet-
SizeHints. A|so used in reading these properties with XGetSizeHints, XGet-
NormalHints, or XGetZoomHints.
typedef struct {
long flags;
int x, y;
int width, height;
iDt min_width, min_hight;
int max_width, max_height;
int width_inc, height_inc;
struct
int x;
int y;
} min_aspect, max_aspect;
} XSizeHints;
/* marks defined fields in structure */
/* numerator */
/* denominator */
Appendix F: Structure Reference 603
XStandardColormap
XStandardColormap describes a standard colormap, giving its ID and its color charac-
teristics. This is the format of the standard colormap properties set on the root window,
which can be changed with XSetStandardProperties and changed with XGet-
St anda rdP ropert ies.
typedef struct {
Colormap colormap;
unsigned long red max;
--
unsigned long red mult;
--
unsigned long green_max;
unsigned long green_mult;
unsigned long blue max;
--
unsigned long blue mult;
--
unsigned long base_pixel;
} XStandardColormap;
XTextltem
XTextItem describes a string, the font to print it in, and the horizontal offset from the pre-
vious string drawn or from the location specified by the drawing command. Used in
XDrawText.
typedef struct {
char *chars;
int nchars;
int delta;
Font font;
} XTextItem;
/* pointer to string */
/* number of characters */
/* delta between strings */
/* font to print it in, None don't change */
X'l'extltem16
XTextItem16 describes a string in a two-byte font, the font to print it in, and the horizon-
tal offset from the previous string drawn or from the location specified by the drawing com-
mand. Used in XDrawText 16.
typedef struct {
XChar2b *chars;
int nchars;
int delta;
Font font;
} XTextIteml6;
/* two-byte characters */
/* number of characters */
/* delta between strings */
/* font to print it in, None don't change */
604
Xlib Reference Manual
XWindowAttributes
XWindowAttributes describes the complete set of window attributes, including those
that can't be set without window manager interaction. This structure is returned by XGet-
WindowAttributes. It is not used by XChangeWindowAttributes or XCreate-
Window.
typedef struct {
int x, y;
int width, height;
int border width;
--
int depth;
Visual *visual;
Window root;
int class;
int bit_gravity;
int win_gravity;
int backing_store;
unsigned long backing_planes;
unsigned long backing_pixel;
Bool save_under;
Colormap colormap;
Bool map_installed;
int map_state;
long all_event_masks;
long your_event_mask;
long do_not_propagate_mask;
Bool override redirect;
--
Screen *screen;
} XWindowAttributes;
/* location of window */
/* width and height of window */
/* border width of window */
/* depth of window */
/* the associated visual structure */
/* root of screen containing window */
/* InputOutput, InputOnly*/
/* one of bit gravity values */
/* one of the window gravity values */
/* NotUseful, WhenMapped, Always */
/* planes to be preserved if possible */
/* value to be used when restoring planes */
/* Boolean, should bits under be saved */
/* colormap to be associated with window */
/* Boolean, is colormap currently installed*/
/* IsUnmapped, IsUnviewable, IsViewable */
/* events all people have interest in*/
/* my event mask */
/* set of events that should not propagate */
/* Boolean value for override-redirect */
XWindowChanges
XWindowChanges descfbes a configuration for a window. Used in XConfigure-
Window, which can change the screen layout and therefore can be intercepted by the win-
dow manager. This se some of the remaining members of XWindowAttributes that
cannot be set with XChangeWindowAttributes or XCreateWindow.
typedef struct {
int x, y;
int width, height;
int border_width;
Window sibling;
int stack_mode;
} XWindowChanges;
606
Xlib Reference Manual
G
Symbol Reference
This appendix presents an alphabetical listing of the symbols used in X. The routines in
parentheses following the descriptions indicate the routines associated with those symbols.
A
_Above
AllHints
AllTemporary
AllValues
AllocAll
AllocNone
AllowExposures
AlreadyGrabbed
Always
AnyButton
AnyKey
AnyModifier
AnyPropertyType
ArcChord
ArcPieSlice
AsyncBoth
AsyncKeyboard
AsyncPointer
AutoRepeatModeDefault
AutoRepeatModeOff
AutoRepeatModeOn
stocking method (XConfigureWindow)
XA WM HINTS propeny, all membes set
(XGetWMHint s, XSetWMHint s)
resource ID passed to XKillClient
mask used by XParseGeometry, returns those set by user
allocate entire map writable (XCreateColormap)
create map with no entries (XCreateColormap)
screen saver (XSet SreenSave r, XGet Sc reenSave r)
XGrabPointer, XGrabKeyboard return Status
ba eking_st ore attribute
(XCreateWindow, XChangeWindowAt t ribut e s)
button name for XGrabButton, or for ButtonPress or
ButtonRelease del
keycode for XGrabKey
modifier key mask for XGrabButton, XGrabKey, results of
XQueryPointer, event state
atom for XGetProperty
arc_mode in GC, join endpoints of arc (XFillArcs)
arc mode GC, join endpoints to center of arc
--
(XFillArcs)
XA 11 owEvent s mode
XA 11 owEvent s mode
XAI 1 owEvent s mode
keyboard preferences
(XChangeKeyboardCont rol, XGetKeyboardCont rol)
keyboard preferences
(XChangeKeyboardCont rol, XGetKeyboa rdCont rol)
keyboard preferences
(XChangeKeyboardCont rol, XGetKeyboardCont rol)
Appendix G: Symbol Reference 607
B
BadAccess
BadAlloc
BadAtom
BadColor
BadCursor
BadDrawable
BadFont
BadGC
BadIDChoice
BadImplementation
BadLength
BadMatch
BadName
BadPixmap
BadRequest
BadValue
BadWindow
Below
BitmapFileInvalid
BitmapNoMemory
BitmapOpenFailed
BitmapSucces
BottomIf
Buttonl
ButtonlMask
ButtonlMotionMask
Button2
Button2Mask
Button2MotionMask
Button3
Button3Mask
Button3MotionMask
Button4
Button4Mask
Button4MotionMask
Button5
Button5Mask
Button5MotionMask
used by
used by
used by
used by
used by
used by
used by
used by
used by
used by
used by
used by
used by
used by
used by
used by
used by
stacking
returned
returned
returned
returned
extensions
extensions
extensions
extensions
extensions
extensions
extensions
extensions
extensions
extensions
extensions
extensions
extensions
extensions
extensions
extensions
only,
only,
only,
only,
only,
only,
only,
only,
only,
only,
only,
only,
only,
only,
only,
only,
depending on context
insufficient resources
parameter not an At om
no such colormap
parameter not a Cursor
parameter not a Pixmap or Window
parameter not a Font
parameter not a GC
choice not in range or already used
server is defective
request length incorrect
parameter mismatch
font or color name doesn't exist
parameter not a Pixmap
bad request code
integer parameter out of range
extensions only,
method, XConfigureWindow
Status for XReadBitmapFile,
Status for XReadBitmapFile,
Status for XReadBitmapFile,
Status for XReadBitmapFile,
parameter not a Window
XWriteBitmapFile
XWriteBitmapFile
XWrit eBitmapFile
XWriteBitmapFile
stacking method (XConfigureWindow)
button name in event detail (XGrabButton)
button mask (XQue ryPointe r)
event mask
button name in event detail (XGrabButton)
button mask (XQueryPointer)
event mask
button name in event detail (XGrabButton)
button mask (XQueryPointer)
event mask
button name in event detail (XGrabButton)
button mask (XQueryPointe r)
event mask
button name in event detail (XGrabButton)
button mask (XQue ryPointe r)
event mask
608
Xlib Reference Manual
ButtonMotionMask
ButtonPress
ButtonPressMask
ButtonRelease
ButtonReleaseMask
C
CapButt
CapNot La st
CapPro jecting
CapRound
CenterGravity
CirculateNotify
CirculateRequest
ClientMessage
ClipByChildren
ColormapChangeMask
ColormapInstalled
ColormapNotify
ColormapUninstalled
Complex
ConfigureNotify
ConfigureRequest
ControlMapIndex
ControlMask
Convex
CoordModeOrigin
CoordModePrevious
CopyFromParent
CreateNotify
CurrentTime
CursorShape
CWBackPixel
event mask
event type
event mask
event type
event mask
line cap_style of GC (XSetLineAttributes)
IMe cap_style of GC (XSetLineAttributes)
line cap_style of OC (XSetLineAttributes)
line cap_style of OC (XSetLineAttributes)
bit_gravity and win_gravity atibute c0nsmnt
event type
event type
event type
subwindow mode of GC, don't draw through children
--
(XS et Su bw indowMode)
event mask
ColormapNot i fy event state
event type
ColormapNot i fy event state
polygon shapes, paths may intersect (XFillPolygon)
event type
event type
modifier names for XSetModifierMapping,
XGet Modi fierMapping
modifier key mask for XGrabButton, XGrabKey, results of
XQueryPointer, event state
polygon shapes, wholly convex (XFillPolygon)
interpret points relative to origin
(XDrawLines, XDrawPoint s)
interpret points relative to previous point
(XDrawLines, XDrawPoint s)
border pixmap, visual ID, window class
(XCreateWindow, XChangeWindowAt t ribut e s)
event type
most time arguments
largest displayable size
(XQueryBest Si ze, XQueryBestCursor)
window attribute mask
(XCreateWindow, XChangeWindowAt t ribut es)
Appendix G: Symbol Reference 609
InputFocus
InputHint
InputOnly
InputOutput
IsCursorKey
IsFunctionKey
IsKeypadKey
IsMiscFunctionKey
IsModifierKey
IsPFKey
IsUnmapped
IsUnviewable
IsViewable
JoinBevel
JoinMiter
JoinRound
KL
KBAut oRepeatMode
KBBellDuration
KBBellPercent
KBBellPitch
KBKey
KBKeyClickPercent
KBLed
KBLedMode
KeyPress
KeyPressMask
KeyRelease
KeyReleaseMask
window in XSendEvent
XA WM HINTS property, input member mask
(XGetWMHints, XSetWMHint s)
window class (XCreateWindow)
window class (XCreateWindow)
keysym class macro
keysym class macro
keysym class macro
keysym class macro
keysym class macro
keysym class macro
map_state member of XWindowAttributes
(XGet WindowAtt ribut e s)
map_state member of XWindowAttributes
(XGet Win dowAtt ribut e s)
map_state member of XWindowAttributes
(XGet WindowAt t ribut e s)
line join_style of GC (XSetLineAttributes)
line join_style of GC (XSetLineAttributes)
line join_style of GC (XSetLineAttributes)
mask for setting keyboard preferences
(XChangeKeyboa rdCont rol, XGetKeyboardControl)
mask for setting keyboard preferences
(XChangeKeyboa rdCont ro i, XGetKeyboardCont rol)
mask for setting keyboard preferences
(XChangeKeyboardCont ro i, XGetKeyboardControl)
mask for setting keyboard preferences
(XChangeKeyboa rdCont ro i, XGetKeyboardCont rol)
mask for setting keyboard preferences
(XChan geKeyboa rdCont ro i, XGetKeyboa rdCont ro i)
mask for setting keyboard preferences
(XChan geKeyboa rdCont ro i, XGetKeyboa rdCont ro i)
mask for setting keyboard preferences
(XChangeKeyboa rdCont ro i, XGetKeyboardControl)
mask for setting keyboard preferences
(XChangeKeyboa rdCont rol, XGetKeyboardControl)
event type
event mask
event type
event mask
614
Xlib Reference Manual
KeymapNotify
KeymapStateMask
LASTEvent
LastExtensionError
LeaveNotify
LeaveWindowMask
LedModeOff
LedModeOn
LineDoubleDash
LineOnOffDash
LineSolid
LockMapIndex
LockMask
LowerHighest
LSBFirst
M
MapNot i fy
MapReque st
MappingBusy
MappingFailed
MappingKeyboard
MappingModifier
MappiagNotify
MappingPointer
MappingSuccess
ModlMapIndex
Mo dl Ma s k
Mod2MapIndex
Mod2 Ma s k
event type
event mask
bigger than any event type value
use if writing extension
event type
event mask
keyboard preferences
(XChangeKeyboa rdCont rol, XGetKeyboa rdCont rol)
keyboard preferences
(XChangeKeyboa rdCont rol, XGetKeyboa rdCont rol)
line_style of OC (XSetLineAttributes)
line_style of OC (XSetLineAttributes)
line_style of OC (XSetLineAttributes)
modifier names for XSetModi f ie rMapping,
XGetModifierMapping
modifier key mask for XGrabButton, XGrabKey, results of
XQueryPointer, event state
circulation direcfi0n, XCirculateSubwindows
byte order, used in image structure
(XCreateImage, ImageByteOrder)
event type
event type
pointer or modifier mapping status
(XSet Modi fierMapping, XSetPointerMapping)
pointer or modifier mapping Status
(XSet Modi fierMapping, XSetPointerMapping)
MappingNot ify event
MappingNot i fy event
event type
MappingNot i fy event
pointer or modifier mapping Status
(XSetModi fierMapping, XSetPointerMapping)
modifier names for XSetModifierMapping,
XGet Modi fierMapping
modifier key mask for XGrabButton, XGrabKey, results of
XQue ryPointe r, event state
modifier names for XSetModifierMapping,
XGet Modi fierMapping
modifier key mask for XGrabButton, XGrabKey, resul of
XQueryPointer, event state
Appendix G: Symbol Reference 615
Mod3MapIndex
Mod3Mask
Mod4MapIndex
Mod4Mask
Mod5MapIndex
Mod5Mask
MotionNotify
MSBFirst
N
NoEventMask
NoExpose
NoSymbol
NoValue
Nonconvex
None
NormalState
NorthEastGravity
NorthGravity
NorthWestGravity
NotUseful
NotifyAncestor
NotifyDetailNone
NotifyGrab
NotifyHint
NotifyInferior
NotifyNonlinear
NotifyNonlinear-
Virtual
NotifyNormal
NotifyPointer
NotifyPointerRoot
modifier names for XSetModifierMapping,
XGetModifierMapping
modifier key mask for XGrabButton, XGrabKey, results
XQueryPointer, event state
modifier names for XSetModifierMapping,
XGetModi fierMapping
modifier key mask for XGrabButton, XGrabKey, results
XQueryPointer, event state
modifier names for XSetModifierMapping,
XGetModifierMapping
modifier key mask for XGrabButton, XGrabKey, results
XQueryPointer, event state
event type
byte order, used in image structure
(XCreateImage, ImageByteOrder)
event mask
event type
keysym for no symbol
mk usa by XParseGeometry, returns those set by user
polygon shapes, no paths intersect, but not convex
(XFillPolygon)
universal null resource or null atom
window state, not iconified or zoomed
(value for member of xwrtints)
bit_gravity and win_gravity attribute constant
bit_gravity and win_gravity attribute constant
bit_gravity and win_gravity attribute constant
backing_store attribute
(XCreateWindow, XChangeWindowAtt ribute s)
FocusIn, FocusOut, EnterNotify, LeaveNotify detail
FocusIn, FocusOut,
FocusIn, FocusOut,
MotionNoti fy event
FocusIn, FocusOut,
FocusIn, FocusOut,
FocusIn, FocusOut,
FocusIn, FocusOut,
FocusIn, FocusOut,
FocusIn, FocusOut,
EnterNotify, LeaveNotify detail
EnterNotify, LeaveNotify mode
hint
EnterNotify, LeaveNotify detail
EnterNotify, LeaveNotify detail
EnterNotify, LeaveNotify detail
EnterNotify, LeaveNotify mode
EnterNotify, LeaveNotify detail
EnterNotify, LeaveNotify detail
616
Xlib Reference Manual
RectangleOut
RectanglePart
ReparentNotify
ReplayKeyboard
ReplayPointer
ResizeRedirectMask
ResizeRequest
RetainPern%nent
RetainTemporary
RevertToNone
RevertToParent
RevertToPointerRoot
rectangle is outside region (XRectInRegion)
rectangle is part inside region (XRect InRegion)
event type
XAllowEvents mode
XAllowEvent s mode
event mask
event type
mode in XSetCloseDownMode
mode in XSetCloseDownMode
backup keybod focus window
(XSet InputFocus, XGet InputFocus)
backup keybod focus window
(XSet InputFocu s, XGet InputFocu s)
backup keybod focus window
(XSet InputFocus, XGet InputFocus)
S
ScreenSaverActive
ScreenSaverReset
SelectionClear
SelectionNotify
SelectionRequest
SetModeDelete
SetModeInsert
ShiftMapIndex
Shi ftMask
SouthEastGravity
SouthGravity
SouthWestGravity
StateHint
StaticColor
StaticGravity
StaticGray
StippleShape
StructureNotifyMask
tum screen saver on (XForceScreenSaver)
tum screen saver off (XForceScreenSaver)
event type
event type
event type
change_mode argument of XChangeSave Set
change_mode argument of XChangeSaveSet
modifier names for XSetModifierMapping,
XGet Modi fi erMappin g
modifier key mask for XGrabButton, XGrabKey, results of
XQueryPointer, event state
bit_gravity and win_gravity atibute constant
bit_gravity and win_gravity atibute constant
bit_gravity and win_gravity atibute constant
XA WM HINTS property, window state mask
(XGetWMHints, XSetWMHint s)
visual class, read-only
(XGetVisualInfo, XMat chVisualInfo)
bit_gravity and win_gravity atibute constant
visual class, read-only
(XGetVisualInfo, XMat chVisualInfo)
size filed fastest (XQue ryBe st Si ze, XQue ryBe st St ipple)
event mask
Subst ru ctureNot ifyMas k event mask
618
Xlib Reference Manual
VisualNoMask
VisualRedMaskMask
VisualScreenMask
WestGravity
WhenMapped
WidthValue
WindingRule
WindowGroupHint
X
XA ARC
--
XA ATOM
--
XA BITMAP
--
XA CAP HEIGHT
-- _
XA CARDINAL
XA COLORMAP
--
XA COPYRIGHT
--
XA CURSOR
XA CUT BUFFER0
XA_CUT_BUFFERI
X_CU_BUFFER2
XA_CUT_BUFFER3
XA_CUT_UFFER4
XA_CUT_UFFER5
XA_CUT_BUFFER 6
XA_CUT_BUFFER7
XA_DRAWABLE
XA END SPACE
XA FAMILY NAME
XA FONT
XA FONT NAME
XA FULL NAME
XA_INTEGER
XA_ITALIC ANGLE
XA_LAST_PREDEFI NED
mask for determining desired visual structure
(XGetVisual Info, Mat chVi sual In fo)
mask for determining desired visual structure
(XGetVisual Info, Mat chVi sual In fo)
mask for determining desired visual structure
(XGetVisualInfo, MatchVi sual Info)
bit_gravity and win_gravity attribu constant
backing_store attribute
(XCreateWindow, XChangeWindowAtt ribute s)
mask used by XParseGeometry, returns ose set by user
fill_rule of OC, for po|ygons
(XSetFillRule, XPolygonRegion)
XA WM HINTS property, group property mask
(XGetWMHints, XSetWMHint s)
predefined type atom
predefined type atom
predefined type atom
predefined font atom
predefined type atom
predefined type atom
predefined font atom
predefined type atom
predefined cut buffer atom
predefined cut buffer atom
predefined cut buffer atom
predefined cut buffer atom
predefined cut buffer atom
predefined cut buffer atom
predefined cut buffer atom
predefined cut buffer atom
predefined type atom
predefined font atom
predefined font atom
predefined type atom
predefined font atom
predefined font atom
predefined type atom
predefined font atom
predefined font atom
62O
Xlib Reference Manual
XA MAX SPACE
XA MIN SPACE
XA NORM SPACE
-- --
XA NOTICE
--
XA PIXMAP
--
XA POINT
--
XA POINT SIZE
-- --
XA PRIMARY
--
XA_QUAD_WIDTH
XA RECTANGLE
--
XA RESOLUTION
--
XA RESOURCE MANAGER
-- --
XA RGB BEST MAP
-- -- --
XA RGB BLUE MAP
-- -- --
XA RGB COLOR MAP
-- -- --
XA RGB DEFAULT MAP
-- -- --
XA RGB GRAY MAP
XA RGB GREEN MAP
-- -- --
XA RGB RED MAP
-- -- --
XA SECONDARY
--
XA STRIKEOUT ASCENT
-- --
XA STRIKEOUT DESCENT
XA STRING
--
XA SUBSCRIPT X
-- --
XA SUBSCRIPT Y
-- --
XA SUPERSCRIPT X
-- --
XA SUPERSCRIPT Y
-- --
XA UNDERLINE POSITION
-- --
XA UNOERLINE THICKNESS
XA VISUALID
--
XAWEIGHT
--
XAWINDOW
--
XAWM CLASS
XA WM CLIENT MACHINE
--
XA WM COMMAND
XA WM HINTS
XA WM ICON NAME
XA WM ICON SIZE
XAWM NAME
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predcfined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
predefined
font atom
font atom
font atom
font atom
type atom
type atom
font atom
selection atom
font atom
type atom
font atom
resource manager atom
colormap atom
colormap atom
type atom
colormap atom
colormap atom
colormap atom
colormap atom
selection atom
font atom
font atom
type atom
font atom
font atom
font atom
font atom
font atom
font atom
type atom
font atom
type atom
font atom
string atom
window manager hints atom
window manager hints atom
window manager hints atom
window manager hints atom
window manager hints atom
Appendix G: Symbol Reference 621
Table H-2. MISCELLANY
Keysym
XK_BackSpace
XK Tab
--
XK Linefeed
XK Clear
--
XK Return
--
XK Pause
XK_Escape
XK Delete
XK_Mult i_key
XK_Kan j i
XK Home
--
XK Left
--
x_up
XK_Right
XK Down
XK Prior
XK Next
XK End
--
XK_Begin
XK Select
XK Print
--
XK Execute
--
XK Insert
--
XK Undo
XK Redo
--
XK Menu
--
XK Find
--
XK Cancel
XK_Help
XK Break
--
XK Mode switch
XK_script_switch
XK Num Lock
-- __
XK KP Space
XK KP Tab
XK KP Enter
XK KP F1
XK KP F2
XK KP F3
XK KP F4
XK KP Equal
XK KP Multiply
XK KP Add
Description
Backspace, Back Space, Back Char
Tab
Linefeed, LF
Clear
Retum, Enter
Pause, Hold, Scroll Lock
Escape
Delete, Rubout
Multi-key character preface
Kanji, Kanji convert
Home
Left, move left, left arrow
Up, move up, up arrow
Right, move right, right arrow
Down, move down, down arrow
Prior, previous
Next
End, EOL
Begin, BOL
Select, mark
Print
Execute, run, do
Insert, insert here
Undo, oops
Redo, again
Menu
Find, search
Cancel, stop, abort, exit
Help, question mark
Break
Mode switch, script switch,
character set switch
Alias for mode switch, script switch,
character set switch
Num Lock
Keypad Space
Keypad Tab
Keypad Enter
Keypad F1, PF1, a
Keypad F2, PF2, b
Keypad F3, PF3, c
Keypad F4, PF4, d
Keypad equals sign
Keypad multiplication sign, asterisk
Keypad plus sign
Appendix H: Keysyms 625
Table H-2. MISCELLANY (continued)
Ke),s),m
XK_KP_geparat or
XK KP Subtract
XK KP Decimal
XK KP Divide
XK KP 0
XK KP 1
XK KP 2
XK KP 3
XK KP 4
XK KP 5
XK KP 6
XK KP 7
XK KP 8
XK KP 9
XK F1
XK F2
XK F3
XK F4
XK F5
XK F6
XK F7
XK F8
XK F9
XK FI0
XK FII
XK L1
--
XK FI2
XK L2
XK FI3
--
XK L3
XK FI4
XK L4
XK FI5
XK L5
XK FI6
XK L6
XK FI7
XK L7
XK FI8
XK L8
XK FI9
XK L9
XK F20
XK LI0
XK F21
)ton
Keypad separator, comma
Keypad minus sign, hyphen
Keypad decimal point, full stop
Keypad division sign, solidus
Keypad digit zero
Keypad digit one
Keypad digit two
Keypad digit three
Keypad digit four
Keypad digit five
Keypad digit six
Keypad digit seven
Keypad digit eight
Keypad digit nine
F1 function key
F2 function key
F3 function key
F4 function key
F5 function key
F6 function key
F7 function key
F8 function key
F9 function key
F10 function key
F11 function key
L1 function key
F12 function key
L2 function key
F13 function key
L3 function key
F14 function key
L4 function key
F15 function key
L5 function key
F16 function key
L6 function key
F17 function key
L7 function key
F18 function key
L8 function key
F19 function key
L9 function key
F20 function key
L10 function key
F21 function key
66
Xlib Reference Manual
Table H-2. MISCELLANY (continued)
Keysym
XK R1
--
XK F22
--
XK R2
--
XK F23
--
XK R3
XK F24
--
XK R4
XK F25
--
XK R5
--
XK F26
--
XK R6
--
XK F27
--
XK R7
--
XK F28
--
XK R8
XK F29
--
XK R9
--
XK F30
--
XK RI0
XK F31
--
XK RII
--
XK F32
--
XK RI2
--
XK RI3
--
XK F33
--
XK F34
--
XK RI4
--
XK F35
--
XK RI5
--
XK Shift L
XK Shift R
XK C6ntrol L
XK Control R
-- __
XK_Caps_Lock
XK Shift Lock
XK Meta L
XK Meta R
XK Alt L
-- __
XK Alt R
-- --
XK_Super_L
XK_Super_R
XK_Hyper_L
XK_Hyper_R
Description
R1 function key
F22 function key
R2 function key
F23 function key
R3 function key
F24 function key
R4 function key
F25 function key
R5 function key
F26 function key
R6 function key
F27 function key
R7 function key
F28 function key
R8 function key
F29 function key
R9 function key
F30 function key
RI0 function key
F31 function key
R11 function key
F32 function key
R12 function key
F33 function key
R 13 function key
F34 function key
R14 function key
F35 function key
R15 function key
Left Shift
Right Shift
Left Control
Right Control
Caps Lock
S hift Lock
Left Meta
Right Meta
Left Alt
Right Alt
Left Super
Right Super
Left Hyper
Right Hyper
Appendix H: Keysyms 627
Table H-3. LA TINI
Keysym
XK_space
XK exclam
--
XK_quot edbl
XK_number sign
XK dollar
--
XK_pe rcen t
XK_ampersand
XK_quoteright
XK_pa renleft
XK_parenright
XK asterisk
--
XK_plus
XK comma
--
XK minus
--
XK_period
XK slash
--
XK 0
--
XK 1
--
XK 2
--
XK 3
XK 4
--
XK 5
XK 6
--
XK 7
XK 8
--
XK 9
XK colon
--
XK_semi colon
XK less
XK_equal
XK_greater
XK_question
XK at
XK A
XK B
XK C
XK D
XK E
Description
Space
Exclamation point
Quotation mark
Number sign
Dollar sign
Percent sign
Ampersand
Apostrophe
Left parenthesis
Right parenthesis
Asterisk
Plus sign
Comma
Hyphen, minus sign
Full stop
Solidus
Digit zero
Digit one
Digit two
Digit three
Digit four
Digit five
Digit six
Digit seven
Digit eight
Digit nine
Colon
Semicolon
Less than sign
Equals sign
Greater than sign
Question mark
Commercial at
Latin capital A
Latin capital B
Latin capital C
Latin capital D
Latin capital E
Character
/
0
1
2
3
4
5
6
7
8
9
;
<
?
@
A
B
C
D
E
628
Xlib Reference Manual
Table H-3. LATIN1 (continued)
Keysym
XK F
--
XK G
--
XK H
--
XK I
--
XK J
--
XK K
--
XK L
--
XK M
--
XK N
--
XK 0
XK P
XK Q
XK R
XK S
XK T
XK U
--
XK V
--
XK W
XK X
--
XK Y
--
XK Z
XK bracketleft
--
XK backslash
--
XK_bracketright
XK asciicircum
XK underscore
XK_qubteleft
XK a
--
XK b
--
XK c
--
XK d
--
XK e
--
XK f
XK_g
XK h
--
XK i
--
Descdpdon
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
capital F
capital G
capital H
capital I
capital J
capital K
capital L
capital M
capital N
capital O
capital P
capital Q
capital R
capital S
capital T
capital U
capital V
capital W
capital X
capital Y
Latin capital Z
Left square bracket
Reverse solidus
Right square bracket
Circumflex accent
Low line
Grave accent
Latin small a
Latin small b
Latin small c
Latin small d
Latin small e
Latin small f
Latin small g
Latin small h
Latin small i
Latin small j
Character
F
G
H
I
J
K
L
M
N
O
P
Q
R
S
T
U
V
W
X
Y
Z
[
\
]
^
Appendix H: Keysyms 629
Table H-3. LATIN1 (continued)
Keysym
XK k
XK 1
XK m
XK n
--
XK o
--
XK_p
XK_q
XK r
--
XK s
XK t
XK u
--
XK v
--
XK w
--
XK x
--
XK_y
XK z
--
XK braceleft
--
XK bar
--
XK_braceright
XK asciitilde
XK_nobreakspace
XK_exclamdown
XK cent
XK_sterling
XK_currency
XK_yen
XK_brokenbar
XK_section
XK diaeresis
XK_copyright
XK_ordfeminine
XK_guillemotleft
XK_notsign
XK_hyphen
XK_regi stered
XK_macron
XK_degree
Description
Latin small k
Latin small 1
Latin small m
Latin small n
Latin small o
Latin small p
Latin small q
Latin small r
Latin small s
Latin small t
Latin small u
Latin small v
Latin small w
Latin small x
Latin small y
Latin small z
Left brace
Vertical line
Right brace
Tilde
No-break space
Inverted exclamation mark
Cent sign
Pound sign
Currency sign
Yen sign
Broken vertical bar
Paragraph sign, section sign
Diaeresis
Copyright sign
Feminine ordinal indicator
Left angle quotation mark
Not sign
Short horizontal hyphen
Registered trade mark sign
Macron
Degree sign, ring above
Character
k
1
u
v
w
x
Y
z
{
I
}
63O
Xlib Reference Manual
Table H-3. LATIN1 (continued)
Keysym
XK Odiaeresis
XK_mu It iply
XK Oobl ique
XK_Ugrave
XK Uacute
XK Ucircumflex
XK Udiaeresis
XK Yacute
XK Thorn
XK_s s ha rp
XK_agrave
XK aacute
--
XK acircumflex
XK atilde
XK adiaeresis
XK_aring
XK ae
XK ccedilla
XK_egrave
XK eacute
XK_ecircumflex
XK_ediaeres is
XK_igrave
XK iacute
XK_icircumflex
XK idiaeresis
XK eth
XK ntilde
XK_ograve
XK oacute
XK_oc ircumflex
XK otilde
XK_odiaeresis
XK_divi sion
XK_oslash
XK_ugrave
XK uacute
Description
Latin capital 0 with diaeresis
Multiplication sign
Latin capital 0 with oblique stroke
Latin capital U with grave accent
Latin capital U with acute accent
Latin capital U with circumflex accent
Latin capital U with diaeresis
Latin capital Y with acute accent
Icelandic capital THORN
German small sharp s
Latin small a with grave accent
Latin small a with acute accent
Latin small a with circumflex accent
Latin small a with tilde
Latin small a with diaeresis
Latin small a with ring above
Latin small diphthong ae
Latin small c with cedilla
Latin small e with grave accent
Latin small e with acute accent
Latin small e with circumflex accent
Latin small e with diaeresis
Latin small i with grave accent
Latin small i with acute accent
Latin small i with circumflex accent
Latin small i with diaeresis
Icelandic small eth
Latin small n with tilde
Latin small o with grave accent
Latin small o with acute accent
Latin small o with circumflex accent
Latin small o with tilde
Latin small o with diaeresis
Division sign
Latin small o with oblique stroke
Latin small u with grave accent
Latin small u with acute accent
Character
0
632
Xlib Reference Manual
Table H-3. LATIN1 (continued)
Keysym
XK ucircumflex
XK udiaeresis
XK_yacut e
XK t ho rn
XK_ydiaeresis
Description
Latin small u with circumflex accent
Latin small u with diaeresis
Latin small y with acute accent
Icelandic small thorn
Latin small y with diaeresis
Character
Appendix H: Keysyms 633
Table H-4. LATIN2
Keysym
XK_Aogonek
XK breve
XK Lstroke
--
XK Lcaron
XK Sacute
XK Scaron
XK Scedilla
--
XK Tcaron
--
XK Zacute
--
XK Zcaron
--
XK Zabovedot
--
XK_aogonek
XK_ogonek
XK istroke
--
XK icaron
XK sacute
--
XK caron
--
XK scaron
--
XK scedilla
--
XK tcaron
--
XK zacute
--
XK_doubleacute
XK zcaron
--
XK_zabovedot
XK Racute
--
XK Abreve
--
XK Cacute
--
XK Ccaron
XK_Eogonek
XK_Ecaron
XK Dcaron
XK Nacute
XK_Ncaron
XK_Odoubleacute
XK_Rcaron
XK_Uring
XK_Udoubleacute
XK_Tcedilla
634
Description
Latin capital A with ogonek
Breve
Latin capital
Latin capital
Latin capital
Latin capital
Latin capital
Latin capital
Latin capital
Latin capital
L with stroke
L with caron
S with acute accent
S with caron
S with cedilla
T with caron
Z with acute accent
Z with caron
Latin capital Z with dot above
Latin small a with ogonek
Ogonek
Latin small I with stroke
Latin small I with caron
Latin small s with acute accent
Caron
Latin small s with caron
Latin small s with cedilla
Latin small t with caron
Latin small z with acute accent
Double acute accent
Latin small z with caron
Latin small z with dot above
Latin capital R with acute accent
Latin capital A with breve
Latin capital C with acute accent
Latin capital C with caron
Latin capital E with ogonek
Latin capital E with caron
Latin capital D with caron
Latin capital N with acute accent
Latin capital N with caron
Latin capital O with double acute accent
Latin capital R with caron
Latin capital U with ring above
Latin capital U with double acute accent
Latin capital T with cedilla
Character
15
6
T
Xlib Reference Manual
Table H-4. LATIN2 (continued)
Keysym
XK racute
--
XK abreve
--
XK cacute
XK ccaron
--
XK_eogonek
XK ecaron
XK dcaron
--
XK nacute
--
XK ncaron
XK odoubleacute
--
XK rcaron
--
XK_uring
XK udoubleacute
--
XK tcedilla
XK abovedot
--
Description
Latin small
Latin small
Latin small
Latin small
Latin small
Latin small
Latin small
Latin small
Latin small
Latin small
Latin small
Latin small
Latin small
Latin small
Dot above
r with acute accent
a with breve
c with acute accent
c with caron
e with ogonek
e with caron
d with caron
n with acute accent
n with caron
o with double acute accent
r with caron
u with ring above
u with double acute accent
t with cedilla
Character
Appendix H: Keysyms 635
Table H-6. LATIN4
Keysym
XK_kappa
XK Rcedilla
--
XK Itilde
--
XK Lcedilla
--
XK Emacron
--
XK Gcedilla
XK Tslash
--
XK rcedilla
--
XK itilde
--
XK icedilla
--
XK emacron
--
XK_gacute
XK tslash
--
XK ENG
--
XK_eng
XK Amacron
--
XK_Iogonek
XK Eabovedot
--
XK Imacron
--
XK Ncedilla
--
XK Omacron
--
XK Kcedilla
--
XK_Uogonek
XK Utilde
--
XK Umacron
--
XK amacron
--
XK_iogonek
XK eabovedot
--
XK imacron
--
XK ncedilla
--
XK omacron
--
XK kcedilla
--
XK_uogonek
XK utilde
XK umacron
--
Description
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
small kappa
capital R with cedilla
capital I with tilde
capital L with cedilla
capital E with macron
capital G with cedilla
capital T with oblique slxoke
small r with cedilla
small i with tilde
small I with cedilla
small e with macron
small g with acute accent
Latin small t with oblique stroke
Lappish capital ENG
Lappish small eng
Latin capital A with macron
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
Latin
capital
capital
capital
capital
capital
capital
capital
capital
capital
small
small
small
small
small
small
small
small
small
small
I with ogonek
E with dot above
I with macron
N with cedilla
O with macron
K with cedilla
U with ogonck
U with tilde
U with macron
a with macron
i with ogonek
e with dot above
i with macron
n with cedilla
o with macron
k with cedilla
u with ogonek
u with tilde
u with macron
Character
O
K.
i
Appendix H: Keysyms 637
Table H-7. GREEK
Keysym
XK Greek ALPHAaccent
-- _
XK Greek EPSILONaccent
-- _
XK Greek ETAaccent
-- _
XK Greek IOTAaccent
-- _
XK Greek IOTAdiaeresis
-- _
XK Greek IOTAaccentdiaeresis
-- _
XK Greek OMICRONaccent
-- _
XK Greek UPSILONaccent
-- _
XK Greek UPSILONdieresis
-- _
XK Greek UPSILONaccentdieresis
-- _
XK Greek OMEGAaccent
-- _
XK_Greek_alphaaccent
XK_Greek_epsilonaccent
XK Greek etaaccent
-- _
XK Greek iotaaccent
-- _
XK Greek iotadieresis
-- _
XK_Greek_iotaaccentdieresis
XK Greek omicronaccent
--
--
XK_Greek_upsilonaccent
XK_Greek_upsilondieresis
XK_Greek_upsilonaccentdieresis
XK_Greek_omegaaccent
XK Greek ALPHA
--
--
XK Greek BETA
--
--
XK Greek GAMMA
--
--
XK Greek DELTA
--
--
XK Greek EPSILON
--
--
XK Greek ZETA
--
--
XK Greek ETA
--
--
XK Greek THETA
--
--
XK Greek IOTA
--
--
XK Greek KAPPA
--
--
XK Greek LAMBDA
--
--
XK Greek MU
--
--
XK Greek NU
--
--
XK Greek XI
--
--
XK_Greek OMICRON
--
XK Greek PI
--
--
638
Description
Greek capital alpha with accent
Greek capital epsilon with accent
Greek capital eta with accent
Greek capital iota with accent
Greek capital iota with diaeresis
Greek capital iota with accent+dieresis
Greek capital omicron with accent
Greek capital upsilon with accent
Greek capital upsilon with dieresis
Greek capital upsilon with accent+dieresis
Greek capital omega with accent
Greek small alpha with accent
Greek small epsilon with accent
Greek small eta with accent
Greek small iota with accent
Greek small iota with dieresis
Greek small iota with accent+dieresis
Greek small omicron with accent
Greek small upsilon with accent
Greek small upsilon with dieresis
Greek small upsilon with accent+dieresis
Greek small omega with accent
Greek capital alpha
Greek capital beta
Greek capital gamma
Greek capital delta
Greek capital epsilon
Greek capital zeta
Greek capital eta
Greek capital theta
Greek capital iota
Greek capital kappa
Greek capital lambda
Greek capital mu
Greek capital nu
Greek capital xi
Greek capital omicron
Greek capital pi
Character
A
B
F
A
E
Z
H
O
I
K
A
M
N
O
H
Xlib Reference Manual
Table I- 1. Standard Cursor Symbols
Symbol Value
Row I
XC X cursor 0
XC arrow 2
--
XC based arrow down 4
XC_ba sed_arrow_up 6
XC boat 8
--
XC_bogosity I0
XC bottom left corner 12
-- _ _
XC_bot t om_right_corne r 14
XC bottom side 16
-- _
XC bottom tee 18
-- _
XC_box_spiral 20
XC_cent er_pt r 22
Row 2
XC__c i rc le 24
XC__clock 26
XC_coffee_mug 28
XC_cross 30
XC_cros s reverse 32
--
XC_cros shair 34
XC_diamond_cros s 36
XC_dot 38
XC_dotbox 40
XC_double_arrow 42
XC_draft_large 44
XC_draft_small 46
Row 3
XC_draped_box 48
XC_exchange 50
XC_fleur 52
XC_gobble r 54
XC_gumby 56
XC_handl 58
XC_hand2 60
XC_heart 62
XC_icon 64
XC_iron_cro s s 66
XC_Ie ft_pt r 68
XC_Ie ft_s ide 70
Symbol
Value
Row 4
XC left tee
-- _
XC left button
-- _
XC ii angle
XC ir angle
-- _
XC man
--
XC middlebutt on
--
XC mouse
--
XC_pencil
XC_pi rate
XC_pI u s
XC_qu e s t i on_a rrow
XC_ri ght_pt r
Row 5
XC_right_side
XC_right_tee
XC_rightbutton
XC_rt l_logo
XC sailboat
XC sb down arrow
--
XC sb h double arrow
--
XC sb left arrow
--
XC_sb_right_arrow
XC_sb_up_arrow
XC sb v double arrow
--
XC shuttle
--
Row 6
XC_sizing
XC_spider
XC_spraycan
XC star
XC_target
XC tcross
XC_top_le ft_arrow
XC_top_le ft corner
--
XC_top_right_corner
XC_top_side
XC_top_tee
XC trek
--
Row 7
XC ul angle
XC_umbr e i i a
XC_ur_angle
XC watch
XC xterm
XC_num_glyphs
72
74
76
78
80
82
84
86
88
90
92
94
96
98
100
102
104
106
108
110
112
114
116
118
120
122
124
126
128
130
132
134
136
138
140
142
144
146
148
150
152
154
642
Xlib Reference Manual
Table J-2 describes the maximum metrics for each font. These are the values of the
max bounds member of XFontStruct (which is an XCharStruct structure with the
--
members shown in the table). Note that it is unlikely that any single character will be the
biggest in all the measurements simultaneously; these describe the largest lbearing of
any character in the font, the largest rbearing for any character in the font, and so on.
For a description of each of the character measurements, see Volume One, Section 6.2.3.
Table J-2. Maximum Font Metrics
Font Name
6x10
6x12
6x13
8x13
8xl3bold
9x15
a14
apl-s25
arrow3
chp-s25
chs-s50
crturz
cursor
cyr-s25
cyr-s30
cyr-s38
dancer
ent
fcor-20
fg-13
fg-16
fg-18
fg-20
fg-22
fg-25
fg-30
fg-40
fgl-25
fgb-13
fgb-25
fgbl-25
fgbl-30
fgi-2o
fgil-25
fgs-22
fixed
ibearing rbearing ascent descent width
0 6 8 2 6
0 6 8 4 6
0 6 10 3 6
0 8 10 3 8
0 8 10 3 8
0 9 12 3 9
0 7 12 2 7
0 27 20 5 27
0 59 8 18 59
0 34 23 2 34
0 50 40 10 50
0 100 0 155 100
1 16 15 16 17
0 28 24 5 28
0 37 30 8 37
0 37 30 8 37
0 47 36 10 47
0 640 0 170 640
0 16 16 4 16
0 9 11 2 9
0 10 11 5 10
0 12 13 5 12
0 12 15 5 12
0 13 17 5 13
0 16 20 5 16
0 19 25 5 19
0 25 33 7 25
0 14 20 5 14
0 10 11 2 10
0 17 20 5 17
0 16 20 5 16
0 16 20 10 16
0 12 15 5 12
0 16 20 5 16
0 13 17 5 13
0 6 10 3 6
644
Xlib Reference Manual
Table J-2. Maximum Font Metrics (continued)
Font Name
fqxb-25
fr-25
fr-33
frl-25
fr2-25
fr3-25
frb-32
fri-33
fril-25
ger-s35
grk-s25
grk-s30
hbr-s25
hbr-s40
ipa-s25
kanal4
krivo
lat-s30
met25
micro
mit
oldera
plunk
r14
rot-sl6
runlen
sansl2
sansbl2
sansil2
serifl0
serifl2
serifbl0
serifbl2
serifil0
serifil2
stan
stempl
sub
subsub
sup
supsup
swd-s30
sym-s25
sym-s53
Ibearing rbearing
ascent
descent
width
0 22 20 5 22
0 17 20 5 17
0 23 23 10 23
0 16 20 5 16
0 16 20 5 16
0 16 20 5 16
0 19 24 8 19
0 26 24 9 26
0 17 20 5 17
0 32 30 5 32
0 27 20 5 27
0 35 26 5 35
0 20 32 13 20
0 29 50 14 29
0 16 20 5 16
0 7 12 2 7
0 49 50 50 49
0 16 25 5 16
0 7 21 9 7
0 4 5 0 4
0 161 143 2 161
0 15 9 6 15
0 26 21 9 26
0 7 12 2 7
0 25 16 0 25
0 96 3 0 96
0 11 11 3 11
0 11 11 3 11
0 11 11 3 11
0 8 10 3 8
0 11 11 3 11
0 8 10 3 8
0 11 11 3 11
0 8 10 3 8
0 11 11 3 11
0 225 108 108 225
0 28 28 0 28
0 20 9 12 20
0 13 0 14 13
0 20 28 -7 20
0 13 36 -22 13
0 16 25 5 16
0 24 20 5 24
0 34 35 18 34
Appendix J: Fonts 645
Table J-2. Maximum Font Metrics (continued)
Font Name
variable
vbee-36
vctl-25
vg-13
vg-20
vg-25
vg-31
vg-40
vgb-25
vgb-31
vgbc-25
vgh-25
vgi-20
vgi-25
vgi-31
vgl-40
vgvb-31
vmic-25
vply-36
vr-20
vr-25
vr-27
vr-30
vr-31
vr-40
vrb-25
vrb-30
vrb-31
vrb-35
vrb-37
vri-25
vri-30
vri-31
vri-40
vsg- 114
vsgn-57
vshd-40
vtbold
vtsingle
vxms-37
vxms-43
xif-s25
Ibearing rbearing ascent descent width
16 16
0 38
0 25
0 13
0 20
0 23
0 31
0 37
0 23
0 32
0 22
0 23
0 20
0 23
0 31
0 37
0 32
0 28
0 16
0 24
0 25
0 28
0 31
0 28
0 38
0 25
0 30
0 30
0 35
0 51
0 27
0 30
0 28
0 43
0 189
0 95
0 38
0 8
0 9
0 44
0 56
0 16
11
29
19
11
16
20
24
32
20
24
20
20
16
20
24
32
24
20
27
15
21
20
22
25
30
20
22
25
26
27
20
22
25
33
100
50
32
10
12
28
35
20
3
7
6
2
4
5
7
8
5
7
5
5
4
5
7
8
7
5
9
5
4
7
8
6
10
5
8
6
9
10
5
8
6
7
12
7
8
3
3
9
8
5
16
38
25
13
20
23
31
37
23
32
22
23
20
23
31
37
32
28
16
24
25
28
31
28
38
25
30
30
35
51
27
30
28
43
189
95
38
8
9
44
56
16
646
Xlib Reference Manual
The remaining pages of this appendix show the characters in each font, actual size, as they
would appear on a 900 x 1180 pixel, 10" x 13.5" screen (Sun). On a screen with different
pixel density, these fonts would appear a proportionally different size.
For most fonts, the entire character set is shown. For very large fonts, we have sometimes
shown just a few characters to save space. Also, fonts that begin with many blank charac-
ters are shown with most leading blanks removed. Therefore, you can't always get the char-
acter number of each cell in the font by counting from the first cell we have shown. Use xfd
to quickly determine the code for a particular cell.
Appendix J: Fonts 647
6x10
< => ? A' CIEFO H I 3 KLh NO pQIRST U/WX y
Z [,N ] ^_"abc de(gh ilj k lnoprstuvw
6x12
8x13
648
Xlib Reference Manual
cyr-s25
E F,XM K
PCTUB
, a 6 a e
lIIAfi /1
JI MHOFI
I3
r :x lj K
FXH
3
cyr-s30
KJIMHO
PCTYB
)KRa 6
H
p c r yB
Appendix J: Fonts 651
fr2-25
n o p t !vwxyz { [
fr3-25
frb-32
ABCDEFGHI JK
LMNOPORSUVWXYZ
abcdefghi j kl mnopq
rstuvwxyz
Appendix J: Fonts 653
fri-33
:v ! ",X,&" ()+,
-. Cf 2S4 56789:
fril-25
abe g'
l rnno ,
654 Xlib Reference Manual
fgs-22
fixed
/j012 45 B789 : ; <=> ?eIFBC DE'FGH I.IIKLN NO PQ RS TU!VI, I'X YZ [ \ ]
"l-,'abcdef9hlijklnopJqrs:tulvwxyzi{I ]-~[111 IIIIIIII]11]1
656
Xlib Reference Manual
fqxb-25
" #$.&" ( ) +, -. /Ell
:-< ?
e h--klg 1 j mnopqrstuv
wxyz{I i
fr-25
? @ ABC:DEFGHI JKLMNOPQRS
L j m:no s uvwxyz
Appendix J: Fonts 657
fcor-20
.v ,,#$&, ( )
*+, --. /01 23456789: ; < =>
? @ABCDEFGHI JKLM:NOPQRS
TUVWXYZ[ \] ^_ abcdefgh
ij kl mnopqrs tuvwxyz
fg-13
#S&' ( )+,-. /81Z3q55?S9:
FGHIJK_MNOPQRSTUVWXY[\]^_'aBcdef9
i jklnopqrstuvxz{I}-
fg-16
{"#$,& ' ( )*+ ,-. /01,23456,2'89 - ;(=>?
OABCDE F GHIJKLHNOPQRSTUVW)YZ[ ]
abcdefgh1j klmnopqrstuvwxlYzl{ I }~
fg-18
! "' #$%& ( ) * +, -. /01234567
89- ; !<: > ?@ABCDEF GHI JK_MNOPQiRS
TUVWXYZ[ \] ^ " abcdefghi jk mno
pqrstuvwxyz- I }-
Appendix J: Fonts 661
hbr-s25
hbr-s40
664
Xlib Reference Manual
ipa-s25
-./ 1 4 8 ,<-->
BCDEFGHII JKLrlNOPQRSTUVI4
XYZ [\] 1'e 'abcd!e f ghi j k lm
,nopqr s tuvxgz { I } ~
Appendix J: Fonts 665
sym-s53
674
Xlib Reference Manual
vgb-25
qr s t uvwxyz ~
vgb-31
678 Xlib Reference Manual
vgvb-31
i V- TI
" -' " I "
<-> CD
!' a c deaf g h I k
I mnopqr s t uvw
xyz{'j
vmic-25
bc e f ghi i I mn 13
pq r st uv wx y z { I }
,N
682 Xlib Reference Manual
vr-25
Z[\]^_ abcde'fgh
i j 'k 1 m n o p q r s t u v w
vr-27
_< '> = v ! " , $ y. &' ( )
* +, - f 01 23t5'67
89 : ; : - > ? A!BCDE
11U V W YZ _ a
b c de f g hi j k 1 mn o
pqr s t uvwxy z { }
684 Xlib Reference Manual
vr-30
r Y 6 T +
NOP Q. RS TUVWXYZ
[ \ ] "_' abc de fg
hi j kl mnopq r s t
u vwxy z { } ~f
T
.<>.-v ! ",%&' ()
*+,-. /01234567
89: ; <-- >? @ABCDE
F 6HI J KL NNOP QRS
TUVyXYZI jk" '
_ a
bcd f,gh 1 mno
p q !r s t u v w x y z { }
N
Appendix J: Fonts 685
vr-40
,-. /01,2
uV3
E G I JK
MNOP QRS TUVW
:XYZ[ \ ] a b
c de f ghi ] kl m
nopqrs
'{ ,,,
yz I }
tuvwx
686
Xlib Reference Manual
vrb-31
45678
AB CDE
-
9: ; <=>?@
FGHI J K L 1VI
NOPQRS TUVWXYZ
[hi! ' abcdefg
] ki-mnop q r s t
{
uvwxyz }
688 Xlib Reference Manual
vri-40
< > -- V ! "
, DE=FG
HI JKLMNOP
QRSTUVWXY
1 mn o p q r s t
Appendix J: Fonts 693
vsg-114
vsgn-57
vshd-40
694
Xlib Reference Manual
vxms-43
696
Xlib Reference Manual
xif-s25
,-. /012345B789: ; <=>?cA
BCDEFGHI JK _tINOPQRST JVkl
XYZ[ \] A_, abcdef ghi j kl m
nopqr s t iuvxgz{ I } ~ 1111
Appendix J: Fonts 697
K
Xlib Release 3 Update
This appendix is an update to Volume Two, Xlib Reference Manual. It describes the
changes to Xlib, and to application writing standards in general, that took place in Release
3. Next, there is a description of corrections to the book based on Release 3 protocol clarifi-
cations. Some of these apply to Release 2 as well.
New Routines
Five new routines have been added to Xlib in Release 3. They are all very simple, and in
fact four of them could actually have been simple macros. Here are their definitions:
Example K- 1. Code for routines added to Xlib in ReAease 3 Update
long XMaxRequestSize(dpy)
Display *dpy;
{
return dpy->max_request_size;
}
char *XResourceManagerString(dpy)
Display *dpy;
{
return dpy->xdefaults;
} -
unsigned long XDisplayMotionBufferSize(dpy)
Display *dpy;
{
return dpy->motion_buffer;
)
XDisplayKeycodes(dpy, min_keycode_return, max_keycode_return)
Display *dpy;
int *min_keycode_return, *max_keycode_return;
*min_keycode_return = dpy->min_keycode;
*max_keycode_return = dpy->max_keycode;
Appendix K: Xlib Release 3 Update 699
Command Line Options
The convention until Release 3 has been that any command line argument containing : was a
display specification and any argument beginning with = was a geometry specification.
These no longer hold, and none of the core clients now operate this way. Applications
should require an explicit -display or -geometry option. The = in the geometry
specification is now optional.
Fonts
There is no standard that specifies the fonts a server must provide. However, this should not
be a portability problem for properly written applications, because fonts should be resources
that can be specified by the user or system administrator. You'll probably want to "build
in" default font names, either in an app-defaults file or in your code, but your code ought to
be robust enough to fall back on the default font in the GC if all else fails.
We bring this up because the font environment provided in the MIT distribution has
changed substantially since Release 2. In Release 3, a unified family of fonts has been
donated by Adobe, Inc. and BitStream, Inc. These include fonts of various sizes in the
Courier, Times Roman, Helvetica, New Century Schoolbook, and Bitstream Charter families
in regular weight, bold, and italic, and symbol fonts in various sizes from Adobe/DEC are
also provided. Furthermore, font aliasing has been added so that font names in code and
resource files can be long enough to fully describe a font, but the actual files containing the
fonts may be 14 characters or less for compatibility with System V. An organized font-
naming scheme has also been instituted.
The new font names look like this:*
-adobe-cou rie r-bo id-o-no rma i--I 0-10 0-7 5-7 5-m- 6 0-i so 8 8 5 9-1
Because the font names that applications and users must specify are now so long, wildcards
are now permitted as arguments to the Xlib routines XLoadFont, XQueryFont, and
XLoadQueryFont. They were already permitted for the routines XListFonts and
XL-i stFont sWith In f-o.
To specify a font, you specify only the fields that are important to you. For example, if you
wanted to use a 12 point Roman Courier font for an xterm, you could use the either of the
following names:
-adobe- cou rie r-medium- r-norma i-- 12-12 0- 7 5-7 5-m- 7 0-i so 8 8 5 9-1
*-courier-*-r-*-I 2 0-*
Note that you should match the point size field which is measured in tenths of a point (the
120 in this example) rather than the pixel size field (the 12). This allows your defaults to
*Most of this description of the new font-naming scheme was provided by Jim Fulton of the X Consortium.
Appendix K: Xlib ReAease 3 Update 701
work properly on tubes of different resolution. For example, to specify a 24 point, normal
italic Charter,
*-cha rt e r-medium-i-* -240-*
will match either:
-bit st ream-cha rt er-medium-i-normal--25-240- 75- 75-p- 136-i s o 8859-1
-bit st ream-cha rt er-medium-i-no rma i--33-240-I 00-I 00-p-I 79-i so 8859-1
depending on whether the 75 dpi or 100 dpi font directory comes first in your font path.
This example also demonsates why the pixel size should not be used when wildcarding.
On a 75 dpi monitor, a 24 point font will be 25 pixels tall; on a 100 dpi monitor, it will be
33 pixels tall.
If your application depends on the Release 2 fonts, they can be used with a Release 3 server
by placing the Release 2 fonts in a directory and allowing users to add it to their font path
(see the mkfontdir man page). If you have particular fonts that you want to use, and you
have them in source (BDF) form, then most server vendors should supply a font compiler
with their server, allowing you to import fonts.
Internal and Invisible Changes to Xlib
Xlib has been modified internally so that it will compile and run on Cray machines. This
does not change the programming interface. Untested support for Mips computers has also
been contributed.
Other internal changes include improvements to Graphics Context cache flushing. The
region code was improved, including fix for overflow on complex regions.
Small Interface Changes
The routines XChangeProperty and XGetWindowProperty now rake care of con-
verting arrays of chars, shorts, and longs to and from the formats required by the protocol
(8-bit, 16-bit, and 32-bit signed integers respectively). XGetWindowProperty now
always mallocs space for its return data even if the data has zero elements.
XLookupString now has list of key bindings per display, can cope with modifier map-
ping changes, handles upper and lower case of all Latin-1 keysyms, doesn't convert non-
Latin-1 keysyms, understands Control 2-8 and/, and uses the preferred protocol definition
for CapsLock.
XrmPutFileDatabase will write file with proper special char quoling.
702
Xlib Reference Manual
Server Fixes
Some problems that existed in sample server code affected application programming under
Release 2. You may wish to inspect programs for workarounds for these problems. We
cannot list and explain all the bugs that were found and fixed; see the CHANGES file in the
appropriate directory of the X distribution. However, the following changes to the device-
independent (dix) part of the server were among the most likely to affect client program-
ming:
The AllocColorPlanes request has been fixed to allow allocation of all planes at
once.
Delayed/Buffered writes for client events implemented. Delayed writes are simply a per-
formance improvement; the server now queues all events generated by a single request
for greater network efficiency. Buffered writes fix a bug that appeared when reading
long properties from the server. Client connections would be severed when the client
refused or was slow in reading a long message from the server.
SelectionClear events are now sent to the selection owner (set by xSet-
SelectionOwner, not the window creator.
Font routines and color name lookup routines now fold upper case in names to lower
case. Case is no longer significant in the color database, and items in the database
differing only in case have been removed.
Save under support has been added to the device-independent portion of the server. This
code supplies save unders to any server which has backing store but not save unders
implemented in the device-dependent portion.
Mixing window gravity and bit gravity has been fixed.
Many other specious requests also generate Value errors now.
The Xmu library
A new miscellaneous utilities library has been placed on the X distribution tape. This
library is not part of the Xlib standard. It contains routines which only use public interfaces
so that it may be layered on top of any proprietary implementation of Xlib or Xt.
It is intended to support clients in the MIT distribution; vendors may choose not to distri-
bute this library if they wish. Therefore, applications developers who depend on this library
should be prepared to treat it as part of their software base when porting.
The following routines apply to Xlib (there are a few not described here that are for use with
the X Toolkit):
Routines to cache atoms, avoiding multiple server round-trips. XmuMakeAtom creates
and initializes an opaque AtomRec. XmuInternAtora fetches an atom from cache or
server. XmuInternStrings fetches multiple atoms as strings. XmuGetAtomNarae
returns name of an atom. XmuNameOfAtora returns name from an AtomPtr.
Appendix K: Xlib Release 3 Update 703
XmuCreatePixmapFromBitmap routine converts a bitmap to a pixmap. The routine
uses xc opyP i ane).
XmuConvertStandardSelection converts a known selection into the appropriate
target type.
XmuPrintDefaultErrorMessage prints a nice error that looks like the usual mes-
sage. Returns 1 if the caller should consider exiting, else 0.
.XmuDrawRoundedRectangle draws a rounded rectangle, x, y, w, h are the dimen-
sions of the rectangle, ew and eh are the sizes of a bounding boxes that each corner is
drawn inside of.
XmuReadBitmapDataFromFile reads X10 or Xll format bitmap files and return
data.
Release 3 Protocol Clarifications
The following changes are not errors, per se. They reflect clarifications of the protocol
specification made in Release 3. These changes, where noted, were also true in Release 2.
Page 36
The return type from XAddPixel is deleted. XAddPixel has its value argument
changed from int to long.
Page 53
XChangeActivePointerGrab is capable of generating a BadValue error.
Page 70
XCheckMaskEvent has its mask argument changed from unsigned long to long.
Page 73
XCheckWindowEvent has its mask argument changed from int to long.
Page 77
On the XClearArea page, the first sentence of the third paragraph should end: "... the
rectangle is tiled with a plane__mask of all l's, a function of GXcopy, and a
subwindow._mode or ClipByChildren." This should be true in Release 2.
Page 90
XCopyGC now generates a BadValue error when bits outside the set of valid GC mask
bits are set.
Page 92
The plane argument of XCopyPlane must be a plane that exists in the source drawable,
or a BadValue error is generated.
7O4
Xlib Reference Manual
Page 213
On the second page of XGet Image, the first sentence should say that the source window
must be viewable, not just mapped (all its ancestors also must be mapped). The page should
also mention that the pointer cursor is not included in the image. This is also true in
Release 2.
Page 219
The XTimeCoord structure has its x and y members changed from type unsigned
short tO short.
Page 248
The XGrabButton page should mention that the call overrides all previous passive grabs
by the same client on the same key/button combinations on the same window. This is also
true in Release 2.
Page 255
For XGrabPointer, the constant GrabNotViewable is returned for the reasons given
at the bottom of the page, but also if the confine_to window is completely outside the
root window. This was true in Release 2.
Page 284
The string that XLookupString returns in the buffer argument is in Latin-1 encoding,
not necessarily in ASCII. (Latin-1 uses codes 128 to 255 to specify foreign characters,
while ASCII uses only up to 127. ASCII is a subset of Latin-1.)
Page 291
The event_mask argument of XMaskEvent changes from unsigned long tO long.
Page 349
The XReparentWindow page should say that the reparenting leaves unchanged the abso-
lute coordinates (relative tO the root window) of the upper-left outer comer of the window.
This was true in Release 2.
Page 391
The event mask argument of XSelectInput changes from type unsigned long to
type long.
Page 393
Th'e event_mask argument of XSendEvent changes from type unsigned long to
type long. dso, XSendEvent can now generate a BadValue error if the event type
sent is not valid in the core or an extension.
Page 410
The error_code, request_code, and minor_code members of XErrorEvent
have been changed from type char to type unsigned char.
Page 429
In the paragraph about server restrictions on the XSetModifierMapping page, it should
mention that one restriction may be that it might not be possible tO disable autO-repeat on
certain keys. This is also true in Release 2.
Appendix K: Xlib Release 3 Update 705
0
0
0
At-a-glance 707
At-a-glance 709
About the Editor
Adrian Nye is a senior technical writer at O'Reilly and Associates. In addition
to the X Window System programming manuals, he has written user's manuals
for data acquisition products, and customized UNIX documentation for Sun
Microsystems and Prime. Adrian has also worked as a programmer writing
educational software in C, and as a mechanical engineer designing offshore oil-
spill cleanup equipment. He has long-term interests in using his technical
writing skills to promote recycling and other environmentally-sound
technologies. He graduated from the Massachusetts Institute of Technology in
1984 with a B.S. in Mechanical Engineering.
[--] Please send me the information
I have asked for on the reverse
side of this card.
PLACE
STAMP
HERE
Name
Company __
Address _
City __
State. ZIP
(Fill out or tape
business card here)
Nutshell Handbooks
.u+s.ELL, O'Reilly & Associates. Inc.
I I 632 Petaluma Avenue
,+mt3BOOKS Sebastopol CA 95472
1] Please send me the information
I have asked for on the reverse
side of this card.
PLACE
STAMP
HERE
Name
Company
Address
City
State. ZIP
(Fill out or tape
business card here)
Nutshell Handbooks
,o+s.ELL O'Reilly & Associates. Inc.
I I 632 Petaluma Avenue
.A,DBOO,S Sebastopol CA 95472
Volume Two: Xlib Reference Manual
This book provides a complete reference to the X library, which is the lowest
level of programming interface to X. It provides:
Reference pages for each Xlib function
A permuted index to the Xlib functions
Reference pages for each event type
Description of macros
A listing of the standard color name database
Alphabetical index and description of structures
Alphabetical index and description of defined symbols
Alist ofkeysyms and their meanings, including sample characters
A list and illustration of the standard cursor font
A list of standard fonts with illustration of each font
A function group index, for finding the right routine for a
particular task
Single-page reference aids for the GC and window attributes
The Xlib Programming Manual and Xlib Reference Manual have been licensed and
customized by major system vendors, including Apollo, Silicon Graphics, Stellar,
Masscomp and Motorola. Other companies, including Intergraph, Sequent,
Pyramid, and Graphics Software Systems, are planning to ship the generic version
of the manuals with their systems.
723 pages
Volume 2: ISBN 0-937175-28-5 Set: ISBN 0-937175-26-9
O'Reilly & Associates, Inc.
I
Live Music Archive
Librivox Free Audio
Metropolitan Museum
Cleveland Museum of Art
Internet Arcade
Console Living Room
Books to Borrow
Open Library
TV News
Understanding 9/11