vtkCommand.h 14.4 KB
Newer Older
Ken Martin's avatar
Ken Martin committed
1
2
3
4
5
/*=========================================================================

  Program:   Visualization Toolkit
  Module:    vtkCommand.h

6
  Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
7
8
  All rights reserved.
  See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
Ken Martin's avatar
Ken Martin committed
9

10
11
     This software is distributed WITHOUT ANY WARRANTY; without even
     the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
12
     PURPOSE.  See the above copyright notice for more information.
Ken Martin's avatar
Ken Martin committed
13
14

=========================================================================*/
15
// .NAME vtkCommand - superclass for callback/observer methods
Ken Martin's avatar
Ken Martin committed
16
// .SECTION Description
17
18
// vtkCommand is an implementation of the observer/command design
// pattern.  In this design pattern, any instance of vtkObject can be
19
// "observed" for any events it might invoke. For example,
20
21
22
23
24
25
26
27
28
// vtkRenderer invokes a StartEvent as it begins to render and a
// EndEvent when it finishes rendering. Filters (subclasses of
// vtkProcessObject) invoke StartEvent, ProgressEvent, and EndEvent as
// the filter processes data. Observers of events are added with the
// AddObserver() method found in vtkObject.  AddObserver(), besides
// requiring an event id or name, also takes an instance of vtkCommand
// (or a subclasses). Note that vtkCommand is meant to be subclassed,
// so that you can package the information necessary to support your
// callback.
Will Schroeder's avatar
Will Schroeder committed
29
//
30
31
32
33
34
35
36
37
38
// Event processing can be organized in priority lists, so it is
// possible to truncate the processing of a particular event by
// setting the AbortFlag variable. The priority is set using the
// AddObserver() method.  By default the priority is 0, events of the
// same priority are processed in last-in-first-processed order. The
// ordering/aborting of events is important for things like 3D
// widgets, which handle an event if the widget is selected (and then
// aborting further processing of that event).  Otherwise. the event
// is passed along for further processing.
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
//
// When an instance of vtkObject invokes an event, it also passes an optional
// void pointer to a callData. This callData is NULL most of the time.
// The callData is not specific to a type of event but specific to a type
// of vtkObject invoking a specific event. For instance, vtkCommand::PickEvent
// is invoked by vtkProp with a NULL callData but is invoked by
// vtkInteractorStyleImage with a pointer to the vtkInteractorStyleImage object
// itself.
//
// Here is the list of events that may be invoked with a none NULL callData.
// - vtkCommand::ProgressEvent
//  - most of the objects return a pointer to a double value ranged between
// 0.0 and 1.0
//  - Infovis/vtkFixedWidthTextReader returns a pointer to a float value equal
// to the number of lines read so far.
// - vtkCommand::ErrorEvent
//  - an error message as a const char * string
// - vtkCommand::WarningEvent
//  - a warning message as a const char * string
// - vtkCommand::StartAnimationCueEvent
//  - a pointer to a vtkAnimationCue::AnimationCueInfo object
// - vtkCommand::EndAnimationCueEvent
//  - a pointer to a vtkAnimationCue::AnimationCueInfo object
// - vtkCommand::AnimationCueTickEvent
//  - a pointer to a vtkAnimationCue::AnimationCueInfo object
// - vtkCommand::PickEvent
//  - Common/vtkProp returns NULL
//  - Rendering/vtkInteractorStyleImage returns a pointer to itself
// - vtkCommand::StartPickEvent
//  - Rendering/vtkPropPicker returns NULL
//  - Rendering/vtkInteractorStyleImage returns a pointer to itself
// - vtkCommand::EndPickEvent
//  - Rendering/vtkPropPicker returns NULL
//  - Rendering/vtkInteractorStyleImage returns a pointer to itself
// - vtkCommand::WrongTagEvent
//  - Parallel/vtkSocketCommunicator returns a received tag as a char *
// - vtkCommand::SelectionChangedEvent
//  - Views/vtkView returns NULL
//  - Views/vtkDataRepresentation returns a pointer to a vtkSelection
//  - Rendering/vtkInteractorStyleRubberBand2D returns an array of 5 unsigned
79
80
81
// integers (p1x, p1y, p2x, p2y, mode), where mode is
// vtkInteractorStyleRubberBand2D::SELECT_UNION or
// vtkInteractorStyleRubberBand2D::SELECT_NORMAL
82
83
84
// - vtkCommand::AnnotationChangedEvent
//  - GUISupport/Qt/vtkQtAnnotationView returns a pointer to a 
// vtkAnnotationLayers
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
// - vtkCommand::PlacePointEvent
//  - Widgets/vtkSeedWidget returns a pointer to an int, being the current
// handle number
// - vtkCommand::ResetWindowLevelEvent
//  - Widgets/vtkImagePlaneWidget returns an array of 2 double values (window
// and level)
//  - Rendering/vtkInteractorStyleImage returns a pointer to itself
// - vtkCommand::StartWindowLevelEvent
//  - Widgets/vtkImagePlaneWidget returns an array of 2 double values (window
// and level)
//  - Rendering/vtkInteractorStyleImage returns a pointer to itself
// - vtkCommand::EndWindowLevelEvent
//  - Widgets/vtkImagePlaneWidget returns an array of 2 double values (window
// and level)
//  - Rendering/vtkInteractorStyleImage returns a pointer to itself
// - vtkCommand::WindowLevelEvent
//  - Widgets/vtkImagePlaneWidget returns an array of 2 double values (window
// and level)
//  - Rendering/vtkInteractorStyleImage returns a pointer to itself
// - vtkCommand::CharEvent
//  - most of the objects return NULL
//  - GUISupport/Qt/QVTKWidget returns a QKeyEvent *
// - vtkCommand::TimerEvent
//  - most of the objects return a to an int representing a timer id
//  - Rendering/vtkXRenderWindowTclInteractor returns NULL
//  - Widgets/vtkHoverWidget returns NULL
// - vtkCommand::CreateTimerEvent
//  - Rendering/vtkGenericRenderWindowInteractor returns a to an int
// representing a timer id
// - vtkCommand::DestroyTimerEvent
//  - Rendering/vtkGenericRenderWindowInteractor returns a to an int
// representing a timer id
// - vtkCommand::UserEvent
//  - most of the objects return NULL
//  - Infovis/vtkInteractorStyleTreeMapHover returns a pointer to a vtkIdType
// representing a pedigree id
// - vtkCommand::KeyPressEvent
//  - most of the objects return NULL
//  - GUISupport/Qt/QVTKWidget returns a QKeyEvent*
// - vtkCommand::KeyReleaseEvent
//  - most of the objects return NULL
//  - GUISupport/Qt/QVTKWidget returns a QKeyEvent*
// - vtkCommand::LeftButtonPressEvent
//  - most of the objects return NULL
//  - GUISupport/Qt/QVTKWidget returns a QMouseEvent*
// - vtkCommand::LeftButtonReleaseEvent
//  - most of the objects return NULL
//  - GUISupport/Qt/QVTKWidget returns a QMouseEvent*
// - vtkCommand::MouseMoveEvent
//  - most of the objects return NULL
//  - GUISupport/Qt/QVTKWidget returns a QMouseEvent*
// - vtkCommand::MouseWheelForwardEvent
//  - most of the objects return NULL
//  - GUISupport/Qt/QVTKWidget returns a QWheelEvent*
// - vtkCommand::MouseWheelBackwardEvent
//  - most of the objects return NULL
//  - GUISupport/Qt/QVTKWidget returns a QWheelEvent*
// - vtkCommand::RightButtonPressEvent
//  - most of the objects return NULL
//  - GUISupport/Qt/QVTKWidget returns a QMouseEvent*
// - vtkCommand::RightButtonReleaseEvent
//  - most of the objects return NULL
//  - GUISupport/Qt/QVTKWidget returns a QMouseEvent*
// - vtkCommand::MiddleButtonPressEvent
//  - most of the objects return NULL
//  - GUISupport/Qt/QVTKWidget returns a QMouseEvent*
// - vtkCommand::MiddleButtonReleaseEvent
//  - most of the objects return NULL
//  - GUISupport/Qt/QVTKWidget returns a QMouseEvent*
// - vtkCommand::CursorChangedEvent
//  - most of the objects return a pointer to an int representing a shape
//  - Rendering/vtkInteractorObserver returns NULL
// - vtkCommand::ResetCameraEvent
//  - Rendering/vtkRenderer returns a pointer to itself
// - vtkCommand::ResetCameraClippingRangeEvent
//  - Rendering/vtkRenderer returns a pointer to itself
161
162
163
164
// - vtkCommand::ActiveCameraEvent
//  - Rendering/vtkRenderer returns a pointer to the active camera
// - vtkCommand::CreateCameraEvent
//  - Rendering/vtkRenderer returns a pointer to the created camera
165
166
167
168
169
170
171
172
// - vtkCommand::EnterEvent
//  - most of the objects return NULL
//  - GUISupport/Qt/QVTKWidget returns a QEvent*
// - vtkCommand::LeaveEvent
//  - most of the objects return NULL
//  - GUISupport/Qt/QVTKWidget returns a QEvent*
// - vtkCommand::RenderWindowMessageEvent
//  - Rendering/vtkWin32OpenGLRenderWindow return a pointer to a UINT message
173
174
// - vtkCommand::ComputeVisiblePropBoundsEvent
//  - Rendering/vtkRenderer returns a pointer to itself
175
176
177
178
179
180
181
182
183
184
// - QVTKWidget::ContextMenuEvent
//  - GUISupport/Qt/QVTKWidget returns a QContextMenuEvent*
// - QVTKWidget::DragEnterEvent
//  - GUISupport/Qt/QVTKWidget returns a QDragEnterEvent*
// - QVTKWidget::DragMoveEvent
//  - GUISupport/Qt/QVTKWidget returns a QDragMoveEvent*
// - QVTKWidget::DragLeaveEvent
//  - GUISupport/Qt/QVTKWidget returns a QDragLeaveEvent*
// - QVTKWidget::DropEvent
//  - GUISupport/Qt/QVTKWidget returns a QDropEvent*
185
186
// - vtkCommand::ViewProgressEvent
//  - View/vtkView returns a ViewProgressEventCallData*
187
188
189
190
// - vtkCommand::VolumeMapperRenderProgressEvent
//  - A pointer to a double value between 0.0 and 1.0
// - vtkCommand::VolumeMapperComputeGradientsProgressEvent
//  - A pointer to a double value between 0.0 and 1.0
191
192
193
194
195
196
// - vtkCommand::TDxMotionEvent (TDx=3DConnexion)
//  - A vtkTDxMotionEventInfo*
// - vtkCommand::TDxButtonPressEvent
//  - A int* being the number of the button
// - vtkCommand::TDxButtonReleaseEvent
//  - A int* being the number of the button
197
//
Will Schroeder's avatar
Will Schroeder committed
198
// .SECTION See Also
199
200
// vtkObject vtkCallbackCommand vtkOldStyleCallbackCommand
// vtkInteractorObserver vtk3DWidget
Ken Martin's avatar
Ken Martin committed
201

202
203
#ifndef __vtkCommand_h
#define __vtkCommand_h
Ken Martin's avatar
Ken Martin committed
204

205
#include "vtkObjectBase.h"
206
#include "vtkObject.h" // Need vtkTypeMacro
Ken Martin's avatar
Ken Martin committed
207

208
// The superclass that all commands should be subclasses of
209
class VTK_COMMON_EXPORT vtkCommand : public vtkObjectBase
Ken Martin's avatar
Ken Martin committed
210
211
{
public:
212
213
  vtkTypeMacro(vtkCommand,vtkObjectBase);

Ken Martin's avatar
Ken Martin committed
214
215
216
217
218
  // Description:
  // Decrease the reference count (release by another object). This has
  // the same effect as invoking Delete() (i.e., it reduces the reference
  // count by 1).
  void UnRegister();
219
  virtual void UnRegister(vtkObjectBase *) 
Will Schroeder's avatar
Will Schroeder committed
220
    { this->UnRegister(); }
Ken Martin's avatar
Ken Martin committed
221
  
Will Schroeder's avatar
Will Schroeder committed
222
  // Description:
223
224
225
226
227
228
229
230
231
232
  // All derived classes of vtkCommand must implement this
  // method. This is the method that actually does the work of the
  // callback. The caller argument is the object invoking the event,
  // the eventId parameter is the id of the event, and callData
  // parameter is data that can be passed into the execute
  // method. (Note: vtkObject::InvokeEvent() takes two parameters: the
  // event id (or name) and call data. Typically call data is NULL,
  // but the user can package data and pass it this
  // way. Alternatively, a derived class of vtkCommand can be used to
  // pass data.)
233
234
  virtual void Execute(vtkObject *caller, unsigned long eventId, 
                       void *callData) = 0;
Will Schroeder's avatar
Will Schroeder committed
235
236

  // Description:
237
238
  // Convenience methods for translating between event names and event
  // ids.
239
  static const char *GetStringFromEventId(unsigned long event);
240
  static unsigned long GetEventIdFromString(const char *event);
Ken Martin's avatar
Ken Martin committed
241

242
243
244
  // Description:
  // Set/Get the abort flag. If this is set to true no further
  // commands are executed.
Will Schroeder's avatar
Will Schroeder committed
245
  void SetAbortFlag(int f)  
246
    { this->AbortFlag = f; }
Will Schroeder's avatar
Will Schroeder committed
247
  int GetAbortFlag() 
248
    { return this->AbortFlag; }
Will Schroeder's avatar
Will Schroeder committed
249
250
251
252
  void AbortFlagOn() 
    { this->SetAbortFlag(1); }
  void AbortFlagOff() 
    { this->SetAbortFlag(0); }
Bill Hoffman's avatar
Bill Hoffman committed
253
  
254
255
256
257
258
259
260
261
262
263
264
265
266
267
  // Description:
  // Set/Get the passive observer flag. If this is set to true, this
  // indicates that this command does not change the state of the
  // system in any way. Passive observers are processed first, and
  // are not called even when another command has focus.
  void SetPassiveObserver(int f)  
    { this->PassiveObserver = f; }
  int GetPassiveObserver() 
    { return this->PassiveObserver; }
  void PassiveObserverOn() 
    { this->SetPassiveObserver(1); }
  void PassiveObserverOff() 
    { this->SetPassiveObserver(0); }
  
268
//BTX
269
270
271
272
273
  // Description:
  // All the currently defined events are listed here.  Developers can
  // use -- vtkCommand::UserEvent + int to specify their own event
  // ids. If this list is adjusted, be sure to adjust
  // vtkCommandEventStrings in vtkCommand.cxx to match.
Ken Martin's avatar
Ken Martin committed
274
275
  enum EventIds {
    NoEvent = 0,
Ken Martin's avatar
Ken Martin committed
276
    AnyEvent,
Ken Martin's avatar
Ken Martin committed
277
278
279
    DeleteEvent,
    StartEvent,
    EndEvent,
Sebastien Barre's avatar
Sebastien Barre committed
280
    RenderEvent,
Ken Martin's avatar
Ken Martin committed
281
282
    ProgressEvent,
    PickEvent,
Ken Martin's avatar
Ken Martin committed
283
284
    StartPickEvent,
    EndPickEvent,
Ken Martin's avatar
Ken Martin committed
285
    AbortCheckEvent,
Ken Martin's avatar
Ken Martin committed
286
    ExitEvent,
Ken Martin's avatar
Ken Martin committed
287
288
289
290
291
292
293
294
295
296
297
    LeftButtonPressEvent,
    LeftButtonReleaseEvent,
    MiddleButtonPressEvent,
    MiddleButtonReleaseEvent,
    RightButtonPressEvent,
    RightButtonReleaseEvent,
    EnterEvent,
    LeaveEvent,
    KeyPressEvent,
    KeyReleaseEvent,
    CharEvent,
Sebastien Barre's avatar
Sebastien Barre committed
298
    ExposeEvent,
Ken Martin's avatar
Ken Martin committed
299
300
301
    ConfigureEvent,
    TimerEvent,
    MouseMoveEvent,
302
303
    MouseWheelForwardEvent,
    MouseWheelBackwardEvent,
304
305
    ActiveCameraEvent,
    CreateCameraEvent,
Charles Law's avatar
Charles Law committed
306
307
    ResetCameraEvent,
    ResetCameraClippingRangeEvent,
308
    ModifiedEvent,
Ken Martin's avatar
Ken Martin committed
309
    WindowLevelEvent,
310
311
    StartWindowLevelEvent,
    EndWindowLevelEvent,
312
    ResetWindowLevelEvent,
John Biddiscombe's avatar
John Biddiscombe committed
313
    SetOutputEvent,
314
    ErrorEvent,
Andy Cedilnik's avatar
Andy Cedilnik committed
315
    WarningEvent,
316
    StartInteractionEvent, //mainly used by vtkInteractorObservers
Will Schroeder's avatar
Will Schroeder committed
317
318
    InteractionEvent,
    EndInteractionEvent,
319
320
    EnableEvent,
    DisableEvent,
321
322
    CreateTimerEvent,
    DestroyTimerEvent,
323
    PlacePointEvent,
324
    PlaceWidgetEvent,
325
    CursorChangedEvent,
326
    ExecuteInformationEvent,
327
    RenderWindowMessageEvent,
328
    WrongTagEvent,
329
330
331
    StartAnimationCueEvent, // used by vtkAnimationCue
    AnimationCueTickEvent,
    EndAnimationCueEvent,
332
    VolumeMapperRenderEndEvent,
333
    VolumeMapperRenderProgressEvent,
334
    VolumeMapperRenderStartEvent,
335
336
337
    VolumeMapperComputeGradientsEndEvent,
    VolumeMapperComputeGradientsProgressEvent,
    VolumeMapperComputeGradientsStartEvent,
338
    WidgetModifiedEvent,
339
340
    WidgetValueChangedEvent,
    WidgetActivateEvent,
341
342
    ConnectionCreatedEvent, 
    ConnectionClosedEvent,
Berk Geveci's avatar
Berk Geveci committed
343
    DomainModifiedEvent,
344
345
    PropertyModifiedEvent,
    UpdateEvent,
346
347
    RegisterEvent,
    UnRegisterEvent,
348
    UpdateInformationEvent,
349
    AnnotationChangedEvent,
350
    SelectionChangedEvent,
351
    UpdatePropertyEvent,
352
    ViewProgressEvent,
353
    UpdateDataEvent,
354
    CurrentChangedEvent,
355
    ComputeVisiblePropBoundsEvent,
356
357
358
    TDxMotionEvent, // 3D Connexion device event
    TDxButtonPressEvent, // 3D Connexion device event
    TDxButtonReleaseEvent, // 3D Connexion device event
359
    HoverEvent,
360
361
    LoadStateEvent,
    SaveStateEvent,
362
    StateChangedEvent,
363
364
365
    WindowMakeCurrentEvent,
    WindowIsCurrentEvent,
    WindowFrameEvent,
366
    UserEvent = 1000
Ken Martin's avatar
Ken Martin committed
367
  };
368
//ETX
Will Schroeder's avatar
Will Schroeder committed
369

Ken Martin's avatar
Ken Martin committed
370
protected:
371
  int AbortFlag;
372
373
  int PassiveObserver;

374
  vtkCommand();
Will Schroeder's avatar
Will Schroeder committed
375
376
377
  virtual ~vtkCommand() {}

  friend class vtkSubjectHelper;
378
//BTX
Andy Cedilnik's avatar
Andy Cedilnik committed
379
  vtkCommand(const vtkCommand& c) : vtkObjectBase(c) {}
380
381
  void operator=(const vtkCommand&) {}
//ETX
Ken Martin's avatar
Ken Martin committed
382
383
};

384
385
#endif /* __vtkCommand_h */