diff options
Diffstat (limited to 'libX11/specs/libX11/CH16')
| -rw-r--r-- | libX11/specs/libX11/CH16 | 2364 |
1 files changed, 2364 insertions, 0 deletions
diff --git a/libX11/specs/libX11/CH16 b/libX11/specs/libX11/CH16 new file mode 100644 index 000000000..3a21a2290 --- /dev/null +++ b/libX11/specs/libX11/CH16 @@ -0,0 +1,2364 @@ +.\" 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 |