user manual

106 Chapter 5: Creating an iTool
Creating an iTool Launch Routine iTool Developer’s Guide
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.