KWWidgets
debian/tmp/usr/include/KWWidgets/vtkKWNotebook.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Module: $RCSfile: vtkKWNotebook.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 vtkKWNotebook - a tabbed notebook of UI pages
15 // .SECTION Description
16 // The notebook represents a tabbed notebook component where you can
17 // add or remove pages.
18 
19 #ifndef __vtkKWNotebook_h
20 #define __vtkKWNotebook_h
21 
22 #include "vtkKWCompositeWidget.h"
23 
24 class vtkKWFrame;
25 class vtkKWIcon;
26 class vtkKWLabel;
28 class vtkKWMenu;
29 class vtkKWNotebookInternals;
31 
33 {
34 public:
35  static vtkKWNotebook* New();
36  vtkTypeRevisionMacro(vtkKWNotebook,vtkKWCompositeWidget);
37  void PrintSelf(ostream& os, vtkIndent indent);
38 
39  // Description:
40  // Add a new page to the notebook.
41  // By setting balloon string, the page will display a balloon help (tooltip).
42  // An optional icon can also be specified and will be displayed on the left
43  // side of the tab label (all icons can be hidden later on using the
44  // SetShowIcons() method). No reference is kept to the icon object, its
45  // contents is copied locally.
46  // An optional integer tag can be provided and will be associated to the
47  // page (see SetPageTag()); this/ tag will default to 0 otherwise.
48  // Return a unique positive ID corresponding to that page, or < 0 on error.
49  int AddPage(const char *title, const char* balloon, vtkKWIcon *icon,int tag);
50  int AddPage(const char *title, const char* balloon, vtkKWIcon *icon);
51  int AddPage(const char *title, const char* balloon);
52  int AddPage(const char *title);
53 
54  // Description:
55  // Does it have a given page
56  int HasPage(int id);
57  int HasPage(const char *title, int tag);
58  int GetPageId(const char *title, int tag);
59 
60  // Description:
61  // Set/Get a page's title
62  const char* GetPageTitle(int id);
63  virtual void SetPageTitle(int id, const char *title);
64 
65  // Description:
66  // Set/Get a page's balloon help string
67  const char* GetPageBalloonHelpString(int id);
68  virtual void SetPageBalloonHelpString(int id, const char *str);
69 
70  // Description:
71  // Set/Get a page's icon. No reference is kept to the icon object, its
72  // contents is copied locally.
73  vtkKWIcon* GetPageIcon(int id);
74  virtual void SetPageIcon(int id, vtkKWIcon *icon);
75  virtual void SetPageIconToPredefinedIcon(int id, int icon_index);
76 
77  // Description:
78  // Set/Get a page's small counter. This is a small icon representing
79  // a counter on top of the page tab. Set it to 0 (default) to hide the
80  // icon, 1 to 9 to reflect that value. Any value over 9 will be
81  // represented as 9+. Since only one page is visible at any one time
82  // in a notebook, such counter can be used for example to reflect
83  // a change that was made to another tab that is not currently
84  // visible (the counter would be the number of changes for example).
85  int GetPageSmallCounterValue(int id);
86  virtual void SetPageSmallCounterValue(int id, int v);
87 
88  // Description:
89  // Return the number of pages in the notebook.
90  unsigned int GetNumberOfPages();
91  unsigned int GetNumberOfPagesMatchingTag(int tag);
92 
93  // Description:
94  // Set/Get a page tag. A tag (int) can be associated to a page (given the
95  // page id). This provides a way to group pages. The default tag, if not
96  // provided, is 0.
97  // If a page title is provided instead of a page id, the first page matching
98  // that title is considered.
99  void SetPageTag(int id, int tag);
100  void SetPageTag(const char *title, int tag);
101  int GetPageTag(int id);
102  int GetPageTag(const char *title);
103 
104  // Description:
105  // Raise the specified page to be on the top (i.e. the one selected).
106  // If a page title is provided instead of a page id, the first page matching
107  // that title is considered. In the same way, if a tag is provided with the
108  // title, the page which match both title *and* tag is considered.
109  // GetRaisedPageId() returns the id of the page raised at the moment, -1 if
110  // none is raised.
111  // RaiseFirstPageMatchingTag() raises the first page matching a given tag.
112  void RaisePage(int id);
113  void RaisePage(const char *title);
114  void RaisePage(const char *title, int tag);
115  int GetRaisedPageId();
116  void RaiseFirstPageMatchingTag(int tag);
117 
118  // Description:
119  // Get the vtkKWWidget corresponding to the frame of a specified page (Tab).
120  // This is where the UI components should be inserted.
121  // If a page title is provided instead of a page id, the first page matching
122  // that title is considered. In the same way, if a tag is provided with the
123  // title, the page which match both title *and* tag is considered.
124  // Return NULL on error.
125  vtkKWFrame *GetFrame(int id);
126  vtkKWFrame *GetFrame(const char *title);
127  vtkKWFrame *GetFrame(const char *title, int tag);
128  int GetPageIdFromFrameWidgetName(const char *frame_wname);
129 
130  // Description:
131  // Remove a page from the notebook.
132  // If a page title is provided instead of a page id, the first page matching
133  // that title is considered.
134  // If the currently selected page is removed, it is unselected first and
135  // the first visible tab (if any) becomes selected instead.
136  // Return 1 on success, 0 on error.
137  int RemovePage(int id);
138  int RemovePage(const char *title);
139 
140  // Description:
141  // Remove all pages matching a tag.
142  void RemovePagesMatchingTag(int tag);
143 
144  // Description:
145  // Show/hide a page tab (i.e. Set/Get the page visibility). Showing a page
146  // tab does not raise the page, it just makes the page selectable by
147  // displaying its tab. A hidden page tab is not displayed in the tabs: the
148  // corresponding page can not be selected.
149  // If a page title is provided instead of a page id, the first page matching
150  // that title is considered. In the same way, if a tag is provided with the
151  // title, the page which match both title *and* tag is considered.
152  // If the currently selected page is hidden, it is unselected first and
153  // the first visible tab (if any) becomes selected instead.
154  // A pinned page tab can not be hidden (see PinPage()/UnpinPage()).
155  void ShowPage(int id);
156  void ShowPage(const char *title);
157  void ShowPage(const char *title, int tag);
158  void HidePage(int id);
159  void HidePage(const char *title);
160  void HidePage(const char *title, int tag);
161  void SetPageVisibility(int id, int flag);
162  void SetPageVisibility(const char *title, int flag);
163  void SetPageVisibility(const char *title, int tag, int flag);
164  int GetPageVisibility(int id);
165  int GetPageVisibility(const char *title);
166  int GetPageVisibility(const char *title, int tag);
167  void TogglePageVisibility(int id);
168  void TogglePageVisibility(const char *title);
169  void TogglePageVisibility(const char *title, int tag);
170  int CanBeHidden(int id);
171  int CanBeHidden(const char *title);
172  int CanBeHidden(const char *title, int tag);
173  void HideAllPages();
174 
175  // Description:
176  // Enable/Disable a page. Note that this differs from show/hide a tab in the
177  // sense that the tab will still be visible but disabled. All tabs are
178  // enabled by default. Calling SetEnabled(flag) on this notebook will
179  // set the state of all pages to 'flag' unless the page itself has been
180  // disabled. The only way to re-enable a page that was disabled using
181  // SetPageEnabled is to call SetPageEnabled again.
182  void SetPageEnabled(int id, int flag);
183  void SetPageEnabled(const char *title, int flag);
184  void SetPageEnabled(const char *title, int tag, int fkag);
185 
186  // Description:
187  // Return the number of visible pages in the notebook.
188  unsigned int GetNumberOfVisiblePages();
189  unsigned int GetNumberOfVisiblePagesMatchingTag(int tag);
190 
191  // Description:
192  // Get the n-th visible page id (starting at index 0, i.e. the first visible
193  // page is at index 0, although it does not necessary reflects the way
194  // the page tab are packed/ordered in the tab row).
195  // Return -1 if the index is out of the range, or if there is no visible
196  // page for that index.
197  int GetVisiblePageId(int idx);
198 
199  // Description:
200  // Show/Hide all page tabs matching or not matching a given tag.
201  // ShowPagesMatchingTagReverse processes pages starting from the last one.
202  void HidePagesMatchingTag(int tag);
203  void ShowPagesMatchingTag(int tag);
204  void ShowPagesMatchingTagReverse(int tag);
205  void HidePagesNotMatchingTag(int tag);
206  void ShowPagesNotMatchingTag(int tag);
207 
208  // Description:
209  // Make the notebook automatically bring up page tabs with the same tag
210  // (i.e. all page tabs that have the same tag are always shown).
211  virtual void SetShowAllPagesWithSameTag(int);
212  vtkGetMacro(ShowAllPagesWithSameTag, int);
213  vtkBooleanMacro(ShowAllPagesWithSameTag, int);
214 
215  // Description:
216  // Make the notebook automatically show only those page tabs that have the
217  // same tag as the currently selected page (i.e. once a page tab has been
218  // selected, all pages not sharing the same tag are hidden).
219  virtual void SetShowOnlyPagesWithSameTag(int);
220  vtkGetMacro(ShowOnlyPagesWithSameTag, int);
221  vtkBooleanMacro(ShowOnlyPagesWithSameTag, int);
222 
223  // Description:
224  // Make the notebook automatically maintain a list of most recently used
225  // page. The size of this list can be set (defaults to 4). Once it is full,
226  // any new shown page will make the least recent page hidden.
227  // It is suggested that ShowAllPagesWithSameTag and ShowOnlyPagesWithSameTag
228  // shoud be Off for this feature to work properly.
229  virtual void SetShowOnlyMostRecentPages(int);
230  vtkGetMacro(ShowOnlyMostRecentPages, int);
231  vtkBooleanMacro(ShowOnlyMostRecentPages, int);
232  vtkSetMacro(NumberOfMostRecentPages, int);
233  vtkGetMacro(NumberOfMostRecentPages, int);
234 
235  // Description:
236  // Get the n-th most recent page id. Most recent pages indexes start at 0
237  // (i.e. the most recent page is at index 0).
238  // Return -1 if the index is out of the range, or if there is no most
239  // recent page for that index.
240  int GetMostRecentPageId(int idx);
241 
242  // Description:
243  // Pin/unpin a page tab. A pinned page tab can not be hidden.
244  // If a page title is provided instead of a page id, the first page matching
245  // that title is considered. In the same way, if a tag is provided with the
246  // title, the page which match both title *and* tag is considered.
247  void PinPage(int id);
248  void PinPage(const char *title);
249  void PinPage(const char *title, int tag);
250  void UnpinPage(int id);
251  void UnpinPage(const char *title);
252  void UnpinPage(const char *title, int tag);
253  void TogglePagePinned(int id);
254  void TogglePagePinned(const char *title);
255  void TogglePagePinned(const char *title, int tag);
256  int GetPagePinned(int id);
257  int GetPagePinned(const char *title);
258  int GetPagePinned(const char *title, int tag);
259 
260  // Description:
261  // Pin/Unpin all page tabs matching a given tag.
262  void PinPagesMatchingTag(int tag);
263  void UnpinPagesMatchingTag(int tag);
264 
265  // Description:
266  // Allow pages to be pinned.
267  virtual void SetPagesCanBePinned(int);
268  vtkGetMacro(PagesCanBePinned, int);
269  vtkBooleanMacro(PagesCanBePinned, int);
270 
271  // Description:
272  // Return the number of pinned pages in the notebook.
273  unsigned int GetNumberOfPinnedPages();
274 
275  // Description:
276  // Get the n-th pinned page id (starting at index 0, i.e. the first pinned
277  // page is at index 0).
278  // Return -1 if the index is out of the range, or if there is no pinned
279  // page for that index.
280  int GetPinnedPageId(int idx);
281 
282  // Description:
283  // By default, pages are vtkKWFrame. If the user needs scrollbars, he can
284  // make the page the parent of a vtkKWFrameWithScrollbar. For convenience,
285  // this option can be turned on so that pages that are added from now on are
286  // automatically put inside a vtkKWFrameWithScrollbar.
287  // Note that HorizontalScrollbarVisibility is set to Off by default on
288  // the vtkKWFrameWithScrollbar created by this class.
289  vtkSetMacro(UseFrameWithScrollbars, int);
290  vtkGetMacro(UseFrameWithScrollbars, int);
291  vtkBooleanMacro(UseFrameWithScrollbars, int);
292 
293  // Description:
294  // The notebook will automatically resize itself to fit its
295  // contents. This can lead to a lot of resizing. So you can
296  // specify a minimum width and height for the notebook. This
297  // can be used to significantly reduce or eliminate the resizing
298  // of the notebook.
299  virtual void SetMinimumWidth(int);
300  vtkGetMacro(MinimumWidth,int);
301  virtual void SetMinimumHeight(int);
302  vtkGetMacro(MinimumHeight,int);
303 
304  // Description:
305  // Normally, the tab frame is not shown when there is only
306  // one page. Turn this on to override that behaviour.
307  virtual void SetAlwaysShowTabs(int);
308  vtkGetMacro(AlwaysShowTabs, int);
309  vtkBooleanMacro(AlwaysShowTabs, int);
310 
311  // Description:
312  // Show/hide all tab icons (if any).
313  virtual void SetShowIcons(int);
314  vtkGetMacro(ShowIcons, int);
315  vtkBooleanMacro(ShowIcons, int);
316 
317  // Description:
318  // Enable the page tab context menu.
319  vtkSetMacro(EnablePageTabContextMenu, int);
320  vtkGetMacro(EnablePageTabContextMenu, int);
321  vtkBooleanMacro(EnablePageTabContextMenu, int);
322 
323  // Description:
324  // Set/Get the background color of the widget.
325  // Override the super to make sure all elements are set correctly.
326  virtual void SetBackgroundColor(double r, double g, double b);
327  virtual void SetBackgroundColor(double rgb[3])
328  { this->SetBackgroundColor(rgb[0], rgb[1], rgb[2]); };
329 
330  // Description:
331  // Set/Get the color of the page tabs, the outline of the pinned page tabs
332  // and the selected page tab.
333  // Note that PageTabColor, and SelectedPageTabColor are
334  // undefined by default (i.e. one of the RGB component is < 0), meaning that
335  // the background color of the native window system will be used in place of
336  // SelectedTabColor, and a slightly darker shade of that background color in
337  // place of TabColor.
338  vtkGetVector3Macro(PageTabColor,double);
339  virtual void SetPageTabColor(double r, double g, double b);
340  virtual void SetPageTabColor(double rgb[3])
341  { this->SetPageTabColor(rgb[0], rgb[1], rgb[2]); };
342  vtkGetVector3Macro(SelectedPageTabColor,double);
343  virtual void SetSelectedPageTabColor(double r, double g, double b);
344  virtual void SetSelectedPageTabColor(double rgb[3])
345  { this->SetSelectedPageTabColor(rgb[0], rgb[1], rgb[2]); };
346  vtkGetVector3Macro(PinnedPageTabOutlineColor,double);
347  virtual void SetPinnedPageTabOutlineColor(double r, double g, double b);
348  virtual void SetPinnedPageTabOutlineColor(double rgb[3])
349  { this->SetPinnedPageTabOutlineColor(rgb[0], rgb[1], rgb[2]); };
350  vtkGetVector3Macro(PageTabTextColor,double);
351  virtual void SetPageTabTextColor(double r, double g, double b);
352  virtual void SetPageTabTextColor(double rgb[3])
353  { this->SetPageTabTextColor(rgb[0], rgb[1], rgb[2]); };
354  vtkGetVector3Macro(SelectedPageTabTextColor,double);
355  virtual void SetSelectedPageTabTextColor(double r, double g, double b);
356  virtual void SetSelectedPageTabTextColor(double rgb[3])
357  { this->SetSelectedPageTabTextColor(rgb[0], rgb[1], rgb[2]); };
358 
359  // Description:
360  // Set/Get the amount of padding that is to be added to the internal
361  // vertical padding of the selected tab (basically defines the additional
362  // height of the selected tab compared to an unselected tabs).
363  vtkGetMacro(SelectedPageTabPadding, int);
364  virtual void SetSelectedPageTabPadding(int arg);
365 
366  // Description:
367  // Get the id of the visible page which tab contains a given pair of screen
368  // coordinates (-1 if not found).
369  virtual int GetPageIdContainingCoordinatesInTab(int x, int y);
370 
371  // Description:
372  // Update the "enable" state of the object and its internal parts.
373  // Depending on different Ivars (this->Enabled, the application's
374  // Limited Edition Mode, etc.), the "enable" state of the object is updated
375  // and propagated to its internal parts/subwidgets. This will, for example,
376  // enable/disable parts of the widget UI, enable/disable the visibility
377  // of 3D widgets, etc.
378  virtual void UpdateEnableState();
379 
380  // Description:
381  // Schedule the widget to resize itself, or resize it right away
382  virtual void ScheduleResize();
383  virtual void Resize();
384 
385  // Description:
386  // Events: the following events are send by a notebook instance.
387  // The below events are sent as a result of a direct user interaction
388  // (clicking, context menu), not as a result of a programmatical call.
389  // The following parameters are also passed as client data:
390  // - the title/tag pair for the page, as a const char *[2] (first item
391  // in the array is title (eventually NULL), second is its numerical tag,
392  // as a string)
393  // vtkKWEvent::NotebookRaisePageEvent: a page has been raised
394  // vtkKWEvent::NotebookPinPageEvent: a page has been pinned (context menu)
395  // vtkKWEvent::NotebookUnpinPageEvent: a page has been unpinned (context menu)
396  // vtkKWEvent::NotebookShowPageEvent: a page was shown (context menu?)
397  // vtkKWEvent::NotebookHidePageEvent: a page was hidden (context menu)
398 
399  // Description:
400  // Callbacks. Internal, do not use.
401  virtual void PageTabContextMenuCallback(int id, int x, int y);
402  virtual void RaiseCallback(int id);
403  virtual void TogglePagePinnedCallback(int id);
404  virtual void TogglePageVisibilityCallback(int id);
405 
406 protected:
407  vtkKWNotebook();
408  ~vtkKWNotebook();
409 
410  // Description:
411  // Create the widget.
412  virtual void CreateWidget();
413 
425 
426  double PageTabColor[3];
427  double SelectedPageTabColor[3];
428  double PageTabTextColor[3];
429  double SelectedPageTabTextColor[3];
430  double PinnedPageTabOutlineColor[3];
432 
437 
438  //BTX
439 
440  // A notebook page
441 
442  class Page
443  {
444  public:
445  Page();
446  void Delete();
447  void UpdateEnableState();
448  void Bind();
449  void UnBind();
450 
451  int Id;
453  int Pinned;
454  int Tag;
455  int Enabled;
456  char *Title;
463  };
464 
465  // PIMPL Encapsulation for STL containers
466 
467  vtkKWNotebookInternals *Internals;
468  friend class vtkKWNotebookInternals;
469 
470  // Return a pointer to a page.
471  // If a page title is provided instead of a page id, the first page matching
472  // that title is considered. In the same way, if a tag is provided with the
473  // title, the page which title *and* tag match is considered.
474 
475  Page* GetPage(int id);
476  Page* GetPage(const char *title);
477  Page* GetPage(const char *title, int tag);
478 
479  // Get the first visible page
480  // Get the first page matching a tag
481  // Get the first packed page not matching a tag
482 
483  Page* GetFirstVisiblePage();
484  Page* GetFirstPageMatchingTag(int tag);
485  Page* GetFirstPackedPageNotMatchingTag(int tag);
486 
487  // Raise, Lower, Remove, Show, Hide, Pin, Unpin, Tag a specific page
488 
489  void SetPageTag(Page*, int tag);
490  void RaisePage(Page*);
491  void ShowPageTab(Page*);
492  void ShowPageTabAsLow(Page*);
493  void LowerPage(Page*);
494  int RemovePage(Page*);
495  void ShowPage(Page*);
496  void HidePage(Page*);
497  void PinPage(Page*);
498  void UnpinPage(Page*);
499  void TogglePagePinned(Page*);
500  int GetPageVisibility(Page*);
501  void TogglePageVisibility(Page*);
502  int CanBeHidden(Page*);
503  int GetPageTag(Page*);
504  int GetPagePinned(Page*);
505  const char* GetPageTitle(Page*);
506  const char* GetPageBalloonHelpString(Page*);
507  vtkKWIcon* GetPageIcon(Page*);
508  void SetPageEnabled(Page*, int flag);
509  void BuildPage(Page*,const char *title,const char* balloon,vtkKWIcon *icon);
510 
511  int AddToMostRecentPages(Page*);
512  int RemoveFromMostRecentPages(Page*);
513  int PutOnTopOfMostRecentPages(Page*);
514 
515  // Update the tab frame color of a page
516 
517  virtual void UpdatePageTabAspect(Page*);
518  virtual void UpdateAllPagesTabAspect();
519 
520  //ETX
521 
525 
526  // Returns true if some tabs are visible.
527 
528  int AreTabsVisible();
529 
530  // Update the position of the body and mask elements
531 
532  void UpdateBodyPosition();
533  void UpdateMaskPosition();
534 
535  // Constrain the visible pages depending on:
536  // ShowAllPagesWithSameTag,
537  // ShowOnlyPagesWithSameTag,
538  // ShowOnlyMostRecentPages
539 
540  void ConstrainVisiblePages();
541 
542  // Send event
543 
544  void SendEventForPage(unsigned long event, int id);
545 
546  // Description:
547  // Bind/Unbind events.
548  virtual void Bind();
549  virtual void UnBind();
550 
552 
553 private:
554  vtkKWNotebook(const vtkKWNotebook&); // Not implemented
555  void operator=(const vtkKWNotebook&); // Not implemented
556 };
557 
558 #endif
559