Class MMViewer

Object
   |
   +--MMViewer

Direct Known Subclasses:

MultimapViewer

class MMViewer

Defined in MultimapAPI

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 eventhandler should be of the format: function( eventType, eventTarget, more args... ) Where eventType is one of the types that can be passed to this function and eventTarget is the element on which the event has 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
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
drag	mapviewer
startPan	mapviewer
endPan	mapviewer	start position	end position	reason for the pan
addOverlay	overlay
removeOverlay	overlay
removeAllOverlays	mapviewer
openInfoBox	overlay
closeInfoBox	overlay
startGeocode	mapviewer	location being geocoded
endGeocode	mapviewer	location that was geocoded	error code if there was a problem

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

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

addOverlay

boolean addOverlay( <MMOverlay> overlay )

A function to (re)display an overlay (marker/info box) that you have a reference for but have previously removed from the mapviewer. If the overlay is actually already within the mapviewer then nothing will happen.

Parameters:
overlay - The overlay to be (re)displayed

Returns:
True if the overlay was redisplayed, false if it was already there

addTileOverlayCallback

void addTileOverlayCallback( <Function> callback_function )

Adds an image overlay callback function. There are times when a second set of map tiles will need to be overlaid on top of the normal map tiles. In this case we provide this method to developers. The only argument is a function that needs to be called for every tile that is placed on the map. This function will be passed the arguments: position (MMPoint) and zoom_factor and needs to return either a HTML object or undefined.

Parameters:
callback_function - The callback function to be added

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. There are times when you will not want the default map actions to occur such as for the HTML within an info box. If you call this function passing in the HTML element you want the actions to not occur on it will assign new handlers for the element that will ensure that the map mapviewer ignores events initiated from within this HTML element.

Parameters:
element - HTML Element

drawAndPositionMap

void 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

geoPosToContainerPixels

MMPoint geoPosToContainerPixels( <MMLatLon> position )

Gives the position within the mapviewer of the given position given in an appropriate coordinate system.

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 of geographic points (or both).

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.

Returns:
An array of available zoom factor values.

getBrowserDimensions

MMDimensions getBrowserDimensions()

Function for getting the dimensions of the browser, 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

getDimensions

MMDimensions getDimensions()

A method to retrieve the dimensions of the mapviewer.

Returns:
The dimensions of the mapviewer.

getDraggable

boolean getDraggable()

Gets the current value for the 'draggable' property.

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

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()

Retrieves the setting of the keyboard panning option.

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

getMouseWheelZoom

boolean getMouseWheelZoom()

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.

---

getSmoothPanning

boolean getSmoothPanning()

Retrieves the current value for the smooth panning setting.
Returns:
True if smooth panning is enabled, false otherwise.

---

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()

Gets the current value for the 'zoom doubleclickable' property.
Returns:
True if the map is zoom doubleclickable, false if not.

---

getZoomDraggable

boolean getZoomDraggable()

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.

---

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 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().

---

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.

---

removeTileOverlayCallback

void removeTileOverlayCallback( <Function> callback_function )

Removes an image overlay callback function. Removes a callback function registered with addTileOverlayCallback(). Note that this does not remove any overlays added by the callback which should be removed externally by the developer.
Parameters:
callback_function - The callback function 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( )

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.
Any website developer who provides a mechanism for resizing the DIV container (perhaps via "bigger or smaller" links) should call this method.

---

setDraggable

void setDraggable( <boolean> draggable )

This function sets the 'draggable' property 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 )

Enables or disables keyboard panning.
Parameters:
value - True to allow keyboard panning, false otherwise.

---

setMouseWheelZoom

void setMouseWheelZoom( <boolean> value )

Enables or disables mousewheel zoom.
Parameters:
value - The value that you want to set this option to.

---

setSmoothPanning

void setSmoothPanning( <boolean> smooth_panning )

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 )

Sets the 'zoom doubleclickable' property of the map. This should be true if you want to be able the map to zoom in or out when you double click. Left double click will zoom in, left double click + shift will zoom out, right double click will also zoom out.
Parameters:
doubleclick_zoom - The new setting

---

setZoomDraggable

void setZoomDraggable( <boolean> zoom_draggable )

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.

---

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 )

Zooms the map within the mapviewer. This method will zoom the map within the mapviewer by the specified delta. It will clip to the extents of coverage, and will do nothing if we are already at the largest/smallest zoom factor where applicable.
A negative value will zoom in and a positive value will zoom out.
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.
Returns:
The resultant zoom factor, or -1 if there is no change

---

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 Wed Aug 16 15:33:06 2006