1
.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
3
.\" Permission is hereby granted, free of charge, to any person obtaining
4
.\" a copy of this software and associated documentation files (the
5
.\" "Software"), to deal in the Software without restriction, including
6
.\" without limitation the rights to use, copy, modify, merge, publish,
7
.\" distribute, sublicense, and/or sell copies of the Software, and to
8
.\" permit persons to whom the Software is furnished to do so, subject to
9
.\" the following conditions:
11
.\" The above copyright notice and this permission notice shall be included
12
.\" in all copies or substantial portions of the Software.
14
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
15
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
17
.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
18
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
19
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
20
.\" OTHER DEALINGS IN THE SOFTWARE.
22
.\" Except as contained in this notice, the name of the X Consortium shall
23
.\" not be used in advertising or otherwise to promote the sale, use or
24
.\" other dealings in this Software without prior written authorization
25
.\" from the X Consortium.
27
.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
28
.\" Digital Equipment Corporation
30
.\" Portions Copyright \(co 1990, 1991 by
33
.\" Permission to use, copy, modify and distribute this documentation for
34
.\" any purpose and without fee is hereby granted, provided that the above
35
.\" copyright notice appears in all copies and that both that copyright notice
36
.\" and this permission notice appear in all copies, and that the names of
37
.\" Digital and Tektronix not be used in in advertising or publicity pertaining
38
.\" to this documentation without specific, written prior permission.
39
.\" Digital and Tektronix makes no representations about the suitability
40
.\" of this documentation for any purpose.
41
.\" It is provided ``as is'' without express or implied warranty.
46
\s+1\fBChapter 4\fP\s-1
48
\s+1\fBWindow Information Functions\fP\s-1
58
Chapter 4: Window Information Functions
60
After you connect the display to the X server and create a window,
61
you can use the Xlib window information functions to:
63
Obtain information about a window
65
Translate screen coordinates
67
Manipulate property lists
69
Obtain and change window properties
73
Obtaining Window Information
75
\*(SN Obtaining Window Information
78
Xlib provides functions that you can use to obtain information about
79
the window tree, the window's current attributes,
80
the window's current geometry, or the current pointer coordinates.
81
Because they are most frequently used by window managers,
82
these functions all return a status to indicate whether the window still
86
To obtain the parent, a list of children, and number of children for
91
.IN "XQueryTree" "" "@DEF@"
94
Status XQueryTree\^(\^\fIdisplay\fP, \fIw\fP\^, \fIroot_return\fP\^, \fIparent_return\fP\^, \fIchildren_return\fP\^, \fInchildren_return\fP\^)
96
Display *\fIdisplay\fP\^;
100
Window *\fIroot_return\fP\^;
102
Window *\fIparent_return\fP\^;
104
Window **\fIchildren_return\fP\^;
106
unsigned int *\fInchildren_return\fP\^;
109
Specifies the connection to the X server.
110
.ds Wi whose list of children, root, parent, and number of children \
113
Specifies the window \*(Wi.
114
.IP \fIroot_return\fP 1i
115
Returns the root window.
116
.IP \fIparent_return\fP 1i
117
Returns the parent window.
118
.IP \fIchildren_return\fP 1i
119
Returns the list of children.
120
.IP \fInchildren_return\fP 1i
121
Returns the number of children.
126
function returns the root ID, the parent window ID,
127
a pointer to the list of children windows
128
(NULL when there are no children),
129
and the number of children in the list for the specified window.
130
The children are listed in current stacking order, from bottom-most
131
(first) to top-most (last).
133
returns zero if it fails and nonzero if it succeeds.
134
To free a non-NULL children list when it is no longer needed, use
143
To obtain the current attributes of a given window, use
144
.PN XGetWindowAttributes .
145
.IN "XGetWindowAttributes" "" "@DEF@"
148
Status XGetWindowAttributes\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwindow_attributes_return\fP\^)
150
Display *\fIdisplay\fP\^;
154
XWindowAttributes *\fIwindow_attributes_return\fP\^;
157
Specifies the connection to the X server.
158
.ds Wi whose current attributes you want to obtain
160
Specifies the window \*(Wi.
161
.IP \fIwindow_attributes_return\fP 1i
162
Returns the specified window's attributes in the
163
.PN XWindowAttributes
168
.PN XGetWindowAttributes
169
function returns the current attributes for the specified window to an
170
.PN XWindowAttributes
173
.IN "XWindowAttributes" "" "@DEF@"
179
int x, y; /* location of window */
180
int width, height; /* width and height of window */
181
int border_width; /* border width of window */
182
int depth; /* depth of window */
183
Visual *visual; /* the associated visual structure */
184
Window root; /* root of screen containing window */
185
int class; /* InputOutput, InputOnly*/
186
int bit_gravity; /* one of the bit gravity values */
187
int win_gravity; /* one of the window gravity values */
188
int backing_store; /* NotUseful, WhenMapped, Always */
189
unsigned long backing_planes; /* planes to be preserved if possible */
190
unsigned long backing_pixel; /* value to be used when restoring planes */
191
Bool save_under; /* boolean, should bits under be saved? */
192
Colormap colormap; /* color map to be associated with window */
193
Bool map_installed; /* boolean, is color map currently installed*/
194
int map_state; /* IsUnmapped, IsUnviewable, IsViewable */
195
long all_event_masks; /* set of events all people have interest in*/
196
long your_event_mask; /* my event mask */
197
long do_not_propagate_mask; /* set of events that should not propagate */
198
Bool override_redirect; /* boolean value for override-redirect */
199
Screen *screen; /* back pointer to correct screen */
204
The x and y members are set to the upper-left outer
205
corner relative to the parent window's origin.
206
The width and height members are set to the inside size of the window,
207
not including the border.
208
The border_width member is set to the window's border width in pixels.
209
The depth member is set to the depth of the window
210
(that is, bits per pixel for the object).
211
The visual member is a pointer to the screen's associated
214
The root member is set to the root window of the screen containing the window.
215
The class member is set to the window's class and can be either
220
The bit_gravity member is set to the window's bit gravity
221
and can be one of the following:
253
The win_gravity member is set to the window's window gravity
254
and can be one of the following:
286
For additional information on gravity,
289
The backing_store member is set to indicate how the X server should maintain
290
the contents of a window
296
The backing_planes member is set to indicate (with bits set to 1) which bit
297
planes of the window hold dynamic data that must be preserved in backing_stores
298
and during save_unders.
299
The backing_pixel member is set to indicate what values to use
300
for planes not set in backing_planes.
302
The save_under member is set to
306
The colormap member is set to the colormap for the specified window and can be
309
The map_installed member is set to indicate whether the colormap is
310
currently installed and can be
314
The map_state member is set to indicate the state of the window and can be
320
is used if the window is mapped but some ancestor is unmapped.
322
The all_event_masks member is set to the bitwise inclusive OR of all event
323
masks selected on the window by all clients.
324
The your_event_mask member is set to the bitwise inclusive OR of all event
325
masks selected by the querying client.
326
The do_not_propagate_mask member is set to the bitwise inclusive OR of the
327
set of events that should not propagate.
329
The override_redirect member is set to indicate whether this window overrides
330
structure control facilities and can be
334
Window manager clients should ignore the window if this member is
337
The screen member is set to a screen pointer that gives you a back pointer
338
to the correct screen.
339
This makes it easier to obtain the screen information without
340
having to loop over the root window fields to see which field matches.
342
.PN XGetWindowAttributes
350
To obtain the current geometry of a given drawable, use
352
.IN "XGetGeometry" "" "@DEF@"
355
Status XGetGeometry\^(\^\fIdisplay\fP, \fId\fP\^, \^\fIroot_return\fP\^, \fIx_return\fP\^, \fIy_return\fP\^, \fIwidth_return\fP\^,
357
\fIheight_return\fP\^, \fIborder_width_return\fP\^, \fIdepth_return\fP\^)
359
Display *\fIdisplay\fP\^;
363
Window *\fIroot_return\fP\^;
365
int *\fIx_return\fP\^, *\fIy_return\fP\^;
367
unsigned int *\fIwidth_return\fP\^, *\fIheight_return\fP\^;
369
unsigned int *\fIborder_width_return\fP\^;
371
unsigned int *\fIdepth_return\fP\^;
374
Specifies the connection to the X server.
375
.ds Dr , which can be a window or a pixmap
377
Specifies the drawable\*(Dr.
378
.IP \fIroot_return\fP 1i
379
Returns the root window.
380
.IP \fIx_return\fP 1i
383
.IP \fIy_return\fP 1i
384
Return the x and y coordinates that define the location of the drawable.
386
these coordinates specify the upper-left outer corner relative to
388
For pixmaps, these coordinates are always zero.
389
.IP \fIwidth_return\fP 1i
392
.IP \fIheight_return\fP 1i
393
Return the drawable's dimensions (width and height).
395
these dimensions specify the inside size, not including the border.
396
.IP \fIborder_width_return\fP 1i
397
Returns the border width in pixels.
398
If the drawable is a pixmap, it returns zero.
399
.IP \fIdepth_return\fP 1i
400
Returns the depth of the drawable (bits per pixel for the object).
405
function returns the root window and the current geometry of the drawable.
406
The geometry of the drawable includes the x and y coordinates, width and height,
407
border width, and depth.
408
These are described in the argument list.
409
It is legal to pass to this function a window whose class is
417
Translating Screen Coordinates
419
\*(SN Translating Screen Coordinates
422
Applications sometimes
423
need to perform a coordinate transformation from the coordinate
424
space of one window to another window or need to determine which
425
window the pointing device is in.
426
.PN XTranslateCoordinates
429
fulfill these needs (and avoid any race conditions) by
430
asking the X server to perform these operations.
433
To translate a coordinate in one window to the coordinate
434
space of another window, use
435
.PN XTranslateCoordinates .
436
.IN "XTranslateCoordinates" "" "@DEF@"
439
Bool XTranslateCoordinates\^(\^\fIdisplay\fP, \fIsrc_w\fP\^, \fIdest_w\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIdest_x_return\fP\^,
441
\fIdest_y_return\fP\^, \fIchild_return\fP\^)
443
Display *\fIdisplay\fP\^;
445
Window \fIsrc_w\fP\^, \fIdest_w\fP\^;
447
int \fIsrc_x\fP\^, \fIsrc_y\fP\^;
449
int *\fIdest_x_return\fP\^, *\fIdest_y_return\fP\^;
451
Window *\fIchild_return\fP\^;
454
Specifies the connection to the X server.
456
Specifies the source window.
458
Specifies the destination window.
463
Specify the x and y coordinates within the source window.
464
.IP \fIdest_x_return\fP 1i
467
.IP \fIdest_y_return\fP 1i
468
Return the x and y coordinates within the destination window.
469
.IP \fIchild_return\fP 1i
470
Returns the child if the coordinates are contained in a mapped child of the
475
.PN XTranslateCoordinates
478
it takes the src_x and src_y coordinates relative
479
to the source window's origin and returns these coordinates to
480
dest_x_return and dest_y_return
481
relative to the destination window's origin.
483
.PN XTranslateCoordinates
486
src_w and dest_w are on different screens,
487
and dest_x_return and dest_y_return are zero.
488
If the coordinates are contained in a mapped child of dest_w,
489
that child is returned to child_return.
490
Otherwise, child_return is set to
493
.PN XTranslateCoordinates
499
To obtain the screen coordinates of the pointer
500
or to determine the pointer coordinates relative to a specified window, use
502
.IN "XQueryPointer" "" "@DEF@"
505
Bool XQueryPointer\^(\^\fIdisplay\fP, \fIw\fP\^, \fIroot_return\fP\^, \fIchild_return\fP\^, \fIroot_x_return\fP\^, \fIroot_y_return\fP\^,
507
\fIwin_x_return\fP\^, \fIwin_y_return\fP\^, \fImask_return\fP\^)
509
Display *\fIdisplay\fP\^;
513
Window *\fIroot_return\fP\^, *\fIchild_return\fP\^;
515
int *\fIroot_x_return\fP\^, *\fIroot_y_return\fP\^;
517
int *\fIwin_x_return\fP\^, *\fIwin_y_return\fP\^;
519
unsigned int *\fImask_return\fP\^;
522
Specifies the connection to the X server.
524
Specifies the window.
525
.ds Ro that the pointer is in
526
.IP \fIroot_return\fP 1i
527
Returns the root window \*(Ro.
528
.IP \fIchild_return\fP 1i
529
Returns the child window that the pointer is located in, if any.
530
.IP \fIroot_x_return\fP 1i
533
.IP \fIroot_y_return\fP 1i
534
Return the pointer coordinates relative to the root window's origin.
535
.IP \fIwin_x_return\fP 1i
538
.IP \fIwin_y_return\fP 1i
539
Return the pointer coordinates relative to the specified window.
540
.IP \fImask_return\fP 1i
541
Returns the current state of the modifier keys and pointer buttons.
546
function returns the root window the pointer is logically on and the pointer
547
coordinates relative to the root window's origin.
552
the pointer is not on the same screen as the specified window, and
556
to child_return and zero to win_x_return and win_y_return.
561
the pointer coordinates returned to win_x_return and win_y_return
562
are relative to the origin of the specified window.
565
returns the child that contains the pointer, if any,
571
returns the current logical state of the keyboard buttons
572
and the modifier keys in mask_return.
573
It sets mask_return to the bitwise inclusive OR of one or more
574
of the button or modifier key bitmasks to match
575
the current state of the mouse buttons and the modifier keys.
577
Note that the logical state of a device (as seen through Xlib)
578
may lag the physical state if device event processing is frozen
588
\*(SN Properties and Atoms
591
A property is a collection of named, typed data.
592
The window system has a set of predefined properties
593
.IN "Atom" "predefined"
594
(for example, the name of a window, size hints, and so on), and users can
595
define any other arbitrary information and associate it with windows.
596
Each property has a name,
597
which is an ISO Latin-1 string.
598
For each named property,
599
a unique identifier (atom) is associated with it.
600
A property also has a type, for example, string or integer.
601
These types are also indicated using atoms, so arbitrary new
602
types can be defined.
603
Data of only one type may be associated with a single
605
Clients can store and retrieve properties associated with windows.
606
For efficiency reasons,
607
an atom is used rather than a character string.
609
can be used to obtain the atom for property names.
612
A property is also stored in one of several possible formats.
613
The X server can store the information as 8-bit quantities, 16-bit
614
quantities, or 32-bit quantities.
615
This permits the X server to present the data in the byte order that the
618
If you define further properties of complex type,
619
you must encode and decode them yourself.
620
These functions must be carefully written if they are to be portable.
621
For further information about how to write a library extension,
624
The type of a property is defined by an atom, which allows for
625
arbitrary extension in this type scheme.
628
Certain property names are
629
predefined in the server for commonly used functions.
630
The atoms for these properties are defined in
632
To avoid name clashes with user symbols, the
634
name for each atom has the XA_ prefix.
635
For an explanation of the functions that let you get and set
636
much of the information stored in these predefined properties,
639
The core protocol imposes no semantics on these property names,
640
but semantics are specified in other X Consortium standards,
641
such as the \fIInter-Client Communication Conventions Manual\fP
642
and the \fIX Logical Font Description Conventions\fP.
644
You can use properties to communicate other information between
646
The functions described in this section let you define new properties
647
and get the unique atom IDs in your applications.
649
Although any particular atom can have some client interpretation
650
within each of the name spaces,
651
atoms occur in five distinct name spaces within the protocol:
663
event (none are built into the X server)
666
The built-in selection property names are:
676
The built-in property names are:
680
CUT_BUFFER0 RESOURCE_MANAGER
682
CUT_BUFFER2 WM_CLIENT_MACHINE
683
CUT_BUFFER3 WM_COLORMAP_WINDOWS
684
CUT_BUFFER4 WM_COMMAND
686
CUT_BUFFER6 WM_ICON_NAME
687
CUT_BUFFER7 WM_ICON_SIZE
689
RGB_BLUE_MAP WM_NORMAL_HINTS
690
RGB_DEFAULT_MAP WM_PROTOCOLS
691
RGB_GRAY_MAP WM_STATE
692
RGB_GREEN_MAP WM_TRANSIENT_FOR
693
RGB_RED_MAP WM_ZOOM_HINTS
697
The built-in property types are:
715
The built-in font property names are:
719
MIN_SPACE STRIKEOUT_DESCENT
720
NORM_SPACE STRIKEOUT_ASCENT
721
MAX_SPACE ITALIC_ANGLE
723
SUPERSCRIPT_X QUAD_WIDTH
725
SUBSCRIPT_X POINT_SIZE
726
SUBSCRIPT_Y RESOLUTION
727
UNDERLINE_POSITION COPYRIGHT
728
UNDERLINE_THICKNESS NOTICE
729
FONT_NAME FAMILY_NAME
734
For further information about font properties,
738
To return an atom for a given name, use
740
.IN "Atom" "interning"
741
.IN "XInternAtom" "" "@DEF@"
744
Atom XInternAtom\^(\^\fIdisplay\fP, \fIatom_name\fP\^, \fIonly_if_exists\fP\^)
746
Display *\fIdisplay\fP\^;
748
char *\fIatom_name\fP\^;
750
Bool \fIonly_if_exists\fP\^;
753
Specifies the connection to the X server.
754
.IP \fIatom_name\fP 1i
755
Specifies the name associated with the atom you want returned.
756
.IP \fIonly_if_exists\fP 1i
757
Specifies a Boolean value that indicates whether the atom must be created.
762
function returns the atom identifier associated with the specified atom_name
766
the atom is created if it does not exist.
771
If the atom name is not in the Host Portable Character Encoding,
772
the result is implementation-dependent.
773
Uppercase and lowercase matter;
774
the strings ``thing'', ``Thing'', and ``thinG''
775
all designate different atoms.
776
The atom will remain defined even after the client's connection closes.
777
It will become undefined only when the last connection to
788
To return atoms for an array of names, use
790
.IN "Atom" "interning"
791
.IN "XInternAtoms" "" "@DEF@"
794
Status XInternAtoms\^(\^\fIdisplay\fP, \fInames\fP\^, \fIcount\fP\^, \fIonly_if_exists\fP, \fIatoms_return\fP\^)
796
Display *\fIdisplay\fP\^;
798
char **\fInames\fP\^;
802
Bool \fIonly_if_exists\fP\^;
804
Atom *\fIatoms_return\fP\^;
807
Specifies the connection to the X server.
809
Specifies the array of atom names.
810
.ds Cn atom names in the array
812
Specifies the number of \*(Cn.
813
.IP \fIonly_if_exists\fP 1i
814
Specifies a Boolean value that indicates whether the atom must be created.
815
.IP \fIatoms_return\fP 1i
821
function returns the atom identifiers associated with the specified names.
822
The atoms are stored in the atoms_return array supplied by the caller.
823
Calling this function is equivalent to calling
825
for each of the names in turn with the specified value of only_if_exists,
826
but this function minimizes the number of round-trip protocol exchanges
827
between the client and the X server.
829
This function returns a nonzero status if atoms are returned for
831
otherwise, it returns zero.
841
To return a name for a given atom identifier, use
843
.IN "Atom" "getting name"
844
.IN "XGetAtomName" "" "@DEF@"
847
char *XGetAtomName\^(\^\fIdisplay\fP, \fIatom\fP\^)
849
Display *\fIdisplay\fP\^;
854
Specifies the connection to the X server.
856
Specifies the atom for the property name you want returned.
861
function returns the name associated with the specified atom.
862
If the data returned by the server is in the Latin Portable Character Encoding,
863
then the returned string is in the Host Portable Character Encoding.
864
Otherwise, the result is implementation-dependent.
865
To free the resulting string,
875
To return the names for an array of atom identifiers, use
877
.IN "Atom" "getting name"
878
.IN "XGetAtomNames" "" "@DEF@"
881
Status XGetAtomNames\^(\^\fIdisplay\fP, \fIatoms\fP, \fIcount\fP\^, \fInames_return\fP\^)
883
Display *\fIdisplay\fP\^;
889
char **\fInames_return\fP\^;
892
Specifies the connection to the X server.
894
Specifies the array of atoms.
895
.ds Cn atoms in the array
897
Specifies the number of \*(Cn.
898
.IP \fInames_return\fP 1i
899
Returns the atom names.
904
function returns the names associated with the specified atoms.
905
The names are stored in the names_return array supplied by the caller.
906
Calling this function is equivalent to calling
908
for each of the atoms in turn,
909
but this function minimizes the number of round-trip protocol exchanges
910
between the client and the X server.
912
This function returns a nonzero status if names are returned for
914
otherwise, it returns zero.
921
Obtaining and Changing Window Properties
923
\*(SN Obtaining and Changing Window Properties
926
You can attach a property list to every window.
927
Each property has a name, a type, and a value (see section 4.3).
928
The value is an array of 8-bit, 16-bit, or 32-bit quantities,
929
whose interpretation is left to the clients. The type
931
is used to represent 8-bit quantities, the type
933
is used to represent 16-bit quantities, and the type
935
is used to represent 32-bit quantities.
937
Xlib provides functions that you can use to obtain,
938
change, update, or interchange window properties.
939
In addition, Xlib provides other utility functions for inter-client
940
communication (see chapter 14).
943
To obtain the type, format, and value of a property of a given window, use
944
.PN XGetWindowProperty .
945
.IN "Property" "getting"
947
.IN "XGetWindowProperty" "" "@DEF@"
950
int XGetWindowProperty\^(\^\fIdisplay\fP, \fIw\fP\^, \fIproperty\fP\^, \fIlong_offset\fP\^, \fIlong_length\fP\^, \fIdelete\fP\^, \fIreq_type\fP\^,
952
\fIactual_type_return\fP\^, \fIactual_format_return\fP\^, \fInitems_return\fP\^, \fIbytes_after_return\fP\^,
956
Display *\fIdisplay\fP\^;
960
Atom \fIproperty\fP\^;
962
long \fIlong_offset\fP\^, \fIlong_length\fP\^;
966
Atom \fIreq_type\fP\^;
968
Atom *\fIactual_type_return\fP\^;
970
int *\fIactual_format_return\fP\^;
972
unsigned long *\fInitems_return\fP\^;
974
unsigned long *\fIbytes_after_return\fP\^;
976
unsigned char **\fIprop_return\fP\^;
979
Specifies the connection to the X server.
980
.ds Wi whose property you want to obtain
982
Specifies the window \*(Wi.
983
.IP \fIproperty\fP 1i
984
Specifies the property name.
985
.IP \fIlong_offset\fP 1i
986
Specifies the offset in the specified property (in 32-bit quantities)
987
where the data is to be retrieved.
988
.IP \fIlong_length\fP 1i
989
Specifies the length in 32-bit multiples of the data to be retrieved.
991
Specifies a Boolean value that determines whether the property is deleted.
992
.IP \fIreq_type\fP 1i
993
Specifies the atom identifier associated with the property type or
994
.PN AnyPropertyType .
995
.IP \fIactual_type_return\fP 1i
996
Returns the atom identifier that defines the actual type of the property.
997
.IP \fIactual_format_return\fP 1i
998
Returns the actual format of the property.
999
.IP \fInitems_return\fP 1i
1000
Returns the actual number of 8-bit, 16-bit, or 32-bit items
1001
stored in the prop_return data.
1002
.IP \fIbytes_after_return\fP 1i
1003
Returns the number of bytes remaining to be read in the property if
1004
a partial read was performed.
1005
.IP \fIprop_return\fP 1i
1006
Returns the data in the specified format.
1010
.PN XGetWindowProperty
1011
function returns the actual type of the property; the actual format of the property;
1012
the number of 8-bit, 16-bit, or 32-bit items transferred; the number of bytes remaining
1013
to be read in the property; and a pointer to the data actually returned.
1014
.PN XGetWindowProperty
1015
sets the return arguments as follows:
1017
If the specified property does not exist for the specified window,
1018
.PN XGetWindowProperty
1021
to actual_type_return and the value zero to
1022
actual_format_return and bytes_after_return.
1023
The nitems_return argument is empty.
1024
In this case, the delete argument is ignored.
1026
If the specified property exists
1027
but its type does not match the specified type,
1028
.PN XGetWindowProperty
1029
returns the actual property type to actual_type_return,
1030
the actual property format (never zero) to actual_format_return,
1031
and the property length in bytes
1032
(even if the actual_format_return is 16 or 32)
1033
to bytes_after_return.
1034
It also ignores the delete argument.
1035
The nitems_return argument is empty.
1037
If the specified property exists and either you assign
1039
to the req_type argument or the specified type matches the actual property type,
1040
.PN XGetWindowProperty
1041
returns the actual property type to actual_type_return and the actual
1042
property format (never zero) to actual_format_return.
1043
It also returns a value to bytes_after_return and nitems_return, by
1044
defining the following
1048
N = actual length of the stored property in bytes
1049
(even if the format is 16 or 32)
1052
L = MINIMUM(T, 4 * long_length)
1056
The returned value starts at byte index I in the property (indexing
1057
from zero), and its length in bytes is L.
1058
If the value for long_offset causes L to be negative,
1062
The value of bytes_after_return is A,
1063
giving the number of trailing unread bytes in the stored property.
1065
If the returned format is 8, the returned data is represented as a
1068
If the returned format is 16, the returned data is represented as a
1070
array and should be cast to that type to obtain the elements.
1071
If the returned format is 32, the returned data is represented as a
1073
array and should be cast to that type to obtain the elements.
1075
.PN XGetWindowProperty
1076
always allocates one extra byte in prop_return
1077
(even if the property is zero length)
1078
and sets it to zero so that simple properties consisting of characters
1079
do not have to be copied into yet another string before use.
1083
and bytes_after_return is zero,
1084
.PN XGetWindowProperty
1085
deletes the property
1086
from the window and generates a
1088
event on the window.
1090
The function returns
1092
if it executes successfully.
1093
To free the resulting data,
1097
.PN XGetWindowProperty
1106
To obtain a given window's property list, use
1107
.PN XListProperties .
1108
.IN "Property" "listing"
1109
.IN "XListProperties" "" "@DEF@"
1112
Atom *XListProperties\^(\^\fIdisplay\fP, \fIw\fP\^, \fInum_prop_return\fP\^)
1114
Display *\fIdisplay\fP\^;
1118
int *\fInum_prop_return\fP\^;
1120
.IP \fIdisplay\fP 1i
1121
Specifies the connection to the X server.
1122
.ds Wi whose property list you want to obtain
1124
Specifies the window \*(Wi.
1125
.IP \fInum_prop_return\fP 1i
1126
Returns the length of the properties array.
1131
function returns a pointer to an array of atom properties that are defined for
1132
the specified window or returns NULL if no properties were found.
1133
To free the memory allocated by this function, use
1142
To change a property of a given window, use
1143
.PN XChangeProperty .
1144
.IN "Property" "changing"
1145
.IN "Property" "appending"
1146
.IN "Property" "prepending"
1147
.IN "Property" "replacing"
1148
.IN "Property" "format"
1149
.IN "Property" "type"
1150
.IN "XChangeProperty" "" "@DEF@"
1153
XChangeProperty\^(\^\fIdisplay\fP, \fIw\fP\^, \fIproperty\fP\^, \fItype\fP\^, \fIformat\fP\^, \fImode\fP\^, \fIdata\fP\^, \fInelements\fP\^)
1155
Display *\fIdisplay\fP\^;
1159
Atom \fIproperty\fP\^, \fItype\fP\^;
1165
unsigned char *\fIdata\fP\^;
1167
int \fInelements\fP\^;
1169
.IP \fIdisplay\fP 1i
1170
Specifies the connection to the X server.
1171
.ds Wi whose property you want to change
1173
Specifies the window \*(Wi.
1174
.IP \fIproperty\fP 1i
1175
Specifies the property name.
1177
Specifies the type of the property.
1178
The X server does not interpret the type but simply
1179
passes it back to an application that later calls
1180
.PN XGetWindowProperty .
1182
Specifies whether the data should be viewed as a list
1183
of 8-bit, 16-bit, or 32-bit quantities.
1184
Possible values are 8, 16, and 32.
1185
This information allows the X server to correctly perform
1186
byte-swap operations as necessary.
1187
If the format is 16-bit or 32-bit,
1188
you must explicitly cast your data pointer to an (unsigned char *) in the call
1190
.PN XChangeProperty .
1191
.\" Changed name of this file to prop_mode.a on 1/13/87
1193
Specifies the mode of the operation.
1195
.PN PropModeReplace ,
1196
.PN PropModePrepend ,
1198
.PN PropModeAppend .
1200
Specifies the property data.
1201
.IP \fInelements\fP 1i
1202
Specifies the number of elements of the specified data format.
1207
function alters the property for the specified window and
1208
causes the X server to generate a
1210
event on that window.
1212
performs the following:
1215
.PN PropModeReplace ,
1217
discards the previous property value and stores the new data.
1222
.PN PropModeAppend ,
1224
inserts the specified data before the beginning of the existing data
1225
or onto the end of the existing data, respectively.
1226
The type and format must match the existing property value,
1230
If the property is undefined,
1231
it is treated as defined with the correct type and
1232
format with zero-length data.
1234
If the specified format is 8, the property data must be a
1237
If the specified format is 16, the property data must be a
1240
If the specified format is 32, the property data must be a
1244
The lifetime of a property is not tied to the storing client.
1245
Properties remain until explicitly deleted, until the window is destroyed,
1246
or until the server resets.
1247
For a discussion of what happens when the connection to the X server is closed,
1249
The maximum size of a property is server dependent and can vary dynamically
1250
depending on the amount of memory the server has available.
1251
(If there is insufficient space, a
1266
To rotate a window's property list, use
1267
.PN XRotateWindowProperties .
1269
.IN "XRotateWindowProperties" "" "@DEF@"
1272
XRotateWindowProperties\^(\^\fIdisplay\fP, \fIw\fP, \fIproperties\fP, \fInum_prop\fP, \fInpositions\fP\^)
1274
Display *\fIdisplay\fP\^;
1278
Atom \fIproperties\fP\^[]\^;
1280
int \fInum_prop\fP\^;
1282
int \fInpositions\fP\^;
1284
.IP \fIdisplay\fP 1i
1285
Specifies the connection to the X server.
1287
Specifies the window.
1288
.IP \fIproperties\fP 1i
1289
Specifies the array of properties that are to be rotated.
1290
.IP \fInum_prop\fP 1i
1291
Specifies the length of the properties array.
1292
.IP \fInpositions\fP 1i
1293
Specifies the rotation amount.
1297
.PN XRotateWindowProperties
1298
function allows you to rotate properties on a window and causes
1299
the X server to generate
1302
If the property names in the properties array are viewed as being numbered
1303
starting from zero and if there are num_prop property names in the list,
1304
then the value associated with property name I becomes the value associated
1305
with property name (I + npositions) mod N for all I from zero to N \- 1.
1306
The effect is to rotate the states by npositions places around the virtual ring
1307
of property names (right for positive npositions,
1308
left for negative npositions).
1309
If npositions mod N is nonzero,
1310
the X server generates a
1312
event for each property in the order that they are listed in the array.
1313
If an atom occurs more than once in the list or no property with that
1314
name is defined for the window,
1323
no properties are changed.
1325
.PN XRotateWindowProperties
1334
To delete a property on a given window, use
1335
.PN XDeleteProperty .
1336
.IN "Property" "deleting"
1337
.IN "XDeleteProperty" "" "@DEF@"
1340
XDeleteProperty\^(\^\fIdisplay\fP, \fIw\fP\^, \fIproperty\fP\^)
1342
Display *\fIdisplay\fP\^;
1346
Atom \fIproperty\fP\^;
1348
.IP \fIdisplay\fP 1i
1349
Specifies the connection to the X server.
1350
.ds Wi whose property you want to delete
1352
Specifies the window \*(Wi.
1353
.IP \fIproperty\fP 1i
1354
Specifies the property name.
1359
function deletes the specified property only if the
1360
property was defined on the specified window
1361
and causes the X server to generate a
1363
event on the window unless the property does not exist.
1378
Selections are one method used by applications to exchange data.
1379
By using the property mechanism,
1380
applications can exchange data of arbitrary types and can negotiate
1381
the type of the data.
1382
A selection can be thought of as an indirect property with a dynamic type.
1383
That is, rather than having the property stored in the X server,
1384
the property is maintained by some client (the owner).
1385
A selection is global in nature (considered to belong to the user
1386
but be maintained by clients) rather than being private to a particular
1387
window subhierarchy or a particular set of clients.
1389
Xlib provides functions that you can use to set, get, or request conversion
1391
This allows applications to implement the notion of current selection,
1392
which requires that notification be sent to applications when they no
1393
longer own the selection.
1394
Applications that support selection often highlight the current selection
1395
and so must be informed when another application has
1396
acquired the selection so that they can unhighlight the selection.
1398
When a client asks for the contents of
1399
a selection, it specifies a selection target type.
1401
can be used to control the transmitted representation of the contents.
1402
For example, if the selection is ``the last thing the user clicked on''
1403
and that is currently an image, then the target type might specify
1404
whether the contents of the image should be sent in XY format or Z format.
1406
The target type can also be used to control the class of
1407
contents transmitted, for example,
1408
asking for the ``looks'' (fonts, line
1409
spacing, indentation, and so forth) of a paragraph selection, not the
1410
text of the paragraph.
1411
The target type can also be used for other
1413
The protocol does not constrain the semantics.
1416
To set the selection owner, use
1417
.PN XSetSelectionOwner .
1418
.IN "Selection" "setting the owner"
1419
.IN "XSetSelectionOwner" "" "@DEF@"
1422
XSetSelectionOwner\^(\^\fIdisplay\fP, \fIselection\fP\^, \fIowner\fP\^, \fItime\fP\^)
1424
Display *\fIdisplay\fP\^;
1426
Atom \fIselection\fP\^;
1428
Window \fIowner\fP\^;
1432
.IP \fIdisplay\fP 1i
1433
Specifies the connection to the X server.
1434
.IP \fIselection\fP 1i
1435
Specifies the selection atom.
1437
Specifies the owner of the specified selection atom.
1438
You can pass a window or
1442
You can pass either a timestamp or
1447
.PN XSetSelectionOwner
1448
function changes the owner and last-change time for the specified selection
1449
and has no effect if the specified time is earlier than the current
1450
last-change time of the specified selection
1451
or is later than the current X server time.
1452
Otherwise, the last-change time is set to the specified time,
1455
replaced by the current server time.
1456
If the owner window is specified as
1458
then the owner of the selection becomes
1460
(that is, no owner).
1461
Otherwise, the owner of the selection becomes the client executing
1464
If the new owner (whether a client or
1467
the same as the current owner of the selection and the current
1470
the current owner is sent a
1473
If the client that is the owner of a selection is later
1474
terminated (that is, its connection is closed)
1475
or if the owner window it has specified in the request is later
1477
the owner of the selection automatically
1480
but the last-change time is not affected.
1481
The selection atom is uninterpreted by the X server.
1482
.PN XGetSelectionOwner
1483
returns the owner window, which is reported in
1484
.PN SelectionRequest
1488
Selections are global to the X server.
1490
.PN XSetSelectionOwner
1498
To return the selection owner, use
1499
.PN XGetSelectionOwner .
1500
.IN "Selection" "getting the owner"
1501
.IN "XGetSelectionOwner" "" "@DEF@"
1504
Window XGetSelectionOwner\^(\^\fIdisplay\fP, \fIselection\fP\^)
1506
Display *\fIdisplay\fP\^;
1508
Atom \fIselection\fP\^;
1510
.IP \fIdisplay\fP 1i
1511
Specifies the connection to the X server.
1512
.ds Se whose owner you want returned
1513
.IP \fIselection\fP 1i
1514
Specifies the selection atom \*(Se.
1518
.PN XGetSelectionOwner
1520
returns the window ID associated with the window that currently owns the
1521
specified selection.
1522
If no selection was specified, the function returns the constant
1527
there is no owner for the selection.
1529
.PN XGetSelectionOwner
1535
To request conversion of a selection, use
1536
.PN XConvertSelection .
1537
.IN "Selection" "converting"
1538
.IN "XConvertSelection" "" "@DEF@"
1541
XConvertSelection\^(\^\fIdisplay\fP, \fIselection\fP\^, \fItarget\fP\^, \fIproperty\fP\^, \fIrequestor\fP\^, \fItime\fP\^)
1543
Display *\fIdisplay\fP\^;
1545
Atom \fIselection\fP\^, \fItarget\fP\^;
1547
Atom \fIproperty\fP\^;
1549
Window \fIrequestor\fP\^;
1553
.IP \fIdisplay\fP 1i
1554
Specifies the connection to the X server.
1555
.IP \fIselection\fP 1i
1556
Specifies the selection atom.
1558
Specifies the target atom.
1559
.IP \fIproperty\fP 1i
1560
Specifies the property name.
1563
.IP \fIrequestor\fP 1i
1564
Specifies the requestor.
1567
You can pass either a timestamp or
1571
.PN XConvertSelection
1572
requests that the specified selection be converted to the specified target
1575
If the specified selection has an owner, the X server sends a
1576
.PN SelectionRequest
1577
event to that owner.
1579
If no owner for the specified
1580
selection exists, the X server generates a
1583
requestor with property
1586
The arguments are passed on unchanged in either of the events.
1587
There are two predefined selection atoms: PRIMARY and SECONDARY.
1589
.PN XConvertSelection
added
removed
specs/libX11/CH04
