KWWidgets
vtkKWObject.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Module: $RCSfile: vtkKWObject.h,v $
4 
5  Copyright (c) Kitware, Inc.
6  All rights reserved.
7  See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
8 
9  This software is distributed WITHOUT ANY WARRANTY; without even
10  the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
11  PURPOSE. See the above copyright notice for more information.
12 
13 =========================================================================*/
14 // .NAME vtkKWObject - Superclass that supports basic Tcl functionality
15 // .SECTION Description
16 // vtkKWObject is the superclass for most application classes.
17 // It is a direct subclass of vtkObject but adds functionality for
18 // invoking Tcl scripts, obtaining the Tcl name for an instance, etc.
19 // This class requires a vtkKWApplication in order to work (as do all classes).
20 // .SECTION See Also
21 // vtkKWApplication
22 
23 #ifndef __vtkKWObject_h
24 #define __vtkKWObject_h
25 
26 #include "vtkObject.h"
27 
28 #include "vtkTcl.h" // Needed for Tcl interpreter
29 #include "vtkKWWidgets.h" // Needed for export symbols directives
30 
31 class vtkKWApplication;
32 class vtkCallbackCommand;
33 
34 class KWWidgets_EXPORT vtkKWObject : public vtkObject
35 {
36 public:
37  static vtkKWObject* New();
38  vtkTypeRevisionMacro(vtkKWObject,vtkObject);
39  void PrintSelf(ostream& os, vtkIndent indent);
40 
41  // Description:
42  // Get the name of the Tcl object this instance represents.
43  const char *GetTclName();
44 
45  // Description:
46  // Set/Get the application instance for this object.
47  vtkGetObjectMacro(Application,vtkKWApplication);
48  virtual void SetApplication (vtkKWApplication* arg);
49 
50  //BTX
51  // Description:
52  // Invoke some Tcl script code and perform argument substitution.
53  virtual const char* Script(const char *EventString, ...);
54  //ETX
55 
56  // Description:
57  // Add/Remove a callback command observer.
58  // This AddCallbackCommandObserver() method makes sure the
59  // CallbackCommand object is setup properly, then add an observer on
60  // 'object', if it does not exist already. This observer is triggered by
61  // 'event' and will invoke the CallbackCommand's Execute() method.
62  // This method is prefered over the vtkObject::AddObserver method as
63  // it takes care of initializing CallbackCommand, and eventually keep
64  // track of observers that have been added, so that they can be removed
65  // properly using RemoveCallbackCommandObserver(s).
66  // Listeners (i.e. classes that add observers) can process the events
67  // sent by the object/observer pairs by re-implementing the protected
68  // ProcessCallbackCommandEvents virtual method.
69  virtual void AddCallbackCommandObserver(
70  vtkObject *object, unsigned long event);
71  virtual void RemoveCallbackCommandObserver(
72  vtkObject *object, unsigned long event);
73 
74  // Description:
75  // Add all the default observers needed by that object, or remove
76  // all the observers that were added through AddCallbackCommandObservers.
77  // Subclasses can override these methods to add/remove their own default
78  // observers, but should call the superclass too.
79  // Note that RemoveCallbackCommandObservers should not remove *all* the
80  // observers that were added using AddCallbackCommandObserver, but only
81  // the ones that were added in AddCallbackCommandObservers (i.e. they
82  // are symmetrical methods).
83  virtual void AddCallbackCommandObservers() {};
84  virtual void RemoveCallbackCommandObservers();
85 
86 protected:
87  vtkKWObject();
88  ~vtkKWObject();
89 
90  // Description:
91  // Convenience method that can be used to create a Tcl callback command.
92  // The 'command' argument is a pointer to the command to be created.
93  // The 'object' argument is the object that will have the method called on
94  // it. The 'method' argument is the name of the method to be called and any
95  // arguments in string form. If the object is NULL, the method is still
96  // evaluated as a simple command.
97  // Note that 'command' is allocated automatically using the 'new'
98  // operator. If it is not NULL, it is deallocated first using 'delete []'.
99  virtual void SetObjectMethodCommand(
100  char **command, vtkObject *object, const char *method);
101 
102  // Description:
103  // Convenience method to invoke a Tcl callback command that was created
104  // using the SetObjectMethodCommand method. This simply checks if the
105  // command is not empty and evaluate it from Tcl.
106  virtual void InvokeObjectMethodCommand(const char *command);
107 
108  // Description:
109  // Get the callback command.
110  // Its ClientData is set to this vtkKWObject instance
111  // itself, do not change it. Its Execute() method calls the static
112  // ProcessCallbackCommandEventsFunction method, passing it its ClientData,
113  // which in turn is converted back to a vtkKWObject pointer. The virtual
114  // ProcessCallbackCommandEvents method is invokved on that pointer.
115  // Subclasses can override this method to set specific flags, like
116  // the AbortFlagOnExecute flag.
117  virtual vtkCallbackCommand* GetCallbackCommand();
118 
119  // Description:
120  // Processes the events that are passed through CallbackCommand (or others).
121  // Subclasses can override this method to process their own events, but
122  // should call the superclass too.
123  // Also check AddCallbackCommandObserver and RemoveCallbackCommandObserver.
124  virtual void ProcessCallbackCommandEvents(
125  vtkObject *caller, unsigned long event, void *calldata);
126 
127  // Description:
128  // Static callback function that is invoked by the
129  // CallbackCommand's Execute() method. It converts its clientdata back to
130  // a vtkKWObject pointer and invoke its virtual
131  // ProcessCallbackCommandEvents method. Subclass should *not* reimplement
132  // this method, but the virtual ProcessCallbackCommandEvents instead.
133  static void ProcessCallbackCommandEventsFunction(
134  vtkObject *object, unsigned long event, void *clientdata, void *calldata);
135 
136 private:
137 
138  vtkKWApplication *Application;
139  char *TclName;
140 
141  // Description:
142  // The callback command. In private, so that GetCallbackCommand() can be
143  // used to lazy allocate it.
144  vtkCallbackCommand *CallbackCommand;
145 
146  vtkKWObject(const vtkKWObject&); // Not implemented
147  void operator=(const vtkKWObject&); // Not implemented
148 };
149 
150 #endif
151