Class Documentation
Keypress |
1.0 |
ID_KEYPRESS |
Stable |
I/O |
February 2003 |
Rocklyte Systems |
Rocklyte Systems (c) 2000-2003. All rights reserved. |
Provides management for specific keys on the keyboard. |
Description
The Keypress class is commonly used to respond to key-presses in the user
interface. Special key codes such as the function keys, key combinations
like CTRL-Z, and miscellaneous keys such as PrintScreen can all be detected
by this class. By default, key-presses are responded to when certain objects
(such as a window area) have the focus. However, you can also support
key-presses globally, which is appropriate for keys such as PrintScreen.
The following example illustrates the use of a Keypress object that
is used to take screenshots whenever the PrintScreen button is pressed:
<keypress key="prtscr" flags="global">
<script static src="graphics:screenshot.dml"/>
</keypress>
For a list of supported key-presses, refer to the documentation on the
Key field. Key qualifiers such as shift, control and alt
are also supported under the Qualifier field.
Actions
The Keypress class supports the following actions:
DataChannel | This action can be used to send fake keyboard input to a Keypress object. |
Structure
The Keypress object consists of the following public fields:
Flags | Optional flags. |
Focus | Determines the local object that will be monitored for key presses. |
Key | The key that is to be monitored. |
KeyboardID | Must refer to a Keyboard object in order to receive key presses. |
Qualifier | Set this field to analyse key qualifiers such as shift and control. |
DataChannel |
This action can be used to send fake keyboard input to a Keypress object. |
Fake keypresses can be sent to a Keypress object with the DATA_KEYPRESS
data type, as if the user was typing at the keyboard personally. The
keypresses will be interpreted no differently to 'real' user keypresses.
It is extremely important that the key qualifiers are set correctly and
that each key press is matched with a key release. If the data is not
defined correctly, it may be misinterpreted.
|
|
Field: | Flags |
Short: | Optional flags. |
Type: | LONG |
Prefix: | KF |
Status: | Read/Write |
Special flags affecting the functionality of keypress objects are listed
in the following table:
GLOBAL | If the global flag is set then the keypress object will monitor its associated key on a constant basis, rather than monitoring it at times when it has the focus. |
REPEAT | Set the repeat flag if you would like the keypress object to respond to repeat keypresses (which occur when the user holds down a key for an extended period of time). |
|
|
Field: | Focus |
Short: | Determines the local object that will be monitored for key presses. |
Type: | OBJECTID |
Status: | Read/Init |
To specify the object that you want to monitor for key presses, set this
field. The Keypress object will watch the target object for key presses.
Incoming key presses will be compared to the Key and Qualifier fields to
check for a match. Key presses are only translated when the target object
has the focus - at all other times, key presses are ignored.
You do not need to set the Focus field if you are checking for global
key presses, or if you want to monitor the drawable container of a Keypress
object.
|
|
Field: | Key |
Short: | The key that is to be monitored. |
Type: | STRING |
Status: | Read/Write |
This field must refer to the key that the Keypress object will monitor and
respond to. If you want to refer to a printable character such as that
represented by an alpha or numeric key, simply specify that character, e.g.
'a', '1', '='. If you want to refer to a special key type such as a function
key, you need to choose the correct key from the following table:
Function Keys
f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 f11 f12 f13 f14 f15 f16 f17 f18 f19 f20
|
Cursor Keys
down left right up
Control Keys
lalt ralt lcommand rcommand lctrl rctrl lshift rshift
|
Orientation Keys
end home pagedown pageup
Text Keys
backspace capslock delete enter escape insert tab
|
Special Keys
break cancel clear execute find help menu numlock pause power prtscr redo scroll select sleep undo wake
|
You can also set key qualifiers to handle combinations such as CTRL-C and
SHIFT-ENTER. Refer to the Qualifier field for
details.
|
|
Field: | KeyboardID |
Short: | Must refer to a Keyboard object in order to receive key presses. |
Type: | OBJECTID |
Status: | Read/Write |
By default a new Keypress object will read its input from the default
Keyboard object 'SystemKeyboard', which normally represents the keyboard
hooked into the PC. If necessary you can set this field to explicitly
declare the Keyboard object that the keys should be read from. Refer to the
Keyboard class for details on setting up Keyboard
objects.
|
|
Field: | Qualifier |
Short: | Set this field to analyse key qualifiers such as shift and control. |
Type: | STRING |
Status: | Read/Write |
The Qualifier field can be set in conjunction with the Key field in order
to watch for key combinations. The following table illustrates the qualifier
keys that are supported:
Paired Keys
lalt ralt lctrl rctrl lcommand rcommand lshift rshift
|
General Key References
alt capslock command ctrl numpad shift
|
|
|