UserInputGetActions.mesa
Copyright Ó 1990, 1991, 1992 by Xerox Corporation. All rights reserved.
Bier, July 24, 1990 12:06 pm PDT
Christian Jacobi, February 24, 1992 11:19 am PST
Contents: UserInputGetActions allows to remove a rich and extensible set of actions from an UserInput Handle.
DIRECTORY
KeyTypes USING [KeyCode, KeySym],
RelativeTimes USING [TimeStamp],
UserInput USING [Handle],
UserInputTypes USING [Acceptance, WaitMode];
UserInputGetActions:
CEDAR
DEFINITIONS =
BEGIN
Acceptance: TYPE ~ UserInputTypes.Acceptance;
DeltaTime: TYPE ~ INT32; -- in milliseconds.
Handle: TYPE ~ UserInput.Handle;
KeyCode: TYPE ~ KeyTypes.KeyCode;
KeySym: TYPE ~ KeyTypes.KeySym;
TimeStamp:
TYPE ~ RelativeTimes.TimeStamp;
in milliseconds, relative to an arbitrary per-handle starting point.
WaitMode: TYPE ~ UserInputTypes.WaitMode;
Getting Actions from the UserInput queue. Note that only some of the fields of an InputActionBody are valid at a time, depending on the value of a.kind. See the comment below for details.
GetInputAction:
PROC [handle: Handle, waitMode: WaitMode ¬ forever, waitInterval: DeltaTime ¬ 100, acceptance: Acceptance ¬ all]
RETURNS [a: InputAction];
Allocates an InputAction and stores the data in it. Returns when an action is available or when the stated period of time ellapses (using the input action timestamps as a clock, not the clock of the local processor). Actions that do not pass the acceptance filter are flushed from the queue if an acceptable action is found within the time limit. Otherwise, they are left on the queue and reconsidered by the next GetInputAction call.
GetInputActionBody:
PROC [handle: Handle, waitMode: WaitMode ¬ forever, waitInterval: DeltaTime ¬ 100, acceptance: Acceptance ¬ all]
RETURNS [a: InputActionBody];
A version of GetInputAction that does not allocate.
InputAction: TYPE = REF InputActionBody;
InputActionBody:
TYPE =
RECORD [
kind: ATOM ¬ $TimeOut,
eventTime: TimeStamp,
deltaTime: DeltaTime,
device: REF ¬ NIL,
user: REF ¬ NIL,
data: REF ¬ NIL,
down: BOOL ¬ TRUE,
keyCode: KeyCode ¬ NULL,
preferredSym: KeySym ¬ [0],
x, y: INTEGER ¬ 0,
rx, ry: REAL ¬ 0.0,
display: REF ¬ NIL,
eventSource: REF READONLY ANY ¬ NIL,
ref: REF ¬ NIL
];
Depending on the value of "kind", the following fields will be valid. Each value of kind only occurs when the given values of acceptance hold.
$TimeOut => no valid fields; acceptance = clicks, clicksAndMotion, or all.
$EventTime => eventTime, data are valid; acceptance = all.
$TimeIsPassing => deltaTime, data are valid; acceptance = all.
$End => deltaTime, data are valid; acceptance = clicks, clicksAndMotion, or all.
$AllUp => deltaTime, device, data are valid; acceptance = all.
$KeyStillDown => deltaTime, keyCode, device, data are valid; acceptance = all.
$Key => deltaTime, device, user, data, down, keyCode, preferredSym are valid; acceptance = clicks, clicksAndMotion, or all.
$IntegerPosition => deltaTime, device, user, data, x, y, display are valid; acceptance = clicksAndMotion or all.
$Position => deltaTime, device, user, data, rx, ry, display are valid; acceptance = clicksAndMotion or all.
$FakePosition => deltaTime, device, user, data, display are valid; acceptance = clicksAndMotion or all.
$Enter => deltaTime, device, user, data, display are valid; acceptance = clicksAndMotion or all.
$Exit => deltaTime, device, user, data, display are valid; acceptance = clicksAndMotion or all.
$Ref => deltaTime, device, user, data, ref are valid; acceptance = <the value of the acceptance variable that was passed to UserInputInsertActions.InsertRef>.
The "eventSource" field allows to recognize what caused this action to be included to handle. It is valid for all values of "kind", but it may or may not be defined for different sources of actions.
Other values of kind may be introduced by adding other interfaces.
InsertInputAction:
PROC [handle: Handle, a: InputAction];
A convenient way to insert an InputAction that was received from GetInputAction on a new queue.
InsertInputActionBody:
PROC [handle: Handle, a: InputActionBody];
A convenient way to insert an InputActionBody that was received from GetInputActionBody on a new queue.
LogNewActions:
PROC [handle: Handle, logger: NewLoggingProc ¬
NIL];
Associates a logging proc with the handle. This proc will be called whenever a new action is received. Useful for debugging.
NewLoggingProc: TYPE = PROC [a: InputActionBody];
END.