DataMuseum.dk

top - metrics - download

    Length: 44505 (0xadd9)
    Types: TextFile
    Names: »CH04«

└─⟦276d19d6e⟧ Bits:30007243 EUUGD5_I: X11R5
    └─⟦4856bf7e7⟧ »./mit-4/mit-4.00« 
        └─⟦635ff9e7e⟧ 
            └─⟦this⟧ »mit/doc/Xlib/CH04« 

TextFile

\&
.sp 1
.ce 3
\s+1\fBChapter 4\fP\s-1

\s+1\fBWindow Information Functions\fP\s-1
.sp 2
.nr H1 4
.nr H2 0
.nr H3 0
.nr H4 0
.nr H5 0
.na
.LP
.XS
Chapter 4: Window Information Functions 
.XE
After you connect the display to the X server and create a window,
you can use the Xlib window information functions to:
.IP \(bu 5
Obtain information about a window
.IP \(bu 5
Translate screen coordinates
.IP \(bu 5
Manipulate property lists
.IP \(bu 5
Obtain and change window properties
.IP \(bu 5
Manipulate selections
.NH 2
Obtaining Window Information
.XS
\*(SN Obtaining Window Information 
.XE
.LP
Xlib provides functions that you can use to obtain information about 
the window tree, the window's current attributes, 
the window's current geometry, or the current pointer coordinates.
Because they are most frequently used by window managers,
these functions all return a status to indicate whether the window still
exists.
.LP
.sp
To obtain the parent, a list of children, and number of children for 
a given window, use 
.PN XQueryTree .
.IN "Child Window"
.IN "Parent Window"
.IN "XQueryTree" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XQueryTree.f,v 1.1 88/02/26 10:02:19 mento Exp $
Status XQueryTree\^(\^\fIdisplay\fP, \fIw\fP\^, \fIroot_return\fP\^, \fIparent_return\fP\^, \fIchildren_return\fP\^, \fInchildren_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      Window *\fIroot_return\fP\^;
.br
      Window *\fIparent_return\fP\^;
.br
      Window **\fIchildren_return\fP\^;
.br
      unsigned int *\fInchildren_return\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.ds Wi whose list of children, root, parent, and number of children \
you want to obtain
.\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
.IP \fIw\fP 1i
Specifies the window \*(Wi.
.\" $Header: root.a,v 1.2 88/05/08 10:54:56 mento Exp $
.IP \fIroot_return\fP 1i
Returns the root window.
.IP \fIparent_return\fP 1i
Returns the parent window.
.\" $Header: children.a,v 1.2 88/05/08 10:58:36 mento Exp $
.IP \fIchildren_return\fP 1i
Returns the list of children.
.\" $Header: nchildren.a,v 1.2 88/05/08 11:00:11 mento Exp $
.IP \fInchildren_return\fP 1i
Returns the number of children.
.\" End marker code here
.LP
.\" $Header: XQueryTree.d,v 1.2 88/06/11 07:52:43 mento Exp $
The
.PN XQueryTree
function returns the root ID, the parent window ID, 
a pointer to the list of children windows, 
and the number of children in the list for the specified window.
The children are listed in current stacking order, from bottommost 
(first) to topmost (last).
.PN XQueryTree
returns zero if it fails and nonzero if it succeeds.
To free this list when it is no longer needed, use 
.PN XFree .
.LP
.PN XQueryTree
can generate a
.PN BadWindow
error.
.LP
.sp
To obtain the current attributes of a given window, use 
.PN XGetWindowAttributes .
.IN "XGetWindowAttributes" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XGetAttr.f,v 1.1 88/02/26 10:00:23 mento Exp $
Status XGetWindowAttributes\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwindow_attributes_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XWindowAttributes *\fIwindow_attributes_return\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.ds Wi whose current attributes you want to obtain
.\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
.IP \fIw\fP 1i
Specifies the window \*(Wi.
.\" $Header: windatt.a,v 1.1 88/02/26 10:32:38 mento Exp $
.IP \fIwindow_attributes_return\fP 1i
Returns the specified window's attributes in the
.PN XWindowAttributes
structure.
.\" End marker code here
.LP
.\" $Header: XGetAttr.d,v 1.1 88/02/26 10:42:12 mento Exp $
The
.PN XGetWindowAttributes
function returns the current attributes for the specified window to an
.PN XWindowAttributes
structure.
.LP
.IN "XWindowAttributes" "" "@DEF@"
.\" Start marker code here
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	int x, y;	/* location of window */
	int width, height;	/* width and height of window */
	int border_width;	/* border width of window */
	int depth;	/* depth of window */
	Visual *visual;	/* the associated visual structure */
	Window root;	/* root of screen containing window */
	int class;	/* InputOutput, InputOnly*/
	int bit_gravity;	/* one of the bit gravity values */
	int win_gravity;	/* one of the window gravity values */
	int backing_store;	/* NotUseful, WhenMapped, Always */
	unsigned long backing_planes;	/* planes to be preserved if possible */
	unsigned long backing_pixel;	/* value to be used when restoring planes */
	Bool save_under;	/* boolean, should bits under be saved? */
	Colormap colormap;	/* color map to be associated with window */
	Bool map_installed;	/* boolean, is color map currently installed*/
	int map_state;	/* IsUnmapped, IsUnviewable, IsViewable */
	long all_event_masks;	/* set of events all people have interest in*/
	long your_event_mask;	/* my event mask */
	long do_not_propagate_mask;	/* set of events that should not propagate */
	Bool override_redirect;	/* boolean value for override-redirect */
	Screen *screen;	/* back pointer to correct screen */
} XWindowAttributes;
.De
.\" End marker code here
.LP
The x and y members are set to the upper-left outer
corner relative to the parent window's origin.
The width and height members are set to the inside size of the window, 
not including the border.
The border_width member is set to the window's border width in pixels.
The depth member is set to the depth of the window 
(that is, bits per pixel for the object).
The visual member is a pointer to the screen's associated
.PN Visual
structure.
The root member is set to the root window of the screen containing the window.
The class member is set to the window's class and can be either
.PN InputOutput
or
.PN InputOnly .
.LP
The bit_gravity member is set to the window's bit gravity
and can be one of the following:
.LP
.TS
lw(1.5i) lw(1.5i).
T{
.PN ForgetGravity
T}	T{
.PN EastGravity
T}
T{
.PN NorthWestGravity
T}	T{
.PN SouthWestGravity
T}
T{
.PN NorthGravity
T}	T{
.PN SouthGravity
T}
T{
.PN NorthEastGravity
T}	T{
.PN SouthEastGravity
T}
T{
.PN WestGravity
T}	T{
.PN StaticGravity
T}
.PN CenterGravity
.TE
.LP
The win_gravity member is set to the window's window gravity
and can be one of the following:
.LP
.TS
lw(1.5i) lw(1.5i).
T{
.PN UnmapGravity
T}	T{
.PN EastGravity
T}
T{
.PN NorthWestGravity
T}	T{
.PN SouthWestGravity
T}
T{
.PN NorthGravity
T}	T{
.PN SouthGravity
T}
T{
.PN NorthEastGravity
T}	T{
.PN SouthEastGravity
T}
T{
.PN WestGravity
T}	T{
.PN StaticGravity
T}
.PN CenterGravity
.TE
.LP
For additional information on gravity,
see section 3.3.
.LP
The backing_store member is set to indicate how the X server should maintain
the contents of a window 
and can be 
.PN WhenMapped ,
.PN Always ,
or
.PN NotUseful .
The backing_planes member is set to indicate (with bits set to 1) which bit 
planes of the window hold dynamic data that must be preserved in backing_stores 
and during save_unders.
The backing_pixel member is set to indicate what values to use 
for planes not set in backing_planes.
.LP
The save_under member is set to 
.PN True
or
.PN False .
The colormap member is set to the colormap for the specified window and can be
a colormap ID or 
.PN None .
The map_installed member is set to indicate whether the colormap is 
currently installed and can be 
.PN True
or
.PN False .
The map_state member is set to indicate the state of the window and can be
.PN IsUnmapped ,
.PN IsUnviewable ,
or
.PN IsViewable .
.PN IsUnviewable
is used if the window is mapped but some ancestor is unmapped.
.LP
The all_event_masks member is set to the bitwise inclusive OR of all event 
masks selected on the window by all clients.
The your_event_mask member is set to the bitwise inclusive OR of all event 
masks selected by the querying client.
The do_not_propagate_mask member is set to the bitwise inclusive OR of the 
set of events that should not propagate.
.LP
The override_redirect member is set to indicate whether this window overrides
structure control facilities and can be 
.PN True
or
.PN False .
Window manager clients should ignore the window if this member is
.PN True .
.LP
The screen member is set to a screen pointer that gives you a back pointer 
to the correct screen.
This makes it easier to obtain the screen information without
having to loop over the root window fields to see which field matches.
.LP
.PN XGetWindowAttributes
can generate
.PN BadDrawable
and
.PN BadWindow
errors.
.LP
.sp
To obtain the current geometry of a given drawable, use 
.PN XGetGeometry .
.IN "XGetGeometry" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XGetGeometry.f,v 1.1 88/02/26 10:00:34 mento Exp $
Status XGetGeometry\^(\^\fIdisplay\fP, \fId\fP\^, \^\fIroot_return\fP\^, \fIx_return\fP\^, \fIy_return\fP\^, \fIwidth_return\fP\^, 
.br
                      \fIheight_return\fP\^, \fIborder_width_return\fP\^, \fIdepth_return\fP\^)
.br
        Display *\fIdisplay\fP\^;
.br
        Drawable \fId\fP\^;
.br
        Window *\fIroot_return\fP\^;
.br
        int *\fIx_return\fP\^, *\fIy_return\fP\^;
.br
        unsigned int *\fIwidth_return\fP\^, *\fIheight_return\fP\^;
.br
        unsigned int *\fIborder_width_return\fP\^;
.br
        unsigned int *\fIdepth_return\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.ds Dr , which can be a window or a pixmap
.\" $Header: d_gen.a,v 1.2 88/08/04 11:09:21 mento Exp $
.IP \fId\fP 1i
Specifies the drawable\*(Dr. 
.\" $Header: root.a,v 1.2 88/05/08 10:54:56 mento Exp $
.IP \fIroot_return\fP 1i
Returns the root window.
.\" $Header: getxy.a,v 1.5 88/08/17 09:00:47 mento Exp $
.IP \fIx_return\fP 1i
.br
.ns
.IP \fIy_return\fP 1i
Return the x and y coordinates that define the location of the drawable.
For a window, 
these coordinates specify the upper-left outer corner relative to
its parent's origin.
For pixmaps, these coordinates are always zero.
.IP \fIwidth_return\fP 1i
.br
.ns
.IP \fIheight_return\fP 1i
Return the drawable's dimensions (width and height).
For a window, 
these dimensions specify the inside size, not including the border.
.IP \fIborder_width_return\fP 1i
Returns the border width in pixels. 
If the drawable is a pixmap, it returns zero.
.IP \fIdepth_return\fP 1i
Returns the depth of the drawable (bits per pixel for the object).
.\" End marker code here
.LP
.\" $Header: XGetGeometry.d,v 1.3 88/06/11 07:51:01 mento Exp $
The
.PN XGetGeometry
function returns the root window and the current geometry of the drawable.
The geometry of the drawable includes the x and y coordinates, width and height,
border width, and depth.
These are described in the argument list.
It is legal to pass to this function a window whose class is
.PN InputOnly .
.LP
.PN XGetGeometry
can generate a
.PN BadDrawable
error.
.NH 2
Translating Screen Coordinates
.XS
\*(SN Translating Screen Coordinates 
.XE
.LP
Applications sometimes
need to perform a coordinate transformation from the coordinate
space of one window to another window or need to determine which
window the pointing device is in.
.PN XTranslateCoordinates
and
.PN XQueryPointer
fulfill these needs (and avoids any race conditions) by
asking the X server to perform these operations.
.LP
.sp
To translate a coordinate in one window to the coordinate
space of another window, use
.PN XTranslateCoordinates .
.IN "XTranslateCoordinates" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XTranCoords.f,v 1.2 88/04/05 14:44:04 mento Exp $
Bool XTranslateCoordinates\^(\^\fIdisplay\fP, \fIsrc_w\fP\^, \fIdest_w\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIdest_x_return\fP\^, 
.br
                            \fIdest_y_return\fP\^, \fIchild_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIsrc_w\fP\^, \fIdest_w\fP\^;
.br
      int \fIsrc_x\fP\^, \fIsrc_y\fP\^;
.br
      int *\fIdest_x_return\fP\^, *\fIdest_y_return\fP\^;
.br
      Window *\fIchild_return\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: sw.a,v 1.2 88/05/07 13:19:45 mento Exp $
.IP \fIsrc_w\fP 1i
Specifies the source window.
.\" $Header: dw.a,v 1.2 88/05/07 13:20:18 mento Exp $
.IP \fIdest_w\fP 1i
Specifies the destination window.
.\" $Header: srcxy1.a,v 1.1 88/02/26 10:31:23 mento Exp $
.IP \fIsrc_x\fP 1i
.br
.ns
.IP \fIsrc_y\fP 1i
Specify the x and y coordinates within the source window.
.\" $Header: destxy.a,v 1.2 88/05/07 13:21:31 mento Exp $
.IP \fIdest_x_return\fP 1i
.br
.ns
.IP \fIdest_y_return\fP 1i
Return the x and y coordinates within the destination window.
.\" $Header: child.a,v 1.1 88/02/26 10:05:43 mento Exp $
.IP \fIchild_return\fP 1i
Returns the child if the coordinates are contained in a mapped child of the
destination window.
.\" End marker code here
.LP
.\" $Header: XTranCoords.d,v 1.5 88/08/17 08:32:02 mento Exp $
If
.PN XTranslateCoordinates
returns
.PN True ,
it takes the src_x and src_y coordinates relative
to the source window's origin and returns these coordinates to 
dest_x_return and dest_y_return
relative to the destination window's origin.
If
.PN XTranslateCoordinates
returns 
.PN False , 
src_w and dest_w are on different screens,
and dest_x_return and dest_y_return are zero.
If the coordinates are contained in a mapped child of dest_w,
that child is returned to child_return.
Otherwise, child_return is set to
.PN None .
.LP
.PN XTranslateCoordinates
can generate a
.PN BadWindow 
error.
.LP
.sp
To obtain the screen coordinates of the pointer,
or to determine the pointer coordinates relative to a specified window, use 
.PN XQueryPointer .
.IN "XQueryPointer" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XQueryPntr.f,v 1.1 88/02/26 10:02:18 mento Exp $
Bool XQueryPointer\^(\^\fIdisplay\fP, \fIw\fP\^, \fIroot_return\fP\^, \fIchild_return\fP\^, \fIroot_x_return\fP\^, \fIroot_y_return\fP\^, 
.br
                     \fIwin_x_return\fP\^, \fIwin_y_return\fP\^, \fImask_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      Window *\fIroot_return\fP\^, *\fIchild_return\fP\^;
.br
      int *\fIroot_x_return\fP\^, *\fIroot_y_return\fP\^;
.br
      int *\fIwin_x_return\fP\^, *\fIwin_y_return\fP\^;
.br
      unsigned int *\fImask_return\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.ds Ro that the pointer is in
.\" $Header: root_gen.a,v 1.2 88/08/04 11:19:15 mento Exp $
.IP \fIroot_return\fP 1i
Returns the root window \*(Ro.
.IP \fIchild_return\fP 1i
Returns the child window that the pointer is located in, if any.
.\" $Header: rootxy.a,v 1.2 88/08/17 09:03:18 mento Exp $
.IP \fIroot_x_return\fP 1i
.br
.ns
.IP \fIroot_y_return\fP 1i
Return the pointer coordinates relative to the root window's origin.
.\" $Header: winxy.a,v 1.2 88/08/17 09:04:07 mento Exp $
.IP \fIwin_x_return\fP 1i
.br
.ns
.IP \fIwin_y_return\fP 1i
Return the pointer coordinates relative to the specified window.
.\" $Header: mask1.a,v 1.1 88/02/26 10:28:48 mento Exp $
.IP \fImask_return\fP 1i
Returns the current state of the modifier keys and pointer buttons.
.\" End marker code here
.LP
.\" $Header: XQueryPntr.d,v 1.2 88/06/11 07:52:42 mento Exp $
The
.PN XQueryPointer
function returns the root window the pointer is logically on and the pointer
coordinates relative to the root window's origin.
If
.PN XQueryPointer
returns 
.PN False , 
the pointer is not on the same screen as the specified window, and
.PN XQueryPointer
returns 
.PN None
to child_return and zero to win_x_return and win_y_return.
If 
.PN XQueryPointer
returns 
.PN True , 
the pointer coordinates returned to win_x_return and win_y_return
are relative to the origin of the specified window.
In this case, 
.PN XQueryPointer
returns the child that contains the pointer, if any,
or else
.PN None
to child_return.
.LP
.PN XQueryPointer
returns the current logical state of the keyboard buttons 
and the modifier keys in mask_return.
It sets mask_return to the bitwise inclusive OR of one or more
of the button or modifier key bitmasks to match 
the current state of the mouse buttons and the modifier keys.
.LP
Note that the logical state of a device (as seen through Xlib)
may lag the physical state if device event processing is frozen
(see section 12.1).
.LP
.PN XQueryPointer
can generate a
.PN BadWindow 
error.
.NH 2
Properties and Atoms
.XS
\*(SN Properties and Atoms 
.XE
.LP
A property is a collection of named, typed data.
The window system has a set of predefined properties
.IN "Atom" "predefined"
(for example, the name of a window, size hints, and so on), and users can
define any other arbitrary information and associate it with windows.
Each property has a name,
which is an ISO Latin-1 string.
For each named property,
a unique identifier (atom) is associated with it. 
A property also has a type, for example, string or integer.
These types are also indicated using atoms, so arbitrary new
types can be defined.
Data of only one type may be associated with a single
property name.
Clients can store and retrieve properties associated with windows.
For efficiency reasons,
an atom is used rather than a character string.
.PN XInternAtom
can be used to obtain the atom for property names.
.IN "Atom" 
.LP
A property is also stored in one of several possible formats.
The X server can store the information as 8-bit quantities, 16-bit
quantities, or 32-bit quantities.
This permits the X server to present the data in the byte order that the
client expects.
.NT Note
If you define further properties of complex type, 
you must encode and decode them yourself.
These functions must be carefully written if they are to be portable.
For further information about how to write a library extension,
see appendix C.
.NE
The type of a property is defined by an atom, which allows for
arbitrary extension in this type scheme.
.IN "Atom" 
.LP
Certain property names are
predefined in the server for commonly used functions.
The atoms for these properties are defined in 
.Pn < X11/Xatom.h >.
To avoid name clashes with user symbols, the 
.PN #define 
name for each atom has the XA_ prefix.
For definitions of these properties,
see section 4.3.
For an explanation of the functions that let you get and set
much of the information stored in these predefined properties,
see chapter 14.
.LP
The core protocol imposes no semantics on these property names,
but semantics are specified in other X Consortium standards,
such as the \fIInter-Client Communication Conventions Manual\fP
and the \fIX Logical Font Description Conventions\fP.
.LP
You can use properties to communicate other information between
applications.
The functions described in this section let you define new properties 
and get the unique atom IDs in your applications.
.LP
Although any particular atom can have some client interpretation 
within each of the name spaces, 
atoms occur in five distinct name spaces within the protocol: 
.IP \(bu 5
Selections
.IP \(bu 5
Property names
.IP \(bu 5
Property types
.IP \(bu 5
Font properties 
.IP \(bu 5
Type of a 
.PN ClientMessage 
event (none are built into the X server)
.LP
.LP
The built-in selection property names are:
.LP
.Ds 0
.TA .5i 1.5i 3i
.ta .5i 1.5i 3i
.R
PRIMARY
SECONDARY
.De
.LP
The built-in property names are: 
.TS
lw(2i) lw(2i).
.sp 6p
CUT_BUFFER0	RESOURCE_MANAGER
CUT_BUFFER1	WM_CLASS
CUT_BUFFER2	WM_CLIENT_MACHINE
CUT_BUFFER3	WM_COLORMAP_WINDOWS
CUT_BUFFER4	WM_COMMAND
CUT_BUFFER5	WM_HINTS
CUT_BUFFER6	WM_ICON_NAME
CUT_BUFFER7	WM_ICON_SIZE
RGB_BEST_MAP	WM_NAME
RGB_BLUE_MAP	WM_NORMAL_HINTS
RGB_DEFAULT_MAP	WM_PROTOCOLS
RGB_GRAY_MAP	WM_STATE
RGB_GREEN_MAP	WM_TRANSIENT_FOR
RGB_RED_MAP
.sp 6p
.TE
.LP
The built-in property types are: 
.LP
.TS
lw(2i) lw(2i).
.sp 6p
ARC	POINT
ATOM	RGB_COLOR_MAP
BITMAP	RECTANGLE
CARDINAL	STRING
COLORMAP	VISUALID
CURSOR	WINDOW
DRAWABLE	WM_HINTS
FONT	WM_SIZE_HINTS
INTEGER	
PIXMAP
.sp 6p
.TE
.LP
The built-in font property names are: 
.TS
lw(2i) lw(2i).
.sp 6p
MIN_SPACE	STRIKEOUT_DESCENT
NORM_SPACE	STRIKEOUT_ASCENT
MAX_SPACE	ITALIC_ANGLE
END_SPACE	X_HEIGHT
SUPERSCRIPT_X	QUAD_WIDTH
SUPERSCRIPT_Y	WEIGHT
SUBSCRIPT_X	POINT_SIZE
SUBSCRIPT_Y	RESOLUTION
UNDERLINE_POSITION	COPYRIGHT
UNDERLINE_THICKNESS	NOTICE
FONT_NAME	FAMILY_NAME
FULL_NAME	CAP_HEIGHT
.sp 6p
.TE
.LP
For further information about font properties,
see section 8.5.
.LP
.sp
To return an atom for a given name, use 
.PN XInternAtom .
.IN "Atom" "interning"
.IN "XInternAtom" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XInternAtom.f,v 1.1 88/02/26 10:01:15 mento Exp $
Atom XInternAtom\^(\^\fIdisplay\fP, \fIatom_name\fP\^, \fIonly_if_exists\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      char *\fIatom_name\fP\^;
.br
      Bool \fIonly_if_exists\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: atom_name.a,v 1.1 88/02/26 10:05:01 mento Exp $
.IP \fIatom_name\fP 1i
Specifies the name associated with the atom you want returned.
.\" $Header: onlyifexist.a,v 1.3 88/05/08 11:36:14 mento Exp $
.IP \fIonly_if_exists\fP 1i
Specifies a Boolean value that indicates whether
.PN XInternAtom
creates the atom.
.\" End marker code here
.LP
.\" $Header: XInternAtom.d,v 1.5 88/08/17 09:06:25 mento Exp $
The
.PN XInternAtom
function returns the atom identifier associated with the specified atom_name
string.
If only_if_exists is 
.PN False ,
the atom is created if it does not exist.
Therefore,
.PN XInternAtom
can return
.PN None .
If the atom name is not in the Host Portable Character Encoding
the result is implementation dependent.
Case matters; the strings \fIthing\fP, \fIThing\fP, and \fIthinG\fP 
all designate different atoms.  
The atom will remain defined even after the client's connection closes.
It will become undefined only when the last connection to
the X server closes.
.LP
.PN XInternAtom
can generate
.PN BadAlloc
and
.PN BadValue 
errors.
.LP
.sp
To return a name for a given atom identifier, use 
.PN XGetAtomName .
.IN "Atom" "getting name"
.IN "XGetAtomName" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XGetAtomName.f,v 1.1 88/02/26 10:00:23 mento Exp $
char *XGetAtomName\^(\^\fIdisplay\fP, \fIatom\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Atom \fIatom\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: atom.a,v 1.2 88/04/06 12:06:45 mento Exp $
.IP \fIatom\fP 1i
Specifies the atom for the property name you want returned.
.\" End marker code here
.LP
.\" $Header: XGetAtomName.d,v 1.3 88/05/08 11:40:48 mento Exp $
The
.PN XGetAtomName
function returns the name associated with the specified atom.
If the data returned by the server is in the Latin Portable Character Encoding,
then the returned string is in the Host Portable Character Encoding.
Otherwise, the result is implementation dependent.
To free the resulting string,
call
.PN XFree .
.LP
.PN XGetAtomName
can generate a
.PN BadAtom 
error.
.NH 2
Obtaining and Changing Window Properties
.XS
\*(SN Obtaining and Changing Window Properties 
.XE
.LP
You can attach a property list to every window.
Each property has a name, a type, and a value (see section 4.3).
The value is an array of 8-bit, 16-bit, or 32-bit quantities,
whose interpretation is left to the clients. 
.LP
Xlib provides functions that you can use to obtain, 
change, update, or interchange window properties.
In addition, Xlib provides other utility functions for inter-client
communication (see chapter 14).
.LP
.sp
To obtain the type, format, and value of a property of a given window, use 
.PN XGetWindowProperty .
.IN "Property" "getting"
.LP
.IN "XGetWindowProperty" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XGetProperty.f,v 1.1 88/02/26 10:00:55 mento Exp $
int XGetWindowProperty\^(\^\fIdisplay\fP, \fIw\fP\^, \fIproperty\fP\^, \fIlong_offset\fP\^, \fIlong_length\fP\^, \fIdelete\fP\^, \fIreq_type\fP\^, 
.br
                        \fIactual_type_return\fP\^, \fIactual_format_return\fP\^, \fInitems_return\fP\^, \fIbytes_after_return\fP\^, 
.br
                        \fIprop_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      Atom \fIproperty\fP\^;
.br
      long \fIlong_offset\fP\^, \fIlong_length\fP\^;
.br
      Bool \fIdelete\fP\^;
.br
      Atom \fIreq_type\fP\^; 
.br
      Atom *\fIactual_type_return\fP\^;
.br
      int *\fIactual_format_return\fP\^;
.br
      unsigned long *\fInitems_return\fP\^;
.br
      unsigned long *\fIbytes_after_return\fP\^;
.br
      unsigned char **\fIprop_return\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.ds Wi whose property you want to obtain
.\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
.IP \fIw\fP 1i
Specifies the window \*(Wi.
.\" $Header: property.a,v 1.2 88/04/05 15:19:43 mento Exp $
.IP \fIproperty\fP 1i
Specifies the property name.
.IP \fIlong_offset\fP 1i
Specifies the offset in the specified property (in 32-bit quantities) 
where the data is to be retrieved.
.IP \fIlong_length\fP 1i
Specifies the length in 32-bit multiples of the data to be retrieved.
.\" $Header: delete.a,v 1.4 88/05/08 11:45:29 mento Exp $
.IP \fIdelete\fP 1i
Specifies a Boolean value that determines whether the property is deleted.
.\" $Header: reqtype.a,v 1.3 88/05/08 11:46:32 mento Exp $
.IP \fIreq_type\fP 1i
Specifies the atom identifier associated with the property type or
.PN AnyPropertyType .
.\" $Header: actual_type.a,v 1.1 88/02/26 10:04:47 mento Exp $
.IP \fIactual_type_return\fP 1i
Returns the atom identifier  that defines the actual type of the property.
.\" $Header: act_format.a,v 1.1 88/02/26 10:04:45 mento Exp $
.IP \fIactual_format_return\fP 1i
Returns the actual format of the property.
.IP \fInitems_return\fP 1i
Returns the actual number of 8-bit, 16-bit, or 32-bit items 
stored in the prop_return data.
.IP \fIbytes_after_return\fP 1i
Returns the number of bytes remaining to be read in the property if 
a partial read was performed.
.IP \fIprop_return\fP 1i
Returns the data in the specified format.
.\" End marker code here
.LP
.\" $Header: XGetProperty.d,v 1.3 88/08/17 09:10:14 mento Exp $
The
.PN XGetWindowProperty
function returns the actual type of the property; the actual format of the property;
the number of 8-bit, 16-bit, or 32-bit items transferred; the number of bytes remaining
to be read in the property; and a pointer to the data actually returned.
.PN XGetWindowProperty
sets the return arguments as follows:
.IP \(bu 5
If the specified property does not exist for the specified window,
.PN XGetWindowProperty 
returns 
.PN None
to actual_type_return and the value zero to 
actual_format_return and bytes_after_return.
The nitems_return argument is empty.
In this case, the delete argument is ignored.
.IP \(bu 5
If the specified property exists 
but its type does not match the specified type,
.PN XGetWindowProperty 
returns the actual property type to actual_type_return, 
the actual property format (never zero) to actual_format_return, 
and the property length in bytes (even if the actual_format_return is 16 or 32) 
to bytes_after_return.
It also ignores the delete argument.
The nitems_return argument is empty.
.IP \(bu 5
If the specified property exists and either you assign 
.PN AnyPropertyType 
to the req_type argument or the specified type matches the actual property type,
.PN XGetWindowProperty 
returns the actual property type to actual_type_return and the actual
property format (never zero) to actual_format_return. 
It also returns a value to bytes_after_return and nitems_return, by 
defining the following
values:
.IP
.nf
	N = actual length of the stored property in bytes
	     (even if the format is 16 or 32)
	I = 4 * long_offset
	T = N - I
	L = MINIMUM(T, 4 * long_length)
	A = N - (I + L)
.fi
.IP
The returned value starts at byte index I in the property (indexing
from zero), and its length in bytes is L.
If the value for long_offset causes L to be negative,
a
.PN BadValue
error results. 
The value of bytes_after_return is A, 
giving the number of trailing unread bytes in the stored property.
.LP
.PN XGetWindowProperty
always allocates one extra byte in prop_return 
(even if the property is zero length) 
and sets it to ASCII null so that simple properties consisting of characters
do not have to be copied into yet another string before use.
If delete is 
.PN True 
and bytes_after_return is zero, 
.PN XGetWindowProperty
deletes the property 
from the window and generates a 
.PN PropertyNotify 
event on the window.
.LP
The function returns
.PN Success
if it executes successfully.
To free the resulting data,
use
.PN XFree .
.LP
.PN XGetWindowProperty
can generate
.PN BadAtom ,
.PN BadValue ,
and
.PN BadWindow 
errors.
.LP
.sp
To obtain a given window's property list, use 
.PN XListProperties .
.IN "Property" "listing"
.IN "XListProperties" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XListProps.f,v 1.1 88/02/26 10:01:22 mento Exp $
Atom *XListProperties\^(\^\fIdisplay\fP, \fIw\fP\^, \fInum_prop_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      int *\fInum_prop_return\fP\^; 
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.ds Wi whose property list you want to obtain
.\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
.IP \fIw\fP 1i
Specifies the window \*(Wi.
.IP \fInum_prop_return\fP 1i
Returns the length of the properties array.
.\" End marker code here
.LP
.\" $Header: XListProps.d,v 1.4 88/05/08 11:58:22 mento Exp $
The
.PN XListProperties
function returns a pointer to an array of atom properties that are defined for 
the specified window or returns NULL if no properties were found.
To free the memory allocated by this function, use
.PN XFree .
.LP
.PN XListProperties
can generate a
.PN BadWindow 
error.
.LP
.sp
To change a property of a given window, use
.PN XChangeProperty .
.IN "Property" "changing"
.IN "Property" "appending"
.IN "Property" "prepending"
.IN "Property" "replacing"
.IN "Property" "format"
.IN "Property" "type"
.IN "XChangeProperty" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XChProperty.f,v 1.1 88/02/26 09:58:33 mento Exp $
XChangeProperty\^(\^\fIdisplay\fP, \fIw\fP\^, \fIproperty\fP\^, \fItype\fP\^, \fIformat\fP\^, \fImode\fP\^, \fIdata\fP\^, \fInelements\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      Atom \fIproperty\fP\^, \fItype\fP\^;
.br
      int \fIformat\fP\^;
.br
      int \fImode\fP\^;
.br
      unsigned char *\fIdata\fP\^;
.br
      int \fInelements\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.ds Wi whose property you want to change
.\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
.IP \fIw\fP 1i
Specifies the window \*(Wi.
.\" $Header: property.a,v 1.2 88/04/05 15:19:43 mento Exp $
.IP \fIproperty\fP 1i
Specifies the property name.
.\" $Header: type.a,v 1.2 88/03/29 08:07:25 mento Exp $
.IP \fItype\fP 1i
Specifies the type of the property.
The X server does not interpret the type but simply
passes it back to an application that later calls 
.PN XGetWindowProperty .
.\" $Header: format.a,v 1.2 88/05/08 11:59:58 mento Exp $
.IP \fIformat\fP 1i
Specifies whether the data should be viewed as a list
of 8-bit, 16-bit, or 32-bit quantities.
Possible values are 8, 16, and 32.
This information allows the X server to correctly perform
byte-swap operations as necessary.
If the format is 16-bit or 32-bit,
you must explicitly cast your data pointer to an (unsigned char *) in the call
to 
.PN XChangeProperty .
.\" $Header: prop_mode.a,v 1.2 88/04/04 11:18:11 mento Exp $
.\" Changed name of this file to prop_mode.a on 1/13/87
.IP \fImode\fP 1i
Specifies the mode of the operation.
You can pass
.PN PropModeReplace ,
.PN PropModePrepend ,
or
.PN PropModeAppend .
.\" $Header: data1.a,v 1.1 88/02/26 10:06:15 mento Exp $
.IP \fIdata\fP 1i
Specifies the property data.
.\" $Header: nelements.a,v 1.2 88/05/08 12:00:41 mento Exp $
.IP \fInelements\fP 1i
Specifies the number of elements of the specified data format.
.\" End marker code here
.LP
.\" $Header: XChProperty.d,v 1.2 88/06/11 07:49:04 mento Exp $
The
.PN XChangeProperty
function alters the property for the specified window and
causes the X server to generate a
.PN PropertyNotify
event on that window.
.PN XChangeProperty
performs the following:
.IP \(bu 5
If mode is
.PN PropModeReplace ,
.PN XChangeProperty
discards the previous property value and stores the new data.
.IP \(bu 5
If mode is
.PN PropModePrepend
or
.PN PropModeAppend ,
.PN XChangeProperty
inserts the specified data before the beginning of the existing data
or onto the end of the existing data, respectively.
The type and format must match the existing property value,
or a
.PN BadMatch
error results.
If the property is undefined, 
it is treated as defined with the correct type and
format with zero-length data.
.LP
The lifetime of a property is not tied to the storing client.
Properties remain until explicitly deleted, until the window is destroyed,
or until the server resets.
For a discussion of what happens when the connection to the X server is closed,
see section 2.6. 
The maximum size of a property is server dependent and can vary dynamically
depending on the amount of memory the server has available.
(If there is insufficient space, a
.PN BadAlloc
error results.)
.LP
.PN XChangeProperty
can generate
.PN BadAlloc ,
.PN BadAtom ,
.PN BadMatch ,
.PN BadValue ,
and
.PN BadWindow 
errors.
.LP
.sp
To rotate a window's property list, use
.PN XRotateWindowProperties .
.LP
.IN "XRotateWindowProperties" "" "@DEF@"
.\" Start marker code here
.FD 0
XRotateWindowProperties\^(\^\fIdisplay\fP, \fIw\fP, \fIproperties\fP, \fInum_prop\fP, \fInpositions\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      Atom \fIproperties\fP\^[]\^;
.br
      int \fInum_prop\fP\^;
.br
      int \fInpositions\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" $Header: properties.a,v 1.1 88/02/26 10:30:43 mento Exp $
.IP \fIproperties\fP 1i
Specifies the array of properties that are to be rotated.
.IP \fInum_prop\fP 1i
Specifies the length of the properties array.
.IP \fInpositions\fP 1i
Specifies the rotation amount.
.\" End marker code here
.LP
.\" $Header: XRotProp.d,v 1.3 88/06/11 07:52:52 mento Exp $
The
.PN XRotateWindowProperties
function allows you to rotate properties on a window and causes
the X server to generate
.PN PropertyNotify
events.
If the property names in the properties array are viewed as being numbered 
starting from zero and if there are num_prop property names in the list,
then the value associated with property name I becomes the value associated 
with property name (I + npositions) mod N for all I from zero to N \- 1.
The effect is to rotate the states by npositions places around the virtual ring
of property names (right for positive npositions, 
left for negative npositions).
If npositions mod N is nonzero,
the X server generates a
.PN PropertyNotify
event for each property in the order that they are listed in the array.
If an atom occurs more than once in the list or no property with that 
name is defined for the window,
a 
.PN BadMatch 
error results.
If a 
.PN BadAtom 
or 
.PN BadMatch 
error results,
no properties are changed.
.LP
.PN XRotateWindowProperties
can generate
.PN BadAtom ,
.PN BadMatch ,
and
.PN BadWindow 
errors.
.LP
.sp
To delete a property on a given window, use 
.PN XDeleteProperty .
.IN "Property" "deleting"
.IN "XDeleteProperty" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XDeleteProp.f,v 1.1 88/02/26 09:59:36 mento Exp $
XDeleteProperty\^(\^\fIdisplay\fP, \fIw\fP\^, \fIproperty\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      Atom \fIproperty\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.ds Wi whose property you want to delete
.\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
.IP \fIw\fP 1i
Specifies the window \*(Wi.
.\" $Header: property.a,v 1.2 88/04/05 15:19:43 mento Exp $
.IP \fIproperty\fP 1i
Specifies the property name.
.\" End marker code here
.LP
.\" $Header: XDeleteProp.d,v 1.2 88/05/08 12:07:50 mento Exp $
The
.PN XDeleteProperty
function deletes the specified property only if the
property was defined on the specified window
and causes the X server to generate a
.PN PropertyNotify
event on the window unless the property does not exist.
.LP
.PN XDeleteProperty
can generate
.PN BadAtom
and
.PN BadWindow 
errors.
.NH 2
Selections
.XS
\*(SN Selections
.XE
.LP
.IN "Selection"
Selections are one method used by applications to exchange data.
By using the property mechanism,
applications can exchange data of arbitrary types and can negotiate
the type of the data.
A selection can be thought of as an indirect property with a dynamic type.
That is, rather than having the property stored in the X server,
the property is maintained by some client (the owner).
A selection is global in nature (considered to belong to the user 
but be maintained by clients) rather than being private to a particular 
window subhierarchy or a particular set of clients.
.LP
Xlib provides functions that you can use to set, get, or request conversion
of selections.
This allows applications to implement the notion of current selection,
which requires that notification be sent to applications when they no 
longer own the selection.
Applications that support selection often highlight the current selection
and so must be informed when another application has
acquired the selection so that they can unhighlight the selection.
.LP
When a client asks for the contents of
a selection, it specifies a selection target type.
This target type
can be used to control the transmitted representation of the contents.
For example, if the selection is ``the last thing the user clicked on''
and that is currently an image, then the target type might specify
whether the contents of the image should be sent in XY format or Z format.
.LP
The target type can also be used to control the class of
contents transmitted, for example, 
asking for the ``looks'' (fonts, line
spacing, indentation, and so forth) of a paragraph selection, not the
text of the paragraph.
The target type can also be used for other
purposes.
The protocol does not constrain the semantics.
.LP
.sp
To set the selection owner, use 
.PN XSetSelectionOwner .
.IN "Selection" "setting the owner"
.IN "XSetSelectionOwner" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XSetSelOwner.f,v 1.1 88/02/26 10:03:38 mento Exp $
XSetSelectionOwner\^(\^\fIdisplay\fP, \fIselection\fP\^, \fIowner\fP\^, \fItime\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Atom \fIselection\fP\^;
.br
      Window \fIowner\fP\^; 
.br
      Time \fItime\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: selection.a,v 1.1 88/02/26 10:31:11 mento Exp $
.IP \fIselection\fP 1i
Specifies the selection atom.
.\" $Header: owner.a,v 1.2 88/05/08 12:15:34 mento Exp $
.IP \fIowner\fP 1i
Specifies the owner of the specified selection atom.
You can pass a window or
.PN None .
.IP \fItime\fP 1i
Specifies the time.
You can pass either a timestamp or
.PN CurrentTime .
.\" End marker code here
.LP
.\" $Header: XSetSelOwner.d,v 1.3 88/06/11 07:53:34 mento Exp $
The
.PN XSetSelectionOwner
function changes the owner and last-change time for the specified selection
and has no effect if the specified time is earlier than the current
last-change time of the specified selection 
or is later than the current X server time.
Otherwise, the last-change time is set to the specified time,
with
.PN CurrentTime
replaced by the current server time.
If the owner window is specified as
.PN None ,
then the owner of the selection becomes 
.PN None
(that is, no owner).
Otherwise, the owner of the selection becomes the client executing
the request.
.LP 
If the new owner (whether a client or
.PN None )
is not
the same as the current owner of the selection and the current
owner is not
.PN None ,
the current owner is sent a 
.PN SelectionClear 
event.
If the client that is the owner of a selection is later
terminated (that is, its connection is closed)
or if the owner window it has specified in the request is later
destroyed,
the owner of the selection automatically
reverts to
.PN None ,
but the last-change time is not affected.
The selection atom is uninterpreted by the X server.
.PN XGetSelectionOwner
returns the owner window, which is reported in 
.PN SelectionRequest
and
.PN SelectionClear
events.
Selections are global to the X server.
.LP
.PN XSetSelectionOwner
can generate
.PN BadAtom
and
.PN BadWindow 
errors.
.LP
.sp
To return the selection owner, use 
.PN XGetSelectionOwner .
.IN "Selection" "getting the owner"
.IN "XGetSelectionOwner" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XGetSelOwner.f,v 1.1 88/02/26 10:00:59 mento Exp $
Window XGetSelectionOwner\^(\^\fIdisplay\fP, \fIselection\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Atom \fIselection\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.ds Se whose owner you want returned
.\" $Header: select_gen.a,v 1.2 88/08/04 11:20:01 mento Exp $
.IP \fIselection\fP 1i
Specifies the selection atom \*(Se.
.\" End marker code here
.LP
.\" $Header: XGetSelOwner.d,v 1.2 88/06/11 07:51:28 mento Exp $
The
.PN XGetSelectionOwner
function
returns the window ID associated with the window that currently owns the
specified selection.
If no selection was specified, the function returns the constant
.PN None .
If
.PN None
is returned,
there is no owner for the selection.
.LP
.PN XGetSelectionOwner
can generate a
.PN BadAtom 
error.
.LP
.sp
To request conversion of a selection, use 
.PN XConvertSelection .
.IN "Selection" "converting"
.IN "XConvertSelection" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XConvertSel.f,v 1.1 88/02/26 09:58:58 mento Exp $
XConvertSelection\^(\^\fIdisplay\fP, \fIselection\fP\^, \fItarget\fP\^, \fIproperty\fP\^, \fIrequestor\fP\^, \fItime\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Atom \fIselection\fP\^, \fItarget\fP\^;
.br
      Atom \fIproperty\fP\^;
.br
      Window \fIrequestor\fP\^;
.br
      Time \fItime\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: selection.a,v 1.1 88/02/26 10:31:11 mento Exp $
.IP \fIselection\fP 1i
Specifies the selection atom.
.\" $Header: target.a,v 1.1 88/02/26 10:31:37 mento Exp $
.IP \fItarget\fP 1i
Specifies the target atom.
.\" $Header: property.a,v 1.2 88/04/05 15:19:43 mento Exp $
.IP \fIproperty\fP 1i
Specifies the property name.
You also can pass 
.PN None .
.\" $Header: requestor.a,v 1.1 88/02/26 10:30:53 mento Exp $
.IP \fIrequestor\fP 1i
Specifies the requestor.
.IP \fItime\fP 1i
Specifies the time.
You can pass either a timestamp or
.PN CurrentTime .
.\" End marker code here
.LP
.\" $Header: XConvertSel.d,v 1.3 88/05/08 12:25:35 mento Exp $
.PN XConvertSelection
requests that the specified selection be converted to the specified target
type:
.IP \(bu 5
If the specified selection has an owner, the X server sends a
.PN SelectionRequest
event to that owner.
.IP \(bu 5
If no owner for the specified
selection exists, the X server generates a
.PN SelectionNotify
event to the
requestor with property
.PN None .
.LP
The arguments are passed on unchanged in either of the events.
There are two predefined selection atoms: PRIMARY and SECONDARY.
.LP
.PN XConvertSelection
can generate
.PN BadAtom
and
.PN BadWindow 
errors.
.bp