1 /*=========================================================================
2 
3   Program:   Visualization Toolkit
4   Module:    vtkHoverWidget.h
5 
6   Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
7   All rights reserved.
8   See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
9 
10      This software is distributed WITHOUT ANY WARRANTY; without even
11      the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
12      PURPOSE.  See the above copyright notice for more information.
13 
14 =========================================================================*/
15 /**
16  * @class   vtkHoverWidget
17  * @brief   invoke a vtkTimerEvent when hovering
18  *
19  * The vtkHoverWidget is used to invoke an event when hovering in a render window.
20  * Hovering occurs when mouse motion (in the render window) does not occur
21  * for a specified amount of time (i.e., TimerDuration). This class can be used
22  * as is (by observing TimerEvents) or for class derivation for those classes
23  * wishing to do more with the hover event.
24  *
25  * To use this widget, specify an instance of vtkHoverWidget and specify the
26  * time (in milliseconds) defining the hover period. Unlike most widgets,
27  * this widget does not require a representation (although subclasses like
28  * vtkBalloonWidget do require a representation).
29  *
30  * @par Event Bindings:
31  * By default, the widget observes the following VTK events (i.e., it
32  * watches the vtkRenderWindowInteractor for these events):
33  * <pre>
34  *   MouseMoveEvent - manages a timer used to determine whether the mouse
35  *                    is hovering.
36  *   TimerEvent - when the time between events (e.g., mouse move), then a
37  *                timer event is invoked.
38  *   KeyPressEvent - when the "Enter" key is pressed after the balloon appears,
39  *                   a callback is activated (e.g., WidgetActivateEvent).
40  * </pre>
41  *
42  * @par Event Bindings:
43  * Note that the event bindings described above can be changed using this
44  * class's vtkWidgetEventTranslator. This class translates VTK events
45  * into the vtkHoverWidget's widget events:
46  * <pre>
47  *   vtkWidgetEvent::Move -- start (or reset) the timer
48  *   vtkWidgetEvent::TimedOut -- when enough time is elapsed between defined
49  *                               VTK events the hover event is invoked.
50  *   vtkWidgetEvent::SelectAction -- activate any callbacks associated
51  *                                   with the balloon.
52  * </pre>
53  *
54  * @par Event Bindings:
55  * This widget invokes the following VTK events on itself when the widget
56  * determines that it is hovering. Note that observers of this widget can
57  * listen for these events and take appropriate action.
58  * <pre>
59  *   vtkCommand::TimerEvent (when hovering is determined to occur)
60  *   vtkCommand::EndInteractionEvent (after a hover has occurred and the
61  *                                    mouse begins moving again).
62  *   vtkCommand::WidgetActivateEvent (when the balloon is selected with a
63  *                                    keypress).
64  * </pre>
65  *
66  * @sa
67  * vtkAbstractWidget
68  */
69 
70 #ifndef vtkHoverWidget_h
71 #define vtkHoverWidget_h
72 
73 #include "vtkAbstractWidget.h"
74 #include "vtkInteractionWidgetsModule.h" // For export macro
75 
76 class VTKINTERACTIONWIDGETS_EXPORT vtkHoverWidget : public vtkAbstractWidget
77 {
78 public:
79   /**
80    * Instantiate this class.
81    */
82   static vtkHoverWidget* New();
83 
84   ///@{
85   /**
86    * Standard methods for a VTK class.
87    */
88   vtkTypeMacro(vtkHoverWidget, vtkAbstractWidget);
89   void PrintSelf(ostream& os, vtkIndent indent) override;
90   ///@}
91 
92   ///@{
93   /**
94    * Specify the hovering interval (in milliseconds). If after moving the
95    * mouse the pointer stays over a vtkProp for this duration, then a
96    * vtkTimerEvent::TimerEvent is invoked.
97    */
98   vtkSetClampMacro(TimerDuration, int, 1, 100000);
99   vtkGetMacro(TimerDuration, int);
100   ///@}
101 
102   /**
103    * The method for activating and deactivating this widget. This method
104    * must be overridden because it performs special timer-related operations.
105    */
106   void SetEnabled(int) override;
107 
108   /**
109    * A default representation, of which there is none, is created. Note
110    * that the superclasses vtkAbstractWidget::GetRepresentation()
111    * method returns nullptr.
112    */
CreateDefaultRepresentation()113   void CreateDefaultRepresentation() override { this->WidgetRep = nullptr; }
114 
115 protected:
116   vtkHoverWidget();
117   ~vtkHoverWidget() override;
118 
119   // The state of the widget
120 
121   enum
122   {
123     Start = 0,
124     Timing,
125     TimedOut
126   };
127 
128   int WidgetState;
129 
130   // Callback interface to execute events
131   static void MoveAction(vtkAbstractWidget*);
132   static void HoverAction(vtkAbstractWidget*);
133   static void SelectAction(vtkAbstractWidget*);
134 
135   // Subclasses of this class invoke these methods. If a non-zero
136   // value is returned, a subclass is handling the event.
SubclassHoverAction()137   virtual int SubclassHoverAction() { return 0; }
SubclassEndHoverAction()138   virtual int SubclassEndHoverAction() { return 0; }
SubclassSelectAction()139   virtual int SubclassSelectAction() { return 0; }
140 
141   ///@{
142   /**
143    * Helper methods for creating and destroying timers.
144    */
145   int TimerId;
146   int TimerDuration;
147   ///@}
148 
149 private:
150   vtkHoverWidget(const vtkHoverWidget&) = delete;
151   void operator=(const vtkHoverWidget&) = delete;
152 };
153 
154 #endif
155