Class Documentation

Name:Keypress
Version:1.0
ID:ID_KEYPRESS
Status:Stable
Category:I/O
Date:February 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2003. All rights reserved.
Short:  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.
Action:DataChannel
Short: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:

FlagDescription
GLOBALIf 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.
REPEATSet 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, which when received, 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