# Catalyst Source-Interactions 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:12 2008.

# List of Routines

- ANNOTATEINTERACTION::ALIGNGUI, EVENT
- ANNOTATEINTERACTION::ALIGN_EVENTS
- ANNOTATEINTERACTION::BUILDMODEMENU
- ANNOTATEINTERACTION::BUILDMULTISELECTMENU
- ANNOTATEINTERACTION::CLEANUP
- ANNOTATEINTERACTION::CONTROLPANEL
- ANNOTATEINTERACTION::DISTRIBUTEGUI, EVENT
- ANNOTATEINTERACTION::DISTRIBUTE_EVENTS
- ANNOTATEINTERACTION::DRAW
- ANNOTATEINTERACTION::EVENT_HANDLER
- ANNOTATEINTERACTION::GETPROPERTY
- ANNOTATEINTERACTION::INIT
- ANNOTATEINTERACTION::RESTOREDISPLAY
- ANNOTATEINTERACTION::SETDISPLAY
- ANNOTATEINTERACTION::SETPROPERTY
- ANNOTATEINTERACTION__DEFINE
- INTERACTION::ADD
- INTERACTION::CLEANUP
- INTERACTION::CLEARABANDONEDOBJECTS
- INTERACTION::DRAW
- INTERACTION::EVENT_HANDLER
- INTERACTION::GETPROPERTY
- INTERACTION::INIT
- INTERACTION::MESSAGEHANDLER
- INTERACTION::NEEDDIALOG
- INTERACTION::REFRESHPIXMAP
- INTERACTION::RESTOREDISPLAY
- INTERACTION::SENDEVENT
- INTERACTION::SETDISPLAY
- INTERACTION::SETPROPERTY
- INTERACTION__DEFINE
- SELECTINTERACTION::ADD
- SELECTINTERACTION::CLEANUP
- SELECTINTERACTION::DRAW
- SELECTINTERACTION::EVENT_HANDLER
- SELECTINTERACTION::GETPROPERTY
- SELECTINTERACTION::INIT
- SELECTINTERACTION::MESSAGEHANDLER
- SELECTINTERACTION::NEEDDIALOG
- SELECTINTERACTION::REFRESHPIXMAP
- SELECTINTERACTION::RESTOREDISPLAY
- SELECTINTERACTION::SENDEVENT
- SELECTINTERACTION::SETDISPLAY
- SELECTINTERACTION::SETPROPERTY
- SELECTINTERACTION__DEFINE

# Routine Descriptions

## ANNOTATEINTERACTION::ALIGNGUI, EVENT

[Next Routine] [List of Routines]

     NAME:
           ANNOTATEINTERACTION::ALIGNGUI, event

     PURPOSE:

           This method builds a modal dialog for obtaining user input for
           how to align selected items.

     SYNTAX:

           theObject -> AlignGUI, event

     ARGUMENTS:

           event:    The event structure.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\interactions\annotateinteraction__define.pro)

## ANNOTATEINTERACTION::ALIGN_EVENTS

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

     NAME:
           ANNOTATEINTERACTION::ALIGN_EVENTS

     PURPOSE:

           This event handling method for the ALIGNGUI widget creation method.

     SYNTAX:

           theObject -> Align_Events, event

     ARGUMENTS:

           event:    The event structure.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\interactions\annotateinteraction__define.pro)

## ANNOTATEINTERACTION::BUILDMODEMENU

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

     NAME:
           ANNOTATEINTERACTION::BUILDMODEMENU

     PURPOSE:

           This method builds a mode-select context menu.

     SYNTAX:

           theObject -> BuildModeMenu

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\interactions\annotateinteraction__define.pro)

## ANNOTATEINTERACTION::BUILDMULTISELECTMENU

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

     NAME:
           ANNOTATEINTERACTION::BUILDMULTISELECTMENU

     PURPOSE:

           This method builds a multi-select context menu.

     SYNTAX:

           theObject -> BuildMultiSelectMenu

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\interactions\annotateinteraction__define.pro)

## ANNOTATEINTERACTION::CLEANUP

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

     NAME:
           ANNOTATEINTERACTION::CLEANUP

     PURPOSE:

           This is the ANNOTATEINTERACTION object class destructor method.

     SYNTAX:

           Called automatically when the object is destroyed.

     ARGUMENTS:

           None.

     KEYWORDS:

          None.

(See C:\IDL\Catalyst\source\interactions\annotateinteraction__define.pro)

## ANNOTATEINTERACTION::CONTROLPANEL

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

     NAME:
           ANNOTATEINTERACTION::CONTROLPANEL

     PURPOSE:

           This method creates a control panel for the object

     SYNTAX:

           imageObject -> ControlPanel, baseObj

     ARGUMENTS:

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

     KEYWORDS:

           _EXTRA:       Any keywords appropriate for the "CONTROLPANEL::INIT" method.

(See C:\IDL\Catalyst\source\interactions\annotateinteraction__define.pro)

## ANNOTATEINTERACTION::DISTRIBUTEGUI, EVENT

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

     NAME:
           ANNOTATEINTERACTION::DISTRIBUTEGUI, event

     PURPOSE:

           This method builds a modal dialog for obtaining user input for
           how to align selected items.

     SYNTAX:

           theObject -> DistributeGUI, event

     ARGUMENTS:

           event:    The event structure.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\interactions\annotateinteraction__define.pro)

## ANNOTATEINTERACTION::DISTRIBUTE_EVENTS

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

     NAME:
           ANNOTATEINTERACTION::DISTRIBUTE_EVENTS

     PURPOSE:

           This event handling method for the DISTRIBUTEGUI widget creation method.

     SYNTAX:

           theObject -> Distribute_Events, event

     ARGUMENTS:

           event:    The event structure.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\interactions\annotateinteraction__define.pro)

## ANNOTATEINTERACTION::DRAW

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

     NAME:
           ANNOTATEINTERACTION::DRAW

     PURPOSE:

           This method draws the interaction in the display window.

     SYNTAX:

           theObject -> Draw

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\interactions\annotateinteraction__define.pro)

## ANNOTATEINTERACTION::EVENT_HANDLER

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

     NAME:
            ANNOTATEINTERACTION::EVENT_HANDLER

     PURPOSE:

            This method is the event handler for the ANNOTATEINTERACTION object.

     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\interactions\annotateinteraction__define.pro)

## ANNOTATEINTERACTION::GETPROPERTY

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

     NAME:
           ANNOTATEINTERACTION::GETPROPERTY

     PURPOSE:

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

     SYNTAX:

           theObject -> GetProperty ...

     ARGUMENTS:

         None.

     KEYWORDS:

         BACKGROUND:         Set this keyword to draw a background for the text.

         BG_COLOR:           The name of the background color. By default, "white".

         COLOR:              Set this keyword to the name of a color for the text. By default, "black".

         DEF_ARROW_OBJECT:   A default arrow object. New objects are created with this object's properties.

         DEF_BOX_OBJECT:     A default box object. New objects are created with this object's properties.

         DEF_ELLIPSE_OBJECT: A default ellipse object. New objects are created with this object's properties.

         DEF_MEASURE_OBJECT: A default tapemeasure object. New objects are created with this object's properties.

         DEF_POLYGON_OBJECT: A default polygon object. New objects are created with this object's properties.

         DEF_TEXT_OBJECT:    A default text object. New objects are created with this object's properties.

         DEFAULT_OBJECT:     The current default object.

         LAYER:              The current annotation CATLAYER object.

         LINESTYLE:          The default linestyle for objects created with this object. By default, 0.

         MODE:               The current object mode.

         THICKNESS:          The default thickness of lines created by annotation objects. By default, 2.

         PIXMAPWIDGET:       The object reference to any pixmap widget that is created.

         SELECTEDOBJECTS:    Any objects currently selected.

         _REF_EXTRA:         Any keywords appropriate for the superclass GetProperty method.

(See C:\IDL\Catalyst\source\interactions\annotateinteraction__define.pro)

## ANNOTATEINTERACTION::INIT

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

     NAME:
           ANNOTATEINTERACTION::INIT

     PURPOSE:

           This is the ANNOTATEINTERACTION object class initialization method.

     SYNTAX:

           Called automatically when the object is created.

     ARGUMENTS:

         drawObject:          The draw widget object that you will be taking over events from.

     KEYWORDS:

         BACKGROUND:          Set this keyword to draw a background for the text.

         BG_COLOR:            The name of the background color. By default, "black".

         COLOR:               Set this keyword to the name of a color for the text. By default, "white".

         COORD_OBJECT:        A coordinate object (CATCOORD) for establishing a coordinate system for the
                              interaction objects. Currently, only the TAPEMEASURE uses a coordinate system.
                              All other coordinate systems are normalized.

         DEF_ANGLE_OBJECT:    An optional default ANGLETOOL object. New objects are created with this object's properties.

         DEF_ARROW_OBJECT:    An optional default ARROW object. New objects are created with this object's properties.

         DEF_BOX_OBJECT:      An optional default BOX object. New objects are created with this object's properties.

         DEF_ELLIPSE_OBJECT:  An optional default ELLIPSE object. New objects are created with this object's properties.

         DEF_MEASURE_OBJECT:  An optional default TAPEMEASURE object. New objects are created with this object's properties.

         DEF_POLYGON_OBJECT:  An optional default POLYGON object. New objects are created with this object's properties.

         DEF_TEXT_OBJECT:     An optional default TEXTLINE object. New objects are created with this object's properties.

         DEFAULT_OBJECT:      Set this keyword to an object reference to a SELECTABLEOBJECT object. By default,
                              is set to a DEF_TEXT_OBJECT. This object will be deleted when the ANNOTATEINTERACTION
                              object is destroyed.

         LAYER:               An optional CATLAYER object for holding the annotation objects. If a layer object is
                              not provided, the annotations are placed directly in the drawObject container. Otherwise,
                              the annotations are placed in the CATLAYER object, and the CATLAYER object is placed in
                              the drawObject.

         LINESTYLE:          The default linestyle for objects created with this object. By default, 0.

         OUTPUT_FILENAME:    The base name of the output filename used in SAVE AS operations. By default, "annotation".

         THICKNESS:          The default thickness of lines created by annotation objects. By default, 2.

         STATUSBAR:          A reference to a statusbar object. Messages can be sent from the interaction
                             to the statusbar object, if supplied. The statusbar object is NOT destroyed by
                             the interaction when the interaction is destroyed.

         _EXTRA:              Any keywords appropriate for the superclass INIT method or DEFAULT_OBJECT INIT method.

(See C:\IDL\Catalyst\source\interactions\annotateinteraction__define.pro)

## ANNOTATEINTERACTION::RESTOREDISPLAY

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

     NAME:
           ANNOTATEINTERACTION::RESTOREDISPLAY

     PURPOSE:

           This method restores the draw widget to its former state.

     SYNTAX:

           theObject -> RestoreDisplay

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\interactions\annotateinteraction__define.pro)

## ANNOTATEINTERACTION::SETDISPLAY

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

     NAME:
           ANNOTATEINTERACTION::SETDISPLAY

     PURPOSE:

           This method takes over event handling from the draw widget and
           sets up the object so that everything can be restored to the way
           it was when the interaction is finished.

     SYNTAX:

           theObject -> SetDisplay

     ARGUMENTS:

           drawWidget:   The draw widget used in the interaction. (Optional argument.)

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\interactions\annotateinteraction__define.pro)

## ANNOTATEINTERACTION::SETPROPERTY

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

     NAME:
           ANNOTATEINTERACTION::SETPROPERTY

     PURPOSE:

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

     SYNTAX:

           theObject -> SetProperty ...

     ARGUMENTS:

         None.

     KEYWORDS:

         The following keywords set default properties for new objects created in this interaction.

         BACKGROUND:         Set this keyword to draw a background for the text.

         BG_COLOR:           The name of the background color. By default, "white".

         COLOR:              Set this keyword to the name of a color for the text. By default, "black".

         DEF_ANGLE_OBJECT:   A default ANGLETOOL object. New objects are created with this object's properties.

         DEF_ARROW_OBJECT:   A default arrow object. New objects are created with this object's properties.

         DEF_BOX_OBJECT:     A default box object. New objects are created with this object's properties.

         DEF_ELLIPSE_OBJECT: A default ellipse object. New objects are created with this object's properties.

         DEF_MEASURE_OBJECT: A default tapemeasure object. New objects are created with this object's properties.

         DEF_POLYGON_OBJECT: A default polygon object. New objects are created with this object's properties.

         DEF_TEXT_OBJECT:    A default text object. New objects are created with this object's properties.

         DEFAULT_OBJECT:     Set this keyword to an object reference to a SELECTABLEOBJECT object. By default,
                             is set to a DEF_TEXT_OBJECT.

         LAYER:              A CATLAYER object for holding the annotation objects. The old annotation layer
                             and everything it contains will be destroyed.

         LINESTYLE:          The default linestyle for objects created with this object. By default, 0.

         MODE:               The current object mode.

         THICKNESS:          The default thickness of lines created by annotation objects. By default, 2.

         _EXTRA:             Any keywords appropriate for the superclass SetProperty method.

(See C:\IDL\Catalyst\source\interactions\annotateinteraction__define.pro)

## ANNOTATEINTERACTION__DEFINE

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

     NAME:
           ANNOTATEINTERACTION__DEFINE

     PURPOSE:

           The purpose of this routine is to provide an interaction for creating
           and manipulating SELECTABLEOBJECT objects. An interaction takes over
           draw widget event handling for the duration of the interaction and then
           restores it to its normal funcitoning. We spent a LOT of time implementing
           this, and while it works, it is extremely complicated (bordering on iTools
           complicated!). I am not happy with the complexity, and I am not sure this
           is what is needed anyway. I think interaction functionality is too user-specific
           to be handled like this. In practice, I seldom use interactions, but code
           the functionality I want for a particular application in the event handlers.
           That said, this particular interaction is amazingly useful for annotating
           graphics windows.

     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("ANNOTATEINTERACTION")

     SUPERCLASSES:

           INTERACTION
           CATCONTAINER IDLITCOMPONENT
           IDL_CONTAINER

     CLASS_STRUCTURE:

       class = { ANNOTATEINTERACTION, $
                 align_gui_tlb: Obj_New(), $      ; The align GUI top-level base object.
                 align_tb: 0L, $                  ; The current align top/bottom value.
                 align_lr: 0L, $                  ; The current align left/right value.
                 distribute_gui_tlb: Obj_New(), $ ; The distrubute GUI top-level base object.
                 distribute_h: 0L, $              ; The current distribute horizontal value.
                 distribute_v: 0L, $              ; The current distribute vertical value.
                 distribute_gap_h: Obj_New(), $   ; The distribute horizonal gap field object.
                 distribute_gap_v: Obj_New(), $   ; The distribute vertical gap field object.
                 selectedObjects: Ptr_New(), $    ; The currently selected objects.
                 sx: 0L, $                        ; The static X location.
                 sy: 0L, $                        ; The static Y location.

                 defaultObject: Obj_New(), $      ; The default (or current) selectable object.
                 defTextObject: Obj_New(), $      ; The default TEXTLINE object.
                 defAngleObject: Obj_New(), $     ; The default ANGLETOOL object.
                 defArrowObject: Obj_New(), $     ; The default ARROW object.
                 defBoxObject: Obj_New(), $       ; The default BOX object.
                 defEllipseObject: Obj_New(), $   ; The default ELLIPSE object.
                 defPolygonObject: Obj_New(), $   ; The default POLYGON object.
                 defMeasureObject: Obj_New(), $   ; The default MEASUREMENT object.
                 layerObject: Obj_New(), $        ; A layer object for holding selectable annotation objects.

                 angleID: Obj_New(), $            ; The ANGLE MEASURMENT button on the ControlPanel.
                 annotateOn: Obj_New(), $         ; The ANNOTATE_LAYER_ON button on the ControlPanel.
                 annotateOff: Obj_New(), $        ; The ANNOTATE_LAYER_OFF button on the ControlPanel.
                 arrowID: Obj_New(), $            ; The ARROW button on ControlPanel.
                 boxID: Obj_New(), $              ; The BOX button on ControlPanel.
                 ellipseID: Obj_New(), $          ; The ELLIPSE button on the ControlPanel.
                 globalID: Obj_New(), $           ; The GLOBAL_PROPERTY button on ControlPanel.
                 measureID: Obj_New(), $          ; The MEASUREMENT button on the ControlPanel.
                 polygonID: Obj_New(), $          ; The POLYGON button on the ControlPanel.
                 saveID: Obj_New(), $             ; The SAVE_WINDOW button on ControlPanel.
                 selectID: Obj_New(), $           ; The SELECT button on ControlPanel.
                 textID: Obj_New(), $             ; The TEXT button on ControlPanel.

                 INHERITS INTERACTION $
               }

     MESSAGES:

       None.

     NOTES:

       The way the interaction works is by copying the contents of the draw widget into a pixmap,
       so they can be redrawn appropriately. This is only successful if the contents of the draw
       widget can be drawn in the pixmap. Images, for example, might have their WID keyword set and
       be attached to a draw widget already. (This is especially the case if they are responding to
       color table events of some kind.) These kinds of images are not appropriate for annotation
       interactions, because they can't be drawn in the pixmap.

     MODIFICATION_HISTORY:

           Written by: David W. Fanning, 9 August 2004.

(See C:\IDL\Catalyst\source\interactions\annotateinteraction__define.pro)

## INTERACTION::ADD

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

     NAME:
           INTERACTION::ADD

     PURPOSE:

           This method is where you can screen what kinds of objects are
           added to this object's hierarchy. The method is not always needed.
           If you do create it, be CERTAIN to call the superclass ADD method
           or your program will not work correctly.

     SYNTAX:

           theObject -> Add, object

     ARGUMENTS:

         object:     The object to be added to this one.

     KEYWORDS:

         _EXTRA:     Any keywords appropriate for the superclass Add method.

(See C:\IDL\Catalyst\source\interactions\interaction__define.pro)

## INTERACTION::CLEANUP

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

     NAME:
           INTERACTION::CLEANUP

     PURPOSE:

           This is the INTERACTION object class destructor method.

     SYNTAX:

           Called automatically when the object is destroyed.

     ARGUMENTS:

           None.

     KEYWORDS:

          None.

(See C:\IDL\Catalyst\source\interactions\interaction__define.pro)

## INTERACTION::CLEARABANDONEDOBJECTS

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

     NAME:
           INTERACTION::CLEARABANDONEDOBJECTS

     PURPOSE:

           Many of the interaction objects create an object and add it to the draw widget.
           For example, the RUBBERBANDBOX interaction adds a BOX object to the draw widget.
           If the ASK_ON_UP keyword is set, this object may be abandoned by the user not
           selecting either the Accept or Cancel button. Since I cannot anticipate when this
           will happen, this method is about recovering from those unfortunate times when I
           cannot tell what has happened previously. I might callt his method when the user
           switches interactions, for example. The method will simple look for an object
           with the CLASSNAME prepended to the word "SELECTABLE_". If it finds it, it will
           destroy it.

     SYNTAX:

           theObject -> ClearAbandonedObjects

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\interactions\interaction__define.pro)

## INTERACTION::DRAW

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

     NAME:
           INTERACTION::DRAW

     PURPOSE:

           This method draws the "interaction" in the draw widget.

     SYNTAX:

           theObject -> Draw

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\interactions\interaction__define.pro)

## INTERACTION::EVENT_HANDLER

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

     NAME:
            INTERACTION::EVENT_HANDLER

     PURPOSE:

            This method is the event handler for the INTERACTION object. It will be used
            to respond to event generated in the draw widget.

     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\interactions\interaction__define.pro)

## INTERACTION::GETPROPERTY

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

     NAME:
           INTERACTION::GETPROPERTY

     PURPOSE:

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

     SYNTAX:

           theObject -> GetProperty ...

     ARGUMENTS:

         None.

     KEYWORDS:

         COLOR:          The name of the color of the region of interest.

         DRAWIMAGE:      Set this keyword to a named variable to receive a copy of the
                         draw widget's current contents as an image. May by undefined
                         if SetDisplay hasn't been called, or if RestoreDisplay has been called.

         DRAWWIDGET:     The draw widget object for whom you are taking over events.

         PIXMAPIMAGE:    Set this keyword to a named variable to receive a copy of the
                         draw widget's original contents (at the moment SetDisplay was called)
                         as an image. May by undefined if SetDisplay hasn't been called, or if
                         RestoreDisplay has been called.

         MODE:           The current "mode" of the interaction.

         SELECTEDOBJECT: The currenly selected object.

         STATUSBAR:      A reference to the current statusbar object.

         XPT:            The X location of the click interaction.

         YPT:            The Y location of the click interaction.

         _REF_EXTRA:     Any keywords appropriate for the superclass GetProperty method.

(See C:\IDL\Catalyst\source\interactions\interaction__define.pro)

## INTERACTION::INIT

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

     NAME:
           INTERACTION::INIT

     PURPOSE:

           This is the INTERACTION object class initialization method

     SYNTAX:

           Called automatically when the object is created.

     ARGUMENTS:

         drawObject:   The draw widget object that you will be taking over events from.

     KEYWORDS:

         ASK_ON_UP:      Set this keyword if you wish the user to respond to a ACCEPT/CANCEL
                         dialog when the box is finished drawing. If there is no dialog, it is
                         as if an ACCEPT were recorded and a RUBBERBANDBOX_EVENT is sent to the
                         appropriate event handler method.

         COLOR:          The name of the color of the region of interest. By default, "Yellow".

         NOPICRESTORE:   Normally, when the display is restored, the contents of the draw widget
                         are restored to the state they were in before the interaction took place.
                         However, if this keyword is set, the contents of the display window are
                         left as they are at the end of the interaction.

         MODE:           The current "mode" of the interaction. By default, "DRAW".

         SELECTEDOBJECT: The currenly selected object. Normally, this object will be moved or dragged
                         if the mode is MOVE or DRAG, etc.

         START_NOW:      If this keyword is set, the SetDisplay method is called from within the INIT method.
                         If the draw widget is unrealized at the time of the call, the interaction object
                         will register for a DRAWWIDGETREALIZED message.

         STATUSBAR:      A reference to a statusbar object. Messages can be sent from the interaction
                         to the statusbar object, if supplied. The statusbar object is NOT destroyed by
                         the interaction when the interaction is destroyed.

         _EXTRA:         Any keywords appropriate for the superclass INIT method.

(See C:\IDL\Catalyst\source\interactions\interaction__define.pro)

## INTERACTION::MESSAGEHANDLER

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

     NAME:
           Interaction::MESSAGEHANDLER

     PURPOSE:

           This method responds to "messages" sent from other objects. It is called
           automatically by other objects. To receive messages, it is necessary to
           "register" with the messaging object.

     SYNTAX:

           None. Called by other objects.

     ARGUMENTS:

           TITLE:  The message title. This is the "name" of the message indicated when
                   the object registered for messages with the messaging object.

     KEYWORDS:

           DATA:   Information from the SENDER that may be relevant in processing the message.
                   Typically, an anonymous structure variable, although it could be anything at all.

           SENDER: An output keyword. This is the object reference of the object that is sending
                   the message.

(See C:\IDL\Catalyst\source\interactions\interaction__define.pro)

## INTERACTION::NEEDDIALOG

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

     NAME:
           INTERACTION::NEEDDIALOG

     PURPOSE:

           This method is a utility routine to simply determine if a dialog is required on not.
           If not, an event is generated and sent to the user of the interaction.

     SYNTAX:

           theObject -> NeedDialog, event

     ARGUMENTS:

           event:      The event structure currently in effect.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\interactions\interaction__define.pro)

## INTERACTION::REFRESHPIXMAP

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

     NAME:
           INTERACTION::REFRESHPIXMAP

     PURPOSE:

           This method refreshes the pixmap (the original display might have changed in some way) and
           (optionally) calls the DRAW method.

     SYNTAX:

           theObject -> RefreshPixmap

     ARGUMENTS:

           None.

     KEYWORDS:

           DRAW:       If this keyword is set, the DRAW method is called..

(See C:\IDL\Catalyst\source\interactions\interaction__define.pro)

## INTERACTION::RESTOREDISPLAY

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

     NAME:
           INTERACTION::RESTOREDISPLAY

     PURPOSE:

           This method restores the draw widget to its former state.

     SYNTAX:

           theObject -> RestoreDisplay

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\interactions\interaction__define.pro)

## INTERACTION::SENDEVENT

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

     NAME:
           INTERACTION::SENDEVENT

     PURPOSE:

           This method allows the user to send an event to the real draw widget event handler.

     SYNTAX:

           theObject -> SetEvent

     ARGUMENTS:

         event          The original event.

     KEYWORDS:

         None.

(See C:\IDL\Catalyst\source\interactions\interaction__define.pro)

## INTERACTION::SETDISPLAY

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

     NAME:
           INTERACTION::SETDISPLAY

     PURPOSE:

           This method takes over event handling from the draw widget and
           sets up the object so that everything can be restored to the way
           it was when the interaction is finished.

     SYNTAX:

           theObject -> SetDisplay

     ARGUMENTS:

           drawWidget  ; The draw widget used in the interaction.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\interactions\interaction__define.pro)

## INTERACTION::SETPROPERTY

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

     NAME:
           INTERACTION::SETPROPERTY

     PURPOSE:

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

     SYNTAX:

           theObject -> SetProperty ...

     ARGUMENTS:

         None.

     KEYWORDS:

         DRAWWIDGET:     The draw widget object for whom you are taking over events.

         NOPICRESTORE:   Set this keyword to not update the draw widget with original image
                         when RestoreDisplay method is called.

         COLOR:          The name of the color of the region of interest.

         MODE:           The current "mode" of the interaction. By default, "DRAW".

         SELECTEDOBJECT: The currenly selected object. Normally, this object will be moved or dragged
                         if the mode is MOVE or DRAG, etc.

         START_NOW:      If this keyword is set, the SetDisplay method is called immediately.

         STATUSBAR:      A reference to a statusbar object. Messages can be sent from the interaction
                         to the statusbar object, if supplied. The statusbar object is NOT destroyed by
                         the interaction when the interaction is destroyed.

         _EXTRA:         Any keywords appropriate for the superclass SetProperty method.

(See C:\IDL\Catalyst\source\interactions\interaction__define.pro)

## INTERACTION__DEFINE

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

     NAME:
           INTERACTION__DEFINE

     PURPOSE:

           The purpose of this routine is to implement the most basic of interactions.
           An "interaction" is an operation that takes over control of a draw widget and
           allows the user to interact with the draw widget in some way. For example,
           drawing ROI's on a draw widget is a good example of an interaction. Most interactions
           will be subclassed from this INTERACTION object. We have spent an inordinate amount
           of time on interactions, but in the end they are *extremely* complicated to program.
           I am of the mind now that users should program their own functionality and not
           rely on interactions, since the programming effort to create interactions seems
           disproportional to the results. I'm saying that most of the time, interactive functionality
           can be programmed as normal event handler procedures, rather than relying on interactions.
           That said, the interactions we have programmed do work, and they have been instrumental
           in producing some very nice functionality in Catalyst applications. Ideas for simplifying
           interactions are especially needed.

     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("INTERACTION")

     SUPERCLASSES:

           CATATOM
           CATCONTAINER IDLITCOMPONENT
           IDL_CONTAINER

     CLASS_STRUCTURE:

       class = { INTERACTION, $
                 _ask_on_up: 0B, $                     ; Flag for UP button dialog widget.
                 _drawID: Obj_New(), $                 ; The draw widget whose events are being hijacked.
                 _drawID_events: IntArr(7), $          ; Storage for the draw widget event types.
                 _drawID_excl_event_obj: Obj_New(), $  ; The old exclusive event (if there is one).
                 _drawID_pixmap: Obj_New(), $          ; A pixmap for storing the drawID picture.
                 _drawID_event_objects: Ptr_New(), $   ; The event objects for the draw widget.
                 _click_x: 0L, $                       ; The X location of button down event.
                 _click_y: 0L, $                       ; The Y location of button down event.
                 _contextmenu: Obj_New(), $            ; The context menu.
                 _mode: "", $                          ; The "mode" of the interaction: eg., MOVE or DRAW.
                 _noPicture: 0L, $                     ; A flag: Should picture be restored at end of interaction?
                 _roi_color: "", $                     ; The color of the roi.
                 _selectedObject: Obj_New(), $         ; A selectable interaction object that can be moved.
                 _statusbar: Obj_New(), $              ; A statusbar object. Can be passed messages, etc.
                 INHERITS CATATOM $
               }

     MESSAGES:

       None.

     MODIFICATION_HISTORY:

           Written by: David W. Fanning, 10 February 2004.
           Added DRAW_REALIZE keyword. 14 February 2005.

(See C:\IDL\Catalyst\source\interactions\interaction__define.pro)

## SELECTINTERACTION::ADD

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

     NAME:
           SELECTINTERACTION::ADD

     PURPOSE:

           This method is where you can screen what kinds of objects are
           added to this object's hierarchy. The method is not always needed.
           If you do create it, be CERTAIN to call the superclass ADD method
           or your program will not work correctly.

     SYNTAX:

           theObject -> Add, object

     ARGUMENTS:

         object:     The object to be added to this one.

     KEYWORDS:

         _EXTRA:     Any keywords appropriate for the superclass Add method.

(See C:\IDL\Catalyst\source\interactions\selectinteraction__define.pro)

## SELECTINTERACTION::CLEANUP

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

     NAME:
           SELECTINTERACTION::CLEANUP

     PURPOSE:

           This is the SELECTINTERACTION object class destructor method.

     SYNTAX:

           Called automatically when the object is destroyed.

     ARGUMENTS:

           None.

     KEYWORDS:

          None.

(See C:\IDL\Catalyst\source\interactions\selectinteraction__define.pro)

## SELECTINTERACTION::DRAW

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

     NAME:
           SELECTINTERACTION::DRAW

     PURPOSE:

           This method draws the "interaction" in the draw widget.

     SYNTAX:

           theObject -> Draw

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\interactions\selectinteraction__define.pro)

## SELECTINTERACTION::EVENT_HANDLER

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

     NAME:
            SELECTINTERACTION::EVENT_HANDLER

     PURPOSE:

            This method is the event handler for the SELECTINTERACTION object. It will be used
            to respond to event generated in the draw widget.

     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\interactions\selectinteraction__define.pro)

## SELECTINTERACTION::GETPROPERTY

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

     NAME:
           SELECTINTERACTION::GETPROPERTY

     PURPOSE:

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

     SYNTAX:

           theObject -> GetProperty ...

     ARGUMENTS:

         None.

     KEYWORDS:

         COLOR:          The name of the color of the region of interest.

         COORD_OBJECT:   A coordinate object for establishing a data coordinate system.

         DRAWIMAGE:      Set this keyword to a named variable to receive a copy of the
                         draw widget's current contents as an image. May by undefined
                         if SetDisplay hasn't been called, or if RestoreDisplay has been called.

         DRAWWIDGET:     The draw widget object for whom you are taking over events.

         LINESTYLE:      The linestyle index.

         PIXMAPOBJECT:   Set this keyword to a named variable to receive the pixmap object associated with the draw widget.

         MODE:           The current "mode" of the interaction.

         SELECTEDOBJECT: The currenly selected object.

         STATUSBAR:      A reference to the current statusbar object.

         THICK:          The line thickness index.

         _REF_EXTRA:     Any keywords appropriate for the superclass GetProperty method.

(See C:\IDL\Catalyst\source\interactions\selectinteraction__define.pro)

## SELECTINTERACTION::INIT

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

     NAME:
           SELECTINTERACTION::INIT

     PURPOSE:

           This is the SELECTINTERACTION object class initialization method

     SYNTAX:

           Called automatically when the object is created.

     ARGUMENTS:

         drawObject:   The draw widget object that you will be taking over events from.

     KEYWORDS:

         ASK_ON_UP:      Set this keyword if you wish the user to respond to a ACCEPT/CANCEL
                         dialog when the selectable object reports an UP event.

         COLOR:          The name of the color of the selectable object. By default, "NONE". If
                         this keyword is set to "NONE", the color of the SELECTEDOBJECT will be
                         used instead.

         COORD_OBJECT:   A coordinate object for establishing a data coordinate system. If not
                         provided, the coordinate object of the draw widget is obtained. If this
                         is unavailable, a normalized coordinate system is used. The COORD_OBJECT
                         is passed to the SelectableObject as its coordinate system.

         LINESTYLE:      The linestyle index of the region of interest. By default, "-1". If
                         this keyword is set to "-1", the linestyle of the SELECTEDOBJECT will be
                         used instead.

         NOPICRESTORE:   Normally, when the display is restored, the contents of the draw widget
                         are restored to the state they were in before the interaction took place.
                         However, if this keyword is set, the contents of the display window are
                         left as they are at the end of the interaction.

         MODE:           The current "mode" of the interaction. By default, "INSERT". All draw widget
                         events are passed along to the selected object to process in its INTERACTION_EVENTS
                         method.

         SELECTEDOBJECT: The currenly selected or "default" object. It must be a subclassed SELECTABLEOBJECT,
                         such as a BOX or ELLIPSE object. This object will be destroyed when the interaction
                         is destroyed.

         START_NOW:      If this keyword is set, the SetDisplay method is called from within the INIT method.
                         If the draw widget is unrealized at the time of the call, the interaction object
                         will register for a DRAWWIDGETREALIZED message.

         STATUSBAR:      A reference to a statusbar object. Messages can be sent from the interaction
                         to the statusbar object, if supplied. The statusbar object is NOT destroyed by
                         the interaction when the interaction is destroyed.

         THICK:          The thickness index of the region of interest. By default, "-1". If
                         this keyword is set to "-1", the thickness index of the SELECTEDOBJECT will be
                         used instead.

         _EXTRA:         Any keywords appropriate for the superclass INIT method.

(See C:\IDL\Catalyst\source\interactions\selectinteraction__define.pro)

## SELECTINTERACTION::MESSAGEHANDLER

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

     NAME:
           SelectInteraction::MESSAGEHANDLER

     PURPOSE:

           This method responds to "messages" sent from other objects. It is called
           automatically by other objects. To receive messages, it is necessary to
           "register" with the messaging object.

     SYNTAX:

           None. Called by other objects.

     ARGUMENTS:

           TITLE:  The message title. This is the "name" of the message indicated when
                   the object registered for messages with the messaging object.

     KEYWORDS:

           DATA:   Information from the SENDER that may be relevant in processing the message.
                   Typically, an anonymous structure variable, although it could be anything at all.

           SENDER: An output keyword. This is the object reference of the object that is sending
                   the message.

(See C:\IDL\Catalyst\source\interactions\selectinteraction__define.pro)

## SELECTINTERACTION::NEEDDIALOG

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

     NAME:
           SELECTINTERACTION::NEEDDIALOG

     PURPOSE:

           This method is a utility routine to simply determine if a dialog is required on not.
           If not, an event is generated and sent to the user of the interaction.

     SYNTAX:

           theObject -> NeedDialog, event

     ARGUMENTS:

           event:      The event structure currently in effect.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\interactions\selectinteraction__define.pro)

## SELECTINTERACTION::REFRESHPIXMAP

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

     NAME:
           SELECTINTERACTION::REFRESHPIXMAP

     PURPOSE:

           This method refreshes the pixmap (the original display might have changed in some way) and
           (optionally) calls the DRAW method.

     SYNTAX:

           theObject -> RefreshPixmap

     ARGUMENTS:

           None.

     KEYWORDS:

           DRAW:       If this keyword is set, the DRAW method is called..

(See C:\IDL\Catalyst\source\interactions\selectinteraction__define.pro)

## SELECTINTERACTION::RESTOREDISPLAY

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

     NAME:
           SELECTINTERACTION::RESTOREDISPLAY

     PURPOSE:

           This method restores the draw widget to its former state.

     SYNTAX:

           theObject -> RestoreDisplay

     ARGUMENTS:

           None.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\interactions\selectinteraction__define.pro)

## SELECTINTERACTION::SENDEVENT

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

     NAME:
           SELECTINTERACTION::SENDEVENT

     PURPOSE:

           This method allows the user to send an event to the real draw widget event handler.

     SYNTAX:

           theObject -> SetEvent

     ARGUMENTS:

         event          The original event.

     KEYWORDS:

         None.

(See C:\IDL\Catalyst\source\interactions\selectinteraction__define.pro)

## SELECTINTERACTION::SETDISPLAY

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

     NAME:
           SELECTINTERACTION::SETDISPLAY

     PURPOSE:

           This method takes over event handling from the draw widget and
           sets up the object so that everything can be restored to the way
           it was when the interaction is finished.

     SYNTAX:

           theObject -> SetDisplay

     ARGUMENTS:

           drawWidget  ; The draw widget used in the interaction.

     KEYWORDS:

           None.

(See C:\IDL\Catalyst\source\interactions\selectinteraction__define.pro)

## SELECTINTERACTION::SETPROPERTY

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

     NAME:
           SELECTINTERACTION::SETPROPERTY

     PURPOSE:

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

     SYNTAX:

           theObject -> SetProperty ...

     ARGUMENTS:

         None.

     KEYWORDS:

         DRAWWIDGET:     The draw widget object for whom you are taking over events.

         NOPICRESTORE:   Set this keyword to not update the draw widget with the original background image
                         when RestoreDisplay method is called.

         COLOR:          The name of the color of the region of interest. By default, "NONE". If
                         this keyword is set to "NONE", the color of the SELECTEDOBJECT will be
                         used instead.

         COORD_OBJECT:   A coordinate object for establishing a data coordinate system. Note that
                         changing the coordinate object here will not have any effect on the current
                         selectedObject. The selectedObject will have to be replace in a second call,
                         for this coordinate system to be assigned.

         LINESTYLE:      The linestyle index of the region of interest. By default, "-1". If
                         this keyword is set to "-1", the linestyle of the SELECTEDOBJECT will be
                         used instead.

         MODE:           The current "mode" of the interaction. By default, "INSERT".

         SELECTEDOBJECT: The currenly selected object. In other words, the object the interaction
                         manipulates. This is a BOX object by default.

         START_NOW:      If this keyword is set, the SetDisplay method is called immediately.

         STATUSBAR:      A reference to a statusbar object. Messages can be sent from the interaction
                         to the statusbar object, if supplied. The statusbar object is NOT destroyed by
                         the interaction when the interaction is destroyed.

         THICK:          The thickness index of the region of interest. By default, "-1". If
                         this keyword is set to "-1", the thickness index of the SELECTEDOBJECT will be
                         used instead.

         _EXTRA:         Any keywords appropriate for the superclass SetProperty method.

(See C:\IDL\Catalyst\source\interactions\selectinteraction__define.pro)

## SELECTINTERACTION__DEFINE

[Previous Routine] [List of Routines]

     NAME:
           SELECTINTERACTION__DEFINE

     PURPOSE:

           The purpose of this routine is to implement the most basic of interactions.
           An "interaction" is an operation that takes over control of a draw widget and
           allows the user to interact with the draw widget in some way. For example,
           drawing ROI's on a draw widget is a good example of an interaction. This will
           be the basic interaction object many other interactions will inherit.

           The philosophy of an interaction is that there is an object to "draw" in the
           window. Once drawn, the object can be selected, moved, rearranged, resized, etc.
           Then, when finished the interaction can report results to the real event handler
           for the draw widget.

           Much of the event handling for an interaction occurs in the INTERACTION_EVENTS
           method of the object being drawn or manipulated. These objects are SELECTABLEOBJECTS
           (e.g. BOX, ARROW, TEXTLINE, etc.) and must be written in a particular way. This
           approach is, in my opinion, overly complicated at the moment, and new interaction
           objects are difficult to write. I have given this subject a great deal of thought,
           and have still not hit on the one simple, elegant idea. So, I leave this to you.

     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("SELECTINTERACTION")

     SUPERCLASSES:

           CATATOM
           CATCONTAINER IDLITCOMPONENT
           IDL_CONTAINER

     EVENT_STRUCTURE:

           event = { ID:theObject, TOP:topObject, HANDLER:Obj_New(), EVENT_NAME='SELECTINTERACTION_EVENT', $
                      NAME: self._name, ACTION:"", CURRENTMODE:"", ... }

           If the interaction is in DRAW mode, an event is generated immediately upon an UP event.
           If the interaction is in INSERT mode, the action is similar, unless the ASK_ON_UP keyword
           is set. Then, the event is sent only when the user responds to the CANCEL or ACCEPT buttons.
           In any case, the ACTION field is always set to "ACCEPT" unless the CANCEL button is selected,
           and then it is set to "CANCEL".

     CLASS_STRUCTURE:

       class = { SELECTINTERACTION, $
                 _ask_on_up: 0B, $                     ; Flag for UP button dialog widget.
                 _color: "", $                         ; The color of the object drawn.
                 _coord_object: Obj_New(), $           ; A coordinate object.
                 _drawID: Obj_New(), $                 ; The draw widget whose events are being hijacked.
                 _drawID_events: IntArr(7), $          ; Storage for the draw widget event types.
                 _drawID_excl_event_obj: Obj_New(), $  ; The old exclusive event (if there is one).
                 _drawID_pixmap: Obj_New(), $          ; A pixmap for storing the drawID picture.
                 _drawID_event_objects: Ptr_New(), $   ; The event objects for the draw widget.
                 _contextmenu: Obj_New(), $            ; The context menu.
                 _linestyle: 0L,  $                    ; The linestyle of the object drawn.
                 _mode: "", $                          ; The "mode" of the interaction: eg., INSERT or DRAW.
                 _noPicture: 0L, $                     ; A flag: Should picture be restored at end of interaction?
                 _selectedObject: Obj_New(), $         ; A selectable interaction object that can be moved.
                 _statusbar: Obj_New(), $              ; A statusbar object. Can be passed messages, etc.
                 _sx: 0L, $                            ; The static X location of a selected item.
                 _sy: 0L, $                            ; The static Y location of a selected item.
                 _thick: 0L, $                         ; The thickness of the line of the object drawn.
                 INHERITS CATATOM $
               }

     MESSAGES:

       None.

     MODIFICATION_HISTORY:

           Written by: David W. Fanning, 10 February 2004.

(See C:\IDL\Catalyst\source\interactions\selectinteraction__define.pro)