
Welcome to the TclTkGRASS!                      22. December 1999

The programming of new modules within the TCLTKGRASS environment
is quite easy now.

1. Adding a module window into TCLTKGRASS

   To add a module into the TCLTKGRASS windows environment
   you have to edit
       main/menu.tcl
   
   The structure is as follows:
    
1.a) Menu with submenu:

   <Menuentry> {
     "<Submenu entry 1> {
         "source $env(TCLTKGRASSBASE)/module/<module.definitionfile>"
         }
     "<Submenu entry 2> {
         "source $env(TCLTKGRASSBASE)/module/<module.definitionfile>"
         }
   } 

1.b) Simple Submenu
    "<Submenu entry 1> {
         "source $env(TCLTKGRASSBASE)/module/<module.definitionfile>"
         }

1.c) Direct module call (if the module has to used interactively)
    "<Submenu entry 1> {
         "exec xterm -exec <grassmodule>"
         }


Example:

     "Misc tools" {
            "Convert raster to lines from a thinned raster" {
                "source $env(TCLTKGRASSBASE)/module/r.line"
            }
            "Vector digitizer" {
                "exec xterm -exec v.digit"
            }



2. Programming the module window itself (the module.definitionfile)

2.a) Programming of non-interactive module windows

Here a listing of the entries follows (the braces are important, but do not
insert "<" and ">" !). See an example below.

First entry:
  interface_build {
Second entry:
  {<grass module name>} 
Third entry (interactive flag):
      1 <if data must be input interactively from terminal (xterm),> 
<or>  0 <...else (for setting paramters through module menu)>
Fourth entry:
  {<Comment to be displayed in first module windows line>.}
Fifth to xxx line: query for variables:
  {entry <module variable> {<Comment for this variable>:} 0 <button>}
Fifth to xxx line: checkboxes for options:
  {checkbox <module option> {<Comment for this option>.} "" <module option>}
Last line:
  }

Module variables have to be specified for input and output files.
Module options allow for example to run this module quietly, or output 
special information in a tcltkgrass window etc. 
The "interactive flag" indicates if the module will be directed through
the window entries or through a xterm (see description and example below).
You get all required information about a specific GRASS module 
from the GRASS man pages, if you want to define the module yourself.

The <button> may be:
 raster:     query GRASS raster map
 +raster:    query several GRASS raster maps (for multiple input separated 
               with comma
 vector:     query GRASS vector map
 +vector:    query several GRASS vector maps (for multiple input separated 
               with comma
 sites:      query GRASS site file
 +sites:     query several GRASS sites maps (for multiple input separated 
               with comma
 file:       choose file for reading from user's home directory
 File:       choose file for writing from user's home directory
 xy:         pick x,y coordinates on the active monitor window
 xyz.<map>:  pick x,y coordinates on the active monitor window
                + z value for the raster map whose name is in variable <map>
                (compare d.3d)
 "":         no query button
 arc:        choose ARC/INFO file in <location>/<mapset>/arc
 area:       choose area unit
 color:      choose a color from a list (for display commands)
 Color:      choose a color from a list including color "none" in the list
 3Dcolor:    choose a color from a list including color "color" in the list
                 (only used in d.3d)
 distance:   choose distance unit (km, m, etc.)
 dlg:        choose dlg file
 dlg_ascii:  choose dlg ascii file
 font:       choose font
 group:      choose image group
 subgroup:   choose image subgroup
 signature:  choose signature file from subgroup
 icon:       choose paint icon file
 label:      choose paint label file
 paint:      choose painter device
 monitor:    choose monitor
 region:     choose region definition file
 spheroid:   choose spheroid

...some more feature: see script/gui.tcl for details.


To create fields in the module window, you have three possibilities:
 - "entry": This is an empty line

    Generally:  {entry parameter {description:} 0 button} 
                                  (you may specify "" instead of button)
    Example:    {entry input {Input site map:} 0 sites}

 - "checkbox": Use this clickable box for flags
    Generally:  {checkbox flag {description} "" flag}
    Example:    {checkbox -h {Display reference information.} "" -h}

 - "scale": This displays a numbered adjust bar
    Generally:  {scale parameter {description} min max interval}
    Example:    {scale size {Neighborhood size:} 1 25 2}

The easiest way is to develop new module windows from
existing definitions.

Example:

interface_build {
    {s.surf.tps} 0
    {Interpolates and computes topographic analysis from site map using spline with tension.}
    {entry input {Input site map:} 0 sites}
    {entry elev {Output elevation raster map:} 0 raster}
    {entry slope {Output slope raster map (optional):} 0 raster}
    {entry aspect {Output aspect raster map (optional):} 0 raster}
    {entry pcurv {Output profile curvature raster map (optional):} 0 raster}
    {entry tcurv {Output tangential curvature raster map (optional):} 0 raster}
    {entry mcurv {Output mean curvature raster map (optional):} 0 raster}
    {entry maskmap {Use this existing raster file name as a mask (optional):} 0 raster}
    {entry dmin {Minimum distance between points (default: 0.5 grid cell):} 0 ""}
    {entry zmult {Multiplier for z-value in site map (default: 1):} 0 ""}
    {entry tension {Tension parameter (appropriate for smooth surfaces) (default: 40):} 0 ""}
    {entry smooth {Smoothing parameter (default: 0 = no smoothing:} 0 ""}
    {entry segmax {Maximum number of points per segment (default: 40):} 0 ""}
    {entry npmin {Minimum number of points for interpolation (default: 150, see man page):} 0 ""}
    {checkbox -h {Display reference information.} "" -h}
}


2.b) Speciality: The GRASS module shall be used interactively from xterm 

This will be achieved through "1" in the second line of the module
definition.

Example:

interface_build {
    {r.mapcalc} 1
    {Raster map layer data calculator.}
}

2.c) Speciality: Define standard options for GRASS modules

Some modules need options which the user should not be able to change.
You can enter a command name with several words in the second line of the
module.definitionfile. 

Example: v.support
interface_build {
    {v.support option=build} 0
    {(Re)Builds topology of vector file.}
    {entry map {Name of the GRASS vector file to be (re)build:} 0 vector}
    {entry threshold {Snap threshold value (valid only with -s option):} 0 ""}
    {checkbox -s {Snap nodes.} "" -s}
    {checkbox -r {Set map region from data.} "" -r}
}
 

The easiest way is to copy existing module.definitionfile and change
this copy to your purposes. Some more internal details are stored in 
the comments of script/gui.tcl.

So, we hope to receive new module window files from you for the 
integration into TCLTKGRASS...

Have fun with this new concept!


   Jacques Bouchard (bouchard@onera.fr) (who did all this programming work!)
   Markus Neteler (neteler@geog.uni-hannover.de) (who wrote texts and some
                                                  module files)
