• Main Page
  • Classes
  • Files
  • Directories
  • File List
  • File Members

vtkKWTree.h

Go to the documentation of this file.
00001 /*=========================================================================
00002 
00003 Copyright (c) 1998-2003 Kitware Inc. 469 Clifton Corporate Parkway,
00004 Clifton Park, NY, 12065, USA.
00005 All rights reserved.
00006 
00007 Redistribution and use in source and binary forms, with or without
00008 modification, are permitted provided that the following conditions are met:
00009 
00010  * Redistributions of source code must retain the above copyright notice,
00011    this list of conditions and the following disclaimer.
00012 
00013  * Redistributions in binary form must reproduce the above copyright notice,
00014    this list of conditions and the following disclaimer in the documentation
00015    and/or other materials provided with the distribution.
00016 
00017  * Neither the name of Kitware nor the names of any contributors may be used
00018    to endorse or promote products derived from this software without specific
00019    prior written permission.
00020 
00021  * Modified source versions must be plainly marked as such, and must not be
00022    misrepresented as being the original software.
00023 
00024 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
00025 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00026 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00027 ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR
00028 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00029 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
00030 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00031 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
00032 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
00033 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00034 
00035 =========================================================================*/
00036 // .NAME vtkKWTree - tree widget
00037 // .SECTION Description
00038 // A simple tree widget
00039 
00040 #ifndef __vtkKWTree_h
00041 #define __vtkKWTree_h
00042 
00043 #include "vtkKWCoreWidget.h"
00044 
00045 class vtkKWTreeInternals;
00046 
00047 class KWWidgets_EXPORT vtkKWTree : public vtkKWCoreWidget
00048 {
00049 public:
00050   static vtkKWTree* New();
00051   vtkTypeRevisionMacro(vtkKWTree,vtkKWCoreWidget);
00052   void PrintSelf(ostream& os, vtkIndent indent);
00053 
00054   // Description:
00055   // Add a new node identified by 'node' at the end of the children list of 
00056   // 'parent'. If parent is NULL, or an empty string or 'root', insert at the
00057   // root of the tree automatically. Note that the 'node' parameter is the
00058   // string identifier to be used later on to refer to the node. The label
00059   // of the node itself is provided by the 'text' parameter.
00060   // A new node is selectable and closed by default.
00061   virtual void AddNode(const char *parent, const char *node, const char *text);
00062   
00063   // Description:
00064   // Delete a node identified by parameter 'node', which is the
00065   // unique string identifier.
00066   virtual void DeleteNode(const char *node);
00067 
00068   // Description:
00069   // Set/Get the label of the node.
00070   // The return value of GetNodeText is a pointer to a temporary buffer
00071   // which contents should be copied *right away*.
00072   virtual const char* GetNodeText(const char *node);
00073   virtual void SetNodeText(const char *node, const char *text);
00074 
00075   // Description:
00076   // Set/Get if node can be selected.
00077   virtual int GetNodeSelectableFlag(const char *node);
00078   virtual void SetNodeSelectableFlag(const char *node, int flag);
00079 
00080   // Description:
00081   // Specifies the font to use when drawing a specific node. 
00082   // You can use predefined font names (e.g. 'system'), or you can specify
00083   // a set of font attributes with a platform-independent name, for example,
00084   // 'times 12 bold'. In this example, the font is specified with a three
00085   // element list: the first element is the font family, the second is the
00086   // size, the third is a list of style parameters (normal, bold, roman, 
00087   // italic, underline, overstrike). Example: 'times 12 {bold italic}'.
00088   // The Times, Courier and Helvetica font families are guaranteed to exist
00089   // and will be matched to the corresponding (closest) font on your system.
00090   // If you are familiar with the X font names specification, you can also
00091   // describe the font that way (say, '*times-medium-r-*-*-12*').
00092   // The return value of GetNodeFont is a pointer to a temporary buffer
00093   // which contents should be copied *right away*.
00094   virtual const char* GetNodeFont(const char *node);
00095   virtual void SetNodeFont(const char *node, const char *font);
00096 
00097   // Description:
00098   // Convenience methods to set the font weight/slant for a specific node.
00099   // For more control, check the SetNodeFont method.
00100   virtual void SetNodeFontWeightToBold(const char *node);
00101   virtual void SetNodeFontWeightToNormal(const char *node);
00102   virtual void SetNodeFontSlantToItalic(const char *node);
00103   virtual void SetNodeFontSlantToRoman(const char *node);
00104 
00105   // Description:
00106   // Set/Get the user data associated to the node. This can be used
00107   // to bury additional data in the node.
00108   // The return value of GetNodeUserData is a pointer to a temporary buffer
00109   // which contents should be copied *right away*.
00110   virtual const char* GetNodeUserData(const char *node);
00111   virtual void SetNodeUserData(const char *node, const char *data);
00112   virtual int GetNodeUserDataAsInt(const char *node);
00113   virtual void SetNodeUserDataAsInt(const char *node, int);
00114 
00115   // Description:
00116   // Query if given node exists in the tree
00117   virtual int HasNode(const char *node);
00118 
00119   // Description:
00120   // Delete all nodes
00121   virtual void DeleteAllNodes();
00122   
00123   // Description:
00124   // Delete all child nodes of the given node
00125   virtual void DeleteNodeChildren(const char *node);
00126   
00127   // Description:
00128   // Get node's children as a space separated list of nodes
00129   // The return value of GetNodeChildren is a pointer to a temporary buffer
00130   // which contents should be copied *right away*.
00131   virtual const char* GetNodeChildren(const char *node);
00132 
00133   // Description:
00134   // Get node's parent
00135   // The return value of GetNodeParent is a pointer to a temporary buffer
00136   // which contents should be copied *right away*.
00137   virtual const char* GetNodeParent(const char *node);
00138 
00139   // Description:
00140   // Return if a node is the ancestor of another node.
00141   virtual int IsNodeAncestor(const char *ancestor, const char *node);
00142 
00143   // Description:
00144   // Mode a node to the children list of parent at position index. Parent
00145   // can not be a descendant of node.
00146   virtual void MoveNode(const char *node, const char *new_parent, int pos);
00147 
00148   // Description:
00149   // Find a node with a specific user data associated, starting the
00150   // search among the children of a specific node (set it to NULL or 'root'
00151   // to search the whole tree).
00152   // Return node name if found, NULL otherwise.
00153   // The return value of both methods is a pointer to a temporary buffer
00154   // which contents should be copied *right away*.
00155   virtual const char* FindNodeWithUserData(
00156     const char *parent, const char *data);
00157   virtual const char* FindNodeWithUserDataAsInt(
00158     const char *parent, int data);
00159 
00160   // Description:
00161   // Set/Get the one of several styles for manipulating the selection. 
00162   // Valid constants can be found in vtkKWOptions::SelectionModeType.
00163   virtual void SetSelectionMode(int);
00164   vtkGetMacro(SelectionMode, int);
00165   virtual void SetSelectionModeToSingle();
00166   virtual void SetSelectionModeToMultiple();
00167 
00168   // Description:
00169   // Select a node (this adds the node to the selection), deselect a node.
00170   // Note that this selecting more than one node is likely not to work if
00171   // the SelectionMode is not Multiple.
00172   virtual void SelectNode(const char *node);
00173   virtual void DeselectNode(const char *node);
00174 
00175   // Description:
00176   // Select a single node (any other selection is cleared first)
00177   virtual void SelectSingleNode(const char *node);
00178 
00179   // Description:
00180   // Clear the selection
00181   virtual void ClearSelection();
00182 
00183   // Description:
00184   // Return the selection as a list of space separated selected nodes
00185   // The return value of GetSelection is a pointer to a temporary buffer
00186   // which contents should be copied *right away*.
00187   virtual const char* GetSelection();
00188 
00189   // Description:
00190   // Return if a node is selected
00191   virtual int HasSelection();
00192 
00193   // Description:
00194   // Select/Deselect all the node's children.
00195   // Note that this selecting more than one node is likely not to work if
00196   // the SelectionMode is not Multiple.
00197   virtual void SelectNodeChildren(const char *node);
00198   virtual void DeselectNodeChildren(const char *node);
00199 
00200   // Description:
00201   // Arrange the tree to see a given node
00202   virtual void SeeNode(const char *node);
00203 
00204   // Description:
00205   // Open/close a node.
00206   virtual void OpenNode(const char *node);
00207   virtual void CloseNode(const char *node);
00208   virtual int IsNodeOpen(const char *node);
00209 
00210   // Description:
00211   // Open/close the first node of the tree.
00212   virtual void OpenFirstNode();
00213   virtual void CloseFirstNode();
00214 
00215   // Description:
00216   // Open/close a tree, i.e. a node and all its children.
00217   virtual void OpenTree(const char *node);
00218   virtual void CloseTree(const char *node);
00219 
00220   // Description:
00221   // Specifies wether or not a node can be reparented interactively using
00222   // drag and drop.
00223   // Check the NodeParentChangedCommand callback and NodeParentChangedEvent
00224   // to be notified about the change.
00225   vtkBooleanMacro(EnableReparenting, int);
00226   vtkGetMacro(EnableReparenting, int);
00227   virtual void SetEnableReparenting(int);
00228 
00229   // Description:
00230   // Set/Get the width/height.
00231   virtual void SetWidth(int);
00232   virtual int GetWidth();
00233   virtual void SetHeight(int);
00234   virtual int GetHeight();
00235 
00236   // Description:
00237   // Specifies an image to display at the left of the label of a node.
00238   // The SetImageToPredefinedIcon method accepts an index to one of the
00239   // predefined icon listed in vtkKWIcon.
00240   // The SetImageToPixels method sets the image using pixel data. It expects
00241   // a pointer to the pixels and the structure of the image, i.e. its width, 
00242   // height and the pixel_size (how many bytes per pixel, say 3 for RGB, or
00243   // 1 for grayscale). If buffer_length = 0, it is computed automatically
00244   // from the previous parameters. If it is not, it will most likely indicate
00245   // that the buffer has been encoded using base64 and/or zlib.
00246   // If pixel_size > 3 (i.e. RGBA), the image is blend the with background
00247   // color of the widget.
00248   virtual void SetNodeImageToIcon(const char *node, vtkKWIcon *icon);
00249   virtual void SetNodeImageToPredefinedIcon(const char *node, int icon_index);
00250   virtual void SetNodeImageToPixels(const char *node,
00251     const unsigned char *pixels, int width, int height, int pixel_size,
00252     unsigned long buffer_length = 0);
00253   
00254   // Description:
00255   // Set/Get a window/widget to display at the left of the label of a node.
00256   // This option overrides any image option.
00257   // Note that this window/widget *has* to be a child of this tree instance.
00258   virtual void SetNodeWindow(const char *node, vtkKWWidget *w);
00259   virtual vtkKWWidget* GetNodeWindow(const char *node);
00260 
00261   // Description:
00262   // Starting with node, find all children nodes with a NodeWindow set
00263   // and call Delete() and each of the corresponding widget.
00264   // Use NULL or "root" to delete from the top.
00265   virtual void DeleteAllNodeWindows(const char *parent);
00266 
00267   // Description:
00268   // Set/Get the distance between image or window and text of a node.
00269   virtual void SetNodePadX(const char *node, int);
00270   virtual int GetNodePadX(const char *node);
00271 
00272   // Description:
00273   // Specifies wether or not the tree should be redrawn when entering idle. 
00274   // Set it to false if you call update while modifying the tree
00275   vtkBooleanMacro(RedrawOnIdle, int);
00276   virtual void SetRedrawOnIdle(int);
00277   virtual int GetRedrawOnIdle();
00278 
00279   // Description:
00280   // Specifies wether or not lines should be drawn between nodes.
00281   vtkBooleanMacro(LinesVisibility, int);
00282   virtual void SetLinesVisibility(int);
00283   virtual int GetLinesVisibility();
00284 
00285   // Description:
00286   // If true, the selection box will be drawn across the entire tree from
00287   // left-to-right instead of just around the item text.
00288   vtkBooleanMacro(SelectionFill, int);
00289   virtual void SetSelectionFill(int);
00290   virtual int GetSelectionFill();
00291 
00292   // Description:
00293   // Set/Get the background color of the widget.
00294   virtual void GetBackgroundColor(double *r, double *g, double *b);
00295   virtual double* GetBackgroundColor();
00296   virtual void SetBackgroundColor(double r, double g, double b);
00297   virtual void SetBackgroundColor(double rgb[3])
00298     { this->SetBackgroundColor(rgb[0], rgb[1], rgb[2]); };
00299   
00300   // Description:
00301   // Set/Get the highlight thickness, a non-negative value indicating the
00302   // width of the highlight rectangle to draw around the outside of the
00303   // widget when it has the input focus.
00304   virtual void SetHighlightThickness(int);
00305   virtual int GetHighlightThickness();
00306   
00307   // Description:
00308   // Set/Get the border width, a non-negative value indicating the width of
00309   // the 3-D border to draw around the outside of the widget (if such a border
00310   // is being drawn; the Relief option typically determines this).
00311   virtual void SetBorderWidth(int);
00312   virtual int GetBorderWidth();
00313   
00314   // Description:
00315   // Set/Get the 3-D effect desired for the widget. 
00316   // The value indicates how the interior of the widget should appear
00317   // relative to its exterior. 
00318   // Valid constants can be found in vtkKWOptions::ReliefType.
00319   virtual void SetRelief(int);
00320   virtual int GetRelief();
00321   virtual void SetReliefToRaised();
00322   virtual void SetReliefToSunken();
00323   virtual void SetReliefToFlat();
00324   virtual void SetReliefToRidge();
00325   virtual void SetReliefToSolid();
00326   virtual void SetReliefToGroove();
00327 
00328   // Description:
00329   // Set/Get the distance between image or window and text of the nodes.
00330   virtual void SetPadX(int);
00331   virtual int GetPadX();
00332 
00333   // Description:
00334   // Set/Get the horizontal indentation between a node and its children.
00335   virtual void SetDeltaX(int);
00336   virtual int GetDeltaX();
00337 
00338   // Description:
00339   // Set/Get the vertical size of the nodes.
00340   virtual void SetDeltaY(int);
00341   virtual int GetDeltaY();
00342 
00343   // Description:
00344   // Set/Get the selection foreground and background color
00345   virtual void GetSelectionBackgroundColor(double *r, double *g, double *b);
00346   virtual double* GetSelectionBackgroundColor();
00347   virtual void SetSelectionBackgroundColor(double r, double g, double b);
00348   virtual void SetSelectionBackgroundColor(double rgb[3])
00349     { this->SetSelectionBackgroundColor(rgb[0], rgb[1], rgb[2]); };
00350   virtual void GetSelectionForegroundColor(double *r, double *g, double *b);
00351   virtual double* GetSelectionForegroundColor();
00352   virtual void SetSelectionForegroundColor(double r, double g, double b);
00353   virtual void SetSelectionForegroundColor(double rgb[3])
00354     { this->SetSelectionForegroundColor(rgb[0], rgb[1], rgb[2]); };
00355   
00356   // Description:
00357   // Specifies a command to associate with the widget. This command is 
00358   // typically invoked when the user opens a node.
00359   // The 'object' argument is the object that will have the method called on
00360   // it. The 'method' argument is the name of the method to be called and any
00361   // arguments in string form. If the object is NULL, the method is still
00362   // evaluated as a simple command. 
00363   // The following parameters are also passed to the command:
00364   // - path to the opened node: const char*
00365   virtual void SetOpenCommand(vtkObject *object, const char *method);
00366 
00367   // Description:
00368   // Specifies a command to associate with the widget. This command is 
00369   // typically invoked when the user closes a node.
00370   // The 'object' argument is the object that will have the method called on
00371   // it. The 'method' argument is the name of the method to be called and any
00372   // arguments in string form. If the object is NULL, the method is still
00373   // evaluated as a simple command. 
00374   // The following parameters are also passed to the command:
00375   // - path to the closed node: const char*
00376   virtual void SetCloseCommand(vtkObject *object, const char *method);
00377   
00378   // Description:
00379   // Set/add/remove a binding to a widget, i.e. the command that is invoked
00380   // whenever the 'event' is triggered on the widget.
00381   // SetBinding will replace any old bindings, whereas AddBinding will
00382   // add the binding to the list of bindings already defined for that event.
00383   // RemoveBinding can remove a specific binding or all bindings for an event.
00384   // The 'object' argument is the object that will have the method called on
00385   // it. The 'method' argument is the name of the method to be called and any
00386   // arguments in string form. If the object is NULL, the method is still
00387   // evaluated as a simple command. 
00388   virtual void SetBinding(
00389     const char *event, vtkObject *object, const char *method);
00390   virtual void SetBinding(
00391     const char *event, const char *command);
00392   virtual void AddBinding(
00393     const char *event, vtkObject *object, const char *method);
00394   virtual void AddBinding(
00395     const char *event, const char *command);
00396   virtual void RemoveBinding(const char *event);
00397   virtual void RemoveBinding(
00398     const char *event, vtkObject *object, const char *method);
00399 
00400   // Description:
00401   // Specifies a command to execute whenever the event sequence given 
00402   // by 'event' occurs on the label of a node. 
00403   // The 'object' argument is the object that will have the method called on
00404   // it. The 'method' argument is the name of the method to be called and any
00405   // arguments in string form. If the object is NULL, the method is still
00406   // evaluated as a simple command. 
00407   // The following parameters are also passed to the command:
00408   // - path to the node for which the event occured: const char*
00409   virtual void SetBindText(
00410     const char *event, vtkObject *object, const char *method);
00411 
00412   // Description:
00413   // Set the command for single/double/right click on a node. This, 
00414   // in turn, just calls SetBindText.
00415   // WARNING: SetSingleClickOnNodeCommand will override the default behaviour
00416   // that selects a node when it is clicked on. It is therefore up to the
00417   // user to select the node if needed.
00418   // The 'object' argument is the object that will have the method called on
00419   // it. The 'method' argument is the name of the method to be called and any
00420   // arguments in string form. If the object is NULL, the method is still
00421   // evaluated as a simple command. 
00422   // The following parameters are also passed to the command:
00423   // - path to the node for which the event occured: const char*
00424   virtual void SetDoubleClickOnNodeCommand(
00425     vtkObject *object, const char *method);
00426   virtual void SetSingleClickOnNodeCommand(
00427     vtkObject *object, const char *method);
00428   virtual void SetRightClickOnNodeCommand(
00429     vtkObject *object, const char *method);
00430   
00431   // Description:
00432   // Specifies a command to associate with the widget. This command is 
00433   // typically invoked when the selection changes.
00434   // The 'object' argument is the object that will have the method called on
00435   // it. The 'method' argument is the name of the method to be called and any
00436   // arguments in string form. If the object is NULL, the method is still
00437   // evaluated as a simple command. 
00438   virtual void SetSelectionChangedCommand(
00439     vtkObject *object, const char *method);
00440   
00441   // Description:
00442   // Specifies a command to associate with the widget. This command is 
00443   // typically invoked when a node is reparented interactively.
00444   // The 'object' argument is the object that will have the method called on
00445   // it. The 'method' argument is the name of the method to be called and any
00446   // arguments in string form. If the object is NULL, the method is still
00447   // evaluated as a simple command. 
00448   // The following parameters are also passed to the command:
00449   // - path to the node that was reparented: const char*
00450   // - path to the node's new parent: const char*
00451   // - path to the node's previous parent: const char*
00452   virtual void SetNodeParentChangedCommand(
00453     vtkObject *object, const char *method);
00454   
00455   // Description:
00456   // Events. The SelectionChangedEvent is triggered when the selection is
00457   // changed (i.e. one or more node(s) are selected/deselected).
00458   // It is  similar in concept as the 'SelectionChangedCommand' but can be
00459   // used by multiple listeners/observers at a time.
00460   // The RightClickOnNodeEvent event is triggered when right-clicking on
00461   // a specific node.
00462   // The following parameters are also passed as client data for 
00463   // RightClickOnNodeEvent:
00464   // - path to the node: const char*
00465   // The following parameters are also passed as client data for 
00466   // NodeParentChangedEvent:
00467   // - path to the node that was reparented: const char*
00468   // - path to the node's new parent: const char*
00469   // - path to the node's previous parent: const char*
00470   //BTX
00471   enum
00472   {
00473     SelectionChangedEvent = 10000,
00474     RightClickOnNodeEvent,
00475     NodeParentChangedEvent
00476   };
00477   //ETX
00478 
00479   // Description:
00480   // Update the "enable" state of the object and its internal parts.
00481   // Depending on different Ivars (this->Enabled, the application's 
00482   // Limited Edition Mode, etc.), the "enable" state of the object is updated
00483   // and propagated to its internal parts/subwidgets. This will, for example,
00484   // enable/disable parts of the widget UI, enable/disable the visibility
00485   // of 3D widgets, etc.
00486   virtual void UpdateEnableState();
00487 
00488   // Description:
00489   // Specifies if the node text should be stored in a raw format, i.e. 
00490   // without converting from the application's CharacterEncoding to the
00491   // internal Tcl/Tk encoding. Off by default.
00492   vtkBooleanMacro(UseRawNodeText, int);
00493   vtkGetMacro(UseRawNodeText, int);
00494   vtkSetMacro(UseRawNodeText, int);
00495 
00496   // Description:
00497   // Specifies if the node user data should be stored in a raw format, i.e. 
00498   // without converting from the application's CharacterEncoding to the
00499   // internal Tcl/Tk encoding. Off by default.
00500   vtkBooleanMacro(UseRawNodeUserData, int);
00501   vtkGetMacro(UseRawNodeUserData, int);
00502   vtkSetMacro(UseRawNodeUserData, int);
00503 
00504   // Description:
00505   // Set focus to this widget.
00506   virtual void Focus();
00507   virtual int HasFocus();
00508 
00509   // Description:
00510   // Callbacks. Internal, do not use.
00511   virtual void SelectionCallback();
00512   virtual void RightClickOnNodeCallback(const char *node);
00513   virtual void KeyNavigationCallback(const char* key);
00514   virtual void DropOverNodeCallback(const char*, const char*, const char*, const char*, const char*, const char*);
00515 
00516   // Description:
00517   // Automatically scroll the window to show most, if not all, 
00518   // sub-directories of the given node
00519   virtual void DisplayChildNodes(const char* node);
00520 
00521 protected:
00522   vtkKWTree();
00523   ~vtkKWTree();
00524 
00525   // Description:
00526   // Create the widget.
00527   virtual void CreateWidget();
00528   
00529   int SelectionMode;
00530   int EnableReparenting;
00531   int UseRawNodeUserData;
00532   int UseRawNodeText;
00533 
00534   char *SelectionChangedCommand;
00535   virtual void InvokeSelectionChangedCommand();
00536   
00537   char *NodeParentChangedCommand;
00538   virtual void InvokeNodeParentChangedCommand(
00539     const char *node, const char *new_parent, const char *previous_parent);
00540 
00541   virtual void UpdateDragAndDrop();
00542 
00543   // PIMPL Encapsulation for STL containers
00544   //BTX
00545   vtkKWTreeInternals *Internals;
00546   //ETX
00547 
00548 private:
00549   vtkKWTree(const vtkKWTree&); // Not implemented
00550   void operator=(const vtkKWTree&); // Not implemented
00551 };
00552 
00553 #endif

Generated on Sat Dec 11 2010 02:08:01 for KWWidgets by  doxygen 1.7.2