DragonFly On-Line Manual Pages
tkgeomap(n) Tk Extensions tkgeomap tkgeomap(n)
See the file man.macros.
NAME
tkgeomap - a package for displaying geographic lines and points in
canvas widgets.
VERSION
2
SYNOPSIS
package require tkgeomap ?2?
INTRODUCTION
The tkgeomap package adds two item types to the canvas widget. The
first type, geomap_lnarr displays a linearray, which is an anonymous
set of points created with the geomap::lnarr command. The other type,
geomap_place displays a named place created with the geomap::place
command. See the tclgeomap (n) man page for information on how to
create linearrays and places.
DEFINING A GEOGRAPHIC MAP FOR GEOMAP_LNARR AND GEOMAP_PLACE ITEMS
The map that contains a geomap_lnarr or geomap_place item is defined by
the item's coords and by its configuration. This section describes the
configuration options that define the map. geomap_lnarr and
geomap_place items have other type specific configuration options,
which are described in later sections. Items can be drawn on the same
map giving them the same map configuration. This is most easily done
by giving them a common tag and applying the map configuration to items
with that tag. Here are the configuration options that define a map.
-refpoint {lat lon}
This option specifies the reference point of the item, which is
the {lat lon} at the x, y coordinates given as the item's
coords. Note that the reference point is not necessarily the
location of the place in a geomap_place item, nor is it
necessarily a point on the linearray displayed in a geomap_lnarr
item. It only helps define the map in which the item is
displayed. Other lat-lon's are positioned relative to the
reference point. A map can be shifted by changing the reference
point with the -refpoint option, or by changing the item's
coordinates with the canvas coords or move command. A useful
convention is to keep all item coords at the center of the
canvas. Then the refpoint value is the lat-lon at the center of
the canvas, which is presumably a point of interest.
-projection projId
Specifies the geographic projection for converting {lat lon}
values to map coordinates. projId must be the name of a command
returned by the geomap::projection command. See the tclgeomap
man page for information on how to create and manipulate
projections. If no projection is specified, the item is not
drawn.
-rotation doubleValueORdirection
Specifies the map's orientation. A value of 0.0 or north means
the top of the map is north. A double value gives the number of
degrees the map is rotated clockwise from the conventional
north-is-up orientation. A value of north, nneast, neast,
eneast, east, eseast, seast, sseast, south, sswest, swest,
wswest, west, wnwest, nwest, or nnwest gives the direction at
the top of the map.
-scale doubleValue
Specifies the cartographic scale for converting distances on the
projection plane to distances on the printed or displayed map.
The actual canvas coordinates of a geomap_lnarr or geomap_place item
can be retrieved by adding the keyword dump to the coords command.
GEOMAP_LNARR ITEMS
Items of type geomap_lnarr display and allow users to interact with
arrays of geographic points, called linearrays, created with the
geomap::lnarr command. See the tclgeomap (n) man page for information
on how to create and manipulate linearrays. geomap_lnarr items can
display linearrays in three ways. First, the points can be connected
to make outlines. Second, the regions bounded by the points can be
filled with a solid color, assuming they are closed polygons. Third,
dots can be drawn at the points. The display method is determined by
the item configuration, described below.
geomap_lnarr items are created with widget commands of the following
form:
pathName create geomap_lnarr x y ?option value option value ...?
The options x and y give the canvas coordinates of the geomap_lnarr
item's reference point, which is defined in its configuration. (See
"DEFINING A GEOGRAPHIC MAP FOR GEOMAP_LNARR AND GEOMAP_PLACE ITEMS"
above). After the coordinates there may be any number of option-value
pairs, each of which sets one of the configuration options for the
item. These same option value pairs may be used in itemconfigure
widget commands to change the item's configuration.
COMMON CANVAS OPTIONS FOR GEOMAP_LNARR ITEMS
geomap_lnarr items support the following standard options. See the
canvas (n) man page for details.
-fill
-stipple
-outline
-tags
SPECIAL OPTIONS FOR GEOMAP_LNARR ITEMS
In addition to the map options and standard options described above,
geomap_lnarr items also recognize the following special options.
-lnarr arrayName
Specifies the name of a linearray to display in the item.
arrayName should be the name of a linearray, usually created by
the geomap::lnarr command. See the tclgeomap (n) man page for
information on how to create linearrays. When setting the
linearray to display, arrayName MUST BE FULLY QUALIFIED unless
the array command is global. If arrayName is an empty string,
no linearray will be displayed in the item. When this option is
used to retrieve the array name, such as with cget, only the
base name (without any :: namespace qualifiers) is returned. If
linearray arrayName is deleted, the item disappears from the
canvas, although the item continues to exist, and the value for
this option becomes an empty string.
-width outlineWidth
Specifies the width of lines to draw. outlineWidth can be a
coordinate specifier as described in the canvas (n) man page, or
it can be none, "", or a negative number to indicate no lines
should be drawn.
-linestyle style
Specifies a linestyle, either LineSolid or LineOnOffDash.
-dashes dashLength
Specifies the length of dashes it line style is LineOnOffDash.
-smooth boolean
Specifies whether to smooth the outline. boolean must have one
of the forms accepted by Tk_GetBoolean. Currently, only bezier
smoothing is available. If set, the line will be rendered as a
set of parabolic splines: one spline is drawn for the first and
second line segments, one for the second and third, and so on.
Straight-line segments can be generated within a curve by
duplicating the end-points of the desired line segment.
-splinesteps number
Specifies the degree of smoothness desired for curves: each
spline will be approximated with number line segments. This
option is ignored unless the -smooth option is true.
-shape polygonType
Tells the type of shape to be filled in when using the -fill
option. This option is usually unnecessary, but might improve
performance. Shape must be one of Convex, Nonconvex, or
Complex. Convex means any segment connecting two points on the
polygon does not cross the polygon. This type of shape can be
faster to draw. Nonconvex means the shape is not convex, but it
does not cross itself. Complex means the shape might cross
itself. Results are undefined if a shape is given as convex
when it is not, or nonconvex when it is complex. Note that the
assumption must apply for all projections used.
-dotsize number
Specifies size in pixels of dots to draw at the segment ends.
If number is greater than 0 and the -width and -fill options are
set to 0, the linearray will be displayed as a collection of
dots, which can be useful for making density plots or simple
images.
GEOMAP_PLACE ITEMS
Items of type geomap_place display and allow users to interact with
named geographic locations. See the tclgeomap (n) man page for
information on how to create and manipulate places. geomap_place items
can display dots, bitmaps, and text at given geographic locations.
geomap_place items are created with widget commands of the following
form:
pathName create geomap_place x y ?option value option value ...?
The options x and y give the canvas coordinates of the geomap_place
item's reference point, which is defined in its configuration. (See
"DEFINING A GEOGRAPHIC MAP FOR GEOMAP_LNARR AND GEOMAP_PLACE ITEMS"
above). After the coordinates there may be any number of option-value
pairs, each of which sets one of the configuration options for the
item. These same option value pairs may be used in itemconfigure
widget commands to change the item's configuration.
OPTIONS FOR GEOMAP_PLACE ITEMS
In addition to the map configuration options described above,
geomap_place items recognize the following options.
-place placeName
Specifies the name of a geoplace to display in the item.
placeName should be the name of a geoplace created with either
the geomap::place new or geomap::place set command. See the
tclgeomap (n) man page for information on how to create places.
When setting the place to display, placeName MUST BE FULLY
QUALIFIED unless the place command is global. If placeName is
an empty string, no place will be displayed in the item. When
this option is used to retrieve the place name, such as with
cget, only the base name (without any :: namespace qualifiers)
is returned. If geoplace placeName is deleted, the item
disappears from the canvas, although the item continues to
exist, and the value for this option becomes an empty string.
-dotcolor color
Specifies the color of a dot drawn at the place. color may have
any of the forms accepted by Tk_GetColor. If color is an empty
string, no dot is drawn at the place.
-dotsize integer
Specifies the size of dot to draw at the place. If integer is
<= 0, no dot is drawn at the place.
-bitmap bitmap
Specifies a bitmap to draw at the place. bitmap may have any of
the forms accepted by Tk_GetBitmap. If bitmap is an empty
string, no bitmap is drawn.
-bitmapcolor color
Specifies the bitmap color. color specifies the bitmap
foreground color, which is used for bitmap pixels whose value is
1. color may have any of the forms accepted by Tk_GetColor. If
color is an empty string, no bitmap is drawn at the place.
-text string
Specifies a string of text to display at the place.
-textcolor color
Specifies the text color. color may have any of the forms
accepted by Tk_GetColor.
-font fontName
Specifies the font to use for the text item. fontName may be
any string acceptable to Tk_GetFontStruct.
-anchor anchorPos
Tells how to position the text relative to the place. It may
have any of the forms accepted by Tk_GetAnchor. For example, if
anchorPos is center then the text is centered on the place; if
anchorPos is n then the North end of the text will be at the
place.
-arrow {azimuth shaft_len tip_len}
Draws an arrow at the place. The arrow will be oriented azimuth
degrees clockwise from true north. The shaft will be shaft_len
pixels long. The tip will have edges 'shaft_len * tip_len'
pixels long, i.e. tip_len is a fraction of shaft_len.
-arrowcolor color
Specifies the arrow color. color may have any of the forms
accepted by Tk_GetColor.
-tags tagList
Standard tags option to identify the item in canvas widget
commands.
SEE ALSO
canvas (n)
tclgeomap (n)
FILES
These commands are added to wish by the tkgeomap package in file
libtkgeomap.so or libtkgeomap.a built by the tkgeomap-2.11.6
distribution. It is part of the tkgeomap executable, or can be added
to the current interpreter with the load or package commands. Run
package names to determine if the tkgeomap package is present. See the
tkgeomap-2.11.6 distribution for installation information.
The code for the bezier spline computation was shamelessly lifted from
tkTrig.c and tkUtil.c of the Tk8.3.0 source distribution.
AUTHOR
Gordon Carrie <user0@tkgeomap.org>
Tk 2 tkgeomap(n)