Whatamap

Whatamap object represents a logical map that is either loaded from Whatamap database or formed otherwise. A map may contain multiple layers, points of interest, and so on.

new Whatamap('myapikey', 'mapid', null, function(wam) { var mapview = wam.createMapView('parent-div-id'); });

Arguments:

{String}

apikey

The Whatamap API key to be used.

{String}

mapid

The id of the map data to be loaded.

{Object}

options

A set of configuration options. Pass

null

for default values.

{Function}

callback

A function that is called after the map data has been loaded. A reference to the newly created

Whatamap

object is passed to that function.

createMapView(pid, eventlistener, options)

Creates a

MapView

object displaying this map.

// Loads and initializes Whatamap and creates a map view new Whatamap('apikey', 'mapid', function(wam) { var mv = wam.createMapView('parentdiv', { onClick: function() { alert('Map view clicked!'); }}); });

Arguments:

{String}

pid

The id of the parent DOM element where the map view should be placed.

{Object}

[eventlistener]

A callback object whose methods onClick and mapViewUpdated can be overridden to catch those events.

{String}

[options]

A set of configuration options to control the map view. For example, pass

{ showzoom: false }

to hide default zoom in and out buttons.

Class MapView

Version 1.4

General

getParentId()

Returns the id of the parent DOM element (typically a div) in which this map view resides.

var pdiv = document.getElementById(mapview.getParentId());

Returns:

{String}

id of the parent DOM element

redraw()

Redraws the map instantly, and in this same thread.

mapview.redraw();

redrawLater(delay)

Redraws the map after a delay, in the timer event thread.

mapview.redrawLater(10);

Arguments:

{Number}

[delay]

The delay after which to redraw, in milliseconds. Defaults to 10 if omitted.

setBackgroundImage(imgurl)

Sets the background image to be used behind the actual map tiles. If there was a previous map background image, it is replaced. The image is stretched to cover the map area in its entirety or as bounded by {@link MapView#boundVisibleArea}.

mapview.setMapBackgroundImage('http://www.domain.com/path/to/image.png'); mapview.redraw();

Arguments:

{String}

imgurl

URL to the image file to be used as a background.

addBackgroundImage(imgurl, left, top, right, bottom)

Adds an additional background image to above the actual map tiles but behind overlays. The image is stretched to cover the specified map area.

var bgid = mapview.addBackgroundImage('http://www.domain.com/path/to/image.png', 0, 0, 200, 200); mapview.redraw();

Arguments:

{String}

imgurl

URL to the image file to be used as a background.

{Number}

left

the map x coordinate of the top left corner of the image

{Number}

top

the map y coordinate of the top left corner of the image

{Number}

right

the map x coordinate of the bottom right corner of the image

{Number}

bottom

the map y coordinate of the bottom right corner of the image

Returns:

{String}

id of the newly added background image

removeBackgroundImage(bgid)

Removes a previously added additional background image.

mapview.removeBackgroundImage(bgid); mapview.redraw();

Arguments:

{String}

bgid

an id of the specific background image, as returned from {@link MapView#addBackgroundImage}

Coordinate Transforms

mapToWGSCoordinates(mapx, mapy)

Transforms between WGS84 and map coordinates.

var wgscoord = mapview.mapToWGSCoordinates(150,250); console.log('(150,250) on map is (' + wgscoord.lat + ',' + wgscoord.lon + ')' + ' in WGS84 coordinates');

Arguments:

{Number|String}

mapx

The x coordinate of the point to be transformed. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

mapy

The y coordinate of the point to be transformed. If a string value is passed, parseFloat() is used to transform it into a number.

Returns:

{Object}

The point in WGS84 coordinates, specified by attributes {lat, lon}.

wgsToMapCoordinates(lat, lon)

Transforms between map and WGS84 coordinates.

var mapcoord = mapview.wgsToMapCoordinates(62.121226,25.410004); console.log('(62.121226,25.410004) in WGS84 coordinates is (' + mapcoord.x + ',' + mapcoord.y + ') on map');

Arguments:

{Number|String}

lat

The latitude of the point to be transformed. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

lon

The longitude coordinate of the point to be transformed. If a string value is passed, parseFloat() is used to transform it into a number.

Returns:

{Object}

The point in map coordinates, specified by attributes {x, y}.

viewToMapCoordinates(viewx, viewy)

Transforms between map and view coordinates.

// calculates where the upper left corner of the current view is on map var mapcoord = mapview.viewToMapCoordinates(0, 0); console.log('View upper left corner points to (' + mapcoord.x + ',' + mapcoord.y + ') on map');

Arguments:

{Number|String}

viewx

The x coordinate of the point to be transformed, in view coordinates. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

viewy

The y coordinate of the point to be transformed, in view coordinates. If a string value is passed, parseFloat() is used to transform it into a number.

Returns:

{Object}

The point in map coordinates, specified by attributes {x, y}.

mapToViewCoordinates(mapx, mapy)

Transforms between view and map coordinates.

// calculates the view coordinates of the point (100, 250) on map var viewcoord = mapview.viewToMapCoordinates(100, 250); console.log('Map point (100,250) is visible at pixel (' + viewcoord.x + ',' + viewcoord.y + ') in the view');

Arguments:

{Number|String}

mapx

The x coordinate of the point to be transformed, in map coordinates. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

mapy

The y coordinate of the point to be transformed, in map coordinates. If a string value is passed, parseFloat() is used to transform it into a number.

Returns:

{Object}

The point in view coordinates, specified by attributes {x, y}.

viewToMapDistance(view)

Calculates the distance on map spanned by a known distance on screen.

var mapd = mapview.viewToMapDistance(320); console.log('320 pixels on screen spans ' + mapd + ' pixels on map.');

Arguments:

{Number|String}

view

The distance on screen. If a string value is passed, parseFloat() is used to transform it into a number.

Returns:

{Number}

The distance in map coordinates.

mapToViewDistance(map)

Calculates the distance on screen spanned by a known distance on map.

var viewd = mapview.mapToViewDistance(100); console.log('100 pixels on map spans ' + viewd + ' pixels on screen.');

Arguments:

{Number|String}

view

The distance on map. If a string value is passed, parseFloat() is used to transform it into a number.

Returns:

{Number}

The distance in view coordinates.

Scrolling and Zooming

scrollMapTo(mapx, mapy, animate)

Centers the map at the specified point. If the map is centered elsewhere, optionally animates the transition.

Please note that during animated transitions, redraw() is called automatically whereas if the transition is not animated, you have to call redraw() or redrawLater() manually after changing the view.

// Center the map at (500,500) mapview.scrollMapTo(500,500); mapview.redraw(); // Center the map at (100,100), and animate 1.5 second transition to (300,600) mapview.scrollMapTo(100,100); mapview.scrollMapTo(300, 600, 1500);

{Number|String}

mapx

The x coordinate of the point on map where map is to be centered at. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

mapy

The y coordinate of the point on map where map is to be centered at. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|Boolean}

[animate]

The time in milliseconds to use for the animated transition from current view to the newly centered view. If true, defaults to 1000, if false or omitted, the transition is instantaneous with no animation.

scrollMap(offsetx, offsety, animate)

Moves the map around by the specified offset in map coordinates, optionally animating the transition.

Please note that during animated transitions, redraw() is called automatically whereas if the transition is not animated, you have to call redraw() or redrawLater() manually after changing the view.

// Move the map right by 100 map pixels mapview.scrollMap(100,0); mapview.redraw(); // Move the map up by 200 map pixels, animating the transition for 2 seconds. mapview.scrollMap(0,200,2000);

Arguments:

{Number|String}

offsetx

The offset by which to move the x coordinate of the center of the map, in map coordinates. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

offsety

The offset by which to move the y coordinate of the center of the map, in map coordinates. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|Boolean}

[animate]

scrollMapView(offsetx, offsety, animate)

Moves the map around by the specified offset in view coordinates, optionally animating the transition.

Please note that during animated transitions, redraw() is called automatically whereas if the transition is not animated, you have to call redraw() or redrawLater() manually after changing the view.

// Move the map right by 100 view pixels mapview.scrollMapView(100,0); mapview.redraw(); // Move the map up by 200 view pixels, animating the transition for 2 seconds. mapview.scrollMapView(0,200,2000);

Arguments:

{Number|String}

offsetx

The offset by which to move the x coordinate of the center of the map, in view pixels. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

offsety

The offset by which to move the y coordinate of the center of the map, in view pixels. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|Boolean}

[animate]

zoomMapTo(z, animate)

Changes the map zoom level to the specified number. If the current zoom level is different, optionally animates the transition.

Map zoom level is defined as (amount of pixels in the map image) divided by (amount of pixels in the view). For example, the zoom level of 4.0 means that every screen pixel covers 4 map pixels (higher zoom level), and a zoom level of 0.5 means that every map pixel covers 2 screen pixels (lower zoom level).

Please note that during animated transitions, redraw() is called automatically whereas if the transition is not animated, you have to call redraw() or redrawLater() manually after changing the view.

// zoom close mapview.zoomMapTo(0.5); mapview.redraw(); // animate a transition from current zoom level to a high zoom level mapview.zoomMapTo(5, true);

{Number|String}

The new zoom level. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|Boolean}

[animate]

zoom(factor, animate)

As {@link MapView#zoomMapTo}, but instead of setting a new zoom level explicitly just multiplies the current zoom level by the specified factor.

For more details, see {@link this.zoomMapTo}.

// zoom closer mapview.zoom(0.5); mapview.redraw(); // animate a transition from current zoom level to a higher zoom level mapview.zoom(2, true);

{Number|String}

The factor with which the current zoom level is multiplied. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|Boolean}

[animate]

zoomIn(animate)

As {@link MapView#zoomMapTo}, but instead of setting a new zoom level explicitly just multiplies the current zoom level 0.5; equivalent to calling zoom(0.5)

For more details, see {@link MapView#zoomMapTo}.

// zoom closer mapview.zoomIn(); mapview.redraw(); // zoom closer, animating the transition mapview.zoomIn(true);

{Number|Boolean}

[animate]

zoomOut(animate)

As {@link MapView#zoomMapTo}, but instead of setting a new zoom level explicitly just multiplies the current zoom level by 2.0; equivalent to calling zoom(2.0)

For more details, see {@link MapView#zoomMapTo}.

// zoom higher mapview.zoomOut(); mapview.redraw(); // zoom higher, animating the transition mapview.zoomOut(true);

{Number|Boolean}

[animate]

getZoom()

Gets the current zoom level of the map view.

if( mapview.getZoom() > 0.75 ) { mapview.zoomMapTo(0.75); mapview.redraw(); }

Returns:

{Object}

The zoom level, as defined in {@link MapView#zoomMapTo}.

Visible Area

getVisibleArea()

Gets the currently visible area of the map, in map coordinates.

// print visible area to browser log var va = mapview.getVisibleArea(); console.log('Currently visible area: (' + va.left + ',' + va.top + ') to ' + '(' + va.right + ',' + va.bottom + ')');

Returns:

{Object}

The visible area, specified by attributes {left, right, top, bottom, width and height}.

setVisibleArea(left, top, right, bottom, animate, marginl, margint, marginr, marginb)

Sets the currently visible area of the map, optionally animating the transition.

If the specified area is not of the same proportions as the current view element, then the actual area shown is larger; calling this function guarantees that at least the specified area is visible.

Please note that during animated transitions, redraw() is called automatically whereas if the transition is not animated, you have to call redraw() or redrawLater() manually after changing the view.

// set visible area mapview.setVisibleArea(100,100,500,500); mapview.redraw(); // set visible area, with 2 second animated transition mapview.setVisibleArea(100,100,500,500,2000); // set visible area, with a left and right margin in view coordinates mapview.setVisibleArea(100,100,500,500,null,100,0,100,0); mapview.redraw();

Arguments:

{Number|String}

left

The left boundary of the visible area, in map coordinates. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

top

The top boundary of the visible area, in map coordinates. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

right

The right boundary of the visible area, in map coordinates. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

bottom

The bottom boundary of the visible area, in map coordinates. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|Boolean}

[animate]

{Number|String}

[marginl]

A left margin, in view coordinates, to be left visible in addition to the specified area. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

[margint]

A top margin, in view coordinates, to be left visible in addition to the specified area. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

[marginr]

A right margin, in view coordinates, to be left visible in addition to the specified area. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

[marginb]

A bottom margin, in view coordinates, to be left visible in addition to the specified area. If a string value is passed, parseFloat() is used to transform it into a number.

boundVisibleArea(left, top, right, bottom)

Bounds the visible area of the map, so that user cannot scroll or zoom outside of these boundaries. optionally animating the transition.

If the specified area is not of the same proportions as the current view element, then the actual area shown is larger; calling this function guarantees that at least the specified area is visible.

Please note that during animated transitions, redraw() is called automatically whereas if the transition is not animated, you have to call redraw() or redrawLater() manually after changing the view.

// bound visible area mapview.boundVisibleArea(100,100,500,500); mapview.redraw();

Arguments:

{Number|String}

left

The left boundary, in map coordinates. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

top

The top boundary, in map coordinates. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

right

The right boundary, in map coordinates. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

bottom

The bottom boundary, in map coordinates. If a string value is passed, parseFloat() is used to transform it into a number.

setFixedVisibleArea(left, top, right, bottom, marginl, margint, marginr, marginb)

Fixes the visible area of the map so that it cannot be changed by user via scrolling or zooming the map, with similar semantics as {@link MapView#setVisibleArea}.

// fix visible area mapview.fixVisibleArea(100,100,500,500); mapview.redraw(); // fix visible area, with a left and right margin in view coordinates mapview.setVisibleArea(100,100,500,500,100,0,100,0); mapview.redraw();

Arguments:

{Number|String}

left

The left boundary of the visible area, in map coordinates. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

top

The top boundary of the visible area, in map coordinates. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

right

The right boundary of the visible area, in map coordinates. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

bottom

The bottom boundary of the visible area, in map coordinates. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

[marginl]

A left margin, in view coordinates, to be left visible in addition to the specified area. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

[margint]

A top margin, in view coordinates, to be left visible in addition to the specified area. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

[marginr]

A right margin, in view coordinates, to be left visible in addition to the specified area. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

[marginb]

A bottom margin, in view coordinates, to be left visible in addition to the specified area. If a string value is passed, parseFloat() is used to transform it into a number.

Markers and Balloons

addMarkerPin(mapx, mapy, color, clickfun)

Adds a default marker on the map.

Please see {@link MapView#addMarker} if you need to specify the marker more accurately.

// Add a marker pin that cannot be clicked var markerid = mapview.addMarkerPin(100, 200); // Add a marker pin that alerts when clicked var markerid = mapview.addMarkerPin(100, 200, 'blue', function() { alert('Blue pin clicked!');} ); mapview.redraw();

Arguments:

{Number|String}

mapx

The map x coordinate where to place the marker. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

mapy

The map y coordinate where to place the marker. If a string value is passed, parseFloat() is used to transform it into a number.

{String}

[color]

The color of the marker pin to be used. Available values include 'red', 'blue', 'green', 'yellow', 'black' and 'purple'. Defaults to 'red' if omitted.

{Function}

[clickfun]

The callback function to be called when the marker is clicked.

Returns:

{String}

A marker id that can later be used to refer to the newly created marker. Returns "" if the marker was not created (due to invalid parameters to this function).

addMarker(mapx, mapy, icon, iconwidth, iconheight, iconoffsetx, iconoffsety, clickfun)

Adds a marker on the map.

Please see {@link MapView#addMarkerPin} for a shortcut version of this function.

var markerid = mapview.addMarker(100, 200, 'http://domain.com/path/to/icon.png', 48, 48, 0, 0, function() { alert('Marker clicked!'); }); mapview.redraw();

Arguments:

{Number|String}

mapx

The map x coordinate where to place the marker. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

mapy

The map y coordinate where to place the marker. If a string value is passed, parseFloat() is used to transform it into a number.

{String}

icon

A URL to the icon image to be displayed at the marker location.

{Number|String}

[iconwidth]

The width of the icon when displayed on map, in pixels. This does not have to equal the physical width of the icon image. If a string value is passed, parseFloat() is used to transform it into a number. Defaults to 32.

{Number|String}

[iconheight]

The height of the icon when displayed on map, in pixels. This does not have to equal the physical height of the icon image. If a string value is passed, parseFloat() is used to transform it into a number. Defaults to 32.

{Number|String}

[iconoffsetx]

The horizontal offset by which to move the marker from the position of centered around (mapx,mapy). For instance, if the marker bitmap represents a needle, it may be necessary to offset the marker to make the needle pinpoint the correct location. If a string value is passed, parseFloat() is used to transform it into a number. Defaults to 0.

{Number|String}

[iconoffsety]

The vertical offset by which to move the marker from the position of centered around (mapx,mapy). For instance, if the marker bitmap represents a needle, it may be necessary to offset the marker to make the needle pinpoint the correct location. If a string value is passed, parseFloat() is used to transform it into a number. Defaults to 0.

{Function}

[clickfun]

The callback function to be called when the marker is clicked.

Returns:

{String}

A marker id that can later be used to refer to the newly created marker. Returns "" if the marker was not created (due to invalid parameters to this function).

addCustomMarker(mapx, mapy, customMarker )

Adds a custom HTML marker on the map.

Please see {@link MapView#addMarkerPin} or {@link MapView#addMarker} for a simple icon marker addition.

var markerid = mapview.addCustomMarker(100, 200, "<div><p onclick='alert();'>Click Me!</p></div>"); mapview.redraw();

Arguments:

{Number|String}

mapx

The map x coordinate where to place the marker. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

mapy

The map y coordinate where to place the marker. If a string value is passed, parseFloat() is used to transform it into a number.

{String}

customMarker

The HTML fragment to be added at the specific map location. Please note that to center this around the marker location, you may need to apply CSS relative positioning within this element.

Returns:

{String}

A marker id that can later be used to refer to the newly created marker. Returns "" if the marker was not created (due to invalid parameters to this function).

moveMarker(markerid, newx, newy)

Moves a marker to a new location.

mapview.moveMarker(mid, 150, 250); mapview.redraw();

Arguments:

{String}

markerid

The id of the marker to be moved, as returned from {@link MapView#addMarkerPin}, {@link MapView#addMarker} or {@link MapView#addMarker}.

{Number|String}

newx

The new map x coordinate where to move the marker to. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

newy

The new map y coordinate where to move the marker to. If a string value is passed, parseFloat() is used to transform it into a number.

removeAllMarkers()

Removes all markers that have been added to this map view.

mapview.removeAllMarkers(); mapview.redraw();

removeMarker(id)

Removes the specified marker.

mapview.removeMarker(mid); mapview.redraw();

Arguments:

{String}

markerid

The id of the marker to be removed, as returned from {@link MapView#addMarkerPin}, {@link MapView#addMarker} or {@link MapView#addMarker}.

showBalloonPin(markerid, title, color, clickfun, clickfunbody)

Shows a default balloon popup on top of a marker.

Please see {@link MapView#showBalloon} if you need to specify the balloon more accurately.

// Add a marker and display a balloon var markerid = mapview.addMarkerPin(100, 200); var balloonid = mapview.showBalloonPin(markerid, 'Test Balloon', 'red', function() { alert('Blue pin clicked!'); }, function() { alert('Blue balloon clicked!'); }); mapview.redraw();

Arguments:

{String}

markerid

The id of the marker to be moved, as returned from {@link MapView#addMarkerPin}, {@link MapView#addMarker} or {@link MapView#addMarker}.

{String}

title

The text to be displayed in the balloon.

{String}

[color]

The color of the balloon icon to be displayed. Available values include 'red', 'blue', 'green', 'yellow', 'black' and 'purple'. No icon displayed if omitted or null.

{Function}

[clickfun]

The callback function to be called when the arrow button in the balloon is clicked. If null or omitted, no arrow button will be displayed in the balloon.

{Function}

[clickfunbody]

The callback function to be called when the balloon is clicked.

Returns:

{String}

A balloon id that can later be used to refer to the newly created balloon. Returns "" if the marker was not created (due to invalid parameters to this function).

showBalloon(markerid, title, icon, iconwidth, iconheight, clickfun, clickfunbody)

Shows a balloon popup on top of a marker.

Please see {@link MapView#showBalloonPin} for a shortcut version.

// Add a marker and display a balloon var markerid = mapview.addMarkerPin(100, 200); var balloonid = mapview.showBalloonPin(markerid, 'Test Balloon', 'http://www.domain.com/path/to/icon.png', 32, 32, function() { alert('Blue pin clicked!'); }, function() { alert('Blue balloon clicked!'); }); mapview.redraw();

Arguments:

{String}

markerid

The id of the marker to be moved, as returned from {@link MapView#addMarkerPin}, {@link MapView#addMarker} or {@link MapView#addMarker}.

{String}

title

The text to be displayed in the balloon.

{String}

icon

A URL to the icon image to be displayed in the balloon.

{Number|String}

[iconwidth]

The width of the icon in pixels. This does not have to equal the physical width of the icon image. If a string value is passed, parseFloat() is used to transform it into a number. Defaults to 32.

{Number|String}

[iconheight]

The height of the icon when displayed in pixels. This does not have to equal the physical height of the icon image. If a string value is passed, parseFloat() is used to transform it into a number. Defaults to 32.

{Function}

[clickfun]

The callback function to be called when the arrow button in the balloon is clicked. If null or omitted, no arrow button will be displayed in the balloon.

{Function}

[clickfunbody]

The callback function to be called when the balloon is clicked.

Returns:

{String}

A balloon id that can later be used to refer to the newly created balloon. Returns "" if the balloon was not created (due to invalid parameters to this function).

hideBalloon(markerid)

Hides the specified balloon.

var balloonid = mapview.showBalloonPin(markerid, 'Balloon Title'); mapview.hideBalloon(balloonid); mapview.redraw();

Arguments:

{String}

balloonid

The id of the balloon to be removed, as returned from {@link MapView#showBalloonPin} or {@link MapView#showBalloon}.

hideAllBalloons()

Hides all balloons that are being displayed.

mapview.hideAllBalloons(); mapview.redraw();

Overlays

addOverlay(renderfun, createcanvas, zindex)

Adds an overlay to be displayed on top of the map view.

The overlay is practically a HTML5 Canvas element that is positioned on the map and can display whatever content is necessary. The canvas is positioned below markers, so that markers, labels and balloons are always visible.

// An overlay that covers the area (100,100)-(300,300) on map with a red rectangle. mapview.addOverlay(function(ctx, mv, width, height) { ctx.clearRect(0, 0, width, height); var p1 = mv.mapToViewCoordinates(100, 100); var p2 = mv.mapToViewCoordinates(300, 300); ctx.fillStyle = "#ff0000"; ctx.fillRect(p1.x, p1.y, p2.x-p1.x, p2.y-p1.y); }); mapview.redraw();

Arguments:

{Function}

renderfun

A callback function to be called when the overlay is rendered. The function is of the form function(ctx, mapview, width, height, mx0, my0, mx1, my1) where ctx is the HTML5 Canvas 2D context, mapview is reference to the MapView object, width and height specify the canvas width and height in pixels and (mx0,my0) and (mx1,my1) are the upper left and lower right corners of the canvas in map coordinates.

{Boolean}

[createcanvas]

A flag telling whether the overlay will use HTML5 Canvas element. If true, a canvas element is created, if false, not. In that case, the rendering function could instead move around HTML image elements etc. to visualize the overlay. If omitted, defaults to true

{Number}

[zindex]

A z-index to be passed to the CSS style of the created canvas div. If omitted, defaults to 0

Returns:

{String}

An overlay id that can later be used to refer to the newly created overlay. Returns "" if the overlay was not created.

addImageOverlay(imgurl, imgw, imgh, topleftx, toplefty, toprightx, toprighty, bottomrightx, bottomrighty, zindex)

Adds an image overlay to be displayed on top of the map view.

This is a helper function that calls {@link MapView#addOverlay} internally with an overlay that stretches an image over specified map coordinates.

// An image overlay mapview.addImageOverlay('overlay.png', 300, 300, 0, 100, 100, 0, 100, 100); mapview.redraw();

Arguments:

{String}

imgurl

An URL to the image to be displayed

{Number}

imgw

Width of the image

{Number}

imgh

Height of the image

{Number}

topleftx

The x-coordinate of the top left corner of the image, in map coordinates

{Number}

toplefty

The y-coordinate of the top left corner of the image, in map coordinates

{Number}

toprightx

The x-coordinate of the top right corner of the image, in map coordinates

{Number}

toprighty

The y-coordinate of the top right corner of the image, in map coordinates

{Number}

bottomrightx

The x-coordinate of the bottom right corner of the image, in map coordinates

{Number}

bottomrighty

The y-coordinate of the bottom right corner of the image, in map coordinates

{Number}

[zindex]

A z-index to be passed to {@link MapView#addOverlay}

Returns:

{String}

An overlay id that can later be used to refer to the newly created overlay, as in {@link MapView#addOverlay}

removeOverlay(overlayid)

Hides the specified overlay.

var overlayid = mapview.addOverlay(function(ctx, mv, width, height) { ctx.clearRect(0, 0, width, height); var p1 = mv.mapToViewCoordinates(100, 100); var p2 = mv.mapToViewCoordinates(300, 300); ctx.fillStyle = "#ff0000"; ctx.fillRect(p1.x, p1.y, p2.x-p1.x, p2.y-p1.y); }); mapview.removeOverlay(overlayid);

Arguments:

{String}

overlayid

The id of the overlay to be removed, as returned from {@link MapView#addOverlay}.

Labels

addLabel(mapx, mapy, text, font)

Places a label on the map at specific map coordinates.

// Add a marker pin that cannot be clicked var labelid = mapview.addLabelBox(100, 200, 'An Important Area', "font-family: 'Lucida Grande', 'sans-serif'; font-size: 14px; " + "color: #ffffff; text-shadow: #000000 1px 1px 1px;"); mapview.redraw();

Arguments:

{Number|String}

mapx

The map x coordinate where the label should be centered at. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

mapy

The map y coordinate where the label should be centered at. If a string value is passed, parseFloat() is used to transform it into a number.

{String}

text

The text to be displayed.

{String}

[font]

The font to be used when displaying the text. This string should be a valid CSS style specifying font-family, font-size, color, text-shadow and other relevant attributes. If omitted, a default font will be used.

Returns:

{String}

A label id that can later be used to refer to the newly created label. Returns "" if the label was not created (due to invalid parameters to this function).

addLabelBox(mapx, mapy, mapw, maph, text, font, fontsmall, force)

Places a label on the map within specific map coordinates, and optionally only displays the label if it fits within the area.

// Add a marker pin that cannot be clicked var labelid = mapview.addLabelBox(100, 200, 150, 50, 'An Important Area', "font-family: 'Lucida Grande', 'sans-serif'; font-size: 14px; " + "color: #ffffff; text-shadow: #000000 1px 1px 1px;", "font-family: 'Lucida Grande', 'sans-serif'; font-size: 10px; " + "color: #ffffff; text-shadow: #000000 1px 1px 1px;", false); mapview.redraw();

Arguments:

{Number|String}

mapx

The map x coordinate specifying the upper left corner of the area where the label should be displayed. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

mapy

The map y coordinate specifying the upper left corner of the area where the label should be displayed. If a string value is passed, parseFloat() is used to transform it into a number.

{Number|String}

mapw

The width of the area where the label should be displayed, in map coordinates. If a string value is passed, parseFloat() is used to transform it into a number. If 0, then the label is centered around (mapx, mapy) and always displayed.

{Number|String}

maph

The height of the area where the label should be displayed, in map coordinates. If a string value is passed, parseFloat() is used to transform it into a number. If 0, then the label is centered around (mapx, mapy) and always displayed.

{String}

text

The text to be displayed.

{String}

[font]

{String}

[fontsmall]

A second, smaller font to be used when displaying the text. This font will be tried if the text does not fit within the box using the first font. If omitted, the bigger font will be always used.

{Boolean}

[force]

If true, the text is displayed even if it does not fit within the specified box.

Returns:

{String}

A label id that can later be used to refer to the newly created label. Returns "" if the label was not created (due to invalid parameters to this function).

removeLabel(id)

Removes the specified label.

mapview.removeLabel(mid); mapview.redraw();

Arguments:

{String}

labelid

The id of the label to be removed, as returned from {@link MapView#addLabel} or {@link MapView#addLabelBox}.

removeAllLabels()

Removes all labels that have been added to this map view.

mapview.removeAllLabels(); mapview.redraw();