KWWidgets
debian/tmp/usr/include/KWWidgets/vtkKWUserInterfaceManagerNotebook.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Module: $RCSfile: vtkKWUserInterfaceManagerNotebook.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 vtkKWUserInterfaceManagerNotebook - 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 notebook
19 // under the hood and delivers a notebook's page when one of its managed panels
20 // request a "page" (i.e. a section within a panel). Within the notebook, each
21 // page will be associated to a tag corresponding to its panel's ID. This
22 // allows panels to be shown once at a time, or grouped, or displayed using
23 // more advanced combination (like most recently used pages among all panels,
24 // pinned pages, etc.).
25 // This class is not a widget, the notebook is. Besides packing the notebook,
26 // you will just have to set each panel's UserInterfaceManager ivar to point
27 // to this manager, and the rest should be taken care of (i.e. you do not
28 // need to manually add a panel to a manager, or manually request a page from
29 // the manager, it should be done through the panel's API).
30 // .SECTION See Also
31 // vtkKWUserInterfaceManager vtkKWUserInterfacePanel
32 
33 #ifndef __vtkKWUserInterfaceManagerNotebook_h
34 #define __vtkKWUserInterfaceManagerNotebook_h
35 
37 
38 class vtkKWIcon;
39 class vtkKWNotebook;
41 class vtkKWWidget;
42 class vtkKWUserInterfaceManagerNotebookInternals;
43 
45 {
46 public:
49  void PrintSelf(ostream& os, vtkIndent indent);
50 
51  // Description:
52  // Set the user interface manager's notebook. This has to be done before
53  // Create() is called (i.e. the sooner, the better), and can be done only
54  // once.
55  virtual void SetNotebook(vtkKWNotebook*);
56  vtkGetObjectMacro(Notebook, vtkKWNotebook);
57 
58  // Description:
59  // Get the application instance for this object.
60  // Override the superclass to try to retrieve the notebook's application
61  // if it was not set already.
63 
64  // Description:
65  // Create the manager widget (i.e. the widget that will group and display
66  // all user interface panels). A notebook must be associated to the manager
67  // before it is created.
68  virtual void Create();
69 
70  // Description:
71  // Instruct the manager to reserve or remove a page for a given panel.
72  // In this concrete implementation, this adds or removes a page to the
73  // notebook, and sets the page tag to be the panel's ID.
74  // Note that you should use the panel's own API to add a page to a panel:
75  // this will automatically call this method with the proper panel parameter
76  // (see vtkKWUserInterfacePanel::AddPage() and
77  // vtkKWUserInterfacePanel::RemovePage()).
78  // Return a unique positive ID for the page that was reserved/removed,
79  // or < 0 on error.
80  virtual int AddPage(vtkKWUserInterfacePanel *panel,
81  const char *title,
82  const char *balloon = 0,
83  vtkKWIcon *icon = 0);
84  virtual int RemovePage(vtkKWUserInterfacePanel *panel,
85  const char *title);
86 
87  // Description:
88  // Set a page's title, balloon help and icon.
89  virtual void SetPageTitle(int id, const char *new_title);
90  virtual void SetPageBalloonHelpString(int id, const char *str);
91  virtual void SetPageIcon(int id, vtkKWIcon *icon);
92  virtual void SetPageIconToPredefinedIcon(int id, int icon_index);
93 
94  // Description:
95  // Retrieve the widget corresponding to a given page reserved by the manager.
96  // This can be done through the unique page ID, or using a panel and the
97  // page title. The user UI components should be inserted into this widget.
98  // In this concrete implementation, this returns the inner frame of a
99  // notebook's page.
100  // Note that you should use the panel's own API to get a page widget: this
101  // will automatically call this method with the proper ID or panel parameter
102  // (see vtkKWUserInterfacePanel::GetPageWidget()).
103  // Return NULL on error.
104  virtual vtkKWWidget* GetPageWidget(int id);
106  const char *title);
107 
108  // Description:
109  // Retrieve the parent widget of the pages associated to a panel. It is
110  // the unique widget that is common to all pages in the chain of parents.
111  // Note that you should use the panel's own API to get the page parent: this
112  // will automatically call this method with the proper panel parameter
113  // (see vtkKWUserInterfacePanel::GetPagesParentWidget()).
115 
116  // Description:
117  // Raise a page reserved by the manager. This can be done through the unique
118  // page ID, or using a panel and the page title.
119  // In this concrete implementation, this raises a notebook's page.
120  // Note that you should use the panel's own API to raise a page: this
121  // will automatically call this method with the proper ID or panel parameter
122  // (see vtkKWUserInterfacePanel::RaisePage()).
123  // Note that if the panel corresponding to the page to raise has not been
124  // created yet, it will be created automatically by calling the panel's
125  // Create() method (see vtkKWUserInterfacePanel::Create()) ; this allows the
126  // creation of the panel to be delayed until it is really needed.
127  virtual void RaisePage(int id);
128  virtual void RaisePage(vtkKWUserInterfacePanel *panel,
129  const char *title);
130 
131  // Description:
132  // Show/Hide a panel. It will make sure the pages reserved by the manager
133  // for this panel are shown/hidden.
134  // In this concrete implementation, this shows/hides all notebook's pages
135  // belonging to this panel.
136  // RaisePanel() behaves like ShowPanel(), but it will also try to bring
137  // up the first page of the panel to the front (i.e., "select" it).
138  // IsPanelVisible() checks if the pages of the panel are visible/shown.
139  // Note that you should use the panel's own API to show a panel: this
140  // will automatically call this method with the proper panel parameter
141  // (see vtkKWUserInterfacePanel::Show()).
142  // Note that if the panel has not been created yet, it will be created
143  // automatically by calling the panel's Create() method (see
144  // vtkKWUserInterfacePanel::Create()) ; this allows the creation of the
145  // panel to be delayed until it is really needed.
146  // Return 1 on success, 0 on error.
147  virtual int ShowPanel(vtkKWUserInterfacePanel *panel);
148  virtual int HidePanel(vtkKWUserInterfacePanel *panel);
149  virtual int IsPanelVisible(vtkKWUserInterfacePanel *panel);
150  virtual int RaisePanel(vtkKWUserInterfacePanel *panel);
151 
152  // Description:
153  // Update a panel according to the manager settings (i.e., it just performs
154  // manager-specific changes on the panel). Note that it does not call the
155  // panel's Update() method, on the opposite the panel's Update() will call
156  // this method if the panel has a UIM set.
157  virtual void UpdatePanel(vtkKWUserInterfacePanel *panel);
158 
159  // Description:
160  // Get the panel from a page ID (return the ID of the panel that holds
161  // that page).
162  virtual vtkKWUserInterfacePanel* GetPanelFromPageId(int page_id);
163 
164  // Description:
165  // Enable/disable Drag and Drop. If enabled, elements of the user interface
166  // can be drag&drop within the same panel, or between different panels.
167  virtual void SetEnableDragAndDrop(int);
168  vtkBooleanMacro(EnableDragAndDrop, int);
169  vtkGetMacro(EnableDragAndDrop, int);
170 
171  // Description:
172  // Get the number of Drag&Drop entries so far.
173  // Delete all Drag&Drop entries.
174  virtual int GetNumberOfDragAndDropEntries();
175  virtual int DeleteAllDragAndDropEntries();
176 
177  // Description:
178  // Save/restore Drag&Drop entries to a text file.
179  // GetDragAndDropEntry() can be used to get a Drag&Drop entry parameters
180  // as plain text string.
181  // DragAndDropWidget() will perform a Drag&Drop given parameters similar
182  // to those acquired through GetDragAndDropEntry().
183  virtual int GetDragAndDropEntry(
184  int idx,
185  ostream &widget_label,
186  ostream &from_panel_name,
187  ostream &from_page_title,
188  ostream &from_after_widget_label,
189  ostream &to_panel_name,
190  ostream &to_page_title,
191  ostream &to_after_widget_label);
192  virtual int DragAndDropWidget(
193  const char *widget_label,
194  const char *from_panel_name,
195  const char *from_page_title,
196  const char *from_after_widget_label,
197  const char *to_panel_name,
198  const char *to_page_title,
199  const char *to_after_widget_label);
200 
201  // Description:
202  // Lock Drag and Drop entries. If enabled, GetDragAndDropEntry() will
203  // not return any entry, and DragAndDropWidget() will not set any.
204  vtkBooleanMacro(LockDragAndDropEntries, int);
205  vtkSetMacro(LockDragAndDropEntries, int);
206  vtkGetMacro(LockDragAndDropEntries, int);
207 
208  //BTX
209  // A Widget location.
210  // Store both the page the widget is packed in, and the widget it is
211  // packed after (if any).
212  // @cond nested_class
213  class WidgetLocation
214  {
215  public:
216  WidgetLocation();
217  void Empty();
218 
219  int PageId;
220  vtkKWWidget *AfterWidget;
221  };
222  // @endcond
223 
224  // A D&D entry.
225  // Store the widget source and target location.
226  // @cond nested_class
227  class DragAndDropEntry
228  {
229  public:
230  DragAndDropEntry();
231 
232  vtkKWWidget *Widget;
233  WidgetLocation FromLocation;
234  WidgetLocation ToLocation;
235  };
236  // @endcond
237  //ETX
238 
239  // Description:
240  // Callbacks. Internal, do not use.
241  virtual void DragAndDropEndCallback(
242  int x, int y,
243  vtkKWWidget *widget, vtkKWWidget *anchor, vtkKWWidget *target);
244 
245 protected:
248 
249  // Description:
250  // Remove the widgets of all pages belonging to a panel. It is called
251  // by RemovePanel().
252  // In this concrete implementation, this will remove all notebook's pages
253  // belonging to this panel.
254  // Return 1 on success, 0 on error.
255  virtual int RemovePageWidgets(vtkKWUserInterfacePanel *panel);
256 
258 
259  // Description:
260  // Update Drag And Drop bindings
261  virtual void UpdatePanelDragAndDrop(vtkKWUserInterfacePanel *panel);
264 
265  //BTX
266 
267  // Description:
268  // Check if a given widget can be Drag&Dropped given our framework.
269  // At the moment, only labeled frame can be D&D. If **anchor is not NULL,
270  // it will be assigned the widget D&D anchor (i.e. the internal part of
271  // the widget that is actually used to grab the widget).
272  // Return 1 if can be D&D, 0 otherwise.
273  virtual int CanWidgetBeDragAndDropped(
274  vtkKWWidget *widget, vtkKWWidget **anchor = 0);
275 
276  // Description:
277  // Assuming that the widget can be Drag&Dropped given our framework,
278  // return a label that will be used to identify it. This is mostly used to
279  // save a D&D event to a text string/file.
280  virtual char* GetDragAndDropWidgetLabel(vtkKWWidget *widget);
281 
282  // PIMPL Encapsulation for STL containers
283 
284  vtkKWUserInterfaceManagerNotebookInternals *Internals;
285  friend class vtkKWUserInterfaceManagerNotebookInternals;
286 
287  // Description:
288  // Get the location of a widget.
289  virtual int GetDragAndDropWidgetLocation(
290  vtkKWWidget *widget, WidgetLocation *loc);
291 
292  // Description:
293  // Get a D&D widget given its label (as returned by
294  // GetDragAndDropWidgetLabel()) and a hint about its location.
295  virtual vtkKWWidget* GetDragAndDropWidgetFromLabelAndLocation(
296  const char *widget_label, const WidgetLocation *loc_hint);
297 
298  // Description:
299  // Get the last D&D entry that was added for a given widget
300  DragAndDropEntry* GetLastDragAndDropEntry(vtkKWWidget *Widget);
301 
302  // Description:
303  // Check if a widget that was drag & drop has gone back to its previous
304  // location
305  virtual int IsDragAndDropWidgetAtOriginalLocation(vtkKWWidget *widget);
306 
307  // Description:
308  // Add a D&D entry to the list of entries, given a widget and its
309  // target location (its current/source location will be computed
310  // automatically)
311  int AddDragAndDropEntry(
312  vtkKWWidget *Widget,
313  const WidgetLocation *from_loc,
314  const WidgetLocation *to_loc);
315 
316  // Description:
317  // Perform the actual D&D given a widget and its target location.
318  // It will call AddDragAndDropEntry() and pack the widget to its new
319  // location
320  virtual int DragAndDropWidget(
321  vtkKWWidget *widget,
322  const WidgetLocation *from_loc,
323  const WidgetLocation *to_loc);
324 
325  //ETX
326 
327 private:
328 
330  void operator=(const vtkKWUserInterfaceManagerNotebook&); // Not Implemented
331 };
332 
333 #endif
334