Overview

This document describes the Rappture::MapViewer widget and its API. For more details on the Rappture::Map data object used in this API, see MapObjectAPI.

Creating a New Map View

package require Rappture
package require RapptureGUI

# Read server list from resources file
Rappture::resources::load

set widgetPath .mapview

set mapviewer [Rappture::MapViewer $widgetPath]

Adding a Map to the View

The MapViewer::add method adds the layers of a Map object to the view. The call to add should be followed by a call to MapViewer::scale with a list of map objects to tell the viewer which map objects should be used to determine the extents of the view.

set map [Rappture::Map #auto]

# ... Set initial map props and layers ...

# Add map to viewer
$mapviewer add $map
# Tell the viewer to update the view extents to include this map
$mapviewer scale $map

Adding and Deleting Layers

A map view is made up of all the layers from each Rappture::Map object that has been added to the viewer using the MapViewer::add method. If layers are added to or removed from a Map object after adding the Map object to the viewer, the viewer needs to be updated. This is done by calling the MapViewer::refresh method:

set map [Rappture::Map #auto]

# ... Set initial map props and layers ...

# Add map to viewer
$mapviewer add $map
$mapviewer scale $map

# Add a new layer
$map addLayer image myNewLayer [list label "My New Layer"] gdal [list url {local://sample.tif}]

# Update the viewer
$mapviewer refresh

Layer Names

In the MapViewer API, shared layers are base or overlay layers shared by all Map objects in the view. Non-shared layers are "data" layers that belong to a particular Map object.

When referring to layer names in the MapViewer API, the name of non-shared layers will be prefixed by the name of the Map object command and a dash. For example, if we have a Map object with the command name "::map0" and this map has two layers, one shared layer named "base" and one non-shared layer called "data", the layer names are:

• "base" shared layer: layerName = "base"
• "data" non-shared layer: layerName = "::map0-data"

Picking and Selection

Rappture::MapViewer::setSelectCallback <commandName>

<commandName>

name of a proc or incrTcl class method. You may need to use [itcl::code myMethod] if you are using a class method rather than a global proc, since the callback is evaluated at a global scope.

Your callback function should have this signature:

callback signature: <option> <?args?>

<option>

annotation|clear|feature|region

<args>

depends on option:

• annotation: <annotationName>
• clear: no args
• feature: <op> <featureIDList> <layerName>
  • <op>: add|delete|set
  • <layerName>: If non-shared, layer name is prefixed by map command name and a dash (see Layer Names)
• region: <xmin> <ymin> <xmax> <ymax>
  • Coordinates are in geographic SRS of map. For spherical-mercator maps, returns wgs84.

To notify the map viewer of a selection from an outside widget (e.g. a table view):

Rappture::MapViewer::select <option> <?args?>

<option>

annotation|clear|feature

<args>

depends on option:

• annotation: <annotationName>
• clear: no args
• feature: <op> <featureIDList> <layerName>
  • <op>: add|delete|set
  • <layerName>: If non-shared, layer name is prefixed by map command name and a dash (see Layer Names)

Example:

proc handleSelect {option {args ""}} {
    switch $option {
        "annotation" {
            # User clicked a map annotation (not a feature) like a user-added pin, etc.
        }
        "clear" {
            # Clear any previous selection, user clicked on background where there is no feature
            # No args
        }
        "feature" {
            foreach {op featureIdList layerName} $args break
            switch $op {
                "add" {}
                "delete" {}
                "set" {}
            }
            puts stderr "select feature $op $featureIdList $layerName"
        }
        "region" {
            foreach {xmin ymin xmax ymax} $args break
            puts "select region: ($xmin, $ymin) - ($xmax, $ymax)"
        }
    }
}

(in the following $mapViewer is a Rappture::MapViewer object and $map is a Rappture::Map object)

$mapViewer setSelectCallback "handleSelect"

$mapViewer select feature set [list 1 2 3] "$map-myLayerID"