# Catalyst Source-Core Directory On-Line Help

This page was created by the IDL library routine `mk_html_help`. For more information on this routine, refer to the IDL Online Help Navigator or type:

         ? mk_html_help

at the IDL command line prompt.

Last modified: Sun Oct 26 20:43:11 2008.

# List of Routines

- CATATOM
- CATATOM::ADDTOTRASH
- CATATOM::CLEANUP
- CATATOM::CONTROLPANEL
- CATATOM::COPY
- CATATOM::DOCUMENT
- CATATOM::DRAW
- CATATOM::ERROR
- CATATOM::EVENTHANDLER
- CATATOM::GETPROPERTY
- CATATOM::GETSTATE
- CATATOM::HELP
- CATATOM::INIT
- CATATOM::MESSAGEHANDLER
- CATATOM::PRINT
- CATATOM::REGISTERFORMESSAGE
- CATATOM::REPORT
- CATATOM::SELECT
- CATATOM::SENDMESSAGE
- CATATOM::SETPROPERTY
- CATATOM::SETSTATE
- CATATOM::WHOMESSAGERECIPIENTS
- CATCONTAINER
- CATCONTAINER::ADD
- CATCONTAINER::ADDPARENT
- CATCONTAINER::CLEANUP
- CATCONTAINER::FINDBYNAME
- CATCONTAINER::GET
- CATCONTAINER::GETNAME
- CATCONTAINER::GETPROPERTY
- CATCONTAINER::GETPROPERTY (FUNCTION)
- CATCONTAINER::INIT
- CATCONTAINER::PRINT
- CATCONTAINER::REMOVE
- CATCONTAINER::REMOVEPARENT
- CATCONTAINER::SETPROPERTY
- CATCONTAINER::SHOWCONTENTS
- CATCONTROLPANEL
- CATCONTROLPANEL::CLEANUP
- CATCONTROLPANEL::CREATED_OWN_TLB
- CATCONTROLPANEL::DRAW
- CATCONTROLPANEL::EVENTHANDLER
- CATCONTROLPANEL::INIT
- CATCONTROLPANEL::REFRESH_PROPERTIES
- CATCONTROLPANEL::SHOW
- CATIPTOOL
- CATIPTOOL::APPLY
- CATIPTOOL::CLEANUP
- CATIPTOOL::GETPROPERTY
- CATIPTOOL::INIT
- CATIPTOOL::LOADCOMMAND
- CATIPTOOL::REDO
- CATIPTOOL::SETPROPERTY
- CATIPTOOL::UNDO
- CATLAYER::APPLYCOLORS
- CATLAYER::APPLYCOORDS
- CATLAYER::CLEANUP
- CATLAYER::CONTROLPANEL
- CATLAYER::DRAW
- CATLAYER::EVENT_HANDLER
- CATLAYER::GETPROPERTY
- CATLAYER::INIT
- CATLAYER::SELECT
- CATLAYER::SETPROPERTY
- CATLAYER__DEFINE
- CATLIST
- CATLIST::ADD
- CATLIST::ADDVALUE
- CATLIST::CLEANUP
- CATLIST::GETVALUE
- CATLIST::INIT
- CATLISTVALUE
- CATLISTVALUE STRUCTURE DEFINITION
- CATLISTVALUE::ADD
- CATLISTVALUE::CLEANUP
- CATLISTVALUE::GETVALUE
- CATLISTVALUE::INIT
- CATLISTVALUE::SETVALUE
- CATTOOL
- CATTOOL::CACHE
- CATTOOL::CLEANUP
- CATTOOL::GETPROPERTY
- CATTOOL::INIT
- CATTOOL::SETPROPERTY
- CATTOOLLIST
- CATTOOLLIST::ADD
- CATTOOLLIST::CLEANUP
- CATTOOLLIST::GET
- CATTOOLLIST::GETPROPERTY
- CATTOOLLIST::INIT
- CATTOOLLIST::REDO
- CATTOOLLIST::REMOVE
- CATTOOLLIST::SETPROPERTY
- CATTOOLLIST::UNDO
- COLORTOOL
- COLORTOOL::ADDNAMEDCOLOR
- COLORTOOL::CLEANUP
- COLORTOOL::COLOR24TO8
- COLORTOOL::COLOR8TO24
- COLORTOOL::CONGRID
- COLORTOOL::DRAW
- COLORTOOL::EVENTHANDLER
- COLORTOOL::GETCOLOR
- COLORTOOL::GETPROPERTY
- COLORTOOL::GUI_UPDATE
- COLORTOOL::INIT
- COLORTOOL::LOADCOLOR
- COLORTOOL::LOADCT
- COLORTOOL::PICKCOLORNAME
- COLORTOOL::RESET
- COLORTOOL::REVERSE
- COLORTOOL::SELECTCOLOR
- COLORTOOL::SETPROPERTY
- COLORTOOL::SHOWCOLORS
- COLORTOOL::STRETCH
- COLORTOOL::XCOLORS
- COLORTOOL::XCOLORS_UPDATE

# Routine Descriptions

## CATATOM

[Next Routine] [List of Routines]

     NAME:
           CATATOM

     PURPOSE:

           This is second most basic object in the CATALYST Object Library. It is a subclassed
           CATCONTAINER object and implements an IDL object hierarchy. All objects in
           the CATALYST Object Library are subclassed from the CATATOM object. Object
           error handling, object reporting and documentation, object messaging, and
           widget event handling are all set up in this object, allowing all objects
           in the CATALYST Object Library to partake in this functionality.

     AUTHORS:

            FANNING SOFTWARE CONSULTING   BURRIDGE COMPUTING
            1645 Sheely Drive             18 The Green South
            Fort Collins                  Warborough, Oxon
            CO 80526 USA                  OX10 7DN, ENGLAND
            Phone: 970-221-0438           Phone: +44 (0)1865 858279
            E-mail: davidf@dfanning.com   E-mail: davidb@burridgecomputing.co.uk

     SUPERCLASSES:

           CATCONTAINER, IDLITCOMPONENT
           IDL_CONTAINER

     SYNTAX:

           atomObject = Obj_New('CATATOM')

     CLASS_STRUCTURE:

       class =  { CATATOM,                          $ ; The CATATOM object class name.
                  _controlPanel       : OBJ_NEW (), $ ; The control panel for the object.
                  _errorLevel         : 0B,         $ ; The error reporting level.
                  _event_method       : "",         $ ; The name of the event method associated with this object.
                  _event_objects      : OBJ_NEW (), $ ; The object(s) to whom events for this object are passed.
                  _excl_event_object  : OBJ_NEW (), $ ; An exclusive event object.
                  _messageRecipients  : OBJ_NEW (), $ ; A list of objects to be notified of method calls.
                  _reportLevel        : 0B,         $ ; The info reporting level.
                  _trash              : OBJ_NEW(),  $ ; A trash container for destroying other objects.
                  _uvalue             : PTR_NEW (), $ ; A user value placeholder for the object.
                  INHERITS CatContainer,            $ ; All objects in the Catalyst Library are containers
                  INHERITS IDLitComponent           $ ; Inherits the IDLitComponnet class for object properties.
                }

     MODIFICATION_HISTORY:

           Written by: David Burridge, 13 March 2003.
           Made sure there are no duplicated registrations in RegisterForMessage. DWF. 15 May 2004.
           Made a change in the way EVENT_METHOD is assigned. If not passed in, will try to get EVENT_METHOD
             from the parent first, before assigning EventHandler as method. 9 August 2004. DWF.
           Removed TOP_OBJECT reference. It was not being used and got in the way of saving/restoring
             object. 22 January 2005. DWF.
           Added TRASH container and ADDTOTRASH method. 27 July 2005. DWF.

(See C:\IDL\Catalyst\source\core\catatom__define.pro)

## CATATOM::ADDTOTRASH

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATATOM::ADDTOTRASH

     PURPOSE:

            This procedure adds a specified object to the trash container. The purpose
            is to have a place to store objects that need to be cleaned up when another
            object is destroyed. Every object in the Catalyst system has a trash container.

     SYNTAX:

           object -> AddToTrash, anotherObject

     ARGUMENTS:

            anotherObject: The object, or array of objects, to be added to the trash container.

     KEYWORDS:

            None.

(See C:\IDL\Catalyst\source\core\catatom__define.pro)

## CATATOM::CLEANUP

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATATOM::CLEANUP

     PURPOSE:

           This is the CATATOM object class destructor method.

     SYNTAX:

           Called automatically when the object is destroyed.

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

     MODIFICATIONS:

           I have commented out the code that destroys the control panel, if it exits. While
           programs work fine with this code in the IDLDE, the code causes errors on program
           exit in run-time programs. I believe this is because of the order in which objects
           are destroyed. In any case, control panels always destroy themselves in my experience
           and commenting this code out here has not resulted in any memory leakage in any of
           the programs I have tested. DWF. 10 Sept 2003.

(See C:\IDL\Catalyst\source\core\catatom__define.pro)

## CATATOM::CONTROLPANEL

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatAtom::CONTROLPANEL

     PURPOSE:

           This method creates a control panel for the object. A control
           panel is a graphical user interface for setting object
           properties.

     SYNTAX:

           theObject -> ControlPanel, baseObject

     ARGUMENTS:

           baseObject:    The object reference of a base widget for this control to
                          be added to. If not supplied, the control panel will be in a
                          self contained window (i.e., a TOPLEVELBASE object).

     KEYWORDS:

           _EXTRA:       Any keywords appropriate for the CatControlPanel::INIT method.

(See C:\IDL\Catalyst\source\core\catatom__define.pro)

## CATATOM::COPY

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATATOM::COPY

     PURPOSE:

            This procedure takes an object and returns a copy of it. Note that
            this is a "deep" copy in so far as all the data referred to by the
            object is copied. Also note that this is an inherently SLOW process!!

            This routine uses a temporary file during execution, so ensure that
            some disk space is available. The temporary file is stored in the
            current directory unless the TEMPDIR keyword is set or the default
            variable TEMPDIR has been defined with CatSetDefault.

     SYNTAX:

           copy = obj -> Copy, object, TempDir=tempdir

     ARGUMENTS:

            OBJECT: The object to be copied. If not supplied, self is copied.

     KEYWORDS:

            TEMPDIR: The directory to be used for the temporary file.

(See C:\IDL\Catalyst\source\core\catatom__define.pro)

## CATATOM::DOCUMENT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATATOM::DOCUMENT

     PURPOSE:

           This method creates an HTML file (usually files, since superclass
           objects are also documented) for the object. If running on Windows,
           a Internet Explorer is spawned to read the documentation files.

     SYNTAX:

           self -> Document

     ARGUMENTS:

           None.

     KEYWORDS:

           DIRECTORY: The name of directory where the HTML files should be saved.
                      By default, the method will try to use the default variable DOCDIR,
                      which can be set with CatSetDefault. Otherwise, the user is asked
                      to specify a currently-existing directory. If none is specified,
                      the current directory is used.

(See C:\IDL\Catalyst\source\core\catatom__define.pro)

## CATATOM::DRAW

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATATOM::DRAW

     PURPOSE:

           This method propogates a DRAW method invocation to the children of this
           object. We expect the method to be called automatically by all subclasses
           of the CatAtom class. On those occasions when you do NOT want the DRAW method
           of children invoked, set the NO_CHILDREN keyword and the DRAW method returns
           immediately. If an invalid child object is discovered, it is removed from
           the parent container.

     SYNTAX:

           self -> Draw

     ARGUMENTS:

           None.

     KEYWORDS:

           REQUESTER:        This optional keyword is set to the object that requests a DRAW of the
                             object. This is helpful sometimes when messages are received by other
                             objects.

           NO_CHILDREN:      If this keyword is set, the DRAW method is not propogated to the
                             object children, but the DRAW method returns immediately.

(See C:\IDL\Catalyst\source\core\catatom__define.pro)

## CATATOM::ERROR

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATATOM::ERROR

     PURPOSE:

           This method implements an error report into a log file or to standard output.
           The method should normally only be called from within a CATCH error handler.
           It relies on !ERROR_STATE having current information about the error.

     SYNTAX:

           self -> Error

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\catatom__define.pro)

## CATATOM::EVENTHANDLER

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATATOM::EVENTHANDLER

     PURPOSE:

           A dummy event handler method to catch widget events. If events come here, they
           are dispatched, if possible, to the first parent of this object. If there are
           no parents, an error message is delivered.

     SYNTAX:

           Called from the CATEVENTDISPATCHER utility routine.

     ARGUMENTS:

           Event:  The event structure from a widget event.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\catatom__define.pro)

## CATATOM::GETPROPERTY

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATATOM::GETPROPERTY

     PURPOSE:

           This method is used to get the object's properties.

     SYNTAX:

           self -> GetProperty, Name=objectName

     ARGUMENTS:

           None.

     KEYWORDS:

           AUTO_DESTROY:  A flag indicating whether this objects lifecycle
                          is controlled my the memory management system.

           CONTROLPANEL:  The object reference of the control panel. If none exists, a null object
                          is returned.

           ERRORLEVEL:    The error reporting level for this object.

           EVENT_METHOD:  The name of the current event method for this object.

           EVENT_OBJECTS: This keyword returns the widget object or objects that will handle events for this
                          particular object.

           EXCLUSIVE_EVENT_OBJECT: The exclusive event object, if available.

           NAME:          The name given to this object.

           PARENTS:       An array of the parents of this object.

           REPORTLEVEL:   The informational reporting level for this object.

           TOP:           A reference to the object at the top of the object hierarchy to which this
                          object belongs.

           NO_COPY:       Set this keyword to transfer the UVALUE without copying.

           UVALUE:        A user value pointer. Can be used to store any IDL variable type.

(See C:\IDL\Catalyst\source\core\catatom__define.pro)

## CATATOM::GETSTATE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATATOM::GETSTATE

     PURPOSE:

           This method is used to get the object's properties as a structure. It
           is primarily intended to be used with the corresponding SETSTATE method.

     SYNTAX:

           state = self -> GetState ()

     ARGUMENTS:

           None.

     KEYWORDS:

           SCALARS:   Set this keyword to include scalar properties. If no type
                      keywords are specified, this will be set. (Input)

           ARRAYS:    Set this keyword to include array properties. If no type
                      keywords are specified, this will be set. (Input)

           POINTERS:  Set this keyword to include pointer properties. If no type
                      keywords are specified, this will NOT be set. (Input)

           OBJECTS:   Set this keyword to include object reference properties. If no type
                      keywords are specified, this will NOT be set. (Input)

           ALL:       Set this keyword to include the all the above types. (Input)

           INHERITED: Set this keyword to include properties inherited from the
                      superclass. (Input)

(See C:\IDL\Catalyst\source\core\catatom__define.pro)

## CATATOM::HELP

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATATOM::HELP

     PURPOSE:

           This method allows you to look at the current value of the object class structure.
           It is similar to doing a Help, object, /Structure call at the IDL command line.
           It depends upon having defined an output parameter for the CLASSNAME__DEFINE procedure
           of any object that uses the method. All Catalyst objects use this convention:

           PRO CLASSNAME__DEFINE, class
              class = {....}
           END

     SYNTAX:

           anObject = self -> Help

     ARGUMENTS:

           theField:     The name of a particular field you would like HELP on.

     KEYWORDS:

           FIELDS:       Set this keyword to see a list of the structure field names.

(See C:\IDL\Catalyst\source\core\catatom__define.pro)

## CATATOM::INIT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATATOM::INIT

     PURPOSE:

           This is the CATATOM object class creator method.

     SYNTAX:

           Called automatically when the object is created.

     ARGUMENTS:

           None.

     KEYWORDS:

           ERRORLEVEL:     The error level for this object. The default value is 2. Values can be:

                           0: Silently ignore the error. No visual output to the user.
                           1: Notify the user of the error by writing traceback information in the command log
                              or journal file. No graphical user interface notification.
                           2: Default. Notify the user with a graphical dialog and also write traceback
                              information in the command log or journal file.

           EVENT_METHOD:   Set this keyword to the name of the event method that should be
                           called when an event is generated for this widget. If undefined,
                           the event method is "EventHandler".

           EVENT_OBJECT:   This is an object reference to an object that will receive the
                           event from a specific widget event. It is the equivalent (in
                           widget terms) of specifying an EVENT_PRO or EVENT_FUNC keyword.
                           In other words, it is a way of deflected an event from the EVENTHANDLER
                           method of the object that generated the event to the EVENTHANDLER
                           method of the object specified with this keyword.

           EXCLUSIVE_EVENT_OBJECT: If this keyword is set to a vaid object, events are passed directly
                           and only to this object, ignoring the other event objects. To disable this,
                           set this keyword to be a NULL object or zero. This keyword is designed for
                           situations where an object wishes to hog the events for a limited period.

           NO_COPY:        Set this keyword to transfer the UVALUE without copying.

           PARENT:         A parent container object. Must be subclassed from IDL_CONTAINER. The object
                           will be added to its parent container. (Input)

           REPORTLEVEL:    This sets the report level for the object. Reports are sent with the REPORT
                           method with a ReportLevel value. If the ReportLevel value is less than the
                           REPORTLEVEL value set here, then the report is suppressed. The default REPORTLEVEL
                           value is 2, allowing normal and debug messages to be recorded while suppressing
                           more verbose reporting. Report levels correspond to these values:

                           0: An "alert" message is sent.
                           1: An "informational" message is sent.
                           2: A "debug informational" message is sent.
                           3: A "normal" message is sent. (This is the default for the REPORT method.)

                           Reports are sent to a log file (if the Catalyst Library global variable
                           LOGFILENAME is defined) or or the command log window.

           UVALUE:         A user-value pointer. Can be used to store any IDL variable type.

           _EXTRA:         Any keyword appropriate for the IDL_CONTAINER::INIT method.

(See C:\IDL\Catalyst\source\core\catatom__define.pro)

## CATATOM::MESSAGEHANDLER

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATATOM::MESSAGEHANDLER

     PURPOSE:

           This method receives notification of a SENDMESSAGE call from another object's
           method. This method should be overridden in any object that expects to receive
           messages from objects. Be sure your MessageHandler methods define the arguments
           and keywords shown here. If the message gets here, we issue an error message.

     SYNTAX:

           thisObject -> MessageHandler, title, SENDER=sender, DATA=data

     ARGUMENTS:

           TITLE:   The title of the message.

     KEYWORDS:

           DATA:    A keyword that contains any information the sender wishes to pass
                    with the message. It can be empty.

           SENDER:  The object that generated the message

(See C:\IDL\Catalyst\source\core\catatom__define.pro)

## CATATOM::PRINT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATATOM::PRINT

     PURPOSE:

           This method prints a simple display showing the hierarchy rooted
           at this object.

     SYNTAX:

           self -> Print

     ARGUMENTS:

           None.

     KEYWORDS:

           Level: The depth in the hierarchy of this object. Note that this
                  is normally set internally as the program recurses through
                  the hierarchy.

(See C:\IDL\Catalyst\source\core\catatom__define.pro)

## CATATOM::REGISTERFORMESSAGE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATATOM::REGISTERFORMESSAGE

     PURPOSE:

           This method enables an object to request messages of a specific title. These
           messages, when generated, will be passed to the MessageHandler method of the
           recipient object. This method can also be used to unregister for a message
           by setting the UNREGISTER keyword.

     SYNTAX:

           thisObject -> Register_For_Message, recipient, title

     ARGUMENTS:

           RECIPIENT:   The object that requires notification.

           TITLE:       The title of messages to pass.

     KEYWORDS:

           UNREGISTER: Set this keyword to unregister an object that has previously
                       registered itself for messages. The RECIPIENT and TITLE must
                       be the same as when the RECIPIENT registered the message.

(See C:\IDL\Catalyst\source\core\catatom__define.pro)

## CATATOM::REPORT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATATOM::REPORT

     PURPOSE:

           This method is used to send program reports either to a log file or to standard
           output. If the self._reportLevel variable is less than or equal to that requested,
           the  message is output. This allows great flexibility
           in the kinds of reports that get reported, and in particular it allows the user to turn
           reporting to a higher level for a specific object than for other objects. This is
           extremely useful in debugging object programs.

           Reports are sent to a log file if the LogFileName system default is not a NULL string.

           An "alert" message throws up a DIALOG_MESSAGE widget that the user must repond to.

     SYNTAX:

           self -> Report, theMessage, reportLevel

     ARGUMENTS:

           theMessage:  The message text.

           reportLevel: The type of report. 0: alert, 1: informational, 2: verbose report.
                        All reports depend upon a comparison between the ReportLevel,
                        the self._reportLevel and the input reportLevel values. The largest of these
                        three values is used to set the report level.

     KEYWORDS:

           COMPLETED:   A "completed" standard verbose message.

           FAILED:      A "failed" standard verbose message.

           STARTED:     A "started" standard verbose message.

(See C:\IDL\Catalyst\source\core\catatom__define.pro)

## CATATOM::SELECT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATATOM::SELECT

     PURPOSE:

           This method is a dummy method for a "selection" process. An object who wishes
           to be "selected" must override this method. A "selected" object will return its
           own object reference.

     SYNTAX:

           thisObject -> Select, x, y

     ARGUMENTS:

           X:         A dummy parameter. Perhaps the X location in a draw widget.

           Y:         A dummy parameter. Perhaps the Y location in a draw widget.

     KEYWORDS:

           SUCCESS:   Set to 1 if a selection is made. To 0 otherwise.

           _EXTRA:    Any extra keywords.

(See C:\IDL\Catalyst\source\core\catatom__define.pro)

## CATATOM::SENDMESSAGE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATATOM::SENDMESSAGE

     PURPOSE:

           This method dispatches messages to objects that have registered to receive
           them (using the RegisterForMessage method).

     SYNTAX:

           thisObject -> SendMessage, title, DATA=data

     ARGUMENTS:

           TITLE:   The title of the message. The message will be sent to objects that have
                    registered to receive messages with this title.

     KEYWORDS:

           DATA:    A keyword for passing relevant data along with the message.

(See C:\IDL\Catalyst\source\core\catatom__define.pro)

## CATATOM::SETPROPERTY

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATATOM::SETPROPERTY

     PURPOSE:

           This method is used to set the object's properties.

     SYNTAX:

           self -> SetProperty, NAME=theName

     ARGUMENTS:

           None.

     KEYWORDS:

           AUTO_DESTROY:   Set this keyword to use memory management to destroy the object.  (Input)

           CONTROLPANEL:   A control panel object. Must be subclassed from CATCONTROLPANEL. (Input)

           DRAW:           Set this keyword to call the draw method after setting properties (Input).

           ERRORLEVEL:     Set this keyword to modify the behaviour when an error occurs (Input).

           EVENT_METHOD:   Set this keyword to the name of the object method that will
                           handle the events for this object. It is roughly equivalent
                           to setting EVENT_PRO in a widget program.

           EVENT_OBJECTS:  This is an object reference to an object that will receive the
                           event from a specific widget event. It is the equivalent (in
                           object terms) of specifying an EVENT_PRO or EVENT_FUNC keyword.
                           In other words, it is a way of deflected an event from the EVENTHANDLER
                           method of the object widget that generated the event to the EVENTHANDLER
                           method of the object specified with this keyword. It may be an array of
                           objects. Any objects currently defined as event objects will be replaced.

           EXCLUSIVE_EVENT_OBJECT: If this keyword is set to a vaid object, events are passed directly
                           and only to this object, ignoring the other event objects. To disable this
                           set this keyword to be a NULL object or zero. This keyword is designed for
                           situations where an object wishes to hog the events for a limited period.

           GROUP_LEADER:   The group leader widget ID. Must be used for floating and
                           modal base widgets.

           NAME:           The "name" of the object. Used to keep track of the object in the code. (Input)

           NO_COPY:        Set this keyword to transfer the UVALUE without copying.

           REPORTLEVEL:    Set this keyword to modify the behaviour when an message is invoked (Input).

           UVALUE:         A user-value pointer. Can be used to store any IDL variable type.

(See C:\IDL\Catalyst\source\core\catatom__define.pro)

## CATATOM::SETSTATE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATATOM::SETSTATE

     PURPOSE:

           This method is used to set the object's properties using a structure. It
           is primarily intended to be used with the corresponding GETSTATE method.

     SYNTAX:

           self -> SetState (state)

     ARGUMENTS:

           STATE:        A structure whose tag names match some/all of the object properties.
                         Normally this structure would be from a GETSTATE method invocation
                         for this object or another of the same class.

     KEYWORDS:

           IGNORE_CLASS: The state structure returned by the GETSTATE method has a name
                         identifying it as the state structure for a partucular class. If
                         an attempt is made to apply it to another class, the call fails.
                         To override this behaviour, set the UNMATCHED keyword. (Input)

(See C:\IDL\Catalyst\source\core\catatom__define.pro)

## CATATOM::WHOMESSAGERECIPIENTS

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATATOM::WHOMESSAGERECIPIENTS

     PURPOSE:

           This method prints out the name of all current message recipients and
           which messages they are regestered for. This is a debugging method.

     SYNTAX:

           thisObject -> WhoMessageRecipients

     ARGUMENTS:

           None.

     KEYWORDS:

           None

(See C:\IDL\Catalyst\source\core\catatom__define.pro)

## CATCONTAINER

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatContainer

     PURPOSE:

            This is the most basic object in the Catalyst Library. It is actually a simple
            wrapper around the IDL_CONTAINER object, adding get-by-name, reference counting,
            and memory management. Reference counting is what assures that objects in the
            Catalyst system are not destroyed until every other object in the system is done
            using them. For the most part, users can completely ignore this feature of
            the program and their programs will clean themselves up miraculously. To avoid
            memory leaks, all you have to do is make sure you destroy all pointers and objects
            you use to hold information in your program in your CLEANUP method. (And be *absolutely*
            sure you call the superclass CLEANUP method.) But any objectyou add to another object is
            destroyed automatically. This feature alone is worth the astronomical cost of the Catalyst Library!

     AUTHORS:

            FANNING SOFTWARE CONSULTING   BURRIDGE COMPUTING
            1645 Sheely Drive             18 The Green South
            Fort Collins                  Warborough, Oxon
            CO 80526 USA                  OX10 7DN, ENGLAND
            Phone: 970-221-0438           Phone: +44 (0)1865 858279
            E-mail: davidf@dfanning.com   E-mail: davidb@burridgecomputing.co.uk

     SUPERCLASSES:

           IDL_CONTAINER

     SYNTAX:

           catContainerObject = Obj_New('CatContainer')

     CLASS_STRUCTURE:

       struct = { CatContainer,                   $ ; The CatContainer object class name.
                  _autoDestroy      : 0B,         $ ; A flag denoting whether the object self destructs
                                                      when reference count reaches 0.
                  _name             : "",         $ ; The "name" of the object.
                  _parents          : OBJ_NEW (), $ ; A list (container) of parent objects.
                  _memoryManagement : 0B,         $ ; A flag to show if objects contained within this
                                                      object know about this object.
                  _indexed          : 0B,         $ ; A flag to specify whether the list is specifically indexed.
                  INHERITS IDL_CONTAINER          $
                }

     MODIFICATION_HISTORY:

           Written by: David Burridge, 12th March 2003
           Added OCHILD and OSYBLING keywords to the GetProperty method. 24 June 2005. DWF.

(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)

## CATCONTAINER::ADD

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatContainer::ADD

     PURPOSE:

           This method overrides the IDL_CONTAINER Add method to allow
           the user to add an child object to this container.

           If the child is a CatContainer (or subclass of), it is
           notified of the additional parent.

     SYNTAX:

           container -> Add, object

     ARGUMENTS:

           object: The object to add to the container. (Required)

     KEYWORDS:

           POSITION: The position index where the object should be added to
                     the container.

(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)

## CATCONTAINER::ADDPARENT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatContainer::ADDPARENT

     PURPOSE:

           This method is used to notify this object that it has been added to a new
           parent object. This is used internally in the object and should not be
           called from the outside.

     SYNTAX:

           container -> AddParent, object

     ARGUMENTS:

           object: The parent object to which this one has been added. (Required)

     KEYWORDS:

           NONE.

(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)

## CATCONTAINER::CLEANUP

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatContainer::CLEANUP

     PURPOSE:

           This is the CatContainer object class destructor method.

     SYNTAX:

           Called automatically when the object is destroyed.

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)

## CATCONTAINER::FINDBYNAME

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatContainer::FindByName

     PURPOSE:

           This method is returns the positions (indices) of named objects in the container.

     SYNTAX:

           locns = container -> FindByName( searchName )

     ARGUMENTS:

           searchName:     The name of the object you are looking for in this container (Required)

     KEYWORDS:

           CASE_SENSITIVE: Set this keyword to 1 to indicate a case-sensitive search. By default, the
                           search is case-insensitive.

           COUNT:          Set this keyword to a named variable that upon exit will contain the number
                           of objects returned that meet the searchName description. (Output)

           REGEXP:         Set this keyword to 1 to indicate the searchName is a regular expression.

           _EXTRA:         Any keywords supported by STREGEX can also be used. Requires REGEXP to be set.

(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)

## CATCONTAINER::GET

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatContainer::GET

     PURPOSE:

           This method overrides the IDL_CONTAINER GET method to allow the user to return
           an object or objects by "name".

     SYNTAX:

           object = self -> Get(searchName)

     RETURN_VALUE:

           object:     The found object or an array of objects (if more than one meet the search criteria).
                       A null object is retuned if there are no matches.

     ARGUMENTS:

           searchName: The name of the object to find in the containment hierarchy. If absent,
                       the superclass IDL_CONTAINER::GET method is called and the first object
                       in the container (if there is one) is returned. Otherwise, a null object
                       is returned. You may use a regular expression for the searchName, if the
                       REGEXP keyword is set. For example, to find all objects with the names
                       beginning with capital C through G, the searchName would be "[C-G.]".)

     KEYWORDS:

           ALL:        Set this keyword to return an array of object references to all of the objects
                       in the container.

           CASE_SENSITIVE: Set this keyword to do a case-sensitive search for the objects. Searches
                       are case-insensitive by default.

           COUNT:      The number of objects found. Check this output keyword instead of the return value
                       to indicate success. (Output)

           ISA:        Set this keyword equal to a class name or vector of class names. This keyword is used
                       in conjunction with the ALL keyword. The ISA keyword filters the array returned by the
                       ALL keyword, returning only the objects that inherit from the class or classes specified
                       by the ISA keyword. This keyword is ignored if the ALL keyword is not provided.

           POSITION:   Set this keyword equal to a scalar or array containing the zero-based indices
                       of the positions of the objects to return.

           RECURSIVE_SEARCH: If this keyword is set, the seach is conducted on all objects
                       in the object hierarchy below the entry point. In other words, the search
                       is done not only on child objects, but grandchild objects, great-grandchild
                       objects. etc.

           REGEXP:     Set this keyword to indicate the searchName is a regular expression.

           _EXTRA:     Any keywords supported by STREGEX can also be used. Requires REGEXP to be set.

(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)

## CATCONTAINER::GETNAME

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatContainer::GETNAME

     PURPOSE:

           This method is used to return the object's name.

     SYNTAX:

           name = self -> GetName()

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)

## CATCONTAINER::GETPROPERTY

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatContainer::GETPROPERTY

     PURPOSE:

           This method is used to get the object's properties.

     SYNTAX:

           self -> GetProperty, Name=objectName

     ARGUMENTS:

           None.

     KEYWORDS:

           AUTO_DESTROY:      A flag specifying whether this object self destructs when its parent
                              reference count reduces to zero. (Output)

           OCHILD:            Returns the first child in the object container. If there are no children,
                              a null object is returned. Used to traverse the object hierarchy.

           FIRST_PARENT:      This keyword will return the first parent in the _parents container.
                              If there are no parents, it will return a null object.

           INDEXED:           A flag specifying whether the list is indexed.

           MEMORY_MANAGEMENT: A flag specifying whether the children of this object know about
                              this parent (and therefore whether their existance depends on this object)
                              (Output)

           NAME:              The "name" of the object. Used to keep track of the object in the code. (Output)

           PARENTS:           An array of parent objects.

           OSYBLING:          Returns the first sybling in the object container. If there are no children,
                              a null object is returned. Used to traverse the object hierarchy.

(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)

## CATCONTAINER::GETPROPERTY (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATCONTAINER::GETPROPERTY (function)

     PURPOSE:

           This function method is a wrapper around the GetProperty procedure method. It
           is primarily intended for convenience in getting a single property. Note that
           it takes about twice as long to execute as its procedure counterpart.

     SYNTAX:

           result = self -> GetProperty (/KEYWORD)

     ARGUMENTS:

           None.

     KEYWORDS:

           KEYWORD: By setting any keyword appropriate for the GetProperty method of this
                    object, that property is returned by the function. If more than one
                    property is set, the function will fail.

(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)

## CATCONTAINER::INIT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatContainer::INIT

     PURPOSE:

           This is the CatContainer object class creator method.

     SYNTAX:

           Called automatically when the object is created.

     ARGUMENTS:

           PARENT:      A parent container object. Must be subclassed from IDL_CONTAINER. The object
                        will be added to its parent container. (Input)

     KEYWORDS:

           AUTO_DESTROY: The CATCONTAINER object keeps track of the number of parents it has (reference
                         counting). When the reference count changes from 1 to 0, the object is automatically
                         destroyed. Setting AUTO_DESTROY to 0 will prevent this automatic destruction.
                         By default, this keyword is set to 1. Note that if you set AUTO_DESTROY=0
                         you will be responsible for destroying the object when you are finished with it.
                         (In reference counting, when an object's reference count goes to 0, the object
                         is automatically destroyed. Setting this keyword prevents the automatic destruction
                         that would occur otherwise.)

           INDEXED:      If set, the objects that are added to the container will always have
                         the same index value they are assigned when they are added to the container.
                         If objects are later removed from the container, a null object is added in that
                         indexed space, thus assuring that all objects keep their assigned index number.

           MEMORY_MANAGEMENT: Setting this keyword to 0 disables automatic memory management for
                         this container. This means that objects added to the container will not realize they
                         are children of this container. The default is to set this keyword to 1. (This
                         is "reference counting".)

           NAME:         The "name" of the object. Used to keep track of the object in the code.
                         You can "GET" an object by its name, for example.  Any string is acceptible. (Input)

           POSITION:     This object's position in the parent container. See the IDL_CONTAINER
                         documentation. (Input)

(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)

## CATCONTAINER::PRINT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatContainer::PRINT

     PURPOSE:

           This method is used to print a list of the objects contents.

     SYNTAX:

           container -> Print

     ARGUMENTS:

           None.

     KEYWORDS:

           LABEL:      Any text passed through 'Label' will be prepended onto the printed lines.

           RECURSIVE:  If set, this keyword prints the contents of any child objects who
                       are also containers. (input)

(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)

## CATCONTAINER::REMOVE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatContainer::REMOVE

     PURPOSE:

           This method overrides the IDL_CONTAINER REMOVE method to allow the user to remove by
           name an object with reference counting.

     SYNTAX:

           self -> Remove, object

     ARGUMENTS:

           object:    Either the object reference or name (searchName) of the object to remove.

     KEYWORDS:

           ALL:       Set this keyword to remove all objects from the container. If both the object parameter and
                      this keyword is set, all objects of the specified type/name will be removed.

           POSITION:  Set this keyword equal to the zero-based index of the object to be removed. If the
                      SearchName argument is supplied, this keyword is ignored.

           REGEXP:    Set this keyword to indicate the searchName is a regular expression.

           _EXTRA:    Any keywords supported by STREGEX can also be used. Requires REGEXP to be set.

(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)

## CATCONTAINER::REMOVEPARENT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatContainer::REMOVEPARENT

     PURPOSE:

           This method removes a parent reference from an object list. It is used internally in
           the container object and should not be called from outside.

           If the last parent is removed and the AutoDestroy property is TRUE, the object will
           self destruct (as it is no longer required).

     SYNTAX:

           container -> RemoveParent, thisParent

     ARGUMENTS:

           thisParent: The object reference of the parent to be removed.

     KEYWORDS:

           NODESTROY:  If this keyword is set, the AUTO_DESTROY keyword is set to 0 on the object
                       before its parent is removed, and set back to its input value on exit. The
                       point of setting the NODESTROY keyword is to be able to remove object
                       parents prior to SAVING the object. (If this is not done, the entire
                       object hierarchy will be SAVED with the SAVE file.)

(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)

## CATCONTAINER::SETPROPERTY

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatContainer::SETPROPERTY

     PURPOSE:

           This method is used to set the object's properties.

     SYNTAX:

           self -> SetProperty, NAME=theName

     ARGUMENTS:

           None.

     KEYWORDS:

           AUTO_DESTROY: The CATCONTAINER object keeps track of the number of parents it has (reference
                         counting). When the reference count changes from 1 to 0, the object is automatically
                         destroyed. Setting AUTO_DESTROY to 0 will prevent this automatic destruction.
                         By default, this keyword is set to 1. Note that if you set AUTO_DESTROY=0
                         you will be responsible for destroying the object when you are finished with it.

           NAME:         The "name" of the object. Used to keep track of the object in the code. (Input)

(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)

## CATCONTAINER::SHOWCONTENTS

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATCONTAINER::SHOWCONTENTS

     PURPOSE:

           This method is used to graphically represent the contents of an object.
           It does a recursive search through the object containers.

     SYNTAX:

           self -> ShowContents

     ARGUMENTS:

           None.

     KEYWORDS:

           _EXTRA:   Any keywords appropriate for the PROPERTYPANEL object.

(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)

## CATCONTROLPANEL

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATCONTROLPANEL

     PURPOSE:

           The purpose of this routine is to implement a control panel as an object. It
           automatically deals with whether the CP is embedded or standalone and adds
           OK, APPLY and CANCEL buttons if required. Control panels are most often
           represented by propertysheet widgets, but don't have to be. Our original
           notion was that every object in the Catalyst system could have its own control
           panel to allow the user to manipulate the properties of that object. See the
           ControlPanel method of the IMGAXES object as an example of how to create control
           panels for objects.

           Objects can (and should) customise the control panel by adding other widget
           objects. Note that the events for these will be passed to the caller object
           event handler.

     AUTHORS:

            FANNING SOFTWARE CONSULTING   BURRIDGE COMPUTING
            1645 Sheely Drive             18 The Green South
            Fort Collins                  Warborough, Oxon
            CO 80526 USA                  OX10 7DN, ENGLAND
            Phone: 970-221-0438           Phone: +44 (0)1865 858279
            E-mail: davidf@dfanning.com   E-mail: davidb@burridgecomputing.co.uk

     CATEGORY:

           Object widgets.

     SYNTAX:

           aCatControlPanel = Obj_New("CatControlPanel", callerObject)

     SUPERCLASSES:

           WIDGETATOM
           CATATOM
           IDL_CONTAINER

     CLASS_STRUCTURE:

       class = { CatControlPanel, $
                 _caller : OBJ_NEW (), $           ; The object that calls the Control Panel.
                 _tlb    : OBJ_NEW (), $           ; The pseudo-TLB of the Control Panel widgets.
                 _event_destination: OBJ_NEW(), $  ; The object that will receive events.
                INHERITS BaseWidget $
                }

     MODIFICATION_HISTORY:

           Written by: David Burridge, 19th August 2002.

(See C:\IDL\Catalyst\source\core\catcontrolpanel__define.pro)

## CATCONTROLPANEL::CLEANUP

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATCONTROLPANEL::CLEANUP

     PURPOSE:

           This method cleans up a control panel.

     SYNTAX:

           Called automatically on destruction, thus:

           OBJ_DESTROY, aCatControlPanel

     ARGUMENTS:

           None.

     KEYWORDS:

           _EXTRA: Any keywords valid for the "BASEWIDGET::CLEANUP" method.

(See C:\IDL\Catalyst\source\core\catcontrolpanel__define.pro)

## CATCONTROLPANEL::CREATED_OWN_TLB

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATCONTROLPANEL::CREATED_OWN_TLB

     PURPOSE:

           This method returns a 1 if the control panel object created it's own TLB, and a 0 otherwise.

     SYNTAX:

            IF aCatControlPanel -> CREATED_OWN_TLB(tlb) THEN tlb -> Draw ELSE cp -> Show

     ARGUMENTS:

           tlb   : The object reference stored in the self._tlb field of the object. (Output)

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\catcontrolpanel__define.pro)

## CATCONTROLPANEL::DRAW

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATCONTROLPANEL::DRAW

     PURPOSE:

           This method draws the control panel.

     SYNTAX:

           aCatControlPanel -> Draw

     ARGUMENTS:

           None.

     KEYWORDS:

           _EXTRA:   Any keywords accepted by the "BASEWIDGET::DRAW" method.

(See C:\IDL\Catalyst\source\core\catcontrolpanel__define.pro)

## CATCONTROLPANEL::EVENTHANDLER

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATCONTROLPANEL::EVENTHANDLER

     PURPOSE:

           This method serves as an event handler for the "OK", "APPLY" and "CANCEL" buttons
           (if they exist for this control panel). When an event is received, and new CATCONTROL_PANEL
           event structure is created with the name of the button as the VALUE field. This event
           structure is then sent to the real object handling the events for this control panel.

     SYNTAX:

           Called automatically by the event dispatcher.

     ARGUMENTS:

           event:    A structure describing the event.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\catcontrolpanel__define.pro)

## CATCONTROLPANEL::INIT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATCONTROLPANEL::INIT

     PURPOSE:

           This method creates a default control panel.

     SYNTAX:

           Called automatically by initialisation, thus:

           aCatControlPanel = OBJ_NEW ('CatControlPanel', caller)

     ARGUMENTS:

           CALLER:         The object reference of the object the control panel controls.

     KEYWORDS:

           BASEWIDGET:     A parent object for the control panel. If this is a base widget object
                           the control panel will be mounted upon it. Otherwise, the control panel
                           will be in its own window (see the TITLE and TLB_FRAME_ATTR keywords below).

           EVENT_OBJECT:   The object that should receive the events generated by this control panel.
                           If not provided, this will be the same as the CALLER.

           NAME:           The name of the control panel. By default, it is set to the name of the
                           caller object with " Control Panel" appended to it.

           NO_APPLY:       Set this keyword to specify no "Apply" button on the interface. This keyword
                           only applies if the CatControlPanel creates its own top-level base.

           NO_CANCEL:      Set this keyword to specify no "Cancel" button on the interface. This keyword
                           only applies if the CatControlPanel creates its own top-level base.

           NO_OK:          Set this keyword to specify no "OK" button on the interface. This keyword
                           only applies if the CatControlPanel creates its own top-level base.

           PARENT:         A parent object for the control panel. If this is a base widget object
                           the control panel will be mounted upon it. Otherwise, the control panel
                           will be in its own window (see the TITLE and TLB_FRAME_ATTR keywords below).

           TITLE:          The title attributes of the top-level base of the Control Panel. Only
                           used if baseObj is not provided.

           TLB_FRAME_ATTR: The frame attributes of the top-level base of the Control Panel. Only
                           used if BASEWIDGET keyword is not provided.

           _EXTRA:         Any keywords valid for the "BASEWIDGET::INIT" method.

(See C:\IDL\Catalyst\source\core\catcontrolpanel__define.pro)

## CATCONTROLPANEL::REFRESH_PROPERTIES

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATCONTROLPANEL::REFRESH_PROPERTIES

     PURPOSE:

           This method searches in the ControlPanel base widget for a child
           that is a PropertySheet widget. If it finds one, it sets the
           REFRESH_PROPERTY keyword to 1 so that all the properties in the
           control panel are updated at once.

     SYNTAX:

           aCatControlPanel -> Refresh_Properties

     ARGUMENTS:

           None.

     KEYWORDS:

           PROPERTIES:   The string or string array listing the properties that should be refreshed.
                         If not provided, all properties are refreshed.

(See C:\IDL\Catalyst\source\core\catcontrolpanel__define.pro)

## CATCONTROLPANEL::SHOW

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATCONTROLPANEL::SHOW

     PURPOSE:

           This method shows the control panel on the screen. If the control panel
           already exists, it gets popped to the front.

     SYNTAX:

           aCatControlPanel -> Show

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\catcontrolpanel__define.pro)

## CATIPTOOL

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATIPTOOL

     PURPOSE:

           The purpose of this routine is to implement an image processing command
           as a tool object, giving the command the ability to be undone. Any
           image processing command can be used. The command will call the GETDATA
           method on the target image object to obtain the data to processes. Any
           number of keywords are supported in the object.

     AUTHORS:

            FANNING SOFTWARE CONSULTING   BURRIDGE COMPUTING
            1645 Sheely Drive             18 The Green South
            Fort Collins                  Warborough, Oxon
            CO 80526 USA                  OX10 7DN, ENGLAND
            Phone: 970-221-0438           Phone: +44 (0)1865 858279
            E-mail: davidf@dfanning.com   E-mail: davidb@burridgecomputing.co.uk

     CATEGORY:

           Objects.

     SYNTAX:

           aTool = Obj_New("CATIPTOOL", command, targetImageObject, Keyword=keyword)

     SUPERCLASSES:

           CATTOOL
           CATATOM
           CATCONTAINER
           IDL_CONTAINER

     CLASS_STRUCTURE:

       class = { CATIPTOOL, $           ; The CATIPTOOL object class.
                 INHERITS CATTOOL, $    ; Inherits the CATTOOL object class.
                 _command: "", $        ; The IDL image processing command.
                 _p1: Ptr_New(), $      ; The first additional parameter of the command.
                 _p2: Ptr_New(), $      ; The second additional parameter of the command.
                 _p3: Ptr_New(), $      ; The third additional parameter of the command.
                 _nparams: 0L, $        ; The number of additional parameters.
                 _keywords: Ptr_New() $ ; A structure of keywords used with the command.
               }

     MODIFICATION_HISTORY:

           Written by: David Fanning, July 14, 2003.

(See C:\IDL\Catalyst\source\core\catiptool__define.pro)

## CATIPTOOL::APPLY

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATIPTOOL::APPLY

     PURPOSE:

           This method applies or executes the image processing command.
    ;
     SYNTAX:

           thisObject -> Apply

     ARGUMENTS:

           None.

     KEYWORDS:

           DRAW:     Set this keyword if you wish to call the draw method of the target object
                     after the command has been applied.

(See C:\IDL\Catalyst\source\core\catiptool__define.pro)

## CATIPTOOL::CLEANUP

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATIPTOOL::CLEANUP

     PURPOSE:

           This is the CATIPTOOL object class destructor method.

     SYNTAX:

           Called automatically when the object is destroyed.

     ARGUMENTS:

           None.

     KEYWORDS:

           _EXTRA:  Any keyword appropriate for the "TOOLATOM::Cleanup" method.

(See C:\IDL\Catalyst\source\core\catiptool__define.pro)

## CATIPTOOL::GETPROPERTY

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATIPTOOL::GETPROPERTY

     PURPOSE:

           This method enables the getting of the CATIPTOOL object class
           properties.

     SYNTAX:

           aGraphicsCmd -> GetProperty ...

     ARGUMENTS:

         None.

     KEYWORDS:

         _EXTRA:           Any keywords appropriate for the superclass SetProperty methods.

(See C:\IDL\Catalyst\source\core\catiptool__define.pro)

## CATIPTOOL::INIT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATIPTOOL::INIT

     PURPOSE:

           This is the CATIPTOOL object class initialization method.

     SYNTAX:

           Called automatically when the object is created.

     ARGUMENTS:

           command:      This is the name of the image processing "command" that is to be executed.
                         It should be a string. The image processing command should also be a function.
                         For example, "SOBEL" or "SMOOTH".

           targetObject: The image object that will provide the image data to be processed by this
                         image processing command object.

           p1:           This is the first additional parameter of the image processing command.
                         The *first* parameter of the image processing command is always the
                         image data obtained from the targetObject with the GETDATA method. For
                         example, in this case P1 will be equal to 7:

                             smoothObj = Obj_New('CATIPTOOL', 'Smooth', targetObject, 7)

                         And the command that will be executed is this:

                             targetObject -> SetData, Smooth(targetObject->GetData(), 7)

           p2:           This is the second additional parameter of the image processing command.

           p3:           This is the third additional parameter of the image processing command.

     KEYWORDS:

           AUTO_DESTROY: This object keeps track of the number of parents it has (reference counting). When
                         this value changes from 1 to 0, the object will be destroyed unless Auto_Destroy
                         has been set to zero. (Input)

           EVENT_OBJECT: This is an object reference to an object that will receive the
                         event from a specific widget event. It is the equivalent (in
                         object terms) of specifying an EVENT_PRO or EVENT_FUNC keyword.
                         In other words, it is a way of deflected an event from the EVENTHANDLER
                         method of the object widget that generated the event to the EVENTHANDLER
                         method of the object specified with this keyword.

           EXCLUSIVE_EVENT_OBJECT: If this keyword is set to a vaid object, events are passed directly
                         and only to this object, ignoring the other event objects. To disable this
                         set this keyword to be a NULL object or zero. This keyword is designed for
                         situations where an object wishes to hog the events for a limited period.

           INDEXED:      If set, the contents of this container will remain at the same index(ie:
                         indices will not automatically be re-used.

           MEMORY_MANAGEMENT: Setting this keyword to zero disables automatic memory management for
                         this container. This means that child objects will not realize that they
                         are children of this container.

           NAME:         The "name" of the object. Used to keep track of the object in the code.
                         You can "GET" an object by its name, for example.  Any string is acceptible. (Input)

           NO_COPY:      Set this keyword to transfer the UVALUE without copying.

           NOCACHE:      Set this keyword to indicate that the input data should not be cached
                         or stored in the storage location.

           ORIGINAL:     If set to 1, act on original image data instead of image display data.

           PARENT:       A parent container object. Must be subclassed from IDL_CONTAINER. The object
                         will be added to its parent container. (Input)

           POSITION:     This object's position in the parent container. See the IDL_CONTAINER
                         documentation. (Input)

           REPORTLEVEL:  The reporting level for the atom. This is honored only if the reporting
                         level for the atom is higher than the reporting level in the !Smart system
                         variable. It is used primarily for debugging purposes. Values between 0 and 2. (Input)

           TARGETOBJECT: The image object that is the target of this command. Note that a target object
                         is REQUIRED for the command to work correctly, although you do not have to
                         set the target in the INIT method. You can set it via the LOADCOMMAND and SETPROPERTY
                         methods, too. There must be a valid target at the time the APPLY method is called,
                         or an error is generated. The targetObject must be a valid CATIMAGE2D object.

           UVALUE:       A user-value pointer. Can be used to store any IDL variable type.

           _EXTRA:       Any keywords appropriate for the image processing command.

(See C:\IDL\Catalyst\source\core\catiptool__define.pro)

## CATIPTOOL::LOADCOMMAND

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATIPTOOL::LoadCommand

     PURPOSE:

           This method allows the user to load a command into the object.

     SYNTAX:

           aGraphicsCmd -> LoadCommand, 'command', targetObject, p1, p2, p3

     ARGUMENTS:

           command:      This is the name of the image processing "command" that is to be executed.
                         It should be a string. The image processing command should also be a function.
                         For example, "SOBEL" or "SMOOTH".

           targetObject: The image object that will provide the image data to be processed by this
                         image processing command object.

           p1:           This is the first additional parameter of the image processing command.
                         The *first* parameter of the image processing command is always the
                         image data obtained from the targetObject with the GETDATA method. For
                         example, in this case P1 will be equal to 7:

                             smoothObj = Obj_New('CATIPTOOL', 'Smooth', TARGETOBJECT=targetObject, 7)

                         And the command that will be executed is this:

                             targetObject -> SetData, Smooth(targetObject->GetData(), 7)

           p2:           This is the second additional parameter of the image processing command.

           p3:           This is the third additional parameter of the image processing command.

     KEYWORDS:

         DRAW:           Set this keyword to immediately call the Draw method when the command is executed.

          TARGETOBJECT:  The image object that is the target of this command. Note that a target object
                         is REQUIRED for the command to work correctly, although you do not have to
                         set the target in the INIT method. You can set it via the LOADCOMMAND and SETPROPERTY
                         methods, too. There must be a valid target at the time the APPLY method is called,
                         or an error is generated. The targetObject must be a valid CATIMAGE2D object.

         _EXTRA:         Any keywords appropriate for command may be used.

(See C:\IDL\Catalyst\source\core\catiptool__define.pro)

## CATIPTOOL::REDO

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATIPTOOL::REDO

     PURPOSE:

           This method attempts to redo the previous command operation.
    ;
     SYNTAX:

           thisObject -> REDO

     ARGUMENTS:

           None.

     KEYWORDS:

           DRAW:     Set this keyword if you wish to call the DRAW method on the target object
                     after the REDO operation.

(See C:\IDL\Catalyst\source\core\catiptool__define.pro)

## CATIPTOOL::SETPROPERTY

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATIPTOOL::SETPROPERTY

     PURPOSE:

           This method enables the setting of the CATIPTOOL object class
           properties.

     SYNTAX:

           aGraphicsCmd -> SetProperty ...

     ARGUMENTS:

         None.

     KEYWORDS:

          TARGETOBJECT:  The image object that is the target of this command. Note that a target object
                         is REQUIRED for the command to work correctly, although you do not have to
                         set the target in the this method. You can set it via the LOADCOMMAND and INIT
                         methods, too. There must be a valid target at the time the APPLY method is called,
                         or an error is generated. The targetObject must be a valid CATIMAGE2D object.

         _EXTRA:         Any keywords appropriate for the superclass SetProperty methods.

(See C:\IDL\Catalyst\source\core\catiptool__define.pro)

## CATIPTOOL::UNDO

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATIPTOOL::UNDO

     PURPOSE:

           This method attempts to undo the previous command operation by restoring
           the cached image data.
    ;
     SYNTAX:

           thisObject -> UNDO

     ARGUMENTS:

           None.

     KEYWORDS:

           DRAW:     Set this keyword if you wish to call the DRAW method on the target object
                     after the UNDO operation.

(See C:\IDL\Catalyst\source\core\catiptool__define.pro)

## CATLAYER::APPLYCOLORS

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATLAYER::APPLYCOLORS

     PURPOSE:

           This method sets up the colors for the layer object if they exist. For this
           reason, sub-classes *MUST* call this method at the *START* of their draw methods.

     SYNTAX:

           self -> ApplyColors

     ARGUMENTS:

           None.

     KEYWORDS:

          None.

(See C:\IDL\Catalyst\source\core\catlayer__define.pro)

## CATLAYER::APPLYCOORDS

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATLAYER::APPLYCOORDS

     PURPOSE:

           This method sets up the coordinates for the data object if they exist. For this
           reason, sub-classes *MUST* call this method at the *START* of their draw methods.

     SYNTAX:

           self -> ApplyCoords

     ARGUMENTS:

           None.

     KEYWORDS:

          None.

(See C:\IDL\Catalyst\source\core\catlayer__define.pro)

## CATLAYER::CLEANUP

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATLAYER::CLEANUP

     PURPOSE:

           This is the CATLAYER object class destructor method.

     SYNTAX:

           Called automatically when the object is destroyed.

     ARGUMENTS:

           None.

     KEYWORDS:

          None.

(See C:\IDL\Catalyst\source\core\catlayer__define.pro)

## CATLAYER::CONTROLPANEL

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATLAYER::CONTROLPANEL

     PURPOSE:

           This method creates a control panel for the CATLAYER object. A
           control panel is a graphical user interface for setting object
           properties. If you create a control panel, the events are typically
           sent to the EVENTHANDLER method.

     SYNTAX:

           theObject -> ControlPanel, baseObject

     ARGUMENTS:

           baseObject:    The object reference of a base widget for this control to
                          be added to. If not supplied, the control panel will be in a
                          self contained window (i.e., a TOPLEVELBASE object).

     KEYWORDS:

           _EXTRA:       Any keywords appropriate for the CatControlPanel::INIT method.

(See C:\IDL\Catalyst\source\core\catlayer__define.pro)

## CATLAYER::DRAW

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATLAYER::DRAW

     PURPOSE:

           This method may or may not be needed by your object, depending
           upon whether a graphical representation of the object is required.
           If you wish the DRAW method to automatically propogates down to any
           objects contained in this object's container, call the superclass DRAW
           method.

     SYNTAX:

           theObject -> Draw

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\catlayer__define.pro)

## CATLAYER::EVENT_HANDLER

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
            CATLAYER::EVENT_HANDLER

     PURPOSE:

            This method is the event handler for the CATLAYER object. It will typically
            be used to respond to events from widget objects created in the CONTROLPANEL
            method.

     SYNTAX:

            This method is called automatically by the event handling mechanism.

     ARGUMENTS:

           event: The event structure as described in the IDL help files, except
                  that the ID, TOP and HANDLER tags will be object references.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\catlayer__define.pro)

## CATLAYER::GETPROPERTY

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATLAYER::GETPROPERTY

     PURPOSE:

           This method allows the user to obtain CATLAYER properties. Be sure
           you ALWAYS call the superclass GETPROPERTY method if you have extra
           keywords!

     SYNTAX:

           theObject -> GetProperty ...

     ARGUMENTS:

         None.

     KEYWORDS:

          COLOR_OBJECT:   Use this keyword to get the contained COLORTOOL object.

          COORD_OBJECT:   Use this keyword to get the contained CATCOORD object.

          SELECTABLE:     Set to 1 if the layer is selectable, otherwise to 0.

          VISIBLE:        Set to 1 if the layer is visible, otherwise to 0.

          _REF_EXTRA:     Any keywords appropriate for the superclass GetProperty method.

(See C:\IDL\Catalyst\source\core\catlayer__define.pro)

## CATLAYER::INIT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATLAYER::INIT

     PURPOSE:

           This is the CATLAYER object class initialization method

     SYNTAX:

           Called automatically when the object is created.

     ARGUMENTS:

         parent:     The parent object reference.

     KEYWORDS:

         COLOR_OBJECT: Use this keyword to load a color object for setting up colors for data display.

         COORD_OBJECT: Use this keyword to load a coordinate object for setting up the data coordinate
                       system for data display.

         SELECTABLE:   Set this keyword to 0 to turn layer selectability OFF and to 1 to turn selectability ON.
                       Selectability is set to 1 by default.

         VISIBLE:      Set this keyword to 0 to turn layer visibilty OFF and to 1 to turn visibility ON.
                       Visibility is set to 1 by default.

         _EXTRA:       Any keywords appropriate for the superclass INIT method.

(See C:\IDL\Catalyst\source\core\catlayer__define.pro)

## CATLAYER::SELECT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATLAYER::SELECT

     PURPOSE:

           This method passes on a selection event to its SELECTABLEOBJECT children, and returns
           all possible selected objects.

     SYNTAX:

           selectedObject = theObject -> Select, x, y

     ARGUMENTS:

           X:   The X location of a point in device or window coordinates.

           Y:   The Y location of a point in device or window coordinates.

     KEYWORDS:

           SUCCESS:   Set to 1 if a selection is made. To 0 otherwise.

(See C:\IDL\Catalyst\source\core\catlayer__define.pro)

## CATLAYER::SETPROPERTY

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATLAYER::SETPROPERTY

     PURPOSE:

           This method allows the user to set the CATLAYER object's properties. Be sure
           you ALWAYS call the superclass SETPROPERTY method if you have extra keywords!

     SYNTAX:

           theObject -> SetProperty ...

     ARGUMENTS:

         None.

     KEYWORDS:

         SELECTABLE:  Set this keyword to 0 to turn layer selectability OFF and to 1 to turn selectability ON.
                      Selectability is set to 1 by default.

          VISIBLE:    Set this keyword to 0 to turn layer visibilty OFF and to 1 to turn visibility ON.

         _EXTRA:      Any keywords appropriate for the superclass SetProperty method.

(See C:\IDL\Catalyst\source\core\catlayer__define.pro)

## CATLAYER__DEFINE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATLAYER__DEFINE

     PURPOSE:

           The purpose of this routine is to implement a container object that can be used
           for layering or overlaying graphic elements in a draw widget, on an image, etc.
           Essentially, it is a means of grouping graphic elements (e.g., annotations) in
           a way that make them easy to draw and easy to turn on/off.

     AUTHORS:

            FANNING SOFTWARE CONSULTING   BURRIDGE COMPUTING
            1645 Sheely Drive             18 The Green South
            Fort Collins                  Warborough, Oxon
            CO 80526 USA                  OX10 7DN, ENGLAND
            Phone: 970-221-0438           Phone: +44 (0)1865 858279
            E-mail: davidf@dfanning.com   E-mail: davidb@burridgecomputing.co.uk

     CATEGORY:

           Objects.

     SYNTAX:

           theObject = Obj_New("CATLAYER")

     SUPERCLASSES:

           CATATOM
           CATCONTAINER IDLITCOMPONENT
           IDL_CONTAINER

     CLASS_STRUCTURE:

       class = { CATLAYER, $
                  _coords    : OBJ_NEW(), $   ; A CATCOORD object of some type.
                  _colors    : OBJ_NEW(), $   ; A COLORTOOL object for setting up color tables.
                  _visible   : 0L, $          ; A flag that indicates the layer is visible (1), or not (0).
                  _selectable: 0L, $          ; A flag that indicates if the layer will allow selection on contained objects.
                 INHERITS CATATOM $
               }

     MESSAGES:

       None.

     MODIFICATION_HISTORY:

           Written by: David W. Fanning, 18 January 2005.

(See C:\IDL\Catalyst\source\core\catlayer__define.pro)

## CATLIST

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatList

     PURPOSE:

            This is object is part of the Catalyst Library. It presents a mechanism for
            dynamically creating and retrieving lists of information of any data type.
            It is like a hash in the perl programming language. CATLISTVALUE objects
            are stored in the CATLIST.

     AUTHORS:

            FANNING SOFTWARE CONSULTING   BURRIDGE COMPUTING
            1645 Sheely Drive             18 The Green South
            Fort Collins                  Warborough, Oxon
            CO 80526 USA                  OX10 7DN, ENGLAND
            Phone: 970-221-0438           Phone: +44 (0)1865 858279
            E-mail: davidf@dfanning.com   E-mail: davidb@burridgecomputing.co.uk

     SUPERCLASSES:

           CAT_CONTAINER
           IDL_CONTAINER

     SYNTAX:

           CatListObject = Obj_New('CatList')

     CLASS_STRUCTURE:

        class = { CatList               $ ; The CatContainer object class name.
                  INHERITS CatContainer $ ; Sub-class of CatContainer
                }

     MODIFICATION_HISTORY:

           Written by: David Burridge, 12th March 2003

(See C:\IDL\Catalyst\source\core\catlist__define.pro)

## CATLIST::ADD

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatList::ADD

     PURPOSE:

            This method overrides the default ADD method to provide two possiblities:
            either child objects of class CatListValue can be added, or a name and
            value can be specified which causes the CatListValue to be created.

     SYNTAX:

            defaultsObj -> Add, name, Value=value, Success=success

     ARGUMENTS:

            NAME:    If this is a text string, a CatListValue object of this name is
                     created to add. If this is a CatListValue object it is added directly
                     to this container.

     KEYWORDS:

            VALUE:   The value to enter into the list if NAME is a string. Can be of any IDL
                     type. If NAME is specified without VALUE, VALUE will be a NULL string.

            SUCCESS: A flag indicating the success of the routine. If set, the
                     routine will fail quietly.

(See C:\IDL\Catalyst\source\core\catlist__define.pro)

## CATLIST::ADDVALUE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatList::ADDVALUE

     PURPOSE:

            This method adds child objects of class CatListValue or a name and
            value can be specified which causes the CatListValue to be created
            and added to the list.

     SYNTAX:

            defaultsObj -> AddValue, name, Value=value, Success=success

     ARGUMENTS:

            NAME:    If this is a text string, a CatListValue object of this name is
                     created to add. If this is a CatListValue object it is added directly
                     to this container.

     KEYWORDS:

            VALUE:   The value to enter into the list if NAME is a string. Can be of any IDL
                     type. If NAME is specified without VALUE, VALUE will be a NULL string.

            SUCCESS: A flag indicating the success of the routine. If set, the
                     routine will fail quietly.

(See C:\IDL\Catalyst\source\core\catlist__define.pro)

## CATLIST::CLEANUP

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatList::CLEANUP

     PURPOSE:

           This is the CatList object class destructor method.

     SYNTAX:

           Called automatically when the object is destroyed.

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\catlist__define.pro)

## CATLIST::GETVALUE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
            CatList::GetValue

     PURPOSE:

            This function method gets a named value from the container. Note that
            only one value can be returned at a time. To implement multiple Gets,
            Use the normal GET method and extract the values sequentially.

     SYNTAX:

           Value = ListObject -> GetValue (name)

     ARGUMENTS:

           NAME:     The name of the value to retrieve from the container. (Required)

     KEYWORDS:

            SUCCESS: A flag indicating the success of the routine. If set, the
                     routine will fail quietly.

(See C:\IDL\Catalyst\source\core\catlist__define.pro)

## CATLIST::INIT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatList::INIT

     PURPOSE:

           This is the CatList object class creator method.

     SYNTAX:

           Called automatically when the object is created.

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\catlist__define.pro)

## CATLISTVALUE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATLISTVALUE

     PURPOSE:

            This object is part of the Catalyst Library. It is a simple object used
            to store a named value of any data type in a CatList object. It is
            similar to a hash in the perl programming language.

            This object is designed solely to be used by the CATLIST container
            object and should not be called individually.

     AUTHORS:

            FANNING SOFTWARE CONSULTING   BURRIDGE COMPUTING
            1645 Sheely Drive             18 The Green South
            Fort Collins                  Warborough, Oxon
            CO 80526 USA                  OX10 7DN, ENGLAND
            Phone: 970-221-0438           Phone: +44 (0)1865 858279
            E-mail: davidf@dfanning.com   E-mail: davidb@burridgecomputing.co.uk

     SUPERCLASSES:

           CATCONTAINER
           IDL_CONTAINER

     SYNTAX:

           catListValueObject = Obj_New('CatListValue', parent, name, Value=value)

     ARGUMENTS:

            parent: The parent object - must be a CatList object (required)

            name:   The name of the value in the list (optional)

     KEYWORDS:

            VALUE:  The variable to be assigned as the value of the object. If
                    no value is supplied, a NULL string is used.

     CLASS_STRUCTURE:

        class = { CatListValue,      $
                  _value : PTR_NEW (),  $
                  INHERITS CatContainer $
                }

     MODIFICATION_HISTORY:

           Written by: David Burridge, 12th March 2003.

(See C:\IDL\Catalyst\source\core\catlistvalue__define.pro)

## CATLISTVALUE STRUCTURE DEFINITION

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATLISTVALUE STRUCTURE DEFINITION

     PURPOSE:

            This procedure defines the CatListValue object structure.

     SYNTAX:

            None. See syntax for INIT method

     ARGUMENTS:

            None.

     KEYWORDS:

            None.

(See C:\IDL\Catalyst\source\core\catlistvalue__define.pro)

## CATLISTVALUE::ADD

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATLISTVALUE::ADD

     PURPOSE:

            This method overrides the default ADD method to prevent child objects
            being added.

     SYNTAX:

            None.

     ARGUMENTS:

            None.

     KEYWORDS:

            SUCCESS: A flag indicating the success of the routine. If set, the
                     routine will fail quietly.

(See C:\IDL\Catalyst\source\core\catlistvalue__define.pro)

## CATLISTVALUE::CLEANUP

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATLISTVALUE::CLEANUP

     PURPOSE:

            This function method cleans up the object upon destruction.

     SYNTAX:

            OBJ_DESTROY, defaultValueObj

     ARGUMENTS:

            None.

     KEYWORDS:

            None.

(See C:\IDL\Catalyst\source\core\catlistvalue__define.pro)

## CATLISTVALUE::GETVALUE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATLISTVALUE::GETVALUE

     PURPOSE:

           This function method retrieves the data value associated with the list entry.

     SYNTAX:

           value = valueObj -> GetValue ()

     ARGUMENTS:

           None.

     KEYWORDS:

            SUCCESS: A flag indicating the success of the routine. If set, the
                     routine will fail quietly.

(See C:\IDL\Catalyst\source\core\catlistvalue__define.pro)

## CATLISTVALUE::INIT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATLISTVALUE::INIT

     PURPOSE:

            This function method initialises the object.

     SYNTAX:

            valueObj = OBJ_NEW ('CatListValue')

     ARGUMENTS:

            Parent: The parent object - must be a CatLists object (required)

            Name:   The name of the value in the list (optional)

     KEYWORDS:

            Value:  The variable to be assigned to the first value (input). If
                    no value is supplied, a NULL string is used.

(See C:\IDL\Catalyst\source\core\catlistvalue__define.pro)

## CATLISTVALUE::SETVALUE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATLISTVALUE::SETVALUE

     PURPOSE:

           This procedure method sets the data value associated with the list entry.

     SYNTAX:

           valueObj -> SetValue, listValue

     ARGUMENTS:

           ListValue: The variable to be used as the value.

     KEYWORDS:

            SUCCESS: A flag indicating the success of the routine. If set, the
                     routine will fail quietly.

(See C:\IDL\Catalyst\source\core\catlistvalue__define.pro)

## CATTOOL

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATTOOL

     PURPOSE:

           This object implements a tool object class. It contains a storage pointer for
           the data before the tool is applied. This is so the result of the tool can be
           undone later. And it contains a target field so it knows what object was the
           target of the tool. The tool applies an operation to the target object.

     AUTHORS:

            FANNING SOFTWARE CONSULTING   BURRIDGE COMPUTING
            1645 Sheely Drive             18 The Green South
            Fort Collins                  Warborough, Oxon
            CO 80526 USA                  OX10 7DN, ENGLAND
            Phone: 970-221-0438           Phone: +44 (0)1865 858279
            E-mail: davidf@dfanning.com   E-mail: davidb@burridgecomputing.co.uk

     SUPERCLASSES:

           CATATOM
           CATCONTAINER
           IDL_CONTAINER

     SYNTAX:

           toolObject = OBJ_NEW ('CATTOOL')

     CLASS_STRUCTURE:

       class = { CATTOOL,               $ ; The object class name.
                 INHERITS CATATOM,      $ ; Inherits CATATOM
                 _theCache: Ptr_New(),  $ ; The pre-tool data location.
                 _noCache: 0L           $ ; A flag that indicates the input data is not to be cached or stored.
                 _theTarget: Obj_New(), $ ; The tool target. The tool is APPLIED to the data in this object.
               }

     MODIFICATION_HISTORY:

           Written by: David Fanning, 3 April 2003.

(See C:\IDL\Catalyst\source\core\cattool__define.pro)

## CATTOOL::CACHE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATTOOL::CACHE

     PURPOSE:

           This method enables the CATTOOL storage pointer to be loaded with the pre-tool data.

     SYNTAX:

           toolObject -> Cache, theData

     ARGUMENTS:

           theData:    The data to be cached or saved.

     KEYWORDS:

           NO_COPY:  Set this keyword to transfer the data to the cache pointer
                     without making a copy.

(See C:\IDL\Catalyst\source\core\cattool__define.pro)

## CATTOOL::CLEANUP

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATTOOL::CLEANUP

     PURPOSE:

           This is the CATTOOL object class destructor method.

     SYNTAX:

           Called automatically when the object is destroyed thus:

               OBJ_DESTROY, toolObject

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\cattool__define.pro)

## CATTOOL::GETPROPERTY

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATTOOL::GETPROPERTY

     PURPOSE:

           This method is used to get properties of the CATTOOL object

     SYNTAX:

           toolObject -> GETPROPERTY, CACHED_DATA=data

     ARGUMENTS:

           None.

     KEYWORDS:

           CACHED_DATA:   The data cached in the storage pointer.

           NOCACHE:       The current setting of the noCache flag.

           TARGET:        A reference to the target object.

           _REF_EXTRA:    Any keyword appropriate for the  superclass GETPROPERTY method.

(See C:\IDL\Catalyst\source\core\cattool__define.pro)

## CATTOOL::INIT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATTOOL::INIT

     PURPOSE:

           This method is called upon object creation.

     SYNTAX:

           Called automatically when the object is created thus:

               toolObject = OBJ_NEW ('CATTOOL')

     ARGUMENTS:

           None.

     KEYWORDS:

         NOCACHE:   Set this keyword to indicate that the input data should not be cached
                    or stored in the storage location.

         TARGET:    Set this keyword to an object reference for the target object. The tool is
                    applied to the data in this target.

         _EXTRA:    Any keyword appropriate for the INIT method of the superclass object.

(See C:\IDL\Catalyst\source\core\cattool__define.pro)

## CATTOOL::SETPROPERTY

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATTOOL::SETPROPERTY

     PURPOSE:

           This method enables the setting of the CATTOOL object class
           properties.

     SYNTAX:

           toolObject -> SETPROPERTY, CACHED_DATA=cached_data

     ARGUMENTS:

           None.

     KEYWORDS:

           CACHED_DATA:   The data stored in the cache.

           NOCACHE:       Set this keyword to indicate that the input data should not be cached
                          or stored in the storage location.

           NO_COPY:       Set this keyword to transfer the data to the cache without making a copy.

           TARGET:        Set this keyword to an object reference for the target object. The tool is
                          applied to the data in this target.

          _EXTRA:         Any keywords appropriate for the superclass SetProperty method.

(See C:\IDL\Catalyst\source\core\cattool__define.pro)

## CATTOOLLIST

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatToolList

     PURPOSE:

            This is object is part of the Catalyst Library. It presents a mechanism for
            creating and managing lists of tools (objects that operate on others).

     AUTHORS:

            FANNING SOFTWARE CONSULTING   BURRIDGE COMPUTING
            1645 Sheely Drive             18 The Green South
            Fort Collins                  Warborough, Oxon
            CO 80526 USA                  OX10 7DN, ENGLAND
            Phone: 970-221-0438           Phone: +44 (0)1865 858279
            E-mail: davidf@dfanning.com   E-mail: davidb@burridgecomputing.co.uk

     SUPERCLASSES:

           CATATOM
           CATCONTAINER
           IDL_CONTAINER

     SYNTAX:

           ToolListObject = Obj_New('CatToolList')

     CLASS_STRUCTURE:

           struct = {CatToolList, _current:0L, _limit:0L, INHERITS CatAtom}

     MODIFICATION_HISTORY:

           Written by: David Burridge, 29th April 2003

(See C:\IDL\Catalyst\source\core\cattoollist__define.pro)

## CATTOOLLIST::ADD

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatToolList::Add

     PURPOSE:

            This method overrides the default ADD method to ensure that objects added
            to this list are ToolAtom objects. The new object becomes the "current"
            tool.

            Note that if the tool is not added to the end of the list (i.e. previous
            operation was an UNDO), the remaining tools will be removed.

            Since the validity of the items in the list depends on it being sequential,
            addition of tools within the list (using the POSITION keyword) causes the
            list to be truncated.

            Note that the ADD method of the IDL_CONTAINER object is used.
            This is to bypass all memory management of CatToolList objects. These just
            need to be added to simple containers.

     SYNTAX:

            toolListObj -> Add, tool

     ARGUMENTS:

            TOOL:  The tool to be added. This must be subclasses from CATTOOL.

     KEYWORDS:

            POSITION: The position that the tool should be added to the list. If this
                      keyword is set, the list will be truncated at the new tool.

(See C:\IDL\Catalyst\source\core\cattoollist__define.pro)

## CATTOOLLIST::CLEANUP

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatToolList::CLEANUP

     PURPOSE:

           This is the CatToolList object class destructor method.

     SYNTAX:

           Called automatically when the object is destroyed.

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\cattoollist__define.pro)

## CATTOOLLIST::GET

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatToolList::Get

     PURPOSE:

            This method overrides the default GET method so that a default GET (with
            no POSITION or ALL keyword) gets the CURRENT tool (rather than the first).

     SYNTAX:

            currentTool = toolListObj -> Get ()

     ARGUMENTS:

            None.

     KEYWORDS:

            POSITION: The position that the tool should be added to the list. If this
                      keyword is set, the list will be truncated at the new tool.

            ALL:      Set this keyword to get all of the tools from the list.

(See C:\IDL\Catalyst\source\core\cattoollist__define.pro)

## CATTOOLLIST::GETPROPERTY

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatToolList::GetProperty

     PURPOSE:

            This method exists so that properties of the object can be retrieved.

     SYNTAX:

            toolListObj -> Add, tool

     ARGUMENTS:

            None.

     KEYWORDS:

            CURRENT_INDEX: The current index into the tool list array.

            CURRENT_TOOL:  The current tool in the tool list array.

            LIMIT:         The current limit for the number of tools in this tool list.

            _REF_EXTRA:    Any extra keywords for superclass GETPROPERTY methods.

(See C:\IDL\Catalyst\source\core\cattoollist__define.pro)

## CATTOOLLIST::INIT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatToolList::INIT

     PURPOSE:

           This is the CatToolList object class creator method.

     SYNTAX:

           Called automatically when the object is created.

     ARGUMENTS:

           PARENT: The parent object that will contain the tool list.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\cattoollist__define.pro)

## CATTOOLLIST::REDO

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatToolList::Redo

     PURPOSE:

            This method includes a previously "undone" tool back into the tool list.
     SYNTAX:

            toolListObj -> Redo

     ARGUMENTS:

            None.

     KEYWORDS:

            ALL: Set this keyword to REDO all undone items in the list, starting from the current item.

(See C:\IDL\Catalyst\source\core\cattoollist__define.pro)

## CATTOOLLIST::REMOVE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatToolList::Remove

     PURPOSE:

            This method overrides the default REMOVE method. The last object in the list becomes
            the "current" tool.

            Note that the REMOVE method of the IDL_CONTAINER object is used.
            This is to bypass all memory management of CatToolList objects. These just
            need to be removed from simple containers.

     SYNTAX:

            toolListObj -> Remove, Position=pos

     ARGUMENTS:

            None.

     KEYWORDS:

            POSITION: The position of the tool to remove from the list.

(See C:\IDL\Catalyst\source\core\cattoollist__define.pro)

## CATTOOLLIST::SETPROPERTY

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatToolList::SetProperty

     PURPOSE:

            This method exists so that properties of the object can be set.

     SYNTAX:

            toolListObj -> SetProperty, Limit=10

     ARGUMENTS:

            None.

     KEYWORDS:

            LIMIT:         The current limit for the number of tools in this tool list.

            _F_EXTRA:      Any extra keywords for superclass SETPROPERTY methods.

(See C:\IDL\Catalyst\source\core\cattoollist__define.pro)

## CATTOOLLIST::UNDO

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CatToolList::Undo

     PURPOSE:

            This method UNDOes a tool from tool list.
     SYNTAX:

            toolListObj -> Undo

     ARGUMENTS:

            None.

     KEYWORDS:

            ALL: Set this keyword to UNDO all items in the list, starting from the current item.

(See C:\IDL\Catalyst\source\core\cattoollist__define.pro)

## COLORTOOL

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COLORTOOL

     PURPOSE:

           The purpose of the ColorTool object is to allow the user to construct and manage
           a color table. Standard color tables can be loaded, drawing colors can be
           specified by name and value, etc. Calling the DRAW method on a Colortool object causes
           that object's color table to be loaded in IDL's hardware color table. A fundamental
           principle of the Catalyst Library is that every piece of data should have associated
           with it a color table by which it can be displayed, and a coordinate system which will
           establish a data coordinate system for the data. The COLORTOOL performs the former function.
           It can be set and retrieved from data objects by using the COLOR_OBJECT keyword in
           SetProperty and GetProperty methods. ColorTool objects are often inherited by objects.
           For example, if you add a data object to a draw widget, the data object is likely to
           inherit the ColorTool object of the draw widget. This makes it easy to establish a
           consistent color scheme for all objects being displayed in a single draw widget.

     AUTHOR:

           FANNING SOFTWARE CONSULTING       BURRIDGE COMPUTING
           1645 Sheely Drive                 18 The Green South
           Fort Collins, CO 80526 USA        Warborough, Oxon, OX10 7DN England
           Phone: 970-221-0438               Phone: +44 (0) 1865 858 279
           E-mail: davidf@dfanning.com       davidb@burridgecomputing.co.uk

     SUPERCLASSES:

           CATATOM
           CATCONTAINER
           IDL_CONTAINER

     SYNTAX:

           colorObject = Obj_New('COLORTOOL')

     CLASS_STRUCTURE:

       class  = { COLORTOOL, $               ; The COLORTOOL object definition.
                  INHERITS CATATOM, $        ; Inherits the CATATOM object class.
                  _brewer: 0B, $             ; Flag that indicates a brewer color table.
                  _r: BytArr(256), $         ; The red color table vector.
                  _g: BytArr(256), $         ; The green color table vector.
                  _b: BytArr(256),  $        ; The blue color table vector.
                  _colornames: Ptr_New(), $  ; The names of "known" colors.
                  _rvalue: Ptr_New(), $      ; The red color values associated with color names.
                  _gvalue: Ptr_New(), $      ; The red color values associated with color names.
                  _bvalue: Ptr_New(), $      ; The red color values associated with color names.
                  _colorfile: "", $          ; The name of the color table file to read.
                  _ncolors: 0L, $            ; The number of colors in standard color table.
                  _bottom: 0L, $             ; The starting index of the standard color table.
                  _scTLB: Obj_New(), $       ; The SHOWCOLORS tlb object.
                  _selTLB: Obj_New(), $      ; The SELECTCOLORS tlb object.
                  _xcTLB: Obj_New(), $       ; The XCOLORS tlb object.
                  _xc_registerName: "", $    ; The name with which the XCOLORS dialog is registered.
                  _ctindex: 0L, $            ; The current color table index.
                  _r_old: BytArr(256), $     ; The old red color table vector.
                  _g_old: BytArr(256), $     ; The old green color table vector.
                  _b_old: BytArr(256) $      ; The old blue color table vector.
                 }

     MESSAGES:

           COLORTOOL_TABLECHANGE: A message with this title is sent when color table vectors are
                                  changed in the object. In additon to the message, a DATA keyword is
                                  used to pass an anonymous structure containing the current R, G, and
                                  B color table vectors, along with the BOTTOM index for loading the vectors.

           COLORTOOL_SETPROPERTY: A message with this title is sent any time the SetProperty method is
                                  called. No data is sent. Message recipients can call the GetPropery
                                  method on the message SENDER to obtain appropriate information.

     MODIFICATION_HISTORY:

           Written by: David W. Fanning, 13 March 2003.
           Added system color names to GETCOLOR method. DWF. 23 Jan 2004.
           Modified the way ShowColors method works if a ShowColors window is on the display. Now
              current colors are always displayed when ShowColors is called. DWF, 26 Jan 2004.
           Added Stretch method to object. DWF, 26 Jan 2004.
           Added support for 8-bit displays to GETCOLOR method. DWF. 25 Aug 2004.
           Added support for BREWER color tables. 25 June 2008. DWF.
           Added PICKCOLORNAME method. 7 July 2008. DWF.
           Additional changes to BREWER support. 25 October 2008. DWF.

(See C:\IDL\Catalyst\source\core\colortool__define.pro)

## COLORTOOL::ADDNAMEDCOLOR

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COLORTOOL::AddNamedColor

     PURPOSE:

           This method adds a color to the internal list of named colors.

     SYNTAX:

           colorObject -> AddNamedColor, color, colorName
     or
           colorObject -> AddNamedColor, r, g, b, colorName

     ARGUMENTS:

           color:     A long integer (or integer array) represeting a 24-bit color.

           colorname: The name of the color. The color *must* have a name!

           r:         The red component (or array of components) of the color.

           g:         The green component (or array of components) of the color.

           b:         The blue component (or array of components) of the color.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\colortool__define.pro)

## COLORTOOL::CLEANUP

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COLORTOOL::CLEANUP

     PURPOSE:

           This is the COLORTOOL object class destructor method.

     SYNTAX:

           Called automatically when the object is destroyed.

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\colortool__define.pro)

## COLORTOOL::COLOR24TO8

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COLORTOOL::COLOR24to8

     PURPOSE:

           This method converts a 24-bit integer value representing a color to a
           three-element array representing the equivalent RGB values of the 24-bit integer.
           In other words, it is the inverse operation to Color8to24.

     SYNTAX:

           rgbcolor = colorObject -> Color24to8(color24)

     ARGUMENTS:

           color:     A 24-bit long integer value representing a 24-bit color.

     RETURN VALUE:

           rgbcolor:  A three-element array, representing the red, green, and blue components
                      of the 24-bit starting value. Or, if an array is passed in, a 3-by-n array
                      of color values.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\colortool__define.pro)

## COLORTOOL::COLOR8TO24

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COLORTOOL::COLOR8to24

     PURPOSE:

           This method converts a color triple to an equivalent 24-bit integer value.

     SYNTAX:

           color24 = colorObject -> Color8to24(color)

     ARGUMENTS:

           color:    A [red, green, blue] color triple that describes a particular color.
                     The triple can be either a row or column vector of 3 elements or it
                     can be an N-by-3 array of color triples.

     RETURN VALUE:

           color24:  A 24-bit value, representing the red, green, and blue components
                     of the 8-bit starting values.
     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\colortool__define.pro)

## COLORTOOL::CONGRID

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COLORTOOL::CONGRID

     PURPOSE:

           This method is a slight variation of IDL's Congrid routine. Specifically,
           it checks for a divide by zero that can occur occasionally in XCOLORS.

     SYNTAX:

           newArray = colorObject -> Congrid(array, x, y, z)

     ARGUMENTS:

           array:  A 1, 2, or 3 dimensional array to resize.
                   Data Type : Any type except string or structure.

           x:      The new X dimension of the resized array.
                   Data Type : Int or Long (greater than or equal to 2).

           y:      The new Y dimension of the resized array. If the original
                   array has only 1 dimension then y is ignored. If the original
                   array has 2 or 3 dimensions then y MUST be present.

           z:      The new Z dimension of the resized array. If the original
                   array has only 1 or 2 dimensions then z is ignored. If the
                   original array has 3 dimensions then z MUST be present.

     KEYWORDS:

           CENTER: If this keyword is set, shift the interpolation so that points
                   in the input and output arrays are assumed to lie at the midpoint
                   of their coordinates rather than at their lower-left corner.

           CUBIC:  If specified and non-zero, "Cubic convolution"
                   interpolation is used.  This is a more
                   accurate, but more time-consuming, form of interpolation.
                   CUBIC has no effect when used with 3 dimensional arrays.
                   If this parameter is negative and non-zero, it specifies the
                   value of the cubic interpolation parameter as described
                   in the INTERPOLATE function.  Valid ranges are -1 <= Cubic < 0.
                   Positive non-zero values of CUBIC (e.g. specifying /CUBIC)
                   produce the default value of the interpolation parameter
                   which is -1.0.

           INTERP: If set, causes linear interpolation to be used.
                   Otherwise, the nearest-neighbor method is used.

           MINUS_ONE: If set, will prevent CONGRID from extrapolating one row or
                   column beyond the bounds of the input array.   For example,
                   If the input array has the dimensions (i, j) and the
                   output array has the dimensions (x, y), then by
                   default the array is resampled by a factor of (i/x)
                   in the X direction and (j/y) in the Y direction.
                   If MINUS_ONE is present (AND IS NON-ZERO) then the array
                   will be resampled by the factors (i-1)/(x-1) and (j-1)/(y-1).

(See C:\IDL\Catalyst\source\core\colortool__define.pro)

## COLORTOOL::DRAW

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COLORTOOL::DRAW

     PURPOSE:

           This method loads the color table vectors in the hardware color table.

     SYNTAX:

           colorObject -> Draw

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\colortool__define.pro)

## COLORTOOL::EVENTHANDLER

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COLORTOOL::EVENTHANDLER

     PURPOSE:

           An event handler method to handle widget events from the various graphical user interfaces
           associated with the ColorTool Object.

     SYNTAX:

           Typically called from the EVENTDISPATCHER utility routine. All event objects are named,
           and the CASE statement branches on the object's name.

     ARGUMENTS:

           Event:  The event structure from a widget event.

           Object: The object reference of the widget object that generated the event.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\colortool__define.pro)

## COLORTOOL::GETCOLOR

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COLORTOOL::GETCOLOR

     PURPOSE:

           The purpose of this method is to obtain a drawing color
           by name and in a device-decomposition independent way. To
           see a list of color names available, type:

             colorNames = colorObject -> GetColor(/Names) & Print, colorNames

     SYNTAX:

          result = colorObject -> GetColor(theColor, colorIndex)

     EXAMPLE:

          axisColor = colorObject -> GetColor("Green", !D.Table_Size-2)
          backColor = colorObject -> GetColor("Charcoal", !D.Table_Size-3)
          dataColor = colorObject -> GetColor("Yellow", !D.Table_Size-4)
          Plot, Findgen(11), Color=axisColor, Background=backColor, /NoData
          OPlot, Findgen(11), Color=dataColor

     ARGUMENTS:

           theColor: A string with the "name" of the color. To see a list
               of the color names available set the NAMES keyword. This may
               also be a vector of color names. Colors available are these:

                    Almond   Antique White      Aquamarine           Beige          Bisque           Black
                      Blue     Blue Violet           Brown       Burlywood        Charcoal      Chartreuse
                 Chocolate           Coral        Cornsilk            Cyan  Dark Goldenrod       Dark Gray
                Dark Green      Dark Khaki     Dark Orchid     Dark Salmon       Deep Pink     Dodger Blue
                 Firebrick    Forest Green            Gold       Goldenrod            Gray           Green
              Green Yellow        Honeydew        Hot Pink      Indian Red           Ivory           Khaki
                  Lavender      Lawn Green     Light Coral      Light Cyan      Light Gray    Light Salmon
              Light Yellow      Lime Green           Linen         Magenta          Maroon     Medium Gray
             Medium Orchid        Moccasin            Navy           Olive      Olive Drab          Orange
                Orange Red          Orchid  Pale Goldenrod      Pale Green          Papaya            Peru
                      Pink            Plum     Powder Blue          Purple             Red            Rose
                Rosy Brown      Royal Blue    Saddle Brown          Salmon     Sandy Brown       Sea Green
                  Seashell          Sienna        Sky Blue      Slate Gray            Snow    Spring Green
                Steel Blue             Tan         Thistle          Tomato       Turquoise          Violet
                Violet Red           Wheat           White          Yellow

               Also, these system color names are available in IDL 5.6 and higher:

                  Frame, Text, Active, Shadow, Highlight, Edge, Selected, Face.

               The color WHITE is used if this parameter is absent or a color name is mis-spelled. To see a list
               of the color names available in the program, type this:

                  Print, self -> GetColor(/Names), Format='(6A15)'

           theColorIndex: The color table index (or vector of indices the same length
               as the color name vector) where the specified color is loaded. The color table
               index parameter should always be used if you wish to obtain a color value in a
               color-decomposition-independent way in your code. See the NORMAL CALLING
               SEQUENCE for details. If theColor is a vector, and theColorIndex is a scalar,
               then the colors will be loaded starting at theColorIndex.

     RETURN VALUE:

           The value that is returned by this method depends upon the keywords
           used to call it and on the version of IDL you are using. In general,
           the return value will be either a color index number where the specified
           color is loaded by the program, or a 24-bit color value that can be
           decomposed into the specified color on true-color systems. (Or a vector
           of such numbers.)

           If you are running IDL 5.2 or higher, the program will determine which
           return value to use, based on the color decomposition state at the time
           the program is called. If you are running a version of IDL before IDL 5.2,
           then the program will return the color index number. This behavior can
           be overruled in all versions of IDL by setting the DECOMPOSED keyword.
           If this keyword is 0, the program always returns a color index number. If
           the keyword is 1, the program always returns a 24-bit color value.

           If the TRIPLE keyword is set, the program always returns the color triple,
           no matter what the current decomposition state or the value of the DECOMPOSED
           keyword. Normally, the color triple is returned as a 1 by 3 column vector.
           This is appropriate for loading into a color index with TVLCT:

              IDL> TVLCT, FSC_Color('Yellow', /Triple), !P.Color

           But sometimes (e.g, in object graphics applications) you want the color
           returned as a row vector. In this case, you should set the ROW keyword
           as well as the TRIPLE keyword:

              viewobj= Obj_New('IDLgrView', Color=FSC_Color('charcoal', /Triple, /Row))

           If the ALLCOLORS keyword is used, then instead of a single value, modified
           as described above, then all the color values are returned in an array. In
           other words, the return value will be either an NCOLORS-element vector of color
           table index numbers, an NCOLORS-element vector of 24-bit color values, or
           an NCOLORS-by-3 array of color triples.

           If the NAMES keyword is set, the program returns a vector of
           color names known to the program.

     INPUT KEYWORD PARAMETERS:

           ALLCOLORS:  Set this keyword to return indices, or 24-bit values, or color
                       triples, for all the known colors, instead of for a single color.

           DECOMPOSED: Set this keyword to 0 or 1 to force the return value to be
                       a color table index or a 24-bit color value, respectively.

           NAMES:      If this keyword is set, the return value of the function is
                       a ncolors-element string array containing the names of the colors.
                       These names would be appropriate, for example, in building
                       a list widget with the names of the colors. If the NAMES
                       keyword is set, the COLOR and INDEX parameters are ignored.

                       listID = Widget_List(baseID, Value=GetColor(/Names), YSize=16)

           ROW:        If this keyword is set, the return value of the function when the TRIPLE
                       keyword is set is returned as a row vector, rather than as the default
                       column vector. This is required, for example, when you are trying to
                       use the return value to set the color for object graphics objects. This
                       keyword is completely ignored, except when used in combination with the
                       TRIPLE keyword.

           TRIPLE:     Setting this keyword will force the return value of the function to
                       *always* be a color triple, regardless of color decomposition state or
                       visual depth of the machine. The value will be a three-element column
                       vector unless the ROW keyword is also set.

     OUTPUT KEYWORD PARAMETERS:

           CANCEL:     This keyword is always set to 0, unless that SELECTCOLOR keyword is used.
                       Then it will correspond to the value of the CANCEL output keyword in PICKCOLORNAME.

           NCOLORS:    The number of colors recognized by the program. It will be 88 by default.

(See C:\IDL\Catalyst\source\core\colortool__define.pro)

## COLORTOOL::GETPROPERTY

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COLORTOOL::GETPROPERTY

     PURPOSE:

           This method obtains properties from the object.

     SYNTAX:

           colorObject -> GetProperty, RED=r, GREEN=g, BLUE=b
           TVLCT, r, g, b

     ARGUMENTS:

           None.

     KEYWORDS:

           BLUE:       The blue color vector.

           BREWER:      Is set, using Brewer Color Tables.

           COLORPALETTE:  A n-by-3 array containing the current color table vectors

           CTINDEX:    The current color table index number.

           GREEN:      The green color vector.

           NCOLORS:    The number of colors.

           RED:        The red color vector.

           _REF_EXTRA: Any keyword appropriate for the GETPROPERTY method of the superclass object.

(See C:\IDL\Catalyst\source\core\colortool__define.pro)

## COLORTOOL::GUI_UPDATE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COLORTOOL::GUI_UPDATE

     PURPOSE:

           This method updates the colors in any COLORTOOL GUI that happens to
           be open on the display.

     SYNTAX:

           colorObject -> GUI_Update

     ARGUMENTS:

           INFO:  The information structure used by the XCOLORS method.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\colortool__define.pro)

## COLORTOOL::INIT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COLORTOOL::INIT

     PURPOSE:

           This method initiates the COLORTOOL object.

     SYNTAX:

           colorObject Obj_New('ColorTool')

     ARGUMENTS:

           colorIndex: The color table index number to load. A number between 0 and 40. If
                       missing, 0 is assumed.

     KEYWORDS:

           BREWER:       Set this keyword to load the Brewer color tables.

                         This program will look first in the $IDL_DIR/resource/colors directory for
                         the color table file, and failing to find it there will look in the same
                         directory that the source code of this program is located, then in the current
                         directory. Finally, if it still can't find the file, it will ask you to locate it.
                         If you can't find it, the program will simply return without loading a color table.

                         NOTE: YOU WILL HAVE TO DOWNLOAD THE FSC_BREWER.TBL FILE FROM THE COYOTE LIBRARY AND
                         PLACE IT IN ONE OF THE THREE PLACES OUTLINED ABOVE:

                         http://www.dfanning.com/programs/fsc_brewer.tbl

           BOTTOM:       The starting location where the color table is loaded.

           COLORFILE:    The fully qualified file name of the file containing color tables. By default,
                         colorFile = Filepath(SubDirectory=['resource','colors'], 'colors1.tbl')

           COLORPALETTE: An n-by-3 byte array containing the color palette to load.

           NCOLORS:      The number of colors in the color palette.

(See C:\IDL\Catalyst\source\core\colortool__define.pro)

## COLORTOOL::LOADCOLOR

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COLORTOOL::LOADCOLOR

     PURPOSE:

           This method loads a color value or values into the color table vectors.
           All color vectors must be the same size.

     SYNTAX:

           colorObject -> LoadColor, colorName

           or,

           colorObject -> LoadColor, r, g, b

     ARGUMENTS:

           colorName: A scalar or vector of color names.

           Or,

           r:         A scalar or vector of red values.

           g:         A scalar or vector of green values.

           b:         A scalar or vector of blue values.

     KEYWORDS:

           DRAW:  If this keyword is set, the DRAW method is called after the colors
                  have been loaded.

           INDEX: If a scalar, the starting index for loading the specified color vectors.
                  IF a vector, the indices of the specified colors. Must be the same size
                  as the color vectors. If absent, then set to !D.Table_Size - (N_Elements(r) + 1).

     EXAMPLE:

           colorObject -> LoadColor, 'red', Index=10
           colorObject -> LoadColor, ['red','yellow'], Index=20
           colorObject -> LoadColor, ['red','yellow'], Index=[30,35]
           colorObject -> ShowColors

           colorObject -> LoadColor, 255, 255, 0, Index=10
           colorObject -> LoadColor, [255, 0], [255,255], [0,0], Index=20
           colorObject -> LoadColor, [255, 0], [255,255], [0,0], Index=[30,35]
           colorObject -> ShowColors

(See C:\IDL\Catalyst\source\core\colortool__define.pro)

## COLORTOOL::LOADCT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COLORTOOL::LOADCT

     PURPOSE:

           This method loads a pre-determined color table.

     SYNTAX:

           colorObject -> LoadCT, colorIndex

     ARGUMENTS:

           colorIndex: The color table index number to load. If absent, 0 is assumed

     KEYWORDS:

           DRAW:       If this keyword is set, the DRAW method is called after the colors
                       have been loaded.

(See C:\IDL\Catalyst\source\core\colortool__define.pro)

## COLORTOOL::PICKCOLORNAME

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COLORTOOL::PICKCOLORNAME

     PURPOSE:

           This method allows the user to select a color name interactively.

     SYNTAX:

           theColor = colorObject -> PickColorName()

     ARGUMENTS:

           defaultColor: The name of the default color to be set to the "current color"
                         If not supplied, the color "white" is used.

     RETURN_VALUE:

           theColor:     The name of the selected color.

     KEYWORDS:

           GROUP_LEADER: The group leader object or widget reference. The group leader MUST
                         be passed to make this a modal widget. If absent, the program will
                         try to block the IDL command line. But this is not guaranteed and
                         is not recommended.

           INDEX:        If this keyword is set to a color index, the selected color will
                         be loaded at that location in the internal color table.

           TITLE:        The title of the pop-up dialog widget.

(See C:\IDL\Catalyst\source\core\colortool__define.pro)

## COLORTOOL::RESET

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COLORTOOL::RESET

     PURPOSE:

           This method allows resets the current color vectors to the old color vectors.

     SYNTAX:

           colorObject -> Reset

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\colortool__define.pro)

## COLORTOOL::REVERSE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COLORTOOL::REVERSE

     PURPOSE:

           This method allows the current color vectors to be reversed.

     SYNTAX:

           colorObject -> Reverse

     ARGUMENTS:

           None.

     KEYWORDS:

           DRAW:  If this keyword is set, the DRAW method is called after the colors have been loaded.

(See C:\IDL\Catalyst\source\core\colortool__define.pro)

## COLORTOOL::SELECTCOLOR

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COLORTOOL::SELECTCOLOR

     PURPOSE:

           This method allows the user to select a color interactively.

     SYNTAX:

           theColor = colorObject -> SelectColor()

     ARGUMENTS:

           defaultColor: The name of the default color to be set to the "current color",
                         or the RGB value (three-element array or 24-bit value) of the
                         default color. If not supplied, the color "white" is used.

     RETURN_VALUE:

           theColor:     A three-element array, representing the RGB values of the selected color.

     KEYWORDS:

           GROUP_LEADER: The group leader object or widget reference. The group leader MUST
                         be passed to make this a modal widget. If absent, the program will
                         try to block the IDL command line. But this is not guaranteed and
                         is not recommended.

           INDEX:        If this keyword is set to a color index, the selected color will
                         be loaded at that location in the internal color table.

           TITLE:        The title of the pop-up dialog widget.

(See C:\IDL\Catalyst\source\core\colortool__define.pro)

## COLORTOOL::SETPROPERTY

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COLORTOOL::SETPROPERTY

     PURPOSE:

           This method allows properties of the object to be set.

     SYNTAX:

           TVLCT, r, g, b, /GET
           colorObject -> SetProperty, RED=r, GREEN=g, BLUE=b

     ARGUMENTS:

           None.

     KEYWORDS:

           BLUE:       The blue color vector.

           BREWER:     Use the brewer color tables.

           BOTTOM:     The bottom color index.

           COLORFILE:  The fully-qualified name of a color table file to open and display.

           COLORPALETTE:  A n-by-3 array containing the current color table vectors

           GREEN:      The green color vector.

           INDEX:      The color table index number.

           NCOLORS:    The number of colors in the color table.

           RED:        The red color vector.

           _EXTRA:     Any keyword appropriate for the SETPROPERTY method of the CATATOM object.

(See C:\IDL\Catalyst\source\core\colortool__define.pro)

## COLORTOOL::SHOWCOLORS

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COLORTOOL::SHOWCOLORS

     PURPOSE:

           The purpose of this program is to allow the user to see the colors currently
           loaded in the color table vectors. A window with the current colors will open
           on the display.

     SYNTAX:

           colorObject -> ShowColors

     ARGUMENTS:

           None.

     KEYWORDS:

           TITLE: The title of the window.

(See C:\IDL\Catalyst\source\core\colortool__define.pro)

## COLORTOOL::STRETCH

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COLORTOOL::STRETCH

     PURPOSE:

           This method stretches the current colortable between minValue and maxValue.

     SYNTAX:

           colorObject -> Stretch, minValue, maxValue

     ARGUMENTS:

           minValue:    The minimum value of the stretch. 0 > minValue < maxValue < 256 .

           maxValue:    The maximum value of the stretch. 0 > minValue > maxValue < 256.

     KEYWORDS:

           DRAW:       If this keyword is set, the DRAW method is called after the colors have been loaded.

(See C:\IDL\Catalyst\source\core\colortool__define.pro)

## COLORTOOL::XCOLORS

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COLORTOOL::XCOLORS

     PURPOSE:

           The purpose of this method is to interactively change color tables.

     SYNTAX:

           colorObject -> XColors

     ARGUMENTS:

           None.

     KEYWORDS:

           BREWER:        Set this keyword if you wish to use the Brewer Colors, as
                          implemented by Mike Galloy in the file brewer.tbl, and implemented
                          here as fsc_brewer.tbl. See these references:

                          Brewer Colors: http://www.personal.psu.edu/cab38/ColorBrewer/ColorBrewer_intro.html
                          Mike Galloy Implementation: http://michaelgalloy.com/2007/10/30/colorbrewer.html

                          This program will look first in the $IDL_DIR/resource/colors directory for
                          the color table file, and failing to find it there will look in the same
                          directory that the source code of this program is located, then in your IDL path.
                          Finally, if it still can't find the file, it will ask you to locate it.
                          If you can't find it, the program will simply return without loading a color table.

                          NOTE: YOU WILL HAVE TO DOWNLOAD THE FSC_BREWER.TBL FILE FROM THE COYOTE LIBRARY AND
                          PLACE IT IN ONE OF THE THREE PLACES OUTLINED ABOVE:

                          http://www.dfanning.com/programs/fsc_brewer.tbl

           DRAG: Set this keyword if you want colors loaded as you drag
              the sliders. Default is to update colors only when you release
              the sliders. Applies only to UNIX computers.

           GROUP_LEADER: The group leader for this program. When the group
              leader is destroyed, this program will be destroyed.

           MODAL: Set this keyword (along with the GROUP_LEADER keyword) to
              make the XCOLORS dialog a modal widget dialog. Note that NO
              other events can occur until the XCOLORS program is destroyed
              when in modal mode.

           TITLE: This is the window title. It is "Load Color Tables" by
              default.

           XOFFSET: This is the X offset of the program on the display. The
              program will be placed approximately in the middle of the display
              by default.

           YOFFSET: This is the Y offset of the program on the display. The
              program will be placed approximately in the middle of the display
              by default.

(See C:\IDL\Catalyst\source\core\colortool__define.pro)

## COLORTOOL::XCOLORS_UPDATE

[Previous Routine] [List of Routines]

     NAME:
           COLORTOOL::XCOLORS_UPDATE

     PURPOSE:

           This method updates the color tables for the XCOLORS method.

     SYNTAX:

           Called from the EVENT_HANDLER method when events occur in the XCOLORS method interface.

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\core\colortool__define.pro)