KWWidgets
debian/tmp/usr/include/KWWidgets/vtkKWUserInterfaceManager.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Module: $RCSfile: vtkKWUserInterfaceManager.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 vtkKWUserInterfaceManager - a user interface manager.
15 // .SECTION Description
16 // This class is used to abstract the way a set of interface "panels"
17 // (vtkKWUserInterfacePanel) can be grouped inside a widget.
18 // For example, if a concrete implementation of that class
19 // uses a notebook as its underlying widget, then it will deliver a notebook's
20 // page when one of its managed panels request a "page" (i.e. a section
21 // within a panel). If another concrete implementation chooses for
22 // a flat GUI for example, then it will likely return frames as pages and
23 // pack them on top of each other.
24 // This class is not a widget. Concrete implementation of this class will
25 // provide an access point to a widget into which the manager will organize
26 // its panels (a notebook, a frame, etc.).
27 // Besides packing this widget, you will just have to set each panel's
28 // UserInterfaceManager ivar to point to this manager, and the rest should
29 // be taken care of (i.e. you do not need to manually add a panel to a manager,
30 // or manually request a page from the manager, it should be done through the
31 // panel's API).
32 // .SECTION See Also
33 // vtkKWUserInterfaceManagerNotebook vtkKWUserInterfacePanel
34 
35 #ifndef __vtkKWUserInterfaceManager_h
36 #define __vtkKWUserInterfaceManager_h
37 
38 #include "vtkKWObject.h"
39 
40 class vtkKWIcon;
41 class vtkKWWidget;
43 class vtkKWUserInterfaceManagerInternals;
44 
46 {
47 public:
48  vtkTypeRevisionMacro(vtkKWUserInterfaceManager,vtkKWObject);
49  void PrintSelf(ostream& os, vtkIndent indent);
50 
51  // Description:
52  // Create the manager widget (i.e. the widget that will group and display
53  // all user interface panels).
54  virtual void Create();
55  virtual int IsCreated();
56 
57  // Description:
58  // Enable/Disable this interface. This propagates SetEnabled() calls to all
59  // panels.
60  virtual void SetEnabled(int);
61  virtual void UpdateEnableState();
62 
63  // Description:
64  // Iterate over all panels and call Update() for each one. This will refresh
65  // the panels (provided that Update() has been reimplemented).
66  virtual void Update();
67 
68  // Description:
69  // Add a panel to the manager.
70  // Note that you most probably do not need to call this method, since setting
71  // a panel's UserInterfaceManager ivar will add the panel automatically
72  // (see vtkKWUserInterfacePanel::SetUserInterfaceManager()).
73  // Return a unique positive ID corresponding to that panel, or < 0 on error.
74  virtual int AddPanel(vtkKWUserInterfacePanel *panel);
75  virtual int HasPanel(vtkKWUserInterfacePanel *panel);
76 
77  // Description:
78  // Get the number of panel
79  virtual int GetNumberOfPanels();
80 
81  // Description:
82  // Get the panel from its name or ID, from a page ID (return the ID of the
83  // panel that holds that page), or the nth panel.
84  virtual vtkKWUserInterfacePanel* GetPanel(const char *panel_name);
85  virtual vtkKWUserInterfacePanel* GetPanel(int id);
86  virtual vtkKWUserInterfacePanel* GetPanelFromPageId(int id) = 0;
87  virtual vtkKWUserInterfacePanel* GetNthPanel(int rank);
88 
89  // Description:
90  // Remove a panel (or all) from the manager.
91  // Note that you most probably do not need to call this method, since setting
92  // a panel's UserInterfaceManager ivar to NULL will remove the panel
93  // automatically (this is done in the panel's destructor).
94  // Return 1 on success, 0 on error.
95  virtual int RemovePanel(vtkKWUserInterfacePanel *panel);
96  virtual void RemoveAllPanels();
97 
98  // Description:
99  // Instruct the manager to reserve or remove a page for a given panel.
100  // Note that you should use the panel's own API to add a page to a panel:
101  // this will automatically call this method with the proper panel parameter
102  // (see vtkKWUserInterfacePanel::AddPage() and
103  // vtkKWUserInterfacePanel::RemovePage()).
104  // Return a unique positive ID for the page that was reserved/removed,
105  // or < 0 on error.
106  virtual int AddPage(vtkKWUserInterfacePanel *panel,
107  const char *title,
108  const char *balloon = 0,
109  vtkKWIcon *icon = 0) = 0;
110  virtual int RemovePage(vtkKWUserInterfacePanel *panel,
111  const char *title) = 0;
112 
113  // Description:
114  // Set a page's title, balloon help and icon.
115  virtual void SetPageTitle(int id, const char *title) = 0;
116  virtual void SetPageBalloonHelpString(int id, const char *str) = 0;
117  virtual void SetPageIcon(int id, vtkKWIcon *icon) = 0;
118  virtual void SetPageIconToPredefinedIcon(int id, int icon_index) = 0;
119 
120  // Description:
121  // Retrieve the widget corresponding to a given page reserved by the manager.
122  // This can be done through the unique page ID, or using a panel and the
123  // page title. The user UI components should be inserted into this widget.
124  // Note that you should use the panel's own API to get a page widget: this
125  // will automatically call this method with the proper ID or panel parameter
126  // (see vtkKWUserInterfacePanel::GetPageWidget()).
127  // Return NULL on error.
128  virtual vtkKWWidget* GetPageWidget(int id) = 0;
129  virtual vtkKWWidget* GetPageWidget(vtkKWUserInterfacePanel *panel,
130  const char *title) = 0;
131 
132  // Description:
133  // Retrieve the parent widget of the pages associated to a panel. It is
134  // the unique widget that is common to all pages in the chain of parents.
135  // Note that you should use the panel's own API to get the page parent: this
136  // will automatically call this method with the proper panel parameter
137  // (see vtkKWUserInterfacePanel::GetPagesParentWidget()).
138  virtual vtkKWWidget *GetPagesParentWidget(vtkKWUserInterfacePanel *panel)= 0;
139 
140  // Description:
141  // Raise a page reserved by the manager. This can be done through the unique
142  // page ID, or using a panel and the page title.
143  // Note that you should use the panel's own API to raise a page: this
144  // will automatically call this method with the proper ID or panel parameter
145  // (see vtkKWUserInterfacePanel::RaisePage()).
146  virtual void RaisePage(int id) = 0;
147  virtual void RaisePage(vtkKWUserInterfacePanel *panel,
148  const char *title) = 0;
149 
150  // Description:
151  // Show/Hide a panel. It will make sure the pages reserved by the manager
152  // for this panel are shown/hidden.
153  // RaisePanel() behaves like ShowPanel(), but it will also try to bring
154  // up the first page of the panel to the front (i.e., "select" it).
155  // IsPanelVisible() checks if the pages of the panel are visible/shown.
156  // Note that you should use the panel's own API to show/raise a panel: this
157  // will automatically call this method with the proper panel parameter
158  // (see vtkKWUserInterfacePanel::Show/Raise()).
159  // Return 1 on success, 0 on error.
160  virtual int ShowPanel(vtkKWUserInterfacePanel *panel) = 0;
161  virtual int HidePanel(vtkKWUserInterfacePanel *panel) = 0;
162  virtual int IsPanelVisible(vtkKWUserInterfacePanel *panel) = 0;
163  virtual int RaisePanel(vtkKWUserInterfacePanel *panel)
164  { return this->ShowPanel(panel); };
165 
166  // Description:
167  // Show/hide all panels.
168  virtual void ShowAllPanels();
169  virtual void HideAllPanels();
170 
171  // Description:
172  // Update a panel according to the manager settings (i.e., it just performs
173  // manager-specific changes on the panel). Note that it does not call the
174  // panel's Update() method, on the opposite the panel's Update() will call
175  // this method if the panel has a UIM set.
177 
178 protected:
181 
182  // Description:
183  // Remove the widgets of all pages belonging to a panel. It is called
184  // by RemovePanel() and should be overloaded if the concrete implementation
185  // of the manager needs to unmap/unpack widgets before everything is deleted.
186  // Return 1 on success, 0 on error.
187  virtual int RemovePageWidgets(vtkKWUserInterfacePanel *)
188  { return 1; };
189 
190  int IdCounter;
191 
192  //BTX
193 
194  // A panel slot associate a panel to a unique Id
195 
196  class PanelSlot
197  {
198  public:
199  int Id;
201  };
202 
203  // PIMPL Encapsulation for STL containers
204 
205  vtkKWUserInterfaceManagerInternals *Internals;
206  friend class vtkKWUserInterfaceManagerInternals;
207 
208  // Helper methods
209  // Get a panel slot given a panel or an id, check if the manager has a given
210  // panel, get a panel id given a panel, etc.
211 
212  PanelSlot* GetPanelSlot(vtkKWUserInterfacePanel *panel);
213  PanelSlot* GetPanelSlot(int id);
214  PanelSlot* GetPanelSlot(const char *panel_name);
215  PanelSlot* GetNthPanelSlot(int rank);
216  int GetPanelId(vtkKWUserInterfacePanel *panel);
217 
218  //ETX
219 
220  // Description:
221  // This method is (and should be) called each time the number of panels
222  // changes (for example, after AddPanel() / RemovePanel())
223  virtual void NumberOfPanelsChanged() {};
224 
225 private:
226 
227  int ManagerIsCreated;
228 
229  vtkKWUserInterfaceManager(const vtkKWUserInterfaceManager&); // Not implemented
230  void operator=(const vtkKWUserInterfaceManager&); // Not Implemented
231 };
232 
233 #endif
234