| Previous | Contents | Index |
Xlib differs from most VMS programming libraries in the way it handles error conditions. In particular, Xlib does not perform any validation of input arguments when an Xlib routine is called.
If the input arguments are incorrect, the server usually generates an error event when it receives the Xlib request. Unless the client has specified an error handler, the server invokes the default Xlib error handler, which prints out a diagnostic message and exits. For more information about the Xlib error handler, refer to Section 9.13.2.
In some cases, Xlib signals a fatal access violation (SYS-F-ACCVIO)
when passed incorrect arguments. This occurs when arguments are missing
or are passed using the wrong addressing mode (passed by value instead
of passed by reference).
1.4 Debugging Xlib Programs
As noted in Section 1.1, Xlib handles client requests asynchronously. Instead of dispatching requests as it receives them, Xlib buffers requests to increase communication efficiency.
Buffering contributes to delays in error reporting. Asynchronous reporting enables Xlib and the server to continue processing client requests despite the occurrence of errors. However, buffering contributes to the delay between the occurrence and client notification of an error.
As a result, programmers who want to step through routines to locate errors must override the buffering that causes asynchronous communication between client and server. To override buffering, use the SYNCHRONIZE routine. Example 1-1 includes a SYNCHRONIZE call as a debugging tool. Use the SYNC routine if you are interested in a specific call. The SYNC routine flushes the output buffer and then waits until all requests have been processed.
A client requires one or more servers to process requests and return keyboard and mouse input. The server can be located either on the same system as the client or at a remote location where it is accessed across a network.
This chapter describes the following topics related to managing the client-server connection:
A client using Xlib makes its first call to open a display. After opening a display, the client can get display information from and send requests to the server. To increase the efficiency of the client-server connection, Xlib buffers client requests.
To understand the relationship between a display and hardware, consider the classroom illustrated in Figure 2-1. The server and an instructor client program are running on the instructor VAXstation, which includes a screen, a keyboard, and a mouse. When the instructor opens a display, Xlib establishes a connection between the instructor client program and the server. The instructor can output graphics on the instructor VAXstation screen.
Figure 2-1 Graphics Output to Instructor VAXstation
If the instructor wants to output graphics to student screens, each student VAXstation must be running a server, and the client program must be connected to each server, as Figure 2-2 illustrates. Unlike the prior example, where the client program opened one display by making an internal connection with the server running on the VAXstation, here the client program establishes connections with multiple servers.
Xlib also enables multiple clients to establish connections with one server. For example, to output student work on the instructor screen, each student must open a display with the server running on the instructor VAXstation.
Figure 2-2 Graphics Output to Student VAXstations
The OPEN DISPLAY routine establishes a connection between the client and the server. The OPEN DISPLAY routine call has the following format:
|
display=XOpenDisplay(display_name) |
In this call, display_name is a string that specifies the node on which the server is running. The display_name argument has the following format:
|
hostname::number.screen |
The elements of the argument are as follows:
| Elements | Description |
|---|---|
| hostname | The host on which the server is running. If the client and server are physically running in the same CPU, clients can specify a display number of zero. |
| number | The number of the display on the host machine. |
| screen | The screen on which client input and output is handled. |
Passing a null argument to the OPEN DISPLAY routine causes Xlib to search for the definition of the logical DECW$DISPLAY. If successful, OPEN DISPLAY returns a unique identifier of the display. See Example 1-1 for an example of defining a display with this method.
A display can also be defined by using the DCL command SET DISPLAY,
which sets the logical name DECW$DISPLAY. Refer to the Using DECwindows Motif for OpenVMS for
more information about specifying a display.
2.3 Closing the Client-Server Connection
Although Xlib automatically destroys windows and resources related to a process when the process exits the server, clients should close their connection with a server explicitly. Clients can close the connection using the CLOSE DISPLAY routine. CLOSE DISPLAY destroys all windows associated with the display and all resources the client has allocated. The CLOSE DISPLAY routine call has the following format:
|
XCloseDisplay(display) |
For an example of closing a display, see Example 1-1.
After closing a display, clients should not refer to windows, identifiers, and other resources associated with that display.
For more information about closing the X server connection, refer to
the X Window System.
2.4 Getting Information About the Client-Server Connection
After opening a display, clients can get information about the client-server connection, client screens, and images created on client screens by using the routines listed in this section. These routines are useful for supplying arguments to other routines. See the X Window System for more information about these routines.
This manual uses a generic format when referring to Xlib routine names in text. Routine names are represented in all uppercase letters with separating spaces. In addition, the X prefix has been omitted. For example, in text the routine name is written as OPEN DISPLAY; however, the MIT C binding format of the same routine is XOpenDisplay. See the X Window System for a complete reference and description of all MIT C Binding Xlib routines. |
Clients can get client-server information by using the following routines:
| ALL PLANES | DISPLAY PLANES |
| BLACK PIXEL | DISPLAY STRING |
| CONNECTION NUMBER | IMAGE BYTE ORDER |
| DEFAULT COLORMAP | MAX REQUEST SIZE |
| DEFAULT DEPTH | PROTOCOL REVISION |
| DEFAULT GC | PROTOCOL VERSION |
| DEFAULT ROOT WINDOW | Q LENGTH |
| DEFAULT SCREEN | ROOT WINDOW |
| DEFAULT VISUAL | SCREEN COUNT |
| DISPLAY CELLS | SERVER VENDOR |
| DISPLAY KEYCODES | VENDOR RELEASE |
| DISPLAY MOTION BUFFER SIZE | WHITE PIXEL |
Clients can get information about client screens using the following routines:
| BLACK PIXEL OF SCREEN | HEIGHT OF SCREEN |
| CELLS OF SCREEN | HEIGHT MM OF SCREEN |
| DEFAULT COLORMAP OF SCREEN | MAX CMAPS OF SCREEN |
| DEFAULT DEPTH OF SCREEN | MIN CMAPS OF SCREEN |
| DEFAULT GC OF SCREEN | PLANES OF SCREEN |
| DEFAULT SCREEN OF DISPLAY | ROOT WINDOW OF SCREEN |
| DEFAULT VISUAL OF DISPLAY | SCREEN OF DISPLAY |
| DOES BACKING STORE | VISUAL ID FROM VISUAL |
| DOES SAVE UNDERS | WHITE PIXEL OF SCREEN |
| DISPLAY OF SCREEN | WIDTH OF SCREEN |
| EVENT MASK OF SCREEN | WIDTH MM OF SCREEN |
Clients can get information about images created on screens using the following routines:
| BITMAP BIT ORDER | DISPLAY HEIGHT MM |
| BITMAP PAD | DISPLAY WIDTH |
| BITMAP UNIT | DISPLAY WIDTH MM |
| DISPLAY HEIGHT |
Instead of sending each request to the server as the client specifies the request, Xlib buffers requests and sends them as a block to increase the efficiency of client-to-server communication. The routines listed in Table 2-1 control how requests output from the buffer.
| Routine | Description |
|---|---|
| FLUSH | Flushes the buffer. |
| SET AFTER FUNCTION | Specifies the function the client calls after processing each protocol request. |
| SYNC | Flushes the buffer and waits until the server has received and processed all events, including errors. Use SYNC to isolate one call when debugging. |
| SYNCHRONIZE | Causes the server to process requests in the buffer synchronously. SYNCHRONIZE causes Xlib to generate a return after each Xlib routine completes. Use it to debug an entire client or block. |
Most clients do not need to call the FLUSH routine because the output buffer is automatically flushed by calls to event management routines. Refer to Chapter 9 for more information about event handling.
Windows receive information from users; they display graphics, text, and messages. Xlib routines enable a client to create multiple windows and define window size, location, and visual appearance on one or more screens.
Conflicts between clients about displaying windows are handled by a window manager, which controls the size and placement of windows and, in some cases, window characteristics such as title bars and borders. The window manager also keeps clients informed about what it is doing with their windows. For example, the window manager might tell a client that one of its windows has been resized so that the client can reformat information displayed in the window.
This chapter describes the following topics related to windows and the window manager:
A window is an area of the screen that either receives input or receives input and displays graphics.
One type of window only receives input. Because an input-only window does not display text or graphics, it is not visible on the screen. Clients can use input-only windows to control cursors, manage input, and define regions in which the pointer is used exclusively by one client. A second type of window both receives input and displays text and graphics.
Clients can make input-output windows visible on the screen. To make a
window visible, a client first creates the window and then maps it.
Mapping a window allows it to become visible on the screen. When more
than one window is mapped, the windows may overlap. Window hierarchy
and position on the screen determine whether or not one window hides
the contents of another window.
3.1.1 Window Hierarchy
Windows that clients create are part of a window hierarchy. The hierarchy determines how windows are seen. At the base of the hierarchy is the root window, which covers the entire screen when the client opens a display. All windows created after opening a display are subwindows of the root window.
When a client creates one or more subwindows of the root window, the root window becomes a parent. Children of the root window become parents when clients create subwindows of the children.
The hierarchy is structured like a stack of papers. At the bottom of the stack is the root window. Windows that clients create after opening a display are stacked on top of the root window, overlapping parts of it. For example, the window named child-of-root overlaps parts of the root window in Figure 3-1. The child-of-root window always touches the root window. Xlib always stacks children on top of the parents.
Figure 3-1 Root Window and One Child
If a window has more than one child and if their borders intersect, Xlib stacks siblings in the order the client creates them, with the last sibling on top. For example, the second-level window named 2nd-child-of-root, which was created last, overlaps the second-level window named 1st-child-of-root in Figure 3-2.
Figure 3-2 Relationship Between Second-Level Windows
Third-level windows maintain the hierarchical relationships of their parents. The child-of-1st-child-of-root window overlaps child-of-2nd-child-of-root in Figure 3-3.
Figure 3-3 Relationship Between Third-Level Windows
Windows created before a specified window and hierarchically related to
it are ancestors of that window. For example, the root window and the
window named 1st-child-of-root are ancestors of
child-of-1st-child-of-root.
3.1.2 Window Position
Xlib coordinates define window position on a screen and place graphics within windows. Coordinates that specify the position of a window are relative to the origin, the upper left corner of the parent window. Coordinates that specify the position of a graphic object within a window are relative to the origin of the window in which the graphic object is displayed.
Xlib measures length along the x-axis from the origin to the right; it measures length along the y-axis from the origin down. Xlib specifies coordinates in units of pixels, the smallest unit the server can display on a screen. Figure 3-4 illustrates the Xlib coordinate system.
Figure 3-4 Coordinate System
For more information about positioning windows, see Section 3.2. For
more information about positioning graphics, see Chapter 6.
3.1.3 Window Visibility and Occlusion
A window is visible if one can see it on the screen. To be visible, a window must be an input-output window, it must be mapped, its ancestors must be mapped, and it must not be totally hidden by another window. When a window and its ancestors are mapped, the window is considered viewable. A viewable window that is totally hidden by another window is not visible.
Even though input-only windows are never visible, they can overlap other windows. An input-only window that overlaps another window is considered to occlude that window. Specifically, window A occludes window B if both are mapped, if A is higher in the stacking order than B, and if the rectangle defined by the outside edges of A intersects the rectangle defined by the outside edges of B.
A viewable input-output window that overlaps another window is
considered to obscure that window. Specifically,
window A obscures window B if A is a viewable input-output window, if A
is higher in the stacking order than B, and if the rectangle defined by
the outside edges of A intersects the rectangle defined by the outside
edges of B.
3.2 Creating Windows
After opening a display, clients can create windows. As noted in the description of window fundamentals ( Section 3.1), creating a window does not make it visible on a screen. To be visible, the window must meet the conditions described in Section 3.1.3.
Clients can either create windows that inherit most characteristics not
relating to size or shape from their parents or define all
characteristics when creating windows.
3.2.1 Using Attributes of the Parent Window
An attribute is a characteristic of a window not relating to size or shape, such as the window background color. The CREATE SIMPLE WINDOW routine creates an input-output subwindow that inherits the following attributes from its parent:
For more information about these attributes, see Section 3.2.2.
If the parent is a root window, the new window created with the CREATE SIMPLE WINDOW routine has the following attributes:
In addition to creating a window with attributes inherited from the parent window, the CREATE SIMPLE WINDOW routine enables clients to define the border and background attributes of the window and to determine window position and size.
Example 3-1 illustrates creating a simple window. To make the window visible, the example includes mapping and event handling functions, which are described in Section 3.4 and Chapter 9.
| Example 3-1 Creating a Simple Window |
|---|
Window win1;
.
.
.
static void doCreateWindows( )
{
(1) int win1W = 600;
int win1H = 600;
(2) int win1X = (XWidthOfScreen(screen)-window1W)>>1;
int win1Y = (XHeightOfScreen(screen)-window1H)>>1;
/* Create the window */
(3) win1 = XCreateSimpleWindow(dpy, XRootWindowOfScreen(screen),
win1X, win1Y, win1W, win1H, 10, XBlackPixelOfScreen(screen),
XWhitePixelOfScreen(screen);
}
|
| Previous | Next | Contents | Index |