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

  • You can write separate functions for each type of mouse event, as described in the Syntax section.
  • Each 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 mouse event handler properties in ENVIView to the names of the event handler functions.
  • You can also write a general event handler class that contains all event-handling code, instead of creating separate functions for each event handler.


The syntax of the various event handler functions are similar:

Handler Type


Mouse Down

Result = FunctionName(View, X, Y, Button, KeyMods, Clicks)

Mouse Motion

Result = FunctionName(View, X, Y, KeyMods)

Mouse Up

Result = FunctionName(View, X, Y, Button)

Mouse Wheel

Result = FunctionName(View, X, Y, Delta, KeyMods)



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


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.


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


A value indicating how many button clicks occurred:

  • 1: Single click
  • 2: Double click


The following example prints different sets of coordinates to the IDL console when you click the mouse button on any location of a georeferenced image. Copy the following code and save it to a file named

PRO ExampleMouseDown
  ; Start the application
  e = ENVI()
  ; Select an input file and display it
  file = FILEPATH('qb_boulder_msi', ROOT_DIR=e.ROOT_DIR, $
    SUBDIR = ['data'])
  raster = e.OpenRaster(file)
  view = e.GetView()
  layer = view.CreateLayer(raster, BANDS = [2,1,0])
  ; Set the mouse event handler
  view.SetProperty, MOUSE_DOWN_HANDLER='ExampleMouseDownHandler'
FUNCTION ExampleMouseDownHandler, oView, $
  x, y, iButton, KeyMods, nClicks
  ; Convert from IDL window coordinates to view (file) coordinates
  oView.ConvertWindowToFile, x, y, xFile, yFile
  ; Use HitTest to determine the closest item to the location
  ; of the mouse event
  Result = oView.HitTest(xFile, yFile, DIMENSIONS=[10,10])
  PRINT, Result
  ; Get the spatial reference from the view
  SpatialRefView = oView.SpatialRef
  ; If the view does not contain a spatial reference, then return
  IF ~ISA(SpatialRefView) THEN BEGIN
  ; Retrieve different sets of coordinates from the image
  SpatialRefView.ConvertFileToMap, xFile, yFile, coordsMapX, coordsMapY
  PRINT, 'Map coordinates:', coordsMapX, coordsMapY, FORMAT='(A, 2X, f14.4, 2X, f14.4)'
  SpatialRefView.ConvertMapToFile, coordsMapX, coordsMapY, coordsFileX, coordsFileY
  PRINT, 'File coordinates:', coordsFileX, coordsFileY, FORMAT='(A, 2X, f14.4, 2X, f14.4)'
  SpatialRefView.ConvertMapToLonLat, coordsMapX, coordsMapY, coordsLon, coordsLat
  PRINT, 'Lat/Lon coordinates:', coordsLat, coordsLon, FORMAT='(A, 2X, f14.4, 2X, f14.4)'
  SpatialRefView.ConvertLonLatToMGRS, coordsLon, coordsLat, mgrsString
  PRINT, 'MGRS coordinates:', mgrsString, FORMAT='(A, 2X, A)'
  RETURN, 1 ; Perform default event handling