| Page: | 1 | 2 | 3 | 4 | 5 | 6 |
|---|
After you connect the display to the X server and create a window, you can use the Xlib window information functions to:
| Home |
|---|
4.1. 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.
Status XQueryTree(display, w, root_return,
parent_return, children_return,
nchildren_return)
Display *display;
Window w;
Window *root_ return;
Window *parent_ return;
Window **children_return;
unsigned int *nchildren_return;
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 bottommost (first) to topmost (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.
Status XGetWindowAttributes(display, w,
window_attributes_return)
Display *display;
Window w;
XWindowAttributes *window_attributes_return;
The XGetWindowAttributes function returns the current attributes for the specified window to an XWindowAttributes structure.
| typedef struct { | ||
| int
x, y; int width, height; int border_width; int depth; Visual *visual; Window root; int class; int bit_gravity; int win_gravity; int backing_store; unsigned long backing_planes; unsigned long backing_pixel; Bool save_under; Colormap colormap; Bool map_installed; int map_state; long all_event_masks; long your_event_mask; long do_not_propagate_mask; Bool override_redirect; Screen *screen; | /* location of window */ /* width and height of window */ /* border width of window */ /* depth of window */ /* the associated visual structure */ /* root of screen containing window */ /* InputOutput, InputOnly*/ /* one of the bit gravity values */ /* one of the window gravity values */ /* NotUseful, WhenMapped, Always */ /* planes to be preserved if possible */ /* value to be used when restoring planes */ /* boolean, should bits under be saved? */ /* color map to be associated with window */ /* boolean, is color map currently installed*/ /* IsUnmapped, IsUnviewable, IsViewable */ /* set of events all people have interest in*/ /* my event mask */ /* set of events that should not propagate */ /* boolean value for override-redirect */ /* 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 CenterGravity | 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 CenterGravity | EastGravity SouthWestGravity SouthGravity SouthEastGravity StaticGravity |
For additional information on gravity, see section 3.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 so 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.
Status XGetGeometry(dispiay, d, root_return,
x_return, y_return, width_return,
height_return, border_width_return,
depth_return)
Display *display;
Drawable d;
Window *root_return;
int *x_return, *y_return;
unsigned int *width_return, *height_return;
unsigned int *border_width_return;
unsigned int *depth_return;
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.
| Home |
|---|
4.2. 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 .
Bool XTranslateCoordinates(display, src_w, dest_w, src_x, src_y, dest_x_return, dest_y_return, child_return) Display *display; Window src_w, dest_w; int src_x, src_y; int *dest_x_return, *dest_y_return; Window *child_return;
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.
Bool XQueryPointer(display, w, root_return, child_return, root_x_return, root_y_return, win_x_return, win_y_return, mask_return) Display *display; Window w; Window *root_return, *child_return; int *root_x_return, *root_y_return; int *win_x_return, *win_y_return; unsigned int *mask_return;
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, XQueryPoinler 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.
| Home |
|---|
A property is a collection of named, typed data. The window system has a set of predefined properties (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.
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.
Certain property names are predefined in the server for commonly used functions. The atoms for these properties are defined in <X11/Xatom.h>. To avoid name clashes with user symbols, the #define name for each atom has the XA_ prefix. For definitions of these properties, see section 4.3. For an explanation of the functions that let you get and set much of the information stored in these predefined properties, see Chapter 14.
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 in the SUPER-UX X Window System Programmer's Guide and the X Logical Font Description Conventions (provided in printed version only).
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:
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. NAME="Atom__interning__01">
To return an atom for a given name, use XInternAtom.
Atom XInternAtom(display, atom_name, only_if_exists) Display *display; char *atom_name; Bool only_if_exists;
The XlnternAtom 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.
Status XInternAtoms(display, names, count,
only_if_exists, atoms_return)
Display *display;
char **names;
int count;
Bool only_if_exists;
Atom *atoms_return;
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 XlnternAtom 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.
char *XGetAtomName(display, atom)
Display *display;
Atom atom;
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.
Status XGetAtomNames(display, atoms, count,
names_return)
Display *display;
Atom *atoms;
int count;
char **names_return;
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.
| Home |
|---|
4.4. 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.
int XGetWindowProperty(display, w, property, long_offset, long_length, delete, req_type,
actual_type_return, actual_format_return, nitems_return, bytes_after_return,
prop_return)
Display *display;
Window w;
Atom property;
long long_offset, long_length;
Bool delete;
Atom req_type;
Atom *actual_type _return;
int *actual_format_return;
unsigned long *nitems_return;
unsigned long *bytes_after_return;
unsigned char **prop_return;
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.
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)
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 freethe resulting data, use XFree. XGetWindowProperty can generate BadAtom, BadValue, and BadWindow errors. To obtain a given window's property list, use XListProperties.
Atom *XListProperties(display, w, num_prop_return) Display *display; Window w; int *num_prop_return;
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.
XChangeProperty(display, w, property, type, format, mode, data, nelements) Display *display; Window w; Atom property, type; int format; int mode; unsigned char *data; int nelements;
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 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(display, w, properties, num_prop, npositions) Display *display; Window w; Atom properties[]; int num_prop; int npositions;
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.
XDeleteProperty(display, w, property) Display *display; Window w; Atom property;
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.
| Home |
|---|
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.
XSetSelectionOwner(display, selection, owner, time) Display *display; Atom selection; Window owner; Time time;
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
Window XGetSelectionOwner(display, selection) Display *display; Atom selection;
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.
XConvertSelection(display, selection, target, property, requestor, time) Display *display; Atom selection, target; Atom property; Window requestor; Time time;
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.
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.
| Home |
|---|
| Contents | Previous Chapter | Next Chapter |