| Page: | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 |
|---|
Although it is difficult to categorize functions as exclusively for an application, a window manager, or a session manager, the functions in this chapter are most often used by window managers and session managers. It is not expected that these functions will be used by most application programs. Xlib provides management functions to:
To change a window's parent to another window on the same screen, use XReparentWindow. There is no way to move a window between screens.
XReparentWindow(display, w, parent, x, y) Display *display; Window w; Window parent; int x, y;
If the specified window is mapped, XReparentWindow automatically performs an UnmapWindow request on it, removes it from its current position in the hierarchy, and inserts it as the child of the specified parent. The window is placed in the stacking order on top with respect to sibling windows.
After reparenting the specified window, XReparentWindow causes the X server to generate a ReparentNotify event. The override_redirect member returned in this event is set to the window's corresponding attribute. Window manager clients usually should ignore this window if this member is set to True. Finally, if the specified window was originally mapped, the X server automatically performs a MapWindow request on it.
The X server performs normal exposure processing on formerly obscured windows. The X server might not generate Expose events for regions from the initial UnmapWindow request that are immediately obscured by the final MapWindow request. A BadMatch error results if:
XReparentWindow can generate BadMatch and BadWindow errors.
| Home |
|---|
The save-set of a client is a list of other clients' windows that, if they are inferiors of one of the client's windows at connection close, should not be destroyed and should be remapped if they are unmapped. For further information about close-connection processing, see section 2.6. To allow an application's window to survive when a window manager that has reparented a window fails, Xlib provides the save-set functions that you can use to control the longevity of subwindows that are normally destroyed when the parent is destroyed. For example, a window manager that wants to add decoration to a window by adding a frame might reparent an application's window. When the frame is destroyed, the application's window should not be destroyed but be returned to its previous place in the window hierarchy.
The X server automatically removes windows from the save-set when they are destroyed.
To add or remove a window from the client's save-set, use XChangeSaveSet.
XChangeSaveSet(display, w, change_mode) Display *display; Window w; int change_mode;
Depending on the specified mode, XChangeSaveSet either inserts or deletes the specified window from the client's saveset. The specified window must have been created by some other client, or a BadMatch error results.
XChangeSaveSet can generate BadMatch, BadValue, and BadWindow errors.
To add a window to the client's save-set, use XAddToSaveSet.
XAddToSaveSet(display, w) Display *display; Window w;
The XAddToSaveSet function adds the specified window to the client's save-set. The specified window must have been created by some other client, or a BadMatch error results.
XAddToSaveSet can generate BadMatch and BadWindow errors.
To remove a window from the client's save-set, use XRemoveFromSaveSet.
XRemoveFromSaveSet(display, w) Display *display; Window w;
The XRemoveFromSaveSet function removes the specified window from the client's save-set. The specified window must have been created by some other client, or a BadMatch error results.
XRemoveFromSaveSet can generate BadMatch and BadWindow errors.
| Home |
|---|
The X server maintains a list of installed colormaps. Windows using these colormaps are guaranteed to display with correct colors; windows using other colormaps may or may not display with correct colors. Xlib provides functions that you can use to install a colormap, uninstall a colormap, and obtain a list of installed colormaps.
At any time, there is a subset of the installed maps that is viewed as an ordered list and is called the required list. The length of the required list is at most M, where M is the minimum number of installed colormaps specified for the screen in the connection setup. The required list is maintained as follows. When a colormap is specified to XInstallColormap, it is added to the head of the list; the list is truncated at the tail, if necessary, to keep its length to at most M. When a colormap is specified to XUninstallColormap and it is in the required list, it is removed from the list. A colormap is not added to the required list when it is implicitly installed by the X server, and the X server cannot implicitly uninstall a colormap that is in the required list.
To install a colormap, use XInstallColormap.
XInstallColormap(display, colormap) Display *display; Colormap colormap;
The XInstallColormap function installs the specified colormap for its associated screen. All windows associated with this colormap immediately display with true colors. You associated the windows with this colormap when you created them by calling XCreateWindow, XCreateSimpleWindow, XChangeWindowAttributes, or XSetWindowColormap.
If the specified colormap is not already an installed colormap, the X server generates a ColormapNotify event on each window that has that colormap. In addition, for every other colormap that is installed as a result of a call to XInstallColormap, the X server generates a ColormapNotify event on each window that has that colormap.
XInstallColormap can generate a BadColor error.
To uninstall a colormap, use XUninstallColormap.
XUninstallColormap(display, colormap) Display *display; Colormap colormap;
The XUninstallColormap function removes the specified colormap from the required list for its screen. As a result, the specified colormap might be uninstalled, and the X server might implicitly install or uninstall additional colormaps. Which colormaps get installed or uninstalled is server-dependent except that the required list must remain installed.
If the specified colormap becomes uninstalled, the X server generates a ColormapNotify event on each window that has that colormap. In addition, for every other colormap that is installed or uninstalled as a result of a call to XUninstallColormap, the X server generates a ColormapNotify event on each window that has that colormap.
XUninstallColormap can generate a BadColor error.
To obtain a list of the currently installed colormaps for a given screen, use XListInstalledColormaps.
Colormap *XListInstalledColormaps(display, w, num_return) Display *display; Window w; int *num_return;
The XListInstalledColormaps function returns a list of the currently installed colormaps for the screen of the specified window. The order of the colormaps in the list is not significant and is no explicit indication of the required list. When the allocated list is no longer needed, free it by using XFree.
XListInstalledColormaps can generate a BadWindow error.
| Home |
|---|
The set of fonts available from a server depends on a font search path. Xlib provides functions to set and retrieve the search path for a server.
To set the font search path, use XSetFontPath.
XSetFontPath(display, directories, ndirs) Display *display; char **directories; int ndirs;
The XSetFontPath function defines the directory search path for font lookup. There is only one search path per X server, not one per client. The encoding and interpretation of the strings is implementation dependent, but typically they specify directories or font servers to be searched in the order listed. An X server is permitted to cache font information internally; for example, it might cache an entire font from a file and not check on subsequent opens of that font to see if the underlying font file has changed. However, when the font path is changed, the X server is guaranteed to flush all cached information about fonts for which there currently are no explicit resource IDs allocated. The meaning of an error from this request is implementation dependent.
XSetFontPath can generate a BadValue error.
To get the current font search path, use XGetFontPath.
char **XGetFontPath(display, npaths_return)
Display *display
int *npaths_return;
The XGetFontPath function allocates and returns an array of strings containing the search path. The contents of these strings are implementation dependent and are not intended to be interpreted by client applications. When it is no longer needed, the data in the font path should be freed by using XFreeFontPath.
To free data returned by XGetFontPath, use XFreeFontPath.
XFreeFontPath(list) char **list;
The XFreeFontPath function frees the data allocated by XGetFontPath.
| Home |
|---|
Xlib provides functions that you can use to grab and ungrab the server. These functions can be used to control processing of output on other connections by the window system server. While the server is grabbed, no processing of requests or close downs on any other connection will occur. A client closing its connection automatically ungrabs the server. Although grabbing the server is highly discouraged, it is sometimes necessary.
To grab the server, use XGrabServer.
XGrabServer(display) Display *display;
The XGrabServer function disables processing of requests and close downs on all other connections than the one this request arrived on. You should not grab the X server any more than is absolutely necessary.
To ungrab the server, use XUngrabServer.
XUngrabServer(display) Display *display;
The XUngrabServer function restarts processing of requests and close downs on other connections. You should avoid grabbing the X server as much as possible.
| Home |
|---|
Xlib provides a function to cause the connection to a client to be closed and its resources to be destroyed. To destroy a client, use XKillClient.
XKillClient(display, resource) Display *display; XID resource;
The XKillClient function forces a closedown of the client that created the resource if a valid resource is specified. If the client has already terminated in either RetainPermanent or RetainTemporary mode, all of the client's resources are destroyed. If AllTemporary is specified, the resources of all clients that have terminated in RetainTemporary are destroyed (see section 2.5). This permits implementation of window manager facilities that aid debugging. A client can set its closedown mode to RetainTemporary. If the client then crashes, its windows would not be destroyed. The programmer can then inspect the application's window tree and use the window manager to destroy the zombie windows.
XKillClient can generate a BadValue error.
| Home |
|---|
Xlib provides functions that you can use to set or reset the mode of the screen saver, to force or activate the screen saver, or to obtain the current screen saver values.
To set the screen saver mode, use XSetScreenSaver.
XSetScreenSaver(display, timeout, interval, prefer_blanking, allow_exposures) Display *display; int timeout, interval; int prefer_blanking; int allow_exposures;
Timeout and interval are specified in seconds. A timeout of 0 disables the screen saver (but an activated screen saver is not deactivated), and a timeout of -1 restores the default. Other negative values generate a BadValue error. If the timeout value is nonzero, XSetScreenSaver enables the screen saver. An interval of 0 disables the random-pattern motion. If no input from devices (keyboard, mouse, and so on) is generated for the specified number of timeout seconds once the screen saver is enabled, the screen saver is activated.
For each screen, if blanking is preferred and the hardware supports video blanking, the screen simply goes blank. Otherwise, if either exposures are allowed or the screen can be regenerated without sending Expose events to clients, the screen is tiled with the root window background tile randomly reorigined each interval seconds. Otherwise, the screens' state do not change, and the screen saver is not activated. The screen saver is deactivated, and all screen states are restored at the next keyboard or pointer input or at the next call to XForceScreenSaver with mode ScreenSaverReset .
If the server-dependent screen saver method supports periodic change, the interval argument serves as a hint about how long the change period should be, and zero hints that no periodic change should be made. Examples of ways to change the screen include scrambling the colormap periodically, moving an icon image around the screen periodically, or tiling the screen with the root window background tile, randomly reorigined periodically.
XSetScreenSaver can generate a BadValue error.
To force the screen saver on or off, use XForceScreenSaver.
XForceScreenSaver(display, mode) Display *display; int mode;
If the specified mode is ScreenSaverActive and the screen saver currently is deactivated, XForceScreenSaver activates the screen saver even if the screen saver had been disabled with a timeout of zero. If the specified mode is ScreenSaverReset and the screen saver currently is enabled, XForceScreenSaver deactivates the screen saver if it was activated, and the activation timer is reset to its initial state (as if device input had been received).
XForceScreenSaver can generate a BadValue error.
To activate the screen saver, use XActivateScreenSaver.
XActivateScreenSaver(display) Display *display;
To reset the screen saver, use XResetScreenSaver.
XResetScreenSaver(display) Display *display;
To get the current screen saver values, use XGetScreenSaver.
XGetScreenSaver(display, timeout_return, interval_return, prefer_blanking_return,
allow_exposures_return)
Display *display;
int *timeout_return, *interval_return;
int *prefer_blanking_return;
int *allow_exposures_return;
| Home |
|---|
This section discusses how to:
X does not provide any protection on a per-window basis. If you find out the resource ID of a resource, you can manipulate it. To provide some minimal level of protection, however, connections are permitted only from machines you trust. This is adequate on single-user workstations but obviously breaks down on timesharing machines. Although provisions exist in the X protocol for proper connection authentication, the lack of a standard authentication server leaves host-level access control as the only common mechanism.
The initial set of hosts allowed to open connections typically consists of:
If a host is not in the access control list when the access control mechanism is enabled and if the host attempts to establish a connection, the server refuses the connection. To change the access list, the client must reside on the same host as the server and/or must have been granted permission in the initial authorization at connection setup.
Servers also can implement other access control policies in addition to or in place of this host access facility. For further information about other access control implementations, see "X Window System Protocol" (provided in printed version only).
Xlib provides functions that you can use to add, get, or remove hosts from the access control list. All the host access control functions use the XHostAddress structure, which contains:
| typedef struct { | ||
| int family; int length; char *address; | /* for example FamilyInternet */ /* length of address, in bytes */ /* pointer to where to find the address */ | |
| } XHostAddress; | ||
The family member specifies which protocol address family to use (for example, TCP/IP or DECnet) and can be FamilyInternet, FamilyDECnet, or FamilyChaos. The length member specifies the length of the address in bytes. The address member specifies a pointer to the address.
For TCP/IP, the address should be in network byte order. For the DECnet family, the server performs no automatic swapping on the address bytes. A Phase IV address is two bytes long. The first byte contains the least-significant eight bits of the node number. The second byte contains the most-significant two bits of the node number in the least-significant two bits of the byte and the area in the most-significant six bits of the byte.
To add a single host, use XAddHost.
XAddHost(display, host) Display *display; XHostAddress *host;
The XAddHost function adds the specified host to the access control list for that display. The server must be on the same host as the client issuing the command, or a BadAecess error results.
XAddHost can generate BadAeeess and BadValue errors.
To add multiple hosts at one time, use XAddHosts.
XAddHosts(display, hosts, num_hosts) Display *display; XHostAddress *hosts; int num_hosts;
The XAddHosts function adds each specified host to the access control list for that display. The server must be on the same host as the client issuing the command, or a BadAccess error results. XAddHosts can generate BadAccess and BadValue errors.
To obtain a host list, use XListHosts.
XHostAddress*XListHosts(display, nhosts_return, state_return) Display *display; int *nhosts_return; Bool *state_return;
The XListHosts function returns the current access control list as well as whether the use of the list at connection setup was enabled or disabled. XListHosts allows a program to find out what machines can make connections. It also returns a pointer to a list of host structures that were allocated by the function. When no longer needed, this memory should be freed by calling XFree.
To remove a single host, use XRemoveHost.
XRemoveHost(display, host) Display *display; XHostAddress *host;
The XRemoveHost function removes the specified host from the access control list for that display. The server must be on the same host as the client process, or a BadAccess error results. If you remove your machine from the access list, you can no longer connect to that server, and this operation cannot be reversed unless you reset the server.
XRemoveHost can generate BadAccess and BadValue errors.
To remove multiple hosts at one time, use XRemoveHosts.
XRemoveHosts(display, hosts, num_hosts) Display *display; XHostAddress *hosts; int num_hosts;
The XRemoveHosts function removes each specified host from the access control list for that display. The X server must be on the same host as the client process, or a BadAccess error results. If you remove your machine from the access list, you can no longer connect to that server, and this operation cannot be reversed unless you reset the server.
XRemoveHosts can generate BadAccess and BadValue errors.
Xlib provides functions that you can use to enable, disable, or change access control.
For these functions to execute successfully, the client application must reside on the same host as the X server and/or have been given permission in the initial authorization at connection setup.
To change access control, use XSetAccessControl.
XSetAccessControl(display, mode) Display *display; int mode;
The XSetAccessControl function either enables or disables the use of the access control list at each connection setup.
XSetAccessControl can generate BadAccess and BadValue errors.
To enable access control, use XEnableAccessControl.
XEnableAccessControl(display) Display *display;
The XEnableAccessControl function enables the use of the access control list at each connection setup.
XEnableAccessControl can generate a BadAccess error.
To disable access control, use XDisableAccessControl.
XDisableAccessControl(display) Display *display;
The XDisableAccessControl function disables the use of the access control list at each connection setup.
XDisableAccessControl can generate a BadAccess error.
| Home |
|---|
| Contents | Previous Chapter | Next Chapter |