Digital PDFs

AA-MA99B-TE

May 1989

741 pages

Original

20MB

Document:	ULTRIX Worksystem Software Reference Pages, Sections 3Dwt, 3X11, and 3Xt
Order Number:	AA-MA99B-TE
Revision:	000
Pages:	741
Original Filename:

OCR Text

ULTRIX
Worksystem Software

Reference Pages,
Sections 3Dwt, 3X 11, and 3Xt

Order Number: AA-MA99B-TE

ULTRIX Worksystem Software

Reference Pages,
Sections 3Dwt, 3X11, and 3Xt

Order Number: AA-MA99B-TE

Product Version:
Operating System and Version:

digital equipment corporation
maynard, massachusetts

ULTRIX Worksystem Software, Version 2.2
ULTRIX-32, Version 3.1 or higher

Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as
set forth in subparagraph (c) (1) (ii) of the Rights in Technical Data and Computer Software clause of
DFARS 252.227-7013.
© Digital Equipment Corporation 1989
All rights reserved.

Portions of the information herein are derived from copyrighted material as permitted under license
agreements with AT&T and the Regents of the University of California. © AT&T 1979, 1984. All
Rights Reserved.
Portions of the information herein are derived from copyrighted material as permitted under a license
agreement with Sun MicroSystems, Inc. © Sun MicroSystems, Inc, 1985. All Rights Reserved.
Portions of this document © Massachusetts Institute of Technology, Cambridge, Massachusetts, 1984,
1985, 1986, 1988.
The information in this document is subject to change without notice and should not be construed as a
commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no
responsibility for any errors that may appear in this document.
The software described in this document is furnished under a license and may be used or copied only in
accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment that is not supplied by
Digital or its affiliated companies.

The following are trademarks of Digital Equipment Corporation:
CDA
DEC
DECUS
DECnet
DEC station
DECwindows
DDIF
DDIS

DTIF
MASSBUS
MicroVAX
Q-bus
ULTRIX
ULTRIX Mail Connection
ULTRIX Worksystem Software
VAX

VAX station
VMS
VMS/ULTRIX Connection
VT
XUI

~DmDDmD

UNIX is a registered trademark of AT&T in the USA and other countries.
X Window System, X, and XII are registered trademarks of MIT.

This manual was written and produced by the Open Software Publications group.

About This Manual

Organization
The ULTRIX Worksystem Software Reference Pages, Sections 3Dwt, 3Xii,
and 3Xt contain the reference pages for the XUI Toolkit functions, the XUI
Toolkit intrinsics, and the Xlib functions.

Format
Each reference page has the following general format.
Each has a title header consisting of the subject name and the appropriate
section number, for example, DwtAt tachedDB(3Dwt),
XOpenDisplay(3Xll), and XtCreateApplicationContext(3Xt).
The remaining subsections provide the specific information that is relevant to
the topic. In general, the following subsection titles are used where
appropriate:

Name
Lists the topic name and a short description of the entry.

Syntax
Provides the function definition. Boldface indicates characters typed
literally. Italics indicates variable information that is to be specified by the
user. An ellipsis ( ...) indicates that the preceding argument can be repeated.
Square brackets [ ] enclose optional arguments.

Arguments
Describes each arguments that passed to or returned by the function.

Description
Describes the function, its usage, and its effects. Note that all references to
chapters and sections in the Description section are for the respective,
companion descriptive guide listed in the See Also section at the end of that
page.

Diagnostics
Describes the diagnostic and error messages that may appear. In most cases,
self-explanatory messages are not listed.

Restrictions
Describes all known restrictions or limitations for that function.

Files
Lists the related files that are either used or created by the function.

See Also
Lists references to related functions in the same library and to other, related
documents.

Related Documents
XUI Style Guide
Describes the XUI user interface and, hence, the "look and feel" of an
XUI application.

Guide to Writing Applications Using XUI Toolkit Widgets
Describes how to create an application using the XUI Toolkit.

Guide to the XUI Toolkit: C Language Binding
Describes the widgets (user interface abstractions) that you can use to
write your XUI-based application.

Guide to the XUI Toolkit Intrinsics: C Language Binding
Describes the Intrinsics functions that you can use to write your XUIbased application or widget.

Guide to the Xlib Library: C Language Binding
Describes the low-level C functions that you can use to write your Xbased application.
X Window System Protocol: X Version 11

Describes the precise semantics of the XII protocol specification.

Conventions
The following typeface conventions are used in this manual:
special

In text, all function names, events, errors, constant names,
and pathnames are presented in this type.

UPPERCASE

Although the ULTRIX system differentiates between
lowercase and uppercase characters, uppercase is used
intentionally in this manual where it is applicable.

In addition, the following conventions are used in this manual:
•

To eliminate any ambiguity between those arguments that you pass and
those that a function returns to you, the explanations for all arguments

iv About This Manual

that you pass start with the word specifies or, in the case of multiple
arguments, the word specify. The explanations for all arguments that
are returned to you start with the word returns or, in the case of
multiple arguments, the word return. The explanations for all
arguments that you can pass and are returned start with the words
specifies and returns.
•

Any pointer to a structure that is used to return a value is designated as
such by the _return suffix as part of its name. All other pointers passed
to these functions are used for reading only. A few arguments use
pointers to structures that are used for both input and output and are
indicated by the jn_out suffix.

About This Manual v

XUI Toolkit Functions

Insert tabbed
divider here.
Then discard
this sheet.

DwtActivateWidget (3Dwt)
Name
DwtActivateWidget - Allows the application to simulate push button
activation.

Syntax
void DwtActivateWidget( widget)
Widget widget;

Arguments
widget

Specifies a pointer to the widget data structure.

Description
The DwtActi vateWidget function allows the application to simulate
push button activation. DwtActi vateWidget generates the same
highlighting and callbacks that would occur if the user clicks on a push
button. For example, an application might contain functions that a user could
choose either by selecting a menu option or by activating a push button. If
the user selected the menu option, the application could activate the
corresponding push button to maintain a consistent user interface. Only push
buttons are currently supported by DwtActi vateWidget.

See Also
Guide to the XUI Toolkit: C Language Binding
Guide to the XUI Toolkit Intrinsics: C Language Binding

Subroutines 3-1

DwtAddFontList (3Dwt)
Name
DwtAddFontList - Adds an entry to a font list.

Syntax
DwtFontList DwtAddFontList( list, font, charset)
DwtFontList list;
XFontStruct *font;
long charset;

Arguments
list

Specifies a pointer to the font list to which an entry will be
added.

font

Specifies a pointer to the font structure to be added to the
list.

charset

Specifies the character set identifier for the font. Values for
this argument can be found in the required file
/usr/include/cda_def.h.

Description
The DwtAddFontList function adds an entry to a font list.

Return Value
This function returns the new font list.

See Also
DwtCreateFontList (3Dwt)
Guide to the XUI Toolkit: C Language Binding
Guide to the XUI Toolkit Intrinsics: C Language Binding

3-2 Subroutines

DwtAttachedDB (3Dwt)
Name
DwtAttachedDB, DwtAttachedDBCreate, DwtAttachedDBPopupCreateCreates an attached dialog box or a pop-up attached dialog box widget to
contain other information/request (dialog) subwidgets.

Syntax
Widget DwtAttachedDB (parent_widget, name, defaultyosition,
x, y, title, style,
map callback, help callback)
Widget parent widget;
char *name; Boolean defaultyosition;
Position x, y;
DwtCompString title;
unsigned char style;
DwtCallbackPtr map_callback, help_callback;
Widget DwtAttachedDBCreate (parent_widget, name,
override_argUst, override_argcount)
Widget parent widget;
char * name; ArgList override argUst;
int override_argcount;
Widget DwtAttachedDBPopupCreate (parent_widget, name,
override_argUst,
override_argcount)
Widget parent widget;
char * name; ArgList override argUst;
int override_argcount;

Arguments
parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

DwtAttachedDB (3Dwt)
DwtNy attributes are used to position the widget. .This
argument sets the DwtNdefaultPosition attribute
associated with DwtDialogBoxCreate.

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window. This argument sets the DwtNy core
widget attribute.

title

Specifies the compound-string label. The label is given to
the window manager for the title bar if the DwtNstyle
attribute associated with DwtDialogBoxPopupCreate
is DwtModalor DwtModeless. However, the label is
used in the border if the DwtNstyle attribute associated
with DwtDialogBoxCreate is DwtWorkarea.
The attribute name associated with this argument is
DwtNtitle.

style

Specifies the style of the dialog box widget. You can pass
DwtModal, DwtModeless, or DwtWorkarea. This
argument sets the DwtNstyle attribute associated with
DwtDialogBoxCreate.

map_callback Specifies the callback function or functions called when the
window is about to be mapped. For this callback, the reason
is DwtCRMap. This argument is ignored if DwtNstyle is
DwtWorkarea.

This argument sets the DwtNmapCallback attribute
associated with DwtDialogBoxPopupCreate.
help_callback Specifies the callback function or functions called when a
help request is made. This argument sets the
DwtNhelpCallback common widget attribute.
override_ argUst

Specifies the application override argument list.
override_ argcount
Specifies the number of attributes in the application override
argument list (override _argUst).

3-4 Subroutines

DwtAttachedDB (3Dwt)
Description
The DwtAttachedDB and DwtAttachedDBCreate functions create an
instance of an attached dialog box widget or an attached dialog box pop-up
widget and return its associated widget ID. The
DwtAttachedDBPopupCreate function creates an instance of a pop-up
attached dialog box widget and returns its associated widget ID. The
attached dialog box acts as a container only, and provides no input semantics
over and above the semantics of the widgets that it contains. It differs from
the dialog box in its handling of child widgets. Constraints are placed on
each child widget at the time of creation. The default values for the
constraint attributes are placed on the child unless you specify values for the
constraint attributes. You specify these values either in the override argUst
or by calling XtSetValues.
By using the constraint attributes, you can attach each of the four sides of a
child widget (top, bottom, right side, and left side) to a side of the parent
attached dialog box, a side of another child widget, to a relative position
within the attached dialog box, to itself, or to nothing. The possible
attachments for each of the four sides are described in the Constraint
Attributes section. Specifying these attachments allows you to maintain the
position of child widgets within the attached dialog box as resizing occurs.
If only one attachment in a direction is specified with no width or height, the
default width or height for the widget is used.
For all attachment types, you can optionally specify an offset in pixels or font
units. The offset determines the amount of space between the side of the
child widget and the side or position you attach it to. By default, the child
widgets are positioned in an attached dialog box in terms of font units rather
than pixel units. (That is, DwtNunits is DwtFontUnits.) The X font
units are defined to be one-fourth the width of whatever font is supplied for
the common attribute DwtNfont. The Y font units are defined to be oneeighth the width of whatever font is supplied for DwtNfont.
The offsets given are automatically negated when dealing with right and
bottom sides. For example, a displacement of 5 means that the side stays 5
units to the right of its attachment if a left side, and 5 units to the left if a
right side.
Displacements default to a value specified in the attached dialog box for
attachments to the attached dialog box and the widget, and half the value
specified if attached to a position. Attaching to a point allows several
widgets to grow proportionally; the space between them should be the default
displacement. There are separate horizontal and vertical defaults.

Subroutines 3-5

DwtAttachedDB (3Dwt)
You can determine whether the attached dialog box will honor resize
geometry requests from a given child widget by appropriately setting the
DwtNresize attribute for that child. If it does honor a request, the attached
dialog box reconfigures all child widgets based on the initial coordinate
information. You can add child widgets after the attached dialog box widget
has been realized. If there is extra room in the attached dialog box, the new
child widget will appear. If there is not enough room, the attached dialog
box will ask the geometry manager for permission to resize.

Inherited Attributes
Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Dimension
Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

Determined by the geometr:
manager
Determined by the geometr:
manager
Widget-specific
Widget-specific
One pixel
Default foreground color
NULL
Default background color
NULL
Default color map
True
The bitwise AND of the
parent widget's
DwtNsensitive and

Attribute Name

Core Attributes

DwtNancestorSensit~

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

Constraint Attributes

3-6 Subroutines

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

attributes
NULL
Depth of the parent windm
NULL
True
The parent screen
NULL

OwtAttachedOB (30wt)
DwtNadbTopAttachment

DwtAttachmentType

DwtNadbBottomAttachment

DwtAttachmentType

DwtNadbLeftAttachment

DwtAttachmentType

DwtNadbRightAttachment

DwtAttachmentType

DwtNadbTopWidget
DwtNadbBottomWidget
DwtNadbLeftWidget
DwtNadbRightWidget
DwtNadbTopPosition
DwtNadbBottomPosition
DwtNadbLeftPosition
DwtNadbRightPosition
DwtNadbTopOffset

Widget
Widget
Widget
Widget
int
int
int
int
int

DwtAttachAdbif
DwtNrubberPositioning
is False
DwtAttachSelf if
DwtNrubberPositioning
is True
The default is
DwtAttachNoneif
DwtNrubberPositioning
is False.
The default is
DwtAttachSelfif
DwtNrubberPositioning
is True.
The default is
DwtAttachAdbif
DwtNrubberPositioning
is False.
The default is
DwtAttachSelf if
DwtNrubberPositioning
is True.
The default is
DwtAttachNone if
DwtNrubberPositioning
is False.
The default is
DwtAttachSelf if
DwtNrubberPositioning
is True.
NULL
NULL
NULL
NULL

Zero
Zero
Zero
Zero

The value specified with
DwtNdefaultVerticalOffset.
However, if
DwtNadbTopAttachment
is DwtAttachPosition or
DwtAttachSelf, the
default is one-half the value
specified with
DwtNdefaultVerticalOffset.

Subroutines 3-7

DwtAttachedDB (3Dwt)
DwtNadbBottomOffset

int

DwtNadbLeftOffset

int

DwtNadbRightOffset

int

DwtNresizable

Boolean

The default is the value
specified with
DwtNdefaultVerticalOffset.
However, if
DwtNadbBottomAttachment
is DwtAttachPosition or
DwtAttachSelf, the
default is one-half the value
specified with
DwtNdefaultVerticalOffset.
The default is the value
specified with
DwtNdefaultHorizontalOffs4
However, if
DwtNadbLeftAttachment
is DwtAttachPosition or
DwtAttachSelf, the
default is one-half the value of
DwtNdefaultHorizontalOffs
The value specified with
DwtNdefaultHorizontalOffs
However, if
DwtNadbRightAttachment
is DwtAttachPosition or
DwtAttachSelf, the
default is one-half the value
specified with
DwtNdefaultHorizontalOffs
True

Pixel
Pixel
Pixmap
Opaque *
DwtFontList
DwtCallbackPtr
unsigned char
unsigned char

Default foreground color
Default foreground color
NULL
NULL
The default XUI Toolkit font
NULL
DwtDirectionRightDown
DwtFontUnits

Dialog Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNfont
DwtNhelpCallback
DwtNdirectionRToL
DwtNunits

3-8 Subroutines

DwtAttachedDB (3Dwt)
DwtNstyle

unsigned char

DwtNfocusCallback
DwtNtextMergeTranslations
DwtNmarginWidth

DwtCallbackptr
XtTranslations
Dimension

DwtNmarginHeight

Dimension

DwtNdefaultPosition
DwtNchildOverlap
DwtNresize
DwtNgrabKeySyms

Boolean
Boolean
unsigned char
KeySym

DwtNgrabMergeTranslations

XtTranslations

For
DwtDialogBoxCreate,ilie
default is DwtWorkarea.
For
DwtDialogBoxPopupCreate,
the default is
DwtModeless.
NULL
NULL
For
DwtDialogBoxCreate, the
default is One pixel.
For
DwtDialogBoxPopupCreate,
the default is 3 pixels.
For
DwtDialogBoxCreate, the
default is One pixel.
For
DwtDialogBoxPopupCreate,
the default is 3 pixels.
False
True
DwtResizeGrowOnly
The default array contains the
Tab key symbol.
The default syntax is:
"-Shift<KeyPress>Oxff09:
DWTDIMOVEFOCUSNEXTO\n\
Shift<KeyPress>Oxff09:
DWTDIMOVEFOCUSPREVO";

The following constraint attributes belong to any widget that is made a child
of an attached dialog box widget. You cannot set these attributes on the
attached dialog box itself; you must set them on the child widget. Several of
these constraint attributes take an enumerated data type. You should not
change attachment attributes in an attached dialog box with XtSetValues,
as this could result in an infinite loop.
typedef enum _DwtAttachmentType {
DwtAttachNone,
DwtAttachAdb,
DwtAttachWidget,
DwtAttachPosition,
DwtAttachSelf,
DwtAttachOppWidget,
DwtAtt a chOppAdb ,

Subroutines 3-9

DwtAttachedDB (3Dwt)
} DwtAttachmentType;

DwtNadbTopAttachment
Specifies how the top side of the child widget is
attached to its parent attached dialog box widget,
another child widget, a position, or itself.

The following describes the enumerated data type
values as they apply to this attribute:
Value

Meaning

DwtAttachNone

Do not attach this side. This type of attachment
may be overridden by the defaults of other
attachments that affect this side.

DwtAttachAdb

Attach the top side of the child widget to the top
side of its parent attached dialog box.

DwtAttachOppAdb

Attach the top side of the child widget to the
bottom side of its parent attached dialog box.

DwtAttachWidget

Attach the top side of the child widget to the
bottom side of another child widget within the
parent attached dialog box.

DwtAttachOppWidget

Attach the top side of the child widget to the top
side of another child widget.

DwtAttachPosition

Attach the top side of the child widget to a
relative position inside the parent attached dialog
box. Specify the relative position as a fraction
of the total width or height of the attached
dialog box.

DwtAttachSelf

Attach the top side of the child widget to a
relative position corresponding to the side's
initial position in the attached dialog box.

DwtNadbBottomAttachment
Specifies how the bottom side of the widget is
attached to the side of its parent attached dialog box
widget, another child widget, a position, or itself.

The following describes the enumerated data type
values as they apply to this attribute:

3-10 Subroutines

DwtAttachedDB (3Dwt)
Value

Meaning

DwtAttachNone

Do not attach this side. This type of attachment
overrides any default attachment that might
affect the side.

DwtAttachAdb

Attach this side to the bottom side of its parent
attached dialog box.

DwtAttachOppAdb

Attach this side to the top side of the parent
attached dialog box.

DwtAttachWidget

Attach this side to the top side of another child
widget within the parent attached dialog box.

DwtAttachOppWidget

Attach this side to the bottom side of another
child widget.

DwtAttachPosition

Attach this side to a relative position inside the
parent attached dialog box. Specify the relative
position as a fraction of the total width or height
of the attached dialog box.

DwtAttachSelf

Attach this to a relative position corresponding
to the side's initial position inside the parent
attached dialog box.

DwtNadbLeftAttachment
Specifies how the left side of the widget is attached
to the side of its parent attached dialog box widget,
another child widget, a position, or itself.

The following describes the enumerated data type
values as they apply to this attribute:
Value

Meaning

DwtAttachNone

Do not attach this side. This type of attachment
overrides any default attachment that might
affect the side.

DwtAttachAdb

Attach this side to the left side of its parent
attached dialog box.

DwtAttachOppAdb

Attach this side to the right side of the parent
attached dialog box.

Subroutines 3-11

DwtAttachedDB (3Dwt)
DwtAttachWidget

Attach this side to the right side of another child
widget within the parent attached dialog box.

DwtAttachOppWidget

Attach this side to the left side of another child
widget.

DwtAttachPosition

Attach this side to a relative position inside the
parent attached dialog box. Specify the relative
position as a fraction of the total width or height
of the attached dialog box.

DwtAttachSelf

Attach this side to a relative position
corresponding to the side's initial position in the
parent attached dialog box.

DwtNadbRightAttachment
Specifies how the right side of the widget is attached
to the side of its parent attached dialog box, another
child widget, a position, or itself.

The following describes the enumerated data type
values as they apply to this attribute:
Value

Meaning

DwtAttachNone

Do not attach this side. This type of attachment
overrides any default attachment that might
affect the side.

DwtAttachAdb

Attach this side to the right side of its parent
attached dialog box.

DwtAttachOppAdb

Attach this side to the left side of the parent
attached dialog box.

DwtAttachWidget

Attach this side to the left side of another child
widget within the parent attached dialog box.

DwtAttachOppWidget

Attach this side to the right side of another child
widget.

DwtAttachPosition

Attach this side to a relative position inside the
parent attached dialog box. Specify the relative
position as a fraction of the total width or height
of the attached dialog box.

3-12 Subroutines

DwtAttachedDB (3Dwt)
DwtAttachSelf

Attach this side to a relative position
corresponding to the side's initial position in the
parent attached dialog box.

DwtNadbTopWidget
Specifies the child widget that the top side is
attached to if DwtNadbTopAttachrnent is
DwtAttachWidget or DwtAttachOppWidget.
Otherwise, this attribute is ignored.
DwtNadbBottomWidget
Specifies the widget that the bottom side is attached
to if DwtNadbBottomAttachment is
DwtAttachWidget or DwtAttachOppWidget.
Otherwise, this attribute is ignored.
DwtNadbLeftWidget
Specifies the widget that the left side is attached to if
DwtNadbLeftAttachmentis
DwtAttachWidget or DwtAttachOppWidget.
Otherwise, this attribute is ignored.
DwtNadbRightWidget
Specifies the widget that the right side is attached to
if DwtNadbRightAttachment is
DwtAttachWidget or DwtAttachOppWidget.
Otherwise, this attribute is ignored.
DwtNtopPos i tion Specifies the numerator used with
DwtNfractionBase to determine the relative
positioning of the top side if
DwtNadbTopAttachmentis
DwtAttachPosi tion. Otherwise, this attribute is
ignored.
DwtNadbBottomPosition
Specifies the numerator used with
DwtNfractionBase to determine the relative
positioning of the bottom side if
DwtNadbBottomAttachmentis
DwtAttachPosi tion. Otherwise, this attribute is
ignored.
DwtNadbLeftPosition
Specifies the numerator used with
DwtNfractionBase to determine the relative

Subroutines 3-13

DwtAttachedDB (3Dwt)
positioning of the left side if
DwtNadbLeftAttachmentis
DwtAttachPosition. Otherwise, this attribute is
ignored.
DwtNadbRightPosition
Specifies the numerator used with the
DwtNfractionBase to determine the relative
positioning of the right side if
DwtNadbRightAttachmentis
DwtAttachPosition. Otherwise, this attribute is
ignored.
DwtNadbTopOffset
Specifies the offset of the top side from the position,
widget, or attached dialog box.
DwtNadbBottomOffset
Specifies the offset of the bottom side from the
position, widget, or attached dialog box.
DwtNadbLeftOffset
Specifies the offset of the left side from the position,
widget, or attached dialog box.
DwtNadbRightOffset
Specifies the offset of the right side from the
position, widget, or attached dialog box.
DwtNresizable

Specifies a boolean value that, when True,
indicates that the attached dialog box can change the
size of the child widget. If Fa 1 s e, indicates that
the attached dialog box cannot change the size of the
child widget.

Widget-Specific Attributes
Attribute Name

Data Type

Default

DwtNdefaultHorizontalOffset
DwtNdefaultVerticalOffset
DwtNrubberPositioning
DwtNfractionBase

int
int

Zero
Zero

Boolean

False

int

100

3-14 Subroutines

DwtAttachedDB (3Dwt)
DwtNdefaultHorizontalOffset
Specifies the default horizontal offset for right and
left attachments. The offset determines the amount
of space between the left or right side of a child
widget and the side or position to which it is
attached.
DwtNdefaultVerticalOffset
Specifies the default vertical offset for the top and
bottom attachments. The offset determines the
amount of space between the top or bottom side of a
child widget and the side or position to which it is
attached.
DwtNrubberPositioning
Specifies a boolean value that, when False,
indicates that the child widget left and top sides
default to being attached to the left and top of the
attached dialog box. If True, the child widget sides
default to being attached to the left and top of the
attached dialog box.
DwtNfractionBase

Specifies the denominator used in specifying
fractional positioning.

Return Value
These functions return the ID of the created widget.

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
} DwtAnyCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRMap

The attached dialog box is about to be
mapped.

DwtCRHelpRequested

The user selected Help.

Subroutines 3-15

DwtAttachedDB (3Dwt)
The event member is a pointer to the Xlib structure XEvent, which
describes the event that generated this callback. This structure is a union of
the individual structures declared for each event type. For information on
XEvent and event processing, see the Guide to the Xlib Library: C
Language Binding.

See Also
Guide to the XUI Toolkit: C Language Binding
Guide to the XUI Toolkit Intrinsics: C Language Binding

3-16 Subroutines

DwtBeginCopyToClipboard (3Dwt)
Name
DwtBeginCopyToClipboard - Sets up storage and data structures to receive
clipboard data.

Syntax
int DwtBeginCopyToClipboard(display, window, clip_label,
widget, callback, item id)
Display *display;
Window window;
DwtCompString clip label;
Widget widget;
VoidProc callback;
long * item_id;

Arguments
display

Specifies a pointer to the Display structure that was
returned in a previous call to XOpenDisplay. For
information on XOpenDisplay and the Display
structure, see the Guide to the Xlib Library: C Language
Binding.

window

Specifies the window ID that relates the application window
to the clipboard. The same application instance should pass
the same window ID to each clipboard function that it calls.
Specifies the label to be associated with the data item. This
argument is used to identify the data item, for example, in a
clipboard viewer. An example of a label is the name of the
application that places the data in the clipboard.

widget

Specifies the ID of the widget that will receive messages
requesting data previously passed by name. This argument
must be present in order to pass data by name. Any valid
widget ID in your application can be used. All message
handling is done by the cut and paste functions.

callback

Specifies the address of the callback function that is called
when the clipboard needs data that was originally passed by
name. This is also the callback to receive the DELETE
message for items that were originally passed by name. This
argument must be present in order to pass data by name.

Subroutines 3-17

DwtBeginCopyToClipboard (3Dwt)
item id

Specifies the number assigned to this data item. The
application uses this number in calls to
DwtCopyToClipboar~ DwtEndCopyToClipboar~

and DwtCancelCopyToClipboard.

Description
The DwtBeginCopyToClipboard function sets up storage and data
structures to receive clipboard data. An application calls
DwtBeginCopyToClipboard during a cut or copy operation. The data
item that these structures receive then becomes the next-paste item in the
clipboard.
The widget and callback arguments must be present in order to pass data by
name. The callback format is as follows:
function name ( widget, data id, private id, reason)
Widget *widget;
int *data id;
int *private id;
int *reason;
widget

Specifies the ID of the widget passed to
DwtBeginCopyToClipboard.

data id

Specifies the identifying number returned by
DwtCopyToClipboard, which identifes the pass-by-name
data.

private_id

Specifies the private information passed to
DwtCopyToClipboard.

reason

Specifies the reason, which is either
DwtCRClipboardDataDelete or
DwtCRClipboardDataRequest.

Return Value
This function returns one of these status return constants:
ClipboardSuccess
The function is successful.

3-18 Subroutines

DwtBeginCopyToClipboard (3Dwt)
ClipboardLocked

The function failed because the clipboard
was locked by another application. The
application can continue to call the function
with the same parameters until the
clipboard is unlocked. Optionally, the
application can ask if the user wants to
keep trying or to give up on the operation.

See Also
DwtCopyToClipboard (3Dwt), DwtEndCopyToClipboard (3Dwt),
DwtCancelCopyToClipboard (3Dwt), DwtStartCopyToClipboard (3Dwt)
Guide to the XUI Toolkit: C Language Binding
Guide to the XUI Toolkit Intrinsics: C Language Binding

Subroutines 3-19

DwtCancelCopyFormat (3Dwt)
Name
DwtCancelCopyFormat - Indicates that the application will no longer supply
a data item to the clipboard that the application had previously passed by
name.

Syntax
int DwtCancelCopyFormat(display, window, data id)
Display *display;
Window window;
int data_id;

Arguments
display

window

Specifies the window ID that relates the application window
to the clipboard. The same application instance should pass
the same window ID to each clipboard function that it calls.

data id

Specifies an identifying number assigned to the data item that
uniquely identifies the data item and the format. This was
assigned to the item when it was originally passed by
DwtCopyToClipboard

Description
The DwtCancelCopyFormat function indicates that the application will
no longer supply a data item to the clipboard that the application had
previously passed by name.

Return Value
This function returns one of these status return constants:
ClipboardSuccess

3-20 Subroutines

The function is successful.

OwtCancelCopyFormat (30wt)
ClipboardLocked

See Also
Guide to the XUI Toolkit: C Language Binding
Guide to the XUI Toolkit Intrinsics: C Language Binding

Subroutines 3-21

DwtCancelCopyToClipboard (3Dwt)
Name
DwtCancelCopyToClipboard - Cancels the copy to clipboard that is in
progress.

Syntax
void DwtCancelCopyToClipboard (display, window, item_id)
Display *display;
Window window;
long item_id;

Arguments
display

window

Specifies the window ID that relates the application window
to the clipboard. The same application instance should pass
the same window ID to each clipboard function that it calls.

item id

Specifies the number assigned to this data item. This number
was returned by a previous call to
DwtBeginCopyToClipboard.

Description
The DwtCancelCopyToClipboard function cancels the copy to
clipboard that is in progress. DwtCancelCopyToClipboard also frees
up temporary storage. If DwtCancelCopyToClipboard is called, then
DwtEndCopyToClipboard does not have to be called. A call to
DwtCancelCopyToClipboard is valid only after a call to
DwtBeginCopyToClipboard and before a call to
DwtEndCopyToClipboard.

See Also
DwtBeginCopyToClipboard (3Dwt), DwtEndCopyToClipboard (3Dwt)
Guide to the XUI Toolkit: C Language Binding
Guide to the XUI Toolkit Intrinsics: C Language Binding

3-22 Subroutines

OwtCautionBox (30wt)
Name
DwtCautionBox, DwtCautionBoxCreate - Creates a caution box widget for
the application to display caution messages.

Syntax
Widget DwtCautionBox(parent_widget, name, dejaultyosition,
x, y, style, label,
yeslabel, nolabel, cancel_label,
defaultyush _button, callback,
help_callback)
Widget parent widget;
char *name; Boolean defaultyosition;
Position x, y;
int style;
DwtCompString label;
DwtCompString yeslabel;
DwtCompString nolabel;
DwtCompString cancel_label;
int defaultyush_button;
DwtCallbackPtr callback, help_callback;
Widget DwtCautionBoxCreate (parent widget, name,
override argUst,override- argcount)
Widget parent_widget; char *name;
ArgList override argUst;
int override_argcount;

Arguments
parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

defaultyosition
Specifies a boolean value that, when True, causes DwtNx
and DwtNy to be ignored and forces the default widget
position. The default widget position is centered in the
parent window. If False, the specified DwtNx and
DwtNy attributes are used to position the widget. This

Subroutines 3-23

DwtCautionBox (3Dwt)
argument sets the DwtNdefaultPosition attribute
associated with DwtDialogBoxCreate.

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window. This argument sets the DwtNy core
widget attribute.

style

Specifies the style of the caution box widget. You can pass
DwtModal (modal) or DwtModeless (modeless). This
argument sets the DwtNstyle attribute associated with
DwtDialogBoxPopupCreate.

label

Specifies the text in the message line or lines. This argument
sets the DwtNlabel attribute associated with
DwtCautionBoxCreate.

yeslabel

Specifies the label for the Yes push button. If the label is a
zero length string, the button is not displayed. This
argument sets the DwtNyesLabel attribute associated with
DwtCautionBoxCreate.

nolabel

Specifies the label for the No push button. If the label is a
zero length string, the button is not displayed. This
argument sets the DwtNnoLabel attribute associated with
DwtCautionBoxCreate.

cancel label

Specifies the label for the Cancel push button. If the label is
a NULL string, the button is not displayed. This argument
sets the DwtNcancelLabel attribute associated with
DwtCautionBoxCreate.

defaultyush _button
Specifies the push button that represents the default user
action. You can pass DwtYesButton, DwtNoButton,
or DwtCancelButton. This argument sets the
DwtNdefaul tPushbutton attribute associated with
DwtCautionBoxCreate.
callback

3-24 Subroutines

Specifies the callback function or functions called when the
user activates the Yes, No, or Cancel buttons. This argument
sets the DwtNyesCallback, DwtNnoCallback, and

DwtCautionBox (3Dwt)
DwtNcancelCallback attributes associated with
DwtCautionBoxCreate.

help_callback Specifies the callback function or functions called when a
help request is made. This argument sets the
DwtNhelpCallback common widget attribute.
parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_arglist

Specifies the application override argument list.
override argcount
Specifies the number of attributes in the application override
argument list (override _arglist).

Description
The DwtCautionBox and DwtCautionBoxCreate functions create a
caution box widget and return its associated widget ID. When calling
DwtCautionBox, you set the caution box widget attributes presented in the
formal parameter list. For DwtCautionBoxCreate, however, you
specify a list of attribute name/value pairs that represent all the possible
caution box widget attributes.
A caution box warns the user of the application of the consequences of
carrying out an action. It stops application activity and requires the user to
provide instructions on how to proceed. Your application should generate a
caution box when an action by the user could destroy data or cause a simialr
irrevocable event. The caution box usually contains Yes, No, and Cancel
push buttons. When possible, caution messages should be written as
inquiries. In all cases, the default push button should be the least destructive
operation. If DwtNstyle is DwtModal when the user activates any push
button, the widget is cleared from the screen, but not destroyed. You can
redisplay the widget by calling XtManageChild.

Inherited Attributes
Attribute Name

Data Type

Default

Position

Determined by the geometry
manager

Core Attributes
DwtNx

Subroutines 3-25

DwtCautionBox (3Dwt)
DwtNy

position

DwtNwidth
DwtNheight
DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Dimension
Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

Determined by the geometry
manager
5 pixels
5 pixels
One pixel
Default foreground color
NULL
Default background color
NULL
Default color map
True
The bitwise AND of the
parent widget's
DwtNsensitive and
DwtNancestorSensitive
attributes
NULL
Depth of the parent window
NULL
True
The parent screen
NULL

Dialog Pop-Up Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNfont
DwtNhelpCallback
DwtNdirectionRToL
DwtNunits
DwtNtitle
DwtNstyle
DwtNmapCallback
DwtNunmapCallback
DwtNfocusCallback
DwtNtextMergeTranslations
DwtNmarginWidth
DwtNmarginHeight
DwtNdefaultPosition

3-26 Subroutines

Pixel
Pixel
Pixmap
Opaque *
DwtFontList
DwtCallbackptr
NOT SUPPORTED
NOT SUPPORTED
DwtCompString
unsigned char
DwtCallbackPtr
DwtCallbackPtr
DwtCallbackPtr
NOT SUPPORTED
Dimension
Dimension
Boolean

Default foreground color
Default foreground color
NULL
NULL
The default XUI Toolkit font
NULL

Widget name
DwtModal
NULL
NULL
NULL
12 pixels
10 pixels
False

DwtCautionBox (3Dwt)
DwtNchildOverlap
DwtNresize
DwtNtakeFocus

unsigned char
Boolean

DwtNnoResize

Boolean

DwtNautoUnmanage
DwtNdefaultButton
DwtNcancelButton

NOT SUPPORTED
NOT SUPPORTED

NOT SUPPORTED

DwtResizeShrinkWrap
Truefor modal dialog box
Fa 1 s e for modeless dialog
box
True (that is, no window
manager resize button)
True

Boolean

Widget-Specific Attributes
Attribute Name

Data Type

Default

DwtNlabel
DwtNyesLabel
DwtNnoLabel
DwtNcancelLabel
DwtNdefaultPushbutton
DwtNyesCallback
DwtNnoCallback
DwtNcancelCallback

DwtCompString
DwtCompString
DwtCompString
DwtCompString
unsigned char
DwtCallbackPtr
DwtCallbackPtr
DwtCallbackPtr

Widget name
"Yes"
"No"

"Cancel"
DwtYesButton
NULL
NULL
NULL

DwtNlabel

Specifies the text in the message line or lines.

DwtNyesLabel

Specifies the label for the Yes push button. If the
label is a zero length string, the button is not
displayed.

DwtNnoLabel

Specifies the label for the No push button. If the
label is a zero length string, the button is not
displayed.

DwtNcancelLabel

Specifies the label for the Cancel push button. If the
label is a NULL string, the button is not displayed.

DwtNdefaultPushbutton

Specifies the push button that represents the default
user action. You can pass DwtYesButton,
DwtNoButton, or DwtCancelButton.
DwtNyesCallback

Specifies the callback function or functions called
when the user clicks on the Yes button. For this
callback, the reason is Dwt CR Yes.

Subroutines 3-27

DwtCautionBox (3Dwt)
DwtNnoCallback

Specifies the callback function or functions called
when the user clicks on the No button. For this
callback, the reason is DwtCRNo.

DwtNcancelCallback

Specifies the callback function or functions called
when the user clicks on the Cancel button. For this
callback, the reason is DwtCRCancel.

Return Value
These functions return the ID of the created widget.

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *eventi
} DwtAnyCallbackStructi

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRYes

The user activated the Yes button.

DwtCRNo

The user activated the No button.

DwtCRCancel

The user activated the Cancel button.

DwtCRFocus

The caution box has received the input
focus.

DwtCRHelpRequested

The user selected Help somewhere in the
caution box.

3-28 Subroutines

DwtCautionBox (3Dwt)
See Also
Guide to the XUI Toolkit: C Language Binding
Guide to the XUI Toolkit Intrinsics: C Language Binding

Subroutines 3-29

DwtClipboardLock (3Dwt)
Name
DwtClipboardLock - Locks the clipboard from access by other applications.

Syntax
int DwtClipboardLock( display, window)
Display *display;
Window window;

Arguments
display

window

Specifies the window ID that relates the application window
to the clipboard. The same application instance should pass
the same window ID to each clipboard function that it calls.

Description
The DwtClipboardLock function locks the clipboard from access by
another application until you call DwtClipboardUnlock. All clipboard
functions lock and unlock the clipboard to prevent simultaneous access. The
DwtClipboardLock and DwtClipboardUnlock functions allow the
application to keep the clipboard data from changing between calls to the
inquire functions and other clipboard functions. The application does not
need to lock the clipboard between calls to
DwtBeginCopyToClipboardood DwtEndCopyToClipboard.
If the clipboard is already locked by another application,
DwtClipboardLock returns an error status.

Multiple calls to DwtClipboardLock by the same application increase
the lock level.

Return Value
This function returns one of these status return constants:
ClipboardSuccess

3-30 Subroutines

The function is successful.

OwtClipboardLock (30wt)
ClipboardLocked

See Also
DwtClipboardUnlock (3Dwt)
Guide to the XUI Toolkit: C Language Binding
Guide to the XUI Toolkit Intrinsics: C Language Binding

Subroutines 3-31

DwtClipboardRegisterFormat (3Dwt)
Name
DwtClipboardRegisterFormat - Registers the length of the data for formats
not specified by ICCCM conventions.

Syntax
int DwtClipboardRegisterFormat (display, format name,
format_length)
Display *display;
char * format name;
unsigned long format_length;

Arguments
display

format_name

Specifies a name string for the format. See the table of Data
Format Names for the formats defined by ICCCM
conventions.

format_length

Specifies the format length in bits: 8, 16, or 32.

Description
The DwtClipboardRegisterFormat function allows an application to
register the data length for formats not specified by the ICCCM conventions.
Failure to register the length of the data results in applications being
incompatible across platforms that have different byte-swapping orders.
The following table lists the formats defined by the conventions:
Format Name

Format Length

Description

TARGETS
MULTIPLE
TIMESTAMP

32
32
32

STRING
TEXT

8
8

List of valid target atoms
Look in the ConvertSelection property
Timestamping used to acquire
selection
ISO Latin 1 (+T AB+NEWLINE) text
Text in owner's encoding

3-32 Subroutines

OwtClipboardRegisterFormat (30wt)
LIST_LENGTH
PIXMAP
DRAWABLE
BITMAP
FOREGROUND
BACKGROUND
COLORMAP
ODIF

32
32
32
32
32
32
32
8

OWNER_OS
FILE_NAME
HOST_NAME
CHARACTER_POSITION
LINE_NUMBER
COLUMN_NUMBER
LENGTH
USER
PROCEDURE
MODULE
PROCESS
TASK
CLASS
NAME
CLIENT_WINDOW

8
8
8
32
32
32
32
8
8
8
32 or 8
32 or 8
8
8
32

Number of disjoint parts of selection
Pixmap ID
Drawable ID
Bitmap ID
Pixel value
Pixel value
Colormap ID
ISO Office Document Interchange
Format
Operating system of owner
Full path name of a file
See WM_CLIENT_MACHINE
Start and end of selection in bytes
Start and end line numbers
Number of bytes in selection
Name of user running owner
Name of selected procedure
Name of selected module
Process ID of owner
Task ID of owner
Class of owner-See WM_CLASS
Name of owner-See WM_NAME
Top-level window of owner

For infonnation on the built-in selection property names
WM_CLIENT_MACHINE, WM_CLASS, and WM_NAME, see the Guide
to the Xlib Library: C Language Binding.

Return Value
This function returns one of these status return constants:
ClipboardSuccess
ClipboardLocked

Subroutines 3-33

DwtClipboardRegisterFormat (3Dwt)
ClipboardBadFormat

ClipboardFail

The function failed because the
format name or format length was
inappropriate. A NULL format_name or a
format length other than 8, 16, or 32, for
example, would be inappropriate.
The function failed because the application
tried to redefine a predefined format. See
the table of Data Format Names for the
predefined formats.

See Also
Guide to the XUI Toolkit: C Language Binding
Guide to the XUI Toolkit Intrinsics: C Language Binding

3-34 Subroutines

DwtClipboardUnlock (3Dwt)
Name
DwtClipboardUnlock - Unlocks the clipboard, enabling other applications to
access it.

Syntax
int DwtClipboardUnlock(display, window, remove all locks)
Display *display;
- Window window;
Boolean remove_all_locks;

Arguments
display

Binding.
window

Specifies the window ID that relates the application window
to the clipboard. The same application instance should pass
the same window ID to each clipboard function that it calls.

remove all locks
Specifies a boolean value that, when True, indicates that all
nested locks should be removed. If False, indicates that
only one level of lock should be removed.

Description
The DwtClipboardUnlock function unlocks the clipboard, enabling it to
be accessed by other applications.
If mUltiple calls to DwtClipboardLock have occurred, then the same
number of calls to DwtClipboardUnlock is necessary to unlock the
clipboard, unless the remove_all_locks argument is True.

Return Value
This function returns one of these status return constants:
ClipboardSuccess

The function is successful.

Subroutines 3-35

DwtClipboardUnlock (3Dwt)
ClipboardLocked

See Also
DwtClipboardLock (3Dwt)
Guide to the XUI Toolkit: C Language Binding
Guide to the XUI Toolkit Intrinsics: C Language Binding

3-36 Subroutines

DwtCloseHierarchy (3Dwt)
Name
DwtCloseHierarchy - Closes a UID hierarchy.

Syntax
#inc1ude <Xll/DwtAppl.h>
Cardinal DwtCloseHierarchy (hierarchy_id)
DRMHierarchy hierarchy_id;

Arguments
hierarchy_id

Specifies the ID of a previously opened UID hierarchy. The
hierarchy_id was returned in a previous call to
DwtOpenHierarchy.

Description
The DwtCloseHierarchy function closes a UID hierarchy previously
opened by DwtOpenHierarchy. All files associated with the hierarchy
are closed by DRM and all associated memory is returned.

Return Value
This function returns one of these status return constants:
DRMSuccess
DRMFailure

The function executed successfully.
The function failed.

See Also
Guide to the Xlib Library

3-372 Subroutines

XAliocColor (3X11 )
Name
XAllocColor, XAllocNamedColor, XAllocColorCells, XAllocColorPlanes,
XFreeColors - allocate and free colors

Syntax
Status XAllocColor(display, colormap, screen_in_out)
Display *display;
Colormap colormap;
XColor *screen_in_out;
Status XAllocNamedColor(display, colormap, color_name,
screen def return, exact def return)
DiSplay *display; - Colormap colormap;
char *color name;
XColor *screen_def_return, *exact_def_return;
Status XAllocColorCells (display, colormap, contig, plane_masks_return,
nplanes, pixels_return, npixels)
Display *display;
Colormap colormap;
Bool contig;
unsigned long plane_masks_return[] ;
unsigned int nplanes;
unsigned long pixels return[];
unsigned int npixels;
Status XAllocColorPlanes (display, colormap, contig, pixels_return, ncolors,
nreds, ngreens, nblues, rmask return, gmask return, bmask return)
Display *display;
Colormap colormap;
Bool contig;
unsigned long pixels_return[] ;
int ncolors;
int nreds, ngreens, nblues;
unsigned long *rmask_return, *gmask_return, *bmask_return;

XFreeColors(display, colormap, pixels, npixels, planes)
Display *display;
Colormap colormap;
unsigned long pixels [];
int npixels;
unsigned long planes;
Subroutines 3-373

XAliocColor{3X11 )
Arguments
color name

Specifies the color name string (for example, red) whose
color definition structure you want returned.

colormap

Specifies the colormap.

contig

Specifies a Boolean value that indicates whether the planes
must be contiguous.

display

Specifies the connection to the X server.

exact_del_return
Returns the exact RGB values.
ncolors

Specifies the number of pixel values that are to be returned in
the pixels_return array.

npixels

Specifies the number of pixels.

nplanes

Specifies the number of plane masks that are to be returned
in the plane masks array.

nreds
ngreens
nblues
Specify the number of red, green, and blue planes. The value
you pass must be nonnegative.

pixels

Specifies an array of pixel values.

pixels return

Returns an array of pixel values.

plane mask return
- Returns an array of plane masks.
planes

Specifies the planes you want to free.

rmask return
gmask-return
bmask-return Return bit masks for the red, green, and blue planes.
screen de! return
- Returns the closest RGB values provided by the hardware.
screen in out Specifies and returns the values actually used in the
colormap.

3-374 Subroutines

XAliocColor (3X11 )
Description
The XAllocColor function allocates a read-only colormap entry
corresponding to the closest RGB values supported by the hardware.
XAllocColor returns the pixel value of the color closest to the specified
RGB elements supported by the hardware and returns the RGB values
actually used. The corresponding colormap cell is read-only. In addition,
XAllocColor returns nonzero if it succeeded or zero if it failed. Readonly colormap cells are shared among clients. When the last client
deallocates a shared cell, it is deallocated. XAllocColor does not use or
affect the flags in the XColor structure.
XAllocColor can generate a BadColor error.

The XAllocNamedColor function looks up the named color with respect
to the screen that is associated with the specified colormap. It returns both
the exact database definition and the closest color supported by the screen.
The allocated color cell is read-only. You should use the ISO Latin-l
encoding; uppercase and lowercase do not matter.
XAllocNamedColor can generate a BadColor error.

The XAllocColorCells function allocates read/write color cells. The
number of colors must be positive and the number of planes nonnegative, or
a BadVal ue error results. If ncolors and nplanes are requested, then ncolors
pixels and nplane plane masks are returned. No mask will have any bits set
to 1 in common with any other mask or with any of the pixels. By ORing
together each pixel with zero or more masks, ncolors * 2nplanes distinct pixels
can be produced. All of these are allocated writable by the request. For
GrayScale or PseudoColor, each mask has exactly one bit set to 1. For
DirectColor, each has exactly three bits set to 1. If contig is True and
if all masks are ORed together, a single contiguous set of bits set to 1 will be
formed for GrayScale or PseudoColor and three contiguous sets of bits
set to 1 (one within each pixel subfield) for DirectColor. The RGB
values of the allocated entries are undefined. XAllocColorCells returns
nonzero if it succeeded or zero if it failed.
XAllocColorCells can generate BadColor and BadValue errors.

The specified ncolors must be positive; and nreds, ngreens, and nblues must
be nonnegative, or a BadVal ue error results. If ncolors colors, nreds reds,
ngreens greens, and nblues blues are requested, ncolors pixels are returned;
and the masks have nreds, ngreens, and nblues bits set to 1, respectively. If
contig is True, each mask will have a contiguous set of bits set to 1. No
mask will have any bits set to 1 in common with any other mask or with any
of the pixels. For DirectColor, each mask will lie within the

Subroutines 3-375

XAliocColor (3X11 )
corresponding pixel subfield.
By ~Ring together subsets of masks with each pixel value, ncolors *
2(nreds+ngreens+nblues) distinct pixel values can be produced. All of these are
allocated by the request. However, in the colormap, there are only ncolors *
2 nreds independent red entries, ncolors * 2ngreens independent green entries,
and ncolors * 2nblues independent blue entries. This is true even for
PseudoColor. When the colormap entry of a pixel value is changed
(using XStoreColors, XStoreColor, or XStoreNamedColor), the
pixel is decomposed according to the masks, and the corresponding
independent entries are updated. XAllocColorPlanes returns nonzero if
it succeeded or zero if it failed.
XAllocColorPlanes can generate BadColor and BadValue errors.

The XFreeColors function frees the cells represented by pixel,s whose
values are in the pixels array. The planes argument should not have any bits
set to 1 in common with any of the pixels. The set of all pixels is produced
by ~Ring together subsets of the planes argument with the pixels. The
request frees all of these pixels that were allocated by the client (using
XAllocColor,XAllocNamedColor, XAllocColorCells, and
XAllocColorPlanes). Note that freeing an individual pixel obtained
from XAllocColorPlanes may not actually allow it to be reused until all
of its related pixels are also freed.
All specified pixels that are allocated by the client in the colormap are freed,
even if one or more pixels produce an error. If a specified pixel is not a valid
index into the colormap, a BadValue error results. If a specified pixel is
not allocated by the client (that is, is unallocated or is only allocated by
another client), a BadAccess error results. If more than one pixel is in
error, the one that gets reported is arbitrary.
XFreeColors can generate BadAccess, BadColor, and BadValue
errors.

Diagnostics
BadAccess

A client attempted to free a color map entry that it did not
already allocate.

BadAccess

A client attempted to store into a read-only color map entry.

BadColor

A value for a Colormap argument does not name a defined
Colormap.

BadVal ue

Some numeric value falls outside the range of values
accepted by the request. Unless a specific range is specified

3-376 Subroutines

XAliocColor (3X11 )
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.

See Also
XCreateColormap(3Xll), XQueryColor(3Xll), XStoreColors(3Xll)
Guide to the Xlib Library

Subroutines 3-377

XAliowEvents (3X11 )
Name
XAllowEvents - release queued events

Syntax
XAllowEvents (display, event_mode, time)
Display *display;
int event mode;
Time time;

Arguments
display

Specifies the connection to the X server.

event mode

Specifies the event mode. You can pass AsyncPointer,
SyncPointer,AsyncKeyboard,SyncKeyboard,
ReplayPointer,ReplayKeyboard,AsyncBoth,or
SyncBoth.

time

Specifies the time. You can pass either a timestamp or
Current Time.

Description
The XAllowEvents function releases some queued events if the client has
caused a device to freeze. It has no effect if the specified time is earlier than
the last-grab time of the most recent active grab for the client or if the
specified time is later than the current X server time.
XAllowEvents can generate a BadValue error.

Diagnostics
BadValue

See Also
Guide to the Xlib Library

3-378 Subroutines

XChangeKeyboardControl (3X11 )
Name
XChangeKeyboardControl, XGetKeyboardControl, XAutoRepeatOn,
XAutoRepeatOff, XBell, XQueryKeymap - manipulate keyboard settings

Syntax
XChangeKeyboardControl( display, value mask, values)
Display *display;
unsigned long value_mask;
XKeyboardControl *values;
XGetKeyboardControl( display, values_return)
Display *display;
XKeyboardState *values_return;
XAutoRepeatOn( display)
Display *display;
XAutoRepeatOff( display)
Display *display;
XBell(display, percent)
Display *display;
int percent;
XQueryKeymap( display, keys_return)
Display *display;
char keys_return[32] ;

Arguments
display

Specifies the connection to the X server.

keys_return

Returns an array of bytes that identifies which keys are
pressed down. Each bit represents one key of the keyboard.

percent

Specifies the volume for the bell, which can range from -100
to 100 inclusive.

value mask

Specifies one value for each bit set to 1 in the mask.

values

Specifies which controls to change. This mask is the bitwise
inclusive OR of the valid control mask bits.

values return

Returns the current keyboard controls in the specified
XKeyboardState structure.

Subroutines 3-379

XChangeKeyboardControl (3X11 )
Description
The XChangeKeyboardControl function controls the keyboard
characteristics defined by the XKeyboardControl structure. The
value_mask argument specifies which values are to be changed.
XChangeKeyboardControl can generate BadMatch and BadValue
errors.

The XGetKeyboardControl function returns the current control values
for the keyboard to the XKeyboardState structure.
The XAutoRepeatOn function turns on auto-repeat for the keyboard on the
specified display.
The XAutoRepeatOff function turns off auto-repeat for the keyboard on
the specified display.
The XBell function rings the bell on the keyboard on the specified display,
if possible. The specified volume is relative to the base volume for the
keyboard. If the value for the percent argument is not in the range -100 to
100 inclusive, a BadValue error results. The volume at which the bell
rings when the percent argument is nonnegative is:
base - [(base * percent) / 100] + percent
The volume at which the bell rings when the percent argument is negative is:
base + [(base * percent) / 100]
To change the base volume of the bell, use XChangeKeyboardControl.
XBell can generate a BadValue error.

The XQueryKeymap function returns a bit vector for the logical state of the
keyboard, where each bit set to 1 indicates that the corresponding key is
currently pressed down. The vector is represented as 32 bytes. Byte N (from
0) contains the bits for keys 8N to 8N + 7 with the least-significant bit in the
byte representing key 8N.
Note that the logical state of a device (as seen by client applications) may lag
the physical state if device event processing is frozen.

Diagnostics
BadMatch

Some argument or pair of arguments has the correct type and
range but fails to match in some other way required by the
request.

BadValue

Some numeric value falls outside the range of values
accepted by the request. Unless a specific range is specified

3-380 Subroutines

XChangeKeyboardControl (3X11 )
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.

See Also
XChangeKeyboardMapping(3Xll), XSetPointerMapping(3Xll)
Guide to the Xlib Library

Subroutines 3-381

XChangeKeyboardMapping (3X11 )
Name
XChangeKeyboardMapping, XGetKeyboardMapping, XDisplayKeycodes,
XSetModifierMapping, XGetModifierMapping, XNewModifiermap,
XInsertModifiermapEntry, XDeleteModifiermapEntry, XFreeModifierMap manipulate keyboard encoding

Syntax
XChangeKeyboardMapping(display, first_ keycode, keysymsyer_ keycode,
keysyms, num codes)
Display *display;
int first keycode;
int keysymsyer_ keycode;
KeySym *keysyms;
int num_codes;
KeySym *XGetKeyboardMapping(display, first_keycode, keycode_count,
keysymsyer_ keycode_return)
Display *display;
KeyCode first_ keycode;
int keycode count;
int *keysymsyer_ keycode_return;
XDisplayKeycodes( display, min_ keycodes_return, max_ keycodes_return)
Display * display;
int * min_ keycodes_return, max_ keycodes_return;
int XSetModifierMapping( display, modmap)
Display *display;
XModifierKeymap *modmap;
XModifierKeymap *XGetModifierMapping( display)
Display *display;
XModifierKeymap *XNewModifiermap(max_keysyer_mod)
int max_keysyer_mod;
XModifierKeymap *XInsertModifiermapEntry( modmap, keycode_entry,
modifier)
XModifierKeymap *modmap;
KeyCode keycode_entry;
int modifier;

3-382 Subroutines

XChangeKeyboardMapping (3X11 )
XModifierKeymap *XDeleteModifiermapEntry(modmap, keycode_entry,
modifier)
XModifierKeymap *modmap;
KeyCode keycode_entry;
int modifier;
XFreeModifiermap(modmap)
XModifierKeymap *modmap;

Arguments
display

Specifies the connection to the X server.

first_ keycode

Specifies the first KeyCode that is to be changed or returned.

keycode_count Specifies the number of KeyCodes that are to be returned.
keycode_entry Specifies the KeyCode.
keysyms

Specifies a pointer to an array of KeySyms.

keysymsyer_ keycode
Specifies the number of KeySyms per KeyCode.
keysymsyer_ keycode_return
Returns the number of KeySyms per KeyCode.
max_keysyer_mod
Specifies the number of KeyCode entries preallocated to the
modifiers in the map.
max keycodes return
- Returns the maximum number of KeyCodes.
min keycodes return
- Returns the minimum number of KeyCodes.
modifier

Specifies the modifier.

modmap

Specifies a pointer to the XModifierKeymap structure.

num codes

Specifies the number of KeyCodes that are to be changed.

Description
The XChangeKeyboardMapping function defines the symbols for the
specified number of KeyCodes starting with first_keycode. The symbols for
KeyCodes outside this range remain unchanged. The number of elements in
keysyms must be:

Subroutines 3-383

XChangeKeyboardMapping (3X11 )
num_codes * keysyms_per_keycode
The specified first_keycode must be greater than or equal to min_keycode
returned by XDisplayKeycodes, or a BadValue error results. In
addition, the following expression must be less than or equal to max_keycode
as returned by XDisplayKeycodes, or a BadValue error results:
first_keycode + num_codes - 1
KeySym number N, counting from zero, for KeyCode K has the following
index in keysyms, counting from zero:
(K - first_keycode) * keysyms_per_keycode + N
The specified keysyms_per_keycode can be chosen arbitrarily by the client to
be large enough to hold all desired symbols. A special KeySym value of
NoSymbol should be used to fill in unused elements for individual
KeyCodes. It is legal for NoSymbol to appear in nontrailing positions of the
effective list for a KeyCode. XChangeKeyboarciMapping generates a
MappingNotifyevent.
There is no requirement that the X server interpret this mapping. It is merely
stored for reading and writing by clients.
XChangeKeyboarciMapping can generate BadAlloc and BadVal ue
errors.
The XGetKeyboarciMapping function returns the symbols for the
specified number of KeyCodes starting with first_keycode. The value
specified in first_keycode must be greater than or equal to min_keycode as
returned by XDisplayKeycodes, or a BadValue error results. In
addition, the following expression must be less than or equal to max_keycode
as returned by XDisplayKeycodes:
first_keycode + keycode_count - 1
If this is not the case, a BadVal ue error results. The number of elements in

the KeySyms list is:
keycode_count * keysyms_per_keycode_return
KeySym number N, counting from zero, for KeyCode K has the following
index in the list, counting from zero:
(K - first_code) * keysyms_per_code_return + N
The X server arbitrarily chooses the keysyms_per_keycode_return value to be
large enough to report all requested symbols. A special KeySym value of
NoSymbol is used to fill in unused elements for individual KeyCodes. To
free the storage returned by XGetKeyboarciMapping, use XFree.

3-384 Subroutines

XChangeKeyboardMapping (3X11 )
XGetKeyboarciMapping can generate a BadVal ue error.

The XDisplayKeycodes function returns the min-keycodes and maxkeycodes supported by the specified display. The minimum number of
KeyCodes returned is never less than 8, and the maximum number of
KeyCodes returned is never greater than 255. Not all KeyCodes in this range
are required to have corresponding keys.
The XSetModi fie rMapping function specifies the KeyCodes of the keys
(if any) that are to be used as modifiers. If it succeeds, the X server
generates a MappingNotify event, and XSetModifierMapping
returns MappingSuccess. X permits at most eight modifier keys. If more
than eight are specified in the XModifierKeymap structure, a
BadLength error results.
The modifiermap member of the XModifierKeymap structure contains
eight sets of max_keypermod KeyCodes, one for each modifier in the order
Shift, Lock, Control, ModI, Mod2, Mod3, Mod4, and ModS. Only
nonzero KeyCodes have meaning in each set, and zero KeyCodes are
ignored. In addition, all of the nonzero KeyCodes must be in the range
specified by min_keycode and max_keycode in the Display structure, or a
BadValue error results. No KeyCode may appear twice in the entire map,
or a BadVal ue error results.
An X server can impose restrictions on how modifiers can be changed, for
example, if certain keys do not generate up transitions in hardware, if autorepeat cannot be disabled on certain keys, or if multiple modifier keys are not
supported. If some such restriction is violated, 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 logically down state,
XSetModifierMapping returns MappingBusy, and none of the
modifiers is changed.
XSetModifierMapping can generate BadAlloc and BadValue errors.

The XGetModifierMapping function returns a pointer to a newly created
XModifierKeymap structure that contains the keys being used as
modifiers. The structure should be freed after use by calling
XFreeModifiermap. If only zero values appear in the set for any
modifier, that modifier is disabled.
The XNewModifiermap function returns a pointer to
XModifierKeymap structure for later use.

Subroutines 3-385

XChangeKeyboardMapping (3X11 )
The XlnsertModifiermapEntry function adds the specified KeyCode
to the set that controls the specified modifier and returns the resulting
XModifierKeymap structure (expanded as needed).
The XDeleteModifiermapEntry function deletes the specified
KeyCode from the set that controls the specified modifier and returns a
pointer to the resulting XModifierKeymap structure.
The XFreeModifiermap function frees the specified
XModifierKeymap structure.

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadValue

See Also
XSetPointerMapping(3Xll)
Guide to the Xlib Library

3-386 Subroutines

XChangePointerControl (3X11 )
Name
XChangePointerControl, XGetPointerControl - control pointer

Syntax
XChangePointerControl( display, do_aeeel, do_threshold, aeeel_numerator,
aeeel denominator, threshold)
Display *display;
Bool do aeeel, do threshold;
int aeeer numerator, aeeel denominator;
int threshold;
XGetPointerControl(display, aeeel numerator return,
aeeel denominator return, threshold return) Display *display;
int *aeeel numerator return, *aeeel denominator return;
int *threshold_return;
-

Arguments
aeeel denominator
Specifies the denominator for the acceleration multiplier.
aeeel denominator return
Reiiims the denominator for the acceleration multiplier.
aeeel numerator
Specifies the numerator for the acceleration multiplier.
aeeel numerator return
Returns the numerator for the acceleration multiplier.
display

Specifies the connection to the X server.

do aeeel

Specifies a Boolean value that controls whether the values for
the accel_numerator or accel_denominator are used.

do threshold

Specifies a Boolean value that controls whether the value for
the threshold is used.

threshold

Specifies the acceleration threshold.

threshold return
Returns the acceleration threshold.

Subroutines 3-387

XChangePointerControl (3X11 )
Description
The XChangePointerControl function defines how the pointing device
moves. The acceleration, expressed as a fraction, is a multiplier for
movement. For example, specifying 3/1 means the pointer moves three times
as fast as normal. The fraction may be rounded arbitrarily by the X server.
Acceleration only takes effect if the pointer moves more than threshold pixels
at once and only applies to the amount beyond the value in the threshold
argument. Setting a value to -1 restores the default. The values of the
do_acce1 and do_threshold arguments must be True for the pointer values to
be set, or the parameters are unchanged. Negative values (other than -1)
generate a BadVal ue error, as does a zero value for the accel_denominator
argument.
XChangePointerControl can generate a BadValue error.

The XGetPointerControl function returns the pointer's current
acceleration multiplier and acceleration threshold.

Diagnostics
BadValue

See Also
Guide to the Xlib Library

3-388 Subroutines

XChangeSaveSet (3X11 )
Name
XChangeSaveSet, XAddToSaveSet, XRemoveFromSaveSet - change a
client's save set

Syntax
XChangeSaveSet(display, w, change_mode)
Display *display;
Windoww;
int change_mode;
XAddToSaveSet(display, w)
Display *display;
Windoww;
XRemoveFromSaveSet( display, w)
Display *display;
Window w;

Arguments
change_mode

Specifies the mode. You can pass SetModelnsert or
SetModeDelete.

display

Specifies the connection to the X server.

Specifies the window that you want to add or delete from the
client's save-set.

Description
Depending on the specified mode, XChangeSaveSet either inserts or
deletes the specified window from the client's save-set. The specified window
must have been created by some other client, or a BadMa t ch error results.
XChangeSaveSet can generate BadMatch, BadValue, and
BadWindow errors.

The XAddToSaveSet function adds the specified window to the client's
save-set. The specified window must have been created by some other client,
or a BadMatch error results.
XAddToSaveSet can generate BadMatch and BadWindow errors.

The XRemoveFromSaveSet function removes the specified window from
the client's save-set. The specified window must have been created by some
other client, or a BadMa t ch error results.
Subroutines 3-389

XChangeSaveSet (3X11 )
XRemoveFromSaveSet can generate BadMatch and BadWindow errors.

Diagnostics
BadMatch

Some argument or pair of arguments has the correct type and
range but fails to match in some other way required by the
request.

BadVal ue

BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XReparentWindow(3Xll )
Guide to the Xlib Library

3-390 Subroutines

XChangeWindowAttributes (3X11 )
Name
XChangeWindowAttributes, XSetWindowBackground,
XSetWindowBackgroundPixmap, XSetWindowBorder,
XSetWindowBorderPixmap - change window attributes

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

XSetWindowBackground(display, w, backgroundyixel)
Display *display;
Window w;
unsigned long backgroundyixel;
XSetWindowBackgroundPixmap( display, w, backgroundyixmap)
Display *display;
Window w;
Pixmap backgroundyixmap;

XSetWindowBorder(display, w, borderyixel)
Display *display;
Window w;
unsigned long borderyixel;

XSetWindowBorderPixmap(display, w, borderyixmap)
Display *display;
Windoww;
Pixmap borderyixmap;

Arguments
attributes

Specifies the structure from which the values (as specified by
the value mask) are to be taken. The value mask should have
the appropriate bits set to indicate which attributes have been
set in the structure.

backgroundyixel
Specifies the pixel that is to be used for the background.

backgroundyixmap
Specifies the background pixmap, ParentRelati ve, or

Subroutines 3-391

XChangeWindowAttributes (3X11 )
None.
borderyixel

Specifies the entry in the colorrnap.

borderyixmap Specifies the border pixmap or CopyFrornParent.
display

Specifies the connection to the X server.

valuemask

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

Specifies the window.

Description
Depending on the valuemask, the XChangeWindowAttributes function
uses the window attributes in the XSetWindowAttributes structure to
change the specified window attributes. Changing the background does not
cause the window contents to be changed. To repaint the window and its
background, use XCIearWindow. Setting the border or changing the
background such that the border tile origin changes causes the border to be
repainted. Changing the background of a root window to None or
ParentReIative restores the default background pixmap. Changing the
border of a root window to CopyFrornParent 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 Al ways, or changing the backing-planes, backing-pixel, or
save-under of a mapped window may have no immediate effect. Changing
the colorrnap of a window (that is, defining a new map, not changing the
contents of the existing map) generates a ColormapNotify event.
Changing the colorrnap of a visible window may have no immediate effect on
the screen because the map may not be installed (see
XlnstaIIColormap). Changing the cursor of a root window to None
restores the default cursor. Whenever possible, you are encouraged to share
colorrnaps.
Multiple clients can select input on the same window. Their event masks are
maintained separately. When an event is generated, it is reported to all
interested clients. However, only one client at a time can select for
SubstructureRedirectMask, ResizeRedirectMask,and
ButtonPressMask. If a client attempts to select any of these event masks
and some other client has already selected one, a BadAccess error results.
There is only one do-not-propagate-mask for a window, not one per client.

3-392 Subroutines

XChangeWindowAttributes (3X11 )
XChangeWindowAttributes can generate BadAccess, BadColor,
BadCursor, BadMatch, BadPixmap, BadValue, and BadWindow
errors.

The XSetWindowBackground function sets the background of the
window to the specified pixel value. Changing the background does not
cause the window contents to be changed. XSetWindowBackground
uses a pixmap of undefined size filled with the pixel value you passed. If
you try to change the background of an InputOnly window, a BadMatch
error results.
XSetWindowBackground can generate BadMatch and BadWindow
errors.

The XSetWindowBackgroundP ixmap function sets the background
pixmap of the window to the specified pixmap. The background pixmap can
immediately be freed if no further explicit references to it are to be made. If
ParentRelati ve is specified, the background pixmap of the window's
parent is used, or on the root window, the default background is restored. If
you try to change the background of an InputOnly window, a BadMatch
error results. If the background is set to None, the window has no defined
background.
XSetWindowBackgroundP ixmap can generate BadMatch,
BadP ixmap, and BadWindow errors.

The XSetWindowBorder function sets the border of the window to the
pixel value you specify. If you attempt to perform this on an InputOnly
window, a BadMatch error results.
XSetWindowBorder can generate BadMatch and BadWindow errors.

The XSetWindowBorderP ixmap function sets the border pixmap of the
window to the pixmap you specify. The border pixmap can be freed
immediately if no further explicit references to it are to be made. If you
specify CopyFromParent, a copy of the parent window's border pixmap is
used. If you attempt to perform this on an InputOnly window, a
BadMat ch error results.
XSetWindowBorderPixmap can generate BadMatch, BadPixmap, and
BadWindow errors.

Diagnostics
BadAccess

A client attempted to free a color map entry that it did not
already allocate.

BadAccess

A client attempted to store into a read-only color map entry.
Subroutines 3-393

XChangeWindowAHributes (3X11 )
BadColor

A value for a Colormap argument does not name a defined
Colormap.

BadCursor

A value for a Cursor argument does not name a defined
Cursor.

BadMat ch

Some argument or pair of arguments has the correct type and
range but fails to match in some other way required by the
request.

BadMatch

An InputOnly window locks this attribute.

BadPixmap

A value for a Pixmap argument does not name a defined
Pixmap.

BadValue

BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XConfigureWindow(3Xll), XCreateWindow(3Xll),
XDestroyWindow(3Xl1), XMapWindow(3Xll), XRaiseWindow(3Xll),
XUnmapWindow(3Xl1)
Guide to the Xlib Library

3-394 Subroutines

XClearArea (3X11)
Name
XClearArea, XClearWindow - clear area or window

Syntax
XClearArea(display, w, x, y, width, height, exposures)
Display *display;
Windoww;
int x, y;
unsigned int width, height;
Bool exposures;
XClearWindow(display, w)
Display *display;
Window w;

Arguments
display

Specifies· the connection to the X server.

exposures

Specifies a Boolean value that indicates if Expose events
are to be generated.

Specifies the window.

width
height

Specify the width and height, which are the dimensions of
the rectangle.

Specify the x and y coordinates, which are relative to the
origin of the window and specify the upper-left corner of the
rectangle.

Description
The XClearArea function paints a rectangular area in the specified window
according to the specified dimensions with the window's background pixel or
pixmap. The subwindow-mode effectively is ClipByChildren. If width
is zero, it is replaced with the current width of the window minus x. If
height is zero, it is replaced with the current height of the window minus y.
If the window has a defined background tile, the rectangle clipped by any
children is filled with this tile. If the window has background None, the
contents of the window are not changed. In either case, if exposures is True,
one or more Expo s e events are generated for regions of the rectangle that

Subroutines 3-395

XClearArea (3X11)
are either visible or are being retained in a backing store. If you specify a
window whose class is InputOnly, a BadMatch error results.
XClearArea can generate BadMatch, BadValue, and BadWindow

errors.
The XClearWindow function clears the entire area in the specified window
and is equivalent to XClearArea (display, w, 0, 0, 0, 0, False). If the
window has a defined background tile, the rectangle is tiled with a planemask of all ones and GXcopy function. If the window has background
None, the contents of the window are not changed. If you specify a window
whose class is InputOnly, a BadMatch error results.
XClearWindow can generate BadMatch and BadWindow errors.

Diagnostics
BadMatch

An InputOnly window is used as a Drawable.

BadValue

BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XCopyArea(3Xll)
Guide to the Xlib Library

3-396 Subroutines

XConfigureWindow (3X11 )
Name
XConfigureWindow, XMoveWindow, XResizeWindow,
XMoveResizeWindow, XSetWindowBorderWidth - configure windows

Syntax
XConfigureWindow(display, w, value mask, values)
Display *display;
Windoww;
unsigned int value_mask;
XWindowChanges *values;
XMoveWindow(display, w, x, y)
Display *display;
Windoww;
int x, y;
XResizeWindow(display, w, width, height)
Display *display;
Windoww;
unsigned int width, height;
XMoveResizeWindow(display, w, x, y, width, height)
Display *display;
Windoww;
int x, y;
unsigned int width, height;
XSetWindowBorderWidth(display, w, width)
Display *display;
Windoww;
unsigned int width;

Arguments
display

Specifies the connection to the X server.

value mask

Specifies which values are to be set using information in the
values structure. This mask is the bitwise inclusive OR of
the valid configure window values bits.

values

Specifies a pointer to the XWindowChanges structure.

Specifies the window to be reconfigured, moved, or resized..

width

Specifies the width of the window border.

Subroutines 3-397

XConfigureWindow(3X11 )
width
height

x
y

Specify the width and height, which are the interior
dimensions of the window.
Specify the x and y coordinates, which define the new
location of the top-left pixel of the window's border or the
window itself if it has no border or define the new position
of the window relative to its parent.

Description
The XConfigureWindow function uses the values specified in the
XWindowChanges structure to reconfigure a window's size, position,
border, and stacking order. Values not specified are taken from the existing
geometry of the window.
If a sibling is specified without a stack_mode or if the window is not actually
a sibling, a BadMatch error results. Note that the computations for
BottomIf, TopIf, and Opposite are performed with respect to the
window's final geometry (as controlled by the other arguments passed to
XConfigureWindow), not its initial geometry. Any backing store contents
of the window, its inferiors, and other newly visible windows are either
discarded or changed to reflect the current screen contents (depending on the
implementation).

XConfigureWindow can generate BadMatch, BadValue, and
BadWindowerrors.
The XMoveWindow function moves the specified window to the specified x
and y coordinates, but it does not change the window's size, raise the
window, or change the mapping state of the window. Moving a mapped
window mayor may not lose the window's contents depending on if the
window is obscured by nonchildren and if no backing store exists. If the
contents of the window are lost, the X server generates Expo s e events.
Moving a mapped window generates Expose events on any formerly
obscured windows.
If the override-redirect flag of the window is False and some other client
has selected SubstructureRedirectMask on the parent, the X server
generates a ConfigureRequest event, and no further processing is
performed. Otherwise, the window is moved.

XMoveWindow can generate a BadWindow error.

3-398 Subroutines

XConfigureWindow{3X11 )
The XResizeWindow function changes the inside dimensions of the
specified window, not including its borders. This function does not change
the window's upper-left coordinate or the origin and does not restack the
window. Changing the size of a mapped window may lose its contents and
generate Expose events. If a mapped window is made smaller, changing its
size generates Expose events on windows that the mapped window formerly
obscured.
If the override-redirect flag of the window is False and some other client
has selected SubstructureRedirectMask on the parent, the X server
generates a ConfigureRequest event, and no further processing is
performed. If either width or height is zero, a BadValue error results.
XResizeWindow can generate BadValue and BadWindow errors.

The XMoveResizeWindow function changes the size and location of the
specified window without raising it. Moving and resizing a mapped window
may generate an Expose event on the window. Depending on the new size
and location parameters, moving and resizing a window may generate
Expo s e events on windows that the window formerly obscured.
If the override-redirect flag of the window is False and some other client
has selected SubstructureRedirectMask on the parent, the X server
generates a ConfigureRequest event, and no further processing is
performed. Otherwise, the window size and location are changed.
XMoveResizeWindow can generate BadValue and BadWindow errors.

The XSetWindowBorderWidth function sets the specified window's
border width to the specified width.
XSetWindowBorderWidth can generate a BadWindow error.

Diagnostics
BadMatch

An InputOnly window is used as a Drawable.

BadMatch

Some argument or pair of arguments has the correct type and
range but fails to match in some other way required by the
request.

BadValue

BadWindow

A value for a Window argument does not name a defined

Subroutines 3-399

XConfigureWindow(3X11 )
Window.

See Also
XChangeWindowAttributes(3Xll), XCreateWindow(3X 11),
XDestroyWindow(3Xll), XMapWindow(3Xl1), XRaiseWindow(3Xll),
XUnmapWindow(3Xl1)
Guide to the Xlib Library

3-400 Subroutines

XCopyArea (3X11)
Name
XCopyArea, XCopyPlane - copy areas

Syntax
XCopyArea(display, src, dest, gc, src_x, srcy, width, height, dest_x,
desty)
Display *display;
Drawable src, dest;
GCgc;
int srcy, srcy;
unsigned int width, height;
int dest_x, desty;
XCopyPlane(display, src, dest, gc, src~, srcy, width, height, dest_x,
desty, plane)
Display *display;
Drawable src, dest;
GC gc;
int srcy, srcy;
unsigned int width, height;
int dest_x, desty;
unsigned long plane;

Arguments
dest x
desty

display
gc
plane
src
dest
src x
srcy

Specify the x and y coordinates, which are relative to the
origin of the destination rectangle and specify its upper-left
comer.
Specifies the connection to the X server.
Specifies the GC.
Specifies the bit plane. You must set exactly one bit to 1.
Specify the source and destination rectangles to be combined.
Specify the x and y coordinates, which are relative to the
origin of the source rectangle and specify its upper-left
comer.

width
Subroutines 3-401

XCopyArea{3X11 )
height

Specify the width and height, which are the dimensions of
both the source and destination rectangles.

Description
The XCopyArea function combines the specified rectangle of src with the
specified rectangle of dest. The drawables must have the same root and
depth, or a BadMatch error results.
If regions of the source rectangle are obscured and have not been retained in
backing store or if regions outside the boundaries of the source drawable are
specified, those regions are not copied. Instead, the following occurs on all
corresponding destination regions that are either visible or are retained in
backing store.
If the destination is a window with a background other than None,
corresponding regions of the destination are tiled with that background (with
plane-mask of all ones and GXcopy function).

Regardless of tiling or whether the destination is a window or a pixmap, if
graphics-exposures is True, then GraphicsExpose events for all
corresponding destination regions are generated. If graphics-exposures is
True but no GraphicsExpose events are generated, a NoExpose event
is generated. Note that by default graphics-exposures is True in new GCs.
This function uses these GC components: function, plane-mask, subwindowmode, graphics-exposures, clip-x-origin, clip-y-origin, and clip-mask.
XCopyArea can generate BadDrawable, BadGC, and BadMatch errors.

The XCopyP lane function uses a single bit plane of the specified source
rectangle combined with the specified GC to modify the specified rectangle
of dest. The drawables must have the same root but need not have the same
depth. If the drawables do not have the same root, a BadMat ch error
results. If plane does not have exactly one bit set to 1 and the values of
planes must be less than 2n , where n is the depth of scr, a BadValue error
results.
Effectively, XCopyP lane forms a pixmap of the same depth as the
rectangle of dest and with a size specified by the source region. It uses the
foreground/background pixels in the GC (foreground everywhere the bit
plane in src contains a bit set to 1, background everywhere the bit plane in
src contains a bit set to 0) and the equivalent of a CopyArea potocol
request is performed with all the same exposure semantics. This can also be
thought of as using the specified region of the source bit plane as a stipple
with a fill-style of FillOpaqueStippled for filling a rectangular area of
the destination.
3-402 Subroutines

XCopyArea (3X11)
This function uses these GC components: function, plane-mask, foreground,
background, subwindow-mode, graphics-exposures, clip-x-origin, clip-yorigin, and clip-mask.
XCopyP lane can generate BadDrawable, BadGC, BadMatch, and
BadValue errors.

Diagnostics
BadDrawable

A value for a Drawable argument does not name a defined
Window or Pixmap.
BadGC

A value for a GContext argument does not name a defined
GContext.

BadMatch

An InputOnly window is used as a Drawable.

BadMatch

Some argument or pair of arguments has the correct type and
range but fails to match in some other way required by the
request.

BadValue

See Also
XClearArea(3Xll)
Guide to the Xlib Library

Subroutines 3-403

XCreateColormap (3X11 )
Name
XCreateColormap, XCopyColormapAndFree, XFreeColormap,
XSetWindowColormap - create, copy, or destroy colormaps

Syntax
Colormap XCreateColormap(display, w, visual, aUoe)
Display *display;
Window w;
Visual *visual;
int aUoe;
Colormap XCopyColormapAndFree( display, eolormap)
Display *display;
Colormap eolormap;
XFreeColormap( display, eolormap)
Display *display;
Colormap eolormap;
XSetWindowColormap(display, w, eolormap)
Display *display;
Windoww;
Colormap eolormap;

Arguments
aUoe

Specifies the colormap entries to be allocated. You can pass
AllocNone or AllocAll.

eolormap

Specifies the colormap that you want to create, copy, set, or
destroy.

display

Specifies the connection to the X server.

visual

Specifies a pointer to a visual type supported on the screen.
If the visual type is not one supported by the screen, a
BadMatch error results.

Specifies the window for which you want to create or set a
colormap.

3-404 Subroutines

XCreateColormap (3X11 )
Description
The XCreateColormap function creates a colonnap of the specified visual
type for the screen on which the specified window resides and returns the
colonnap ID associated with it. Note that the specified window is only used
to detennine the screen.
The initial values of the colonnap entries are undefined for the visual classes
GrayScale, PseudoColor, and DirectColor. For StaticGray,
StaticColor, and TrueColor, the entries have defined values, but those
values are specific to the visual and are not defined by X. For
StaticGray, StaticColor, and TrueColor, alloc must be
AllocNone, or a BadMatch error results. For the other visual classes, if
alloc is AllocNone, the colonnap initially has no allocated entries, and
clients can allocate them. For infonnation about the visual types, see Section
3.1.

If alloc is AllocAII, the entire colonnap is allocated writable. The initial
values of all allocated entries are undefined. For GrayScale and
PseudoColor, the effect is as if an XAllocColorCells call returned
all pixel values from zero to N - 1, where N is the colormap entries value in
the specified visual. For DirectColor, the effect is as if an
XAllocColorP lanes call returned a pixel value of zero and red_mask,
green_mask, and blue_mask values containing the same bits as the
corresponding masks in the specified visual. However, in all cases, none of
these entries can be freed by using XFreeColors.
XCreateColormap can generate BadAlloc, BadMatch, BadValue,
and BadWindow errors.
The XCopyColormapAndFree function creates a colonnap of the same
visual type and for the same screen as the specified colormap and returns the
new colormap ID. It also moves all of the client's existing allocation from
the specified colonnap to the new colorinap with their color values intact and
their read-only or writable characteristics intact and frees those entries in the
specified colormap. Color values in other entries in the new colonnap are
undefined.

If the specified colonnap was created by the client with alloc set to
AllocAII, the new colormap is also created with AllocAII, all color
values for all entries are copied from the specified colonnap, and then all
entries in the specified colonnap are freed. If the specified colonnap was not
created by the client with All 0 cAll, the allocations to be moved are all
those pixels and planes that have been allocated by the client using
XAllocColor,XAllocNamedColor, XAllocColorCells, or
XAllocColorP lanes and that have not been freed since they were
Subroutines 3-405

XCreateColormap (3X11 )
allocated.
XCopyColormapAndFree can generate BadAlloc and BadColor
errors.
The XFreeColormap function deletes the association between the
colormap resource ID and the colormap and frees the colormap storage.
However, this function has no effect on the default colormap for a screen. If
the specified colormap is an installed map for a screen, it is uninstalled (see
XUninstallColormap). If the specified colormap is defined as the
colormap for a window (by XCreateWindow, XSetWindowColormap,
or XChangeWindowAttributes), XFreeColormap changes the
colormap associated with the window to None and generates a
ColormapNotifyevent. X does not define the colors displayed for a
window with a colormap of None.
XFreeColormap can generate a BadColor error.
The XSetWindowColormap function sets the specified colormap of the
specified window. The colormap must have the same visual type as the
window, or a BadMatch error results.
XSetWindowColormap can generate BadColor, BadMatch, and
BadWindow errors.

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadColor

A value for a Colormap argument does not name a defined
Colormap.

BadMatch
BadMatch

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.

BadValue

BadWindow

3-406 Subroutines

XCreateColormap (3X11 )
See Also
XAllocColor(3Xll), XQueryColor(3Xll), XStoreColors(3Xll)
Guide to the Xlib Library

Subroutines 3-407

XCreateFontCursor (3X11 )
Name
XCreateFontCursor, XCreatePixmapCursor, XCreateGlyphCursor - create
cursors

Syntax
#include <Xll/cursorfont.h>
Cursor XCreateFontCursor(display, shape)
Display *display;
unsigned int shape;
Cursor XCreatePixmapCursor( display, source, mask, foreground_color,
background_color,x,y)
Display *display;
Pixmap source;
Pixmap mask;
XColor *foreground_color;
XColor *background color;
unsigned int x, y;
Cursor XCreateGlyphCursor(display, sourceJont, maskJont, source_char,
mask char, foreground color, background color)
Display *display; Font sourceJont, maskJont;
unsigned int source_char, mask_char;
XColor *foreground_color;
XColor *background_color;

Arguments
background_color
Specifies the RGB values for the background of the source.
display

Specifies the connection to the X server.

foreground_color
Specifies the RGB values for the foreground of the source.
mask

Specifies the cursor's source bits to be displayed or None.

mask char

Specifies the glyph character for the mask.

maskJont

Specifies the font for the mask glyph or None.

shape

Specifies· the shape of the cursor.

3-408 Subroutines

XCreateFontCursor (3X11 )
source

Specifies the shape of the source cursor.

source char

Specifies the character glyph for the source.

sourceJont

Specifies the font for the source glyph.

x
y

Specify the x and y coordinates, which indicate the hotspot
relative to the source's origin.

Description

x provides a set of standard cursor shapes in a special font named cursor.
Applications are encouraged to use this interface for their cursors because the
font can be customized for the individual display type. The shape argument
specifies which glyph of the standard fonts to use.
The hotspot comes from the information stored in the cursor font. The initial
colors of a cursor are a black foreground and a white background (see
XRecolorCursor).
XCreateFontCursor can generate BadAlloc and BadValue errors.
The XCreateP ixmapCursor function creates a cursor and returns the
cursor ID associated with it. The foreground and background RGB values
must be specified using foreground_color and background_color, even if the
X server only has a StaticGray or GrayScale screen. The foreground
color is used for the pixels set to 1 in the source, and the background color is
used for the pixels set to O.
Both source and mask, if specified, must have depth one (or a BadMat ch
error results) but can have any root. The Mask argument defines the shape of
the cursor. The pixels set to 1 in the mask define which source pixels are
displayed, and the pixels set to 0 define which pixels are ignored. If no mask
is given, all pixels of the source are displayed. The mask, if present, must be
the same size as the pixmap defined by the source argument, or a BadMat ch
error results. The hotspot must be a point within the source, or a BadMat ch
error results.
The components of the cursor can be transformed arbitrarily to meet display
limitations. The pixmaps can be freed immediately if no further explicit
references to them are to be made. Subsequent drawing in the source or
mask pixmap has an undefined effect on the cursor. The X server might or
might not make a copy of the pixmap.
XCreatePixmapCursor can generate BadAlloc and BadPixmap
errors.

Subroutines 3-409

XCreateFontCursor{3X11 )
The XCreateGlyphCursor function is similar to
XCreateP ixmapCursor except that the source and mask bitmaps are
obtained from the specified font glyphs. The source_char must be a defined
glyph in source_font, or a BadValue error results. If mask_font is given,
mask_char must be a defined glyph in mask_font, or a BadVal ue error
results. The mask_font and character are optional.
The origins of the source_char and mask_char (if defined) glyphs are
positioned coincidently and define the hotspot. The source_char and
mask_char need not have the same bounding box metrics, and there is no
restriction on the placement of the hotspot relative to the bounding boxes. If
no mask_char is given, all pixels of the source are displayed. You can free
the fonts immediately by calling XFreeFont if no further explicit
references to them are to be made.
For 2-byte matrix fonts, the 16-bit value should be fonned with the byte1
member in the most-significant byte and the byte2 member in the leastsignificant byte.
XCreateGlyphCursor can generate BadAlloc, BadFont, and
BadVal ue errors.

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadFont

A value for a Font or GContext argument does not name a
defined Font.

BadMatch

Some argument or pair of arguments has the correct type and
range but fails to match in some other way required by the
request.

BadPixmap

A value for a Pixmap argument does not name a defined
Pixmap.

BadVal ue

3-410 Subroutines

XCreateFontCursor (3X11 )
See Also
XDefineCursor(3Xll), XRecolorCursor(3Xll)
Guide to the Xlib Library

Subroutines 3-411

XCreateGC (3X11 )
Name
XCreateGC, XCopyGC, XChangeGC, XFreeGC, XGContextFromGCcreate or free graphics contexts

Syntax
GC XCreateGC(display, d, valuemask, values)
Display *display;
Drawable d;
unsigned long valuemask;
XGCValues *values;
XCopyGC(display, src, valuemask, dest)
Display *display;
GC src, dest;
unsigned long valuemask;
XChangeGC(display, gc, valuemask, values)
Display *display;
GCgc;
unsigned long valuemask;
XGCValues * values;
XFreeGC(display, gc)
Display *display;
GC gc;
GContext XGContextFromGC(gc)
GCgc;

Arguments
d

Specifies the drawable.

dest

Specifies the destination GC.

display

Specifies the connection to the X server.

Specifies the GC.

src

Specifies the components of the source GC.

valuemask

Specifies which components in the GC are to be set, copied,
or changed. This argument is the bitwise inclusive OR of
one or more of the valid GC component mask bits.

values

Specifies any values as specified by the valuemask.

3-412 Subroutines

XCreateGC (3X11 )
Description
The XCreateGC function creates a graphics context and returns a GC. The
GC can be used with any destination drawable having the same root and
depth as the specified drawable. Use with other drawables results in a
BadMatch error.
XCreateGC can generate BadAlloc, BadDrawable, BadFont,
BadMatch, BadPixmap, and BadValue errors.

The XCopyGC function copies the specified components from the source GC
to the destination GC. The source and destination GCs must have the same
root and depth, or a BadMatch error results. The valuemask specifies
which component to copy, as for XCreateGC.
XCopyGC can generate BadAlloc, BadGC, and BadMatch errors.

The XChangeGC function changes the components specified by valuemask
for the specified GC. The values argument contains the values to be set. The
values and restrictions are the same as for XCreateGC. Changing the clipmask overrides any previous XSetClipRectangles request on the
context. Changing the dash-offset or dash-list overrides any previous
XSetDashes request on the context. The order in which components are
verified and altered is server-dependent. If an error is generated, a subset of
the components may have been altered.
XChangeGC can generate BadAlloc, BadFont, BadGC, BadMatch,
BadP ixmap, and BadVal ue errors.

The XFreeGC function destroys the specified GC as well as all the
associated storage.
XFreeGC can generate a BadGC error.

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadDrawable

A value for a Drawable argument does not name a defined
Window or Pixmap.
BadFont

A value for a Font or GContext argument does not name a
defined Font.

BadGC

A value for a GContext argument does not name a defined
GContext.
Subroutines 3-413

XCreateGC (3X11 )
BadMatch

An InputOnly window is used as a Drawable.

BadMatch

Some argument or pair of arguments has the correct type and
range but fails to match in some other way required by the
request.

BadPixmap

A value for a Pixmap argument does not name a defined
Pixmap.

BadValue

See Also
XQueryBestSize(3Xll), XSetArcMode(3Xll), XSetClipOrigin(3Xll),
XSetFillStyle(3Xll), XSetFont(3Xll), XSetLineAttributes(3Xl1),
XSetState(3Xl1), XSetTile(3Xl1)
Guide to the Xlib Library

3-414 Subroutines

XCreatelmage (3X11 )
Name
XCreateImage, XGetPixel, XPutPixel, XSubImage, XAddPixel,
XDestroyImage - image utilities

Syntax
XImage *XCreateImage(display, visual, depth,format, offset, data, width,
height, bitmapyad, bytesyer_line)
Display *display;
Visual *visual;
unsigned int depth;
intformat;
int offset;
char *data;
unsigned int width;
unsigned int height;
int bitmapyad;
int bytesyer_line;
unsigned long XGetPixel(ximage, x, y)
XImage *ximage;
int x;
int y;

int XPutPixel (ximage, x, y, pixel)
XImage *ximage;
int x;
int y;
unsigned long pixel;
XImage *XSubImage(ximage, x, y, subimage_width, subimage_height)
XImage *ximage;
int x;
int y;
unsigned int subimage width;
unsigned int subimage-height;

XAddPixel(ximage, value)
XImage *ximage;
long value;
int XDestroylmage(ximage)
XImage *ximage;

Subroutines 3-415

XCreatelmage (3X11 )
Arguments
bitmapyad

Specifies the quantum of a scanline (8, 16, or 32). In other
words, the start of one scanline is separated in client memory
from the start of the next scanline by an integer multiple of
this many bits.

bytesyer_line Specifies the number of bytes in the client image between the
start of one scanline and the start of the next.
data

Specifies a pointer to the image data.

depth

Specifies· the depth of the image.

display

Specifies the connection to the X server.

format

Specifies the format for the image. You can pass
XYBitmap,XYPixmap,orZPixmap.

height

Specifies the height of the image, in pixels.

offset

Specifies the number of pixels to ignore at the beginning of
the scanline.

pixel

Specifies the new pixel value.

subimage_height
Specifies the height of the new subimage, in pixels.
sub image width
Specifies the width of the new subimage, in pixels.
value

Specifies the constant value that is to be added.

visual

Specifies a pointer to the visual.

width

Specifies the width of the image, in pixels.

ximage

Specifies a pointer to the image.

Specify the x and y coordinates.

Description
The XCreateImage function allocates the memory needed for an XImage
structure for the specified display but does not allocate space for the image
itself. Rather, it initializes the structure byte-order, bit-order, and bitmap-unit
values from the display and returns a pointer to the XImage structure. The
red, green, and blue mask values are defined for Z format images only and
are derived from the Visual structure passed in. Other values also are
passed in. The offset permits the rapid displaying of the image without
3-416 Subroutines

XCreatelmage (3X11 )
requiring each scanline to be shifted into position. If you pass a zero value
in bytes_per_Iine, Xlib assumes that the scanlines are contiguous in memory
and calculates the value of bytes_per_Iine itself.
Note that when the image is created using XCreatelmage, XGetlmage,
or XSublmage, the destroy procedure that the XDestroylmage function
calls frees both the image structure and the data pointed to by the image
structure.
The basic functions used to get a pixel, set a pixel, create a subimage, and
add a constant offset to a Z format image are defined in the image object.
The functions in this section are really macro invocations of the functions in
the image object and are defined in <Xll/Xutil. h>.
The XGetPixel function returns the specified pixel from the named image.
The pixel value is returned in normalized format (that is, the least-significant
byte of the long is the least-significant byte of the pixel). The image must
contain the x and y coordinates.
The XPutPixel function overwrites the pixel in the named image with the
specified pixel value. The input pixel value must be in normalized format
(that is, the least-significant byte of the long is the least-significant byte of
the pixel). The image must contain the x and y coordinates.
The XSublmage function creates a new image that is a subsection of an
existing one. It allocates the memory necessary for the new Xlmage
structure and returns a pointer to the new image. The data is copied from the
source image, and the image must contain the rectangle defined by x, y,
subimage_width, and subimage_height.
The XAddP ixel function adds a constant value to every pixel in an image.
It is useful when you have a base pixel value from allocating color resources
and need to manipulate the image to that form.
The XDestroylmage function deallocates the memory associated with the
Xlmage structure.

See Also
XPutlmage(3Xll)
Guide to the Xlib Library

Subroutines 3-417

XCreatePixmap (3X11 )
Name
XCreatePixmap, XFreePixmap - create or destroy pixmaps

Syntax
Pixmap XCreatePixmap(display, d, width, height, depth)
Display *display;
Drawabled;
unsigned int width, height;
unsigned int depth;
XFreePixmap(display, pixmap)
Display *display;
Pixmap pixmap;

Arguments
d

Specifies which screen the pixmap is created on.

depth

Specifies the depth of the pixmap.

display

Specifies the connection to the X server.

pixmap

Specifies the pixmap.

width
height

Specify the width and height, which define the dimensions of
the pixmap.

Description
The XCreatePixmap function creates a pixmap of the width, height, and
depth you specified and returns a pixmap ID that identifies it. It is valid to
pass an InputOnly window to the drawable argument. The width and
height arguments must be nonzero, or a BadValue error results. The depth
argument must be one of the depths supported by the screen of the specified
drawable, or a BadVal ue error results.
The server uses the specified drawable to determine on which screen to create
the pixmap. The pixmap can be used only on this screen and only with other
drawables of the same depth (see XCopyP lane for an exception to this
rule). The initial contents of the pixmap are undefined.
XCreateP ixmap can generate BadAlloc, BadDrawable, and
BadVal ue errors.

3-418 Subroutines

XCreatePixmap (3X11 )
The XFreePixmap function first deletes the association between the
pixmap ID and the pixmap. Then, the X server frees the pixmap storage
when there are no references to it. The pixmap should never be referenced
again.
XFreePixmap can generate a BadPixmap error.

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadDrawable
A value for a Drawable argument does not name a defined
Window or Pixmap.
BadPixmap

A value for a Pixmap argument does not name a defined
Pixmap.

BadVal ue

See Also
Guide to the Xlib Library

Subroutines 3-419

XCreateRegion (3X11 )
Name
XCreateRegion, XSetRegion, XDestroyRegion - create or destroy regions

Syntax
Region XCreateRegionO

XSetRegion(display, gc, r)
Display *display;
GCgc;
Region r;
XDestroyRegion (r)
Region r;

Arguments
display

Specifies the connection to the X server.

Specifies the GC.

Specifies the region.

Description
The XCreateRegion function creates a new empty region.
The XSetRegion function sets the clip-mask in the GC to the specified
region. Once it is set in the GC, the region can be destroyed.
The XDestroyRegion function deallocates the storage associated with a
specified region.

See Also
XEmptyRegion(3Xll), XIntersectRegion(3Xll)
Guide to the Xlib Library

3-420 Subroutines

XCreateWindow {3X11 }
Name
XCreateWindow, XCreateSimpleWindow - create windows

Syntax
Window XCreateWindow(display, parent, x, y, width, height, border width,
depth, class, visual, valuemask, attributes)
Display *display;
Window parent;
int x, y;
unsigned int width, height;
unsigned int border width;
int depth;
unsigned int class;
Visual *visual
unsigned long valuemask;
XSetWindowAttributes *attributes;
Window XCreateSimpleWindow(display, parent, x, y, width, height,
border_width, border, background)
Display *display;
Window parent;
int x, y;
unsigned int width, height;
unsigned int border width;
unsigned long border;
unsigned long background;

Arguments
attributes

background

Specifies the background pixel value of the window.

border

Specifies the border pixel value of the window.

border width

Specifies the width of the created window's border in pixels.

class

Specifies the created window's class. You can pass
InputOutput,InputOnly,orCopyFromParent. A

Subroutines 3-421

XCreateWindow (3X11 )
class of CopyFromParent means the class is taken from
the parent.
depth

Specifies the window's depth. A depth of
CopyFromParent means the depth is taken from the
parent.

display

Specifies the connection to the X server.

parent

Specifies the parent window.

valuemask

visual

Specifies the visual type. A visual of CopyFromParent
means the visual type is taken from the parent.

width
height

x
y

Specify the width and height, which are the created window's
inside dimensions and do not include the created window's
borders.
Specify the x and y coordinates, which are the top-left
outside corner of the window's borders and are relative to the
inside of the parent window's borders.

Description
The XCreateWindow function creates an unmapped subwindow for a
specified parent window, returns the window ID of the created window, and
causes the X server to generate a CreateNotify event. The created
window is placed on top in the stacking order with respect to siblings.
The border_width for an InputOnly window must be zero, or a
BadMatch error results. For class InputOutput, the visual type and
depth must be a combination supported for the screen, or a BadMat ch error
results. The depth need not be the same as the parent, but the parent must
not be a window of class InputOnly, or a BadMatch error results. For
an InputOnly window, the depth must be zero, and the visual must be one
supported by the screen. If either condition is not met, a BadMatch error
results. The parent window, however, may have any depth and class. If you
specify any invalid window attribute for a window, a BadMa t ch error
results.

3-422 Subroutines

XCreateWindow (3X11 )
The created window is not yet displayed (mapped) on the user's display. To
display the window, call XMapWindow. The new window initially uses the
same cursor as its parent. A new cursor can be defined for the new window
by calling XDefineCursor. The window will not be visible on the screen
unless it and all of its ancestors are mapped and it is not obscured by any of
its ancestors.
XCreateWindow can generate BadAlloc BadColor, BadCursor,
BadMatch, BadP ixmap, BadVal ue, and BadWindow errors.
The XCreateSimpleWindow function creates an unmapped
InputOutput subwindow for a specified parent window, returns the
window ID of the created window, and causes the X server to generate a
CreateNotifyevent. The created window is placed on top in the
stacking order with respect to siblings. Any part of the window that extends
outside its parent window is clipped. The border_width for an InputOnly
window must be zero, or a BadMatch error results.
XCreateSimpleWindow inherits its depth, class, and visual from its
parent. All other window attributes, except background and border, have
their default values.
XCreateSimpleWindow can generate BadAlloc, BadMatch,
BadVal ue, and BadWindow errors.

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadColor

A value for a Colormap argument does not name a defined
Colormap.

BadCursor

A value for a Cursor argument does not name a defined
Cursor.

BadMatch

The values do not exist for an InputOnly window.

BadMatch

Some argument or pair of arguments has the correct type and
range but fails to match in some other way required by the
request.

BadPixmap

A value for a Pixmap argument does not name a defined
Pixmap.

BadValue

XCreateWindow (3X11 )
alternatives can generate this error.
BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XChangeWindowAttributes(3Xll), XConfigureWindow(3Xll),
XDestroyWindow(3Xll), XMapWindow(3Xll), XRaiseWindow(3Xll),
XUnmapWindow(3Xll)
Guide to the Xlib Library

3-424 Subroutines

XDefineCursor (3X11 )
Name
XDefineCursor, XUndefineCursor - define cursors

Syntax
XDefineCursor( display, w, cursor)
Display *display;
Window w;
Cursor cursor;
XUndefineCursor( display, w)
Display *display;
Window w;

Arguments
cursor

Specifies the cursor that is to be displayed or None.

display

Specifies the connection to the X server.

Specifies the window.

Description
If a cursor is set, it will be used when the pointer is in the window. If the
cursor is None, it is equivalent to XUndefineCursor.
XDefineCursor can generate BadCursor and BadWindow errors.

The XUndefineCursor undoes the effect of a previous
XDefineCursor for this window. When the pointer is in the window, the
parent's cursor will now be used. On the root window, the default cursor is
restored.
XUndefineCursor can generate a BadWindow error.

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadCursor

A value for a Cursor argument does not name a defined
Cursor.

BadWindow

A value for a Window argument does not name a defined
Window.

Subroutines 3-425

XDefineCursor (3X11 )
See Also
XCreateFontCursor(3X 11), XRecolorCursor(3Xll)
Guide to the Xlib Library

3-426 Subroutines

XDestroyWindow (3X11 )
Name
XDestroyWindow, XDestroySubwindows - destroy windows

Syntax
XDestroyWindow(display, w)
Display *display;
Window w;
XDestroySubwindows (display, w)
Display *display;
Window w;

Arguments
display

Specifies the connection to the X server.

Specifies the window.

Description
The XDestroyWindow function destroys the specified window as well as
all of its subwindows and causes the X server to generate a
DestroyNotify event for each window. The window should never be
referenced again. If the window specified by the w argument is mapped, it is
unmapped automatically. The ordering of the DestroyNotify events is
such that for any given window being destroyed, DestroyNotify is
generated on any inferiors of the window before being generated on the
window itself. The ordering among siblings and across subhierarchies is not
otherwise constrained. If the window you specified is a root window, no
windows are destroyed. Destroying a mapped window will generate
Expo s e events on other windows that were obscured by the window being
destroyed.
XDestroyWindow can generate a BadWindow error.

The XDestroySubwindows function destroys all inferior windows of the
specified window, in bottom-to-top stacking order. It causes the X server to
generate a DestroyNotify event for each window. If any mapped
subwindows were actually destroyed, XDestroySubwindows causes the X
server to generate Expose events on the specified window. This is much
more efficient than deletmg many windows one at a time because much of
the work need be performed only once for all of the windows, rather than for
each window. The subwindows should never be referenced again.

Subroutines 3-427

XDestroyWindow{3X11 )
XDestroySubwindows can generate a BadWindow error.

Diagnostics
BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XChangeWindowAttributes(3Xll), XConfigureWindow(3Xll),
XCreateWindow(3Xll), XMapWindow(3Xll), XRaiseWindow(3Xll),
XUnmapWindow(3Xll)
Guide to the Xlib Library

3-428 Subroutines

XDrawArc (3X11 )
Name
XDrawArc, XDrawArcs - draw arcs

Syntax
XDrawArc(display, d, gc, x, y, width, height, angle], angle2)
Display *display;
Drawable d;
GCgc;
int x, y;
unsigned int width, height;
int angle] , angle2;
XDrawArcs(display, d, gc, arcs, narcs)
Display *display;
Drawable d;
GCgc;
XArc *arcs;
int narcs;

Arguments
angle]

Specifies the start of the arc relative to the three-o'clock
position from the center, in units of degrees * 64.

angle2

Specifies the path and extent of the arc relative to the start of
the arc, in units of degrees * 64.

arcs

Specifies a pointer to an array of arcs.

Specifies the drawable.

display

Specifies the connection to the X server.

Specifies the GC.

narcs

Specifies the number of arcs in the array.

width
height

x
y

Specify the width and height, which are the major and minor
axes of the arc.
Specify the x and y coordinates, which are relative to the
origin of the drawable and specify the upper-left corner of the
bounding rectangle.

Subroutines 3-429

XDrawArc (3X11)
Description
XDrawArc draws a single circular or elliptical arc, and XDrawArcs draws
multiple circular or elliptical arcs. Each arc is specified by a rectangle and
two angles. The center of the circle or ellipse is the center of the rectangle,
and the major and minor axes are specified by the width and height. Positive
angles indicate counterclockwise motion, and negative angles indicate
clockwise motion. If the magnitude of angle2 is greater than 360 degrees,
XDrawArc or XDrawArcs truncates it to 360 degrees.

For an arc specified as [x, y, width, height, angle 1, angle 2], the origin of
. andmmor
'
. at [widtli
. fi rute
. Iy th'm
the major
axes IS
x+ -2-' y+ height]
2
,and the m
path describing the entire circle or ellipse intersects the horizontal axis at
'
teh
' al axIS
' at
[x, y+ height]
2
and [x+ WI'dth , y+ height]
2
and mtersects
vertIc
width
width,
,
[x+-- , y] and [x+-- , y+helght], These coordmates can be
2
2
fractional and so are not truncated to discrete coordinates. The path should
be defined by the ideal mathematical path. For a wide line with line-width
lw, the bounding outlines for filling are given by the two infinitely thin paths
consisting of all points whose perpendicular distance from the path of the
circle/ellipse is equal to Iw/2 (which may be a fractional value). The capstyle and join-style are applied the same as for a line corresponding to the
tangent of the circle/ellipse at the endpoint.
For an arc specified as [x, y, width, height, angle 1, angle 2], the angles
must be specified in the effectively skewed coordinate system of the ellipse
(for a circle, the angles and coordinate systems are identical). The
relationship between these angles and angles expressed in the normal
coordinate system of the screen (as measured with a protractor) is as follows:
skewed-angle = atan [tan(nOrmal-angle)*

wi~th 1+ adjust

height

The skewed-angle and normal-angle are expressed in radians (rather than in
degrees scaled by 64) in the range [0, 21t] and where atan returns a value in

~e range [- ~, ~] and adjust is:

for normal-angle in the range [0, ~]

for nonnal-angle in the range [

21t

for normal-angle in the range [ ; , 21t]

3-430 Subroutines

3; 1

XDrawArc (3X11 )
For any given arc, XDrawArc and XDrawArcs do not draw a pixel more
than once. If two arcs join correctly and if the line-width is greater than zero
and the arcs intersect, XDrawArc and XDrawArcs do not draw a pixel
more than once. Otherwise, the intersecting pixels of intersecting arcs are
drawn multiple times. Specifying an arc with one endpoint and a clockwise
extent draws the same pixels as specifying the other endpoint and an
equivalent counterclockwise extent, except as it affects joins.
If the last point in one arc coincides with the first point in the following arc,
the two arcs will join correctly. If the first point in the first arc coincides with
the last point in the last arc, the two arcs will join correctly. By specifying
one axis to be zero, a horizontal or vertical line can be drawn. Angles are
computed based solely on the coordinate system and ignore the aspect ratio.

Both functions use these GC components: function, plane-mask, line-width,
line-style, cap-style, join-style, fill-style, subwindow-mode, clip-x-origin,
clip-y-origin, and clip-mask. They also use these GC mode-dependent
components: foreground, background, tile, stipple, tile-stipple-x-origin, tilestipple-y-origin, dash-offset, and dash-list.
XDrawArc XDrawArcs and can generate BadDrawable, BadGC, and
BadMatch errors.

Diagnostics
BadDrawable

A value for a Drawable argument does not name a defined
Window or Pixmap.
BadGC

A value for a GContext argument does not name a defined
GContext.

BadMatch

An InputOnly window is used as a Drawable.

BadMatch

Some argument or pair of arguments has the correct type and
range but fails to match in some other way required by the
request.

See Also
XDrawLine(3Xll), XDrawPoint(3Xll), XDrawRectangle(3Xll)
Guide to the Xlib Library

Subroutines 3-431

XDrawlmageString (3X11 )
Name
XDrawImageString, XDrawImageString16 - draw image text

Syntax
XDrawImageString( display, d, gc, x, y, string, length)
Display *display;
Drawable d;
GC gc;
int x, y;
char *string;
int length;
XDrawImageString 16( display, d, gc, x, y, string, length)
Display *display;
Drawable d;
GCgc;
int x, y;
XChar2b *string;
int length;

Arguments
d

Specifies the drawable.

display

Specifies the connection to the X server.

Specifies the GC.

length

Specifies the number of characters in the string argument.

string

Specifies the character string.

x
y

Specify the x and y coordinates, which are relative to the
origin of the specified drawable and define the origin of the
first character.

Description
The XDrawlmageString16 function is similar to XDrawlmageString
except that it uses 2-byte or 16-bit characters. Both functions also use both
the foreground and background pixels of the GC in the destination.

3-432 Subroutines

XDrawlmageString (3X11 )
The effect is first to fill a destination rectangle with the background pixel
defined in the GC and then to paint the text with the foreground pixel. The
upper-left corner of the filled rectangle is at:
[x, y - font-ascent]
The width is:
overall-width
The height is:
font-ascent + font-descent
The overall-width, font-ascent, and font-descent are as would be returned by
XQueryTextExtents using gc and string. The function and fill-style
defined in the GC are ignored for these functions. The effective function is
GXcopy, and the effective fill-style is FillSolid.
For fonts defined with 2-byte matrix indexing and used with
XDrawlmageString, each byte is used as a byte2 with a bytel of zero.
Both functions use these GC components: plane-mask, foreground,
background, font, subwindow-mode, clip-x-origin, clip-y-origin, and clipmask.
XDrawlmageString XDrawlmageString16 and can generate
BadDrawable, BadGC, and BadMatch errors.

Diagnostics
BadDrawable
A value for a Drawable argument does not name a defined
Window or Pixmap.
BadGC

A value for a GContext argument does not name a defined
GContext.

BadMatch

An InputOnly window is used as a Drawable.

BadMat ch

Some argument or pair of arguments has the correct type and
range but fails to match in some other way required by the
request.

See Also
XDrawString(3Xll), XDrawText(3Xll)
Guide to the Xlib Library

Subroutines 3-433

XDrawLine (3X11 )
Name
XDrawLine, XDrawLines, XDrawSegments - draw lines and polygons

Syntax
XDrawLine(display, d, ge, xl, yl, x2, y2)
Display *display;
Drawable d;
GC ge;
int xl, yl, x2, y2;
XDrawLines(display, d, ge,points, npoints, mode)
Display *display;
Drawable d;
GCge;
XPoint *points;
int npoints;
int mode;
XDrawSegments(display, d, ge, segments, nsegments)
Display *display;
Drawable d;
GCge;
XSegment *segments;
int nsegments;

Arguments
d

Specifies the drawable.

display

Specifies the connection to the X server.

Specifies the GC.

mode

Specifies the coordinate mode. You can pass
CoordModeOrigin or CoordModePrevious.

npoints

Specifies the number of points in the array.

nsegments

Specifies the number of segments in the array.

points

Specifies a pointer to an array of points.

segments

Specifies a pointer to an array of segments.

xl
yl

3-434 Subroutines

XDrawLine (3X11 )
x2

Specify the points (xl, yl) and (x2, y2) to be connected.

Description
The XDrawLine function uses the components of the specified GC to draw
a line between the specified set of points (xl, yl) and (x2, y2). It does not
perform joining at coincident endpoints. For any given line, XDrawLine
does not draw a pixel more than once. If lines intersect, the intersecting
pixels are drawn multiple times.
The XDrawLines function uses the components of the specified GC to
draw npoints-Ilines between each pair of points (point[i], point[i+l]) in the
array of XPoint structures. It draws the lines in the order listed in the
array. The lines join correctly at all intermediate points, and if the first and
last points coincide, the first and last lines also join correctly. For any given
line, XDrawLines does not draw a pixel more than once. If thin (zero
line-width) lines intersect, the intersecting pixels are drawn multiple times. If
wide lines intersect, the intersecting pixels are drawn only once, as though
the entire PolyLine protocol request were a single, filled shape.
CoordModeOrigin treats all coordinates as relative to the origin, and
CoordModePrevious treats all coordinates after the first as relative to the
previous point.
The XDrawSegrnents function draws multiple, unconnected lines. For each
segment, XDrawSegrnents draws a line between (xl, yl) and (x2, y2). It
draws the lines in the order listed in the array of XSegrnent structures and
does not perform joining at coincident endpoints. For any given line,
XDrawSegrnents does not draw a pixel more than once. If lines intersect,
the intersecting pixels are drawn multiple times.
All three functions use these GC components: function, plane-mask, linewidth, line-style, cap-style, fill-style, subwindow-mode, clip-x-origin, clip-yorigin, and clip-mask. The XDrawLines function also uses the join-style
GC component. All three functions also use these GC mode-dependent
components: foreground, background, tile, stipple, tile-stipple-x-origin, tilestipple-y-origin, dash-offset, and dash-list.
XDrawLine XDrawLines XDrawSegrnents and can generate
BadDrawable, BadGC, and BadMatch errors. XDrawLines can also
generate a BadVal ue error.

Subroutines 3-435

XDrawLine (3X11 )
Diagnostics
BadDrawable
A value for a Drawable argument does not name a defined
Window or Pixmap.
BadGe

A value for a GContext argument does not name a defined
GContext.

BadMatch

An InputOnly window is used as a Drawable.

BadMat ch

Some argument or pair of arguments has the correct type and
range but fails to match in some other way required by the
request.

BadVal ue

See Also
XDrawArc(3Xll), XDrawPoint(3Xll), XDrawRectangle(3Xll)
Guide to the Xlib Library

3-436 Subroutines

XDrawPoint (3X11 )
Name
XDrawPoint, XDrawPoints - draw points

Syntax
XDrawPoint(display, d, ge, x, y)
Display *display;
Drawable d;
GCge;
int x, y;
XDrawPoints(display, d, ge,points, npoints, mode)
Display *display;
Drawable d;
GCge;
XPoint *points;
int npoints;
int mode;

Arguments
d

Specifies the drawable.

display

Specifies the connection to the X server.

Specifies the GC.

mode

Specifies the coordinate mode. You can pass
CoordModeOrigin or CoordModePrevious.

npoints

Specifies the number of points in the array.

points

Specifies a pointer to an array of points.

x
y

Specify the x and y coordinates where you want the point
drawn.

Description
The XDrawPoint function uses the foreground pixel and function
components of the GC to draw a single point into the specified drawable;
XDrawPoints draws multiple points this way. CoordModeOrigin
treats all coordinates as relative to the origin, and CoordModePrevious
treats all coordinates after the first as relative to the previous point.
XDrawPoints draws the points in the order listed in the array.

Subroutines 3-437

XDrawPoint (3X11 )
Both functions use these GC components: function, plane-mask, foreground,
subwindow-mode, clip-x~origin, clip-y-origin, and clip-mask.
XDrawPoint can generate BadDrawable, BadGe, and BadMatch
errors. XDrawPoints can generate BadDrawable, BadGC, BadMatch,
and BadValue errors.

Diagnostics
BadDrawable

A value for a Drawable argument does not name a defined
Window or Pixmap.
BadGC

A value for a GContext argument does not name a defined
GContext.

BadMatch

An InputOnly window is used as a Drawable.

BadMatch

Some argument or pair of arguments has the correct type and
range but fails to match in some other way required by the
request.

BadValue

See Also
XDrawArc(3Xll), XDrawLine(3Xll), XDrawRectangle(3Xll)
Guide to the Xlib Library

3-438 Subroutines

XDrawRectangle (3X11 )
Name
XDrawRectangle, XDrawRectangles - draw rectangles

Syntax
XDrawRectangle(display, d, gc, x, y, width, height)
Display *display;
Drawable d;
GC gc;
int x, y;
unsigned int width, height;
XDrawRectangles(display, d, gc, rectangles, nrectangles)
Display *display;
Drawable d;
GCgc;
XRectangle rectangles[];
int nrectangles;

Arguments
d

Specifies the drawable.

display

Specifies the connection to the X server.

Specifies the GC.

nrectangles

Specifies the number of rectangles in the array.

rectangles

Specifies a pointer to an array of rectangles.

width
height

x
y

Specify the width and height, which specify the dimensions
of the rectangle.
Specify the x and y coordinates, which specify the upper-left
comer of the rectangle.

Description
The XDrawRectangle and XDrawRectangles functions draw the
outlines of the specified rectangle or rectangles as if a five-point PolyLine
protocol request were specified for each rectangle:
[x,y] [x+width,y] [x+width,y+height] [x,y+height] [x,y]

Subroutines 3-439

XDrawRectangle (3X11 )
For the specified rectangle or rectangles, these functions do not draw a pixel
more than once. XDrawRectangles draws the rectangles in the order
listed in the array. If rectangles intersect, the intersecting pixels are drawn
multiple times.
Both functions use these GC components: function, plane-mask, line-width,
line-style, join-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin,
and clip-mask. They also use these GC mode-dependent components:
foreground, background, tile, stipple, tile-stipple-x-origin, tile-stipple-yorigin, dash-offset, and dash-list.
XDrawRectangle XDrawRectangles and can generate
BadDrawable, BadGC, and BadMatch errors.

Diagnostics
BadDrawable

A value for a Drawable argument does not name a defined
Window or Pixmap.
BadGC

A value for a GContext argument does not name a defined
GContext.

BadMatch

An InputOnly window is used as a Drawable.

BadMatch

Some argument or pair of arguments has the correct type and
range but fails to match in some other way required by the
request.

See Also
XDrawArc(3Xl1), XDrawLine(3Xl1), XDrawPoint(3Xll)
Guide to the Xlib Library

3-440 Subroutines

XDrawString (3X11 )
Name
XDrawString, XDrawString 16 - draw text characters

Syntax
XDrawString(display, d, gc, x, y, string, length)
Display *display;
Drawable d;
GC gc;
int x, y;
char *string;
int length;
XDrawString16(display, d, gc, x, y, string, length)
Display *display;
Drawable d;
GC gc;
int x, y;
XChar2b *string;
int length;

Arguments
d

Specifies the drawable.

display

Specifies the connection to the X server.

Specifies the GC.

length

Specifies the number of characters in the string argument.

string

Specifies the character string.

Specify the x and y coordinates, which are relative to the
origin of the specified drawable and define the origin of the
first character.

Description
Each character image, as defined by the font in the GC, is treated as an
additional mask for a fill operation on the drawable. The drawable is
modified only where the font character has a bit set to 1. For fonts defined
with 2-byte matrix indexing and used with XDrawString16, each byte is
used as a byte2 with a byte 1 of zero.

Subroutines 3-441

XDrawString (3X11 )
Both functions use these GC components: function, plane-mask, fill-style,
font, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. They also
use these GC mode-dependent components: foreground, background, tile,
stipple, tile-stipple-x-origin, and tile-stipple-y-origin.
XDrawString XDrawString16 and can generate BadDrawable,
BadGC, and BadMa t ch errors.

Diagnostics
BadDrawable

A value for a Drawable argument does not name a defined
Window or Pixmap.
BadGC

A value for a GContext argument does not name a defined
GContext.

BadMatch

An InputOnly window is used as a Drawable.

BadMatch

Some argument or pair of arguments has the correct type and
range but fails to match in some other way required by the
request.

See Also
XDrawImageString(3Xll), XDrawText(3Xll)
Guide to the Xlib Library

3-442 Subroutines

XDrawText (3X11 )
Name
XDrawText, XDrawText16 - draw polytext text

Syntax
XDrawText(display, d, ge, x, y, items, nitems)
Display *display;
Drawable d;
GCge;
int x, y;
XTextItem *items;
int nitems;
XDrawText16(display, d, ge, x, y, items, nitems)
Display *display;
Drawable d;
GC ge;
int x, y;
XTextItem16 *items;
int nitems;

Arguments
d

Specifies the drawable.

display
ge

Specifies the connection to the X server.

items

Specifies a pointer to an array of text items.

nitems

Specifies the number of text items in the array.

Specifies the GC.

x
y

Specify the x and y coordinates, which are relative to the
origin of the specified drawable and define the origin of the
first character.

Description
The XDrawText16 function is similar to XDrawText except that it uses
2-byte or 16-bit characters. Both functions allow complex spacing and font
shifts between counted strings.

Subroutines 3-443

XDrawText (3X11 )
Each text item is processed in turn. A font member other than None in an
item causes the font to be stored in the GC and used for subsequent text. A
text element delta specifies an additional change in the position along the x
axis before the string is drawn. The delta is always added to the character
origin and is not dependent on any characteristics of the font. Each character
image, as defined by the font in the GC, is treated as an additional mask for a
fill operation on the drawable. The drawable is modified only where the font
character has a bit set to 1. If a text item generates a BadFont error, the
previous text items may have been drawn.
For fonts defined with linear indexing rather than 2-byte matrix indexing,
each XChar2b structure is interpreted as a 16-bit number with byte1 as the
most-significant byte.
Both functions use these GC components: function, plane-mask, fill-style,
font, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. They also
use these GC mode-dependent components: foreground, background, tile,
stipple, tile-stipple-x-origin, and tile-stipple-y-origin.
XDrawText XDrawText16 and can generate BadDrawable, BadFont,
BadGC, and BadMa t ch errors.

Diagnostics
BadDrawable

A value for a Drawable argument does not name a defined
Window or Pixmap.
BadFont

A value for a Font or GContext argument does not name a
defined Font.

BadGC

A value for a GContext argument does not name a defined
GContext.

BadMatch

An InputOnly window is used as a Drawable.

See Also
XDrawImageString(3X11), XDrawString(3X11)
Guide to the Xlib Library

3-444 Subroutines

XEmptyRegion {3X11 }
Name
XEmptyRegion, XEqualRegion, XPointInRegion, XRectInRegion detennine if regions are empty or equal

Syntax
Bool XEmptyRegion(r)
Region r;
Bool XEqualRegion (r1 , r2)
Region rl, r2;
Bool XPointInRegion (r , x, y)
Region r;
int x, y;
int XRectInRegion(r, x, y, width, height)
Region r;
int x, y;
unsigned int width, height;

Arguments
r

Specifies the region.

rl
r2

Specify the two regions.

width
height

Specify the width and height, which define the rectangle.

x
y

Specify the x and y coordinates, which define the point or the
coordinates of the upper-left corner of the rectangle.

Description
The XEmptyRegion function returns True if the region is empty.
The XEqualRegion function returns True if the two regions have the
same offset, size, and shape.
The XPointInRegion function returns True if the point (x, y) is
contained in the region r.

Subroutines 3-445

XEmptyRegion (3X11 )
The XRectInRegion function returns RectangleIn if the rectangle is
entirely in the specified region, RectangleOut if the rectangle is entirely
out of the specified region, and RectanglePart if the rectangle is
partially in the specified region.

See Also
XCreateRegion(3Xll), XIntersectRegion(3Xll)
Guide to the Xlib Library

3-446 Subroutines

XFillRectangle (3X11)
Name
XFillRectangle, XFillRectangles, XFillPolygon, XFillArc, XFillArcs - fill
rectangles, polygons, or arcs

Syntax
XFillRectangle(display, d, gc, x, y, width, height)
Display *display;
Drawable d;
GCgc;
int x, y;
unsigned int width, height;
XFillRectangles(display, d, gc, rectangles, nrectangles)
Display *display;
Drawable d;
GCgc;
XRectangle *rectangles;
int nrectangles;
XFillPolygon (display, d, gc, points, npoints, shape, mode)
Display *display;
Drawabled;
GCgc;
XPoint *points;
int npoints;
int shape;
int mode;

XFillArc(display, d, gc, x, y, width, height, angle1, angle2)
Display *display;
Drawable d;
GCgc;
int x, y;
unsigned int width, height;
int angle1, angle2;
XFillArcs(display, d, gc, arcs, narcs)
Display *display;
Drawable d;
GCgc;
XArc *arcs;
int narcs;

Subroutines 3-447

XFiliRectangle (3X11 )
Arguments
angle]

Specifies the start of the arc relative to the tbree-o' clock
position from the center, in units of degrees * 64.

angle2

Specifies the path and extent of the arc relative to the start of
the arc, in units of degrees * 64.

arcs

Specifies a pointer to an array of arcs.

Specifies the drawable.

display

Specifies. the connection to the X server.

Specifies the GC.

mode

Specifies the coordinate mode. You can pass
CoordModeOrigin or CoordModePrevious.

narcs

Specifies the number of arcs in the array.

npoints

Specifies the number of points in the array.

nrectangles

Specifies the number of rectangles in the array.

points

Specifies a pointer to an array of points.

rectangles

Specifies a pointer to an array of rectangles.

shape

Specifies a shape that helps the server to improve
performance. You can pass Complex, Convex, or
Nonconvex.

width
height

Specify the width and height, which are the dimensions of
the rectangle to be filled or the major and minor axes of the
arc.

Specify the x and y coordinates, which are relative to the
origin of the drawable and specify the upper-left comer of the
rectangle.

Description
The XFillRectangle and XFillRectangles functions fill the
specified rectangle or rectangles as if a four-point FillPolygon protocol
request were specified for each rectangle:
[x,y] [x+width,y] [x+width,y+height] [x,y+height]

3-448 Subroutines

XFiliRectangle (3X11 )
Each function uses the x and y coordinates, width and height dimensions, and
GC you specify.
XFillRectangles fills the rectangles in the order listed in the array. For
any given rectangle, XFillRectangle and XFillRectangles do not
draw a pixel more than once. If rectangles intersect, the intersecting pixels
are drawn multiple times.

Both functions use these GC components: function, plane-mask, fill-style,
subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. They also use
these GC mode-dependent components: foreground, background, tile, stipple,
tile-stipple-x-origin, and tile-stipple-y-origin.
XFillRectangle XFillRectangles and can generate
BadDrawable, BadGC, and BadMatch errors.
XFillPolygon fills the region closed by the specified path. The path is
closed automatically if the last point in the list does not coincide with the
first point. XFillPolygon does not draw a pixel of the region more than
once. CoordModeOrigin treats all coordinates as relative to the origin,
and CoordModePrevious treats all coordinates after the first as relative to
the previous point.

Depending on the specified shape, the following occurs:
•

If shape is Complex, the path may self-intersect.

•

If shape is Convex, the path is wholly convex. If known by the client,
specifying Convex can improve performance. If you specify Convex
for a path that is not convex, the graphics results are undefined.

•

If shape is Nonconvex, the path does not self-intersect, but the shape
is not wholly convex. If known by the client, specifying Nonconvex
instead of Complex may improve performance. If you specify
Nonconvex for a self-intersecting path, the graphics results are
undefined.

The fill-rule of the GC controls the filling behavior of self-intersecting
polygons.
This function uses these GC components: function, plane-mask, fill-style,
fill-rule, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It also
uses these GC mode-dependent components: foreground, background, tile,
stipple, tile-stipple-x-origin, and tile-stipple-y-origin.
XFillPolygon can generate BadDrawable, BadGC, BadMatch, and
BadValue errors.

Subroutines 3-449

XFiliRectangle (3X11 )
For each arc, XFillArc or XFillArcs fills the region closed by the
infinitely thin path described by the specified arc and, depending on the arcmode specified in the GC, one or two line segments. For ArcChord, the
single line segment joining the endpoints of the arc is used. For
ArcP ieSlice, the two line segments joining the endpoints of the arc with
the center point are used. XF i lIAr c s fills the arcs in the order listed in the
array. For any given arc, XFillArc and XFillArcs do not draw a pixel
more than once. IT regions intersect, the intersecting pixels are drawn
multiple times.
Both functions use these GC components: function, plane-mask, fill-style,
arc-mode, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
They also use these GC mode-dependent components: foreground,
background, tile, stipple, tile-stipple-x-origin, and tile-stipple-y-origin.
XFillArc XFillArcs and can generate BadDrawable, BadGC, and
BadMatch errors.

Diagnostics
BadDrawable

A value for a Drawable argument does not name a defined
Window or Pixmap.
BadGC

A value for a GContext argument does not name a defined
GContext.

BadMatch

An InputOnly window is used as a Drawable.

BadMatch

Some argument or pair of arguments has the correct type and
range but fails to match in some other way required by the
request.

BadValue

See Also
XDrawArc(3Xll), XDrawRectangle(3Xll)
Guide to the Xlib Library

3-450 Subroutines

XFlush (3X11 )
Name
XFlush, XSync, XEventsQueued, XPending - handle the output buffer or
event queue

Syntax
XFlush (display)
Display *display;
XSync (display, discard)
Display *display;
Bool discard;
int XEventsQueued(display, mode)
Display *display;
int mode;
int XPending( display)
Display *display;

Arguments
discard

Specifies a Boolean value that indicates whether XSync
discards all events on the event queue.

display

Specifies the connection to the X server.

mode

Specifies the mode. You can pass QueuedAlready,
QueuedAfterFlush, or QueuedAfterReading.

Description
The XFlush function flushes the output buffer. Most client applications
need not use this function because the output buffer is automatically flushed
as needed by calls to XPending, XNextEvent, and XWindowEvent.
Events generated by the server may be enqueued into the library's event
queue.
The XSync function flushes the output buffer and then waits until all
requests have been received and processed by the X server. Any errors
generated must be handled by the error handler. For each error event
received by Xlib, XSync calls the client application's error handling routine
(see section 8.12.2). Any events generated by the server are enqueued into
the library's event queue.

Subroutines 3-451

XFlush (3X11)
Finally, if you passed False, XSync does not discard the events in the
queue. If you passed True, XSync discards all events in the queue,
including those events that were on the queue before XSync was called.
Client applications seldom need to call XSync.
If mode is QueuedAlready, XEventsQueued returns the number of
events already in the event queue (and never performs a system call). If
mode is QueuedAfterFlush, XEventsQueued returns the number of
events already in the queue if the number is nonzero. If there are no events
in the queue, XEventsQueued flushes the output buffer, attempts to read
more events out of the application's connection, and returns the number read.
If mode is QueuedAfterReading, XEventsQueued returns the number
of events already in the queue if the number is nonzero. If there are no events
in the queue, XEventsQueued attempts to read more events out of the
application's connection without flushing the output buffer and returns the
number read.

XEvent sQueued 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
XQLength function.

The XPending function returns the number of events that have been
received from the X server but have not been removed from the event queue.
XPending is identical to XEventsQueued with the mode
QueuedAfterF 1 ush specified.

See Also
XIfEvent(3Xll), XNextEvent(3Xll), XPutBackEvent(3Xll)
Guide to the Xlib Library

3-452 Subroutines

XFree (3X11)
Name
XFree, XNoOp - free client data

Syntax
XFree( data)
char *data;

XNoOp(display)
Display *display;

Arguments
display

Specifies the connection to the X server.

data

Specifies a pointer to the data that is to be freed.

Description
The XFree function is a general-purpose Xlib routine that frees the specified
data. You must use it to free any objects that were allocated by Xlib.
The XNoOp function sends a NoOperation protocol request to the X
server, thereby exercising the connection.

See Also
Guide to the Xlib Library

Subroutines 3-453

XGetDefault (3X11 )
Name
XGetDefault, XResourceManagerString - get X program defaults

Syntax
char *XGetDefault(display, program, option)
Display *display;
char *program;
char *option;
char *XResourceManagerString( display)
Display *display;

Arguments
display

Specifies the connection to the X server.

option

Specifies the option name.

program

Specifies the program name for the Xlib defaults (usually
argv[O] of the main program).

Description
The XGetDefaul t function returns the value NULL if the option name
specified in this argument does not exist for the program. The strings
returned by XGetDefault are owned by Xlib and should not be modified
or freed by the client.
The XResourceManagerString returns the RESOURCE_MANAGER
property from the server's root window of screen zero, which was returned
when the connection was opened using XOpenDisplay.

See Also
XrmGetSearchList(3Xll)
Guide to the Xlib Library

3-454 Subroutines

XGetVisualinfo (3X11 )
Name
XGetVisualInfo, XMatchVisualInfo, XVisualIDFromVisual- obtain visual
information

Syntax
XVisualInfo *XGetVisuallnfo( display, vinfo_mask, vinfo_template,
nitems return)
DlSplay *display;
long vinfo mask;
XVisualInfo *vinfo template;
int *nitems_return;Status XMatchVisualInfo(display, screen, depth, class, vinfo return)
Display *display;
int screen;
int depth;
int class;
XVisuallnfo *vinfo_return;
VisualID XVisualIDFromVisual ( visual)
Visual *visual;

Arguments
class

Specifies the class of the screen.

depth

Specifies the depth of the screen.

display

Specifies the connection to the X server.

nitems return Returns the number of matching visual structures.
screen

Specifies the screen.

visual

Specifies the visual type.

vinfo mask

Specifies the visual mask value.

vinfo return

Returns the matched visual information.

vinfo_template Specifies the visual attributes that are to be used in matching
the visual structures.

Subroutines 3-455

XGetVisualinfo (3X11 )
Description
The XGetVisuallnfo function returns a list of visual structures that
match the attributes specified by vinfo_template. If no visual structures
match the template using the specified vinfo_mask, XGetVisuallnfo
returns a NULL. To free the data returned by this function, use XFree.
The XMatchVisuallnfo function returns the visual information for a
visual that matches the specified depth and class for a screen. Because
multiple visuals that match the specified depth and class can exist, the exact
visual chosen is undefined. If a visual is found, XMatchVisuallnfo
returns nonzero and the information on the visual to vinfo_return. Otherwise,
when a visual is not found, XMatchVisuallnfo returns zero.
The XVisualIDFrornVisual function returns the visual ID for the
specified visual type.

See Also
Guide to the Xlib Library

3-456 Subroutines

XGetWindowAttributes (3X11 )
Name
XGetWindowAttributes, XGetGeometry - get current window attribute or
geometry

Syntax
Status XGetWindowAttributes(display, w, window attributes return)
Display *display;
-Window w;
XWindowAttributes *window_attributes_return;
Status XGetGeometry( display, d, root_return, x_return, y_return,
width_return, height_return, border_width_return, depth_return)
Display *display;
Drawable d;
Window *root return;
int *x return, *y return;
unsigtled int *width_return, *height_return;
unsigned int *border_width_return;
unsigned int *depth_return;

Arguments
border width return
- Returns the border width in pixels.
d

Specifies the drawable, which can be a window or a pixmap.

depth_return

Returns the depth of the drawable (bits per pixel for the
object).

display

Specifies the connection to the X server.

root return

Returns the root window.

Specifies the window whose current attributes you want to
obtain.

width return
height return

Return the drawable's dimensions (width and height).

window attributes return
Returns the specified window's attributes in the
XWindowAttributes structure.
x return
y return

Return the x and y coordinates that define the location of the
Subroutines 3-457

XGetWindowAttributes (3X11 )
drawable. For a window, these coordinates specify the
upper-left outer comer relative to its parent's origin. For
pixmaps, these coordinates are always zero.

Description
The XGetWindowAttributes function returns the current attributes for
the specified window to an XWindowAttributes structure.
XGetWindowAttributes can generate BadDrawable and
BadWindow errors.

The XGetGeometry function returns the root window and the current
geometry of the drawable. The geometry of the drawable includes the x and
y coordinates, width and height, border width, and depth. These are
described in the argument list. It is legal to pass to this function a window
whose class is InputOnly.

Diagnostics
BadDrawable
A value for a Drawable argument does not name a defined
Window or Pixmap.
BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XQueryPointer(3Xll), XQueryTree(3Xll)
Guide to the Xlib Library

3-458 Subroutines

XGetWindowProperty (3X11 )
Name
XGetWindowProperty, XListProperties, XChangeProperty,
XRotateWindowProperties, XDeleteProperty - obtain and change window
properties

Syntax
int XGetWindowProperty(display, w, property, long_offset, long_length,
delete, req_type, actual_type_return, actualJormat_return, nitems_return,
bytes_after_return, prop_return)
Display *display;
Window w;
Atom property;
long long_offset, long_length;
Bool delete;
Atom req type;
Atom *actual_type_return;
int *actualJormat_return;
unsigned long *nitems return;
unsigned long *bytes_after_return;
unsigned char **prop_return;
Atom *XListProperties (display, w, numyrop_return)
Display *display;
Window w;
int *numyrop_return;

XChangeProperty(display, w, property, type ,format, mode, data,
nelements)
Display *display;
Window w;
Atom property, type;
intformat;
int mode;
unsigned char *data;
int nelements;
XRotateWindowProperties(display, w, properties, numyrop, npositions)
Display *display;
Window w;
Atom properties [] ;
int numyrop;
int npositions;

Subroutines 3-459

XGetWindowProperty (3X11 )
XDeleteProperty( display, w, property)
Display *display;
Windoww;
Atom property;

Arguments
actualJormat_return
Returns the actual fonnat of the property.
actual type return
Returns the atom identifier that defines the actual type of the
property.
bytes after return
Returns the number of bytes remaining to be read in the
property if a partial read was perfonned.
data

Specifies the property data.

delete

Specifies a Boolean value that detennines whether the
property is deleted.

display

Specifies the connection to the X server.

format

Specifies whether the data should be viewed as a list of 8-bit,
16-bit, or 32-bit quantities. Possible values are 8, 16, and
32. This infonnation allows the X server to correctly
perfonn byte-swap operations as necessary. If the fonnat is
16-bit or 32-bit, you must explicitly cast your data pointer to
a (char *) in the call to XChangeProperty.

long_length

Specifies the length in 32-bit multiples of the data to be
retrieved.

long_offset

Specifies the offset in the specified property (in 32-bit
quantities) where the data is to be retrieved.

mode

Specifies the mode of the operation. You can pass
PropModeReplace,PropModePrepend,or
P ropModeAppend.

nelements

Specifies the number of elements of the specified data
fonnat.

nitems return Returns the actual number of 8-bit, 16-bit, or 32-bit items
stored in the prop_return data.
numyrop

3-460 Subroutines

Specifies the length of the properties array.

XGetWindowProperty (3X11 )
num yrop_return
Returns the length of the properties array.
npositions

Specifies the rotation amount.

prop_return

Returns a pointer to the data in the specified format.

property

Specifies the property name.

properties

Specifies the array of properties that are to be rotated.

req_type

Specifies the atom identifier associated with the property type
or AnyPropertyType.

type

Specifies the type of the property. The X server does not
interpret the type but simply passes it back to an application
that later calls XGetWindowProperty.

Specifies the window whose property you want to obtain,
change, rotate or delete.

Description
The XGetWindowProperty function returns the actual type of the
property; the actual format of the property; the number of 8-bit, 16-bit, or
32-bit items transferred; the number of bytes remaining to be read in the
property; and a pointer to the data actually returned.
XGetWindowProperty sets the return arguments as follows:
•

If the specified property does not exist for the specified window,
XGetWindowProperty returns None to actual_type_return and the
value zero to actual_form at_return and bytes_after_return. The
nitems_return argument is empty. In this case, the delete argument is
ignored.

•

If the specified property exists but its type does not match the specified
type, XGetWindowProperty returns the actual property type to
actual_type_return, the actual property format (never zero) to
actual_format_return, and the property length in bytes (even if the
actual_format_return is 16 or 32) to bytes_after_return. It also ignores
the delete-argument. The nitems_return argument is empty.

•

If the specified property exists and either you assign
AnyPropertyType to the req_type argument or the specified type
matches the actual property type, XGetWindowProperty returns the
actual property type to actual_type_return and the actual property
format (never zero) to actual_form at_return. It also returns a value to
bytes_after_return and nitems_return, by defining the following values:

Subroutines 3-461

XGetWindowProperty (3X11)
N = actual length of the stored property in bytes
(even if the format is 16 or 32)
1=4 * long_offset
T=N -I
L = MINIMUM(T, 4 * long_length)
A = N - (I + L)
The returned value starts at byte index I in the property (indexing from
zero), and its length in bytes is L. If the value for long_offset causes L
to be negative, a BadValue error results. The value of
bytes_after_return is A, giving the number of trailing unread bytes in
the stored property.
XGetWindowProperty always allocates one extra byte in prop_return
(even if the property is zero length) and sets it to ASCII null so that simple
properties consisting of characters do not have to be copied into yet another
string before use. If delete is True and bytes_after_return is zero,
XGetWindowProperty deletes the property from the window and
generates a PropertyNotify event on the window.

The function returns Success if it executes successfully. To free the
resulting data, use XFree.
XGetWindowProperty can generate BadAtom, BadValue, and
BadWindow errors.

The XListProperties function returns a pointer to an array of atom
properties that are defined for the specified window or returns NULL if no
properties were found. To free the memory allocated by this function, use
XFree.
XListProperties can generate a BadWindow error.

The XChangeProperty function alters the property for the specified
window and causes the X server to generate a PropertyNotify event on
that window. XChangeProperty performs the following:

•

If mode is PropModeReplace, XChangeProperty discards the
previous property value and stores the new data.

•

If mode is P ropModeP repend or P ropModeAppend,
XChangeProperty inserts the specified data before the beginning of
the existing data or onto the end of the existing data, tespectively. The
type and format must match the existing property value, or a
BadMatch error results. If the property is undefined, it is treated as
defined with the correct type and format with zero-length data.

3-462 Subroutines

XGetWindowProperty (3X11 )
The lifetime of a property is not tied to the storing client. Properties remain
until explicitly deleted, until the window is destroyed, or until the server
resets. For a discussion of what happens when the connection to the X server
is closed, see section 2.5. The maximum size of a property is server
dependent and can vary dynamically depending on the amount of memory
the server has available. (If there is insufficient space, a BadAlloc error
results.)

XChangeProperty can generate BadAlloc, BadAtom, BadMatch,
BadVal ue, and BadWindow errors.
The XRotateWindowProperties function allows you to rotate
properties on a window and causes the X server to generate
P rope rt yN ot i fy events. If the property names in the properties array are
viewed as being numbered starting from zero and if there are num_prop
property names in the list, then the value associated with property name 1
becomes the value associated with property name (I + npositions) mod N for
all 1 from zero to N - 1. The effect is to rotate the states by npositions places
around the virtual ring of property names (right for positive npositions, left
for negative npositions). If npositions mod N is nonzero, the X server
generates a PropertyNotify event for each property in the order that
they are listed in the array. If an atom occurs more than once in the list or
no property with that name is defined for the window, a BadMatch error
results. If a BadAtorn or BadMatch error results, no properties are
changed.

XRotateWindowProperties can generate BadAtorn, BadMatch, and
BadWindow errors.
The XDeleteProperty function deletes the specified property only if the
property was defined on the specified window and causes the X server to
generate a PropertyNotify event on the window unless the property
does not exist.

XDeleteProperty can generate BadAtorn and BadWindow errors.

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadAtorn

A value for an Atom argument does not name a defined
Atom.

BadValue

Some numeric value falls outside the range of values
accepted by the request. Unless a specific range is specified

Subroutines 3-463

XGetWindowProperty (3X11 )
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.
BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XInternAtom(3Xll)
Guide to the Xlib Library

3-464 Subroutines

XGrabButton (3X11 )
Name
XGrabButton, XUngrabButton - grab pointer buttons

Syntax
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;
Boolowner events;
unsigned intevent_mask;
int pointer_mode, keyboard_mode;
Window confine to;
Cursor cursor; XUngrabButton( display, button, modifiers, grab_window)
Display *display;
unsigned int button;
unsigned int modifiers;
Window grab_window;

Arguments
button

Specifies the pointer button that is to be grabbed or released
or AnyButton.

confine to

Specifies the window to confine the pointer in or None.

cursor

Specifies the cursor that is to be displayed or None.

display

Specifies the connection to the X server.

event mask

Specifies which pointer events are reported to the client. The
mask is the bitwise inclusive OR of the valid pointer event
mask bits.

grab_window

Specifies the grab window.

keyboard mode
Specifies further processing of keyboard events. You can
pass GrabModeSync or GrabModeAsync.
modifiers

Specifies the set of keymasks or AnyModifier. The mask
is the bitwise inclusive OR of the valid keymask bits.

Subroutines 3-465

XGrabButton (3X11 )
owner events

Specifies a Boolean value that indicates whether the pointer
events are to be reported as usual or reported with respect to
the grab window if selected by the event mask.

pointer mode Specifies further processing of pointer events. You can pass
GrabModeSync or GrabModeAsync.

Description
The XGrabButton function establishes a passive grab. In the future, the
pointer is actively grabbed (as for XGrabPointer), the last-pointer-grab
time is set to the time at which the button was pressed (as transmitted in the
ButtonPress event), and the ButtonPress event is reported if all of
the following conditions are true:
•

The pointer is not grabbed, and the specified button is logically pressed
when the specified modifier keys are logically down, and no other
buttons or modifier keys are logically down.

•

The grab_window contains the pointer.

•

The confine_to window (if any) is viewable.

•

A passive grab on the same button/key combination does not exist on
any ancestor of grab_window.

The interpretation of the remaining arguments is as for XGrabPointer.
The active grab is terminated automatically when the logical state of the
pointer has all buttons released (independent of the state of the logical
modifier keys).
Note that the logical state of a device (as seen by client applications) may lag
the physical state if device event processing is frozen.
This request overrides all previous grabs by the same client on the same
buttonlkey combinations on the same window. A modifiers of
AnyModifier is equivalent to issuing the grab request for all possible
modifier combinations (including the combination of no modifiers). It is not
required that all modifiers specified have currently assigned KeyCodes. A
button of AnyButton is equivalent to issuing the request for all possible
buttons. Otherwise, it is not required that the specified button currently be
assigned to a physical button.

If some other client has already issued a XGrabButton with the same
button/key combination on the same window, a BadAccess error results.
When using AnyModifier or AnyButton, the request fails completely,
and a BadAccess error results (no grabs are established) if there is a
conflicting grab for any combination. XGrabButton has no effect on an

3-466 Subroutines

XGrabButton (3X11 )
active grab.
XGrabButton can generate BadCursor, BadValue, and BadWindow

errors.
The XUngrabButton function releases the passive button!key combination
on the specified window if it was grabbed by this client. A modifiers of
AnyModifier is equivalent to issuing 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.
XUngrabButton has no effect on an active grab.
XUngrabButton can generate BadValue and BadWindow errors.

Diagnostics
BadCursor

A value for a Cursor argument does not name a defined
Cursor.

BadVal ue

BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XAllowEvents(3XIl), XGrabPointer(3Xll), XGrabKey(3Xll),
XGrabKeyboard(3Xll),
Guide to the Xlib Library

Subroutines 3-467

XGrabKey (3X11 )
Name
XGrabKey, XUngrabKey - grab keyboard keys

Syntax
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;
XUngrabKey(display, keycode, modifiers, grab window)
Display *display;
int keycode;
unsigned int modifiers;
Window grab_window;

Arguments
display

Specifies the connection to the X server.

grab_window

Specifies the grab window.

keyboard mode
Specifies further processing of keyboard events. You can
pass GrabModeSync or GrabModeAsync.
keycode

Specifies the KeyCode or AnyKey.

modifiers

Specifies the set of keymasks or AnyModifier. The mask
is the bitwise inclusive OR of the valid keymask bits.

owner events

Specifies a Boolean value that indicates whether the pointer
events are to be reported as usual or reported with respect to
the grab window if selected by the event mask.

pointer_mode

Specifies further processing of pointer events. You can pass
GrabModeSync or GrabModeAsync.

3-468 Subroutines

XGrabKey (3X11 )
Description
The XGrabKey function establishes a passive grab on the keyboard. In the
future, the keyboard is actively grabbed (as for XGrabKeyboard), the lastkeyboard-grab time is set to the time at which the key was pressed (as
transmitted in the KeyPress event), and the KeyPress event is reported if
all of the following conditions are true:
•

The keyboard is not grabbed and the specified key (which can itself be
a modifier key) is logically pressed when the specified modifier keys
are logically down, and no other modifier keys are logically down.

•

Either the grab_window is an ancestor of (or is) the focus window, or
the grab_window is a descendant of the focus window and contains the
pointer.

•

A passive grab on the same key combination does not exist on any
ancestor of grab_window.

The interpretation of the remaining arguments is as for XGrabKeyboard.
The active grab is terminated automatically when the logical state of the
keyboard has the specified key released (independent of the logical state of
the modifier keys).
Note that the logical state of a device (as seen by client applications) may lag
the physical state if device event processing is frozen.
A modifiers argument of AnyModifier is equivalent to issuing the request
for all possible modifier combinations (including the combination of no
modifiers). It is not required that all modifiers specified have currently
assigned KeyCodes. A keycode argument of AnyKey is equivalent to
issuing the request for all possible KeyCodes. Otherwise, the specified
keycode must be in the range specified by minJceycode and max_keycode in
the connection setup, or a BadVal ue error results.
If some other client has issued a XGrabKey with the same key combination
on the same window, a BadAccess error results. When using
AnyModifier or AnyKey, the request fails completely, and a
BadAccess error results (no grabs are established) if there is a conflicting
grab for any combination.
XGrabKey can generate BadAccess, BadValue, and BadWindow

errors.
The XUngrabKey function releases the key combination on the specified
window if it was grabbed by this client. It has no effect on an active grab.
A modifiers of AnyModifier is equivalent to issuing the request for all
possible modifier combinations (including the combination of no modifiers).

Subroutines 3-469

XGrabKey (3X11 )
A keycode argument of AnyKey is equivalent to issuing the request for all
possible key codes.
XUngrabKey can generate BadValue and BadWindow error.

Diagnostics
BadAccess

A client attempted to grab a key/button combination already
grabbed by another client.

BadVal ue

BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XAllowAccess(3Xll), XGrabButton(3Xll), XGrabKeyboard(3Xll),
XGrabPointer(3Xll )
Guide to the Xlib Library

3-470 Subroutines

XGrabKeyboard (3X11 )
Name
XGrabKeyboard, XUngrabKeyboard - grab the keyboard

Syntax
int XGrabKeyboard( display, grab_window, owner_events, pointer_mode,
keyboard_mode, time)
Display *display;
Window grab window;
Bool owner events;
int pointer mode, keyboard mode;
Time time;
XUngrabKeyboard( display, time)
Display *display;
Time time;

Arguments
display

Specifies the connection to the X server.

grab window

Specifies the grab window.

keyboard mode
Specifies further processing of keyboard events. You can
pass GrabModeSync or GrabModeAsync.
owner events

Specifies a Boolean value that indicates whether the pointer
events are to be reported as usual or reported with respect to
the grab window if selected by the event mask.

pointer mode

Specifies further processing of pointer events. You can pass
GrabModeSync or GrabModeAsync.

time

Specifies the time. You can pass either a timestamp or
Current Time.

Description
The XGrabKeyboard function actively grabs control of the keyboard and
generates Focusln and FocusOut events. Further key events are reported
only to the grabbing client. XGrabKeyboard overrides any active
keyboard grab by this client. If owner_events is False, all generated key
events are reported with respect to grab_window. If owner_events is True
and if a generated key event would normally be reported to this client, it is
reported normally; otherwise, the event is reported with respect to the
Subroutines 3-471

XGrabKeyboard (3X11 )
grab_window. Both KeyPress and KeyRelease events are always
reported, independent of any event selection made by the client.
If the keyboard_mode argument is GrabModeAsync, keyboard event
processing continues as usual. If the keyboard is currently frozen by this
client, then processing of keyboard events is resumed. If the keyboard_mode
argument is GrabModeSync, the state of the keyboard (as seen by client
applications) appears to freeze, and the X server generates no further
keyboard events until the grabbing client issues a releasing XAllowEvents
call or until the keyboard grab is released. Actual keyboard changes are not
lost while the keyboard is frozen; they are simply queued in the server for
later processing.
If pointer_mode is Gr abModeAsync, pointer event processing is unaffected
by activation of the grab. If pointer_mode is GrabModeSync, the state of
the pointer (as seen by client applications) appears to freeze, and the X server
generates no further pointer events until the grabbing client issues a releasing
XAllowEvents call or until the keyboard grab is released. Actual pointer
changes are not lost while the pointer is frozen; they are simply queued in the
server for later processing.
If the keyboard is actively grabbed by some other client, XGrabKeyboard
fails and returns AlreadyGrabbed. If grab_window is not viewable, it
fails and returns GrabNotViewable. If the keyboard is frozen by an
active grab of another client, it fails and returns GrabFrozen. If the
specified time is earlier than the last-keyboard-grab time or later than the
current X server time, it fails and returns GrabInvalidTime. Otherwise,
the last-keyboard-grab time is set to the specified time (Current Time is
replaced by the current X server time).
XGrabKeyboard can generate BadVal ue and BadWindow errors.

The XUngrabKeyboard function releases the keyboard and any queued
events if this client has it actively grabbed from either XGrabKeyboard or
XGrabKey. XUngrabKeyboard does not release the keyboard and any
queued events if the specified time is earlier than the last-keyboard-grab time
or is later than the current X server time. It also generates FocusIn and
FocusOut events. The X server automatically performs an
UngrabKeyboard request if the event window for an active keyboard grab
becomes not viewable.

3-472 Subroutines

XGrabKeyboard (3X11 )
Diagnostics
BadValue

BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XAllowEvents(3Xll), XGrabButton(3Xll), XGrabKey(3Xll),
XGrabPointer(3Xll)
Guide to the Xlib Library

Subroutines 3-473

XGrabPointer (3X11 )
Name
XGrabPointer, XUngrabPointer, XChangeActivePointerGrab - grab the
pointer

Syntax
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 intevent_mask;
int pointer_mode, keyboard_mode;
Window confine to;
Cursor cursor; Time time;
XUngrabPointer( display, time)
Display *display;
Time time;
XChangeActivePointerGrab(display, event_mask, cursor, time)
Display *display;
unsigned int event_mask;
Cursor cursor;
Time time;

Arguments
confine_to
cursor

Specifies the window to confine the pointer in or None.
Specifies the cursor that is to be displayed during the grab or
None.

display

Specifies the connection to the X server.

event mask

Specifies which pointer events are reported to the client. The
mask is the bitwise inclusive OR of the valid pointer event
mask bits.

grab window

Specifies the grab window.

keyboard mode
Specifies further processing of keyboard events. You can
pass GrabModeSync or GrabModeAsync.

3-474 Subroutines

XGrabPointer (3X11 )
owner events

Specifies a Boolean value that indicates whether the pointer
events are to be reported as usual or reported with respect to
the grab window if selected by the event mask.

pointer mode Specifies further processing of pointer events. You can pass
GrabModeSync or GrabModeAsync.
time

Specifies the time. You can pass either a timestamp or
CurrentTime.

Description
The XGrabPointer function actively grabs control of the pointer and
returns GrabSuccess if the grab was successful. Further pointer events
are reported only to the grabbing client. XGrabPointer overrides any
active pointer grab by this client. If owner_events is False, all generated
pointer events are reported with respect to grab_window and are reported
only if selected by event_mask. If owner_events is True and if a generated
pointer event would normally be reported to this client, it is reported as
usual. Otherwise, the event is reported with respect to the grab_window and
is reported only if selected by event_mask. For either value of owner_events,
unreported events are discarded.
If the pointer_mode is GrabModeAsync, pointer event processing continues
as usual. If the pointer is currently frozen by this client, the processing of
events for the pointer is resumed. If the pointer_mode is GrabModeSync,
the state of the pointer, as seen by client applications, appears to freeze, and
the X server generates no further pointer events until the grabbing client calls
XAllowEvents or until the pointer grab is released. Actual pointer
changes are not lost while the pointer is frozen; they are simply queued in the
server for later processing.
If the keyboard_mode is GrabModeAsync, keyboard event processing is
unaffected by activation of the grab. If the keyboard_mode is
GrabModeSync, the state of the keyboard, as seen by client applications,
appears to freeze, and the X server generates no further keyboard events until
the grabbing client calls XAllowEvents or until the pointer grab is
released. Actual keyboard changes are not lost while the pointer is frozen;
they are simply queued in the server for later processing.
If a cursor is specified, it is displayed regardless of what window the pointer
is in. If None is specified, the normal cursor for that window is displayed
when the pointer is in grab_window or one of its subwindows; otherwise, the
cursor for grab_window is displayed.

Subroutines 3-475

XGrabPointer (3X11 )
If a confine_to window is specified, the pointer is restricted to stay contained
in that window. The confine_to window need have no relationship to the
grab_window. If the pointer is not initially in the confine_to window, it is
warped automatically to the closest edge just before the grab activates and
enterlIe ave events are generated as usual. If the confine_to window is
subsequently reconfigured, the pointer is warped automatically, as necessary,
to keep it contained in the window.

The time argument allows you to avoid certain circumstances that come up if
applications take a long time to respond or if there are long network delays.
Consider a situation where you have two applications, both of which
normally grab the pointer when clicked on. If both applications specify the
timestamp from the event, the second application may wake up faster and
successfully grab the pointer before the first application. The first application
then will get an indication that the other application grabbed the pointer
before its request was processed.
XGrabPointer generates EnterNotify and LeaveNotify events.

Either if grab_window or confine_to window is not viewable or if the
confine_to window lies completely outside the boundaries of the root
window, XGrabPointer fails and returns GrabNotViewable. If the
pointer is actively grabbed by some other client, it fails and returns
AlreadyGrabbed. If the pointer is frozen by an active grab of another
client, it fails and returns GrabFrozen. If the specified time is earlier than
the last-pointer-grab time or later than the current X server time, it fails and
returns GrabInvalidTime. Otherwise, the last-pointer-grab time is set to
the specified time (CurrentTime is replaced by the current X server time).
XGrabPointer can generate BadCursor, BadValue, and BadWindow
errors.

The XUngrabPointer function releases the pointer and any queued events
if this client has actively grabbed the pointer from XGrabPointer,
XGrabButton, or from a normal button press. XUngrabPointer does
not release the pointer if the specified time is earlier than the last-pointer-grab
time or is later than the current X server time. It also generates
EnterNotify and LeaveNotify events. The X server performs an
UngrabPointer request automatically if the event window or confine_to
window for an active pointer grab becomes not viewable or if window
reconfiguration causes the confine_to window to lie completely outside the
boundaries of the root window.
The XChangeActi vePointerGrab function changes the specified
dynamic parameters if the pointer is actively grabbed by the client and if the
specified time is no earlier than the last-pointer-grab time and no later than
3-476 Subroutines

XGrabPointer (3X11 )
the current X server time. This function has no effect on the passive
parameters of a XGrab Button. The interpretation of event_mask and
cursor is the same as described in XGrabPointer.
XChangeActivePointerGrab can generate a BadCursor and
BadVal ue error.

Diagnostics
BadCursor

A value for a Cursor argument does not name a defined
Cursor.

BadValue

BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XAllowEvents(3Xll), XGrabButton(3Xll), XGrabKey(3Xll),
XGrabKeyboard(3Xll)
Guide to the Xlib Library

Subroutines 3-477

XGrabServer (3X11)
Name
XGrabServer, XUngrabServer - grab the server

Syntax
XGrabServer( display)
Display *display;
XUngrabServer( display)
Display *display;

Arguments
display

Specifies the connection to the X server.

Description
The XGrabServer function disables processing of requests and close
downs on all other connections than the one this request arrived on. You
should not grab the X server any more than is absolutely necessary.
The XUngrabServer function restarts processing of requests and close
downs on other connections. You should avoid grabbing the X server as
much as possible.

See Also
XGrabButton(3Xll), XGrabKey(3Xll), XGrabKeyboard(3Xll),
XGrabPointer(3Xl1)
Guide to the Xlib Library

3-478 Subroutines

XlfEvent (3X11 )
Name
XIfEvent, XCheckIfEvent, XPeekIfEvent - check the event queue with a
predicate procedure

Syntax
XIfEvent(display, event return, predicate, arg)
Display *display; XEvent *event return;
Bool (*predicate) 0;
char *arg;
Bool XCheckIfEvent(display, event return, predicate, arg)
Display *display;
XEvent *event return;
Bool (*predicate)O;
char *arg;
XPeekIfEvent(display, event return, predicate, arg)
Display *display;
XEvent *event return;
Bool (*predicate)();
char *arg;

Arguments
arg

Specifies the user-supplied argument that will be passed to
the predicate procedure.

display

Specifies the connection to the X server.

event return

Returns either a copy of or the matched event's associated
structure.

predicate

Specifies the procedure that is to be called to determine if the
next event in the queue matches what you want.

Description
The XI fEvent function completes only when the specified predicate
procedure returns True for an event, which indicates an event in the queue
matches. XI fEvent flushes the output buffer if it blocks waiting for
additional events. XI fEvent removes the matching event from the queue
and copies the structure into the client-supplied XEvent structure.

Subroutines 3-479

XlfEvent (3X11 )
When the predicate procedure finds a match, XChecklfEvent copies the
matched event into the client-supplied XEvent structure and returns True.
(This event is removed from the queue.) If the predicate procedure finds no
match, XChecklfEvent returns False, and the output buffer will have
been flushed. All earlier events stored in the queue are not discarded.
The XPeeklfEvent function returns only when the specified predicate
procedure returns True for an event. After the predicate procedure finds a
match, XPeeklfEvent copies the matched event into the client-supplied
XEven t structure without removing the event from the queue.
XPeeklfEvent flushes the output buffer if it blocks waiting for additional
events.

See Also
XPutBackEvent(3Xll) XNextEvent(3Xll), XSendEvent(3Xll)
Guide to the Xlib Library

3-480 Subroutines

XlnstaliColormap (3X11 )
Name
XInstallColonnap, XUninstallColonnap, XListInstalledColonnaps - control
colonnaps

Syntax
XInstallColonnap (display, colormap)
Display *display;
Colonnap colormap;
XUninstallColonnap (display, colormap)
Display *display;
Colonnap colormap;
Colormap *XListInstalledColonnaps (display, w, num_return)
Display *display;
Window w;
int *num_return;

Arguments
colormap

Specifies the colormap.

display

Specifies the connection to the X server.

num return

Returns the number of currently installed colormaps.

Specifies the window that detennines the screen.

Description
The XlnstallColormap function installs the specified colormap for its
associated screen. All windows associated with this colonnap immediately
display with true colors. You associated the windows with this colonnap
when you created them by calling XCreateWindow,
XCreateSimpleWindow,XChangeWindowAttributes,or
XSetWindowColormap.
If the specified colormap is not already an installed colormap, the X server
generates a ColormapNotify event on each window that has that
colonnap. In addition, for every other colonnap that is installed as a result of
a call to XlnstallColormap, the X server generates a
ColormapNotify event on each window that has that colonnap.

Subroutines 3-481

XlnstaliColormap (3X11 )
XlnstallColormap can generate a BadColor error.

The XUninstallColormap function removes the specified colormap from
the required list for its screen. As a result, the specified colormap might be
uninstalled, and the X server might implicitly install or uninstall additional
colormaps. Which colormaps get installed or uninstalled is server·dependent
except that the required list must remain installed.
If the specified colormap becomes uninstalled, the X server generates a
ColormapNoti fy event on each window that has that colormap. In
addition, for every other colormap that is installed or uninstalled as a result
of a call to XUninstallColormap, the X server generates a
ColormapNotify event on each window that has that colormap.
XUninstallColormap can generate a BadColor error.

The XListlnstalledColormaps function returns a list of the currently
installed colormaps for the screen of the specified window. The order of the
colormaps in the list is not significant and is no explicit indication of the
required list. When the allocated list is no longer needed, free it by using
XFree.
XListlnstalledColormaps can generate a BadWindow error.

Diagnostics
BadColor

A value for a Colormap argument does not name a defined
Colormap.

BadWindow

A value for a Window argument does not name a defined
Window.

See Also
Guide to the Xlib Library

3-482 Subroutines

XlnternAtom (3X11 )
Name
XInternAtom, XGetAtomName - create or return atom names

Syntax
Atom XInternAtom(display, atom_name, only_if_exists)
Display *display;
char *atom name;
Bool only_if_exists;
char *XGetAtomName(display, atom)
Display *display;
Atom atom;

Arguments
atom

Specifies the atom for the property name you want returned.

atom name

Specifies the name associated with the atom you want
returned.

display

Specifies the connection to the X server.

only if exists

Specifies a Boolean value that indicates whether
XlnternAtom creates the atom.

Description
The XI nt e rnAt om function returns the atom identifier associated with the
specified atom_name string. If only_if_exists is False, the atom is created
if it does not exist. Therefore, XlnternAtom can return None. You
should use a null-terminated ISO Latin-l string for atom_name. Case
matters; the strings thing, Thing, and thinG all designate different atoms. The
atom will remain defined even after the client's connection closes. It will
become undefined only when the last connection to the X server closes.
XlnternAtom can generate BadAlloc and BadValue errors.

The XGetAtomName function returns the name associated with the specified
atom. To free the resulting string, call XFree.
XGetAtomName can generate a BadAtom error.

Subroutines 3-483

XlnternAtom (3X11 )
Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadAtom

A value for an Atom argument does not name a defined
Atom.

BadValue

See Also
XGetWindowProperty(3Xll)
Guide to the Xlib Library

3-484 Subroutines

XlntersectRegion (3X11 )
Name
XIntersectRegion, XUnionRegion, XUnionRectWithRegion,
XSubtractRegion, XXorRegion, XOffsetRegion, XShrinkRegion - region
arithmetic utilities

Syntax
XIntersectRegion(sra, srb, dr_return)
Region sra, srb, dr_return;
XUnionRegion(sra, srb, dr return)
Region sra, srb, dr_return;
XUnionRectWithRegion(rectangle, src_region, dest_region_return)
XRectangle *rectangle;
Region src region;
Region dest_region_return;
XSubtractRegion(sra, srb, dr_return)
Region sra, srb, dr_return;
XXorRegion(sra, srb, dr_return)
Region sra, srb, dr_return;
XOffsetRegion (r, dx, dy)
Region r;
int dx, dy;
XShrinkRegion (r, dx, dy)
Region r;
int dx, dy;

Arguments
dest region return
Returns the destination region.
dr return

Returns the result of the computation. ds Dy move or shrink

dx
dy

Specify the x and y coordinates, which define the amount
you want to the specified region.

Specifies the region.

rectangle

Specifies the rectangle.

sra

Subroutines 3-485

XlntersectRegion (3X11 )
srb

Specify the two regions with which you want to petform the
computation.
Specifies the source region to be used.

Description
The XIntersectRegion function computes the intersection of two
regions.
The XUnionRegion function computes the union of two regions.
The XUnionRectWithRegion function updates the destination region
from a union of the specified rectangle and the specified source region.
The XSubtractRegion function subtracts srb from sra and stores the
results in dr_return.
The XXorRegion function calculates the difference between the union and
intersection of two regions.
The XOffsetRegion function moves the specified region by a specified
amount.
The XShrinkRegion function reduces the specified region by a specified
amount. Positive values shrink the size of the region, and negative values
expand the region.

See Also
XCreateRegion(3Xll), XEmptyRegion(3Xll),
Guide to the Xlib Library

3-486 Subroutines

XListFonts (3X11 )
Name
XListFonts, XFreeFontNames, XListFontsWithInfo, XFreeFontInfo - obtain
or free font names and information

Syntax
char **XListFonts(display, pattern, maxnames, actual_count_return)
Display *display;
char *pattern;
int maxnames;
int *actual_count_return;
XFreeFontNames( list)
char *list [] ;
char **XListFontsWithInfo(display, pattern, maxnames, count return,
~~rn)

Display *display;
char *pattern;
int maxnames;
int *count return;
XFontStruct **info return;
XFreeFontInfo(names, free info, actual count)
char **names;
XFontStruct *free info;
int actual_count; -

Arguments
actual count

Specifies the actual number of matched font names returned
by XListFontsWithlnfo.

actual count return
- Returns the actual number of font names.
count return

Returns the actual number of matched font names.

display

Specifies the connection to the X server.

info return

Returns a pointer to the font information.

free info

Specifies the pointer to the font information returned by
XListFontsWithlnfo.

list

Specifies the array of strings you want to free.

Subroutines 3-487

XListFonts (3X11 )
maxnames

Specifies the maximum number of names to be returned.

names

Specifies the list of font names returned by
XListFontsWi thInfo.

pattern

Specifies the null-terminated pattern string that can contain
wildcard characters.

Description
The XListFonts function returns an array of available font names (as
controlled by the font search path; see XSetFontPath) that match the
string you passed to the pattern argument. The string should be ISO Latin-I;
uppercase and lowercase do not matter. Each string is terminated by an
ASCII null. The pattern string can contain any characters, but each asterisk
(*) is a wildcard for any number of characters, and each question mark (?) is
a wildcard for a single character. The client should call XFreeFontNames
when finished with the result to free the memory.
The XFreeFontNames function frees the array and strings returned by
XListFonts or XListFontsWi thInfo.
The XLi stF on t sWi thInf 0 function returns a list of font names that
match the specified pattern and their associated font information. The list of
names is limited to size specified by maxnames. The information returned
for each font is identical to what XLoadQueryFont would return except
that the per-character metrics are not returned. The pattern string can contain
any characters, but each asterisk (*) is a wildcard for any number of
characters, and each question mark (?) is a wildcard for a single character.
To free the allocated name array, the client should call XFreeFontNames.
To free the the font information array, the client should call
XFreeFont Info.
The XFreeFontInfo function frees the the font information array.

See Also
XLoadFont(3Xll), XSetFontPath(3Xll)
Guide to the Xlib Library

3-488 Subroutines

XLoadFont (3X11 )
Name
XLoadFont, XQueryFont, XLoadQueryFont, XFreeFont, XGetFontProperty,
XUnloadFont - load or unload fonts

Syntax
Font XLoadFont(display, name)
Display *display;
char *name;
XFontStruct *XQueryFont(display,font ID)
Display *display;
XIDfont ID;
XFontStruct *XLoadQueryFont(display, name)
Display *display;
char *name;
XFreeFont( display, font struct)
Display *display; XFontStruct *font struct;
Bool XGetFontProperty (font_struct, atom, value_return)
XFontStruct *font struct;
Atom atom;
unsigned long *value_return;
XUnloadFont( display, font)
Display *display;
Font font;

Arguments
atom

Specifies the atom for the property name you want returned.

display

Specifies the connection to the X server.

font

Specifies the font.

font ID

Specifies the font ID or the GContext ID.

font struct

Specifies the storage associated with the font.

Specifies the Ge.

name

Specifies the name of the font, which is a null-terminated
string.

value return

Returns the value of the font property.
Subroutines 3-489

XLoadFont{3X11 )
Description
The XLoadFont function loads the specified font and returns its associated
font ID. The name should be ISO Latin-l encoding; uppercase and
lowercase do not matter. If XLoadFont was unsuccessful at loading the
specified font, a BadName error results. Fonts are not associated with a
particular screen and can be stored as a component of any GC. When the
font is no longer needed, call XUnloadFont.
XLoadFont can generate BadAlloc and BadName errors.

The XQueryFont function returns a pointer to the XFontStruct
structure, which contains information associated with the font. You can
query a font or the font stored in a GC. The font ID stored in the
XFontStruct structure will be the GContext ID, and you need to be
careful when using this ID in other functions (see XGContextFromGC).
To free this data, use XFreeFontlnfo.
XLoadQueryFont can generate a BadAlloc error.

The XLoadQueryFont function provides the most common way for
accessing a font. XLoadQueryFont both opens (loads) the specified font
and returns a pointer to the appropriate XFontStruct structure. If the font
does not exist, XLoadQueryFont returns NULL.
The XFreeFont function deletes the association between the font resource
ID and the specified font and frees the XFontStruct structure. The font
itself will be freed when no other resource references it. The data and the
font should not be referenced again.
XFreeFont can generate a BadFont error.

Given the atom for that property, the XGetFontProperty function returns
the value of the specified font property. XGetFontProperty also returns
F al s e if the property was not defined or True if it was defined. A set of
predefined atoms exists for font properties, which can be found in
<Xll /Xatom. h>. This set contains the standard properties associated with
a font. Although it is not guaranteed, it is likely that the predefined font
properties will be present.
The XUnloadFont function deletes the association between the font
resource ID and the specified font. The font itself will be freed when no
other resource references it. The font should not be referenced again.
XUnloadFont can generate a BadFont error.

3-490 Subroutines

XLoadFont (3X11 )
Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadFont

A value for a Font or GContext argument does not name a
defined Font.

BadName

A font or color of the specified name does not exist.

See Also
XListFonts(3Xll), XSetFontPath(3Xll)
Guide to the Xlib Library

Subroutines 3-491

XLookupKeysym (3X11 )
Name
XLookupKeysym, XRefreshKeyboardMapping, XLookupString,
XRebindKeySym - handle keyboard input events

Syntax
KeySym XLookupKeysym( key_event, index)
XK.eyEvent *key_event;
int index;
XRefreshKeyboardMapping( event_map)
~appingEvent*event_Inap;

int XLookupString( event_struct, buffer_return, bytes_buffer, keysYIn_return,
status in out)
XKeyEvent *event_struct;
char *buffer return;
int bytes buffer;
KeySym-*keysym return;
XComposeStatus "* status_in_out;
XRebindKeysym(display, keysym, list, mod_count, string, bytes_string)
Display *display;
KeySym keysYIn;
KeySym list [] ;
int Inod count;
unsigned char *string;
int bytes_string;

Arguments
buffer_return

Returns the translated characters.

bytes_buffer

Specifies the length of the buffer. No more than bytes_buffer
of translation are returned.

bytes_string

Specifies the length of the string.

display

Specifies the connection to the X server.

event_map

Specifies the mapping event that is to be used.

event struct

Specifies the key event structure to be used. You can pass
XKeyPressedEvent or XKeyReleasedEvent.

index

Specifies the index into the KeySyms list for the event's
KeyCode.

3-492 Subroutines

XLookupKeysym (3X11 )
key_event

Specifies the KeyPress or KeyRelease event.

keysym

Specifies the KeySym that is to be tested.

keysym_return Returns the KeySym computed from the event if this
argument is not NULL.
list

Specifies the KeySyms to be used as modifiers.

mod count

Specifies the number of modifiers in the modifier list.

status in out

Specifies or returns the XComposeStatus structure or
NULL.

string

Specifies a pointer to the string that is copied and will be
returned by XLookupString.

Description
The XLookupKeysym function uses a given keyboard event and the index
you specified to return the KeySym from the list that corresponds to the
KeyCode member in the XKeyPressedEvent or XKeyReleasedEvent
structure. If no KeySym is defined for the KeyCode of the event,
XLookupKeysym returns NoSymbol.
The XRefreshKeyboardMapping function refreshes the stored modifier
and keymap information. You usually call this function when a
MappingNot i fy event with a request member of MappingKeyboard or
MappingModifier occurs. The result is to update Xlib's knowledge of
the keyboard.
The XLookupString function is a convenience routine that maps a key
event to an ISO Latin-l string, using the modifier bits in the key event to
deal with shift, lock, and control. It returns the translated string into the
user's buffer. It also detects any rebound KeySyms (see XRebindKeysym)
and returns the specified bytes. XLookupString returns the length of the
string stored in the tag buffer. If the lock modifier has the caps lock KeySym
associated with it, XLookupString interprets the lock modifier to perform
caps lock processing.
If present (non-NULL), the XComposeStatus structure records the state,
which is private to Xlib, that needs preservation across calls to
XLookupSt ring to implement compose processing.

The XRebindKeysym function can be used to rebind the meaning of a
KeySym for the client. It does not redefine any key in the X server but
merely provides an easy way for long strings to be attached to keys.
XLookupString returns this string when the appropriate set of modifier
keys are pressed and when the KeySym would have been used for the
Subroutines 3-493

XLookupKeysym (3X11 )
translation. Note that you can rebind a KeySym that may not exist.

See Also
XStringToKeysym(3Xll)
Guide to the Xlib Library

3-494 Subroutines

XMapWindow (3X11 )
Name
XMapWindow, XMapRaised, XMapSubwindows - map windows

Syntax
XMapWindow ( display, w)
Display *display;
Window w;
XMapRaised(display, w)
Display *display;
Windoww;
XMapSubwindows (display, w)
Display *display;
Window w;

Arguments
display

Specifies the connection to the X server.

Specifies the window.

Description
The XMapWindow function maps the window and all of its subwindows that
have had map requests. Mapping a window that has an unmapped ancestor
does not display the window but marks it as eligible for display when the
ancestor becomes mapped. Such a window is called unviewable. When all
its ancestors are mapped, the window becomes viewable and will be visible
on the screen if it is not obscured by another window. This function has no
effect if the window is already mapped.
If the override-redirect of the window is False and if some other client has
selected SubstructureRedirectMask on the parent window, then the
X server generates a MapRequest event, and the XMapWindow function
does not map the window. Otherwise, the window is mapped, and the X
server generates a MapNotify event.
If the window becomes viewable and no earlier contents for it are
remembered, the X server tiles the window with its background. If the
window's background is undefined, the existing screen contents are not
altered, and the X server generates zero or more Expose events. If
backing-store was maintained while the window was unmapped, no Expose
events are generated. If backing-store will now be maintained, a full-window

Subroutines 3-495

XMapWindow{3X11 }
exposure is always generated. Otherwise, only visible regions may be
reported. Similar tiling and exposure take place for any newly viewable
inferiors.
If the window is an InputOutput window, XMapWindow generates
Expose events on each InputOutput window that it causes to be
displayed. If the client maps and paints the window and if the client begins
processing events, the window is painted twice. To avoid this, first ask for
Expose events and then map the window, so the client processes input
events as usual. The event list will include Expose for each window that
has appeared on the screen. The client's normal response to an Expose
event should be to repaint the window. This method usually leads to simpler
programs and to proper interaction with window managers.
XMapWindow can generate a BadWindow error.

The XMapRaised function essentially is similar to XMapWindow in that it
maps the window and all of its subwindows that have had map requests.
However, it also raises the specified window to the top of the stack.
XMapRai sed can generate a BadWindow error.

The XMapSubwindows function maps all subwindows for a specified
window in top-to-bottom stacking order. The X server generates Expose
events on each newly displayed window. This may be much more efficient
than mapping many windows one at a time because the server needs to
perform much of the work only once, for all of the windows, rather than for
each window.
XMapSubwindows can generate a BadWindow error.

Diagnostics
BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XChangeWindowAttributes(3Xll), XConfigureWindow(3Xll),
XCreateWindow(3Xll), XDestroyWindow(3Xll), XRaiseWindow(3Xll),
XUnmapWindow(3Xll)
Guide to the Xlib Library

3-496 Subroutines

XNextEvent (3X11 )
Name
NextEvent, XPeekEvent, XWindowEvent, XCheckWindowEvent,
XMaskEvent, XCheckMaskEvent, XCheckTypedEvent,
XCheckTypedWindowEvent - select events by type

Syntax
XNextEvent(display, event_return)
Display *display;
XEvent *event_return;
XPeekEvent(display, event_return)
Display *display;
XEvent *event_return;
XWindowEvent(display, w, event_mask, event_return)
Display *display;
Window w;
long event_mask;
XEvent *event_return;
Bool XCheckWindowEvent(display, w, event_mask, event_return)
Display *display;
Window w;
long event mask;
XEvent *event_return;

XMaskEvent(display, event_mask, event_return)
Display *display;
long event mask;
XEvent *event_return;
Bool XCheckMaskEvent( display, event_mask, event_return)
Display *display;
long event mask;
XEvent *event_return;
Bool XCheckTypedEvent( display, event_type, event_return)
Display *display;
int event_type;
XEvent *event_return;
Bool XCheckTypedWindowEvent(display, w, event_type, event_return)
Display *display;
Windoww;

Subroutines 3-497

XNextEvent (3X11 )
int event type;
XEvent *event_return;

Arguments
display

Specifies the connection to the X server.

event mask

Specifies the event mask.

event return

Returns the matched event's associated structure.

event return

Returns the next event in the queue.

event return

Returns a copy of the matched event's associated structure.

event_type

Specifies the event type to be compared.

Specifies the window whose event uou are interested in.

Description
The XNextEvent function copies the first event from the event queue into
the specified XEvent structure and then removes it from the queue. If the
event queue is empty, XNextEvent flushes the output buffer and blocks
until an event is received.
The XPeekEvent function returns the first event from the event queue, but
it does not remove the event from the queue. If the queue is empty,
XPeekEvent flushes the output buffer and blocks until an event is received.
It then copies the event into the client-supplied XEvent structure without
removing it from the event queue.
The XWindowEvent function searches the event queue for an event that
matches both the specified window and event mask. When it finds a match,
XWindowEvent removes that event from the queue and copies it into the
specified XEvent structure. The other events stored in the queue are not
discarded. If a matching event is not in the queue, XWindowEvent flushes
the output buffer and blocks until one is received.
The XCheckWindowEvent function searches the event queue and then the
events available on the server connection for the first event that matches the
specified window and event mask. If it finds a match,
XCheckWindowEvent removes that event, copies it into the specified
XEvent structure, and returns True. The other events stored in the queue
are not discarded. If the event you requested is not available,
XCheckWindowEvent returns False, and the output buffer will have
been flushed.

3~498 Subroutines

XNextEvent (3X11 )
The XMaskEvent function searches the event queue for the events
associated with the specified mask. When it finds a match, XMaskEvent
removes that event and copies it into the specified XEvent structure. The
other events stored in the queue are not discarded. If the event you requested
is not in the queue, XMaskEvent flushes the output buffer and blocks until
one is. received.
The XCheckMaskEvent function searches the event queue and then any
events available on the server connection for the first event that matches the
specified mask. If it finds a match, XCheckMaskEvent removes that
event, copies it into the specified XEvent structure, and returns True. The
other events stored in the queue are not discarded. If the event you requested
is not available, XCheckMaskEvent returns False, and the output buffer
will have been flushed.
The XCheckTypedEvent function searches the event queue and then any
events available on the server connection for the first event that matches the
specified type. If it finds a match, XCheckTypedEvent removes that
event, copies it into the specified XEvent structure, and returns True. The
other events in the queue are not discarded. If the event is not available,
XCheckTypedEvent returns False, and the output buffer will have been
flushed.
The XCheckTypedWindowEvent function searches the event queue and
then any events available on the server connection for the first event that
matches the specified type and window. If it finds a match,
XCheckTypedWindowEvent removes the event from the queue, copies it
into the specified XEvent structure, and returns True. The other events in
the queue are not discarded. If the event is not available,
XCheckTypedWindowEvent returns False, and the output buffer will
have been flushed.

See Also
XIfEvent(3Xll), XPutBackEvent(3Xll), XSendEvent(3Xll)
Guide to the Xlib Library

Subroutines 3-499

XOpenDisplay (3X11 )
Name
XOpenDisplay, XCloseDisplay - connect or disconnect to X server

Syntax
Display *XOpenDisplay(display_name)
char *display_name;

XCloseDisplay(display)
Display *display;

Arguments
display

Specifies the connection to the X server.

display_name

Specifies the hardware display name, which detennines the
display and communications domain to be used. On a
UNIX-based system, if the display_name is NULL, it
defaults to the value of the DISPLAY environment variable.

Description
The XOpenDisplay function returns a Display structure that serves as
the connection to the X server and that contains all the infonnation about that
X server. XOpenDisplay connects your application to the X server
through TCP, UNIX domain, or DECnet communications protocols. If the
hostname is a host machine name and a single ·colon (:) separates the
hostname and display number, XOpenDisplay connects using TCP
streams. If the hostname is unix and a single colon (:) separates it from the
display number, XOpenDisplay connects using UNIX domain IPC
streams. If the hostname is not specified, Xlib uses whatever it believes is
the fastest transport. If the hostname is a host machine name and a double
colon (::) separates the hostname and display number, XOpenDisplay
connects using DECnet. A single X server can support any or all of these
transport mechanisms simultaneously. A particular Xlib implementation can
support many more of these transport mechanisms.

If successful, XOpenDisplay returns a pointer to a Display structure,
which is defined in <Xl1/Xlib. h>. If XOpenDisplay does not succeed,
it returns NULL. After a successful call to XOpenDisplay, all of the
screens in the display can be used by the client. The screen number specified
in the display_name argument is returned by the DefaultScreen macro
(or the XDefaultScreen function). You can access elements of the
Display and Screen structures only by using the infonnation macros or
3-500 Subroutines

XOpenDisplay (3X11 )
functions. For information about using macros and functions to obtain
information from the Display structure, see section 2.2.1.
The XCloseDisplay function closes the connection to the X server for the
display specified in the Display structure and destroys all windows,
resource IDs (Window, Font, Pixmap, Colormap, Cursor, and
GContext), or other resources that the client has created on this display,
unless the close-down mode of the resource has been changed (see
XSetCloseDownMode). Therefore, these windows, resource IDs, and
other resources should never be referenced again or an error will be
generated. Before exiting, you should call XCloseDisplay explicitly so
that any pending errors are reported as XCloseDisplay performs a final
XSync operation.
XCloseDisplay can generate a BadGC error.

See Also
Guide to the Xlib Library

Subroutines 3-501

XParseGeometry (3X11 )
Name
XParseGeometry, XGeometry, XParseColor - parse window geometry and
color

Syntax
int XParseGeometry (parse string , x_return, y_return, width_return,
height return)
char *parsestring;
int *x return, *y return;
int *width_return-' *height_return;
int XGeometry( display, screen, position, defaultyosition, bwidth, fwidth,
fheight, xadder, yadder, x_return, y_return, width_return, height_return)
Display *display;
int screen;
char *position, *defaultyosition;
unsigned int bwidth;
unsigned int fwidth ,fheight;
int xadder, yadder;
int *x return, *y return;
int *width_return-' *height_return;
Status XParseColor( display, colormap, spec, exact_def_return)
Display *display;
Colormap colormap;
char *spec;
XColor *exact_def_return;

Arguments
bwidth

Specifies the border width.

colormap

Specifies the colormap.

position
defaultyosition
Specify the geometry specifications.

display

Specifies the connection to the X server.

exact de! return
- Returns the exact color value for later use and sets the
DoRed, DoGreen, and DoBl ue flags.
fheight
3-502 Subroutines

XParseGeometry (3X11 )
Specify the font height and width in pixels (increment size).
[width
Specifies the string you want to parse.
parsestring
screen
Specifies the screen.
Specifies the color name string; case is ignored.
spec
width return
height-.return Return the width and height determined.
xadder
yadder
Specify additional interior padding needed in the window.
x return
y return
Return the x and y offsets.

Description
By convention, X applications use a standard string to indicate window size
and placement. XParseGeometry makes it easier to conform to this
standard because it allows you to parse the standard window geometry.
Specifically, this function lets you parse strings of the form:

[=][<width>x<height>][{ +-}<xoffset>{+-}<yoffset>]
The items in this form map into the arguments associated with this function.
(Items enclosed in <> are integers, items in [] are optional, and items
enclosed in { } indicate "choose one of". Note that the brackets should not
appear in the actual string.)
The XParseGeometry function returns a bitmask that indicates which of
the four values (width, height, xoffset, and yoffset) were actually found in the
string and whether the x and y values are negative. By convention, -0 is not
equal to +0, because the user needs to be able to say "position the window
relative to the right or bottom edge." For each value found, the
.
corresponding argument is updated. For each value not found, the argument
is left unchanged. The bits are represented by XValue, YValue,
WidthValue, HeightValue, XNegative, or YNegative and are
defined in <Xll/Xutil. h>. They will be set whenever one of the values
is defined or one of the signs is set.
If the function returns either the XVal ue or YVal ue flag, you should place
the window at the requested position.
You pass in the border width (bwidth), size of the increments fwidth and
fueight (typically font width and height), and any additional interior space
(xadder and yadder) to make it easy to compute the resulting size. The
XGeometry function returns the position the window should be placed

Subroutines 3-503

XParseGeometry (3X11 )
given a position and a default position. XGeometry determines the
placement of a window using a geometry specification as specified by
XParseGeometry and the additional information about the window.
Given a fully qualified default geometry specification and an incomplete
geometry specification, XParseGeometry returns a bitmask value as
defined above in the XParseGeometry call, by using the position
argument.
The returned width and height will be the width and height specified by
default_position as overridden by any user-specified position. They are not
affected by fwidth, theight, xadder, or yadder. The x and y coordinates are
computed by using the border width, the screen width and height, padding as
specified by xadder and yadder, and the theight and fwidth times the width
and height from the geometry specifications.
The XParseColor function provides a simple way to create a standard user
interface to color. 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 that are suitable for a subsequent call to
XAllocColor or XStoreColor. The color can be specified either as a
color name (as in XAllocNamedColor) or as an initial sharp sign
character followed by a numeric specification, in one of the following
formats:
#RGB
#RRGGBB
#RRRGGGBBB
#RRRRGGGGBBBB

(4 bits each)
(8 bits each)
(12 bits each)
(16 bits each)

The R, G, and B represent single hexadecimal digits (both uppercase and
lowercase). When fewer than 16 bits each are specified, they represent the
most-significant bits of the value. For example, #3a7 is the same as
#3000a0007000. The colormap is used only to determine which screen to
look up the color on. For example, you can use the screen's default
colormap.
If the initial character is a sharp sign but the string otherwise fails to fit the
above formats or if the initial character is not a sharp sign and the named
color does not exist in the server's database, XParseColor fails and
returns zero.
XParseColor can generate a BadColor error.

3-504 Subroutines

XParseGeometry (3X11 )
Diagnostics
BadColor

A value for a Colormap argument does not name a defined
Colormap.

See Also
Guide to the Xlib Library

Subroutines 3-505

XPolygonRegion (3X11 )
Name
XPolygonRegion, XClipBox - generate regions

Syntax
Region XPolygonRegion (points, n, fill rule)
XPoint points!];
int n;
int fill_rule;
XClipBox (r, reet return)
Region r;
XRectangle *reet_return;

Arguments
fill_rule

Specifies the fill-rule you want to set for the specified GC.
You can pass EvenOddRule or WindingRule.

Specifies the number of points in the polygon.

points

Specifies an array of points.

Specifies the region.

reet return

Returns· the smallest enclosing rectangle.

Description
The XPolygonRegion function returns a region for the polygon defined by
the points array. For an explanation of fill_rule, see XCreateGC.
The XClipBox function returns the smallest rectangle enclosing the
specified region.

See Also
Guide to the Xlib Library

3-506 Subroutines

XPutBackEvent (3X11 )
Name
XPutBackEvent - put events back on the queue

Syntax
XPutBackEvent(display, event)
Display *display;
XEvent *event;

Arguments
display

Specifies the connection to the X server.

event

Specifies a pointer to the event.

Description
The XPutBackEvent function pushes an event back onto the head of the
display's event queue by copying the event into the queue. This can be
useful if you read an event and then decide that you would rather deal with it
later. There is no limit to the number of times in succession that you can call
XPutBackEvent.

See Also
XIfEvent(3Xll), XNextEvent(3Xll), XSendEvent(3Xll)
Guide to the Xlib Library

Subroutines 3--507

XPutlmage (3X11 )
Name
XPutImage, XGetImage, XGetSublmage - transfer images

Syntax
XPutlmage(display, d, gc, image, src_x, srcy, dest~, desty, width,
height)
Display *display;
Drawable d;
GCgc;
XImage *image;
int src_x, srcy;
int dest_x, desty;
unsigned int width, height;
XImage *XGetImage(display, d, x, y, width, height, plane_mask,format)
Display *display;
Drawable d;
int x, y;
unsigned int width, height;
long plane mask;
intformat;XImage *XGetSublmage(display, d, x, y, width, height, plane mask,
format, dest_image, dest_x, desty)
Display *display;
Drawable d;
int x, y;
unsigned int width, height;
unsigned long plane mask;
intformat;
XImage *dest_image;
int dest_x, desty;

Arguments
d

Specifies the drawable.

dest_image

Specify the destination image.

dest x
desiy

3-508 Subroutines

Specify the x and y coordinates, which are relative to the
origin of the drawable and are the coordinates of the
subimage or which are relative to the origin of the

XPutlmage (3X11 )
destination rectangle, specify its upper-left comer, and
determine where the subimage is placed in the destination
image.
display

Specifies the connection to the X server.

format

Specifies the format for the image. You can pass
XYBitmap,XYPixmap,orZPixmap.

Specifies the GC.

image

Specifies the image you want combined with the rectangle.

plane_mask

Specifies the plane mask.

src x

Specifies the offset in X from the left edge of the image
defined by the Xlmage data structure.

srcy

Specifies the offset in Y from the top edge of the image
defined by the Xlmage data structure.

width
height

x
y

Specify the width and height of the subimage, which define
the dimensions of the rectangle.
Specify the x and y coordinates, which are relative to the
origin of the drawable and define the upper-left comer of the
rectangle.

Description
The XPutlmage function combines an image in memory with a rectangle of
the specified drawable. If XYBi tmap format is used, the depth must be one,
or a BadMatch error results. The foreground pixel in the GC defines the
source for the one bits in the image, and the background pixel defines the
source for the zero bits. For XYPixmap and ZPixmap, the depth must
match the depth of the drawable, or a BadMatch error results. The section
of the image defined by the src_x, src-y, width, and height arguments is
drawn on the specified part of the drawable.
This function uses these GC components: function, plane-mask, subwindowmode, clip-x-origin, clip-y-origin, and clip-mask. It also uses these GC
mode-dependent components: foreground and background.
XPutlmage can generate BadDrawable, BadGe, BadMatch, and
BadVal ue errors.

Subroutines 3-509

XPutlmage (3X11 )
The XGet Image function returns a pointer to an XImage structure. This
structure provides you with the contents of the specified rectangle of the
drawable in the fonnat you specify. If the fonnat argument is XYP ixmap,
the image contains only the bit planes you passed to the plane_mask
argument. If the plane_mask argument only requests a subset of the planes
of the display, the depth of the returned image will be the number of planes
requested. If the fonnat argument is ZP ixmap, XGet Image returns as zero
the bits in all planes not specified in the plane_mask argument. The function
performs no range checking on the values in plane_mask and ignores
extraneous bits.
XGetImage returns the depth of the image to the depth member of the
XImage structure. The depth of the image is as specified when the drawable
was created, except when getting a subset of the planes in XYP ixmap

format, when the depth is given by the number of bits set to 1 in plane_mask.

If the drawable is a pixmap, the given rectangle must be wholly contained
within the pixmap, or a BadMa t ch error results. If the drawable is a
window, the window must be viewable, and it must be the case that if there
were no inferiors or overlapping windows, the specified rectangle of the
window would be fully visible on the screen and wholly contained within the
outside edges of the window, ora BadMatch error results. Note that the
borders of the window can be included and read with this request. If the
window has backing-store, the backing-store contents are returned for regions
of the window that are obscured by noninferior windows. If the window does
not have backing-store, the returned contents of such obscured regions are
undefined. The returned contents of visible regions of inferiors of a different
depth than the specified window's depth are also undefined. The pointer
cursor image is not included in the returned contents.
XGetImage can generate BadDrawable, BadMatch, and BadValue
errors.
The XGetSubImage function updates dest_image with the specified
subimage in the same manner as XGet Image. If the format argument is
XYPixmap, the image contains only the bit planes you passed to the
plane_mask argument. If the format argument is ZP ixmap,
XGetSubImage returns as zero the bits in all planes not specified in the
plane_mask argument. The function performs no range checking on the
values in plane_mask and ignores extraneOJS bits. As a convenience,
XGetSubImage returns a pointer to the same XImage structure specified
by dest_image.

3-510 Subroutines

XPutlmage (3X11 )
The depth of the destination Xlmage structure must be the same as that of
the drawable. If the specified subimage does not fit at the specified location
on the destination image, the right and bottom edges are clipped. If the
drawable is a pixmap, the given rectangle must be wholly contained within
the pixmap, or a BadMa t ch error results. If the drawable is a window, the
window must be viewable, and it must be the case that if there were no
inferiors or overlapping windows, the specified rectangle of the window
would be fully visible on the screen and wholly contained within the outside
edges of the window, or a BadMatch error results. If the window has
backing-store, then the backing-store contents are returned for regions of the
window that are obscured by noninferior windows. If the window does not
have backing-store, the returned contents of such obscured regions are
undefined. The returned contents of visible regions of inferiors of a different
depth than the specified window's depth are also undefined.
XGetSublmage can generate BadDrawable, BadGC, BadMatch, and
BadValue errors.

Diagnostics
BadDrawable

A value for a Drawable argument does not name a defined
Window or Pixmap.
BadGC

A value for a GContext argument does not name a defined
GContext.

BadMatch

An InputOnly window is used as a Drawable.

BadMatch

Some argument or pair of arguments has the correct type and
range but fails to match in some other way required by the
request.

BadValue

See Also
Guide to the Xlib Library

Subroutines 3-511

XQueryBestSize (3X11 )
Name
XQueryBestSize, XQueryBestTile, XQueryBestStipple - determine efficient
sizes

Syntax
Status XQueryBestSize(display, class, which screen, width, height,
width return, height return)
Display *display;
int class;
Drawable which screen;
unsigned int width, height;
unsigned int *width_return, *height_return;
Status XQueryBestTile(display, which_screen, width, height, width_return,
height return)
Display *display;
Drawable which screen;
unsigned int width, height;
unsigned int *width_return, *height_return;
Status XQueryBestStipple(display, which_screen, width, height,
width return, height return)
Display *display;
Drawable which screen;
unsigned int width, height;
unsigned int *width_return, *height_return;

Arguments
class

Specifies· the class that you are interested in. You can pass
TileShape,CursorShape,orStippleShape.

display

Specifies the connection to the X server.

width
height

Specify the width and height.

which screen

Specifies any drawable on the screen.

width return
height_return

3-512 Subroutines

Return the width and height of the object best supported by
the display hardware.

XQueryBestSize (3X11 )
Description
The XQueryBestSize function returns the best or closest size to the
specified size. For CursorShape, this is the largest size that can be fully
displayed on the screen specified by which_screen. For TileShape, this is
the size that can be tiled fastest. For StippleShape, this is the size that
can be stippled fastest. For CursorShape, the drawable indicates the
desired screen. For TileShape and StippleShape, the drawable
indicates the screen and possibly the window class and depth. An
InputOnly window cannot be used as the drawable for TileShape or
StippleShape, or a BadMatch error results.
XQueryBestSize can generate BadDrawable, BaciMatch, and
BadVal ue errors.

The XQueryBestTile function returns the best or closest size, that is, the
size that can be tiled fastest on the screen specified by which_screen. The
drawable indicates the screen and possibly the window class and depth. If an
InputOn).y window is used as the drawable, a BadMatch error results.
XQueryBest Tile can generate BadDrawable and BadMatch errors.
XQueryBestTile can generate BadDrawable and BadMatch errors.

The XQueryBestStipple function returns the best or closest size, that is,
the size that can be stippled fastest on the screen specified by which_screen.
The drawable indicates the screen and possibly the window class and depth.
If an InputOnly window is used as the drawable, a BadMatch error
results.
XQueryBestStipple can generate BadDrawable and BadMatch
errors.

Diagnostics
BadMatch

An InputOnly window is used as a Drawable.

BadDrawable
A value for a Drawable argument does not name a defined
Window or Pixmap.
BadMatch

The values do not exist for an InputOnly window.

BadValue

Subroutines 3-513

XQueryBestSize (3X11 )
See Also
XCreateGC(3Xll), XSetArcMode(3Xl1), XSetClipOrigin(3Xll),
XSetFillStyle(3Xll), XSetFont(3Xll), XSetLineAttributes(3Xll),
XSetState(3Xll), XSetTile(3Xll)
Guide to the Xlib Library

3-514 Subroutines

XQueryColor (3X11 )
Name
XQueryColor, XQueryColors, XLookupColor - obtain color values

Syntax
XQueryColor(display, colormap, def_in_out)
Display *display;
Colormap colormap;
XColor *de! in out;
XQueryColors (display, colormap, defs_in_out, ncolors)
Display *display;
Colormap colormap;
XColor defs in out[];
int ncolors; - Status XLookupColor(display, colormap, color_name, exact_def_return,
screen de! return)
DiSplay *display;
Colormap colormap;
char *color name;
XColor *exact_def_return, *screen_def_return;

Arguments
colormap

Specifies the colormap.

color name

Specifies the color name string (for example, red) whose
color definition structure you want returned.
Specifies and returns the ROB values for the pixel specified
in the structure.
Specifies and returns an array of color definition structures
for the pixel specified in the structure.

display

Specifies the connection to the X server.

exact de! return
- Returns the exact ROB values.
ncolors

Specifies the number of XColor structures in the color
definition array.

screen de! return
- Returns the closest ROB values provided by the hardware.

Subroutines 3-515

XQueryColor (3X11 )
Description
The XQueryColor function returns the ROB values for each pixel in the
XColor structures and sets the DoRed, DoGreen, and DoBlue flags. The
XQueryColors function returns the ROB values for each pixel in the
XColor structures and sets the DoRed, DoGreen, and DoBlue flags.
XQueryColor XQueryColors and can generate BadColor and
BadVal ue errors.

The XLookupColor function looks up the string name of a color with
respect to the screen associated with the specified colormap. It returns both
the exact color values and the closest values provided by the screen with
respect to the visual type of the specified colormap. You should use the ISO
Latin-l encoding; uppercase and lowercase do not matter. XLookupColor
returns nonzero if the name existed in the color database or zero if it did not
exist.

Diagnostics
BadColor

A value for a Colormap argument does not name a defined
Colormap.

BadValue

See Also
XAllocColor(3Xll), XCreateColormap(3Xll), XStoreColors(3Xll)
Guide to the Xlib Library

3-516 Subroutines

XQueryPointer (3X11 )
Name
XQueryPointer - get pointer coordinates

Syntax
Bool XQueryPointer(display, w, root_return, child_return, root_x_return,
rooty_return, win_x_return, winy_return, mask_return)
Display *display;
Window w;
Window *root return, *child return;
int *root_x_return, *rooty _return;
int *win~_return, *winy _return;
unsigned int *mask_return;

Arguments
child return

Returns the child window that the pointer is located in, if
any.

display

Specifies the connection to the X server.

mask return

Returns the current state of the modifier keys and pointer
buttons.

root return

Returns the root window that the pointer is in.

root x return
rooty _return Return the pointer coordinates relative to the root window's
origin.
w
win x return
winy_return

Specifies the window.
Return the pointer coordinates relative to the specified
window.
.

Description
The XQueryPointer function returns the root window the pointer is
logically on and the pointer coordinates relative to the root window's origin.
If XQueryPointer returns False, the pointer is not on the same screen
as the specified window, and XQueryPointer returns None to
child_return and zero to win_x_retum and win-y_return. If
XQueryPointer returns True, the pointer coordinates returned to
win_x_return and win-y_return are relative to the origin of the specified
window. In this case, XQueryPointer returns the child that contains the
Subroutines 3-517

XQueryPointer (3X11 )
pointer, if any, or else None to child_return.
XQueryPointer returns the current logical state of the keyboard buttons
and the modifier keys in mask_return. It sets mask_return to the bitwise
inclusive OR of one or more of the button or modifier key bitmasks to match
the current state of the mouse buttons and the modifier keys.
XQueryPointer can generate a BadWindow error.

Diagnostics
BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XGetWindowAttributes(3Xll), XQueryTree(3Xll)
Guide to the Xlib Library

3-518 Subroutines

XQueryTree (3X11 )
Name
XQueryTree - query window tree infonnation

Syntax
Status XQueryTree( display, W, root_return, parent_return, children_return,
nchildren return)
Dispiiy *display;
Window w;
Window *root return;
Window *parent_return;
Window **children return;
unsigned int *nchildren_return;

Arguments
children return
Returns a pointer to the list of children.
display

Specifies the connection to the X server.

nchildren return
Returns the number of children.
parent return Returns the parent window.
root return

Returns the root window.

Specifies the window whose list of children, root, parent, and
number of children you want to obtain.

Description
The XQueryTree function returns the root ID, the parent window ID, a
pointer to the list of children windows, and the number of children in the list
for the specified window. The children are listed in current stacking order,
from bottommost (first) to topmost (last). XQueryTree returns zero if it
fails and nonzero if it succeeds. To free this list when it is no longer needed,
use XFree.

Bugs
This really should return a screen *, not a root window ID.

Subroutines 3-519

XQueryTree (3X11 )
See Also
XGetWindowAttributes(3Xll), XQueryPointer(3Xll)
Guide to the Xlib Library

3-520 Subroutines

XRaiseWindow (3X11 )
Name
XRaiseWindow, XLowerWindow, XCirculateSubwindows,
XCirculateSubwindowsUp, XCirculateSubwindowsDown, XRestackWindows
- change window stacking order

Syntax
XRaiseWindow (display, w)
Display *display;
Window w;
XLowerWindow( display, w)
Display *display;
Window w;

XCirculateSubwindows(display, w, direction)
Display *display;
Windoww;
int direction;
XCirculateSubwindowsUp( display, w)
Display *display;
Windoww;
XCirculateSubwindowsDown( display, w)
Display *display;
Window w;

XRestackWindows(display, windows, nwindows);
Display *display;
Window windows [];
int nwindows;

Arguments
direction

Specifies the direction (up or down) that you want to
circulate the window. You can pass RaiseLowest or
LowerHighest.

display

Specifies the connection to the X server.

nwindows

Specifies the number of windows to be restacked.

Specifies the window.

windows

Specifies an array containing the windows to be restacked.

Subroutines 3-521

XRaiseWindow (3X11 )
Description
The XRaiseWindow function raises the specified window to the top of the
stack so that no sibling window obscures it. If the windows are regarded as
overlapping sheets of paper stacked on a desk, then raising a window is
analogous to moving the sheet to the top of the stack but leaving its x and y
location on the desk constant. Raising a mapped window may generate
Expose events for the window and any mapped subwindows that were
formerly obscured.
If the override-redirect attribute of the window is False and some other
client has selected SubstructureRedirectMask on the parent, the X
server generates a ConfigureRequest event, and no processing is
performed. Otherwise, the window is raised.

XRaiseWindow can generate a BadWindow error.

The XLowerWindow function lowers the specified window to the bottom of
the stack so that it does not obscure any sibling windows. If the windows are
regarded as overlapping sheets of paper stacked on a desk, then lowering a
window is analogous to moving the sheet to the bottom of the stack but
leaving its x and y location on the desk constant. Lowering a mapped
window will generate Expose events on any windows it formerly obscured.
If the override-redirect attribute of the window is False and some other
client has selected SubstructureRedirectMask on the parent, the X
server generates a ConfigureRequest event, and no processing is
performed. Otherwise, the window is lowered to the bottom of the stack.

XLowerWindow can generate a BadWindow error.

The XCirculateSubwindows function circulates children of the specified
window in the specified direction. If you specify RaiseLowest,
XCirculateSubwindows raises the lowest mapped child (if any) that is
occluded by another child to the top of the stack. If you specify
LowerHighest, XCirculateSubwindows lowers the highest mapped
child (if any) that occludes another child to the bottom of the stack.
Exposure processing is then performed on formerly obscured windows. If
some other client has selected SubstructureRedirectMask on the
window, the X server generates a CirculateRequest event, and no
further processing is performed. If a child is actually restacked, the X server
generates a CirculateNotify event.
XCirculateSubwindows can generate BadValue and BadWindow
errors.

3-522 Subroutines

XRaiseWindow (3X11 )
The XCirculateSubwindowsUp function raises the lowest mapped child
of the specified window that is partially or completely occluded by another
child. Completely unobscured children are not affected. This is a
convenience function equivalent to XCirculateSubwindows with
RaiseLowest specified.
XCirculateSubwindowsUp can generate a BadWindow error.

The XCirculateSubwindowsDown function lowers the highest mapped
child of the specified window that partially or completely occludes another
child. Completely unobscured children are not affected. This is a
convenience function equivalent to XCirculateSubwindows with
LowerHighest specified.
XCirculateSubwindowsDown can generate a BadWindow error.

The XRestackWindows function restacks the windows in the order
specified, from top to bottom. The stacking order of the first window in the
windows array is unaffected, but the other windows in the array are stacked
underneath the first window, in the order of the array. The stacking order of
the other windows is not affected. For each window in the window array that
is not a child of the specified window, a BadMat ch error results.
If the override-redirect attribute of a window is False and some other client
has selected SubstructureRedirectMask on the parent, the X server
generates ConfigureRequest events for each window whose overrideredirect flag is not set, and no further processing is performed. Otherwise,
the windows will be restacked in top to bottom order.

XRestackWindows can generate BadWindow error.

Diagnostics
BadValue

BadWindow

A value for a Window argument does not name a defined
Window.

Subroutines 3-523

XRaiseWindow (3X11 )
See Also
XChangeWindowAttributes(3Xll), XConfigureWindow(3Xll),
XCreateWindow(3Xll), XDestroyWindow(3Xl1), XMapWindow(3Xll),
XUnmapWindow(3Xl1)
Guide to the Xlib Library

3-524 Subroutines

XReadBitmapFile (3X11 )
Name
XReadBitmapFile, XWriteBitmapFile, XCreatePixmapFromBitmapData,
XCreateBitmapFromData - manipulate bitmaps

Syntax
int XReadBitmapFile(display, d,fiiename, width_return, height_return,
bitmap_return, x_hot_return, y_hot_return)
Display *display;
Drawable d;
char *filename;
unsigned int *width_return, *height_return;
Pixmap *bitmap_return;
int *x_hot_return, *y_hot_return;
int XWriteBitmapFile(display,filename, bitmap, width, height, x_hot, y_hot)
Display *display;
char *filename;
Pixmap bitmap;
unsigned int width, height;
int x_hot, Y_hot;
Pixmap XCreatePixmapFromBitmapData(display, d, data, width, height,/g,
bg, depth)
Display *display;
Drawable d;
char *data;
unsigned int width, height;
unsigned long/g, bg;
unsigned int depth;
Pixmap XCreateBitmapFromData(display, d, data, width, height)
Display *display;
Drawable d;
char *data;
unsigned int width, height;

Arguments
bitmap

Specifies the bitmap.

bitmapJeturn Returns the bitmap that is created.
d

Specifies the drawable that indicates the screen.

Subroutines 3-525

XReadBitmapFile (3X11 )
data

Specifies the data in bitmap format.

data

Specifies the location of the bitmap data.

depth

Specifies the depth of the pixmap.

display

Specifies the connection to the X server.

Specify the foreground and background pixel values to use.

filename

Specifies the file name to use. The format of the file name is
operating-system dependent.

width
height

Specify the width and height.

width return
height return

Return the width and height values of the read in bitmap file.

x hot
y_hot
x hot return
y-hot-return

Specify where to place the hotspot coordinates (or -1,-1 if
none are present) in the file.
Return the hotspot coordinates.

Description
The XReadBitmapFile function reads in a file containing a bitmap. The
file can be either in the standard X version 10 format (that is, the format used
by X version 10 bitmap program) or in the X version 11 bitmap format. If
the file cannot be opened, XReadBitmapFile returns
BitmapOpenFailed. If the file can be opened but does not contain valid
bitmap data, it returns BitmapFilelnvalid. If insufficient working
storage is allocated, it returns Bi tmapNoMemory. If the file is readable and
valid, it returns BitmapSuccess.
XReadBi tmapFile returns the bitmap's height and width, as read from the
file, to width_return and height_return. It then creates a pixmap of the
appropriate size, reads the bitmap data from the file into the pixmap, and
assigns the pixmap to the caller's variable bitmap. The caller must free the
bitmap using XFreePixmap when finished. If name_x_hot and
name_y_hot exist, XReadBitmapFile returns them to x_hot_return and
y_hot_return; otherwise, it returns -1,-1.
XReadBitmapFile can generate BadAlloc and BadDrawable errors.

3-526 Subroutines

XReadBitmapFile (3X11 )
The XWri teBi tmapFile function writes a bitmap out to a file. While
XReadBitmapFile can read in either X version 10 format or X version 11
format, XWriteBitmapFile always writes out X version 11 format. If
the file cannot be opened for writing, it returns BitmapOpenFailed. If
insufficient memory is allocated, XWri teBi tmapF ile returns
BitmapNoMemory; otherwise, on no error, it returns BitmapSuccess.
If x_hot and y_hot are not -1, -1, XWriteBitmapFile writes them out as
the hotspot coordinates for the bitmap.
XWriteBitmapFile can generate BadDrawable and BadMatch errors.

The XCreateP ixmapFromBi tmapData function creates a pixmap of the
given depth and then does a bitmap-format XPut Image of the data into it.
The depth must be supported by the screen of the specified drawable, or a
BadMatch error results.
XCreatePixmapFromBitmapData can generate BadAlloc and
BadMatch errors.

The XCreateBi tmapFromData function allows you to include in your C
program (using #include) a bitmap file that was written out by
XWriteBitmapFile (X version 11 format only) without reading in the
bitmap file. The following example creates a gray bitmap:
#include "gray.bitmap"
Pixmap bitmap;
bitmap = XCreateBitmapFromData(display, window, gray_bits, gray_width, gray_height
If insufficient working storage was allocated, XCreateBitmapFromData
returns None. It is your responsibility to free the bitmap using
XFreeP ixmap when finished.

XCreateBitmapFromData can generate a BadAlloc error.

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadDrawable
A value for a Drawable argument does not name a defined
Window or Pixmap.
BadMatch

An InputOnly window is used as a Drawable.

Subroutines 3-527

XReadBitmapFile (3X11 )
See Also
Guide to the Xlib Library

3-528 Subroutines

XRecolorCursor (3X11 )
Name
XRecolorCursor, XFreeCursor, XQueryBestCursor - manipulate cursors

Syntax
XRecolorCursor( display, cursor, foreground_color, background_color)
Display *display;
Cursor cursor;
XColor *foreground_color, *background_color;
XFreeCursor( display, cursor)
Display *display;
Cursor cursor;
Status XQueryBestCursor(display, d, width, height, width_return,
height_return)
Display *display;
Drawable d;
unsigned int width, height;
unsigned int *width_return, *height_return;

Arguments
background color
Specifies the ROB values for the background of the source.
cursor

Specifies the cursor.

Specifies the drawable, which indicates the screen.

display

Specifies the connection to the X server.

foreground color
Specifies the ROB values for the foreground of the source.
width
height
width return
height_return

Specify the width and heightof the cursor that you want the
size information for.
Return the best width and height that is closest to the
specified width and height.

Subroutines 3-529

XRecolorCursor (3X11 )
Description
The XRecolorCursor function changes the color of the specified cursor,
and if the cursor is being displayed on a screen, the change is visible
immediately.
XRecolorCursor can generate a BadCursor error.

The XFreeCursor function deletes the association between the cursor
resource ID and the specified cursor. The cursor storage is freed when no
other resource references it. The specified cursor ID should not be referred to
again.
XFreeCursor can generate a ~adCursor error.

Some displays allow larger cursors than other displays. The
XQueryBestCursor function provides a way to find out what size cursors
are actually possible on the display. It returns the largest size that can be
displayed. Applications should be prepared to use smaller cursors on
displays that cannot support large ones.
XQueryBestCursor can generate a BadDrawable error.

Diagnostics
BadCursor

A value for a Cursor argument does not name a defined
Cursor.

BadDrawable
A value for a Drawable argument does not name a defined
Window or Pixmap.

See Also
XCreateFontCursor(3XII), XDefineCusor(3Xll)
Guide to the Xlib Library

3-530 Subroutines

XReparentWindow (3X11 )
Name
XReparentWindow - reparent windows

Syntax
XReparentWindow(display, w, parent, x, y)
Display *display;
Window w;
Window parent;
int x, y;

Arguments
display

Specifies the connection to the X server.

parent

Specifies ·the parent window.

Specifies the window.

Specify the x and y coordinatesof the position in the new
parent window.

Description
If the specified window is mapped, XReparentWindow automatically
performs an UnmapWindow request on it, removes it from its current
position in the hierarchy, and inserts it as the child of the specified parent.
The window is placed in the stacking order on top with respect to sibling
windows.

After reparenting the specified window, XReparentWindow causes the X
server to generate a ReparentNotify event. The override_redirect
member returned in this event is set to the window's corresponding attribute.
Window manager clients usually should ignore this window if this member is
set to True. Finally, if the specified window was originally mapped, the X
server automatically performs a MapWindow request on it.
The X server performs normal exposure processing on formerly obscured
windows. The X server might not generate Expo s e events for regions from
the initial UnmapWindow request that are immediately obscured by the final
MapWindow request. A BadMatch error results if:
•

The new parent window is not on the same screen as the old parent
window.

Subroutines 3-531

XReparentWindow(3X11 )
•

The new parent window is the specified window or an inferior of the
specified window.

•

The specified window has a ParentRelative background, and the
new parent window is not the same depth as the specified window.

XReparentWindow can generate BadMatch and BadWindow errors.

Diagnostics
BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XChangeSaveSet(3Xll)
Guide to the Xlib Library

3-532 Subroutines

XrmGetResource (3X11 )
Name
XrmGetResource, XrmQGetResource, XrmQGetSearchList,
XrmQGetSearchResource - retrieve database resources and search lists

Syntax
Bool XrmGetResource(database, str_name, str_class, str_type_return,
value return)
xilnDatabase database;
char *str name;
char *str- class;
char **str type return;
XrmV alue-*value_return;
Bool XrmQGetResource(database, quark_name, quark_class,
quark_type_return, value_return)
XrmDatabase database;
XnnNameList quark_name;
XrmClassList quark_class;
XnnRepresentation *quark_type_return;
XrmValue *value_return;
typedef XrmHashTable *XrmSearchList;
Bool XrmQGetSearchList(database, names, classes, list return, list length)
XrmDatabase database;
-XnnNameList names;
XrmClassList classes;
XrmSearchList list return;
int list_length;
Bool XrmQGetSearchResource(list, name, class, type return, value return)
XrmSearchList list;
- XnnName name;
XrmClass class;
XnnRepresentation *type_return;
XrmValue *value_return;

Arguments
class

Specifies the resource class.

classes

Specifies a list of resource classes.

Subroutines 3-533

XrmGetResource (3X11 )
database

Specifies the database that is to be used.

list

Specifies the search list returned by
XrmQGetSearchList.

list_length

Specifies the number of entries (not the byte size) allocated
for list_return.

list return

Returns a search list for further use.

name

Specifies the resource name.

names

Specifies a list of resource names.

quark_class

Specifies the fully qualified class of the value being retrieved
(as a quark).

quark_name

Specifies the fully qualified name of the value being retrieved
(as a quark).

quark type return
Returns a pointer to the representation type of the destination
(as a quark).
str class

Specifies the fully qualified class of the value being retrieved
(as a string).

str name

Specifies the fully qualified name of the value being retrieved
(as a string).

str_type_return Returns a pointer to the representation type of the destination
(as a string).
type_return

Returns data representation type.

value return

Returns the value in the database.

Description
The XrmGetResource and XrmQGetResource functions retrieve a
resource from the specified database. Both take a fully qualified name/class
pair, a destination resource representation, and the address of a value
(size/address pair). The value and returned type point into database memory;
therefore, you must not modify the data.
The database only frees or overwrites entries on XrmPutResource,
XrmQPutResource, or XrmMergeDatabases. A client that is not
storing new values into the database or is not merging the database should be
safe using the address passed back at any time until it exits. If a resource
was found, both XrmGetResource and XrmQGetResource return
True; otherwise, they return False.

3-534 Subroutines

XrmGetResource (3X11 )
The XrmQGetSearchList function 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 algorithm as XrmGetResource
for determining precedence. If list_return was large enough for the search
list, XrmQGetSearchList returns True; otherwise, it returns False.
The size of the search list that the caller must allocate is dependent upon the
number of levels and wildcards in the resource specifiers that are stored in
the database. The worst case length is 3n , where n is the number of name or
class components in names or classes.
When using XrmQGetSearchList followed by multiple probes for
resources with a common name and class prefix, only the common prefix
should be specified in the name and class list to XrmQGetSearchList.
The XrmQGetSearchResource function searches the specified database
levels for the resource that is fully identified by the specified name and class.
The search stops with the first match. XrmQGetSearchResource returns
True if the resource was found; otherwise, it returns False.
A call to XrmQGetSearchList with a name and class list containing all
but the last component of a resource name followed by a call to
XrmQGetSearchResource with the last component name and class
returns the same database entry as XrmGetResource and
XrmQGetResource with the fully qualified name and class.

See Also
XrmInitialize(3Xll), XrmMergeDatabases(3Xll), XrmPutResource(3Xll),
XrmUniqueQuark(3Xll)
Guide to the Xlib Library

Subroutines 3-535

Xrmlnitialize (3X11 )
Name
XnnInitialize, XnnParseCommand - initialize the Resource Manager and
parse the command line

Syntax
void XrmInitialize();
void XnnParseCommand( database, table, table_count, name, argc_in_out,
argv in out ,)
XnilDatabase *database;
XrmOptionDescList table;
int table count;
char *name;
int *argc in out;
char **argv]n_out;

Arguments
argc_in_out

Specifies the number of arguments and returns the number of
remaining arguments.

argv_in_out

Specifies a pointer to the command line arguments and
returns the remaining arguments.

database

Specifies a pointer to the resource database.

name

Specifies the application name.

table

Specifies the table of command line arguments to be parsed.

table count

Specifies the number of entries in the table.

Description
The Xrmlnitialize function initialize the resource manager.
The XrmParseCommand function parses an (argc, argv) pair according to
the specified option table, loads recognized options into the specified
database with type "String," and modifies the (argc, argv) pair to remove all
recognized options.
The specified table is used to parse the command line. Recognized entries in
the table are removed from argv, and entries are made in the specified
resource database. The table entries contain information on the option string,
the option name, the style of option, and a value to provide if the option kind
is XrmoptionNoArg. The argc argument specifies the number of
3-536 Subroutines

Xrmlnitialize (3X11 )
arguments in argv and is set to the remaining number of arguments that were
not parsed. The name argument should be the name of your application for
use in building the database entry. The name argument is prefixed to the
resourceName in the option table before storing the specification. No
separating (binding) character is inserted. The table must contain either a
period (.) or an asterisk (*) as the first character in each resourceName entry.
To specify a more completely qualified resource name, the resourceName
entry can contain multiple components.

See Also
XrmGetResource(3Xll), XrmMergeDatabases(3Xll),
XnnPutResource(3Xll), XrmUniqueQuark(3Xll)
Guide to the Xlib Library

Subroutines 3-537

XrmMergeDatabases (3X11 )
Name
XrmMergeDatabases, XrmGetFileDatabase, XnnPutFileDatabase,
XrmGetStringDatabase - manipulate resource databases

Syntax
void XrmMergeDatabases(source _db, target_db)
XrmDatabase source_db, *target_db;
XrmDatabase XrmGetFileDatabase(filename)
char *filename;
void XnnPutFileDatabase(database, stored db)
XrmDatabase database;
char *stored_db;
XrmDatabase XnnGetStringDatabase( data)
char *data;

Arguments
data

Specifies the database contents using a string.

database

Specifies the database that is to be used.

filename

Specifies the resource database file name.

source db

Specifies the resource database that is to be merged into the
target database.

stored db

Specifies the file name for the stored database.

target_db

Specifies a pointer to the resource database into which the
source database is to be merged.

Description
The XrmMergeDatabases function merges the contents of one database
into another. It may overwrite entries in the destination database. This
function is used to combine databases (for example, an application specific
database of defaults and a database of user preferences). The merge is
destructive; that is, the source database is destroyed.
The XrmGetFileDatabase function opens the specified file, creates a
new resource database, and loads it with the specifications read in from the
specified file. The specified file must contain lines in the format accepted by
XrmPutLineResQurce. If it cannot open the specified file,

3-538 Subroutines

XrmMergeDatabases (3X11 )
XrmGetFileDatabase returns NULL.

The XrmPutFileDatabase function stores a copy of the specified
database in the specified file. The file is an ASCII text file that contains lines
in the fonnat that is accepted by XrmPutLineResQurce.
The XrmGetStringDatabase function creates a new database and stores
the resources specified in the specified null-tenninated string.
XrmGetStringDatabase is similar to XrmGetFileDatabase except
that it reads the infonnation out of a string instead of out of a file. Each line
is separated by a new-line character in the fonnat accepted by
XrmPutLineResQurce.

See Also
XnnGetResource(3Xll), XrmInitialize(3Xll), XrmPutResource(3Xll),
XnnUniqueQuark(3Xll)
Guide to the Xlib Library

Subroutines 3-539

XrmPutResource {3X11 }
Name
XnnPutResource, XnnQPutResource, XnnPutStringResource,
XnnQPutStringResource, XnnPutLineResource - store database resources

Syntax
void XnnPutResource(database, specifier, type, value)
XnnDatabase *database;
char *specifier;
char *type;
XnnValue *value;
void XnnQPutResource(database, bindings, quarks, type, value)
XnnDatabase *database;
XnnBindingList bindings;
XnnQuarkList quarks;
XnnRepresentation type;
XnnValue *value;
void XnnPutStringResource(database, specifier, value)
XnnDatabase *database;
char *specifier;
char *value;
void XnnQPutStringResource(database, bindings, quarks, value)
XnnDatabase *database;
XnnBindingList bindings;
XnnQuarkList quarks;
char *value;
void XnnPutLineResource(database, line)
XnnDatabase *database;
char *line;

Arguments
bindings

Specifies a list of bindings.

database

Specifies a pointer to the resource database.

line

Specifies the resource value pair as a single string. A single
colon (:) separates the name from the value.

quarks

Specifies the complete or partial name or the class list of the
resource.

3-540 Subroutines

XrmPutResource (3X11 )
specifier

Specifies a complete or partial specification of the resource.

type

Specifies the type of the resource.

value

Specifies the value of the resource, which is specified as a
string.

Description
If database contains NULL, XrmPutResource creates a new database and
returns a pointer to it. XtmPutResource is a convenience function that
calls XrmStringToBindingQuarkList followed by:

XrmQPutResource(database, bindings, quarks, XrmStringToQuark(type), value)
If database contains NULL, XrmQPutResource creates a new database
and returns a pointer to it.
If database contains NULL, XrmPutStringResource creates a new
database and returns a pointer to it. XrmPutStringResource adds a
resource with the specified value to the specified database.
XrmPutStringResource is a convenience routine that takes both the
resource and value as null-terminated strings, converts them to quarks, and
then calls XrmQPutResource, using a "String" representation type.
If database contains NULL, XrmQPutStringResource creates a new
database and returns a pointer to it. XrmQPutStringResource is a
convenience routine that constructs an XrmValue for the value string (by
calling strlen to compute the size) and then calls XrmQPutResource,
using a "String" representation type.
If database contains NULL, XrmPutLineResource creates a new
database and returns a pointer to it. XrmPutLineResource adds a single
resource entry to the specified database. Any white space before or after the
name or colon in the line argument is ignored. The value is terminated by a
new-line or a NULL character. To allow values to contain embedded newline characters, a "\n" is recognized and replaced by a new-line character.
For example, line might have the value "xterm*background:green\n". Nullterminated strings without a new line are also permitted.

See Also
XrmGetResource(3Xll), XnnInitialize(3Xll), XrmMergeDatabases(3Xll),
XrmUniqueQuark(3Xll)
Guide to the Xlib Library

Subroutines 3-541

XrmUniqueQuark (3X11 )
Name
XnnUniqueQuark, XnnStringToQuark, XnnQuarkToString,
XnnStringToQuarkList, XnnStringToBindingQuarkList - manipulate
resource quarks

Syntax
XnnQuark XnnUniqueQuark()
#define XnnStringToName(string) XnnStringToQuark(string) #define
XnnStringToClass(string) XnnStringToQuark(string) #define
XnnStringToRepresentation(string) XnnStringToQuark(string)
XnnQuark XnnStringToQuark(string)
char *string;
#define XnnNameToString(name) XnnQuarkToString(name) #define
XnnClassToString(class) XnnQuarkToString(class) #define
XnnRepresentationToString(type) XnnQuarkToString(type)
char *XnnQuarkToString( quark)
XnnQuark quark;
#define XnnStringToNameList(str, name) XnnStringToQuarkList«str),
(name)) #define XnnStringToClassList(str,class) XnnStringToQuarkList«str),
(class))
void XnnStringToQuarkList(string, quarks return)
char *string;
XnnQuarkList quarks return;

XnnStringToBindingQuarkList(string, bindings_return, quarks_return)
char *string;
XnnBindingList bindings return;
XnnQuarkList quarks return;

Arguments
bindings return
Returns the binding list.
quark
Specifies the quark for which the equivalent string is desired.
quarks return Returns the list of quarks.
string
3-542 Subroutines

Specifies the string for which a quark is to be allocated.

XrmUniqueQuark (3X11 )
Description
The XrmUniqueQuark function allocates a quark that is guaranteed not to
represent any string that is known to the resource manager.
These functions can be used to convert to and from quark representations.
The string pointed to by the return value must not be modified or freed. If
no string exists for that quark, XrmQuarkToString returns NULL.
The XrmQuarkToString function converts the specified resource quark
representation back to a string.
The XrmStringToQuarkList function converts the null-terminated
string (generally a fully qualified name) to a list of quarks. The components
of the string are separated by a period or asterisk character.
A binding list is a list of type XrmBindingList and indicates if
components of name or class lists are bound tightly or loosely (that is, if
wildcarding of intermediate components is specified).
typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList
XrmBindTightly indicates that a period separates the components, and
XrmBindLoosely indicates that an asterisk separates the components.

The XrmStringToBindingQuarkList function converts the specified
string to a binding list and a quark list. Component names in the list are
separated by a period or an asterisk character. If the string does not start
with period or asterisk, a period is assumed. For example, "*a.b*c"
becomes:
quarks
bindings

a
loose

b
tight

c
loose

See Also
XrmGetResource(3Xll), XrmInitialize(3Xll), XrmMergeDatabases(3Xll),
~tResource(3Xll)

Guide to the Xlib Library

Subroutines 3-543

XSaveContext (3X11 )
Name
XSaveContext, XFindContext, XDeleteContext, XUniqueContext associative lookup routines

Syntax
int XSaveContext(display, w, context, data)
Display *display;
Windoww;
XContext context;
caddr_t data;
int XFindContext(display, w, context, data return)
Display *display;
Window w;
XContext context;
caddr_t *data_return;
int XDeleteContext( display, w, context)
Display *display;
Window w;
XContext context;
XContext XUniqueContext()

Arguments
context

Specifies the context type to which the data belongs.

data

Specifies the data to be associated with the window and type.

data return

Returns a pointer to the data.

display

Specifies the connection to the X server.

Specifies the window with which the data is associated.

Description
If an entry with the specified window and type already exists,
XSaveContext overrides it with the specified context. The
XSaveContext function returns a nonzero error code if an error has
occurred and zero otherwise. Possible errors are XCNOMEM (out of memory).

Because it is a return value, the data is a pointer. The XFindContext
function returns a nonzero error code if an error has occurred and zero
otherwise. Possible errors are XCNOENT (context-not-found).
3-544 Subroutines

XSaveContext (3X11 )
The XDeleteContext function deletes the entry for the given window and
type from the data structure. This function returns the same error codes that
XF indContext returns if called with the same arguments.
XDeleteContext does not free the data whose address was saved.
The XUniqueContext function creates a unique context type that may be
used in subsequent calls to XSaveContext.

See Also
Guide to the Xlib Library

Subroutines 3-545

XSelectinput{3X11 )
Name
XSelectInput, XSelectAsyncInput - select input events

Syntax
XSelectInput(display, w, event mask)
Display *display;
Window w;
long event_mask;
XSelectAsyncInput(display, w, event_mask, procedure, argument)
Display *display;
Window w;
unsigned long event_mask;
int (*procedure)o
unsigned long argument;

Arguments
argument

Specifies the argument that is to be passed to the specified
procedure.

display

Specifies the connection to the X server.

event mask

Specifies the event mask.

procedure

Specifies the procedure that is to be called.

Specifies the window whose events you are interested in.

Description
The XSelectlnput function requests that the X server report the events
associated with the specified event mask. Initially, X will not report any of
these events. Events are reported relative to a window. If a window is not
interested in a device event, it usually propagates to the closest ancestor that
is interested, unless the do_not_propagate mask prohibits it.
Setting the event-mask attribute of a window overrides any previous call for
the same window but not for other clients. Multiple clients can select for the
same events on the same window with the following restrictions:
•

Multiple clients can select events on the same window because their
event masks are disjoint. When the X server generates an event, it
reports it to all interested clients.

3-546 Subroutines

XSelectlnput {3X11 }
•

Only one client at a time can select CirculateRequest,
ConfigureRequest, or MapRequest events, which are associated
with the event mask SubstructureRedirectMask.

•

Only one client at a time can select a ResizeRequest event, which
is associated with the event mask ResizeRedirectMask.

•

Only one client at a time can select a ButtonPress event, which is
associated with the event mask ButtonPressMask.

The server reports the event to all interested clients.
XSelectlnput can generate a BadWindow error.

The XSelectAsynclnput function establishes asynchrous notification
mode and calls the specified procedure, passing it the specified argument
when you receive the event selected with the event_mask. Anyone who
asynchrous notification cannot also use the SIGIO signal.

Diagnostics
BadWindow

A value for a Window argument does not name a defined
Window.

See Also
Guide to the Xlib Library

Subroutines 3-547

XSendEvent (3X11 )
Name
XSendEvent, XDisplayMotionBufferSize, XGetMotionEvents - send events

Syntax
Status XSendEvent(display, w, propagate, event_mask, event_send)
Display *display;
Window w;
Bool propagate;
long event_mask;
XEvent *event_send;
unsigned long XDisplayMotionBufferSize(display)
Display *display;
XTimeCoord *XGetMotionEvents (display, w, start, stop, nevents_return)
Display *display;
Window w;
Time start, stop;
int *nevents_return;

Arguments
display

Specifies the connection to the X server.

event mask

Specifies the event mask.

event send

Specifies a pointer to the event that is to be sent.

nevents return Returns the number of events from the motion history buffer.
propagate
start
stop

Specifies a Boolean value.
Specify the time interval in which the events are returned
from the motion history buffer. You can pass a timestamp or

CurrentTime. PointerWindow,
W

Specifies the window the window the event is to be sent to,.

Description
The XSendEvent function identifies the destination window, determines
which clients should receive the specified events, and ignores any active
grabs. This function requires you to pass an event mask. For a discussion of
the valid event mask names, see section 8.3. This function uses the w
argument to identify the destination window as follows:
3-548 Subroutines

XSendEvent (3X11 )
•

H w is PointerWindow, the destination window is the window that
contains the pointer.

•

H w is InputFocus and if the focus window contains the pointer, the
destination window is the window that contains the pointer; otherwise,
the destination window is the focus window.

To detennine which clients should receive the specified events,
XSendEvent uses the propagate argument as follows:
•

H event_mask is the empty set, the event is sent to the client that
created the destination window. H that client no longer exists, no
event is sent.

•

H propagate is False, the event is sent to every client selecting on
destination any of the event types in the event_mask argument.

•

H propagate is True and no clients have selected on destination any of
the event types in event-mask, the destination is replaced with the
closest ancestor of destination for which some client has selected a
type in event-mask and for which no intervening window has that type
in its do-not-propagate-mask. H no such window exists or if the
window is an ancestor of the focus window and InputFocus was
originally specified as the destination, the event is not sent to any
clients. Otherwise, the event is reported to every client selecting on the
final destination any of the types specified in event_mask.

The event in the XEvent structure must be one of the core events or one of
the events defined by an extension (or a BadValue error results) so that the
X server can correctly byte-swap the contents as necessary. The contents of
the event are otherwise unaltered and unchecked by the X server except to
force send_event to True in the forwarded event and to set the serial number
in the event correctly.
XSendEvent returns zero if the conversion to wire protocol fonnat failed
and returns nonzero otherwise. XSendEvent can generate BadVal ue and
BadWindowerrors.
The server may retain the recent history of the pointer motion and do so to a
finer granularity than is reported by MotionNotify events. The
XGetMotionEvents function makes this history available.
The XGetMotionEvents function returns all events in the motion history
buffer that fall between the specified start and stop times, inclusive, and that
have coordinates that lie within the specified window (including its borders)
at its present placement. H the start time is later than the stop time or if the
start time is in the future, no events are returned. H the stop time is in the

Subroutines 3-549

XSendEvent (3X11 )
future, it is equivalent to specifying CurrentTime.
XGetMotionEvents can generate a BadWindowe error.

Diagnostics
BadVal ue

BadWindow

See Also
XIfEvent(3Xll), XNextEvent(3Xll), XPutBackEvent(3Xll)
Guide to the Xlib Library

3-550 Subroutines

XSetArcMode (3X11 )
Name
XSetArcMode, XSetSubwindowMode, XSetGraphicsExposure - GC
convenience routines

Syntax
XSetArcMode(display, gc, arc_mode)
Display *display;
GC gc;
int arc_mode;
XSetSubwindowMode (display, gc, subwindow_mode)
Display *display;
GC gc;
int subwindow_mode;
XSetGraphicsExposures(display, gc, graphics_exposures)
Display *display;
GCgc;
Bool graphics_exposures;

Arguments
arc mode

Specifies the arc mode. You can pass ArcChord or
ArcP ieSlice.

display

Specifies the connection to the X server.

Specifies the GC.

graphics_exposures
Specifies a Boolean value that indicates whether you want
GraphicsExpose and NoExpose events to be reported
when calling XCopyArea and XCopyP lane with this GC.
subwindow mode
Specifies the subwindow mode. You can pass
ClipByChildren or Includelnferiors.

Description
The XSetArcMode function sets the arc mode in the specified GC.
XSetArcMode can generate BadAlloc, BadGC, and BadValue errors.

Subroutines 3-551

XSetArcMode(3X11 )
The XSetSubwindowMode function sets the subwindow mode in the
specified GC.
XSetSubwindowMode can generate BadAlloc, B~dGC, and BadValue
errors.

The XSetGraphicsExposures function sets the graphics-exposures flag
in the specified GC.
XSetGraphicsExposures can generate BadAlloc, BadGC, and
BadVal ue errors.

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadGC

A value for a GContext argument does not name a defined
GContext.

BadValue

See Also
XCreateGC(3Xll), XQueryBestSize(3Xll), XSetClipOrigin(3Xll),
XSetFillStyle(3Xll), XSetFont(3Xll), XSetLineAttributes(3Xll),
XSetState(3Xll), XSetTile(3Xl1)
Guide to the Xlib Library

3-552 Subroutines

XSetClassHint {3X11 }
Name
XSetClassHint, XGetClassHint - set or get class hint

Syntax
XSetClassHint(display, w, class hints)
Display *display;
Window w;
XClassHint *class_hints;

Status XGetClassHint (display, w, class_hints_return)
Display *display;
Windoww;
XClassHint *class_hints_return;

Arguments
class hints

Specifies a pointer to a XClassHint structure that is to be
used.

class hints return
Returns the XClas sHint structure.
display

Specifies the connection to the X server.

Specifies the window.

Description
The XSetClassHint function sets the class hint for the specified window.
XSetClassHint can generate BadAlloc and BadWindow errors.

The XGetClassHint function returns the class of the specified window.
To free res_name and res_class when finished with the strings, use XFree.
XGetClassHint can generate a BadWindow error.

Property
WM_CLASS

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadWindow

A value for a Window argument does not name a defined
Subroutines 3-553

XSetClassHint (3X11 )
Window.

See Also
XSetCommand(3Xll), XSetIconName(3Xll), XSetIconSizeHints(3Xll),
XSetNormalHints(3Xl1), XSetSizeHints(3Xll),
XSetStandardProperties(3Xll), XSetTransientForHint(3Xll),
XSetWMHints(3Xll), XSetZoomHints(3Xll), XStoreName(3Xll)
Guide to the Xlib Library

3-554 Subroutines

XSetClipOrigin {3X11 }
Name
XSetClipOrigin, XSetClipMask, XSetClipRectangles - GC convenience
routines

Syntax
XSetClipOrigin(display, gc, clip_x_origin, clipy_origin)
Display *display;
GC gc;
int clip~_origin, clipy _origin;
XSetClipMask (display, gc, pixmap)
Display *display;
GCgc;
Pixmap pixmap;
XSetClipRectangles(display, gc, clip_x_origin, clipy_origin, rectangles, n,
ordering)
Display *display;
GCgc;
int clip_x_origin, clipy _ orig in;
XRectangle rectangles[];
int n;
int ordering;

Arguments
display

Specifies the connection to the X server.

clip_x_origin
clipy _origin

Specify the x and y coordinates of the clip-mask origin.

Specifies the GC.

Specifies the number of rectangles.

ordering

Specifies the ordering relations on the rectangles. You can
pass Unsorted, YSorted, YXSorted, or YXBanded.

pixmap

Specifies the pixmap or None.

rectangles

Specifies an array of rectangles that define the clip-mask.

Subroutines 3-555

XSetClipOrigin (3X11)
Description
The XSetClipOrigin function sets the clip origin in the specified GC.
The clip-mask origin is interpreted relative to the origin of whatever
destination drawable is specified in the graphics request.
XSetClipOrigin can generate BadAlloc and BadGC errors.

The XSetClipMask function sets the clip-mask in the specified GC to the
specified pixmap. If the clip-mask is set to None, the pixels are are always
drawn (regardless of the clip-origiti).
XSetClipMask can generate BadAlloc, BadGC, BadMatch, and
BadVal ue errors.

The XSetClipRectangles function changes the clip-mask in the
specified GC to the specified list of rectangles and sets the clip origin. The
output is clipped to remain contained within the rectangles. The clip-origin
is interpreted relative to the origin of whatever destination drawable is
specified in a graphics request. The rectangle coordinates are interpreted
relative to the clip-origin. The rectangles should be nonintersecting, or the
graphics results will be undefined. Note that the list of rectangles can be
empty, which effectively disables output. This is the opposite of passing
None as the clip-mask in XCreateGC, XChangeGC, and
XSetClipMask.

If known by the client, ordering relations on the rectangles can be specified
with the ordering argument. This may provide faster operation by the server.
If an incorrect ordering is specified, the X server may generate a BadMatch
error, but it is not required to do so. If no error is generated, the graphics
results are undefined. Unsorted means the rectangles are in arbitrary order.
YSort e d means that the rectangles are nondecreasing in their Y origin.
YXSorted additionally constrains YSorted order in that all rectangles
with an equal Y origin are nondecreasing in their X origin. YXBanded
additionally constrains YXSorted by requiring that, for every possible Y
scanline, all rectangles that include that scanline have an identical Y origins
and Y extents.
XSetClipRectangles can generate BadAlloc, BadGC, BadMatch,

and BadValue errors.

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadGC

A value for a GContext argument does not name a defined

3-556 Subroutines

XSetClipOrigin (3X11 )
GContext.
BadMatch

Some argument or pair of arguments has the correct type and
range but fails to match in some other way required by the
request.

BadValue

See Also
XCreateGC(3Xll), XQueryBestSize(3Xll), XSetArcMode(3Xll),
XSetFillStyle(3Xll), XSetFont(3Xll), XSetLineAttributes(3Xll),
XSetState(3Xll), XSetTile(3Xll)
Guide to the Xlib Library

Subroutines 3-557

XSetCloseDownMode (3X11 )
Name
XSetCloseDownMode, XKillClient - control clients

Syntax
XSetCloseDownMode( display, close_mode)
Display *display;
int close_mode;
XKillClient(display, resource)
Display *display;
XID resource;

Arguments
close mode

Specifies the client close-down mode. You can pass
DestroyAII,RetainPermanent,or
RetainTemporary.

display

Specifies the connection to the X server.

resource

Specifies any resource associated with the client that you
want to destroy or AIITemporary.

Description
The XSetCloseDownMode defines what will happen to the client's
resources at connection close. A connection starts in DestroyAl1 mode.
For information on what happens to the client's resources when the
close_mode argument is RetainPermanent or RetainTemporary, see
section 2.6.
XSetCloseDownMode can generate a BadValue error.
The XKillClient function forces a close-down of the client that created
the resource if a valid resource is specified. If the client has already
terminated in either RetainPermanent or RetainTemporary mode,
all of the client's resources are destroyed. If All Temporary is specified,
the resources of all clients that have terminated in RetainTemporary are
destroyed (see section 2.6). This permits implementation of window
manager facilities that aid debugging. A client can set its close-down mode
to RetainTemporary. If the client then crashes, its windows would not
be destroyed. The programmer can then inspect the application's window tree
and use the window manager to destroy the zombie windows.

3-558 Subroutines

XSetCloseDownMode (3X11 )
XKillClient can generate a BadValue error.

Diagnostics
BadValue

See Also
Guide to the Xlib Library

Subroutines 3-559

XSetCommand (3X11 )
Name
XSetCommand - set command atom

Syntax
XSetCommand(display, w, argv, argc)
Display *display;
Window w;
char **argv;
int argc;

Arguments
argc

Specifies the number of arguments.

argv

Specifies the application's argument list.

display

Specifies the connection to the X server.

Specifies the window.

Description
The XSetCommand function sets the command and arguments used to
invoke the application. (Typically, argv is the argv array of your main
program.)
XSetCommand can generate BadAlloc and BadWindow errors.

Property
WM_COMMAND

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XSetClassHint(3Xll), XSetIconName(3Xll), XSetIconSizeHints(3Xll),
XSetNonnalHints(3Xll), XSetSizeHints(3Xll),
XSetStandardProperties(3Xll), XSetTransientForHint(3Xll),

3-560 Subroutines

XSetCommand (3X11 )
XSetWMHints(3Xll), XSetZoomHints(3Xll), XStoreName(3Xll)
Guide to the Xlib Library

Subroutines 3-561

XSetErrorHandler (3X11 )
Name
XSetErrorHandler, XGetErrorText, XDisplayName, XSetIOErrorHandler,
XGetErrorDatabaseText - default error handlers

Syntax
XSetErrorHandler( handler)
int (* handler) (Display *, XErrorEvent *)

XGetErrorText(display, code, buffer return, length)
Display *display;
int code;
char *buffer return;
int length; char *XDisplayName(string)
char *string;
XSetIOErrorHandler( handler)
int (* handler) (Display *);

XGetErrorDatabaseText(display, name, message, default_string,
buffer return, length)
Dlsplay *display;
char *name, *message;
char *default_string;
char *buffer return;
int length; -

Arguments
buffer_return

Returns the error description.

code

Specifies the error code for which you want to obtain a
description.

default string Specifies the default error message if none is found in the
database.
display

Specifies the connection to the X server.

handler

Specifies the program's supplied error handler.

length

Specifies the size of the buffer.

message

Specifies the type of the error message.

name

Specifies the name of the application.

3-562 Subroutines

XSetErrorHandler (3X11 )
string

Specifies the character string.

Description
Xlib generally calls the program's supplied error handler whenever an error is
received. It is not called on BadName errors from OpenFont,
LookupColor, or AllocNamedColor protocol requests or on BadFont
errors from a QueryFont protocol request. These errors generally are
reflected back to the program through the procedural interface. Because this
condition is not assumed to be fatal, it is acceptable for your error handler to
return. However, the error handler should not call any functions (directly or
indirectly) on the display that will generate protocol requests or that will look
for input events.
The XGetErrorText function copies a null-tenninated string describing
the specified error code into the specified buffer. It is recommended that you
use this function to obtain an error description because extensions to Xlib
may define their own error codes and error strings.
The XDisplayName function returns the name of the display that
XOpenDisplay would attempt to use. If a NULL string is specified,
XDisplayName looks in the environment for the display and returns the
display name that XOpenDisplay would attempt to use. This makes it
easier to report to the user precisely which display the program attempted to
open when the initial connection attempt failed.
The XSetIOErrorHandler sets the fatal I/O error handler. Xlib calls the
program's supplied error handler if any sort of system call error occurs (for
example, the connection to the server was lost). This is assumed to be a fatal
condition, and the called routine should not return. If the I/O error handler
does return, the client process exits.
The XGetErrorDatabaseText function returns a message (or the default
message) from the error message database. Xlib uses this function internally
to look up its error messages. On a UNIX-based system, the error message
database is /usr/lib/Xll/XErrorDB.
The name argument should generally be the name of your application. The
message argument should indicate which type of error message you want.
Xlib uses three predefined message types to report errors (uppercase and
lowercase matter):

XProtoError The protocol error number is used as a string for the message
argument.
XlibMessage

These are the message strings that are used internally by the
library.
Subroutines 3-563

XSetErrorHandler (3X11 )
XRequest

The major request protocol number is used for the message
argument. If no string is found in the error database, the
default_string is returned to the buffer argument.

See Also
XSynchronize(3Xll)
Guide to the Xlib Library

3-564 Subroutines

XSetFillStyle (3X11 )
Name
XSetFillStyle, XSetFillRule - GC convenience routines

Syntax
XSetFillStyle(display, gc, fill_style)
Display *display;
GCgc;
int fill style;

XSetFillRule (display, gc, fill rule)
Display *display;
GCgc;
int fill_rule;

Arguments
display

Specifies the connection to the X server.

fill_rule

Specifies the fill-rule you want to set for the specified GC.
You can pass EvenOddRule or WindingRule.

fill style

Specifies the fill-style you want to set for the specified GC.
You can pass FillSolid, FillTiled, FillStippled,
or FillOpaqueStippled.

Specifies the GC.

Description
The XSetFillStyle function sets the fill-style in the specified GC.
XSetFillStyle can generate BadAlloc, BadGe, and BadValue

errors.
The XSetFillRule function sets the fill-rule in the specified GC.
XSetFillRule can generate BadAlloc, BadGe, and BadValue errors.

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadGe

A value for a GContext argument does not name a defined

GContext.
BadVal ue

Some numeric value falls outside the range of values
Subroutines 3-565

XSetFiliStyle (3X11 )
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.

See Also
XCreateGC(3Xll), XQueryBestSize(3Xll), XSetArcMode(3Xll),
XSetClipOrigin(3Xll), XSetFont(3Xll), XSetLineAttributes(3Xll),
XSetState(3Xll), XSetTile(3Xl1)
Guide to the Xlib Library

3-566 Subroutines

XSetFont (3X11 )
Name
XSetFont - GC convenience routines

Syntax
XSetFont (display, gc, font)
Display *display;
GCgc;
Font font;

Arguments
display

Specifies the connection to the X server.

font

Specifies the font.

Specifies the GC.

Description
The XSetFont function sets the current font in the specified GC.
XSetFont can generate BadAlloc, BadFont, and BadGC errors.

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadFont

A value for a Font or GContext argument does not name a
defined Font.

BadGC

A value for a GContext argument does not name a defined
GContext.

See Also
XCreateGC(3Xll), XQueryBestSize(3Xll), XSetArcMode(3Xll),
XSetClipOrigin(3Xll), XSetFillStyle(3Xll), XSetLineAttributes(3Xl1),
XSetState(3Xll), XSetTile(3Xl1)
Guide to the Xlib Library

Subroutines 3-567

XSetFontPath (3X11 )
Name
XSetFontPath, XGetFontPath, XFreeFontPath - set, get, or free the font
search path

Syntax
XSetFontPath (display, directories, ndirs)
Display *display;
char **directories;
int ndirs;
char **XGetFontPath (display, npaths_return)
Display *display;
int *npaths_return;
XFreeFontPath (list)
char **list;

Arguments
directories

Specifies the directory path used to look for a font. Setting
the path to the empty list restores the default path defined for
the X server.

display

Specifies the connection to the X server.

list

Specifies the array of strings you want to free.

ndirs

Specifies the number of directories in the path.

npaths_return Returns the number of strings in the font path array.

Description
The XSetFontPath function defines the directory search path for font
lookup. There is only one search path per X server, not one per client. The
interpretation of the strings is operating system dependent, but they are
intended to specify directories to be searched in the order listed. Also, the
contents of these strings are operating system dependent and are not intended
to be used by client applications. Usually, the X server is free to cache font
information internally rather than having to read fonts from files. In addition,
the X server is guaranteed to flush all cached information about fonts for
which there currently are no explicit resource IDs allocated. The meaning of
an error from this request is operating system dependent.
3-568 Subroutines

XSetFontPath (3X11 )
XSetFontPath can generate a BadValue error.

The XGetFontPath function allocates and returns an array of strings
containing the search path. When it is no longer needed, the data in the font
path should be freed by using XFreeFontPath.
The XFreeFontPath function frees the data allocated by
XGetFontPath.

Diagnostics
BadValue

See Also
XListFont(3Xll), XLoadFonts(3Xll)
Guide to the Xlib Library

Subroutines 3-569

XSetlconName (3X11 )
Name
XSetIconName, XGetIconName - set or get icon names

Syntax
XSetIconName(display, w, icon name)
Display *display;
Window w;
char *icon_name;
Status XGetIconName(display, w,icon name return)
Display *display;
-Window w;
char **icon_name_return;

Arguments
display

Specifies the connection to the X server.

icon name

Specifies the icon name, which should be a null-terminated
string.

icon name return
Returns a pointer to the window's icon name, which is a
null-terminated string.
W

3-570 Subroutines

Specifies the window.

XSetlconName (3X11 )
Description
The XSetIconName function sets the name to be displayed in a window's
icon.
XSetIconName can generate BadAlloc and BadWindow errors.

The XGetIconName function returns the name to be displayed in the
specified window's icon. If it succeeds, it returns nonzero; otherwise, if no
icon name has been set for the window, it returns zero. If you never assigned
a name to the window, XGetIconName sets icon_name_retum to NULL.
When finished with it, a client must free the icon name string using XFree.
XGet I conName can generate a BadWindow error.

Property
WM_ICON_NAME

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadWindow

A value for a Window argument does not name a defined
Window.

Subroutines 3-571

XSetlconName (3X11 )
See Also
XSetClassHint(3Xll), XSetCommand(3Xll), XSetIconSizeHints(3Xll),
XSetNormalHints(3Xll), XSetSizeHints(3Xll),
XSetStandardProperties(3Xll), XSetTransientForHint(3Xll),
XSetWMHints(3Xll), XSetZoomHints(3Xll), XStoreName(3Xll)
Guide to the Xlib Library

3-572 Subroutines

XSetlconSizeHints (3X11 )
Name
XSetIconSizes, XGetIconSizes - set or get icon size hints

Syntax
XSetIconSizes(display, w, size_list, count)
Display *display;
Window w;
XIconSize *size_list;
int count;
Status XGetIconSizes(display, w, size list return, count return)
Display *display;
- Windoww;
XIconSize ** size list return;
int *count_return-; -

Arguments
display

Specifies the connection to the X server.

count

Specifies the number of items in the size list.

count return

Returns the number of items in the size list.

size list

Specifies a pointer to the size list.

size_list_return Returns a pointer to the size list.
w

Specifies the window.

Description
The XSetlconSizes function is used only by window managers to set the
supported icon sizes.
XSetlconSizes- c-an-generate BadAlloc and BadWindow errors.

The XGetlconSizes function returns zero if a window manager has not
set icon sizes or nonzero otherwise. XGetlconSizes should be called by
an application that wants to find out what icon sizes would be most
appreciated by the window manager under which the application is running.
The application should then use XSetwMHints to supply the window
manager with an icon pixmap or window in one of the supported sizes. To
free the data allocated in size_list_return, use XFree.

Subroutines 3-573

XSetlconSizeHints (3X11)
XGetlconSizes can generate a BadWindow error.

Property
WM_ICON_SIZE

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XSetClassHint(3Xll), XSetCommand(3Xll), XSetIconName(3Xll),
XSetNonnalHints(3Xll), XSetSizeHints(3Xll),
XSetStandardProperties(3Xll), XSetTransientForHint(3Xll),
XSetWMHints(3Xll), XSetZoomHints(3Xll), XStoreName(3Xll)
Guide to the Xlib Library

3-574 Subroutines

XSetlnputFocus (3X11 )
Name
XSetInputFocus, XGetInputFocus - control input focus

Syntax
XSetInputFocus (display, focus, revert_to, time)
Display *display;
Window focus;
int revert to;
Time time;
XGetInputFocus( display, focus_return, revert_to_return)
Display *display;
Window *focus return;
int *revert_to_return;

Arguments
display

Specifies the connection to the X server.

focus

Specifies the window, PointerRoot, or None.

focus_return

Returns the focus window, PointerRoot, or None.

revert to

Specifies where the input focus reverts to if the window
becomes not viewable. You can pass RevertToParent,
RevertToPointerRoot, or RevertToNone.

revert to return
Returns the current focus state (RevertToParent,
RevertToPointerRoot, or RevertToNone).
time

Specifies the time. You can pass either a timestamp or
Current Time.

Description
The XSetlnputFocus function changes the input focus and the lastfocus-change time. It has no effect if the specified time is earlier than the
current last-focus-change time or is later than the current X server time.
Otherwise, the last-focus-change time is set to the specified time
(CurrentTime is replaced by the current X server time).
XSetlnputFocus causes the X server to generate Focusln and
FocusOut events.

Subroutines 3-575

XSetlnputFocus (3X11 )
Depending on the focus argument, the following occurs:
•

If focus is None, all keyboard events are discarded until a new focus
window is set, and the revert_to argument is ignored.

•

If focus is a window, it becomes the keyboard's focus window. If a
generated keyboard event would normally be reported to this window
or one of ~ts inferiors, the event is reported as usual. Otherwise, the
event is reported relative to the focus window.

•

If focus is PointerRoot, the focus window is dynamically taken to
be the root window of whatever screen the pointer is on at each
keyboard event. In this case, the revert_to argument is ignored.

The specified focus window must be viewable at the time
XSetlnputFocus is called, or a BadMatch error results. If the focus
window later becomes not viewable, the X server evaluates the revert_to
argument to determine the new focus window as follows:
•

If revert_to is Revert ToParent, the focus reverts to the parent (or
the closest viewable ancestor), and the new revert_to value is taken to
be Revert ToNone.

•

If revert_to is Revert ToPointerRoot or Revert ToNone, the
focus reverts to PointerRoot or None, respectively. When the
focus reverts, the X server generates Focusln and FocusOut
events, but the last-focus-change time is not affected.

XSetlnputFocus can generate BadMatch, BadValue, and
BadWindowerrors.
The XGetlnputFocus function returns the focus window and the current
focus state.

Diagnostics
BadVal ue

BadWindow

A value for a Window argument does not name a defined
Window.

3-576 Subroutines

XSetlnputFocus (3X11 )
See Also
XWarpPointer(3Xll)
Guide to the Xlib Library

Subroutines 3-5n

XSetLineAttribute (3X11 )
Name
XSetLineAttribute, XSetDashes - GC convenience routines

Syntax
XSetLineAttributes(display, gc, line_width, line_style, cap_style, join_style)
Display *display;
GCgc;
unsigned int line width;
int line_style; int cap style;
int join__style;
XSetDashes(display, gc, dash_offset, dash_list, n)
Display *display;
GCgc;
int dash offset;
char dash_list[] ;
int n;

Arguments
Specifies the line-style and cap-style you want to set for the
specified GC. You can pass CapNotLast, CapButt,
CapRound, or CapProjecting.

dash list

Specifies the dash-list for the dashed line-style you want to
set for the specified GC.

dash offset

Specifies the phase of the pattern for the dashed line-style
you want to set for the specified GC.

display

Specifies the connection to the X server.

Specifies the GC.

join_style

Specifies the line join-style you want to set for the specified
GC. You can pass JoinMiter·, JoinRound, or
JoinBevel.
Specifies the line-style you want to set for the specified GC.
You can pass LineSolid, LineOnOffDash, or
LineDoubleDash.

line width

Specifies the line-width you want to set for the specified GC.

Specifies the number of elements in dash_list.

3-578 Subroutines

XSetLineAttribute (3X11 )
Description
The XSetLineAttributes function sets the line drawing components in
the specified GC.
XSetLineAttributes can generate BadAlloc, BadGe, and
BadVal ue errors.

The XSetDashes function sets the dash-offset and dash-list attributes for
dashed line styles in the specified GC. There must be at least one element in
the specified dash_list, or a BadVal ue error results. The initial and
alternating elements (second, fourth, and so on) of the dash_list are the even
dashes, and the others are the odd dashes. Each element specifies a dash
length in pixels. All of the elements must be nonzero, or a BadValue error
results. Specifying an odd-length list is equivalent to specifying the same list
concatenated with itself to produce an even-length list.
The dash-offset defines the phase of the pattern, specifying how many pixels
into the dash-list the pattern should actually begin in any single graphics
request. Dashing is continuous through path elements combined with a joinstyle but is reset to the dash-offset each time a cap-style is applied at a line
endpoint.
The unit of measure for dashes is the same for the ordinary coordinate
system. Ideally, a dash length is measured along the slope of the line, but
implementations are only required to match this ideal for horizontal and
vertical lines. Failing the ideal semantics, it is suggested that the length be
measured along the major axis of the line. The major axis is defined as the x
axis for lines drawn at an angle of between -45 and +45 degrees or between
315 and 225 degrees from the x axis. For all other lines, the major axis is
the y axis.
XSetDashes can generate BadAlloc, BadGe, and BadValue errors.

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadGe

A value for a GContext argument does not name a defined
GContext.

BadValue

Subroutines 3-579

XSetLineAttribute {3X11 }
alternatives can generate this error.

See Also
XCreateGC(3Xll), XQueryBestSize(3Xll), XSetArcMode(3Xll),
XSetClipOrigin(3Xll), XSetFillStyle(3Xll), XSetFont(3Xll),
XSetState(3Xll), XSetTile(3Xll)
Guide to the Xlib Library

3-580 Subroutines

XSetNormalHints (3X11 )
Name
XSetNormalHints, XGetNormalHints - set or get normal state hints

Syntax
XSetNormalHints (display, w, hints)
Display *display;
Window w;
XSizeHints *hints;
Status XGetNormalHints(display, w, hints return)
Display *display;
Window w;
XSizeHints *hints_return;

Arguments
display

Specifies the connection to the X server.

hints

Specifies a pointer to the size hints for the window in its
normal state.

hints return

Returns the size hints for the window in its normal state.

Specifies the window.

Description
The XSetNormalHints function sets the size hints structure 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 that wants to move or resize itself should call
XSetNormalHints and specify its new desired location and size as well
as making direct Xlib calls to move or resize. This is because window
managers may ignore redirected configure requests, but they pay attention to
property changes.
To set size hints, an application not only must assign values to the
appropriate members in the hints structure but also must set the flags member
of the structure to indicate which information is present and where it came
from. A call to XSetNormalHints is meaningless, unless the flags
member is set to indicate which members of the structure have been assigned
values.

Subroutines 3-581

XSetNormalHints (3X11 )
XSetNormalHints can generate BadAlloc and BadWindow errors.

The XGetNormalHints function returns the size hints for a window in its
normal state. It returns a nonzero status if it succeeds or zero if the
application specified no normal size hints for this window.
XGetNormalHints can generate a BadWindow error.

Property
WM_NORMAL_HINTS

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XSetCommand(3Xll), XSetIconName(3Xll), XSetIconSizeHints(3Xl1),
XSetSizeHints(3Xll), XSetStandardProperties(3Xll), XSetWMHints(3Xll),
XSetZoomHints(3Xll), XStoreName(3Xll)
Guide to the Xlib Library

3-582 Subroutines

XSetPointerMapping (3X11 )
Name
XSetPointerMapping, XGetPointerMapping - manipulate pointer settings

Syntax
int XSetPointerMapping (display, map, nmap)
Display *display;
unsigned char map [] ;
int nmap;
int XGetPointerMapping(display, map_return, nmap)
Display *display;
unsigned char map_return [] ;
int nmap;

Arguments
display

Specifies the connection to the X server.

map

Specifies the mapping list.

map_return

Returns the mapping list.

nmap

Specifies the number of items in the mapping list.

Description
The XSetPointerMapping function sets the mapping of the pointer. If it
succeeds, the X server generates a MappingNotify event, and
XSetPointerMapping returns MappingSuccess. Elements of the list
are indexed starting from one. The length of the list must be the same as
XGetPointerMapping would return, or a BadValue error results. The
index is a core button number, and the element of the list defines the
effective number. A zero element disables a button, and elements are not
restricted in value by the number of physical buttons. However, no two
elements can have the same nonzero value, or a BadVal ue error results. If
any of the buttons to be altered are logically in the down state,
XSetPointerMapping returns MappingBusy, and the mapping is not
changed.
XSetPointerMapping can generate a BadVal ue error.

The XGetPointerMapping function returns the current mapping of the
pointer. Elements of the list are indexed starting from one.
XGetPointerMapping returns the number of physical buttons actually on
the pointer. The nominal mapping for a pointer is the identity mapping:
Subroutines 3-583

XSetPointerMapping (3X11 )
map[i]=i. The nmap argument specifies the length of the array where the
pointer mapping is returned, and only the first nmap elements are returned in
map_return.

Diagnostics
BadValue

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.

See Also
XChangeKeyboardControl(3Xll), XChangeKeyboardMapping(3Xl1)
Guide to the Xlib Library

3-584 Subroutines

XSetScreenSaver (3X11 )
Name
XSetScreenSaver, XForceScreenSaver, XActivateScreenSaver,
XResetScreenSaver, XGetScreenSaver - manipulate the screen saver

Syntax
XSetScreenSaver( display, timeout, interval, prefer_blanking,
allow exposures)
DIsplay *display;
int timeout, interval;
int prefer blanking;
int allowj!xposures;
XForceScreenSaver( display, mode)
Display *display;
int mode;
XActivateScreenSaver( display)
Display *display;
XResetScreenSaver( display)
Display *display;
XGetScreenSaver( display, timeout_return, interval_return,
prefer_blanking_return, allow_exposures_return)
Display *display;
int *timeout return, *interval return;
int *prefer_blanking_return; int *allow_exposures_return;

Arguments
allow exposures
Specifies the screen save control values. You can pass
DontAllowExposures,AllowExposures,or
DefaultExposures.
allow exposures return
Returns the current screen save control value
(DontAllowExposures,AllowExposures,or
Defaul tExposures).
display

Specifies the connection to the X server.

interval

Specifies the interval between screen saver alterations.

Subroutines 3-585

XSetScreenSaver (3X11 )
interval return Returns the interval between screen saver invocations.
mode

Specifies the mode that is to be applied. You can pass
ScreenSaverActi ve or ScreenSaverReset.

prefer_blanking
Specifies how to enable screen blanking. You can pass
DontPreferBlanking,PreferBlanking,or
Defaul tBlanking.
prefer blanking return
Returns the current screen blanking preference
(DontPreferBlanking,PreferBlanking,or
Defaul tBlanking).
timeout

Specifies the timeout, in seconds, until the screen saver turns
on.

timeout return Returns the timeout, in minutes, until the screen saver turns
on.

Description
Timeout and interval are specified in seconds. A timeout of 0 disables the
screen saver, and a timeout of -1 restores the default. Other negative values
generate a BadValue error. If the timeout value is nonzero,
XSetScreenSaver enables the screen saver. An interval of 0 disables the
random-pattern motion. If no input from devices (keyboard, mouse, and so
on) is generated for the specified number of timeout seconds once the screen
saver is enabled, the screen saver is activated.
For each screen, if blanking is preferred and the hardware supports video
blanking, the screen simply goes blank. Otherwise, if either exposures are
allowed or the screen can be regenerated without sending Expose events to
clients, the screen is tiled with the root window background tile randomly
re-origined each interval minutes. Otherwise, the screens' state do not
change, and the screen saver is not activated. The screen saver is
deactivated, and all screen states are restored at the next keyboard or pointer
input or at the next call to XForceScreenSaver with mode
ScreenSaverReset.
If the server-dependent screen saver method supports periodic change, the
interval argument serves as a hint about how long the change period should
be, and zero hints that no periodic change should be made. Examples of
ways to change the screen include scrambling the colormap periodically,
moving an icon image around the screen periodically, or tiling the screen
with the root window background tile, randomly re-origined periodically.
3-586 Subroutines

XSetScreenSaver (3X11 )
XSetScreenSaver can generate a BadVal ue error.
If the specified mode is ScreenSaverActi ve and the screen saver
currently is deactivated, XForceScreenSaver activates the screen saver
even if the screen saver had been disabled with a timeout of zero. If the
specified mode is ScreenSaverReset and the screen saver currently is
enabled, XForceScreenSaver deactivates the screen saver if it was
activated, and the activation timer is reset to its initial state (as if device input
had been received).
XForceScreenSaver can generate a BadValue error.

The XActi vateScreenSaver function activates the screen saver.
The XResetScreenSaver function resets the screen saver.
The XGetScreenSaver function gets the current screen saver values.

Subroutines 3-587

XSetScreenSaver (3X11 )
Diagnostics
BadValue

See Also
Guide to the Xlib Library

3-588 Subroutines

XSetSelectionOwner (3X11 )
Name
XSetSelectionOwner, XGetSelectionOwner, XConvertSelection - manipulate
window selection

Syntax
XSetSelectionOwner(display, selection, owner, time)
Display *display;
Atom selection;
Window owner;
Time time;
Window XGetSelectionOwner(display, selection)
Display *display;
Atom selection;
XConvertSelection(display, selection, target, property, requestor, time)
Display *display;
Atom selection, target;
Atom property;
Window requestor;
Time time;

Arguments
display

Specifies the connection to the X server.

owner

Specifies the owner of the specified selection atom. You can
pass a window or None.

property

Specifies the property name. You also can pass None.

requestor

Specifies the requestor.

selection

Specifies the selection atom.

target

Specifies the target atom.

time

Specifies the time. You can pass either a timestamp or
Current Time.

Description
The XSetSelectionOwner function changes the owner and last-change
time for the specified selection and has no effect if the specified time is
earlier than the current last-change time of the specified selection or is later
than the current X server time. Otherwise, the last-change time is set to the
Subroutines 3-589

XSetSelectionOwner (3X11 )
specified time, with CurrentTime replaced by the current server time. If
the owner window is specified as None, then the owner of the selection
becomes None (that is, no owner). Otherwise, the owner of the selection
becomes the client executing the request.
If the new owner (whether a client or None) is not the same as the current
owner of the selection and the current owner is not None, the current owner
is sent a SelectionClear event. If the client that is the owner of a
selection is later terminated (that is, its connection is closed) or if the owner
window it has specified in the request is later destroyed, the owner of the
selection automatically reverts to None, but the last-change time is not
affected. The selection atom is uninterpreted by the X server.
XGetSelectionOwner returns the owner window, which is reported in
SelectionRequest and SelectionClear events. Selections are
global to the X server.
XSetSelectionOwner can generate BadAtom and BadWindow errors.

The XGetSelectionOwner function returns the window ID associated
with the window that currently owns the specified selection. If no selection
was specified, the function returns the constant None. If None is returned,
there is no owner for the selection.
XGetSelectionOwner can generate a BadAtom error.
XConvertSelection requests that the specified selection be converted to
the specified target type:

•

If the specified selection has an owner, the X server sends a
SelectionRequest event to that owner.

•

If no owner for the specified selection exists, the X server generates a
SelectionNotify event to the requestor with property None.

In either event, the arguments are passed on unchanged. There are two
predefined selection atoms: PRIMARY and SECONDARY.
XConvertSelection can generate BadAtom and BadWindow errors.

Diagnostics
BadAtom

A value for an Atom argument does not name a defined
Atom.

BadWindow

A value for a Window argument does not name a defined
Window.

3-590 Subroutines

XSetSelectionOwner {3X11 }
See Also
Guide to the Xlib Library

Subroutines 3-591

XSetSizeHints (3X11 )
Name
XSetSizeHints, XGetSizeHints - set or get window size hints

Syntax
XSetSizeHints (display, w, hints, property)
Display *display;
Window w;
XSizeHints *hints;
Atom property;
Status XGetSizeHints(display, w, hints return, property)
Display *display;
Windoww;
XSizeHints *hints return;
Atom property; -

Arguments
display

Specifies the connection to the X server.

hints

Specifies a pointer to the size hints.

hints return

Returns the size hints.

property

Specifies the property name.

Specifies the window.

Description
The XSetSizeHints function sets the XSizeHints structure for the
named property and the specified window. This is used by
XSetNormalHints and XSetZoomHints, and can be used to set the
value of any property of type WM_SIZE_HINTS. Thus, it may be useful if
other properties of that type get defined.
XSetSizeHints can generate BadAlloc, BadAtom, and BadWindow
errors.
XGetSizeHints returns the XSizeHints structure for the named
property and the specified window. This is used by XGetNormalHints
and XGetZoomHints. It also can be used to retrieve the value of any
property of type WM_SIZE_HINTS. Thus, it may be useful if other
properties of that type get defined. XGetSizeHints returns a nonzero
status if a size hint was defined or zero otherwise.

3-592 Subroutines

XSetSizeHints (3X11 )
XGetSizeHints can generate BadAtom and BadWindow errors.

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadAtom

A value for an Atom argument does not name a defined
Atom.

BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XSetClassHint(3Xll), XSetCommand(3Xll), XSetIconName(3Xl1),
XSetIconSizeHints(3Xll), XSetNormalHints(3Xll),
XSetStandardProperties(3X 11), XSetTransientForHint(3X 11),
XSetWMHints(3Xll), XSetZoomHints(3Xll), XStoreName(3Xll)
Guide to the Xlib Library

Subroutines 3-593

XSetStandardColormap (3X11 )
Name
XSetStandardColormap, XGetStandardColormap - set or get standard
colormaps

Syntax
XSetStandardColormap(display, w, c%rmap, property)
Display *display;
Window w;
XStandardColormap *colormap;
Atom property;
/* RGB_BEST_MAP, etc. */

Status XGetStandardColormap( display, w, colormap_return, property)
Display *display;
Window w;
XStandardColormap *colormap_return;
Atom property;
/* RGB_BEST_MAP, etc. */

Arguments
c%rmap

Specifies the colormap.

colormap return
Returns the colormap associated with the specified atom.
display

Specifies the connection to the X server.

property

Specifies the property name.

Specifies the window.

Description
The XSetStandardColormap function usually is only used by window
managers. To create a standard colormap, follow this procedure:
1.

Open a new connection to the same server.

Grab the server.

See if the property is on the property list of the root window for the
screen.

If the desired property is not present:
•

Create a colormap (not required for RGB_DEFAULT_MAP)

•

Determine the color capabilities of the display.

3-594 Subroutines

XSetStandardColormap (3X11 )
•

Call XAllocColorPlanes or XAllocColorCells to
allocate cells in the colormap.

•

Call XStoreColors to store appropriate color values in the
colormap.

•

Fill in the descriptive members in the XStandardColormap
structure.

•
•

Attach the property to the root window.
Use XSetCloseDownMode to make the resource permanent.

S.
Ungrab the server.
XSetStandardColormap can generate BadAlloc, BadAtom, and
BadWindowerrors.
The XGetStandardColormap function returns the colormap definition
associated with the atom supplied as the property argument. For example, to
fetch the standard GrayScale colormap (or a display, you use
XGetStandardColormap with the following syntax:
XGetStandardColormap(dpy, DefaultRootWindow(dpy), &cmap, XA_RGB_GRAY_MAP
Once you have fetched a standard colormap, you can use it to convert RGB
values into pixel values. For example, given an XStandardColormap
structure and floating-point RGB coefficients in the range 0.0 to 1.0, you can
compose pixel values with the following C expression:
pixel =base_pixel
+ «unsigned long) (0.5 + r * red_max» * red_mult
+ «unsigned long) (0.5 + g * green_max» * green_mult
+ «unsigned long) (0.5 + b * blue_max» * blue_mult;
The use of addition rather than logical OR for composing pixel values
permits allocations where the RGB value is not aligned to bit boundaries.
XGetStandardColormap can generate BadAtom and BadWindow
errors.

Diagnostics
BadAlloc
BadAtom
BadWindow

The server failed to allocate the requested resource or server
memory.
A value for an Atom argument does not name a defined
Atom.
A value for a Window argument does not name a defined
Window.
Subroutines 3-595

XSetStandardColormap (3X11 )
See Also
Guide to the Xlib Library

3-596 Subroutines

XSetStandardProperties (3X11 )
Name
XSetStandardProperties - set standard window manager properties

Syntax
XSetStandardProperties(display, w, window_name, icon_name, iconyixmap,
argv, argc, hints)
Display *display;
Windoww;
char *window_name;
char *icon name;
Pixmap iconyixmap;
char **argv;
int argc;
XSizeHints *hints;

Arguments
argc

Specifies the number of arguments~

argv

Specifies the application's argument list.

display

Specifies the connection to the X server.

hints

Specifies a pointer to the size hints for the window in its
normal state.

icon name

Specifies the icon name, which should be a null-terminated
string.

iconyixmap

Specifies the bitmap that is to be used for the icon or None.

Specifies the window.

window name Specifies the window name, which should be a nullterminated string.

Description
The XSetStandardProperties function provides a means by which
simple applications set the most essential properties with a single call.
XSetStandardProperties should be used to give a window manager
some information about your program's preferences. It should not be used by
applications that need to communicate more information than is possible with
XSetStandardProperties. (Typically, argv is the argv array of your
main program.)

Subroutines 3-597

XSetStandardProperties (3X11 )
XSetStandardProperties can generate BadAlloc and BadWindow
errors.

Properties
WM_NAME, WM_ICON_NAME, WM_HINTS, WM_COMMAND, and
WM_NORMALHINTS

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XSetClassHint(3Xll), XSetCommand(3Xll), XSetIconName(3Xl1),
XSetIconSizeHints(3Xll), XSetNormalHints(3Xll), XSetSizeHints(3Xll),
XSetTransientForHint(3Xll), XSetWMHints(3Xl1), XSetZoomHints(3Xl1),
XStoreName(3Xl1)
Guide to the Xlib Library

3-598 Subroutines

XSetState (3X11) ,
Name
XSetState, XSetFunction, XSetPlaneMask, XSetForeground,
XSetBackground - GC convenience routines

Syntax
XSetState (display, gc, foreground, background, function, plane_mask)
Display *display;
GCgc;
unsigned long foreground, background;
int function;
unsigned long plane_mask;
XSetFunction (display, gc, function)
Display *display;
GCgc;
int function;

XSetPlaneMask(display, gc, plane mask)
Display *display;
GCgc;
unsigned long plane_mask;
XSetForeground(display, gc, foreground)
Display *display;
GCgc;
unsigned long foreground;
XSetBackground(display, gc, background)
Display *display;
GCgc;
unsigned long background;

Arguments
background

Specifies the background you want to set for the specified
GC.

display

Specifies the connection to the X server.

foreground

Specifies the foreground you want to set for the specified
GC.

function

Specifies the function you want to set for the specified GC.

Specifies the GC.

Subroutines 3-599

XSetState(3X11 }
Specifies the plane mask.

Description
The XSetState function sets the foreground, background, plane mask, and
function components for the specified GC.
XSetState can generate BadAlloc, BadGe, and BadValue errors.
XSetFunction sets a specified value in the specified GC.
XSetFunction can generate BadAlloc, BadGe, and BadValue errors.

The XSetp laneMask function sets the plane mask in the specified GC.
XSetPlaneMask can generate BadAlloc and BadGe errors.

The XSetForeground function sets the foreground in the specified GC.
XSetForeground can generate BadAlloc and BadGe errors.

The XSetBackground function sets the background in the specified GC.
XSetBackground can generate BadAlloc and BadGe errors.

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadGe

A value for a GContext argument does not name a defined
GContext.

BadValue

See Also
XCreateGC(3Xll), XQueryBestSize(3Xll), XSetArcMode(3Xl1),
XSetClipOrigin(3Xll), XSetFillStyle(3Xll), XSetFont(3Xll),
XSetLineAttributes(3Xll), XSetTile(3Xll)
Guide to the Xlib Library

3-600 Subroutines

XSetTile (3X11 )
Name
XSetTile, XSetStipple, XSetTSOrigin - GC convenience routines

Syntax
XSetTile (display, gc, tile)
Display *display;
GCgc;
Pixmap tile;

XSetStipple(display, gc, stipple)
Display *display;
GCgc;
Pixmap stipple;

XSetTSOrigin(display, gc, ts_x_origin, tsy_origin)
Display *display;
GCgc;
int ts_x_origin, tsy_origin;

Arguments
display

Specifies·the connection to the X server.

Specifies the GC.

stipple

Specifies the stipple you want to set for the specified GC.

tile

Specifies the fill tile you want to set for the specified GC.

ts_x_origin
tsy_origin

Specify the x and y coordinates of the tile and stipple origin.

Description
The XSetTile function sets the fill tile in the specified GC. The tile and
GC must have the same depth, or a BadMatch error results.
XSetTile can generate BadAlloc, BadGC, BadMatch, and
BadP ixmap errors.

The XSetStipple function sets th~ stipple in the specified GC. The
stipple and GC must have the same depth, or a BadMatch error results.
XSetStipple can generate BadAlloc, BadGC, BadMatch, and
BadP ixmap errors.

Subroutines 3-601

XSetTile (3X11)
The XSetTSOrigin function sets the tile/stipple origin in the specified GC.
When graphics requests call for tiling or stippling, the parent's origin will be
interpreted relative to whatever destination drawable is specified in the
graphics request.
XSetTSOrigin can generate BadAlloc and BadGC errors.

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadGC

A value for a GContext argument does not name a defined
GContext.

BadMatch

Some argument or pair of arguments has the correct type and
range but fails to match in some other way required by the
request.

BadPixmap

A value for a Pixmap argument does not name a defined
Pixmap.

See Also
XCreateGC(3Xll), XQueryBestSize(3Xll), XSetArcMode(3Xll),
XSetClipOrigin(3Xll), XSetFillStyle(3Xll), XSetFont(3Xll),
XSetLineAttributes(3Xll), XSetState(3Xll)
Guide to the Xlib Library

3-602 Subroutines

XSetTransientForHint (3X11 )
Name
XSetTransientForHint, XGetTransientForHint - set or get transient for hint

Syntax
XSetTransientForHint(display, w, prop_window)
Display *display;
Window w;
Window prop_window;
Status XGetTransientForHint( display, w, prop window return)
Display *display;
-Window w;
Window *prop_window_return;

Arguments
display

Specifies the connection to the X server.

Specifies the window.

prop_window

Specifies the window that the WM_TRANSIENT_FOR
property is to be set to.

prop window return
- Returns the WM_TRANSIENT_FOR property of the
specified window.

Description
The XSet TransientForHint function sets the WM_TRANSIENT_FOR
property of the specified window to the specified prop_window.
XSetTransientForHint can generate BadAlloc and BadWindow
errors.

The XGet TransientForHint function returns the
WM_TRANSIENT_FOR property for the specified window.
XGetTransientForHint can generate a BadWindow error.

Property
WM_TRANSIENT_FOR

Subroutines 3-603

XSetTransientForHint (3X11 )
Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XSetClassHint(3Xll), XSetCommand(3Xll), XSetIconName(3Xll),
XSetIconSizeHints(3Xll), XSetNormalHints(3Xll), XSetSizeHints(3Xll),
XSetStandardProperties(3Xll), XSetWMHints(3Xl1),
XSetZoomHints(3Xll), XStoreName(3Xll)
Guide to the Xlib Library

3-604 Subroutines

XSetWMHints (3X11 )
Name
XSetWMHints, XGetWMHints - set or get window manager hints

Syntax
XSetWMHints(display, w, wmhints)
Display *display;
Windoww;
XWMHints *wmhints;
XWMHints *XGetWMHints(display, w)
Display *display;
Windoww;

Arguments
display

Specifies the connection to the X server.

Specifies the window.

wmhints

Specifies a pointer to the window manager hints.

Description
The XSetWMHints function sets the window manager hints that include
icon information and location, the initial state of the window, and whether
the application relies on the window manager to get keyboard input.
XSetWMHints can generate BadAlloc and BadWindow errors.

The XGetWMHints function reads the window manager hints and returns
NULL if no WM_HINTS property was set on the window or a pointer to a
XWMHints structure if it succeeds. When finished with the data, free the
space used for it by calling XFree.
XGetWMHints can generate a BadWindow error.

Property
WM_HINTS

Subroutines 3-605

XSetWMHints (3X11 )
Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XSetClassHint(3Xll), XSetCommand(3Xll), XSetIconName(3Xll),
XSetIconSizeHints(3Xll), XSetNormalHints(3Xll), XSetSizeHints(3Xll),
XSetStandardProperties(3Xll), XSetTransientForHint(3Xll),
XSetZoomHints(3Xll), XStoreName(3Xll)
Guide to the Xlib Library

3-606 Subroutines

XSetZoomHints (3X11 )
Name
XSetZoomHints, XGetZoomHints - set or get zoom state hints

Syntax
XSetZoomHints (display, w, zhints)
Display *display;
Windoww;
XSizeHints *zhints;
Status XGetZoomHints (display, w, zhints_return)
Display *display;
Window w;
XSizeHints *zhints_return;

Arguments
display

Specifies the connection to the X server.

Specifies the window.

zhints

Specifies a pointer to the zoom hints.

zhints return

Returns the zoom hints.

Description
Many window managers think of windows in one of three states: iconic,
normal, or zoomed. The XSetZoornHints function provides the window
manager with information for the window in the zoomed state.
XSetZoornHints can generate BadAlloc and BadWindow errors.

The XGetZoornHints function returns the size hints for a window in its
zoomed state. It returns a nonzero status if it succeeds or zero if the
application specified no zoom size hints for this window.
XGetZoornHints can generate a BadWindow error.

Property
WM_ZOOM_HINTS

Subroutines 3-607

XSetZoomHints (3X11 )
Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XSetClassHint(3Xll), XSetCommand(3Xll), XSetIconName(3Xl1),
XSetIconSizeHints(3Xll), XSetNormalHints(3Xl1), XSetSizeHints(3Xll),
XSetStandardProperties(3Xl1), XSetTransientForHint(3Xl1),
XSetWMHints(3Xll), XStoreName(3Xll)
Guide to the Xlib Library

3-608 Subroutines

XStartStat (3X11 )
Name
XStartStat, XStopStat, XPrintStat - start, stop, or display process statistics

Syntax
XStartStat(display)
Display *display;
XStopStat (display)
Display *display;
XPrintStat(display, file)
Display *display;
FILE file;

Arguments
display

Specifies the connection to the X server.

file

Specifies the file to which the statistics are to be written.

Description
The XStartStat function turns on client-side statistics gathering mode.
The XStartStop function turns off client-side statistics gathering mode.
The XPrintStat function write the client-side statistics to the specified
file. If file is not stdout or stderr, you must open the file before
XPrintStat can write the statistics to it.

See Also
Guide to the Xlib Library

Subroutines 3-609

XStoreBytes (3X11 )
Name
XStoreBytes, XStoreBuffer, XFetchBytes, XFetchBuffer, XRotateBuffersmanipulate cut and paste buffers

Syntax
XStoreBytes (display, bytes, nbytes)
Display *display;
char *bytes;
int nbytes;
XStoreBuffer( display, bytes, nbytes, buffer)
Display *display;
char *bytes;
int nbytes;
int buffer;
char *XFetchBytes(display, nbytes_return)
Display *display;
int *nbytes_return;
char *XFetchBuffer(display, nbytes return, buffer)
Display *display;
int *nbytes return;
int buffer; XRotateBuffers (display, rotate)
Display *display;
int rotate;

Arguments
buffer

Specifies the buffer in which you want to store the bytes or
from which you want the· stored data returned.

bytes

Specifies the bytes, which are not necessarily ASCII or nullterminated.

display

Specifies the connection to the X server.

nbytes

Specifies the number of bytes to be stored.

nbytes_return

Returns the number of bytes in the buffer.

rotate

Specifies how much to rotate the cut buffers.

3-610 Subroutines

XStoreBytes (3X11 )
Description
Note that the cut buffer's contents need not be text, so zero bytes are not
special. The cut buffer's contents can be retrieved later by any client calling
XFetchBytes.
XStoreBytes can generate a BadAlloc error.

If the property for the buffer has never been created, a BadAtom error
results.
XStoreBuffer can generate BadAlloc and BadAtom errors.

The XFetchBytes function returns the number of bytes in the
nbytes_return argument, if the buffer contains data. Otherwise, the function
returns NULL and sets nbytes to O. 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 zero bytes and may not
terminate with a null byte.
The XFetchBuffer function returns zero to the nbytes_retum argument if
there is no data in the buffer.
XFetchBuffer can generate a BadValue error.

The XRotateBuffers function rotates the cut buffers, such that buffer 0
becomes buffer n, buffer 1 becomes n + 1 mod 8, and so on. This cut buffer
numbering is global to the display. Note that XRotateBuffers generates
BadMat ch errors if any of the eight buffers have not been created.
XRotateBuffers can generate a BadMatch error.

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadAtom

A value for an Atom argument does not name a defined
Atom.

BadMatch

Some argument or pair of arguments has the correct type and
range but fails to match in some other way required by the
request.

BadValue

Subroutines 3-611

XStoreBytes (3X11 )
alternatives can generate this error.

See Also
Guide to the Xlib Library

3-612 Subroutines

XStoreColors (3X11 )
Name
XStoreColors, XStoreColor, XStoreNamedColor - set colors

Syntax
XStoreColors(display, colormap, color, ncolors)
Display *display;
Colormap colormap;
XColor color[];
int ncolors;
XStoreColor( display, colormap, color)
Display *display;
Colormap colormap;
XColor *color;
XStoreNamedColor( display, colormap, color, pixe I, flags)
Display *display;
Colormap colormap;
char *color;
unsigned long pixel;
intflags;

Arguments
color

Specifies the pixel and RGB values or the color name string
(for example, red).

color

Specifies an array of color definition structures to be stored.

colormap

Specifies the colormap.

display

Specifies the connection to the X server.

flags

Specifies which red, green, and blue components are set.

ncolors

Specifies the number of XColor structures in the color
definition array.

pixel

Specifies the entry in the colonnap.

Description
The XStoreColors function changes the colormap entries of the pixel
values specified in the pixel members of the XColor structures. You
specify which color components are to be changed by setting DoRed,
DoGreen, and/or DoBl ue in the flags member of the XColor structures.
Subroutines 3-613

XStoreColors (3X11 )
If the colonnap is an installed map for its screen, the changes are visible
immediately. XStoreColors changes the specified pixels if they are
allocated writable in the colonnap by any client, even if one or more pixels
generates an error. If a specified pixel is not a valid index into the colonnap,
a BadValue error results. If a specified pixel either is unallocated or is
allocated read-only, a BadAccess error results. If more than one pixel is in
error, the one that gets reported is arbitrary.
XStoreColors can generate BadAccess, BadColor, and BadValue
errors.

The XStoreColor function changes the colonnap entry of the pixel value
specified in the pixel member of the XColor structure. You specified this
value in the pixel member of the XColor structure. This pixel value must
be a read/write cell and a valid index into the colonnap. If a specified pixel
is not a valid index into the colonnap, a BadVal ue error results.
XStoreColor also changes the red, green, and/or blue color components.
You specify which color components are to be changed by setting DoRed,
DoGreen, and/or DoBl ue in the flags member of the XColor structure. If
the colonnap is an installed map for its screen, the changes are visible
immediately.
XStoreColor can generate BadAccess, BadColor, and BadValue
errors.

The XStoreNamedColor function looks up the named color with respect
to the screen associated with the colonnap and stores the result in the
specified colonnap. The pixel argument determines the entry in the
colonnap. The flags argument determines which of the red, green, and blue
components are set. You can set this member to the bitwise inclusive OR of
the bits DoRed, DoGreen, and DoBl ue. If the specified pixel is not a
valid index into the colonnap, a BadValue error results. If the specified
pixel either is unallocated or is allocated read-only, a BadAccess error
results. You should use the ISO Latin-l encoding; uppercase and lowercase
do not matter.
XStoreNamedColor can generate BadAccess, BadColor, BadName,
and BadVal ue errors.

Diagnostics
BadAccess

A client attempted to free a color map entry that it did not
already allocate.

BadAccess

A client attempted to store into a read-only color map entry.

3-614 Subroutines

XStoreColors (3X11 )
BadColor

A value for a Colormap argument does not name a defined
Colormap.

BadName

A font or color of the specified name does not exist.

BadValue

See Also
XAllocColor(3Xll), XCreateColormap(3Xll), XQueryColor(3Xl1)
Guide to the Xlib Library

Subroutines 3-615

XStoreName (3X11 )
Name
XStoreName, XFetchName - set or get window names

Syntax
XStoreName( display, W,. window name)
Display *display;
Window w;
char *window_name;
Status XFetchName(display, w, window name return)
-Display *display;
Window w;
char **window_name_return;

Arguments
display

Specifies the connection to the X server.

Specifies the window.

window name Specifies the window name, which should be a nullterminated string.
window name return
- Returns a pointer to the window name, which is a nullterminated string.

Description
The XStoreName function assigns the name passed to window_name to the
specified window. A window manager can display the window name in
some prominent place, such as the title bar, to allow users to identify
windows easily. Some window managers may display a window's name in
the window's icon, although they are encouraged to use the window's icon
name if one is provided by the application.
XStoreName can generate BadAlloc and BadWindow errors.

The XFetchName function returns the name of the specified window. If it
succeeds, it returns nonzero; otherwise, if no name has been set for the
window, it returns zero. If the WM_NAME property has not been set for
this window, XFetchName sets window_uame_return to NULL. When
finished with it, a client must free the window name string using XFree.

3-616 Subroutines

XStoreName (3X11 )
XFetchName can generate a BadWindow error.

Property
WM_NAME

Diagnostics
BadAlloc

The server failed to allocate the requested resource or server
memory.

BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XSetCommand(3Xll), XSetIconName(3Xll), XSetIconSizeHints(3Xll),
XSetNormalHints(3Xll), XSetSizeHints(3Xll),
XSetStandardProperties(3Xll), XSetWMHints(3Xl1),
XSetZoomHints(3Xll )
Guide to the Xlib Library

Subroutines 3-617

XStringToKeysym (3X11 )
Name
XStringToKeysym, XKeysymToString, XKeycodeToKeysym,
XKeysymToKeycode - convert keysyms

Syntax
KeySym XStringToKeysym(string)
char *string;
char *XKeysymToString (keysym)
KeySym keysym;
KeySym XKeycodeToKeysym(display, keycode, index)
Display *display;
KeyCode keycode;
int index;
KeyCode XKeysymToKeycode( display, keysym)
Display *display;
KeySym keysym;

Arguments
display

Specifies the connection to the X server.

index

Specifies the element of KeyCode vector.

keycode

Specifies the KeyCode.

keysym

Specifies the KeySym that is to be searched for or converted.

string

Specifies the name of the KeySym that is to be converted.

Description
Valid KeySym names are listed in <XII /keysymdef • h> by removing the
XK_ prefix from each name. If the specified string does not match a valid
KeySym, XStringToKeysym returns NoSymbol.
The returned string is in a static area and must not be modified. If the
specified KeySym is not defined, XKeysymToString returns a NULL.
The XKeycodeToKeysym function uses internal Xlib tables and returns the
KeySym defined for the specified KeyCode and the element of the KeyCode
vector. If no symbol is defined, XKeycodeToKeysym returns NoSymbol.

3-618 Subroutines

XStringToKeysym (3X11 )
If the specified KeySym is not defined for any KeyCode,
XKeysymToKeycode returns zero.

See Also
XLookupKeysym(3Xll)
Guide to the Xlib Library

Subroutines 3-619

XSynchronize (3X11 )
Name
XSynchronize, XSetAfterFunction - enable or disable synchronization

Syntax
int (*XSynchronize (display, onoff))O
Display *display;
Boolonoff;
int (*XSetAfterFunction (display, procedure))O
Display *display;
int (* procedure) 0;

Arguments
display

Specifies the connection to the X server.

procedure

Specifies the function to be called after an Xlib function that
generates a protocol request completes its work.

onoff

Specifies a Boolean value that indicates whether to enable or
disable synchronization.

Description
The XSynchronize function returns the previous after function. If onoff is
True, XSynchronize turns on synchronous behavior. If onoff is False,
XSynchronize turns off synchronous behavior.
The specified procedure is called with only a display pointer.
XSetAfterFunction returns the previous after function.

See Also
XSetErrorHandler(3Xll )
Guide to the Xlib Library

3-620 Subroutines

XTextExtents (3X11 )
Name
XTextExtents, XTextExtents 16, XQueryTextExtents, XQueryTextExtents 16 compute or query text extents

Syntax
XTextExtents(font_struct, string, nchars, direction_return,
font ascent return, font descent return, overall return)
XFontStruct *font itruct; char *string;
int nchars;
int *direction return;
int *font ascent return, *font descent return;
XCharStruct *overall_return;XTextExtents 16 (font_struct, string, nchars, direction_return,
font ascent return, font descent return, overall return)
XFontStruct *font struct; XChar2b *string;int nchars;
int *direction return;
int *font ascent return, *font descent return;
XCharStruct *overall_return;XQueryTextExtents( dispJay, font_ID, string, nc hars, direction_return,
font_ascent_return, font_descent_return, overall_return)
Display *dispJay;
XIDfont ID;
char *string;
int nchars;
int *direction return;
int *font ascent return, *font descent return;
XCharStruct *oVerall_return;XQueryTextExtents 16( display, font_ID, string, nchars, direction_return,
font ascent return, font descent return, overall return)
-Display *dispJay; XIDfont ID;
XChar2b-* string;
int nchars;
int *direction_return;

Subroutines 3-621

XTextExtents (3X11 )
int *font_ascent_return, *font_descent_return;
XCharStruct *overall_return;

Arguments
direction return
Returns the value of the direction hint (FontLeftToRight
or FontRight ToLeft).
display

Specifies the connection to the X server.

fontJD

Specifies either the font ID or the GContext ID that
contains the font.

font_ascent_return
Returns the font ascent.
font descent return
- Returns the font descent.
font_struct

Specifies a pointer to the XFontStruct structure.

nchars

Specifies the number of characters in the character string.

string

Specifies the character string.

overall return Returns the overall size in the specified XCharStruct
structure.

Description
The XTextExtents and XTextExtents16 functions perform the size
computation locally and, thereby, avoid the round-trip overhead of
XQueryTextExtents and XQueryTextExtents16. Both functions
return an XCharStruct structure, whose members are set to the values as
follows.
The ascent member is set to the maximum of the ascent metrics of all
characters in the string. The descent member is set to the maximum of the
descent metrics. The width member is set to the sum of the character-width
metrics of all characters in the string. For each character in the string, let W
be the sum of the character-width metrics of all characters preceding it in the
string. Let L be the left-side-bearing metric of the character plus W. Let R
be the right-side-bearing metric of the character plus W. The lbearing
member is set to the minimum L of all characters in the string. The rbearlng
member is set to the maximum R.

3-622 Subroutines

XTextExtents (3X11 )
For fonts defined with linear indexing rather than 2-byte matrix indexing,
each XChar2b structure is interpreted as a 16-bit number with byte1 as the
most-significant byte. If the font has no defined default character, undefined
characters in the string are taken to have all zero metrics.
The XQueryTextExtents and XQueryTextExtents16 functions
return the bounding box of the specified 8-bit and 16-bit character string in
the specified font or the font contained in the specified GC. These functions
query the X server and, therefore, suffer the round-trip overhead that is
avoided by XTextExtents and XTextExtents16. Both functions
return a XCharStruct structure, whose members are set to the values as
follows.
The ascent member is set to the maximum of the ascent metrics of all
characters in the string. The descent member is set to the maximum of the
descent metrics. The width member is set to the sum of the character-width
metrics of all characters in the string. For each character in the string, let W
be the sum of the character-width metrics of all characters preceding it in the
string. Let L be the left-side-bearing metric of the character plus W. Let R
be the right-side-bearing metric of the character plus W. The lbearing
member is set to the minimum L of all characters in the string. The rbearing
member is set to the maximum R.
For fonts defined with .linear indexing rather than 2-byte matrix indexing,
each XChar2b structure is interpreted as a 16-bit number with byte1 as the
most-significant byte. If the font has no defined default character, undefined
characters in the string are taken to have all zero metrics.
XQueryTextExtents XQueryTextExtents16 and can generate
BadFont and BadGC errors.

Diagnostics
BadFont

A value for a Font or GContext argument does not name a
defined Font.

BadGC

A value for a GContext argument does not name a defined
GContext.

See Also
XTextWidth(3X11)
Guide to the Xlib Library

Subroutines 3-623

XTextWidth (3X11 )
Name
XTextWidth, XTextWidth16 - compute text width

Syntax
int XTextWidth(font_struct, string, count)
XFontStruct *font struct;
char *string;
int count;
int XTextWidth16(font_struct, string, count)
XFontStruct *font_struct;
XChar2b *string;
int count;

Arguments
count

Specifies the character count in the specified string.

font_struct

Specifies the font used for the width computation.

string

Specifies the character string.

Description
The XTextWidth and XTextWidth16 functions return the width of the
specified 8-bit or 2-byte character strings.

See Also
XTextExtents(3Xll)
Guide to the Xlib Library

3-624 Subroutines

XTranslateCoordinates (3X11 )
Name
XTranslateCoordinates - translate window coordinates

Syntax
Bool XTranslateCoordinates(display, src_w, dest_w, src_x, srcy,
dest-.x_return, desty _return, child_return)
Display *display;
Window src_w, dest_w;
int src_x, srcy;
int *dest_x_return, *desty_return;
Window *child_return;

Arguments
child return

Returns the child if the coordinates are contained in a
mapped child of the destination window.

dest w

Specifies the destination window.

dest x return
desty=return Return the x and y coordinates within the destination
window.
display
Specifies the connection to the X server.
src w

Specifies the source window.

src x
srcy

Specify the x and y coordinates within the source window.

Description
The XTranslateCoordinates function takes the src_x and src-y
coordinates relative to the source window's origin and returns these
coordinates to dest_x_return and dest-y_return relative to the destination
window's origin. If XTranslateCoordinates returns zero, src_wand
dest_w are on different screens, and dest_x_return and dest-y_return are zero.
If the coordinates are contained in a mapped child of dest_w, that child is
returned to child_return. Otherwise, child_return is set to None.
XTranslateCoordinates can generate a BadWindow error.

Subroutines 3-625

XTranslateCoordinates (3X11 )
Diagnostics
BadWindow

A value for a Window argument does not name a defined
Window.

See Also
Guide to the Xlib Library

3-626 Subroutines

XUnmapWindow (3X11 )
Name
XUnmapWindow, XUnmapSubwindows - unmap windows

Syntax
XUnmapWindow(display, w)
Display *display;
Windoww;
XUnmapSubwindows (display, w)
Display *display;
Window w;

Arguments
display

Specifies the connection to the X server.

Specifies the window.

Description
The XUnmapWindow function unmaps the specified window and causes the
X server to generate an UnmapNotify event. If the specified window is
already unmapped, XUnmapWindow has no effect. Normal exposure
processing on formerly obscured windows is performed. Any child window
will no longer be visible until another map call is made on the parent. In
other words, the subwindows are still mapped but are not visible until the
parent is mapped. Unmapping a window will generate Expose events on
windows that were formerly obscured by it.
XUnmapWindow can generate a BadWindow error.

The XUnmapSubwindows function unmaps all subwindows for the
specified window in bottom-to-top stacking order. It causes the X server to
generate an UnmapNotify event on each subwindow and Expose events
on formerly obscured windows. Using this function is much more efficient
than unmapping multiple windows one at a time because the server needs to
perform much of the work only once, for all of the windows, rather than for
each window.
.
XUnmapSubwindows can generate a BadWindow error.

Subroutines 3-627

XUnmapWindow(3X11 )
Diagnostics
BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XChangeWindowAttributes(3Xll), XConfigureWindow(3Xll),
XCreateWindow(3Xll), XDestroyWindow(3Xll), XMapWindow(3Xll)
XRaiseWindow(3Xl1)
Guide to the Xlib Library

3-628 Subroutines

XWarpPointer (3X11 )
Name
XWarpPointer - move pointer

Syntax
XWarpPointer(display, src_w, dest_w, srcy, srcy, src_width, src_height,
dest_x, desty)
Display *display;
Window src_w, dest_w;
int src_x, srcy;
unsigned int src_width, src_height;
int dest_x, desty;

Arguments
dest w
dest x
desiy

Specifies the destination window or None.
Specify the x and y coordinates within the destination
window.

display

Specifies the connection to the X server.

src x
srcy
src width
src_height

Specify a rectangle in the source window.

src w

Specifies the source window or None.

Description
If dest_w is None, XWarpPointer moves the pointer by the offsets
(dest_x, dest_y) relative to the current position of the pointer. If dest_w is a
window, XWarpPointer moves the pointer to the offsets (dest_x, dest-y)
relative to the origin of dest_w. However, if src_w is a window, the move
only takes place if the specified rectangle src_w contains the pointer.

The src_x and src-y coordinates are relative to the origin of src_w. If
srcjleight is zero, it is replaced with the current height of src_w minus
src-y. If src_width is zero, it is replaced with the current width of src_w
minus src_x.
There is seldom any reason for calling this function. The pointer should
normally be left to the user. If you do use this function, however, it
generates events just as if the user had instantaneously moved the pointer
Subroutines 3-629

XWarpPointer {3X11 }
from one position to another. Note that you cannot use XWarpPointer to
move the pointer outside the confine_to window of an active pointer grab.
An attempt to do so will only move the pointer as far as the closest edge of
the confine_to window.
XWarpPointer can generate a BadWindow error.

Diagnostics
BadWindow

A value for a Window argument does not name a defined
Window.

See Also
XSetInputFocus(3Xll)
Guide to the Xlib Library

3-630 Subroutines

Xlib Functions

Insert tabbed
divider here.
Then discard
this sheet.

XtAddCaliback (3Xt)

Name
XtAddCallback, XtAddCallbacks, XtRemoveCallback, XtRemoveCallbacks,
XtRemoveAllCallbacks - add and remove callback procedures

Syntax
void XtAddCallback(w, callback name, callback, client data)
Widget w;
String callback_name;
XtCallbackProc callback;
caddr_t client_data;
void XtAddCallbacks(w, callback name, callbacks)
Widget w;
String callback name;
XtCallbackListcallbacks;
void XtRemoveCallback(w, callback name, callback, client data)
Widget w;
String callback_name;
XtCallbackProc callback;
caddr_t client_data;
void XtRemoveCallbacks(w, callback name, callbacks)
Widget w;
String callback name;
XtCallbackListcallbacks;
void XtRemoveAllCallbacks(w, callback name)
Widget w;
String callback_name;

Arguments
callback

Specifies the callback procedure.

callbacks

Specifies the null-tenninated list of callback procedures and
corresponding client data.

Subroutines 3-631

XtAddCallback (3Xt)
callback_name Specifies the callback list to which the procedure is to be
appended or deleted.
client data

Specifies the argument that is to be passed to the specified
procedure when it is invoked by XtCallbacks or NULL, or
the client data to match on the registered callback procedures.

Specifies the widget.

Description
The XtAddCallback function adds the specified callback procedure to the
specified widget's callback list.
The XtAddCallbacks add the specified list of callbacks to the specified
widget's callback list.
The XtRemoveCallback function removes a callback only if both the
procedure and the client data match.
The XtRemoveCallbacks function removes the specified callback
procedures from the specified widget's callback list.
The XtRemoveAllCallbacks function removes all the callback
procedures from the specified widget's callback list.

See Also
XtCalICallbacks(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

3-632 Subroutines

XtAdd EventHandler (3Xt)
Name
XtAddEventHandler, XtAddRawEventHandler, XtRemoveEventHandler,
XtRemoveRawEventHandler - add and remove event handlers

Syntax
void XtAddEventHandler(w, event_mask, nonmaskable, proc, client_data)
Widget w;
EventMask event mask;
Boolean nonmaskable;
XtEventHandler proc;
caddr_t client_data;
void XtAddRawEventHandler(w, event mask, nonmaskable, proc,

c~m~~

Widget w;
EventMask event mask;
Boolean nonmaskable;
XtEventHandler proc;
caddr_t client_data;
void XtRemoveEventHandler(w, event mask, nonmaskable, proc,
client data)
Widget w;
EventMask event mask;
Boolean nonmaskable;
XtEventHandler proc;
caddr_t client_data;
void XtRemoveRawEventHandler(w, event_mask, nonmaskable, proc,
client data)
Widget w;
EventMask event mask;
Boolean nonmaskable;
XtEventHandler proc;
caddr_t client_data;

Arguments
client data

Specifies additional data to be passed to the client's event
handler.

event mask

Specifies the event mask for which to call or unregister this
procedure.
Subroutines 3-633

XtAdd EventHandler (3Xt)
nonmaskable

Specifies a Boolean value that indicates whether this
procedure should be called or removed on the nonmaskable
events (GraphicsExpose, NoExpose,
SelectionClear,SelectionRequest,
SelectionNotify,ClientMessage,and
MappingNotify).

proc

Specifies the procedure that is to be added or removed.

Specifies the widget for which this event handler is being
registered.

Description
The XtAddEventHandler function registers a procedure with the dispatch
mechanism that is to be called when an event that matches the mask occurs
on the specified widget. If the procedure is already registered with the" same
client_data, the specified mask is ORed into the existing mask. If the widget
is realized, XtAddEventHandler calls XSelectlnput, if necessary.
The XtAddRawEventHandlerfunction is similar to
XtAddEventHandler except that it does not affect the widget'S mask and
never causes an XSelectlnput for its events. Note that the widget might
already have those mask bits set because of other nonraw event handlers
"
registered on it.
The XtAddRawEventHandler function is similar to
XtAddEventHandler except that it does not affect the widget's mask and
never causes an XSelectlnput for its events. Note that the widget might
already have those mask bits set because of other nonraw event handlers
registered on it.
The XtRemoveRawEventHandler function stops the specified procedure
from receiving the specified events. Because the procedure is a raw event
handler, this does not affect the widget's mask and never causes a calIon
XSelectlnput.

See Also
XtAppNextEvent(3Xt), XtBuildEventMask(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

3-634 Subroutines

XtAddExposureToRegion (3Xt)
Name
XtAddExposureToRegion - merge exposure events into a region

Syntax
void XtAddExposureToRegion(event, region)
XEvent *event;
Region region;

Arguments
event

Specifies a pointer to the Expose or GraphicsExpose
event.

region

Specifies the region object (as defined in <Xll/Xutil. h».

Description
The XtAddExposureToRegion function computes the union of the
rectangle defined by the exposure event and the specified region. Then, it
stores the results back in region. If the event argument is not an Expose or
GraphicsExpose event, XtAddExposureToRegion returns without
an error and without modifying region.
This function is used by the exposure compression mechanism (see Section
7.9.3).

See Also
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-635

XtAddGrab (3Xt)
Name
XtAddGrab, XtRemoveGrab - redirect user input to a modal widget

Syntax
void XtAddGrab(w, exclusive, spring loaded)
Widget w;
Boolean exclusive;
Boolean spring_loaded;
void XtRemoveGrab(w)
Widget w;

Arguments
exclusive

Specifies whether user events should be dispatched
exclusively to this widget or also to previous widgets in the
cascade.

spring_loaded Specifies whether this widget was popped up because the
user pressed a pointer button.
w

Specifies the widget to add to or remove from the modal
cascade.

Description
The XtAddGrab function appends the widget (and associated parameters) to
the modal cascade and checks that exclusive is True if spring_loaded is
True. If these are not True, XtAddGrab generates an error.
The modal cascade is used by XtDispatchEvent when it tries to dispatch
a user event. When at least one modal widget is in the widget cascade,
XtDispatchEvent first determines if the event should be delivered. It
starts at the most recent cascade entry and follows the cascade up to and
including the most recent cascade entry added with the exclusive parameter
True.
This subset of the modal cascade along with all descendants of these widgets
comprise the active subset. User events that occur outside the widgets in this
subset are ignored or remapped. Modal menus with submenus generally add
a submenu widget to the cascade with exclusive False. Modal dialog
boxes that need to restrict user input to the most deeply nested dialog box
add a subdialog widget to the cascade with exclusive True. User events that
occur within the active subset are delivered to the appropriate widget, which

3-636 Subroutines

XtAddGrab (3Xt)
is usually a child or further descendant of the modal widget.
Regardless of where on the screen they occur, remap events are always
delivered to the most recent widget in the active subset of the cascade that
has spring_loaded True, if any such widget exists.
The XtRemoveGrab function removes widgets from the modal cascade
starting at the most recent widget up to and including the specified widget. It
issues an error if the specified widget is not on the modal cascade.

See Also
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-637

XtAppAddActions (3Xt)
Name
XtAppAddActions - register an action table

Syntax
void XtAppAddActions(app _context, actions, num_actions)
XtAppContext app_context,
XtActionList actions;
Cardinal num_actions;

Arguments
app_context

Specifies the application context.

actions

Specifies the action table to register.

num_ args

Specifies the number of entries in this action table.

Description
The XtAppAddActions function adds the specified action table and
registers it with the translation manager.

See Also
XtParseTranslationTable(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

3-638 Subroutines

XtAppAddConverter (3Xt)
Name
XtAppAddConverter - register a resource converter

Syntax
void XtAppAddConverter(app _context, from_type, to_type, converter,
convert_args, num_args)
XtAppContext app_context,
String from type;
String to type;
XtConverter converter;
XtConvertArgList convert_args;·
Cardinal num_ args;

Arguments
app_context

Specifies the application context.

converter

Specifies the type converter procedure.

convert_ args

Specifies how to compute the additional arguments to the
converter or NULL.

from type

Specifies the source type.

num_args

Specifies the number of additional arguments to the converter
or zero.
Specifies the destination type.

Description
The XtAppAddConverter registers the specified resource converter.

See Also
XtConvert(3Xt), XtStringConversionW aming(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-639

XtAppAddlnput(3Xt)
Name
XtAppAddInput, XtRemoveInput - register and remove an input source

Syntax
XtInputId XtAppAddInput(app_context, source, condition, proc, client_data)
XtAppContext app_context,
int source;
caddr_t condition;
XtInputCallbackProc proc;
caddr_t client_data;
void XtRemoveInput(id)
XtInputId id;

Arguments
app_context

Specifies the application context that identifies the
application.

client data

Specifies the argument that is to be passed to the specified
procedure when input is available.

condition

Specifies the mask that indicates a read, write, or exception
condition or some operating system dependent condition.

Specifies the ID returned from the corresponding
XtAppAddInput call.

proc

Specifies the procedure that is to be called when input is
available.

source

Specifies the source file descriptor on a UNIX-based system
or other operating system-dependent device specification.

Description
The XtAppAddlnput function registers with the Intrinsics read routine a
new source of events, which is usually file input but can also be file output.
Note that file should be loosely interpreted to mean any sink or source of
data. XtAppAddInput also specifies the conditions under which the
source can generate events. When input is pending on this source, the
callback procedure is called.

3-640 Subroutines

XtAppAddlnput (3Xt)
The legal values for the condition argument are operating-system dependent.
On a UNIX-based system, the condition is some union of
XtInputReadMask,XtInputWriteMask,and
XtInputExceptMask. The XtRemoveInput function causes the
Intrinsics read routine to stop watching for input from the input source.

See Also
XtAppAddTimeOut(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-641

XtAppAddTimeOut (3Xt)
Name
XtAppAddTimeOut, XtRemoveTimeOut - register and remove timeouts

Syntax
XtIntervalId XtAppAddTimeOut(app _context, interval, proc, client_data)
XtAppContext app context;
unsigned long interval;
XtTimerCallbackProc proc;
caddr_t client_data;
void XtRemoveTimeOut(timer)
XtIntervalId timer;

Arguments
app_context

Specifies the application context for which the timer is to be
set.

client data

Specifies the argument that is to be passed to the specified
procedure when input is available.

interval

Specifies the time interval in milliseconds.

proc

Specifies the procedure that is to be called when time
expires.

timer

Specifies the ID for the timeout request to be destroyed.

Description
The XtAppAddTimeOut function creates a timeout and returns an identifier
for it. The timeout value is set to interval. The callback procedure is called
when the time interval elapses, and then the timeout is removed.
The XtRemoveT imeOut function removes the timeout. Note that timeouts
are automatically removed once they trigger.

See Also
XtAppAddInput(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

3-642 Subroutines

XtAppAddWorkProc (3Xt)
Name
XtAppAddWorkProc, XtRemoveWorkProc - add and remove background
processll1gprocedures

Syntax
XtWorkProcId XtAppAddWorkProc(app _context, proc, client_data)
XtAppContext app context,
XtWorkProc proc;caddr_t client_data;
void XtRemoveWorkProc(id)
XtWorkProcId id;

Arguments
app_context

Specifies the application context that identifies the
application.

client data

Specifies the argument that is to be passed to the specified
procedure when it is called.

proc

Specifies the procedure that is to be called when time
expires.

Specifies which work procedure to remove.

Description
The XtAppAddWorkProc function adds the specified work procedure for
the application identified by app_context.
The XtRemoveWorkProc function explicitly removes the specified
background work procedure.

See Also
XtAppNextEvent(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-643

XtAppCreateShel1 (3Xt)
Name
XtAppCreateShell - create top-level widget instance

Syntax
Widget XtAppCreateShell(application_name, application_class,
widget_class, display, args, num_args)
String application_name;
String application_class;
WidgetClass widget_class;
Display *display;
ArgList args;
Cardinal num_ args;

Arguments
application_class
Specifies the class name of this application.
application_name
Specifies the name of the application instance.
args

Specifies the argument list in which to set in the
WM_COMMAND property.

display

Specifies the display from which to get the resources.

num_args

Specifies the number of arguments in the argument list.

widget_class

Specifies the widget class that the application top-level
widget should be.

Description
The XtAppCreateShell function saves the specified application name
and application class for qualifying all widget resource specifiers. The
application name and application class are used as the left-most components
in all widget resource names for this application. XtAppCreateShell
should be used to create a new logical application within a program or to
create a shell on another display. In the first case, it allows the specification
of a new root in the resource hierarchy. In the second case, it uses the
resource database associated with the other display.
Note that the widget returned by XtAppCreateShell has the
WM_COMMAND property set for session managers (see Chapter 4).

3-644 Subroutines

. XtAppCreateShel1 (3Xt)
See Also
XtCreateWidget(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-645

XtAppError (3Xt)
Name
XtAppError, XtAppSetErrorHandler, XtAppSetWarningHandler,
XtAppWaming -low-level error handlers

Syntax
void XtAppError(app context, message)
XtAppContext app_context;
String message;
void XtAppSetErrorHandler(app_context, handler)
XtAppContext app_context;
XtErrorHandler handler;
void XtAppSetWamingHandler(app_context, handler)
XtAppContext app_context;
XtErrorHandler handler;
void XtAppWaming(app· context, message)
XtAppContext app_context;
String message;

Arguments
app_context
message
handler
message

Specifies the application context.
Specifies the nonfatal error message that is to be reported.
Specifies the new fatal error procedure, which should not
return, or the nonfatal error procedure, which usually returns.
Specifies the message that is to be reported.

Description
The XtAppError function calls the installed error procedure and passes the
specified message.
The XtAppSetErrorHandler function registers the specified procedure,
which is called when a fatal error condition occurs.
The XtAppSetWarningHandler registers the specified procedure, which
is called when a nonfatal error condition occurs.
The XtAppWarning function calls the installed nonfatal error procedure
and passes the specified message.

3-646 Subroutines

XtAppError (3Xt)
See Also
XtAppGetErrorDatabase(3Xt), XtAppErrorMsg(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-647

XtAppErrorMsg (3Xt)
Name
XtAppErrorMsg, XtAppSetErrorMsgHandler, XtAppSetWamingMsgHandler,
XtAppWamingMsg - high-level error handlers

Syntax
void XtAppErrorMsg(app_context, name, type, class, default, params,

numyarams)
XtAppContext app_context;
String name;
String type;
String class;
String default;
String *params;
Cardinal *numyarams;
void XtAppSetErrorMsgHandler(app_context, msg_handler)
XtAppContext app_context;
XtErrorMsgHandler msg_handler;
void XtAppSetWamingMsgHandler(app_context, msg_handler)
XtAppContext app_context;
XtErrorMsgHandler msg_handler;
void XtAppWamingMsg(app _context, name, type, class, default, params,
numyarams)
XtAppContext app_context;
String name;
String type;
String class;
String default;
String *params;
Cardinal *numyarams;

Arguments
app_context
class
default
name
type

3-648 Subroutines

Specifies the application context.
Specifies the resource class.
Specifies the default message to use.
Specifies the general kind of error.
Specifies the detailed name of the error.

XtAppErrorMsg (3Xt)
Specifies the new fatal error procedure, which should not
return, or the nonfatal error procedure, which usually returns.

numyarams

Specifies the number of values in the parameter list.

params

Specifies a pointer to a list of values to be stored in the
message.

Description
The XtAppErrorMsg function calls the high-level error handler and passes
the specified information.
The XtAppSetErrorMsgHandler function registers the specified
procedure, which is called when a fatal error occurs.
The XtAppSetWarningMsgHandler function registers the specified
procedure, which is called when a nonfatal error condition occurs.
The XtAppWarningMsg function calls the high-level error handler and
passes· the specified information.

See Also
XtAppGetErrorDatabase(3Xt), XtAppError(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-649

XtAppGetErrorDatabase (3Xt)
Name
XtAppGetErrorDatabase, XtAppGetErrorDatabaseText - obtain error
database

Syntax
XrmDatabase *XtAppGetErrorDatabase(app_context)
XtAppContext app_context,
void XtAppGetErrorDatabaseText(app_context, name, type, class, default,
buffer_return, nbytes, database)
XtAppContext app_context,
char *name, *type, *class;
char *default;
char *buffer return;
int nbytes; XrmDatabase database;

Arguments
app_context

Specifies the application context.

buffer return

Specifies the buffer into which the error message is to be
returned.

class

Specifies the resource class of the error message.

database

Specifies the name of the alternative database that is to be
used or NULL if the application's database is to be used.

default

Specifies the default message to use.

name
type
nbytes

Specifies the name and type that are concatenated to form the
resource name of the error message.
Specifies the size of the buffer in bytes.

Description
The XtAppGetErrorDatabase function returns the address of the error
database. The Intrinsics do a lazy binding of the error database and do not
merge in the database file until the first call to
XtAppGetErrorDatbaseText.

3-650 Subroutines

XtAppGetErrorDatabase (3Xt)
The XtAppGetErrorDatabaseText returns the appropriate message
from the error database or returns the specified default message if one is not
found in the error database.

See Also
XtAppError(3Xt), XtAppErrorMsg(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-651

XtAppGetSelectionTimeout (3Xt)
Name
XtAppGetSelectionTimeout, XtAppSetSelectionTimeout - set and obtain
selection timeout values

Syntax
unsigned long XtAppGetSelectionTimeout(app_context)
XtAppContext app_context,
void XtAppSetSelectionTimeout(app_context, timeout)
XtAppContext app context,
unsigned long timeout;

Arguments
app_context

Specifies the application context.

timeout

Specifies the selection timeout in milliseconds.

Description
The XtAppGetSelectionTimeout function returns the current selection
timeout value, in milliseconds. The selection timeout is the time within
which the two communicating applications must respond to one another. The
initial timeout value is set by the selectionTimeout application
resource, or, if selectionTimeout is not specified, it defaults to five
seconds.
The XtAppSetSelectionTimeout function sets the Intrinsics's
selection timeout mechanism. Note that most applications should not set the
selection timeout.

See Also
XtOwnSelection(3Xt)
Guide to the XU] Toolkit Intrinsics
Guide to the Xlib Library

3-652 Subroutines

XtAppNextEvent (3Xt)
Name
XtAppNextEvent, XtAppPending, XtAppPeekEvent, XtAppProcessEvent,
XtDispatchEvent, XtAppMainLoop - query and process events and input

Syntax
void XtAppNextEvent(app _context, event_return)
XtAppContext app_context;
XEvent *event_return;
Boolean XtAppPeekEvent(app _context, event_return)
XtAppContext app_context;
XEvent *event_return;
XtInputMask XtAppPending(app _context)
XtAppContext app_context;
void XtAppProcessEvent(app _context, mask)
XtAppContext app context;
XtJnputMask mask;Boolean XtDispatchEvent(event)
XEvent *event;
void XtAppMainLoop(app _context)
XtAppContext app_context;

Arguments
app_context

Specifies the application context that identifies the
application.

event

Specifies a pointer to the event structure that is to be
dispatched to the appropriate event handler.

event return
mask

Returns the event infonnation to the specified event structure.
Specifies. what types of events to process. The mask is the
bitwise inclusive OR of any combination of XtIMXEvent,
XtIMTimer, and XtlMAlternatelnput. As a
convenience, the XUI Toolkit defines the symbolic name
Xt lMAll to be the bitwise inclusive OR of all event types.

Subroutines 3-653

XtAppNextEvent (3Xt)
Description
If no input is on the X input queue, XtAppNextEvent flushes the X output
buffer and waits for an event while looking at the other input sources and
timeout values and calling any callback procedures triggered by them. This
wait time can be used for background processing (see Section 7.8).
If there is an event in the queue, XtAppPeekEvent fills in the event and
returns a nonzero value. If no X input is on the queue, XtAppPeekEvent
flushes the output buffer and blocks until input is available (possibly calling
some timeout callbacks in the process). If the input is an event,
XtAppPeekEvent fills in the event and returns a nonzero value.
Otherwise, the input is for an alternate input source, and XtAppPeekEvent
returns zero.

The XtAppPending function returns a nonzero value if there are events
pending from the X server, timer pending, or other input sources pending.
The value returned is a bit mask that is the OR of Xt IMXEvent,
XtIMTimer, and XtlMAlternatelnput (see XtAppProcessEvent).
If there are no events pending, XtAppPending flushes the output buffer
and returns zero.
The XtAppProcessEvent function processes one timer, alternate input,
or X event. If there is nothing of the appropriate type to process,
XtAppProcessEvent blocks until there is. If there is more than one type
of thing available to process, it is undefined which will get processed.
Usually, this procedure is not called by client applications (see
XtAppMainLoop). XtAppProcessEvent processes timer events by
calling any appropriate timer callbacks, alternate input by calling any
appropriate alternate input callbacks, and X events by calling
XtDispatchEvent.
When an X event is received, it is passed to XtDispatchEvent, which
calls the appropriate event handlers and passes them the widget, the event,
and client-specific data registered with each procedure. If there are no
handlers for that event registered, the event is ignored and the dispatcher
simply returns. The order in which the handlers are called is undefined.
The XtDispatchEvent function sends those events to the event handler
functions that have been previously registered with the dispatch routine.
XtDispatchEvent returns True if it dispatched the event to some
handler and False if it found no handler to dispatch the event to. The most
common use of XtDispatchEvent is to dispatch events acquired with the
XtAppNextEvent procedure. However, it also can be used to dispatch
user-constructed events. XtDispatchEvent also is responsible for
implementing the grab semantics for XtAddGrab.
3-654 Subroutines

XtAppNextEvent (3Xt)
The XtAppMainLoop function first reads the next incoming X event by
calling XtAppNextEvent and then it dispatches the event to the
appropriate registered procedure by calling XtDispatchEvent. This
constitutes the main loop of XUI Toolkit applications, and, as such, it does
not return. Applications are expected to exit in response to some user action.
There is nothing special about XtAppMainLoop; it is simply an infinite
loop that calls XtAppNextEvent and then XtDispatchEvent.
Applications can provide their own version of this loop, which tests some
global termination flag or tests that the number of top-level widgets is larger
than zero before circling back to the call to XtAppNextEvent.

See Also
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-655

XtBuildEventMask (3Xt)
Name
XtBuildEventMask - retrieve a widget's event mask

Syntax
EventMask XtBuildEventMask(w)
Widget w;

Arguments
w

Specifies the widget.

Description
The XtBuildEventMask function returns the event mask representing the
logical OR of all event masks for event handlers registered on the widget
with XtAddEventHandler and all event translations, including
accelerators, installed on the widget. This is the same event mask stored into
the XSetWindowAttributes structure by XtRealizeWidget and sent
to the server when event handlers and translations are installed or removed
on the realized widget.

See Also
XtAddEventHandler(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

3-656 Subroutines

XtCallAcceptFocus (3Xt)
Name
XtCallAcceptFocus - call a widget's accept_focus procedure

Syntax
Boolean XtCalIAcceptFocus(w, time)
Widget w;
Time *time;

Arguments
time

Specifies the X time of the event that is causing the accept
focus.

Specifies the widget.

Description
The XtCallAcceptFocus function calls the specified widget's
accept_focus procedure, passing it the specified widget and time, and returns
what the accept_focus procedure returns. If accept_focus is NULL,
XtCallAcceptFocus returns False.

See Also
XtSetKeyboardFocus(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-657

XtCaliCalibacks (3Xt)
Name
XtCallCallbacks, XtHasCallbacks - process callbacks

Syntax
void XtCalICallbacks(w, callback name, call data)
Widget w;
-String callback name;
caddr_t call_data;
typedef enum {XtCallbackNoList, XtCallbackHasNone,
XtCallbackHasSome} XtCallbackStatus;
XtCallbackStatus XtHasCallbacks(w, callback name)
Widget w;
String callback_name;

Arguments
callback_name Specifies the callback list to be executed or checked.
call data

Specifies a callback list-specific data value to pass to each of
the callback procedure in the list.

Specifies the widget.

Description
The XtCallCallbacks function calls each procedure that is registered in
the specified widget's callback list.
The XtHasCallbacks function first checks to see if the widget has a
callback list identified by callback_name. If the callback list does not exist,
XtHasCallbacks returns XtCallbackNoList. If the callback list
exists but is empty, it returns XtCallbackHasNone. If the callback list
exists and has at least one callback registered, it returns
XtCallbackHasSome.

See Also
XtAddCallback(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

3-658 Subroutines

XtClass (3Xt)
Name
XtClass, XtSuperClass, XtIsSubclass, XtCheckSubclass, XtIsComposite,
XtIsManaged - obtain and verify a widget's class-

Syntax
WidgetClass XtClass(w)
Widget w;
WidgetClass XtSuperclass(w)
Widget w;
Boolean XtIsSubclass(w, widget class)
Widget w;
WidgetClass widget_class;
void XtCheckSubclass(w, widget class, message)
Widget w;
WidgetClass widget class;
String message;
Boolean XtIsComposite(w)
Widget w;
Boolean XtIsManaged(w)
Widget w;

Arguments
w

Specifies the widget.

widget_class

Specifies the widget class that the application top-level
widget should be.

message

Specifies the message that is to be used.

Description
The XtClass function returns a pointer to the widget's class structure.
The XtSuperclass function returns a pointer to the widget's superclass
class structure.
The XtIsSubclass function returns True if the class of the specified
widget is equal to or is a subclass of the specified widget class. The
specified widget can be any number of subclasses down the chain and need
not be an immediate subclass of the specified widget class. Composite

Subroutines 3-659

XtClass (3Xt)
widgets that need to restrict the class of the items they contain can use
XtIsSubclass to find out if a widget belongs to the desired class of
objects.
The XtCheckSubclass macro determines if the class of the specified
widget is equal to or is a subclass of the specified widget class. The widget
can be any number of subclasses down the chain and need not be an
immediate subclass of the specified widget class. If the specified widget is
not a subclass, XtCheckSubclass constructs an error message from the
supplied message, the widget's actual class, and the expected class and calls
XtErrorMsg. XtCheckSubclass should be used at the entry point of
exported routines to ensure that the client has passed in a valid widget class
for the exported operation.
XtCheckSubclass is only executed when the widget has been compiled
with the compiler symbol DEBUG defined; otherwise, it is defined as the
empty string and generates no code.

The XtIsComposite function is a convenience function that is equivalent
to XtIsSubclass with compositeWidgetClass specified.
The Xt I sManaged macro (for widget programmers) or function (for
application programmers) returns True if the specified child widget is
managed or F al s e if it is not.

See Also
XtAppErrorMsg(3Xt), XtDisplay(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

3-660 Subroutines

XtConfigureWidget (3Xt)
Name
XtConfigureWidget, XtMoveWidget, XtResizeWidget - move and resize
widgets

Syntax
void XtConfigureWidget(w, x, y, width, height, border_width)
Widget w;
Position x;
Position y;
Dimension width;
Dimension height;
Dimension border_width;
void XtMoveWidget(w, x, y)
Widget w;
Position x;
Position y;
void XtResizeWidget(w, width, height, border_width)
Widget w;
Dimension width;
Dimension height;
Dimension border_width;
void XtResizeWindow(w)
Widget w;

Arguments
width
height
border width

Specify the new widget size.

Specifies the widget.

Specify the new widget x and y coordinates.

Description
The XtConfigureWidget function returns immediately if the specified
geometry fields are the same as the old values. Otherwise,
XtConfigureWidget writes the new x, y, width, height, and
border_width values into the widget and, if the widget is realized, makes an

Subroutines 3-661

XtConfigureWidget (3Xt)
Xlib XConfigureWindow calIon the widget's window.
If either the new width or height is different from its old value,
XtConfigureWidget calls the widget's resize procedure to notify it of
the size change; otherwise, it simply returns.

The XtMoveWidget function returns immediately if the specified geometry
fields are the same as the old values. Otherwise, XtMoveWidget writes the
new x and y values into the widget and, if the widget is realized, issues an
Xlib XMoveWindow calIon the widget's window.
The XtResizeWidget function returns immediately if the specified
geometry fields are the same as the old values. Otherwise,
XtResizeWidget writes the new width, height, and border_width values
into the widget and, if the widget is realized, issues an
XConfigureWindow call on the widget's window.
If the new width or height is different from the old values,
XtResizeWidget calls the widget's resize procedure to notify it of the
size change.

The XtResizeWindow function calls the XConfigureWindow Xlib
function to make the window of the specified widget match its width, height,
and border width. This request is done unconditionally because there is no
way to tell if these values match the current values. Note that the widget's
resize procedure is not called.
There are very few times to use XtResizeWindow; instead, you should use
XtResizeWidget.

See Also
XtMakeGeometryRequest(3Xt), XtQueryGeometry(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

3-662 Subroutines

XtConvert {3Xt}
Name
XtConvert, XtDirectConvert - invoke resource converters

Syntax
void XtConvert(w,from type,from, to type, to return)
-Widget w;
String from_type;
XrmValuePtr from;
String to_type;
XrmValuePtr to_return;
void XtDirectConvert(converter, args, num_args,from, to_return)
XtConverter converter;
XrmValuePtr args;
Cardinal num args;
XrmValuePtr from;
XrmValuePtr to_return;

Arguments
args

Specifies the argument list that contains the additional
arguments needed to perform the conversion (often NULL).

converter

Specifies the conversion procedure that is to be called.

from

Specifies the value to be converted.

from_type

Specifies the source type.

num_args

Specifies the number of additional arguments (often zero).

to_type

Specifies the destination type.

to return

Returns the converted value.

Specifies the widget to use for additional arguments (if any
are needed).

Description
The XtConvert function looks up the type converter registered to convert
from_type to to_type, computes any additional arguments needed, and then
calls XtDirectConvert.

Subroutines 3-663

XtConvert (3Xt)
The XtDirectConvert function looks in the converter cache to see if this
conversion procedure has been called with the specified arguments. If so, it
returns a descriptor for information stored in the cache; otherwise, it calls the
converter and enters the result in the cache.
Before calling the specified converter, XtDirectConvert sets the return
value size to zero and the return value address to NULL. To determine if the
conversion was successful, the client should check to_retum.address for nonNULL.

See Also
XtAppAddConverter(3Xt), XtStringConversionW aming(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

3-664 Subroutines

XtCreateApplicationContext (3Xt)
Name
XtCreateApplicationContext, XtDestroyApplicationContext,
XtWidgetToApplicationContext, XtToolkitInitialize - create, destroy, and
obtain an application context

Syntax
XtAppContext XtCreateApplicationContextO
void XtDestroyApplicationContext(app_context)
XtAppContext app_context;
XtAppContext XtWidgetToApplicationContext(w)
Widget w;
void XtToolkitInitializeO

Arguments
app_context

Specifies the application context.

Specifies the widget to use for additional arguments (if any
are needed).

Description
The XtCreateApplicationContext function returns an application
context, which is an opaque type. Every application must have at least one
application context.
The XtDestroyApplicationContext function destroys the specified
application context as soon as it is safe to do so. If called from with an event
dispatch (for example, a callback procedure),
XtDestroyApplicationContext does not destroy the application
context until the dispatch is complete.
The XtWidgetToApplicationContext function returns the application
context for the specified widget.
The semantics of calling Xt Too lk it I ni t i al i z e more than once are
undefined.

Subroutines 3-665

XtCreateApplicationContext (3Xt)
See Also
XtDisplayInitialize(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

3-666 Subroutines

XtCreatePopupShell (3Xt)
Name
XtCreatePopupShell - create a pop-up shell

Syntax
Widget XtCreatePopupShell(name, widget_class, parent, args, num_args)
String name;
WidgetClass widget_class;
Widget parent;
ArgList args;
Cardinal num_args;

Arguments
args

Specifies the argument list to override the resource defaults.

name

Specifies the text name for the created shell widget.

num_args

Specifies the number of arguments in the argument list.

parent

Specifies the parent widget.

widget_class

Specifies the widget class pointer for the created shell
widget.

Description
The XtCreatePopupShell function ensures that the specified class is a
subclass of Shell and, rather than using insert_child to attach the widget to
the parent's children list, attaches the shell to the parent's pop-ups list
directly.
A spring-loaded pop-up invoked from a translation table already must exist at
the time that the translation is invoked, so the translation manager can find
the shell by name. Pop-ups invoked in other ways can be created "on-thefly" when the pop-up actually is needed. This delayed creation of the shell
is particularly useful when you pop up an unspecified number of pop-ups.
You can look to see if an appropriate unused shell (that is, not currently
popped up) exists and create a new shell if needed.

See Also
XtCreateWidget(3Xt), XtPopdown(3Xt), XtPopup(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-667

XtCreateWidget (3Xt)
Name
XtCreateWidget, XtCreateManagedWidget, XtDestroyWidget - create and
destroy widgets

Syntax
Widget XtCreateWidget(name, widget_class, parent, args, num_args)
String name;
WidgetClass widget_class;
Widget parent;
ArgList args;
Cardinal num_args;
Widget XtCreateManagedWidget(name, widget_class, parent, args,
num args)
String name;
WidgetClass widget_class;
Widget parent;
ArgList args;
Cardinal num_args;
void XtDestroyWidget(w)
Widget w;

Arguments
args

Specifies the argument list to override the resource defaults.

name

Specifies the resource name for the created widget, which is
used for retrieving resources and, for that reason, should not
be the same as any other widget that is a child of same
parent.

num_args

Specifies the number of arguments in the argument list.

parent

Specifies the parent widget.

Specifies the widget.

widget_class

Specifies the widget class pointer for the created widget.

3-668 Subroutines

XtCreateWidget (3Xt)
Description
The XtCreateWidget function performs much of the boilerplate
operations of widget creation:
•

Checks to see if the class_initialize procedure has been called for this
class and for all superclasses and, if not, calls those necessary in a
superclass-to-subclass order.

•

Allocates memory for the widget instance.

•

If the parent is a subclass of constraintWidgetClass, it
allocates memory for the parent's constraints and stores the address of
this memory into the constraints field.

•

Initializes the core nonresource data fields (for example, parent and
visible).

•

Initializes the resource fields (for example, background_pixel) by using
the resource lists specified for this class and all superclasses.

•

If the parent is a subclass of constraintWidgetClass, it
initializes the resource fields of the constraints record by using the
constraint resource list specified for the parent's class and all
superclasses up to constraintWidgetClass.

•

Calls the initialize procedures for the widget by starting at the Core
initialize procedure on down to the widget's initialize procedure.

•

If the parent is a subclass of composi teWidgetClass, it puts the
widget into its parent's children list by calling its parent's insert_child
procedure. For further information, see Section 3.5.

•

If the parent is a subclass of constraintWidgetClass, it calls the
constraint initialize procedures, starting at
constraintWidgetClass on down to the parent's constraint
initialize procedure.

Note that you can determine the number of arguments in an argument list by
using the XtNurnber macro. For further information, see Section 11.1.
The XtCreateManagedWidget function is a convenience routine that
calls XtCreateWidget and XtManageChild.
The XtDestroyWidget function provides the only method of destroying a
widget, including widgets that need to destroy themselves. It can be called at
any time, including from an application callback routine of the widget being
destroyed. This requires a two-phase destroy process in order to avoid
dangling references to destroyed widgets.

Subroutines 3-669

XtCreateWidget (3Xt)
In phase one, XtDestroyWidget performs the following:
•

If the being_destroyed field of the widget is True, it returns
immediately.

•

Recursively descends the widget tree and sets the being_destroyed field
to True for the widget and all children.

•

Adds the widget to a list of widgets (the destroy list) that should be
destroyed when it is safe to do so.

Entries on the destroy list satisfy the invariant that if w2 occurs after wI on
the destroy list then w2 is not a descendent of wI. (A descendant refers to
both normal and pop-up children.)
Phase two occurs when all procedures that should execute as a result of the
current event have been called (includ~g all procedures registered with the
event and translation managers), that is, when the current invocation of
XtDispatchEvent is about to return or immediately if not in
XtDispatchEvent.
In phase two, XtDestroyWidget performs the following on each entry in
the destroy list:

•

Calls the destroy callback procedures registered on the widget (and all
descendants) in post-order (it calls children callbacks before parent
. callbacks).

•

If the widget'S parent is a subclass of compositeWidgetClass
and if the parent is not being destroyed, it calls XtUnmanageChild
on the widget and then calls the widget's parent's delete_child
procedure (see Section 3.4).

•

If the widget's parent is a subclass of constraintWidgetClass,
it calls the constraint destroy procedure for the parent, then the parent's
superclass, until finally it calls the constraint destroy procedure for
constraintWidgetClass.

•

Calls the destroy methods for the widget (and all descendants) in postorder. For each such widget, it calls the destroy procedure declared in
the widget class, then the destroy procedure declared in its superc1ass,
until finally it calls the destroy procedure declared in the Core class
record.

•

Calls XDestroyWindow if the widget is realized (that is, has an X
window). The server recursively destroys all descendant windows.

•

Recursively descends the tree and deallocates all pop-up widgets,
constraint records, callback lists and, if the widget is a subclass of

3-670 Subroutines

XtCreateWidget (3Xt)
composi teWidgetClass, children.

See Also
XtAppCreateShell(3Xt), XtCreatePopupShell(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-671

XtCreateWindow (3Xt)
Name
XtCreateWindow - window creation convenience function

Syntax
void XtCreateWindow(w, window class, visual, value mask, attributes)
Widget w;
unsigned int window_class;
Visual *visual;
XtValueMask value mask;
XSetWindowAttribUtes *attributes;

Arguments
attributes

Specifies the window attributes to use in the
XCreateWindow call.

value mask

Specifies which attribute fields to use.

visual

Specifies the visual type (usually CopyFrornParent).

Specifies the widget that is used to set the x,y coordinates
and other geometry information.

window class Specifies the Xlib window class (for example,
InputOutput, InputOnly, or CopyFrornParent).

Description
The XtCreateWindow function calls the Xlib XCreateWindow function
with values from the widget structure and the passed parameters. Then, it
assigns the created window to the widget's window field.
XtCreateWindow evaluates the following fields of the Core widget
structure:

•

depth

•
•
•
•

screen
parent -> core. window
x

3-672 Subroutines

XtCreateWindow (3Xt)
•
•

width
height

•

border_width

See Also
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-673

XtDisplay (3Xt)
Name
XtDisplay, XtParent, XtScreen, XtWindow - obtain window information
about a widget

Syntax
Display *XtDisplay(w)
Widget w;
Widget XtParent(w)
Widget w;
Screen *XtScreen(w)
Widget w;
Window XtWindow(w)
Widget w;

Arguments
w

Specifies the widget.

Description
XtDisplay returns the display pointer for the specified widget.
XtParent returns the parent widget for the specified widget.
XtScreen returns the screen pointer for the specified widget.
XtWindow returns the window of the specified widget.

See Also
XtClass(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

3-674 Subroutines

XtDisplayl nitialize (3Xt)
Name
XtDisplayInitialize, XtOpenDisplay, XtDatabase, XtCloseDisplay - initialize,
open, or close a display

Syntax
void XtToolkitInitializeO
void XtDisplayInitialize(app_context, display, application_name,
application_class, options, num_options, argc, argv)
XtAppContext app_context,
Display *display;
String application name;
String application- class;
XnnOptionDescRec *options;
Cardinal num_options;
Cardinal *argc;
String *argv;
Display *XtOpenDisplay(app_context, display_string, application_name,
application_class, options, num_options, argc, argv)
XtAppContext app_context,
String display string;
String application name;
String application-class;
XnnOptionDescRec *options;
Cardinal num options;
Cardinal *argc;
String *argv;
void XtCloseDisplay(display)
Display *display;
XnnDatabase XtDatabase(display)
Display *display;

Arguments
argc

Specifies a pointer to the number of command line
parameters.

argv

Specifies the command line parameters.

app_context

Specifies the application context.

application_class
Subroutines 3-675

XtDisplaylnitialize (3Xt)
Specifies the class name of this application, which usually is
the generic name for all instances of this application.

application_name
Specifies the name of the application instance.
display

Specifies the display from which to get the resources. Note
that a display can be in at most one application context.

num_options

Specifies the number of entries in the options list.

options

Specifies how to parse the command line for any
application-specific resources. The options argument is
passed as a parameter ,to XrrnParseCommand. For further
information, see Guide to the Xlib Library.

Description
The XtDisplaylni tialize function builds the resource database, calls
the Xlib XrrnParseCommand function to parse the command line, and
performs other per-display initialization. After XrrnParseCommand has
been called, argc and argv contain only those parameters that were not in the
standard option table or in the table specified by the options argument. If the
modified argc is not zero, most applications simply print out the modified
argv along with a message listing the allowable options. On UNIX-based
systems, the application name is usually the final component of argv[O]. If
the synchronize resource is True for the specified application,
XtDisplaylnitialize calls the Xlib XSynchronize function to put
Xlib into synchronous mode for this display connection. If the reverseVideo
resource is True, the Intrinsics exchange XtDefaul tForeground and
XtDefaul tBackground for widgets created on this display. (See Section
9.6.1.)
The XtOpenDisplay function calls XOpenDisplay the specified display
name. If display_string is NULL, XtOpenDisplay uses the current value
of the -display option specified in argv and if no display is specified in argv,
uses the user's default display (on UNIX-based systems, this is the value of
the DISPLAY environment variable).

If this succeeds, it then calls XtDisplaylni tialize and pass it the
opened display and the value of the -name option specified in argv as the
application name. If no name option is specified, it uses the application
name passed to XtOpenDisplay. If the application name is NULL, it uses
the last component of argv[O]. XtOpenDisplay returns the newly opened
display or NULL if it failed.

3-676 Subroutines

XtDisplaylnitialize (3Xt)
XtOpenDisplay is provided as a convenience to the application
programmer.

The XtCloseDisplay function closes the specified display as soon as it is
safe to do so. If called from within an event dispatch (for example, a
callback procedure), XtCloseDisplay does not close the display until the
dispatch is complete. Note that applications need only call
XtCloseDisplay if they are to continue executing after closing the
display; otherwise, they should call XtDestroyApplicationContext
or just exit.
The XtDatabase function returns the fully merged resource database that
was built by XtDisplaylnitialize associated with the display that was
passed in. If this display has not been initialized by
XtDisplayIni tialize, the results are not defined.

See Also
XtAppCreateShell(3Xt), XtCreateApplicationContext(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-677

XtGetGC (3Xt)
Name
XtGetGC, XtReleaseGC - obtain and destroy a shareable GC

Syntax
GC XtGetGC(w, value mask, values)
Widget w;
XtGCMask value mask;
XGCValues *values;
void XtReleaseGC(w, gc)
Widget w;
GCgc;

Arguments
gc

Specifies the GC to be deallocated.

values

Specifies the actual values for this GC.

value mask

Specifies which fields of the values are specified.

Specifies the widget.

Description
The XtGetGC function returns a shareable, read-only GC. The parameters
to this function are the same as those for XCreateGC except that a widget is
passed instead of a display. XtGetGC shares only GCs in which all values
in the GC returned by XCreateGC are the same. In particular, it does not
use the value_mask provided to determine which fields of the GC a widget
considers relevant. The value_mask is used only to tell the server which
fields should be filled in with widget data and which it should fill in with
default values. For further information about value_mask and values, see
XCreateGC in the Guide to the Xlib Library.
The XtReleaseGC function deallocates the specified shared GC.

See Also
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

3-678 Subroutines

XtGetResourceList (3Xt)
Name
XtGetResourceList - obtain a resource list

Syntax
void XtGetResourceList(class, resources_return, num_resources_return);
WidgetClass class;
XtResourceList *resources return;
Cardinal *num_resources_return;

Arguments
num resources return
-Specifies a pointer to where to store the number of entries in
the resource list.
resources return
Specifies a pointer to where to store the returned resource
list. The caller must free this storage using XtFree when
done with it.
widget_class

Specifies the widget class pointer for the created widget.

Description
If it is called before the widget class is initialized (that is, before the first
widget of that class has been created), XtGetResQurceList returns the
resource list as specified in the widget class record. If it is called after the
widget class has been initialized, XtGetResQurceList returns a merged
resource list that contains the resources for all superclasses.

See Also
XtGetSubresources(3Xt), XtOffset(3Xt)
Guide to -the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-679

XtGetSelectionValue (3Xt)
Name
XtGetSelectionValue, XtGetSelectionValues,
XtGetSelectionValueIncremental, XtGetSelectionValuesIncremental- obtain
selection values

Syntax
void XtGetSelectionValue(w, selection, target, callback, client_data, time)
Widget w;
Atom selection;
Atom target;
XtSelectionCallbackProc callback;
caddr_t client_data;
Time time;
void XtGetSelectionValues(w, selection, targets, count, callback, client_data,
time)
Widget w;
Atom selection;
Atom *targets;
int count;
XtSelectionCallbackProc callback;
caddr_t client data;
Time time; void XtGetSelectionValueIncremental(w, selection, target, selection_callback,
cancel callback, client data, time)
Widget w;
Atom selection;
Atom target;
XtSelectionIncrCallbackProc selection callback;
XtCancelSelectionCallbackProc cance"Ccallback;
caddr_t client data;
Time time; void XtGetSelectionValuesIncrementa1(w, selection, targets, count,
selection callback, cancel callback, client data, time)
Widget w;
Atom selection;
Atom *targets;
int count;
XtSelectionIncrCallbackProc selection callback;
XtCancelConvertSelectionProc cancel~.callback;

3-680 Subroutines

XtGetSelectionValue (3Xt)
caddr_t client data;
Time time; -

Arguments
callback

Specifies the callback procedure that is to be called when the
selection value has been obtained.

cancel callback
Specifies the callback procedure that is to be called if the
connection is lost.
client data

Specifies the argument that is to be passed to the specified
procedure when it is called.

client data

Specifies the client data (one for each target type) that is
passed to the callback procedure when it is called for that
target.

count

Specifies the length of the targets and client_data lists.

selection

Specifies the particular selection desired (that is, primary or
secondary).

selection callback
Specifies the callback procedure that is to be called to obtain
the next incremental chunk of data or for each selection value
obtained.
Specifies the type of the information that is needed about the
target
selection.
targets

Specifies the types of information that is needed about the
selection.

time

Specifies the timestamp that. indicates when the selection
value is desired.

Specifies the widget that is making the request.

Description
The XtGetSelectionValue function requests the value of the selection
that has been converted to the target type. The specified callback will be
called some time after XtGetSelectionValue is called; in fact, it may
be called before or after XtGetSelectionValue returns.

Subroutines 3-681

XtGetSelection Value (3Xt)
The XtGetSelectionValues function is similar to
XtGetSelectionVal ue except that it takes a list of target types and a
list of client data and obtains the current value of the selection converted to
each of the targets. The effect is as if each target were specified in a separate
call to XtGetSelectionValue. The callback is called once with the
corresponding client data for each target. XtGetSelectionValues does
guarantee that all the conversions will use the same selection value becaues
the ownership of the selection cannot change in the middle of the list, as
would be when calling XtGetSelectionValue repeatedly.
The XtGetSelectionValuelncremental function is similar to
XtGetSelectionVal ue except that the callback procedure will be called
repeatedly each time upon delivery of the next segment of the selection
value. The end of the selection value is detected when callback is called with
a value of length zero. If the transfer of the selection is aborted in the middle
of a transfer, the cancel_callback procedure is called so that the requestor can
dispose of the partial selection value it has collected up until that point.
The XtGetSelectionValueslncremental function is similar to
XtGetSelectionValuelncremental except that it takes a list of
targets and client_data. XtGetSelectionValuesIncremental is
equivalent to calling XtGetSelectionValueIncremental
successively for each target/client_data pair.
XtGetSelectionValuesIncremental does guarantee that all the
conversions will use the same selection value because the ownership of the
selection cannot change in the middle .of the list, as would be possible when
calling XtGetSelectionValuelncremental repeatedly.

See Also
XtAppGetSelectionTimeout(3Xt), XtOwnSelection(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

3-682 Subroutines

XtGetSubresources (3Xt)
Name
XtGetSubresources, XtGetApplicationResources - obtain subresources or
application resources

Syntax
void XtGetSubresources(w, base, name, class, resources, num_resources,
args, num args)
Widget w;
caddr_t base;
String name;
String class;
XtResourceList resources;
Cardinal num resources;
ArgList args;Cardinal num_args;
void XtGetApplicationResources(w, base, resources, num_resources, args,
num args)
Widget w;
caddr_t base;
XtResourceList resources;
Cardinal num resources;
ArgList args;Cardinal num_args;

Arguments
args

Specifies the argument list to override resources obtained
from the resource database.

base

Specifies the base address of the subpart data structure where
the resources should be written.

class

Specifies the class of the subpart.

name

Specifies the name of the subpart.

num_args

Specifies the number of arguments in the argument list.

num_resources Specifies the number of resources in the resource list.
resources

Specifies the resource list for the subpart.

Specifies the widget that wants resources for a subpart or that
identifies the resource database to search.

Subroutines 3-683

XtGetSubresources (3Xt)
Description
The XtGetSubresources function constructs a name/class list from the
application name/class, the name/classes of all its ancestors, and the widget
itself. Then, it appends to this list the name/class pair passed in. The
resources are fetched from the argument list, the resource database, or the
default values in the resource list. Then, they are copied into the subpart
record. If args is NULL, num_args must be zero. However, if num_args is
zero, the argument list is not referenced.
The XtGetApplicationResources function first uses the passed
widget, which is usually an application shell, to construct a resource name
and class list, Then, it retrieves the resources from the argument list, the
resource database, or the resource list default values. After adding base to
each address, XtGetApplicationResources copies the resources into
the address given in the resource list. If args is NULL, num_args must be
zero. However, if num_args is :z;ero, the argument list is not referenced. The
portable way to specify application resources is to declare them as members
of a structure and pass the address of the structure as the base argument.

See Also
XtGetResourceList(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

3-684 Subroutines

XtMakeGeometryRequest (3Xt)
Name
XtMakeGeometryRequest, XtMakeResizeRequest - make geometry manager
request

Syntax
XtGeometryResult XtMakeGeometryRequest(w, request, reply_return)
Widget w;
XtWidgetGeometry *request;
XtWidgetGeometry *reply_return;
XtGeometryResult XtMakeResizeRequest(w, width, height, width_return,
height return)
Widget w;
Dimension width, height;
Dimension *width_return, *height_return

Arguments
reply_return

Returns the allowed widget size or may be NULL if the
requesting widget is not interested in handling
XtGeometryAlmost.

request

Specifies the desired widget geometry (size, position, border
width, and stacking order).

Specifies the widget that is making the request.

width return
heigh~return

Return the allowed widget width and height.

Description
Depending on the condition, XtMakeGeometryRequest performs the
following:

•

If the widget is unmanaged or the widget's parent is not realized, it
makes the changes and returns XtGeometryYes.

•

If the parent is not a subclass of composi teWidgetClass or the
parent's geometry_manager is NULL, it issues an error.

•

If the widget's being_destroyed field is True, it returns
XtGeometryNo.

•

If the widget x, y, width, height and border_width fields are all equal
to the requested values, it returns XtGeometryYes; otherwise, it
Subroutines 3-685

XtMakeGeometryRequest (3Xt)
calls the parent' s geometry_manager procedure with the given
parameters.
•

If the parent's geometry manager returns XtGeometryYes and if
XtCWQueryOnly is not set in the request_mode and if the widget is
realized, XtMakeGeometryRequest calls the
XConfigureWindow Xlib function to reconfigure the widget's
window (set its size, location, and stacking order as appropriate).

•

If the geometry manager returns XtGeometryDone, the change has
been approved and actually has been done. In this case,
XtMakeGeometryRequest does no configuring and returns
XtGeometryYes. XtMakeGeometryRequest never returns

XtGeometryDone.

Otherwise, XtMakeGeometryRequest returns the resulting value from
the parent's geometry manager.
Children of primitive widgets are always unmanaged; thus,
XtMakeGeometryRequest always returns XtGeometryYes when
called by a child of a primitive widget.
The XtMakeResizeRequest function, a simple interface to
XtMakeGeometryRequest, creates a XtWidgetGeometry structure
and specifies that width and height should change. The geometry manager is
free to modify any of the other window attributes (position or stacking order)
to satisfy the resize request. If the return value is XtGeometryAlmost,
width_return and height_return contain a compromise width and height. If
these are acceptable, the widget should immediately make an
XtMakeResizeRequest and request that the compromise width and
height be applied. If the widget is not interested in XtGeometryAlmost
replies, it can pass NULL for width_return and height_return.

See Also
XtConfigureWidget(3Xt), XtQueryGeometery(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

3-686 Subroutines

XtMalioc (3Xt)
Name
XtMalloc, XtCalloc, XtRealloc, XtFree, XtNew, XtNewString - memory
management functions

Syntax
char *XtMalloc(size);
Cardinal size;
char *XtCalloc(num, size);
Cardinal num;
Cardinal size;
char *XtRealloc(ptr, num);
char *ptr;
Cardinal num;
void XtFree(ptr);
char *ptr;

type *XtNew(type);
type;
String XtNewString(string);
String string;

Arguments
num
ptr

Specifies the number of bytes or array elements.
Specifies a pointer to the old storage or to the block of
storage that is to be freed.

size

Specifies the size of an array element (in bytes) or the
number of bytes desired.

string
type

Specifies a previously declared string.
Specifies a previously declared data type.

Description
The XtMalloc functions returns a pointer to a block of storage of at least
the specified size bytes. If there is insufficient memory to allocate the new
block, XtMalloc calls XtErrorMsg.

Subroutines 3-687

XtMalioc (3Xt)
The XtCalloc function allocates space for the specified number of array
elements of the specified size and initializes the space to zero. If there is
insufficient memory to allocate the new block, XtCalloc calls
XtErrorMsg.
The XtRealloc function changes the size of a block of storage (possibly
moving it). Then, it copies the old contents (or as much as will fit) into the
new block and frees the old block. If there is insufficient memory to allocate
the new block, XtRealloc calls XtErrorMsg. If ptr is NULL,
XtRealloc allocates the new storage without copying the old contents; that
is, it simply calls XtMalloc.
The XtFree function returns storage and allows it to be reused. If ptr is
NULL, XtFree returns immediately.
XtNew returns a pointer to the allocated storage. If there is insufficient
memory to allocate the new block, XtNew calls XtErrorMsg. XtNew is a
convenience macro that calls XtMalloc with the following arguments
specified:

«type *) XtMalloc«unsigned) sizeof(type))
XtNewString returns a pointer to the allocated storage. If there is
insufficient memory to allocate the new block, XtNewString calls
XtErrorMsg. XtNewString is a convenience macro that calls
XtMalloc with the following arguments specified:

(strcpy(XtMalloc«unsigned) strlen(str) + 1), str))

See Also
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

3-688 Subroutines

XtManageChiidren (3Xt)
Name
XtManageChildren, XtManageChild, XtUnmanageChildren,
XtUnmanageChild - manage and unmanage children

Syntax
typedef Widget *WidgetList;
void XtManageChildren(children, num children)
WidgetList children;
Cardinal num_children;
void XtManageChild(child)
Widget child;
void XtUnmanageChildren(children, num children)
WidgetList children;
Cardinal num_children;
void XtUnmanageChild(child)
Widget child;

Arguments
child

Specifies the child.

children

Specifies a list of child widgets.

num children

Specifies the number of children.

Description
The XtManageChildren function performs the following:
•

Issues an error if the children do not all have the same parent or if the
parent is not a subclass of composi teWidgetClass.

•

Returns immediately if the common parent is being destroyed;
otherwise, for each unique child on the list, XtManageChildren
ignores the child if it already is managed or is being destroyed and
marks it if not.

•

If the parent is realized and after all children have been marked, it
makes some of the newly managed children viewable:

Calls the change_managed routine of the widgets' parent.
Calls XtRealizeWidget on each previously unmanaged child

Subroutines 3-689

XtManageChiidren (3Xt)
that is unrealized.
Maps each previously unmanaged child that has
map_when_managed True.
Managing children is independent of the ordering of children and
independent of creating and deleting children. The layout routine of the
parent should consider children whose. managed field is True and should
ignore all other children. Note that some composite widgets, especially fixed
boxes, call XtManageChild from their insert_child procedure.
If the parent widget is realized, its change_managed procedure is called to
notify it that its set of managed children has changed. The parent can
reposition and resize any of its children. It moves each child as needed by
calling XtMoveWidget, which first updates the x and y fields and then calls
XMoveWindow if the widget is realized.
The XtManageChild function constructs a WidgetList of length one
and calls XtManageChildren.
The XtUnmanageChildren function performs the following:
•

Issues an error if the children do not all have the same parent or if the
parent is not a subclass of compositeWidgetClass.

•

Returns immediately if the common parent is being destroyed;
otherwise, for each unique child on the list, XtUnmanageChildren
performs the following:
Ignores the child if it already is unmanaged or is being destroyed
and marks it if not.
If the child is realized, it makes it nonvisible by unmapping it.

•

Calls the change_managed routine of the widgets' parent after all
children have been marked if the parent is realized.

XtUnmanageChildren does not destroy the children widgets. Removing
widgets from a parent's managed set is often a temporary banishment, and,
some time later, you may manage the children again.

The Xt UnmanageChi 1 d function constructs a widget list of length one and
calls XtUnmanageChildren.

See Also
XtMapWidget(3Xt), XtRealizeWidget(3Xt)
Guide to the XU] Toolkit Intrinsics
Guide to the Xlib Library

3-690 Subroutines

XtMapWidget (3Xt)
Name
XtMapWidget, XtSetMappedWhenManaged, XtUnmapWidget - map and
unmap widgets

Syntax
XtMapWidget(w)
Widget w;
void XtSetMappedWhenManaged(w, map when managed)
Widget w;
Boolean map_when_managed;
XtUnmapWidget(w)
Widget w;

Arguments
map when managed
Specifies a Boolean value that indicates the new value of the
map_when_managed field.
w

Specifies the widget.

Description
If the widget is realized and managed and if the new value of
map_when_managed is True, XtSetMappedWhenManaged maps the
window. If the widget is realized and managed and if the new value of
map_when_managed is False, it unmaps the window.
XtSetMappedWhenManaged is a convenience function that is equivalent
to (but slightly faster than) calling XtSetVal ues and setting the new value
for the mappedWhenManaged resource. As an alternative to using
XtSetMappedWhenManaged to control mapping, a client may set
mapped_when_managed to False and use XtMapWidget and
XtUnmapWidget explicitly.

See Also
XtManageChildren(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-691

XtNameToWidget (3Xt)
Name
XtNameToWidget, XtWidgetToWindow - translate strings to widgets or
widgets to windows

Syntax
Widget XtNameToWidget(reference, names);
Widget reference;
String names;
Widget XtWindowToWidget(display, window)
Display *display;
Window window;

Arguments
display

Specifies the display on which the window is defined.

names

Specifies the fully qualified name of the desired widget.

reference

Specifies the widget from which the search is to start.

window

Specify the window for which you want the widget.

Description
The XtNameToWidget function looks for a widget whose name is the first
component in the specified names and that is a pop-up child of reference (or
a normal child if reference is a subclass of compositeWidgetClass). It
then uses that widget as the new reference and repeats the search after
deleting the first component from the specified names. If it cannot find the
specified widget, XtNameToWidget returns NULL.
Note that the names argument contains the name of a widget with respect to
the specified reference widget and can contain more than one widget name
(separated by periods) for widgets that are not direct children of the specified
reference widget.
If more than one child of the reference widget matches the name,
XtNameToWidget can return any of the children. The Intrinsics do not
require that all children of a widget have unique names. If the specified
names contain more than one component and if more than one child matches
the first component, XtNameToWidget can return NULL if the single
branch that it follows does not contain the named widget. That is,
XtNameToWidget does not back up and follow other matching branches of
the widget tree.
3-692 Subroutines

XtNameToWidget (3Xt)
The XtWindowToWidget function translates the specified window and
display pointer into the appropriate widget instance.

See Also
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-693

XtOffset (3Xt)
Name
XtOffset, XtNumber - determine the byte offset or number of array elements

Syntax
Cardinal XtOffset(pointer_type, field_name)
Type pointer_type;
Field Jield_name;
I

Cardinal XtNumber(array)
ArrayVariable array;

Arguments
array

Specifies a fixed-size array.

field_name

Specifies the name of the field for which to calculate the byte
offset.

pointer_type

Specifies a type that is declared as a pointer to the structure.

Description
The XtOffset macro is usually used to determine the offset of various
resource fields from the beginning of a widget and can be used at compile
time in static initializations.
The XtNumber macro returns the number of elements in the specified
argument lists, resource lists, and other counted arrays.

See Also
XtGetResourceList(3Xt), XtSetArg(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

3-694 Subroutines

XtOwnSelection (3Xt)
Name
XtOwnSelection, XtOwnSelectionlncremental, XtDisownSelection - set
selection owner

Syntax
Boolean XtOwnSelection(w, selection, time, convertyroc, lose_selection,
doneyroc)
Widget w;
Atom selection;
Time time;
XtConvertSelectionProc convertyroc;
XtLoseSelectionProc lose' selection;
XtSelectionDoneProc done yroc;
Boolean XtOwnSelectionlncremental(w, selection, time, convert_callback,
lose callback, done callback, cancel callback, client data)
Widget w;
Atom selection;
Time time;
XtConvertSelectionlncrProc convert callback;
XtLoseSelectionlncrProc lose callback;
XtSelectionDoneIncrProc done callback;
XtCancelConvertSelectionProccancel callback;
caddr_t client_data;
void XtDisownSelection(w, selection, time)
Widget w;
Atom selection;
Time time;

Arguments
cancel callback
Specifies the callback procedure that is to be called to obtain
the next incremental chunk of data or for each selection value
obtained.
client data

Specifies the argument that is to be passed to the appropriate
procedure when one of the condition occurs.

convertyroc

Specifies the procedure that is to be called whenever
someone requests the current value of the selection.

Subroutines 3-695

XtOwnSelection {3Xt}
doneyroc

Specifies the procedure that is called after the requestor has
received the selection or NULL if the owner is not interested
in being called back.

lose selection Specifies the procedure that is to be called whenever the
widget has lost selection ownership or NULL if the owner is
not interested in being called back.

selection

Specifies an atom that describes the type of the selection (for
example, XA PRIMARY, XA SECONDARY, or
XA_CLIPBOARD).
-

time

Specifies the timestamp that indicates when the selection
ownership should commence or is to be relinquished.

Specifies the widget that wishes to become the owner or to
relinquish ownership.

Description
The XtOwnSelection function informs the Intrinsics selection mechanism
that a widget believes it owns a selection. It returns T ru e if the widget has
successfully become the owner and False otherwise. The widget may fail
to become the owner if some other widget has asserted ownership at a time
later than this widget. Note that widgets can lose selection ownership either
because someone else asserted later ownership of the selection or because the
widget voluntarily gave up ownership of the selection. Also note that the
lose_selection procedure is not called if the widget fails to obtain selection
ownership in the first place.
The XtOwnSelectionIncremental informs the Intrinsics incremental
selection mechanism that the specified widget believes it owns the selection.
It returns True if the specified widget successfully becomes the selection
owner or False otherwise.
Widgets that use the incremental transfer mechanism should use
XtDisownSelection to relinquish selection ownership.
The XtDisownSelection function informs the Intrinsics selection
mechanism that the specified widget is to lose ownership of the selection. If
the widget does not currently own the selection either because it lost the
selection or because it never had the selection to begin with,
XtDisownSelection does nothing.
After a widget has called XtDisownSelection, its convert procedure is
not called even if a request arrives lat~r with a timestamp during the period
that this widget owned the selection. However, its done procedure will be

3-696 Subroutines

XtOwnSelection {3Xt}
called if a conversion that started before the call to XtDisownSelection
finishes after the call to XtDisownSelection.

See Also
XtAppGetSelectionTimeout(3Xt), XtGetSelectionValue(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-697

XtParseAcceleratorTable (3Xt)
Name
XtParseAcceleratorTable, XtlnstallAccelerators, XtInstallAllAccelerators manage accelerator tables

Syntax
XtAccelerators XtParseAcceleratorTable(source)
String source;
void XtInstallAccelerators(destination, source)
Widget destination;
Widget source;
void XtInstallAlIAccelerators(destination, source)
Widget destination;
Widget source;

Arguments
source
destination
source

Specifies the accelerator table to compile.
Specifies the widget on which the accelerators are to be
installed.
Specifies the widget or the root widget of the widget tree
from which the accelerators are to come.

Description
The XtParseAcceleratorTable function compiles the accelerator table
into the opaque internal representation.
The XtlnstallAccelerators function installs the accelerators from
source onto destination by augmenting the destination translations with the
source accelerators. If the source display_accelerator method is non-NULL,
XtlnstallAccelerators calls it with the source widget and a string
representation of the accelerator table, which indicates that its accelerators
have been installed and that it should display them appropriately. The string
representation of the accelerator table is its canonical translation table
representation.
The XtlnstallAllAccelerators function recursively descends the
widget tree rooted at source and installs the accelerators of each widget
encountered onto destination. A common use is to call
XtlnstallAllAccelerators and pass the application main window as
the source.
3-698 Subroutines

XtParseAcceleratorTable (3Xt)
See Also
XtParseTranslationTable( 1)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-699

XtParseTranslationTable (3Xt)
Name
XtParseTranslationTable, XtAugmentTranslations, XtOverrideTranslations,
XtUninstallTranslations - manage translation tables

Syntax
XtTranslations XtParseTranslationTable(table)
String table;
void XtAugmentTranslations(w, translations)
Widget w;
XtTranslations translations;
void XtOverrideTranslations(w, translations)
Widget w;
XtTranslations translations;
void XtUninstallTranslations(w)
Widget w;

Arguments
table

Specifies the translation table to compile.

translations

Specifies the compiled translation table to merge in (must not
be NULL).

Specifies the widget into which the new translations are to be
merged or removed.

Description
The XtParseTranslationTable function compiles the translation table
into the opaque internal representation of type Xt Translations. Note
that if an empty translation table is required for any purpose, one can be
obtained by calling XtParseTranslationTable and passing an empty
string.
The XtAugmentTranslations function nondestructively merges the
new translations into the existing widget translations. If the new translations
contain an event or event sequence that already exists in the widget's
translations, the new translation is ignored.
The XtOverrideTranslations function destructively merges the new
translations into the existing widget translations. If the new translations
contain an event or event sequence that already exists in the widget's

3-700 Subroutines

XtParseTranslationTable (3Xt)
translations, the new translation is merged in and override the widget's
translation.
To replace a widget's translations completely, use XtSetValues on the
XtNtranslations resource and specifiy a compiled translation table as the
value.
The XtUninstall Translations function causes the entire translation
table for widget to be removed.

See Also
XtAppAddActions(3Xt), XtCreatePopupShell(3Xt),
XtParseAcceleratorTable(3Xt), XtPopup(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-701

XtPopdown (3Xt)
Name
XtPopdown, XtCallbackPopdown, MenuPopdown - unmap a pop-up

Syntax
void XtPopdown(popup _shell)
Widget popup_shell;
void XtCallbackPopdown(w, client_data, call_data)
Widget w;
caddr_t client data;
caddr_t call_data;
void MenuPopdown(shell_name)
String shell_name;

Arguments
call data

Specifies the callback data, which is not used by this
procedure.

client data

Specifies a pointer to the XtPopdownID structure.

popup_shell

Specifies the widget shell to pop down.

shell name

Specifies the name of the widget shell to pop down.

Specifies the widget.

Description
The XtPopdown function performs the following:
•

Calls XtCheckSubclass to ensure popup_shell is a subclass of
Shell.

•

Checks that popup_shell is currently popped_up; otherwise, it
generates an error.

•

Unmaps popup_shell' s window.

•

If popup_sheIl's grabjcind is either XtGrabNonexcl usi ve or
XtGrabExclusive, it calls XtRemoveGrab.

•

Sets pop-up shell's popped_up field to False.

•

Calls the callback procedures on the shell's popdown_callback list.

3-702 Subroutines

XtPopdown (3Xt)
The XtCallbackPopdown function casts the client data parameter to an
XtPopdownID pointer:
typedef struct {
Widget shell_widget;
Widget enable_widget;
} XtPopdownIDRec, *XtPopdownID;
The shell_widget is the pop-up shell to pop down, and the enable_widget is
the widget that was used to pop it up.
XtCallbackPopdown calls XtPopdown with the specified shell_widget
and then calls XtSetSensitive to resensitize the enable_widget.

If a shell name is not given, MenuPopdown calls XtPopdown with the
widget for which the translation is specified. If a shell_name is specified in
the translation table, MenuPopdown tries to find the shell by looking up the
widget tree starting at the parent of the widget in which it is invoked. If it
finds a shell with the specified name in the pop-up children of that parent, it
pops down the shell; otherwise, it moves up the parent chain as needed. If
MenuPopdown gets to the application top-level shell widget and cannot find
a matching shell, it generates an error.

See Also
XtCreatePopupShell(3Xt), XtPopup(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-703

XtPopup (3Xt)
Name
XtPopup, XtCallbackNone, XtCallbackNonexc1usive, XtCallbackExc1usive,
MenuPopup - map a pop-up

Syntax
void XtPopup(popup _shell, grab_kind)
Widget popup_shell;
XtGrabKind grab_kind;
void XtCallbackNone(w, client data, call data)
-Widget w;
caddr_t client data;
caddr_t call_data;
void XtCallbackNonexc1usive(w, client data, call data)
-Widget w;
caddr_t client_data;
caddr_t call_data;
void XtCallbackExclusive(w, client data, call data)
Widget w;
-caddr_t client data;
caddr_t call_data;
void MenuPopup(shell name)
String shell_name;

Arguments
call data

Specifies the callback data, which is not used by this
procedure.

client data

Specifies the pop-up shell.

grab kind

Specifies the way in which user events should be constrained.

popup_shell

Specifies the widget shell to pop down.

Specifies the widget.

Description
The XtPopup function performs the following:
•

Calls XtCheckSubclass to ensure popup_shell is a subclass of
Shell.

3-704 Subroutines

XtPopup{3Xt)
•
•

Generates an error if the shell's popped_up field is already True.
Calls the callback procedures on the shell's popup_callback list.

•

Sets the shell popped_up field to True, the shell spring_loaded field to
False, and the shell grab_kind field from grab_kind.

•

If the shell's create_popup_child field is non-NULL, XtPopup calls it
with popup_shell as the parameter.

•

If grab_kind is either XtGrabNonexcl usi ve or
XtGrabExclusive, it calls:

XtAddGrab(popup_shell, (grab_kind == XtGrabExclusive), False)
•

Calls XtRealizeWidget with popup_shell specified.

•
Calls XMapWindow with popup_shell specified.
TheXtCallbackNone,XtCallbackNonexclusive,and
XtCallbackExclusive functions call XtPopup with the shell specified
by the client data argument and grab_kind set as the name specifies.
XtCallbackNone,XtCallbackNonexclusive,and
XtCallbackExcl usi ve specify XtGrabNone,
XtGrabNonexclusive, and XtGrabExclusive, respectively. Each
function then sets the widget that executed the callback list to be insensitive
by using XtSetSensi ti ve. Using these functions in callbacks is not
required. In particular, an application must provide customized code for
callbacks that create pop-up shells dynamically or that must do more than
desensitizing the button.
MenuPopup is known to the translation manager, which must perfonn
special actions for spring-loaded pop-ups. Calls to MenuPopup in a
translation specification are mapped into calls to a nonexported action
procedure, and the translation manager fills in parameters based on the event
specified on the left-hand side of a translation.
If MenuPopup is invoked on ButtonPress (possibly with modifiers), the
translation manager pops up the shell with grab_kind set to
XtGrabExcl usi ve and spring_loaded set to True. If MenuPopup is
invoked on EnterWindow (possibly with modifiers), the translation
manager pops up the shell with grab_kind set to XtGrabNonexcl usi ve
and spring_loaded set to F al s e. Otherwise, the translation manager
generates an error. When the widget is popped up, the following actions
occur:

•

Calls XtCheckSubclass to ensure popup_shell is a subclass of
Shell.

Subroutines 3-705

XtPopup (3Xt)
•

Generates an error if the shell's popped_up field is already True.

•

Calls the callback procedures on the shell's popup_callback list.

•

Sets the shell popped_up field to True and the shell grab_kind and
spring_loaded fields appropriately.

•

If the shell's create_popup_child field is non-NULL, it is called with
popup_shell as the parameter.

•
Calls:
XtAddGrab(popup_shell, (grab_kind == XtGrabExclusive), spring_loaded)
•

Calls XtRealizeWidgetwith popup_shell specified.

•

Calls XMapWindow with popup_shell specified.

(Note that these actions are the same as those for XtPopup.) MenuPopup
tries to find the shell by searching the widget tree starting at the parent of the
widget in which it is invoked. If it finds a shell with the specified name in
the pop-up children of that parent, it pops up the shell with the appropriate
parameters. Otherwise, it moves up the parent chain as needed. If
MenuPopup gets to the application widget and cannot find a matching shell,
it generates an error.

See Also
XtCreatePopupShell(3Xt), XtPopdown(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

3-706 Subroutines

XtQueryGeometry (3Xt)
Name
XtQueryGeometry - query the preferred geometry of a child widget

Syntax
XtGeometryResult XtQueryGeometry(w, intended, preferred_return)
Widget w;
XtWidgetGeometry *intended, *preferred_return;

Arguments
intended

Specifies any changes the parent plans to make to the child's
geometry or NULL.

preferred return
Returns the child widget's preferred geometry.
w

Specifies the widget.

Description
To discover a child's preferred geometry, the child's parent sets any changes
that it intends to make to the child's geometry in the corresponding fields of
the intended structure, sets the corresponding bits in intended.request_mode,
and calls XtQueryGeometry.
XtQueryGeometry clears all bits in the preferred_return->request_mode
and checks the query~eometry field of the specified widget's class record.
If query~eometry is not NULL, XtQueryGeometry calls the
query~eometry procedure and passes as arguments the specified widget,
intended, and preferred_return structures. If the intended argument is NULL,
XtQueryGeometry replaces it with a pointer to an XtWidgetGeometry
structure with request_mode=O before calling query~eometry.

See Also
XtConfigureWidget(3Xt), XtMakeGeometryRequest(3Xt)
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-707

XtRealizeWidget (3Xt)
Name
XtRealizeWidget, XtlsRealized, XtUnrealizeWidget - realize and unrealize
widgets

Syntax
void XtRealizeWidget(w)
Widget w;
Boolean XtIsRealized(w)
Widget w;
void XtUnrealizeWidget(w)
Widget w;

Arguments
Specifies the widget.

Description
If the widget is already realized, XtRealizeWidget simply returns.
Otherwise, it performs the following:

•

Binds all action names in the widget's translation table to procedures
(see Section 10.1.2).

•

Makes a post-order traversal of the widget tree rooted at the specified
widget and calls the change_managed procedure of each composite
widget that has one or more managed children.

•

Constructs an XSetWindowAttributes structure filled in with
information derived from the Core widget fields and calls the realize
procedure for the widget, which adds any widget-specific attributes and
creates the X window.

•

If the widget is not a subclass of composi teWidgetClass,
XtRealizeWidget returns; otherwise, it continues and performs the
following:

Descends recursively to each of the widget's managed children
and calls the realize procedures. Primitive widgets that
instantiate children are responsible for realizing those children
themselves.
Maps all of the managed children windows that have
mapped_when_managed True. (If a widget is managed but
3-708 Subroutines

XtRealizeWidget (3Xt)
mapped_when_managed is False, the widget is allocated visual
space but is not displayed. Some people seem to like this to
indicate certain states.}
If the widget is a top-level shell widget (that is, it has no parent), and
mapped_when_managed is True, XtRealizeWidget maps the widget
window.

The XtlsRealized function returns True if the widget has been realized,
that is, if the widget has a nonzero X window ID.
Some widget procedures (for example, set_values) might wish to operate
differently after the widget has been realized.
The XtUnrealizeWidget function destroys the windows of an existing
widget and all of its children (recursively down the widget tree). To recreate
the windows at a later time, call XtRealizeWidget again. If the widget
was managed, it will be unmanaged automatically before its window is freed.

See Also
XtManageChildren(3Xt}
Guide to the XUI Toolkit Intrinsics
Guide to the Xlib Library

Subroutines 3-709

XtSetArg (3Xt)
Name
XtSetArg, XtMergeArgLists - set and merge ArgLists

Syntax
XtSetArg(arg, name, value)
Arg arg;
String name;
XtArgVal value;
ArgList XtMergeArgLists(argsl, num_argsl, args2, num_args2)
ArgList argsl;
Cardinal num_argsl;
ArgList args2;
Cardinal num_args2;

Arguments
arg

Specifies the name-value pair to set.

argsl

Specifies the first ArgLi st.

args2

Specifies the second ArgList.

num_argsl

Specifies the number of arguments in the first argument list.

num_args2

Specifies the number of arguments in the second argument
list.

name

Specifies the name of the resource.

value

Specifies the value of the resource if it will fit in an
XtArgVal or the address.

Description
The XtSetArg function is usually used in a highly stylized manner to
minimize the probability of making a mistake; for example:
Arg args[20];
int n;
n = 0;
XtSetArg(args[n], XtNheight, 100);
XtSetArg(args[n], XtNwidth, 200);
XtSetValues(widget, args, n);

3-710 Subroutines

n++;
n++;

XtSetArg (3Xt)
Alternatively, an application can statically declare the argument list and use
XtNumber:

static Args args []
{XtNheight, (XtArgVal) lOO},
{XtNwidth, (XtArgVal) 200},
};
XtSetValues(Widget, args, XtNumber(args»;
Note that you should not use auto-increment or auto-decrement within the
first argument to XtSetArg. XtSetArg can be implemented as a macro
that dereferences the first argument twice.
The XtMergeArgLists function allocates enough storage to hold the
combined ArgList structures and copies them into it. Note that it does not
check for duplicate entries. When it is no longer needed, free the returned
storage by using XtFree.