# 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