1 /*=========================================================================
2 
3   Program:   Visualization Toolkit
4   Module:    vtkHandleRepresentation.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   vtkHandleRepresentation
17  * @brief   abstract class for representing widget handles
18  *
19  * This class defines an API for widget handle representations. These
20  * representations interact with vtkHandleWidget. Various representations
21  * can be used depending on the nature of the handle. The basic functionality
22  * of the handle representation is to maintain a position. The position is
23  * represented via a vtkCoordinate, meaning that the position can be easily
24  * obtained in a variety of coordinate systems.
25  *
26  * Optional features for this representation include an active mode (the widget
27  * appears only when the mouse pointer is close to it). The active distance is
28  * expressed in pixels and represents a circle in display space.
29  *
30  * The class may be subclassed so that alternative representations can
31  * be created.  The class defines an API and a default implementation that
32  * the vtkHandleWidget interacts with to render itself in the scene.
33  *
34  * @warning
35  * The separation of the widget event handling and representation enables
36  * users and developers to create new appearances for the widget. It also
37  * facilitates parallel processing, where the client application handles
38  * events, and remote representations of the widget are slaves to the
39  * client (and do not handle events).
40  *
41  * @sa
42  * vtkRectilinearWipeWidget vtkWidgetRepresentation vtkAbstractWidget
43  */
44 
45 #ifndef vtkHandleRepresentation_h
46 #define vtkHandleRepresentation_h
47 
48 #include "vtkInteractionWidgetsModule.h" // For export macro
49 #include "vtkWidgetRepresentation.h"
50 
51 class vtkCoordinate;
52 class vtkRenderer;
53 class vtkPointPlacer;
54 
55 class VTKINTERACTIONWIDGETS_EXPORT vtkHandleRepresentation : public vtkWidgetRepresentation
56 {
57 public:
58   ///@{
59   /**
60    * Standard methods for instances of this class.
61    */
62   vtkTypeMacro(vtkHandleRepresentation, vtkWidgetRepresentation);
63   void PrintSelf(ostream& os, vtkIndent indent) override;
64   ///@}
65 
66   ///@{
67   /**
68    * Handles usually have their coordinates set in display coordinates
69    * (generally by an associated widget) and internally maintain the position
70    * in world coordinates. (Using world coordinates insures that handles are
71    * rendered in the right position when the camera view changes.) These
72    * methods are often subclassed because special constraint operations can
73    * be used to control the actual positioning.
74    */
75   virtual void SetDisplayPosition(double pos[3]);
76   virtual void GetDisplayPosition(double pos[3]);
77   virtual double* GetDisplayPosition() VTK_SIZEHINT(3);
78   virtual void SetWorldPosition(double pos[3]);
79   virtual void GetWorldPosition(double pos[3]);
80   virtual double* GetWorldPosition() VTK_SIZEHINT(3);
81   ///@}
82 
83   ///@{
84   /**
85    * The tolerance representing the distance to the widget (in pixels)
86    * in which the cursor is considered near enough to the widget to
87    * be active.
88    */
89   vtkSetClampMacro(Tolerance, int, 1, 100);
90   vtkGetMacro(Tolerance, int);
91   ///@}
92 
93   ///@{
94   /**
95    * Flag controls whether the widget becomes visible when the mouse pointer
96    * moves close to it (i.e., the widget becomes active). By default,
97    * ActiveRepresentation is off and the representation is always visible.
98    */
99   vtkSetMacro(ActiveRepresentation, vtkTypeBool);
100   vtkGetMacro(ActiveRepresentation, vtkTypeBool);
101   vtkBooleanMacro(ActiveRepresentation, vtkTypeBool);
102   ///@}
103 
104   // Enums define the state of the representation relative to the mouse pointer
105   // position. Used by ComputeInteractionState() to communicate with the
106   // widget. Note that ComputeInteractionState() and several other methods
107   // must be implemented by subclasses.
108   enum _InteractionState
109   {
110     Outside = 0,
111     Nearby,
112     Selecting,
113     Translating,
114     Scaling
115   };
116 
117   ///@{
118   /**
119    * The interaction state may be set from a widget (e.g., HandleWidget) or
120    * other object. This controls how the interaction with the widget
121    * proceeds. Normally this method is used as part of a handshaking
122    * processwith the widget: First ComputeInteractionState() is invoked that
123    * returns a state based on geometric considerations (i.e., cursor near a
124    * widget feature), then based on events, the widget may modify this
125    * further.
126    */
127   vtkSetClampMacro(InteractionState, int, Outside, Scaling);
128   ///@}
129 
130   ///@{
131   /**
132    * Specify whether any motions (such as scale, translate, etc.) are
133    * constrained in some way (along an axis, etc.) Widgets can use this
134    * to control the resulting motion.
135    */
136   vtkSetMacro(Constrained, vtkTypeBool);
137   vtkGetMacro(Constrained, vtkTypeBool);
138   vtkBooleanMacro(Constrained, vtkTypeBool);
139   ///@}
140 
141   /**
142    * Method has to be overridden in the subclasses which has
143    * constraints on placing the handle
144    * (Ex. vtkConstrainedPointHandleRepresentation). It should return 1
145    * if the position is within the constraint, else it should return
146    * 0. By default it returns 1.
147    */
148   virtual int CheckConstraint(vtkRenderer* renderer, double pos[2]);
149 
150   ///@{
151   /**
152    * Methods to make this class properly act like a vtkWidgetRepresentation.
153    */
154   void ShallowCopy(vtkProp* prop) override;
155   virtual void DeepCopy(vtkProp* prop);
156   void SetRenderer(vtkRenderer* ren) override;
157   ///@}
158 
159   /**
160    * Overload the superclasses' GetMTime() because the internal vtkCoordinates
161    * are used to keep the state of the representation.
162    */
163   vtkMTimeType GetMTime() override;
164 
165   ///@{
166   /**
167    * Set/Get the point placer. Point placers can be used to dictate constraints
168    * on the placement of handles. As an example, see vtkBoundedPlanePointPlacer
169    * (constrains the placement of handles to a set of bounded planes)
170    * vtkFocalPlanePointPlacer (constrains placement on the focal plane) etc.
171    * The default point placer is vtkPointPlacer (which does not apply any
172    * constraints, so the handles are free to move anywhere).
173    */
174   virtual void SetPointPlacer(vtkPointPlacer*);
175   vtkGetObjectMacro(PointPlacer, vtkPointPlacer);
176   ///@}
177 
178   ///@{
179   /**
180    * Gets the translation vector
181    */
182   virtual void GetTranslationVector(const double* p1, const double* p2, double* v) const;
183 
184   ///@{
185   /**
186    * Translates world position by vector p1p2 projected on the constraint axis if any.
187    */
188   virtual void Translate(const double* p1, const double* p2);
189   ///@}
190 
191   ///@{
192   /**
193    * Translates world position by vector v projected on the constraint axis if any.
194    */
195   virtual void Translate(const double* v);
196   ///@}
197 
198   ///@{
199   /**
200    * Gets/Sets the constraint axis for translations. Returns Axis::NONE
201    * if none.
202    **/
203   vtkGetMacro(TranslationAxis, int);
204   vtkSetClampMacro(TranslationAxis, int, -1, 2);
205   ///@}
206 
207   ///@{
208   /**
209    * Toggles constraint translation axis on/off.
210    */
SetXTranslationAxisOn()211   void SetXTranslationAxisOn() { this->TranslationAxis = Axis::XAxis; }
SetYTranslationAxisOn()212   void SetYTranslationAxisOn() { this->TranslationAxis = Axis::YAxis; }
SetZTranslationAxisOn()213   void SetZTranslationAxisOn() { this->TranslationAxis = Axis::ZAxis; }
SetTranslationAxisOff()214   void SetTranslationAxisOff() { this->TranslationAxis = Axis::NONE; }
215   ///@}
216 
217   ///@{
218   /**
219    * Returns true if ContrainedAxis
220    **/
IsTranslationConstrained()221   bool IsTranslationConstrained() { return this->TranslationAxis != Axis::NONE; }
222   ///@}
223 
224 protected:
225   vtkHandleRepresentation();
226   ~vtkHandleRepresentation() override;
227 
228   int Tolerance;
229   vtkTypeBool ActiveRepresentation;
230   vtkTypeBool Constrained;
231 
232   // Two vtkCoordinates are available to subclasses, one in display
233   // coordinates and the other in world coordinates. These facilitate
234   // the conversion between these two systems. Note that the WorldPosition
235   // is the ultimate maintainer of position.
236   vtkCoordinate* DisplayPosition;
237   vtkCoordinate* WorldPosition;
238 
239   // Keep track of when coordinates were changed
240   vtkTimeStamp DisplayPositionTime;
241   vtkTimeStamp WorldPositionTime;
242 
243   // Constraint the placement of handles.
244   vtkPointPlacer* PointPlacer;
245 
246   // Constraint axis translation
247   int TranslationAxis;
248 
249 private:
250   vtkHandleRepresentation(const vtkHandleRepresentation&) = delete;
251   void operator=(const vtkHandleRepresentation&) = delete;
252 };
253 
254 #endif
255