KWWidgets
debian/tmp/usr/include/KWWidgets/vtkKWWindow.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Module: $RCSfile: vtkKWWindow.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 vtkKWWindow - a window superclass which holds splittable panels.
15 // .SECTION Description
16 // This class represents a top level window with a menu bar, a status
17 // line (as per vtkKWWindowBase) and user interface panels that can be
18 // resized and/or collapsed.
19 //
20 // Here is the layout of the whole window. Remember that the superclass
21 // "view frame" (as returned by GetViewFrame()) was the whole usable space
22 // between the menu bar on top (and eventually toolbars) and the status bar
23 // at the bottom.
24 //
25 // This old "view frame" is now further divided horizontally into two parts
26 // by a split frame instance.
27 // The first part (on the left) is called the "main panel" area, and
28 // can be hidden or shown using the SetMainPanelVisibility() method.
29 // A convenience method GetMainPanelFrame() can be used to retrieve that
30 // "main panel area" frame, even if it is currently entirely allocated to
31 // the main notebook, MainNotebook.
32 // The MainNotebook element is packed in the main panel and is used to
33 // display interface elements organized as *pages* inside *panels*.
34 //
35 // Note that the proper way to do so is to create "user interface panels"
36 // (UIP, subclasses of vtkKWUserInterfacePanel), and set their
37 // "user interface manager" (UIM) to the main user interface manager, as
38 // returned by GetMainUserInterfaceManager(). Since the main UIM is itself
39 // attached to the main notebook, it will display the UIP automatically inside
40 // the notebook and take care of showing/raising/hiding the pages properly.
41 // The ShowMainUserInterface() method can be used to show a main interface
42 // panel given its name. The name is typically the string returned by the
43 // GetName() method of a vtkKWUserInterfacePanel (UIP).
44 // The ShowMainUserInterface() method will query the main UIM to check if it
45 // is indeed managing a panel (UIP) with that name, and show/raise that UIP
46 // accordingly. If you do not know which user interface manager is used
47 // by the panel, just call Show() or Raise() on the panel itself !
48 //
49 // Note that by following such framework, a subclass will be free of using
50 // a totally different type of UIM, while the UIP implementation and
51 // manipulation will remain exactly the same. One just has to focus on creating
52 // simple panels to pack user interface components, and the UIM will be
53 // responsible for mapping them into a higher-level interface, like a notebook.
54 // It will also take care of show/hiding conflicting interfaces, provide
55 // some cross-panels features like drag and drop, serialize the UI state, etc.
56 //
57 // In the same way, the right part of the MainSplitFrame (i.e., not the main
58 // panel itself, but the remaining space on the right side of the separator)
59 // is also divided vertically into two parts by a split frame instance.
60 // The same methods as described above are available for this secondary
61 // subdivision, i.e. SetSecondaryPanelVisibility() can be
62 // used to show/hide the secondary panel, GetSecondaryPanelFrame() can be
63 // used to retrieve the secondary panel frame, a SecondaryNotebook is
64 // packed inside the secondary panel, and GetMainUserInterfaceManager() can
65 // be used to retrieve the corresponding UIM.
66 //
67 // Below the SecondarySplitFrame is a second toolbar set (SecondaryToolbarSet)
68 // available for extra toolbars.
69 //
70 // The space available for "viewing", or packing 3D scenes, is returned by
71 // GetViewFrame(). Under the hood, a third user interface manager, the
72 // ViewUserInterfaceManager is coupled to a ViewNotebook and packed inside
73 // the top part of the secondary split frame (i.e. the large part that is
74 // not considered a user interface panel). A default page is added to that
75 // notebook to provide the frame for GetViewFrame(). Since there is only
76 // one page, the tab is not shown by default, leaving all the notebook
77 // space available for viewing. This notebook and its user interface manager
78 // are likely not be manipulated as often as the other panels and UIM, but
79 // can be used to provide multiple "views" for example.
80 // As a convenience, a GetViewPanelFrame() method returns the parent
81 // of the notebook, i.e. the space into which the notebook was packed, so
82 // that other elements can be packed below or before the notebook itself.
83 //
84 // A fourth user interface manager is used to display and group all
85 // panels related to application settings (i.e. "Preferences"). It is not
86 // part of the layout as it will popup as a dialog instead. Note that
87 // the panels do not have to bother about that, the manager will parse
88 // each panel and create the dialog accordingly. If you have more application
89 // settings parameters, just create your own panels and set their UIM to
90 // the ApplicationSettingsUserInterfaceManager.
91 //
92 // This describes the default layout so far, where the secondary panel is
93 // located below the view frame. The PanelLayout ivar can be set
94 // to change this layout to different configurations where:
95 // - the secondary panel is below the main panel.
96 // - the secondary panel is below both main and the view panel.
97 // Note that there is no accessor to get the split frame objects, since
98 // you should not rely on them to parent your widgets. Use the panel
99 // frame accessors instead, they will return the correct value even if
100 // the layout changes (i.e., GetMainPanelFrame(), GetSecondaryPanelFrame(),
101 // GetViewPanelFrame()).
102 //
103 // MB: GetMenu() (see vtkKWTopLevel)
104 // MTBS: GetMainToolbarSet() (see superclass)
105 // MPF: GetMainPanelFrame()
106 // MNB: MainNotebook
107 // VNB: ViewNotebook
108 // VPF: GetViewPanelFrame()
109 // VF: GetViewFrame() (first page of the VNB)
110 // SPF: GetSecondaryPanelFrame()
111 // SNB: SecondaryNotebook
112 // STBS: GetSecondaryToolbarSet()
113 // SF: GetStatusFrame() (see superclass)
114 //
115 // @verbatim
116 // +----------------------+ +----------------------+ +----------------------+
117 // | MB | | MB | | MB |
118 // +----------------------+ +----------------------+ +----------------------+
119 // | MTBS | | MTBS | | MTBS |
120 // +--------+-------------+ +--------+-------------+ +--------+-------------+
121 // |+--+ MPF|+--+ VPF | |+--+ MPF|+--+ VPF | |+--+ MPF|+--+ VPF |
122 // || +---+|| +--------+| || +---+|| +--------+| || +---+|| +--------+|
123 // || ||| || || ||| || || ||| ||
124 // || ||| VNB (VF) || || ||| || || ||| ||
125 // || ||| || || ||| || || ||| VNB (VF) ||
126 // || ||| || || MNB ||| || || MNB ||| ||
127 // || ||+-----------+| || ||| || || ||| ||
128 // || MNB |+-------------+ |+------+|| VNB (VF) || || ||| ||
129 // || ||+--+ SPF | +--------+| || || ||+-----------+|
130 // || ||| +--------+| |+--+ SPF|| || |+------+| STBS |
131 // || ||| || || +---+|| || +--------+-------------+
132 // || ||| SNB || || ||| || |+--+ SPF |
133 // || ||| || || ||| || || +-----------------+|
134 // || ||| || || SNB ||| || || SNB ||
135 // || ||+-----------+| || ||+-----------+| || ||
136 // |+------+| STBS | |+------+| STBS | |+--------------------+|
137 // +--------+-------------+ +--------+-------------+ +----------------------+
138 // | SF | | SF | | SF |
139 // +----------------------+ +----------------------+ +----------------------+
140 // Secondary below View Secondary below Main Secondary below Both
141 // @endverbatim
142 
143 #ifndef __vtkKWWindow_h
144 #define __vtkKWWindow_h
145 
146 #include "vtkKWWindowBase.h"
147 
148 class vtkKWFrame;
149 class vtkKWNotebook;
150 class vtkKWSplitFrame;
151 class vtkKWToolbar;
157 
159 {
160 public:
161 
162  static vtkKWWindow* New();
163  vtkTypeRevisionMacro(vtkKWWindow,vtkKWWindowBase);
164  void PrintSelf(ostream& os, vtkIndent indent);
165 
166  // Description:
167  // Main panel.
168  // The whole layout of the window is described at length at the beginning
169  // of this document.
170  virtual vtkKWFrame* GetMainPanelFrame();
171  virtual int GetMainPanelVisibility();
172  virtual void SetMainPanelVisibility(int);
173  vtkBooleanMacro(MainPanelVisibility, int );
174  virtual vtkKWNotebook* GetMainNotebook();
175  virtual int HasMainUserInterfaceManager();
176  virtual vtkKWUserInterfaceManager* GetMainUserInterfaceManager();
177  virtual void ShowMainUserInterface(const char *name);
178  vtkGetObjectMacro(MainSplitFrame, vtkKWSplitFrame);
179 
180  // Description:
181  // Secondary panel.
182  // The whole layout of the window is described at length at the beginning
183  // of this document.
184  virtual vtkKWFrame* GetSecondaryPanelFrame();
185  virtual int GetSecondaryPanelVisibility();
186  virtual void SetSecondaryPanelVisibility(int);
187  vtkBooleanMacro(SecondaryPanelVisibility, int );
188  virtual vtkKWNotebook* GetSecondaryNotebook();
189  virtual int HasSecondaryUserInterfaceManager();
190  virtual vtkKWUserInterfaceManager* GetSecondaryUserInterfaceManager();
191  virtual void ShowSecondaryUserInterface(const char *name);
192  vtkGetObjectMacro(SecondarySplitFrame, vtkKWSplitFrame);
193 
194  // Description:
195  // Set the panel layout type.
196  // The whole layout of the window is described at length at the beginning
197  // of this document.
198  // IMPORTANT: this ivar has to be set before calling Create(), and can
199  // not be changed afterwards.
200  //BTX
201  enum
202  {
203  PanelLayoutSecondaryBelowView = 0,
205  PanelLayoutSecondaryBelowMainAndView
206  };
207  //ETX
208  vtkSetClampMacro(PanelLayout, int,
211  vtkGetMacro(PanelLayout, int);
212  virtual void SetPanelLayoutToSecondaryBelowView()
213  { this->SetPanelLayout(vtkKWWindow::PanelLayoutSecondaryBelowView);};
214  virtual void SetPanelLayoutToSecondaryBelowMain()
215  { this->SetPanelLayout(vtkKWWindow::PanelLayoutSecondaryBelowMain);};
216  virtual void SetPanelLayoutToSecondaryBelowMainAndView()
217  {this->SetPanelLayout(vtkKWWindow::PanelLayoutSecondaryBelowMainAndView);};
218 
219  // Description:
220  // Set the view panel position. Default is on the right of the window.
221  // IMPORTANT: this ivar has to be set before calling Create(), and can
222  // not be changed afterwards.
223  //BTX
224  enum
225  {
226  ViewPanelPositionLeft = 0,
227  ViewPanelPositionRight
228  };
229  //ETX
230  virtual void SetViewPanelPosition(int);
231  virtual int GetViewPanelPosition();
232  virtual void SetViewPanelPositionToLeft()
233  { this->SetViewPanelPosition(vtkKWWindow::ViewPanelPositionLeft);};
234  virtual void SetViewPanelPositionToRight()
235  { this->SetViewPanelPosition(vtkKWWindow::ViewPanelPositionRight);};
236 
237  // Description:
238  // Get the frame available for "viewing".
239  // Override the superclass to return a page in the notebook of the
240  // view user interface manager (located in the first part of the
241  // SecondarySplitFrame).
242  // This method should be used instead of GetViewPanelFrame(), unless
243  // you really need to have both multiple notebook pages and common UI
244  // elements on top or below the notebook.
245  // The rational here is that GetViewFrame() always return the frame that
246  // can be used by users or developpers to add more "viewing" element (say,
247  // renderwidgets, 3D scenes), without knowing about the current layout.
248  virtual vtkKWFrame* GetViewFrame();
249 
250  // Description:
251  // View panel.
252  // The whole layout of the window is described at length at the beginning
253  // of this document.
254  // This panel is probably not going to be used much, by default it
255  // creates a single page in the notebook, which frame is returned by
256  // GetViewFrame(). The GetViewPanelFrame() method returns the parent of
257  // the notebook, if one really need to pack something out of the
258  // GetViewFrame().
259  virtual vtkKWNotebook* GetViewNotebook();
260  virtual int HasViewUserInterfaceManager();
261  virtual vtkKWUserInterfaceManager* GetViewUserInterfaceManager();
262  virtual void ShowViewUserInterface(const char *name);
263  virtual vtkKWFrame* GetViewPanelFrame();
264 
265  // Description:
266  // Get the secondary toolbar set.
267  virtual vtkKWToolbarSet* GetSecondaryToolbarSet();
268 
269  // Description:
270  // Set the status frame position. The default position is at the
271  // bottom of the window, but this object can also be displayed
272  // at the bottom of the main panel (MainPanel), at the bottom of
273  // the secondary panel (SecondaryPanel) or at the bottom of the view panel
274  // (ViewPanel). Note that if any of the above is used, the status bar
275  // will actually be hidden if the corresponding panel visibility is changed,
276  // since the status bar is actually packed in the panel frame itself. Set
277  // the position to LeftOfDivider or RightOfDivider to place the status
278  // bar out of the panel, but either of the left or the right of the
279  // main vertical divider.
280  //BTX
281  enum
282  {
283  StatusFramePositionWindow = 0,
288  StatusFramePositionRightOfDivider
289  };
290  //ETX
291  vtkGetMacro(StatusFramePosition, int);
292  virtual void SetStatusFramePosition(int);
293  virtual void SetStatusFramePositionToWindow()
294  { this->SetStatusFramePosition(
296  virtual void SetStatusFramePositionToMainPanel()
297  { this->SetStatusFramePosition(
299  virtual void SetStatusFramePositionToSecondaryPanel()
300  { this->SetStatusFramePosition(
302  virtual void SetStatusFramePositionToViewPanel()
303  { this->SetStatusFramePosition(
305  virtual void SetStatusFramePositionToLeftOfDivider()
306  { this->SetStatusFramePosition(
308  virtual void SetStatusFramePositionToRightOfDivider()
309  { this->SetStatusFramePosition(
311 
312  // Description:
313  // Call render on all widgets and elements that support that functionality
314  virtual void Render();
315 
316  // Description:
317  // Get the Application Settings Interface as well as the Application
318  // Settings User Interface Manager.
319  virtual vtkKWUserInterfaceManager* GetApplicationSettingsUserInterfaceManager();
320  virtual void ShowApplicationSettingsUserInterface(const char *name);
321  virtual vtkKWApplicationSettingsInterface *GetApplicationSettingsInterface();
322 
323  // Description:
324  // Update the UI. This will call:
325  // UpdateToolbarState
326  // UpdateEnableState
327  // UpdateMenuState
328  // Update on all panels belonging to the UserInterfaceManager, if any
329  virtual void Update();
330 
331  // Description:
332  // Update the "enable" state of the object and its internal parts.
333  // Depending on different Ivars (this->Enabled, the application's
334  // Limited Edition Mode, etc.), the "enable" state of the object is updated
335  // and propagated to its internal parts/subwidgets. This will, for example,
336  // enable/disable parts of the widget UI, enable/disable the visibility
337  // of 3D widgets, etc.
338  // Note: if you need to enable/disable a menu item conditionally in a
339  // subclass, do it so by reimplementing UpdateMenuState(); do not forget to
340  // call the parent class's UpdateMenuState() from the subclass as well.
341  virtual void UpdateEnableState();
342  virtual void UpdateMenuState();
343 
344  // Description:
345  // Update the toolbar state
346  virtual void UpdateToolbarState();
347 
348  // Description:
349  // Deallocate/delete/reparent some internal objects in order to solve
350  // reference loops that would prevent this instance from being deleted.
351  virtual void PrepareForDelete();
352 
353  // Description:
354  // Callbacks. Internal, do not use.
355  virtual void MainPanelVisibilityCallback();
356  virtual void SecondaryPanelVisibilityCallback();
357  virtual void PrintSettingsCallback();
359  virtual void NumberOfToolbarsChangedCallback();
360 
361  // Description:
362  // Some constants
363  vtkGetStringMacro(MainPanelSizeRegKey);
364  vtkGetStringMacro(MainPanelVisibilityRegKey);
365  vtkGetStringMacro(MainPanelVisibilityKeyAccelerator);
366  vtkGetStringMacro(HideMainPanelMenuLabel);
367  vtkGetStringMacro(ShowMainPanelMenuLabel);
368  vtkGetStringMacro(SecondaryPanelSizeRegKey);
369  vtkGetStringMacro(SecondaryPanelVisibilityRegKey);
370  vtkGetStringMacro(SecondaryPanelVisibilityKeyAccelerator);
371  vtkGetStringMacro(HideSecondaryPanelMenuLabel);
372  vtkGetStringMacro(ShowSecondaryPanelMenuLabel);
373  vtkGetStringMacro(DefaultViewPanelName);
374  vtkGetStringMacro(TclInteractorMenuLabel);
375  vtkGetStringMacro(ViewPanelPositionRegKey);
376  vtkGetStringMacro(LogDialogMenuLabel);
377 
378  // Description:
379  // Add all the default observers needed by that object, or remove
380  // all the observers that were added through AddCallbackCommandObserver.
381  // Subclasses can override these methods to add/remove their own default
382  // observers, but should call the superclass too.
383  virtual void AddCallbackCommandObservers();
384  virtual void RemoveCallbackCommandObservers();
385 
386 protected:
387  vtkKWWindow();
388  ~vtkKWWindow();
389 
390  // Description:
391  // Create the widget.
392  virtual void CreateWidget();
393 
394  // Description:
395  // Save/Restore window geometry
396  virtual void SaveWindowGeometryToRegistry();
397  virtual void RestoreWindowGeometryFromRegistry();
398 
399  // Description:
400  // Show a main or secondary user interface panel.
401  // The ShowMainUserInterface() method will
402  // query the main UserInterfaceManager (UIM) to check if it is indeed
403  // managing the UIP, and show/raise that UIP accordingly.
404  // The ShowSecondaryUserInterface will do the same on the secondary UIM.
405  // The ShowViewUserInterface will do the same on the view UIM.
406  // The ShowApplicationSettingsUserInterface will do the same on the app
407  // settings UIM.
408  virtual void ShowMainUserInterface(vtkKWUserInterfacePanel *panel);
409  virtual void ShowSecondaryUserInterface(vtkKWUserInterfacePanel *panel);
410  virtual void ShowViewUserInterface(vtkKWUserInterfacePanel *panel);
411  virtual void ShowApplicationSettingsUserInterface(vtkKWUserInterfacePanel *panel);
412 
413  // Description:
414  // Pack/repack the UI
415  virtual void Pack();
416 
418 
420 
422 
424 
426 
427  // Description:
428  // Some constants
429  vtkSetStringMacro(MainPanelSizeRegKey);
430  vtkSetStringMacro(MainPanelVisibilityRegKey);
431  vtkSetStringMacro(MainPanelVisibilityKeyAccelerator);
432  vtkSetStringMacro(HideMainPanelMenuLabel);
433  vtkSetStringMacro(ShowMainPanelMenuLabel);
434  vtkSetStringMacro(SecondaryPanelSizeRegKey);
435  vtkSetStringMacro(SecondaryPanelVisibilityRegKey);
436  vtkSetStringMacro(SecondaryPanelVisibilityKeyAccelerator);
437  vtkSetStringMacro(HideSecondaryPanelMenuLabel);
438  vtkSetStringMacro(ShowSecondaryPanelMenuLabel);
439  vtkSetStringMacro(DefaultViewPanelName);
440  vtkSetStringMacro(TclInteractorMenuLabel);
441  vtkSetStringMacro(ViewPanelPositionRegKey);
442  vtkSetStringMacro(LogDialogMenuLabel);
443 
444  // Description:
445  // Processes the events that are passed through CallbackCommand (or others).
446  // Subclasses can oberride this method to process their own events, but
447  // should call the superclass too.
448  virtual void ProcessCallbackCommandEvents(
449  vtkObject *caller, unsigned long event, void *calldata);
450 
451  // Description:
452  // Populate the menus.
453  // Note: if you need to enable/disable a menu item conditionally in a
454  // subclass, do it so by reimplementing UpdateMenuState(); do not forget to
455  // call the parent class's UpdateMenuState() from the subclass as well.
456  virtual void PopulateWindowMenu();
457  virtual void PopulateViewMenu();
458 
459 private:
460 
461  vtkKWNotebook *MainNotebook;
462  vtkKWNotebook *SecondaryNotebook;
463  vtkKWNotebook *ViewNotebook;
464 
465  vtkKWToolbarSet *SecondaryToolbarSet;
466 
467  vtkKWUserInterfaceManagerNotebook *MainUserInterfaceManager;
468  vtkKWUserInterfaceManagerNotebook *SecondaryUserInterfaceManager;
469  vtkKWUserInterfaceManagerNotebook *ViewUserInterfaceManager;
470 
471  vtkKWUserInterfaceManagerDialog *ApplicationSettingsUserInterfaceManager;
472 
473  vtkKWWindow(const vtkKWWindow&); // Not implemented
474  void operator=(const vtkKWWindow&); // Not implemented
475 
476  // Description:
477  // Some constants
478  char *MainPanelSizeRegKey;
479  char *MainPanelVisibilityRegKey;
480  char *MainPanelVisibilityKeyAccelerator;
481  char *HideMainPanelMenuLabel;
482  char *ShowMainPanelMenuLabel;
483  char *SecondaryPanelSizeRegKey;
484  char *SecondaryPanelVisibilityRegKey;
485  char *SecondaryPanelVisibilityKeyAccelerator;
486  char *HideSecondaryPanelMenuLabel;
487  char *ShowSecondaryPanelMenuLabel;
488  char *DefaultViewPanelName;
489  char *TclInteractorMenuLabel;
490  char *ViewPanelPositionRegKey;
491  char *LogDialogMenuLabel;
492 };
493 
494 #endif
495