KWWidgets
debian/tmp/usr/include/KWWidgets/vtkKWDirectoryExplorer.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Module: $RCSfile: vtkKWDirectoryExplorer.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 vtkKWDirectoryExplorer - a widget for exploring directories
15 // .SECTION Description
16 // This class contains a hierarchy structure to explore directories of a
17 // file systems. It also includes a toolbar, which offers Back/Forward
18 // browsing of visited directories and functions to Create/Delete directories.
19 // .SECTION Thanks
20 // This work is part of the National Alliance for Medical Image
21 // Computing (NAMIC), funded by the National Institutes of Health
22 // through the NIH Roadmap for Medical Research, Grant U54 EB005149.
23 // Information on the National Centers for Biomedical Computing
24 // can be obtained from http://nihroadmap.nih.gov/bioinformatics.
25 // .SECTION See Also
26 // vtkKWFileBrowserDialog vtkKWFileBrowserWidget
27 
28 #ifndef __vtkKWDirectoryExplorer_h
29 #define __vtkKWDirectoryExplorer_h
30 
31 #include "vtkKWCompositeWidget.h"
32 
33 class vtkKWIcon;
34 class vtkKWToolbar;
35 class vtkKWPushButton;
38 class vtkKWMenu;
39 class vtkKWDirectoryExplorerInternals;
40 
42 {
43 public:
44  static vtkKWDirectoryExplorer* New();
46  void PrintSelf(ostream& os, vtkIndent indent);
47 
48  // Description:
49  // Open a directory given the full path.
50  // Return 1 on success, 0 otherwise
51  virtual int OpenDirectory(const char* path);
52 
53  // Description:
54  // Rename a directory name, given the current and new name
55  // of the directory.
56  // Return 1 on success, 0 otherwise
57  virtual int RenameDirectory(const char* currentname, const char* newname);
58 
59  // Description:
60  // Remove/delete a directory.
61  // Return 1 on success, 0 otherwise
62  virtual int DeleteDirectory(const char* dirname);
63 
64  // Description:
65  // Set/Get the selection mode
66  // Valid constants can be found in vtkKWOptions::SelectionModeType.
67  virtual void SetSelectionMode(int);
68  virtual void SetSelectionModeToSingle();
69  virtual void SetSelectionModeToMultiple();
70 
71  // Description:
72  // Return if one (or more) directory is/are selected.
73  virtual int HasSelection();
74 
75  // Description:
76  // Get/Set the selected director(ies).
77  virtual const char *GetSelectedDirectory()
78  {return GetNthSelectedDirectory(0);}
79  virtual int GetNumberOfSelectedDirectories();
80  virtual const char *GetNthSelectedDirectory(int i);
81  virtual void SelectDirectory(const char*);
82  virtual void DeselectDirectory(const char*);
83  virtual void ClearSelection();
84 
85  // Description:
86  // Set/Get the maximum number of directories that will be stored
87  // in back/forward history list.
88  virtual void SetMaximumNumberOfDirectoriesInHistory(int);
89  vtkGetMacro(MaximumNumberOfDirectoriesInHistory, int);
90 
91  // Description:
92  // Set/Get the selection background and foreground colors.
93  virtual void GetSelectionBackgroundColor(double *r, double *g, double *b);
94  virtual double* GetSelectionBackgroundColor();
95  virtual void SetSelectionBackgroundColor(double r, double g, double b);
96  virtual void SetSelectionBackgroundColor(double rgb[3])
97  { this->SetSelectionBackgroundColor(rgb[0], rgb[1], rgb[2]); };
98  virtual void GetSelectionForegroundColor(double *r, double *g, double *b);
99  virtual double* GetSelectionForegroundColor();
100  virtual void SetSelectionForegroundColor(double r, double g, double b);
101  virtual void SetSelectionForegroundColor(double rgb[3])
102  { this->SetSelectionForegroundColor(rgb[0], rgb[1], rgb[2]); };
103 
104  // Description:
105  // Convenience method to Set/Get the width (in chars) and height (in lines)
106  // of the tree widget.
107  virtual void SetTreeWidth(int);
108  virtual int GetTreeWidth();
109  virtual void SetTreeHeight(int);
110  virtual int GetTreeHeight();
111 
112  // Description:
113  // Convenience method to Set/Get the tree background color.
114  virtual void GetTreeBackgroundColor(double *r, double *g, double *b);
115  virtual double* GetTreeBackgroundColor();
116  virtual void SetTreeBackgroundColor(double r, double g, double b);
117  virtual void SetTreeBackgroundColor(double rgb[3])
118  { this->SetTreeBackgroundColor(rgb[0], rgb[1], rgb[2]); };
119 
120  // Description:
121  // Specifies selection-related commands to associate with the widget.
122  // DirectorySelected is called whenever the selection is changed or cleared.
123  // The 'object' argument is the object that will have the method called on
124  // it. The 'method' argument is the name of the method to be called and any
125  // arguments in string form. If the object is NULL, the method is still
126  // evaluated as a simple command.
127  // - DirectorySelected is passed the first selected directory (const char *).
128  // - DirectoryOpened and DirectoryClosed are passed the directory being
129  // opened or closed (const char *).
130  // - DirectoryAdded and DirectoryDeleted are passed the directory that was
131  // added or removed (const char *).
132  // - DirectoryRenamed is passed the preview and new name (path) of the
133  // directory that was renamed (const char *, const char *).
134  virtual void SetDirectorySelectedCommand(vtkObject *obj, const char *method);
135  virtual void SetDirectoryOpenedCommand(vtkObject *obj, const char *method);
136  virtual void SetDirectoryClosedCommand(vtkObject *obj, const char *method);
137  virtual void SetDirectoryCreatedCommand(vtkObject *obj, const char *method);
138  virtual void SetDirectoryDeletedCommand(vtkObject *obj, const char *method);
139  virtual void SetDirectoryRenamedCommand(vtkObject *obj, const char *method);
140 
141  // Description:
142  // Events are passed the same parameters as the commands, if any.
143  //BTX
144  enum
145  {
146  DirectorySelectedEvent = 10000,
150  DirectoryDeletedEvent
151  };
152  //ETX
153 
154  // Description:
155  // Set focus to the directory widget component of this widget.
156  virtual void Focus();
157  virtual int HasFocus();
158 
159  // Description:
160  // Get the toolbar object.
161  vtkGetObjectMacro(Toolbar, vtkKWToolbar);
162 
163  // Description:
164  // Get the button objects.
165  // DO NOT modify the callbacks, these accessors are provided to change
166  // the button icons, for example.
167  vtkGetObjectMacro(CreateFolderButton, vtkKWPushButton);
168  vtkGetObjectMacro(BackButton, vtkKWPushButtonWithMenu);
169  vtkGetObjectMacro(ForwardButton, vtkKWPushButtonWithMenu);
170  vtkGetObjectMacro(UpButton, vtkKWPushButton);
171 
172  // Description:
173  // Add event binding to the internal component widget
174  // for the directory hierarchy, so that these events will be
175  // invoked directly from the directory component of this widget.
176  virtual void AddBindingToInternalWidget(
177  const char* event, vtkObject *obj, const char* method);
178 
179  // Description:
180  // Callback, do NOT use.
181  // When the dropdown menu button of the Back/Forward buttons
182  // is clicked, navigate to the corresponding directory is the history list.
183  // 'node' is a pointer to the unique directory node string,
184  // 'offsetFromCurrentIndex' is the offset from current directory index in
185  // history list.
186  virtual void OpenDirectoryNodeCallback(
187  const char* node, int offsetFromCurrentIndex);
188 
189  // Description:
190  // Callback, do NOT use.
191  // When the node selection is changed in the directory tree, the
192  // corresponding directory is refreshed, loading any new files or
193  // directories underneath it.
194  virtual void SingleClickOnNodeCallback(const char* node);
195 
196  // Description:
197  // Callback, do NOT use.
198  // Right-click to popup context menu.
199  virtual void RightClickCallback( int x, int y, const char* node);
200 
201  // Description:
202  // Callback, do NOT use.
203  // Rename directory node from right-click context menu.
204  virtual int RenameCallback();
205 
206  // Description:
207  // Callback, do NOT use.
208  // Launch native explorer from right-click context menu.
209  virtual void RightClickExploreCallback(const char*);
210 
211  // Description:
212  // Callback, do NOT use.
213  // When the Navigation keys (Up/Down, Home/End,
214  // Prior(PageUp)/Next(PageDown)) are pressed. This is used to setup
215  // logic to update the new selected node after the KeyPress events.
216  virtual void TreeKeyNavigationCallback();
217 
218  // Description:
219  // Callback, do NOT use.
220  // When a node is opened in the directory tree, the corresponding
221  // directory is refreshed, loading new files and directories.
222  virtual void DirectoryOpenedCallback(const char* node);
223 
224  // Description:
225  // Callback, do NOT use.
226  // When a node selection is changed in the directory tree.
227  virtual void DirectorySelectedCallback();
228 
229  // Description:
230  // Callback, do NOT use.
231  // When a node is closed in the directory tree.
232  // Also need refreshing the contents of the corresponding directory.
233  virtual void DirectoryClosedCallback(const char* node);
234 
235  // Description:
236  // Callback, do NOT use.
237  // When the "Create New Folder" button is clicked, a dialog is displayed
238  // prompting the user for the name of the new directory. If the user inputs
239  // a valid dir name, create the new directory, add it to the dir tree, and
240  // select the node.
241  virtual void CreateNewFolderCallback();
242 
243  // Description:
244  // Callback, do NOT use.
245  // When the "Back to previous directory" button is clicked, navigate
246  // to the previously visited directory. A history of visited directories
247  // is saved in memory.
248  virtual void BackToPreviousDirectoryCallback();
249 
250  // Description:
251  // Callback, do NOT use.
252  // When the "Go to next directory" button is clicked, navigate
253  // to next directory in the history list.
254  virtual void ForwardToNextDirectoryCallback();
255 
256  // Description:
257  // Callback, do NOT use.
258  // When the "Go up one directory" button is clicked, navigate
259  // to the parent directory of the currently selected directory.
260  virtual void GoUpDirectoryCallback();
261 
262  // Description:
263  // Callback, do NOT use.
264  // When the 'Delete' key is pressed, remove the selected item from the dir
265  // tree/file list.
266  virtual int RemoveSelectedNodeCallback();
267 
268  // Description:
269  // Callback, do NOT use.
270  virtual void LoadRootDirectoryCallback();
271 
272  // Description:
273  // Update the "enable" state of the object and its internal parts.
274  // Depending on different Ivars (this->Enabled, the application's
275  // Limited Edition Mode, etc.), the "enable" state of the object
276  // is updated and propagated to its internal parts/subwidgets.
277  // This will, for example, enable/disable parts of the widget UI,
278  // enable/disable the visibility of 3D widgets, etc.
279  virtual void UpdateEnableState();
280  virtual void Update();
281 
282  // Description:
283  // Given the prefix of a sub-folder name of the current selected directory,
284  // this function will make the corresponding child node for this
285  // sub-folder visible in the window.
286  virtual void ScrollToDirectory(const char* prefix);
287 
288 protected:
291 
292  // Description:
293  // Create the widget.
294  virtual void CreateWidget();
295 
296  // Description:
297  // Load root directory. For Win32, this will load the drives;
298  // for *nix, this will load root "/" directory
299  virtual void LoadRootDirectory();
300 
301  // Description:
302  // Close all the nodes up to root level: drives for Win32; '/' for *nix
303  virtual void BackToRoot();
304 
305  // Description:
306  // When the node selection is changed in the directory tree, the
307  // corresponding directory is refreshed, loading any new files or
308  // directories underneath it.
309  virtual void SelectDirectoryNode(const char* node, int opennode = 1);
310 
311  // Description:
312  // If the directory is already loaded in the tree, navigate to
313  // and reload this input directory; if not, this function will
314  // call OpenDirectory(path) to open this directory.
315  // 'node' is a pointer to the node string (can be NULL), 'path' a pointer
316  // to the absolute path to the directory.
317  // Return the node associated with this directory.
318  virtual const char* ReloadDirectory(const char* node, const char* path);
319 
320  // Description:
321  // Reload a directory node given the parent node, and the fullpath.
322  // This is used to open the sub directory node of a parent node.
323  // 'select' is a flag to indicate whether to select this sub node after
324  // opening it.
325  // Return the node opened.
326  virtual const char* ReloadDirectory(const char* parentnode,
327  const char* dirname,
328  int select);
329 
330  // Description:
331  // Open a subdirectory of a parent tree node.
332  // 'parentnode' is the parent node of this directory, 'fullname' is the full
333  // path name of this sub-directory, 'select' a flag to indicate whether to
334  // select this sub node after opening it.
335  virtual void OpenSubDirectory(const char* parentnode,
336  const char* fullname,
337  int select = 1);
338 
339  // Description:
340  // This is the main funtion used to find all the directories and
341  // adding all the corresponding node to the dir tree.
342  virtual void OpenDirectoryNode(const char* node,
343  int select = 1,
344  int opennode = 1);
345 
346  // Description:
347  // Open the node, including all its parent nodes.
348  virtual void OpenWholeTree(const char* node);
349 
350  // Description:
351  // Calling OpenDirectoryNode after centain logic to determine
352  // whether to open the whole tree.
353  virtual void ReloadDirectoryNode(const char* node);
354 
355  // Description:
356  // This is the actual funtion adding all the nodes to the tree,
357  // called from OpenDirectoryNode.
358  virtual void UpdateDirectoryNode(const char* node);
359 
360  // Description:
361  // Add a node to the dir tree.
362  virtual void AddDirectoryNode(
363  const char* parentnode,
364  const char* node,
365  const char* text,
366  const char* fullname,
367  vtkKWIcon *nodeicon);
368 
369  // Description:
370  // Get one node from a multiple selection of nodes. An
371  // error will be generated if the index is out of range.
372  const char *GetNthSelectedNode(int i);
373 
374  // Description:
375  // Update the directory history list given the most recent node
376  virtual void UpdateMostRecentDirectoryHistory(const char* node);
377 
378  // Description:
379  // Update directory history list according to the
380  // MaximumNumberOfDirectoriesInHistory
381  virtual void PruneMostRecentDirectoriesInHistory();
382 
383  // Description:
384  // Remove a directory node from the most recent history list
385  virtual void RemoveDirectoryFromHistory(const char* node);
386 
387  // Description:
388  // Populate the context menu.
389  virtual void PopulateContextMenu(vtkKWMenu *menu, const char*);
390 
391  // Description:
392  // Check if the node is one of the selected nodes.
393  int IsNodeSelected(const char* node);
394 
395  // Description:
396  // Open the directory.
397  // -dirname, the directory that is going to be opened
398  // -select, is the flag to whether select this directory
399  // return a node for this directory
400  const char* OpenDirectoryInternal(const char* dirname, int select);
401 
402  // Description:
403  // Commands
410 
411  // Description:
412  // Invoke Commands
413  virtual void InvokeDirectorySelectedCommand(const char* path);
414  virtual void InvokeDirectoryOpenedCommand(const char* path);
415  virtual void InvokeDirectoryClosedCommand(const char* path);
416  virtual void InvokeDirectoryCreatedCommand(const char* path);
417  virtual void InvokeDirectoryDeletedCommand(const char* path);
418  virtual void InvokeDirectoryRenamedCommand(
419  const char* oldname, const char* newname);
420 
421  // Description:
422  // Internal PIMPL class for STL purposes.
423  vtkKWDirectoryExplorerInternals *Internals;
424 
425  // Description:
426  // GUI
434 
435  // Description:
436  // Member variables
438 
439 private:
440 
441  static vtkIdType IdCounter;
442 
443  vtkKWDirectoryExplorer(const vtkKWDirectoryExplorer&); // Not implemented
444  void operator=(const vtkKWDirectoryExplorer&); // Not implemented
445 };
446 #endif