>  Docs Center  >  ENVI API  >  Event Handler Class

Event Handler Class

Event Handler Class

This topic describes how to create a custom event handler class to handle events in an ENVIView. You may find it more convenient to create a single class to hold all of your event handlers as opposed to writing separate functions for each type of event (mouse, keyboard, etc.) throughout your code. Just set the EVENT_HANDLER property of ENVIView to the name of the event handler class.


The event handler class can contain any combination of the following methods:

Result = ENVIView.MouseDown(View, X, Y, Button, KeyMods, Clicks)

Result = ENVIView.MouseMotion(View, X, Y, KeyMods)

Result = ENVIView.MouseUp(View, X, Y, Button)

Result = ENVIView.MouseWheel(View, X, Y, Delta, KeyMods)

Result = ENVIView.KeyHandler(View, IsASCII, Character, KeyValue, X, Y, Press, Release, KeyMods)

Result = ENVIView.SelectChange(View, Graphic, Mode, WasSelected)



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


The x-coordinate location of the mouse cursor (in device coordinates) at the time of the event.


The y-coordinate location of the mouse cursor (in device coordinates) at the time of the event.


The value of the clicked mouse button. Possible values are:

  • 1: Left
  • 2: Middle
  • 4: Right


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.


A value indicating how many button clicks occurred:

  • 1: Single click
  • 2: Double click


A value indicating the direction and number of movements of the mouse wheel. Pushing the wheel forward generates positive values, while pulling it backward generates negative values. The magnitude of the value depends on the device setting for the individual mouse, but it is usually limited to small integer values such as +1, -1, +2, -2, etc.


The graphic to be selected or un-selected.


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.


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


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.


A value representing the mode used for the current selection. Possible values are:

  • 0: Unselect
  • 1: Select
  • 2: Toggled selection
  • 3: Additive


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.


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.


A value of 1 indicates an item was selected prior to the event; a value of 0 indicates an item was not selected.


The following example shows how to create a custom event handler that contains the keyboard and selection change handler code examples in one program.

Copy and paste the following code to a file named ExampleAPIEventsClass.pro, compile it, then run it.

FUNCTION ExampleAPIEventsClass::KeyHandler, View, $
  IsASCII, Character, KeyValue, X, Y, Press, Release, KeyMods
    CASE STRING(Character) of
      'z': view.Zoom
      'Z': view.Zoom, /OUT
  RETURN, 0 ; Skip default event handling
FUNCTION ExampleAPIEventsClass::SelectChange, View, $
  graphic, mode, isSelected
  IF ISA(graphic) && ISA(graphic, 'ENVIRASTERLAYER') && ~isSelected THEN BEGIN
  RETURN, 1 ; Perform default event handling
PRO ExampleAPIEventsClass__define
  ; Subclass from GraphicsEventAdapter.
  void = {ExampleAPIEventsClass, INHERITS GraphicsEventAdapter, $
    X0: 0, Y0:0, BUTTONDOWN:0, POLY:OBJ_NEW()}
PRO ExampleAPIEventsClass
  ; Launch the application
  e = ENVI()
  ; Open an image file
  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
  ; This example uses the same event handler for both views, but
  ; you may have cases when you want to use different event handlers
  ; for different views.
  eventHandler = obj_new('ExampleAPIEventsClass')
  view1.SetProperty, EVENT_HANDLER=eventHandler
  view2.SetProperty, EVENT_HANDLER=eventHandler

© 2020 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us