Volume 7A: XView Programming Manual

Figure 4-7. Base frame with a command frame

4.3.1 Manually Displaying Frames

The attribute XV_SHOW sets whether a window (or frame, in this case) will be displayed. If it

is set to FALSE, the frame will not be seen. Base frames are always displayed because

xv_main_loop sets the XV_SHOW attribute to TRUE. Pop-up frames are not displayed

unless the XV_SHOW attribute is set by the application. An application might create many

pop-up dialog boxes initially and then determine the appropriate time to actually display

them. A callback routine invoked by some action (e.g., panel button selection) from the base

frame might be used to display the pop-up frame. When a command frame is displayed, the

new cursor is moved to the default panel item within the command frame.

When a frame is displayed, the server allocates space for it. If you create an application that

uses many objects and requires a large amount of server memory to display those objects,

then, on servers with limited memory, you may need to specially manage or limit the number

of frames that are displayed.

4.3.2 The Pushpin

On a command frame, the pushpin at the upper-left corner is unpinned by default. The push-

pin is controlled by using both the FRAME_CMD_DEFAULT_PIN_STATE and the FRAME_

CMD_PIN_STATE

attributes. FRAME_CMD_DEFAULT_PIN_STATE controls the initial state of

the command frame’s pin when the frame goes from unmapped (withdrawn) to mapped state.

It is valid for both mapped and unmapped frames. However, if the frame is currently mapped,

the change will be visible only on the next transition from unmapped to mapped state. Valid

values for the state are defined in <xview/frame.h> and include: FRAME_CMD_PIN_IN and

FRAME_CMD_PIN_OUT.

FRAME_CMD_PIN_STATE returns the current state of the pin. It is valid for both mapped and

unmapped frames. For unmapped frames this always returns FRAME_CMD_PIN_OUT.

Frames

Frames 69

A simple example can demonstrate how some of the frame attributes interact. The program

in Example 4-6 builds a base frame with a panel button that says, “Hello.” If selected, a com-

mand frame pops up. The new frame has a panel button that says, “Push Me,” and if pushed,

“Hello World” is printed to stdout. If the command frame’s pushpin is out, once the Push Me

button is selected, the frame is taken down. To get the frame up again, the user must select

Hello again. However, if the pin is in, then the frame remains up for repeated use. Selecting

Hello while the frame is already up causes the command frame to be raised to the top of the

window tree. This is useful in case the command frame gets obscured by other windows.

Example 4-6. Using several frame attributes

/*

* popup.c -- popup a frame and allow the user to interact with

* the new popup frame.

*/

#include <xview/xview.h>

#include <xview/panel.h>

Frame frame; /* top level application base-frame */

Frame subframe; /* subframe (FRAME_CMD) is a child of frame */

main(argc, argv)

int argc;

char *argv[ ];

{

Panel panel;

int show_cmd_frame(), pushed();

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

/* Create base frame */

frame = (Frame)xv_create(NULL, FRAME,

FRAME_LABEL, argv[0],

NULL);

/* Install a panel and a panel button */

panel = (Panel)xv_create(frame, PANEL, NULL);

(void) xv_create(panel, PANEL_BUTTON,

PANEL_LABEL_STRING, "Hello",

PANEL_NOTIFY_PROC, show_cmd_frame,

NULL);

/* Create the command frame -- not displayed until XV_SHOW is set */

subframe = (Frame)xv_create(frame, FRAME_CMD,

FRAME_LABEL, "Popup",

NULL);

/* Command frames have panels already created by default -- get it */

panel = (Panel)xv_get(subframe, FRAME_CMD_PANEL);

(void) xv_create(panel, PANEL_BUTTON,

PANEL_LABEL_STRING, "Push Me",

PANEL_NOTIFY_PROC, pushed,

NULL);

xv_main_loop(frame);

}

70 XView Programming Manual

Example 4-6. Using several frame attributes (continued)

/* Called when base frame’s button is pushed -- show/raise subframe */

show_cmd_frame(item, event)

Frame item;

Event *event;

{

xv_set(subframe, XV_SHOW, TRUE, NULL);

}

/* Called when command frame’s button is pushed */

pushed(item,event)

Panel_item item;

Event *event;

{

printf("Hello world.\n");

/* Check to see if the pushpin is in -- if not, close frame */

/* Return value of FRAME_CMD_PIN_STATE is cast to int */

if ((int)xv_get(subframe,

FRAME_CMD_PIN_STATE) == FRAME_CMD_PIN_IN)

xv_set(subframe, XV_SHOW, FALSE, NULL);

}

Several things are noteworthy in this sample program. First, there is only one Panel vari-

able (called panel). It is used to store the handle to the panel created by the base frame. It

does not matter that this variable is also used to store the return value of the call to:

xv_create(frame, PANEL, NULL)

because its use is temporary. This demonstrates that the programmer need not maintain

handles to objects that are never referenced. A common programming efficiency error is to

declare many variables that reference objects created via xv_create() and then never to

use them. The panel is needed, but only long enough to use it as the owner of the panel but-

ton that is created. Once ownership is established, the handle to that panel is no longer

needed. Therefore, the variable is reused in the call that gets the already created panel from

the subframe. This call is as follows:

panel = (Panel)xv_get(subframe, FRAME_CMD_PANEL)

The handles to the buttons are never needed, so the return values of those creation calls are

ignored. On the other hand, it is always prudent to check for return values in case of error—

had the panel creation returned a NULL handle, then the buttons should not be created. The

sample programs do not demonstrate this type of error checking in order to keep the

examples simple and readable.

4.3.3 The FRAME_DONE_PROC Procedure

If the pushpin is pushed in by the user, the application has no knowledge of this action. How-

ever, if the user pulls the pin out, then the toolkit calls the command frame’s

FRAME_DONE_PROC routine. By default, if the parent of command frame is NULL, then the

frame is unmapped. The programmer can override this behavior by installing another

FRAME_DONE_PROC routine. This is only needed if you want to check that the frame can be

Frames

Frames 71

dismissed. Suppose that the purpose of the subframe is to query for a filename. If the

filename was not given, you might want to display a notice indicating that and allow the user

to type in a filename. In this case, the FRAME_DONE_PROC is responsible for doing the neces-

sary checking and deciding whether to display a notice or to take the frame down.

When you install your own FRAME_DONE_PROC routine, XView will not take down the frame

regardless of what your code does. If you want the frame to be unmapped, by set XV_SHOW to

FALSE.

The parameter passed to your routine is a handle to the subframe itself, as shown in

Example 4-7.

Example 4-7. The subframe.c program

#include <xview/xview.h>

#include <xview/frame.h>

/*

* subframe.c -- create a base frame that has an associated subframe.

* Pull the pin out of the subframe and its FRAME_DONE_PROC procedure

* gets called.

*/

main(argc, argv)

int argc;

char *argv[ ];

{

Frame frame, subframe;

int done_proc();

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

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

subframe = (Frame)xv_create(frame, FRAME_CMD,

FRAME_DONE_PROC, done_proc,

XV_SHOW, TRUE,

NULL);

xv_main_loop(frame);

}

/*

* when the pushpin is pulled out, this routine is called

*/

done_proc(subframe)

Frame subframe;

{

/* we have the choice of vetoing or granting the user’s

* request to dismiss the frame -- if we choose to dismiss

* the frame, we must do it manually. Like so:

*/

xv_set(subframe, XV_SHOW, FALSE, NULL);

/* otherwise, we should push the pin back in */

}

The call to xv_set(XV_SHOW, FALSE) is safe because no action is taken at all if this was

not the result of the pin being pulled out. The frame will not go down (i.e., the xv_set() is

a no-op) if the pin is in or is already out. This gives the programmer the flexibility of using

72 XView Programming Manual

the same function (something like done_proc()) in other places throughout the applica-

tion. For example, it could be used in a callback routine for a panel button.

If the subframe must be taken down regardless of whether the pin is in or out, the application

should forcefully remove the pin using:

xv_set(subframe, FRAME_CMD_DEFAULT_PIN_STATE, FALSE, NULL);

Forcefully removing the pin in this fashion does not result in the frame’s done procedure

getting called. This routine is only called when the pin has been removed as a result of an

action that the user has taken and when the application has no knowledge of this action.

4.3.4 Showing Resize Corners

It should also be noted that the command frame has no resize corners as the base frame does.

This is the default behavior for command frames, but the attribute FRAME_

SHOW_RESIZE_CORNER

can be set to TRUE to force the resize corners to be shown. This

allows the user to resize command frames the same as base frames. Base frames have resize

corners by default, but they can be turned off at creation time or at any time before the frame

is mapped to the screen. After the frame has been displayed, the resize corners may not be

turned off.

4.3.5 Minimum and Maximum Frame Sizes

The attribute FRAME_MIN_SIZE allows you to specify a minimum a frame can be resized. It

takes two integer parameters, specifying the minimum width and height of the frame.

This information is passed onto the window manager as part of the WM_

NORMAL_HINTS property. Note that the minimum size is only a hint to the window man-

ager. Some window managers may choose to ignore certain application specified hints. Set-

ting both the minimum width and height to 0 effectively removes any application controlled

minimum restriction on size. Similarly,

FRAME_MAX_SIZE allows you to specify a maximum

size that a frame can be resized.

4.4 Miscellaneous Attributes

Some frame attributes discussed in the following sections only work with OPEN LOOK win-

dow managers. Attributes such as FRAME_BUSY, FRAME_SHOW_RESIZE_CORNERS,

FRAME_CMD_PINSTATE communicate with the window manager. You will get unpredictable

results if you are not running an OPEN LOOK window manager or if there is no window man-

ager running at all.

Frames

Frames 73