VTK Tcl wrappers
===========================================================================

  I) Invoking the VTK package(s)
 II) Invoking additional packages
III) Installing the packages



=============================
  I) Invoking the VTK Tcl package(s)

Load the whole VTK API by issuing the following line before any
invocation of a VTK command (typically at the top of your Tcl script):

        package require vtk

This will load all VTK components and the corresponding
commands. Depending on how VTK was built, some components might not be
available (since Hybrid, Parallel, and Rendering can be
excluded).

VTK may also be used on a component-by-component basis by requiring
the component explicitly. Example:

        package require vtkrendering

The above line will resolve the dependencies and invoke (in that case)
the vtkgraphics and vtkimaging packages automatically (which will
trigger the vtkfiltering and vtkcommon packages too). This method can
be used to speed-up startup-time since only the required commands will
be loaded.



=============================
 II) Invoking additional packages


A) vtkinteraction
**************

The vtkinteraction package can be loaded to provide additional
interaction support.

        package require vtkinteraction

i) Tcl interactor: 

The vtkinteraction package creates a generic Tcl interactor inside a
console widget, allowing you to issue any Tcl commands while running
the script. Once the package is loaded, a hidden .vtkInteract widget
is created. Bind a key or set the user method of your
vtkRenderWindowInteractor to deiconify that widget:

        vtkRenderWindowInteractor iren
            [...]
            iren SetUserMethod {wm deiconify .vtkInteract}

Example: see Examples/GUI/Tcl/Mace.Tcl.


ii) 'vtkTkRenderWidget bindings':

The vtkinteraction package also brings a set of user-interaction
bindings for the vtkTkRenderWidget class. It allows you to use this Tk
widget in a way similar to the usual VTK interactor. Once the package
is loaded, call ::vtk::bind_tk_render_widget to associate the bindings
to the render widget:

        set ren [vtkTkRenderWidget .ren -width 300 -height 300 -rw renWin]
        ::vtk::bind_tk_render_widget $ren

Example: see Examples/GUI/Tcl/MaceTk.Tcl.


B) vtktesting
*************

Some developpers might load the vtktesting package to include
additional facilities.

        package require vtktesting

Once loaded, the package provides the functions usually located in the following files:

        backdrop.tcl
        colors.tcl
        mccases.tcl



=============================
 IV) Installing the package index file

A good description of the package and library facilities is given in
the Chapter 12 "Script, Libraries and Packages" (page 135) of
"Practical Programming in Tcl & Tk", Brent B. Welch, ISBN
0-13-616830-2.

When a package is "required" by the 'package' command (see part I to
III), the Tcl interpreter looks through a set of directories and their
subdirectories for pkgIndex.tcl files. It sources those to build an
internal database of packages (and version information).

A pkgIndex.tcl file is generated by this VTK distribution to provide
the packages described in the previous sections to the
interpreter. They will load the corresponding DLLs, set some default
behaviours/bindings/widgets and exit with an error message if the
package could not be provided (DLL not found, for example).

The package facility assume that Tcl libraries (and packages) are kept
in well-known directories (and their subdirectories). The list of
well-known directories is kept in the auto_path Tcl variable. It is
initialized by tclsh or wish to provide default directories, including
the default Tcl script library directory. For example :

Windows:
--------

% puts $auto_path
C:/devel/langages/tcl/8.3/lib/tcl8.3 C:/devel/langages/tcl/8.3/lib C:/devel/langages/tcl/8.3/lib/tk8.3

Linux/Unix:
--------

root [1003] ~/tmp# wish
% puts $auto_path
/usr/lib/tcl8.3 /usr/lib /usr/lib/tk8.3

Now let's see how we can make Tcl aware of the VTK Tcl packages. Tcl
provides a way for you to tell the Tcl interpreter to search for
pkgIndex.tcl files in any user-specified directory (and its
subdirectories). Just set the TCLLIBPATH environment variable to a set
of space-separated directories to search in (warning: Windows users
shall use '/' instead of '\').

If you have a VTK build tree on your hard disk, add Wrapping/Tcl to
TCLLIBPATH.  For example:

Windows:
--------

TCLLIBPATH=C:/Project/VTK-msvc6/Wrapping/Tcl/Debug

Now check auto_path :

% puts $auto_path
C:/Project/VTK-msvc6/Wrapping/Tcl/Debug C:/devel/langages/tcl/8.3/lib/tcl8.3 C:/devel/langages/tcl/8.3/lib C:/devel/langages/tcl/8.3/lib/tk8.3

Linux/Unix:
--------

root [1011] ~/tmp# export TCLLIBPATH=/home/myuser/VTK-gcc/Wrapping/Tcl
root [1012] ~/tmp# wish
% puts $auto_path
/home/myuser/VTK-gcc/Wrapping/Tcl /usr/lib/tcl8.3 /usr/lib /usr/lib/tk8.3

This shall do the trick :))
Sebastien BARRE (sebastien.barre@kitware.com)