KWWidgets
|
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