Nokia Maps API Reference

Contents

Class nokia.maps.gfx.BitmapImage

Class Summary

The class BitmapImage loads a bitmap (PNG, GIF, JPEG and others) from a Web server and makes it available as a GFX image. The difference between a GFX image and a native DOM image is that a GFX image is not loaded unless it is necessary or forced by calling prepare(). Additionally, a GFX image can be clipped (sprite creation).

The main purpose of sprite images is to save server requests by adding multiple images into one image and then clip this single image to produce multiple images from one. GFX images are also used if it is unclear exactly when an image should be loaded. This applies for example to instances of nokia.maps.map.Marker and their icons. For example, you may add a thousand markers with different icon images to the map, but you only need to load those for the markers that are within the visible viewport.

Examples:
		// Create a reference to the document body.
		var body = document.body || document._documentElement;

		// Create a new bitmap.
		var bitmap = new nokia.maps.gfx.BitmapImage("http://www.w3.org/Icons/WWW/w3c_home_nb.png");

		// Add the bitmap in original size into the body. 
		body.appendChild(bitmap.createElement());

		// Clone the bitmap, pick out the center of the image (from pixel 16,16 a square of 32 pixel) 
		// and add that to the document body.
		var sprite = bitmap.clone(document, 32,32, 16,16);
		body.appendChild(sprite.createElement());

		// Display the size of the image as soon as it is known.
		sprite.prepare(function (img) {
			alert("natural image size: " + img.naturalWidth + "x" + img.naturalHeight);
			alert("current sprite offset-x/y: " + img.offsetX + ", " + img.offsetY + " with " + img.width + "x" + img.height + "px size");
		});
new nokia.maps.gfx.BitmapImage (image, [doc, [width, [height, [offsetX, [offsetY]]]]])
Method Summary
abstract clone ([doc]) : nokia.maps.gfx.Image This method clones the given image and optionally binds it to a different document.
clone ([doc, [width, [height, [offsetX, [offsetY]]]]]) : nokia.maps.gfx.BitmapImage This method clones the given image and clips it to the size specified by the caller (creating a sprite).
abstract createElement ([opacity]) : Node This method creates a DOM node containing the given image.
abstract getDocument () : Document This method retrieves the document to which the given image is bound.
abstract prepare (callback, [context]) : nokia.maps.gfx.Image This method prepares the given image and calls a callback on completion or failure.
abstract setOpacity (element, opacity) : nokia.maps.gfx.Image This method changes the global opacity of an element returned by the createElement().
Field Summary
Number height This property holds the target height of the image in pixels.
abstract Number height This property holds the height of the image in pixels.
Boolean isBitmap This bitfield property indicates that the given image is a bitmap.
Number naturalHeight This property holds the natural height of the image in pixels.
Number naturalWidth This property holds the natural width of the image in pixels.
Number offsetX This property holds the x-offset (in pixels) within the image to create a sprite or undefined, if the image is not to be used to create a sprite.
Number offsetY This property holds the y-offset (in pixels) within the image to create a sprite or undefined, if the image is not to be used to create a sprite.
abstract Number opacity This property holds the default opacity for the image.
final String src This property holds the URL of the image.
abstract Number state This property holds the state of the image.
abstract Number width This property holds the width of the image in pixels.
Number width This property holds the target width of the image in pixels.
Constructor Detail

This method creates a new image from an image URL or an already loaded HTML image.

The method accepts four optional parameters for width, height, x- and y-offset to define a viewport for an image and to allow for spriting. If only the width and height are supplied, but no x- and y-offset, then the image is scaled to match these dimensions. If no width or height are provided by the caller at all, the image size remains unchanged.

new nokia.maps.gfx.BitmapImage(image, [doc, [width, [height, [offsetX, [offsetY]]]]])
Examples:
		// Create a reference to the document body.
		var body = document.body || document._documentElement;

		// Create a new bitmap.
		var bitmap = new nokia.maps.gfx.BitmapImage("http://www.w3.org/Icons/WWW/w3c_home_nb.png");

		// Add the bitmap in original size into the body. 
		body.appendChild(bitmap.createElement());

		// Clone the bitmap, pick out the center of the image (from pixel 16,16 a square of 32 pixel) 
		// and add that to the document body.
		var sprite = bitmap.clone(document, 32,32, 16,16);
		body.appendChild(sprite.createElement());

		// Display the size of the image as soon as it is known.
		sprite.prepare(function (img) {
			alert("natural image size: " + img.naturalWidth + "x" + img.naturalHeight);
			alert("current sprite offset-x/y: " + img.offsetX + ", " + img.offsetY + " with " + img.width + "x" + img.height + "px size");
		});
Parameters:
{String | Image} image Either a URL of an image or an already loaded HTML image
{Document} [doc]: The document to which the instance of BitmapImage is to be bound; if this argument is omitted, the current document is used
{Number} [width]: The target width of the image in pixels
{Number} [height]: The target height of the image in pixels
{Number} [offsetX]: The x-offset within the image to create a sprite (in pixels)
{Number} [offsetY]: The y-offset within the image to create a sprite (in pixels)
Method Detail
clone ([doc, [width, [height, [offsetX, [offsetY]]]]]) : nokia.maps.gfx.BitmapImage
This method clones the given image and clips it to the size specified by the caller (creating a sprite). The clone is attached either to the same document as the original image, or to another document if provided by the caller.
Parameters:
{Document} [doc]: A reference to a document to which the image should be attached
{Number} [width]: The target width of the image in pixels; if not provided, the current value is used
{Number} [height]: The target height of the image in pixels; if not provided, the current value is used
{Number} [offsetX]: The x-offset within the image to create a sprite (in pixels); if not provided, the current value is used
{Number} [offsetY]: The y-offset within the image to create a sprite (in pixels); if not provided, the current value is used
Returns:
{nokia.maps.gfx.BitmapImage} An object representing the cloned image
Field Detail
Number height
This property holds the target height of the image in pixels.
Boolean isBitmap
This bitfield property indicates that the given image is a bitmap.
Default Value:
true
Number naturalHeight
This property holds the natural height of the image in pixels. The value of the property may be undefined until the image has been prepared successfully.
Number naturalWidth
This property holds the natural width of the image in pixels. The value of the property may be undefined until the image has been prepared successfully.
Number offsetX
This property holds the x-offset (in pixels) within the image to create a sprite or undefined, if the image is not to be used to create a sprite.
Number offsetY
This property holds the y-offset (in pixels) within the image to create a sprite or undefined, if the image is not to be used to create a sprite.
final String src
This property holds the URL of the image.
Number width
This property holds the target width of the image in pixels.
Documentation generated on Thu Dec 15 2011 15:14:30 GMT+0100 (CET).