The CAatMap object is the base object which encapsulates a map. It can contain as many bitmap/data layers as is feasible within the constraints of the user’s computer power. A number of callbacks offer interactivity between the user and the website application, and there is a rich set of commands to maintain the map’s state and content.

Working Example

Dependant Objects

CAatBitmapLayer

A raster map layer; this may contain street centerline data, satellite data, statistical data, and the API has facilities for users to create their own CAatBitmapLayer via URL callbacks to their own server which serves images.

CAatPointLayer

A data layer, which holds data points overlayed; usually overlayed onto the lower CAatBitmapLayer layers on the map.

About Zoom Levels

Properties

RedrawCallback

Assign this property to a function that is called whenever the map has finished redrawing, usually as a result of the Init() function. The function declaration should be

function RedrawCallbackFunction (mapobj,x,y,source,forcemove)

Where

mapobj (CAatMap) The map object that has just finished redrawing

x (float) The geographical X coordinate of the center of the map

y (float) The geographical Y coordinate of the center of the map

source (string) A description passed through from the item which invoked the redraw. Useful for debugging.

forcemove (Boolean) Treat the redraw as if the map has moved since the last time RedrawCallbackFunction was invoked, even if it has not.

PopupMenuCallback

Assign this property to a function which is called when the user selects an item from the rightclick-popup menu that is not handled by the system ; ie. A user function. The function declaration should be

function PopupMenuCallbackFunction(mapobj, selected, x, y)

Where

mapobj (CAatMap) object that the menu was invoked from

selected (string) The string associated with the menu item which was selected

x (float) The geographical X coordinate at which the menu was invoked

y (float) The geographical Y coordinate at which the menu was invoked

ClickCallback

Description

Assign this property to a function which will be fired each time the user clicks on the map. The declaration of the function should be

function ClickCallbackFunction (x, y, mapobj)

Where

x (float) The geographical X coordinate at which the cursor was clicked

y (float) The geographical Y coordinate at which the cursor was clicked

mapobj (CAatMap) The map which was clicked on

Methods

Setup / Initialization

AddLayer (type, position, id)

Adds a new layer to the map.

Arguments

type (string) Type of layer to add, currently defined layers are:
map: The basic bitmapped streetmap layer CAatBitmapLayer
point: CAatPointLayer layer
custom: Allows the use of custom CAatBitmapLayer layers

position (number) Z-Position of the layer in the stack – the higher this number is, the further toward the bottom of the stack of layers it will be. Layers with a lower position will appear to be stacked on top of ones with a higher number.

id (string) A unique reference for this layer; It only needs to be unique should you need to use it later, the system does not require this to be unique to function correctly.

Returns

Depending on the “type” argument; “map” and “custom” will return a CAatBitmapLayer, and “point” will return a CAatPointLayer object.

Init (callbacks)

Redraws the map object, and effects all the changes you have made the variables.

Arguments

callbacks true: Once the map has redrawn, it will call any of the callbacks that you have set.
false: The callbacks will not be called after the redraw, even if they are set.

Returns

Nothing.

Jump (newx, newy, newzoom)

Updates the internal variables to the new position. The map is not affected, only internal variables are updated. To update them and then perform the map update, use the JumpTo method.

Arguments

newx (float) New geographic X coordinate

newy (float) New geographic Y coordinate

newzoom (float) New Zoom Level; this has to be a valid zoom level, one of the following:
10.24, 5.12, 2.56, 1.28, 0.64, 0.32, 0.12, 0.05, 0.02, 0.01, 0.005, 0.0025, 0.00125, 0.000625
This represents the amount of map, in degrees, per 300x300 pixel tile, between the center an an edge.

Returns

Nothing

JumpTo(newx, newy, newzoom)

The JumpTo method invokes the Jump method to update the internal parameters, then calls Init(true) to update the map.

Returns

Nothing

See Also

Jump, Init

SetBranding (logoname, width, height)

Sets the logo that is placed at the bottom-right of the map for branding purposes.

Arguments

logoname (string-url) URL of the logo to be displayed. Preferably a PNG logo with an alpha channel so that it’s non-obtrusive and blends into the ma pwell.

width (float) The width, in pixels, of the image speicified in logoname

height (float) The height, in pixels, of the image speicified in logoname

Returns

Nothing

SetOutput (ctrlname)

Set the container into which the map shall be rendered. This should be a <div> section, with a size that doesn’t change, ie. It should be made sure that the dimensions are not dynamic in the markup which encapsulates the <div>. This is easiest done through style=”width:X;height:Y;” when the div is declared.

Arguments

ctrlname (string) The name of the <div> section into which the map will be rendered.

Returns

Nothing

Map Navigation / Positioning

DegWidth ()

Methods used to discover the width of the map pane, in degrees.

Returns

(float) The total distance, in degrees, from the left to the right edges of the map pane.

DegHeight ()

Methods used to discover the height of the map pane, in degrees.

Returns

(float) The total distance, in degrees, from the top to the bottom edges of the map pane.

FindBigger (closeto)

Arguments

closeto (float) The desired zoom level

Returns

(float) The next largest (zoomed-out) CAatMap supported zoom level that is close to the closeto argument.

FindZoom (numdegx, numdegy, notfound)

Find a zoom level that will fit the specified geographical dimensions on the map.

Arguments

numdegx (float) Number of geographical degrees to fit into the X dimension of the map

numdegy (float) Number of geographical degrees to fit into the Y dimension of the map

notfound (float, optional) If the speicified arguments cannot be made to fit onto the screen (either too small or large), this value wll be used

Returns

(float) The closest zoom level that will contain the given dimensions.

GetTileZoom ()

Returns

(float) The zoom level of the individual tiles in the map. Each tile is 300x300 pixels.

GetX ()

Returns

(float) The geographic X coordinate of the center of the displayed map.

GetY ()

Returns

(float) The geographic X coordinate of the center of the displayed map.

GetZoom ()

Returns

(float) The zoom level which represents the entire map area. This zoom level is the number of degrees between the center of the map and the furthest edge.

SetTileZoom (newzoom)

Arguments

newzoom (float) A new zoom level to set the internal CAatMap object’s level to. This should be a valid zoom level; see the Introduction for these zoom levels. The map is not updated, Init() will have to be called for this to take effect.

Returns

Nothing

SetX (newx)

Arguments

newx (float) A new X coordinate to set the internal CAatMap object’s X coordinate to. The map is not updated, Init() will have to be called for this to take effect.

Returns

Nothing

SetY (newy)

Arguments

newy (float) A new Y coordinate to set the internal CAatMap object’s Y coordinate to. The map is not updated, Init() will have to be called for this to take effect.

Returns

Nothing

ZoomBounds (x1, y1, x2, y2)

Updates the internal CAatMap variables to fit in the specified area of the map. The map itself is not updated, Init() will need to be called to reflect the update. The map might be zoomed out a little more than the exact bounds of the specified area, to fit in with one of CAatMap’s zoom levels.

Arguments

x1, y1 (float) Top-left coordinate of the area which needs to be viewed.

x2, y2 (float) Bottom-Right coordinate of the area which needs to be viewed.

Returns

Nothing

On-Map Elements and Controls

SetModeButtons (visible)

Arguments

visible (boolean) true: The Map/Hybrid/Sat tabs will be drawn on the map
false: The Map/Hybrid/Sat tabs will not be drawn on the map

Returns

Nothing

SetNavigate (visible)

Arguments

visible (boolean) true: All the navigation items will be drawn
false: None of the navigation items will be drawn – this includes the zoom slider, arrows at the side of the map, as well as all tabs around the map area. The copyright notice will be the only item to appear on the map, for legal reasons.

Returns

Nothing

SetPointsButtons (visible)

Arguments

visible (boolean) true: The Points/Numbers tabs will be drawn on the map
false: The Points/Numbers tabs will not be drawn on the map

Returns

Nothing

SetScaleBar (visible)

Arguments

visible (boolean) true: The scale bar will be drawn at the bottom-left of the map
false: The scale bar will not be drawn at the bottom-left of the map

Returns

Nothing

Layer Manipulation

GetLayer (id)

Finds a given layer within the CAatMap object

Arguments

id (string) The ID of the layer that was specified at layer creation

Returns

(CAatBitmapLayer or CAatPointLayer) The layer corresponding to the one specified by id, or null if no layer was found with the specified ID.

See Also

CAatMap::CreateLayer

RemoveLayer (id)

Removes a given layer within the CAatMap object. The layer is deleted, but the map is not refreshed. The CAatMap::Init() function must be called separately to update the onscreen map

Arguments

id (string) The ID of the layer specified at layer creation

Returns

(boolean) true: Layer was found and deleted

false: Layer was not found

See Also

CAatMap::CreateLayer

Javascript API – CAatPointLayer Object

Introduction

A CAatPointLayer contains one or more points. This layer is added to an active CAatMap object with the CAatMap::AddLayer function, after which point the CAatPointLayer::AddPoint function can be called to add the points to the CAatPointLayer layer.

Working Example

Dependant Objects

CAatpoint

The base point type.

Methods

Point Set up / Manipulation

AddPoint (x, y, caption, id)

Adds a point to the layer. Only the very bare minimum properties of the point are set with this function, one would almost always want to use the CAatPoint methods to further enrich the look and functionality of the point.

Arguments

x (float) X Coordinate of the new point

y (float) Y Coordinate of the new point

caption (string) Default caption for this new point

id (string) Optional: Unique identifier for the point, only needed should you plan on accessing the point using it later.

Returns

(CAatPoint) The newly added point

DeletePoint (id)

Arguments

id (string) The unique identifier of the point to delete, as specified in AddPoint.

Returns

(boolean) true: Point was found and deleted

false: Point was not found in the layer

RemoveAllPoints ()

Removes all the points in the layer

Returns

None

SetDefaultAnchor (anchorx, anchory)

Sets the default anchor which all points added subsequently on this layer will use, unless overridden.

Arguments

anchorx (string) Horizonal alignment of the elements in the point
left: Elements are aligned with left side on the specified X coordinate of the point
center: Centers of the elements are aligned on the specified X coordinate of the point
right: Right edges of the elements are aligned to the specified X coordinate of the point

anchory (string) Vertical alignment of the elements in the point
top: Elements are aligned with top edge on the specified Y coordinate of the point
center: Centers of the elements are aligned on the specified Y coordinate of the point
bottom: B ottom edges of the elements are aligned to the specified Y coordinate of the point

Returns

Nothing

See Also

CAatPoint::SetIconAnchor, CAatPoint::SetLabelAnchor

Utility Methods

GetBounds ()

Calculates a bounding rectangle that will contain all the points in the layer

Returns

(array of floats): the array contains 4 elements, (x_topleft, y_topleft, x_bottomright, y_bottomright).

IsPoint (id)

Arguments

id (string) Unique identifier of a point, as specified when the point was added with AddPoint()

Returns

(boolean) true: The point was found in the layer
false: The point was not found in the layer

FindPoint (id)

Arguments

id (string) Unique identifier of a point, as specified when the point was added with AddPoint()

Returns

(CAatPoint) The point with a matching unique identifier id, or null if the point was not found.

Javascript API – CAatPoint Object

Introduction

Working Example

Properties

Methods

SetIconSize (newx, newy)

Sets the size of the icon which will be used. This is necessary to ensure accurate rendering and placement of the point.

Arguments

newx (integer) Size, in pixels, of the width of the icon to be used for this point

newy (integer) Size, in pixels, of the height of the icon to be used for this point

Returns

Nothing

See Also

SetIcon

SetVisible (min, max)

Controls the zoom levels between which the icon is visible.

Arguments

min (float) Minimum zoom level to show this point at

max (float) Maximum zoom level to show this point at

Returns

Nothing

See Also

“About Zoom Levels” in the CAatMap section

SetClickBehaviour (behaviour)

Although you can override the behavior of the point click, the API provides the most common behaviours you might need.

Arguments

behavior (string) New behaviour of this point
“toggle_all_label”: Clicking on either the label area or the image icon will toggle between just displaying the icon and the icon and label together
“toggle_icon_label”: Clicking on only the icon will toggle between displaying the icon and the icon and label together. This should be used should your popup label contain any hotspots.

Returns

Nothing

SetStyle (style)

Arguments

style (string) The display style of this point
“label”: The label an corresponding icon will both be shown
“icon”: Only the icon will be shown

Returns

Nothing

SetTooltip (tip)

Arguments

tip (string) The string which will be displayed in a standard tooltip when then cursor hovers over the icon of the point.

Returns

Nothing

SetIcon (icon)

Arguments

icon (string) The URL of the icon which will represent this point. It is suggested that a png or gif file is used, as the API will honour transparent backgrounds and attempt to make the PNG files work in IE6, where there are issues with PNG files and transparent images.

Returns

Nothing

SetIconAnchor (anchorx, anchory)

Arguments

anchorx (string) How the icon image will be aligned to the coordinates specified for this point
“left”: The left edge of the image will be aligned to the coordinate
“center”: The center of the image will be aligned to the coordinate
“right”: The right edge of the image will be aligned to the coordinate

anchory (string) Controls how the icon is aligned vertically
“top”: The top edge of the icon is aligned to the coordinate
“center”: The center of the image is aligned to the coordinate
“bottom”: The bottom edge of the icon sits on the coordinate

Returns

Nothing

SetLabelAnchor (anchorx, anchory)

Arguments

anchorx (string) How the pop-up label will be aligned to the coordinates specified for this point
“left”: The left edge of the label will be aligned to the coordinate
“center”: The center of the label will be aligned to the coordinate
“right”: The right edge of the label will be aligned to the coordinate

anchory (string) Controls how the label is aligned vertically
“top”: The top edge of the label is aligned to the coordinate
“center”: The center of the label is aligned to the coordinate
“bottom”: The bottom edge of the label sits on the coordinate