HP OpenVMS Systems Documentation

1. For information about connecting client and server, see Chapter 2.
2. Xlib buffers client requests and sends them to the server asynchronously. This sequence causes clients to receive errors after they have occurred. When debugging a program, call the SYNCHRONIZE routine to enable synchronous error reporting. Using the SYNCHRONIZE routine has a serious negative effect on performance. Clients should call the routine only when debugging. For more information about debugging, see Section 1.4.
3. For information about creating windows, see Chapter 3.
4. Before drawing a graphics object on the screen, clients must define the characteristics of the object. The program defines the foreground and background values for writing text. For information about defining graphics characteristics, see Chapter 4.
5. The sample program loads a VMS DECwindows font, New Century Schoolbook Roman 14, which the program uses to write the text inWINDOW_2. For information about loading fonts, see Chapter 8.
6. Mapping windows makes them visible on the screen. For information about window mapping, see Chapter 3
7. For more information about event handling, see Chapter 9.
8. When a client exits a VMS DECwindows program on the VMS operating system, the series of calls to unmap and destroy windows and close the display occurs automatically.
9. VMS DECwindows includes named colors for the convenience of clients. The sample program uses the named colors "dark slate blue," "light grey," and "firebrick." It shares the named colors it uses with other clients. For information about sharing colors, whether named or client-defined, see Chapter 5. For information about defining colors for exclusive use, see Section 5.4. For a list of named colors, see the X and Motif Quick Reference Guide.

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:

• Overview of the client-server connection
• Opening and closing a display
• Getting information about a display
• Managing sending requests to the server

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:

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:

The elements of the argument are as follows:

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:

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.

Clients can get client-server information by using the following routines:

Clients can get information about client screens using the following routines:

Clients can get information about images created on screens using the following routines:

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.

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:

• Window fundamentals---A description of window type, hierarchy, position, and visibility
• Creating and destroying windows---How to create and destroy windows
• Working with the window manager---How to work with the window manager to define user information concerning window management
• Mapping and unmapping windows---How to make windows visible on the screen
• Changing window characteristics---How to change the size, position, stacking order, and attributes of windows
• Getting information about windows---How to get information about window hierarchies, attributes, and geometry

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:

• Method of moving the contents of a window when the parent is moved or resized
• Instructions for saving window contents when the window obscures or is obscured by another window
• Instructions to the server regarding information that ancestors should know when a window change occurs
• Instructions to the window manager concerning map requests
• Color
• Cursor

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:

• The server discards window contents if the window is reconfigured.
• The server discards the contents of obscured portions of the window.
• The server discards the contents of any window that the new window obscures.
• No events are specified as being of interest to the window ancestors.
• No restrictions are placed on the window manager.
• The color is identical to the parent color.
• No cursor is specified.

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.

        INTEGER*4 WINDOW_1
        INTEGER*4 WINDOW_1X, WINDOW_1Y

(1)      PARAMETER   WINDOW_1W = 600, WINDOW_1H = 600
                    .
                    .
                    .
(2)      WINDOW_1X = (X$DISPLAY_WIDTH_OF_SCREEN(SCREEN) - WINDOW_1W) / 2
        WINDOW_1Y = (X$DISPLAY_HEIGHT_OF_SCREEN(SCREEN) - WINDOW_1H) / 2

(3)      WINDOW_1 = X$CREATE_SIMPLE_WINDOW(DPY,
        1   X$ROOT_WINDOW_OF_SCREEN(SCREEN),
        1   WINDOW_1X, WINDOW_1Y, WINDOW_1W, WINDOW_1H, 10,
        1   X$BLACK_PIXEL_OF_SCREEN(SCREEN), X$WHITE_PIXEL_OF_SCREEN(SCREEN))
                    .
                    .
                    .