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