Example: Simple iTool

This example creates a very simple iTool named example1tool that incorporates standard functionality from the iTools distribution.

Class Definition File

The class definition for the example1tool consists of an Init method and a class structure definition routine. As with all object class definition files, the class structure definition routine is the last routine in the file, and the file is given the same name as the class definition routine (with the suffix .pro appended).

Init Method

FUNCTION example1tool::Init, _REF_EXTRA = _EXTRA 
 
   ; Call our super class 
   IF ( self -> IDLitToolbase::Init(_EXTRA = _extra) EQ 0) THEN $ 
      RETURN, 0 
 
   ;*** Visualizations 
   self -> RegisterVisualization, 'Image', 'IDLitVisImage', $ 
      ICON = 'image', /DEFAULT 
 
   self -> RegisterVisualization, 'Colorbar', 'IDLitVisColorbar', $ 
      ICON = 'colorbar' 
 
   ;*** Insert menu 
   self -> RegisterOperation, 'Colorbar', 'IDLitOpInsertColorbar', $ 
      IDENTIFIER = 'Insert/Colorbar', ICON = 'colorbar' 
 
   RETURN, 1 
 
END 

Discussion

The first item in our class definition file is the Init method. The Init method's function signature is defined first, using the class name example1tool. Note the use of the _REF_EXTRA keyword inheritance mechanism; this allows any keywords specified in a call to the Init method to be passed through to routines that are called within the Init method even if we do not know the names of those keywords in advance.

Next, we call the Init method of the superclass. In this case, we are creating a subclass of the IDLitToolbase class; this provides us with all of the standard iTool functionality automatically. Any "extra" keywords specified in the call to our Init method are passed to the IDLitToolbase::Init method via the keyword inheritance mechanism.

We register two standard iTool visualization types: Image and Colorbar. Both of these types are part of the regular iTool distribution, so we simply register the existing classes.

We also register a standard iTool operation: Insert Colorbar. Our call to the RegisterOperation method specifies the IDENTIFIER property as 'Insert/Colorbar', which places a Colorbar entry on the Insert menu of the iTool.

Finally, we return the value 1 to indicate successful initialization.

Class Definition

PRO example1tool__Define 
 
struct = { example1tool,              $ 
           INHERITS IDLitToolbase     $ ; Provides iTool interface 
         } 
 
END 

Discussion

Our class definition routine is very simple. We create an IDL structure variable with the name example1tool, specifying that the structure inherits from the IDLitToolbase class.

Launch Routine

Our iTool launch routine also uses the class name example1tool. It accepts a single data argument, which we assume will contain an image array. The code is shown below:

PRO example1tool, data, IDENTIFIER = IDENTIFIER, _EXTRA = _EXTRA 
 
nParams = N_PARAMS() 
 
IF (nParams gt 0) THEN BEGIN 
   oParmSet = OBJ_NEW('IDLitParameterSet', $ 
      NAME = 'example 1 parameters', $ 
      ICON = 'image', $ 
      DESCRIPTION = 'Example tool parameters') 
 
   IF (N_ELEMENTS(data) GT 0) THEN BEGIN 
      oData = OBJ_NEW("IDLitDataIDLImagePixels") 
      result = oData -> SetData(data, _EXTRA = _EXTRA) 
      oParmSet -> Add, oData, PARAMETER_NAME = "ImagePixels" 
 
      ; Create a default grayscale ramp. 
      ramp = BINDGEN(256) 
      oPalette = OBJ_NEW('IDLitDataIDLPalette', $ 
         TRANSPOSE([[ramp], [ramp], [ramp]]), $ 
         NAME = 'Palette') 
      oParmSet -> Add, oPalette, PARAMETER_NAME = 'PALETTE' 
 
   ENDIF 
 
ENDIF 
 
   ITREGISTER, "Example 1 Tool", "example1tool" 
 
   identifier = IDLITSYS_CREATETOOL("Example 1 Tool",$ 
      VISUALIZATION_TYPE = ["Image"], $ 
      INITIAL_DATA = oParmSet, _EXTRA = _EXTRA, $ 
      TITLE = "First Example iTool") 
END 

Discussion

Our iTool launch routine accepts a single data argument. We also specify that our launch routine should accept the IDENTIFIER keyword; we will use the variable specified as the value of this keyword (if any) to return the iTool identifier of the new iTool we create.

First, we check the number of non-keyword arguments that were supplied using the N_PARAMS function. If an argument was supplied, we create an IDLitParameterSet object to hold the data.

Next, we check to make sure the supplied data argument is not empty using the N_ELEMENTS function. If the supplied argument contains data, we create an IDLitDataImage object to contain the image data and add the object to our parameter set object, assigning the parameter name 'Image'.

We use the ITREGISTER procedure to register our iTool class with the name "Example 1 Tool".

Finally, we call the IDLITSYS_CREATETOOL function with the registered name of our iTool class.