• Main Page
  • Classes
  • Files
  • Directories
  • File List
  • File Members

vtkKWWidget.h

Go to the documentation of this file.
00001 /*=========================================================================
00002 
00003   Module:    $RCSfile: vtkKWWidget.h,v $
00004 
00005   Copyright (c) Kitware, Inc.
00006   All rights reserved.
00007   See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
00008 
00009      This software is distributed WITHOUT ANY WARRANTY; without even
00010      the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
00011      PURPOSE.  See the above copyright notice for more information.
00012 
00013 =========================================================================*/
00014 // .NAME vtkKWWidget - superclass of KW widgets
00015 // .SECTION Description
00016 // This class is the superclass of all UI based objects in the
00017 // Kitware toolkit. It contains common methods such as specifying
00018 // the parent widget, generating and returning the Tcl widget name
00019 // for an instance, and managing children. It overrides the 
00020 // Unregister method to handle circular reference counts between
00021 // child and parent widgets.
00022 
00023 #ifndef __vtkKWWidget_h
00024 #define __vtkKWWidget_h
00025 
00026 #include "vtkKWObject.h"
00027 
00028 class vtkKWTopLevel;
00029 class vtkKWDragAndDropTargetSet;
00030 class vtkKWWidgetInternals;
00031 class vtkKWBalloonHelpManager;
00032 class vtkKWKeyBindingsManager;
00033 class vtkKWIcon;
00034 
00035 class KWWidgets_EXPORT vtkKWWidget : public vtkKWObject
00036 {
00037 public:
00038   static vtkKWWidget* New();
00039   vtkTypeRevisionMacro(vtkKWWidget,vtkKWObject);
00040   void PrintSelf(ostream& os, vtkIndent indent);
00041 
00042   // Description:
00043   // Set/Get the parent widget for this widget.
00044   // Important: you can not reparent a widget that has been Create()'ed already.
00045   virtual void SetParent(vtkKWWidget *p);
00046   vtkGetObjectMacro(Parent, vtkKWWidget);
00047 
00048   // Description:
00049   // Get the application instance for this object.
00050   // Override the superclass to try to retrieve the parent's application
00051   // if it was not set already.
00052   virtual vtkKWApplication* GetApplication();
00053 
00054   // Description:
00055   // Create the widget.
00056   // The parent should be set before calling this method (see SetParent()).
00057   // Once the object is fully created:
00058   // - the widget is configured according to the settings found in the 
00059   //   application's option database.
00060   // - the UpdateEnableState() method is called to make sure the state
00061   //   of the widget and its internal sub-widgets is up-to-date.
00062   // - a WidgetCreatedEvent event is sent.
00063   // Subclasses should *not* re-implement this method but re-implement the
00064   // protected CreateWidget() method instead.
00065   virtual void Create();
00066 
00067   // Description:
00068   // Get the name of the underlying Tk widget being used.
00069   // The Create() method should be called before invoking this method.
00070   // Note that setting the widget name manually is *not* recommended ; use
00071   // it only if you know what you are doing, say, for example, if
00072   // you have to map an external Tk widget to a vtkKWWidget object.
00073   virtual const char *GetWidgetName();
00074   vtkSetStringMacro(WidgetName);
00075 
00076   // Description:
00077   // Globally Set/Get if the widget name should include the object class name.
00078   // NOTE: this is a *static* method that defines the behaviour for *all*
00079   // instances to be created afterwards. This is typically called in your 
00080   // application class or your main executable, before creating any UI.
00081   // By default it is globally *disabled*.
00082   static int GetUseClassNameInWidgetName();
00083   static void SetUseClassNameInWidgetName(int);
00084   static void UseClassNameInWidgetNameOn();
00085   static void UseClassNameInWidgetNameOff();
00086 
00087   // Description:
00088   // Query if the widget was created successfully.
00089   virtual int IsCreated();
00090 
00091   // Description:
00092   // Query if the widget is "alive" (i.e. IsCreated()) and has not been 
00093   // deleted as far as Tk is concerned.
00094   virtual int IsAlive();
00095   
00096   // Description:
00097   // Query if the widget is mapped (i.e, on screen)
00098   virtual int IsMapped();
00099   
00100   // Description:
00101   // Set/query focus to this widget.
00102   virtual void Focus();
00103   virtual int HasFocus();
00104 
00105   // Description:
00106   // Set/Get the enabled state.
00107   virtual void SetEnabled(int);
00108   vtkBooleanMacro(Enabled, int);
00109   vtkGetMacro(Enabled, int);
00110 
00111   // Description:
00112   // Set/add/remove a binding to a widget, i.e. the command that is invoked
00113   // whenever the 'event' is triggered on the widget.
00114   // SetBinding will replace any old bindings, whereas AddBinding will
00115   // add the binding to the list of bindings already defined for that event.
00116   // RemoveBinding can remove a specific binding or all bindings for an event.
00117   // The 'object' argument is the object that will have the method called on
00118   // it. The 'method' argument is the name of the method to be called and any
00119   // arguments in string form. If the object is NULL, the method is still
00120   // evaluated as a simple command. 
00121   virtual void SetBinding(
00122     const char *event, vtkObject *object, const char *method);
00123   virtual void SetBinding(
00124     const char *event, const char *command);
00125   virtual const char* GetBinding(const char *event);
00126   virtual void AddBinding(
00127     const char *event, vtkObject *object, const char *method);
00128   virtual void AddBinding(
00129     const char *event, const char *command);
00130   virtual void RemoveBinding(const char *event);
00131   virtual void RemoveBinding(
00132     const char *event, vtkObject *object, const char *method);
00133 
00134   // Description:
00135   // A convenience method to add a key binding. This method does call
00136   // SetBinding under the hood (which can still be used to add key bindings)
00137   // but use the 'context' and 'description' to register that specific binding
00138   // to an application-wide key bindings (keyboard shortcuts) manager. That
00139   // manager can in turn be queried to create a list of key bindings and
00140   // present it to the user (in the Help menu for example). Use this method
00141   // only for important key bindings that you want the user to be reminded 
00142   // of. Simple bindings like <Return> on a button to allow the user
00143   // to "press" said button by hitting <Return, should probably not be set
00144   // with this method, but with the usual SetBinding method.
00145   // 'context' is a string in plain English (or preferably localized) that
00146   // explains in which context this key binding is valid. For example: 
00147   // "Any 2D View", or "Any Main Window". It usually is a simple/short
00148   // description of the class setting the binding. 
00149   // 'description' is a string in plain English (or preferably localized) that
00150   // explains what that binding does. For example: "Reset the camera".
00151   virtual void SetKeyBinding(
00152     const char *event, vtkObject *object, const char *method,
00153     const char *context, const char *description);
00154   virtual void RemoveKeyBinding(const char *event);
00155   virtual void RemoveKeyBinding(
00156     const char *event, vtkObject *object, const char *method);
00157 
00158   // Description:
00159   // A convenience method that will return the key bindings manager associated
00160   // to the application this widget belongs to. There is no key bindings
00161   // internal ivar, this method returns the *application-wide* manager.
00162   virtual vtkKWKeyBindingsManager* GetKeyBindingsManager();
00163 
00164   // Description:
00165   // Set a drop-file binding to a widget, i.e. the command that is invoked
00166   // whenever a file is dropped on the widget.
00167   // The following parameters are also passed to the command:
00168   // - filename(s): list of filenames
00169   virtual void SetDropFileBinding(vtkObject *object, const char *method);
00170 
00171   // Description:
00172   // Get the parent vtkKWTopLevel for this widget if there is one (by
00173   // recursively tracking the parents).
00174   // This can be safe-downcasted to a vtkKWWindowBase or vtkKWWindow.
00175   // NOTE: this may return NULL if the widget is not in a toplevel.
00176   vtkKWTopLevel* GetParentTopLevel();
00177 
00178   // Description:
00179   // Query if widget is pack'ed, i.e. if the widget has been layout using 
00180   // the 'pack' geometry manager. 
00181   // Get number of packed children, unpack (remove from layout).
00182   virtual int IsPacked();
00183   virtual int GetNumberOfPackedChildren();
00184   virtual void Unpack();
00185 
00186   // Description:
00187   // Query if widget is grid'ed, i.e. if the widget has been layout using 
00188   // the 'grid' geometry manager. 
00189   // Get number of grid'ed children, ungrid (remove from layout).
00190   virtual int IsGridded();
00191   virtual int GetNumberOfGriddedChildren();
00192   virtual void Ungrid();
00193 
00194   // Description:
00195   // Query if widget is place'ed, i.e. if the widget has been layout using 
00196   // the 'place' geometry manager. 
00197   // Get number of placed children, unplace (remove from layout).
00198   virtual int IsPlaced();
00199   virtual int GetNumberOfPlacedChildren();
00200   virtual void Unplace();
00201 
00202   // Description:
00203   // Unpack widget, unpack siblings (slave's of parent widget), unpack children
00204   // This will both unpack and ungrid and unplace, for convenience.
00205   virtual void UnpackSiblings();
00206   virtual void UnpackChildren();
00207   
00208   // Description:
00209   // Set the balloon help string or icon for this widget.
00210   // This will popup a small tooltip window over the widget after some delay.
00211   // The tooltip settings are common to all widgets within the application
00212   // and can be accessed by retrieving the balloon help manager using
00213   // the GetBalloonHelpManager method. In some very specific case, a new
00214   // tooltip manager can be set specifically for a widget instance.
00215   virtual void SetBalloonHelpString(const char *str);
00216   vtkGetStringMacro(BalloonHelpString);
00217   virtual void SetBalloonHelpIcon(vtkKWIcon *icon);
00218   vtkGetObjectMacro(BalloonHelpIcon, vtkKWIcon);
00219 
00220   // Description:
00221   // Set/Get the balloon help manager.
00222   // If the widget has been created, this returns the application
00223   // balloon help manager. Be aware that changing its settings will
00224   // affect all widgets. 
00225   // Setting the manager to a different instance allows a widget to use
00226   // specific balloon help settings (say, a different delay or color)
00227   // without affecting the other widgets. This has to be done before
00228   // calling Create().
00229   // This is an advanced feature, SetBalloonHelpString or
00230   // SetBalloonHelpIcon are the only methods that are really needed to setup
00231   // a proper tooltip 99% of the time.
00232   virtual vtkKWBalloonHelpManager *GetBalloonHelpManager();
00233   virtual void SetBalloonHelpManager(vtkKWBalloonHelpManager *mgr);
00234 
00235   // Description:
00236   // Query if there are drag and drop targets between this widget and
00237   // other widgets. Get the targets.
00238   // IMPORTANT: the vtkKWDragAndDropTargetSet object is lazy-allocated, i.e.
00239   // allocated only when it is needed, as GetDragAndDropTargetSet() is called.
00240   // Therefore, to check if the instance *has* drag and drop targets, use 
00241   // HasDragAndDropTargetSet(), not GetDragAndDropTargetSet().
00242   virtual int HasDragAndDropTargetSet();
00243   virtual vtkKWDragAndDropTargetSet* GetDragAndDropTargetSet();
00244 
00245   // Description:
00246   // Grab the widget (locally)
00247   virtual void Grab();
00248   virtual void ReleaseGrab();
00249   virtual int IsGrabbed();
00250 
00251   // Description:
00252   // Update the "enable" state of the object and its internal parts.
00253   // Depending on different Ivars (this->Enabled, the application's 
00254   // Limited Edition Mode, etc.), the "enable" state of the object is updated
00255   // and propagated to its internal parts/subwidgets. This will, for example,
00256   // enable/disable parts of the widget UI, enable/disable the visibility
00257   // of 3D widgets, etc.
00258   virtual void UpdateEnableState();
00259 
00260   // Description::
00261   // Override Unregister since widgets have loops.
00262   virtual void UnRegister(vtkObjectBase *o);
00263 
00264   // Description:
00265   // Get the net reference count of this widget. That is the
00266   // reference count of this widget minus its children.
00267   virtual int  GetNetReferenceCount();
00268 
00269   // Description:
00270   // Query children from this widget
00271   virtual int HasChild(vtkKWWidget *w);
00272   virtual int GetNumberOfChildren();
00273   virtual vtkKWWidget* GetNthChild(int rank);
00274   virtual vtkKWWidget* GetChildWidgetWithName(const char *);
00275   virtual void RemoveAllChildren();
00276 
00277   // Description:
00278   // Events.
00279   // The WidgetCreatedEvent is sent after Create() is called.
00280   //BTX
00281   enum
00282   {
00283     WidgetCreatedEvent = 30000
00284   };
00285   //ETX
00286 
00287 
00288 protected:
00289   vtkKWWidget();
00290   ~vtkKWWidget();
00291 
00292   // Description:
00293   // Add/Remove a child to/from this widget
00294   virtual void AddChild(vtkKWWidget *w);
00295   virtual void RemoveChild(vtkKWWidget *w);
00296 
00297   // Description:
00298   // The name of the underlying Tk widget being used.
00299   char *WidgetName;
00300 
00301   // Description:
00302   // The parent of the widget
00303   vtkKWWidget *Parent;
00304 
00305   // Description:
00306   // The tooltip associated to the widget, and the balloon help manager
00307   char *BalloonHelpString;
00308   vtkKWIcon *BalloonHelpIcon;
00309   vtkKWBalloonHelpManager *BalloonHelpManager;
00310   virtual void AddBalloonHelpBindings();
00311 
00312   // Description:
00313   // PIMPL Encapsulation for STL containers
00314   vtkKWWidgetInternals *Internals;
00315 
00316   // Description:
00317   // Propagates the Enabled state of the instance to another subwidget
00318   // (preferably a sub-widget).
00319   // It calls SetEnabled(this->GetEnabled()) on the 'widget' parameter
00320   virtual void PropagateEnableState(vtkKWWidget* widget);
00321 
00322   // Description:
00323   // Create the widget. This is the method that should be implemented to
00324   // create the widget itself, as well as its internal widgets if any.
00325   // Subclasses should re-implement this method (do *not* re-implement the
00326   // public Create() method).
00327   virtual void CreateWidget();
00328 
00329   // Description:
00330   // Create a specific Tk widget of type 'type', with optional arguments 
00331   // 'args' and map it to an object 'obj'.
00332   // This method should only be used to from a subclass to implement a
00333   // specific kind of pure Tk widget as a vtkKWWidget subclass, or  to map
00334   // an external pure Tk widget into a vtkKWWidget.
00335   // If 'type' is NULL, this method will still perform some checkings and
00336   // set the proper flags indicating that the widget has been created. 
00337   // Ideally, the 'args' parameter should only be used to specify options that
00338   // can *not* be changed using Tk's 'configure' 
00339   // (i.e. SetConfigurationOptions()), and therefore that have to be passed
00340   // at widget's creation time. For example the -visual and -class options 
00341   // of the 'toplevel' widget.
00342   // Return 1 on success, 0 otherwise.
00343   static int CreateSpecificTkWidget(
00344     vtkKWWidget *obj, const char *type, const char *args = NULL);
00345 
00346   // Description:
00347   // Set/add/remove a binding to a target, i.e. the command that is invoked
00348   // whenever the 'event' is triggered on the target.
00349   // The target here could be a tag, a widget name, etc. It is NOT, by 
00350   // default, the widget this method was called on. This method technically
00351   // should be static, but we need a pointer to the application, etc.
00352   virtual void SetGenericBinding(
00353     const char *target, const char *event, 
00354     vtkObject *object, const char *method);
00355   virtual void AddGenericBinding(
00356     const char *target, const char *event, 
00357     vtkObject *object, const char *method);
00358   virtual void RemoveGenericBinding(
00359     const char *target, const char *event);
00360   virtual void RemoveGenericBinding(
00361     const char *target, const char *event, 
00362     vtkObject *object, const char *method);
00363 
00364 private:
00365   
00366   // Description:
00367   // The Drag & Drop targets, if any. In private: so that it can be
00368   // lazy-created
00369   vtkKWDragAndDropTargetSet* DragAndDropTargetSet;
00370 
00371   int WidgetIsCreated;
00372   int Enabled;
00373 
00374   static int UseClassNameInWidgetName;
00375 
00376   virtual unsigned long GetNextAvailableChildID();
00377 
00378   vtkKWWidget(const vtkKWWidget&); // Not implemented
00379   void operator=(const vtkKWWidget&); // Not implemented
00380 };
00381 
00382 #endif

Generated on Mon Aug 16 2010 18:58:48 for KWWidgets by  doxygen 1.7.1