KWWidgets
vtkKWWindowBase.h
Go to the documentation of this file.
00001 /*=========================================================================
00002 
00003   Module:    $RCSfile: vtkKWWindowBase.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 vtkKWWindowBase - a window superclass
00015 // .SECTION Description
00016 // This class represents a top level window with a menu bar, a status
00017 // line and a main central frame.
00018 
00019 #ifndef __vtkKWWindowBase_h
00020 #define __vtkKWWindowBase_h
00021 
00022 #include "vtkKWTopLevel.h"
00023 
00024 class vtkKWFrame;
00025 class vtkKWLabel;
00026 class vtkKWMenu;
00027 class vtkKWMostRecentFilesManager;
00028 class vtkKWKeyBindingsManager;
00029 class vtkKWProgressGauge;
00030 class vtkKWSeparator;
00031 class vtkKWToolbar;
00032 class vtkKWToolbarSet;
00033 
00034 class KWWidgets_EXPORT vtkKWWindowBase : public vtkKWTopLevel
00035 {
00036 public:
00037   static vtkKWWindowBase* New();
00038   vtkTypeRevisionMacro(vtkKWWindowBase,vtkKWTopLevel);
00039   void PrintSelf(ostream& os, vtkIndent indent);
00040 
00041   // Description:
00042   // Close this window, possibly prompting the user.
00043   // Note that the current vtkKWApplication implementation will
00044   // exit the application if no more windows are open.
00045   // Return 1 if the window closed successfully, 0 otherwise (for example,
00046   // if some dialogs are still up, or the user did not confirm, etc).
00047   virtual int Close();
00048 
00049   // Description:
00050   // Set/Get if a confirmation dialog should be displayed before a
00051   // window is closed. Default to false.
00052   vtkSetMacro(PromptBeforeClose, int);
00053   vtkGetMacro(PromptBeforeClose, int);
00054   vtkBooleanMacro(PromptBeforeClose, int);
00055 
00056   // Description:
00057   // Load and evaluate a Tcl based script. 
00058   // If called without an argument it will open a file dialog.
00059   // This implementation basically forwards the call to 
00060   // vtkKWApplication::LoadScript.
00061   virtual void LoadScript();
00062   virtual void LoadScript(const char *filename);
00063 
00064   // Description:
00065   // The extension used in LoadScript. Default is .tcl.
00066   vtkSetStringMacro(ScriptExtension);
00067   vtkGetStringMacro(ScriptExtension);
00068 
00069   // Description:
00070   // The type name used in LoadScript. Default is Tcl.
00071   vtkSetStringMacro(ScriptType);
00072   vtkGetStringMacro(ScriptType);
00073 
00074   // Description:
00075   // Set the text for the status bar of this window.
00076   virtual void SetStatusText(const char *);
00077   virtual const char *GetStatusText();
00078   
00079   // Description:
00080   // Set the error/warning icon in the tray.
00081   // Note that if StatusFrameVisibility is Off, you may want to move the
00082   // tray frame to a different position (say, in a toolbar), using
00083   // the SetTrayFramePosition() method.
00084   //BTX
00085   enum 
00086   {
00087     ErrorIconNone = 0,
00088     ErrorIconBlack,
00089     ErrorIconRed
00090   };
00091   //ETX
00092   virtual void SetErrorIcon(int);
00093   virtual void SetErrorIconToNone()
00094     { this->SetErrorIcon(vtkKWWindowBase::ErrorIconNone); };
00095   virtual void SetErrorIconToBlack()
00096     { this->SetErrorIcon(vtkKWWindowBase::ErrorIconBlack); };
00097   virtual void SetErrorIconToRed()
00098     { this->SetErrorIcon(vtkKWWindowBase::ErrorIconRed); };
00099 
00100   // Description:
00101   // The window is made of a menu bar (methods are available to access each
00102   // menus), a separator, a toolbar placeholder, a large main frame called
00103   // the "view frame", and a status frame (inside which the a progress
00104   // gauge and some other UI elements can be found).
00105   // Note that this large frame is likely to be re-allocated by subclasses
00106   // into a different UI structure involving panels, notebooks, interface 
00107   // managers, etc. therefore GetViewFrame() will be overriden in order to
00108   // return the most convenient viewing frame. 
00109   // The rational here is that GetViewFrame() always return the frame that
00110   // can be used by users or developpers to add more "viewing" element (say,
00111   // renderwidgets, 3D scenes), without knowing about the current layout.
00112   virtual vtkKWFrame* GetViewFrame();
00113 
00114   // Description:
00115   // Get the main toolbar set.
00116   vtkGetObjectMacro(MainToolbarSet, vtkKWToolbarSet);
00117 
00118   // Description:
00119   // Get the status frame object.
00120   vtkGetObjectMacro(StatusFrame, vtkKWFrame);
00121 
00122   // Description:
00123   // Set/Get the visibility of the status frame. If set to Off, the status
00124   // text, as set by SetStatusText(), will not be displayed anymore. Neither
00125   // will the progress gauge, the application icon, the tray frame and status
00126   // icons. Both the progress gauge and tray frame position can be changed 
00127   // independently though (see SetProgressGaugePosition and 
00128   // SetTrayFramePosition).
00129   virtual void SetStatusFrameVisibility(int flag);
00130   vtkGetMacro(StatusFrameVisibility, int);
00131   vtkBooleanMacro(StatusFrameVisibility, int);  
00132 
00133   // Description:
00134   // Get the progress gauge widget.  The progress gauge is displayed
00135   // in the Status frame on the bottom right corner of the window.
00136   vtkGetObjectMacro(ProgressGauge, vtkKWProgressGauge);
00137 
00138   // Description:
00139   // Set the progress gauge position. The default position is in the
00140   // status frame, but this object can also be displayed in a toolbar, on
00141   // top of the window. This is useful when StatusFrameVisibility is set
00142   // to Off.
00143   //BTX
00144   enum 
00145   {
00146     ProgressGaugePositionStatusFrame = 0,
00147     ProgressGaugePositionToolbar
00148   };
00149   //ETX
00150   virtual void SetProgressGaugePosition(int);
00151   virtual void SetProgressGaugePositionToStatusFrame()
00152     { this->SetProgressGaugePosition(
00153       vtkKWWindowBase::ProgressGaugePositionStatusFrame); };
00154   virtual void SetProgressGaugePositionToToolbar()
00155     { this->SetProgressGaugePosition(
00156       vtkKWWindowBase::ProgressGaugePositionToolbar); };
00157 
00158   // Description:
00159   // Get the tray frame object. A default status icon is already packed
00160   // in this frame and modified by SetErrorIcon, but other icons can
00161   // probably fit there.
00162   vtkGetObjectMacro(TrayFrame, vtkKWFrame);
00163 
00164   // Description:
00165   // Set the tray frame position. The default position is in the
00166   // status frame, but this object can also be displayed in a toolbar, on
00167   // top of the window. This is useful when StatusFrameVisibility is set
00168   // to Off.
00169   //BTX
00170   enum 
00171   {
00172     TrayFramePositionStatusFrame = 0,
00173     TrayFramePositionToolbar
00174   };
00175   //ETX
00176   vtkGetMacro(TrayFramePosition, int);
00177   virtual void SetTrayFramePosition(int);
00178   virtual void SetTrayFramePositionToStatusFrame()
00179     { this->SetTrayFramePosition(
00180       vtkKWWindowBase::TrayFramePositionStatusFrame); };
00181   virtual void SetTrayFramePositionToToolbar()
00182     { this->SetTrayFramePosition(
00183       vtkKWWindowBase::TrayFramePositionToolbar); };
00184 
00185   // Description:
00186   // Get the menu objects. This will allocate and create them on the fly.
00187   // Several convenience functions are also available to get the position
00188   // where to safely insert entries in those menus without interferring with
00189   // entries that should stay at the end of the menus.
00190   // Note: if you need to enable/disable a menu item conditionally in a 
00191   // subclass, do it so by reimplementing UpdateMenuState(); do not forget to
00192   // call the parent class's UpdateMenuState() from the subclass as well.
00193   vtkKWMenu *GetFileMenu();
00194   vtkKWMenu *GetEditMenu();
00195   vtkKWMenu *GetViewMenu();
00196   vtkKWMenu *GetWindowMenu();
00197   vtkKWMenu *GetHelpMenu();
00198   vtkKWMenu *GetToolbarsVisibilityMenu();
00199   vtkGetObjectMacro(MenuBarSeparator, vtkKWSeparator);
00200 
00201   // Description:
00202   // Convenience method that return the position where to safely insert 
00203   // entries in the corresponding menu without interferring with entries
00204   // that should stay at the end of the menu.
00205   // At the moment, GetFileMenuInsertPosition() checks for the 'close',
00206   // 'exit' or 'print setup' commands, GetHelpMenuInsertPosition() checks for
00207   // the 'about' commands, GetViewMenuInsertPosition() is available for
00208   // subclasses to be redefined. 
00209   virtual int GetFileMenuInsertPosition();
00210   virtual int GetHelpMenuInsertPosition();
00211   virtual int GetViewMenuInsertPosition();
00212 
00213   // Description:
00214   // Set/Get a hint about help support. Disabled by default.
00215   // If set to true (programmatically or by a superclass), it will hint the
00216   // instance about populating the help menu with common entries. 
00217   // For example, an entry invoking the application's DisplayHelpDialog or
00218   // DisplayTutorial.
00219   vtkSetClampMacro(SupportHelp, int, 0, 1);
00220   vtkGetMacro(SupportHelp, int);
00221   vtkBooleanMacro(SupportHelp, int);
00222 
00223   // Description:
00224   // Add a file to the Recent File list, and save the whole list to
00225   // the registry.
00226   // If the "Recent files" sub-menu has been inserted at that point (see
00227   // the InsertRecentFilesMenu method), it will be updated as well.
00228   virtual void AddRecentFile(
00229     const char *filename, vtkObject *target, const char *command);
00230 
00231   // Description:
00232   // Insert a "Recent Files" sub-menu to the File menu at position 'pos'
00233   // and fill it with the most recent files stored in the registry.
00234   // The 'target' parameter is the object against which the command
00235   // associated to a most recent file will be executed (usually the instance).
00236   virtual void InsertRecentFilesMenu(int pos, vtkObject *target);
00237  
00238   // Description:
00239   // Set/Get a hint about print support. Disabled by default.
00240   // If set to true (programmatically or by a superclass), it will hint the
00241   // instance about populating some menus with common print-related entries. 
00242   // For example, an entry in the file menu to set up print options like
00243   // the application's PrintTargetDPI.
00244   vtkSetClampMacro(SupportPrint, int, 0, 1);
00245   vtkGetMacro(SupportPrint, int);
00246   vtkBooleanMacro(SupportPrint, int);
00247 
00248   // Description:
00249   // Get the key bindings manager.
00250   vtkGetObjectMacro(KeyBindingsManager, vtkKWKeyBindingsManager);
00251 
00252   // Description:
00253   // Get title of window.
00254   // Override the superclass to use app name if the title was not set
00255   virtual char* GetTitle();
00256 
00257   // Description:
00258   // Update the UI. This will call:
00259   //   UpdateToolbarState
00260   //   UpdateEnableState 
00261   //   UpdateMenuState
00262   //   Update on all panels belonging to the UserInterfaceManager, if any
00263   virtual void Update();
00264 
00265   // Description:
00266   // Update the toolbar state
00267   virtual void UpdateToolbarState();
00268 
00269   // Description:
00270   // Update the "enable" state of the object and its internal parts.
00271   // Depending on different Ivars (this->Enabled, the application's 
00272   // Limited Edition Mode, etc.), the "enable" state of the object is updated
00273   // and propagated to its internal parts/subwidgets. This will, for example,
00274   // enable/disable parts of the widget UI, enable/disable the visibility
00275   // of 3D widgets, etc.
00276   // Note: if you need to enable/disable a menu item conditionally in a 
00277   // subclass, do it so by reimplementing UpdateMenuState(); do not forget to
00278   // call the parent class's UpdateMenuState() from the subclass as well.
00279   virtual void UpdateEnableState();
00280   virtual void UpdateMenuState();
00281 
00282   // Description:
00283   // Deallocate/delete/reparent some internal objects in order to solve
00284   // reference loops that would prevent this instance from being deleted.
00285   virtual void PrepareForDelete();
00286 
00287   // Description:
00288   // Some constants
00289   vtkGetStringMacro(PrintOptionsMenuLabel);
00290   vtkGetStringMacro(FileMenuLabel);
00291   vtkGetStringMacro(FileCloseMenuLabel);
00292   vtkGetStringMacro(FileExitMenuLabel);
00293   vtkGetStringMacro(OpenRecentFileMenuLabel);
00294   vtkGetStringMacro(EditMenuLabel);
00295   vtkGetStringMacro(ViewMenuLabel);
00296   vtkGetStringMacro(WindowMenuLabel);
00297   vtkGetStringMacro(HelpMenuLabel);
00298   vtkGetStringMacro(HelpAboutMenuLabel);
00299   vtkGetStringMacro(HelpTopicsMenuLabel);
00300   vtkGetStringMacro(HelpTutorialMenuLabel);
00301   vtkGetStringMacro(HelpKeyBindingsMenuLabel);
00302   vtkGetStringMacro(HelpCheckForUpdatesMenuLabel);
00303   vtkGetStringMacro(ToolbarsVisibilityMenuLabel);
00304   vtkGetStringMacro(WindowGeometryRegKey);
00305   vtkGetStringMacro(DefaultGeometry);
00306 
00307   // Description:
00308   // Events. 
00309   // WindowClosedEvent is called when the window is closing. It is triggered
00310   // right before requesting the application to remove the window instance
00311   // from its window pool (vtkKWApplication::RemoveWindow).
00312   //BTX
00313   enum
00314   {
00315     WindowClosingEvent = 10000
00316   };
00317   //ETX
00318 
00319   // Description:
00320   // Add all the default observers needed by that object, or remove
00321   // all the observers that were added through AddCallbackCommandObserver.
00322   // Subclasses can override these methods to add/remove their own default
00323   // observers, but should call the superclass too.
00324   virtual void AddCallbackCommandObservers();
00325   virtual void RemoveCallbackCommandObservers();
00326 
00327   // Description:
00328   // Add observers required to propagate error messages. Note that they
00329   // were not put in AddCallbackCommandObservers on purpose, so that they
00330   // do not get accidentally removed by RemoveCallbackCommandObservers: 
00331   // propagation of error messages, after all, should never be disabled.
00332   virtual void AddErrorCallbackCommandObservers();
00333   virtual void RemoveErrorCallbackCommandObservers();
00334 
00335   // Description:
00336   // Callbacks. Internal, do not use.
00337   virtual void ErrorIconCallback();
00338   virtual void PrintSettingsCallback() {};
00339   virtual void ToolbarVisibilityChangedCallback(vtkKWToolbar*);
00340   virtual void NumberOfToolbarsChangedCallback();
00341   virtual void DisplayKeyBindingsCallback();
00342 
00343 protected:
00344   vtkKWWindowBase();
00345   ~vtkKWWindowBase();
00346 
00347   // Description:
00348   // Create the widget.
00349   virtual void CreateWidget();
00350 
00351   // Description:
00352   // Display the close dialog.
00353   // Return 1 if the user wants to close the window, 0 otherwise
00354   virtual int DisplayCloseDialog();
00355 
00356   // Description:
00357   // Update the image in the status frame. Usually a logo of some sort.
00358   // Override this function to include your own application logo
00359   virtual void UpdateStatusImage();
00360   virtual vtkKWLabel *GetStatusImage();
00361 
00362   // Description:
00363   // Recent files manager
00364   vtkKWMostRecentFilesManager *MostRecentFilesManager;
00365 
00366   // Description:
00367   // Key bindings manager
00368   vtkKWKeyBindingsManager *KeyBindingsManager;
00369 
00370   // Description:
00371   // Save/Restore window geometry
00372   virtual void SaveWindowGeometryToRegistry();
00373   virtual void RestoreWindowGeometryFromRegistry();
00374 
00375   // Description:
00376   // Pack/repack the UI
00377   virtual void Pack();
00378 
00379   vtkKWSeparator *MenuBarSeparator;
00380   vtkKWFrame *MainFrame;
00381 
00382   vtkKWSeparator *StatusFrameSeparator;
00383   vtkKWFrame *StatusFrame;
00384   vtkKWLabel *StatusImage;
00385   vtkKWLabel *StatusLabel;
00386 
00387   vtkKWProgressGauge *ProgressGauge;
00388   int                ProgressGaugePosition;
00389 
00390   vtkKWFrame      *TrayFrame;
00391   vtkKWLabel      *TrayImageError;
00392   int             TrayFramePosition;
00393 
00394   vtkKWToolbarSet *MainToolbarSet;
00395   vtkKWToolbar    *StatusToolbar;
00396 
00397   char *ScriptExtension;
00398   char *ScriptType;
00399   int  SupportHelp;
00400   int  SupportPrint;
00401   int  PromptBeforeClose;
00402   int  StatusFrameVisibility;
00403 
00404   // Allocated and created when queried
00405 
00406   vtkKWMenu *FileMenu;
00407   vtkKWMenu *EditMenu;
00408   vtkKWMenu *ViewMenu;
00409   vtkKWMenu *WindowMenu;
00410   vtkKWMenu *HelpMenu;
00411   vtkKWMenu *ToolbarsVisibilityMenu;
00412 
00413   // Description:
00414   // Populate the menus.
00415   // Note: if you need to enable/disable a menu item conditionally in a 
00416   // subclass, do it so by reimplementing UpdateMenuState(); do not forget to
00417   // call the parent class's UpdateMenuState() from the subclass as well.
00418   virtual void PopulateFileMenu();
00419   virtual void PopulateEditMenu();
00420   virtual void PopulateViewMenu();
00421   virtual void PopulateWindowMenu();
00422   virtual void PopulateHelpMenu();
00423 
00424   vtkKWTclInteractor *TclInteractor;
00425 
00426   // Description:
00427   // Some constants
00428   vtkSetStringMacro(PrintOptionsMenuLabel);
00429   vtkSetStringMacro(FileMenuLabel);
00430   vtkSetStringMacro(FileCloseMenuLabel);
00431   vtkSetStringMacro(FileExitMenuLabel);
00432   vtkSetStringMacro(OpenRecentFileMenuLabel);
00433   vtkSetStringMacro(EditMenuLabel);
00434   vtkSetStringMacro(ViewMenuLabel);
00435   vtkSetStringMacro(WindowMenuLabel);
00436   vtkSetStringMacro(HelpMenuLabel);
00437   vtkSetStringMacro(HelpTopicsMenuLabel);
00438   vtkSetStringMacro(HelpTutorialMenuLabel);
00439   vtkSetStringMacro(HelpKeyBindingsMenuLabel);
00440   vtkSetStringMacro(HelpAboutMenuLabel);
00441   vtkSetStringMacro(HelpCheckForUpdatesMenuLabel);
00442   vtkSetStringMacro(ToolbarsVisibilityMenuLabel);
00443   vtkSetStringMacro(WindowGeometryRegKey);
00444   vtkSetStringMacro(DefaultGeometry);
00445 
00446   // Description:
00447   // Processes the events that are passed through CallbackCommand (or others).
00448   // Subclasses can oberride this method to process their own events, but
00449   // should call the superclass too.
00450   virtual void ProcessCallbackCommandEvents(
00451     vtkObject *caller, unsigned long event, void *calldata);
00452   
00453 private:
00454 
00455   // Description:
00456   // Some constants
00457   char *PrintOptionsMenuLabel;
00458   char *FileMenuLabel;
00459   char *FileCloseMenuLabel;
00460   char *FileExitMenuLabel;
00461   char *OpenRecentFileMenuLabel;
00462   char *EditMenuLabel;
00463   char *ViewMenuLabel;
00464   char *WindowMenuLabel;
00465   char *HelpMenuLabel;
00466   char *HelpTopicsMenuLabel;
00467   char *HelpTutorialMenuLabel;
00468   char *HelpKeyBindingsMenuLabel;
00469   char *HelpAboutMenuLabel;
00470   char *HelpCheckForUpdatesMenuLabel;
00471   char *ToolbarsVisibilityMenuLabel;
00472   char *WindowGeometryRegKey;
00473   char *DefaultGeometry;
00474 
00475   vtkKWWindowBase(const vtkKWWindowBase&); // Not implemented
00476   void operator=(const vtkKWWindowBase&); // Not implemented
00477 };
00478 
00479 #endif