Creating Keyboard Event Functions
You can create custom functions to handle keyboard events in a graphics WINDOW or in a WIDGET_WINDOW. These functions must use the syntax described below.
Each function must return a value of 0 to turn off default event handling or 1 to perform default event handling.
Tip: Instead of creating a separate function for each event handler, you may find it convenient to use a custom event handling class along with the EVENT_HANDLER property. See Creating an Event Handler Class to Control Events for details on how to write this object class.
Syntax
Result = FUNCTION_NAME(Window, IsASCII, Character, KeyValue, X, Y, Press, Release, KeyMods)
Where FUNCTION_NAME is a unique name for the function, which will be called from one of the keyboard event handling keywords of WINDOW or WIDGET_WINDOW. Avoid using generic names such as "KeyboardHandler" to prevent name collisions with other applications using event handlers.
Arguments
Window
The object reference of the window in which a keyboard event happened.
IsASCII
A scalar byte value that indicates whether the keyboard event corresponds to an ASCII character. If IsASCII is non-zero, the Character argument will be set to a byte value corresponding to the character of the pressed key. If IsASCII is zero, the KeySymbol argument will be set to a numeric value indicating the key that was pressed.
Character
If IsASCII is non-zero, this argument is set to a byte value corresponding to the ASCII character of the key that was pressed. Otherwise, this argument is set to zero.
KeyValue
If IsASCII is zero, this argument is set to a value that indicates the key that was pressed. Otherwise, this argument is set to zero. Possible values are:
|
Value |
Key |
|---|---|
|
1 |
Shift |
|
2 |
Control |
|
3 |
Caps lock |
|
4 |
Alt |
|
5 |
Left |
|
6 |
Right |
|
7 |
Up |
|
8 |
Down |
|
9 |
Page up |
|
10 |
Page down |
|
11 |
Home |
|
12 |
End |
Note: On East Asian (Chinese, Japanese, Korean) localized Windows operating systems with an Asian language pack installed, characters entered in the Windows Input Method Manager (IMM)composition window are returned in the the KeyValue argument as unsigned integers representing a Wide character (Unicode value). The I18N_WIDECHARTOMULTIBYTE routine can convert these characters to multibyte strings. For more information, see Internationalizing Code.
X
The position to the right of the lower left corner of the drawable area, in device coordinates (pixels).
Y
The position above the lower left corner of the drawable area, in device coordinates (pixels).
Press
The value indicating that this event represents a key press. This argument is non-zero if the event is the result of pressing the key.
Release
The value indicating that this event represents a key release. This argument is non-zero if the event is the result of releasing the key.
KeyMods
The value containing a bitwise mask indicating which modifier keys are active at the time of the keyboard event. If a bit is zero, the key is up; if the bit is set, the key is pressed. The following table describes the bits in this bit mask. Possible values are:
|
Value |
Modifier Key |
|
1 |
Shift |
|
2 |
Control |
|
4 |
Caps lock |
|
8 |
Alt |
Example
In the following example code, the KeyboardEventsTestHandler function creates graphic element selections based on the keyboard character that is typed. Copy this code into a new IDL file and compile it. The example below this one is a test that you can run to see these selections work.
FUNCTION KeyboardEventsTestHandler, Window, $
IsASCII, Character, KeyValue, X, Y, Press, Release, KeyMods
print, 'KeyboardHandler'
help, Window, $
IsASCII, Character, KeyValue, X, Y, Press, Release, KeyMods
IF Release then return, 1
graphics = Window.uValue
graphics[0].select, /clear
FOREACH graphic, graphics do begin
CASE string(character) OF
't': if ISA(graphic, 'TEXT') then graphic.select, /ADD
'c': if ISA(graphic, 'ELLIPSE') then graphic.select, /ADD
'l': if ISA(graphic, 'POLYLINE') then graphic.select, /ADD
'p': if ISA(graphic, 'POLYGON') then graphic.select, /ADD
ELSE:
ENDCASE
ENDFOREACH
Window.refresh
RETURN, 0 ; Skip default event handling
END
Keyboard Character Selection Example
Run the following code example to test the event handling functions defined in the previous code example.
PRO KeyboardEventsTest
window = window()
text1=text(.2, .95, 'Type t to select text, c for circles, p for polygons, l for lines')
text2=text(.5, .8, 'Text 1')
text3=text(.5, .65, 'Text 2')
circle = ELLIPSE(500, 150, MAJOR=50, /device, $
FILL_COLOR="yellow")
x = indgen(200)+225
y = SIN(2.0*FINDGEN(200)*!PI/25.0)*EXP(-0.02*FINDGEN(200))*100 + 150
polygon = POLYGON(x, y, /device, $
/FILL_BACKGROUND, FILL_COLOR=!COLOR.LIGHT_STEEL_BLUE)
x = [100, 200, 200, 100, 100]
y = [100, 100, 200, 200, 100]
line = POLYLINE(x, y, /DEVICE)
window.uValue = [text1, text2, text3, circle, polygon, line]
window.KEYBOARD_HANDLER='KeyboardEventsTestHandler'
END