1
<?xml version="1.0" encoding="UTF-8" ?>
2
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
4
<chapter id="application_utility_functions">
5
<title>Application Utility Functions</title>
16
<!-- Chapter 16: Application Utility Functions -->
18
Once you have initialized the X system,
19
you can use the Xlib utility functions to:
24
Use keyboard utility functions
29
Use Latin-1 keyboard event functions
34
Allocate permanent storage
39
Parse the window geometry
54
Determine the appropriate visual type
69
Use the context manager
76
the functions discussed in this chapter provide the functionality that
77
is frequently needed and that spans toolkits.
78
Many of these functions do not generate actual protocol requests to the server.
80
<sect1 id="Using_Keyboard_Utility_Functions">
81
<title>Using Keyboard Utility Functions</title>
83
<!-- (SN Using Keyboard Utility Functions -->
87
This section discusses mapping between KeyCodes and KeySyms,
88
classifying KeySyms, and mapping between KeySyms and string names.
89
The first three functions in this section operate on a cached copy of the
90
server keyboard mapping.
91
The first four KeySyms for each KeyCode
92
are modified according to the rules given in section 12.7.
93
To obtain the untransformed KeySyms defined for a key,
94
use the functions described in section 12.7.
99
To obtain a KeySym for the KeyCode of an event, use
100
<function>XLookupKeysym</function>.
101
<indexterm significance="preferred"><primary>XLookupKeysym</primary></indexterm>
105
<funcdef>KeySym <function>XLookupKeysym</function></funcdef>
106
<paramdef>XKeyEvent<parameter> *key_event</parameter></paramdef>
107
<paramdef>int<parameter> index</parameter></paramdef>
114
<emphasis remap='I'>key_event</emphasis>
119
<symbol>KeyPress</symbol>
121
<symbol>KeyRelease</symbol>
128
<emphasis remap='I'>index</emphasis>
132
Specifies the index into the KeySyms list for the event's KeyCode.
142
<function>XLookupKeysym</function>
143
function uses a given keyboard event and the index you specified to return
144
the KeySym from the list that corresponds to the KeyCode member in the
145
<type>XKeyPressedEvent</type>
147
<type>XKeyReleasedEvent</type>
149
If no KeySym is defined for the KeyCode of the event,
150
<function>XLookupKeysym</function>
152
<symbol>NoSymbol</symbol>.
157
To obtain a KeySym for a specific KeyCode, use
158
<function>XKeycodeToKeysym</function>.
159
<indexterm significance="preferred"><primary>XKeycodeToKeysym</primary></indexterm>
163
<funcdef>KeySym <function>XKeycodeToKeysym</function></funcdef>
164
<paramdef>Display<parameter> *display</parameter></paramdef>
165
<paramdef>KeyCode<parameter> keycode</parameter></paramdef>
166
<paramdef>int<parameter> index</parameter></paramdef>
173
<emphasis remap='I'>display</emphasis>
177
Specifies the connection to the X server.
183
<emphasis remap='I'>keycode</emphasis>
187
Specifies the KeyCode.
193
<emphasis remap='I'>index</emphasis>
197
Specifies the element of KeyCode vector.
207
<function>XKeycodeToKeysym</function>
208
function uses internal Xlib tables
209
and returns the KeySym defined for the specified KeyCode and
210
the element of the KeyCode vector.
211
If no symbol is defined,
212
<function>XKeycodeToKeysym</function>
214
<symbol>NoSymbol</symbol>.
219
To obtain a KeyCode for a key having a specific KeySym, use
220
<function>XKeysymToKeycode</function>.
221
<indexterm significance="preferred"><primary>XKeysymToKeycode</primary></indexterm>
225
<funcdef>KeyCode <function>XKeysymToKeycode</function></funcdef>
226
<paramdef>Display<parameter> *display</parameter></paramdef>
227
<paramdef>KeySym<parameter> keysym</parameter></paramdef>
234
<emphasis remap='I'>display</emphasis>
238
Specifies the connection to the X server.
244
<emphasis remap='I'>keysym</emphasis>
248
Specifies the KeySym that is to be searched for.
257
If the specified KeySym is not defined for any KeyCode,
258
<function>XKeysymToKeycode</function>
264
The mapping between KeyCodes and KeySyms is cached internal to Xlib.
265
When this information is changed at the server, an Xlib function must
266
be called to refresh the cache.
267
To refresh the stored modifier and keymap information, use
268
<function>XRefreshKeyboardMapping</function>.
269
<indexterm significance="preferred"><primary>XRefreshKeyboardMapping</primary></indexterm>
273
<funcdef><function>XRefreshKeyboardMapping</function></funcdef>
274
<paramdef>XMappingEvent<parameter> *event_map</parameter></paramdef>
281
<emphasis remap='I'>event_map</emphasis>
285
Specifies the mapping event that is to be used.
295
<function>XRefreshKeyboardMapping</function>
296
function refreshes the stored modifier and keymap information.
297
You usually call this function when a
298
<symbol>MappingNotify</symbol>
299
event with a request member of
300
<symbol>MappingKeyboard</symbol>
302
<symbol>MappingModifier</symbol>
304
The result is to update Xlib's knowledge of the keyboard.
309
To obtain the uppercase and lowercase forms of a KeySym, use
310
<function>XConvertCase</function>.
311
<indexterm significance="preferred"><primary>XConvertCase</primary></indexterm>
315
<funcdef>void <function>XConvertCase</function></funcdef>
316
<paramdef>KeySym<parameter> keysym</parameter></paramdef>
317
<paramdef>KeySym<parameter> *lower_return</parameter></paramdef>
318
<paramdef>KeySym<parameter> *upper_return</parameter></paramdef>
322
<!-- .ds Fn converted -->
326
<emphasis remap='I'>keysym</emphasis>
330
Specifies the KeySym that is to be (Fn.
336
<emphasis remap='I'>lower_return</emphasis>
340
Returns the lowercase form of keysym, or keysym.
346
<emphasis remap='I'>upper_return</emphasis>
350
Returns the uppercase form of keysym, or keysym.
360
<function>XConvertCase</function>
361
function returns the uppercase and lowercase forms of the specified Keysym,
362
if the KeySym is subject to case conversion;
363
otherwise, the specified KeySym is returned to both lower_return and
365
Support for conversion of other than Latin and Cyrillic KeySyms is
366
implementation-dependent.
371
KeySyms have string names as well as numeric codes.
372
To convert the name of the KeySym to the KeySym code, use
373
<function>XStringToKeysym</function>.
374
<indexterm significance="preferred"><primary>XStringToKeysym</primary></indexterm>
378
<funcdef>KeySym <function>XStringToKeysym</function></funcdef>
379
<paramdef>char<parameter> *string</parameter></paramdef>
386
<emphasis remap='I'>string</emphasis>
390
Specifies the name of the KeySym that is to be converted.
399
Standard KeySym names are obtained from
400
<filename class="headerfile"><X11/keysymdef.h></filename>
401
<indexterm type="file"><primary><filename class="headerfile">X11/keysymdef.h</filename></primary></indexterm>
402
<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/keysymdef.h></filename></secondary></indexterm>
403
<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/keysymdef.h></filename></secondary></indexterm>
404
by removing the XK_ prefix from each name.
405
KeySyms that are not part of the Xlib standard also may be obtained
407
The set of KeySyms that are available in this manner
408
and the mechanisms by which Xlib obtains them is implementation-dependent.
412
If the KeySym name is not in the Host Portable Character Encoding,
413
the result is implementation-dependent.
414
If the specified string does not match a valid KeySym,
415
<function>XStringToKeysym</function>
417
<symbol>NoSymbol</symbol>.
422
To convert a KeySym code to the name of the KeySym, use
423
<function>XKeysymToString</function>.
424
<indexterm significance="preferred"><primary>XKeysymToString</primary></indexterm>
428
<funcdef>char *<function>XKeysymToString</function></funcdef>
429
<paramdef>KeySym<parameter> keysym</parameter></paramdef>
433
<!-- .ds Fn converted -->
437
<emphasis remap='I'>keysym</emphasis>
441
Specifies the KeySym that is to be (Fn.
450
The returned string is in a static area and must not be modified.
451
The returned string is in the Host Portable Character Encoding.
452
If the specified KeySym is not defined,
453
<function>XKeysymToString</function>
456
<sect2 id="KeySym_Classification_Macros">
457
<title>KeySym Classification Macros</title>
459
<!-- (SN KeySym Classification Macros -->
463
You may want to test if a KeySym is, for example,
464
on the keypad or on one of the function keys.
465
You can use KeySym macros to perform the following tests.
467
<para>IsCursorKey(<emphasis remap='I'>keysym</emphasis>)</para>
469
<!-- .ds Fn tested -->
473
<emphasis remap='I'>keysym</emphasis>
477
Specifies the KeySym that is to be tested.
486
<indexterm significance="preferred"><primary>IsCursorKey</primary></indexterm>
488
<symbol>True</symbol>
489
if the specified KeySym is a cursor key.
494
<para>IsFunctionKey(<emphasis remap='I'>keysym</emphasis>)</para>
496
<!-- .ds Fn tested -->
500
<emphasis remap='I'>keysym</emphasis>
504
Specifies the KeySym that is to be tested.
513
<indexterm significance="preferred"><primary>IsFunctionKey</primary></indexterm>
515
<symbol>True</symbol>
516
if the specified KeySym is a function key.
521
<para>IsKeypadKey(<emphasis remap='I'>keysym</emphasis>)</para>
523
<!-- .ds Fn tested -->
527
<emphasis remap='I'>keysym</emphasis>
531
Specifies the KeySym that is to be (Fn.
540
<indexterm significance="preferred"><primary>IsKeypadKey</primary></indexterm>
542
<symbol>True</symbol>
543
if the specified KeySym is a standard keypad key.
548
<para>IsPrivateKeypadKey(<emphasis remap='I'>keysym</emphasis>)</para>
553
<emphasis remap='I'>keysym</emphasis>
557
Specifies the KeySym that is to be (Fn.
566
<indexterm significance="preferred"><primary>IsPrivateKeypadKey</primary></indexterm>
568
<symbol>True</symbol>
569
if the specified KeySym is a vendor-private keypad key.
575
<para>IsMiscFunctionKey(<emphasis remap='I'>keysym</emphasis>)</para>
577
<!-- .ds Fn tested -->
581
<emphasis remap='I'>keysym</emphasis>
585
Specifies the KeySym that is to be (Fn.
594
<indexterm significance="preferred"><primary>IsMiscFunctionKey</primary></indexterm>
596
<symbol>True</symbol>
597
if the specified KeySym is a miscellaneous function key.
602
<para>IsModifierKey(<emphasis remap='I'>keysym</emphasis>)</para>
607
<emphasis remap='I'>keysym</emphasis>
611
Specifies the KeySym that is to be tested.
620
<indexterm significance="preferred"><primary>IsModifierKey</primary></indexterm>
622
<symbol>True</symbol>
623
if the specified KeySym is a modifier key.
626
<para>IsPFKey(<emphasis remap='I'>keysym</emphasis>)</para>
631
<emphasis remap='I'>keysym</emphasis>
635
Specifies the KeySym that is to be tested.
644
<indexterm significance="preferred"><primary>IsPFKey</primary></indexterm>
646
<symbol>True</symbol>
647
if the specified KeySym is a PF key.
651
<sect1 id="Using_Latin_Keyboard_Event_Functions">
652
<title>Using Latin-1 Keyboard Event Functions</title>
654
<!-- (SN Using Latin-1 Keyboard Event Functions -->
658
Chapter 13 describes internationalized text input facilities,
659
but sometimes it is expedient to write an application that
660
only deals with Latin-1 characters and ASCII controls,
661
so Xlib provides a simple function for that purpose.
662
<function>XLookupString</function>
663
handles the standard modifier semantics described in section 12.7.
664
This function does not use any of the input method facilities
665
described in chapter 13 and does not depend on the current locale.
670
To map a key event to an ISO Latin-1 string, use
671
<function>XLookupString</function>.
672
<indexterm significance="preferred"><primary>XLookupString</primary></indexterm>
676
<funcdef>int <function>XLookupString</function></funcdef>
677
<paramdef>XKeyEvent<parameter> *event_struct</parameter></paramdef>
678
<paramdef>char<parameter> *buffer_return</parameter></paramdef>
679
<paramdef>int<parameter> bytes_buffer</parameter></paramdef>
680
<paramdef>KeySym<parameter> *keysym_return</parameter></paramdef>
681
<paramdef>XComposeStatus<parameter> *status_in_out</parameter></paramdef>
688
<emphasis remap='I'>event_struct</emphasis>
692
Specifies the key event structure to be used.
694
<type>XKeyPressedEvent</type>
696
<type>XKeyReleasedEvent</type>.
702
<emphasis remap='I'>buffer_return</emphasis>
706
Returns the translated characters.
712
<emphasis remap='I'>bytes_buffer</emphasis>
716
Specifies the length of the buffer.
717
No more than bytes_buffer of translation are returned.
723
<emphasis remap='I'>keysym_return</emphasis>
727
Returns the KeySym computed from the event if this argument is not NULL.
733
<emphasis remap='I'>status_in_out</emphasis>
737
Specifies or returns the
738
<structname>XComposeStatus</structname>
749
<function>XLookupString</function>
750
function translates a key event to a KeySym and a string.
751
The KeySym is obtained by using the standard interpretation of the
752
<symbol>Shift</symbol>,
753
<symbol>Lock</symbol>,
754
group, and numlock modifiers as defined in the X Protocol specification.
755
If the KeySym has been rebound (see
756
<function>XRebindKeysym</function>),
757
the bound string will be stored in the buffer.
758
Otherwise, the KeySym is mapped, if possible, to an ISO Latin-1 character
759
or (if the Control modifier is on) to an ASCII control character,
760
and that character is stored in the buffer.
761
<function>XLookupString</function>
762
returns the number of characters that are stored in the buffer.
766
If present (non-NULL),
768
<structname>XComposeStatus</structname>
769
structure records the state,
770
which is private to Xlib,
771
that needs preservation across calls to
772
<function>XLookupString</function>
773
to implement compose processing.
775
<structname>XComposeStatus</structname>
776
structures is implementation-dependent;
777
a portable program must pass NULL for this argument.
781
<function>XLookupString</function>
782
depends on the cached keyboard information mentioned in the
783
previous section, so it is necessary to use
784
<function>XRefreshKeyboardMapping</function>
785
to keep this information up-to-date.
790
To rebind the meaning of a KeySym for
791
<function>XLookupString</function>,
793
<function>XRebindKeysym</function>.
794
<indexterm significance="preferred"><primary>XRebindKeysym</primary></indexterm>
798
<funcdef><function>XRebindKeysym</function></funcdef>
799
<paramdef>Display<parameter> *display</parameter></paramdef>
800
<paramdef>KeySym<parameter> keysym</parameter></paramdef>
801
<paramdef>KeySym<parameter> list[ ]</parameter></paramdef>
802
<paramdef>int<parameter> mod_count</parameter></paramdef>
803
<paramdef>unsignedchar<parameter> *string</parameter></paramdef>
804
<paramdef>int<parameter> num_bytes</parameter></paramdef>
811
<emphasis remap='I'>display</emphasis>
815
Specifies the connection to the X server.
816
<!-- .ds Fn rebound -->
822
<emphasis remap='I'>keysym</emphasis>
826
Specifies the KeySym that is to be (Fn.
832
<emphasis remap='I'>list</emphasis>
836
Specifies the KeySyms to be used as modifiers.
842
<emphasis remap='I'>mod_count</emphasis>
846
Specifies the number of modifiers in the modifier list.
852
<emphasis remap='I'>string</emphasis>
856
Specifies the string that is copied and will be returned by
857
<function>XLookupString</function>.
863
<emphasis remap='I'>num_bytes</emphasis>
867
Specifies the number of bytes in the string argument.
877
<function>XRebindKeysym</function>
878
function can be used to rebind the meaning of a KeySym for the client.
879
It does not redefine any key in the X server but merely
880
provides an easy way for long strings to be attached to keys.
881
<function>XLookupString</function>
882
returns this string when the appropriate set of
883
modifier keys are pressed and when the KeySym would have been used for
885
No text conversions are performed;
886
the client is responsible for supplying appropriately encoded strings.
887
Note that you can rebind a KeySym that may not exist.
890
<sect1 id="Allocating_Permanent_Storage">
891
<title>Allocating Permanent Storage</title>
893
<!-- (SN Allocating Permanent Storage -->
897
To allocate some memory you will never give back, use
898
<function>Xpermalloc</function>.
899
<indexterm significance="preferred"><primary>Xpermalloc</primary></indexterm>
903
<funcdef>char *<function>Xpermalloc</function></funcdef>
904
<paramdef>unsignedint<parameter> size</parameter></paramdef>
913
<function>Xpermalloc</function>
914
function allocates storage that can never be freed for the life of the
915
program. The memory is allocated with alignment for the C type double.
916
This function may provide some performance and space savings over
917
the standard operating system memory allocator.
920
<sect1 id="Parsing_the_Window_Geometry">
921
<title>Parsing the Window Geometry</title>
923
<!-- (SN Parsing the Window Geometry -->
927
To parse standard window geometry strings, use
928
<function>XParseGeometry</function>.
929
<indexterm><primary>Window</primary><secondary>determining location</secondary></indexterm>
930
<indexterm significance="preferred"><primary>XParseGeometry</primary></indexterm>
937
<funcdef>int <function>XParseGeometry</function></funcdef>
938
<paramdef>char<parameter> *parsestring</parameter></paramdef>
939
<paramdef>int*x_return,<parameter> *y_return</parameter></paramdef>
940
<paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
947
<emphasis remap='I'>parsestring</emphasis>
951
Specifies the string you want to parse.
957
<emphasis remap='I'>x_return</emphasis>
968
<emphasis remap='I'>y_return</emphasis>
972
Return the x and y offsets.
978
<emphasis remap='I'>width_return</emphasis>
989
<emphasis remap='I'>height_return</emphasis>
993
Return the width and height determined.
1003
X applications use a standard string to indicate window size and placement.
1004
<function>XParseGeometry</function>
1005
makes it easier to conform to this standard because it allows you
1006
to parse the standard window geometry.
1007
Specifically, this function lets you parse strings of the form:
1011
<!-- .\" Start marker code here -->
1012
<literallayout class="monospaced">
1013
[=][<<emphasis remap='I'>width</emphasis>>{xX}<<emphasis remap='I'>height</emphasis>>][{+-}<<emphasis remap='I'>xoffset</emphasis>>{+-}<<emphasis remap='I'>yoffset</emphasis>>]
1015
<!-- .\" End marker code here -->
1019
The fields map into the arguments associated with this function.
1020
(Items enclosed in < > are integers, items in [ ] are optional, and
1021
items enclosed in { } indicate ``choose one of.''
1022
Note that the brackets should not appear in the actual string.)
1023
If the string is not in the Host Portable Character Encoding,
1024
the result is implementation-dependent.
1029
<function>XParseGeometry</function>
1030
function returns a bitmask that indicates which of the four values (width,
1031
height, xoffset, and yoffset) were actually found in the string
1032
and whether the x and y values are negative.
1033
By convention, −0 is not equal to +0, because the user needs to
1034
be able to say ``position the window relative to the right or bottom edge.''
1035
For each value found, the corresponding argument is updated.
1036
For each value not found, the argument is left unchanged.
1037
The bits are represented by
1038
<symbol>XValue</symbol>,
1039
<symbol>YValue</symbol>,
1040
<symbol>WidthValue</symbol>,
1041
<symbol>HeightValue</symbol>,
1042
<symbol>XNegative</symbol>,
1044
<symbol>YNegative</symbol>
1046
<filename class="headerfile"><X11/Xutil.h></filename>.
1047
<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
1048
<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
1049
<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
1050
They will be set whenever one of the values is defined
1051
or one of the signs is set.
1055
If the function returns either the
1056
<symbol>XValue</symbol>
1058
<symbol>YValue</symbol>
1060
you should place the window at the requested position.
1065
To construct a window's geometry information, use
1066
<function>XWMGeometry</function>.
1067
<indexterm significance="preferred"><primary>XWMGeometry</primary></indexterm>
1071
<funcdef>int <function>XWMGeometry</function></funcdef>
1072
<paramdef>Display<parameter> *display</parameter></paramdef>
1073
<paramdef>int<parameter> screen</parameter></paramdef>
1074
<paramdef>char<parameter> *user_geom</parameter></paramdef>
1075
<paramdef>char<parameter> *def_geom</parameter></paramdef>
1076
<paramdef>unsignedint<parameter> bwidth</parameter></paramdef>
1077
<paramdef>XSizeHints<parameter> *hints</parameter></paramdef>
1078
<paramdef>int*x_return,<parameter> *y_return</parameter></paramdef>
1079
<paramdef>int<parameter> *width_return</parameter></paramdef>
1080
<paramdef>int<parameter> *height_return</parameter></paramdef>
1081
<paramdef>int<parameter> *gravity_return</parameter></paramdef>
1088
<emphasis remap='I'>display</emphasis>
1092
Specifies the connection to the X server.
1098
<emphasis remap='I'>screen</emphasis>
1102
Specifies the screen.
1108
<emphasis remap='I'>user_geom</emphasis>
1112
Specifies the user-specified geometry or NULL.
1118
<emphasis remap='I'>def_geom</emphasis>
1122
Specifies the application's default geometry or NULL.
1128
<emphasis remap='I'>bwidth</emphasis>
1132
Specifies the border width.
1138
<emphasis remap='I'>hints</emphasis>
1142
Specifies the size hints for the window in its normal state.
1148
<emphasis remap='I'>x_return</emphasis>
1159
<emphasis remap='I'>y_return</emphasis>
1163
Return the x and y offsets.
1169
<emphasis remap='I'>width_return</emphasis>
1180
<emphasis remap='I'>height_return</emphasis>
1184
Return the width and height determined.
1190
<emphasis remap='I'>gravity_return</emphasis>
1194
Returns the window gravity.
1204
<function>XWMGeometry</function>
1205
function combines any geometry information (given in the format used by
1206
<function>XParseGeometry</function>)
1207
specified by the user and by the calling program with size hints
1208
(usually the ones to be stored in <property>WM_NORMAL_HINTS</property>) and returns the position,
1210
(<symbol>NorthWestGravity</symbol>,
1211
<symbol>NorthEastGravity</symbol>,
1212
<symbol>SouthEastGravity</symbol>,
1214
<symbol>SouthWestGravity</symbol>)
1215
that describe the window.
1216
If the base size is not set in the
1217
<structname>XSizeHints</structname>
1219
the minimum size is used if set.
1220
Otherwise, a base size of zero is assumed.
1221
If no minimum size is set in the hints structure,
1222
the base size is used.
1223
A mask (in the form returned by
1224
<function>XParseGeometry</function>)
1225
that describes which values came from the user specification
1226
and whether or not the position coordinates are relative
1227
to the right and bottom edges is returned.
1228
Note that these coordinates will have already been accounted for
1229
in the x_return and y_return values.
1233
Note that invalid geometry specifications can cause a width or height
1234
of zero to be returned.
1235
The caller may pass the address of the hints win_gravity field
1236
as gravity_return to update the hints directly.
1240
<sect1 id="Manipulating_Regions">
1241
<title>Manipulating Regions</title>
1243
<!-- (SN Manipulating Regions -->
1246
Regions are arbitrary sets of pixel locations.
1247
Xlib provides functions for manipulating regions.
1249
<structname>Region</structname>
1251
<filename class="headerfile"><X11/Xutil.h></filename>.
1252
<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
1253
<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
1254
<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
1255
Xlib provides functions that you can use to manipulate regions.
1256
This section discusses how to:
1262
Create, copy, or destroy regions
1267
Move or shrink regions
1272
Compute with regions
1277
Determine if regions are empty or equal
1282
Locate a point or rectangle in a region
1287
<sect2 id="Creating_Copying_or_Destroying_Regions">
1288
<title>Creating, Copying, or Destroying Regions</title>
1290
<!-- (SN Creating, Copying, or Destroying Regions -->
1294
To create a new empty region, use
1295
<function>XCreateRegion</function>.
1297
<para>Region XCreateRegion()</para>
1303
To generate a region from a polygon, use
1304
<function>XPolygonRegion</function>.
1306
<indexterm significance="preferred"><primary>XPolygonRegion</primary></indexterm>
1310
<funcdef>Region <function>XPolygonRegion</function></funcdef>
1311
<paramdef>XPoint<parameter> points[]</parameter></paramdef>
1312
<paramdef>int<parameter> n</parameter></paramdef>
1313
<paramdef>int<parameter> fill_rule</parameter></paramdef>
1320
<emphasis remap='I'>points</emphasis>
1324
Specifies an array of points.
1330
<emphasis remap='I'>n</emphasis>
1334
Specifies the number of points in the polygon.
1340
<emphasis remap='I'>fill_rule</emphasis>
1344
Specifies the fill-rule you want to set for the specified GC.
1346
<symbol>EvenOddRule</symbol>
1348
<symbol>WindingRule</symbol>.
1358
<function>XPolygonRegion</function>
1359
function returns a region for the polygon defined by the points array.
1360
For an explanation of fill_rule,
1362
<function>XCreateGC</function>.
1367
To set the clip-mask of a GC to a region, use
1368
<function>XSetRegion</function>.
1369
<indexterm significance="preferred"><primary>XSetRegion</primary></indexterm>
1373
<funcdef><function>XSetRegion</function></funcdef>
1374
<paramdef>Display<parameter> *display</parameter></paramdef>
1375
<paramdef>GC<parameter> gc</parameter></paramdef>
1376
<paramdef>Region<parameter> r</parameter></paramdef>
1383
<emphasis remap='I'>display</emphasis>
1387
Specifies the connection to the X server.
1393
<emphasis remap='I'>gc</emphasis>
1403
<emphasis remap='I'>r</emphasis>
1407
Specifies the region.
1417
<function>XSetRegion</function>
1418
function sets the clip-mask in the GC to the specified region.
1419
The region is specified relative to the drawable's origin.
1420
The resulting GC clip origin is implementation-dependent.
1421
Once it is set in the GC,
1422
the region can be destroyed.
1427
To deallocate the storage associated with a specified region, use
1428
<function>XDestroyRegion</function>.
1429
<indexterm significance="preferred"><primary>XDestroyRegion</primary></indexterm>
1433
<funcdef><function>XDestroyRegion</function></funcdef>
1434
<paramdef>Region<parameter> r</parameter></paramdef>
1441
<emphasis remap='I'>r</emphasis>
1445
Specifies the region.
1456
<sect2 id="Moving_or_Shrinking_Regions">
1457
<title>Moving or Shrinking Regions</title>
1459
<!-- (SN Moving or Shrinking Regions -->
1463
To move a region by a specified amount, use
1464
<function>XOffsetRegion</function>.
1465
<indexterm significance="preferred"><primary>XOffsetRegion</primary></indexterm>
1469
<funcdef><function>XOffsetRegion</function></funcdef>
1470
<paramdef>Region<parameter> r</parameter></paramdef>
1471
<paramdef>intdx,<parameter> dy</parameter></paramdef>
1478
<emphasis remap='I'>r</emphasis>
1482
Specifies the region.
1483
<!-- .ds Dy move -->
1489
<emphasis remap='I'>dx</emphasis>
1500
<emphasis remap='I'>dy</emphasis>
1504
Specify the x and y coordinates,
1505
which define the amount you want to (Dy the specified region.
1515
To reduce a region by a specified amount, use
1516
<function>XShrinkRegion</function>.
1517
<indexterm significance="preferred"><primary>XShrinkRegion</primary></indexterm>
1521
<funcdef><function>XShrinkRegion</function></funcdef>
1522
<paramdef>Region<parameter> r</parameter></paramdef>
1523
<paramdef>intdx,<parameter> dy</parameter></paramdef>
1530
<emphasis remap='I'>r</emphasis>
1534
Specifies the region.
1535
<!-- .ds Dy shrink -->
1541
<emphasis remap='I'>dx</emphasis>
1552
<emphasis remap='I'>dy</emphasis>
1556
Specify the x and y coordinates,
1557
which define the amount you want to (Dy the specified region.
1566
Positive values shrink the size of the region,
1567
and negative values expand the region.
1570
<sect2 id="Computing_with_Regions">
1571
<title>Computing with Regions</title>
1573
<!-- (SN Computing with Regions -->
1578
To generate the smallest rectangle enclosing a region, use
1579
<function>XClipBox</function>.
1580
<indexterm significance="preferred"><primary>XClipBox</primary></indexterm>
1584
<funcdef><function>XClipBox</function></funcdef>
1585
<paramdef>Region<parameter> r</parameter></paramdef>
1586
<paramdef>XRectangle<parameter> *rect_return</parameter></paramdef>
1593
<emphasis remap='I'>r</emphasis>
1597
Specifies the region.
1603
<emphasis remap='I'>rect_return</emphasis>
1607
Returns the smallest enclosing rectangle.
1617
<function>XClipBox</function>
1618
function returns the smallest rectangle enclosing the specified region.
1623
To compute the intersection of two regions, use
1624
<function>XIntersectRegion</function>.
1625
<indexterm significance="preferred"><primary>XIntersectRegion</primary></indexterm>
1629
<funcdef><function>XIntersectRegion</function></funcdef>
1630
<paramdef>Regionsra,srb,<parameter> dr_return</parameter></paramdef>
1637
<emphasis remap='I'>sra</emphasis>
1648
<emphasis remap='I'>srb</emphasis>
1652
Specify the two regions with which you want to perform the computation.
1658
<emphasis remap='I'>dr_return</emphasis>
1662
Returns the result of the computation.
1672
To compute the union of two regions, use
1673
<function>XUnionRegion</function>.
1674
<indexterm significance="preferred"><primary>XUnionRegion</primary></indexterm>
1678
<funcdef><function>XUnionRegion</function></funcdef>
1679
<paramdef>Regionsra,srb,<parameter> dr_return</parameter></paramdef>
1686
<emphasis remap='I'>sra</emphasis>
1697
<emphasis remap='I'>srb</emphasis>
1701
Specify the two regions with which you want to perform the computation.
1707
<emphasis remap='I'>dr_return</emphasis>
1711
Returns the result of the computation.
1721
To create a union of a source region and a rectangle, use
1722
<function>XUnionRectWithRegion</function>.
1723
<indexterm significance="preferred"><primary>XUnionRectWithRegion</primary></indexterm>
1727
<funcdef><function>XUnionRectWithRegion</function></funcdef>
1728
<paramdef>XRectangle<parameter> *rectangle</parameter></paramdef>
1729
<paramdef>Region<parameter> src_region</parameter></paramdef>
1730
<paramdef>Region<parameter> dest_region_return</parameter></paramdef>
1737
<emphasis remap='I'>rectangle</emphasis>
1741
Specifies the rectangle.
1747
<emphasis remap='I'>src_region</emphasis>
1751
Specifies the source region to be used.
1757
<emphasis remap='I'>dest_region_return</emphasis>
1761
Returns the destination region.
1771
<function>XUnionRectWithRegion</function>
1772
function updates the destination region from a union of the specified rectangle
1773
and the specified source region.
1778
To subtract two regions, use
1779
<function>XSubtractRegion</function>.
1780
<indexterm significance="preferred"><primary>XSubtractRegion</primary></indexterm>
1784
<funcdef><function>XSubtractRegion</function></funcdef>
1785
<paramdef>Regionsra,srb,<parameter> dr_return</parameter></paramdef>
1792
<emphasis remap='I'>sra</emphasis>
1803
<emphasis remap='I'>srb</emphasis>
1807
Specify the two regions with which you want to perform the computation.
1813
<emphasis remap='I'>dr_return</emphasis>
1817
Returns the result of the computation.
1827
<function>XSubtractRegion</function>
1828
function subtracts srb from sra and stores the results in dr_return.
1833
To calculate the difference between the union and intersection
1835
<function>XXorRegion</function>.
1836
<indexterm significance="preferred"><primary>XXorRegion</primary></indexterm>
1840
<funcdef><function>XXorRegion</function></funcdef>
1841
<paramdef>Regionsra,srb,<parameter> dr_return</parameter></paramdef>
1848
<emphasis remap='I'>sra</emphasis>
1859
<emphasis remap='I'>srb</emphasis>
1863
Specify the two regions with which you want to perform the computation.
1869
<emphasis remap='I'>dr_return</emphasis>
1873
Returns the result of the computation.
1884
<sect2 id="Determining_if_Regions_Are_Empty_or_Equal">
1885
<title>Determining if Regions Are Empty or Equal</title>
1887
<!-- (SN Determining if Regions Are Empty or Equal -->
1891
To determine if the specified region is empty, use
1892
<function>XEmptyRegion</function>.
1893
<indexterm significance="preferred"><primary>XEmptyRegion</primary></indexterm>
1897
<funcdef>Bool <function>XEmptyRegion</function></funcdef>
1898
<paramdef>Region<parameter> r</parameter></paramdef>
1905
<emphasis remap='I'>r</emphasis>
1909
Specifies the region.
1919
<function>XEmptyRegion</function>
1921
<symbol>True</symbol>
1922
if the region is empty.
1927
To determine if two regions have the same offset, size, and shape, use
1928
<function>XEqualRegion</function>.
1929
<indexterm significance="preferred"><primary>XEqualRegion</primary></indexterm>
1933
<funcdef>Bool <function>XEqualRegion</function></funcdef>
1934
<paramdef>Regionr1,<parameter> r2</parameter></paramdef>
1941
<emphasis remap='I'>r1</emphasis>
1952
<emphasis remap='I'>r2</emphasis>
1956
Specify the two regions.
1966
<function>XEqualRegion</function>
1968
<symbol>True</symbol>
1969
if the two regions have the same offset, size, and shape.
1972
<sect2 id="Locating_a_Point_or_a_Rectangle_in_a_Region">
1973
<title>Locating a Point or a Rectangle in a Region</title>
1975
<!-- (SN Locating a Point or a Rectangle in a Region -->
1979
To determine if a specified point resides in a specified region, use
1980
<function>XPointInRegion</function>.
1981
<indexterm significance="preferred"><primary>XPointInRegion</primary></indexterm>
1985
<funcdef>Bool <function>XPointInRegion</function></funcdef>
1986
<paramdef>Region<parameter> r</parameter></paramdef>
1987
<paramdef>intx,<parameter> y</parameter></paramdef>
1994
<emphasis remap='I'>r</emphasis>
1998
Specifies the region.
1999
<!-- .ds Xy , which define the point -->
2005
<emphasis remap='I'>x</emphasis>
2016
<emphasis remap='I'>y</emphasis>
2020
Specify the x and y coordinates(Xy.
2030
<function>XPointInRegion</function>
2032
<symbol>True</symbol>
2033
if the point (x, y) is contained in the region r.
2038
To determine if a specified rectangle is inside a region, use
2039
<function>XRectInRegion</function>.
2040
<indexterm significance="preferred"><primary>XRectInRegion</primary></indexterm>
2044
<funcdef>int <function>XRectInRegion</function></funcdef>
2045
<paramdef>Region<parameter> r</parameter></paramdef>
2046
<paramdef>intx,<parameter> y</parameter></paramdef>
2047
<paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
2054
<emphasis remap='I'>r</emphasis>
2058
Specifies the region.
2059
<!-- .ds Xy , which define the coordinates of the upper-left corner of the rectangle -->
2065
<emphasis remap='I'>x</emphasis>
2076
<emphasis remap='I'>y</emphasis>
2080
Specify the x and y coordinates(Xy.
2081
<!-- .ds Wh , which define the rectangle -->
2087
<emphasis remap='I'>width</emphasis>
2098
<emphasis remap='I'>height</emphasis>
2102
Specify the width and height(Wh.
2112
<function>XRectInRegion</function>
2114
<symbol>RectangleIn</symbol>
2115
if the rectangle is entirely in the specified region,
2116
<symbol>RectangleOut</symbol>
2117
if the rectangle is entirely out of the specified region,
2119
<symbol>RectanglePart</symbol>
2120
if the rectangle is partially in the specified region.
2124
<sect1 id="Using_Cut_Buffers">
2125
<title>Using Cut Buffers</title>
2127
<!-- (SN Using Cut Buffers -->
2131
<indexterm><primary>Cut Buffers</primary></indexterm>
2132
Xlib provides functions to manipulate cut buffers,
2133
a very simple form of cut-and-paste inter-client communication.
2134
Selections are a much more powerful and useful mechanism for
2135
interchanging data between clients (see section 4.5)
2136
and generally should be used instead of cut buffers.
2140
Cut buffers are implemented as properties on the first root window
2142
The buffers can only contain text, in the STRING encoding.
2143
The text encoding is not changed by Xlib when fetching or storing.
2144
Eight buffers are provided
2145
and can be accessed as a ring or as explicit buffers (numbered 0 through 7).
2150
To store data in cut buffer 0, use
2151
<function>XStoreBytes</function>.
2152
<indexterm significance="preferred"><primary>XStoreBytes</primary></indexterm>
2156
<funcdef><function>XStoreBytes</function></funcdef>
2157
<paramdef>Display<parameter> *display</parameter></paramdef>
2158
<paramdef>char<parameter> *bytes</parameter></paramdef>
2159
<paramdef>int<parameter> nbytes</parameter></paramdef>
2166
<emphasis remap='I'>display</emphasis>
2170
Specifies the connection to the X server.
2176
<emphasis remap='I'>bytes</emphasis>
2180
Specifies the bytes, which are not necessarily ASCII or null-terminated.
2186
<emphasis remap='I'>nbytes</emphasis>
2190
Specifies the number of bytes to be stored.
2199
The data can have embedded null characters
2200
and need not be null-terminated.
2201
The cut buffer's contents can be retrieved later by
2203
<function>XFetchBytes</function>.
2207
<function>XStoreBytes</function>
2209
<errorname>BadAlloc</errorname>
2215
To store data in a specified cut buffer, use
2216
<function>XStoreBuffer</function>.
2217
<indexterm significance="preferred"><primary>XStoreBuffer</primary></indexterm>
2221
<funcdef><function>XStoreBuffer</function></funcdef>
2222
<paramdef>Display<parameter> *display</parameter></paramdef>
2223
<paramdef>char<parameter> *bytes</parameter></paramdef>
2224
<paramdef>int<parameter> nbytes</parameter></paramdef>
2225
<paramdef>int<parameter> buffer</parameter></paramdef>
2232
<emphasis remap='I'>display</emphasis>
2236
Specifies the connection to the X server.
2242
<emphasis remap='I'>bytes</emphasis>
2246
Specifies the bytes, which are not necessarily ASCII or null-terminated.
2252
<emphasis remap='I'>nbytes</emphasis>
2256
Specifies the number of bytes to be stored.
2257
<!-- .ds Fn in which you want to store the bytes -->
2263
<emphasis remap='I'>buffer</emphasis>
2267
Specifies the buffer (Fn.
2276
If an invalid buffer is specified, the call has no effect.
2277
The data can have embedded null characters
2278
and need not be null-terminated.
2282
<function>XStoreBuffer</function>
2284
<errorname>BadAlloc</errorname>
2290
To return data from cut buffer 0, use
2291
<function>XFetchBytes</function>.
2292
<indexterm significance="preferred"><primary>XFetchBytes</primary></indexterm>
2296
<funcdef>char *<function>XFetchBytes</function></funcdef>
2297
<paramdef>Display<parameter> *display</parameter></paramdef>
2298
<paramdef>int<parameter> *nbytes_return</parameter></paramdef>
2305
<emphasis remap='I'>display</emphasis>
2309
Specifies the connection to the X server.
2315
<emphasis remap='I'>nbytes_return</emphasis>
2319
Returns the number of bytes in the buffer.
2329
<function>XFetchBytes</function>
2331
returns the number of bytes in the nbytes_return argument,
2332
if the buffer contains data.
2333
Otherwise, the function
2334
returns NULL and sets nbytes to 0.
2335
The appropriate amount of storage is allocated and the pointer returned.
2336
The client must free this storage when finished with it by calling
2337
<function>XFree</function>.
2342
To return data from a specified cut buffer, use
2343
<function>XFetchBuffer</function>.
2344
<indexterm significance="preferred"><primary>XFetchBuffer</primary></indexterm>
2348
<funcdef>char *<function>XFetchBuffer</function></funcdef>
2349
<paramdef>Display<parameter> *display</parameter></paramdef>
2350
<paramdef>int<parameter> *nbytes_return</parameter></paramdef>
2351
<paramdef>int<parameter> buffer</parameter></paramdef>
2358
<emphasis remap='I'>display</emphasis>
2362
Specifies the connection to the X server.
2368
<emphasis remap='I'>nbytes_return</emphasis>
2372
Returns the number of bytes in the buffer.
2373
<!-- .ds Fn from which you want the stored data returned -->
2379
<emphasis remap='I'>buffer</emphasis>
2383
Specifies the buffer (Fn.
2393
<function>XFetchBuffer</function>
2394
function returns zero to the nbytes_return argument
2395
if there is no data in the buffer or if an invalid
2396
buffer is specified.
2401
To rotate the cut buffers, use
2402
<function>XRotateBuffers</function>.
2403
<indexterm significance="preferred"><primary>XRotateBuffers</primary></indexterm>
2407
<funcdef><function>XRotateBuffers</function></funcdef>
2408
<paramdef>Display<parameter> *display</parameter></paramdef>
2409
<paramdef>int<parameter> rotate</parameter></paramdef>
2416
<emphasis remap='I'>display</emphasis>
2420
Specifies the connection to the X server.
2426
<emphasis remap='I'>rotate</emphasis>
2430
Specifies how much to rotate the cut buffers.
2440
<function>XRotateBuffers</function>
2441
function rotates the cut
2442
buffers, such that buffer 0 becomes buffer n,
2443
buffer 1 becomes n + 1 mod 8, and so on.
2444
This cut buffer numbering is global to the display.
2446
<function>XRotateBuffers</function>
2448
<errorname>BadMatch</errorname>
2449
errors if any of the eight buffers have not been created.
2452
<sect1 id="Determining_the_Appropriate_Visual_Type">
2453
<title>Determining the Appropriate Visual Type</title>
2455
<!-- (SN Determining the Appropriate Visual Type -->
2459
A single display can support multiple screens.
2460
Each screen can have several different visual types supported
2461
at different depths.
2462
You can use the functions described in this section to determine
2463
which visual to use for your application.
2467
The functions in this section use the visual information masks and the
2468
<structname>XVisualInfo</structname>
2471
<filename class="headerfile"><X11/Xutil.h></filename>
2472
<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
2473
<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
2474
<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
2479
<literallayout class="monospaced">
2481
/* Visual information mask bits */
2484
#define VisualNoMask 0x0
2485
#define VisualIDMask 0x1
2486
#define VisualScreenMask 0x2
2487
#define VisualDepthMask 0x4
2488
#define VisualClassMask 0x8
2489
#define VisualRedMaskMask 0x10
2490
#define VisualGreenMaskMask 0x20
2491
#define VisualBlueMaskMask 0x40
2492
#define VisualColormapSizeMask 0x80
2493
#define VisualBitsPerRGBMask 0x100
2494
#define VisualAllMask 0x1FF
2498
<literallayout class="monospaced">
2509
unsigned long red_mask;
2510
unsigned long green_mask;
2511
unsigned long blue_mask;
2520
To obtain a list of visual information structures that match a specified
2522
<function>XGetVisualInfo</function>.
2523
<indexterm significance="preferred"><primary>XGetVisualInfo</primary></indexterm>
2527
<funcdef>XVisualInfo *<function>XGetVisualInfo</function></funcdef>
2528
<paramdef>Display<parameter> *display</parameter></paramdef>
2529
<paramdef>long<parameter> vinfo_mask</parameter></paramdef>
2530
<paramdef>XVisualInfo<parameter> *vinfo_template</parameter></paramdef>
2531
<paramdef>int<parameter> *nitems_return</parameter></paramdef>
2538
<emphasis remap='I'>display</emphasis>
2542
Specifies the connection to the X server.
2548
<emphasis remap='I'>vinfo_mask</emphasis>
2552
Specifies the visual mask value.
2558
<emphasis remap='I'>vinfo_template</emphasis>
2562
Specifies the visual attributes that are to be used in matching the visual
2569
<emphasis remap='I'>nitems_return</emphasis>
2573
Returns the number of matching visual structures.
2583
<function>XGetVisualInfo</function>
2584
function returns a list of visual structures that have attributes
2585
equal to the attributes specified by vinfo_template.
2586
If no visual structures match the template using the specified vinfo_mask,
2587
<function>XGetVisualInfo</function>
2589
To free the data returned by this function, use
2590
<function>XFree</function>.
2595
To obtain the visual information that matches the specified depth and
2596
class of the screen, use
2597
<function>XMatchVisualInfo</function>.
2598
<indexterm significance="preferred"><primary>XMatchVisualInfo</primary></indexterm>
2602
<funcdef>Status <function>XMatchVisualInfo</function></funcdef>
2603
<paramdef>Display<parameter> *display</parameter></paramdef>
2604
<paramdef>int<parameter> screen</parameter></paramdef>
2605
<paramdef>int<parameter> depth</parameter></paramdef>
2606
<paramdef>int<parameter> class</parameter></paramdef>
2607
<paramdef>XVisualInfo<parameter> *vinfo_return</parameter></paramdef>
2614
<emphasis remap='I'>display</emphasis>
2618
Specifies the connection to the X server.
2624
<emphasis remap='I'>screen</emphasis>
2628
Specifies the screen.
2634
<emphasis remap='I'>depth</emphasis>
2638
Specifies the depth of the screen.
2644
<emphasis remap='I'>class</emphasis>
2648
Specifies the class of the screen.
2654
<emphasis remap='I'>vinfo_return</emphasis>
2658
Returns the matched visual information.
2668
<function>XMatchVisualInfo</function>
2669
function returns the visual information for a visual that matches the specified
2670
depth and class for a screen.
2671
Because multiple visuals that match the specified depth and class can exist,
2672
the exact visual chosen is undefined.
2673
If a visual is found,
2674
<function>XMatchVisualInfo</function>
2675
returns nonzero and the information on the visual to vinfo_return.
2676
Otherwise, when a visual is not found,
2677
<function>XMatchVisualInfo</function>
2681
<sect1 id="Manipulating_Images">
2682
<title>Manipulating Images</title>
2684
<!-- (SN Manipulating Images -->
2688
Xlib provides several functions that perform basic operations on images.
2689
All operations on images are defined using an
2690
<structname>XImage</structname>
2693
<filename class="headerfile"><X11/Xlib.h></filename>.
2694
<indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm>
2695
<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm>
2696
<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm>
2697
Because the number of different types of image formats can be very large,
2698
this hides details of image storage properly from applications.
2702
This section describes the functions for generic operations on images.
2703
Manufacturers can provide very fast implementations of these for the
2704
formats frequently encountered on their hardware.
2705
These functions are neither sufficient nor desirable to use for general image
2707
Rather, they are here to provide minimal functions on screen format
2709
The basic operations for getting and putting images are
2710
<function>XGetImage</function>
2712
<function>XPutImage</function>.
2716
Note that no functions have been defined, as yet, to read and write images
2717
to and from disk files.
2722
<structname>XImage</structname>
2723
structure describes an image as it exists in the client's memory.
2724
The user can request that some of the members such as height, width,
2725
and xoffset be changed when the image is sent to the server.
2726
Note that bytes_per_line in concert with offset can be used to
2727
extract a subset of the image.
2728
Other members (for example, byte order, bitmap_unit, and so forth)
2729
are characteristics of both the image and the server.
2731
differ between the image and the server,
2732
<function>XPutImage</function>
2733
makes the appropriate conversions.
2734
The first byte of the first line of
2735
plane n must be located at the address (data + (n * height * bytes_per_line)).
2736
For a description of the
2737
<structname>XImage</structname>
2745
<structname>XImage</structname>
2746
structure and initialize it with image format values from a display, use
2747
<function>XCreateImage</function>.
2748
<indexterm significance="preferred"><primary>XCreateImage</primary></indexterm>
2752
<funcdef>XImage *<function>XCreateImage</function></funcdef>
2753
<paramdef>Display<parameter> *display</parameter></paramdef>
2754
<paramdef>Visual<parameter> *visual</parameter></paramdef>
2755
<paramdef>unsignedint<parameter> depth</parameter></paramdef>
2756
<paramdef>int<parameter> format</parameter></paramdef>
2757
<paramdef>int<parameter> offset</parameter></paramdef>
2758
<paramdef>char<parameter> *data</parameter></paramdef>
2759
<paramdef>unsignedint<parameter> width</parameter></paramdef>
2760
<paramdef>unsignedint<parameter> height</parameter></paramdef>
2761
<paramdef>int<parameter> bitmap_pad</parameter></paramdef>
2762
<paramdef>int<parameter> bytes_per_line</parameter></paramdef>
2769
<emphasis remap='I'>display</emphasis>
2773
Specifies the connection to the X server.
2779
<emphasis remap='I'>visual</emphasis>
2784
<structname>Visual</structname>
2791
<emphasis remap='I'>depth</emphasis>
2795
Specifies the depth of the image.
2801
<emphasis remap='I'>format</emphasis>
2805
Specifies the format for the image.
2807
<symbol>XYBitmap</symbol>,
2808
<symbol>XYPixmap</symbol>,
2810
<symbol>ZPixmap</symbol>.
2816
<emphasis remap='I'>offset</emphasis>
2820
Specifies the number of pixels to ignore at the beginning of the scanline.
2826
<emphasis remap='I'>data</emphasis>
2830
Specifies the image data.
2836
<emphasis remap='I'>width</emphasis>
2840
Specifies the width of the image, in pixels.
2846
<emphasis remap='I'>height</emphasis>
2850
Specifies the height of the image, in pixels.
2856
<emphasis remap='I'>bitmap_pad</emphasis>
2860
Specifies the quantum of a scanline (8, 16, or 32).
2861
In other words, the start of one scanline is separated in client memory from
2862
the start of the next scanline by an integer multiple of this many bits.
2868
<emphasis remap='I'>bytes_per_line</emphasis>
2872
Specifies the number of bytes in the client image between
2873
the start of one scanline and the start of the next.
2883
<function>XCreateImage</function>
2884
function allocates the memory needed for an
2885
<structname>XImage</structname>
2887
specified display but does not allocate space for the image itself.
2888
Rather, it initializes the structure byte-order, bit-order, and bitmap-unit
2889
values from the display and returns a pointer to the
2890
<structname>XImage</structname>
2892
The red, green, and blue mask values are defined for Z format images only
2893
and are derived from the
2894
<structname>Visual</structname>
2895
structure passed in.
2896
Other values also are passed in.
2897
The offset permits the rapid displaying of the image without requiring each
2898
scanline to be shifted into position.
2899
If you pass a zero value in bytes_per_line,
2900
Xlib assumes that the scanlines are contiguous
2901
in memory and calculates the value of bytes_per_line itself.
2905
Note that when the image is created using
2906
<function>XCreateImage</function>,
2907
<function>XGetImage</function>,
2909
<function>XSubImage</function>,
2910
the destroy procedure that the
2911
<function>XDestroyImage</function>
2912
function calls frees both the image structure
2913
and the data pointed to by the image structure.
2917
The basic functions used to get a pixel, set a pixel, create a subimage,
2918
and add a constant value to an image are defined in the image object.
2919
The functions in this section are really macro invocations of the functions
2920
in the image object and are defined in
2921
<filename class="headerfile"><X11/Xutil.h></filename>.
2922
<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
2923
<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
2924
<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
2929
To obtain a pixel value in an image, use
2930
<function>XGetPixel</function>.
2931
<indexterm significance="preferred"><primary>XGetPixel</primary></indexterm>
2935
<funcdef>unsigned long <function>XGetPixel</function></funcdef>
2936
<paramdef>XImage<parameter> *ximage</parameter></paramdef>
2937
<paramdef>int<parameter> x</parameter></paramdef>
2938
<paramdef>int<parameter> y</parameter></paramdef>
2945
<emphasis remap='I'>ximage</emphasis>
2949
Specifies the image.
2955
<emphasis remap='I'>x</emphasis>
2966
<emphasis remap='I'>y</emphasis>
2970
Specify the x and y coordinates.
2980
<function>XGetPixel</function>
2981
function returns the specified pixel from the named image.
2982
The pixel value is returned in normalized format (that is,
2983
the least significant byte of the long is the least significant byte
2985
The image must contain the x and y coordinates.
2990
To set a pixel value in an image, use
2991
<function>XPutPixel</function>.
2992
<indexterm significance="preferred"><primary>XPutPixel</primary></indexterm>
2996
<funcdef><function>XPutPixel</function></funcdef>
2997
<paramdef>XImage<parameter> *ximage</parameter></paramdef>
2998
<paramdef>int<parameter> x</parameter></paramdef>
2999
<paramdef>int<parameter> y</parameter></paramdef>
3000
<paramdef>unsignedlong<parameter> pixel</parameter></paramdef>
3007
<emphasis remap='I'>ximage</emphasis>
3011
Specifies the image.
3017
<emphasis remap='I'>x</emphasis>
3028
<emphasis remap='I'>y</emphasis>
3032
Specify the x and y coordinates.
3038
<emphasis remap='I'>pixel</emphasis>
3042
Specifies the new pixel value.
3052
<function>XPutPixel</function>
3053
function overwrites the pixel in the named image with the specified pixel value.
3054
The input pixel value must be in normalized format
3055
(that is, the least significant byte of the long is the least significant
3057
The image must contain the x and y coordinates.
3062
To create a subimage, use
3063
<function>XSubImage</function>.
3064
<indexterm significance="preferred"><primary>XSubImage</primary></indexterm>
3068
<funcdef>XImage *<function>XSubImage</function></funcdef>
3069
<paramdef>XImage<parameter> *ximage</parameter></paramdef>
3070
<paramdef>int<parameter> x</parameter></paramdef>
3071
<paramdef>int<parameter> y</parameter></paramdef>
3072
<paramdef>unsignedint<parameter> subimage_width</parameter></paramdef>
3073
<paramdef>unsignedint<parameter> subimage_height</parameter></paramdef>
3080
<emphasis remap='I'>ximage</emphasis>
3084
Specifies the image.
3090
<emphasis remap='I'>x</emphasis>
3101
<emphasis remap='I'>y</emphasis>
3105
Specify the x and y coordinates.
3111
<emphasis remap='I'>subimage_width</emphasis>
3115
Specifies the width of the new subimage, in pixels.
3121
<emphasis remap='I'>subimage_height</emphasis>
3125
Specifies the height of the new subimage, in pixels.
3135
<function>XSubImage</function>
3136
function creates a new image that is a subsection of an existing one.
3137
It allocates the memory necessary for the new
3138
<structname>XImage</structname>
3140
and returns a pointer to the new image.
3141
The data is copied from the source image,
3142
and the image must contain the rectangle defined by x, y, subimage_width,
3143
and subimage_height.
3148
To increment each pixel in an image by a constant value, use
3149
<function>XAddPixel</function>.
3150
<indexterm significance="preferred"><primary>XAddPixel</primary></indexterm>
3154
<funcdef><function>XAddPixel</function></funcdef>
3155
<paramdef>XImage<parameter> *ximage</parameter></paramdef>
3156
<paramdef>long<parameter> value</parameter></paramdef>
3163
<emphasis remap='I'>ximage</emphasis>
3167
Specifies the image.
3173
<emphasis remap='I'>value</emphasis>
3177
Specifies the constant value that is to be added.
3187
<function>XAddPixel</function>
3188
function adds a constant value to every pixel in an image.
3189
It is useful when you have a base pixel value from allocating
3190
color resources and need to manipulate the image to that form.
3195
To deallocate the memory allocated in a previous call to
3196
<function>XCreateImage</function>,
3198
<function>XDestroyImage</function>.
3199
<indexterm significance="preferred"><primary>XDestroyImage</primary></indexterm>
3203
<funcdef><function>XDestroyImage</function></funcdef>
3204
<paramdef>XImage *<parameter>ximage</parameter></paramdef>
3211
<emphasis remap='I'>ximage</emphasis>
3215
Specifies the image.
3225
<function>XDestroyImage</function>
3226
function deallocates the memory associated with the
3227
<structname>XImage</structname>
3232
Note that when the image is created using
3233
<function>XCreateImage</function>,
3234
<function>XGetImage</function>,
3236
<function>XSubImage</function>,
3237
the destroy procedure that this macro calls
3238
frees both the image structure and the data pointed to by the image structure.
3241
<sect1 id="Manipulating_Bitmaps">
3242
<title>Manipulating Bitmaps</title>
3244
<!-- (SN Manipulating Bitmaps -->
3248
Xlib provides functions that you can use to read a bitmap from a file,
3249
save a bitmap to a file, or create a bitmap.
3250
This section describes those functions that transfer bitmaps to and
3251
from the client's file system, thus allowing their reuse in a later
3252
connection (for example, from an entirely different client or to a
3253
different display or server).
3257
The X version 11 bitmap file format is:
3262
<literallayout class="monospaced">
3263
#define <emphasis remap='I'>name</emphasis>_width <emphasis remap='I'>width</emphasis>
3264
#define <emphasis remap='I'>name</emphasis>_height <emphasis remap='I'>height</emphasis>
3265
#define <emphasis remap='I'>name</emphasis>_x_hot <emphasis remap='I'>x</emphasis>
3266
#define <emphasis remap='I'>name</emphasis>_y_hot <emphasis remap='I'>y</emphasis>
3267
static unsigned char <emphasis remap='I'>name</emphasis>_bits[] = { 0x<emphasis remap='I'>NN</emphasis>,... }
3273
The lines for the variables ending with _x_hot and _y_hot suffixes are optional
3274
because they are present only if a hotspot has been defined for this bitmap.
3275
The lines for the other variables are required.
3276
The word ``unsigned'' is optional;
3277
that is, the type of the _bits array can be ``char'' or ``unsigned char''.
3278
The _bits array must be large enough to contain the size bitmap.
3279
The bitmap unit is 8.
3284
To read a bitmap from a file and store it in a pixmap, use
3285
<function>XReadBitmapFile</function>.
3286
<indexterm significance="preferred"><primary>XReadBitmapFile</primary></indexterm>
3290
<funcdef>int <function>XReadBitmapFile</function></funcdef>
3291
<paramdef>Display<parameter> *display</parameter></paramdef>
3292
<paramdef>Drawable<parameter> d</parameter></paramdef>
3293
<paramdef>char<parameter> *filename</parameter></paramdef>
3294
<paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
3295
<paramdef>Pixmap<parameter> *bitmap_return</parameter></paramdef>
3296
<paramdef>int*x_hot_return,<parameter> *y_hot_return</parameter></paramdef>
3303
<emphasis remap='I'>display</emphasis>
3307
Specifies the connection to the X server.
3308
<!-- .ds Dr \ that indicates the screen -->
3314
<emphasis remap='I'>d</emphasis>
3318
Specifies the drawable(Dr.
3324
<emphasis remap='I'>filename</emphasis>
3328
Specifies the file name to use.
3329
The format of the file name is operating-system dependent.
3335
<emphasis remap='I'>width_return</emphasis>
3346
<emphasis remap='I'>height_return</emphasis>
3350
Return the width and height values of the read in bitmap file.
3356
<emphasis remap='I'>bitmap_return</emphasis>
3360
Returns the bitmap that is created.
3366
<emphasis remap='I'>x_hot_return</emphasis>
3377
<emphasis remap='I'>y_hot_return</emphasis>
3381
Return the hotspot coordinates.
3391
<function>XReadBitmapFile</function>
3392
function reads in a file containing a bitmap.
3393
The file is parsed in the encoding of the current locale.
3394
The ability to read other than the standard format
3395
is implementation-dependent.
3396
If the file cannot be opened,
3397
<function>XReadBitmapFile</function>
3399
<returnvalue>BitmapOpenFailed</returnvalue>.
3400
If the file can be opened but does not contain valid bitmap data,
3402
<returnvalue>BitmapFileInvalid</returnvalue>.
3403
If insufficient working storage is allocated,
3405
<returnvalue>BitmapNoMemory</returnvalue>.
3406
If the file is readable and valid,
3408
<returnvalue>BitmapSuccess</returnvalue>.
3412
<function>XReadBitmapFile</function>
3413
returns the bitmap's height and width, as read
3414
from the file, to width_return and height_return.
3415
It then creates a pixmap of the appropriate size,
3416
reads the bitmap data from the file into the pixmap,
3417
and assigns the pixmap to the caller's variable bitmap.
3418
The caller must free the bitmap using
3419
<function>XFreePixmap</function>
3421
If <emphasis remap='I'>name</emphasis>_x_hot and <emphasis remap='I'>name</emphasis>_y_hot exist,
3422
<function>XReadBitmapFile</function>
3423
returns them to x_hot_return and y_hot_return;
3424
otherwise, it returns −1,−1.
3428
<function>XReadBitmapFile</function>
3430
<errorname>BadAlloc</errorname>,
3431
<errorname>BadDrawable</errorname>,
3433
<errorname>BadGC</errorname>
3439
To read a bitmap from a file and return it as data, use
3440
<function>XReadBitmapFileData</function>.
3441
<indexterm significance="preferred"><primary>XReadBitmapFileData</primary></indexterm>
3445
<funcdef>int <function>XReadBitmapFileData</function></funcdef>
3446
<paramdef>char<parameter> *filename</parameter></paramdef>
3447
<paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
3448
<paramdef>unsignedchar<parameter> *data_return</parameter></paramdef>
3449
<paramdef>int*x_hot_return,<parameter> *y_hot_return</parameter></paramdef>
3456
<emphasis remap='I'>filename</emphasis>
3460
Specifies the file name to use.
3461
The format of the file name is operating-system dependent.
3467
<emphasis remap='I'>width_return</emphasis>
3478
<emphasis remap='I'>height_return</emphasis>
3482
Return the width and height values of the read in bitmap file.
3488
<emphasis remap='I'>data_return</emphasis>
3492
Returns the bitmap data.
3498
<emphasis remap='I'>x_hot_return</emphasis>
3509
<emphasis remap='I'>y_hot_return</emphasis>
3513
Return the hotspot coordinates.
3523
<function>XReadBitmapFileData</function>
3524
function reads in a file containing a bitmap, in the same manner as
3525
<function>XReadBitmapFile</function>,
3526
but returns the data directly rather than creating a pixmap in the server.
3527
The bitmap data is returned in data_return; the client must free this
3528
storage when finished with it by calling
3529
<function>XFree</function>.
3530
The status and other return values are the same as for
3531
<function>XReadBitmapFile</function>.
3536
To write out a bitmap from a pixmap to a file, use
3537
<function>XWriteBitmapFile</function>.
3538
<indexterm significance="preferred"><primary>XWriteBitmapFile</primary></indexterm>
3542
<funcdef>int <function>XWriteBitmapFile</function></funcdef>
3543
<paramdef>Display<parameter> *display</parameter></paramdef>
3544
<paramdef>char<parameter> *filename</parameter></paramdef>
3545
<paramdef>Pixmap<parameter> bitmap</parameter></paramdef>
3546
<paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
3547
<paramdef>intx_hot,<parameter> y_hot</parameter></paramdef>
3554
<emphasis remap='I'>display</emphasis>
3558
Specifies the connection to the X server.
3564
<emphasis remap='I'>filename</emphasis>
3568
Specifies the file name to use.
3569
The format of the file name is operating-system dependent.
3575
<emphasis remap='I'>bitmap</emphasis>
3579
Specifies the bitmap.
3585
<emphasis remap='I'>width</emphasis>
3596
<emphasis remap='I'>height</emphasis>
3600
Specify the width and height.
3606
<emphasis remap='I'>x_hot</emphasis>
3617
<emphasis remap='I'>y_hot</emphasis>
3621
Specify where to place the hotspot coordinates (or −1,−1 if none are present)
3632
<function>XWriteBitmapFile</function>
3633
function writes a bitmap out to a file in the X Version 11 format.
3634
The name used in the output file is derived from the file name
3635
by deleting the directory prefix.
3636
The file is written in the encoding of the current locale.
3637
If the file cannot be opened for writing,
3639
<returnvalue>BitmapOpenFailed</returnvalue>.
3640
If insufficient memory is allocated,
3641
<function>XWriteBitmapFile</function>
3643
<returnvalue>BitmapNoMemory</returnvalue>;
3644
otherwise, on no error,
3646
<returnvalue>BitmapSuccess</returnvalue>.
3647
If x_hot and y_hot are not −1, −1,
3648
<function>XWriteBitmapFile</function>
3649
writes them out as the hotspot coordinates for the bitmap.
3653
<function>XWriteBitmapFile</function>
3655
<errorname>BadDrawable</errorname>
3657
<errorname>BadMatch</errorname>
3663
To create a pixmap and then store bitmap-format data into it, use
3664
<function>XCreatePixmapFromBitmapData</function>.
3665
<indexterm significance="preferred"><primary>XCreatePixmapFromBitmapData</primary></indexterm>
3669
<funcdef>Pixmap <function>XCreatePixmapFromBitmapData</function></funcdef>
3670
<paramdef>Display<parameter> *display</parameter></paramdef>
3671
<paramdef>Drawable<parameter> d</parameter></paramdef>
3672
<paramdef>char<parameter> *data</parameter></paramdef>
3673
<paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
3674
<paramdef>unsignedlongfg,<parameter> bg</parameter></paramdef>
3675
<paramdef>unsignedint<parameter> depth</parameter></paramdef>
3682
<emphasis remap='I'>display</emphasis>
3686
Specifies the connection to the X server.
3687
<!-- .ds Dr \ that indicates the screen -->
3693
<emphasis remap='I'>d</emphasis>
3697
Specifies the drawable(Dr.
3703
<emphasis remap='I'>data</emphasis>
3707
Specifies the data in bitmap format.
3713
<emphasis remap='I'>width</emphasis>
3724
<emphasis remap='I'>height</emphasis>
3728
Specify the width and height.
3734
<emphasis remap='I'>fg</emphasis>
3745
<emphasis remap='I'>bg</emphasis>
3749
Specify the foreground and background pixel values to use.
3755
<emphasis remap='I'>depth</emphasis>
3759
Specifies the depth of the pixmap.
3769
<function>XCreatePixmapFromBitmapData</function>
3770
function creates a pixmap of the given depth and then does a bitmap-format
3771
<function>XPutImage</function>
3772
of the data into it.
3773
The depth must be supported by the screen of the specified drawable,
3775
<errorname>BadMatch</errorname>
3780
<function>XCreatePixmapFromBitmapData</function>
3782
<errorname>BadAlloc</errorname>,
3783
<errorname>BadDrawable</errorname>,
3784
<errorname>BadGC</errorname>,
3786
<errorname>BadValue</errorname>
3792
To include a bitmap written out by
3793
<function>XWriteBitmapFile</function>
3794
<indexterm><primary>XWriteBitmapFile</primary></indexterm>
3795
in a program directly, as opposed to reading it in every time at run time, use
3796
<function>XCreateBitmapFromData</function>.
3797
<indexterm significance="preferred"><primary>XCreateBitmapFromData</primary></indexterm>
3801
<funcdef>Pixmap <function>XCreateBitmapFromData</function></funcdef>
3802
<paramdef>Display<parameter> *display</parameter></paramdef>
3803
<paramdef>Drawable<parameter> d</parameter></paramdef>
3804
<paramdef>char<parameter> *data</parameter></paramdef>
3805
<paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
3812
<emphasis remap='I'>display</emphasis>
3816
Specifies the connection to the X server.
3817
<!-- .ds Dr \ that indicates the screen -->
3823
<emphasis remap='I'>d</emphasis>
3827
Specifies the drawable(Dr.
3833
<emphasis remap='I'>data</emphasis>
3837
Specifies the location of the bitmap data.
3843
<emphasis remap='I'>width</emphasis>
3854
<emphasis remap='I'>height</emphasis>
3858
Specify the width and height.
3868
<function>XCreateBitmapFromData</function>
3869
function allows you to include in your C program (using
3870
<code>#include</code>)
3871
a bitmap file that was written out by
3872
<function>XWriteBitmapFile</function>
3873
(X version 11 format only) without reading in the bitmap file.
3874
The following example creates a gray bitmap:
3878
<literallayout class="monospaced">
3879
#include "gray.bitmap"
3882
bitmap = XCreateBitmapFromData(display, window, gray_bits, gray_width, gray_height);
3887
If insufficient working storage was allocated,
3888
<function>XCreateBitmapFromData</function>
3890
<symbol>None</symbol>.
3891
It is your responsibility to free the
3893
<function>XFreePixmap</function>
3898
<function>XCreateBitmapFromData</function>
3900
<errorname>BadAlloc</errorname>
3902
<errorname>BadGC</errorname>
3906
<sect1 id="Using_the_Context_Manager">
3907
<title>Using the Context Manager</title>
3909
<!-- (SN Using the Context Manager -->
3913
The context manager provides a way of associating data with an X resource ID
3914
(mostly typically a window) in your program.
3915
Note that this is local to your program;
3916
the data is not stored in the server on a property list.
3917
Any amount of data in any number of pieces can be associated with a
3919
and each piece of data has a type associated with it.
3920
The context manager requires knowledge of the resource ID
3921
and type to store or retrieve data.
3925
Essentially, the context manager can be viewed as a two-dimensional,
3926
sparse array: one dimension is subscripted by the X resource ID
3927
and the other by a context type field.
3928
Each entry in the array contains a pointer to the data.
3929
Xlib provides context management functions with which you can
3930
save data values, get data values, delete entries, and create a unique
3932
The symbols used are in
3933
<filename class="headerfile"><X11/Xutil.h></filename>.
3934
<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
3935
<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
3936
<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
3941
To save a data value that corresponds to a resource ID and context type, use
3942
<function>XSaveContext</function>.
3943
<indexterm significance="preferred"><primary>XSaveContext</primary></indexterm>
3947
<funcdef>int <function>XSaveContext</function></funcdef>
3948
<paramdef>Display<parameter> *display</parameter></paramdef>
3949
<paramdef>XID<parameter> rid</parameter></paramdef>
3950
<paramdef>XContext<parameter> context</parameter></paramdef>
3951
<paramdef>XPointer<parameter> data</parameter></paramdef>
3958
<emphasis remap='I'>display</emphasis>
3962
Specifies the connection to the X server.
3968
<emphasis remap='I'>rid</emphasis>
3972
Specifies the resource ID with which the data is associated.
3978
<emphasis remap='I'>context</emphasis>
3982
Specifies the context type to which the data belongs.
3988
<emphasis remap='I'>data</emphasis>
3992
Specifies the data to be associated with the window and type.
4001
If an entry with the specified resource ID and type already exists,
4002
<function>XSaveContext</function>
4003
overrides it with the specified context.
4005
<function>XSaveContext</function>
4006
function returns a nonzero error code if an error has occurred
4009
<symbol>XCNOMEM</symbol>
4015
To get the data associated with a resource ID and type, use
4016
<function>XFindContext</function>.
4017
<indexterm significance="preferred"><primary>XFindContext</primary></indexterm>
4021
<funcdef>int <function>XFindContext</function></funcdef>
4022
<paramdef>Display<parameter> *display</parameter></paramdef>
4023
<paramdef>XID<parameter> rid</parameter></paramdef>
4024
<paramdef>XContext<parameter> context</parameter></paramdef>
4025
<paramdef>XPointer<parameter> *data_return</parameter></paramdef>
4032
<emphasis remap='I'>display</emphasis>
4036
Specifies the connection to the X server.
4042
<emphasis remap='I'>rid</emphasis>
4046
Specifies the resource ID with which the data is associated.
4052
<emphasis remap='I'>context</emphasis>
4056
Specifies the context type to which the data belongs.
4062
<emphasis remap='I'>data_return</emphasis>
4075
Because it is a return value,
4076
the data is a pointer.
4078
<function>XFindContext</function>
4079
function returns a nonzero error code if an error has occurred
4082
<symbol>XCNOENT</symbol>
4083
(context-not-found).
4088
To delete an entry for a given resource ID and type, use
4089
<function>XDeleteContext</function>.
4090
<indexterm significance="preferred"><primary>XDeleteContext</primary></indexterm>
4094
<funcdef>int <function>XDeleteContext</function></funcdef>
4095
<paramdef>Display<parameter> *display</parameter></paramdef>
4096
<paramdef>XID<parameter> rid</parameter></paramdef>
4097
<paramdef>XContext<parameter> context</parameter></paramdef>
4104
<emphasis remap='I'>display</emphasis>
4108
Specifies the connection to the X server.
4114
<emphasis remap='I'>rid</emphasis>
4118
Specifies the resource ID with which the data is associated.
4124
<emphasis remap='I'>context</emphasis>
4128
Specifies the context type to which the data belongs.
4138
<function>XDeleteContext</function>
4139
function deletes the entry for the given resource ID
4140
and type from the data structure.
4141
This function returns the same error codes that
4142
<function>XFindContext</function>
4143
returns if called with the same arguments.
4144
<function>XDeleteContext</function>
4145
does not free the data whose address was saved.
4150
To create a unique context type that may be used in subsequent calls to
4151
<function>XSaveContext</function>
4153
<function>XFindContext</function>,
4155
<function>XUniqueContext</function>.
4157
<para>XContext XuniqueContext()</para>
added
removed
specs/libX11/CH16.xml
