Class MMViewer

Object
   |
   +--MMViewer

Direct Known Subclasses:

MultimapViewer

class MMViewer

Defined in MultimapOpenAPI

Constructor Detail

MMViewer

MMViewer( map, div_element )

This is the base mapviewer class. This manages all of the HTML that makes up the mapviewer. It keeps an array of the map tiles and manages overlays according to the instructions you specify.

addEventHandler

boolean addEventHandler( <String> eventType, <Function> handlerFunction )

Adds an event handler. If the function has been assigned for the event type before then the previous one is removed.
The event handler should always accept a minimum of two arguments. The first is always the event type, and the second is the object on which the event occurred. This allows you to use the same function for multiple types. The other arguments will depend on the type of event as follows:

Event type	Event target	3rd Argument	4th Argument	5th Argument
click	mapviewer	position clicked on in local coordsys	pixel distance of click from map center
click	marker
changeZoom	mapviewer	old zoom	new zoom	reason that zoom change occurred
changeMapType	mapviewer	old map type	new map type
mapBoundsChanged	mapviewer	reason that map bounds changed
eventError	mapviewer	type of the event that caused the error	target of the event that caused the error	javascript exception object that was caught
dataPreferencesChanged	mapviewer	map type	new set of preferences
coverageUpdated	mapviewer
drag	mapviewer
startPan	mapviewer
endPan	mapviewer	start position	end position	reason for the pan
addOverlay	overlay
removeOverlay	overlay
removeAllOverlays	mapviewer
openInfoBox	overlay	parent marker
closeInfoBox	overlay
resize	mapviewer	old mapviewer dimensions	new mapviewer dimensions
startGeocode	mapviewer	location being geocoded
endGeocode	mapviewer	location that was geocoded	error code if there was a problem
startRouteRequest	mapviewer	route being requested
endRouteRequest	mapviewer	route that was requested	error code if there was a problem
startSearchRequest	mapviewer	search being requested
endSearchRequest	mapviewer	search that was requested	error code if there was a problem
zoomFactorsChanged	mapviewer	an array of the now available zoom factors
contextMenu	mapviewer	a reference to the context menu that will be added to the map	the geographical position that was clicked on	pixel distance of click from map center
optionChanged	mapviewer	the name of the option that was changed	the new value of the option
startMouseDrag	mapviewer/overlay	pixel distance of click from map center
continueMouseDrag	mapviewer/overlay	pixel distance of this stage of the mouse drag
endMouseDrag	mapviewer/overlay	pixel distance from the previous continueMouseDrag event
overlayStartDrag	overlay	pixel distance of the drag so far
overlayContinueDrag	overlay	pixel distance of the drag so far
overlayEndDrag	overlay	new position of the overlay (MMLatLon for a marker, MMBounds for a rectangle)	pixel distance of the entire drag
declutterStart	mapviewer	type of decluttering (MM_DECLUTTER_AGGREGATE or MM_DECLUTTER_GRID)	group name that is being decluttered (or undefined for "unnamed markers")
declutterCluster	mapviewer	type of decluttering (MM_DECLUTTER_AGGREGATE or MM_DECLUTTER_GRID)	group name that is being decluttered (or undefined for "unnamed markers")	an array of markers that have been clustered	for aggregate decluttering, a reference to the aggregate marker, allowing you to change properties such as the label	for aggregate decluttering, an anonymous object that contains options that will be passed to setInfoBoxContent(), allowing you to change the class name
declutterEnd	mapviewer	type of decluttering (MM_DECLUTTER_AGGREGATE or MM_DECLUTTER_GRID)	group name that is being decluttered (or undefined for "unnamed markers")
mouseover	mapviewer/marker/polyline	for mapviewer and polyline target, the step distance from the center of the mapviewer to the mouse cursor
mousemove	mapviewer/marker/polyline	for mapviewer and polyline target, the step distance from the center of the mapviewer to the mouse cursor
mouseout	mapviewer/marker/polyline	for mapviewer and polyline target, the step distance from the center of the mapviewer to the mouse cursor

Parameters:
eventType - Type of the event being called
handlerFunction - The event handling function

Returns:
True if the event type was valid, false otherwise

addOverlay

void addOverlay( <MMOverlay> overlay )

A function for adding an overlay (marker, info box or polyline) to the mapviewer. If the overlay is already on the map, it will be removed and re-added.

Parameters:
overlay - The overlay to be added to the mapviewer.

addWidget

void addWidget( <MMWidget> widget )

Adds a Widget to the mapviewer.

Parameters:
widget - The widget to add to the mapviewer.

assignIgnoreEvents

void assignIgnoreEvents( <HTMLElement> element )

Sets up handlers for a HTML element to stop the mapviewer responding. This should be used when client HTML is added to the mapviewer to stop the mapviewer responding to browser events that occur on the client HTML.

Parameters:
element - HTML Element

beenDrawn

boolean beenDrawn()

Returns true if the viewer has been drawn.

cancelSmoothMove

void cancelSmoothMove()

Cancels a smooth move which is in progress.

drawAndPositionMap

Object drawAndPositionMap( <MMLocation> location )

Draws a map centered on a specific position. You may optionally include a zoom factor as part of the location.

Parameters:
location - Location to start from, including zoom factor

endManageLayout

void endManageLayout( element )

De-register a HTML element for management by the API.

geoPosToContainerPixels

MMPoint geoPosToContainerPixels( <MMLatLon> position )

When given a position in an appropriate coordinate system this method returns the pixel coordinates for that location within the viewer.

Parameters:
position - Position in an appropriate coordinate system.

Returns:
The position, in pixels, of a location within the mapviewer container.

getAutoScaleLocation

MMLocation getAutoScaleLocation( <Array> entries )

Returns the correct scale and centerpoint to fit the set of points or markers in the mapviewer. Passing in a single point/marker will return the position of that marker. Passing in no points is invalid and the function will return nothing in this case. Takes into account the International Date Line if a world map is used.

Parameters:
entries - An array of overlays or geographic points.

Returns:
The location of the centerpoint and correct zoom factor to fit all points in the mapviewer.

getAvailableZoomFactors

Array getAvailableZoomFactors()

Function to retrieve the range of available zoom factors available for this map type.

Returns:
An array of available zoom factor values.

getBrowserDimensions

MMDimensions getBrowserDimensions()

Function for getting the dimensions of the browser; this function uses a number of methods so should work in all browsers supported by the mapviewer. Not really related to the mapviewer but only used by it so offered as a member function of the class.

Returns:
The current dimensions of the browser window

getContainer

HTMLElement getContainer()

Retrieves a reference to the HTML element that contains the mapviewer elements.

Returns:
A reference to a HTML element containing the mapviewer elements.

getCurrentPosition

MMLatLon getCurrentPosition()

Gets the current position of the map.

Returns:
The current position.

getDimensions

MMDimensions getDimensions()

A method to retrieve the dimensions of the mapviewer.

Returns:
The dimensions of the mapviewer.

getDraggable

boolean getDraggable()

DEPRECATED Use getOption( 'drag' ) instead. Gets the current value for the 'draggable' property.

Returns:
True if the map is draggable, false if not.

getGreatCircleDistance

Object getGreatCircleDistance( <MMLatLon> first, <MMLatLon> second, <String> units )

Retrieves the "Great Circle" distance between two locations specified as Lat/Lon coordinates (or MMLocations containing MMLatLons).

Parameters:
first - First location.
second - Second location.
units - (optional) The units of measurement to return 'km' or the default 'miles'.

getInnerDimensions

MMBox getInnerDimensions()

A method to retrieve the inner dimensions of the mapviewer. Takes into account space taken up by widgets. Gives the coordinates of the viewable area as a box. The algorithm used is fairly basic and assumes there is no widget across the center of the mapviewer; it will fail if that is the case.

Returns:
The inner dimensions of the mapviewer.

getKeyboardPanning

boolean getKeyboardPanning()

DEPRECATED Use getOption( 'keyboard' ) instead. Retrieves the setting of the keyboard panning option.

Returns:
True if keyboard panning is turned on, false otherwise.

getMapBounds

MMBounds getMapBounds()

Returns the bounds of the rectangle displayed in the mapviewer.

Returns:
Coordinates of the south west and north east points of the map.

getMapPositionAt

MMLatLon getMapPositionAt( <MMPoint> step, <MMLatLon> relative_to )

Returns the position at the given pixel offset.

Parameters:
step - Pixel offset from the center of the map
relative_to - (optional) Geographical coordinates you want the pixel offset relative to. Default is the center of the viewer.

Returns:
The map position at the given pixel offset

getMouseWheelZoom

boolean getMouseWheelZoom()

DEPRECATED Use getOption( 'mousewheel:wheelup' ) and getOption( 'mousewheel:wheeldown' ) instead. Retrieves the setting of the mousewheel zoom option.

Returns:
True if mousewheel zoom is turned on, false otherwise.

getNamedLayer

HTMLDivElement getNamedLayer( <String> name, <Integer> zIndex )

Gets a named layer for drawing overlays on. If a layer with the given name does not exist, and a zIndex value is passed in, then the layer will be created first. The following layers are created by the mapviewer by default and with these zIndexes:
• shadows - 999
• markers - 1000
• infobox - 1100
If creating a custom layer for custom overlays, a zIndex should always be passed.
Parameters:
name - Name of layer to create.
zIndex - Value to set for the zIndex of this layer, if it does not already exist.
Returns:
A layer, or nothing if the layer does not exist and no zIndex was passed.

---

getOption

mixed getOption( <String> name )

Get the value of an option.
Parameters:
name - Name of the option to get the value for.
Returns:
The value for the option.

---

getSmoothPanning

boolean getSmoothPanning()

DEPRECATED Use getOption( 'smoothpan' ) instead. Retrieves the current value for the smooth panning setting.
Returns:
True if smooth panning is enabled, false otherwise.

---

getVersion

String getVersion()

Returns a string describing the version of the API in use.
Returns:
A string describing the version of the API in use.

---

getXMLHTTPRequest

Object getXMLHTTPRequest()

Returns an XMLHTTPRequest object. This function takes away the browser-compatibility worries of creating an XMLHTTPRequest object. If you call this function you will receive the correct object regardless of which browser you are using (assuming your browser is supported).
Returns:
Browser specific XMLHTTPRequest object

---

getZoomDoubleClickable

boolean getZoomDoubleClickable()

DEPRECATED Use getOption( 'doubleclick' ) instead. Gets the current value for the 'zoom doubleclickable' property.
Returns:
True if the map is zoom doubleclickable, false if not.

---

getZoomDraggable

boolean getZoomDraggable()

DEPRECATED Use getOption( 'drag:shift' ) instead. Gets the current value for the 'zoom draggable' property.
Returns:
True if the map is zoom draggable, false if not.

---

getZoomFactor

integer getZoomFactor()

Function to return the current zoom_factor that the map is set to.
Returns:
The current zoom factor of the map.

---

goToPosition

void goToPosition( <MMLocation> new_pos, <integer> zoom_factor, <String> reason, <boolean> no_reset )

Centers the map on a new geographical position. If the position to which you are moving is within the mapviewer, and you have not requested an alternative zoom factor, this will smoothly pan the mapviewer; otherwise it will load a new set of tiles for the new location.
Parameters:
new_pos - New location to go to.
zoom_factor - Zoom factor that you want to display the map at, optional
reason - Reason code for the move, for logging purposes, should usually be left out.
no_reset - If true the position moved to by resetPosition is not updated to the position passed in.

---

manageLayout

void manageLayout( <HTMLElement> element )

Register that you want the API to manage the layout of a HTML element in Internet Explorer.
Parameters:
element - Element that you want to be managed.

---

mortonToTile

MMPoint mortonToTile( morton )

Takes a morton number and converts to a tile coordinate.
Parameters:
morton - Morton number for the given coordinate and zoom factor
Returns:
A tile coordinate.

---

moveMap

void moveMap( <MMPoint> new_step, <String> reason )

Move the map to a specified pixel offset. If the position to which you are moving is within the mapviewer, and you have not requested an alternative zoom factor, this will smoothly pan the mapviewer; otherwise it will load a new set of tiles for the new location. It assumes the origin is top left, so a positive X and Y value will move the center of the map down and to the right. This function will check to see if the offset that you are moving to is within the mapviewer and if it is will do a simple move action (which just moves the map tiles). This may or may not be a smooth animated move depending on whether or not smooth panning has been disabled. A positive X and Y value will move the center of the map down and to the right.
Parameters:
new_step - The amount to move, in pixels
reason - Reason code for the move, for logging purposes, should usually be left out.

---

moveMapMeters

void moveMapMeters( <MMPoint> new_step, <String> reason )

Moves the map to a position a number of meters away.
Parameters:
new_step - Offset from the center to move to, in metres
reason - Reason code for the move, for logging purposes, should usually be left out.

---

panToPosition

void panToPosition( <MMLocation> new_pos, <String> reason )

Allows the user to smoothly pan to a location, no matter how far away it is. Most instances should use goToPosition() instead.
Parameters:
new_pos - New position to pan to.
reason - Reason code for the move, for logging purposes, should usually be left out.

---

redisplayOverlay

Object redisplayOverlay( overlay )

redisplayOverlay is now an alias to addOverlay().

---

redrawMap

void redrawMap()

Redraws the mapviewer. Should be called after modifying data preferences.

---

removeAllOverlays

void removeAllOverlays()

A function to remove all overlays from the mapviewer that have been added by createMarker, createInfoBox and addOverlay().

---

removeEventHandler

boolean removeEventHandler( <String> eventType, <Function> handlerFunction )

Removes an event handler for the given type.
Parameters:
eventType - Type of the event being called.
handlerFunction - The event handling function.
Returns:
True if the event type was valid, false otherwise

---

removeOverlay

void removeOverlay( <MMOverlay> overlay )

A function to remove an overlay from the mapviewer. This function can be used for removing either markers or info boxes.
Parameters:
overlay - The overlay to be removed.

---

removeWidget

void removeWidget( <MMWidget> widget )

Removes a widget from the mapviewer.
Parameters:
widget - The widget to remove from the mapviewer.

---

resetPosition

MMLocation resetPosition()

Resets the position of the map to the last requested position. This uses the last position of the map as passed into goToPosition() or drawAndPositionMap()
Returns:
The new location (and zoom factor) of the map

---

resize

void resize( <MMPoint> resized_side )

This function alerts the mapviewer to a change in container size. It is called automatically when the page is resized. The container DIV is then queried to find out if it has changed size.
This should be used when an external method for resizing the mapviewer container is offered (perhaps via "bigger" and "smaller" links).
When calling by hand you may pass in an argument to specify what side of the viewer was modified. The default value is (1,1) to indicate that the new tiles should be loaded on the bottom right. A value of (0,0) can be used to indicate that new tiles should load on both sides. Also (-1,-1) can be used to indicate that new tiles should load on the top and left. Any combination of these values may be used.
Parameters:
resized_side - (optional) This parameter allows you to specify which side of the viewer has been resized.

---

setAllowedZoomFactors

Array setAllowedZoomFactors( <integer> minimum, <integer> maximum )

Sets the maximum and minimum zoom factors. Passing in undefined values will remove any previously set restrictions. Minimum and maximum values are inclusive so arguments of 1 and 4 would include 1, 2, 3 and 4.
Parameters:
minimum - (optional) Minimum zoom factor.
maximum - (optional) Maximum zoom factor.
Returns:
The resultant set of available zoom factors.

---

setDraggable

void setDraggable( <boolean> draggable )

DEPRECATED Use setOption( 'drag', 'dragmap' ) instead. This function sets the 'draggable' option of a map. This should be set to true if you wish the map to be draggable with the mouse or false if you do not.
Parameters:
draggable - The new setting.

---

setKeyboardPanning

void setKeyboardPanning( <boolean> value )

DEPRECATED Use setOption( 'keyboard', 'pan' ) instead. Enables or disables keyboard panning.
Parameters:
value - True to allow keyboard panning, false otherwise.

---

setMouseWheelZoom

void setMouseWheelZoom( <boolean> value )

DEPRECATED Use setOption( 'mousewheel:wheelup', 'zoomin ) and setOption( 'mousewheel:wheeldown', 'zoomout' ) instead. Enables or disables mousewheel zoom.
Parameters:
value - The value that you want to set this option to.

---

setOption

void setOption( <String> name, <String> value )

Set a mapviewer option.
Parameters:
name - Name of the option that you want to set.
value - Value that you want to give the option.

---

setOptions

void setOptions( <Array> options )

Set many options by passing in an object literal. The object literal should take the form of a hash with keys being the name of the option you want to set (including modifiers) and values being the value you want to give to the option. For example: { 'mousewheel:wheelup' : 'zoomin', 'drag:shift' : 'zoombox' }
Parameters:
options - Array of options to set.

---

setSmoothPanning

void setSmoothPanning( <boolean> smooth_panning )

DEPRECATED Use setOption( 'smoothpan', boolean ) instead. Allows you to specify whether or not smooth panning is enabled.
Parameters:
smooth_panning - True if you want smooth panning enabled, false otherwise.

---

setZoomDoubleClickable

void setZoomDoubleClickable( <boolean> doubleclick_zoom )

DEPRECATED Use setOption instead. Sets the 'zoom doubleclickable' property of the map. To enable full support for PC and Mac users you should use: setOption( 'doubleclick', 'zoomin' ); setOption( 'doubleclick:ctrl', 'zoomout' ); setOption( 'doubleclick:rightbutton', 'zoomout' );
Parameters:
doubleclick_zoom - The new setting

---

setZoomDraggable

void setZoomDraggable( <boolean> zoom_draggable )

DEPRECATED Use setOption( 'drag:shift', 'zoombox' ) instead. Sets the 'zoom draggable' property of the map. This should be true if you want to be able to press shift and drag the mouse to select an area to zoom in on.
Parameters:
zoom_draggable - The new setting

---

setZoomFactor

void setZoomFactor( <integer> new_zoom_factor, <String> reason )

Function to set the current zoom factor of the map.
Parameters:
new_zoom_factor - The desired zoom factor for the map.
reason - Reason code for the move, for logging purposes, should usually be left out.

---

tileToMorton

String tileToMorton( <MMPoint> tile, <integer> zoom_factor )

A method that can be used to convert tile coordinates into a morton number.
Parameters:
tile - Tile coordinates to convert.
zoom_factor - The zoom factor to use.
Returns:
A morton number for the given zoom factor and tile.

---

updateLayout

void updateLayout( <HTMLElement> el )

Updates the size of an element if the browser is <= IE6. This will do a single update; however, we advise that you use manageLayout instead.
Parameters:
el - The element to resize.

---

withinMoveLimits

boolean withinMoveLimits( <MMPoint> step )

A method to determine whether the requested move is within the limits of the mapviewer. This determines whether or not to perform a smooth pan. Note that it checks if the step is within a box twice as big as the mapviewer as it can confuse users if a point is just outside the mapviewer and a smooth pan does not occur. This is intended to be an internal function but may be useful externally
Parameters:
step - The amount that needs to be moved, in pixels
Returns:
True if the step is within the mapviewer's limits, false otherwise

---

zoom

integer zoom( <integer> amount, <String> reason, <MMPoint> pre_step, <MMPoint> post_step )

Zooms the map within the mapviewer. This method will zoom the map within the mapviewer by the specified amount. It will clip to the extents of coverage, and will do nothing if the map is already at the largest/smallest zoom factor where applicable.
A negative value will zoom in and a positive value will zoom out.
The pre- and post- step arguments allow you to move the map before and/or after the zoom. This facilitates some of the smooth zooming functionality and is unlikely to be used generally.
For example, if the mapviewer is displaying zoom factor 10 and you pass -4 to this method, the mapviewer will then display zoom factor 6.
Parameters:
amount - The number of factors to zoom in or out by
reason - Reason code for the move, for logging purposes, should usually be left out.
pre_step - (optional) The pixel position, relative to the center, that you want to zoom into.
post_step - (optional) The pixel position, relative to the center, that you want to zoom into.
Returns:
The resultant zoom factor

---

Overview  File   Class  Tree  Index  Help
PREV CLASS  NEXT CLASS	FRAMES    NO FRAMES
SUMMARY: FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---

Documentation generated by JSDoc on Tue Feb 26 16:25:19 2008