jsgraphics.html

xddbg1:

DHTML, JavaScript
Draw Line, Circle, Ellipse (Oval), Polyline, Polygon, Rectangle.
High Performance JavaScript Vector Graphics Library.
Developed by Walter Zorn

Top

Cross Browser?

Documentation

Download

This JavaScript VectorGraphics library provides graphics capabilities for JavaScript: functions to draw circles, ellipses (ovals), oblique lines, polylines and polygons (for instance triangles, rectangles) dynamically into a webpage. Usage of this Vector Graphics library should be easy even if you don't have JavaScript experience. Documentation. Another goal during development of this JavaScript Draw Shapes Vector Graphics Library was to achieve optimized performance and cleanly arranged pixel stair-step patterns (pixel-optimization).

Try it out:

x y

setColor("#")

setStroke()

setStroke(Stroke.DOTTED)

Test Canvas

Performance

Top of Page

Performance?

Cross Browser?

Documentation

Download

In HTML there are no such elements as oblique lines, circles, ellipses or other non-rectangularly bounded elements available. For a workaround, pixels might be painted by creating small background-colored layers (DIV elements), and arranging these to the desired pattern. Creating a separate DIV for each pixel of the pattern, however, would be very inefficient since each of these DIVs inevitably has to lug it's complete browser-internal object overhead.

To minimize the amount of this overhead and to optimize performance to what's possible, this Draw Shapes JavaScript VectorGraphics Library, besides using fast algorithms (based on Bresenham algorithms) to compute the shapes, minimizes the number of required DIVs by combining as many pixels into each DIV as possible. Therefore, as illustrated by the picture on the left, the number of DIV elements is decreased [1] from one per pixel to one per pixel stair-step.

However, don't compare the performance with Java or stand-alone applications! Making a browser create DIV elements is of course much slower than just colouring pixels. Even this JavaScript Vectorgraphics Library can't escape from this fundamental restriction - it just tries to squeeze out the maximum of what's possible. It's recommended to refrain from creating shapes that extend more than 600 - 1000 pixels in both dimensions.

Alternative to SVG? Currently SVG-capable browsers or browsers with a correctly included SVG plugin are still rare. Therefore you might use this vector graphics library as an non-proprietary alternative for small or not-too-complex graphic elements, presumably running on the machines of more than 95% of all internet visitors. Moreover, since this vectorgraphics library allows graphics to overflow the borders of their "canvases", it can render to almost everywhere on a page.

Cross Browser Functionality?

Linux:
Browsers with Gecko-Engine (Mozilla, Netscape 6+, Galeon), Konqueror, Netscape 4, Opera 5, 6 and 7.

Windows:
Gecko-Browsers, IE 4, 5 and 6, Netscape 4, Opera 5, 6 and 7.

Mac:
Safari, Gecko-Browsers, Opera, Netscape 4, partially IE.

The functionality "Draw into html elements even after the page has fully loaded" isn't available for Opera prior to version 7 and Netscape 4, whereas "Draw into the document while the page is parsed" is cross-browser capable.

Documentation: How to Use the JavaScript Graphics Library

1. Include the Library
Insert the following code into the head-section of the html file (between <head> and </head>):

<script type="text/javascript" src="wz_jsgraphics.js"></script>

2. HTML: <div> Elements as Canvases
This step isn't required for the mode "Draw directly into the document while the page is parsed". To draw into DIV elements even after the page has fully loaded, however, relatively as well as absolutely positioned layers (DIV elements) are appropriate to serve as canvases. Each of these layers must have a unique ID:
<div id="myCanvas" style="position:relative;height:250px;width:100%;"></div>
...
<div id="anotherCanvas" style="position:relative;height:100px;width:300px;"></div>

3. Save the JavaScript Vectorgraphics Library
Download the JavaScript Vector Graphics Library and unzipp it into the same directory as the html file. If you'd prefer the library to be placed in a different directory, adapt the path src="wz_jsgraphics.js" in the code piece above.

How to Draw Shapes

Top of Page

Performance?

Cross Browser?

Documentation

Download

1. Create a jsGraphics Object
a) Draw into DIV elements even after the page has fully loaded:
(This mode doesn't work in Netscape 4 and Opera < 7.) See the example below how to create a jsGraphics object for a certain DIV element. This code should be inserted into the html code past the concerned DIV element, but in any case ahead of the closing body tag. The ID (in quotation marks) of the selected DIV element must be passed to the constructor function new jsGraphics():

<script type="text/javascript">  </script>

If there are several separate DIV elements, each requires it's own jsGraphics instance:

<script type="text/javascript">  </script>

b) Draw directly into the document while the page is parsed:
Works even in Netscape 4 and Opera 5/6. Instead of the ID of a DIV element, nothing (or the value null) must be passed to the constructor function:

<script type="text/javascript">  </script>

Instead of jg, jg2 or jg_doc you may choose any other variable name, provided it follows the rules for variable names in JavaScript.

2. Functions to Draw Shapes
Once generated, these graphics objects (in this expample jg, jg2 and/or jg_doc) can be used to call the Draw Shapes methods. The shapes generated by a certain graphics object will be drawn into the concerned html element, or, with mode b) used, into the document itself:

As illustrated in this example, at first the color of the "pen" should be set. Otherwise the default color black will be used. The coordinates passed to the Draw Shapes methods refer either, if mode b) used, to the left-top corner of the document itself, or to the left-top corner of the concerned DIV. For each canvas (graphics object) separately, it's paint() method must be called explicitly to render the internally-generated graphics html. Otherwise nothing will happen on your screen.

Name of function (method)	Code example as to be used with the above example object 'jg' (which is the context of the DIV called "myCanvas")
General Notes 1.) Numbers passed to these functions must always be integer numbers, rather than decimal point numbers (floating point numbers), characters or strings. For instance, values obtained from formular inputs are always strings, and results from previous JavaScript calculations typically floating point numbers. Use either the predefined `parseInt()` or the `Math.round()` JavaScript function to convert data to integer. Example: `jg.setStroke(parseInt(document.MyForm.Linewidth.value));` 2.) Consider that co-ordinates lie between pixels, not on them, and that the drawing "pen" hangs beneath and to the right of the path specified by co-ordinates passed to the functions.
`setColor("#HexColor");` Specifies the color of the drawing "pen". Once set, this color will be used by the subsequently called drawing methods until it will be overridden through another call of setColor(). The value must be enclosed in quotation marks, and should be hexadecimal following the pattern "#rrggbb" (as usual with HTML). Color names available in HTML (for instance "maroon") may be used as well.	`jg.setColor("#ff0000");` or with identical result `jg.setColor("red");`
`setStroke(Number);` Specifies the thickness of the drawing "pen" for lines and bounding lines of shapes. Once set, this thickness will be used by the subsequently called drawing methods until it will be overridden through another call of setStroke(). Default line thickness is 1 px, as long as .setStroke() has not yet been invoked. To create dotted lines, `setStroke()` requires the constant `Stroke.DOTTED` as argument. Width of dotted lines is always 1 pixel.	`jg.setStroke(3);` or `jg.setStroke(Stroke.DOTTED);`
`drawLine(X1, Y1, X2, Y2);` Line from the first to the second pair of coordinates. Line thickness is either 1 px or the value most recently specified by `.setStroke()`.	`jg.drawLine(20,50,453,40);`
`drawPolyline(Xpoints, Ypoints);` A polyline is a series of connected line segments. Xpoints and Ypoints are arrays which specify the x and y coordinates of each point as follows: `var Xpoints = new Array(x1,x2,x3,x4,x5); var YPoints = new Array(y1,y2,y3,y4,y5);` Instead of Xpoints and Ypoints you may of course use other names provided these follow the rules for JavaScript variable names. Line thickness is either 1px or the value most recently specified by `.setStroke()`.	`var Xpoints = new Array(10,85,93,60); var YPoints = new Array(50,10,105,87); jg.drawPolyline(Xpoints,Ypoints);`
`drawRect(X, Y, width, height);` Outline of a rectangle. X and Y give the co-ordinates of the left top corner. Line thickness is either 1px or the value most recently specified by `.setStroke()`.	`jg.drawRect(20,50,70,140);`
`fillRect(X, Y, width, height);` Filled rectangle. X and Y give the co-ordinates to the left top corner.	`jg.fillRect(20,50,453,40);`
`drawPolygon(Xpoints, Ypoints);` Polygon. Xpoints and Ypoints are arrays which specify the x and y coordinates of the polygon's corners as follows: `var Xpoints = new Array(x1,x2,x3,x4,x5); var Ypoints = new Array(y1,y2,y3,y4,y5);` The polygon will be automatically closed if the first and last points are not identical. Line thickness is either 1px or the value most recently specified by `.setStroke()`.	`var Xpoints = new Array(10,85,93,60); var Ypoints = new Array(50,10,105,87); jg.drawPolygon(Xpoints, Ypoints);` Instead of Xpoints and Ypoints you may of course use other names provided these follow the rules for variable names.
`fillPolygon(Xpoints, Ypoints);` Filled Polygon. Parameters as for drawPolygon()	`jg.fillPolygon(new Array(10,85,93,60),` `new Array(50,10,105,87));`
`drawEllipse(X, Y, width, height);` Outline of an ellipse. Values refer to the bounding rectangle of the ellipse, X and Y give the co-ordinates of the left top corner of that rectangle rather than of it's center. Line thickness is either 1px or the value most recently specified by `.setStroke()`.	`jg.drawEllipse(20,50,70,140);` or `jg.drawOval(20,50,70,140);`
`fillEllipse(X, Y, width, height);` Filled ellipse. Values refer to the bounding rectangle of the ellipse, X and Y give the co-ordinates of the left top corner of that rectangle rather than of it's center.	`jg.fillEllipse(20,50,71,141);` or `jg.fillOval(20,50,71,141);`
`setFont("font-family", "size+unit", Style);` This method can be invoked prior to drawString() to specify or change font-family, -size and -style. Values or font-family and -size may be whatever possible in HTML, and must be enclosed in quotation marks. Available font styles: Font.PLAIN for normal style (not bold, not italic) Font.BOLD for bold fonts Font.ITALIC for italics Font.ITALIC_BOLD or Font.BOLD_ITALIC to combine the latters.	Example: see `drawString()` below
`drawString("Text", X, Y);` Writes text to the location specified by X and Y. Differently from Java, these coordinates refer to the left top corner of the first line of the text. The string passed to drawString() must be enclosed in quotation marks. (Non-escaped) HTML tags inside the string will be interpreted. For example, "Some Text<br>more Text" would indeed create a line break.	`jg.setFont("arial","15px",Font.ITALIC_BOLD);` `jg.drawString("Some Text",20,50);`
`drawStringRect("Text", X, Y, Width, Alignment);` Like drawString. Allows however to set the width of the text rectangle and to specify the horizontal text-alignment. Text-alignment value must be a string (i.e. enclosed in quotation marks or apostrophes) and can be either "left", "center", "right" or "justify".	`jg.setFont("verdana","11px",Font.BOLD);` `jg.drawStringRect("Text",20,50,300,"right");`
`drawImage("src", X, Y, width, height);` Draws image on the specified location. "src" parameter specifies path, width and height parameters allow to stretch the image (almost) arbitrarily. Optionally, drawImage() accepts a fifth parameter which you can use to insert an eventhandler into the generated image tag. Example: `jg.drawImage("anImg.jpg",8,5,95,70,"onmouseover=YourFunc()");`	`jg.drawImage("friendlyDog.jpg",` `20,50,100,150);`
`paint();` Must be envoked explicitly to draw the internally-generated graphics into the html page. To optimize performance it's recommended to restrain from calling `paint()` in unnecessarily short intervals. Avoid something like: `jg.drawEllipse(0, 0, 100, 100); jg.paint(); jg.drawLine(200, 10, 400, 40); jg.paint(); ...` The following will be faster: `jg.drawEllipse(0, 0, 100, 100); jg.drawLine(200, 10, 400, 40); /...further drawing methods... / jg.paint();`	`jg.paint();`
`clear();` Any content created by the Graphics JavaScript Library will be deleted (within the canvas the graphics object refers to). The default content of the canvas (content not created by the script) will remain untouched, i.e. neither be changed nor be deleted.	`jg.clear();` Any stuff within "myCanvas" (in these examples the DIV 'jg' refers to) drawn by the script is deleted.
`setPrintable(true);` By default, printing shapes isn't feasible since default printing settings of browsers usually prevent background colors from being printed. Invoking setPrintable() with the parameter true enables wz_jsgraphics.js to draw printable shapes (at least in Mozilla/Netscape 6+ and IE). However, at the price of a slightly decreased rendering speed (about 10% to 25% slower).	`jg.setPrintable(false);` The parameter false switches wz_jsgraphics.js back to non-printable mode. The benefit from this, however, will be re-optimized rendering performance.

Download

Top of Page

Performance?

Cross Browser?

Documentation

Download

wz_jsgraphics.js 2.32 zipped 5.38 KB (not MB)
wz_jsgraphics.zip

History of Updates (it's recommended to read this, especially if you aren't sure about the benefits from an update :-) ).

Notes

[1]
If we assume the probability of line angles on the screen to be equally distributed over 360?
Then for 1 px wide lines the number of layers is averagely sin(45? / (1 - sin(45?) = 2.41 times larger if for each pixel a separate layer is created, compared with a solution that requires merely one layer per pixel stair-step (as is the case with this library). This is true under the assumption that both algorithms let pixel stair-steps touch each other corner-by-corner rather than side-by-side. Otherwise the number of pixels to be colored would be larger, and therefore the disadvantage of an unfavorable one-layer-per-pixel algorithm even bigger.

Walter Zorn, Munich, 2005

visitors on www.walterzorn.com since 27. 12. 2002