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