Volume 7A: XView Programming Manual

These values correspond to the notice’s status. The notice status contains the value of the but-

ton that was selected on the notice. The location where the status is stored can be set with the

attribute NOTICE_STATUS. If NOTICE_STATUS is not set, the notice status can still be

obtained by using xv_get() on NOTICE_STATUS. If the attributes NOTICE_BUTTON_YES

and NOTICE_BUTTON_NO are used, the notice status is either set to NOTICE_YES or

NOTICE_NO, depending upon the user’s notice button selection, which causes the notice to

pop-down. As shown in simple_notice.c, the strings associated with the “Yes” and “No” but-

tons are set with the attributes NOTICE_BUTTON_YES and NOTICE_BUTTON_NO. The notice

button created with NOTICE_BUTTON_YES is the default button and will have the OPEN LOOK

default ring around it.

The notice choices listed above also respond to accelerator keys. In other words, in addition

to the RETURN key, whatever key that is mapped to the semantic action

ACTION_DEFAULT_ACTION can also be used to select the NOTICE_BUTTON_YES button. The

key that is mapped to the semantic action ACTION_STOP can be used to select the

NOTICE_BUTTON_NO button.

When the notice window is mapped, the cursor is immediately warped (moved) to the default

button since it is the default response of the notice.

It is quite common for the application to have more than one appropriate response to some

kind of notice prompt. Suppose that your application is an editor of some kind. If the user

selects the Quit button and there have been changes to the file that have not been accounted

for, you might wish to inform the user and allow more than one response: quit, updating

changes; quit, ignoring changes; or cancel the quit all together. To implement more than two

choices, use the NOTICE_BUTTON attribute to define the choices available:

xv_create(panel, NOTICE,

NOTICE_MESSAGE_STRINGS,

"There have been modifications since your last update",

"Would you like to quit or continue editing?",

NULL,

NOTICE_BUTTON, "Quit, Update changes", 101,

NOTICE_BUTTON, "Quit, Ignore changes", 102,

NOTICE_BUTTON, "Continue Editing", 103,

NULL);

The NOTICE_BUTTON attribute takes two parameters: the button label* and the value for the

button selection. The application should make its decision on how to proceed based on the

button value specified. In this case, the notice would need to handle cases for NOTICE_STA-

TUS

having values of 101, 102, and 103 (in addition to possible errors).

Because the NOTICE_BUTTON attribute is used, there is no button that is bound to the default

NOTICE_YES choice. But since OPEN LOOK requires a default button for every notice, the

default button will be the first button. In this case, the “Quit, Update changes” button will

have the default ring around it.

If no buttons are specified for a notice, a default button labeled “Confirm” with a value set to

NOTICE_YES is provided.

* The button can display text only; no graphic images can be displayed.

312 XView Programming Manual

The Mouseless Model allows keyboard actions for selecting and moving between notice but-

tons (refer to Section 6.13, “The Mouseless Model,” in Chapter 6, Handling Input).

12.2 Types of Notices

The simple_notice.c program shows a default, standard notice. The default notice does

not lock the screen but does block the thread of execution. This section describes the two

types of notices:

• Standard notices that do not lock the screen. Standard notices have two varieties: those

that block the input to the application, and those that do not.

• Screen-locking notices that lock the screen and blocks input to the application.

The Boolean attribute NOTICE_LOCK_SCREEN determines the type of the notice. When

NOTICE_LOCK_SCREEN is FALSE, the attribute NOTICE_BLOCK_THREAD determines whether

the notice blocks the input to the application.

After creating a notice and popping it up or down, you can change its type. For example, if

notice is created with

NOTICE_LOCK_SCREEN set to TRUE (a screen-locking notice), the

following call is valid:

xv_set(notice, NOTICE_LOCK_SCREEN, FALSE,

NULL);

After doing this your notice is a standard notice and you can, if necessary, use the type-spe-

cific attributes that apply to the standard notice (such as NOTICE_BLOCK_THREAD).

12.2.1 Standard Notices

When the attribute

NOTICE_LOCK_SCREEN

is set to FALSE, the notice is a standard notice and

it does not lock the screen (this is the default value for NOTICE_LOCK_SCREEN). Whether it

blocks the thread of execution depends upon the value of the attribute

NOTICE_BLOCK_THREAD (its default value is TRUE). The attribute NOTICE_STATUS is used to

determine which button was pressed.

When the notice is displayed, the state of the application’s other windows is as follows:

• If

NOTICE_BLOCK_THREAD is set to TRUE, then no windows of the application, except the

notice window, will detect mouse and keyboard input (also see xv_window_loop()).

• If NOTICE_BLOCK_THREAD is set to FALSE, only the frame that owns the notice will

ignore mouse and keyboard input. Additional frames that need to be put in this state can

be added with NOTICE_BUSY_FRAMES. All such frames will have their headers grayed out

(also see FRAME_BUSY).

Notices

Notices 313

Table 12-1 lists additional notice attributes that apply only to standard notices (when

NOTICE_LOCK_SCREEN is FALSE).

Table 12-1. Notice Attributes (used with NOTICE_LOCK_SCREEN

=

FALSE)

Attribute Procedures

NOTICE_BLOCK_THREAD create, set

NOTICE_BUSY_FRAMES create, set

NOTICE_EVENT_PROC create, set

Standard notices are centered in the owner frame and are always on top of the frame that

owns them. If the frame is in the iconified state when the notice is mapped, the notice will be

placed centered at the location of the pointer.

NOTICE_BLOCK_THREAD is relevant only for standard notices, those that have

NOTICE_LOCK_SCREEN = FALSE. Example 12-2 shows a standard, thread-blocking

notice.

Example 12-2. Creating a standard notice

/*

* Display a notice that does not lock the screen.

* This doesn’t return until a button on the notice is pressed.

* This is a standard blocking notice.

*/

frame_notice = xv_create(frame, NOTICE,

NOTICE_LOCK_SCREEN, FALSE, /* default */

NOTICE_BLOCK_THREAD, TRUE, /* default */

NOTICE_MESSAGE_STRINGS,

"Are you sure you want to Quit?",

NULL,

NOTICE_BUTTON_YES, "Confirm",

NOTICE_BUTTON_NO, "Cancel",

NOTICE_NO_BEEPING, TRUE,

NOTICE_STATUS, &result,

XV_SHOW, TRUE,

NULL);

switch (result) {

case NOTICE_YES:

/*confirm */

exit(0);

break;

case NOTICE_NO:

/* Cancel */

break;

default:

break;

}

314 XView Programming Manual

12.2.1.1 Using a notice callback

The previous notice examples did not use a callback for notice events. A callback may be

defined to handle the notice events for a standard notice. The attribute NOTICE_EVENT_PROC

specifies an application-defined callback procedure that is called when any of the buttons on

the notice are selected. This procedure has the following format:

void

notice_event_proc(notice, value, event)

Xv_Notice notice; /* public handle to notice */

int value; /* value associated with button */

Event *event; /* Pointer to struct with event info.*/

This procedure is called before the notice pops down. If a procedure is not specified for

NOTICE_EVENT_PROC, the notice still pops down when a button is pressed. Example 12-3

demonstrates a notice using

NOTICE_EVENT_PROC. In this example, the callback procedure

my_notice_event_proc() is defined to handle all the notice button selections.

Example 12-3. A notice using a callback

xv_create(parent, NOTICE,

NOTICE_LOCK_SCREEN, FALSE,

NOTICE_BUTTON, "Save Changes", 100,

NOTICE_BUTTON, "Cancel", 101,

NOTICE_BUTTON, "Quit", 102,

NOTICE_MESSAGE_STRINGS,

"Press Save Changes to save changes to file and quit",

"Press Cancel to continue",

"Press Quit to quit",

NULL,

NOTICE_EVENT_PROC, my_notice_event_proc,

NULL);

/* my_notice_event_proc() Procedure */

my_notice_event_proc(notice, value, event)

Xv_Notice notice;

int value;

Event *event;

{

switch(value) {

case 100:

/* code for save changes */

break;

case 101:

/* code for cancel */

break;

case 102:

/* code for quit */

break;

default:

printf("Bad button value!!\n");

Notices

Notices 315

Example 12-3. A notice using a callback (continued)

break;

}

}

12.2.1.2 Selecting the busy frames

You can use

NOTICE_BUSY_FRAMES to specify the frames or sub-windows that should be set

to “busy” during notice pop-up. NOTICE_BUSY_FRAMES only takes frames for its values.

The following code shows how to use NOTICE_BUSY_FRAMES.

void my_notice_event_proc();

xv_create(parent, NOTICE,

NOTICE_LOCK_SCREEN, FALSE,

NOTICE_BUTTON, "Save Changes", 100,

NOTICE_BUTTON, "Cancel", 101,

NOTICE_BUTTON, "Quit", 102,

NOTICE_MESSAGE_STRINGS,

"Press Save Changes to save changes to file and quit",

"Press Cancel to continue",

"Press Quit to quit",

NULL,

NOTICE_EVENT_PROC, my_notice_event_proc,

NOTICE_BUSY_FRAMES,

sub_frame1, /* frames to make busy */

sub_frame2, /* during pop-up. */

NULL,

NULL);

12.2.2 Notices That Lock the Screen

To create a screen-locking notice, set

NOTICE_LOCK_SCREEN to TRUE. Screen-locking

notices lock the screen and block the thread of execution for the application. You create a

screen-locking notice as follows:

notice = xv_create(frame, NOTICE,

NOTICE_LOCK_SCREEN, TRUE,

NOTICE_MESSAGE_STRINGS,

"Are you sure you want to Quit?",

NULL,

NOTICE_BUTTON_YES, "Confirm",

NOTICE_BUTTON_NO, "Cancel",

XV_SHOW, TRUE,

NULL);

316 XView Programming Manual