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)