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@itc.it) (who wrote texts and some
module files)