NAME

SYNOPSIS

DESCRIPTION

Namespace procedures described below 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. Items created with the namespace procedures 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.

Tasks not done by the namespace procedures can be done with widget commands, whose names are stored in namespace variables. namespaceNmae ::frame is the path name of the frame the holds the map canvas and menus, which was given as pathName in the initial call to geomap::igeomap. namespaceName::canvas is the path name of the canvas. namespaceName::mbar is the path name of the menu bar (a frame). namespaceName::toplevel is the path name of the toplevel widget that contains everything. Array member ::geomap::map_ns(toplevel_path) maps the toplevel widget name to the name of the map namespace.

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

NAMESPACE PROCEDURES

namespaceName::configure option value ?option value ...?

This procedure sets namespace variables that define 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.

namespaceName::cget option

Retrieves a value from the map configuration. option can be one of the options known to the configure procedure, or a canvas option.

namespaceName::draw 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 namespace. 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. This procedure returns the item identifier for the new or modified item.

namespaceName::erase type name

Deletes an item created by the draw command. type and name should be as given to the draw command.

namespaceName::insert_layer layer ?index?

Allows the File->Layers dialog to manipulate the stacking order of map canvas items with tag layer. Layers can be arranged in a hierarchy. A : in layer denotes a separate level in the map hierarchy. Text to the left of a : identifies a parent. Text to the right identifies 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). If present, index specifies where to put these items in the stacking order. index should specify a list index intelligible to the linsert command. A smaller value means the items are lower in the stacking order. Default is end (items with layer tag go on top).

namespaceName::rm_layer 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.

namespaceName::set_layers

Puts items with layer related tags into their stacking order. This procedure should be called whenever an item with a layer tag is created or drawn. 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. insert_layer and rm_layer call set_layers implicitly.

namespaceName::xytolatlon ?-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.

namespaceName::latlontoxy ?-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.

pathName addmenu name

Adds a menu to pathName'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.

deletemenu deletemenu name

Deletes a menu created with the addmenu method. The menu button and associated menu will be destroyed.

namespaceName::delete

Deletes the namespace, canvas, and all associated data. This procedure should be used instead of namespace delete or Tk's destroy command to delete a map created by the geomap::igeomap command.

OTHER PROCEDURES

geomap::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::get_motion_bindings

This query procedure returns a list of bindings that move maps created with the geomap command.

FILES

SEE ALSO

AUTHOR