| Allegro CL version 8.2 Moderately revised from 8.1. 8.1 version |
Arguments: window buttons key-code
This generic function is called when the user presses a keyboard key down. An application may add methods to this generic function to respond to keyboard events in its windows.
window is the window that had the keyboard focus when the event occurred. The keyboard focus is usually indicated by some sort of highlighting.
buttons works as in mouse-left-down, that is it is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
left-mouse-button
middle-mouse-button
right-mouse-button
first-x-button
(see *ignore-mouse-x-buttons*
)
second-x-button
(see *ignore-mouse-x-buttons*
),
shift-key
control-key
alt-key
In addition, if the key that was pressed was one of several "extended
keys" then the extended-key
bit will be set. This
is probably useful only when key-code is the
value of vk-control
or vk-alt
and an
application needs to know whether the righthand or lefthand version of
this key was pressed. For these keys, the extended-key
bit will be set
for the righthand version only.
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest right-mouse-button buttons)
will return true if and only if the right mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
key-code is an integer representing the key that
was pressed. For a letter key, the key code is the char-int of the uppercase character
shown on the key (and NOT the corresponding lowercase character). For
a numeral key, it is the char-int of the numeral character. For
any other key, the key code is the value of the vk-
constant for that key (see key-names
for a list of
vk-
constants); for keys that show both a shifted
character and an unshifted character, this constant will be named
after the unshifted character.
A note about virtual-key-down and character-message:
While a keypress will always cause virtual-key-down and virtual-key-up to be called, it will cause character-message to be called only under certain conditions. First, the keypress must indicate a graphical character. second, one of the following must be true:
dialog-mixin
instance or a child or
other descendant of a dialog-mixin
instance; or
Therefore, if an application adds a virtual-key-down method for a window that is not on a dialog, and this method does not call (call-next-method) for a particular keypress, then the default virtual-key-down method is not called, and therefore character-message will not be called for that keypress.
See cg-events.htm for information about event handling in Common Graphics.
A note about the Enter key: starting in 8.2, a virtual-key-down method will receive more consistent argument values when the Enter key on the main keypad is pressed while holding down the alt key. The change is described in here in release-notes.htm.
The following is an example from cg-events.htm repeated here:
Here's an example that handles the virtual-key-down event, since its
arguments are a little tricky. This code will create a window that
will change its size when the user types control-L, control-semicolon,
control-shift-L, or control-shift-semicolon. The buttons argument is
some subset of the values of the constants control-key, shift-key, and
alt-key logior'ed together (each one is a bit flag). The data
argument is an integer for the key that was pressed, expressed either
as the char-int of the character that is printed on the key or as the
value of one of the "vk-..." constants that are the value of the
constant key-names
.
(in-package :cg-user) (defclass my-window (frame-window)()) (defmethod virtual-key-down ((window my-window) buttons data) (case buttons (#.control-key (case data (#.vk-semicolon (incf (width window) 50)) (#.(char-int #\L) (decf (width window) 50)) (t (call-next-method)))) (#.(logior control-key shift-key) (case data (#.vk-semicolon (incf (height window) 50)) (#.(char-int #\L) (decf (height window) 50)) (t (call-next-method)))) (t (call-next-method)))) (make-window 'herbert :device 'my-window :parent (screen *system*))
Note that if the example window above were created on
(main-development-window *system*
) instead of on the screen,
then the virtual-key-down method would not get called for the defined
keystrokes, because the keystrokes would be overridden by IDE menubar
shortcuts. In general, a menubar shortcut will override a virtual-key-down method,
and a custom virtual-key-down method will override a comtab binding
(since comtab events are implemented as a virtual-key-down method on
the general comtab-mixin class).
Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had moderate revisions compared to the 8.1 page.
Created 2016.6.21.
| Allegro CL version 8.2 Moderately revised from 8.1. 8.1 version |