See the file man.macros.

NAME

wdgeomap - create and manipulate a geographic map with interactive menus and bindings.

SYNOPSIS

package require wdgeomap ?2?
geomap::wdgeomap::create mapName pathName ?options?

DESCRIPTION

The geomap::wdgeomap procedure creates a frame named pathName, which contains a canvas with a geographic map and associated menus. When the geomap::wdgeomap procedure is called, pathName should not exist, although its parent should. The wdgeomap procedure packs the contents of frame pathName, but it does not submit it to any geometry manager. The application that creates the wdgeomap should eventually make the frame visible using Tk geometry management commands, such as pack, place, or grid. The mapName argument identifies the widgets and associated data in the procedures described below. These procedures create and manage geomap_lnarr and geomap_place items in the canvas. These items display information at geographic locations, as described in the tkgeomap (n) man page. The resulting items receive the same -refpoint, -projection, -scale, and -rotation configuration options so that the items are on the same map in the canvas, and they are updated automatically when the map's cartographic properties change. This is more convenient than configuring each canvas item separately. There are also procedures that create and manage menus and bindings that make the map interactive.

The geomap::wdgeomap::create procedure accepts additional option value pairs which initialize the map and canvas configuration. These option value pairs are passed to the 'geomap::wdgeomap::configure mapName' procedure, described below.

DEFAULT MENUS

Unless configured otherwise, a wdgeomap widget will have the following menus in its menu bar. Menus can be managed with the addmenu, getmenu, and deletemenu procedures described below.

File: Contains selections that affect the map or application as a whole. Default selections are:

Postscript: Exports the map to a postscript file. A dialog box prompts the user for a file name and color mode. The dialog box is given a wdgeomap_ps_dlg bindtag for subsequent access.
Quit: Exits the application.

Projection: Selects the cartographic projection.
Scale: Selects the cartographic scale.
Top: Specifies which compass direction is up.

COMMANDS

geomap::wdgeomap::map_canvas mapName: Returns the path of canvas in which the map is drawn.
geomap::wdgeomap::mbar mapName: Returns the path of menu bar.
geomap::wdgeomap::configure mapName option value ?option value ...?: This procedure specifies the cartographic properties of the map and configures associated items in the canvas. If a given option is not in the list below, the procedure applies it to the canvas configuration. If option is not a valid canvas configuration option either, the procedure raises an error. The following options are recognized.

-refpoint {lat lon}: Sets the map center to point {lat lon}. Default value is {0.0 0.0}.
-projname name: Specifies the type of map projection. name should identify a projection from the list returned by the geomap::projections command. Unlike the geomap::projection command, this option does not require any projection parameters. If the projection requires a reference point, such as Orthographic and Lambert Conformal Conic, the lat-lon at the center of the map is used. If the projection requires a reference longitude, such as Mercator, the longitude at the center of the map is used. Projections that require a hemisphere specification, such as Polar Stereographic, use whichever hemisphere contains the map center. Use the geomap::proj_info procedure in tclgeomap_procs package to identify the type of reference, either longitude or point, for each projection. The default value for the -projname option is Mercator.
-scale scale: Specifies the cartographic scale of the map. The value can be a floating point number or a cartographic scale (e.g. 1:30000000). Default value is 1.0e-7.
-rotation rotation: Specifies the map's orientation. The rotation should be a value known to the -rotation option described in the tkgeomap (n) man page. Default value is 0.0.
-update script: Specifies a script to evaluate whenever the -refpoint, -projection, -scale, or -rotation option is changed. This makes it possible to update labels and legends around the map, add or remove items as the scale changes, and perform any other tasks that depend on the map's cartographic characteristics. script is evaluated at global scope. Default value is {}.
-boundcirclecolor color: Specifies the color of the bounding circle for hemispheric projections. Default value is Black.
-lazy boolean: Deletes certain bindings associated with the -projname option. This option should be set to true if the widget appears to be wasting time modifying the map projection without changing the map appearance. This often happens when the map is zoomed in most of the time. Value should be a Boolean. Default value is 0 (false).
-colormenu boolean: Determines whether the File menu will have a Colors selection. This selection creates a dialog in which the user interactively selects colors for map elements whose colors have been specified by the setcolor procedure described below. The dialog box will have a button for each such map element. When the user presses one of these buttons, a color selection dialog will appear. If the user selects a color and clicks OK in the color selection dialog, the application will update the elements color with a call to setcolor. The actual update tasks should be performed by a script assigned to the element with a call to the setcolorscript procedure. The Save button saves color values currently in the dialog to a file identified by the user. The Load button retrieves values from a file created with the Save button. The Undo button retrieves previous color configurations. If the -colormenu configuration option is set to true, the application should use the setcolor and setcolorscript procedures to manage all colors in the map. This will allow the user to modify colors conveniently in one place. The color values and scripts that use them will depend on what data the map displays and how it is imported. When the the dialog box is created, a call to bindtags adds a tag named wdgeomap_color_dlg to its toplevel. This allows applications to add bindings to it, such as context sensitive help.
-layermenu boolean: Determines whether the File menu will have a Layers selection. This selection creates a dialog in which the user can adjust the stacking order of certain canvas items by dragging rectangles representing canvas tags. Items without tags listed in the dialog move to the bottom of the stacking order. Tags can be added to and removed from this dialog with the map add_layer and rm_layer procedures, described below. When the the dialog box is created, a call to bindtags adds a tag named wdgeomap_layer_dlg to its toplevel. This allows applications to add bindings to it, such as context sensitive help.
-projections projectionList: Lists the projection names in the Projections menu. Selecting a projection from the menu sets the -projname option to that projection. Default value is {CylEqDist Mercator CylEqArea LambertConfConic LambertEqArea Stereographic PolarStereographic Orthographic}. If value is {}, the Projections menu is not displayed.
-scales scaleList: Lists the scales in the Scales menu at the top of the map. Selecting a scale from the menu sets the -scale option to that scale. Default value is {1:10000000 1:20000000 1:30000000 1:45000000 1:60000000 1:90000000 1:120000000}. If value is {}, the Scales menu is not displayed.
-rotationmenu boolean: Specifies whether or not the Top menu should be displayed. Selecting a direction from the menu sets the -rotation option so that the chosen direction is at the top of the map. Value should be a Boolean. Default value is 1.

geomap::wdgeomap::cget mapName option: Retrieves a value from the map configuration. option can be one of the options known to the configure procedure, or a canvas option.
geomap::wdgeomap::draw mapName type name ?option value ...?: This procedure creates or modifies a map item in the canvas. type identifies the item type, which must be either geomap_lnarr or geomap_place. name identifies the linearray or place displayed in the item. It should be the name of a linearray or place command returned by the geomap::lnarr or geomap::place command. See the tclgeomap (n) man page for more information on linearrays and places. If the command for the linearray or place is in a non-global namespace, name MUST BE FULLY QUALIFIED. If type and name refer to an already existing item, the item is modified. Otherwise, a new item is created. Item options that define the geographic map, specifically -refpoint, -projection, -rotation, and -scale, will be obtained from the map object. Other options that affect the item's appearance can be given in the option value list. See tkgeomap (n) man page for discussion of recognized options. Any options in the option value list that define the geographic map will be ignored. In addition to any tags specified in the option list, the item will have the following tags: name, and geomap. These tags help identify the item in other procedures and configuration tasks. If the map manages layers, the application should call set_layers after drawing a new line or place. See below for discussion of layer management. This procedure returns the item identifier for the new or modified item.
geomap::wdgeomap::erase mapName type name: Deletes an item created by the draw procedure. type and name should be as given to the draw procedure.
geomap::wdgeomap::setcolor mapName element color: Associates a color with a map element. The element should identify map items that share a color, e.g. water, land, places, etc. The color should be intelligible to Tk_GetColor. After the color for the element is set, a script specified with a call to setcolorscript is invoked. This script should draw or configure the affected map elements using color.
geomap::wdgeomap::setcolorscript mapName element script: Specifies a script to run when the color associated with element is changed with a call to setcolor.
geomap::wdgeomap::getcolor mapName element: Returns the color value specified in the last call to setcolor for element, or "" if their is no color for the element.
geomap::wdgeomap::add_layer mapName layer: Adds a layer to the map layer hierarchy, if the layer is not already present. If layer is already in the hierarchy, due to an earlier call to add_layer, this procedure does nothing. Once layer has been added, the File->Layers dialog can manipulate the stacking order of map canvas items with tag layer. Layers can be arranged in a hierarchy. A list element in layer denotes a separate level in the map hierarchy. The element before a list element identifies a parent. Subsequent elements denote a child or hierarchy of children. If several hierarchical levels of layers are present, the dialog will show them in a tree diagram. Each path through the tree is one layer. All children of an item move with the item. An item can only be moved relative to its siblings (other children of its parent). An application should call set_layers after calling add_layer and before the display is updated for the new stacking order to take effect in the display.
geomap::wdgeomap::rm_layer mapName layer: Removes tag layer from the list of layers managed by the File->Layers dialog. Canvas items with tag layer will still exist, but the File->Layers dialog will no longer control their stacking order. An application should call set_layers after calling rm_layer and before the display is updated for the new stacking order to take effect in the display.
geomap::wdgeomap::set_layers mapName: Puts items with layer related tags into their stacking order. The set_layers call does not have to be immediate. For example, it may be more efficient to create a set of items in a loop and then stack them with a single call to set_layers after the loop. Applications should call set_layers after creating canvas items with the canvas create subcommand, drawing geomap_lnarr or geomap_place items with the wdgeomap draw subcommand, or modifying the layer sequence with the wdgeomap add_layer or rm_layer subcommands.
geomap::wdgeomap::xytolatlon mapName ?-catch? x y ?x y ...?: Returns the geographic coordinates corresponding to one or more pairs of canvas coordinates in the canvas. If the -catch option is present, points for which the conversion is not defined are skipped. Otherwise, an attempt to make an undefined conversion results in an error. Return value is a list of form {{lat1 lon1} {lat2 lon2} ...}, in which each {lat lon} corresponds to an "x y" pair in the input list.
geomap::wdgeomap::latlontoxy mapName ?-catch? {lat1 lon1} ?{lat2 lon2} ...?: Returns a list of canvas coordinates in the canvas corresponding to one or more pairs of geographic coordinates. If the -catch option is present, points for which the conversion is not defined are skipped. Otherwise, an attempt to make an undefined conversion results in an error. Return value is a list of form {x1 y1 x2 y2 ...} in which each "x y" pair corresponds to a {lat lon} in the input list.
geomap::wdgeomap::addmenu mapName name: Adds a menu to mapName's menu bar. This method will create a menu button named name and associated menu. Return value is the path name of the associated menu, which user can then modify as described in the menu (n) man page.
geomap::wdgeomap::getmenu mapName name: Retrieves the path name of the menu button created by addmenu for name.
geomap::wdgeomap::deletemenu mapName name: Deletes a menu created with the addmenu method. The menu button and associated menu will be destroyed.
geomap::wdgeomap::delete mapName: Deletes the map widget, and all associated data.
geomap::wdgeomap::set_motion_bindings modifier button: This procedure applies bindings that allow the user to move a map with the mouse. The type of mouse motion required to move the map depends on the projection. If the projection uses a reference point, like Lamber Conformal Conic, double-clicking selects a new projection reference point and map center. If the projection uses a reference longitude, the map can be moved by dragging. When the mouse is released after dragging, the final longitude at the center of the map becomes the projection reference longitude, unless the -lazy option is set. modifier specifies an additional key to press while moving the map with the mouse. It should be one of "", Alt, Control, or Shift. A non-empty modifier can help prevent spurious map motion. button specifies the mouse button to push while moving the map. It should be 1, 2, or 3.
geomap::wdgeomap::get_motion_bindings: This query procedure returns a list of bindings that move map items created with the draw procedure.

FILES

wdgeomap.tcl

AUTHOR

Gordon Carrie, user0@tkgeomap.org