Class MapCanvas

This class is used to create a map selection/drawing canvas for a map image. The "Rubber Band Box" used to track the selection area is contained within the class variables. This class can be used on its own, to load/display static map images, or can be used as a superclass for other canvas types to allow more dynamic maps.

To better facilitate single-click events, dragging a box doesn't start until the mouse has been dragged five pixels. Clicking on the canvas by default will clear the box, but this can be disabled.


Constructor Summary

MapCanvas ( container , inputGrid )
Create a new canvas object and initialize it.

Method Summary

loadImage ( newImage , newUseImageSize )
Load a new static image to display for the canvas
getImageSize ( )
Returns the dimensions of the canvas image.
getRBB ( )
Returns the RubberBandBox object contained in the canvas.
getCanvas ( )
Returns the Canvas surface object.
loadGrid ( newGrid , newRowOffset , newColOffset )
Loads a new projection grid to use for the canvas.
setClearOnClick ( newClick )
Chooses whether a single click on the canvas will clear the boxes.
setShowXY ( newShow )
Chooses whether to display the green XY box.
setShowLatLon ( newShow )
Chooses whether to display the red lat/lon box.
setShowSperhicalRectangle ( newShow )
Chooses whether to display the yellow spherical XY box.
setShowRowCol ( newShow )
Chooses whether to display the white row/col box.
setXYFromLatLonPolygon ( polygon )
Resets the XYBox values (and thus, all other values from there) to match as closely as possible the input polygon.
adjustLatLonParam ( param , newValue )
Adjusts one of the latitude/longitude parameters, and updates the boxes accordingly.
xyToLatLon ( x , y , lat , lon )
Converts an XY point to a Latitude/Longitude point
xyToRowCol ( x , y , row , col , truncit )
Converts an XY point to a row/col coordinate
latLonToXY ( lat , lon , x , y )
Converts a latitude/longitude point to an XY point on the map
latLonToRowCol ( lat , lon , row , col )
Converts a latitude/longitude point to a row/col coordinate
rowColToXY ( row , col , x , y )
Converts a row/col coordinate to an XY point on the map
rowColToLatLon ( row , col , lat , lon )
Converts a row/col coordinate to a lat/lon point on the map
addLatLonListener ( newListener )
Adds a listener function that will receive lat/lon information when a box is created.
addLatLonPolygonListener ( newListener )
Adds a listener function that will receive information for a lat/lon polygon when a box is created.
addRowColListener ( newListener )
Adds a listener function that will receive row/col information when a box is created.
addMousePosListener ( newListener )
Adds a listener function that will receive moust position information when the mouse is moved over the canvas
addDblClickListener ( newListener , newObject )
Adds a listener function that will receive information when a double-click event is triggered over the canvas
addSingleClickListener ( newListener , newObject )
Adds a listener function that will receive information when a single-click event is triggered over the canvas
addImgLoadListener ( newListener )
Adds a listener function that will receive information when an image load is completed.
getMoreMousePosInfo ( fullpoint )
Adds more information to a point, depending on the MapCanvas child class.
getMoreBoxInfo ( boxinfo )
Adds more Rubber Band Box information, depending on the MapCanvas child class
clearBox ( )
Clears and resets the RBB boxes.

Constructor Detail

MapCanvas

Create a new canvas object and initialize it.


Parameters
container - An HTML DOM container object, usually a DIV, that will contain the canvas
inputGrid - optional; a Grids object (see Grids) used to map the image with it's appropriate projection.


Returns
A new MapCanvas object.

Examples
var mc = new MapCanvas(somediv, somegrid);
// Will create a new MapCanvas object to be contained by the
// somediv object on the page, with the projection defined in
// somegrid.

Notes
The container parameter must be the actual container object, not just the tag id. The container must be capable of having images included within them. If inputGrid is not specified, conversions between map coordinates and geographic coordinates will not be possible, but the grid can be loaded later using loadGrid.

Method Detail

loadImage

Load a new static image to display for the canvas


Parameters
newImage - The URL to the image to be used
newUseImageSize - Boolean, true if the DIV should be stretched to match the size of the image

Returns
False if the newImage is not defined, True otherwise.

Examples
mc.loadImage(imgURL, true);
// This will load the image found at imgURL, and will cause the
// container to be stretched/shrunk to match the image size

Notes
This function does it's work asynchronously using AJAX. While the image URL is being loaded, a red box saying "LOADING" will appear on the canvas to indicate to the user that a new image is being processed. If the browser caches images, and a previously used image is chosen, the load time may be very short, and LOADING may not be displayed for very long. If newUseImageSize is set to false, the image will be stretched and possibly distorted to fit within the container. Note, however, that if this happens, the underlying grid will still map correctly, as the rubber band box will also be distorted to match.


getImageSize

Returns the dimensions of the canvas image.


Parameters
None.

Returns
An object with "width" and "height" parameters, or null if the map image is not defined.

Examples
var imgdim = mc.getImageSize();
// imgdim.width will have the width, imgdim.height will have the
// height of the image

Notes
The returned object is created by the method, so it does not need to be preallocated with width and height parameters.


getRBB

Returns the RubberBandBox object contained in the canvas.


Parameters
None.

Returns
The RubberBandBox object.

Examples
var rbb = mc.getRBB();

Notes
Generally, client code will not need to use this method, as interacting with the rubber band box object is generally done through the Canvas itself. However, this method is important when creating child class Canvas definitions, as the box object itself is not directly visible to child classes due to the way JavaScript scoping works. Thus, if a child Canvas needs to interact with the box, this method will allow it to do so. If not creating child Canvas objects, however, you will probably want to avoid using this directly.


getCanvas

Returns the Canvas surface object.


Parameters
None.

Returns
The Canvas object.

Examples
var canvas = mc.getCanvas();

Notes
Generally, client code will not need to use this method, as most surface functionality is handled internally. Due to JavaScript scoping issues, this method had to be made public for some event handling. This would also be necessary when writing child class definitions to allow access to the canvas object, which is not directly visible to child classes due to the same JavaScript scoping issues. Generally, though, avoid using this method externally.


loadGrid

Loads a new projection grid to use for the canvas.


Parameters
newGrid - The Grids object containing the projection
newRowOffset - Used if the top-left corner's "row" parameter should be something other than 0
newColOffset - Used if the top-left corner's "col" parameter should be something other than 0

Returns
False if newGrid is not defined, True otherwise.

Examples
mc.loadGrid(newGrid, 1.1, 1.2);
// This will load the newGrid projection, and set the top left
// corner's row/col offset information.

Notes
The newGrid object must be completely defined prior to loading it into the canvas object. The newRowOffset and newColOffset parameters are optional, and are set to 0 if not used. These parameters are useful for situations where the image displayed does not represent the entire bounds that the "grid" represents, such as with "zoomed" images. The numbers need not be integers.


setClearOnClick

Chooses whether a single click on the canvas will clear the boxes.


Parameters
newClick - Boolean. Determines whether the click will clear the boxes.

Returns
None.

Examples
mc.setClearOnClick(true);  // single-clicks will clear the boxes
mc.setClearOnClick(false); // single-clicks don't clear the boxes

Notes
This allows the client programs to decide whether or not to automatically allow for single-click box clearing. By default this is set to true.


setShowXY

Chooses whether to display the green XY box.


Parameters
newShow - Boolean. Determines whether the box will be shown.

Returns
None.

Examples
mc.setShowXY(true);     // causes the green XY box to be shown
mc.setShowXY(false); // causes the green XY box to be hidden

Notes
See the RubberBandBox class for more details on what the box is for. This method merely deleages the call to the RubberBandBox object.


setShowLatLon

Chooses whether to display the red lat/lon box.


Parameters
newShow - Boolean. Determines whether the box will be shown.

Returns
None.

Examples
mc.setShowLatLon(true); // causes the red lat/lon box to be shown
mc.setShowLatLon(false);// causes the red lat/lon box to be hidden

Notes
See the RubberBandBox class for more details on what the box is for. This method merely deleages the call to the RubberBandBox object.


setShowSperhicalRectangle

Chooses whether to display the yellow spherical XY box.


Parameters
newShow - Boolean. Determines whether the box will be shown.

Returns
None.

Examples
mc.setShowSphericalRectangle(true);
// causes the yellow spherical rectangle box to be shown
mc.setShowSphericalRectagle(false);
// causes the yellow spherical rectangle box to be hidden

Notes
See the RubberBandBox class for more details on what the box is for. This method merely deleages the call to the RubberBandBox object.


setShowRowCol

Chooses whether to display the white row/col box.


Parameters
newShow - Boolean. Determines whether the box will be shown.

Returns
None.

Examples
mc.setShowRowCol(true);
// causes the white row/col box to be shown
mc.setShowRowCol(false);
// causes the white row/col box to be hidden

Notes
See the RubberBandBox class for more details on what the box is for. This method merely deleages the call to the RubberBandBox object.


setXYFromLatLonPolygon

Resets the XYBox values (and thus, all other values from there) to match as closely as possible the input polygon.


Parameters
polygon - A string or an array representing the polygon

Returns
False if the internal grids are not defined, True otherwise. (If the internal grids are not defined, the polygon cannot be properly processed)

Examples
rbb.setXYFromLatLonPolygon("50,50,50,100,100,100,100,50,50,50");
// string form
rbb.setXYFromLatLonPolygon(50,50,50,100,100,100,100,50,50,50);
// array of integers form
rbb.setXYFromLatLonPolygon(pt1, pt2, pt3, pt4, pt1);
// array of Points form

Notes
If the RubberBandBox object is not initialized (usually because no grid is loaded), or if the input polygon does not match one of the formats listed here, the method will return quietly.
The input value can be a string, or one of two types of array.
A string should be in "lt0,ln0,lt1,ln1,lt2,ln2,lt3,ln3,lt0,ln0" format. (lt is latitude, ln is longitude).
An array of integers should be in the same order as a string, but sent as an array of floating points instead.
An array of points should be in pt0,pt1,pt2,pt3,pt0 order, where each point has both lat and lon properties.


adjustLatLonParam

Adjusts one of the latitude/longitude parameters, and updates the boxes accordingly.


Parameters
param - "north", "south", "west", or "east", the parameter to adjust
newValue - The new value of the parameter

Returns
None.

Examples
mc.adjustLatLonParam('north', 70.2);
// sets the NORTH value of the boxes to 70.2

Notes
If the RubberBandBox object is not initialized (usually because no grid is loaded), or if param does not match one of the above values, the method will return quietly. The newValue parameter will be converted to legal latitude or longitude values, if necessary. If a north value is given that is further south than the current south value, the south value will be made to the north value, and the newValue will be put as the south value. This is true for any "overlap" of parameters.


xyToLatLon

Converts an XY point to a Latitude/Longitude point


Parameters
x - The x coordinate to convert
y - The y coordinate to convert
lat - An array that will contain the latitude at [0]
lon - An array that will contain the longitude at [0]

Returns
A boolean that is true if the conversion was successful.

Examples
var ok = mc.xyToLatLon(100, 100, newlat, newlon);
// The latitude will be at newlat[0], the longitude will be at
// newlon[0]. ok will be true if there were no errors.

Notes
If there is no grid initilized, this will return false. Otherwise, it will use the grid to convert from x/y coordinates to lat/lon coordinates. The lat and lon arrays must be created before calling this method.


xyToRowCol

Converts an XY point to a row/col coordinate


Parameters
x - The x coordinate to convert
y - The y coordinate to convert
row - An array that will contain the row at [0]
col - An array that will contain the column at [0]
truncit - A boolean indicating whether the row/col values should be integers or "exact" coordinates. (True means it will be truncated to an integer)

Returns
A boolean that is true if the conversion was successful.

Examples
var ok = mc.xyToRowCol(100, 100, newrow, newcol, true);
// The row will be at newrow[0], the column will be at newcol[0]
// and both will be truncated to integers.

Notes
If there is no grid initilized, this will return false. Otherwise, it will use the grid to convert from x/y coordinates to row/col coordinates. The row and col arrays must be created before calling this method. Using truncit is good for when the grid itself is very course and you want to get "tile"-type information for a specific point.


latLonToXY

Converts a latitude/longitude point to an XY point on the map


Parameters
lat - The latitude to convert
lon - The longitude to convert
x - An array that will contain the x coordinate at [0]
y - An array that will contain the y coordinate at [0]

Returns
A boolean that is true if the conversion was successful.

Examples
var ok = mc.latLonToXY(30.2, 51.3, newx, newy);
// newx[0] and newy[0] will contain the XY coordinate of the
// point at 30.2 north, 51.3 east.

Notes
If there is no grid initialized, this will return false. Otherwise, it will use the grid to convert from lat/lon coordinates to x/y coordinates. The x and y arrays must be created before calling this method.


latLonToRowCol

Converts a latitude/longitude point to a row/col coordinate


Parameters
lat - The latitude to convert
lon - The longitude to convert
row - An array that will contain the row at [0]
col - An array that will contain the column at [0]

Returns
A boolean that is true if the conversion was successful.

Examples
var ok = mc.latLonToRowCol(30.2, 51.3, newrow, newcol);
// newrow[0] and newcol[0] will contain the row/col coordinate
// of the point at 30.2 north, 51.3 east.

Notes
If there is no grid initialized, this will return false. Otherwise, it will use the grid to convert from lat/lon coordinates to row/col coordinates. The row and col arrays must be created before calling this method.


rowColToXY

Converts a row/col coordinate to an XY point on the map


Parameters
row - The row to convert
col - The column to convert
x - An array that will contain the x coordinate at [0]
y - An array that will contain the y coordinate at [0]

Returns
A boolean that is true if the conversion was successful.

Examples
var ok = mc.rowColToXY(8.3, 3.2, newx, newy);
// newx[0] and newy[0] will contain the XY coordinate of the
// grid row 8.3, column 3.2 on the map.

Notes
If there is no grid initialized, this will return false. Otherwise, it will use the grid to convert from row/col coordinates to x/y coordinates. The x and y arrays must be created before calling this method.


rowColToLatLon

Converts a row/col coordinate to a lat/lon point on the map


Parameters
row - The row to convert
col - The column to convert
lat - An array that will contain the latitude at [0]
lon - An array that will contain the longitude at [0]

Returns
A boolean that is true if the conversion was successful.

Examples
var ok = mc.rowColToLatLon(8.3, 3.2, newlat, newlon);
// newlat[0] and newlon[0] will contain the lat/lon coordinate
// of grid row 8.3, column 3.2 on the map.

Notes
If there is no grid initialized, this will return false. Otherwise, it will use the grid to convert from row/col coordinates to lat/lon coordinates. The lat and lon arrays must be created before calling this method.


addLatLonListener

Adds a listener function that will receive lat/lon information when a box is created.


Parameters
newListener - The function that will receive the information

Returns
None.

Examples
mc.addLatLonListener(newLLfunc);
// adds newLLfunc to the listener list for the class

Notes
The newListener should be the function itself, not just a string containing the name. The listener is actually processed by the RubberBandBox object, so see RubberBandBox.addLatLonListener for more details on what is returned. If no RubberBandBox object is initialized (such as when no grid is loaded), this method just exits quietly.


addLatLonPolygonListener

Adds a listener function that will receive information for a lat/lon polygon when a box is created.


Parameters
newListener - The function that will receive the information

Returns
None.

Examples
mc.addLatLonPolygonListener(newLLPfunc);
// adds newLLPfunc to the listener list for the class

Notes
The newListener should be the function itself, not just a string containing the name. The listener is actually processed by the RubberBandBox object, so see RubberBandBox.addLatLonPolygonListener for more details on what is returned. If no RubberBandBox object is initialized (such as when no grid is loaded), this method just exits quietly.


addRowColListener

Adds a listener function that will receive row/col information when a box is created.


Parameters
newListener - The function that will receive the information

Returns
None.

Examples
mc.addRowColListener(newRCfunc);
// adds newRCfunc to the listener list for the class

Notes
The newListener should be the function itself, not just a string containing the name. The listener is actually processed by the RubberBandBox object, so see RubberBandBox.addRowColListener for more details on what is returned. If no RubberBandBox object is initialized (such as when no grid is loaded), this method just exits quietly.


addMousePosListener

Adds a listener function that will receive moust position information when the mouse is moved over the canvas


Parameters
newListener - The function that will receive the information

Returns
None.

Examples
mc.addMousePosListener(newMousefunc);
// adds newLLfunc to the listener list for the class

Notes
The newListener should be the function itself, not just a string containing the name. Upon processing a mouse move event, the MapCanvas will go through each listener attached to it, and call the listener with one parameter: an object containing the point information. This object will contain "x", "y", "lat", and "lon" fields, as well as any additional fields that are specific to the MapCanvas subclass. (The base MapCanvas class has no additional fields).


addDblClickListener

Adds a listener function that will receive information when a double-click event is triggered over the canvas


Parameters
newListener - The function that will receive the information
newObject - The object that will be returned with the info

Returns
None.

Examples
mc.addDblClickListener(newDCfunc, this);
// adds newDCfunc to the listener list for the class, and will
// return "this" with the event

Notes
The newListener should be the function itself, not just a string containing the name. Upon processing a double click event, the MapCanvas will go through each listener, and call the listener with two parameters: a point object, and the newObject given. The point object contains "x" and "y" fields, corresponding to the location of the mouse when the event is triggered, as well as "lat" and "lon" for the coordinates, "fullrow", "fullcol", "row" and "col" which are the grid coordinates (and truncated versions) at the coordinate, and any other point information returned by getMoreMousePosInfo. The newObject is returned for context. This is done because of the way JavaScript scoping works.
The MapCanvas base class does not do anything with double-clicks, but some child classes may wantto do specific things depending on the class. Returning theobject allows the child class to act on it. Often, this listener will be set up inside the child class itself, so that when the event happens, the child class can handle it.
Usually, you will not need to use this outside of a class, as most often this is just for internal use, but it can be used externally if needed.


addSingleClickListener

Adds a listener function that will receive information when a single-click event is triggered over the canvas


Parameters
newListener - The function that will receive the information
newObject - The object that will be returned with the info

Returns
None.

Examples
mc.addSingleClickListener(newSCfunc, this);
// adds newSCfunc to the listener list for the class, and will
// return "this" with the event

Notes
The newListener should be the function itself, not just a string containing the name. Upon processing a single click event, the MapCanvas will go through each listener, and call the listener with two parameters: a point object, and the newObject given. The point object contains "x" and "y" fields, corresponding to the location of the mouse when the event is triggered, as well as "lat" and "lon" for the coordinates, "fullrow", "fullcol", "row" and "col" which are the grid coordinates (and truncated versions) at the coordinate, and any other point information returned by getMoreMousePosInfo. The newObject is returned for context. This is done because of the way JavaScript scoping works.
The MapCanvas base class does not do anything with single-clicks, but some child classes may wantto do specific things depending on the class. Returning theobject allows the child class to act on it. Often, this listener will be set up inside the child class itself, so that when the event happens, the child class can handle it.
Usually, you will not need to use this outside of a class, as most often this is just for internal use, but it can be used externally if needed.
Note that double-clicking will cause two single-clicks to also be fired, so if you have code that relies on both, you may need to account for that.


addImgLoadListener

Adds a listener function that will receive information when an image load is completed.


Parameters
newListener - The function that will be called

Returns
None.

Examples
mc.addImgLoadListener(newILfunc);
// adds newILfun to the listener list

Notes
The newListener should be the function itself, not just a string containing the name. When an image load is complete, the MapCanvas will go through each listener, and call it. No parameters are passed to the functions; it is merely a notification. This function could be useful if you want to send additional commands to the MapCanvas, but wish to wait until the image is done loading before doing so.


getMoreMousePosInfo

Adds more information to a point, depending on the MapCanvas child class.


Parameters
fullpoint - The point to add information to

Returns
None.

Examples
this.getMoreMousePosInfo(thispoint);
// Will add more info to thispoint

Notes
In MapCanvas itself, this method does nothing, no additional info is added. However, new fields can be added to the fullpoint object by sub-classes that use this method. It will be called after every mouse move (but only if there is a mouse listener). Usually, you will never need to call this method outside of the child class, but due to the way JavaScript scoping works, this must be a public method for the child class to utilize it.


getMoreBoxInfo

Adds more Rubber Band Box information, depending on the MapCanvas child class


Parameters
boxinfo - The current box information to be modified

Returns
None.

Examples
parent.getMoreBoxInfo(thisbox);
// Will add more info to thisbox

Notes
In MapCanvas itself, this method does nothing, no additional info is added. However, new fields can be added to the boxinfo object by child classes that use this method. This will be called by the contained RubberBandBox object after a new box is created on the map (if there is at least one listener). Usually, you will never need to call this method yourself, even in a child class, but due to the way JavaScript scoping works, this must be a public method for the RubberBandBox object to utilize it.


clearBox

Clears and resets the RBB boxes.


Parameters
None.

Returns
None. (The Boxes will be cleared and event notifications sent)

Examples
mc.clearBox();  // Resets the rubberband boxes

Notes
This is useful for situations where the user may want to cancel any selection they have made on the map. By calling this method, the selection will be cleared and new event notifications will be sent to any listeners for the various boxes.