2365 lines
56 KiB
Plaintext
2365 lines
56 KiB
Plaintext
.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
|
|
.\"
|
|
.\" Permission is hereby granted, free of charge, to any person obtaining
|
|
.\" a copy of this software and associated documentation files (the
|
|
.\" "Software"), to deal in the Software without restriction, including
|
|
.\" without limitation the rights to use, copy, modify, merge, publish,
|
|
.\" distribute, sublicense, and/or sell copies of the Software, and to
|
|
.\" permit persons to whom the Software is furnished to do so, subject to
|
|
.\" the following conditions:
|
|
.\"
|
|
.\" The above copyright notice and this permission notice shall be included
|
|
.\" in all copies or substantial portions of the Software.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
|
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
|
|
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
|
|
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
|
.\" OTHER DEALINGS IN THE SOFTWARE.
|
|
.\"
|
|
.\" Except as contained in this notice, the name of the X Consortium shall
|
|
.\" not be used in advertising or otherwise to promote the sale, use or
|
|
.\" other dealings in this Software without prior written authorization
|
|
.\" from the X Consortium.
|
|
.\"
|
|
.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
|
|
.\" Digital Equipment Corporation
|
|
.\"
|
|
.\" Portions Copyright \(co 1990, 1991 by
|
|
.\" Tektronix, Inc.
|
|
.\"
|
|
.\" Permission to use, copy, modify and distribute this documentation for
|
|
.\" any purpose and without fee is hereby granted, provided that the above
|
|
.\" copyright notice appears in all copies and that both that copyright notice
|
|
.\" and this permission notice appear in all copies, and that the names of
|
|
.\" Digital and Tektronix not be used in in advertising or publicity pertaining
|
|
.\" to this documentation without specific, written prior permission.
|
|
.\" Digital and Tektronix makes no representations about the suitability
|
|
.\" of this documentation for any purpose.
|
|
.\" It is provided ``as is'' without express or implied warranty.
|
|
.\"
|
|
\&
|
|
.sp 1
|
|
.ce 3
|
|
\s+1\fBChapter 16\fP\s-1
|
|
|
|
\s+1\fBApplication Utility Functions\fP\s-1
|
|
.sp 2
|
|
.nr H1 16
|
|
.nr H2 0
|
|
.nr H3 0
|
|
.nr H4 0
|
|
.nr H5 0
|
|
.na
|
|
.LP
|
|
.XS
|
|
Chapter 16: Application Utility Functions
|
|
.XE
|
|
Once you have initialized the X system,
|
|
you can use the Xlib utility functions to:
|
|
.IP \(bu 5
|
|
Use keyboard utility functions
|
|
.IP \(bu 5
|
|
Use Latin-1 keyboard event functions
|
|
.IP \(bu 5
|
|
Allocate permanent storage
|
|
.IP \(bu 5
|
|
Parse the window geometry
|
|
.IP \(bu 5
|
|
Manipulate regions
|
|
.IP \(bu 5
|
|
Use cut buffers
|
|
.IP \(bu 5
|
|
Determine the appropriate visual type
|
|
.IP \(bu 5
|
|
Manipulate images
|
|
.IP \(bu 5
|
|
Manipulate bitmaps
|
|
.IP \(bu 5
|
|
Use the context manager
|
|
.LP
|
|
As a group,
|
|
the functions discussed in this chapter provide the functionality that
|
|
is frequently needed and that spans toolkits.
|
|
Many of these functions do not generate actual protocol requests to the server.
|
|
.NH 2
|
|
Using Keyboard Utility Functions
|
|
.XS
|
|
\*(SN Using Keyboard Utility Functions
|
|
.XE
|
|
.LP
|
|
This section discusses mapping between KeyCodes and KeySyms,
|
|
classifying KeySyms, and mapping between KeySyms and string names.
|
|
The first three functions in this section operate on a cached copy of the
|
|
server keyboard mapping.
|
|
The first four KeySyms for each KeyCode
|
|
are modified according to the rules given in section 12.7.
|
|
To obtain the untransformed KeySyms defined for a key,
|
|
use the functions described in section 12.7.
|
|
.LP
|
|
.sp
|
|
To obtain a KeySym for the KeyCode of an event, use
|
|
.PN XLookupKeysym .
|
|
.IN "XLookupKeysym" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
KeySym XLookupKeysym(\^\fIkey_event\fP, \fIindex\fP\^)
|
|
.br
|
|
XKeyEvent *\fIkey_event\fP\^;
|
|
.br
|
|
int \fIindex\fP\^;
|
|
.FN
|
|
.IP \fIkey_event\fP 1i
|
|
Specifies the
|
|
.PN KeyPress
|
|
or
|
|
.PN KeyRelease
|
|
event.
|
|
.IP \fIindex\fP 1i
|
|
Specifies the index into the KeySyms list for the event's KeyCode.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN 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
|
|
.PN XKeyPressedEvent
|
|
or
|
|
.PN XKeyReleasedEvent
|
|
structure.
|
|
If no KeySym is defined for the KeyCode of the event,
|
|
.PN XLookupKeysym
|
|
returns
|
|
.PN NoSymbol .
|
|
.LP
|
|
.sp
|
|
To obtain a KeySym for a specific KeyCode, use
|
|
.PN XKeycodeToKeysym .
|
|
.IN "XKeycodeToKeysym" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
KeySym XKeycodeToKeysym\^(\^\fIdisplay\fP, \fIkeycode\fP, \fIindex\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
KeyCode \fIkeycode\fP\^;
|
|
.br
|
|
int \fIindex\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIkeycode\fP 1i
|
|
Specifies the KeyCode.
|
|
.IP \fIindex\fP 1i
|
|
Specifies the element of KeyCode vector.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN 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,
|
|
.PN XKeycodeToKeysym
|
|
returns
|
|
.PN NoSymbol .
|
|
.LP
|
|
.sp
|
|
To obtain a KeyCode for a key having a specific KeySym, use
|
|
.PN XKeysymToKeycode .
|
|
.IN "XKeysymToKeycode" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
KeyCode XKeysymToKeycode\^(\^\fIdisplay\fP, \fIkeysym\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
KeySym \fIkeysym\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIkeysym\fP 1i
|
|
Specifies the KeySym that is to be searched for.
|
|
.LP
|
|
.eM
|
|
If the specified KeySym is not defined for any KeyCode,
|
|
.PN XKeysymToKeycode
|
|
returns zero.
|
|
.LP
|
|
.sp
|
|
The mapping between KeyCodes and KeySyms is cached internal to Xlib.
|
|
When this information is changed at the server, an Xlib function must
|
|
be called to refresh the cache.
|
|
To refresh the stored modifier and keymap information, use
|
|
.PN XRefreshKeyboardMapping .
|
|
.IN "XRefreshKeyboardMapping" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XRefreshKeyboardMapping(\^\fIevent_map\fP\^)
|
|
.br
|
|
XMappingEvent *\fIevent_map\fP\^;
|
|
.FN
|
|
.IP \fIevent_map\fP 1i
|
|
Specifies the mapping event that is to be used.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XRefreshKeyboardMapping
|
|
function refreshes the stored modifier and keymap information.
|
|
You usually call this function when a
|
|
.PN MappingNotify
|
|
event with a request member of
|
|
.PN MappingKeyboard
|
|
or
|
|
.PN MappingModifier
|
|
occurs.
|
|
The result is to update Xlib's knowledge of the keyboard.
|
|
.LP
|
|
.sp
|
|
To obtain the uppercase and lowercase forms of a KeySym, use
|
|
.PN XConvertCase .
|
|
.IN "XConvertCase" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XConvertCase(\^\fIkeysym\fP, \fIlower_return\fP, \fIupper_return\fP\^)
|
|
.br
|
|
KeySym \fIkeysym\fP\^;
|
|
.br
|
|
KeySym *\fIlower_return\fP\^;
|
|
.br
|
|
KeySym *\fIupper_return\fP\^;
|
|
.FN
|
|
.ds Fn converted
|
|
.IP \fIkeysym\fP 1i
|
|
Specifies the KeySym that is to be \*(Fn.
|
|
.IP \fIlower_return\fP 1i
|
|
Returns the lowercase form of keysym, or keysym.
|
|
.IP \fIupper_return\fP 1i
|
|
Returns the uppercase form of keysym, or keysym.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XConvertCase
|
|
function returns the uppercase and lowercase forms of the specified Keysym,
|
|
if the KeySym is subject to case conversion;
|
|
otherwise, the specified KeySym is returned to both lower_return and
|
|
upper_return.
|
|
Support for conversion of other than Latin and Cyrillic KeySyms is
|
|
implementation-dependent.
|
|
.LP
|
|
.sp
|
|
KeySyms have string names as well as numeric codes.
|
|
To convert the name of the KeySym to the KeySym code, use
|
|
.PN XStringToKeysym .
|
|
.IN "XStringToKeysym" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
KeySym XStringToKeysym\^(\^\fIstring\fP\^)
|
|
.br
|
|
char *\fIstring\fP\^;
|
|
.FN
|
|
.IP \fIstring\fP 1i
|
|
Specifies the name of the KeySym that is to be converted.
|
|
.LP
|
|
.eM
|
|
Standard KeySym names are obtained from
|
|
.hN X11/keysymdef.h
|
|
by removing the XK_ prefix from each name.
|
|
KeySyms that are not part of the Xlib standard also may be obtained
|
|
with this function.
|
|
The set of KeySyms that are available in this manner
|
|
and the mechanisms by which Xlib obtains them is implementation-dependent.
|
|
.LP
|
|
If the KeySym name is not in the Host Portable Character Encoding,
|
|
the result is implementation-dependent.
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
char *XKeysymToString\^(\^\fIkeysym\fP\^)
|
|
.br
|
|
KeySym \fIkeysym\fP\^;
|
|
.FN
|
|
.ds Fn converted
|
|
.IP \fIkeysym\fP 1i
|
|
Specifies the KeySym that is to be \*(Fn.
|
|
.LP
|
|
.eM
|
|
The returned string is in a static area and must not be modified.
|
|
The returned string is in the Host Portable Character Encoding.
|
|
If the specified KeySym is not defined,
|
|
.PN XKeysymToString
|
|
returns a NULL.
|
|
.NH 3
|
|
KeySym Classification Macros
|
|
.XS
|
|
\*(SN KeySym Classification Macros
|
|
.XE
|
|
.LP
|
|
You may want to test if a KeySym is, for example,
|
|
on the keypad or on one of the function keys.
|
|
You can use KeySym macros to perform the following tests.
|
|
.LP
|
|
.sp
|
|
.sM
|
|
.FD 0
|
|
IsCursorKey\^(\^\fIkeysym\fP\^)
|
|
.FN
|
|
.ds Fn tested
|
|
.IP \fIkeysym\fP 1i
|
|
Specifies the KeySym that is to be \*(Fn.
|
|
.LP
|
|
.eM
|
|
.IN "IsCursorKey" "" "@DEF@"
|
|
Returns
|
|
.PN True
|
|
if the specified KeySym is a cursor key.
|
|
.LP
|
|
.sp
|
|
.sM
|
|
.FD 0
|
|
IsFunctionKey\^(\^\fIkeysym\fP\^)
|
|
.FN
|
|
.ds Fn tested
|
|
.IP \fIkeysym\fP 1i
|
|
Specifies the KeySym that is to be \*(Fn.
|
|
.LP
|
|
.eM
|
|
.IN "IsFunctionKey" "" "@DEF@"
|
|
Returns
|
|
.PN True
|
|
if the specified KeySym is a function key.
|
|
.LP
|
|
.sp
|
|
.sM
|
|
.FD 0
|
|
IsKeypadKey\^(\^\fIkeysym\fP\^)
|
|
.FN
|
|
.ds Fn tested
|
|
.IP \fIkeysym\fP 1i
|
|
Specifies the KeySym that is to be \*(Fn.
|
|
.LP
|
|
.eM
|
|
.IN "IsKeypadKey" "" "@DEF@"
|
|
Returns
|
|
.PN True
|
|
if the specified KeySym is a standard keypad key.
|
|
.LP
|
|
.sp
|
|
.sM
|
|
.FD 0
|
|
IsPrivateKeypadKey\^(\^\fIkeysym\fP\^)
|
|
.FN
|
|
.ds Fn tested
|
|
.IP \fIkeysym\fP 1i
|
|
Specifies the KeySym that is to be \*(Fn.
|
|
.LP
|
|
.eM
|
|
.IN "IsPrivateKeypadKey" "" "@DEF@"
|
|
Returns
|
|
.PN True
|
|
if the specified KeySym is a vendor-private keypad key.
|
|
.LP
|
|
.sp
|
|
.sM
|
|
.FD 0
|
|
IsMiscFunctionKey\^(\^\fIkeysym\fP\^)
|
|
.FN
|
|
.ds Fn tested
|
|
.IP \fIkeysym\fP 1i
|
|
Specifies the KeySym that is to be \*(Fn.
|
|
.LP
|
|
.eM
|
|
.IN "IsMiscFunctionKey" "" "@DEF@"
|
|
Returns
|
|
.PN True
|
|
if the specified KeySym is a miscellaneous function key.
|
|
.LP
|
|
.sp
|
|
.sM
|
|
.FD 0
|
|
IsModifierKey\^(\^\fIkeysym\fP\^)
|
|
.FN
|
|
.ds Fn tested
|
|
.IP \fIkeysym\fP 1i
|
|
Specifies the KeySym that is to be \*(Fn.
|
|
.LP
|
|
.eM
|
|
.IN "IsModifierKey" "" "@DEF@"
|
|
Returns
|
|
.PN True
|
|
if the specified KeySym is a modifier key.
|
|
.LP
|
|
.sp
|
|
.sM
|
|
.FD 0
|
|
IsPFKey\^(\^\fIkeysym\fP\^)
|
|
.FN
|
|
.ds Fn tested
|
|
.IP \fIkeysym\fP 1i
|
|
Specifies the KeySym that is to be \*(Fn.
|
|
.LP
|
|
.eM
|
|
.IN "IsPFKey" "" "@DEF@"
|
|
Returns
|
|
.PN True
|
|
if the specified KeySym is a PF key.
|
|
.NH 2
|
|
Using Latin-1 Keyboard Event Functions
|
|
.XS
|
|
\*(SN Using Latin-1 Keyboard Event Functions
|
|
.XE
|
|
.LP
|
|
Chapter 13 describes internationalized text input facilities,
|
|
but sometimes it is expedient to write an application that
|
|
only deals with Latin-1 characters and ASCII controls,
|
|
so Xlib provides a simple function for that purpose.
|
|
.PN XLookupString
|
|
handles the standard modifier semantics described in section 12.7.
|
|
This function does not use any of the input method facilities
|
|
described in chapter 13 and does not depend on the current locale.
|
|
.LP
|
|
.sp
|
|
To map a key event to an ISO Latin-1 string, use
|
|
.PN XLookupString .
|
|
.IN "XLookupString" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
int XLookupString(\^\fIevent_struct\fP, \fIbuffer_return\fP,\
|
|
\fIbytes_buffer\fP, \fIkeysym_return\fP, \fIstatus_in_out\fP\^)
|
|
.br
|
|
XKeyEvent *\fIevent_struct\fP\^;
|
|
.br
|
|
char *\fIbuffer_return\fP\^;
|
|
.br
|
|
int \fIbytes_buffer\fP\^;
|
|
.br
|
|
KeySym *\fIkeysym_return\fP\^;
|
|
.br
|
|
XComposeStatus *\fIstatus_in_out\fP\^;
|
|
.FN
|
|
.IP \fIevent_struct\fP 1i
|
|
Specifies the key event structure to be used.
|
|
You can pass
|
|
.PN XKeyPressedEvent
|
|
or
|
|
.PN XKeyReleasedEvent .
|
|
.IP \fIbuffer_return\fP 1i
|
|
Returns the translated characters.
|
|
.IP \fIbytes_buffer\fP 1i
|
|
Specifies the length of the buffer.
|
|
No more than bytes_buffer of translation are returned.
|
|
.IP \fIkeysym_return\fP 1i
|
|
Returns the KeySym computed from the event if this argument is not NULL.
|
|
.IP \fIstatus_in_out\fP 1i
|
|
Specifies or returns the
|
|
.PN XComposeStatus
|
|
structure or NULL.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XLookupString
|
|
function translates a key event to a KeySym and a string.
|
|
The KeySym is obtained by using the standard interpretation of the
|
|
.PN Shift ,
|
|
.PN Lock ,
|
|
group, and numlock modifiers as defined in the X Protocol specification.
|
|
If the KeySym has been rebound (see
|
|
.PN XRebindKeysym ),
|
|
the bound string will be stored in the buffer.
|
|
Otherwise, the KeySym is mapped, if possible, to an ISO Latin-1 character
|
|
or (if the Control modifier is on) to an ASCII control character,
|
|
and that character is stored in the buffer.
|
|
.PN XLookupString
|
|
returns the number of characters that are stored in the buffer.
|
|
.LP
|
|
If present (non-NULL),
|
|
the
|
|
.PN XComposeStatus
|
|
structure records the state,
|
|
which is private to Xlib,
|
|
that needs preservation across calls to
|
|
.PN XLookupString
|
|
to implement compose processing.
|
|
The creation of
|
|
.PN XComposeStatus
|
|
structures is implementation-dependent;
|
|
a portable program must pass NULL for this argument.
|
|
.LP
|
|
.PN XLookupString
|
|
depends on the cached keyboard information mentioned in the
|
|
previous section, so it is necessary to use
|
|
.PN XRefreshKeyboardMapping
|
|
to keep this information up-to-date.
|
|
.LP
|
|
.sp
|
|
To rebind the meaning of a KeySym for
|
|
.PN XLookupString ,
|
|
use
|
|
.PN XRebindKeysym .
|
|
.IN "XRebindKeysym" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XRebindKeysym(\^\fIdisplay\fP, \fIkeysym\fP, \fIlist\fP, \fImod_count\fP, \fIstring\fP, \fInum_bytes\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
KeySym \fIkeysym\fP\^;
|
|
.br
|
|
KeySym \fIlist\fP\^[\^]\^;
|
|
.br
|
|
int \fImod_count\fP\^;
|
|
.br
|
|
unsigned char *\fIstring\fP\^;
|
|
.br
|
|
int \fInum_bytes\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.ds Fn rebound
|
|
.IP \fIkeysym\fP 1i
|
|
Specifies the KeySym that is to be \*(Fn.
|
|
.IP \fIlist\fP 1i
|
|
Specifies the KeySyms to be used as modifiers.
|
|
.IP \fImod_count\fP 1i
|
|
Specifies the number of modifiers in the modifier list.
|
|
.IP \fIstring\fP 1i
|
|
Specifies the string that is copied and will be returned by
|
|
.PN XLookupString .
|
|
.IP \fInum_bytes\fP 1i
|
|
Specifies the number of bytes in the string argument.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN 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.
|
|
.PN XLookupString
|
|
returns this string when the appropriate set of
|
|
modifier keys are pressed and when the KeySym would have been used for
|
|
the translation.
|
|
No text conversions are performed;
|
|
the client is responsible for supplying appropriately encoded strings.
|
|
Note that you can rebind a KeySym that may not exist.
|
|
.NH 2
|
|
Allocating Permanent Storage
|
|
.XS
|
|
\*(SN Allocating Permanent Storage
|
|
.XE
|
|
.LP
|
|
To allocate some memory you will never give back, use
|
|
.PN Xpermalloc .
|
|
.IN "Xpermalloc" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
char *Xpermalloc\^(\^\fIsize\fP\^)
|
|
.br
|
|
unsigned int \fIsize\fP\^;
|
|
.FN
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN Xpermalloc
|
|
function allocates storage that can never be freed for the life of the
|
|
program. The memory is allocated with alignment for the C type double.
|
|
This function may provide some performance and space savings over
|
|
the standard operating system memory allocator.
|
|
.NH 2
|
|
Parsing the Window Geometry
|
|
.XS
|
|
\*(SN Parsing the Window Geometry
|
|
.XE
|
|
.LP
|
|
To parse standard window geometry strings, use
|
|
.PN XParseGeometry .
|
|
.IN "Window" "determining location"
|
|
.IN "XParseGeometry" "" "@DEF@"
|
|
.LP
|
|
.sM
|
|
.FD 0
|
|
int XParseGeometry\^(\^\fIparsestring\fP\^, \fIx_return\fP\^, \fIy_return\fP\^, \fIwidth_return\fP\^, \fIheight_return\fP\^)
|
|
.br
|
|
char *\fIparsestring\fP\^;
|
|
.br
|
|
int *\fIx_return\fP\^, *\fIy_return\fP\^;
|
|
.br
|
|
unsigned int *\fIwidth_return\fP\^, *\fIheight_return\fP\^;
|
|
.FN
|
|
.IP \fIparsestring\fP 1i
|
|
Specifies the string you want to parse.
|
|
.IP \fIx_return\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIy_return\fP 1i
|
|
Return the x and y offsets.
|
|
.IP \fIwidth_return\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIheight_return\fP 1i
|
|
Return the width and height determined.
|
|
.LP
|
|
.eM
|
|
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:
|
|
.LP
|
|
.\" Start marker code here
|
|
.Ds
|
|
[=][<\fIwidth\fP>{xX}<\fIheight\fP>][{+-}<\fIxoffset\fP>{+-}<\fIyoffset\fP>]
|
|
.De
|
|
.\" End marker code here
|
|
.LP
|
|
The fields 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.)
|
|
If the string is not in the Host Portable Character Encoding,
|
|
the result is implementation-dependent.
|
|
.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 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
|
|
.PN XValue ,
|
|
.PN YValue ,
|
|
.PN WidthValue ,
|
|
.PN HeightValue ,
|
|
.PN XNegative ,
|
|
or
|
|
.PN YNegative
|
|
and are defined in
|
|
.hN X11/Xutil.h .
|
|
They will be set whenever one of the values is defined
|
|
or one of the signs is set.
|
|
.LP
|
|
If the function returns either the
|
|
.PN XValue
|
|
or
|
|
.PN YValue
|
|
flag,
|
|
you should place the window at the requested position.
|
|
.sp
|
|
.LP
|
|
To construct a window's geometry information, use
|
|
.PN XWMGeometry .
|
|
.IN "XWMGeometry" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
int XWMGeometry\^(\^\fIdisplay\fP, \fIscreen\fP, \fIuser_geom\fP, \
|
|
\fIdef_geom\fP, \fIbwidth\fP, \fIhints\fP, \fIx_return\fP, \fIy_return\fP,
|
|
.br
|
|
\fIwidth_return\fP, \fIheight_return\fP, \fIgravity_return\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
int \fIscreen\fP\^;
|
|
.br
|
|
char *\fIuser_geom\fP\^;
|
|
.br
|
|
char *\fIdef_geom\fP\^;
|
|
.br
|
|
unsigned int \fIbwidth\fP\^;
|
|
.br
|
|
XSizeHints *\fIhints\fP\^;
|
|
.br
|
|
int *\fIx_return\fP, *\fIy_return\fP\^;
|
|
.br
|
|
int *\fIwidth_return\fP\^;
|
|
.br
|
|
int *\fIheight_return\fP\^;
|
|
.br
|
|
int *\fIgravity_return\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIscreen\fP 1i
|
|
Specifies the screen.
|
|
.IP \fIuser_geom\fP 1i
|
|
Specifies the user-specified geometry or NULL.
|
|
.IP \fIdef_geom\fP 1i
|
|
Specifies the application's default geometry or NULL.
|
|
.IP \fIbwidth\fP 1i
|
|
Specifies the border width.
|
|
.IP \fIhints\fP 1i
|
|
Specifies the size hints for the window in its normal state.
|
|
.IP \fIx_return\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIy_return\fP 1i
|
|
Return the x and y offsets.
|
|
.IP \fIwidth_return\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIheight_return\fP 1i
|
|
Return the width and height determined.
|
|
.IP \fIgravity_return\fP 1i
|
|
Returns the window gravity.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XWMGeometry
|
|
function combines any geometry information (given in the format used by
|
|
.PN XParseGeometry )
|
|
specified by the user and by the calling program with size hints
|
|
(usually the ones to be stored in WM_NORMAL_HINTS) and returns the position,
|
|
size, and gravity
|
|
.Pn ( NorthWestGravity ,
|
|
.PN NorthEastGravity ,
|
|
.PN SouthEastGravity ,
|
|
or
|
|
.PN SouthWestGravity )
|
|
that describe the window.
|
|
If the base size is not set in the
|
|
.PN XSizeHints
|
|
structure,
|
|
the minimum size is used if set.
|
|
Otherwise, a base size of zero is assumed.
|
|
If no minimum size is set in the hints structure,
|
|
the base size is used.
|
|
A mask (in the form returned by
|
|
.PN XParseGeometry )
|
|
that describes which values came from the user specification
|
|
and whether or not the position coordinates are relative
|
|
to the right and bottom edges is returned.
|
|
Note that these coordinates will have already been accounted for
|
|
in the x_return and y_return values.
|
|
.LP
|
|
Note that invalid geometry specifications can cause a width or height
|
|
of zero to be returned.
|
|
The caller may pass the address of the hints win_gravity field
|
|
as gravity_return to update the hints directly.
|
|
.NH 2
|
|
Manipulating Regions
|
|
.XS
|
|
\*(SN Manipulating Regions
|
|
.XE
|
|
.LP
|
|
Regions are arbitrary sets of pixel locations.
|
|
Xlib provides functions for manipulating regions.
|
|
The opaque type
|
|
.PN Region
|
|
is defined in
|
|
.hN X11/Xutil.h .
|
|
Xlib provides functions that you can use to 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
|
|
.NH 3
|
|
Creating, Copying, or Destroying Regions
|
|
.XS
|
|
\*(SN Creating, Copying, or Destroying Regions
|
|
.XE
|
|
.LP
|
|
To create a new empty region, use
|
|
.PN XCreateRegion .
|
|
.IN "XCreateRegion" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
Region XCreateRegion\^()
|
|
.FN
|
|
.LP
|
|
.eM
|
|
.sp
|
|
To generate a region from a polygon, use
|
|
.PN XPolygonRegion .
|
|
.IN "XPolygonRegion" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
Region XPolygonRegion\^(\^\fIpoints\fP\^, \fIn\fP\^, \fIfill_rule\fP\^)
|
|
.br
|
|
XPoint \fIpoints[]\fP\^;
|
|
.br
|
|
int \fIn\fP\^;
|
|
.br
|
|
int \fIfill_rule\fP\^;
|
|
.FN
|
|
.IP \fIpoints\fP 1i
|
|
Specifies an array of points.
|
|
.IP \fIn\fP 1i
|
|
Specifies the number of points in the polygon.
|
|
.IP \fIfill_rule\fP 1i
|
|
Specifies the fill-rule you want to set for the specified GC.
|
|
You can pass
|
|
.PN EvenOddRule
|
|
or
|
|
.PN WindingRule .
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XPolygonRegion
|
|
function returns a region for the polygon defined by the points array.
|
|
For an explanation of fill_rule,
|
|
see
|
|
.PN XCreateGC .
|
|
.LP
|
|
.sp
|
|
To set the clip-mask of a GC to a region, use
|
|
.PN XSetRegion .
|
|
.IN "XSetRegion" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XSetRegion\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIr\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
GC \fIgc\fP\^;
|
|
.br
|
|
Region \fIr\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIgc\fP 1i
|
|
Specifies the GC.
|
|
.IP \fIr\fP 1i
|
|
Specifies the region.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XSetRegion
|
|
function sets the clip-mask in the GC to the specified region.
|
|
The region is specified relative to the drawable's origin.
|
|
The resulting GC clip origin is implementation-dependent.
|
|
Once it is set in the GC,
|
|
the region can be destroyed.
|
|
.LP
|
|
.sp
|
|
To deallocate the storage associated with a specified region, use
|
|
.PN XDestroyRegion .
|
|
.IN "XDestroyRegion" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XDestroyRegion\^(\^\fIr\fP\^)
|
|
.br
|
|
Region \fIr\fP\^;
|
|
.FN
|
|
.IP \fIr\fP 1i
|
|
Specifies the region.
|
|
.LP
|
|
.eM
|
|
.NH 3
|
|
Moving or Shrinking Regions
|
|
.XS
|
|
\*(SN Moving or Shrinking Regions
|
|
.XE
|
|
.LP
|
|
To move a region by a specified amount, use
|
|
.PN XOffsetRegion .
|
|
.IN "XOffsetRegion" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XOffsetRegion\^(\^\fIr\fP\^, \fIdx\fP\^, \fIdy\fP\^)
|
|
.br
|
|
Region \fIr\fP\^;
|
|
.br
|
|
int \fIdx\fP\^, \fIdy\fP\^;
|
|
.FN
|
|
.IP \fIr\fP 1i
|
|
Specifies the region.
|
|
.ds Dy move
|
|
.IP \fIdx\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIdy\fP 1i
|
|
Specify the x and y coordinates,
|
|
which define the amount you want to \*(Dy the specified region.
|
|
.LP
|
|
.eM
|
|
.sp
|
|
To reduce a region by a specified amount, use
|
|
.PN XShrinkRegion .
|
|
.IN "XShrinkRegion" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XShrinkRegion\^(\^\fIr\fP\^, \fIdx\fP\^, \fIdy\fP\^)
|
|
.br
|
|
Region \fIr\fP\^;
|
|
.br
|
|
int \fIdx\fP\^, \fIdy\fP\^;
|
|
.FN
|
|
.IP \fIr\fP 1i
|
|
Specifies the region.
|
|
.ds Dy shrink
|
|
.IP \fIdx\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIdy\fP 1i
|
|
Specify the x and y coordinates,
|
|
which define the amount you want to \*(Dy the specified region.
|
|
.LP
|
|
.eM
|
|
Positive values shrink the size of the region,
|
|
and negative values expand the region.
|
|
.NH 3
|
|
Computing with Regions
|
|
.XS
|
|
\*(SN Computing with Regions
|
|
.XE
|
|
.LP
|
|
.sp
|
|
To generate the smallest rectangle enclosing a region, use
|
|
.PN XClipBox .
|
|
.IN "XClipBox" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XClipBox\^(\^\fIr\fP\^, \fIrect_return\fP\^)
|
|
.br
|
|
Region \fIr\fP\^;
|
|
.br
|
|
XRectangle *\fIrect_return\fP\^;
|
|
.FN
|
|
.IP \fIr\fP 1i
|
|
Specifies the region.
|
|
.IP \fIrect_return\fP 1i
|
|
Returns the smallest enclosing rectangle.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XClipBox
|
|
function returns the smallest rectangle enclosing the specified region.
|
|
.sp
|
|
.LP
|
|
To compute the intersection of two regions, use
|
|
.PN XIntersectRegion .
|
|
.IN "XIntersectRegion" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XIntersectRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^)
|
|
.br
|
|
Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^;
|
|
.FN
|
|
.IP \fIsra\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIsrb\fP 1i
|
|
Specify the two regions with which you want to perform the computation.
|
|
.IP \fIdr_return\fP 1i
|
|
Returns the result of the computation.
|
|
.LP
|
|
.eM
|
|
.sp
|
|
To compute the union of two regions, use
|
|
.PN XUnionRegion .
|
|
.IN "XUnionRegion" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XUnionRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^)
|
|
.br
|
|
Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^;
|
|
.FN
|
|
.IP \fIsra\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIsrb\fP 1i
|
|
Specify the two regions with which you want to perform the computation.
|
|
.IP \fIdr_return\fP 1i
|
|
Returns the result of the computation.
|
|
.LP
|
|
.eM
|
|
.sp
|
|
To create a union of a source region and a rectangle, use
|
|
.PN XUnionRectWithRegion .
|
|
.IN "XUnionRectWithRegion" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XUnionRectWithRegion\^(\^\fIrectangle\fP, \fIsrc_region\fP, \
|
|
\fIdest_region_return\fP\^)
|
|
.br
|
|
XRectangle *\fIrectangle\fP\^;
|
|
.br
|
|
Region \fIsrc_region\fP\^;
|
|
.br
|
|
Region \fIdest_region_return\fP\^;
|
|
.FN
|
|
.IP \fIrectangle\fP 1i
|
|
Specifies the rectangle.
|
|
.IP \fIsrc_region\fP 1i
|
|
Specifies the source region to be used.
|
|
.IP \fIdest_region_return\fP 1i
|
|
Returns the destination region.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XUnionRectWithRegion
|
|
function updates the destination region from a union of the specified rectangle
|
|
and the specified source region.
|
|
.LP
|
|
.sp
|
|
To subtract two regions, use
|
|
.PN XSubtractRegion .
|
|
.IN "XSubtractRegion" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XSubtractRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^)
|
|
.br
|
|
Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^;
|
|
.FN
|
|
.IP \fIsra\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIsrb\fP 1i
|
|
Specify the two regions with which you want to perform the computation.
|
|
.IP \fIdr_return\fP 1i
|
|
Returns the result of the computation.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XSubtractRegion
|
|
function subtracts srb from sra and stores the results in dr_return.
|
|
.LP
|
|
.sp
|
|
To calculate the difference between the union and intersection
|
|
of two regions, use
|
|
.PN XXorRegion .
|
|
.IN "XXorRegion" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XXorRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^)
|
|
.br
|
|
Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^;
|
|
.FN
|
|
.IP \fIsra\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIsrb\fP 1i
|
|
Specify the two regions with which you want to perform the computation.
|
|
.IP \fIdr_return\fP 1i
|
|
Returns the result of the computation.
|
|
.LP
|
|
.eM
|
|
.NH 3
|
|
Determining if Regions Are Empty or Equal
|
|
.XS
|
|
\*(SN Determining if Regions Are Empty or Equal
|
|
.XE
|
|
.LP
|
|
To determine if the specified region is empty, use
|
|
.PN XEmptyRegion .
|
|
.IN "XEmptyRegion" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
Bool XEmptyRegion\^(\^\fIr\fP\^)
|
|
.br
|
|
Region \fIr\fP\^;
|
|
.FN
|
|
.IP \fIr\fP 1i
|
|
Specifies the region.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XEmptyRegion
|
|
function returns
|
|
.PN True
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
Bool XEqualRegion\^(\^\fIr1\fP\^, \fIr2\fP\^)
|
|
.br
|
|
Region \fIr1\fP\^, \fIr2\fP\^;
|
|
.FN
|
|
.IP \fIr1\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIr2\fP 1i
|
|
Specify the two regions.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XEqualRegion
|
|
function returns
|
|
.PN True
|
|
if the two regions 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
|
|
To determine if a specified point resides in a specified region, use
|
|
.PN XPointInRegion .
|
|
.IN "XPointInRegion" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
Bool XPointInRegion\^(\^\fIr\fP\^, \fIx\fP\^, \fIy\fP\^)
|
|
.br
|
|
Region \fIr\fP\^;
|
|
.br
|
|
int \fIx\fP\^, \fIy\fP\^;
|
|
.FN
|
|
.IP \fIr\fP 1i
|
|
Specifies the region.
|
|
.ds Xy , which define the point
|
|
.IP \fIx\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIy\fP 1i
|
|
Specify the x and y coordinates\*(Xy.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XPointInRegion
|
|
function returns
|
|
.PN True
|
|
if the point (x, y) is contained in the region r.
|
|
.LP
|
|
.sp
|
|
To determine if a specified rectangle is inside a region, use
|
|
.PN XRectInRegion .
|
|
.IN "XRectInRegion" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
int XRectInRegion\^(\^\fIr\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^)
|
|
.br
|
|
Region \fIr\fP\^;
|
|
.br
|
|
int \fIx\fP\^, \fIy\fP\^;
|
|
.br
|
|
unsigned int \fIwidth\fP\^, \fIheight\fP\^;
|
|
.FN
|
|
.IP \fIr\fP 1i
|
|
Specifies the region.
|
|
.ds Xy , which define the coordinates of the upper-left corner of the rectangle
|
|
.IP \fIx\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIy\fP 1i
|
|
Specify the x and y coordinates\*(Xy.
|
|
.ds Wh , which define the rectangle
|
|
.IP \fIwidth\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIheight\fP 1i
|
|
Specify the width and height\*(Wh.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XRectInRegion
|
|
function returns
|
|
.PN RectangleIn
|
|
if the rectangle is entirely in the specified region,
|
|
.PN RectangleOut
|
|
if the rectangle is entirely out of the specified region,
|
|
and
|
|
.PN RectanglePart
|
|
if the rectangle is partially in the specified region.
|
|
.NH 2
|
|
Using Cut Buffers
|
|
.XS
|
|
\*(SN Using Cut Buffers
|
|
.XE
|
|
.LP
|
|
.IN "Cut Buffers"
|
|
Xlib provides functions to manipulate cut buffers,
|
|
a very simple form of cut-and-paste inter-client communication.
|
|
Selections are a much more powerful and useful mechanism for
|
|
interchanging data between clients (see section 4.5)
|
|
and generally should be used instead of cut buffers.
|
|
.LP
|
|
Cut buffers are implemented as properties on the first root window
|
|
of the display.
|
|
The buffers can only contain text, in the STRING encoding.
|
|
The text encoding is not changed by Xlib when fetching or storing.
|
|
Eight buffers are provided
|
|
and can be accessed as a ring or as explicit buffers (numbered 0 through 7).
|
|
.LP
|
|
.sp
|
|
To store data in cut buffer 0, use
|
|
.PN XStoreBytes .
|
|
.IN "XStoreBytes" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XStoreBytes\^(\^\fIdisplay\fP, \fIbytes\fP\^, \fInbytes\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
char *\fIbytes\fP\^;
|
|
.br
|
|
int \^\fInbytes\fP\^;
|
|
.br
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIbytes\fP 1i
|
|
Specifies the bytes, which are not necessarily ASCII or null-terminated.
|
|
.IP \fInbytes\fP 1i
|
|
Specifies the number of bytes to be stored.
|
|
.LP
|
|
.eM
|
|
The data can have embedded null characters
|
|
and need not be null-terminated.
|
|
The cut buffer's contents can be retrieved later by
|
|
any client calling
|
|
.PN XFetchBytes .
|
|
.LP
|
|
.PN XStoreBytes
|
|
can generate a
|
|
.PN BadAlloc
|
|
error.
|
|
.LP
|
|
.sp
|
|
To store data in a specified cut buffer, use
|
|
.PN XStoreBuffer .
|
|
.IN "XStoreBuffer" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XStoreBuffer\^(\^\fIdisplay\fP, \fIbytes\fP\^, \fInbytes\fP\^, \fIbuffer\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
char *\fIbytes\fP\^;
|
|
.br
|
|
int \^\fInbytes\fP\^;
|
|
.br
|
|
int \fIbuffer\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIbytes\fP 1i
|
|
Specifies the bytes, which are not necessarily ASCII or null-terminated.
|
|
.IP \fInbytes\fP 1i
|
|
Specifies the number of bytes to be stored.
|
|
.ds Fn in which you want to store the bytes
|
|
.IP \fIbuffer\fP 1i
|
|
Specifies the buffer \*(Fn.
|
|
.LP
|
|
.eM
|
|
If an invalid buffer is specified, the call has no effect.
|
|
The data can have embedded null characters
|
|
and need not be null-terminated.
|
|
.LP
|
|
.PN XStoreBuffer
|
|
can generate a
|
|
.PN BadAlloc
|
|
error.
|
|
.LP
|
|
.sp
|
|
To return data from cut buffer 0, use
|
|
.PN XFetchBytes .
|
|
.IN "XFetchBytes" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
char *XFetchBytes\^(\^\fIdisplay\fP, \fInbytes_return\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
int *\fInbytes_return\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fInbytes_return\fP 1i
|
|
Returns the number of bytes in the buffer.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN 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 0.
|
|
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 .
|
|
.LP
|
|
.sp
|
|
To return data from a specified cut buffer, use
|
|
.PN XFetchBuffer .
|
|
.IN "XFetchBuffer" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
char *XFetchBuffer\^(\^\fIdisplay\fP, \fInbytes_return\fP\^, \fIbuffer\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
int *\fInbytes_return\fP\^;
|
|
.br
|
|
int \fIbuffer\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fInbytes_return\fP 1i
|
|
Returns the number of bytes in the buffer.
|
|
.ds Fn from which you want the stored data returned
|
|
.IP \fIbuffer\fP 1i
|
|
Specifies the buffer \*(Fn.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XFetchBuffer
|
|
function returns zero to the nbytes_return argument
|
|
if there is no data in the buffer or if an invalid
|
|
buffer is specified.
|
|
.LP
|
|
.sp
|
|
To rotate the cut buffers, use
|
|
.PN XRotateBuffers .
|
|
.IN "XRotateBuffers" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XRotateBuffers\^(\^\fIdisplay\fP, \fIrotate\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
int \fIrotate\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIrotate\fP 1i
|
|
Specifies how much to rotate the cut buffers.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN 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
|
|
.PN XRotateBuffers
|
|
generates
|
|
.PN BadMatch
|
|
errors if any of the eight buffers have not been created.
|
|
.NH 2
|
|
Determining the Appropriate Visual Type
|
|
.XS
|
|
\*(SN Determining the Appropriate Visual Type
|
|
.XE
|
|
.LP
|
|
A single display can 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 visual information masks and the
|
|
.PN XVisualInfo
|
|
structure,
|
|
which is defined in
|
|
.hN X11/Xutil.h
|
|
and contains:
|
|
.sM
|
|
.LP
|
|
/* Visual information mask bits */
|
|
.TS
|
|
lw(.5i) lw(2.5i) lw(.8i).
|
|
T{
|
|
#define
|
|
T} T{
|
|
.PN VisualNoMask
|
|
T} T{
|
|
0x0
|
|
T}
|
|
T{
|
|
#define
|
|
T} T{
|
|
.PN VisualIDMask
|
|
T} T{
|
|
0x1
|
|
T}
|
|
T{
|
|
#define
|
|
T} T{
|
|
.PN VisualScreenMask
|
|
T} T{
|
|
0x2
|
|
T}
|
|
T{
|
|
#define
|
|
T} T{
|
|
.PN VisualDepthMask
|
|
T} T{
|
|
0x4
|
|
T}
|
|
T{
|
|
#define
|
|
T} T{
|
|
.PN VisualClassMask
|
|
T} T{
|
|
0x8
|
|
T}
|
|
T{
|
|
#define
|
|
T} T{
|
|
.PN VisualRedMaskMask
|
|
T} T{
|
|
0x10
|
|
T}
|
|
T{
|
|
#define
|
|
T} T{
|
|
.PN VisualGreenMaskMask
|
|
T} T{
|
|
0x20
|
|
T}
|
|
T{
|
|
#define
|
|
T} T{
|
|
.PN VisualBlueMaskMask
|
|
T} T{
|
|
0x40
|
|
T}
|
|
T{
|
|
#define
|
|
T} T{
|
|
.PN VisualColormapSizeMask
|
|
T} T{
|
|
0x80
|
|
T}
|
|
T{
|
|
#define
|
|
T} T{
|
|
.PN VisualBitsPerRGBMask
|
|
T} T{
|
|
0x100
|
|
T}
|
|
T{
|
|
#define
|
|
T} T{
|
|
.PN VisualAllMask
|
|
T} T{
|
|
0x1FF
|
|
T}
|
|
.TE
|
|
.IN "XVisualInfo" "" "@DEF@"
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
/* Values */
|
|
|
|
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
|
|
.LP
|
|
.eM
|
|
To obtain a list of visual information structures that match a specified
|
|
template, use
|
|
.PN XGetVisualInfo .
|
|
.IN "XGetVisualInfo" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XVisualInfo *XGetVisualInfo\^(\^\fIdisplay\fP, \fIvinfo_mask\fP, \fIvinfo_template\fP, \fInitems_return\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
long \fIvinfo_mask\fP\^;
|
|
.br
|
|
XVisualInfo *\fIvinfo_template\fP\^;
|
|
.br
|
|
int *\fInitems_return\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIvinfo_mask\fP 1i
|
|
Specifies the visual mask value.
|
|
.IP \fIvinfo_template\fP 1i
|
|
Specifies the visual attributes that are to be used in matching the visual
|
|
structures.
|
|
.IP \fInitems_return\fP 1i
|
|
Returns the number of matching visual structures.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XGetVisualInfo
|
|
function returns a list of visual structures that have attributes
|
|
equal to the attributes specified by vinfo_template.
|
|
If no visual structures match the template using the specified vinfo_mask,
|
|
.PN XGetVisualInfo
|
|
returns a NULL.
|
|
To free the data returned by this function, use
|
|
.PN XFree .
|
|
.LP
|
|
.sp
|
|
To obtain the visual information that matches the specified depth and
|
|
class of the screen, use
|
|
.PN XMatchVisualInfo .
|
|
.IN "XMatchVisualInfo" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
Status XMatchVisualInfo\^(\^\fIdisplay\fP, \fIscreen\fP, \fIdepth\fP, \fIclass\fP, \fIvinfo_return\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
int \fIscreen\fP\^;
|
|
.br
|
|
int \fIdepth\fP\^;
|
|
.br
|
|
int \fIclass\fP\^;
|
|
.br
|
|
XVisualInfo *\fIvinfo_return\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIscreen\fP 1i
|
|
Specifies the screen.
|
|
.IP \fIdepth\fP 1i
|
|
Specifies the depth of the screen.
|
|
.IP \fIclass\fP 1i
|
|
Specifies the class of the screen.
|
|
.IP \fIvinfo_return\fP 1i
|
|
Returns the matched visual information.
|
|
.LP
|
|
.eM
|
|
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,
|
|
.PN XMatchVisualInfo
|
|
returns nonzero and the information on the visual to vinfo_return.
|
|
Otherwise, when a visual is not found,
|
|
.PN XMatchVisualInfo
|
|
returns zero.
|
|
.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
|
|
.hN 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 .
|
|
.LP
|
|
Note that no functions have been defined, as yet, to read and write images
|
|
to and from disk files.
|
|
.LP
|
|
The
|
|
.PN XImage
|
|
structure describes an image as it exists in the client's memory.
|
|
The user can 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 a subset of the image.
|
|
Other members (for example, byte order, bitmap_unit, and so forth)
|
|
are characteristics of both the image and the server.
|
|
If these members
|
|
differ between the image and the server,
|
|
.PN XPutImage
|
|
makes the appropriate conversions.
|
|
The first byte of the first line of
|
|
plane n must be located at the address (data + (n * height * bytes_per_line)).
|
|
For a description of the
|
|
.PN XImage
|
|
structure,
|
|
see section 8.7.
|
|
.LP
|
|
.sp
|
|
To allocate an
|
|
.PN XImage
|
|
structure and initialize it with image format values from a display, use
|
|
.PN XCreateImage .
|
|
.IN "XCreateImage" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XImage *XCreateImage\^(\^\fIdisplay\fP, \fIvisual\fP, \fIdepth\fP, \fIformat\fP, \fIoffset\fP, \fIdata\fP, \fIwidth\fP, \fIheight\fP\^, \fIbitmap_pad\fP,
|
|
.br
|
|
\fIbytes_per_line\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Visual *\fIvisual\fP\^;
|
|
.br
|
|
unsigned int \fIdepth\fP\^;
|
|
.br
|
|
int \fIformat\fP\^;
|
|
.br
|
|
int \fIoffset\fP\^;
|
|
.br
|
|
char *\fIdata\fP\^;
|
|
.br
|
|
unsigned int \fIwidth\fP\^;
|
|
.br
|
|
unsigned int \fIheight\fP\^;
|
|
.br
|
|
int \fIbitmap_pad\fP\^;
|
|
.br
|
|
int \fIbytes_per_line\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIvisual\fP 1i
|
|
Specifies the
|
|
.PN Visual
|
|
structure.
|
|
.IP \fIdepth\fP 1i
|
|
Specifies the depth of the image.
|
|
.IP \fIformat\fP 1i
|
|
Specifies the format for the image.
|
|
You can pass
|
|
.PN XYBitmap ,
|
|
.PN XYPixmap ,
|
|
or
|
|
.PN ZPixmap .
|
|
.IP \fIoffset\fP 1i
|
|
Specifies the number of pixels to ignore at the beginning of the scanline.
|
|
.IP \fIdata\fP 1i
|
|
Specifies the image data.
|
|
.IP \fIwidth\fP 1i
|
|
Specifies the width of the image, in pixels.
|
|
.IP \fIheight\fP 1i
|
|
Specifies the height of the image, in pixels.
|
|
.IP \fIbitmap_pad\fP 1i
|
|
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.
|
|
.IP \fIbytes_per_line\fP 1i
|
|
Specifies the number of bytes in the client image between
|
|
the start of one scanline and the start of the next.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XCreateImage
|
|
function allocates the memory needed for an
|
|
.PN 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
|
|
.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.
|
|
Other values also are passed in.
|
|
The offset permits the rapid displaying of the image without requiring each
|
|
scanline to be shifted into position.
|
|
If you pass a zero value in bytes_per_line,
|
|
Xlib assumes that the scanlines are contiguous
|
|
in memory and calculates the value of bytes_per_line itself.
|
|
.LP
|
|
Note that when the image is created using
|
|
.PN XCreateImage ,
|
|
.PN XGetImage ,
|
|
or
|
|
.PN XSubImage ,
|
|
the destroy procedure that the
|
|
.PN XDestroyImage
|
|
function calls 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 value to an 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
|
|
.hN X11/Xutil.h .
|
|
.LP
|
|
.sp
|
|
To obtain a pixel value in an image, use
|
|
.PN XGetPixel .
|
|
.IN "XGetPixel" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
unsigned long XGetPixel\^(\^\fIximage\fP, \fIx\fP, \fIy\fP\^)
|
|
.br
|
|
XImage *\fIximage\fP\^;
|
|
.br
|
|
int \fIx\fP\^;
|
|
.br
|
|
int \fIy\fP\^;
|
|
.FN
|
|
.IP \fIximage\fP 1i
|
|
Specifies the image.
|
|
.IP \fIx\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIy\fP 1i
|
|
Specify the x and y coordinates.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN 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.
|
|
.LP
|
|
.sp
|
|
To set a pixel value in an image, use
|
|
.PN XPutPixel .
|
|
.IN "XPutPixel" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XPutPixel\^(\^\fIximage\fP, \fIx\fP, \fIy\fP, \fIpixel\fP\^)
|
|
.br
|
|
XImage *\fIximage\fP\^;
|
|
.br
|
|
int \fIx\fP\^;
|
|
.br
|
|
int \fIy\fP\^;
|
|
.br
|
|
unsigned long \fIpixel\fP\^;
|
|
.FN
|
|
.IP \fIximage\fP 1i
|
|
Specifies the image.
|
|
.IP \fIx\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIy\fP 1i
|
|
Specify the x and y coordinates.
|
|
.IP \fIpixel\fP 1i
|
|
Specifies the new pixel value.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN 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.
|
|
.LP
|
|
.sp
|
|
To create a subimage, use
|
|
.PN XSubImage .
|
|
.IN "XSubImage" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XImage *XSubImage\^(\^\fIximage\fP, \fIx\fP, \fIy\fP, \fIsubimage_width\fP, \fIsubimage_height\fP\^)
|
|
.br
|
|
XImage *\fIximage\fP\^;
|
|
.br
|
|
int \fIx\fP\^;
|
|
.br
|
|
int \fIy\fP\^;
|
|
.br
|
|
unsigned int \fIsubimage_width\fP\^;
|
|
.br
|
|
unsigned int \fIsubimage_height\fP\^;
|
|
.FN
|
|
.IP \fIximage\fP 1i
|
|
Specifies the image.
|
|
.IP \fIx\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIy\fP 1i
|
|
Specify the x and y coordinates.
|
|
.IP \fIsubimage_width\fP 1i
|
|
Specifies the width of the new subimage, in pixels.
|
|
.IP \fIsubimage_height\fP 1i
|
|
Specifies the height of the new subimage, in pixels.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XSubImage
|
|
function creates a new image that is a subsection of an existing one.
|
|
It allocates the memory necessary for the new
|
|
.PN XImage
|
|
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.
|
|
.LP
|
|
.sp
|
|
To increment each pixel in an image by a constant value, use
|
|
.PN XAddPixel .
|
|
.IN "XAddPixel" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XAddPixel\^(\^\fIximage\fP, \fIvalue\fP\^)
|
|
.br
|
|
XImage *\fIximage\fP\^;
|
|
.br
|
|
long \fIvalue\fP\^;
|
|
.FN
|
|
.IP \fIximage\fP 1i
|
|
Specifies the image.
|
|
.IP \fIvalue\fP 1i
|
|
Specifies the constant value that is to be added.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XAddPixel
|
|
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.
|
|
.LP
|
|
.sp
|
|
To deallocate the memory allocated in a previous call to
|
|
.PN XCreateImage ,
|
|
use
|
|
.PN XDestroyImage .
|
|
.IN "XDestroyImage" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XDestroyImage\^(\^\fIximage\fP\^)
|
|
.br
|
|
XImage *\^\fIximage\fP\^;
|
|
.FN
|
|
.IP \fIximage\fP 1i
|
|
Specifies the image.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XDestroyImage
|
|
function deallocates the memory associated with the
|
|
.PN XImage
|
|
structure.
|
|
.LP
|
|
Note that when the image is created using
|
|
.PN XCreateImage ,
|
|
.PN XGetImage ,
|
|
or
|
|
.PN XSubImage ,
|
|
the destroy procedure that this macro calls
|
|
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 that you can use to 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
|
|
The X version 11 bitmap file format is:
|
|
.LP
|
|
.sM
|
|
.Ds 0
|
|
#define \fIname\fP_width \fIwidth\fP
|
|
#define \fIname\fP_height \fIheight\fP
|
|
#define \fIname\fP_x_hot \fIx\fP
|
|
#define \fIname\fP_y_hot \fIy\fP
|
|
static unsigned char \fIname\fP_bits[] = { 0x\fINN\fP,... }
|
|
.De
|
|
.LP
|
|
.eM
|
|
The lines for the variables ending with _x_hot and _y_hot suffixes are optional
|
|
because they are present only if a hotspot has been defined for this bitmap.
|
|
The lines for the other variables are required.
|
|
The word ``unsigned'' is optional;
|
|
that is, the type of the _bits array can be ``char'' or ``unsigned char''.
|
|
The _bits array must be large enough to contain the size bitmap.
|
|
The bitmap unit is 8.
|
|
.LP
|
|
.sp
|
|
To read a bitmap from a file and store it in a pixmap, use
|
|
.PN XReadBitmapFile .
|
|
.IN "XReadBitmapFile" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
int XReadBitmapFile(\^\fIdisplay\fP, \fId\fP, \fIfilename\fP, \fIwidth_return\fP, \fIheight_return\fP, \fIbitmap_return\fP, \fIx_hot_return\fP,
|
|
.br
|
|
\fIy_hot_return\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Drawable \fId\fP\^;
|
|
.br
|
|
char *\fIfilename\fP\^;
|
|
.br
|
|
unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^;
|
|
.br
|
|
Pixmap *\fIbitmap_return\fP\^;
|
|
.br
|
|
int *\fIx_hot_return\fP, *\fIy_hot_return\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.ds Dr \ that indicates the screen
|
|
.IP \fId\fP 1i
|
|
Specifies the drawable\*(Dr.
|
|
.IP \fIfilename\fP 1i
|
|
Specifies the file name to use.
|
|
The format of the file name is operating-system dependent.
|
|
.IP \fIwidth_return\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIheight_return\fP 1i
|
|
Return the width and height values of the read in bitmap file.
|
|
.IP \fIbitmap_return\fP 1i
|
|
Returns the bitmap that is created.
|
|
.IP \fIx_hot_return\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIy_hot_return\fP 1i
|
|
Return the hotspot coordinates.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XReadBitmapFile
|
|
function reads in a file containing a bitmap.
|
|
The file is parsed in the encoding of the current locale.
|
|
The ability to read other than the standard format
|
|
is implementation-dependent.
|
|
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
|
|
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
|
|
.PN XFreePixmap
|
|
when finished.
|
|
If \fIname\fP_x_hot and \fIname\fP_y_hot exist,
|
|
.PN XReadBitmapFile
|
|
returns them to x_hot_return and y_hot_return;
|
|
otherwise, it returns \-1,\-1.
|
|
.LP
|
|
.PN XReadBitmapFile
|
|
can generate
|
|
.PN BadAlloc ,
|
|
.PN BadDrawable ,
|
|
and
|
|
.PN BadGC
|
|
errors.
|
|
.LP
|
|
.sp
|
|
To read a bitmap from a file and return it as data, use
|
|
.PN XReadBitmapFileData .
|
|
.IN "XReadBitmapFileData" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
int XReadBitmapFileData(\^\fIfilename\fP, \fIwidth_return\fP, \fIheight_return\fP, \fIdata_return\fP, \fIx_hot_return\fP, \fIy_hot_return\fP\^)
|
|
.br
|
|
char *\fIfilename\fP\^;
|
|
.br
|
|
unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^;
|
|
.br
|
|
unsigned char *\fIdata_return\fP\^;
|
|
.br
|
|
int *\fIx_hot_return\fP, *\fIy_hot_return\fP\^;
|
|
.FN
|
|
.IP \fIfilename\fP 1i
|
|
Specifies the file name to use.
|
|
The format of the file name is operating-system dependent.
|
|
.IP \fIwidth_return\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIheight_return\fP 1i
|
|
Return the width and height values of the read in bitmap file.
|
|
.IP \fIdata_return\fP 1i
|
|
Returns the bitmap data.
|
|
.IP \fIx_hot_return\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIy_hot_return\fP 1i
|
|
Return the hotspot coordinates.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XReadBitmapFileData
|
|
function reads in a file containing a bitmap, in the same manner as
|
|
.PN XReadBitmapFile ,
|
|
but returns the data directly rather than creating a pixmap in the server.
|
|
The bitmap data is returned in data_return; the client must free this
|
|
storage when finished with it by calling
|
|
.PN XFree .
|
|
The status and other return values are the same as for
|
|
.PN XReadBitmapFile .
|
|
.LP
|
|
.sp
|
|
To write out a bitmap from a pixmap to a file, use
|
|
.PN XWriteBitmapFile .
|
|
.IN "XWriteBitmapFile" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
int XWriteBitmapFile(\^\fIdisplay\fP, \fIfilename\fP, \fIbitmap\fP, \fIwidth\fP, \fIheight\fP, \fIx_hot\fP, \fIy_hot\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
char *\fIfilename\fP\^;
|
|
.br
|
|
Pixmap \fIbitmap\fP\^;
|
|
.br
|
|
unsigned int \fIwidth\fP, \fIheight\fP\^;
|
|
.br
|
|
int \fIx_hot\fP, \fIy_hot\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIfilename\fP 1i
|
|
Specifies the file name to use.
|
|
The format of the file name is operating-system dependent.
|
|
.IP \fIbitmap\fP 1i
|
|
Specifies the bitmap.
|
|
.IP \fIwidth\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIheight\fP 1i
|
|
Specify the width and height.
|
|
.IP \fIx_hot\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIy_hot\fP 1i
|
|
Specify where to place the hotspot coordinates (or \-1,\-1 if none are present)
|
|
in the file.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XWriteBitmapFile
|
|
function writes a bitmap out to a file in the X Version 11 format.
|
|
The name used in the output file is derived from the file name
|
|
by deleting the directory prefix.
|
|
The file is written in the encoding of the current locale.
|
|
If the file cannot be opened for writing,
|
|
it returns
|
|
.PN BitmapOpenFailed .
|
|
If insufficient memory is allocated,
|
|
.PN XWriteBitmapFile
|
|
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 hotspot coordinates for the bitmap.
|
|
.LP
|
|
.PN XWriteBitmapFile
|
|
can generate
|
|
.PN BadDrawable
|
|
and
|
|
.PN BadMatch
|
|
errors.
|
|
.LP
|
|
.sp
|
|
To create a pixmap and then store bitmap-format data into it, use
|
|
.PN XCreatePixmapFromBitmapData .
|
|
.IN "XCreatePixmapFromBitmapData" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
Pixmap XCreatePixmapFromBitmapData\^(\^\fIdisplay\fP, \fId\fP, \fIdata\fP, \fIwidth\fP, \fIheight\fP, \fIfg\fP, \fIbg\fP, \fIdepth\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Drawable \fId\fP\^;
|
|
.br
|
|
char *\fIdata\fP\^;
|
|
.br
|
|
unsigned int \fIwidth\fP, \fIheight\fP\^;
|
|
.br
|
|
unsigned long \fIfg\fP, \fIbg\fP\^;
|
|
.br
|
|
unsigned int \fIdepth\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.ds Dr \ that indicates the screen
|
|
.IP \fId\fP 1i
|
|
Specifies the drawable\*(Dr.
|
|
.IP \fIdata\fP 1i
|
|
Specifies the data in bitmap format.
|
|
.IP \fIwidth\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIheight\fP 1i
|
|
Specify the width and height.
|
|
.IP \fIfg\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIbg\fP 1i
|
|
Specify the foreground and background pixel values to use.
|
|
.IP \fIdepth\fP 1i
|
|
Specifies the depth of the pixmap.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XCreatePixmapFromBitmapData
|
|
function creates a pixmap of the given depth and then does a bitmap-format
|
|
.PN XPutImage
|
|
of the data into it.
|
|
The depth must be supported by the screen of the specified drawable,
|
|
or a
|
|
.PN BadMatch
|
|
error results.
|
|
.LP
|
|
.PN XCreatePixmapFromBitmapData
|
|
can generate
|
|
.PN BadAlloc ,
|
|
.PN BadDrawable ,
|
|
.PN BadGC ,
|
|
and
|
|
.PN BadValue
|
|
errors.
|
|
.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@"
|
|
.sM
|
|
.FD 0
|
|
Pixmap XCreateBitmapFromData(\^\fIdisplay\fP, \fId\fP, \fIdata\fP, \fIwidth\fP, \fIheight\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Drawable \fId\fP\^;
|
|
.br
|
|
char *\fIdata\fP\^;
|
|
.br
|
|
unsigned int \fIwidth\fP, \fIheight\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.ds Dr \ that indicates the screen
|
|
.IP \fId\fP 1i
|
|
Specifies the drawable\*(Dr.
|
|
.IP \fIdata\fP 1i
|
|
Specifies the location of the bitmap data.
|
|
.IP \fIwidth\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIheight\fP 1i
|
|
Specify the width and height.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XCreateBitmapFromData
|
|
function allows you to include in your C program (using
|
|
.PN #include )
|
|
a bitmap file that was written out by
|
|
.PN XWriteBitmapFile
|
|
(X version 11 format only) without reading in the bitmap file.
|
|
The following example creates a gray bitmap:
|
|
.LP
|
|
.Ds 0
|
|
#include "gray.bitmap"
|
|
.sp 6p
|
|
Pixmap bitmap;
|
|
bitmap = XCreateBitmapFromData(display, window, gray_bits, gray_width, gray_height);
|
|
.De
|
|
.LP
|
|
If insufficient working storage was allocated,
|
|
.PN XCreateBitmapFromData
|
|
returns
|
|
.PN None .
|
|
It is your responsibility to free the
|
|
bitmap using
|
|
.PN XFreePixmap
|
|
when finished.
|
|
.LP
|
|
.PN XCreateBitmapFromData
|
|
can generate
|
|
.PN BadAlloc
|
|
and
|
|
.PN BadGC
|
|
errors.
|
|
.NH 2
|
|
Using the Context Manager
|
|
.XS
|
|
\*(SN Using the Context Manager
|
|
.XE
|
|
.LP
|
|
The context manager provides a way of associating data with an X resource ID
|
|
(mostly typically 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
|
|
resource ID,
|
|
and each piece of data has a type associated with it.
|
|
The context manager requires knowledge of the resource 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 X resource 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
|
|
.hN X11/Xutil.h .
|
|
.LP
|
|
.sp
|
|
To save a data value that corresponds to a resource ID and context type, use
|
|
.PN XSaveContext .
|
|
.IN "XSaveContext" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
int XSaveContext(\^\fIdisplay\fP, \fIrid\fP, \fIcontext\fP, \fIdata\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
XID \fIrid\fP\^;
|
|
.br
|
|
XContext \fIcontext\fP\^;
|
|
.br
|
|
XPointer \fIdata\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIrid\fP 1i
|
|
Specifies the resource ID with which the data is associated.
|
|
.IP \fIcontext\fP 1i
|
|
Specifies the context type to which the data belongs.
|
|
.IP \fIdata\fP 1i
|
|
Specifies the data to be associated with the window and type.
|
|
.LP
|
|
.eM
|
|
If an entry with the specified resource ID and type already exists,
|
|
.PN XSaveContext
|
|
overrides it with the specified context.
|
|
The
|
|
.PN XSaveContext
|
|
function returns a 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 resource ID and type, use
|
|
.PN XFindContext .
|
|
.IN "XFindContext" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
int XFindContext(\^\fIdisplay\fP, \fIrid\fP, \fIcontext\fP, \fIdata_return\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
XID \fIrid\fP\^;
|
|
.br
|
|
XContext \fIcontext\fP\^;
|
|
.br
|
|
XPointer *\fIdata_return\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIrid\fP 1i
|
|
Specifies the resource ID with which the data is associated.
|
|
.IP \fIcontext\fP 1i
|
|
Specifies the context type to which the data belongs.
|
|
.IP \fIdata_return\fP 1i
|
|
Returns the data.
|
|
.LP
|
|
.eM
|
|
Because it is a return value,
|
|
the data is a pointer.
|
|
The
|
|
.PN XFindContext
|
|
function returns a 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 resource ID and type, use
|
|
.PN XDeleteContext .
|
|
.IN "XDeleteContext" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
int XDeleteContext(\^\fIdisplay\fP, \fIrid\fP, \fIcontext\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
XID \fIrid\fP;
|
|
.br
|
|
XContext \fIcontext\fP;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIrid\fP 1i
|
|
Specifies the resource ID with which the data is associated.
|
|
.IP \fIcontext\fP 1i
|
|
Specifies the context type to which the data belongs.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XDeleteContext
|
|
function deletes the entry for the given resource ID
|
|
and type from the data structure.
|
|
This function returns the same error codes that
|
|
.PN XFindContext
|
|
returns if called with the same arguments.
|
|
.PN XDeleteContext
|
|
does not free the data whose address was saved.
|
|
.LP
|
|
.sp
|
|
To create a unique context type that may be used in subsequent calls to
|
|
.PN XSaveContext
|
|
and
|
|
.PN XFindContext ,
|
|
use
|
|
.PN XUniqueContext .
|
|
.IN "XUniqueContext" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XContext XUniqueContext(\^)
|
|
.FN
|
|
.LP
|
|
.eM
|
|
.bp
|