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 { Outside=0, Nearby, Selecting, Translating, Scaling };
109 
110   //@{
111   /**
112    * The interaction state may be set from a widget (e.g., HandleWidget) or
113    * other object. This controls how the interaction with the widget
114    * proceeds. Normally this method is used as part of a handshaking
115    * processwith the widget: First ComputeInteractionState() is invoked that
116    * returns a state based on geometric considerations (i.e., cursor near a
117    * widget feature), then based on events, the widget may modify this
118    * further.
119    */
120   vtkSetClampMacro(InteractionState,int,Outside,Scaling);
121   //@}
122 
123   //@{
124   /**
125    * Specify whether any motions (such as scale, translate, etc.) are
126    * constrained in some way (along an axis, etc.) Widgets can use this
127    * to control the resulting motion.
128    */
129   vtkSetMacro(Constrained,vtkTypeBool);
130   vtkGetMacro(Constrained,vtkTypeBool);
131   vtkBooleanMacro(Constrained,vtkTypeBool);
132   //@}
133 
134   /**
135    * Method has to be overridden in the subclasses which has
136    * constraints on placing the handle
137    * (Ex. vtkConstrainedPointHandleRepresentation). It should return 1
138    * if the position is within the constraint, else it should return
139    * 0. By default it returns 1.
140    */
141   virtual int CheckConstraint(vtkRenderer *renderer, double pos[2]);
142 
143   //@{
144   /**
145    * Methods to make this class properly act like a vtkWidgetRepresentation.
146    */
147   void ShallowCopy(vtkProp *prop) override;
148   virtual void DeepCopy(vtkProp *prop);
149   void SetRenderer(vtkRenderer *ren) override;
150   //@}
151 
152   /**
153    * Overload the superclasses' GetMTime() because the internal vtkCoordinates
154    * are used to keep the state of the representation.
155    */
156   vtkMTimeType GetMTime() override;
157 
158   //@{
159   /**
160    * Set/Get the point placer. Point placers can be used to dictate constraints
161    * on the placement of handles. As an example, see vtkBoundedPlanePointPlacer
162    * (constrains the placement of handles to a set of bounded planes)
163    * vtkFocalPlanePointPlacer (constrains placement on the focal plane) etc.
164    * The default point placer is vtkPointPlacer (which does not apply any
165    * constraints, so the handles are free to move anywhere).
166    */
167   virtual void SetPointPlacer ( vtkPointPlacer * );
168   vtkGetObjectMacro( PointPlacer, vtkPointPlacer );
169   //@}
170 
171 protected:
172   vtkHandleRepresentation();
173   ~vtkHandleRepresentation() override;
174 
175   int Tolerance;
176   vtkTypeBool ActiveRepresentation;
177   vtkTypeBool Constrained;
178 
179   // Two vtkCoordinates are available to subclasses, one in display
180   // coordinates and the other in world coordinates. These facilitate
181   // the conversion between these two systems. Note that the WorldPosition
182   // is the ultimate maintainer of position.
183   vtkCoordinate *DisplayPosition;
184   vtkCoordinate *WorldPosition;
185 
186   // Keep track of when coordinates were changed
187   vtkTimeStamp DisplayPositionTime;
188   vtkTimeStamp WorldPositionTime;
189 
190   // Constrain the placement of handles.
191   vtkPointPlacer * PointPlacer;
192 
193 private:
194   vtkHandleRepresentation(const vtkHandleRepresentation&) = delete;
195   void operator=(const vtkHandleRepresentation&) = delete;
196 };
197 
198 #endif
199