xdocs/svggen.xml - xmlgraphics-batik - Git at Google

 <?xml version="1.0"?>
 <!DOCTYPE document SYSTEM "./dtd/document-v10.dtd">

 <!-- ========================================================================= -->
 <!-- Copyright (C) The Apache Software Foundation. All rights reserved.        -->
 <!--                                                                           -->
 <!-- This software is published under the terms of the Apache Software License -->
 <!-- version 1.1, a copy of which has been included with this distribution in  -->
 <!-- the LICENSE file.                                                         -->
 <!-- ========================================================================= -->

 <!-- ========================================================================= -->
 <!-- author spei@cs.uiowa.edu                                                  -->
 <!-- version $Id$          -->
 <!-- ========================================================================= -->
 <document>
     <header>
         <title>SVGGraphics2D</title>
         <subtitle>A brief of the SVG Generator in Java(SVGGraphics2D)</subtitle>
         <authors>
             <person name="Sheng Pei" email="spei@cs.uiowa.edu"/>
             <person name="Vincent Hardy" email="vincent.hardy@eng.sun.com"/>
         </authors>
     </header>

     <body>
         <s1 title="Introduction">

         <figure src="images/svggen.jpg" alt="Batik SVG Generator"/>
         <p>
                 As SVG(Scalable Vector Graphics) is emerging as a promising graphics format
                 for a wide range of domains and applications, bridging it with Java becomes important.
                 This page explains how Batik's <code>SVGGraphics2D</code>, referred to as the SVG Generator, makes
                 this possible. It is divided into three parts: </p>
                 <ul>
                     <li><link href="#whatIsIt">What is <code>SVGGraphics2D</code>?</link></li>
                     <li><link href="#howToUse">How to use <code>SVGGraphics2D</code>?</link></li>
                 </ul>

         </s1>

         <anchor id="whatIsIt" />
         <s1 title="What's SVGGraphics2D">
                 <p>
                 On the Java platform, all rendering goes through the <code>java.awt.Graphics2D</code>
                 abstract class, which offers methods such as <code>drawRect</code>, <code>fillRect</code>, or
                 <code>drawString</code>. There are specialized
                 implementations of this abstract class for each type of output, such as a monitor or a printer.
                 <code>SVGGraphics2D</code> is a new implementation of that interface that generates SVG content instead of
                 drawing to a screen or a printer.</p>

                 <p>
                 <code>SVGGraphics2D</code> provides the following:
                 </p>
                 <ul>
                         <li> Allows applications to export their graphics into SVG format. </li>
                         <li> Does not require any modification of the graphics code to export to SVG. </li>
                         <li> Offers the user the ability to use the DOM API to manipulate the generated document. </li>
                 </ul>
                 <figure src="images/svggenHighLevelArchi.jpg" alt="High level architecture" />

                 <p>
                 The above figure shows how the generator works with the DOM API. The W3C has defined an API for representing
                 XML content with a Java programming language object. That API allows programmers to manipulate, create,
                 and/or modify XML content in memory. The DOM API contains interfaces such as <code>Document</code>,
                 <code>Element</code>, and <code>Attr</code>,
                 which model the Java programming language equivalent of XML documents, elements and attributes.
                 </p>
                 <p>
                 The generator manages a tree of DOM objects that represent the SVG content corresponding to the rendering
                 calls made on the <code>SVGGraphics2D</code> instance. In other words, every time a program invokes a rendering method,
                 such as <code>fillRect</code>, on a <code>SVGGraphics2D</code> instance, a new DOM object, representing
                 the SVG equivalent, is appended
                 to the DOM tree (for example a &lt;rect&gt; element will be appended after the <code>fillRect</code> method
                 has been invoked).
                 </p>
                 <p>
                 The programmer using this generator can then access the DOM tree to further manipulate it or can directly
                 write the content to an output stream, as we see in the following section.
                 </p>

         </s1>

                 <anchor id="howToUse" />
                 <s1 title="How to use SVGGraphics2D">
                 <p>
                 From the figure in the previous section we can see that in order for an instance of <code>SVGGraphics2D</code> to build
                 the SVG content(the DOM tree), an instance of DOM's <code>Document</code> class is needed. The DOM tree is an in-memory
                 representation of the SVG document, which can be further manipulated by the user using DOM API or be streamed
                 out into any <code>java.io.Writer</code>.
                 </p>

                 <p>
                 The following excerpted code example shows how to generate SVG content from Java graphics.
                 </p>

                 <source>
 import java.awt.Rectangle;
 import java.awt.Graphics2D;
 import java.awt.Color;
 import java.io.Writer;
 import java.io.OutputStreamWriter;
 import java.io.IOException;
 import org.apache.batik.util.awt.svg.SVGGraphics2D;
 import org.apache.batik.dom.GenericDOMImplementation;
 import org.w3c.dom.Document;
 import org.w3c.dom.DOMImplementation;

 public class TestSVGGen {

     public void paint(Graphics2D g2d) {
         g2d.setPaint(Color.red);
         g2d.fill(new Rectangle(10, 10, 100, 100));
     }

     public static void main(String [] args) throws IOException {

         // Get a DOMImplementation
         DOMImplementation domImpl =
             GenericDOMImplementation.getDOMImplementation();

         // Create an instance of org.w3c.dom.Document
         Document document = domImpl.createDocument(null, "svg", null);

         // Create an instance of the SVG Generator
         SVGGraphics2D svgGenerator = new SVGGraphics2D(document);

         // Ask the test to render into the SVG Graphics2D implementation
         TestSVGGen test = new TestSVGGen();
         test.paint(svgGenerator);

         // Finally, stream out SVG to the standard output using UTF-8
         // character to byte encoding
         boolean useCSS = true; // we want to use CSS style attribute
         Writer out = new OutputStreamWriter(System.out, "UTF-8");
         svgGenerator.stream(out, useCSS);
     }
 }
                 </source>

                 <p>
                 We can see that generating SVG content from our <code>TestSVGGen</code> instance is a three step
                 process:
                 </p>
                 <p>
                 1. Create an instance of <code>org.w3c.dom.Document</code> that the generator will use to build its XML content;
                 create a SVG generator using the <code>Document</code> instance.</p>
                         <source>
 // Get a DOMImplementation
 DOMImplementation domImpl =
     GenericDOMImplementation.getDOMImplementation();

 // Create an instance of org.w3c.dom.Document
 Document document = domImpl.createDocument(null, "svg", null);

 // Create an instance of the SVG Generator
 SVGGraphics2D svgGenerator = new SVGGraphics2D(document);

                         </source>
                 <p>
                 2. Invoke the rendering code on our SVG generator. In our example, we invoke <code>TestSVGGen</code>'s
                    <code>paint</code> method: </p>
                         <source>
 // Ask the test to render into the SVG Graphics2D implementation
 TestSVGGen test = new TestSVGGen();
 test.paint(svgGenerator);

                         </source>
                 <p>
                 3. Stream out the SVG content. The SVG generator can stream its content into any <code>java.io.Writer</code>. In our
                         example, we stream the content to the standard output stream:   </p>
                         <source>
 // Finally, stream out SVG to the standard output using UTF-8
 // character to byte encoding
 boolean useCSS = true; // we want to use CSS style attribute
 Writer out = new OutputStreamWriter(System.out, "UTF-8");
 svgGenerator.stream(out, useCSS);
                         </source>
                         <p>
                         SVG has two ways of expressing properties, such as the fill color: either XML attributes or CSS values.
                         The 'useCss' parameter allows the user to control that option.
                         </p>
                 </s1>

     </body>
 </document>
	<?xml version="1.0"?>
	<!DOCTYPE document SYSTEM "./dtd/document-v10.dtd">

	<!-- ========================================================================= -->
	<!-- Copyright (C) The Apache Software Foundation. All rights reserved. -->
	<!-- -->
	<!-- This software is published under the terms of the Apache Software License -->
	<!-- version 1.1, a copy of which has been included with this distribution in -->
	<!-- the LICENSE file. -->
	<!-- ========================================================================= -->

	<!-- ========================================================================= -->
	<!-- author spei@cs.uiowa.edu -->
	<!-- version $Id$ -->
	<!-- ========================================================================= -->
	<document>
	<header>
	<title>SVGGraphics2D</title>
	<subtitle>A brief of the SVG Generator in Java(SVGGraphics2D)</subtitle>
	<authors>
	<person name="Sheng Pei" email="spei@cs.uiowa.edu"/>
	<person name="Vincent Hardy" email="vincent.hardy@eng.sun.com"/>
	</authors>
	</header>

	<body>
	<s1 title="Introduction">

	<figure src="images/svggen.jpg" alt="Batik SVG Generator"/>
	<p>
	As SVG(Scalable Vector Graphics) is emerging as a promising graphics format
	for a wide range of domains and applications, bridging it with Java becomes important.
	This page explains how Batik's <code>SVGGraphics2D</code>, referred to as the SVG Generator, makes
	this possible. It is divided into three parts: </p>
	<ul>
	<li><link href="#whatIsIt">What is <code>SVGGraphics2D</code>?</link></li>
	<li><link href="#howToUse">How to use <code>SVGGraphics2D</code>?</link></li>
	</ul>

	</s1>

	<anchor id="whatIsIt" />
	<s1 title="What's SVGGraphics2D">
	<p>
	On the Java platform, all rendering goes through the <code>java.awt.Graphics2D</code>
	abstract class, which offers methods such as <code>drawRect</code>, <code>fillRect</code>, or
	<code>drawString</code>. There are specialized
	implementations of this abstract class for each type of output, such as a monitor or a printer.
	<code>SVGGraphics2D</code> is a new implementation of that interface that generates SVG content instead of
	drawing to a screen or a printer.</p>

	<p>
	<code>SVGGraphics2D</code> provides the following:
	</p>
	<ul>
	<li> Allows applications to export their graphics into SVG format. </li>
	<li> Does not require any modification of the graphics code to export to SVG. </li>
	<li> Offers the user the ability to use the DOM API to manipulate the generated document. </li>
	</ul>
	<figure src="images/svggenHighLevelArchi.jpg" alt="High level architecture" />

	<p>
	The above figure shows how the generator works with the DOM API. The W3C has defined an API for representing
	XML content with a Java programming language object. That API allows programmers to manipulate, create,
	and/or modify XML content in memory. The DOM API contains interfaces such as <code>Document</code>,
	<code>Element</code>, and <code>Attr</code>,
	which model the Java programming language equivalent of XML documents, elements and attributes.
	</p>
	<p>
	The generator manages a tree of DOM objects that represent the SVG content corresponding to the rendering
	calls made on the <code>SVGGraphics2D</code> instance. In other words, every time a program invokes a rendering method,
	such as <code>fillRect</code>, on a <code>SVGGraphics2D</code> instance, a new DOM object, representing
	the SVG equivalent, is appended
	to the DOM tree (for example a <rect> element will be appended after the <code>fillRect</code> method
	has been invoked).
	</p>
	<p>
	The programmer using this generator can then access the DOM tree to further manipulate it or can directly
	write the content to an output stream, as we see in the following section.
	</p>

	</s1>

	<anchor id="howToUse" />
	<s1 title="How to use SVGGraphics2D">
	<p>
	From the figure in the previous section we can see that in order for an instance of <code>SVGGraphics2D</code> to build
	the SVG content(the DOM tree), an instance of DOM's <code>Document</code> class is needed. The DOM tree is an in-memory
	representation of the SVG document, which can be further manipulated by the user using DOM API or be streamed
	out into any <code>java.io.Writer</code>.
	</p>

	<p>
	The following excerpted code example shows how to generate SVG content from Java graphics.
	</p>

	<source>
	import java.awt.Rectangle;
	import java.awt.Graphics2D;
	import java.awt.Color;
	import java.io.Writer;
	import java.io.OutputStreamWriter;
	import java.io.IOException;
	import org.apache.batik.util.awt.svg.SVGGraphics2D;
	import org.apache.batik.dom.GenericDOMImplementation;
	import org.w3c.dom.Document;
	import org.w3c.dom.DOMImplementation;

	public class TestSVGGen {

	public void paint(Graphics2D g2d) {
	g2d.setPaint(Color.red);
	g2d.fill(new Rectangle(10, 10, 100, 100));
	}

	public static void main(String [] args) throws IOException {

	// Get a DOMImplementation
	DOMImplementation domImpl =
	GenericDOMImplementation.getDOMImplementation();

	// Create an instance of org.w3c.dom.Document
	Document document = domImpl.createDocument(null, "svg", null);

	// Create an instance of the SVG Generator
	SVGGraphics2D svgGenerator = new SVGGraphics2D(document);

	// Ask the test to render into the SVG Graphics2D implementation
	TestSVGGen test = new TestSVGGen();
	test.paint(svgGenerator);

	// Finally, stream out SVG to the standard output using UTF-8
	// character to byte encoding
	boolean useCSS = true; // we want to use CSS style attribute
	Writer out = new OutputStreamWriter(System.out, "UTF-8");
	svgGenerator.stream(out, useCSS);
	}
	}
	</source>

	<p>
	We can see that generating SVG content from our <code>TestSVGGen</code> instance is a three step
	process:
	</p>
	<p>
	1. Create an instance of <code>org.w3c.dom.Document</code> that the generator will use to build its XML content;
	create a SVG generator using the <code>Document</code> instance.</p>
	<source>
	// Get a DOMImplementation
	DOMImplementation domImpl =
	GenericDOMImplementation.getDOMImplementation();

	// Create an instance of org.w3c.dom.Document
	Document document = domImpl.createDocument(null, "svg", null);

	// Create an instance of the SVG Generator
	SVGGraphics2D svgGenerator = new SVGGraphics2D(document);

	</source>
	<p>
	2. Invoke the rendering code on our SVG generator. In our example, we invoke <code>TestSVGGen</code>'s
	<code>paint</code> method: </p>
	<source>
	// Ask the test to render into the SVG Graphics2D implementation
	TestSVGGen test = new TestSVGGen();
	test.paint(svgGenerator);

	</source>
	<p>
	3. Stream out the SVG content. The SVG generator can stream its content into any <code>java.io.Writer</code>. In our
	example, we stream the content to the standard output stream: </p>
	<source>
	// Finally, stream out SVG to the standard output using UTF-8
	// character to byte encoding
	boolean useCSS = true; // we want to use CSS style attribute
	Writer out = new OutputStreamWriter(System.out, "UTF-8");
	svgGenerator.stream(out, useCSS);
	</source>
	<p>
	SVG has two ways of expressing properties, such as the fill color: either XML attributes or CSS values.
	The 'useCss' parameter allows the user to control that option.
	</p>
	</s1>

	</body>
	</document>