This method is synchronous and returns a rendered DOM node that represents the image. If the image is not yet successfully prepared, the preparation has failed or is ongoing, the returned image may be a blank image, with a size of 0 x 0 pixels. If the image is not yet prepared and no preparation is currently ongoing, this method calls the prepare() method.

Note that if an image is being prepared and the returned DOM node has the size of 0 x 0 pixels, the size may be updated automatically as soon as the preparation has finished successfully. Therefore, it is fail-safe to create, for example, a BitmapImage and to call the method createElement() directly, because if the image has not yet been loaded, it will then be loaded asynchronously and the returned DOM node will be extended as soon as the image is available.

 // Create a bitmap image.
var myImage = new nokia.maps.gfx.BitmapImage(
	  "http://www.w3.org/Icons/WWW/w3c_home_nb.png");
 
 // Add the image to the document, prepare() is called 
 // by the method createElement().
var body = document.body || document.documentElement;
body.appendChild(myImage.createElement());

// If GraphicsImage is included in the gfx 
// package, it returns a graphics image on 
// execution of the following code:
var myImage = nokia.maps.gfx.Image.fromObject(
	'<svg xmlns="http://www.w3.org/2000/svg" width="1000" height="600" viewBox="0 0 5 3">'+
	'<rect id="black_stripe" width="5" height="3" y="0" x="0" fill="#000"/>'+
	'<rect id="red_stripe" width="5" height="2" y="1" x="0" fill="#D00"/>'+
	'<rect id="gold_stripe" width="5" height="1" y="2" x="0" fill="#FFCE00"/>'
	'</svg>'
);

Calling this method on an image that is already prepared leads to the callback being invoked immediately. If the method is called multiple times, all the supplied callback handlers are called in the order in which the method has been called.

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

// Create a callback handler that shall be called as 
// soon as the image is loaded.
var myCallback = function (image, msg) {
	 // If preparing the image failed, show an error 
	 // message and return.
	 if (image.state<1) return alert ("Failed to load image!");
	
	 // Show the message supplied to the prepare method, 
	 // if any.
	 if (msg) alert (msg);
	
	 // Paint the image into the document.
	 var body = image.doc.body || image.doc.documentElement;
	 body.appendChild(image.createElement());
};

// Start the image preparation which (in this case) 
// loads the bitmap from the Web server and then calls
// the callback. If the image is within the browser's 
// cache, it may happen that the callback method is 
// called immediately.
myImage.prepare(myCallback, null, "Hello World!");