Volume 7A: XView Programming Manual

4

Frames

A frame is a container for other windows. It manages the geometry and placement of

subwindows that do not overlap and are fixed within the boundary of the frame. The

OPEN LOOK specification refers to subwindows, or panes, as tiled windows because they do

not overlap one another. Subwindow types include canvases, text subwindows, panels, and

scrollbars. These subwindows cannot exist without a parent frame to manage them. Figure

4-1 shows the class hierarchy for the FRAME package.

Generic

Object

(Drawable) Window Frame

Figure 4-1. Frame package class hierarchy

Figure 4-2 shows an example of a screen that displays three frames, each one containing at

least one subwindow. Note that frames do overlap. The File Manager frame has the key-

board focus, as indicated by the title bar having its foreground and background colors

reversed. The setting of the keyboard focus is handled by the window manager, not the

FRAME package. In this case, an OPEN LOOK window manager is using click-to-type to set

the keyboard focus. This is demonstrated by the cursor’s location within an unselected frame

(the Edit: File frame).

The

FRAME

package provides the following capabilities:

• A communication path between the application and the window manager.

• A mechanism to receive input for the application.

• A visual container for user interface objects.

• A method to group windows with related functionality.

• A mechanism to manage footers.

Frames

Frames 59

Figure 4-2. Three base frames

A frame depends upon the window manager for its decorations and many basic operations.

The FRAME package does not manage headers (title bars), resize corners or the colors of those

objects. These are all strictly functions of the window manager. The application gives hints

to the window manager about some of these attributes through the FRAME package (including

not to display decorations at all if so desired), but results vary depending on which window

manager the user is running. The examples in this book assume the user is running an

OPEN LOOK window manager.

Frames do not manage events; this task is left up to the windows that the frame manages.

That is, frames do not get mouse and keyboard events and propagate them to child windows.

While frames are subclassed from the window package, the frame’s window rarely sees any

events at all, and if they do, these are not intended to be processed by the application pro-

grammer.

60 XView Programming Manual

4.1 Types of Frames

Basically, two types of frames are available in XView: base frames and command frames.

The main frame of the application is called the base frame. The base frame resides on the

root window; its handle is passed to xv_main_loop() to begin application processing.

A special kind of frame, called a command frame, is created with a panel subwindow by

default. Command frames are useful as help frames, property frames and such defined by

OPEN LOOK. Programmatically, a command frame is no different from a frame with one

subwindow that is a panel.

A base frame’s parent is the root window, whereas a subframe’s parent is another frame

(either a base frame or a subframe). When a frame goes away (quit or close), all of its child

windows, including subframes, also go away. For example, assume you create a command

subframe to display application-specific help. When this command subframe is activated, it

might display explanatory text along with an OK button to dismiss the help. If you close the

base frame, the help subframe also closes.

XView allows for multiple frames that are not children of the base frame. For instance, you

could create a help frame that is independent of the application’s base frame. The parent of

this frame is the root window of the display and not the base frame. The help frame will

remain visible even if the base frame goes away. The term subframe defines a relationship

among frames at creation time and a slight difference in functionality.

4.1.1 The Role of the Window Manager

It is important to understand what effect the window manager has in determining the appear-

ance and behavior of an XView frame. As mentioned earlier, many attributes defined in the

FRAME package are really hints to the window manager. The window manager is responsible

for frame and window decoration, as well as the size and placement of windows on the

screen (screen geometry). That is, it is the window manager’s job to provide such decora-

tions as title bars and to set attributes such as the color of decorations. It also handles resiz-

ing windows, moving windows, closing windows (iconifying) and so on. The application can

ask the window manager to do things in a certain way, but the window manager is not obli-

gated to act on these requests.

For your application and the window manager to communicate properly, the window man-

ager must comply with the specifications in the Inter-Client Communication Conventions

Manual (

ICCCM

).* Since the window manager is a client of the X server just as the applica-

tion is a client, the two clients must follow specified conventions to communicate with one

another. The FRAME package assumes it is communicating with an OPEN LOOK-compliant

window manager. If not, some of the frame attributes might not work as described here.

*The Inter-Client Communication Conventions Manual is reprinted as Appendix L of Volume Zero, X Protocol Ref-

erence Manual.

Frames

Frames 61

For example, using an OPEN LOOK window manager, a command subframe is a pop-up win-

dow that has a pushpin in the upper-left corner. The state of the pushpin (unpinned or

pinned) determines whether or not the window remains on the screen after the command has

been executed. The pin objects are provided by the OPEN LOOK window manager. If XView

applications are run with another window manager, they might not necessarily be pinnable.

4.2 Base Frames

Let’s first create a base frame using the default attribute settings. To create a frame, use

xv_create, specifying the owner of the frame and identifying the FRAME package. The

program in Example 4-1 shows how to create a simple base frame.

Example 4-1. The simple_frame.c program

#include <xview/xview.h>

main()

{

Frame frame;

frame = (Frame)xv_create(NULL, FRAME, NULL);

xv_main_loop(frame);

}

Specifying NULL as the owner argument tells the FRAME package to use the default value,

which specifies the root window on the current screen. The macro FRAME is defined to be

FRAME_BASE, which is the base FRAME package in XView.

Note that the header file associated with the

FRAME package, <xview/frame.h>, is included

indirectly by <xview/xview.h>. (A separate inclusion has no harmful effect, however.)

The frame displayed by this program is shown in Figure 4-3.

4.2.1 XView Initialization and Base Frames

The first XView object to be created by an application is typically the base frame. However,

xv_init() is always called first to get any command-line parameters, initialize the con-

nection to the X server, set resources, and so on. The code segment in Example 4-2 shows

how argc and argv can be used in conjunction with xv_init().

Example 4-2. Creating a base frame after calling xv_init()

main(argc, argv)

int argc;

char *argv[ ];

{

Frame frame;

...

xv_init(XV_INIT_ARGC_PTR_ARGV, &argc, argv, NULL);

frame = (Frame)xv_create(NULL, FRAME, NULL);

62 XView Programming Manual

Example 4-2. Creating a base frame after calling xv_init() (continued)

...

xv_main_loop(frame);

exit(0);

}

Figure 4-3. Simple base frame created without any FRAME attributes specified

In this sample code segment, the program expects no parameters that are specific to the pro-

gram. Any parameters that the user supplies are expected to be specific to XView or X.

When xv_init() is called with attribute XV_INIT_ARGC_PTR_ARGV, &argc and argv

are passed as values; upon return, argv is stripped of the parameters that are X or XView-

specific. The argc variable is also modified to reflect the number of parameters that remain

after processing. If the user specified no other parameters, then argc should be 1 and argv

should contain one element in its array of strings: the name of the program (since that is

what argv[0] is). If there are any more parameters, then the application has the opportu-

nity to look for application-specific parameters or to report unknown parameters as errors.

When the attribute

XV_INIT_ARGS is used, the value of argc (not the address of argc) is

passed, and neither variable is modified.

4.2.2 Headers and Footers

The OPEN LOOK window manager provides frames with headers that display text. The

header typically displays information such as the application name. The text is centered and

its font is not alterable by the application. The header also has a Close button at the upper-

left corner; selecting the button causes the frame to iconify—that is, the frame turns into a

graphical image, or icon, and is displayed (probably) elsewhere on the screen. The applica-

tion’s state is now closed. This usually indicates that the program is idle.

Frames

Frames 63