fisher@star.dec.com (Burns Fisher ZKO1-1/D42 DTN 381-1466) (05/23/87)
We propose the following as a "standard extension" (is this an oxymoron?) to the
X11 protocol to provide a framework for supporting additional input devices.
Notice that this proposal depends on DEVICE, a data type which is likely to be
removed from the core protocol. Initially, assume that this proposal defines
DEVICE as it was defined in the X alpha update core protocol. Perhaps we can
find a more satisfactory definition in the course of reviewing this proposal.
Notice also that this proposal provides a few basic capabilities which are
general for all devices, namely inquiry, turning on and off, focus, and
grabbing. New devices support extensions will probably need to define events to
suit their own needs. They may also need extension requests to do things like
titles (for example, the backlights on button boxes), mode changes, etc.
This proposal was developed by Pam Levesque at DEC in Nashua, NH, in
conjunction with a number of other DEC folks, including the sample server
developers in Palo Alto.
An X Extension to Support Additional Input Devices
Client Requests
---------------
ListInputDevices
=>
device-list: LISTofDEVICE
Returns a list of input devices available in the server.
The list does not include the system keyboard and pointer.
SetInputDevice
device: DEVICE
state: {ON, OFF}
Errors: Device, Access
Turns a non-standard input device on or off.
This request fails if another client has grabbed the device.
SetDeviceFocus
device: DEVICE
focus: WINDOW or PointerRoot or None
revert-to: {Parent, PointerRoot, None}
timestamp: TIMESTAMP or CurrentTime
Errors: Device, Window, Value
Changes the focus for the specified non-standard device, and
sets the last-focus-change time. This request has no effect
if the specified time is earlier than the current
last-focus-change time or is later than the current server
time.
If None is specified as the focus, all device events are
discarded until a new focus window is set. In this case,
the revert-to argument is ignored.
If a window is specified as the focus, it becomes the focus
window for the specified non-standard device. If a generated
device event would normally be reported to this window or one
of its inferiors, the event is reported normally; otherwise,
the event is reported with respect to the focus window.
If PointerRoot is specified as the focus, the focus window
is dynamically taken to be the root window of whatever screen
the pointer is on at each device event. In this case, the
revert-to argument is ignored.
This request generates DeviceFocusIn and DeviceFocusOut events.
If the focus window becomes not viewable, the new focus window
depends on the revert-to argument. If revert-to is Parent,
the focus reverts to the parent (or the closest viewable
ancestor) and the new revert-to value is taken to be None.
If the revert-to is PointerRoot or None, the focus reverts
to that value. When the focus reverts, DeviceFocusIn and
DeviceFocusOut events are generated, but the last-focus-change
time is not affected.
GetDeviceFocus
device: DEVICE
=>
focus: WINDOW or PointerRoot or None
revert-to: {Parent, PointerRoot, None}
Errors: Device
Returns the current focus state.
GrabInputDevice
device: DEVICE
grab-window: WINDOW
owner-events: BOOL
event-mask: SETofEVENT
time: TIMESTAMP or CurrentTime
=>
status: {Success, AlreadyGrabbed, InvalidTime}
Errors: Device, Access
Actively grabs control of the specified non-standard device.
Further events are reported only to the grabbing client. The request
overrides any active grab by this client.
The specified device must previously have been declared to the
server by an extension. Available devices can be determined by
the ListInputDevice request.
This request does not operate on either the system pointer or
keyboard.
If owner-events is False, all generated device events are
reported with respect to grab-window, and are reported only if
selected by event-mask. If owner-events is True, then if a
generated device event would normally be reported to this client,
it is reported normally; otherwise the event is reported with
respect to the grab-window, and is only reported if selected
by event-mask. For either value of owner-events, unreported
events are simply discarded.
The request fails with status AlreadyGrabbed if the pointer is
actively grabbed by some other client. The request fails with
status NotViewable if grab-window is not viewable. The request
fails with status InvalidTime if the specified time is earlier
than the last-device-grab time or later than the current server
time; otherwise the last-device-grab time is set to the specified
time.
UngrabInputDevice
device: DEVICE
time: TIMESTAMP or CurrentTime
Errors: Device
Releases the specified non-standard input device if the client
had it actively grabbed. The request has no effect if the specified
time is earlier than the last-device-grab time or is later than the
current server time.
QueryDevice
device: DEVICE
=>
device-info: DeviceRecord
Errors: Device
A device record consists of current state (on/off), map length,
and a list of event records. Event records define the events which
may be generated by this device. An event record contains an event
type and its associated event mask.
Extension Events
----------------
DeviceFocusIn and DeviceFocusOut
event: WINDOW
mode: {Normal, WhileGrabbed, Grab, Ungrab}
detail: {Ancestor, Virtual, Inferior, Nonlinear, NonlinearVirtual,
Pointer, PointerRoot, None}
device: DEVICE
Generated when the device focus changes. Reported to clients
selecting FocusChange on the window.
These events are identical to FocusIn and FocusOut, except that
a device id is added.
Refer to the description of FocusIn and FocusOut events in the
core protocol for a full description of mode and detail.