Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages
geomap::igeomap(n) Tk Extensions tkgeomap geomap::igeomap(n)
See the file man.macros.

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

package require tkgeomap_procs ?2?
geomap::igeomap namespaceName pathName ?options?

The geomap::igeomap procedure creates a frame named pathName, which contains a canvas with a geographic map and associated menus. It also creates or modifies a namespace named namespaceName. When the geomap::igeomap procedure is called, pathName should not exist, although its parent should. Namespace namespaceName may already exist. If not, it will be created. The igeomap procedure packs the contents of frame pathName, but it does not submit it to any geometry manager. The application that creates the igeomap should eventually make the frame visible using Tk geometry management commands, such as pack, place, or grid.
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.

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.
-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. Array ::geomap::ProjRef maps projection names to projection reference, which is either longitude or point. 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 various map elements in the display. It assumes that map colors are set with two arrays in the map namespace: namespaceName::colorval and namespaceName::colorscript. These two arrays use the same set of indeces, which should identify map elements that share a color, e.g. water, land, places, etc. Array values in the namespaceName::colorval array are color values to use when displaying the map elements. They should be intelligible to Tk_GetColor. Array values in the namespaceName::colorscript array are scripts to run when the corresponding color changes. Usually they draw or configure the affected map elements. The dialog box will have a button for each map element represented in the colorval and colorscript arrays. 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 corresponding script from the colorscript array will be called. This script should redraw affected items with the chosen color. The Save button saves color values currently in the dialog to a file identified by the user. It adds or modifies a line in the selected file that starts with "Colors:" followed by the contents of the namespaceName::colorval array. The Load button retrieves values from a file created with the Save button. The Undo button retrieves previous color configurations. The path name of the color dialog will be stored in the color_dlg variable in the map namespace. If the -colormenu configuration option is set to true, the application should use the the colorval and colorscript arrays to manage all colors in the map. This will allow the user to modify colors conveniently in one place. The specific indeces and values in these arrays, and the manner in which they are set, will depend on what data the map displays and how it is imported.
-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 namespace insert_layer and rm_layer procedures, described below. The path name of the layer dialog will be stored in the layer_dlg variable in the map namespace.
-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.
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.
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.
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.

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.
This query procedure returns a list of bindings that move maps created with the geomap command.

The geomap::igeomap command is part of the tkgeomap_procs package, which is defined in file tkgeomap_procs.tcl of the tkgeomap installation.

tkgeomap (n)

Gordon Carrie,
2 Tk

Search for    or go to Top of page |  Section n |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.