1 /*========================================================================= 2 3 Program: Visualization Toolkit 4 Module: vtkBalloonWidget.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 vtkBalloonWidget 17 * @brief popup text balloons above instance of vtkProp when hovering occurs 18 * 19 * The vtkBalloonWidget is used to popup text and/or an image when the mouse 20 * hovers over an instance of vtkProp. The widget keeps track of 21 * (vtkProp,vtkBalloon) pairs (where the internal vtkBalloon class is defined 22 * by a pair of vtkStdString and vtkImageData), and when the mouse stops 23 * moving for a user-specified period of time over the vtkProp, then the 24 * vtkBalloon is drawn nearby the vtkProp. Note that an instance of 25 * vtkBalloonRepresentation is used to draw the balloon. 26 * 27 * To use this widget, specify an instance of vtkBalloonWidget and a 28 * representation (e.g., vtkBalloonRepresentation). Then list all instances 29 * of vtkProp, a text string, and/or an instance of vtkImageData to be 30 * associated with each vtkProp. (Note that you can specify both text and an 31 * image, or just one or the other.) You may also wish to specify the hover 32 * delay (i.e., set in the superclass vtkHoverWidget). 33 * 34 * @par Event Bindings: 35 * By default, the widget observes the following VTK events (i.e., it 36 * watches the vtkRenderWindowInteractor for these events): 37 * <pre> 38 * MouseMoveEvent - occurs when mouse is moved in render window. 39 * TimerEvent - occurs when the time between events (e.g., mouse move) 40 * is greater than TimerDuration. 41 * KeyPressEvent - when the "Enter" key is pressed after the balloon appears, 42 * a callback is activated (e.g., WidgetActivateEvent). 43 * </pre> 44 * 45 * @par Event Bindings: 46 * Note that the event bindings described above can be changed using this 47 * class's vtkWidgetEventTranslator. This class translates VTK events 48 * into the vtkBalloonWidget's widget events: 49 * <pre> 50 * vtkWidgetEvent::Move -- start the timer 51 * vtkWidgetEvent::TimedOut -- when hovering occurs, 52 * vtkWidgetEvent::SelectAction -- activate any callbacks associated 53 * with the balloon. 54 * </pre> 55 * 56 * @par Event Bindings: 57 * This widget invokes the following VTK events on itself (which observers 58 * can listen for): 59 * <pre> 60 * vtkCommand::TimerEvent (when hovering is determined to occur) 61 * vtkCommand::EndInteractionEvent (after a hover has occurred and the 62 * mouse begins moving again). 63 * vtkCommand::WidgetActivateEvent (when the balloon is selected with a 64 * keypress). 65 * </pre> 66 * 67 * @sa 68 * vtkAbstractWidget 69 */ 70 71 #ifndef vtkBalloonWidget_h 72 #define vtkBalloonWidget_h 73 74 #include "vtkHoverWidget.h" 75 #include "vtkInteractionWidgetsModule.h" // For export macro 76 77 class vtkBalloonRepresentation; 78 class vtkProp; 79 class vtkAbstractPropPicker; 80 class vtkStdString; 81 class vtkPropMap; 82 class vtkImageData; 83 84 class VTKINTERACTIONWIDGETS_EXPORT vtkBalloonWidget : public vtkHoverWidget 85 { 86 public: 87 /** 88 * Instantiate this class. 89 */ 90 static vtkBalloonWidget* New(); 91 92 ///@{ 93 /** 94 * Standard methods for a VTK class. 95 */ 96 vtkTypeMacro(vtkBalloonWidget, vtkHoverWidget); 97 void PrintSelf(ostream& os, vtkIndent indent) override; 98 ///@} 99 100 /** 101 * The method for activating and deactivating this widget. This method 102 * must be overridden because it performs special timer-related operations. 103 */ 104 void SetEnabled(int) override; 105 106 /** 107 * Specify an instance of vtkWidgetRepresentation used to represent this 108 * widget in the scene. Note that the representation is a subclass of vtkProp 109 * so it can be added to the renderer independent of the widget. 110 */ SetRepresentation(vtkBalloonRepresentation * r)111 void SetRepresentation(vtkBalloonRepresentation* r) 112 { 113 this->Superclass::SetWidgetRepresentation(reinterpret_cast<vtkWidgetRepresentation*>(r)); 114 } 115 116 /** 117 * Return the representation as a vtkBalloonRepresentation. 118 */ GetBalloonRepresentation()119 vtkBalloonRepresentation* GetBalloonRepresentation() 120 { 121 return reinterpret_cast<vtkBalloonRepresentation*>(this->WidgetRep); 122 } 123 124 /** 125 * Create the default widget representation if one is not set. 126 */ 127 void CreateDefaultRepresentation() override; 128 129 ///@{ 130 /** 131 * Add and remove text and/or an image to be associated with a vtkProp. You 132 * may add one or both of them. 133 */ 134 void AddBalloon(vtkProp* prop, vtkStdString* str, vtkImageData* img); 135 void AddBalloon(vtkProp* prop, const char* str, vtkImageData* img); AddBalloon(vtkProp * prop,const char * str)136 void AddBalloon(vtkProp* prop, const char* str) // for wrapping 137 { 138 this->AddBalloon(prop, str, nullptr); 139 } 140 void RemoveBalloon(vtkProp* prop); 141 ///@} 142 143 ///@{ 144 /** 145 * Methods to retrieve the information associated with each vtkProp (i.e., 146 * the information that makes up each balloon). A nullptr will be returned if 147 * the vtkProp does not exist, or if a string or image have not been 148 * associated with the specified vtkProp. 149 */ 150 const char* GetBalloonString(vtkProp* prop); 151 vtkImageData* GetBalloonImage(vtkProp* prop); 152 ///@} 153 154 ///@{ 155 /** 156 * Update the balloon string or image. If the specified prop does not exist, 157 * then nothing is added not changed. 158 */ 159 void UpdateBalloonString(vtkProp* prop, const char* str); 160 void UpdateBalloonImage(vtkProp* prop, vtkImageData* image); 161 ///@} 162 163 /** 164 * Return the current vtkProp that is being hovered over. Note that the 165 * value may be nullptr (if hovering over nothing or the mouse is moving). 166 */ GetCurrentProp()167 virtual vtkProp* GetCurrentProp() { return this->CurrentProp; } 168 169 ///@{ 170 /** 171 * Set/Get the object used to perform pick operations. Since the 172 * vtkBalloonWidget operates on vtkProps, the picker must be a subclass of 173 * vtkAbstractPropPicker. (Note: if not specified, an instance of 174 * vtkPropPicker is used.) 175 */ 176 void SetPicker(vtkAbstractPropPicker*); 177 vtkGetObjectMacro(Picker, vtkAbstractPropPicker); 178 ///@} 179 180 /* 181 * Register internal Pickers within PickingManager 182 */ 183 void RegisterPickers() override; 184 185 protected: 186 vtkBalloonWidget(); 187 ~vtkBalloonWidget() override; 188 189 // This class implements the method called from its superclass. 190 int SubclassEndHoverAction() override; 191 int SubclassHoverAction() override; 192 193 // Classes for managing balloons 194 vtkPropMap* PropMap; // PIMPL'd map of (vtkProp,vtkStdString) 195 196 // Support for picking 197 vtkAbstractPropPicker* Picker; 198 199 // The vtkProp that is being hovered over (which may be nullptr) 200 vtkProp* CurrentProp; 201 202 private: 203 vtkBalloonWidget(const vtkBalloonWidget&) = delete; 204 void operator=(const vtkBalloonWidget&) = delete; 205 }; 206 207 #endif 208