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.

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:

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:

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:

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:

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:

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