Volume 7A: XView Programming Manual

15.5 The FULLSCREEN Package

The FULLSCREEN package allows XView clients to grab the server for keyboard and/or

pointer use either exclusively or nonexclusively with other applications. This package is

used primarily to prompt the user for immediate feedback on a question or to notify the user

of an error that needs attention. Typically, the user responds with a button press or a key-

board event. The NOTICE package uses the FULLSCREEN package extensively to implement

its functionality. In most cases, you need nothing more than the NOTICE package and should

rarely need to use the FULLSCREEN package. The need for this package arises if you choose

to implement your own notice or perhaps a user interface item that is not OPEN LOOK-

compliant. In either case, this is advanced usage and is beyond the scope of this book. Using

the FULLSCREEN package can be very dangerous because it uses the X server’s grabbing

functions in Xlib. It is possible to get into a state from which you cannot get out except by

killing the server remotely or rebooting your workstation. When using a debugger, be

extremely careful that you do not set breakpoints within code when the server is in the

middle of a grab of some kind. Whatever you do, do not step through code that creates a

FULLSCREEN instance. If this is unavoidable, you should prepare for it by making sure that

you have remote access to your workstation or by attaching a terminal to it so you can kill the

debugger to free the server.

The flow of control for client code using the FULLSCREEN package is to create a fullscreen

instance (grabbing the server), scan for a particular event and destroy the fullscreen instance

(freeing the server).

Creating a fullscreen object (grabbing the server) involves xv_create() as usual:

Fullscreen fs;

fs = xv_create(owner, FULLSCREEN, NULL);

The owner in this case may be a visible XView object that has a window associated with it*

and is currently displayed on the screen (e.g., XV_SHOW is TRUE). If owner is NULL, then the

root window of the default screen is used as the owner.

The attribute WIN_CURSOR can be used with a fullscreen object to set the mouse cursor

displayed while the fullscreen object is active. The default value for WIN_CURSOR is inherited

by the fullscreen object from its owner.

Example 15-4 uses the FULLSCREEN package. A simple panel with two panel buttons is

created. The Quit button quits the program, and the Fullscreen button calls the grab() rou-

tine that grabs the server using the

FULLSCREEN package and waits for a button to be pressed.

Once this happens, the routine frees the fullscreen object, thus releasing the server. Event

masks can be specified when creating a FULLSCREEN object to set what kind of events the cli-

ent window will accept or detect. The event masks are specified using the regular WIN_*

attributes. A similar event mask is also needed for xv_input_readevent().†

*This does not include panel items.

†See Chapter 6, Handling Input, for more information about xv_input_readevent().

Nonvisual Objects

Nonvisual Objects 359

Example 15-4. The fullscreen.c program

/*

* fullscreen.c

* Demonstrate the fullscreen package. Create a panel button that

* creates a fullscreen instance, thus grabbing the X server. User

* presses a mouse button to release the server.

*/

#include <xview/xview.h>

#include <xview/panel.h>

#include <xview/fullscreen.h>

main(argc, argv)

char *argv[ ];

{

Frame frame;

Panel panel;

void exit(), grab();

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

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

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

(void) xv_create(panel, PANEL_BUTTON,

PANEL_LABEL_STRING, "Quit",

PANEL_NOTIFY_PROC, exit,

NULL);

(void) xv_create(panel, PANEL_BUTTON,

PANEL_LABEL_STRING, "Fullscreen",

PANEL_NOTIFY_PROC, grab,

NULL);

window_fit(panel);

window_fit(frame);

xv_main_loop(frame);

}

/*

* Notify procedure for when the "Fullscreen" button is pushed.

* Create a fullscreen instance, scan for a button event, then

* destroy it.

*/

void

grab(item, event)

Panel_item item;

Event *event;

{

Panel panel = (Panel)xv_get(item, PANEL_PARENT_PANEL);

Frame frame = (Frame)xv_get(panel, XV_OWNER);

Fullscreen fs;

Inputmask im;

/* set up an input mask for the call to xv_input_readevent(). */

win_setinputcodebit(&im, MS_LEFT);

win_setinputcodebit(&im, MS_MIDDLE);

win_setinputcodebit(&im, MS_RIGHT);

win_setinputcodebit(&im, LOC_MOVE);

360 XView Programming Manual

Example 15-4. The fullscreen.c program (continued)

/*

* Create a fullscreen object (initialize X server grab).

* Specify which events should be allowed to pass through.

* These events should match the input mask coded above.

*/

fs = xv_create(panel, FULLSCREEN,

WIN_CONSUME_EVENTS,

WIN_MOUSE_BUTTONS, LOC_MOVE, NULL,

NULL);

/* Loop till user generates a button event */

while (xv_input_readevent(panel, event, TRUE, TRUE, &im) != -1)

if (event_is_button(event))

break;

/* Destroy the fullscreen (release the X server grab) */

xv_destroy(fs);

/* Report which button was pushed. */

printf("event was button %d (%d, %d)0,

event_id(event) - BUT_FIRST+1,

event_x(event) + (int)xv_get(frame, XV_X),

event_y(event) + (int)xv_get(frame, XV_Y));

}

When this program is run and the user selects the Fullscreen panel item, the X server is

grabbed and the user must select one of the mouse buttons to release it. To users, it may

appear as though they can select another panel button. Although the panel window is the

owner of the fullscreen object, events that occur while the server is grabbed by the fullscreen

object are not propagated to XView objects under the pointer. In Example 15-4, if the user

presses the mouse button when the pointer is on top of any panel button a panel button while

in fullscreen, the button-down event will trigger the call to xv_input_readevent() and

break the loop. The corresponding button-up event is not read yet and will get read by nor-

mal event processing after the call to grab() returns. If the button-up event happened over

a panel button, then the panel button’s notify routine will be called.

The event masks set by the FULLSCREEN package and by the Inputmask do not interfere

with the event masks in any XView window.

15.5.0.1 Debugging and the

FULLSCREEN

package

There are four global variables in the

FULLSCREEN package that can be used to help debug

XView programs that grab the server, keyboard or pointer. Note that these variables can only

be used via the FULLSCREEN package. Here are the variables with their default values:

int fullscreendebug = 0;

int fullscreengrabserver = 1;

int fullscreengrabpointer = 1;

int fullscreengrabkbd = 1;

When fullscreengrabserver is set to 0 (in source code or in debugger), the X server

will not be grabbed despite requests to grab it.

Nonvisual Objects

Nonvisual Objects 361

When fullscreengrabpointer is set to 0, the pointer will not be grabbed despite

requests to grab it.

When fullscreengrabkbd is set to 0, the keyboard will not be grabbed despite requests

to grab it.

When fullscreendebug is set to 1, no grabs of any kind are performed.

15.6 Nonvisual Package Summary

There are procedures or macros in the nonvisual packages. Table 15-1 lists the attributes in

the SCREEN package. Table 15-2 lists the attributes in the SERVER and SERVERIMAGE pack-

ages and Table 15-3 lists the attributes in the FULLSCREEN package. This information is

described fully in the XView Reference Manual.

Table 15-1. Screen Attributes

SCREEN_NUMBER

SCREEN_SERVER

XV_ROOT

Table 15-2. Server and Server Image Attributes

SERVER_ATOM SERVER_EXTERNAL_XEVENT_PROC

SERVER_ATOM_NAME SERVER_NTH_SCREEN

SERVER_EXTENSION_PROC SERVER_SYNC

SERVER_EXTERNAL_XEVENT_MASK SERVER_SYNC_AND_PROCESS_EVENTS

XV_DISPLAY XV_NAME

Table 15-3. Fullscreen Attributes

FULLSCREEN_ALLOW_EVENTS FULLSCREEN_KEYBOARD_GRAB_KBD_MODE

FULLSCREEN_ALLOW_SYNC_EVENT FULLSCREEN_KEYBOARD_GRAB_PTR_MODE

FULLSCREEN_COLORMAP_WINDOW FULLSCREEN_OWNER_EVENTS

FULLSCREEN_CURSOR_WINDOW FULLSCREEN_PAINT_WINDOW

FULLSCREEN_GRAB_KEYBOARD FULLSCREEN_POINTER_GRAB_KBD_MODE

FULLSCREEN_GRAB_POINTER FULLSCREEN_POINTER_GRAB_PTR_MODE

FULLSCREEN_GRAB_SERVER FULLSCREEN_RECT

FULLSCREEN_INPUT_WINDOW FULLSCREEN_SYNC

362 XView Programming Manual

Table 15-3. Fullscreen Attributes (continued)

WIN_CONSUME_EVENT WIN_IGNORE_EVENT

WIN_CONSUME_EVENTS WIN_IGNORE_EVENTS

WIN_CURSOR WIN_INPUT_MASK

Nonvisual Objects

Nonvisual Objects 363