diff options
Diffstat (limited to 'libX11/specs/libX11/CH04')
| -rw-r--r-- | libX11/specs/libX11/CH04 | 1595 |
1 files changed, 0 insertions, 1595 deletions
diff --git a/libX11/specs/libX11/CH04 b/libX11/specs/libX11/CH04 deleted file mode 100644 index b964198c2..000000000 --- a/libX11/specs/libX11/CH04 +++ /dev/null @@ -1,1595 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBChapter 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 |