Creating an iTool Launch Routine

An iTool launch routine is an IDL procedure that creates an instance of an iTool by calling the IDLITSYS_CREATETOOL function. The launch routine may do other things as well, including creating data objects to pass to the create function from command-line arguments.

The process of creating an iTool launch routine is outlined in the following sections:

Specifying Command-Line Arguments and Keywords

If you want to be able to specify data to be loaded into your iTool when launching the tool from the IDL command line, you must specify positional arguments or keywords in the procedure definition. The procedure definition for an iTool launch routine may look something like the following: 

PRO myTool, A1, A2, MYKEYWORD = myKeys, IDENTIFIER = id, $ 
   _EXTRA = _extra

Here, there are two positional parameters (or arguments) and three keyword parameters are specified.

Arguments

Data arguments are specified in an iTool launch routine as with any IDL procedure. See Parameters (Application Programming) for details on arguments.

Keywords

Keyword arguments to an iTool launch routine are handled as with any IDL procedure. See Parameters (Application Programming) for details on keyword arguments. In addition, you may want to include the following keyword arguments in the definition of the launch routine:

The IDENTIFIER Keyword

The IDENTIFIER keyword is used to return the iTool system identifier string for the newly created tool. You must set the variable specified by the IDENTIFIER keyword equal to the return value of the IDLITSYS_CREATETOOL function. This allows the user to retrieve the newly-created iTool's identifier in an IDL variable by including the IDENTIFIER keyword in the call to the launch routine. The iTool identifier can then be used to specify the iTool as the target for another operation, such as overplotting.

The _EXTRA Keyword

Optionally, you can use IDL's keyword inheritance mechanism to pass keyword parameters that are not explicitly handled by your routine through to other routines. See Keyword Inheritance (Application Programming) for details on IDL's keyword inheritance mechanism.

Creating Data Objects

If your iTool launch routine allows users to specify data arguments (as opposed to keywords that are passed through to the iTool component objects), you must process those arguments and create an IDLitParameterSet object to be passed to the IDLITSYS_CREATETOOL function. Parameter sets, data types, and general iTool system data handling concepts are discussed in detail in Data Management.

Parameter Sets

Data is passed to a newly-created iTool instance by supplying an IDLitParameterSet object as the value of the INITIAL_DATA keyword to the IDLITSYS_CREATETOOL function. To create a parameter set object, use the OBJ_NEW function: 

oParameterSet = OBJ_NEW('IDLitParameterSet', NAME = paramSetName)

where oParameterSet is a named variable that will hold the object reference to the parameter set object and paramSetName is a string that will be used by the iTool user interface to refer to the parameter set.

For example, if you are creating a data container to hold X and Y vectors to be plotted in two-dimensions, you might use the following code: 

oPlotData = OBJ_NEW('IDLitParameterSet', NAME = 'Plot data')

See Data Management, and "IDLitParameterSet" (IDL Reference Guide) for details.

Data Items

The parameter set object holds objects of type IDLitData, or objects of types derived from IDLitData, such as IDLitDataImage or IDLitDataVector. These data objects, in turn, hold the actual data used by the iTool. To create a data object, use the OBJ_NEW function: 

oData = OBJ_NEW('IDLitData', vData, TYPE = dataType, $ 
   NAME = dataName)

where oData is a named variable that will hold the object reference to the data object, vData is an IDL variable containing the actual data, dataType is a string specifying the iTool data type of the data held by the object, and dataName is a string that will be used by the iTool user interface to refer to the data object. See iTool Data Types for additional information on iTool data types.

For example, if you are creating a data object to hold the Y vector of a two-dimensional plot, you might use the following code: 

oPlotY = OBJ_NEW('IDLitData', yData, TYPE = 'IDLVECTOR', $ 
   NAME = 'Y data')

Here, the data that make up the Y vector are contained in the variable yData. After a data item has been created, it must be added to the parameter set object. Continuing our example, the following code adds the oPlotY data object to the oPlotData parameter set object, assigning the parameter name 'Y data': 

oPlotData->Add, oPlotY, PARAMETER_NAME='Y data'

See Data Management, and "IDLitData" (IDL Reference Guide) for details.

Example

For an example iTool launch routine that creates and populates a parameter set object, see Example: Simple iTool.

Handling Errors

The error-handling requirements of your iTool launch routine will depend largely on the type of data processing you perform. In general, your goal should be to clean up any objects or pointers your routine creates, display an error message to the user, and return to the calling routine. It is beyond the scope of this chapter to discuss IDL's error handling mechanisms in detail; for more information see Debugging and Error-Handling (Application Programming).

iTool launch routines included in the IDL distribution handle errors by placing a block of IDL code that looks like the following at the beginning of the routine: 

ON_ERROR, 2 
CATCH, iErr 
IF (iErr NE 0) THEN BEGIN 
   CATCH, /CANCEL 
   IF OBJ_VALID(oDataObject) THEN OBJ_DESTROY, oDataObject 
   MESSAGE, /REISSUE_LAST 
   RETURN 
ENDIF

This block of error-handling code does the following:

  1. Uses the ON_ERROR procedure to instruct IDL to return to the caller of the program that establishes an error condition.
  2. Uses the CATCH procedure to establish an error-handler for the iTool launch routine, returning the error code in the variable iErr.
  3. If the value of iErr is not 0 (that is, if an error is detected), do the following:
    • Use the CATCH procedure again to cancel the error handler.
    • Destroy any data objects created by the launch routine. In most cases, destroying the data container object (represented here by oDataObject) will be sufficient to destroy all objects added to the data container.
    • Use the MESSAGE routine to display the error message in the IDL output log.

      • Once these tasks have been accomplished, use the RETURN procedure to return to the routine that called the iTool launch routine, or to the IDL Main level, if the launch routine was invoked at the IDL command prompt.

Depending on the complexity of your iTool launch routine, additional cleanup may be required. For example, you may need to free IDL pointers created by the launch routine. In many cases, however, error-handling code similar to that used in the standard iTool launch routines will be sufficiently robust.

Creating an iTool Instance

Create an instance of your iTool class by calling the IDLITSYS_CREATETOOL function: 

id = IDLITSYS_CREATETOOL('Tool Name', NAME = 'Tool Label', $ 
        VISUALIZATION_TYPE = 'VisType', $ 
        INITIAL_DATA = 'oDataContainer', _EXTRA = _extra)

where Tool Name is the name of a previously-registered iTool class, Tool Label is a text label that will be used in the iTool user interface to identify this instance of the iTool, VisType is the name of a previously-registered iTool visualization type (or array of visualization types), and oDataContainer is an IDLitDataContainer object created from the values specified as arguments or keywords.

We also use IDL's keyword inheritance mechanism (the _EXTRA keyword) to pass any additional keyword parameters specified when the launch routine is called through to the lower-level iTool routines.

See "IDLITSYS_CREATETOOL" (IDL Reference Guide) for details.

iTool Class Registration

Before an instance of an iTool can be created, the iTool class must be registered with the iTool system. An iTool class can be registered with the system within the launch routine by calling the IREGISTER routine, but you may benefit from registering iTool classes separately. See Registering a New Tool Class for details.

iTool Visualization Type Registration

Similarly, the visualization type or types specified by the VISUALIZATION_TYPE keyword must have been registered with the system. In most cases, visualizations will either be predefined iTool visualizations (see Predefined iTool Visualization Classes) or will be registered in the iTool class' Init method, as described in Creating a New iTool Class. All iTools must have at least one visualization type. Multiple visualization types are specified by supplying a string array as the value of the VISUALIZATION_TYPE property.

Note
Once a visualization type has been registered with the iTool system, it is available to all iTools launched during an IDL session. This means that the list of visualization types available to a given iTool can change if other iTools are launched.