XBit provides an enhanced canvas widget, gcanvas, to display and edit map objects.  At the level of Tcl API, a gcanvas can be considered an extenstion of the original Tk canvas widget.  It supports all the generic item types and canvas commands that are implemented by the original Tk canvas.  In addition, a gcanvas has its unique features, including scalable viewport, polygon with holes, text rotation and rescale, scalable image item, graphic symbol, group item and map object.  To support antomatically label display, gcanvas provides commands for polygon centroid and line orientation calculations.  A gcanvas greatly optimizes its performance in displaying large maps by using specialized map objects and floating items.  

The following scripts show how to create a polygon with holes and how to automatically draw line-orientated and polygon-centroided text strings.

set canv .canv
gcanvas $canv -bg #DBDBAB
pack $canv -expand 1 -fill both 
font create f0 -family Times -slant roman

# draw a line
set id [$canv create line 10 10 40 40 80 60 120 80 160 90 180 100 240 140 240 220 -width 3]

# draw text strings along the line
foreach pindex {0.25 .45 0.68 0.9} {
    foreach {angle x y} [$canv langle $id $pindex] break
    $canv create gtext $x $y -text Text -font f0 -anchor s -escapement $angle
    $canv create gtext $x $y -text Text -font f0 -anchor n -escapement $angle
}

# create a polygon with two holes
set id [$canv create polygon 20 20 40 10 80 15 100 20 120 25 160 30 \
190 40 210 80 160 200 110 220 60 200 30 180 15 150 \
40 80 80 100 100 90 110 50 80 30 40 35 \
110 110 150 115 170 100 180 65 140 40 120 50 \
{13 6 6} -fill green -outline red]

# draw a text string at the polygon centroid 
set centroid [$canv centroid $id]
set x [lindex $centroid 0]
set y [lindex $centroid 1]
$canv create text $x $y -text "Polygon With Holes" -anchor n

# Creating one image object, globe and two map objects, contries and us (United States). 
# All are in longitude and latitude coordinate system {180W, 90N, 180E, 90S}
image create gimg globe -file globe.jpg -comb 1/2/3 -pal 8/8/4 -x0 -180 -y0 90 -dx 0.5625 -dy 0.5625
shape.create contries -file cntry94.shp
shape.create us -file states.shp

# Creating a gcanvas widget, defining the positive y pointing toward North and
# setting proper zoom factors and viewport coordinate origin.
gcanvas .map -mx 1.5 -my -1.5 -viewx -180 -viewy 90 -highlightthickness 0
pack .map -expand 1 -fill both

# Creating one scalable image item and two object items and display them in the canvas.
.map create image 0 0 -image globe -scalable 1
.map create object 0 0 -object contries -outline red
.map create object 0 0 -object us -outline green

# Choosing a viewport for a region of interest.
.map config -mx 8 -my -8 -viewxorigin -128 -viewyorigin 53

Scalable Viewport.  A gcanvas has a scalable viewport that pans, flips and magnifies its graphic display without changing the coordinates of the contained items.  Following is a typical viewport specification of a gcanvas:

gcanvas create gcanvPath -mx mx -my my -xvieworigin xo -yvieworigin yo

xViewport = (xWorld - xo) * mx - xOrigin
yViewport = (yWorld - yo) * my - yOrigin

Polygon with Holes.  A polygon item of a gcanvas supports multi-polygon specification.  This is done by extending the coordinate list to include both even and odd number of items.  Following is a typical multi-polygon item specification:

gcanvasPath create polgyon x0 y0 x1 y0... xn yn [{n0 n1... nk}]

Text Rescale and Rotation.  A gcanvas supports a scalable text item, which will change its size when the viewport's magnification factors are changed.  To prevent a text string from changing its size, the value of the option -scalable should be set to 0.   In addition to a text item type, a gcanvas provides a gtext item type with three more options, -escapment, -orientation and -aspectratio.   Following is a typical gtext item specification with a 30 degree rotation angle and 0.6 aspect ratio:

gcanvasPath create gtext x y -texttext -escapement 30.0  -aspectratio 0.6 -orientation 0.0

Scalable Image Item.  A gcanvas supports image items as a Tk canvas does with additional options -scalable and -magnifycommand.  These two options make an image item become automatically rescaled with gcanvas options -mx and -my.  To make a scalable image item, option -scalable should be configured as "1".  Option -magnifycommand specifies a call back Tcl command imageMagnifyCommand to magnify the image according to values of gcanvas options -mx and -my.  The call back command must have the following prototype: 

imageMagnifyCommand mx my

Symbol Item.  A symoble item is specified with an anchor point (x, y) and can be used to draw point related symbolic graphics.  A symbol item includes three different components, text, symbol and marker.  While the text component can be placed around the anchor point, the symbol and marker are centered at the anchor point.  Following is a typical symbol item specification:

gcanvasPath create symbol x y -text symbolText -symboltypesymbolType -markertypemarkerType

Group Item.  A group item is a container to combine other gcanvas items.  It can be used to draw customized map legends or decorations for map annotation.  Following script creates a group item at an anchor point (x, y) and adds an oval and a rectangle into it:

set id [gcanvasPath create group x y]
set gid0 [gcanvasPath group $id oval 20 20]
set gid1 [gcanvasPath group $id rectangle -20 -10 -40 10]

gcanvasPath group $id delete $gid1
gcanvasPath group $id itemconfig $gid0 -fill red

Object Item.  An object item is used for a gcanvas to access to XBit map objects that encapsulate geographic map data sets such as shape (.shp) files.  Following script creates an object item:

gcanvasPath create object x y -object xbitMapObject

gcanvasPath disassemble xbitMapObject
gcanvasPath assemble xbitMapObject type id...

[HOME][CONTENTS][DOWNLOAD]