DragonFly On-Line Manual Pages
geomap::wdgeomap(n) Tk Extensions tkgeomap geomap::wdgeomap(n)
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
SEE ALSO
tclgeomap (n)
tkgeomap (n)
AUTHOR
Gordon Carrie, user0@tkgeomap.org
Tk 2 geomap::wdgeomap(n)