ESCAPE -2(3P) — SUNPHIGS LIBRARY

NAME

ESCAPE -2 − request an input event callback routine

SYNOPSIS

C Syntax

void
pescape ( func_id, in, out )
Pintfunc_id;escape function identifier
Pescapein∗in;input data for the function
Pescapeout∗out;OUT output data of the function

FORTRAN Syntax

SUBROUTINE pesc ( FCTID, LIDR, IDR, MLODR, LODR, ODR )
INTEGERFCTIDfunction identification
INTEGERLIDRdimension of input data record array
CHARACTER∗80IDR(LIDR) input data record
INTEGERMLODRmaximum length of output data record
INTEGERLODROUT number of array elements used in ODR
CHARACTER∗80ODR(MLODR) OUT output data record

Required PHIGS Operating States

(PHOP, ∗, ∗, ∗)

DESCRIPTION

Purpose

ESCAPE -2 requests an input event callback routine.

C Input Parameters

func_id
The function identifier for this escape is PUESC_INPUT_NOTIFY_PROC, which is defined in phigs.h to be -2.

inA pointer to a Pescapein union containing the input data record, uesc2_idatarec. It is defined as:

typedef struct {
void(∗notify_proc)();
} Puesc0002_idatarec; /∗ Input event notification ∗/

notify_proc
A function pointer to the user’s event notification function.

C Output Parameters

There is no output data record for this escape.

FORTRAN Input Parameters

FCTID
The function identifier of this escape is PUESCINPUTNOTIFY, which is defined in phigs77.h to be -2.

LIDRThe dimension of IDR (returned by the PACK DATA RECORD subroutine).

IDR(LIDR)
An ESCAPE data record packed by the PACK DATA RECORD subroutine containing the input data record required by the ESCAPE function specified in FCTID.

ILThe number of integers = 1.

IAContains one integer value, specifying the C-callable input notification function, or zero, for NULL. To store this function name as an integer, use the conversion function:

INTEGER phigsfunctoint(FUNCNAME)

RLThe number of real values = 0.

SLThe number of strings = 0.

FORTRAN Output Parameters

There is no output data record for this ESCAPE.

Execution

When using Sun Canvas workstations, SunPHIGS allows the application to specify a notification function to be called when input events are placed in the input queue, using ESCAPE -2 , the input notification escape. This notification mechanism is provided so that a SunView event-driven input model can be used consistently by a SunPHIGS application. Note: this functionality is only available with Sun Canvas workstation types.

The escape input data record contains the function pointer. If an event notification function is specified, SunPHIGS will call that function when an input event (or sequence of simultaneous input events) are placed in the PHIGS input queue. When called, the application’s notification function may read events from the queue only by using the PHIGS input event retrieval mechanism, i.e., AWAIT EVENT followed by a GET <device class>. The application may also choose to ignore the notification and retrieve the events at a later time. Notification will occur for any and all input devices in EVENT mode. Event notification does not remove events from the input queue.

The application’s notification function will be called only when an input event is queued or the operator has attempted to queue an event but the queue has overflowed; therefore, if events exist in the input queue when the function is specified (when the escape function is called), no notification will be given until a new event is placed in the queue.

A new notification function can be specified any time PHIGS is open. A value of NULL as the function pointer will remove the currently specified function.

The use of this functionality in no way affects the PHIGS input queue, nor does it change the general input model. Only events in EVENT mode will cause notification to be given, and the application must still use the PHIGS mechanisms to retrieve the event. Notification does not remove the event from the input queue, only AWAIT EVENT does that.

Museum