473 lines
14 KiB
Racket
473 lines
14 KiB
Racket
#lang scribble/doc
|
|
@(require "common.rkt")
|
|
|
|
@defclass/title[key-event% event% ()]{
|
|
|
|
A @racket[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 @racket['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? key-code-symbol?) #\nul]
|
|
[shift-down any/c #f]
|
|
[control-down any/c #f]
|
|
[meta-down any/c #f]
|
|
[alt-down any/c #f]
|
|
[x exact-integer? 0]
|
|
[y exact-integer? 0]
|
|
[time-stamp exact-integer? 0]
|
|
[caps-down any/c #f]
|
|
[mod3-down any/c #f]
|
|
[mod4-down any/c #f]
|
|
[mod5-down any/c #f]
|
|
[control+meta-is-altgr any/c #f])]{
|
|
|
|
See the corresponding @racketidfont{get-} and @racketidfont{set-}
|
|
methods for information about @racket[key-code], @racket[shift-down],
|
|
@racket[control-down], @racket[meta-down], @racket[mod3-down], @racket[mod4-down],
|
|
@racket[mod5-down], @racket[alt-down], @racket[x], @racket[y],
|
|
@racket[time-stamp], @racket[caps-down], @racket[mod3-down],
|
|
@racket[mod4-down], @racket[mod5-down], and @racket[control+meta-is-altgr].
|
|
|
|
The release key code, as returned by @method[key-event%
|
|
get-key-release-code], is initialized to @racket['press].
|
|
|
|
@history[#:changed "1.1" @elem{Added @racket[mod3-down], @racket[mod4-down], and @racket[mod5-down].}
|
|
#:changed "1.2" @elem{Added @racket[control+meta-is-altgr].}]
|
|
}
|
|
|
|
@defmethod[(get-alt-down)
|
|
boolean?]{
|
|
Returns @racket[#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 @racket[#t] if the Caps Lock key was on for the event.
|
|
|
|
}
|
|
|
|
@defmethod[(get-control-down)
|
|
boolean?]{
|
|
Returns @racket[#t] if the Control key was down for the event.
|
|
|
|
On 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 @racket[#f].
|
|
|
|
}
|
|
|
|
|
|
@defmethod[(get-control+meta-is-altgr)
|
|
boolean?]{
|
|
|
|
Returns @racket[#t] if a Control plus Meta event should be treated as
|
|
an AltGr event on Windows. By default, AltGr treatment applies if the
|
|
Control key was the left one and the Alt key (as Meta) was the right one---typed
|
|
that way on a keyboard with a right Alt key, or produced by a single
|
|
AltGr key. See also @racket[any-control+alt-is-altgr], which controls
|
|
whether other Control plus Alt combinations are treated as AltGr.
|
|
|
|
@history[#:added "1.2"]}
|
|
|
|
|
|
@defmethod[(get-key-code)
|
|
(or/c char? key-code-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[
|
|
#:style 'compact
|
|
@item{@indexed-racket['start]}
|
|
@item{@indexed-racket['cancel]}
|
|
@item{@indexed-racket['clear]}
|
|
@item{@indexed-racket['shift] --- Shift key}
|
|
@item{@indexed-racket['rshift] --- right Shift key}
|
|
@item{@indexed-racket['control] --- Control key}
|
|
@item{@indexed-racket['rcontrol] --- right Control key}
|
|
@item{@indexed-racket['menu]}
|
|
@item{@indexed-racket['pause]}
|
|
@item{@indexed-racket['capital]}
|
|
@item{@indexed-racket['prior]}
|
|
@item{@indexed-racket['next]}
|
|
@item{@indexed-racket['end]}
|
|
@item{@indexed-racket['home]}
|
|
@item{@indexed-racket['left]}
|
|
@item{@indexed-racket['up]}
|
|
@item{@indexed-racket['right]}
|
|
@item{@indexed-racket['down]}
|
|
@item{@indexed-racket['escape]}
|
|
@item{@indexed-racket['select]}
|
|
@item{@indexed-racket['print]}
|
|
@item{@indexed-racket['execute]}
|
|
@item{@indexed-racket['snapshot]}
|
|
@item{@indexed-racket['insert]}
|
|
@item{@indexed-racket['help]}
|
|
@item{@indexed-racket['numpad0]}
|
|
@item{@indexed-racket['numpad1]}
|
|
@item{@indexed-racket['numpad2]}
|
|
@item{@indexed-racket['numpad3]}
|
|
@item{@indexed-racket['numpad4]}
|
|
@item{@indexed-racket['numpad5]}
|
|
@item{@indexed-racket['numpad6]}
|
|
@item{@indexed-racket['numpad7]}
|
|
@item{@indexed-racket['numpad8]}
|
|
@item{@indexed-racket['numpad9]}
|
|
@item{@indexed-racket['numpad-enter]}
|
|
@item{@indexed-racket['multiply]}
|
|
@item{@indexed-racket['add]}
|
|
@item{@indexed-racket['separator]}
|
|
@item{@indexed-racket['subtract]}
|
|
@item{@indexed-racket['decimal]}
|
|
@item{@indexed-racket['divide]}
|
|
@item{@indexed-racket['f1]}
|
|
@item{@indexed-racket['f2]}
|
|
@item{@indexed-racket['f3]}
|
|
@item{@indexed-racket['f4]}
|
|
@item{@indexed-racket['f5]}
|
|
@item{@indexed-racket['f6]}
|
|
@item{@indexed-racket['f7]}
|
|
@item{@indexed-racket['f8]}
|
|
@item{@indexed-racket['f9]}
|
|
@item{@indexed-racket['f10]}
|
|
@item{@indexed-racket['f11]}
|
|
@item{@indexed-racket['f12]}
|
|
@item{@indexed-racket['f13]}
|
|
@item{@indexed-racket['f14]}
|
|
@item{@indexed-racket['f15]}
|
|
@item{@indexed-racket['f16]}
|
|
@item{@indexed-racket['f17]}
|
|
@item{@indexed-racket['f18]}
|
|
@item{@indexed-racket['f19]}
|
|
@item{@indexed-racket['f20]}
|
|
@item{@indexed-racket['f21]}
|
|
@item{@indexed-racket['f22]}
|
|
@item{@indexed-racket['f23]}
|
|
@item{@indexed-racket['f24]}
|
|
@item{@indexed-racket['numlock]}
|
|
@item{@indexed-racket['scroll]}
|
|
@item{@indexed-racket['wheel-up] --- @index["wheel on mouse"]{mouse} wheel up one notch}
|
|
@item{@indexed-racket['wheel-down] --- mouse wheel down one notch}
|
|
@item{@indexed-racket['wheel-left] --- mouse wheel left one notch}
|
|
@item{@indexed-racket['wheel-right] --- mouse wheel right one notch}
|
|
@item{@indexed-racket['release] --- indicates a key-release event}
|
|
@item{@indexed-racket['press] --- indicates a key-press event; usually only from @racket[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{@racket[#\space] --- the space bar}
|
|
|
|
@item{@racket[#\return] --- the Enter or Return key (on all
|
|
platforms), but not necessarily the Enter key near the numpad
|
|
(which is reported as @racket['numpad-enter] Unix and Mac OS X)}
|
|
|
|
@item{@racket[#\tab] --- the tab key}
|
|
|
|
@item{@racket[#\backspace] --- the backspace key}
|
|
|
|
@item{@racket[#\rubout] --- the delete key}
|
|
|
|
]
|
|
|
|
If a suitable special key symbol or ASCII representation is not
|
|
available, @racket[#\nul] (the NUL character) is reported.
|
|
|
|
A @racket['wheel-up], @racket['wheel-down], @racket['wheel-left], or
|
|
@racket['wheel-right] event may be sent to a window other than the
|
|
one with the keyboard focus, because some platforms generate wheel
|
|
events based on the location of the mouse pointer instead of the
|
|
keyboard focus.
|
|
|
|
On 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. On 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 @racket[special-control-key]. On
|
|
Unix, 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].
|
|
|
|
@history[#:changed "6.1.0.8" @elem{Changed reporting of numpad Enter
|
|
to @racket['numpad-enter] as
|
|
documented, instead of
|
|
@racket[#\u03].}]}
|
|
|
|
|
|
@defmethod[(get-key-release-code)
|
|
(or/c char? key-code-symbol?)]{
|
|
|
|
Gets the virtual key code for a key-release event; the result is
|
|
@racket['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 @racket[#t] if the Meta (Unix), Alt (Windows), or Command (Mac OS
|
|
X) key was down for the event.
|
|
|
|
}
|
|
|
|
@defmethod[(get-mod3-down)
|
|
boolean?]{
|
|
|
|
Returns @racket[#t] if the Mod3 (Unix) key was down for the event.
|
|
|
|
@history[#:added "1.1"]}
|
|
|
|
@defmethod[(get-mod4-down)
|
|
boolean?]{
|
|
|
|
Returns @racket[#t] if the Mod4 (Unix) key was down for the event.
|
|
|
|
@history[#:added "1.1"]}
|
|
|
|
@defmethod[(get-mod5-down)
|
|
boolean?]{
|
|
|
|
Returns @racket[#t] if the Mod5 (Unix) key was down for the event.
|
|
|
|
@history[#:added "1.1"]}
|
|
|
|
@defmethod[(get-other-altgr-key-code)
|
|
(or/c char? key-code-symbol? #f)]{
|
|
|
|
See @method[key-event% get-other-shift-key-code].
|
|
|
|
}
|
|
|
|
@defmethod[(get-other-caps-key-code)
|
|
(or/c char? key-code-symbol? #f)]{
|
|
|
|
See @method[key-event% get-other-shift-key-code].
|
|
|
|
}
|
|
|
|
@defmethod[(get-other-shift-altgr-key-code)
|
|
(or/c char? key-code-symbol? #f)]{
|
|
|
|
See @method[key-event% get-other-shift-key-code].
|
|
|
|
}
|
|
|
|
@defmethod[(get-other-shift-key-code)
|
|
(or/c char? key-code-symbol? #f)]{
|
|
|
|
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 @racket[#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) on Windows and Unix, or the Option key on 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. On Windows,
|
|
alternate mappings are reported when they produce ASCII letters,
|
|
ASCII digits, and ASCII symbols. On Mac OS X and Unix, alternate
|
|
mappings are usually available.
|
|
|
|
}
|
|
|
|
@defmethod[(get-shift-down)
|
|
boolean?]{
|
|
|
|
Returns @racket[#t] if the Shift key was down for the event.
|
|
|
|
}
|
|
|
|
@defmethod[(get-x)
|
|
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)
|
|
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.
|
|
|
|
On 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
|
|
@racket[#f].
|
|
|
|
}
|
|
|
|
@defmethod[(set-control+meta-is-altgr [down? any/c])
|
|
void?]{
|
|
|
|
Sets whether a Control plus Meta combination on Windows should be
|
|
treated as an AltGr combinations. See @method[key-event% get-control+meta-is-altgr].
|
|
|
|
@history[#:added "1.2"]}
|
|
|
|
|
|
@defmethod[(set-key-code [code (or/c char? key-code-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? key-code-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 (Unix), Alt (Windows), or Command (Mac OS X) key
|
|
was down for the event.
|
|
|
|
}
|
|
|
|
@defmethod[(set-mod3-down [down? any/c])
|
|
void?]{
|
|
|
|
Sets whether the Mod3 (Unix) key was down for the event.
|
|
|
|
@history[#:added "1.1"]}
|
|
|
|
@defmethod[(set-mod4-down [down? any/c])
|
|
void?]{
|
|
|
|
Sets whether the Mod4 (Unix) key was down for the event.
|
|
|
|
@history[#:added "1.1"]}
|
|
|
|
@defmethod[(set-mod5-down [down? any/c])
|
|
void?]{
|
|
|
|
Sets whether the Mod5 (Unix) key was down for the event.
|
|
|
|
@history[#:added "1.1"]}
|
|
|
|
@defmethod[(set-other-altgr-key-code [code (or/c char? key-code-symbol? #f)])
|
|
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? key-code-symbol? #f)])
|
|
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? key-code-symbol? #f)])
|
|
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? key-code-symbol? #f)])
|
|
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 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 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.
|
|
|
|
}
|
|
}
|
|
|