00001 /*========================================================================= 00002 00003 Module: $RCSfile: vtkKWUserInterfaceManagerNotebook.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 vtkKWUserInterfaceManagerNotebook - a user interface manager. 00015 // .SECTION Description 00016 // This class is used to abstract the way a set of interface "panels" 00017 // (vtkKWUserInterfacePanel) can be grouped inside a widget. As such, it is a 00018 // concrete implementation of a vtkKWUserInterfaceManager. It uses a notebook 00019 // under the hood and delivers a notebook's page when one of its managed panels 00020 // request a "page" (i.e. a section within a panel). Within the notebook, each 00021 // page will be associated to a tag corresponding to its panel's ID. This 00022 // allows panels to be shown once at a time, or grouped, or displayed using 00023 // more advanced combination (like most recently used pages among all panels, 00024 // pinned pages, etc.). 00025 // This class is not a widget, the notebook is. Besides packing the notebook, 00026 // you will just have to set each panel's UserInterfaceManager ivar to point 00027 // to this manager, and the rest should be taken care of (i.e. you do not 00028 // need to manually add a panel to a manager, or manually request a page from 00029 // the manager, it should be done through the panel's API). 00030 // .SECTION See Also 00031 // vtkKWUserInterfaceManager vtkKWUserInterfacePanel 00032 00033 #ifndef __vtkKWUserInterfaceManagerNotebook_h 00034 #define __vtkKWUserInterfaceManagerNotebook_h 00035 00036 #include "vtkKWUserInterfaceManager.h" 00037 00038 class vtkKWIcon; 00039 class vtkKWNotebook; 00040 class vtkKWUserInterfacePanel; 00041 class vtkKWWidget; 00042 class vtkKWUserInterfaceManagerNotebookInternals; 00043 00044 class KWWidgets_EXPORT vtkKWUserInterfaceManagerNotebook : public vtkKWUserInterfaceManager 00045 { 00046 public: 00047 static vtkKWUserInterfaceManagerNotebook* New(); 00048 vtkTypeRevisionMacro(vtkKWUserInterfaceManagerNotebook,vtkKWUserInterfaceManager); 00049 void PrintSelf(ostream& os, vtkIndent indent); 00050 00051 // Description: 00052 // Set the user interface manager's notebook. This has to be done before 00053 // Create() is called (i.e. the sooner, the better), and can be done only 00054 // once. 00055 virtual void SetNotebook(vtkKWNotebook*); 00056 vtkGetObjectMacro(Notebook, vtkKWNotebook); 00057 00058 // Description: 00059 // Get the application instance for this object. 00060 // Override the superclass to try to retrieve the notebook's application 00061 // if it was not set already. 00062 virtual vtkKWApplication* GetApplication(); 00063 00064 // Description: 00065 // Create the manager widget (i.e. the widget that will group and display 00066 // all user interface panels). A notebook must be associated to the manager 00067 // before it is created. 00068 virtual void Create(); 00069 00070 // Description: 00071 // Instruct the manager to reserve or remove a page for a given panel. 00072 // In this concrete implementation, this adds or removes a page to the 00073 // notebook, and sets the page tag to be the panel's ID. 00074 // Note that you should use the panel's own API to add a page to a panel: 00075 // this will automatically call this method with the proper panel parameter 00076 // (see vtkKWUserInterfacePanel::AddPage() and 00077 // vtkKWUserInterfacePanel::RemovePage()). 00078 // Return a unique positive ID for the page that was reserved/removed, 00079 // or < 0 on error. 00080 virtual int AddPage(vtkKWUserInterfacePanel *panel, 00081 const char *title, 00082 const char *balloon = 0, 00083 vtkKWIcon *icon = 0); 00084 virtual int RemovePage(vtkKWUserInterfacePanel *panel, 00085 const char *title); 00086 00087 // Description: 00088 // Set a page's title, balloon help and icon. 00089 virtual void SetPageTitle(int id, const char *new_title); 00090 virtual void SetPageBalloonHelpString(int id, const char *str); 00091 virtual void SetPageIcon(int id, vtkKWIcon *icon); 00092 virtual void SetPageIconToPredefinedIcon(int id, int icon_index); 00093 00094 // Description: 00095 // Retrieve the widget corresponding to a given page reserved by the manager. 00096 // This can be done through the unique page ID, or using a panel and the 00097 // page title. The user UI components should be inserted into this widget. 00098 // In this concrete implementation, this returns the inner frame of a 00099 // notebook's page. 00100 // Note that you should use the panel's own API to get a page widget: this 00101 // will automatically call this method with the proper ID or panel parameter 00102 // (see vtkKWUserInterfacePanel::GetPageWidget()). 00103 // Return NULL on error. 00104 virtual vtkKWWidget* GetPageWidget(int id); 00105 virtual vtkKWWidget* GetPageWidget(vtkKWUserInterfacePanel *panel, 00106 const char *title); 00107 00108 // Description: 00109 // Retrieve the parent widget of the pages associated to a panel. It is 00110 // the unique widget that is common to all pages in the chain of parents. 00111 // Note that you should use the panel's own API to get the page parent: this 00112 // will automatically call this method with the proper panel parameter 00113 // (see vtkKWUserInterfacePanel::GetPagesParentWidget()). 00114 virtual vtkKWWidget *GetPagesParentWidget(vtkKWUserInterfacePanel *panel); 00115 00116 // Description: 00117 // Raise a page reserved by the manager. This can be done through the unique 00118 // page ID, or using a panel and the page title. 00119 // In this concrete implementation, this raises a notebook's page. 00120 // Note that you should use the panel's own API to raise a page: this 00121 // will automatically call this method with the proper ID or panel parameter 00122 // (see vtkKWUserInterfacePanel::RaisePage()). 00123 // Note that if the panel corresponding to the page to raise has not been 00124 // created yet, it will be created automatically by calling the panel's 00125 // Create() method (see vtkKWUserInterfacePanel::Create()) ; this allows the 00126 // creation of the panel to be delayed until it is really needed. 00127 virtual void RaisePage(int id); 00128 virtual void RaisePage(vtkKWUserInterfacePanel *panel, 00129 const char *title); 00130 00131 // Description: 00132 // Show/Hide a panel. It will make sure the pages reserved by the manager 00133 // for this panel are shown/hidden. 00134 // In this concrete implementation, this shows/hides all notebook's pages 00135 // belonging to this panel. 00136 // RaisePanel() behaves like ShowPanel(), but it will also try to bring 00137 // up the first page of the panel to the front (i.e., "select" it). 00138 // IsPanelVisible() checks if the pages of the panel are visible/shown. 00139 // Note that you should use the panel's own API to show a panel: this 00140 // will automatically call this method with the proper panel parameter 00141 // (see vtkKWUserInterfacePanel::Show()). 00142 // Note that if the panel has not been created yet, it will be created 00143 // automatically by calling the panel's Create() method (see 00144 // vtkKWUserInterfacePanel::Create()) ; this allows the creation of the 00145 // panel to be delayed until it is really needed. 00146 // Return 1 on success, 0 on error. 00147 virtual int ShowPanel(vtkKWUserInterfacePanel *panel); 00148 virtual int HidePanel(vtkKWUserInterfacePanel *panel); 00149 virtual int IsPanelVisible(vtkKWUserInterfacePanel *panel); 00150 virtual int RaisePanel(vtkKWUserInterfacePanel *panel); 00151 00152 // Description: 00153 // Update a panel according to the manager settings (i.e., it just performs 00154 // manager-specific changes on the panel). Note that it does not call the 00155 // panel's Update() method, on the opposite the panel's Update() will call 00156 // this method if the panel has a UIM set. 00157 virtual void UpdatePanel(vtkKWUserInterfacePanel *panel); 00158 00159 // Description: 00160 // Get the panel from a page ID (return the ID of the panel that holds 00161 // that page). 00162 virtual vtkKWUserInterfacePanel* GetPanelFromPageId(int page_id); 00163 00164 // Description: 00165 // Enable/disable Drag and Drop. If enabled, elements of the user interface 00166 // can be drag&drop within the same panel, or between different panels. 00167 virtual void SetEnableDragAndDrop(int); 00168 vtkBooleanMacro(EnableDragAndDrop, int); 00169 vtkGetMacro(EnableDragAndDrop, int); 00170 00171 // Description: 00172 // Get the number of Drag&Drop entries so far. 00173 // Delete all Drag&Drop entries. 00174 virtual int GetNumberOfDragAndDropEntries(); 00175 virtual int DeleteAllDragAndDropEntries(); 00176 00177 // Description: 00178 // Save/restore Drag&Drop entries to a text file. 00179 // GetDragAndDropEntry() can be used to get a Drag&Drop entry parameters 00180 // as plain text string. 00181 // DragAndDropWidget() will perform a Drag&Drop given parameters similar 00182 // to those acquired through GetDragAndDropEntry(). 00183 virtual int GetDragAndDropEntry( 00184 int idx, 00185 ostream &widget_label, 00186 ostream &from_panel_name, 00187 ostream &from_page_title, 00188 ostream &from_after_widget_label, 00189 ostream &to_panel_name, 00190 ostream &to_page_title, 00191 ostream &to_after_widget_label); 00192 virtual int DragAndDropWidget( 00193 const char *widget_label, 00194 const char *from_panel_name, 00195 const char *from_page_title, 00196 const char *from_after_widget_label, 00197 const char *to_panel_name, 00198 const char *to_page_title, 00199 const char *to_after_widget_label); 00200 00201 // Description: 00202 // Lock Drag and Drop entries. If enabled, GetDragAndDropEntry() will 00203 // not return any entry, and DragAndDropWidget() will not set any. 00204 vtkBooleanMacro(LockDragAndDropEntries, int); 00205 vtkSetMacro(LockDragAndDropEntries, int); 00206 vtkGetMacro(LockDragAndDropEntries, int); 00207 00208 //BTX 00209 // A Widget location. 00210 // Store both the page the widget is packed in, and the widget it is 00211 // packed after (if any). 00212 // @cond nested_class 00213 class WidgetLocation 00214 { 00215 public: 00216 WidgetLocation(); 00217 void Empty(); 00218 00219 int PageId; 00220 vtkKWWidget *AfterWidget; 00221 }; 00222 // @endcond 00223 00224 // A D&D entry. 00225 // Store the widget source and target location. 00226 // @cond nested_class 00227 class DragAndDropEntry 00228 { 00229 public: 00230 DragAndDropEntry(); 00231 00232 vtkKWWidget *Widget; 00233 WidgetLocation FromLocation; 00234 WidgetLocation ToLocation; 00235 }; 00236 // @endcond 00237 //ETX 00238 00239 // Description: 00240 // Callbacks. Internal, do not use. 00241 virtual void DragAndDropEndCallback( 00242 int x, int y, 00243 vtkKWWidget *widget, vtkKWWidget *anchor, vtkKWWidget *target); 00244 00245 protected: 00246 vtkKWUserInterfaceManagerNotebook(); 00247 ~vtkKWUserInterfaceManagerNotebook(); 00248 00249 // Description: 00250 // Remove the widgets of all pages belonging to a panel. It is called 00251 // by RemovePanel(). 00252 // In this concrete implementation, this will remove all notebook's pages 00253 // belonging to this panel. 00254 // Return 1 on success, 0 on error. 00255 virtual int RemovePageWidgets(vtkKWUserInterfacePanel *panel); 00256 00257 vtkKWNotebook *Notebook; 00258 00259 // Description: 00260 // Update Drag And Drop bindings 00261 virtual void UpdatePanelDragAndDrop(vtkKWUserInterfacePanel *panel); 00262 int EnableDragAndDrop; 00263 int LockDragAndDropEntries; 00264 00265 //BTX 00266 00267 // Description: 00268 // Check if a given widget can be Drag&Dropped given our framework. 00269 // At the moment, only labeled frame can be D&D. If **anchor is not NULL, 00270 // it will be assigned the widget D&D anchor (i.e. the internal part of 00271 // the widget that is actually used to grab the widget). 00272 // Return 1 if can be D&D, 0 otherwise. 00273 virtual int CanWidgetBeDragAndDropped( 00274 vtkKWWidget *widget, vtkKWWidget **anchor = 0); 00275 00276 // Description: 00277 // Assuming that the widget can be Drag&Dropped given our framework, 00278 // return a label that will be used to identify it. This is mostly used to 00279 // save a D&D event to a text string/file. 00280 virtual char* GetDragAndDropWidgetLabel(vtkKWWidget *widget); 00281 00282 // PIMPL Encapsulation for STL containers 00283 00284 vtkKWUserInterfaceManagerNotebookInternals *Internals; 00285 friend class vtkKWUserInterfaceManagerNotebookInternals; 00286 00287 // Description: 00288 // Get the location of a widget. 00289 virtual int GetDragAndDropWidgetLocation( 00290 vtkKWWidget *widget, WidgetLocation *loc); 00291 00292 // Description: 00293 // Get a D&D widget given its label (as returned by 00294 // GetDragAndDropWidgetLabel()) and a hint about its location. 00295 virtual vtkKWWidget* GetDragAndDropWidgetFromLabelAndLocation( 00296 const char *widget_label, const WidgetLocation *loc_hint); 00297 00298 // Description: 00299 // Get the last D&D entry that was added for a given widget 00300 DragAndDropEntry* GetLastDragAndDropEntry(vtkKWWidget *Widget); 00301 00302 // Description: 00303 // Check if a widget that was drag & drop has gone back to its previous 00304 // location 00305 virtual int IsDragAndDropWidgetAtOriginalLocation(vtkKWWidget *widget); 00306 00307 // Description: 00308 // Add a D&D entry to the list of entries, given a widget and its 00309 // target location (its current/source location will be computed 00310 // automatically) 00311 int AddDragAndDropEntry( 00312 vtkKWWidget *Widget, 00313 const WidgetLocation *from_loc, 00314 const WidgetLocation *to_loc); 00315 00316 // Description: 00317 // Perform the actual D&D given a widget and its target location. 00318 // It will call AddDragAndDropEntry() and pack the widget to its new 00319 // location 00320 virtual int DragAndDropWidget( 00321 vtkKWWidget *widget, 00322 const WidgetLocation *from_loc, 00323 const WidgetLocation *to_loc); 00324 00325 //ETX 00326 00327 private: 00328 00329 vtkKWUserInterfaceManagerNotebook(const vtkKWUserInterfaceManagerNotebook&); // Not implemented 00330 void operator=(const vtkKWUserInterfaceManagerNotebook&); // Not Implemented 00331 }; 00332 00333 #endif 00334