1 /*========================================================================= 2 3 Program: Visualization Toolkit 4 Module: vtkObject.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 vtkObject 17 * @brief abstract base class for most VTK objects 18 * 19 * vtkObject is the base class for most objects in the visualization 20 * toolkit. vtkObject provides methods for tracking modification time, 21 * debugging, printing, and event callbacks. Most objects created 22 * within the VTK framework should be a subclass of vtkObject or one 23 * of its children. The few exceptions tend to be very small helper 24 * classes that usually never get instantiated or situations where 25 * multiple inheritance gets in the way. vtkObject also performs 26 * reference counting: objects that are reference counted exist as 27 * long as another object uses them. Once the last reference to a 28 * reference counted object is removed, the object will spontaneously 29 * destruct. 30 * 31 * @warning 32 * Note: in VTK objects should always be created with the New() method 33 * and deleted with the Delete() method. VTK objects cannot be 34 * allocated off the stack (i.e., automatic objects) because the 35 * constructor is a protected method. 36 * 37 * @sa 38 * vtkCommand vtkTimeStamp 39 */ 40 41 #ifndef vtkObject_h 42 #define vtkObject_h 43 44 #include "vtkCommonCoreModule.h" // For export macro 45 #include "vtkObjectBase.h" 46 #include "vtkSetGet.h" 47 #include "vtkTimeStamp.h" 48 #include "vtkWeakPointerBase.h" // needed for vtkWeakPointer 49 50 class vtkSubjectHelper; 51 class vtkCommand; 52 53 class VTKCOMMONCORE_EXPORT vtkObject : public vtkObjectBase 54 { 55 public: 56 vtkBaseTypeMacro(vtkObject,vtkObjectBase); 57 58 /** 59 * Create an object with Debug turned off, modified time initialized 60 * to zero, and reference counting on. 61 */ 62 static vtkObject *New(); 63 64 #ifdef _WIN32 65 // avoid dll boundary problems 66 void* operator new( size_t tSize ); 67 void operator delete( void* p ); 68 #endif 69 70 /** 71 * Turn debugging output on. 72 */ 73 virtual void DebugOn(); 74 75 /** 76 * Turn debugging output off. 77 */ 78 virtual void DebugOff(); 79 80 /** 81 * Get the value of the debug flag. 82 */ 83 bool GetDebug(); 84 85 /** 86 * Set the value of the debug flag. A true value turns debugging on. 87 */ 88 void SetDebug(bool debugFlag); 89 90 /** 91 * This method is called when vtkErrorMacro executes. It allows 92 * the debugger to break on error. 93 */ 94 static void BreakOnError(); 95 96 /** 97 * Update the modification time for this object. Many filters rely on 98 * the modification time to determine if they need to recompute their 99 * data. The modification time is a unique monotonically increasing 100 * unsigned long integer. 101 */ 102 virtual void Modified(); 103 104 /** 105 * Return this object's modified time. 106 */ 107 virtual vtkMTimeType GetMTime(); 108 109 /** 110 * Methods invoked by print to print information about the object 111 * including superclasses. Typically not called by the user (use 112 * Print() instead) but used in the hierarchical print process to 113 * combine the output of several classes. 114 */ 115 void PrintSelf(ostream& os, vtkIndent indent) override; 116 117 //@{ 118 /** 119 * This is a global flag that controls whether any debug, warning 120 * or error messages are displayed. 121 */ 122 static void SetGlobalWarningDisplay(int val); GlobalWarningDisplayOn()123 static void GlobalWarningDisplayOn(){vtkObject::SetGlobalWarningDisplay(1);}; GlobalWarningDisplayOff()124 static void GlobalWarningDisplayOff() 125 {vtkObject::SetGlobalWarningDisplay(0);}; 126 static int GetGlobalWarningDisplay(); 127 //@} 128 129 //@{ 130 /** 131 * Allow people to add/remove/invoke observers (callbacks) to any VTK 132 * object. This is an implementation of the subject/observer design 133 * pattern. An observer is added by specifying an event to respond to 134 * and a vtkCommand to execute. It returns an unsigned long tag which 135 * can be used later to remove the event or retrieve the command. 136 * When events are invoked, the observers are called in the order they 137 * were added. If a priority value is specified, then the higher 138 * priority commands are called first. A command may set an abort 139 * flag to stop processing of the event. (See vtkCommand.h for more 140 * information.) 141 */ 142 unsigned long AddObserver(unsigned long event, vtkCommand *, 143 float priority=0.0f); 144 unsigned long AddObserver(const char *event, vtkCommand *, 145 float priority=0.0f); 146 vtkCommand *GetCommand(unsigned long tag); 147 void RemoveObserver(vtkCommand*); 148 void RemoveObservers(unsigned long event, vtkCommand *); 149 void RemoveObservers(const char *event, vtkCommand *); 150 vtkTypeBool HasObserver(unsigned long event, vtkCommand *); 151 vtkTypeBool HasObserver(const char *event, vtkCommand *); 152 //@} 153 154 void RemoveObserver(unsigned long tag); 155 void RemoveObservers(unsigned long event); 156 void RemoveObservers(const char *event); 157 void RemoveAllObservers(); //remove every last one of them 158 vtkTypeBool HasObserver(unsigned long event); 159 vtkTypeBool HasObserver(const char *event); 160 161 //@{ 162 /** 163 * Overloads to AddObserver that allow developers to add class member 164 * functions as callbacks for events. The callback function can 165 * be one of these two types: 166 * \code 167 * void foo(void);\n 168 * void foo(vtkObject*, unsigned long, void*); 169 * \endcode 170 * If the callback is a member of a vtkObjectBase-derived object, 171 * then the callback will automatically be disabled if the object 172 * destructs (but the observer will not automatically be removed). 173 * If the callback is a member of any other type of object, then 174 * the observer must be removed before the object destructs or else 175 * its dead pointer will be used the next time the event occurs. 176 * Typical usage of these functions is as follows: 177 * \code 178 * SomeClassOfMine* observer = SomeClassOfMine::New();\n 179 * to_observe->AddObserver(event, observer, \&SomeClassOfMine::SomeMethod); 180 * \endcode 181 * Note that this does not affect the reference count of a 182 * vtkObjectBase-derived \c observer, which can be safely deleted 183 * with the observer still in place. For non-vtkObjectBase observers, 184 * the observer should never be deleted before it is removed. 185 * Return value is a tag that can be used to remove the observer. 186 */ 187 template <class U, class T> 188 unsigned long AddObserver(unsigned long event, 189 U observer, void (T::*callback)(), float priority=0.0f) 190 { 191 vtkClassMemberCallback<T> *callable = 192 new vtkClassMemberCallback<T>(observer, callback); 193 // callable is deleted when the observer is cleaned up (look at 194 // vtkObjectCommandInternal) 195 return this->AddTemplatedObserver(event, callable, priority); 196 } 197 template <class U, class T> 198 unsigned long AddObserver(unsigned long event, 199 U observer, void (T::*callback)(vtkObject*, unsigned long, void*), 200 float priority=0.0f) 201 { 202 vtkClassMemberCallback<T> *callable = 203 new vtkClassMemberCallback<T>(observer, callback); 204 // callable is deleted when the observer is cleaned up (look at 205 // vtkObjectCommandInternal) 206 return this->AddTemplatedObserver(event, callable, priority); 207 } 208 //@} 209 210 //@{ 211 /** 212 * Allow user to set the AbortFlagOn() with the return value of the callback 213 * method. 214 */ 215 template <class U, class T> 216 unsigned long AddObserver(unsigned long event, 217 U observer, bool (T::*callback)(vtkObject*, unsigned long, void*), 218 float priority=0.0f) 219 { 220 vtkClassMemberCallback<T> *callable = 221 new vtkClassMemberCallback<T>(observer, callback); 222 // callable is deleted when the observer is cleaned up (look at 223 // vtkObjectCommandInternal) 224 return this->AddTemplatedObserver(event, callable, priority); 225 } 226 //@} 227 228 //@{ 229 /** 230 * This method invokes an event and return whether the event was 231 * aborted or not. If the event was aborted, the return value is 1, 232 * otherwise it is 0. 233 */ 234 int InvokeEvent(unsigned long event, void *callData); 235 int InvokeEvent(const char *event, void *callData); 236 //@} 237 InvokeEvent(unsigned long event)238 int InvokeEvent(unsigned long event) { return this->InvokeEvent(event, nullptr); }; InvokeEvent(const char * event)239 int InvokeEvent(const char *event) { return this->InvokeEvent(event, nullptr); }; 240 241 protected: 242 vtkObject(); 243 ~vtkObject() override; 244 245 // See vtkObjectBase.h. 246 void RegisterInternal(vtkObjectBase*, vtkTypeBool check) override; 247 void UnRegisterInternal(vtkObjectBase*, vtkTypeBool check) override; 248 249 bool Debug; // Enable debug messages 250 vtkTimeStamp MTime; // Keep track of modification time 251 vtkSubjectHelper *SubjectHelper; // List of observers on this object 252 253 //@{ 254 /** 255 * These methods allow a command to exclusively grab all events. (This 256 * method is typically used by widgets to grab events once an event 257 * sequence begins.) These methods are provided in support of the 258 * public methods found in the class vtkInteractorObserver. Note that 259 * these methods are designed to support vtkInteractorObservers since 260 * they use two separate vtkCommands to watch for mouse and keypress events. 261 */ 262 void InternalGrabFocus(vtkCommand *mouseEvents, vtkCommand *keypressEvents=nullptr); 263 void InternalReleaseFocus(); 264 //@} 265 266 private: 267 vtkObject(const vtkObject&) = delete; 268 void operator=(const vtkObject&) = delete; 269 270 /** 271 * Following classes (vtkClassMemberCallbackBase, 272 * vtkClassMemberCallback, and vtkClassMemberHanderPointer) 273 * along with vtkObjectCommandInternal are for supporting 274 * templated AddObserver() overloads that allow developers 275 * to add event callbacks that are class member functions. 276 */ 277 class vtkClassMemberCallbackBase 278 { 279 public: 280 //@{ 281 /** 282 * Called when the event is invoked 283 */ 284 virtual bool operator()(vtkObject*, unsigned long, void*) = 0; ~vtkClassMemberCallbackBase()285 virtual ~vtkClassMemberCallbackBase(){} 286 }; 287 //@} 288 289 //@{ 290 /** 291 * This is a weak pointer for vtkObjectBase and a regular 292 * void pointer for everything else 293 */ 294 template<class T> 295 class vtkClassMemberHandlerPointer 296 { 297 public: 298 void operator=(vtkObjectBase *o) 299 { 300 // The cast is needed in case "o" has multi-inheritance, 301 // to offset the pointer to get the vtkObjectBase. 302 if ((this->VoidPointer = dynamic_cast<T*>(o)) == nullptr) 303 { 304 // fallback to just using its vtkObjectBase as-is. 305 this->VoidPointer = o; 306 } 307 this->WeakPointer = o; 308 this->UseWeakPointer = true; 309 } 310 void operator=(void *o) 311 { 312 this->VoidPointer = o; 313 this->WeakPointer = nullptr; 314 this->UseWeakPointer = false; 315 } GetPointer()316 T *GetPointer() 317 { 318 if (this->UseWeakPointer && !this->WeakPointer.GetPointer()) 319 { 320 return nullptr; 321 } 322 return static_cast<T*>(this->VoidPointer); 323 } 324 private: 325 vtkWeakPointerBase WeakPointer; 326 void *VoidPointer; 327 bool UseWeakPointer; 328 }; 329 //@} 330 331 //@{ 332 /** 333 * Templated member callback. 334 */ 335 template <class T> 336 class vtkClassMemberCallback : public vtkClassMemberCallbackBase 337 { 338 vtkClassMemberHandlerPointer<T> Handler; 339 void (T::*Method1)(); 340 void (T::*Method2)(vtkObject*, unsigned long, void*); 341 bool (T::*Method3)(vtkObject*, unsigned long, void*); 342 //@} 343 344 public: vtkClassMemberCallback(T * handler,void (T::* method)())345 vtkClassMemberCallback(T* handler, void (T::*method)()) 346 { 347 this->Handler = handler; 348 this->Method1 = method; 349 this->Method2 = nullptr; 350 this->Method3 = nullptr; 351 } 352 vtkClassMemberCallback(T * handler,void (T::* method)(vtkObject *,unsigned long,void *))353 vtkClassMemberCallback( 354 T* handler, void (T::*method)(vtkObject*, unsigned long, void*)) 355 { 356 this->Handler = handler; 357 this->Method1 = nullptr; 358 this->Method2 = method; 359 this->Method3 = nullptr; 360 } 361 vtkClassMemberCallback(T * handler,bool (T::* method)(vtkObject *,unsigned long,void *))362 vtkClassMemberCallback( 363 T* handler, bool (T::*method)(vtkObject*, unsigned long, void*)) 364 { 365 this->Handler = handler; 366 this->Method1 = nullptr; 367 this->Method2 = nullptr; 368 this->Method3 = method; 369 } ~vtkClassMemberCallback()370 ~vtkClassMemberCallback() override { } 371 372 // Called when the event is invoked operator()373 bool operator()( 374 vtkObject* caller, unsigned long event, void* calldata) override 375 { 376 T *handler = this->Handler.GetPointer(); 377 if (handler) 378 { 379 if (this->Method1) 380 { 381 (handler->*this->Method1)(); 382 } 383 else if (this->Method2) 384 { 385 (handler->*this->Method2)(caller, event, calldata); 386 } 387 else if (this->Method3) 388 { 389 return (handler->*this->Method3)(caller, event, calldata); 390 } 391 } 392 return false; 393 } 394 }; 395 396 //@{ 397 /** 398 * Called by templated variants of AddObserver. 399 */ 400 unsigned long AddTemplatedObserver( 401 unsigned long event, vtkClassMemberCallbackBase* callable, float priority); 402 // Friend to access AddTemplatedObserver(). 403 friend class vtkObjectCommandInternal; 404 //@} 405 406 }; 407 408 #endif 409 // VTK-HeaderTest-Exclude: vtkObject.h 410