DragonFly On-Line Manual Pages
geomap::igeomap(n) Tk Extensions tkgeomap geomap::igeomap(n)
See the file man.macros.
NAME
igeomap - create and manipulate a geographic map with interactive menus
and bindings.
SYNOPSIS
package require tkgeomap_procs ?2?
geomap::igeomap namespaceName pathName ?options?
DESCRIPTION
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.
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.
-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.
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
The geomap::igeomap command is part of the tkgeomap_procs package,
which is defined in file tkgeomap_procs.tcl of the tkgeomap
installation.
SEE ALSO
tkgeomap (n)
AUTHOR
Gordon Carrie, user0@tkgeomap.org
Tk 2 geomap::igeomap(n)