text: /*=========================================================================
  
    Program:   Visualization Toolkit
    Module:    $RCSfile: vtkHoverWidget.h,v $
  
    Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
    All rights reserved.
    See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
  
       This software is distributed WITHOUT ANY WARRANTY; without even
       the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
       PURPOSE.  See the above copyright notice for more information.
  
  =========================================================================*/
  // .NAME vtkHoverWidget - invoke a vtkTimerEvent when hovering 
  // .SECTION Description 
  // The vtkHoverWidget is used to invoke an event when hovering in a render window.
  // Hovering occurs when mouse motion (in the render window) does not occur
  // for a specified amount of time (i.e., TimerDuration). This class can be used
  // as is (by observing TimerEvents) or for class derivation for those classes
  // wishing to do more with the hover event.
  // 
  // To use this widget, specify an instance of vtkHoverWidget and specify the
  // time (in milliseconds) defining the hover period. Unlike most widgets,
  // this widget does not require a representation (although subclasses like
  // vtkBalloonWidget do require a representation).
  //
  // .SECTION Event Bindings
  // By default, the widget observes the following VTK events (i.e., it
  // watches the vtkRenderWindowInteractor for these events):
  // <pre>
  //   MouseMoveEvent - manages a timer used to determine whether the mouse
  //                    is hovering.
  //   TimerEvent - when the time between events (e.g., mouse move), then a
  //                timer event is invoked.
  //   KeyPressEvent - when the "Enter" key is pressed after the balloon appears,
  //                   a callback is activited (e.g., WidgetActivateEvent).
  // </pre>
  //
  // Note that the event bindings described above can be changed using this
  // class's vtkWidgetEventTranslator. This class translates VTK events 
  // into the vtkHoverWidget's widget events:
  // <pre>
  //   vtkWidgetEvent::Move -- start (or reset) the timer
  //   vtkWidgetEvent::TimedOut -- when enough time is elapsed between defined
  //                               VTK events the hover event is invoked.
  //   vtkWidgetEvent::SelectAction -- activate any callbacks associated 
  //                                   with the balloon.
  // </pre>
  //
  // This widget invokes the following VTK events on itself when the widget 
  // determines that it is hovering. Note that observers of this widget can
  // listen for these events and take appropriate action.
  // <pre>
  //   vtkCommand::TimerEvent (when hovering is determined to occur)
  //   vtkCommand::EndInteractionEvent (after a hover has occured and the
  //                                    mouse begins moving again).
  //   vtkCommand::WidgetActivateEvent (when the balloon is selected with a
  //                                    keypress).
  // </pre>
  
  // .SECTION See Also
  // vtkAbstractWidget
  
  
  #ifndef __vtkHoverWidget_h
  #define __vtkHoverWidget_h
  
  #include "vtkAbstractWidget.h"
  
  
  class VTK_WIDGETS_EXPORT vtkHoverWidget : public vtkAbstractWidget
  {
  public:
    // Description:
    // Instantiate this class.
    static vtkHoverWidget *New();
  
    // Description:
    // Standard methods for a VTK class.
    vtkTypeRevisionMacro(vtkHoverWidget,vtkAbstractWidget);
    void PrintSelf(ostream& os, vtkIndent indent);
  
    // Description:
    // Specify the hovering interval (in milliseconds). If after moving the
    // mouse the pointer stays over a vtkProp for this duration, then a
    // vtkTimerEvent::TimerEvent is invoked.
    vtkSetClampMacro(TimerDuration,int,1,100000);
    vtkGetMacro(TimerDuration,int);
    
    // Description:
    // The method for activiating and deactiviating this widget. This method
    // must be overridden because it performs special timer-related operations.
    virtual void SetEnabled(int);
  
    // Description:
    // A default representation, of which there is none, is created. Note
    // that the superclasses vtkAbstractWidget::GetRepresentation()
    // method returns NULL.
    void CreateDefaultRepresentation()
      {this->WidgetRep = NULL;}
  
  protected:
    vtkHoverWidget();
    ~vtkHoverWidget();
  
    // The state of the widget
  //BTX
    enum {Start=0,Timing,TimedOut};
  //ETX
    int WidgetState;
  
    // Callback interface to execute events
    static void MoveAction(vtkAbstractWidget*);
    static void HoverAction(vtkAbstractWidget*);
    static void SelectAction(vtkAbstractWidget*);
    
    // Subclasses of this class invoke these methods. If a non-zero
    // value is returned, a subclass is handling the event.
    virtual int SubclassHoverAction() {return 0;}
    virtual int SubclassEndHoverAction() {return 0;}
    virtual int SubclassSelectAction() {return 0;}
    
    // Description:
    // Helper methods for creating and destroying timers.
    int TimerId;
    int TimerDuration;
    
  private:
    vtkHoverWidget(const vtkHoverWidget&);  //Not implemented
    void operator=(const vtkHoverWidget&);  //Not implemented
  };
  
  #endif
  