diff options
Diffstat (limited to 'libX11/specs/libX11/CH04')
| -rw-r--r-- | libX11/specs/libX11/CH04 | 1595 |
1 files changed, 1595 insertions, 0 deletions
diff --git a/libX11/specs/libX11/CH04 b/libX11/specs/libX11/CH04 new file mode 100644 index 000000000..b964198c2 --- /dev/null +++ b/libX11/specs/libX11/CH04 @@ -0,0 +1,1595 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 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@" +.sM +.FD 0 +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 +.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 +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.IP \fIroot_return\fP 1i +Returns the root window. +.IP \fIparent_return\fP 1i +Returns the parent window. +.IP \fIchildren_return\fP 1i +Returns the list of children. +.IP \fInchildren_return\fP 1i +Returns the number of children. +.LP +.eM +The +.PN XQueryTree +function returns the root ID, the parent window ID, +a pointer to the list of children windows +(NULL when there are no children), +and the number of children in the list for the specified window. +The children are listed in current stacking order, from bottom-most +(first) to top-most (last). +.PN XQueryTree +returns zero if it fails and nonzero if it succeeds. +To free a non-NULL children 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@" +.sM +.FD 0 +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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi whose current attributes you want to obtain +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.IP \fIwindow_attributes_return\fP 1i +Returns the specified window's attributes in the +.PN XWindowAttributes +structure. +.LP +.eM +The +.PN XGetWindowAttributes +function returns the current attributes for the specified window to an +.PN XWindowAttributes +structure. +.LP +.IN "XWindowAttributes" "" "@DEF@" +.sM +.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 +.LP +.eM +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.2.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@" +.sM +.FD 0 +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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Dr , which can be a window or a pixmap +.IP \fId\fP 1i +Specifies the drawable\*(Dr. +.IP \fIroot_return\fP 1i +Returns the root window. +.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). +.LP +.eM +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 avoid 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@" +.sM +.FD 0 +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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIsrc_w\fP 1i +Specifies the source window. +.IP \fIdest_w\fP 1i +Specifies the destination window. +.IP \fIsrc_x\fP 1i +.br +.ns +.IP \fIsrc_y\fP 1i +Specify the x and y coordinates within the source window. +.IP \fIdest_x_return\fP 1i +.br +.ns +.IP \fIdest_y_return\fP 1i +Return the x and y coordinates within the destination window. +.IP \fIchild_return\fP 1i +Returns the child if the coordinates are contained in a mapped child of the +destination window. +.LP +.eM +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@" +.sM +.FD 0 +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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.ds Ro that the pointer is in +.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. +.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. +.IP \fIwin_x_return\fP 1i +.br +.ns +.IP \fIwin_y_return\fP 1i +Return the pointer coordinates relative to the specified window. +.IP \fImask_return\fP 1i +Returns the current state of the modifier keys and pointer buttons. +.LP +.eM +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 +.hN X11/Xatom.h . +To avoid name clashes with user symbols, the +.PN #define +name for each atom has the XA_ prefix. +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 WM_ZOOM_HINTS +.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@" +.sM +.FD 0 +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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIatom_name\fP 1i +Specifies the name associated with the atom you want returned. +.IP \fIonly_if_exists\fP 1i +Specifies a Boolean value that indicates whether the atom must be created. +.LP +.eM +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. +Uppercase and lowercase matter; +the strings ``thing'', ``Thing'', and ``thinG'' +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 atoms for an array of names, use +.PN XInternAtoms . +.IN "Atom" "interning" +.IN "XInternAtoms" "" "@DEF@" +.sM +.FD 0 +Status XInternAtoms\^(\^\fIdisplay\fP, \fInames\fP\^, \fIcount\fP\^, \fIonly_if_exists\fP, \fIatoms_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char **\fInames\fP\^; +.br + int \fIcount\fP\^; +.br + Bool \fIonly_if_exists\fP\^; +.br + Atom *\fIatoms_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fInames\fP 1i +Specifies the array of atom names. +.ds Cn atom names in the array +.IP \fIcount\fP 1i +Specifies the number of \*(Cn. +.IP \fIonly_if_exists\fP 1i +Specifies a Boolean value that indicates whether the atom must be created. +.IP \fIatoms_return\fP 1i +Returns the atoms. +.LP +.eM +The +.PN XInternAtoms +function returns the atom identifiers associated with the specified names. +The atoms are stored in the atoms_return array supplied by the caller. +Calling this function is equivalent to calling +.PN XInternAtom +for each of the names in turn with the specified value of only_if_exists, +but this function minimizes the number of round-trip protocol exchanges +between the client and the X server. +.LP +This function returns a nonzero status if atoms are returned for +all of the names; +otherwise, it returns zero. +.LP +.PN XInternAtoms +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@" +.sM +.FD 0 +char *XGetAtomName\^(\^\fIdisplay\fP, \fIatom\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Atom \fIatom\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIatom\fP 1i +Specifies the atom for the property name you want returned. +.LP +.eM +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. +.LP +.sp +To return the names for an array of atom identifiers, use +.PN XGetAtomNames . +.IN "Atom" "getting name" +.IN "XGetAtomNames" "" "@DEF@" +.sM +.FD 0 +Status XGetAtomNames\^(\^\fIdisplay\fP, \fIatoms\fP, \fIcount\fP\^, \fInames_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Atom *\fIatoms\fP\^; +.br + int \fIcount\fP\^; +.br + char **\fInames_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIatoms\fP 1i +Specifies the array of atoms. +.ds Cn atoms in the array +.IP \fIcount\fP 1i +Specifies the number of \*(Cn. +.IP \fInames_return\fP 1i +Returns the atom names. +.LP +.eM +The +.PN XGetAtomNames +function returns the names associated with the specified atoms. +The names are stored in the names_return array supplied by the caller. +Calling this function is equivalent to calling +.PN XGetAtomName +for each of the atoms in turn, +but this function minimizes the number of round-trip protocol exchanges +between the client and the X server. +.LP +This function returns a nonzero status if names are returned for +all of the atoms; +otherwise, it returns zero. +.LP +.PN XGetAtomNames +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. The type +.PN char +is used to represent 8-bit quantities, the type +.PN short +is used to represent 16-bit quantities, and the type +.PN long +is used to represent 32-bit quantities. +.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@" +.sM +.FD 0 +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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi whose property you want to obtain +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.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. +.IP \fIdelete\fP 1i +Specifies a Boolean value that determines whether the property is deleted. +.IP \fIreq_type\fP 1i +Specifies the atom identifier associated with the property type or +.PN AnyPropertyType . +.IP \fIactual_type_return\fP 1i +Returns the atom identifier that defines the actual type of the property. +.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. +.LP +.eM +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 +If the returned format is 8, the returned data is represented as a +.PN char +array. +If the returned format is 16, the returned data is represented as a +.PN short +array and should be cast to that type to obtain the elements. +If the returned format is 32, the returned data is represented as a +.PN long +array and should be cast to that type to obtain the elements. +.LP +.PN XGetWindowProperty +always allocates one extra byte in prop_return +(even if the property is zero length) +and sets it to zero so that simple properties consisting of characters +do not have to be copied into yet another string before use. +.LP +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@" +.sM +.FD 0 +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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi whose property list you want to obtain +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.IP \fInum_prop_return\fP 1i +Returns the length of the properties array. +.LP +.eM +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@" +.sM +.FD 0 +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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi whose property you want to change +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.IP \fIproperty\fP 1i +Specifies the property name. +.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 . +.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 . +.\" 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 . +.IP \fIdata\fP 1i +Specifies the property data. +.IP \fInelements\fP 1i +Specifies the number of elements of the specified data format. +.LP +.eM +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 +If the specified format is 8, the property data must be a +.PN char +array. +If the specified format is 16, the property data must be a +.PN short +array. +If the specified format is 32, the property data must be a +.PN long +array. +.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@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.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. +.LP +.eM +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@" +.sM +.FD 0 +XDeleteProperty\^(\^\fIdisplay\fP, \fIw\fP\^, \fIproperty\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Atom \fIproperty\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi whose property you want to delete +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.IP \fIproperty\fP 1i +Specifies the property name. +.LP +.eM +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@" +.sM +.FD 0 +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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIselection\fP 1i +Specifies the selection atom. +.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 . +.LP +.eM +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@" +.sM +.FD 0 +Window XGetSelectionOwner\^(\^\fIdisplay\fP, \fIselection\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Atom \fIselection\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Se whose owner you want returned +.IP \fIselection\fP 1i +Specifies the selection atom \*(Se. +.LP +.eM +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@" +.sM +.FD 0 +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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIselection\fP 1i +Specifies the selection atom. +.IP \fItarget\fP 1i +Specifies the target atom. +.IP \fIproperty\fP 1i +Specifies the property name. +You also can pass +.PN None . +.IP \fIrequestor\fP 1i +Specifies the requestor. +.IP \fItime\fP 1i +Specifies the time. +You can pass either a timestamp or +.PN CurrentTime . +.LP +.eM +.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 |