ENVI::AddExtension

The ENVI::AddExtension method allows a Toolbox Extension to rename the entry in the Extensions folder, and optionally to place the Toolbox entry inside a user-defined folder structure witin the Toolbox or the ENVI menu.

If you want the Toolbox to display the renamed entry in the current session, issue the .RESET_SESSION command after calling the AddExtension method.

Note: This method should not be used inside of batch programs or while interacting with ENVI at the IDL command line. This method should only be included in an EXTENSIONS_INIT routine.

Example

The following example demonstrates a scenario when you would use the UVALUE keyword. You may want to use the same Toobox extension but with different results, depending on which item the user selects. This example adds two new Toolbox extensions: Brighten Data and Darken Data.

Here, you select a dataset and spatial or spectral subset (using ENVI's Select Input dialog). Depending on whether UVALUE is set to 'brighten' or 'darken', it adds or subtracts a DN value of 50 from each of the selected pixels.

Copy and paste the following code into a new file in IDL, and save the file as brightenordarkendata.pro.

PRO brightenordarkendata_extensions_init

  COMPILE_OPT IDL2

  ; Get the current application

  e = ENVI(/CURRENT)

  e.AddExtension, 'Brighten Data', 'brightenordarkendata', UVALUE='brighten'

  e.AddExtension, 'Darken Data', 'brightenordarkendata', UVALUE='darken'

END

PRO brightenordarkendata, event

  COMPILE_OPT IDL2

  CATCH, err

  IF err NE 0 THEN BEGIN

     CATCH, /CANCEL

     void = DIALOG_MESSAGE('Could not perform operation. An error occurred:' + $

     !ERROR_STATE.msg, /ERROR)

     MESSAGE, /RESET

     RETURN

  ENDIF

  e = ENVI(/CURRENT)

  WIDGET_CONTROL, event.ID, GET_UVALUE = uvalue

  ; Select a raster.

  raster = e.UI.SelectInputData(TITLE = 'Select a file to '+uvalue+'.', $

  /RASTER, BANDS = bands, SUB_RECT = subrect, /DISABLE_NO_DATA)

  ; Get the data and subrect.

  data = raster.GetData()

  ; Select a new raster to save.

  newfile = DIALOG_PICKFILE(/WRITE)

  ; Now brighten or darken the data.

  IF uvalue EQ 'brighten' THEN addvalue = 50 ELSE addvalue = -50

  CASE raster.INTERLEAVE of

     'bsq': data[subrect[0]:subrect[2], subrect[1]:subrect[3], bands] += addvalue

     'bil': data[subrect[0]:subrect[2], bands, subrect[1]:subrect[3]] += addvalue

     'bip': data[bands, subrect[0]:subrect[2], subrect[1]:subrect[3]] += addvalue

  ENDCASE

  ; Create the new raster.

  newraster = ENVIRaster(data, URI=newFile)

  ; Save and display the new raster.

  newraster.save

  view = e.GetView()

  layer = view.CreateLayer(newraster)

END

Issue the following commands to generate a SAVE file. If brightenordarkendata.pro is not in the current directory of the IDL path, provide the full path in the .COMPILE command. The SAVE file will be saved to the current directory unless you specify a full path in which to save.

  .RESET_SESSION

  .COMPILE brightenordarkendata.pro

  RESOLVE_ALL, /CONTINUE_ON_ERROR, SKIP_ROUTINES='ENVI'

   SAVE, FILENAME = 'brightenordarkendata.sav', /ROUTINES

Close IDL.
Move the file brightenordarkendata.pro.sav into install_dir\ENVIxx\extensions. If you do not have write permission to that directory, you can define an ENVI_EXTENSIONS environment variable that points to the directory that contains the SAVE file.
Launch ENVI from the Start menu.
In the Toolbox Extensions folder, notice that the extensions Brighten Data and Darken Data are now listed. Double-click Brighten Data.
When prompted for the input file, select install_dir\ENVIxx\data\qb_boulder_msi.
When prompted for the output file, enter a valid filename and path.
When the script finishes executing, the new file displays.

To place these extensions in the ENVI menu (under Display > Contrast) instead of the Toolbox, modify the AddExtension method calls as follows:

e.AddExtension, 'Brighten Data', 'brightenordarkendata', $
   UVALUE='brighten', /MENU, PATH='Display/Contrast'

e.AddExtension, 'Darken Data', 'brightenordarkendata', $
   UVALUE='darken', /MENU, PATH='Display/Contrast'

Then follow Steps 2 through 5 above to update the extension and to re-start ENVI.

Syntax

ENVI.AddExtension, Name, Routine [, Keywords=value]

Arguments

Name

A scalar string denoting the name that will appear in the Toolbox.

Routine

A scalar string denoting the IDL procedure that will be run when the Toolbox item is double-clicked.

Keywords

Keywords are applied only during the initial creation of the object.

AFTER

Use this keyword in combination with the MENU keyword to indicate the menu position that the new item should follow. This only applies to the final position in the menu hierarchy. For example, suppose that you have an extension named Routine 2 that should follow Routine 1. Set the AFTER keyword as follows:

e.AddExtension, 'Routine 1', 'myroutine1.pro', /MENU, $

   PATH='Display/MyTools'

e.AddExtension, 'Routine 2', 'myroutine2.pro', /MENU, $

   PATH='Display/MyTools', AFTER='Routine 1'

You cannot use this keyword in combination with the BEFORE keyword. Set this keyword to one of the following values:

Integer: If you set this keyword to an integer (beginning with 0 for the first menu item), the new item will appear after the item in that position.
String: The new item will appear after the item that you specify. Strings are not case-sensitive.

BEFORE

Use this keyword in combination with the MENU keyword to indicate the menu position that the new item should precede. This only applies to the final position in the menu hierarchy. You cannot use this keyword in combination with the AFTER keyword. Set this keyword to one of the following values:

Integer: If you set this keyword to an integer (beginning with 0 for the first menu item), the new item will appear before the item in that position.
String: The new item will appear before the item that you specify. Strings are not case-sensitive.

ERROR

Set this keyword to a named variable that will contain any error message issued during execution of this routine. If no error occurs, the ERROR variable will be set to a null string (''). If an error occurs and the routine is a function, then the function result will be undefined.

When this keyword is not set and an error occurs, ENVI returns to the caller and execution halts. In this case, the error message is contained within !ERROR_STATE and can be caught using IDL's CATCH routine. See IDL Help for more information on !ERROR_STATE and CATCH.

See Manage Errors for more information on error handling in ENVI programming.

PATH

A scalar string denoting the tree structure, under the Extensions folder, in which the Toolbox item will appear. If PATH is not specified, the item is added directly to the end of the Extensions folder. Multiple subfolders may be specified by adding the forward slash character between folder names (for example, My Routines/Statistics). If a folder does not currently exist, it will be created automatically.

When used in conjunction with the MENU keyword, the path denotes an optional sub-menu under which the menu button will be added. You can add multiple sub-menus by using the forward slash character (/) between their names.

SEPARATOR

Set this keyword (in conjunction with the MENU keyword) to place a separator line above the new item in the menu. A separator line cannot appear above the first item in a menu.

TOOLTIP

A scalar string denoting a description for this entry that will be displayed when the user hovers over the Toolbox item. This keyword will be ignored if the extension is added to the ENVI menu.

UVALUE

Set this keyword to a value containing information you want to maintain about the new Toolbox item. This value is passed through the extension's widget event, which can be passed in as the first argument to the toolbox extension's main procedure. You can retrieve the UVALUE from the event with the following command:

WIDGET_CONTROL, event.id, GET_UVALUE = uvalue

See Example for a typical scenario that uses UVALUE.

Version History

ENVI 5	Introduced
ENVI 5.0.2	Added AFTER, BEFORE, MENU, and SEPARATOR keywords
ENVI 5.7	Added TOOLTIP keyword

API Version

4.2