.\".U7
.ps 11
.nr PS 11
.\".UT "Application Utility Functions" 10
\&
.sp 1
.ce 3
\s+1\fBChapter 10\fP\s-1

\s+1\fBApplication Utility Functions\fP\s-1
.sp 2
.nr H1 10
.nr H2 0
.nr H3 0
.nr H4 0
.nr H5 0
.na
.LP
.XS
Chapter 10: Application Utility Functions 
.XE
Once you have initialized the X system,
you can use the Xlib utility functions to:
.IP \(bu 5
Handle keyboard events
.IP \(bu 5
Obtain the X environment defaults
.IP \(bu 5
Parse the window geometry
.IP \(bu 5
Parse the hardware colors
.IP \(bu 5
Generate regions
.IP \(bu 5
Manipulate regions
.IP \(bu 5
Use the cut and paste buffers
.IP \(bu 5
Determine the appropriate visual 
.IP \(bu 5
Manipulate images
.IP \(bu 5
Manipulate bitmaps
.IP \(bu 5
Use the resource manager
.IP \(bu 5
Use the context manager
.RE
.NT
As a group,
the functions discussed in this chapter provide the functionality that 
is frequently needed and spans toolkits.
Many of these functions do not generate actual protocol requests to the server.
.NE
.NH 2
Keyboard Utility Functions
.XS
\*(SN Keyboard Utility Functions 
.XE
.LP
This section discusses:
.IP \(bu 5
Keyboard event functions
.IP \(bu 5
Keysym classification macros
.NH 3
Keyboard Event Functions
.XS
\*(SN Keyboard Event Functions 
.XE
.LP
The X server does not predefine the keyboard to be ASCII characters.
It is often useful to know that the ``a'' key was just pressed
or possibly that it was just released.
When a key is pressed or released, the X server sends keyboard events to client
programs.
The structures associated with keyboard events contain a keycode member that
assigns a number to each physical key on the keyboard.
See Section 8.4.1 for a discussion of keyboard event processing.
See Section 7.9 for information on how to manipulate the keyboard encoding.
.LP
Because keycodes are completely arbitrary and may differ from server to server,
client programs wanting to deal with ASCII text, for example, must explicitly
convert the keycode value into ASCII.
The transformation of keycodes to ASCII or other character sets is arbitrary.
Therefore, Xlib provides functions to help you customize the keyboard layout.
Keyboards often differ dramatically, so writing code that presumes the existence
of a particular key on the main keyboard will create portability problems.
It may also be difficult to receive
.PN KeyRelease
events on certain X server implementations because of hardware or software
restrictions.
.LP
Keyboard events are usually sent to the smallest enclosing window
which is interested in that type of event underneath the
pointer's position.
It is also possible to assign the keyboard input focus to a specific
window.
When the input focus is attached to a window,
keyboard events will go to the client which has selected
input on that window rather than the window under the pointer.
.LP
This section discusses the
functions with which you can
query the keyboard, look up the keyboard mappings,
rebind the keyboard, or use an alternate keyboard mapping file.
.NT Warning
Some implementations cannot support 
.PN KeyRelease 
events.
You should think seriously before designing software that takes
advantage of 
.PN KeyRelease
events if you are concerned about wide portability,
though there are some applications that can exploit 
.PN KeyRelease
events
to provide superior user interfaces.
You should also be very careful when selecting which keys may be used
in such applications.
It may be impossible
to guarantee the existence of a set of keys on all keyboards with the probable
exception of a-z, spacebar, and carriage return.
.NE
.sp
To look up the KeySyms, use
.PN XLookupKeysym .
.IN "XLookupKeysym" "" "@DEF@"
.FD 0
.so ./Xsrc/XLKeysym.f
.FN
.so ./Xsrc/event_ksym.a
.so ./Xsrc/index.a
.LP
.so ./Xdescrip/XLKeysym.d
.LP
.sp
To refresh the stored modifier and keymap information, use
.PN XRefreshKeyboardMapping .
.IN "XRefreshKeyboardMapping" "" "@DEF@"
.FD 0
.so ./Xsrc/XRKMap.f
.FN
.so ./Xsrc/event_map.a
.LP
.so ./Xdescrip/XRKMap.d
You usually call this function when a
.PN MappingNotify 
event occurs. 
The result is to update a client application's knowledge of the keyboard.
See Section 8.4.6.7 for information on
.PN MappingNotify
event processing.
.LP
.sp
To map a key event to an ASCII string, use
.PN XLookupString .
.IN "XLookupString" "" "@DEF@"
.FD 0
.so ./Xsrc/XLookStr.f
.FN
.so ./Xsrc/event_key.a
.so ./Xsrc/buffer_ptr.a
.so ./Xsrc/buf_length.a
.so ./Xsrc/keysym.a
.so ./Xsrc/status_str.a
.LP
.so ./Xdescrip/XLookStr.d
It returns the translated string into the user's buffer.  
It also detects any rebound keysyms (see
.PN XRebindKeysym ) 
and returns the specified bytes.
.PN XLookupString
returns, as its value, the length of the string stored in the tag buffer.
If the lock modifier has a caps_lock key associated with it,
.PN XLookupString
interprets the lock modifier to perform caps lock processing.
.LP
.sp
To rebind the meaning of a keysym for a client, use
.PN XRebindKeysym .
.IN "XRebindKeysym" "" "@DEF@"
.FD 0
.so ./Xsrc/XRKeySym.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/keysym_reb.a
.so ./Xsrc/list_reb.a
.so ./Xsrc/mod_count.a
.so ./Xsrc/str_rebind.a
.so ./Xsrc/num_bytes.a
.LP
.so ./Xdescrip/XRKeySym.d
It does not redefine the keycode in the X server but merely
provides an easy way for long strings to be attached to keys.
.PN XLookupString 
.IN "XLookupString" 
returns this string when the appropriate set of
modifier keys are pressed and when the keysym would have been used for
the translation.
Note that you can rebind a keysym that may not exist.
.LP
.sp
To convert the name of the keysym to the keysym code, use
.PN XStringToKeysym .
.IN "XStringToKeysym" "" "@DEF@"
.FD 0
.so ./Xsrc/XSTKeysym.f
.FN
.so ./Xsrc/string_ksym.a
.LP
Valid keysym names are listed in
.Pn < X11/keysymdef.h >.
If the specified string does not match a valid keysym,
.PN XStringToKeysym
returns
.PN NoSymbol .
.LP
.sp
To convert a keysym code to the name of the keysym, use
.PN XKeysymToString .
.IN "XKeysymToString" "" "@DEF@"
.FD 0
.so ./Xsrc/XKTString.f
.FN
.so ./Xsrc/keysym_str.a
.LP
The returned string is in a static area and must not be modified.
If the specified keysym is not defined,
.PN XKeysymToString
returns a NULL.
.LP
.sp
To convert a key code to a defined keysym, use
.PN XKeycodeToKeysym .
.IN "XKeycodeToKeysym" "" "@DEF@"
.FD 0
.so ./Xsrc/XKTKeysym.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/keycode.a
.so ./Xsrc/col.a
.LP
.PN XKeycodeToKeysym
uses internal Xlib tables, 
which already have converted alphabetic upper case to lowercase, 
and returns the keysym defined for the specified keycode and
the element of the keycode vector.
.LP
.sp
To convert a keysym to the appropriate keycode, use
.PN XKeysymToKeycode .
.IN "XKeysymToKeycode" "" "@DEF@"
.FD 0
.so ./Xsrc/XKTKeycode.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/keysym_kcode.a
.LP
If the specified keysym is not defined for any keycode,
.PN XKeysymToKeycode
returns zero.
.NH 3
Keysym Classification Macros
.XS
\*(SN Keysym Classification Macros 
.XE
.LP
You may want to test if a keysym of the defined set (XK_MISCELLANY)
is, for example, on the key pad or the function keys.
You can use the keysym macros to perform the following tests.
.LP
.sp
.FD 0
IsKeypadKey\^(\^\fIkeysym\fP\^)
.FN
Returns
.PN True
if the keysym is on the key pad.
.LP
.sp
.FD 0
IsCursorKey\^(\^\fIkeysym\fP\^)
.FN
Returns
.PN True
if the keysyum is on the cursor key.
.LP
.sp
.FD 0
IsPFKey\^(\^\fIkeysym\fP\^)
.FN
Returns 
.PN True
if the keysyum is on the PF keys.
.LP
.sp
.FD 0
IsFunctionKey\^(\^\fIkeysym\fP\^)
.FN
Returns 
.PN True
if the keysyum is on the function keys.
.LP
.sp
.FD 0
IsMiscFunctionKey\^(\^\fIkeysym\fP\^)
.FN
Returns 
.PN True
if the keysyum is on the miscellaneous function keys.
.LP
.sp
.FD 0
IsModifierKey\^(\^\fIkeysym\fP\^)
.FN
Returns 
.PN True
if the keysyum is on the modifier keys.
.NH 2
Obtaining the X Environment Defaults
.XS
\*(SN Obtaining the X Environment Defaults 
.XE
.LP
A program often needs a variety of options in the X environment
(for example, fonts, colors, mouse, background, text, cursor).
Specifying these options on the command line is inefficient and
unmanageable because individual users have a variety of tastes
with regard to window appearance.
.PN XGetDefault
makes it easy to find out the fonts, colors, and
other environment defaults favored by a particular user.
Defaults are usually loaded into the RESOURCE_MANAGER property 
on the root window at login.
If no such property exists,
a resource file in the user's home directory is loaded.
On a UNIX-based system, 
this file is
.PN "$HOME/.Xdefaults" .
.IN "Files" "$HOME/.Xdefaults"
After loading these defaults,
.PN XGetDefault
merges additional defaults specified by the XENVIRONMENT
environment variable.
If XENVIRONMENT is defined,
it contains a full path name for the additional resource file.
If XENVIRONMENT is not defined,
.PN XGetDefault
looks for
.PN "$HOME/.Xdefaults-\fIname\fP" ,
where \fIname\fP specifies the name of the machine on which the application
is running.
See section 10.11 for details of the format of these files.
.LP
.PN XGetDefaults 
provides a simple interface for clients not wishing to use
the X toolkit or the more elaborate interfaces provided by the
resource manager discussed in section 10.11.
.LP
The strings returned by 
.PN XGetDefault
are owned by Xlib and should not
be modified or freed by the client.
.IN "Default Options"
The definition for this function is:
.IN "XGetDefault" "" "@DEF@"
.FD 0
.so ./Xsrc/XGetDefault.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/program.a
.so ./Xsrc/option.a
.LP
.PN XGetDefault
returns the value NULL if the option name specified in this argument does
not exist for the program.
.NH 2
Parsing the Window Geometry
.XS
\*(SN Parsing the Window Geometry 
.XE
.LP
Xlib provides functions with which you can parse the window geometry.
.LP
.sp
To parse standard window geometry strings, use
.PN XParseGeometry .
.IN "Window" "Initial Location"
.IN "XParseGeometry" "" "@DEF@"
.LP
.FD 0
.so ./Xsrc/XParseGeom.f
.FN
.so ./Xsrc/parsestring.a
.so ./Xsrc/xy_ret.a
.so ./Xsrc/widtheight2.a
.LP
By convention,
X applications use a standard string to indicate window size and placement.
.PN 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:
.IP
\fI=<width>x<height>{+-}<xoffset>{+-}<yoffset>\fP 
.LP
The items in this form map into the arguments associated with this
function.
.LP
The
.PN XParseGeometry
function returns a bitmask that indicates which of the four values (width,
height, xoffset, and yoffset) were
actually found in the string and that indicates 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 these constants:
.PN XValue , 
.PN YValue , 
.PN WidthValue , 
.PN HeightValue ,
.PN XNegative , 
.PN YNegative
and are defined in 
.Pn < X11/Xutil.h >.
They will be set whenever one of the values are defined or signs
are set.
.LP
If the function returns either the 
.PN XValue 
or 
.PN YValue 
flag,
you should
place the window at the requested position.
The border width (bwidth),
size of the increments width and height
(typically font width and height),
and any additional interior space (xadder and yadder)
are passed in to make it easy to compute the resulting size.
It is not normally used by user programs, which typically use
the 
.PN XCreateWindow
or 
.PN XCreateSimpleWindow
function to create the window.
.IN "XCreateWindow"
.IN "XCreateSimpleWindow"
.LP
.sp
To parse window geometry given an argument and a default position, use
.PN XGeometry .
.IN "Window" "Initial Location"
.IN "Window" "Computing Placement"
.IN "XGeometry" "" "@DEF@"
.program
.FD 0
.so ./Xsrc/XGeometry.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/screen.a
.so ./Xsrc/posdef.a
.so ./Xsrc/bwidth.a
.so ./Xsrc/fwdht.a
.so ./Xsrc/xyadder.a
.so ./Xsrc/xy_ret.a
.so ./Xsrc/widtheight2.a
.LP
The
.PN XGeometry 
function returns the position the window should be placed given a position and
a default position.
.PN XGeometry
determines the placement of
a window using the current format to position windows.
Given a fully qualified default geometry specification and, possibly,
an incompletely specified geometry specification, it 
will return a bitmask
value as defined above in the 
.PN XParseGeometry
call.
.NH 2
Parsing the Color Specifications
.XS
\*(SN Parsing the Color Specifications 
.XE
.LP
To parse color values, use
.PN XParseColor .
.IN "Color" "parsing command lines"
.IN "XParseColor" "" "@DEF@"
.FD 0
.so ./Xsrc/XParseColor.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/cmap.a
.so ./Xsrc/spec.a
.so ./Xsrc/def.a
.LP 
The
.PN 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 
.PN XGetDefault 
option, and returns the corresponding red, green, and blue
values that are suitable for a subsequent call to 
.PN XAllocColor 
or
.PN XStoreColor .
The color can be specified either as a color name (as in 
.PN XAllocNamedColor )
or as an initial sharp sign character following by a numeric specification,
in one of the following formats:
.LP
.Ds 0
.TA .5i 3i
.ta .5i 3i
.R
	#RGB	(4 bits each)
	#RRGGBB	(8 bits each)
	#RRRGGGBBB	(12 bits each)
	#RRRRGGGGBBBB	(16 bits each)
.De
The R, G, and B represent single hexadecimal digits (upper or lower case).
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 color map is used only to determine which screen to look up the color on.
For example,
you can use the screen's default color map.
.LP
This routine will fail and return zero status
either if the initial character is a sharp sign, but the string
otherwise fails to fit of the above formats, or if the initial character is
not a sharp sign and the named color does not exist in the server's database.
.LP
.ds fd .PN XParseColor
.so ./Xsrc/errsent4.com
.PN BadColor 
error.
.NH 2
Generating Regions 
.XS
\*(SN Generating Regions
.XE
.LP
Regions are arbitrary collections of pixels.
Xlib provides functions for manipulating regions.
The opaque type 
.PN Region
is defined in 
.Pn < X11/Xutil.h >.
.LP
.sp
To generate a region from points, use
.PN XPolygonRegion .
.IN "XPolygonRegion" "" "@DEF@"
.FD 0
.so ./Xsrc/XPolyRegion.f
.FN
.so ./Xsrc/points1.a
.so ./Xsrc/n1.a
.so ./Xsrc/fill_rule.a
.LP 
.so ./Xdescrip/XPolyRegion.d
See 
.PN XCreateGC
in Section 5.3
for an explanation of fill_rule.
.IN "XCreateGC"
.LP
.sp
To generate the smallest enclosing rectangle in rect, use
.PN XClipBox .
.IN "XClipBox" "" "@DEF@"
.FD 0
.so ./Xsrc/XClipBox.f
.FN
.so ./Xsrc/r.a
This is the region in which the rectangle is located.
.so ./Xsrc/rect.a
This is the rectangle in which the smallest enclosing rectangle is generated.
.LP
.so ./Xdescrip/XClipBox.d
.NH 2
Manipulating Regions
.XS
\*(SN Manipulating Regions 
.XE
.LP
Xlib provides functions with which you can manipulate regions.
This section discusses how to:
.IP \(bu 5
Create, copy, or destroy regions
.IP \(bu 5
Move or shrink regions
.IP \(bu 5
Compute with regions
.IP \(bu 5
Determine if regions are empty or equal
.IP \(bu 5
Locate a point or rectangle in a region
.LE
.NH 3
Creating, Copying, or Destroying Regions
.XS
\*(SN Creating, Copying, or Destroying Regions 
.XE
.LP
Xlib provides functions with which you can create, copy, or destroy a region.
.LP
.sp
To create a new empty region, use
.PN XCreateRegion .
.IN "XCreateRegion" "" "@DEF@"
.FD 0
.so ./Xsrc/XCreRegion.f
.FN
.LP
.sp
To set the graphics contexts to the specified region, use
.PN XSetRegion .
.IN "XSetRegion" "" "@DEF@"
.FD 0
.so ./Xsrc/XSetRegion.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/gc.a
.so ./Xsrc/r.a
This is the region in which you want to set the specified graphics context.
.LP
.so ./Xdescrip/XSetRegion.d
.LP 
.sp
To deallocate the storage associated with a specified region, use
.PN XDestroyRegion .
.IN "XDestroyRegion" "" "@DEF@"
.FD 0
.so ./Xsrc/XDestroyReg.f
.FN
.so ./Xsrc/r.a
.NH 3
Moving or Shrinking Regions
.XS
\*(SN Moving or Shrinking Regions 
.XE
.LP
Xlib provides functions with which you can move or shrink regions.
.LP
.sp
To move the specified region by a specified amount, use 
.PN XOffsetRegion .
.IN "XOffsetRegion" "" "@DEF@"
.FD 0
.so ./Xsrc/XOffsetReg.f
.FN
.so ./Xsrc/r.a
.so ./Xsrc/dxdy.a
These coordinates define the amount by which you want to move the specified region.
.LP 
.sp
To reduce the specified region by a specified amount, use
.PN XShrinkRegion .
.IN "XShrinkRegion" "" "@DEF@"
.FD 0
.so ./Xsrc/XShrinkReg.f
.FN
.so ./Xsrc/r.a
.so ./Xsrc/dxdy.a
These coordinates define the amount by which you want to shrink the specified region.
.LP
Positive values shrink the size of the region, while negative values expand
the region.
.NH 3
Computing with Regions
.XS
\*(SN Computing with Regions 
.XE
.LP
Xlib provides functions with which you can compute the intersection, union,
or results of two regions.
.LP
.sp
To compute the intersection of two regions, use
.PN XIntersectRegion .
.IN "XIntersectRegion" "" "@DEF@"
.FD 0
.so ./Xsrc/XInterReg.f
.FN
.so ./Xsrc/srasrb.a
.so ./Xsrc/dr.a
.LP
.sp
To compute the union of two regions, use
.PN XUnionRegion .
The definition for this function is:
.IN "XUnionRegion" "" "@DEF@"
.FD 0
.so ./Xsrc/XUnionRegion.f
.FN
.so ./Xsrc/srasrb.a
.so ./Xsrc/dr.a
.LP
.sp
To create a union of a source region and a rectangle, use
.PN XUnionRectWithRegion .
.IN "XUnionRectWithRegion" "" "@DEF@"
.FD 0
.so ./Xsrc/XURWReg.f
.FN
.so ./Xsrc/rectangle.a
.so ./Xsrc/src_region.a
.so ./Xsrc/des_region.a
.LP
.so ./Xdescrip/XURWReg.d
.LP
.sp
To subtract two regions, use
.PN XSubtractRegion .
.IN "XSubtractRegion" "" "@DEF@"
.FD 0
.so ./Xsrc/XSubtractReg.f
.FN
.so ./Xsrc/srasrb.a
.so ./Xsrc/dr.a
.LP
.PN XSubtractRegion
subtracts region B from region A.
.LP
.sp
To calculate the difference between the union and intersection 
of two regions, use
.PN XXorRegion .
.IN "XXorRegion" "" "@DEF@"
.FD 0
.so ./Xsrc/XXorRegion.f
.FN
.so ./Xsrc/srasrb.a
.so ./Xsrc/dr.a
.NH 3
Determining If Regions Are Empty or Equal
.XS
\*(SN Determining If Regions Are Empty or Equal 
.XE
.LP
Xlib provides functions with which you can determine if regions are 
empty or equal.
.LP
.sp
To determine if the specified region is empty, use
.PN XEmptyRegion .
.IN "XEmptyRegion" "" "@DEF@"
.FD 0
.so ./Xsrc/XEmptyRegion.f
.FN
.so ./Xsrc/r.a
.LP 
The
.PN XEmptyRegion 
function returns 
nonzero if the region is empty.
.LP
.sp
To determine if two regions have the same offset, size, and shape, use
.PN XEqualRegion .
.IN "XEqualRegion" "" "@DEF@"
.FD 0
.so ./Xsrc/XEqualRegion.f
.FN
.so ./Xsrc/r1r2.a
These are the regions you want to determine have the same offset, size, and shape.
.LP
The
.PN XEqualRegion
function returns nonzero if the two regions are identical
(that is, they have the same offset, size, and shape).
.NH 3
Locating a Point or a Rectangle in a Region
.XS
\*(SN Locating a Point or a Rectangle in a Region 
.XE
.LP
Xlib provides functions with which you can determine if a point
or a rectangle is contained in a region.
.LP
.sp
To determine if a specified point resides in a specified region, use
.PN XPointInRegion .
.IN "XPointInRegion" "" "@DEF@"
.FD 0
.so ./Xsrc/XPointInReg.f
.FN
.so ./Xsrc/r.a
.so ./Xsrc/xy.a
These define the coordinates of the point.
.LP
.so ./Xdescrip/XPointInReg.d
.LP
.sp
To determine if a specified rectangle resides in the specified region, use
.PN XRectInRegion .
The definition for this function is:
.IN "XRecInRegion" "" "@DEF@"
.FD 0
.so ./Xsrc/XRectInReg.f
.FN
.so ./Xsrc/r.a
.so ./Xsrc/xy.a
These define the coordinates of the point.
.so ./Xsrc/widtheight.a
These specify the rectangle in which you want to determine the point resides.
.LP 
.so ./Xdescrip/XRectInReg.d
.NH 2
Using the Cut and Paste Buffers
.XS
\*(SN Using the Cut and Paste Buffers 
.XE
.LP
Xlib provides functions with which you can use cut and paste buffers
for programs using this form of communications.
See also the sections on selections, which are a more
useful mechanism for interchanging data between clients,
as typed information can be exchanged.
X provides areas of memory in which bytes can be stored for implementing
cut and paste between windows
.IN "Cut Buffers"
.IN "Paste Buffers"
(implemented by use of properties on the first root window of the display).
It is up to applications to agree on how to represent the 
data in the buffers.
The data is most often ISO Latin 1 text.
The atoms for eight such buffers are provided, 
which can be accessed as a ring or as explicit buffers (numbered 0 through 7).
These buffers are typically used by either XYO applications or Andrew
applications.
We encourage new applications to share data by using selections.
See Section 4.4 for further information.
.LP
.sp
To store data in cut buffer 0, use 
.PN XStoreBytes .
.IN "XStoreBytes" "" "@DEF@"
.FD 0
.so ./Xsrc/XStoreBytes.f
.FN 
.so ./Xsrc/display.a
.so ./Xsrc/bytes.a
.so ./Xsrc/nbytes2.a
.LP
.so ./Xdescrip/XStoreBytes.d
Note that the cut buffer's contents need not be text, so null bytes 
are not special.
The cut buffer's contents may be retrieved later by
any client calling 
.PN XFetchBytes .
.IN "XFetchBytes"
.LP
.ds fd .PN XStoreBytes
.so ./Xsrc/errsent.com
.PN BadAlloc
and
.PN BadWindow 
errors.
.LP
.sp
To store data in a specified cut buffer, use
.PN XStoreBuffer .
.IN "XStoreBuffer" "" "@DEF@"
.FD 0
.so ./Xsrc/XStoreBuffer.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/bytes.a
.so ./Xsrc/nbytes2.a
.so ./Xsrc/buffer.a
.LP
.ds fd .PN XStoreBuffer
.so ./Xsrc/errsent.com
.PN BadAlloc ,
.PN BadAtom ,
and 
.PN BadWindow 
errors.
.LP
.sp
To return data from cut buffer 0, use 
.PN XFetchBytes .
.IN "XFetchBytes" "" "@DEF@"
.FD 0
.so ./Xsrc/XFetchBytes.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/nbytes.a
.PN XFetchBytes
returns the number of bytes in this argument.
If there is no data in the buffer, 
the value zero is returned to this argument.
.LP
.so ./Xdescrip/XFetchBytes.d
The
.PN XFetchBytes
function
returns the number of bytes in the nbytes argument,
if the buffer contains data.
Otherwise, the function
returns NULL and sets nbytes to zero.
The appropriate amount of storage is allocated and the pointer returned.
The client must free this storage when finished with it by calling
.PN XFree .
(See Section 2.4 for further information.)
Note that the cut buffer does not necessarily contain text, so it may
contain embedded null bytes and may not terminate with a null byte.
.LP
.ds fd .PN XFetchBytes
.so ./Xsrc/errsent4.com
.PN BadWindow 
error.
.LP
.sp
To return data from a specified cut buffer, use 
.PN XFetchBuffer .
.IN "XFetchBuffer" "" "@DEF@"
.FD 0
.so ./Xsrc/XFetchBuffer.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/nbytes.a
.so ./Xsrc/buffer1.a
.LP
.so ./Xdescrip/XFetchBuffer.d
.LP
.ds fd .PN XFetchBuffer
.so ./Xsrc/errsent4.com
.PN BadValue 
error.
.LP
.sp
To rotate the cut buffers, use 
.PN XRotateBuffers .
.IN "XRotateBuffers" "" "@DEF@"
.FD 0
.so ./Xsrc/XRotateBufs.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/rotate.a
.LP 
.so ./Xdescrip/XRotateBufs.d
Note that 
.PN XRotateBuffers
will generate an error if any of the eight buffer have not been created.
.LP
.ds fd .PN XRotateBuffers
.so ./Xsrc/errsent.com
.PN BadAtom ,
.PN BadMatch ,
and
.PN BadWindow 
errors.
.NH 2
Determining the Appropriate Visual Type
.XS
\*(SN Determining the Appropriate Visual Type
.XE
.LP
A single display may support multiple screens.
Each screen can have several different visual types supported 
at different depths.
You can use the functions described in this section to determine
which visual to use for your application.
.LP
The functions in this section use the 
.PN XVisualInfo 
structure,
which can be found in 
.Pn < X11/Xutil.h >.
.LP
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	Visual *visual;
	VisualID visualid;
	int screen;
	unsigned int depth;
	int class;
	unsigned long red_mask;
	unsigned long green_mask;
	unsigned long blue_mask;
	int colormap_size;
	int bits_per_rgb;
} XVisualInfo;
.De
.IN "XVisualInfo"
.IN "XVisualInfo" "" "@DEF@"
The definitions used for the visual information mask (vinfo_mask) are:
.LP
.Ds 0
.TA .5i 3i
.ta .5i 3i
#define VisualNoMask	0x0
#define VisualIDMask	0x1
#define VisualScreenMask	0x2
#define VisualDepthMask	0x4
#define VisualClassMask	0x8
#define VisualRedMaskMask	0x10
#define VisualGreenMaskMask	0x20
#define VisualBlueMaskMask	0x40
#define VisualColormapSizeMask	0x80
#define VisualBitsPerRGBMask	0x100
#define VisualAllMask	0x1FF
.De
.sp
To obtain a list of visual information structures that match a specified
template, use
.PN XGetVisualInfo .
.IN "XGetVisualInfo" "" "@DEF@"
.FD 0
.so ./Xsrc/XGetVInfo.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/vinfo_mask.a
.so ./Xsrc/vinfo_temp.a
.so ./Xsrc/v_nitems.a
.LP
.so ./Xdescrip/XGetVInfo.d
To free the data returned by this function, use
.PN XFree .
(See Section 2.4 for further information.)
.LP
.sp
To obtain the visual information that matches the specified depth and
class of the screen, use
.PN XMatchVisualInfo .
The definition for this function is:
.IN "XMatchVisualInfo" "" "@DEF@"
.FD 0
.so ./Xsrc/XMatVInfo.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/screen.a
.so ./Xsrc/v_depth.a
.so ./Xsrc/v_class.a
.so ./Xsrc/vinfo.a
.LP
The
.PN XMatchVisualInfo
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,
this function returns 
.PN True ,
and the information on the visual is returned
to the vinfo argument.
Otherwise, when a visual is not found,
it returns 
.PN False .
.NH 2
Manipulating Images
.XS
\*(SN Manipulating Images 
.XE
.LP
Xlib provides several functions that perform basic operations on images.
All operations on images are defined using an 
.PN XImage 
structure, 
as defined in
.Pn < X11/Xlib.h >.
Because the number of different types of image formats can be very large,
this hides details of image storage properly from applications.
.LP
This section describes the functions for generic operations on images.
Manufacturers can provide very fast implementations of these for the
formats frequently encountered on their hardware.
These functions are neither sufficient nor desirable to use for general image
processing.
Rather, they are here to provide minimal functions on screen format
images.
The basic operations for getting and putting images are
.PN XGetImage
and 
.PN XPutImage .
See Chapter 6 for further information about these functions.
.NT
The functions to read and write images to and from
disk files are not, as yet, defined.
.NE
Most of the fields are defined in the core protocol to specify hardware
variants, bit and byte ordering you may encounter across manufacturers.
See section 6.7 for a description of the XImage structure.
.LP
The
.PN XImage 
structure describes an image as it exists in the client's memory.  
The user may request that some of the members such as height, width, 
and xoffset be changed when the image is sent to the server.
Note that bytes_per_line in concert with offset can be used to
extract the image to be only the subset.
Other members (for example, byte order, bitmap_unit, and so forth)
are characteristics of both the image and of the server.  
If these members
differ between the image and the server, 
.PN XPutImage 
makes the appropriate conversions.
See Chapter 6 for information about
.PN XPutImage .
If the image is formatted as an XYPixmap, that is the format member is set to
the constant
.PN XYPixmap , 
the first byte of the first line of
plane n must be located at the address (data + (n * height * bytes_per_line)).
.LP
.sp
To allocate sufficient memory for an 
.PN XImage 
structure, use
.PN XCreateImage .
.IN "XCreateImage" "" "@DEF@"
.FD 0
.so ./Xsrc/XCreImage.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/visual_img.a
.so ./Xsrc/depth_img.a
.so ./Xsrc/format_img.a
.so ./Xsrc/offset.a
.so ./Xsrc/data_img.a
.so ./Xsrc/width_img.a
.so ./Xsrc/height_img.a
.so ./Xsrc/xpad.a
.so ./Xsrc/bytesperln.a
.LP
.so ./Xdescrip/XCreImage.d
This function does not allocate space for the image itself.
Rather, it initializes the structure with ``default'' values and
returns a pointer to the 
.PN XImage 
structure.
The red, green, and blue mask values are defined for Z format images only
and are derived from the 
.PN Visual 
structure passed in.
.LP
Note that when the image is created using
.PN XCreateImage
or 
.PN XGetImage ,
the destroy procedure that the 
.PN XDestroyImage
macro calls usually frees both the image structure 
and the data pointed to by the image structure.
.LP
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 macros to call through the image object are defined in
.Pn < X11/Xutil.h >.
.LP
.sp
To obtain a pixel value in an image, use
.PN XGetPixel .
.IN "XGetPixel" "" "@DEF@"
.FD 0
.so ./Xsrc/XGetPixel.f
.FN
.so ./Xsrc/ximage.a
.so ./Xsrc/xy.a
.LP
.so ./Xdescrip/XGetPixel.d
The X and Y coordinates are relative to the origin (upper left [0,0]) of the 
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).
.LP
.sp
To set a pixel value in an image, use
.PN XPutPixel .
.IN "XPutPixel" "" "@DEF@"
.FD 0
.so ./Xsrc/XPutPixel.f
.FN
.so ./Xsrc/ximage.a
.so ./Xsrc/xy.a
.so ./Xsrc/pixel_img.a
.LP
.so ./Xdescrip/XPutPixel.d
The X and Y coordinates are relative to the origin (upper left [0,0])
of the image.
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.
.LP
.sp
To create a subimage, use
.PN XSubImage .
.IN "XSubImage" "" "@DEF@"
.FD 0
.so ./Xsrc/XSubImage.f
.FN
.so ./Xsrc/ximage.a
.so ./Xsrc/xy.a
.so ./Xsrc/sub_width.a
.so ./Xsrc/sub_height.a
.LP
.so ./Xdescrip/XSubImage.d
It allocates the memory necessary for the new 
.PN XImage 
structure
and returns a pointer to the new image.
The algorithm used is repetitive calls to
.PN XGetPixel
and 
.PN XPutPixel .
Therefore, this function may be very slow.
.LP
.sp
To increment each pixel in the pixmap by a constant value, use
.PN XAddPixel .
.IN "XAddPixel" "" "@DEF@"
.FD 0
.so ./Xsrc/XAddPixel.f
.FN
.so ./Xsrc/ximage.a
.so ./Xsrc/value_img.a
.LP
.so ./Xdescrip/XAddPixel.d
This function is very useful when you have a base pixel value from allocating
color resources and need to manipulate the image to that form.
.LP
.sp
To deallocate the memory allocated in a previous call to
.PN XCreateImage ,
use
.PN XDestroyImage .
.IN "XDestroyImage" "" "@DEF@"
.FD 0
.so ./Xsrc/XDestImage.f
.FN
.so ./Xsrc/ximage.a
.LP
.so ./Xdescrip/XDestImage.d
.LP
Note that when the image is created using
.PN XCreateImage
or 
.PN XGetImage ,
the destroy procedure that this macro calls usually
frees both the image structure and the data pointed to by the image structure. 
.NH 2
Manipulating Bitmaps
.XS
\*(SN Manipulating Bitmaps 
.XE
.LP
Xlib provides functions with which you can read a bitmap from a file,
save a bitmap to a file, or create a bitmap. 
This section describes those functions that transfer bitmaps to and
from the client's file system, thus allowing their reuse in a later
connection (for example, from an entirely different client or to a
different display or server).
.LP
.sp
To read a bitmap in from disk, use
.PN XReadBitmapFile .
.IN "XReadBitmapFile" "" "@DEF@"
.FD 0
.so ./Xsrc/XRBitFile.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/d.a
.so ./Xsrc/filename.a
.so ./Xsrc/widtheight3.a
.so ./Xsrc/read_bmap.a
.so ./Xsrc/xy_hot2.a
.LP
.so ./Xdescrip/XRBitFile.d
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 newer X version 11 bitmap format.
If the file cannot be opened, 
.PN XReadBitmapFile 
returns 
.PN BitmapOpenFailed .  
If the file can be opened but does not contain valid bitmap data, 
it returns 
.PN BitmapFileInvalid .  
If insufficient working storage is allocated,
it returns
.PN BitmapNoMemory .  
If the file is readable and valid,
it returns 
.PN BitmapSuccess .
.LP
.PN XReadBitmapFile 
assigns the bitmap's height and width, as read
from the file, to the caller's variables width and height.  
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 
.PN XFreePixmap 
when done.
If x_hot and y_hot are non-NULL, 
.PN XReadBitmapFile 
sets *x_hot and *y_hot to the value of the hot spot as defined 
in the file.
If no hot spot is defined, 
.PN XReadBitmapFile 
sets *x_hot and *y_hot to -1,-1.
.LP
.sp
To write out a bitmap to a file, use
.PN XWriteBitmapFile .
.IN "XWriteBitmapFile" "" "@DEF@"
.FD 0
.so ./Xsrc/XWBitFile.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/filename.a
.so ./Xsrc/write_bmap.a
.so ./Xsrc/widtheight.a
These are the dimensions of the bitmap to be written.
.so ./Xsrc/xy_hot.a
.LP
.so ./Xdescrip/XWBitFile.d
The file is written out in X version 11 bitmap format,  
which is the format used by the X version 11 bitmap program.  
Refer to that program's man pages
for details.  
While 
.PN XReadBitmapFile 
can read in either X
version 10 format or X version 11 format, 
.PN XWriteBitmapFile 
always writes out X version 11 format only.
If the file cannot be opened for writing, 
it returns 
.PN BitmapOpenFailed .  
If insufficient memory is allocated
it returns
.PN BitmapNoMemory .
Otherwise, on no error,
it returns
.PN BitmapSuccess .
If x_hot and y_hot are not -1, -1, 
.PN XWriteBitmapFile
writes them out as the hot spot coordinates for the bitmap.
.LP
.sp
To create a pixmap and then perform a bitmap-format of the data into it, use
.PN XCreatePixmapFromBitmapData .
.IN "XCreatePixmapFromBitmapData" "" "@DEF@"
.FD 0
.so ./Xsrc/XCPFBitData.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/d.a
.so ./Xsrc/data2.a
.so ./Xsrc/widtheight.a
These are the dimensions of the pixmap to create.
.so ./Xsrc/fg_bg.a
.so ./Xsrc/depth1.a
.LP
.so ./Xdescrip/XCPFBitData.d
This is a convenience routine that clients could do manually.
.LP
.sp
To include a bitmap written out by 
.PN XWriteBitmapFile 
.IN "XWriteBitmapFile"
in a program directly, as opposed to reading it in every time at run time, use
.PN XCreateBitmapFromData .
.IN "XCreateBitmapFromData" "" "@DEF@"
.FD 0
.so ./Xsrc/XCreBmap.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/d.a
This is used to determine which screen to create the bitmap on.
.so ./Xsrc/data_bmap.a
.so ./Xsrc/widtheight.a
These are the dimensions of the bitmap to create.
.LP
.so ./Xdescrip/XCreBmap.d
The following is an example of getting a gray bitmap:
.LP
.Ds 0
#include "gray.bitmap"
.sp 6p
Pixmap XCreateBitmapFromData(display, window, gray_bits, gray_width, gray_height);
.De
If insufficient working storage was allocated,
.PN XCreateBitmapFromData 
returns NULL.
It is the user's responsibly to free the
bitmap using 
.PN XFreePixmap 
when done.
.NH 2
Using the Resource Manager
.XS
\*(SN Using the Resource Manager 
.XE
.LP
The resource manager is a database manager but with a twist.
In most data base systems, 
you perform a query using a imprecise specification 
and get back a set of records.
The resource manager, however, allows you to specify a large
set of values with an imprecise specification, to query the database 
with a precise specification, and to get back only a single value.
This should be used by applications that need to know what the
user prefers for colors, fonts, and other resources.
.LP
For example, 
a user of your application may want to specify 
that all windows should have a blue background 
but that all mail reading windows should have a red background.
Presuming that all applications use the resource manager, 
a user can define this information using only two lines of specification.
Your personal resource database usually is stored in a file
and is loaded onto a server property when you log in.
This database is retrieved automatically by Xlib when a connection
is opened.
.LP
As an example of how the resource manager works,
consider a mail reading application called 
.PN xmh .
Assume that it is designed in such a manner that it uses a
complex window hierarchy all the way down to individual command buttons,
which may be actual small subwindows in some toolkits.
These are often called ``objects''.
In such toolkit systems,
user interface objects (called ``widgets''
in the X toolkit) can be composed of other objects.
Each user interface ``object'' can be assigned a name and a class.
Fully qualified names or classes can have arbitrary numbers of component names,
but a fully qualified name always has the same number of component names as a
fully qualified class.
This generally reflects the structure of the application as composed
of these objects, starting with the application itself.
.LP
For example, the xmh mail program has a name ``xmh'' and is one
of a class of ``Mail'' programs.
By convention, the first character of class components is capitalized,
while the first letter of name components is in lowercase.
Each name and class finally have an attribute
(for example ``foreground'' or ``font'').
If each window is properly assigned a name and class,
it becomes easy for the user to specify attributes of any portion 
of the application.
.LP
At the top level, 
the application might consist of a paned window (that is, a window divided
into several sections) named ``toc''.
One pane of the paned window is a button box window named ``buttons''
filled with command buttons. 
One of these command buttons is used to retrieve (``include'')
new mail and has the name ``include''.
This window has a fully qualified name ``xmh.toc.buttons.include'' 
and a fully qualified class ``Xmh.VPaned.Box.Command''.
Its fully qualified name is the name of its parent, ``xmh.toc.buttons'', 
followed by its name ``include''.
Its class is the class of its parent, ``Xmh.VPaned.Box'', 
followed by its particular class, ``Command''.  
The fully qualified name of a resource is
the attribute's name appended to the object's fully qualified
name, and the fully qualified class is its class appended to the object's
class.
.LP
This ``include'' button needs the following resources: 
.IP \(bu 5
Title string
.IP \(bu 5
Font
.IP \(bu 5
Foreground color
.IP \(bu 5
Background color
.IP \(bu 5
Foreground color for its active state
.IP \(bu 5
Background color for its active state
.LP
Each of the resources that this button needs are considered
to be attributes of the button and, as such, have a name and
a class.
For example, the foreground color for the button in
its active state might be named ``activeForeground'',
and its class would be ``Foreground.''
.LP
When an application looks up a resource (for example, a color),
it passes the complete name and complete class of the resource
to a lookup routine.
After lookup, 
the resource manager returns the resource value and the representation type.
.LP
The resource manager allows applications to store resources 
by an incomplete specification of name, class, and a
representation type, as well as to retrieve them given a
fully qualified name and class.
.NH 3
Resource Manager Matching Rules
.XS
\*(SN Resource Manager Matching Rules
.XE
.LP
The algorithm for determining which resource name or names
match a given query is the heart of the database.
Resources are stored with only partially specified names and classes, 
using pattern matching constructs.
An asterisk (``*'') is used to represent any number of intervening components 
(including none).
A dot or period (``.'') is used to separate immediately adjacent components.
All queries fully specify the name and class of the resource needed.
The lookup algorithm then searches the database for the name that most closely 
matches (is most specific) to this full name and class.
The rules (in order of precedence) for a match are:
.IP 1. 5
The attribute of the name and class must match.
For example, queries for
.IP
.Ds 
.TA 2.5i
.ta 2.5i
xterm.scrollbar.background	(name)
XTerm.Scrollbar.Background	(class)
.De
.IP
will not match the following database entry:
.IP
.Ds
.TA 2.5i
.ta 2.5i
xterm.scrollbar:on
.De
.IP 2. 5
Database entries with name or class prefixed by a dot (``.'') 
are more specific than those prefixed by an asterisk (``*'').
For example, 
the entry xterm.geometry is more specific than entry xterm*geometry.
.IP 3. 5
Names are more specific than classes.
For example,
the entry *scrollbar.background is more specific than 
entry *Scrollbar.Background.
.IP 4. 5.
A name or class is more specific than omission.
For example,
the entry Scrollbar*Background is more specific than entry *Background.
.IP 5. 5
Left components are  more specific than right components.
For example,
xterm*background is more specific than entry scrollbar*background.
.IP 6. 5
If neither a dot (``.'') nor an asterisk (``*'') is specified 
at the beginning, a dot (``.'') is implicit.
For example,
xterm.background is identical to .xterm.background.
.LP
As an example of these rules, 
assume the following user preference specification:
.LP
.Ds 
.TA 2.5i
.ta 2.5i
xmh*background:	red
*command.font:	8x13
*command.background:	blue
*Command.Foreground:	green
xmh.toc*Command.activeForeground:	black
.De
.LP
A query for the name
``xmh.toc.messagefunctions.include.activeForeground'' and class
``Xmh.VPaned.Box.Command.Foreground'' would match
``xmh.toc*Command.activeForeground'' and return ``black''.
However, it also matches ``*Command.Foreground''.
.LP
Using the precedence algorithm described above, 
the resource manager would return the value specified by
``xmh.toc*Command.activeForeground''.
.NH 3
Basic Resource Manager Definitions
.XS
\*(SN Basic Resource Manager Definitions
.XE
.LP
The definitions for the resource manager's use are contained in the
.Pn < X11/Xresource.h > 
header file.
Xlib also uses the resource manager internally to allow for
non-English language error messages.
.LP
Database values consist of a size, an address, and a representation type.
The size is specified in bytes.
The representation type is a way for you to store data tagged by some 
application-defined type (for example, ``font'' or ``color'').
It has nothing to do with the C data type or with its class. 
The
.PN XrmValue 
structure contains:
.LP
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	unsigned int size;
	caddr_t addr;
} XrmValue, *XrmValuePtr;
.De
.LP
A resource database is an opaque type used by the lookup routines.
.LP
.Ds 0
typedef struct _XrmHashBucketRec *XrmDatabase;
.De
.LP
To initialize the resource manager, use
.PN XrmInitialize .
.IN "XrmInitialize" "" "@DEF@"
.FD 0
.so ./Xsrc/XrmInit.f
.FN
Most uses of the resource manager involves defining names,
classes, and representation types as string constants.
However, always referring to strings in the resource manager can be slow,
because it is so heavily used in some toolkits.
To solve this problem, a shorthand for a string that is to be used 
in place of the string when the resource 
manager is heavily used in many of the resource manager functions.
Simple comparisons can be performed rather than string comparisons.
The shorthand name for a string is called a ``quark'' and is the
type 
.PN XrmQuark .
On some occasions,
you may want to allocate a quark that has no string equivalent.
.LP
A quark is to a string what an atom is to a property name in the server,
but its use is entirely local to your application.
.LP
.sp
To allocate a new quark, use
.PN XrmUniqueQuark .
.IN "XrmUniqueQuark" "" "@DEF@"
.FD 0
.so ./Xsrc/XrmUQuark.f
.FN
.LP
.so ./Xdescrip/XrmUQuark.d
.LP
.sp
To allocate some memory you will never give back, use
.RN Xpermalloc .
.IN "Xpermalloc" "" "@DEF@"
.FD 0
char *Xpermalloc\^(\^\fIsize\fP\^)
.br
     unsigned int \fIsize\fP\^;
.FN
.LP
The
.PN Xpermalloc
function is used by some toolkits for permanently allocated storage
and allows some performance and space savings over the completely general
memory allocator.
.LP
Names, classes and representation types are all typedef'd as
XrmQuarks.
.LP
.Ds 0
typedef int XrmQuark, *XrmQuarkList;
typedef XrmQuark XrmName;
typedef XrmQuark XrmClass;
typedef XrmQuark XrmRepresentation;
.De
.LP
Lists are represented as null terminated arrays of quarks.
The size of the array must be large enough for the number of components used.
.LP
.Ds 0
typedef XrmQuarkList XrmNameList;
typedef XrmQuarkList XrmClassList;
.De
.LP
.sp
To convert a string to a quark, use
.PN XrmStringToQuark .
.IN "XrmStringToQuark" "" "@DEF@"
.FD 0
.so ./Xsrc/XrmSTQuark.f
.FN
.so ./Xsrc/str_quark.a
.LP
.sp
To convert a quark to a string, use 
.PN XrmQuarkToString .
.IN "XrmQuarkToString" "" "@DEF@"
.FD 0
.so ./Xsrc/XrmQTStr.f
.FN
.so ./Xsrc/quark_str.a
.LP
These routines can be used to convert to and from quark representations.
The string pointed to by the return value must not be modified or freed.
.LP
.sp
To convert a string with one or more components to a quark list, use
.PN XrmStringToQuarkList .
.IN "XrmStringToQuarkList" "" "@DEF@"
.FD 0
.so ./Xsrc/XrmSTQList.f
.FN
.so ./Xsrc/str_quark.a
.so ./Xsrc/quark_ret.a
.LP
.so ./Xdescrip/XrmSTQList.d
.LP
A binding list is a list of type
.PN XrmBindingList
and indicates if components of name or class lists are bound tightly or loosely
(that is, if wildcarding of intermediate components is specified).
.LP
.Ds 0
typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList;
.De
.LP
.PN XrmBindTightly
indicates that a dot (``.'') separates the components, while
.PN XrmBindLoosely
indicates that an asterisk (``*'') separates the components.
.LP
.sp
To convert a string with one or more components to a binding list
and a quark list, use
.PN XrmStringToBindingQuarkList .
.IN "XrmStringToBindingQuarkList" "" "@DEF@"
.FD 0
.so ./Xsrc/XrmSTBQLst.f
.FN
.so ./Xsrc/str_quark.a
.so ./Xsrc/bind_ret.a
The caller must allocate sufficient space for the binding list before calling 
.PN XrmStringToBindingQuarkList .
.so ./Xsrc/quark_ret.a
The caller must allocate sufficient space for the quarks list before calling 
.PN XrmStringToBindingQuarkList .
.LP
Component names in the list are separated by a dot (``.'') or 
an asterisk (``*'') character.
If the string does not start with dot or asterisk, 
a dot (``.'') is assumed.
For example, ``*a.b*c'' becomes:
.LP
.Ds 0
.TA .75i 1.5i 2.25i
.ta .75i 1.5i 2.25i
quarks	a	b	c
bindings	loose	tight	loose
.De
.LP
Xlib provides resource management functions with which you
can manipulate resource databases.
The next sections discuss how to:
.IP \(bu 5
Store and get resources
.IP \(bu 5
Getting database levels
.IP \(bu 5
Merge two databases
.IP \(bu 5
Retrieve and store databases
.NH 4
Storing Into a Resource Database
.XS
\*(SN Storing Into a Resource Database
.XE
.LP
To store resources into the database, use
.PN XrmPutResource 
or
.PN XrmQPutResource .
Both functions take a partial resource specification, a
representation type, and a value.
This value is copied into the specified database.
.LP
.sp
The definition for
.PN XrmPutResource
is:
.IN "XrmPutResource" "" "@DEF@"
.FD 0
.so ./Xsrc/XrmPRes.f
.FN
.so ./Xsrc/database.a
.so ./Xsrc/specifier.a
.so ./Xsrc/res_type.a
.so ./Xsrc/res_value.a
.LP
.PN XrmPutResource
is a convenience function that calls
.PN XrmStringToBindingQuarkList 
followed by:
.LP
.Ds
XrmQPutResource(database, bindings, quarks, XrmStringToQuark(type), value)
.De
.LP
.sp
The definition for
.PN XrmQPutResource 
is:
.IN "XrmQPutResource" "" "@DEF@"
.FD 0
.so ./Xsrc/XrmQPRes.f
.FN
.so ./Xsrc/database.a
.so ./Xsrc/bindings.a
.so ./Xsrc/quarks.a
.so ./Xsrc/res_type.a
.so ./Xsrc/res_value.a
.LP
.sp
To add a resource that is specified as a string, use
.PN XrmPutStringResource .
.IN "XrmPutStringResource" "" "@DEF@"
.FD 0
.so ./Xsrc/XrmPSRes.f
.FN
.so ./Xsrc/database.a
.so ./Xsrc/resource1.a
.so ./Xsrc/res_value.a
The value is specified as a string.
.LP
.so ./Xdescrip/XrmPSRes.d
.PN XrmPutStringResource 
is a convenience routine that takes both the resource and value
as strings, converts them to quarks, and then calls 
.PN XrmQPutResource .
.LP
.sp
To add a string resource using quarks as a specification, use
.PN XrmQPutStringResource .
.IN "XrmQPutStringResource" "" "@DEF@"
.FD 0
.so ./Xsrc/XrmQPSRes.f
.FN
.so ./Xsrc/database.a
If the resource database is NULL, 
a new database will be created.
.so ./Xsrc/bindings.a
.so ./Xsrc/quarks.a
.so ./Xsrc/res_value.a
The value is specified as a string.
.LP
.PN XrmQPutStringResource
is a convenience routine that constructs an 
.PN XrmValue 
for the value string (by calling 
.PN strlen , 
which sets up the address and size) and
then calls 
.PN XrmQPutResource .
.LP
.sp
To add a single resource entry that is specified as a string that contains
both a name and a value, use
.PN XrmPutLineResource .
.IN "XrmPutLineResource" "" "@DEF@"
.FD 0
.so ./Xsrc/XrmPLRes.f
.FN
.so ./Xsrc/database.a
.so ./Xsrc/res_line.a
.LP
.so ./Xdescrip/XrmPLRes.d
Any whitespace before or after the name or colon in the line argument 
is ignored.
The value is terminated by a new-line or a NULL character.
The value may contain embedded new-line characters prefixed by the
``\\'' and ``n'' character pair, 
which are removed before the value is stored in the database.
For example, line might have the value ``xterm*background:green\\n''.
Null teminated strings without a new line are also permitted.
.NH 4
Looking up from a Resource Database
.XS
\*(SN Looking up from a Resource Database
.XE
.LP
To retrieve a resource from a resource database, use
.PN XrmGetResource
or
.PN XrmQGetResource .
.LP
.sp
The definition for 
.PN XrmGetResource
is:
.FD 0
.so ./Xsrc/XrmGRes.f
.FN
.so ./Xsrc/database1.a
.so ./Xsrc/res_name.a
.so ./Xsrc/res_class.a
.so ./Xsrc/rm_type_ret.a
.so ./Xsrc/rm_value_ret.a
.LP
.sp
The definition for
.PN XrmQGetResource
is:
.FD 0
.so ./Xsrc/XrmQGRes.f
.FN
.so ./Xsrc/database1.a
.so ./Xsrc/res_name2.a
.so ./Xsrc/res_class2.a
.so ./Xsrc/rm_type_ret1.a
.so ./Xsrc/rm_value_ret.a
.LP
.so ./Xdescrip/XrmQGRes.d
Both take a fully qualified name/class pair, a destination
resource representation, and the address of a value
(size/address pair).  
The value returned points into database memory;
therefore, you must not modify the data.
.LP
Currently, the database only frees or overwrites entries on
.PN XrmPutResource , 
.PN XrmQPutResource ,
or 
.PN XrmMergeDatabases .
A client that is not storing new values into and
that 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
.PN XrmGetResource 
and
.PN XrmQGetResource 
return 
.PN True .
Otherwise, they return 
.PN False .
.NH 4
Database Search Lists
.XS
\*(SN Database Search Lists
.XE
.LP
Most applications and toolkits do not make random probes
into a resource database to fetch resources.
The X toolkit access pattern for a resource database is quite stylized.
That is, a series of from one to twenty probes are made with only the 
last name/class differing in each probe.
The 
.PN XrmGetResource 
function is at worst a %2 sup n% algorithm,
where n is the length of the name/class list.
This can be improved upon by the application programmer by prefetching a list
of database levels that might match the first part of a name/class list.
.LP
.Ds 0
typedef XrmHashTable *XrmSearchList;
.De
.LP
.sp
To return a list of database levels, use
.PN XrmQGetSearchList .
.IN "XrmQGetSearchList" "" "@DEF@"
.FD 0
.so ./Xsrc/XrmQGSList.f
.FN
.so ./Xsrc/database1.a
.so ./Xsrc/res_names.a
.so ./Xsrc/res_classes.a
.so ./Xsrc/list_ret.a
The caller must allocate sufficient space for the list before calling 
.PN XrmQGetSearchList .
.so ./Xsrc/list_leng.a
.LP
.so ./Xdescrip/XrmQGSList.d
The returned list is in best-to-worst order and
uses the same algorithm as 
.PN XrmGetResource 
for determining precedence.
If list_return was large enough for the search list,
.PN XrmQGetSearchList
returns 
.PN True .
Otherwise, it returns
.PN False .
.LP
The size of the search list that must be allocated by the caller is
dependent upon the number of levels and wildcards in the resource specifiers 
that are stored in the database.
The worst case length is %3 sup n%,
where n is the number of name or class components in names or classes.
.LP
When using 
.PN 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 
.PN XrmQGetSearchList .
.LP
.sp
To search resource database levels for a given resource, use
.PN XrmQGetSearchResource .
.IN "XrmQGetSearchResource" "" "@DEF@"
.FD 0
.so ./Xsrc/XrmQGSRes.f
.FN
.so ./Xsrc/list_level.a
.so ./Xsrc/res_name1.a
.so ./Xsrc/res_class1.a
.so ./Xsrc/rm_typ_ret.a
.so ./Xsrc/rm_val_ret.a
.LP
.so ./Xdescrip/XrmQGSRes.d
The search stops with the first match.
.PN XrmQGetSearchResource
returns True if the resource was found.
.LP
A call to 
.PN XrmQGetSearchList 
with a name and class list containing all but the last component 
of a resource name followed by a call to 
.PN XrmQGetSearchResource 
with the last component name and class returns the same database entry as 
.PN XrmGetResource 
and 
.PN XrmQGetResource 
with the fully qualified name and class.
.NH 4
Merging Resource Databases
.XS
\*(SN Merging Resource Databases
.XE
.LP
To merge the contents of one database into another, use
.PN XrmMergeDatabases .
.IN "XrmMergeDatabases" "" "@DEF@"
.FD 0
.so ./Xsrc/XrmMDBase.f
.FN
.so ./Xsrc/database2.a
.so ./Xsrc/rm_target.a
.LP 
.so ./Xdescrip/XrmMDBase.d
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 original database is destroyed.
.NH 4
Retrieving and Storing Databases
.LP
To retrieve a database from nonvolatile storage, use
.PN XrmGetFileDatabase .
.IN "XrmGetFileDatabase" "" "@DEF@"
.FD 0
.so ./Xsrc/XrmGFDBase.f
.FN
.so ./Xsrc/rm_file.a
.LP
.so ./Xdescrip/XrmGFDBase.d
The specified file must contain lines in the format accepted by
.PN XrmPutLineResource .
If it cannot open the specified file,
.PN XrmGetFileDatabase 
returns NULL.
.LP
.sp
To store a copy of the application's current database in nonvolatile storage,
use
.PN XrmPutFileDatabase .
.IN "XrmPutFileDatabase" "" "@DEF@"
.FD 0
.so ./Xsrc/XrmPFDBase.f
.FN
.so ./Xsrc/database1.a
.so ./Xsrc/rm_file1.a
.LP
.so ./Xdescrip/XrmPFDBase.d
The file is an ASCII text file that contains lines in the format that is
accepted by
.PN XrmPutLineResource .
.LP
.sp
To create a database from a string, use
.PN XrmGetStringDatabase .
.IN "XrmGetStringDatabase" "" "@DEF@"
.FD 0
.so ./Xsrc/XrmGSDbase.f
.FN
.so ./Xsrc/rm_data.a
.LP
.so ./Xdescrip/XrmGSDbase.d
.PN XrmGetStringDatabase 
is similar to
.PN XrmGetFileDatabase , 
except that it reads the information out of a string instead of a file.
Each line is separated by a new line character in the format
accepted by 
.PN XrmPutLineResource .
.NH 3
Parsing Command Line Options
.XS
\*(SN Parsing Command Line Options 
.XE
.LP
The
.PN XrmParseCommand
function can be used to parse the command line arguments to a program
and modify a resource database with selected entries from the command line.
.LP
.Ds 0
.TA .5i 2.5i
.ta .5i 2.5i
typedef enum {
	XrmoptionNoArg,	/* Value is specified in OptionDescRec.value */
	XrmoptionIsArg,	/* Value is the option string itself */
	XrmoptionStickyArg,	/* Value is characters immediately following option */
	XrmoptionSepArg,	/* Value is next argument in argv */
	XrmoptionResArg,	/* Resource and value in next argument in argv */
	XrmoptionSkipArg,	/* Ignore this option and the next argument in argv */
	XrmoptionSkipLine	/* Ignore this option and the rest of argv */
} XrmOptionKind;

typedef struct {
	char *option;	/* Option specification string in argv		    */
	char *resourceName;	/* Binding and resource name (sans application name)    */
	XrmOptionKind argKind;	/* Which style of option it is	    */
	caddr_t value;	/* Value to provide if XrmoptionNoArg    */
} XrmOptionDescRec, *XrmOptionDescList;
.De
.LP
.sp
To load a resource data base from a C command line, use
.PN XrmParseCommand .
.IN "XrmParseCommand" "" "@DEF@"
.FD 0
.so ./Xsrc/XrmParse.f
.FN
.so ./Xsrc/database.a
.so ./Xsrc/dbtable.a
.so ./Xsrc/dbtcount.a
.so ./Xsrc/parname.a
.so ./Xsrc/parseargc.a
.so ./Xsrc/parseargv.a
.LP
.so ./Xdescrip/XrmParse.d
.LP
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 data base.
The table entries contain information on the option string,
the the option name,
which style of option and a value to provide if the option kind is 
.PN XrmoptionNoArg .
The argc argument specifies the number of 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 data base entry.
The name argument is prepended to the resourceName in the option table
before storing the specification.
No separating (binding) character is inserted.
The table must contain either a dot (``.'') or an asterisk (``*'')
as the first character in the resourceName entry.
To specify a more completely qualified resource name,
the resourceName entry can contain multiple components.
.LP
For example, the following is part of the standard option table 
from the X Toolkit
.PN XtInitialize 
routine:
.LP
.Ds 0
.TA 1.25i 3.25i 4.75i
.ta 1.25i 3.25i 4.75i
static XrmOptionDescRec opTable[] = {
{"\-background",	"*background",	XrmoptionSepArg,	(caddr_t) NULL},
{"\-bd",	"*borderColor",	XrmoptionSepArg,	(caddr_t) NULL},
{"\-bg",	"*background",	XrmoptionSepArg,	(caddr_t) NULL},
{"\-borderwidth",	"*TopLevelShell.borderWidth",	XrmoptionSepArg,	(caddr_t) NULL},
{"\-bordercolor",	"*borderColor",	XrmoptionSepArg,	(caddr_t) NULL},
{"\-bw",	"*TopLevelShell.borderWidth",	XrmoptionSepArg,	(caddr_t) NULL},
{"\-display",	".display",	XrmoptionSepArg,	(caddr_t) NULL},
{"\-fg",	"*foreground",	XrmoptionSepArg,	(caddr_t) NULL},
{"\-fn",	"*font",	XrmoptionSepArg,	(caddr_t) NULL},
{"\-font",	"*font",	XrmoptionSepArg,	(caddr_t) NULL},
{"\-foreground",	"*foreground",	XrmoptionSepArg,	(caddr_t) NULL},
{"\-geometry",	".TopLevelShell.geometry",	XrmoptionSepArg,	(caddr_t) NULL},
{"\-iconic",	".TopLevelShell.iconic",	XrmoptionNoArg,	(caddr_t) "on"},
{"\-name",	".name",	XrmoptionSepArg,	(caddr_t) NULL},
{"\-reverse",	"*reverseVideo",	XrmoptionNoArg,	(caddr_t) "on"},
{"\-rv",	"*reverseVideo",	XrmoptionNoArg,	(caddr_t) "on"},
{"\-synchronous",	".synchronous",	XrmoptionNoArg,	(caddr_t) "on"},
{"\-title",	".TopLevelShell.title",	XrmoptionSepArg,	(caddr_t) NULL},
{"\-xrm",	NULL,	XrmoptionResArg,	(caddr_t) NULL},
};
.De
.LP
In this table, if the \-background (or \-bg) option is used to set
background colors, the stored resource specifier will match all
resources of attribute background.  
If the \-borderwidth option is used, 
the stored resource specifier applies only to border width
attributes of class TopLevelShell (that is, outer-most windows, including
pop-up windows).  
If the \-title option is used to set a window name,
only the top-most application windows receive the resource.
.LP
When parsing the command line,
any unique unambiguous abbreviation for an option name in the table is 
considered a match for the option.
.NH 2
Using the Context Manager
.XS
\*(SN Using the Context Manager 
.XE
.LP
The context manager provides a way of associating data with a window in your
program.  
Note that this is local to your program;
the data is not stored in the server on a property list.
Any amount of data in any number of pieces can be associated with a window,
and each piece of data has a type associated with it.  
The context manager requires knowledge of the window ID
and type to store or retrieve data.
.LP
Essentially, the context manager can be viewed as a two-dimensional, 
sparse array:  one dimension is subscripted by the window ID 
and the other by a context type field.
Each entry in the array contains a pointer to the data.
Xlib provides context management functions with which you can
save data values, get data values, delete entries, and create a unique
context type.
The symbols used are in
.Pn < X11/Xutil.h >
header file.
.LP
.sp
To save a data value that corresponds to a window and context type, use
.PN XSaveContext .
.IN "XSaveContext" "" "@DEF@"
.FD 0
.so ./Xsrc/XSContext.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/w_context.a
.so ./Xsrc/context.a
.so ./Xsrc/data_context.a
.LP
If an entry with the specified window and type already exists, 
.PN XSaveContext
overrides it with the specified context.  
However, this override has costs in time and space.  
If you know the entry already exists,
it is better to call 
.PN XDeleteContext
first.
The
.PN XSaveContext
function returns nonzero error code if an error has occurred 
and zero otherwise.
Possible errors are 
.PN XCNOMEM
(out of memory).
.LP
.sp
To get the data associated with a window and type, use
.PN XFindContext .
.IN "XFindContext" "" "@DEF@"
.FD 0
.so ./Xsrc/XFContext.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/w_context.a
.so ./Xsrc/context.a
.so ./Xsrc/data_ret.a
.LP
Because it is a return value,  
the data is a pointer.
The
.PN XFindContext
function returns nonzero error code if an error has occurred 
and zero otherwise. 
Possible errors are 
.PN XCNOENT
(context-not-found).
.LP
.sp
To delete an entry for a given window and type, use
.PN XDeleteContext .
.IN "XDeleteContext" "" "@DEF@"
.FD 0
.so ./Xsrc/XDContext.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/w_context.a
.so ./Xsrc/context.a
.LP
The 
.PN XDeleteContext
function deletes the entry for the given window and type from the data structure.
This returns the same error codes that 
.PN XFindContext
returns if called with the same arguments.
.LP
.sp
To create a unique context type that may be used in subsequent calls to
.PN XSaveContext 
and
.PN XFindContext ,
use
.PN XUniqueContext .
The definition for this function is:
.IN "XUniqueContext" "" "@DEF@"
.FD 0
.so ./Xsrc/XUContext.f
.FN
.bp
