KWWidgets
vtkKWUserInterfaceManagerDialog.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Module: $RCSfile: vtkKWUserInterfaceManagerDialog.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 vtkKWUserInterfaceManagerDialog - 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. As such, it is a
18 // concrete implementation of a vtkKWUserInterfaceManager. It uses a dialog
19 // under the hood to display all pages in a "Preferences" dialog style: the
20 // dialog is split into two parts: on the left, a tree with entries
21 // corresponding to the name of specific UI elements found in the panels.
22 // If an entry is selected, the corresponding UI element is display on the
23 // right side of the dialog. This allows a lot of small UI elements to be
24 // accessed pretty easily while keeping the size of the whole dialog small.
25 // For each panel, this class creates an entry in the tree using the
26 // panel name. For each page in the panel, it creates a sub-entry (leaf)
27 // under the panel name entry, using the page name. Then for each UI elements
28 // in that page, it looks for instances of vtkKWFrameWithLabel. This is the
29 // only constraint put on the panels, other than that, the panels
30 // (vtkKWUserInterfacePanel) can be created as usual, and managed by any
31 // subclass of vtkKWUserInterfaceManager. This is not too big a constraint
32 // since most panels are built that way. For a concrete example of such
33 // a panel, check vtkKWApplicationSettingsInterface.
34 // .SECTION Thanks
35 // This work is part of the National Alliance for Medical Image
36 // Computing (NAMIC), funded by the National Institutes of Health
37 // through the NIH Roadmap for Medical Research, Grant U54 EB005149.
38 // Information on the National Centers for Biomedical Computing
39 // can be obtained from http://nihroadmap.nih.gov/bioinformatics.
40 // .SECTION See Also
41 // vtkKWUserInterfaceManager vtkKWUserInterfacePanel vtkKWApplicationSettingsInterface
42 
43 #ifndef __vtkKWUserInterfaceManagerDialog_h
44 #define __vtkKWUserInterfaceManagerDialog_h
45 
47 
48 class vtkKWIcon;
49 class vtkKWNotebook;
50 class vtkKWPushButton;
51 class vtkKWSeparator;
52 class vtkKWSplitFrame;
53 class vtkKWTopLevel;
55 class vtkKWUserInterfaceManagerDialogInternals;
57 class vtkKWWidget;
58 
60 {
61 public:
64  void PrintSelf(ostream& os, vtkIndent indent);
65 
66  // Description:
67  // Create the manager widget (i.e. the widget that will group and display
68  // all user interface panels). A notebook must be associated to the manager
69  // before it is created.
70  virtual void Create();
71 
72  // Description:
73  // Set the panel node visibility. If On, each panel will show up as
74  // a node in the tree, acting as a parent to the page nodes or the section
75  // nodes. Defaults to Off to avoid too much clutter in the tree.
76  virtual void SetPanelNodeVisibility(int);
77  vtkGetMacro(PanelNodeVisibility, int);
78  vtkBooleanMacro(PanelNodeVisibility, int);
79 
80  // Description:
81  // Set the page node visibility. If On, each page will show up as
82  // a node in the tree, acting as a parent to the section nodes.
83  // Default to On. Since sections can have the same name within different
84  // pages, it is advised to leave it On.
85  virtual void SetPageNodeVisibility(int);
86  vtkGetMacro(PageNodeVisibility, int);
87  vtkBooleanMacro(PageNodeVisibility, int);
88 
89  // Description:
90  // Access to the dialog/toplevel
91  // Can be used to change its title, and master window
92  vtkGetObjectMacro(TopLevel, vtkKWTopLevel);
93 
94  // Description:
95  // Get the application instance for this object.
96  // Override the superclass to try to retrieve the toplevel's application
97  // if it was not set already.
99 
100  // Description:
101  // Raise a specific section, given a panel, a page id (or page title)
102  // and a section name. If panel is NULL, page_id is < 0,
103  // page_title is NULL or empty, section is NULL or empty, then any of these
104  // parameters will be ignored and the first matching section will be picked.
105  virtual void RaiseSection(int page_id,
106  const char *section);
107  virtual void RaiseSection(vtkKWUserInterfacePanel *panel,
108  const char *page_title,
109  const char *section);
110 
111  // Description:
112  // Instruct the manager to reserve or remove a page for a given panel.
113  // In this concrete implementation, this adds or removes a page to the
114  // notebook, and sets the page tag to be the panel's ID.
115  // Note that you should use the panel's own API to add a page to a panel:
116  // this will automatically call this method with the proper panel parameter
117  // (see vtkKWUserInterfacePanel::AddPage() and
118  // vtkKWUserInterfacePanel::RemovePage()).
119  // Return a unique positive ID for the page that was reserved/removed,
120  // or < 0 on error.
121  virtual int AddPage(vtkKWUserInterfacePanel *panel,
122  const char *title,
123  const char *balloon = 0,
124  vtkKWIcon *icon = 0);
125  virtual int RemovePage(vtkKWUserInterfacePanel *panel,
126  const char *title);
127 
128  // Description:
129  // Set a page's title, balloon help and icon.
130  virtual void SetPageTitle(int id, const char *new_title);
131  virtual void SetPageBalloonHelpString(int id, const char *str);
132  virtual void SetPageIcon(int id, vtkKWIcon *icon);
133  virtual void SetPageIconToPredefinedIcon(int id, int icon_index);
134 
135  // Description:
136  // Retrieve the widget corresponding to a given page reserved by the manager.
137  // This can be done through the unique page ID, or using a panel and the
138  // page title. The user UI components should be inserted into this widget.
139  // In this concrete implementation, this returns the inner frame of a
140  // notebook's page.
141  // Note that you should use the panel's own API to get a page widget: this
142  // will automatically call this method with the proper ID or panel parameter
143  // (see vtkKWUserInterfacePanel::GetPageWidget()).
144  // Return NULL on error.
145  virtual vtkKWWidget* GetPageWidget(int id);
147  const char *title);
148 
149  // Description:
150  // Retrieve the parent widget of the pages associated to a panel. It is
151  // the unique widget that is common to all pages in the chain of parents.
152  // Note that you should use the panel's own API to get the page parent: this
153  // will automatically call this method with the proper panel parameter
154  // (see vtkKWUserInterfacePanel::GetPagesParentWidget()).
156 
157  // Description:
158  // Raise a page reserved by the manager. This can be done through the unique
159  // page ID, or using a panel and the page title.
160  // In this concrete implementation, this raises a notebook's page.
161  // Note that you should use the panel's own API to raise a page: this
162  // will automatically call this method with the proper ID or panel parameter
163  // (see vtkKWUserInterfacePanel::RaisePage()).
164  // Note that if the panel corresponding to the page to raise has not been
165  // created yet, it will be created automatically by calling the panel's
166  // Create() method (see vtkKWUserInterfacePanel::Create()) ; this allows the
167  // creation of the panel to be delayed until it is really needed.
168  virtual void RaisePage(int id);
169  virtual void RaisePage(vtkKWUserInterfacePanel *panel,
170  const char *title);
171 
172  // Description:
173  // Show/Hide a panel. It will make sure the pages reserved by the manager
174  // for this panel are shown/hidden.
175  // In this concrete implementation, this shows/hides all notebook's pages
176  // belonging to this panel.
177  // RaisePanel() behaves like ShowPanel(), but it will also try to bring
178  // up the first page of the panel to the front (i.e., "select" it).
179  // IsPanelVisible() checks if the pages of the panel are visible/shown.
180  // Note that you should use the panel's own API to show a panel: this
181  // will automatically call this method with the proper panel parameter
182  // (see vtkKWUserInterfacePanel::Show()).
183  // Note that if the panel has not been created yet, it will be created
184  // automatically by calling the panel's Create() method (see
185  // vtkKWUserInterfacePanel::Create()) ; this allows the creation of the
186  // panel to be delayed until it is really needed.
187  // Return 1 on success, 0 on error.
188  virtual int ShowPanel(vtkKWUserInterfacePanel *panel);
189  virtual int HidePanel(vtkKWUserInterfacePanel *panel);
190  virtual int IsPanelVisible(vtkKWUserInterfacePanel *panel);
191 
192  // Description:
193  // Get the panel from a page ID (return the ID of the panel that holds
194  // that page).
195  virtual vtkKWUserInterfacePanel* GetPanelFromPageId(int page_id);
196 
197  // Description:
198  // Set/Get the vertical scrollbar visibility of the tree (off by default)
199  virtual void SetVerticalScrollbarVisibility(int val);
200  virtual int GetVerticalScrollbarVisibility();
201  vtkBooleanMacro(VerticalScrollbarVisibility, int);
202 
203  // Description:
204  // Callbacks. Internal, do not use.
205  virtual void SelectionChangedCallback();
206 
207 protected:
210 
211  // Description:
212  // Remove the widgets of all pages belonging to a panel. It is called
213  // by RemovePanel().
214  // In this concrete implementation, this will remove all notebook's pages
215  // belonging to this panel.
216  // Return 1 on success, 0 on error.
217  virtual int RemovePageWidgets(vtkKWUserInterfacePanel *panel);
218 
219  vtkKWNotebook *Notebook;
220  vtkKWTopLevel *TopLevel;
221  vtkKWSplitFrame *SplitFrame;
223  vtkKWPushButton *CloseButton;
224  vtkKWSeparator *Separator;
225 
226  // PIMPL Encapsulation for STL containers
227  //BTX
228  vtkKWUserInterfaceManagerDialogInternals *Internals;
229  //ETX
230 
231  virtual void PopulateTree();
232  virtual int ShowSelectedNodeSection();
233  virtual int CreateAllPanels();
234 
235  int PanelNodeVisibility;
236  int PageNodeVisibility;
237 
238  // Description:
239  // This method is (and should be) called each time the number of panels
240  // changes (for example, after AddPanel() / RemovePanel())
241  virtual void NumberOfPanelsChanged();
242 
243  int GetWidgetLocation(
244  const char *widget, vtkKWUserInterfacePanel **panel, int *page_id);
245 
246 private:
247 
249  void operator=(const vtkKWUserInterfaceManagerDialog&); // Not Implemented
250 };
251 
252 #endif
253