.\"
.\" $XConsortium: p008,v 5.2 94/04/17 20:54:17 rws Exp $
.\"
.\" 
$XMCOPY
.\" Copyright (c) 1990, 1991 by Sun Microsystems, Inc. and the X Consortium.
.\" 
.\"                         All Rights Reserved
.\" 
.\" Permission to use, copy, modify, and distribute this software and its 
.\" documentation for any purpose and without fee is hereby granted, 
.\" provided that the above copyright notice appear in all copies and that
.\" both that copyright notice and this permission notice appear in 
.\" supporting documentation, and that the names of Sun Microsystems,
.\" and the X Consortium not be used in advertising or publicity 
.\" pertaining to distribution of the software without specific, written 
.\" prior permission.  
.\" 
.\" SUN MICROSYSTEMS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 
.\" INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
.\" EVENT SHALL SUN MICROSYSTEMS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
.\" CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
.\" USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
.\" OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\" PERFORMANCE OF THIS SOFTWARE.
.TH "AWAIT EVENT" 3P "29 February 1991"
.SH NAME
AWAIT EVENT \- move event from input queue to current event report
.IX "Event Input Mode" "AWAIT EVENT"
.IX "Input Modes" "AWAIT EVENT"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pawait_event ( timeout, ws_id, class, in_num )
Pfloat	timeout;	\fItimeout  ( seconds )\fP
Pint	*ws_id;	\fI\s-2OUT\s+2 workstation identifier\fP
Pin_class	*class;	\fI\s-2OUT\s+2 device class\fP
Pint	*in_num;	\fI\s-2OUT\s+2 logical input device number\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, WSOP, *, *)
.SH DESCRIPTION
.SS Purpose
If the input event queue is not empty, \s-2AWAIT EVENT\s+2 moves the
next event in the queue to the current event report in the \s-2PHIGS\s+2
state list.  It returns the workstation identifier, input class, and input
device number of the input device that generated the event.
.LP
If the input queue is empty, \s-2AWAIT EVENT\s+2 suspends \s-2PHIGS\s+2
until an event is entered into the queue or the time specified by
\fItimeout\fP has elapsed.
.SS C Input Parameters
.IP \fItimeout\fP
The time, in seconds, to wait for an event if none are present in the 
input queue.
.SS C Output Parameters
.IP \fIws_id\fP
If the event queue is not empty, \s-2PHIGS\s+2 sets the variable pointed to
by \fIws_id\fP to the identifier of the workstation that was the source of
the input event.
If the queue is empty, \s-2PHIGS\s+2 does not set this variable.
.IP \fIclass\fP
If the event queue is not empty, \s-2PHIGS\s+2 sets the variable pointed to
by \fIclass\fP to the class of the device that generated the input event.
If the queue is empty, \s-2PHIGS\s+2 sets this variable to PIN_NONE.
Pin_class is an enumerated type that may take the following values:
.sp .4
.ta .5i
.nf
typedef enum {
.sp .2
	PIN_NONE,
	PIN_LOC,
	PIN_STROKE,
	PIN_VAL,
	PIN_CHOICE,
	PIN_PICK,
	PIN_STRING
.sp .2
} Pin_class;
.fi
.IP \fIin_num\fP
A pointer to an integer variable.
If the event queue is not empty,
\s-2PHIGS\s+2 sets this variable to the identifier of the input device
that generated the input event.
.SS Execution
The \s-2AWAIT EVENT\s+2 function writes the logical input value of the
oldest input event in the input queue to the current event report in the
\s-2PHIGS\s+2 state list.
The workstation id, device class, and device number of the input device
that generated the event are returned in the output parameters.
The current event report is accessed by the appropriate
\s-2GET\s+2 device class function;
for example, \s-2GET LOCATOR\s+2 or \s-2GET STRING\s+2.
.LP
If there are no events in the input queue when \s-2AWAIT EVENT\s+2 is
called, \s-2AWAIT EVENT\s+2 does not return until an event is added
to the queue or until the time specified by the timeout parameter has 
elapsed.
If a timeout occurs, \s-2PIN_NONE\s+2 is returned as the device class
and the other two values, workstation id and device number,
are undefined.
.LP
Window system events such as repaints and resizes, and events for all active
input devices are processed as usual while \s-2AWAIT EVENT\s+2 is waiting
for a timeout to expire.
.LP
While the timeout can be any positive floating-point value, the effective
timeout resolution depends on the operating system in use.
.SH ERRORS
.IP 003
Ignoring function, function requires state (\s-2PHOP\s+2, \s-2WSOP\s+2, *, *)
.IP 256
Warning, the input queue has overflowed
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "SET VALUATOR MODE (3P)"
.SM "SET STROKE MODE (3P)"
.SM "SET STRING MODE (3P)"
.SM "SET PICK MODE (3P)"
.SM "SET LOCATOR MODE (3P)"
.SM "SET CHOICE MODE (3P)"
.SM "GET CHOICE (3P)"
.SM "GET LOCATOR (3P)"
.SM "GET LOCATOR 3 (3P)"
.SM "GET PICK (3P)"
.SM "GET STRING (3P)"
.SM "GET STROKE (3P)"
.SM "GET STROKE 3 (3P)"
.SM "GET VALUATOR (3P)"
.SM "INQUIRE MORE SIMULTANEOUS EVENTS (3P)"
.SM "INQUIRE INPUT QUEUE OVERFLOW (3P)"
.fi