Volume 7A: XView Programming Manual

The footer of a base frame shows text such as error messages, a page number, the date or

other miscellaneous information. The footer is split into two parts: the left footer where text

is left justified, and the right footer where the text is right justified.

Unless otherwise specified by giving the appropriate attribute-value pairs, the header of a

base frame is displayed, but the footer is not. The header does contain the abbreviated menu

button, but there is no default header label. Thus, to create a header with a label, the attribute

FRAME_LABEL must have a string value.* This may be a constant string or a variable pointing

to a string. When the frame is displayed, the string will be centered in the header. The

header label can be turned off by setting the FRAME_SHOW_HEADER attribute to FALSE. In this

case, even if the header label is set, the header (including the Close button) will not be

displayed at all. If FRAME_SHOW_HEADER is later set to TRUE, then the label will be displayed

again (see Figure 4-4). Note, some window managers, (including olwm) will only honor

requests to change certain aspects of the decor window when the window is coming out of

withdrawn state (unmapped). Any requests made to a mapped window to change information

about the decor will be held off until the window is withdrawn and mapped again. Thus the

result of setting the header to FALSE will not be seen until the frame is unmapped and then

mapped again.

Figure 4-4. A sample header label display in a frame

The code segment in Example 4-3 sets FRAME_SHOW_HEADER to FALSE at creation but sets it

to TRUE in a separate call. The header displays the name of the program.

*FRAME_LABEL is defined to be XV_LABEL in <xview/frame.h>.

64 XView Programming Manual

Example 4-3. Setting separate values for a frame header

...

Frame frame;

frame = (Frame)xv_create(NULL, FRAME,

FRAME_LABEL, argv[0],

FRAME_SHOW_HEADER, FALSE, NULL);

...

xv_set(frame, FRAME_SHOW_HEADER, TRUE, NULL);

...

Footers in base frames are not displayed by default, so setting either the left or right footer

messages also requires the boolean FRAME_SHOW_FOOTER to be set to TRUE. Note that setting

the footer on and off resizes the total size of the base frame, and while it does not cause any

subwindows to be resized, it is rather distracting to change the frame frequently (or at all).

Therefore, you should decide ahead of time whether you are going to use footers and set

them to be on or off at the time the frame is created. If the footer is no longer needed, set the

left or the right footer string to the null string—not the constant NULL. That is, use "". Fig-

ure 4-5 shows what is displayed when the code in Example 4-4 is run.

Example 4-4. Creating a footer

...

Frame frame;

frame = (Frame)xv_create(NULL, FRAME,

FRAME_LABEL, "hdrs_n_footers",

FRAME_SHOW_FOOTER, TRUE,

FRAME_LEFT_FOOTER, "left side",

FRAME_RIGHT_FOOTER, "right side",

NULL);

...

Figure 4-5. Headers and footers on base frame

Frames

Frames 65

4.2.3 Closed Base Frames

Base frames are distinct from other types of frames because they can be closed, or iconified.

When the frame is closed, an icon replaces the entire base frame, including all subwindows

and control areas.* If any subframes are associated with the base frame, then they are taken

down for as long as the application is closed. Using the appropriate attribute-value pairs, it is

possible to set the image and size of the icon. By default, no icon is associated with a base

frame and the size of the area occupied by an icon is 64x64. See Chapter 14, Icons, for more

information on creating icons used by frames. The bounding box (or Rect) of the icon is

independent of the size of the icon, so the bounding box should be set explicitly if its value is

anything other than the default.

The frame’s dimensions when closed and the icon it uses may be set using xv_create() or

by using xv_set() after the frame has been created. Figure 4-6 shows what any applica-

tion or base frame looks like when it is closed, providing that the application uses the base

frame with default values. The figure also shows a graphical icon used by an application.

Figure 4-6. Default icon and application icon

To set the icon for the base frame, the icon must already have been created. However, assum-

ing one is available, the icon can be set in the base frame using the FRAME_ICON attribute-

value pair. FRAME_ICON will not have an immediate effect on mapped icon’s. One must first

unmap the icon, change the icon, and then remap. Because the icon might not be the default

size (64x64), it is usually a good idea to set the size of the frame when it is in the closed state.

To do this, set the attribute FRAME_CLOSED_RECT to be a pointer to a variable of type Rect *

(pointer to a Rect). (Rect is an XView data type defined in <xview/rect.h>.)

The best way to handle it is to use xv_set() after the call to xv_create():

...

extern Icon icon;

Frame frame;

Rect rect;

...

rect.r_width = (int)xv_get(icon, XV_WIDTH);

rect.r_height = (int)xv_get(icon, XV_HEIGHT);

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

xv_set(frame,

FRAME_ICON, icon,

FRAME_CLOSED_RECT, &rect,

NULL);

*Only base frames have icons associated with them.

66 XView Programming Manual

This code segment sets the size of the icon area to be whatever size the icon is. Since

FRAME_CLOSED_RECT takes a pointer to a variable of type Rect, the address of the variable

is given as the value parameter to the call to xv_set(). Also note that the other fields of

the rect variable, (r_top, r_left) are not used because FRAME_CLOSED_RECT only uses

the width and height dimensions from the variable.

The following call can be made to determine whether the frame is currently closed from

within the application:

is_closed = (Boolean) xv_get(frame, FRAME_CLOSED);

This call is useful for applications that are graphics-intensive. If a complex piece of code is

about to be executed, the application could check to see if the frame is open to display the

graphics.

Another way to change the icon, without worrying about whether the frame is mapped, is to

change the server_image associated with the icon.

extern Icon icon;

Frame frame;

icon = xv_get(frame, FRAME_ICON);

xv_set(icon, ICON_IMAGE, new_image, ICON_MASK_IMAGE, new_mask, NULL);

This method of changing the icon works regardless of whether the frame is in its iconic state,

assuming the Server_image new_image is defined.

4.2.4 Quit Confirmation

OPEN LOOK

specifies that a notice is generally not needed to confirm a “quit” action unless

data will be lost. The base frame, which usually handles this type of action through the win-

dow manager, can be set to ask for confirmation. The attribute

FRAME_NO_CONFIRM, which

defaults to TRUE, can be set to FALSE to force confirmation:

frame = (Frame)xv_create(NULL, FRAME,

FRAME_NO_CONFIRM, FALSE,

NULL);

When the attribute FRAME_NO_CONFIRM is set to FALSE and the user initiates a “quit” action,

a notice dialog box will appear to request confirmation.

Frames

Frames 67

4.3 Command Frames

Command frames are normally subframes in that they are most often created as children of

base frames. Most of the time, they are pop-up frames that serve one function and then go

away. Instead of having a Close button in the frame’s header, the command frame has a

pushpin. The pushpin governs whether the frame remains up after the user performs the

functions that the pop-up frame provides. When a command frame is created, a default panel

is also created automatically. The panel on a command frame can be used to hold the panel

items, such as buttons or sliders, that the user interacts with. xv_get() can be used on

command frames to get the default panel and to avoid creating a new one. A pop-up frame

can have its own child pop-up frame, but this is not a good programming practice.

Example 4-5 shows a simple program that creates a pop-up frame as a child of the base

frame. Figure 4-7 displays the output of this program.

Example 4-5. Creating a subframe

/*

* subframe.c -- display a subframe from a base frame.

*/

#include <xview/xview.h>

main(argc, argv)

int argc;

char *argv[ ];

{

Frame frame, subframe;

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

frame = (Frame)xv_create(NULL, FRAME,

XV_WIDTH, 100,

XV_HEIGHT, 100,

FRAME_LABEL, "Base Frame",

NULL);

subframe = (Frame)xv_create(frame, FRAME_CMD,

XV_WIDTH, 100,

XV_HEIGHT, 100,

FRAME_LABEL, "Popup",

NULL);

xv_set(subframe, XV_SHOW, TRUE, NULL);

xv_main_loop(frame);

}

68 XView Programming Manual