Class SvgLib21

java.lang.Object
  extended by SvgLib21

public class SvgLib21
extends java.lang.Object

File SvgLib21.java

Copyright 2011, R.G.Baldwin

Revised 08/11/11 to add a method named setDescription that can be called to add a element to any other element. The description can be spoken in IVEO by first selecting the element an pressing Ctrl+d.

Revised 08/07/11 to add a parameter for the title to allow the user to pass in a string for the title element.

Revised 08/06/11 to add a title element to each shape element. As a result, when the SVG file is opened in IVEO and you click on the shape, the name of the shape is spoken by IVEO. Note, however, that you must be careful about the order in which you add the shapes to the drawing. For example, a rectangle that is added after a line is added can cover the line and prevent the information about the line from being spoken even though the rectangle may be transparent. Therefore, for IVEO compatibility, you must not allow one shape object to cover another shape object.

DESCRIPTION

This is a graphics library that is designed to eliminate much of the pain involved in writing JDOM code to create SVG output. The library contains individual static methods that are used to construct and return all of the SVG basic shape elements, text elements, description elements and comment elements.

In addition there are methods to set various attributes on shape elements and text elements. This library provides methods to instantiate, return, and manipulate the following types of SVG elements:

Methods that return elements set the stroke attribute value to black and set the stroke-width attribute value to 1.

All of the methods that accept coordinate values or dimensions as input require those values to be in inches or fractions thereof. They are then converted to svg units using a scale factor of 90 svg units per inch.

All incoming vertical coordinate values are modified to cause the origin to be at the lower-left corner. Positive x is to the right and positive y is up the page. Therefore, the user can think in terms of a typical graphing assignment with the origin at the lower-left corner.

One svg unit equals approximately 0.011 inch. An svg unit is not necessarily the same size as a pixel on a monitor or a printer. However, dimensions specified in inches should be very close when you print the image.

In addition to the methods mentioned above, this library provides two different methods for writing the final SVG/XML out to a file. One is named writePrettyFile and the other is named writeCompactFile.

Tested using J2SE 6.0, JDOM 1.1.1, Firefox 5, running under Windows Vista Home Premius Edition.

author: Richard G. Baldwin


Constructor Summary
SvgLib21()
           
 
Method Summary
static org.jdom.Element makeCircle(org.jdom.Element parent, java.lang.String namespace, java.lang.String elementTitle, double cx, double cy, double r)
          This method constructs and returns a circle node for a given parent in a given namespace.
static org.jdom.Comment makeComment(org.jdom.Element parent, java.lang.String text)
          This method constructs and returns a comment node for a given given parent.
static org.jdom.Element makeDescription(org.jdom.Element parent, java.lang.String nameSpace, java.lang.String text)
          DEPRECATED This method has been deprecated Use the method named setDescription instead.
static org.jdom.Element makeEllipse(org.jdom.Element parent, java.lang.String namespace, java.lang.String elementTitle, double cx, double cy, double rx, double ry)
          This method constructs and returns an ellipse node for a given parent in a given namespace.
static org.jdom.Element makeLine(org.jdom.Element parent, java.lang.String namespace, java.lang.String elementTitle, double x1, double y1, double x2, double y2)
          This method constructs and returns a line node for a given parent in a given namespace.
static org.jdom.Element makePolygon(org.jdom.Element parent, java.lang.String namespace, java.lang.String elementTitle, double[] points)
          This method constructs and returns a polygon node for a given parent in a given namespace.
static org.jdom.Element makePolyline(org.jdom.Element parent, java.lang.String namespace, java.lang.String elementTitle, double[] points)
          This method constructs and returns a polyline node for a given parent in a given namespace.
static org.jdom.Element makeRect(org.jdom.Element parent, java.lang.String namespace, java.lang.String elementTitle, double x, double y, double width, double height)
          This method constructs and returns a rect node for a given parent in a given namespace.
static org.jdom.Element makeSvg(java.lang.String ns, java.lang.String documentTitle, double dWidth, double dHeight)
          This method constructs and returns a reference to an SVG root element node named svg.
static org.jdom.Element makeText(org.jdom.Element parent, java.lang.String namespace, double x, double y, java.lang.String fontFamily, int fontSize, java.lang.String textIn)
          This method constructs and returns a text node for a given parent in a given namespace.
static void setDescription(org.jdom.Element parent, java.lang.String namespace, java.lang.String description)
          This method can be used to add a description element to any other element
static void setFill(org.jdom.Element element, java.lang.String fillColor)
          This method can be used to set the fill color for closed shapes such as rectangles, circles, ellipses, and polygons.
static void setFillOpacity(org.jdom.Element element, double opacity)
          This method can be used to set the fill opacity for all closed shapes such as rectangles, circles, ellipses, and polygons.
static void setFontStyle(org.jdom.Element element, java.lang.String fontStyle)
          This method can be used to set the font style for text.
static void setFontWeight(org.jdom.Element element, java.lang.String fontWeight)
          This method can be used to set the font weight for text.
static void setStroke(org.jdom.Element element, java.lang.String strokeColor)
          This method can be used to set the stroke color for all shapes.
static void setStrokeOpacity(org.jdom.Element element, double opacity)
          This method can be used to set the stroke opacity for all shapes.
static void setStrokeWidth(org.jdom.Element element, double widthInInches)
          This method can be used to set the stroke width for rectangles, circles, ellipses, lines, polylines, and polygons.
static void writeCompactFile(java.lang.String fname, org.jdom.Document doc)
          This method writes the SVG code into an output file in whitespace-normalized format, which is more efficient than the prettyPrint format.
static void writePrettyFile(java.lang.String fname, org.jdom.Document doc)
          This method writes the SVG code into an output file in pretty-print format.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SvgLib21

public SvgLib21()
Method Detail

makeCircle

public static org.jdom.Element makeCircle(org.jdom.Element parent,
                                          java.lang.String namespace,
                                          java.lang.String elementTitle,
                                          double cx,
                                          double cy,
                                          double r)
This method constructs and returns a circle node for a given parent in a given namespace. By default,the stroke is black, the stroke-width is 1, and the fill is none. Other methods can be called to change these default values later.

Parameters:
parent - the SVG parent element
namespace - the SVG namespace
elementTitle - the title for IVEO compatibility
cx - the x-coordinate of the center in inches
cy - the y-coordinate of the center in inches
r - the radius of the circle in inches
Returns:
A reference to an object that represents an SVG circle element

makeComment

public static org.jdom.Comment makeComment(org.jdom.Element parent,
                                           java.lang.String text)
This method constructs and returns a comment node for a given given parent.

Parameters:
parent - the SVG parent element
text - the text content for this comment element
Returns:
A reference to an object that represents an SVG comment element.

makeDescription

public static org.jdom.Element makeDescription(org.jdom.Element parent,
                                               java.lang.String nameSpace,
                                               java.lang.String text)
DEPRECATED This method has been deprecated Use the method named setDescription instead. This method constructs and returns a description node for a given namespace and a given parent.

Parameters:
parent - the SVG parent element
nameSpace - the SVG namespace
text - the text content for this desc element
Returns:
A reference to an object that represents an SVG desc element.

makeEllipse

public static org.jdom.Element makeEllipse(org.jdom.Element parent,
                                           java.lang.String namespace,
                                           java.lang.String elementTitle,
                                           double cx,
                                           double cy,
                                           double rx,
                                           double ry)
This method constructs and returns an ellipse node for a given parent in a given namespace. By default, the stroke is black, the stroke-width is 1, and the fill is none.

Parameters:
parent - the SVG parent element
namespace - the SVG namespace
elementTitle - the title for IVEO compatibility
cx - the x-coordinate of the center in inches
cy - the y-coordinate of the center in inches
rx - the horizontal radius of the ellipse in inches
ry - the vertical radius of the ellipse in inches
Returns:
A reference to an object that represents an SVG ellipse element

makeLine

public static org.jdom.Element makeLine(org.jdom.Element parent,
                                        java.lang.String namespace,
                                        java.lang.String elementTitle,
                                        double x1,
                                        double y1,
                                        double x2,
                                        double y2)
This method constructs and returns a line node for a given parent in a given namespace. By default, the stroke is black and the stroke-width is 1.

Parameters:
parent - the SVG parent element
namespace - the SVG namespace
elementTitle - the title for IVEO compatibility
x1 - start x-coordinate in inches
y1 - start y-coordinate in inches
x2 - end x-coordinate in inches
y2 - end y-coordinate in inches
Returns:
A reference to an object that represents an SVG line element

makePolygon

public static org.jdom.Element makePolygon(org.jdom.Element parent,
                                           java.lang.String namespace,
                                           java.lang.String elementTitle,
                                           double[] points)
This method constructs and returns a polygon node for a given parent in a given namespace.

The array of type double[], which contains the coordinates for each point in the polygon, must contain an even number of values for the polygon to be drawn correctly. Otherwise, it simply won't be drawn.

The values are extracted from the array, converted to svg units as type int, and treated as coordinate values x1,y1, x2,y2, x3,y3 ... etc.

The stroke is set to black one pixel wide with no fill.

The main difference between a polygon and a polyline is that a polygon is automatically closed by connecting the last point to the first point.

Parameters:
parent - the SVG parent element
namespace - the SVG namespace
elementTitle - the title for IVEO compatibility
points - an array of x-y coordinate pairs in inches that define the locations of the vertices of the polygon.
Returns:
A reference to an object that represents an SVG polygon element

makePolyline

public static org.jdom.Element makePolyline(org.jdom.Element parent,
                                            java.lang.String namespace,
                                            java.lang.String elementTitle,
                                            double[] points)
This method constructs and returns a polyline node for a given parent in a given namespace.

The array of type double[], which contains the coordinates for each point in the polyline, must contain an even number of values for the polyline to be drawn correctly. Otherwise, it simply won't be drawn.

The values are extracted from the array, converted to svg units as type int, and treated as coordinate values x1,y1, x2,y2, x3,y3 ... etc.

The stroke is set to black one pixel wide with no fill.

The main difference between a polyline and a polygon is that a polygon is automatically closed by connecting the last point to the first point.

Parameters:
parent - the SVG parent element
namespace - the SVG namespace
elementTitle - the title for IVEO compatibility
points - an array of x-y coordinate pairs in inches that define the locations of the end points and the vertices of the polyline.
Returns:
A reference to an object that represents an SVG polyline element

makeRect

public static org.jdom.Element makeRect(org.jdom.Element parent,
                                        java.lang.String namespace,
                                        java.lang.String elementTitle,
                                        double x,
                                        double y,
                                        double width,
                                        double height)
This method constructs and returns a rect node for a given parent in a given namespace. By default,the stroke is black, the stroke-width is 1, and the fill is none.

Parameters:
parent - the SVG parent element
namespace - the SVG namespace
elementTitle - the title for IVEO compatibility
x - x-coordinate of lower left corner in inches
y - y-coordinate of lower left corner in inches
width - width in inches
height - height in inches
Returns:
A reference to an object that represents an SVG rect element

makeSvg

public static org.jdom.Element makeSvg(java.lang.String ns,
                                       java.lang.String documentTitle,
                                       double dWidth,
                                       double dHeight)
This method constructs and returns a reference to an SVG root element node named svg. The svg element represents the canvas on which various shapes can be drawn. The width and height attribute values of the svg element establish the physical size of the canvas on the screen and on the printer. The preserveAspectRatio defaults to none.

Parameters:
ns - the SVG namespace URI
documentTitle - the title for IVEO compatibility
dWidth - the width of the canvas in inches
dHeight - the height of the canvas in inches
Returns:
A reference to an SVG element object

makeText

public static org.jdom.Element makeText(org.jdom.Element parent,
                                        java.lang.String namespace,
                                        double x,
                                        double y,
                                        java.lang.String fontFamily,
                                        int fontSize,
                                        java.lang.String textIn)
This method constructs and returns a text node for a given parent in a given namespace. By default,the stroke is black, and the fill is none.

Parameters:
parent - the SVG parent element
namespace - the SVG namespace
x - x-coordinate of lower left corner of first character in inches
y - y-coordinate of lower left corner of first character in inches
fontFamily - font family such as arial
fontSize - font size in points such as 32
textIn - the text to be displayed
Returns:
A reference to an object that represents an SVG text element

setFill

public static void setFill(org.jdom.Element element,
                           java.lang.String fillColor)
This method can be used to set the fill color for closed shapes such as rectangles, circles, ellipses, and polygons. It can also be applied to polylines, but the results may not be what you expect.

The fill color can be set to "none" or to any of the color names at

http://www.w3.org/TR/SVG/types.html#ColorKeywords

There may be other possibilities as well.

Parameters:
element - the element for which the fill will be set
fillColor - the new color for the fill

setFillOpacity

public static void setFillOpacity(org.jdom.Element element,
                                  double opacity)
This method can be used to set the fill opacity for all closed shapes such as rectangles, circles, ellipses, and polygons.

The fill opacity can be set to any value between 0,0 and 1.0 inclusive, where 0.0 is totally transparent and 1.0 is totally opaque.

Parameters:
element - the element for which the opacity will be set
opacity - the numeric opacity value

setFontStyle

public static void setFontStyle(org.jdom.Element element,
                                java.lang.String fontStyle)
This method can be used to set the font style for text.

The font-style can be set to

normal | italic | oblique

Parameters:
element - the text element for which the font style will be set
fontStyle - the new font style

setFontWeight

public static void setFontWeight(org.jdom.Element element,
                                 java.lang.String fontWeight)
This method can be used to set the font weight for text.

The font-weight can be set to

normal | bold | bolder | lighter | 100 | 200 | 300| 400 | 500 | 600 | 700 | 800 | 900 |

Parameters:
element - the text element for which the font weight will be set
fontWeight - the new font weight

setStroke

public static void setStroke(org.jdom.Element element,
                             java.lang.String strokeColor)
This method can be used to set the stroke color for all shapes.

The stroke color can be set to "none" or any of the color names at

http://www.w3.org/TR/SVG/types.html#ColorKeywords

There may be other possibilities as well.

Parameters:
element - the element for which the stroke color will be set
strokeColor - the new stroke color

setStrokeOpacity

public static void setStrokeOpacity(org.jdom.Element element,
                                    double opacity)
This method can be used to set the stroke opacity for all shapes.

The stroke opacity can be set to any value between 0,0 and 1.0 inclusive, where 0.0 is totally transparent and 1.0 is totally opaque.

Parameters:
element - the element for which the stroke color will be set
opacity - the numeric opacity value

setStrokeWidth

public static void setStrokeWidth(org.jdom.Element element,
                                  double widthInInches)
This method can be used to set the stroke width for rectangles, circles, ellipses, lines, polylines, and polygons.

Parameters:
element - the element for which the stroke color will be set
widthInInches - the new stroke width in inches or parts thereof

setDescription

public static void setDescription(org.jdom.Element parent,
                                  java.lang.String namespace,
                                  java.lang.String description)
This method can be used to add a description element to any other element

Parameters:
parent - the element to which the description will be added
namespace - the SVG namespace
description - the text for the new description.

writeCompactFile

public static void writeCompactFile(java.lang.String fname,
                                    org.jdom.Document doc)
This method writes the SVG code into an output file in whitespace-normalized format, which is more efficient than the prettyPrint format.

Parameters:
fname - path and name of output SVG file including the .svg filename extension
doc - a reference to an object of type Document which was instantiated as

new Document(svg,docType)

where svg is the root element of the SVG document

and docType was instantiated as

DocType docType = new DocType( dtdConstrainedElement,dtdPublicID,dtdSystemID);


writePrettyFile

public static void writePrettyFile(java.lang.String fname,
                                   org.jdom.Document doc)
This method writes the SVG code into an output file in pretty-print format. The pretty-print format is less efficient than the compact format, but it is very useful during test and debugging because you can view source in your browser and the XML code will be reasonably well formatted.

Note that the extension is automatically appended to the output file name, so it should not be included in the file name input parameter.

Parameters:
fname - path and name of output SVG file excluding the .svg filename extension
doc - a reference to an object of type Document which was instantiated as

new Document(svg,docType)

where svg is the root element of the SVG document

and docType was instantiated as

DocType docType = new DocType( dtdConstrainedElement,dtdPublicID,dtdSystemID);