This topic describes how to write custom functions to handle keyboard events in an ENVIView. See the Example below for details.

  • Write a function using the following syntax:

    Result = FunctionName(View, IsASCII, Character, KeyValue, X, Y, Press, Release, KeyMods)

  • Avoid a generic function name such as "KeyboardEventHandler" to prevent name collisions with other applications using event handlers.
  • The function must return a value of 0 to turn off default event handling or 1 to perform event handling.
  • In the main program where you run ENVI and display an ENVIView, set the KEYBOARD_HANDLER property of ENVIView to the name of the event handler function.
  • You can also write a general event handler class that contains all event-handling code, instead of creating separate functions for each event handler.

Arguments

View

A reference to an ENVIView object in which the keyboard event occurred.

IsASCII

A byte value that indicates whether the keyboard event corresponds to an ASCII character. If it is a non-zero value, the Character argument is set to a byte value corresponding to the character of the ASCII pressed key. If it is 0, the KeyValue argument is set to a numeric value indicating the pressed key.

Character

If the IsASCII argument is a non-zero value, Character is set to a byte value corresponding to the ASCII character of the pressed key. Otherwise, it is set to 0.

KeyValue

If the IsASCII argument is set to 0, KeyValue is set to a value that indicates the pressed key. Otherwise, it is set to 0. The possible values are:

  • 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 KeyValue argument as unsigned integers representing a Wide character (Unicode value). The IDL I18N_WIDECHARTOMULTIBYTE routine can convert these characters to multi-byte strings. For more information, see "Internationalizing Code" in the IDL Help.

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

A value indicating that this event represents a key press. This argument is non-zero if the event is a result of pressing the key.

Release

A value indicating that this event represents a key release. This argument is non-zero if the event is a result of releasing the key.

KeyMods

A bitwise mask value indicating which modifier keys are active at the time the mouse event happens:

  • 1: Shift
  • 2: Control
  • 4: Caps Lock
  • 8: Alt

Example

The following example opens and displays two different color combinations of the same raster, each in a separate view. Click inside any view, then press the lower-case z key to zoom in, press the upper-case Z key to zoom out, or press the lower-case p key to display a Portal inside of the view.

Copy and paste the following code into a new file named ExampleAPIEventsKeyboard.pro, compile it, then run it.

FUNCTION ExampleAPIEventsKeyboardHandler, View, $
  IsASCII, Character, KeyValue, X, Y, Press, Release, KeyMods
 
  IF IsASCII && Press THEN BEGIN
    CASE STRING(Character) OF
      'p': portal = view.CreatePortal()
      'z': view.Zoom
      'Z': view.Zoom, /OUT
      ELSE:
    ENDCASE
  ENDIF
  RETURN, 1 ; Perform default event handling
END
 
PRO ExampleAPIEventsKeyboard
; Launch the application
e = ENVI()
 
; Open a raster
file = FILEPATH('qb_boulder_msi', ROOT_DIR=e.ROOT_DIR, $
  SUBDIRECTORY = ['data'])
raster = e.OpenRaster(file)
 
; Create two layers
view1 = e.GetView()
v1layer1 = view1.CreateLayer(raster)
v1layer2 = view1.CreateLayer(raster, /CIR)
view1.SHOW_OVERVIEW = 1
view1.SHOW_SNAIL_TRAIL = 1
 
; Create two layers in another view in opposite order
view2 = e.CreateView()
v2layer1 = view2.CreateLayer(raster, /CIR)
v2layer2 = view2.CreateLayer(raster)
view2.SHOW_OVERVIEW = 1
view2.SHOW_SNAIL_TRAIL = 1
view1.SetProperty, KEYBOARD_HANDLER='ExampleAPIEventsKeyboardHandler'
view2.SetProperty, KEYBOARD_HANDLER='ExampleAPIEventsKeyboardHandler'
END