Volume 7A: XView Programming Manual

/*

* This ensures that no command-line information will

* be stored on this frame.

*/

xv_set(second_frame,

FRAME_WM_COMMAND_ARGC_ARGV, NULL, -1, NULL);

FRAME_WM_COMMAND_ARGC

returns the number of command-line option strings stored on the

frame. FRAME_WM_COMMAND_ARGV returns the array containing the command-line option

strings stored on the frame. The strings in the array must not be modified by client programs.

If the value returned is -1, this means that no command-line information is stored on the

frame.

FRAME_WM_COMMAND_STRINGS works in a similar fashion to FRAME_WM_COM-

MAND_ARGC_ARGV

, but it uses strings. It lets an application set the command-line options that

can be used to (re)start it. The options passed, in addition to XView options are stored on a

property called WM_COMMAND on the frame window. The following example uses

FRAME_WM_COMMAND_STRINGS.

Framebase_frame, second_frame;

/* Ensure that the given options are stored on

* on the base frame

*/

xv_set(base_frame, FRAME_WM_COMMAND_STRINGS,

"-I",

"ls",

"-bold_font",

"courier-bold-14",

NULL,

NULL);

Setting this attribute to -1 prevents any command-line option information from being saved

on the frame. For example:

xv_set(second_frame, FRAME_WM_COMMAND_STRINGS,

-1, NULL, NULL);

4.12 Destroying Frames

When the application wants to exit, the user typically initiates the action via the frame menu.

A call to xv_destroy() destroys the object as well as all objects descended from it.

Therefore, all the objects created by an application can be destroyed simply by destroying the

base frame, assuming that the base frame is the owner of all those objects. Subframes of the

base frame are included, as are icons and panels and so forth. There are exceptions to this

(such as server images or fonts), but those exceptions are covered later in chapters specific to

those objects.

Frames

Frames 79

The following code segment demonstrates how to destroy a base frame. When the routine

quit() is called, which calls xv_destroy_safe() on the base frame, it destroys all the

objects in the frame’s tree, including panels and panel items.

{

...

xv_main_loop(frame);

puts("The program is now done.");

exit(0);

}

quit()

{

xv_destroy_safe(frame);

}

What is significant about this segment is that there is code following the call to

xv_main_loop() so that the routine will return when no more frames are left to display.

The FRAME package keeps track of all the frames in the application. Each time a frame is

created or destroyed, the FRAME package updates its internal count of the number of existing

frames. This includes frames that are not displayed or frames that are iconified. When the

last frame is destroyed, the Notifier stops and xv_main_loop() returns. (Note that the

FRAME package has its own destruction procedures.) Most applications simply exit as shown

in the code fragment above. However, if desired, more frames can be created and the Notifier

can be restarted. For example, the following code shows how the same base frame may be

created five times, assuming that the program does not exit in some manner:

Frame frame;

int i;

for (i = 0; i < 5; i++) {

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

...

xv_main_loop(frame);

}

For this to work, there must be a call to xv_destroy() for each frame in the application.

Granted, this example is rather silly, but consider an application driven by timer interrupts or

by network traffic listening for a particular request. Here, there may be no frames displayed

until the timer goes off or until the network protocol is initiated. Once this happens, the

application that requires user input will create the base frames and enter

xv_main_loop(). When the user is done and has destroyed all the frames,

xv_main_loop() returns and the application can continue waiting for alarm timeouts or

listening for network traffic.

80 XView Programming Manual

4.13 Frame Resize and Repaint Events

This section contains some information on resize events for frames. For a detailed discussion

of events, refer to Chapter 6, Handling Input.

When the size of a window is changed or the window is moved (either by the user or pro-

grammatically), a WIN_RESIZE event is generated to give the client a chance to adjust any

relevant internal state to the new window size. You should not repaint the window when

receiving a resize event. You will receive a separate WIN_REPAINT event when a portion of

the window needs to be repainted.

Top level frames and any other top level windows, when moved, may get multiple resize

events, from the server and from the window manager. ICCCM mandates that the window

manager send these events when the top level window is moved or resized. You can detect

this with the test:

event_xevent(event)->xconfigure.send_event

which returns TRUE on events generated by the window manager. Note that all synthetic

events delivered will follow real events. For more information on the event actions man-

dated by

ICCCM and of the coordinate space mapping, refer to Section L.4.1.15 of Inter-Cli-

ent Communications Manual in Volume Zero, X Protocol Reference Manual.

4.14 Frame Package Summary

Table 4-1 lists the attributes in the FRAME package; the procedures are listed below. This

information is described fully in the XView Reference Manual.

frame_get_rect()

frame_set_rect()

xv_window_loop()

Table 4-1. Frame Attributes

FRAME_ACCELERATOR FRAME_NEXT_PANE

FRAME_BUSY FRAME_NO_CONFIRM

FRAME_CLOSED FRAME_NTH_SUBFRAME

FRAME_CLOSED_RECT FRAME_NTH_SUBWINDOW

FRAME_CMD_DEFAULT_PIN_STATE FRAME_PREVIOUS_ELEMENT

FRAME_CMD_PANEL FRAME_WM_COMMAND_ARGC

FRAME_CMD_PIN_STATE FRAME_WM_COMMAND_ARGC_ARGV

FRAME_DEFAULT_DONE_PROC FRAME_WM_COMMAND_ARGV

FRAME_DONE_PROC FRAME_WM_COMMAND_STRINGS

FRAME_FOCUS_DIRECTION FRAME_X_ACCELERATOR

FRAME_FOCUS_WIN FRAME_PREVIOUS_PANE

FRAME_ICON FRAME_RIGHT_FOOTER

FRAME_INHERIT_COLORS FRAME_SHOW_FOOTER

Frames

Frames 81

Table 4-1. Frame Attributes (continued)

FRAME_LABEL FRAME_SHOW_HEADER

FRAME_LEFT_FOOTER FRAME_SHOW_LABEL

FRAME_MAX_SIZE FRAME_SHOW_RESIZE_CORNER

FRAME_MIN_SIZE

82 XView Programming Manual

This page intentionally left blank

to preserve original page counts.