Volume 7A: XView Programming Manual

12

Notices

A notice is a pop-up window that notifies the user of a problem or asks a question that

requires a response. Generally, notices report serious warnings or errors. OPEN LOOK notices

do not have headers or footers and cannot be moved. The XView notice object is subclassed

from the XView generic object. As with any XView object, you can configure a notice using

attributes and you can use xv_create(), xv_get(), and xv_set(). Figure 12-1 shows

the notice object class hierarchy.

Generic

Object

Notice

Figure 12-1. Notice class hierarchy

XView defines two types of notices, Standard notices and screen-locking notices:

• Standard notices do not lock the screen and are placed centered in the “owner” frame.

This type of notice may either block the application’s thread of execution, or not block.

• Screen-locking notices lock the screen and block input to all applications (the screen is

locked with X grabs). These notices appear with a shadow that emanates from the loca-

tion where an action in an application initiates the notice. This may be a panel button,

such as “Quit,” or some other XView object.

New applications that are created with XView Version 3 should use the

NOTICE package

described in this chapter. Older versions of XView only supported notices with a nonobject-

oriented interface using the notice_prompt() function. For compatibility,

notice_prompt() is still supported. However, for new applications its use is not recom-

mended. Furthermore, the NOTICE package is implemented so that updating applications to

use a notice object is an easy task. Notice objects are only created when the notice package

is used (they are not created when notice_prompt() is used). For more information on

notice_prompt(), refer to Appendix B, Notices.

Notices

Notices 307

Figure 12-2 shows an example of a notice window from the OPEN LOOK GUI Specification.

Figure 12-2. A sample notice window

12.1 Creating and Displaying Notices

To use the NOTICE package, include the header file <xview/notice.h>. It provides the neces-

sary types and definitions for using the package. A notice object’s type is Xv_Notice. In

general, create a notice like any other XView object:

Xv_Notice notice;

Frame owner;

notice = xv_create(owner, NOTICE,

NOTICE_MESSAGE_STRING,

"Please confirm your action.",

NULL,

NULL);

Make a notice visible by setting XV_SHOW to TRUE:

xv_set(notice, XV_SHOW, TRUE, NULL);

Clicking on any button in a notice pops-down the notice. It is not necessary to set XV_SHOW

to FALSE on a notice (the notice package handles this internally).

A notice must have an owner that is a subtype of WINDOW, such as a frame or a panel. If NULL

is used for the owner, an error results and the notice is not created. Typically the window of

the application that causes the notice to be created is the notice’s owner. For example, if the

user tries to type in a read-only text subwindow, a notice might appear from that window

informing the user of the error.

308 XView Programming Manual

Your application has control over the type of the notice (standard or screen-locking), the

messages that are displayed in the notice window, and the choices available to the user as

responses. The notice package creates the notice window, and depending on the type of the

notice, either blocks input to the originating application and does not lock the screen while

waiting for the user to make a selection on one of the available button choices, or, locks the

screen and waits for one of the button choices to be selected (in this case, the screen is frozen

and the application is blocked.) For both types of notices, after the user enters a response in a

notice button, the notice window is unmapped.

The attributes NOTICE_MESSAGE_STRING, NOTICE_MESSAGE_STRINGS, and NOTICE_

MESSAGE_STRINGS_ARRAY_PTR can be used to determine what strings are to be

displayed in a notice. NOTICE_MESSAGE_STRING takes as its value one NULL-terminated

string. This string, however, can contain the character “\n” to serve as a line break. The attri-

bute NOTICE_MESSAGE_STRINGS can take a list of the above strings as its value. This list is

NULL-terminated. Each string in the list will start on a new line. Lastly, NOTICE_MES-

SAGE_STRINGS_ARRAY_PTR

takes a pointer to a NULL-terminated array of strings.

All the strings mentioned above are centered horizontally in the notice.

Below is an example using NOTICE_MESSAGE_STRING:

Xv_Notice notice;

Frame owner;

notice = xv_create(owner, NOTICE,

NOTICE_MESSAGE_STRING,

"Hello!\nPlease confirm your action.\nPress Continue",

NULL);

The following example demonstrates NOTICE_MESSAGE_STRINGS:

Xv_Notice notice;

Frame owner;

notice = xv_create(owner, NOTICE,

NOTICE_MESSAGE_STRINGS,

"Hello!",

"Please confirm your action.\nPress Continue",

NULL,

NULL);

NOTICE_MESSAGE_STRINGS_ARRAY_PTR

takes an array of strings as in the following

example:

char array[5];

array[0] = "Hello!";

array[1] = "This is a sample notice.";

array[2] = "Press Continue.";

array[3] = NULL;

Xv_Notice notice;

Frame owner;

notice = xv_create(owner, NOTICE,

NOTICE_MESSAGE_STRINGS_ARRAY_PTR,

array,

NULL);

Notices

Notices 309

A sample standard notice is demonstrated in Example 12-1.

Example 12-1. The simple_notice.c program

/*

* simple_notice.c -- Demonstrate the use of notices.

*/

#include <xview/xview.h>

#include <xview/panel.h>

#include <xview/notice.h>

Panel panel;

main(argc,argv)

int argc;

char *argv[ ];

{

Frame frame;

Xv_opaque my_notify_proc();

/*

* Initialize XView, create a frame, a panel and one panel button.

*/

xv_init(XV_INIT_ARGS, argc, argv, NULL);

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

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

xv_create(panel, PANEL_BUTTON,

PANEL_LABEL_STRING, "Quit",

PANEL_NOTIFY_PROC, my_notify_proc,

NULL);

/* make sure everything looks good */

window_fit(panel);

window_fit(frame);

/* start window event processing */

xv_main_loop(frame);

}

/*

* my_notify_proc() -- called when the user selects the QUIT button.

* Here the user must choose YES or NO on the notice to confirm

* or deny quitting.

*/

Xv_opaque

my_notify_proc(item, event)

Panel_item item;

Event *event;

{

Xv_notice notice;

int notice_stat;

notice = xv_create(panel, NOTICE,

NOTICE_MESSAGE_STRINGS, "Do you really want to quit?", NULL,

NOTICE_BUTTON_YES, "Yes",

NOTICE_BUTTON_NO, "No",

NOTICE_STATUS, &notice_stat,

310 XView Programming Manual

Example 12-1. The simple_notice.c program (continued)

XV_SHOW, TRUE,

NULL);

switch (notice_stat) {

case NOTICE_YES:

/* Quit */

exit(0);

break;

case NOTICE_NO:

/* Don’t quit */

break;

}

xv_destroy_safe(notice);

}

The program simple_notice.c contains a panel with a Quit button. When the user selects the

Quit button, a notice pops up to prompt the user for confirmation. What the user sees is

shown in Figure 12-3. If the user presses “Yes,” the program exits.

Do you really want to quit?

Yes No

Figure 12-3. Output of simple_notice.c while the notice is up

12.1.1 Notice Values and Status

Two responses are normally available whenever a notice appears: “Yes” and “No.” These are

defined for convenience in <xview/notice.h>:

#define NOTICE_YES 1

#define NOTICE_NO 0

Notices

Notices 311