From 8fd06c45853cb2300105db84e4b722f0e2dad8d2 Mon Sep 17 00:00:00 2001 From: marha Date: Wed, 22 Dec 2010 13:20:05 +0000 Subject: xserver libX11 libXdmcp pixman git update 22-12-2010 --- libX11/specs/libX11/CH04.xml | 5020 +++++++++++++++++++++--------------------- 1 file changed, 2510 insertions(+), 2510 deletions(-) (limited to 'libX11/specs') diff --git a/libX11/specs/libX11/CH04.xml b/libX11/specs/libX11/CH04.xml index 0469b2cde..8a3e8c535 100644 --- a/libX11/specs/libX11/CH04.xml +++ b/libX11/specs/libX11/CH04.xml @@ -1,2510 +1,2510 @@ - - - -Window Information Functions - - -After you connect the display to the X server and create a window, you can use the Xlib window -information functions to: - - - Obtain information about a window - Translate screen coordinates - Manipulate property lists - Obtain and change window properties - Manipulate selections - - - -Obtaining Window Information - - - - - -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. - - - - -To obtain the parent, a list of children, and number of children for -a given window, use -XQueryTree. -Child Window -Parent Window -XQueryTree - - - - Status XQueryTree - Display *display - Window w - Window *root_return - Window *parent_return - Window **children_return - unsignedint *nchildren_return - - - - - - - display - - - -Specifies the connection to the X server. - -you want to obtain - - - - - - w - - - -Specifies the window (Wi. - - - - - - root_return - - - -Returns the root window. - - - - - - parent_return - - - -Returns the parent window. - - - - - - children_return - - - -Returns the list of children. - - - - - - nchildren_return - - - -Returns the number of children. - - - - - - - - -The -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). -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 -XFree. - - - -XQueryTree -can generate a -BadWindow -error. - - - - -To obtain the current attributes of a given window, use -XGetWindowAttributes. -XGetWindowAttributes - - - - Status XGetWindowAttributes - Display *display - Window w - XWindowAttributes *window_attributes_return - - - - - - - display - - - -Specifies the connection to the X server. - - - - - - - w - - - -Specifies the window (Wi. - - - - - - window_attributes_return - - - -Returns the specified window's attributes in the -XWindowAttributes -structure. - - - - - - - - -The -XGetWindowAttributes -function returns the current attributes for the specified window to an -XWindowAttributes -structure. - - - -XWindowAttributes - - - - -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; - - - - - -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 -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 -InputOutput -or -InputOnly. - - - -The bit_gravity member is set to the window's bit gravity -and can be one of the following: - - ForgetGravity - NorthWestGravity - NorthGravity - NorthEastGravity - WestGravity - - EastGravity - SouthWestGravity - SouthGravity - SouthEastGravity - StaticGravity - - - -The win_gravity member is set to the window's window gravity -and can be one of the following: - - UnmapGravity - NorthWestGravity - NorthGravity - NorthEastGravity - WestGravity - - EastGravity - SouthWestGravity - SouthGravity - SouthEastGravity - StaticGravity - CenterGravity - - - - -For additional information on gravity, -see section 3.2.3. - - - -The backing_store member is set to indicate how the X server should maintain -the contents of a window -and can be -WhenMapped, -Always, -or -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. - - - -The save_under member is set to -True -or -False. -The colormap member is set to the colormap for the specified window and can be -a colormap ID or -None. -The map_installed member is set to indicate whether the colormap is -currently installed and can be -True -or -False. -The map_state member is set to indicate the state of the window and can be -IsUnmapped, -IsUnviewable, -or -IsViewable. -IsUnviewable -is used if the window is mapped but some ancestor is unmapped. - - - -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. - - - -The override_redirect member is set to indicate whether this window overrides -structure control facilities and can be -True -or -False. -Window manager clients should ignore the window if this member is -True. - - - -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. - - - -XGetWindowAttributes -can generate -BadDrawable -and -BadWindow -errors. - - - - -To obtain the current geometry of a given drawable, use -XGetGeometry. -XGetGeometry - - - - Status XGetGeometry - Display *display - Drawable d - Window *root_return - int*x_return, *y_return - unsignedint*width_return, *height_return - unsignedint *border_width_return - unsignedint *depth_return - - - - - - - display - - - -Specifies the connection to the X server. - - - - - - - d - - - -Specifies the drawable(Dr. - - - - - - root_return - - - -Returns the root window. - - - - - - x_return - - - - - - - - - - - y_return - - - -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. - - - - - - width_return - - - - - - - - - - - height_return - - - -Return the drawable's dimensions (width and height). -For a window, -these dimensions specify the inside size, not including the border. - - - - - - border_width_return - - - -Returns the border width in pixels. -If the drawable is a pixmap, it returns zero. - - - - - - depth_return - - - -Returns the depth of the drawable (bits per pixel for the object). - - - - - - - - -The -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 -InputOnly. - - - -XGetGeometry -can generate a -BadDrawable -error. - - - -Translating Screen Coordinates - - - - - -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. -XTranslateCoordinates -and -XQueryPointer -fulfill these needs (and avoid any race conditions) by -asking the X server to perform these operations. - - - - -To translate a coordinate in one window to the coordinate -space of another window, use -XTranslateCoordinates. -XTranslateCoordinates - - - - Bool XTranslateCoordinates - Display *display - Windowsrc_w, dest_w - intsrc_x, src_y - int*dest_x_return, *dest_y_return - Window *child_return - - - - - - - display - - - -Specifies the connection to the X server. - - - - - - src_w - - - -Specifies the source window. - - - - - - dest_w - - - -Specifies the destination window. - - - - - - src_x - - - - - - - - - - - src_y - - - -Specify the x and y coordinates within the source window. - - - - - - dest_x_return - - - - - - - - - - - dest_y_return - - - -Return the x and y coordinates within the destination window. - - - - - - child_return - - - -Returns the child if the coordinates are contained in a mapped child of the -destination window. - - - - - - - - -If -XTranslateCoordinates -returns -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 -XTranslateCoordinates -returns -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 -None. - - - -XTranslateCoordinates -can generate a -BadWindow -error. - - - - -To obtain the screen coordinates of the pointer -or to determine the pointer coordinates relative to a specified window, use -XQueryPointer. -XQueryPointer - - - - Bool XQueryPointer - Display *display - Window w - Window*root_return, *child_return - int*root_x_return, *root_y_return - int*win_x_return, *win_y_return - unsignedint *mask_return - - - - - - - display - - - -Specifies the connection to the X server. - - - - - - w - - - -Specifies the window. - - - - - - - root_return - - - -Returns the root window (Ro. - - - - - - child_return - - - -Returns the child window that the pointer is located in, if any. - - - - - - root_x_return - - - - - - - - - - - root_y_return - - - -Return the pointer coordinates relative to the root window's origin. - - - - - - win_x_return - - - - - - - - - - - win_y_return - - - -Return the pointer coordinates relative to the specified window. - - - - - - mask_return - - - -Returns the current state of the modifier keys and pointer buttons. - - - - - - - - -The -XQueryPointer -function returns the root window the pointer is logically on and the pointer -coordinates relative to the root window's origin. -If -XQueryPointer -returns -False, -the pointer is not on the same screen as the specified window, and -XQueryPointer -returns -None -to child_return and zero to win_x_return and win_y_return. -If -XQueryPointer -returns -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, -XQueryPointer -returns the child that contains the pointer, if any, -or else -None -to child_return. - - - -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. - - - -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). - - - -XQueryPointer -can generate a -BadWindow -error. - - - -Properties and Atoms - - - - - -A property is a collection of named, typed data. -The window system has a set of predefined properties -Atompredefined -(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. -XInternAtom -can be used to obtain the atom for property names. -Atom - - - -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. - -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. - -The type of a property is defined by an atom, which allows for -arbitrary extension in this type scheme. -Atom - - - -Certain property names are -predefined in the server for commonly used functions. -The atoms for these properties are defined in -<X11/Xatom.h>. -X11/Xatom.h -Files<X11/Xatom.h> -Headers<X11/Xatom.h> -To avoid name clashes with user symbols, the -#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. - - - -The core protocol imposes no semantics on these property names, -but semantics are specified in other X Consortium standards, -such as the Inter-Client Communication Conventions Manual -and the X Logical Font Description Conventions. - - - -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. - - - -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: - - - - -Selections - - - - -Property names - - - - -Property types - - - - -Font properties - - - - -Type of a -ClientMessage -event (none are built into the X server) - - - - - - - - -The built-in selection property names are: - - PRIMARY - SECONDARY - - - - -The built-in property names are: - - CUT_BUFFER0 - CUT_BUFFER1 - CUT_BUFFER2 - CUT_BUFFER3 - CUT_BUFFER4 - CUT_BUFFER5 - CUT_BUFFER6 - CUT_BUFFER7 - RGB_BEST_MAP - RGB_BLUE_MAP - RGB_DEFAULT_MAP - RGB_GRAY_MAP - RGB_GREEN_MAP - RGB_RED_MAP - - RESOURCE_MANAGER - WM_CLASS - WM_CLIENT_MACHINE - WM_COLORMAP_WINDOWS - WM_COMMAND - WM_HINTS - WM_ICON_NAME - WM_ICON_SIZE - WM_NAME - WM_NORMAL_HINTS - WM_PROTOCOLS - WM_STATE - WM_TRANSIENT_FOR - WM_ZOOM_HINTS - - - -The built-in property types are: - - ARC - ATOM - BITMAP - CARDINAL - COLORMAP - CURSOR - DRAWABLE - FONT - INTEGER - PIXMAP - POINT - RGB_COLOR_MAP - RECTANGLE - STRING - VISUALID - WINDOW - WM_HINTS - WM_SIZE_HINTS - - - -The built-in font property names are: - - MIN_SPACE - NORM_SPACE - MAX_SPACE - END_SPACE - SUPERSCRIPT_X - SUPERSCRIPT_Y - SUBSCRIPT_X - SUBSCRIPT_Y - UNDERLINE_POSITION - UNDERLINE_THICKNESS - FONT_NAME - FULL_NAME - - STRIKEOUT_DESCENT - STRIKEOUT_ASCENT - ITALIC_ANGLE - X_HEIGHT - QUAD_WIDTH - WEIGHT - POINT_SIZE - RESOLUTION - COPYRIGHT - NOTICE - FAMILY_NAME - CAP_HEIGHT - - - - -For further information about font properties, -see section 8.5. - - - - -To return an atom for a given name, use -XInternAtom. -Atominterning -XInternAtom - - - - Atom XInternAtom - Display *display - const char *atom_name - Bool only_if_exists - - - - - - - display - - - -Specifies the connection to the X server. - - - - - - atom_name - - - -Specifies the name associated with the atom you want returned. - - - - - - only_if_exists - - - -Specifies a Boolean value that indicates whether the atom must be created. - - - - - - - - -The -XInternAtom -function returns the atom identifier associated with the specified atom_name -string. -If only_if_exists is -False, -the atom is created if it does not exist. -Therefore, -XInternAtom -can return -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. - - - -XInternAtom -can generate -BadAlloc -and -BadValue -errors. - - - - -To return atoms for an array of names, use -XInternAtoms. -Atominterning -XInternAtoms - - - - Status XInternAtoms - Display *display - const char **names - int count - Bool only_if_exists - Atom *atoms_return - - - - - - - display - - - -Specifies the connection to the X server. - - - - - - names - - - -Specifies the array of atom names. - - - - - - - count - - - -Specifies the number of (Cn. - - - - - - only_if_exists - - - -Specifies a Boolean value that indicates whether the atom must be created. - - - - - - atoms_return - - - -Returns the atoms. - - - - - - - - -The -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 -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. - - - -This function returns a nonzero status if atoms are returned for -all of the names; -otherwise, it returns zero. - - - -XInternAtoms -can generate -BadAlloc -and -BadValue -errors. - - - - -To return a name for a given atom identifier, use -XGetAtomName. -Atomgetting name -XGetAtomName - - - - char *XGetAtomName - Display *display - Atom atom - - - - - - - display - - - -Specifies the connection to the X server. - - - - - - atom - - - -Specifies the atom for the property name you want returned. - - - - - - - - -The -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 -XFree. - - - -XGetAtomName -can generate a -BadAtom -error. - - - - -To return the names for an array of atom identifiers, use -XGetAtomNames. -Atomgetting name -XGetAtomNames - - - - Status XGetAtomNames - Display *display - Atom *atoms - int count - char **names_return - - - - - - - display - - - -Specifies the connection to the X server. - - - - - - atoms - - - -Specifies the array of atoms. - - - - - - - count - - - -Specifies the number of (Cn. - - - - - - names_return - - - -Returns the atom names. - - - - - - - - -The -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 -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. - - - -This function returns a nonzero status if names are returned for -all of the atoms; -otherwise, it returns zero. - - - -XGetAtomNames -can generate a -BadAtom -error. - - - -Obtaining and Changing Window Properties - - - - - -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 -char -is used to represent 8-bit quantities, the type -short -is used to represent 16-bit quantities, and the type -long -is used to represent 32-bit quantities. - - - -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). - - - - -To obtain the type, format, and value of a property of a given window, use -XGetWindowProperty. -Propertygetting - - - -XGetWindowProperty - - - - int XGetWindowProperty - display - w - property - long_offset - long_length - delete - req_type - actual_type_return - actual_format_return - nitems_return - bytes_after_return - .br prop_return - - - - - - - display - - - -Specifies the connection to the X server. - - - - - - - w - - - -Specifies the window (Wi. - - - - - - property - - - -Specifies the property name. - - - - - - long_offset - - - -Specifies the offset in the specified property (in 32-bit quantities) -where the data is to be retrieved. - - - - - - long_length - - - -Specifies the length in 32-bit multiples of the data to be retrieved. - - - - - - delete - - - -Specifies a Boolean value that determines whether the property is deleted. - - - - - - req_type - - - -Specifies the atom identifier associated with the property type or -AnyPropertyType. - - - - - - actual_type_return - - - -Returns the atom identifier that defines the actual type of the property. - - - - - - actual_format_return - - - -Returns the actual format of the property. - - - - - - nitems_return - - - -Returns the actual number of 8-bit, 16-bit, or 32-bit items -stored in the prop_return data. - - - - - - bytes_after_return - - - -Returns the number of bytes remaining to be read in the property if -a partial read was performed. - - - - - - prop_return - - - -Returns the data in the specified format. - - - - - - - - -The -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. -XGetWindowProperty -sets the return arguments as follows: - - - - -If the specified property does not exist for the specified window, -XGetWindowProperty -returns -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. - - - - -If the specified property exists -but its type does not match the specified type, -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. - - - - -If the specified property exists and either you assign -AnyPropertyType -to the req_type argument or the specified type matches the actual property type, -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: - - - - - - 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) - - - - - -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 -BadValue -error results. -The value of bytes_after_return is A, -giving the number of trailing unread bytes in the stored property. - - - - - -If the returned format is 8, the returned data is represented as a -char -array. -If the returned format is 16, the returned data is represented as a -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 -long -array and should be cast to that type to obtain the elements. - - - -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. - - - -If delete is -True -and bytes_after_return is zero, -XGetWindowProperty -deletes the property -from the window and generates a -PropertyNotify -event on the window. - - - -The function returns -Success -if it executes successfully. -To free the resulting data, -use -XFree. - - - -XGetWindowProperty -can generate -BadAtom, -BadValue, -and -BadWindow -errors. - - - - -To obtain a given window's property list, use -XListProperties. -Propertylisting -XListProperties - - - - Atom *XListProperties - Display *display - Window w - int *num_prop_return - - - - - - - display - - - -Specifies the connection to the X server. - - - - - - - w - - - -Specifies the window (Wi. - - - - - - num_prop_return - - - -Returns the length of the properties array. - - - - - - - - -The -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 -XFree. - - - -XListProperties -can generate a -BadWindow -error. - - - - -To change a property of a given window, use -XChangeProperty. -Propertychanging -Propertyappending -Propertyprepending -Propertyreplacing -Propertyformat -Propertytype -XChangeProperty - - - - XChangeProperty - Display *display - Window w - Atomproperty, type - int format - int mode - unsignedchar *data - int nelements - - - - - - - display - - - -Specifies the connection to the X server. - - - - - - - w - - - -Specifies the window (Wi. - - - - - - property - - - -Specifies the property name. - - - - - - type - - - -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 -XGetWindowProperty. - - - - - - format - - - -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 -XChangeProperty. - - - - - - - mode - - - -Specifies the mode of the operation. -You can pass -PropModeReplace, -PropModePrepend, -or -PropModeAppend. - - - - - - data - - - -Specifies the property data. - - - - - - nelements - - - -Specifies the number of elements of the specified data format. - - - - - - - - -The -XChangeProperty -function alters the property for the specified window and -causes the X server to generate a -PropertyNotify -event on that window. -XChangeProperty -performs the following: - - - - -If mode is -PropModeReplace, -XChangeProperty -discards the previous property value and stores the new data. - - - - -If mode is -PropModePrepend -or -PropModeAppend, -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 -BadMatch -error results. -If the property is undefined, -it is treated as defined with the correct type and -format with zero-length data. - - - - - -If the specified format is 8, the property data must be a -char -array. -If the specified format is 16, the property data must be a -short -array. -If the specified format is 32, the property data must be a -long -array. - - - -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 -BadAlloc -error results.) - - - -XChangeProperty -can generate -BadAlloc, -BadAtom, -BadMatch, -BadValue, -and -BadWindow -errors. - - - - -To rotate a window's property list, use -XRotateWindowProperties. - - - -XRotateWindowProperties - - - - XRotateWindowProperties - Display *display - Window w - Atom properties[] - int num_prop - int npositions - - - - - - - display - - - -Specifies the connection to the X server. - - - - - - w - - - -Specifies the window. - - - - - - properties - - - -Specifies the array of properties that are to be rotated. - - - - - - num_prop - - - -Specifies the length of the properties array. - - - - - - npositions - - - -Specifies the rotation amount. - - - - - - - - -The -XRotateWindowProperties -function allows you to rotate properties on a window and causes -the X server to generate -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 -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 -BadMatch -error results. -If a -BadAtom -or -BadMatch -error results, -no properties are changed. - - - -XRotateWindowProperties -can generate -BadAtom, -BadMatch, -and -BadWindow -errors. - - - - -To delete a property on a given window, use -XDeleteProperty. -Propertydeleting -XDeleteProperty - - - - XDeleteProperty - Display *display - Window w - Atom property - - - - - - - display - - - -Specifies the connection to the X server. - - - - - - - w - - - -Specifies the window (Wi. - - - - - - property - - - -Specifies the property name. - - - - - - - - -The -XDeleteProperty -function deletes the specified property only if the -property was defined on the specified window -and causes the X server to generate a -PropertyNotify -event on the window unless the property does not exist. - - - -XDeleteProperty -can generate -BadAtom -and -BadWindow -errors. - - - -Selections - - - - - -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. - - - -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. - - - -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. - - - -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. - - - - -To set the selection owner, use -XSetSelectionOwner. -Selectionsetting the owner -XSetSelectionOwner - - - - XSetSelectionOwner - Display *display - Atom selection - Window owner - Time time - - - - - - - display - - - -Specifies the connection to the X server. - - - - - - selection - - - -Specifies the selection atom. - - - - - - owner - - - -Specifies the owner of the specified selection atom. -You can pass a window or -None. - - - - - - time - - - -Specifies the time. -You can pass either a timestamp or -CurrentTime. - - - - - - - - -The -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 -CurrentTime -replaced by the current server time. -If the owner window is specified as -None, -then the owner of the selection becomes -None -(that is, no owner). -Otherwise, the owner of the selection becomes the client executing -the request. - - - -If the new owner (whether a client or -None) -is not -the same as the current owner of the selection and the current -owner is not -None, -the current owner is sent a -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 -None, -but the last-change time is not affected. -The selection atom is uninterpreted by the X server. -XGetSelectionOwner -returns the owner window, which is reported in -SelectionRequest -and -SelectionClear -events. -Selections are global to the X server. - - - -XSetSelectionOwner -can generate -BadAtom -and -BadWindow -errors. - - - - -To return the selection owner, use -XGetSelectionOwner. -Selectiongetting the owner -XGetSelectionOwner - - - - Window XGetSelectionOwner - Display *display - Atom selection - - - - - - - display - - - -Specifies the connection to the X server. - - - - - - - selection - - - -Specifies the selection atom (Se. - - - - - - - - -The -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 -None. -If -None -is returned, -there is no owner for the selection. - - - -XGetSelectionOwner -can generate a -BadAtom -error. - - - - -To request conversion of a selection, use -XConvertSelection. -Selectionconverting -XConvertSelection - - - - XConvertSelection - Display *display - Atomselection, target - Atom property - Window requestor - Time time - - - - - - - display - - - -Specifies the connection to the X server. - - - - - - selection - - - -Specifies the selection atom. - - - - - - target - - - -Specifies the target atom. - - - - - - property - - - -Specifies the property name. -You also can pass -None. - - - - - - requestor - - - -Specifies the requestor. - - - - - - time - - - -Specifies the time. -You can pass either a timestamp or -CurrentTime. - - - - - - - - -XConvertSelection -requests that the specified selection be converted to the specified target -type: - - - - -If the specified selection has an owner, the X server sends a -SelectionRequest -event to that owner. - - - - -If no owner for the specified -selection exists, the X server generates a -SelectionNotify -event to the -requestor with property -None. - - - - - -The arguments are passed on unchanged in either of the events. -There are two predefined selection atoms: PRIMARY and SECONDARY. - - - -XConvertSelection -can generate -BadAtom -and -BadWindow -errors. - - - - - - + + + +Window Information Functions + + +After you connect the display to the X server and create a window, you can use the Xlib window +information functions to: + + + Obtain information about a window + Translate screen coordinates + Manipulate property lists + Obtain and change window properties + Manipulate selections + + + +Obtaining Window Information + + + + + +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. + + + + +To obtain the parent, a list of children, and number of children for +a given window, use +XQueryTree. +Child Window +Parent Window +XQueryTree + + + + Status XQueryTree + Display *display + Window w + Window *root_return + Window *parent_return + Window **children_return + unsignedint *nchildren_return + + + + + + + display + + + +Specifies the connection to the X server. + +you want to obtain + + + + + + w + + + +Specifies the window (Wi. + + + + + + root_return + + + +Returns the root window. + + + + + + parent_return + + + +Returns the parent window. + + + + + + children_return + + + +Returns the list of children. + + + + + + nchildren_return + + + +Returns the number of children. + + + + + + + + +The +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). +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 +XFree. + + + +XQueryTree +can generate a +BadWindow +error. + + + + +To obtain the current attributes of a given window, use +XGetWindowAttributes. +XGetWindowAttributes + + + + Status XGetWindowAttributes + Display *display + Window w + XWindowAttributes *window_attributes_return + + + + + + + display + + + +Specifies the connection to the X server. + + + + + + + w + + + +Specifies the window (Wi. + + + + + + window_attributes_return + + + +Returns the specified window's attributes in the +XWindowAttributes +structure. + + + + + + + + +The +XGetWindowAttributes +function returns the current attributes for the specified window to an +XWindowAttributes +structure. + + + +XWindowAttributes + + + + +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; + + + + + +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 +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 +InputOutput +or +InputOnly. + + + +The bit_gravity member is set to the window's bit gravity +and can be one of the following: + + ForgetGravity + NorthWestGravity + NorthGravity + NorthEastGravity + WestGravity + + EastGravity + SouthWestGravity + SouthGravity + SouthEastGravity + StaticGravity + + + +The win_gravity member is set to the window's window gravity +and can be one of the following: + + UnmapGravity + NorthWestGravity + NorthGravity + NorthEastGravity + WestGravity + + EastGravity + SouthWestGravity + SouthGravity + SouthEastGravity + StaticGravity + CenterGravity + + + + +For additional information on gravity, +see section 3.2.3. + + + +The backing_store member is set to indicate how the X server should maintain +the contents of a window +and can be +WhenMapped, +Always, +or +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. + + + +The save_under member is set to +True +or +False. +The colormap member is set to the colormap for the specified window and can be +a colormap ID or +None. +The map_installed member is set to indicate whether the colormap is +currently installed and can be +True +or +False. +The map_state member is set to indicate the state of the window and can be +IsUnmapped, +IsUnviewable, +or +IsViewable. +IsUnviewable +is used if the window is mapped but some ancestor is unmapped. + + + +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. + + + +The override_redirect member is set to indicate whether this window overrides +structure control facilities and can be +True +or +False. +Window manager clients should ignore the window if this member is +True. + + + +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. + + + +XGetWindowAttributes +can generate +BadDrawable +and +BadWindow +errors. + + + + +To obtain the current geometry of a given drawable, use +XGetGeometry. +XGetGeometry + + + + Status XGetGeometry + Display *display + Drawable d + Window *root_return + int*x_return, *y_return + unsignedint*width_return, *height_return + unsignedint *border_width_return + unsignedint *depth_return + + + + + + + display + + + +Specifies the connection to the X server. + + + + + + + d + + + +Specifies the drawable(Dr. + + + + + + root_return + + + +Returns the root window. + + + + + + x_return + + + + + + + + + + + y_return + + + +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. + + + + + + width_return + + + + + + + + + + + height_return + + + +Return the drawable's dimensions (width and height). +For a window, +these dimensions specify the inside size, not including the border. + + + + + + border_width_return + + + +Returns the border width in pixels. +If the drawable is a pixmap, it returns zero. + + + + + + depth_return + + + +Returns the depth of the drawable (bits per pixel for the object). + + + + + + + + +The +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 +InputOnly. + + + +XGetGeometry +can generate a +BadDrawable +error. + + + +Translating Screen Coordinates + + + + + +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. +XTranslateCoordinates +and +XQueryPointer +fulfill these needs (and avoid any race conditions) by +asking the X server to perform these operations. + + + + +To translate a coordinate in one window to the coordinate +space of another window, use +XTranslateCoordinates. +XTranslateCoordinates + + + + Bool XTranslateCoordinates + Display *display + Windowsrc_w, dest_w + intsrc_x, src_y + int*dest_x_return, *dest_y_return + Window *child_return + + + + + + + display + + + +Specifies the connection to the X server. + + + + + + src_w + + + +Specifies the source window. + + + + + + dest_w + + + +Specifies the destination window. + + + + + + src_x + + + + + + + + + + + src_y + + + +Specify the x and y coordinates within the source window. + + + + + + dest_x_return + + + + + + + + + + + dest_y_return + + + +Return the x and y coordinates within the destination window. + + + + + + child_return + + + +Returns the child if the coordinates are contained in a mapped child of the +destination window. + + + + + + + + +If +XTranslateCoordinates +returns +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 +XTranslateCoordinates +returns +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 +None. + + + +XTranslateCoordinates +can generate a +BadWindow +error. + + + + +To obtain the screen coordinates of the pointer +or to determine the pointer coordinates relative to a specified window, use +XQueryPointer. +XQueryPointer + + + + Bool XQueryPointer + Display *display + Window w + Window*root_return, *child_return + int*root_x_return, *root_y_return + int*win_x_return, *win_y_return + unsignedint *mask_return + + + + + + + display + + + +Specifies the connection to the X server. + + + + + + w + + + +Specifies the window. + + + + + + + root_return + + + +Returns the root window (Ro. + + + + + + child_return + + + +Returns the child window that the pointer is located in, if any. + + + + + + root_x_return + + + + + + + + + + + root_y_return + + + +Return the pointer coordinates relative to the root window's origin. + + + + + + win_x_return + + + + + + + + + + + win_y_return + + + +Return the pointer coordinates relative to the specified window. + + + + + + mask_return + + + +Returns the current state of the modifier keys and pointer buttons. + + + + + + + + +The +XQueryPointer +function returns the root window the pointer is logically on and the pointer +coordinates relative to the root window's origin. +If +XQueryPointer +returns +False, +the pointer is not on the same screen as the specified window, and +XQueryPointer +returns +None +to child_return and zero to win_x_return and win_y_return. +If +XQueryPointer +returns +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, +XQueryPointer +returns the child that contains the pointer, if any, +or else +None +to child_return. + + + +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. + + + +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). + + + +XQueryPointer +can generate a +BadWindow +error. + + + +Properties and Atoms + + + + + +A property is a collection of named, typed data. +The window system has a set of predefined properties +Atompredefined +(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. +XInternAtom +can be used to obtain the atom for property names. +Atom + + + +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. + +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. + +The type of a property is defined by an atom, which allows for +arbitrary extension in this type scheme. +Atom + + + +Certain property names are +predefined in the server for commonly used functions. +The atoms for these properties are defined in +<X11/Xatom.h>. +X11/Xatom.h +Files<X11/Xatom.h> +Headers<X11/Xatom.h> +To avoid name clashes with user symbols, the +#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. + + + +The core protocol imposes no semantics on these property names, +but semantics are specified in other X Consortium standards, +such as the Inter-Client Communication Conventions Manual +and the X Logical Font Description Conventions. + + + +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. + + + +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: + + + + +Selections + + + + +Property names + + + + +Property types + + + + +Font properties + + + + +Type of a +ClientMessage +event (none are built into the X server) + + + + + + + + +The built-in selection property names are: + + PRIMARY + SECONDARY + + + + +The built-in property names are: + + CUT_BUFFER0 + CUT_BUFFER1 + CUT_BUFFER2 + CUT_BUFFER3 + CUT_BUFFER4 + CUT_BUFFER5 + CUT_BUFFER6 + CUT_BUFFER7 + RGB_BEST_MAP + RGB_BLUE_MAP + RGB_DEFAULT_MAP + RGB_GRAY_MAP + RGB_GREEN_MAP + RGB_RED_MAP + + RESOURCE_MANAGER + WM_CLASS + WM_CLIENT_MACHINE + WM_COLORMAP_WINDOWS + WM_COMMAND + WM_HINTS + WM_ICON_NAME + WM_ICON_SIZE + WM_NAME + WM_NORMAL_HINTS + WM_PROTOCOLS + WM_STATE + WM_TRANSIENT_FOR + WM_ZOOM_HINTS + + + +The built-in property types are: + + ARC + ATOM + BITMAP + CARDINAL + COLORMAP + CURSOR + DRAWABLE + FONT + INTEGER + PIXMAP + POINT + RGB_COLOR_MAP + RECTANGLE + STRING + VISUALID + WINDOW + WM_HINTS + WM_SIZE_HINTS + + + +The built-in font property names are: + + MIN_SPACE + NORM_SPACE + MAX_SPACE + END_SPACE + SUPERSCRIPT_X + SUPERSCRIPT_Y + SUBSCRIPT_X + SUBSCRIPT_Y + UNDERLINE_POSITION + UNDERLINE_THICKNESS + FONT_NAME + FULL_NAME + + STRIKEOUT_DESCENT + STRIKEOUT_ASCENT + ITALIC_ANGLE + X_HEIGHT + QUAD_WIDTH + WEIGHT + POINT_SIZE + RESOLUTION + COPYRIGHT + NOTICE + FAMILY_NAME + CAP_HEIGHT + + + + +For further information about font properties, +see section 8.5. + + + + +To return an atom for a given name, use +XInternAtom. +Atominterning +XInternAtom + + + + Atom XInternAtom + Display *display + char *atom_name + Bool only_if_exists + + + + + + + display + + + +Specifies the connection to the X server. + + + + + + atom_name + + + +Specifies the name associated with the atom you want returned. + + + + + + only_if_exists + + + +Specifies a Boolean value that indicates whether the atom must be created. + + + + + + + + +The +XInternAtom +function returns the atom identifier associated with the specified atom_name +string. +If only_if_exists is +False, +the atom is created if it does not exist. +Therefore, +XInternAtom +can return +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. + + + +XInternAtom +can generate +BadAlloc +and +BadValue +errors. + + + + +To return atoms for an array of names, use +XInternAtoms. +Atominterning +XInternAtoms + + + + Status XInternAtoms + Display *display + char **names + int count + Bool only_if_exists + Atom *atoms_return + + + + + + + display + + + +Specifies the connection to the X server. + + + + + + names + + + +Specifies the array of atom names. + + + + + + + count + + + +Specifies the number of (Cn. + + + + + + only_if_exists + + + +Specifies a Boolean value that indicates whether the atom must be created. + + + + + + atoms_return + + + +Returns the atoms. + + + + + + + + +The +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 +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. + + + +This function returns a nonzero status if atoms are returned for +all of the names; +otherwise, it returns zero. + + + +XInternAtoms +can generate +BadAlloc +and +BadValue +errors. + + + + +To return a name for a given atom identifier, use +XGetAtomName. +Atomgetting name +XGetAtomName + + + + char *XGetAtomName + Display *display + Atom atom + + + + + + + display + + + +Specifies the connection to the X server. + + + + + + atom + + + +Specifies the atom for the property name you want returned. + + + + + + + + +The +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 +XFree. + + + +XGetAtomName +can generate a +BadAtom +error. + + + + +To return the names for an array of atom identifiers, use +XGetAtomNames. +Atomgetting name +XGetAtomNames + + + + Status XGetAtomNames + Display *display + Atom *atoms + int count + char **names_return + + + + + + + display + + + +Specifies the connection to the X server. + + + + + + atoms + + + +Specifies the array of atoms. + + + + + + + count + + + +Specifies the number of (Cn. + + + + + + names_return + + + +Returns the atom names. + + + + + + + + +The +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 +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. + + + +This function returns a nonzero status if names are returned for +all of the atoms; +otherwise, it returns zero. + + + +XGetAtomNames +can generate a +BadAtom +error. + + + +Obtaining and Changing Window Properties + + + + + +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 +char +is used to represent 8-bit quantities, the type +short +is used to represent 16-bit quantities, and the type +long +is used to represent 32-bit quantities. + + + +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). + + + + +To obtain the type, format, and value of a property of a given window, use +XGetWindowProperty. +Propertygetting + + + +XGetWindowProperty + + + + int XGetWindowProperty + display + w + property + long_offset + long_length + delete + req_type + actual_type_return + actual_format_return + nitems_return + bytes_after_return + .br prop_return + + + + + + + display + + + +Specifies the connection to the X server. + + + + + + + w + + + +Specifies the window (Wi. + + + + + + property + + + +Specifies the property name. + + + + + + long_offset + + + +Specifies the offset in the specified property (in 32-bit quantities) +where the data is to be retrieved. + + + + + + long_length + + + +Specifies the length in 32-bit multiples of the data to be retrieved. + + + + + + delete + + + +Specifies a Boolean value that determines whether the property is deleted. + + + + + + req_type + + + +Specifies the atom identifier associated with the property type or +AnyPropertyType. + + + + + + actual_type_return + + + +Returns the atom identifier that defines the actual type of the property. + + + + + + actual_format_return + + + +Returns the actual format of the property. + + + + + + nitems_return + + + +Returns the actual number of 8-bit, 16-bit, or 32-bit items +stored in the prop_return data. + + + + + + bytes_after_return + + + +Returns the number of bytes remaining to be read in the property if +a partial read was performed. + + + + + + prop_return + + + +Returns the data in the specified format. + + + + + + + + +The +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. +XGetWindowProperty +sets the return arguments as follows: + + + + +If the specified property does not exist for the specified window, +XGetWindowProperty +returns +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. + + + + +If the specified property exists +but its type does not match the specified type, +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. + + + + +If the specified property exists and either you assign +AnyPropertyType +to the req_type argument or the specified type matches the actual property type, +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: + + + + + + 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) + + + + + +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 +BadValue +error results. +The value of bytes_after_return is A, +giving the number of trailing unread bytes in the stored property. + + + + + +If the returned format is 8, the returned data is represented as a +char +array. +If the returned format is 16, the returned data is represented as a +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 +long +array and should be cast to that type to obtain the elements. + + + +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. + + + +If delete is +True +and bytes_after_return is zero, +XGetWindowProperty +deletes the property +from the window and generates a +PropertyNotify +event on the window. + + + +The function returns +Success +if it executes successfully. +To free the resulting data, +use +XFree. + + + +XGetWindowProperty +can generate +BadAtom, +BadValue, +and +BadWindow +errors. + + + + +To obtain a given window's property list, use +XListProperties. +Propertylisting +XListProperties + + + + Atom *XListProperties + Display *display + Window w + int *num_prop_return + + + + + + + display + + + +Specifies the connection to the X server. + + + + + + + w + + + +Specifies the window (Wi. + + + + + + num_prop_return + + + +Returns the length of the properties array. + + + + + + + + +The +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 +XFree. + + + +XListProperties +can generate a +BadWindow +error. + + + + +To change a property of a given window, use +XChangeProperty. +Propertychanging +Propertyappending +Propertyprepending +Propertyreplacing +Propertyformat +Propertytype +XChangeProperty + + + + XChangeProperty + Display *display + Window w + Atomproperty, type + int format + int mode + unsignedchar *data + int nelements + + + + + + + display + + + +Specifies the connection to the X server. + + + + + + + w + + + +Specifies the window (Wi. + + + + + + property + + + +Specifies the property name. + + + + + + type + + + +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 +XGetWindowProperty. + + + + + + format + + + +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 +XChangeProperty. + + + + + + + mode + + + +Specifies the mode of the operation. +You can pass +PropModeReplace, +PropModePrepend, +or +PropModeAppend. + + + + + + data + + + +Specifies the property data. + + + + + + nelements + + + +Specifies the number of elements of the specified data format. + + + + + + + + +The +XChangeProperty +function alters the property for the specified window and +causes the X server to generate a +PropertyNotify +event on that window. +XChangeProperty +performs the following: + + + + +If mode is +PropModeReplace, +XChangeProperty +discards the previous property value and stores the new data. + + + + +If mode is +PropModePrepend +or +PropModeAppend, +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 +BadMatch +error results. +If the property is undefined, +it is treated as defined with the correct type and +format with zero-length data. + + + + + +If the specified format is 8, the property data must be a +char +array. +If the specified format is 16, the property data must be a +short +array. +If the specified format is 32, the property data must be a +long +array. + + + +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 +BadAlloc +error results.) + + + +XChangeProperty +can generate +BadAlloc, +BadAtom, +BadMatch, +BadValue, +and +BadWindow +errors. + + + + +To rotate a window's property list, use +XRotateWindowProperties. + + + +XRotateWindowProperties + + + + XRotateWindowProperties + Display *display + Window w + Atom properties[] + int num_prop + int npositions + + + + + + + display + + + +Specifies the connection to the X server. + + + + + + w + + + +Specifies the window. + + + + + + properties + + + +Specifies the array of properties that are to be rotated. + + + + + + num_prop + + + +Specifies the length of the properties array. + + + + + + npositions + + + +Specifies the rotation amount. + + + + + + + + +The +XRotateWindowProperties +function allows you to rotate properties on a window and causes +the X server to generate +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 +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 +BadMatch +error results. +If a +BadAtom +or +BadMatch +error results, +no properties are changed. + + + +XRotateWindowProperties +can generate +BadAtom, +BadMatch, +and +BadWindow +errors. + + + + +To delete a property on a given window, use +XDeleteProperty. +Propertydeleting +XDeleteProperty + + + + XDeleteProperty + Display *display + Window w + Atom property + + + + + + + display + + + +Specifies the connection to the X server. + + + + + + + w + + + +Specifies the window (Wi. + + + + + + property + + + +Specifies the property name. + + + + + + + + +The +XDeleteProperty +function deletes the specified property only if the +property was defined on the specified window +and causes the X server to generate a +PropertyNotify +event on the window unless the property does not exist. + + + +XDeleteProperty +can generate +BadAtom +and +BadWindow +errors. + + + +Selections + + + + + +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. + + + +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. + + + +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. + + + +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. + + + + +To set the selection owner, use +XSetSelectionOwner. +Selectionsetting the owner +XSetSelectionOwner + + + + XSetSelectionOwner + Display *display + Atom selection + Window owner + Time time + + + + + + + display + + + +Specifies the connection to the X server. + + + + + + selection + + + +Specifies the selection atom. + + + + + + owner + + + +Specifies the owner of the specified selection atom. +You can pass a window or +None. + + + + + + time + + + +Specifies the time. +You can pass either a timestamp or +CurrentTime. + + + + + + + + +The +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 +CurrentTime +replaced by the current server time. +If the owner window is specified as +None, +then the owner of the selection becomes +None +(that is, no owner). +Otherwise, the owner of the selection becomes the client executing +the request. + + + +If the new owner (whether a client or +None) +is not +the same as the current owner of the selection and the current +owner is not +None, +the current owner is sent a +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 +None, +but the last-change time is not affected. +The selection atom is uninterpreted by the X server. +XGetSelectionOwner +returns the owner window, which is reported in +SelectionRequest +and +SelectionClear +events. +Selections are global to the X server. + + + +XSetSelectionOwner +can generate +BadAtom +and +BadWindow +errors. + + + + +To return the selection owner, use +XGetSelectionOwner. +Selectiongetting the owner +XGetSelectionOwner + + + + Window XGetSelectionOwner + Display *display + Atom selection + + + + + + + display + + + +Specifies the connection to the X server. + + + + + + + selection + + + +Specifies the selection atom (Se. + + + + + + + + +The +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 +None. +If +None +is returned, +there is no owner for the selection. + + + +XGetSelectionOwner +can generate a +BadAtom +error. + + + + +To request conversion of a selection, use +XConvertSelection. +Selectionconverting +XConvertSelection + + + + XConvertSelection + Display *display + Atomselection, target + Atom property + Window requestor + Time time + + + + + + + display + + + +Specifies the connection to the X server. + + + + + + selection + + + +Specifies the selection atom. + + + + + + target + + + +Specifies the target atom. + + + + + + property + + + +Specifies the property name. +You also can pass +None. + + + + + + requestor + + + +Specifies the requestor. + + + + + + time + + + +Specifies the time. +You can pass either a timestamp or +CurrentTime. + + + + + + + + +XConvertSelection +requests that the specified selection be converted to the specified target +type: + + + + +If the specified selection has an owner, the X server sends a +SelectionRequest +event to that owner. + + + + +If no owner for the specified +selection exists, the X server generates a +SelectionNotify +event to the +requestor with property +None. + + + + + +The arguments are passed on unchanged in either of the events. +There are two predefined selection atoms: PRIMARY and SECONDARY. + + + +XConvertSelection +can generate +BadAtom +and +BadWindow +errors. + + + + + + -- cgit v1.2.3