KWWidgets
|
00001 /*========================================================================= 00002 00003 Module: $RCSfile: vtkKWNotebook.h,v $ 00004 00005 Copyright (c) Kitware, Inc. 00006 All rights reserved. 00007 See Copyright.txt or http://www.kitware.com/Copyright.htm for details. 00008 00009 This software is distributed WITHOUT ANY WARRANTY; without even 00010 the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR 00011 PURPOSE. See the above copyright notice for more information. 00012 00013 =========================================================================*/ 00014 // .NAME vtkKWNotebook - a tabbed notebook of UI pages 00015 // .SECTION Description 00016 // The notebook represents a tabbed notebook component where you can 00017 // add or remove pages. 00018 00019 #ifndef __vtkKWNotebook_h 00020 #define __vtkKWNotebook_h 00021 00022 #include "vtkKWCompositeWidget.h" 00023 00024 class vtkKWFrame; 00025 class vtkKWIcon; 00026 class vtkKWLabel; 00027 class vtkKWSmallCounterLabel; 00028 class vtkKWMenu; 00029 class vtkKWNotebookInternals; 00030 class vtkKWBalloonHelpManager; 00031 00032 class KWWidgets_EXPORT vtkKWNotebook : public vtkKWCompositeWidget 00033 { 00034 public: 00035 static vtkKWNotebook* New(); 00036 vtkTypeRevisionMacro(vtkKWNotebook,vtkKWCompositeWidget); 00037 void PrintSelf(ostream& os, vtkIndent indent); 00038 00039 // Description: 00040 // Add a new page to the notebook. 00041 // By setting balloon string, the page will display a balloon help (tooltip). 00042 // An optional icon can also be specified and will be displayed on the left 00043 // side of the tab label (all icons can be hidden later on using the 00044 // SetShowIcons() method). No reference is kept to the icon object, its 00045 // contents is copied locally. 00046 // An optional integer tag can be provided and will be associated to the 00047 // page (see SetPageTag()); this/ tag will default to 0 otherwise. 00048 // Return a unique positive ID corresponding to that page, or < 0 on error. 00049 int AddPage(const char *title, const char* balloon, vtkKWIcon *icon,int tag); 00050 int AddPage(const char *title, const char* balloon, vtkKWIcon *icon); 00051 int AddPage(const char *title, const char* balloon); 00052 int AddPage(const char *title); 00053 00054 // Description: 00055 // Does it have a given page 00056 int HasPage(int id); 00057 int HasPage(const char *title, int tag); 00058 int GetPageId(const char *title, int tag); 00059 00060 // Description: 00061 // Set/Get a page's title 00062 const char* GetPageTitle(int id); 00063 virtual void SetPageTitle(int id, const char *title); 00064 00065 // Description: 00066 // Set/Get a page's balloon help string 00067 const char* GetPageBalloonHelpString(int id); 00068 virtual void SetPageBalloonHelpString(int id, const char *str); 00069 00070 // Description: 00071 // Set/Get a page's icon. No reference is kept to the icon object, its 00072 // contents is copied locally. 00073 vtkKWIcon* GetPageIcon(int id); 00074 virtual void SetPageIcon(int id, vtkKWIcon *icon); 00075 virtual void SetPageIconToPredefinedIcon(int id, int icon_index); 00076 00077 // Description: 00078 // Set/Get a page's small counter. This is a small icon representing 00079 // a counter on top of the page tab. Set it to 0 (default) to hide the 00080 // icon, 1 to 9 to reflect that value. Any value over 9 will be 00081 // represented as 9+. Since only one page is visible at any one time 00082 // in a notebook, such counter can be used for example to reflect 00083 // a change that was made to another tab that is not currently 00084 // visible (the counter would be the number of changes for example). 00085 int GetPageSmallCounterValue(int id); 00086 virtual void SetPageSmallCounterValue(int id, int v); 00087 00088 // Description: 00089 // Return the number of pages in the notebook. 00090 unsigned int GetNumberOfPages(); 00091 unsigned int GetNumberOfPagesMatchingTag(int tag); 00092 00093 // Description: 00094 // Set/Get a page tag. A tag (int) can be associated to a page (given the 00095 // page id). This provides a way to group pages. The default tag, if not 00096 // provided, is 0. 00097 // If a page title is provided instead of a page id, the first page matching 00098 // that title is considered. 00099 void SetPageTag(int id, int tag); 00100 void SetPageTag(const char *title, int tag); 00101 int GetPageTag(int id); 00102 int GetPageTag(const char *title); 00103 00104 // Description: 00105 // Raise the specified page to be on the top (i.e. the one selected). 00106 // If a page title is provided instead of a page id, the first page matching 00107 // that title is considered. In the same way, if a tag is provided with the 00108 // title, the page which match both title *and* tag is considered. 00109 // GetRaisedPageId() returns the id of the page raised at the moment, -1 if 00110 // none is raised. 00111 // RaiseFirstPageMatchingTag() raises the first page matching a given tag. 00112 void RaisePage(int id); 00113 void RaisePage(const char *title); 00114 void RaisePage(const char *title, int tag); 00115 int GetRaisedPageId(); 00116 void RaiseFirstPageMatchingTag(int tag); 00117 00118 // Description: 00119 // Get the vtkKWWidget corresponding to the frame of a specified page (Tab). 00120 // This is where the UI components should be inserted. 00121 // If a page title is provided instead of a page id, the first page matching 00122 // that title is considered. In the same way, if a tag is provided with the 00123 // title, the page which match both title *and* tag is considered. 00124 // Return NULL on error. 00125 vtkKWFrame *GetFrame(int id); 00126 vtkKWFrame *GetFrame(const char *title); 00127 vtkKWFrame *GetFrame(const char *title, int tag); 00128 int GetPageIdFromFrameWidgetName(const char *frame_wname); 00129 00130 // Description: 00131 // Remove a page from the notebook. 00132 // If a page title is provided instead of a page id, the first page matching 00133 // that title is considered. 00134 // If the currently selected page is removed, it is unselected first and 00135 // the first visible tab (if any) becomes selected instead. 00136 // Return 1 on success, 0 on error. 00137 int RemovePage(int id); 00138 int RemovePage(const char *title); 00139 00140 // Description: 00141 // Remove all pages matching a tag. 00142 void RemovePagesMatchingTag(int tag); 00143 00144 // Description: 00145 // Show/hide a page tab (i.e. Set/Get the page visibility). Showing a page 00146 // tab does not raise the page, it just makes the page selectable by 00147 // displaying its tab. A hidden page tab is not displayed in the tabs: the 00148 // corresponding page can not be selected. 00149 // If a page title is provided instead of a page id, the first page matching 00150 // that title is considered. In the same way, if a tag is provided with the 00151 // title, the page which match both title *and* tag is considered. 00152 // If the currently selected page is hidden, it is unselected first and 00153 // the first visible tab (if any) becomes selected instead. 00154 // A pinned page tab can not be hidden (see PinPage()/UnpinPage()). 00155 void ShowPage(int id); 00156 void ShowPage(const char *title); 00157 void ShowPage(const char *title, int tag); 00158 void HidePage(int id); 00159 void HidePage(const char *title); 00160 void HidePage(const char *title, int tag); 00161 void SetPageVisibility(int id, int flag); 00162 void SetPageVisibility(const char *title, int flag); 00163 void SetPageVisibility(const char *title, int tag, int flag); 00164 int GetPageVisibility(int id); 00165 int GetPageVisibility(const char *title); 00166 int GetPageVisibility(const char *title, int tag); 00167 void TogglePageVisibility(int id); 00168 void TogglePageVisibility(const char *title); 00169 void TogglePageVisibility(const char *title, int tag); 00170 int CanBeHidden(int id); 00171 int CanBeHidden(const char *title); 00172 int CanBeHidden(const char *title, int tag); 00173 void HideAllPages(); 00174 00175 // Description: 00176 // Enable/Disable a page. Note that this differs from show/hide a tab in the 00177 // sense that the tab will still be visible but disabled. All tabs are 00178 // enabled by default. Calling SetEnabled(flag) on this notebook will 00179 // set the state of all pages to 'flag' unless the page itself has been 00180 // disabled. The only way to re-enable a page that was disabled using 00181 // SetPageEnabled is to call SetPageEnabled again. 00182 void SetPageEnabled(int id, int flag); 00183 void SetPageEnabled(const char *title, int flag); 00184 void SetPageEnabled(const char *title, int tag, int fkag); 00185 00186 // Description: 00187 // Return the number of visible pages in the notebook. 00188 unsigned int GetNumberOfVisiblePages(); 00189 unsigned int GetNumberOfVisiblePagesMatchingTag(int tag); 00190 00191 // Description: 00192 // Get the n-th visible page id (starting at index 0, i.e. the first visible 00193 // page is at index 0, although it does not necessary reflects the way 00194 // the page tab are packed/ordered in the tab row). 00195 // Return -1 if the index is out of the range, or if there is no visible 00196 // page for that index. 00197 int GetVisiblePageId(int idx); 00198 00199 // Description: 00200 // Show/Hide all page tabs matching or not matching a given tag. 00201 // ShowPagesMatchingTagReverse processes pages starting from the last one. 00202 void HidePagesMatchingTag(int tag); 00203 void ShowPagesMatchingTag(int tag); 00204 void ShowPagesMatchingTagReverse(int tag); 00205 void HidePagesNotMatchingTag(int tag); 00206 void ShowPagesNotMatchingTag(int tag); 00207 00208 // Description: 00209 // Make the notebook automatically bring up page tabs with the same tag 00210 // (i.e. all page tabs that have the same tag are always shown). 00211 virtual void SetShowAllPagesWithSameTag(int); 00212 vtkGetMacro(ShowAllPagesWithSameTag, int); 00213 vtkBooleanMacro(ShowAllPagesWithSameTag, int); 00214 00215 // Description: 00216 // Make the notebook automatically show only those page tabs that have the 00217 // same tag as the currently selected page (i.e. once a page tab has been 00218 // selected, all pages not sharing the same tag are hidden). 00219 virtual void SetShowOnlyPagesWithSameTag(int); 00220 vtkGetMacro(ShowOnlyPagesWithSameTag, int); 00221 vtkBooleanMacro(ShowOnlyPagesWithSameTag, int); 00222 00223 // Description: 00224 // Make the notebook automatically maintain a list of most recently used 00225 // page. The size of this list can be set (defaults to 4). Once it is full, 00226 // any new shown page will make the least recent page hidden. 00227 // It is suggested that ShowAllPagesWithSameTag and ShowOnlyPagesWithSameTag 00228 // shoud be Off for this feature to work properly. 00229 virtual void SetShowOnlyMostRecentPages(int); 00230 vtkGetMacro(ShowOnlyMostRecentPages, int); 00231 vtkBooleanMacro(ShowOnlyMostRecentPages, int); 00232 vtkSetMacro(NumberOfMostRecentPages, int); 00233 vtkGetMacro(NumberOfMostRecentPages, int); 00234 00235 // Description: 00236 // Get the n-th most recent page id. Most recent pages indexes start at 0 00237 // (i.e. the most recent page is at index 0). 00238 // Return -1 if the index is out of the range, or if there is no most 00239 // recent page for that index. 00240 int GetMostRecentPageId(int idx); 00241 00242 // Description: 00243 // Pin/unpin a page tab. A pinned page tab can not be hidden. 00244 // If a page title is provided instead of a page id, the first page matching 00245 // that title is considered. In the same way, if a tag is provided with the 00246 // title, the page which match both title *and* tag is considered. 00247 void PinPage(int id); 00248 void PinPage(const char *title); 00249 void PinPage(const char *title, int tag); 00250 void UnpinPage(int id); 00251 void UnpinPage(const char *title); 00252 void UnpinPage(const char *title, int tag); 00253 void TogglePagePinned(int id); 00254 void TogglePagePinned(const char *title); 00255 void TogglePagePinned(const char *title, int tag); 00256 int GetPagePinned(int id); 00257 int GetPagePinned(const char *title); 00258 int GetPagePinned(const char *title, int tag); 00259 00260 // Description: 00261 // Pin/Unpin all page tabs matching a given tag. 00262 void PinPagesMatchingTag(int tag); 00263 void UnpinPagesMatchingTag(int tag); 00264 00265 // Description: 00266 // Allow pages to be pinned. 00267 virtual void SetPagesCanBePinned(int); 00268 vtkGetMacro(PagesCanBePinned, int); 00269 vtkBooleanMacro(PagesCanBePinned, int); 00270 00271 // Description: 00272 // Return the number of pinned pages in the notebook. 00273 unsigned int GetNumberOfPinnedPages(); 00274 00275 // Description: 00276 // Get the n-th pinned page id (starting at index 0, i.e. the first pinned 00277 // page is at index 0). 00278 // Return -1 if the index is out of the range, or if there is no pinned 00279 // page for that index. 00280 int GetPinnedPageId(int idx); 00281 00282 // Description: 00283 // By default, pages are vtkKWFrame. If the user needs scrollbars, he can 00284 // make the page the parent of a vtkKWFrameWithScrollbar. For convenience, 00285 // this option can be turned on so that pages that are added from now on are 00286 // automatically put inside a vtkKWFrameWithScrollbar. 00287 // Note that HorizontalScrollbarVisibility is set to Off by default on 00288 // the vtkKWFrameWithScrollbar created by this class. 00289 vtkSetMacro(UseFrameWithScrollbars, int); 00290 vtkGetMacro(UseFrameWithScrollbars, int); 00291 vtkBooleanMacro(UseFrameWithScrollbars, int); 00292 00293 // Description: 00294 // The notebook will automatically resize itself to fit its 00295 // contents. This can lead to a lot of resizing. So you can 00296 // specify a minimum width and height for the notebook. This 00297 // can be used to significantly reduce or eliminate the resizing 00298 // of the notebook. 00299 virtual void SetMinimumWidth(int); 00300 vtkGetMacro(MinimumWidth,int); 00301 virtual void SetMinimumHeight(int); 00302 vtkGetMacro(MinimumHeight,int); 00303 00304 // Description: 00305 // Normally, the tab frame is not shown when there is only 00306 // one page. Turn this on to override that behaviour. 00307 virtual void SetAlwaysShowTabs(int); 00308 vtkGetMacro(AlwaysShowTabs, int); 00309 vtkBooleanMacro(AlwaysShowTabs, int); 00310 00311 // Description: 00312 // Show/hide all tab icons (if any). 00313 virtual void SetShowIcons(int); 00314 vtkGetMacro(ShowIcons, int); 00315 vtkBooleanMacro(ShowIcons, int); 00316 00317 // Description: 00318 // Enable the page tab context menu. 00319 vtkSetMacro(EnablePageTabContextMenu, int); 00320 vtkGetMacro(EnablePageTabContextMenu, int); 00321 vtkBooleanMacro(EnablePageTabContextMenu, int); 00322 00323 // Description: 00324 // Set/Get the background color of the widget. 00325 // Override the super to make sure all elements are set correctly. 00326 virtual void SetBackgroundColor(double r, double g, double b); 00327 virtual void SetBackgroundColor(double rgb[3]) 00328 { this->SetBackgroundColor(rgb[0], rgb[1], rgb[2]); }; 00329 00330 // Description: 00331 // Set/Get the color of the page tabs, the outline of the pinned page tabs 00332 // and the selected page tab. 00333 // Note that PageTabColor, and SelectedPageTabColor are 00334 // undefined by default (i.e. one of the RGB component is < 0), meaning that 00335 // the background color of the native window system will be used in place of 00336 // SelectedTabColor, and a slightly darker shade of that background color in 00337 // place of TabColor. 00338 vtkGetVector3Macro(PageTabColor,double); 00339 virtual void SetPageTabColor(double r, double g, double b); 00340 virtual void SetPageTabColor(double rgb[3]) 00341 { this->SetPageTabColor(rgb[0], rgb[1], rgb[2]); }; 00342 vtkGetVector3Macro(SelectedPageTabColor,double); 00343 virtual void SetSelectedPageTabColor(double r, double g, double b); 00344 virtual void SetSelectedPageTabColor(double rgb[3]) 00345 { this->SetSelectedPageTabColor(rgb[0], rgb[1], rgb[2]); }; 00346 vtkGetVector3Macro(PinnedPageTabOutlineColor,double); 00347 virtual void SetPinnedPageTabOutlineColor(double r, double g, double b); 00348 virtual void SetPinnedPageTabOutlineColor(double rgb[3]) 00349 { this->SetPinnedPageTabOutlineColor(rgb[0], rgb[1], rgb[2]); }; 00350 vtkGetVector3Macro(PageTabTextColor,double); 00351 virtual void SetPageTabTextColor(double r, double g, double b); 00352 virtual void SetPageTabTextColor(double rgb[3]) 00353 { this->SetPageTabTextColor(rgb[0], rgb[1], rgb[2]); }; 00354 vtkGetVector3Macro(SelectedPageTabTextColor,double); 00355 virtual void SetSelectedPageTabTextColor(double r, double g, double b); 00356 virtual void SetSelectedPageTabTextColor(double rgb[3]) 00357 { this->SetSelectedPageTabTextColor(rgb[0], rgb[1], rgb[2]); }; 00358 00359 // Description: 00360 // Set/Get the amount of padding that is to be added to the internal 00361 // vertical padding of the selected tab (basically defines the additional 00362 // height of the selected tab compared to an unselected tabs). 00363 vtkGetMacro(SelectedPageTabPadding, int); 00364 virtual void SetSelectedPageTabPadding(int arg); 00365 00366 // Description: 00367 // Get the id of the visible page which tab contains a given pair of screen 00368 // coordinates (-1 if not found). 00369 virtual int GetPageIdContainingCoordinatesInTab(int x, int y); 00370 00371 // Description: 00372 // Update the "enable" state of the object and its internal parts. 00373 // Depending on different Ivars (this->Enabled, the application's 00374 // Limited Edition Mode, etc.), the "enable" state of the object is updated 00375 // and propagated to its internal parts/subwidgets. This will, for example, 00376 // enable/disable parts of the widget UI, enable/disable the visibility 00377 // of 3D widgets, etc. 00378 virtual void UpdateEnableState(); 00379 00380 // Description: 00381 // Schedule the widget to resize itself, or resize it right away 00382 virtual void ScheduleResize(); 00383 virtual void Resize(); 00384 00385 // Description: 00386 // Events: the following events are send by a notebook instance. 00387 // The below events are sent as a result of a direct user interaction 00388 // (clicking, context menu), not as a result of a programmatical call. 00389 // The following parameters are also passed as client data: 00390 // - the title/tag pair for the page, as a const char *[2] (first item 00391 // in the array is title (eventually NULL), second is its numerical tag, 00392 // as a string) 00393 // vtkKWEvent::NotebookRaisePageEvent: a page has been raised 00394 // vtkKWEvent::NotebookPinPageEvent: a page has been pinned (context menu) 00395 // vtkKWEvent::NotebookUnpinPageEvent: a page has been unpinned (context menu) 00396 // vtkKWEvent::NotebookShowPageEvent: a page was shown (context menu?) 00397 // vtkKWEvent::NotebookHidePageEvent: a page was hidden (context menu) 00398 00399 // Description: 00400 // Callbacks. Internal, do not use. 00401 virtual void PageTabContextMenuCallback(int id, int x, int y); 00402 virtual void RaiseCallback(int id); 00403 virtual void TogglePagePinnedCallback(int id); 00404 virtual void TogglePageVisibilityCallback(int id); 00405 00406 protected: 00407 vtkKWNotebook(); 00408 ~vtkKWNotebook(); 00409 00410 // Description: 00411 // Create the widget. 00412 virtual void CreateWidget(); 00413 00414 int MinimumWidth; 00415 int MinimumHeight; 00416 int AlwaysShowTabs; 00417 int ShowIcons; 00418 int ShowAllPagesWithSameTag; 00419 int ShowOnlyPagesWithSameTag; 00420 int ShowOnlyMostRecentPages; 00421 int NumberOfMostRecentPages; 00422 int PagesCanBePinned; 00423 int EnablePageTabContextMenu; 00424 int UseFrameWithScrollbars; 00425 00426 double PageTabColor[3]; 00427 double SelectedPageTabColor[3]; 00428 double PageTabTextColor[3]; 00429 double SelectedPageTabTextColor[3]; 00430 double PinnedPageTabOutlineColor[3]; 00431 int SelectedPageTabPadding; 00432 00433 vtkKWFrame *TabsFrame; 00434 vtkKWFrame *Body; 00435 vtkKWFrame *Mask; 00436 vtkKWMenu *TabPopupMenu; 00437 00438 //BTX 00439 00440 // A notebook page 00441 00442 class Page 00443 { 00444 public: 00445 Page(); 00446 void Delete(); 00447 void UpdateEnableState(); 00448 void Bind(); 00449 void UnBind(); 00450 00451 int Id; 00452 int Visibility; 00453 int Pinned; 00454 int Tag; 00455 int Enabled; 00456 char *Title; 00457 vtkKWCoreWidget *Frame; 00458 vtkKWFrame *TabFrame; 00459 vtkKWLabel *Label; 00460 vtkKWLabel *ImageLabel; 00461 vtkKWIcon *Icon; 00462 vtkKWSmallCounterLabel *SmallCounterLabel; 00463 }; 00464 00465 // PIMPL Encapsulation for STL containers 00466 00467 vtkKWNotebookInternals *Internals; 00468 friend class vtkKWNotebookInternals; 00469 00470 // Return a pointer to a page. 00471 // If a page title is provided instead of a page id, the first page matching 00472 // that title is considered. In the same way, if a tag is provided with the 00473 // title, the page which title *and* tag match is considered. 00474 00475 Page* GetPage(int id); 00476 Page* GetPage(const char *title); 00477 Page* GetPage(const char *title, int tag); 00478 00479 // Get the first visible page 00480 // Get the first page matching a tag 00481 // Get the first packed page not matching a tag 00482 00483 Page* GetFirstVisiblePage(); 00484 Page* GetFirstPageMatchingTag(int tag); 00485 Page* GetFirstPackedPageNotMatchingTag(int tag); 00486 00487 // Raise, Lower, Remove, Show, Hide, Pin, Unpin, Tag a specific page 00488 00489 void SetPageTag(Page*, int tag); 00490 void RaisePage(Page*); 00491 void ShowPageTab(Page*); 00492 void ShowPageTabAsLow(Page*); 00493 void LowerPage(Page*); 00494 int RemovePage(Page*); 00495 void ShowPage(Page*); 00496 void HidePage(Page*); 00497 void PinPage(Page*); 00498 void UnpinPage(Page*); 00499 void TogglePagePinned(Page*); 00500 int GetPageVisibility(Page*); 00501 void TogglePageVisibility(Page*); 00502 int CanBeHidden(Page*); 00503 int GetPageTag(Page*); 00504 int GetPagePinned(Page*); 00505 const char* GetPageTitle(Page*); 00506 const char* GetPageBalloonHelpString(Page*); 00507 vtkKWIcon* GetPageIcon(Page*); 00508 void SetPageEnabled(Page*, int flag); 00509 void BuildPage(Page*,const char *title,const char* balloon,vtkKWIcon *icon); 00510 00511 int AddToMostRecentPages(Page*); 00512 int RemoveFromMostRecentPages(Page*); 00513 int PutOnTopOfMostRecentPages(Page*); 00514 00515 // Update the tab frame color of a page 00516 00517 virtual void UpdatePageTabAspect(Page*); 00518 virtual void UpdateAllPagesTabAspect(); 00519 00520 //ETX 00521 00522 int IdCounter; 00523 int CurrentId; 00524 int Expanding; 00525 00526 // Returns true if some tabs are visible. 00527 00528 int AreTabsVisible(); 00529 00530 // Update the position of the body and mask elements 00531 00532 void UpdateBodyPosition(); 00533 void UpdateMaskPosition(); 00534 00535 // Constrain the visible pages depending on: 00536 // ShowAllPagesWithSameTag, 00537 // ShowOnlyPagesWithSameTag, 00538 // ShowOnlyMostRecentPages 00539 00540 void ConstrainVisiblePages(); 00541 00542 // Send event 00543 00544 void SendEventForPage(unsigned long event, int id); 00545 00546 // Description: 00547 // Bind/Unbind events. 00548 virtual void Bind(); 00549 virtual void UnBind(); 00550 00551 vtkKWBalloonHelpManager *TabBalloonHelpManager; 00552 00553 private: 00554 vtkKWNotebook(const vtkKWNotebook&); // Not implemented 00555 void operator=(const vtkKWNotebook&); // Not implemented 00556 }; 00557 00558 #endif 00559