- Legend to Symbols
-
Namespace
The namespace is really just an object where further objects and their methods and properties are attached bundling up all the functionality using a unique name.
Interface
The Interface is a contract by which the implementing class adheres. It describes a desired behavior and enforces adherence for any class that implements the interface.
Class
Classes define types of objects that will be used by the application.
Method
A function associated with a class or object.
Field
A variable associated with a class or object.
Inherited Method
A function inherited from the parent class. The present documentation scheme differentiates between a direct or indirect inheritance relationship.
Inherited Field
A variable inherited from the parent class. The present documentation scheme differentiates between a direct or indirect inheritance relationship.
Event
Events are actions that occur because of user interaction. They are normally used in combination with functions, and the function will not be executed before the event occurs.
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");
});
Extends
nokia.maps.gfx.Image.
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.
Direct Inheritance
Inherited from nokia.maps.gfx.Image:
clone
createElement
getDocument
prepare
setOpacity
height
opacity
state
width
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
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.