visky

visky − an application that draws maps with weather data and instrument information.

2.2.3

The visky application generates maps which can display weather data and information about field instruments. It is written in Tool Command Language (TCL), and can be augmented with TCL packages, as described in the package (n) man page. This man page provides information to authors of such packages. Application users should read the user man page, visky (n).

At startup, visky searches the system for TCL packages whose names match glob pattern "visky_*" and adds them, without the "visky_" prefix to the File->Package menu. Users control visky’s optional behavior with this menu. When a visky optional package loads, it usually adds menus and widgets to application windows. The package must collect its procedures and variables in a namespace with the same name as the package. It should not modify procedures or variables in other namespaces, unless allowed to by a well defined, documented interface.

Visky creates one or more wdgeomap’s (widget geographic maps). A wdgeomap is a canvas containing a geographic map and associated menus and bindings. Wdgeomaps are created and managed by procedures in the wdgeomap package, as described in wdgeomap (n). Typical visky package procedures take a wdgeomap map identifier as an argument and pass it to wdgeomap procedures that create map canvas items, menus and bindings. Packages should keep track of their items and menus with tags and item id’s. They should modify and apply bindings only to their own items and widgets.

Each wdgeomap canvas can also have embedded canvas’s that show vertical profiles, called slices. There are two slices. One at the top of the map shows longitude-z plots, another at the left side shows latitude-z plots. The slice canvas’s are children of the map canvas and are displayed as canvas window items. User can control whether or not they are visible. See the VERTICAL SLICES section for discussion of how to add and manage items in these canvas’s.

The namespace for an optional visky package must contain the following procedures:

visky_pkgName::setmap map

This procedure will be called to initialize items and menus in map, which identifies a wdgeomap created by visky. This procedure is called automatically when a map is added to the display. The package should also call this procedure for all maps in the maps list when the package loads itself. This is not done automatically.

visky_pkgName::forget

This procedure is called when the user requests package removal, and when the application exits. The forget procedure should perform any necessary clean up, such as erasing items, deleting menus, and removing layers from all maps in the maps list, deleting map namespace procedures, deleting namespaces created by the package, and storing configuration information in param_dir.

The visky program defines a namespace named ::visky. The following procedures access and manage information in this namespace.

visky::maps

This procedure returns a list of currently displayed maps. Visky creates a map at startup. The user can request additional maps with the ’File->Add map’ menu selection. Each element is in the returned list a map identifier that can be given as an argument to wdgeomap procedures, which are described in the wdgeomap (n) man page.

visky::param_dir

This procedure returns the name of a directory where information is stored between sessions. If packages store information between sessions, they should put it in files in this directory. They should read these files when they load, and update them when they unload or when visky exits.

visky::map_id toplev

Returns the identifier for the map in toplevel window toplev.

visky::init_color map elem deflt

Initializes a color element in the map. If element elem has an entry in the ::visky::colorval array, the entry is used. If not, deflt is used.

visky::save_color elem value

This procedure sets ::visky::colorval(elem) to value. This value becomes the default color value for the element elem in future new maps. The colorval array is written to param_dir/colors file at exit for use as the default in future sessions. If value is "", the value is forgotten.

visky::add_update map name script

Arranges for script to be evaluated when the map changes its reference point, projection, scale, or orientation. script should update parts of the display that depend on map properties. For example, it could update labels, or remove items that would clutter a small scale map. name is used to refer to the script later. If add_update has already been called with name, script replaces the previous script value. This procedure has the same purpose as the ::geomap::wdgeomap::configure -update command. Packages should use ::visky::add_update so that packages do not clobber each other’s update tasks.

visky::rm_update map name

Removes a script added with a call to add_update. name should be the value given to add_update.

visky::add_cursor_update type script

Arranges for script to be evaluated whenever the cursor moves in a map or slice. type identifies where the cursor motion should occur. If type is map, script will be run when the cursor moves on the map. It will be appended with the cursor {latitude longitude} before evaluation. If type is lat_z, script will be run when the cursor moves on the latitude-z canvas. It will be appended with the cursor {latitude z} before evaluation. If type is lon_z, script will be run when the cursor moves on the longitude-z canvas. It will be appended with the cursor {longitude z} before evaluation. In all cases, script is appended with "" if cursor moves in a region where its geographic or slice coordinates are undefined. script should perform tasks that depend on cursor location, such as displaying distance and direction to an instrument , or the value of a field at the cursor location. The callback is deleted it fails, e.g. if script calls a procedure that no longer exists.

visky::set_plus map {lat lon}

Each map displays a plus marker that allows the user to mark points of interest and measure distances and directions, see visky (n). The set_plus procedure moves this marker to position {lat lon} in map. The current plus marker location is printed to standard output.

visky::set_poly map {lat lon}

Each map can display a polygon. It always terminates at the plus marker. This procedure adds a segment from the plus marker in map to {lat lon}, and then moves the plus marker to {lat lon}. The points in the resulting polygon in map are printed to standard output. The polygon is reset with a call to visky::set_plus.

The following procedures help create plots in which one axis follows a latitude circle or meridian, and the other axis is can be anything, such as height or a function that varies with latitude or longitude.

visky::lon_z_canvas map

Returns the path name of the canvas with the longitude-z display in map.

visky::lat_z_canvas map

Returns the path name of the canvas with the latitude-z display in map.

visky::set_slice_params map params

Modifies the slice displays in map. params is an array of new parameters. The following elements are recognized:
params(lat) - sets a new reference latitude for the longitude-z display. In the longitude-z display (at the top of the map canvas), the horizontal coordinate will be longitudes along the latitude circle at lat. The vertical coordinate will be height.
params(lon) - sets a new reference longitude for the latitude-z display. In the latitude-z display (at the left side of the map canvas), the vertical coordinate will be latitudes along the meridian at lon. The horizontal coordinate will be height.
params(z1) - sets the lower height coordinate in both slice displays.
params(z2) - sets the upper height coordinate in both slice displays.
params(size) - sets the canvas height of the longitude-z display and the canvas width of the latitude-z display.
params(borderwidth) - sets the width of the canvas border for both slice displays.
params(visibl) - if true, the slice displays will be visible. If false, they will be hidden. The canvas windows for the slice displays will still exist, and canvas items can be created and managed in them, but they will not be visible as window items in the map canvas.

visky::add_slices_update_script map script

Arranges for script to run whenever ::visky::set_slice_params is run for map.

visky::get_slice_params map params

Puts all of the parameters defined for visky::set_slice_params as applied to map into an array named params.

visky::lon_z_to_cvs map lon1 z1 ?lon2 z2 ...?

Converts longitude-height coordinates in the longitude-z canvas to canvas coordinates. Return value will be a list giving canvas coordinates in the longitude-z canvas in form {x1 y1 x2 y2 ...}.

visky::cvs_to_lon_z map x1 y1 ?x2 y2 ...?

Converts canvas coordinates in the longitude-z canvas to longitude-z coordinates. Return value will be a list giving longitude-z coordinates in form {lon1 z1 lon2 z2 ...}.

visky::lat_z_to_cvs map args

Converts latitude-height coordinates in the latitude-z canvas to canvas coordinates. Return value will be a list giving canvas coordinates in the latitude-z canvas in form {x1 y1 x2 y2 ...}.

visky::cvs_to_lat_z map args

Converts canvas coordinates in the latitude-z canvas to latitude-z coordinates. Return value will be a list giving latitude-z coordinates in form {lat1 z1 lat2 z2 ...}.

Visky uses the wdgeomap layer mechanism to control the stacking order of canvas items. Layer tags obtained with a call to geomap::wdgeomap::get_layers are displayed in a dialog that the user calls with the Map->Layers menu. As the user drags items in this dialog, visky calls geomap::wdgeomap::set_layers to adjust the layer sequences to match the sequence shown in the dialog. Packages should use layer tags and the wdgeomap layer management procedures to manage their items. They should remove their layers with calls to geomap::wdgeomap::rm_layer when they unload. They do not have to remove their layers when the application exits. Visky saves default sequences between sessions. See the wdgeomap (n) man page for discussion off layer management procedures.

The visky user interface supports a help facility which displays tutorial information in a text widget - the help window - which is part of the main window. The text in the help window is updated when the cursor enters certain windows and canvas items. The following procedures access the help facility:

visky::set_win_help win str

Arranges for str to be displayed in the help window when help is enabled and the cursor enters window win. The application runs str through the Tcl subst command, allowing for substitution of variable names in the string with current values. It also replaces instances of more than one space or tab with a single space. If str is "", the help window is not updated. In other words, win no longer interacts with the help facility. This is done automatically when win is destroyed.

visky::set_cvs_help cvs tagOrId str

Arranges for str to be displayed in the help window when help is enabled and the cursor enters item identified with tagOrId in canvas cvs. The application runs str through the Tcl subst command, allowing for substitution of variable names in the string with current values. It also replaces instances of more than one space or tab with a single space. If str is "", the help window is not updated. In other words, the item no longer interacts with the help facility. This should be done if the item is deleted from the map, it is not done automatically.

visky::set_menu_help menu str_arr

This procedure adds a menu to the help facility. menu must be the path name of a menu. str_arr must be the name of an array which maps menu selection labels to help strings. When help is active, and the menu is active, moving the cursor over a menu selection displays the string from str_arr associated with the selection label in the help window. The application runs str through the Tcl subst command, allowing for substitution of variable names in the string with current values. It also replaces instances of more than one space or tab with a single space. This is done automatically when menu is destroyed.

Gordon Carrie <user0@tkgeomap.org>