ALKMaps.Layer.Grid

Base class for layers that use a lattice of tiles.  Create a new grid layer with the ALKMaps.Layer.Grid constructor.

Inherits from

  • <ALKMaps.Layer.HTTPRequest>
Summary
ALKMaps.Layer.GridBase class for layers that use a lattice of tiles.
Properties
tileSize{ALKMaps.Size}
tileOriginCorner{String} If the tileOrigin property is not provided, the tile origin will be derived from the layer’s maxExtent.
tileOrigin{ALKMaps.LonLat} Optional origin for aligning the grid of tiles.
tileOptions{Object} optional configuration options for ALKMaps.Tile instances created by this Layer, if supported by the tile class.
tileClass{ALKMaps.Tile} The tile class to use for this layer.
grid{Array(Array(ALKMaps.Tile))} This is an array of rows, each row is an array of tiles.
singleTile{Boolean} Moves the layer into single-tile mode, meaning that one tile will be loaded.
ratio{Float} Used only when in single-tile mode, this specifies the ratio of the size of the single tile to the size of the map.
buffer{Integer} Used only when in gridded mode, this specifies the number of extra rows and columns of tiles on each side which will surround the minimum grid tiles to cover the map.
transitionEffect{String} The transition effect to use when the map is zoomed.
numLoadingTiles{Integer} How many tiles are still loading?
tileLoadingDelay{Integer} Number of milliseconds before we shift and load tiles when panning.
serverResolutions{Array(Number}} This property is documented in subclasses as an API property.
moveTimerId{Number} The id of the deferMoveGriddedTiles timer.
deferMoveGriddedTiles{Function} A function that defers execution of moveGriddedTiles by tileLoadingDelay.
tileQueueId{Number} The id of the drawTileFromQueue animation.
tileQueue{Array(ALKMaps.Tile)} Tiles queued for drawing.
loading{Boolean} Indicates if tiles are being loaded.
backBuffer{DOMElement} The back buffer.
gridResolution{Number} The resolution of the current grid.
backBufferResolution{Number} The resolution of the current back buffer.
backBufferLonLat{Object} The top-left corner of the current back buffer.
backBufferTimerId{Number} The id of the back buffer timer.
removeBackBufferDelay{Number} Delay for removing the backbuffer when all tiles have finished loading.
className{String} Name of the class added to the layer div.
Constructor
ALKMaps.Layer.GridCreate a new grid layer
Functions
setMap
removeMapCalled when the layer is removed from the map.
destroyDeconstruct the layer and clear the grid.
clearGridGo through and remove all tiles from the grid, calling destroy() on each of them to kill circular references
cloneCreate a clone of this layer
moveToThis function is called whenever the map is moved.
getTileDataGiven a map location, retrieve a tile and the pixel offset within that tile corresponding to the location.
queueTileDrawAdds a tile to the animation queue that will draw it.
drawTileFromQueueDraws the first tile from the tileQueue, and unqueues that tile
clearTileQueueClears the animation queue
destroyTile
getServerResolutionReturn the closest highest server-supported resolution.
getServerZoomReturn the zoom value corresponding to the best matching server resolution, taking into account serverResolutions and <zoomOffset>.
transformDivTransform the layer div.
getResolutionScaleReturn the value by which the layer is currently scaled.
applyBackBufferCreate, insert, scale and position a back buffer for the layer.
createBackBufferCreate a back buffer.
removeBackBufferRemove back buffer from DOM.
moveByPxMove the layer based on pixel vector.
setTileSizeCheck if we are in singleTile mode and if so, set the size as a ratio of the map size (as specified by the layer’s ‘ratio’ property).
getTilesBoundsReturn the bounds of the tile grid.
initSingleTile
calculateGridLayoutGenerate parameters for the grid layout.
getTileOriginDetermine the origin for aligning the grid of tiles.
initGriddedTiles
getMaxExtentGet this layer’s maximum extent.
addTileCreate a tile, initialize it, and add it to the layer div.
addTileMonitoringHooksThis function takes a tile as input and adds the appropriate hooks to the tile so that the layer can keep track of the loading tiles.
removeTileMonitoringHooksThis function takes a tile as input and removes the tile hooks that were added in addTileMonitoringHooks()
moveGriddedTiles
shiftRowShifty grid work
shiftColumnShift grid work in the other dimension
removeExcessTilesWhen the size of the map or the buffer changes, we may need to remove some excess rows and columns.
onMapResizeFor singleTile layers, this will set a new tile size according to the dimensions of the map pane.
getTileBoundsReturns The tile bounds for a layer given a pixel location.

Properties

tileSize

tileOriginCorner

{String} If the tileOrigin property is not provided, the tile origin will be derived from the layer’s maxExtent.  The corner of the maxExtent used is determined by this property.  Acceptable values are “tl” (top left), “tr” (top right), “bl” (bottom left), and “br” (bottom right).  Default is “bl”.

tileOrigin

{ALKMaps.LonLat} Optional origin for aligning the grid of tiles.  If provided, requests for tiles at all resolutions will be aligned with this location (no tiles shall overlap this location).  If not provided, the grid of tiles will be aligned with the layer’s maxExtent.  Default is ``null``.

tileOptions

{Object} optional configuration options for ALKMaps.Tile instances created by this Layer, if supported by the tile class.

tileClass

{ALKMaps.Tile} The tile class to use for this layer.  Defaults is ALKMaps.Tile.Image.

grid

{Array(Array(ALKMaps.Tile))} This is an array of rows, each row is an array of tiles.

singleTile

{Boolean} Moves the layer into single-tile mode, meaning that one tile will be loaded.  The tile’s size will be determined by the ‘ratio’ property.  When the tile is dragged such that it does not cover the entire viewport, it is reloaded.

ratio

{Float} Used only when in single-tile mode, this specifies the ratio of the size of the single tile to the size of the map.

buffer

{Integer} Used only when in gridded mode, this specifies the number of extra rows and columns of tiles on each side which will surround the minimum grid tiles to cover the map.  For very slow loading layers, a larger value may increase performance somewhat when dragging, but will increase bandwidth use significantly.

transitionEffect

{String} The transition effect to use when the map is zoomed.  Two possible values:

nullNo transition effect (the default).
”resize”Existing tiles are resized on zoom to provide a visual effect of the zoom having taken place immediately.  As the new tiles become available, they are drawn over top of the resized tiles.

Using “resize” on non-opaque layers can cause undesired visual effects.  This is therefore discouraged.

numLoadingTiles

{Integer} How many tiles are still loading?

tileLoadingDelay

{Integer} Number of milliseconds before we shift and load tiles when panning.  Ignored if <ALKMaps.Animation.isNative> is true.  Default is 85.

serverResolutions

{Array(Number}} This property is documented in subclasses as an API property.

moveTimerId

{Number} The id of the deferMoveGriddedTiles timer.

deferMoveGriddedTiles

{Function} A function that defers execution of moveGriddedTiles by tileLoadingDelay.  If <ALKMaps.Animation.isNative> is true, this is null and unused.

tileQueueId

{Number} The id of the drawTileFromQueue animation.

tileQueue

{Array(ALKMaps.Tile)} Tiles queued for drawing.

loading

{Boolean} Indicates if tiles are being loaded.

backBuffer

{DOMElement} The back buffer.

gridResolution

{Number} The resolution of the current grid.  Used for backbuffering.  This property is updated each the grid is initialized.

backBufferResolution

{Number} The resolution of the current back buffer.  This property is updated each time a back buffer is created.

backBufferLonLat

{Object} The top-left corner of the current back buffer.  Includes lon and lat properties.  This object is updated each time a back buffer is created.

backBufferTimerId

{Number} The id of the back buffer timer.  This timer is used to delay the removal of the back buffer, thereby preventing flash effects caused by tile animation.

removeBackBufferDelay

{Number} Delay for removing the backbuffer when all tiles have finished loading.  Can be set to 0 when no css opacity transitions for the olTileImage class are used.  Default is 0 for singleTile layers, 2500 for tiled layers.  See className for more information on tile animation.

className

{String} Name of the class added to the layer div.  If not set in the options passed to the constructor then className defaults to “olLayerGridSingleTile” for single tile layers (see singleTile), and “olLayerGrid” for non single tile layers.

Note

The displaying of tiles is not animated by default for single tile layers - ALKMaps’ default theme (style.css) includes this:

.olLayerGrid .olTileImage {
    -webkit-transition: opacity 0.2s linear;
    -moz-transition: opacity 0.2s linear;
    -o-transition: opacity 0.2s linear;
    transition: opacity 0.2s linear;
 }

To animate tile displaying for any grid layer the following CSS rule can be used:

.olTileImage {
    -webkit-transition: opacity 0.2s linear;
    -moz-transition: opacity 0.2s linear;
    -o-transition: opacity 0.2s linear;
    transition: opacity 0.2s linear;
}

In that case, to avoid flash effects, removeBackBufferDelay should not be zero.

Constructor

ALKMaps.Layer.Grid

Create a new grid layer

Parameters

name{String}
url{String}
params{Object}
options{Object} Hashtable of extra options to tag onto the layer

Register a listener for a particular event with the following syntax

layer.events.register(type, obj, listener);

// Sample code for handling NULL tiles.
layer.events.register("tileloaded", layer, function(e){
    var w = 0, h = 0, img = e.tile.imgDiv;
    if(typeof img.naturalWidth === "undefined"){
       // IE 6/7/8
       var tempImg = new Image();
       tempImg.src = img.src;
       w = tempImg.width;
       h = tempImg.height;
    }
    else{
       // HTML5 browsers
      w = img.naturalWidth;
      h = img.naturalHeight;
    }
    if (w <=0 || h <=0) {
       // Set blank image and hide it.
       e.tile.setImgSrc(ALKMaps.Util.getImageLocation("blank.gif"));
       // e.tile.imgDiv.src = e.tile.blankImageUrl;
    }
});

Listeners will be called with a reference to an event object.  The properties of this event depends on exactly what happened.

All event objects have at least the following properties

object{Object} A reference to layer.events.object.
element{DOMElement} A reference to layer.events.element.

Supported event types

tileloadstartTriggered when a tile starts loading.  Listeners receive an object as first argument, which has a tile property that references the tile that starts loading.
tileloadedTriggered when each new tile is loaded, as a means of progress update to listeners. listeners can access ‘numLoadingTiles’ if they wish to keep track of the loading progress.  Listeners are called with an object with a tile property as first argument, making the loded tile available to the listener.
tileerrorTriggered before the tileloaded event (i.e. when the tile is still hidden) if a tile failed to load.  Listeners receive an object as first argument, which has a tile property that references the tile that could not be loaded.

Functions

setMap

setMap: function(map)

Parameters

map{ALKMaps.Map} The map.

removeMap

removeMap: function(map)

Called when the layer is removed from the map.

Parameters

map{ALKMaps.Map} The map.

destroy

destroy: function()

Deconstruct the layer and clear the grid.

clearGrid

clearGrid:function()

Go through and remove all tiles from the grid, calling destroy() on each of them to kill circular references

clone

clone: function (obj)

Create a clone of this layer

Parameters

obj{Object} Is this ever used?

Returns

{ALKMaps.Layer.Grid} An exact clone of this ALKMaps.Layer.Grid

moveTo

moveTo:function(bounds,
zoomChanged,
dragging)

This function is called whenever the map is moved.  All the moving of actual ‘tiles’ is done by the map, but moveTo’s role is to accept a bounds and make sure the data that that bounds requires is pre-loaded.

Parameters

bounds{ALKMaps.Bounds}
zoomChanged{Boolean}
dragging{Boolean}

getTileData

getTileData: function(loc)

Given a map location, retrieve a tile and the pixel offset within that tile corresponding to the location.  If there is not an existing tile in the grid that covers the given location, null will be returned.

Parameters

loc{ALKMaps.LonLat} map location

Returns

{Object} Object with the following properties: tile ({ALKMaps.Tile}), i ({Number} x-pixel offset from top left), and j ({Integer} y-pixel offset from top left).

queueTileDraw

queueTileDraw: function(evt)

Adds a tile to the animation queue that will draw it.

Parameters

evt{Object} Listener argument of the tile’s beforedraw event

drawTileFromQueue

drawTileFromQueue: function()

Draws the first tile from the tileQueue, and unqueues that tile

clearTileQueue

clearTileQueue: function()

Clears the animation queue

destroyTile

destroyTile: function(tile)

Parameters

tile{ALKMaps.Tile}

getServerResolution

getServerResolution: function(resolution)

Return the closest highest server-supported resolution.  Throw an exception if none is found in the serverResolutions array.

Parameters

resolution{Number} The base resolution.  If undefined the map resolution is used.

Returns

{Number} The closest highest server resolution value.

getServerZoom

getServerZoom: function()

Return the zoom value corresponding to the best matching server resolution, taking into account serverResolutions and <zoomOffset>.

Returns

{Number} The closest server supported zoom.  This is not the map zoom level, but an index of the server’s resolutions array.

transformDiv

transformDiv: function(scale)

Transform the layer div.

Parameters

scale{Number} The value by which the layer div is to be scaled.

getResolutionScale

getResolutionScale: function()

Return the value by which the layer is currently scaled.

Returns

{Number} The resolution scale.

applyBackBuffer

applyBackBuffer: function(resolution)

Create, insert, scale and position a back buffer for the layer.

Parameters

resolution{Number} The resolution to transition to.

createBackBuffer

createBackBuffer: function()

Create a back buffer.

Returns

{DOMElement} The DOM element for the back buffer, undefined if the grid isn’t initialized yet.

removeBackBuffer

removeBackBuffer: function()

Remove back buffer from DOM.

moveByPx

moveByPx: function(dx,
dy)

Move the layer based on pixel vector.

Parameters

dx{Number}
dy{Number}

setTileSize

setTileSize: function(size)

Check if we are in singleTile mode and if so, set the size as a ratio of the map size (as specified by the layer’s ‘ratio’ property).

Parameters

size{ALKMaps.Size}

getTilesBounds

getTilesBounds: function()

Return the bounds of the tile grid.

Returns

{ALKMaps.Bounds} A Bounds object representing the bounds of all the currently loaded tiles (including those partially or not at all seen onscreen).

initSingleTile

initSingleTile: function(bounds)

Parameters

bounds{ALKMaps.Bounds}

calculateGridLayout

calculateGridLayout: function(bounds,
origin,
resolution)

Generate parameters for the grid layout.

Parameters

bounds{<ALKMaps.Bound>|Object} ALKMaps.Bounds or an object with a ‘left’ and ‘top’ properties.
origin{<ALKMaps.LonLat>|Object} ALKMaps.LonLat or an object with a ‘lon’ and ‘lat’ properties.
resolution{Number}

Returns

{Object} containing properties tilelon, tilelat, tileoffsetlat, tileoffsetlat, tileoffsetx, tileoffsety

getTileOrigin

getTileOrigin: function()

Determine the origin for aligning the grid of tiles.  If a tileOrigin property is supplied, that will be returned.  Otherwise, the origin will be derived from the layer’s maxExtent property.  In this case, the tile origin will be the corner of the maxExtent given by the tileOriginCorner property.

Returns

{ALKMaps.LonLat} The tile origin.

initGriddedTiles

initGriddedTiles:function(bounds)

Parameters

bounds{ALKMaps.Bounds}

getMaxExtent

getMaxExtent: function()

Get this layer’s maximum extent.  (Implemented as a getter for potential specific implementations in sub-classes.)

Returns

{ALKMaps.Bounds}

addTile

addTile: function(bounds,
position)

Create a tile, initialize it, and add it to the layer div.

Parameters bounds - {ALKMaps.Bounds} position - {ALKMaps.Pixel}

Returns

{ALKMaps.Tile} The added ALKMaps.Tile

addTileMonitoringHooks

addTileMonitoringHooks: function(tile)

This function takes a tile as input and adds the appropriate hooks to the tile so that the layer can keep track of the loading tiles.

Parameters

tile{ALKMaps.Tile}

removeTileMonitoringHooks

removeTileMonitoringHooks: function(tile)

This function takes a tile as input and removes the tile hooks that were added in addTileMonitoringHooks()

Parameters

tile{ALKMaps.Tile}

moveGriddedTiles

moveGriddedTiles: function(deferred)

Parameter

deferred{Boolean} true if this is a deferred call that should not be delayed.

shiftRow

shiftRow:function(prepend)

Shifty grid work

Parameters

prepend{Boolean} if true, prepend to beginning. if false, then append to end

shiftColumn

shiftColumn: function(prepend)

Shift grid work in the other dimension

Parameters

prepend{Boolean} if true, prepend to beginning. if false, then append to end

removeExcessTiles

removeExcessTiles: function(rows,
columns)

When the size of the map or the buffer changes, we may need to remove some excess rows and columns.

Parameters

rows{Integer} Maximum number of rows we want our grid to have.
columns{Integer} Maximum number of columns we want our grid to have.

onMapResize

onMapResize: function()

For singleTile layers, this will set a new tile size according to the dimensions of the map pane.

getTileBounds

getTileBounds: function(viewPortPx)

Returns The tile bounds for a layer given a pixel location.

Parameters

viewPortPx{ALKMaps.Pixel} The location in the viewport.

Returns

{ALKMaps.Bounds} Bounds of the tile at the given pixel location.

Instances of this class represent a width/height pair
{ALKMaps.LonLat} Optional origin for aligning the grid of tiles.
{<ALKMaps.Bounds>|Array} If provided as an array, the array should consist of four values (left, bottom, right, top).
This class represents a longitude and latitude pair
This is a class designed to designate a single tile, however it is explicitly designed to do relatively little.
{Function} A function that defers execution of moveGriddedTiles by tileLoadingDelay.
moveGriddedTiles: function(deferred)
{Integer} Number of milliseconds before we shift and load tiles when panning.
drawTileFromQueue: function()
Draws the first tile from the tileQueue, and unqueues that tile
setMap: function(map)
removeMap: function(map)
Called when the layer is removed from the map.
destroy: function()
Deconstruct the layer and clear the grid.
clearGrid:function()
Go through and remove all tiles from the grid, calling destroy() on each of them to kill circular references
clone: function (obj)
Create a clone of this layer
moveTo:function(bounds,
zoomChanged,
dragging)
This function is called whenever the map is moved.
getTileData: function(loc)
Given a map location, retrieve a tile and the pixel offset within that tile corresponding to the location.
queueTileDraw: function(evt)
Adds a tile to the animation queue that will draw it.
clearTileQueue: function()
Clears the animation queue
destroyTile: function(tile)
getServerResolution: function(resolution)
Return the closest highest server-supported resolution.
getServerZoom: function()
Return the zoom value corresponding to the best matching server resolution, taking into account serverResolutions and zoomOffset.
{Array(Number}} This property is documented in subclasses as an API property.
transformDiv: function(scale)
Transform the layer div.
getResolutionScale: function()
Return the value by which the layer is currently scaled.
applyBackBuffer: function(resolution)
Create, insert, scale and position a back buffer for the layer.
createBackBuffer: function()
Create a back buffer.
removeBackBuffer: function()
Remove back buffer from DOM.
moveByPx: function(dx,
dy)
Move the layer based on pixel vector.
setTileSize: function(size)
Check if we are in singleTile mode and if so, set the size as a ratio of the map size (as specified by the layer’s ‘ratio’ property).
getTilesBounds: function()
Return the bounds of the tile grid.
initSingleTile: function(bounds)
calculateGridLayout: function(bounds,
origin,
resolution)
Generate parameters for the grid layout.
getTileOrigin: function()
Determine the origin for aligning the grid of tiles.
initGriddedTiles:function(bounds)
getMaxExtent: function()
Get this layer’s maximum extent.
addTile: function(bounds,
position)
Create a tile, initialize it, and add it to the layer div.
addTileMonitoringHooks: function(tile)
This function takes a tile as input and adds the appropriate hooks to the tile so that the layer can keep track of the loading tiles.
removeTileMonitoringHooks: function(tile)
This function takes a tile as input and removes the tile hooks that were added in addTileMonitoringHooks()
shiftRow:function(prepend)
Shifty grid work
shiftColumn: function(prepend)
Shift grid work in the other dimension
removeExcessTiles: function(rows,
columns)
When the size of the map or the buffer changes, we may need to remove some excess rows and columns.
onMapResize: function()
For singleTile layers, this will set a new tile size according to the dimensions of the map pane.
getTileBounds: function(viewPortPx)
Returns The tile bounds for a layer given a pixel location.
Create a new grid layer
{Boolean} Moves the layer into single-tile mode, meaning that one tile will be loaded.
{String} Name of the class added to the layer div.
{Number} Delay for removing the backbuffer when all tiles have finished loading.
Instances of ALKMaps.Map are interactive maps embedded in a web page.
Instances of this class represent bounding boxes.
{String} If the tileOrigin property is not provided, the tile origin will be derived from the layer’s maxExtent.
This class represents a screen coordinate, in x and y coordinates
Close