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