KWWidgets
debian/tmp/usr/include/KWWidgets/vtkKWTree.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3 Copyright (c) 1998-2003 Kitware Inc. 469 Clifton Corporate Parkway,
4 Clifton Park, NY, 12065, USA.
5 All rights reserved.
6 
7 Redistribution and use in source and binary forms, with or without
8 modification, are permitted provided that the following conditions are met:
9 
10  * Redistributions of source code must retain the above copyright notice,
11  this list of conditions and the following disclaimer.
12 
13  * Redistributions in binary form must reproduce the above copyright notice,
14  this list of conditions and the following disclaimer in the documentation
15  and/or other materials provided with the distribution.
16 
17  * Neither the name of Kitware nor the names of any contributors may be used
18  to endorse or promote products derived from this software without specific
19  prior written permission.
20 
21  * Modified source versions must be plainly marked as such, and must not be
22  misrepresented as being the original software.
23 
24 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
25 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR
28 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
30 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
31 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
32 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
33 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34 
35 =========================================================================*/
36 // .NAME vtkKWTree - tree widget
37 // .SECTION Description
38 // A simple tree widget
39 
40 #ifndef __vtkKWTree_h
41 #define __vtkKWTree_h
42 
43 #include "vtkKWCoreWidget.h"
44 
45 class vtkKWTreeInternals;
46 
48 {
49 public:
50  static vtkKWTree* New();
51  vtkTypeRevisionMacro(vtkKWTree,vtkKWCoreWidget);
52  void PrintSelf(ostream& os, vtkIndent indent);
53 
54  // Description:
55  // Add a new node identified by 'node' at the end of the children list of
56  // 'parent'. If parent is NULL, or an empty string or 'root', insert at the
57  // root of the tree automatically. Note that the 'node' parameter is the
58  // string identifier to be used later on to refer to the node. The label
59  // of the node itself is provided by the 'text' parameter.
60  // A new node is selectable and closed by default.
61  virtual void AddNode(const char *parent, const char *node, const char *text);
62 
63  // Description:
64  // Delete a node identified by parameter 'node', which is the
65  // unique string identifier.
66  virtual void DeleteNode(const char *node);
67 
68  // Description:
69  // Set/Get the label of the node.
70  // The return value of GetNodeText is a pointer to a temporary buffer
71  // which contents should be copied *right away*.
72  virtual const char* GetNodeText(const char *node);
73  virtual void SetNodeText(const char *node, const char *text);
74 
75  // Description:
76  // Set/Get if node can be selected.
77  virtual int GetNodeSelectableFlag(const char *node);
78  virtual void SetNodeSelectableFlag(const char *node, int flag);
79 
80  // Description:
81  // Specifies the font to use when drawing a specific node.
82  // You can use predefined font names (e.g. 'system'), or you can specify
83  // a set of font attributes with a platform-independent name, for example,
84  // 'times 12 bold'. In this example, the font is specified with a three
85  // element list: the first element is the font family, the second is the
86  // size, the third is a list of style parameters (normal, bold, roman,
87  // italic, underline, overstrike). Example: 'times 12 {bold italic}'.
88  // The Times, Courier and Helvetica font families are guaranteed to exist
89  // and will be matched to the corresponding (closest) font on your system.
90  // If you are familiar with the X font names specification, you can also
91  // describe the font that way (say, '*times-medium-r-*-*-12*').
92  // The return value of GetNodeFont is a pointer to a temporary buffer
93  // which contents should be copied *right away*.
94  virtual const char* GetNodeFont(const char *node);
95  virtual void SetNodeFont(const char *node, const char *font);
96 
97  // Description:
98  // Convenience methods to set the font weight/slant for a specific node.
99  // For more control, check the SetNodeFont method.
100  virtual void SetNodeFontWeightToBold(const char *node);
101  virtual void SetNodeFontWeightToNormal(const char *node);
102  virtual void SetNodeFontSlantToItalic(const char *node);
103  virtual void SetNodeFontSlantToRoman(const char *node);
104 
105  // Description:
106  // Set/Get the user data associated to the node. This can be used
107  // to bury additional data in the node.
108  // The return value of GetNodeUserData is a pointer to a temporary buffer
109  // which contents should be copied *right away*.
110  virtual const char* GetNodeUserData(const char *node);
111  virtual void SetNodeUserData(const char *node, const char *data);
112  virtual int GetNodeUserDataAsInt(const char *node);
113  virtual void SetNodeUserDataAsInt(const char *node, int);
114 
115  // Description:
116  // Query if given node exists in the tree
117  virtual int HasNode(const char *node);
118 
119  // Description:
120  // Delete all nodes
121  virtual void DeleteAllNodes();
122 
123  // Description:
124  // Delete all child nodes of the given node
125  virtual void DeleteNodeChildren(const char *node);
126 
127  // Description:
128  // Get node's children as a space separated list of nodes
129  // The return value of GetNodeChildren is a pointer to a temporary buffer
130  // which contents should be copied *right away*.
131  virtual const char* GetNodeChildren(const char *node);
132 
133  // Description:
134  // Get node's parent
135  // The return value of GetNodeParent is a pointer to a temporary buffer
136  // which contents should be copied *right away*.
137  virtual const char* GetNodeParent(const char *node);
138 
139  // Description:
140  // Return if a node is the ancestor of another node.
141  virtual int IsNodeAncestor(const char *ancestor, const char *node);
142 
143  // Description:
144  // Mode a node to the children list of parent at position index. Parent
145  // can not be a descendant of node.
146  virtual void MoveNode(const char *node, const char *new_parent, int pos);
147 
148  // Description:
149  // Find a node with a specific user data associated, starting the
150  // search among the children of a specific node (set it to NULL or 'root'
151  // to search the whole tree).
152  // Return node name if found, NULL otherwise.
153  // The return value of both methods is a pointer to a temporary buffer
154  // which contents should be copied *right away*.
155  virtual const char* FindNodeWithUserData(
156  const char *parent, const char *data);
157  virtual const char* FindNodeWithUserDataAsInt(
158  const char *parent, int data);
159 
160  // Description:
161  // Set/Get the one of several styles for manipulating the selection.
162  // Valid constants can be found in vtkKWOptions::SelectionModeType.
163  virtual void SetSelectionMode(int);
164  vtkGetMacro(SelectionMode, int);
165  virtual void SetSelectionModeToSingle();
166  virtual void SetSelectionModeToMultiple();
167 
168  // Description:
169  // Select a node (this adds the node to the selection), deselect a node.
170  // Note that this selecting more than one node is likely not to work if
171  // the SelectionMode is not Multiple.
172  virtual void SelectNode(const char *node);
173  virtual void DeselectNode(const char *node);
174 
175  // Description:
176  // Select a single node (any other selection is cleared first)
177  virtual void SelectSingleNode(const char *node);
178 
179  // Description:
180  // Clear the selection
181  virtual void ClearSelection();
182 
183  // Description:
184  // Return the selection as a list of space separated selected nodes
185  // The return value of GetSelection is a pointer to a temporary buffer
186  // which contents should be copied *right away*.
187  virtual const char* GetSelection();
188 
189  // Description:
190  // Return if a node is selected
191  virtual int HasSelection();
192 
193  // Description:
194  // Select/Deselect all the node's children.
195  // Note that this selecting more than one node is likely not to work if
196  // the SelectionMode is not Multiple.
197  virtual void SelectNodeChildren(const char *node);
198  virtual void DeselectNodeChildren(const char *node);
199 
200  // Description:
201  // Arrange the tree to see a given node
202  virtual void SeeNode(const char *node);
203 
204  // Description:
205  // Open/close a node.
206  virtual void OpenNode(const char *node);
207  virtual void CloseNode(const char *node);
208  virtual int IsNodeOpen(const char *node);
209 
210  // Description:
211  // Open/close the first node of the tree.
212  virtual void OpenFirstNode();
213  virtual void CloseFirstNode();
214 
215  // Description:
216  // Open/close a tree, i.e. a node and all its children.
217  virtual void OpenTree(const char *node);
218  virtual void CloseTree(const char *node);
219 
220  // Description:
221  // Specifies wether or not a node can be reparented interactively using
222  // drag and drop.
223  // Check the NodeParentChangedCommand callback and NodeParentChangedEvent
224  // to be notified about the change.
225  vtkBooleanMacro(EnableReparenting, int);
226  vtkGetMacro(EnableReparenting, int);
227  virtual void SetEnableReparenting(int);
228 
229  // Description:
230  // Set/Get the width/height.
231  virtual void SetWidth(int);
232  virtual int GetWidth();
233  virtual void SetHeight(int);
234  virtual int GetHeight();
235 
236  // Description:
237  // Specifies an image to display at the left of the label of a node.
238  // The SetImageToPredefinedIcon method accepts an index to one of the
239  // predefined icon listed in vtkKWIcon.
240  // The SetImageToPixels method sets the image using pixel data. It expects
241  // a pointer to the pixels and the structure of the image, i.e. its width,
242  // height and the pixel_size (how many bytes per pixel, say 3 for RGB, or
243  // 1 for grayscale). If buffer_length = 0, it is computed automatically
244  // from the previous parameters. If it is not, it will most likely indicate
245  // that the buffer has been encoded using base64 and/or zlib.
246  // If pixel_size > 3 (i.e. RGBA), the image is blend the with background
247  // color of the widget.
248  virtual void SetNodeImageToIcon(const char *node, vtkKWIcon *icon);
249  virtual void SetNodeImageToPredefinedIcon(const char *node, int icon_index);
250  virtual void SetNodeImageToPixels(const char *node,
251  const unsigned char *pixels, int width, int height, int pixel_size,
252  unsigned long buffer_length = 0);
253 
254  // Description:
255  // Set/Get a window/widget to display at the left of the label of a node.
256  // This option overrides any image option.
257  // Note that this window/widget *has* to be a child of this tree instance.
258  virtual void SetNodeWindow(const char *node, vtkKWWidget *w);
259  virtual vtkKWWidget* GetNodeWindow(const char *node);
260 
261  // Description:
262  // Starting with node, find all children nodes with a NodeWindow set
263  // and call Delete() and each of the corresponding widget.
264  // Use NULL or "root" to delete from the top.
265  virtual void DeleteAllNodeWindows(const char *parent);
266 
267  // Description:
268  // Set/Get the distance between image or window and text of a node.
269  virtual void SetNodePadX(const char *node, int);
270  virtual int GetNodePadX(const char *node);
271 
272  // Description:
273  // Specifies wether or not the tree should be redrawn when entering idle.
274  // Set it to false if you call update while modifying the tree
275  vtkBooleanMacro(RedrawOnIdle, int);
276  virtual void SetRedrawOnIdle(int);
277  virtual int GetRedrawOnIdle();
278 
279  // Description:
280  // Specifies wether or not lines should be drawn between nodes.
281  vtkBooleanMacro(LinesVisibility, int);
282  virtual void SetLinesVisibility(int);
283  virtual int GetLinesVisibility();
284 
285  // Description:
286  // If true, the selection box will be drawn across the entire tree from
287  // left-to-right instead of just around the item text.
288  vtkBooleanMacro(SelectionFill, int);
289  virtual void SetSelectionFill(int);
290  virtual int GetSelectionFill();
291 
292  // Description:
293  // Set/Get the background color of the widget.
294  virtual void GetBackgroundColor(double *r, double *g, double *b);
295  virtual double* GetBackgroundColor();
296  virtual void SetBackgroundColor(double r, double g, double b);
297  virtual void SetBackgroundColor(double rgb[3])
298  { this->SetBackgroundColor(rgb[0], rgb[1], rgb[2]); };
299 
300  // Description:
301  // Set/Get the highlight thickness, a non-negative value indicating the
302  // width of the highlight rectangle to draw around the outside of the
303  // widget when it has the input focus.
304  virtual void SetHighlightThickness(int);
305  virtual int GetHighlightThickness();
306 
307  // Description:
308  // Set/Get the border width, a non-negative value indicating the width of
309  // the 3-D border to draw around the outside of the widget (if such a border
310  // is being drawn; the Relief option typically determines this).
311  virtual void SetBorderWidth(int);
312  virtual int GetBorderWidth();
313 
314  // Description:
315  // Set/Get the 3-D effect desired for the widget.
316  // The value indicates how the interior of the widget should appear
317  // relative to its exterior.
318  // Valid constants can be found in vtkKWOptions::ReliefType.
319  virtual void SetRelief(int);
320  virtual int GetRelief();
321  virtual void SetReliefToRaised();
322  virtual void SetReliefToSunken();
323  virtual void SetReliefToFlat();
324  virtual void SetReliefToRidge();
325  virtual void SetReliefToSolid();
326  virtual void SetReliefToGroove();
327 
328  // Description:
329  // Set/Get the distance between image or window and text of the nodes.
330  virtual void SetPadX(int);
331  virtual int GetPadX();
332 
333  // Description:
334  // Set/Get the horizontal indentation between a node and its children.
335  virtual void SetDeltaX(int);
336  virtual int GetDeltaX();
337 
338  // Description:
339  // Set/Get the vertical size of the nodes.
340  virtual void SetDeltaY(int);
341  virtual int GetDeltaY();
342 
343  // Description:
344  // Set/Get the selection foreground and background color
345  virtual void GetSelectionBackgroundColor(double *r, double *g, double *b);
346  virtual double* GetSelectionBackgroundColor();
347  virtual void SetSelectionBackgroundColor(double r, double g, double b);
348  virtual void SetSelectionBackgroundColor(double rgb[3])
349  { this->SetSelectionBackgroundColor(rgb[0], rgb[1], rgb[2]); };
350  virtual void GetSelectionForegroundColor(double *r, double *g, double *b);
351  virtual double* GetSelectionForegroundColor();
352  virtual void SetSelectionForegroundColor(double r, double g, double b);
353  virtual void SetSelectionForegroundColor(double rgb[3])
354  { this->SetSelectionForegroundColor(rgb[0], rgb[1], rgb[2]); };
355 
356  // Description:
357  // Specifies a command to associate with the widget. This command is
358  // typically invoked when the user opens a node.
359  // The 'object' argument is the object that will have the method called on
360  // it. The 'method' argument is the name of the method to be called and any
361  // arguments in string form. If the object is NULL, the method is still
362  // evaluated as a simple command.
363  // The following parameters are also passed to the command:
364  // - path to the opened node: const char*
365  virtual void SetOpenCommand(vtkObject *object, const char *method);
366 
367  // Description:
368  // Specifies a command to associate with the widget. This command is
369  // typically invoked when the user closes a node.
370  // The 'object' argument is the object that will have the method called on
371  // it. The 'method' argument is the name of the method to be called and any
372  // arguments in string form. If the object is NULL, the method is still
373  // evaluated as a simple command.
374  // The following parameters are also passed to the command:
375  // - path to the closed node: const char*
376  virtual void SetCloseCommand(vtkObject *object, const char *method);
377 
378  // Description:
379  // Set/add/remove a binding to a widget, i.e. the command that is invoked
380  // whenever the 'event' is triggered on the widget.
381  // SetBinding will replace any old bindings, whereas AddBinding will
382  // add the binding to the list of bindings already defined for that event.
383  // RemoveBinding can remove a specific binding or all bindings for an event.
384  // The 'object' argument is the object that will have the method called on
385  // it. The 'method' argument is the name of the method to be called and any
386  // arguments in string form. If the object is NULL, the method is still
387  // evaluated as a simple command.
388  virtual void SetBinding(
389  const char *event, vtkObject *object, const char *method);
390  virtual void SetBinding(
391  const char *event, const char *command);
392  virtual void AddBinding(
393  const char *event, vtkObject *object, const char *method);
394  virtual void AddBinding(
395  const char *event, const char *command);
396  virtual void RemoveBinding(const char *event);
397  virtual void RemoveBinding(
398  const char *event, vtkObject *object, const char *method);
399 
400  // Description:
401  // Specifies a command to execute whenever the event sequence given
402  // by 'event' occurs on the label of a node.
403  // The 'object' argument is the object that will have the method called on
404  // it. The 'method' argument is the name of the method to be called and any
405  // arguments in string form. If the object is NULL, the method is still
406  // evaluated as a simple command.
407  // The following parameters are also passed to the command:
408  // - path to the node for which the event occured: const char*
409  virtual void SetBindText(
410  const char *event, vtkObject *object, const char *method);
411 
412  // Description:
413  // Set the command for single/double/right click on a node. This,
414  // in turn, just calls SetBindText.
415  // WARNING: SetSingleClickOnNodeCommand will override the default behaviour
416  // that selects a node when it is clicked on. It is therefore up to the
417  // user to select the node if needed.
418  // The 'object' argument is the object that will have the method called on
419  // it. The 'method' argument is the name of the method to be called and any
420  // arguments in string form. If the object is NULL, the method is still
421  // evaluated as a simple command.
422  // The following parameters are also passed to the command:
423  // - path to the node for which the event occured: const char*
424  virtual void SetDoubleClickOnNodeCommand(
425  vtkObject *object, const char *method);
426  virtual void SetSingleClickOnNodeCommand(
427  vtkObject *object, const char *method);
428  virtual void SetRightClickOnNodeCommand(
429  vtkObject *object, const char *method);
430 
431  // Description:
432  // Specifies a command to associate with the widget. This command is
433  // typically invoked when the selection changes.
434  // The 'object' argument is the object that will have the method called on
435  // it. The 'method' argument is the name of the method to be called and any
436  // arguments in string form. If the object is NULL, the method is still
437  // evaluated as a simple command.
438  virtual void SetSelectionChangedCommand(
439  vtkObject *object, const char *method);
440 
441  // Description:
442  // Specifies a command to associate with the widget. This command is
443  // typically invoked when a node is reparented interactively.
444  // The 'object' argument is the object that will have the method called on
445  // it. The 'method' argument is the name of the method to be called and any
446  // arguments in string form. If the object is NULL, the method is still
447  // evaluated as a simple command.
448  // The following parameters are also passed to the command:
449  // - path to the node that was reparented: const char*
450  // - path to the node's new parent: const char*
451  // - path to the node's previous parent: const char*
452  virtual void SetNodeParentChangedCommand(
453  vtkObject *object, const char *method);
454 
455  // Description:
456  // Events. The SelectionChangedEvent is triggered when the selection is
457  // changed (i.e. one or more node(s) are selected/deselected).
458  // It is similar in concept as the 'SelectionChangedCommand' but can be
459  // used by multiple listeners/observers at a time.
460  // The RightClickOnNodeEvent event is triggered when right-clicking on
461  // a specific node.
462  // The following parameters are also passed as client data for
463  // RightClickOnNodeEvent:
464  // - path to the node: const char*
465  // The following parameters are also passed as client data for
466  // NodeParentChangedEvent:
467  // - path to the node that was reparented: const char*
468  // - path to the node's new parent: const char*
469  // - path to the node's previous parent: const char*
470  //BTX
471  enum
472  {
473  SelectionChangedEvent = 10000,
475  NodeParentChangedEvent
476  };
477  //ETX
478 
479  // Description:
480  // Update the "enable" state of the object and its internal parts.
481  // Depending on different Ivars (this->Enabled, the application's
482  // Limited Edition Mode, etc.), the "enable" state of the object is updated
483  // and propagated to its internal parts/subwidgets. This will, for example,
484  // enable/disable parts of the widget UI, enable/disable the visibility
485  // of 3D widgets, etc.
486  virtual void UpdateEnableState();
487 
488  // Description:
489  // Specifies if the node text should be stored in a raw format, i.e.
490  // without converting from the application's CharacterEncoding to the
491  // internal Tcl/Tk encoding. Off by default.
492  vtkBooleanMacro(UseRawNodeText, int);
493  vtkGetMacro(UseRawNodeText, int);
494  vtkSetMacro(UseRawNodeText, int);
495 
496  // Description:
497  // Specifies if the node user data should be stored in a raw format, i.e.
498  // without converting from the application's CharacterEncoding to the
499  // internal Tcl/Tk encoding. Off by default.
500  vtkBooleanMacro(UseRawNodeUserData, int);
501  vtkGetMacro(UseRawNodeUserData, int);
502  vtkSetMacro(UseRawNodeUserData, int);
503 
504  // Description:
505  // Set focus to this widget.
506  virtual void Focus();
507  virtual int HasFocus();
508 
509  // Description:
510  // Callbacks. Internal, do not use.
511  virtual void SelectionCallback();
512  virtual void RightClickOnNodeCallback(const char *node);
513  virtual void KeyNavigationCallback(const char* key);
514  virtual void DropOverNodeCallback(const char*, const char*, const char*, const char*, const char*, const char*);
515 
516  // Description:
517  // Automatically scroll the window to show most, if not all,
518  // sub-directories of the given node
519  virtual void DisplayChildNodes(const char* node);
520 
521 protected:
522  vtkKWTree();
523  ~vtkKWTree();
524 
525  // Description:
526  // Create the widget.
527  virtual void CreateWidget();
528 
533 
535  virtual void InvokeSelectionChangedCommand();
536 
538  virtual void InvokeNodeParentChangedCommand(
539  const char *node, const char *new_parent, const char *previous_parent);
540 
541  virtual void UpdateDragAndDrop();
542 
543  // PIMPL Encapsulation for STL containers
544  //BTX
545  vtkKWTreeInternals *Internals;
546  //ETX
547 
548 private:
549  vtkKWTree(const vtkKWTree&); // Not implemented
550  void operator=(const vtkKWTree&); // Not implemented
551 };
552 
553 #endif