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.

Syntax

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)

Arguments

View

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

X

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

Y

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

Button

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

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

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.

Clicks

A value indicating how many button clicks occurred:

  • 1: Single click
  • 2: Double click

Delta

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.

Graphic

The graphic to be selected or un-selected.

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.

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

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.

Mode

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

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

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.

WasSelected

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

Example

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
  IF IsASCII && Press THEN BEGIN
    CASE STRING(Character) of
      'z': view.Zoom
      'Z': view.Zoom, /OUT
      ELSE:
     ENDCASE
  ENDIF
  RETURN, 0 ; Skip default event handling
END
 
FUNCTION ExampleAPIEventsClass::SelectChange, View, $
  graphic, mode, isSelected
  IF ISA(graphic) && ISA(graphic, 'ENVIRASTERLAYER') && ~isSelected THEN BEGIN
    View.ClearSnailTrail
  ENDIF
  RETURN, 1 ; Perform default event handling
END
 
PRO ExampleAPIEventsClass__define
  ; Subclass from GraphicsEventAdapter.
  void = {ExampleAPIEventsClass, INHERITS GraphicsEventAdapter, $
    X0: 0, Y0:0, BUTTONDOWN:0, POLY:OBJ_NEW()}
END
 
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
END