391 lines
12 KiB
Racket
391 lines
12 KiB
Racket
#lang scribble/doc
|
|
@require["common.ss"]
|
|
|
|
@defclass/title[key-event% event% ()]{
|
|
|
|
A @scheme[key-event%] object contains information about a key press
|
|
or release event. Key events are primarily processed by
|
|
@xmethod[window<%> on-subwindow-char] and
|
|
@xmethod[canvas<%> on-char].
|
|
|
|
For a key-press event, a virtual key code is provided by
|
|
@method[key-event% get-key-code]. For a key-release event,
|
|
@method[key-event% get-key-code] reports @scheme['release], and a virtual key code is provided by
|
|
@method[key-event% get-key-release-code].
|
|
|
|
See also @|mousekeydiscuss|.
|
|
|
|
|
|
@defconstructor[([key-code (or/c char? symbol?) #\nul]
|
|
[shift-down any/c #f]
|
|
[control-down any/c #f]
|
|
[meta-down any/c #f]
|
|
[alt-down any/c #f]
|
|
[x (and/c exact? integer?) 0]
|
|
[y (and/c exact? integer?) 0]
|
|
[time-stamp (and/c exact? integer?) 0]
|
|
[caps-down any/c #f])]{
|
|
|
|
See the corresponding @schemeidfont{get-} and @schemeidfont{set-}
|
|
methods for information about @scheme[key-code], @scheme[shift-down],
|
|
@scheme[control-down], @scheme[meta-down], @scheme[alt-down],
|
|
@scheme[x], @scheme[y], @scheme[time-stamp], @scheme[caps-down].
|
|
|
|
The release key code, as returned by @method[key-event%
|
|
get-key-release-code], is initialized to @scheme['press].
|
|
|
|
}
|
|
|
|
@defmethod[(get-alt-down)
|
|
boolean?]{
|
|
Returns @scheme[#t] if the Option (Mac OS X) key was down for
|
|
the event. When the Alt key is pressed in Windows, it is reported as
|
|
a Meta press (see
|
|
@method[key-event% get-meta-down]).
|
|
|
|
}
|
|
|
|
@defmethod[(get-caps-down)
|
|
boolean?]{
|
|
Returns @scheme[#t] if the Caps Lock key was on for the event.
|
|
|
|
}
|
|
|
|
@defmethod[(get-control-down)
|
|
boolean?]{
|
|
Returns @scheme[#t] if the Control key was down for the event.
|
|
|
|
Under Mac OS X, if a control-key press is combined with a mouse button
|
|
click, the event is reported as a right-button click and
|
|
@method[key-event% get-control-down] for the event reports @scheme[#f].
|
|
|
|
}
|
|
|
|
@defmethod[(get-key-code)
|
|
(or/c char? symbol?)]{
|
|
|
|
Gets the virtual key code for the key event. The virtual key code is
|
|
either a character or a special key symbol, one of the following:
|
|
|
|
@itemize{
|
|
@item{@indexed-scheme['start]}
|
|
@item{@indexed-scheme['cancel]}
|
|
@item{@indexed-scheme['clear]}
|
|
@item{@indexed-scheme['shift]}
|
|
@item{@indexed-scheme['control]}
|
|
@item{@indexed-scheme['menu]}
|
|
@item{@indexed-scheme['pause]}
|
|
@item{@indexed-scheme['capital]}
|
|
@item{@indexed-scheme['prior]}
|
|
@item{@indexed-scheme['next]}
|
|
@item{@indexed-scheme['end]}
|
|
@item{@indexed-scheme['home]}
|
|
@item{@indexed-scheme['left]}
|
|
@item{@indexed-scheme['up]}
|
|
@item{@indexed-scheme['right]}
|
|
@item{@indexed-scheme['down]}
|
|
@item{@indexed-scheme['escape]}
|
|
@item{@indexed-scheme['select]}
|
|
@item{@indexed-scheme['print]}
|
|
@item{@indexed-scheme['execute]}
|
|
@item{@indexed-scheme['snapshot]}
|
|
@item{@indexed-scheme['insert]}
|
|
@item{@indexed-scheme['help]}
|
|
@item{@indexed-scheme['numpad0]}
|
|
@item{@indexed-scheme['numpad1]}
|
|
@item{@indexed-scheme['numpad2]}
|
|
@item{@indexed-scheme['numpad3]}
|
|
@item{@indexed-scheme['numpad4]}
|
|
@item{@indexed-scheme['numpad5]}
|
|
@item{@indexed-scheme['numpad6]}
|
|
@item{@indexed-scheme['numpad7]}
|
|
@item{@indexed-scheme['numpad8]}
|
|
@item{@indexed-scheme['numpad9]}
|
|
@item{@indexed-scheme['numpad-enter]}
|
|
@item{@indexed-scheme['multiply]}
|
|
@item{@indexed-scheme['add]}
|
|
@item{@indexed-scheme['separator]}
|
|
@item{@indexed-scheme['subtract]}
|
|
@item{@indexed-scheme['decimal]}
|
|
@item{@indexed-scheme['divide]}
|
|
@item{@indexed-scheme['f1]}
|
|
@item{@indexed-scheme['f2]}
|
|
@item{@indexed-scheme['f3]}
|
|
@item{@indexed-scheme['f4]}
|
|
@item{@indexed-scheme['f5]}
|
|
@item{@indexed-scheme['f6]}
|
|
@item{@indexed-scheme['f7]}
|
|
@item{@indexed-scheme['f8]}
|
|
@item{@indexed-scheme['f9]}
|
|
@item{@indexed-scheme['f10]}
|
|
@item{@indexed-scheme['f11]}
|
|
@item{@indexed-scheme['f12]}
|
|
@item{@indexed-scheme['f13]}
|
|
@item{@indexed-scheme['f14]}
|
|
@item{@indexed-scheme['f15]}
|
|
@item{@indexed-scheme['f16]}
|
|
@item{@indexed-scheme['f17]}
|
|
@item{@indexed-scheme['f18]}
|
|
@item{@indexed-scheme['f19]}
|
|
@item{@indexed-scheme['f20]}
|
|
@item{@indexed-scheme['f21]}
|
|
@item{@indexed-scheme['f22]}
|
|
@item{@indexed-scheme['f23]}
|
|
@item{@indexed-scheme['f24]}
|
|
@item{@indexed-scheme['numlock]}
|
|
@item{@indexed-scheme['scroll]}
|
|
@item{@indexed-scheme['wheel-up] --- \index["wheel on mouse"]{mouse} wheel up one notch}
|
|
@item{@indexed-scheme['wheel-down] --- mouse wheel down one notch}
|
|
@item{@indexed-scheme['release] --- indicates a key-release event}
|
|
@item{@indexed-scheme['press] --- indicates a key-press event; usually only from @scheme[get-key-release-code]}
|
|
}
|
|
|
|
The special key symbols attempt to capture useful keys that have no
|
|
standard ASCII representation. A few keys have standard
|
|
representations that are not obvious:
|
|
|
|
@itemize{
|
|
|
|
@item{@scheme[#\space] --- the space bar}
|
|
|
|
@item{@scheme[#\return] --- the Enter or Return key (on all
|
|
platforms), but not necessarily the Enter key near the numpad
|
|
(which is reported as @scheme['numpad-enter] if the platform
|
|
distinguishes the two Enter keys)}
|
|
|
|
@item{@scheme[#\tab] --- the tab key}
|
|
|
|
@item{@scheme[#\backspace] --- the backspace key}
|
|
|
|
@item{@scheme[#\rubout] --- the delete key}
|
|
|
|
}
|
|
|
|
If a suitable special key symbol or ASCII representation is not
|
|
available, @scheme[#\nul] (the NUL character) is reported.
|
|
|
|
Under X, a @scheme['wheel-up] or @scheme['wheel-down] event may be sent
|
|
to a window other than the one with the keyboard focus, because X
|
|
generates wheel events based on the location of the mouse pointer.
|
|
|
|
Under Windows, when the Control key is pressed without Alt, the key
|
|
code for ASCII characters is downcased, roughly cancelling the effect
|
|
of the Shift key. Under Mac OS X, the key code is computed without
|
|
Caps Lock effects when the Control or Command key is pressed; in the
|
|
case of Control, Caps Lock is used normally if special handling is
|
|
disabled for the Control key via @scheme[special-control-key]. Under
|
|
X, the key code is computed with Caps Lock effects when the Control
|
|
key is pressed without Alt.
|
|
|
|
See also @method[key-event% get-other-shift-key-code].
|
|
|
|
}
|
|
|
|
@defmethod[(get-key-release-code)
|
|
(or/c char? symbol?)]{
|
|
|
|
Gets the virtual key code for a key-release event; the result is
|
|
@scheme['press] for a key-press event. See @method[key-event%
|
|
get-key-code] for the list of virtual key codes.
|
|
|
|
}
|
|
|
|
@defmethod[(get-meta-down)
|
|
boolean?]{
|
|
|
|
Returns @scheme[#t] if the Meta (X), Alt (Windows), or Command (Mac OS
|
|
X) key was down for the event.
|
|
|
|
}
|
|
|
|
@defmethod[(get-other-altgr-key-code)
|
|
(or/c char? symbol? false/c)]{
|
|
|
|
See @method[key-event% get-other-shift-key-code].
|
|
|
|
}
|
|
|
|
@defmethod[(get-other-caps-key-code)
|
|
(or/c char? symbol? false/c)]{
|
|
|
|
See @method[key-event% get-other-shift-key-code].
|
|
|
|
}
|
|
|
|
@defmethod[(get-other-shift-altgr-key-code)
|
|
(or/c char? symbol? false/c)]{
|
|
|
|
See @method[key-event% get-other-shift-key-code].
|
|
|
|
}
|
|
|
|
@defmethod[(get-other-shift-key-code)
|
|
(or/c char? symbol? false/c)]{
|
|
|
|
Since keyboard mappings vary, it is sometimes useful in key mappings
|
|
for a program to know the result that the keyboard would have
|
|
produced for an event if the Shift key had been toggled
|
|
differently. The @method[key-event% get-other-shift-key-code]
|
|
produces that other mapping, returning @scheme[#f] if the alternate
|
|
mapping is unavailable, otherwise returning the same kind of result
|
|
as @method[key-event% get-key-code].
|
|
|
|
The @method[key-event% get-other-altgr-key-code] method provides the
|
|
same information with respect to the AltGr key (i.e., Alt combined
|
|
with Control) under Windows and X, or the Option key under Mac OS
|
|
X. The @method[key-event% get-other-shift-altgr-key-code] method
|
|
reports a mapping for in tha case that both Shift and AltGr/Option
|
|
were different from the actual event.
|
|
|
|
The @method[key-event% get-other-shift-key-code], @method[key-event%
|
|
get-other-altgr-key-code], and @method[key-event%
|
|
get-other-shift-altgr-key-code] results all report key mappings where
|
|
Caps Lock is off, independent of whether Caps Lock was on for the
|
|
actual event. The @method[key-event% get-other-caps-key-code] method
|
|
reports a mapping for in that case that the Caps Lock state was
|
|
treated opposite as for the @method[key-event% get-key-code]
|
|
result. (Caps Lock normally has either no effect or the same effect as
|
|
Shift, so further combinations involving Caps Lock and other modifier
|
|
keys would not normally produce further alternatives.)
|
|
|
|
Alternate mappings are not available for all events. Under Windows,
|
|
alternate mappings are reported when they produce ASCII letters,
|
|
ASCII digits, and ASCII symbols. Under Mac OS X, alternate mappings are
|
|
available only when the Command key is pressed. Under X, alternate
|
|
mappings are usually available.
|
|
|
|
}
|
|
|
|
@defmethod[(get-shift-down)
|
|
boolean?]{
|
|
|
|
Returns @scheme[#t] if the Shift key was down for the event.
|
|
|
|
}
|
|
|
|
@defmethod[(get-x)
|
|
(and/c exact? integer?)]{
|
|
|
|
Returns the x-position of the mouse at the time of the event, in the
|
|
target's window's (client-area) coordinate system.
|
|
|
|
}
|
|
|
|
@defmethod[(get-y)
|
|
(and/c exact? integer?)]{
|
|
|
|
Returns the y-position of the mouse at the time of the event in the
|
|
target's window's (client-area) coordinate system.
|
|
|
|
}
|
|
|
|
@defmethod[(set-alt-down [down? any/c])
|
|
void?]{
|
|
|
|
Sets whether the Option (Mac OS X) key was down for the event. When
|
|
the Alt key is pressed in Windows, it is reported as a Meta press
|
|
(see @method[key-event% set-meta-down]).
|
|
|
|
}
|
|
|
|
@defmethod[(set-caps-down [down? any/c])
|
|
void?]{
|
|
|
|
Sets whether the Caps Lock key was on for the event.
|
|
|
|
}
|
|
|
|
@defmethod[(set-control-down [down? any/c])
|
|
void?]{
|
|
|
|
Sets whether the Control key was down for the event.
|
|
|
|
Under Mac OS X, if a control-key press is combined with a mouse button
|
|
click, the event is reported as a right-button click and
|
|
@method[key-event% get-control-down] for the event reports
|
|
@scheme[#f].
|
|
|
|
}
|
|
|
|
@defmethod[(set-key-code [code (or/c char? symbol?)])
|
|
void?]{
|
|
|
|
Sets the virtual key code for the event, either a character or one of
|
|
the special symbols listed with @method[key-event% get-key-code].
|
|
|
|
}
|
|
|
|
@defmethod[(set-key-release-code [code (or/c char? symbol?)])
|
|
void?]{
|
|
|
|
Sets the virtual key code for a release event, either a character or
|
|
one of the special symbols listed with @method[key-event%
|
|
get-key-code]. See also @method[key-event% get-key-release-code].
|
|
|
|
}
|
|
|
|
@defmethod[(set-meta-down [down? any/c])
|
|
void?]{
|
|
|
|
Sets whether the Meta (X), Alt (Windows), or Command (Mac OS X) key
|
|
was down for the event.
|
|
|
|
}
|
|
|
|
@defmethod[(set-other-altgr-key-code [code (or/c char? symbol? false/c)])
|
|
void?]{
|
|
|
|
Sets the key code produced by @method[key-event%
|
|
get-other-altgr-key-code].
|
|
|
|
}
|
|
|
|
@defmethod[(set-other-caps-key-code [code (or/c char? symbol? false/c)])
|
|
void?]{
|
|
|
|
Sets the key code produced by @method[key-event%
|
|
get-other-caps-key-code].
|
|
|
|
}
|
|
|
|
@defmethod[(set-other-shift-altgr-key-code [code (or/c char? symbol? false/c)])
|
|
void?]{
|
|
|
|
Sets the key code produced by @method[key-event%
|
|
get-other-shift-altgr-key-code].
|
|
|
|
}
|
|
|
|
@defmethod[(set-other-shift-key-code [code (or/c char? symbol? false/c)])
|
|
void?]{
|
|
|
|
Sets the key code produced by @method[key-event%
|
|
get-other-shift-key-code].
|
|
|
|
}
|
|
|
|
@defmethod[(set-shift-down [down? any/c])
|
|
void?]{
|
|
|
|
Sets whether the Shift key was down for the event.
|
|
|
|
}
|
|
|
|
@defmethod[(set-x [pos (and/c exact? integer?)])
|
|
void?]{
|
|
|
|
Sets the x-position of the mouse at the time of the event in the
|
|
target's window's (client-area) coordinate system.
|
|
|
|
}
|
|
|
|
@defmethod[(set-y [pos (and/c exact? integer?)])
|
|
void?]{
|
|
|
|
Sets the y-position of the mouse at the time of the event in the
|
|
target's window's (client-area) coordinate system.
|
|
|
|
}
|
|
}
|
|
|