Nokia Maps API Reference

Contents

Class nokia.maps.gfx.Graphics

Class Summary

This class represents a two-dimensional graphics context. It produces an IDL (Image Description Language) object that can be rendered into a real image, using an instance of nokia.maps.gfx.Painter. The graphics context itself controls an IDL state and uses it to generate and IDL object.

Note that after creating a graphics context, the method beginImage() must be called, except when the graphics context has been initialized with a previoulsy created IDL, for example:

 // Initialize local variables.
 var Color = nokia.maps.gfx.Color,
     parseCss = Color.parseCss,
     body = document.body || document.documentElement,
     graphics,
     painter,
     image,
     imageNode;

 // Create a new image with a size of 64x64 pixels.
 graphics =  new nokia.maps.gfx.Graphics();
 graphics.beginImage(64, 64, "This is my image");
 graphics.drawRect(16,16, 31,31);
 graphics.set("fillColor", parseCss("red",0.5));
 graphics.set("strokeColor", parseCss("black"));
 graphics.set("lineWidth", 1);
 graphics.fill();
 graphics.stroke();
 image = graphics.getIDL();

 // Create a DOM element from the image using the default painter.
 painter = new nokia.maps.gfx.Painter.defaultPainter();
 imageNode = painter.createElement(image, document);

 // Add this image node to the document.
 body.appendChild( imageNode );

The above example creates a square box with the dimensions 32 x 32 pixels an a 1 pixel wide black border, filled with semi-transparent red color. Each side of the box measures 32 pixels and the inner square (inside the border) is 30 x 30 pixels. The graphics context uses the same coordinate projection as the IDL itself. A path consists of points and each point is infinitely small. The default origin of the coordinate system is the center of the top-left pixel of the destination surface (image). This means that, by default, the coordinate (0,0) is projected to the center of the top-left pixel at the position (0,0) of the image being created. Therefore if lineWidth is set to 1 and a moveTo(1,1).lineTo(200,1) is executed, all the pixels from the position (1,1) to (200,1) are stroked with a one-pixel-wide brush. Because the line is infinitely small and runs through the center of each pixel, all the pixels under the pen are colored, resulting in a line that is 201 pixels long.

Repeating the same exercise, but with lineWidth of two pixels, results in a 203 pixel long and 3 pixel high line, where the pixels from (1,1) to (200,1) are fully filled with black color. In the pixel row from (0,0) to (202,1) and from (0,2) to (202,2) only half of each pixel is filled. This is because we use a two-pixel-wide brush through the center of each pixel from (1,1) to (200,1), which means that we have to stroke one pixel above and one pixel below the center of those pixels. Therefore from the center of the pixel (1,1) we stroke one pixel up, filling the top half of the pixel (1,1) and the bottom half of the pixel (1,0). We then stroke one pixel down, filling the bottom half of the pixel (1,1) and the top half of the pixel (1,2). This results in a completely filled pixel (1,1), while the pixel (1,0) and (1,2) are only half filled. As it is impossible in reality to fill half a pixel, the rendering engine simulates this effect by not making the pixel fully black, but by calculating a color value that takes half the current color and half the new color taking opacity into account. This can lead to unwanted effects, therefore we advice cuation with lineWidth values that are multiples of 2.

Hint: For a box with a specific outer or inner size, subtract the line width from or add it to the length of the side of the box. So if you want a box with an outer size of exactly 200 pixels and a border width of 3 pixels, reduce the width and height in the call to drawRect() by three, which means you need to call the method, specifying 197 as width and height. This results in a rectangle with an outer size of 200 x 200 pixels and an inner size of 194 x 194 pixels, with a border that is three pixels wide.

Method Summary
beginImage (width, height, [description]) : nokia.maps.gfx.Graphics This method resets the state of the graphics context and starts a new 2D image.
beginPath () : nokia.maps.gfx.Graphics This method clears all sub-paths and starts a new path.
bezierCurveTo (cp1x, cp1y, cp2x, cp2y, x, y) : nokia.maps.gfx.Graphics This method draws a Bezier curve from the current cursor position to a new position.
closePath () : nokia.maps.gfx.Graphics This method closes the current sub-path.
drawEllipse (x, y, w, h) : nokia.maps.gfx.Graphics This method creates a new ellipse path.
drawImage (img, sourceX, sourceY, sourceWidth, sourceHeight, destinationX, destinationY, destinationWidth, destinationHeight) : nokia.maps.gfx.Graphics This method draws an image supplied by the caller.
drawRect (x, y, w, h, [rx, [ry]]) : nokia.maps.gfx.Graphics This method creates a new rectangle sub-path and closes it.
fill () : nokia.maps.gfx.Graphics This method fills the current path.
fillText (text, x, y, [nx, [ny]]) This method creates text path at the given position, oriented by a direction vector provided by the caller, closes it and then fills it with the fill color.
getDescription () : String This method retrieves the description of the image.
getHeight () : Number This method retrieves the height of the currently rendered image.
getIDL () : nokia.maps.gfx.IDL This method retrieves the IDL of the given graphics context.
getWidth () : Number This method retrieves the width of the currently rendered image.
lineTo (x, y) : nokia.maps.gfx.Graphics This method draws a line from the current position to the pen position specified by the caller.
moveTo (x, y) : nokia.maps.gfx.Graphics This method moves the cursor to the given position and starts a new sub-path.
polylineTo (coords) : nokia.maps.gfx.Graphics This method draws a polyline from the current position along all the path specified by the caller as an aray of locations.
quadraticCurveTo (cpx, cpy, x, y) : nokia.maps.gfx.Graphics This method draws a quadratic curve from the current cursor position to a new position.
restore () : nokia.maps.gfx.Graphics This method restores a previously saved state of the graphic context or, if the state has not been saved, replaces the current state with the default state.
rotate (angle) : nokia.maps.gfx.Graphics This method rotates the current projection matrix (z axis rotation).
save () : nokia.maps.gfx.Graphics This method saves the current state of the graphics context on the internal stack.
scale (sx, sy) : nokia.maps.gfx.Graphics This method scales the current projection matrix.
set (key, value) : nokia.maps.gfx.Graphics This method changes an IDL state property named by the caller.
setIDL (idl) : nokia.maps.gfx.Graphics This method replaces the current IDL with the object supplied by the caller.
stroke () : nokia.maps.gfx.Graphics This method strokes the current path.
strokeText (text, x, y, [nx, [ny]]) This method creates text path at the given position, oriented by a direction vector provided by the caller, closes it and then strokes it with the stroke color.
translate (dx, dy) : nokia.maps.gfx.Graphics This method translates the current projection matrix.
Constructor Detail

This method creates a new graphics context, either initialized with an IDL or a brand new context.

new nokia.maps.gfx.Graphics([idl])
Parameters:
{nokia.maps.gfx.IDL} [idl]: An instance of IDL with which to initialize the new graphics context
Method Detail
beginImage (width, height, [description]) : nokia.maps.gfx.Graphics
This method resets the state of the graphics context and starts a new 2D image. The method must be called after the graphics context has been created.
Parameters:
{Number} width The width of the image to be created
{Number} height The height of the image
{String} [description]: A description of the image, if omitted "undefined" is used
Returns:
{nokia.maps.gfx.Graphics} The reference to the graphics context (this)
beginPath () : nokia.maps.gfx.Graphics
This method clears all sub-paths and starts a new path. The pen position is lost and a 'moveTo' operation has to be executed to ensure that there is a sub-path with cursor position (x,y) to continue drawing. Therefore the user agent must check if the context has any sub-path. In the absence of a sub-path, the user agent must create a one with the coordinates (x,y) as its first (and only) point, as if the 'moveTo' method had been called.
Returns:
{nokia.maps.gfx.Graphics} A reference to the given graphics context (this)
bezierCurveTo (cp1x, cp1y, cp2x, cp2y, x, y) : nokia.maps.gfx.Graphics
This method draws a Bezier curve from the current cursor position to a new position.

Note that the method does not stroke or fill the path.

Parameters:
{Number} cp1x The x component of the Bezier curve's first control point
{Number} cp1y The y component of the Bezier curve's first control point
{Number} cp2x The x component of the Bezier curve's second control point
{Number} cp2y The y component of the Bezier curve's second control point
{Number} x The x component of the new pixel position
{Number} y The y component of the new pixel position
Returns:
{nokia.maps.gfx.Graphics} A reference to the given graphics context (this)
closePath () : nokia.maps.gfx.Graphics
This method closes the current sub-path.
Returns:
{nokia.maps.gfx.Graphics} A reference to the given graphics context (this)
drawEllipse (x, y, w, h) : nokia.maps.gfx.Graphics
This method creates a new ellipse path.

Note that the method does not stroke or fill the path.

Parameters:
{Number} x The left edge of the ellipse
{Number} y The top edge of the ellipse
{Number} w The width of the ellipse
{Number} h The height of the ellipse
Returns:
{nokia.maps.gfx.Graphics} A reference to the given graphics context (this)
drawImage (img, sourceX, sourceY, sourceWidth, sourceHeight, destinationX, destinationY, destinationWidth, destinationHeight) : nokia.maps.gfx.Graphics
This method draws an image supplied by the caller.
Parameters:
{Image} img The source image
{Number} sourceX The top left corner of the source rectangle
{Number} sourceY The top left corner of the source rectangle
{Number} sourceWidth The width of the source rectangle
{Number} sourceHeight The height of the source rectangle
{Number} destinationX The top left corner of the destination rectangle
{Number} destinationY The top left corner of the destination rectangle
{Number} destinationWidth The width of the destination rectangle
{Number} destinationHeight The height of the destination rectangle
Returns:
{nokia.maps.gfx.Graphics} A reference to the given graphics context (this)
drawRect (x, y, w, h, [rx, [ry]]) : nokia.maps.gfx.Graphics
This method creates a new rectangle sub-path and closes it.

Note that the operation does not cause the path to be stroked or filled. If you want to stroke the path, you should be aware that the path itself does not have a width or height, therefore a rectangle with the top-left corner at 0,0 and a size of 100 x 100 units becomes a 101 pixels wide rectangle if stroked with a lineWidth of 1. Stroking of the same original rectangle with a lineWidth of 3 produces a rectangle whose width is 103 pixels.

Parameters:
{Number} x The left edge of the rectangle
{Number} y The top edge of the rectangle
{Number} w The width of the rectangle
{Number} h The height of the rectangle
{Number} [rx]: The horizontal radius of rounded corners. If omitted it will indicate no border rounding
{Number} [ry]: The vertical radius of rounded corners. If not specified it will be the same as rx
Returns:
{nokia.maps.gfx.Graphics} A reference to the given graphics context (this)
This method fills the current path.
Returns:
{nokia.maps.gfx.Graphics} A reference to the given graphics context (this)
fillText (text, x, y, [nx, [ny]])
This method creates text path at the given position, oriented by a direction vector provided by the caller, closes it and then fills it with the fill color.
Parameters:
{String} text The text to draw.
{Number} x The x component of the text anchor point
{Number} y The y component of the text anchor point
{Number} [nx]: The x component of the absolute direction vector endpoint; if not provided, x + 1 is used
{Number} [ny]: The y component of the absolute direction vector endpoint; if not provided, y is used
getDescription () : String
This method retrieves the description of the image.
Returns:
{String} The description of the image
getHeight () : Number
This method retrieves the height of the currently rendered image.
Returns:
{Number} The height of the currently rendered image
getIDL () : nokia.maps.gfx.IDL
This method retrieves the IDL of the given graphics context.
Returns:
{nokia.maps.gfx.IDL} The IDL of the given graphics context
getWidth () : Number
This method retrieves the width of the currently rendered image.
Returns:
{Number} The width of the currently rendered image
lineTo (x, y) : nokia.maps.gfx.Graphics
This method draws a line from the current position to the pen position specified by the caller.

Note that the method does not stroke or fill the path.

Parameters:
{Number} x The x-offset for the final pen position
{Number} y The y-offset for the final pen position
Returns:
{nokia.maps.gfx.Graphics} A reference to the given graphics context (this)
moveTo (x, y) : nokia.maps.gfx.Graphics
This method moves the cursor to the given position and starts a new sub-path.
Parameters:
{Number} x The x-offset for the cursor position
{Number} y The y-offset for the cursor position
Returns:
{nokia.maps.gfx.Graphics} A reference to the given graphics context (this)
polylineTo (coords) : nokia.maps.gfx.Graphics
This method draws a polyline from the current position along all the path specified by the caller as an aray of locations.

Note that the method does not stroke or fill the path.

Parameters:
{Number[]} coords An array of alternating x- and y-components of coordinates relative to the current position.
Returns:
{nokia.maps.gfx.Graphics} A reference to the given graphics context (this)
quadraticCurveTo (cpx, cpy, x, y) : nokia.maps.gfx.Graphics
This method draws a quadratic curve from the current cursor position to a new position.

Note that the method does not stroke or fill the path.

Parameters:
{Number} cpx The x component of the quadratic curve's control point
{Number} cpy The y component of the quadratic curve's control point
{Number} x The x component of the new pixel position
{Number} y The y component of the new pixel position
Returns:
{nokia.maps.gfx.Graphics} A reference to the given graphics context (this)
This method restores a previously saved state of the graphic context or, if the state has not been saved, replaces the current state with the default state.

If the internal stack is empty, the method restores the default state.

Returns:
{nokia.maps.gfx.Graphics} A reference to the given graphics context (this)
rotate (angle) : nokia.maps.gfx.Graphics
This method rotates the current projection matrix (z axis rotation).

Note that this does rotates the matrix of the context, rather than the image itself, which causes any subsequently created paths to be rotated, without affecting existing paths.

Parameters:
{Number} angle The rotation angle in degrees
Returns:
{nokia.maps.gfx.Graphics} A reference to the given graphics context (this)
This method saves the current state of the graphics context on the internal stack.
Returns:
{nokia.maps.gfx.Graphics} The reference to the given graphics context (this)
scale (sx, sy) : nokia.maps.gfx.Graphics
This method scales the current projection matrix.

Note that the operation scales the matrix of the context, rather than the image itself, which causes any subsequently created paths to be scaled, without affecting existing paths.

Parameters:
{Number} sx The scale factor along the x axis
{Number} sy The scale factor along the y axis
Returns:
{nokia.maps.gfx.Graphics} A reference to the given graphics context (this)
set (key, value) : nokia.maps.gfx.Graphics
This method changes an IDL state property named by the caller. The properties that can be changed are: width, height, description, strokeColor, fillColor, lineWidth, lineCap, lineJoin, miterLimit, font and textAlign.

Note that changing the width or height properties results in a complete reset of the graphics state and clearing of the image buffer, therefore changing the size clears and resets the graphics context.

Parameters:
{String} key The name of the property to modify
{Object} value The value to which to set the property
Returns:
{nokia.maps.gfx.Graphics} A reference to the given graphics context (this)
See:
nokia.maps.gfx.IDL
setIDL (idl) : nokia.maps.gfx.Graphics
This method replaces the current IDL with the object supplied by the caller. The change of IDL affects the image size and description, but has no effect on the saved states.
Parameters:
{nokia.maps.gfx.IDL} idl An object representing the IDL to load
Exceptions:
{String} An exception is thrown if the caller provides an illegal argument that does not represent a valid instance of nokia.maps.gfx.IDL
Returns:
{nokia.maps.gfx.Graphics} A reference to the given graphics context (this)
This method strokes the current path.
Returns:
{nokia.maps.gfx.Graphics} A reference to the given graphics context (this)
strokeText (text, x, y, [nx, [ny]])
This method creates text path at the given position, oriented by a direction vector provided by the caller, closes it and then strokes it with the stroke color.
Parameters:
{String} text The text to draw
{Number} x The x component of the text anchor point
{Number} y The y component of the text anchor point
{Number} [nx]: The x component of the absolute direction vector endpoint; if not provided, x + 1 is used
{Number} [ny]: The y component of the absolute direction vector endpoint; if not provided, y is used
translate (dx, dy) : nokia.maps.gfx.Graphics
This method translates the current projection matrix.

Note that this does translates the matrix of the context, rather than the image itself, which causes any subsequently created paths to be translated, without affecting existing paths.

Parameters:
{Number} dx The translation distance along the x axis
{Number} dy The translation distance along the y axis
Returns:
{nokia.maps.gfx.Graphics} A reference to the given graphics context (this)
Documentation generated on Mon Oct 24 2011 14:24:32 GMT+0200 (CEST).