KWWidgets
vtkKWWidget.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Module: $RCSfile: vtkKWWidget.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 vtkKWWidget - superclass of KW widgets
15 // .SECTION Description
16 // This class is the superclass of all UI based objects in the
17 // Kitware toolkit. It contains common methods such as specifying
18 // the parent widget, generating and returning the Tcl widget name
19 // for an instance, and managing children. It overrides the
20 // Unregister method to handle circular reference counts between
21 // child and parent widgets.
22 
23 #ifndef __vtkKWWidget_h
24 #define __vtkKWWidget_h
25 
26 #include "vtkKWObject.h"
27 
28 class vtkKWTopLevel;
30 class vtkKWWidgetInternals;
33 class vtkKWIcon;
34 
36 {
37 public:
38  static vtkKWWidget* New();
39  vtkTypeRevisionMacro(vtkKWWidget,vtkKWObject);
40  void PrintSelf(ostream& os, vtkIndent indent);
41 
42  // Description:
43  // Set/Get the parent widget for this widget.
44  // Important: you can not reparent a widget that has been Create()'ed already.
45  virtual void SetParent(vtkKWWidget *p);
46  vtkGetObjectMacro(Parent, vtkKWWidget);
47 
48  // Description:
49  // Get the application instance for this object.
50  // Override the superclass to try to retrieve the parent's application
51  // if it was not set already.
53 
54  // Description:
55  // Create the widget.
56  // The parent should be set before calling this method (see SetParent()).
57  // Once the object is fully created:
58  // - the widget is configured according to the settings found in the
59  // application's option database.
60  // - the UpdateEnableState() method is called to make sure the state
61  // of the widget and its internal sub-widgets is up-to-date.
62  // - a WidgetCreatedEvent event is sent.
63  // Subclasses should *not* re-implement this method but re-implement the
64  // protected CreateWidget() method instead.
65  virtual void Create();
66 
67  // Description:
68  // Get the name of the underlying Tk widget being used.
69  // The Create() method should be called before invoking this method.
70  // Note that setting the widget name manually is *not* recommended ; use
71  // it only if you know what you are doing, say, for example, if
72  // you have to map an external Tk widget to a vtkKWWidget object.
73  virtual const char *GetWidgetName();
74  vtkSetStringMacro(WidgetName);
75 
76  // Description:
77  // Globally Set/Get if the widget name should include the object class name.
78  // NOTE: this is a *static* method that defines the behaviour for *all*
79  // instances to be created afterwards. This is typically called in your
80  // application class or your main executable, before creating any UI.
81  // By default it is globally *disabled*.
82  static int GetUseClassNameInWidgetName();
83  static void SetUseClassNameInWidgetName(int);
84  static void UseClassNameInWidgetNameOn();
85  static void UseClassNameInWidgetNameOff();
86 
87  // Description:
88  // Query if the widget was created successfully.
89  virtual int IsCreated();
90 
91  // Description:
92  // Query if the widget is "alive" (i.e. IsCreated()) and has not been
93  // deleted as far as Tk is concerned.
94  virtual int IsAlive();
95 
96  // Description:
97  // Query if the widget is mapped (i.e, on screen)
98  virtual int IsMapped();
99 
100  // Description:
101  // Set/query focus to this widget.
102  virtual void Focus();
103  virtual int HasFocus();
104 
105  // Description:
106  // Set/Get the enabled state.
107  virtual void SetEnabled(int);
108  vtkBooleanMacro(Enabled, int);
109  vtkGetMacro(Enabled, int);
110 
111  // Description:
112  // Set/add/remove a binding to a widget, i.e. the command that is invoked
113  // whenever the 'event' is triggered on the widget.
114  // SetBinding will replace any old bindings, whereas AddBinding will
115  // add the binding to the list of bindings already defined for that event.
116  // RemoveBinding can remove a specific binding or all bindings for an event.
117  // The 'object' argument is the object that will have the method called on
118  // it. The 'method' argument is the name of the method to be called and any
119  // arguments in string form. If the object is NULL, the method is still
120  // evaluated as a simple command.
121  virtual void SetBinding(
122  const char *event, vtkObject *object, const char *method);
123  virtual void SetBinding(
124  const char *event, const char *command);
125  virtual const char* GetBinding(const char *event);
126  virtual void AddBinding(
127  const char *event, vtkObject *object, const char *method);
128  virtual void AddBinding(
129  const char *event, const char *command);
130  virtual void RemoveBinding(const char *event);
131  virtual void RemoveBinding(
132  const char *event, vtkObject *object, const char *method);
133 
134  // Description:
135  // A convenience method to add a key binding. This method does call
136  // SetBinding under the hood (which can still be used to add key bindings)
137  // but use the 'context' and 'description' to register that specific binding
138  // to an application-wide key bindings (keyboard shortcuts) manager. That
139  // manager can in turn be queried to create a list of key bindings and
140  // present it to the user (in the Help menu for example). Use this method
141  // only for important key bindings that you want the user to be reminded
142  // of. Simple bindings like <Return> on a button to allow the user
143  // to "press" said button by hitting <Return, should probably not be set
144  // with this method, but with the usual SetBinding method.
145  // 'context' is a string in plain English (or preferably localized) that
146  // explains in which context this key binding is valid. For example:
147  // "Any 2D View", or "Any Main Window". It usually is a simple/short
148  // description of the class setting the binding.
149  // 'description' is a string in plain English (or preferably localized) that
150  // explains what that binding does. For example: "Reset the camera".
151  virtual void SetKeyBinding(
152  const char *event, vtkObject *object, const char *method,
153  const char *context, const char *description);
154  virtual void RemoveKeyBinding(const char *event);
155  virtual void RemoveKeyBinding(
156  const char *event, vtkObject *object, const char *method);
157 
158  // Description:
159  // A convenience method that will return the key bindings manager associated
160  // to the application this widget belongs to. There is no key bindings
161  // internal ivar, this method returns the *application-wide* manager.
162  virtual vtkKWKeyBindingsManager* GetKeyBindingsManager();
163 
164  // Description:
165  // Set a drop-file binding to a widget, i.e. the command that is invoked
166  // whenever a file is dropped on the widget.
167  // The following parameters are also passed to the command:
168  // - filename(s): list of filenames
169  virtual void SetDropFileBinding(vtkObject *object, const char *method);
170 
171  // Description:
172  // Get the parent vtkKWTopLevel for this widget if there is one (by
173  // recursively tracking the parents).
174  // This can be safe-downcasted to a vtkKWWindowBase or vtkKWWindow.
175  // NOTE: this may return NULL if the widget is not in a toplevel.
176  vtkKWTopLevel* GetParentTopLevel();
177 
178  // Description:
179  // Query if widget is pack'ed, i.e. if the widget has been layout using
180  // the 'pack' geometry manager.
181  // Get number of packed children, unpack (remove from layout).
182  virtual int IsPacked();
183  virtual int GetNumberOfPackedChildren();
184  virtual void Unpack();
185 
186  // Description:
187  // Query if widget is grid'ed, i.e. if the widget has been layout using
188  // the 'grid' geometry manager.
189  // Get number of grid'ed children, ungrid (remove from layout).
190  virtual int IsGridded();
191  virtual int GetNumberOfGriddedChildren();
192  virtual void Ungrid();
193 
194  // Description:
195  // Query if widget is place'ed, i.e. if the widget has been layout using
196  // the 'place' geometry manager.
197  // Get number of placed children, unplace (remove from layout).
198  virtual int IsPlaced();
199  virtual int GetNumberOfPlacedChildren();
200  virtual void Unplace();
201 
202  // Description:
203  // Unpack widget, unpack siblings (slave's of parent widget), unpack children
204  // This will both unpack and ungrid and unplace, for convenience.
205  virtual void UnpackSiblings();
206  virtual void UnpackChildren();
207 
208  // Description:
209  // Set the balloon help string or icon for this widget.
210  // This will popup a small tooltip window over the widget after some delay.
211  // The tooltip settings are common to all widgets within the application
212  // and can be accessed by retrieving the balloon help manager using
213  // the GetBalloonHelpManager method. In some very specific case, a new
214  // tooltip manager can be set specifically for a widget instance.
215  virtual void SetBalloonHelpString(const char *str);
216  vtkGetStringMacro(BalloonHelpString);
217  virtual void SetBalloonHelpIcon(vtkKWIcon *icon);
218  vtkGetObjectMacro(BalloonHelpIcon, vtkKWIcon);
219 
220  // Description:
221  // Set/Get the balloon help manager.
222  // If the widget has been created, this returns the application
223  // balloon help manager. Be aware that changing its settings will
224  // affect all widgets.
225  // Setting the manager to a different instance allows a widget to use
226  // specific balloon help settings (say, a different delay or color)
227  // without affecting the other widgets. This has to be done before
228  // calling Create().
229  // This is an advanced feature, SetBalloonHelpString or
230  // SetBalloonHelpIcon are the only methods that are really needed to setup
231  // a proper tooltip 99% of the time.
232  virtual vtkKWBalloonHelpManager *GetBalloonHelpManager();
233  virtual void SetBalloonHelpManager(vtkKWBalloonHelpManager *mgr);
234 
235  // Description:
236  // Query if there are drag and drop targets between this widget and
237  // other widgets. Get the targets.
238  // IMPORTANT: the vtkKWDragAndDropTargetSet object is lazy-allocated, i.e.
239  // allocated only when it is needed, as GetDragAndDropTargetSet() is called.
240  // Therefore, to check if the instance *has* drag and drop targets, use
241  // HasDragAndDropTargetSet(), not GetDragAndDropTargetSet().
242  virtual int HasDragAndDropTargetSet();
243  virtual vtkKWDragAndDropTargetSet* GetDragAndDropTargetSet();
244 
245  // Description:
246  // Grab the widget (locally)
247  virtual void Grab();
248  virtual void ReleaseGrab();
249  virtual int IsGrabbed();
250 
251  // Description:
252  // Update the "enable" state of the object and its internal parts.
253  // Depending on different Ivars (this->Enabled, the application's
254  // Limited Edition Mode, etc.), the "enable" state of the object is updated
255  // and propagated to its internal parts/subwidgets. This will, for example,
256  // enable/disable parts of the widget UI, enable/disable the visibility
257  // of 3D widgets, etc.
258  virtual void UpdateEnableState();
259 
260  // Description::
261  // Override Unregister since widgets have loops.
262  virtual void UnRegister(vtkObjectBase *o);
263 
264  // Description:
265  // Get the net reference count of this widget. That is the
266  // reference count of this widget minus its children.
267  virtual int GetNetReferenceCount();
268 
269  // Description:
270  // Query children from this widget
271  virtual int HasChild(vtkKWWidget *w);
272  virtual int GetNumberOfChildren();
273  virtual vtkKWWidget* GetNthChild(int rank);
274  virtual vtkKWWidget* GetChildWidgetWithName(const char *);
275  virtual void RemoveAllChildren();
276 
277  // Description:
278  // Events.
279  // The WidgetCreatedEvent is sent after Create() is called.
280  //BTX
281  enum
282  {
283  WidgetCreatedEvent = 30000
284  };
285  //ETX
286 
287 
288 protected:
289  vtkKWWidget();
290  ~vtkKWWidget();
291 
292  // Description:
293  // Add/Remove a child to/from this widget
294  virtual void AddChild(vtkKWWidget *w);
295  virtual void RemoveChild(vtkKWWidget *w);
296 
297  // Description:
298  // The name of the underlying Tk widget being used.
299  char *WidgetName;
300 
301  // Description:
302  // The parent of the widget
303  vtkKWWidget *Parent;
304 
305  // Description:
306  // The tooltip associated to the widget, and the balloon help manager
307  char *BalloonHelpString;
308  vtkKWIcon *BalloonHelpIcon;
309  vtkKWBalloonHelpManager *BalloonHelpManager;
310  virtual void AddBalloonHelpBindings();
311 
312  // Description:
313  // PIMPL Encapsulation for STL containers
314  vtkKWWidgetInternals *Internals;
315 
316  // Description:
317  // Propagates the Enabled state of the instance to another subwidget
318  // (preferably a sub-widget).
319  // It calls SetEnabled(this->GetEnabled()) on the 'widget' parameter
320  virtual void PropagateEnableState(vtkKWWidget* widget);
321 
322  // Description:
323  // Create the widget. This is the method that should be implemented to
324  // create the widget itself, as well as its internal widgets if any.
325  // Subclasses should re-implement this method (do *not* re-implement the
326  // public Create() method).
327  virtual void CreateWidget();
328 
329  // Description:
330  // Create a specific Tk widget of type 'type', with optional arguments
331  // 'args' and map it to an object 'obj'.
332  // This method should only be used to from a subclass to implement a
333  // specific kind of pure Tk widget as a vtkKWWidget subclass, or to map
334  // an external pure Tk widget into a vtkKWWidget.
335  // If 'type' is NULL, this method will still perform some checkings and
336  // set the proper flags indicating that the widget has been created.
337  // Ideally, the 'args' parameter should only be used to specify options that
338  // can *not* be changed using Tk's 'configure'
339  // (i.e. SetConfigurationOptions()), and therefore that have to be passed
340  // at widget's creation time. For example the -visual and -class options
341  // of the 'toplevel' widget.
342  // Return 1 on success, 0 otherwise.
343  static int CreateSpecificTkWidget(
344  vtkKWWidget *obj, const char *type, const char *args = NULL);
345 
346  // Description:
347  // Set/add/remove a binding to a target, i.e. the command that is invoked
348  // whenever the 'event' is triggered on the target.
349  // The target here could be a tag, a widget name, etc. It is NOT, by
350  // default, the widget this method was called on. This method technically
351  // should be static, but we need a pointer to the application, etc.
352  virtual void SetGenericBinding(
353  const char *target, const char *event,
354  vtkObject *object, const char *method);
355  virtual void AddGenericBinding(
356  const char *target, const char *event,
357  vtkObject *object, const char *method);
358  virtual void RemoveGenericBinding(
359  const char *target, const char *event);
360  virtual void RemoveGenericBinding(
361  const char *target, const char *event,
362  vtkObject *object, const char *method);
363 
364 private:
365 
366  // Description:
367  // The Drag & Drop targets, if any. In private: so that it can be
368  // lazy-created
369  vtkKWDragAndDropTargetSet* DragAndDropTargetSet;
370 
371  int WidgetIsCreated;
372  int Enabled;
373 
374  static int UseClassNameInWidgetName;
375 
376  virtual unsigned long GetNextAvailableChildID();
377 
378  vtkKWWidget(const vtkKWWidget&); // Not implemented
379  void operator=(const vtkKWWidget&); // Not implemented
380 };
381 
382 #endif