You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xmlgraphics.apache.org by bu...@apache.org on 2012/04/15 07:46:24 UTC
svn commit: r813020 [6/8] - in /websites/staging/xmlgraphics/trunk/content:
./ batik/ batik/demo/ batik/dev/ batik/tools/ batik/using/
batik/using/scripting/
Added: websites/staging/xmlgraphics/trunk/content/batik/using/extending.html
==============================================================================
--- websites/staging/xmlgraphics/trunk/content/batik/using/extending.html (added)
+++ websites/staging/xmlgraphics/trunk/content/batik/using/extending.html Sun Apr 15 05:46:22 2012
@@ -0,0 +1,225 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+ <head>
+ <title>Extending Batik</title>
+
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ <meta property="og:image" content="http://www.apache.org/images/asf_logo.gif" />
+<!--
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/style.css">
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/code.css">
+-->
+ <link href="/css/xmlgraphics.css" rel="stylesheet" type="text/css">
+
+ </style>
+
+
+
+
+
+ </head>
+
+ <body>
+ <div id="banner">
+ </div>
+
+ <div id="navigation">
+ <h1 id="xml-graphics">XML Graphics</h1>
+<ul>
+<li><a href="/">Overview</a></li>
+<li><a href="/team.html">Who We Are</a></li>
+<li><a href="/legal.html">Legal Stuff</a></li>
+<li><a href="/charter.html">Project Charter</a></li>
+<li><a href="/mail.html">Mailing Lists</a></li>
+<li><a href="/repo.html">Code Repositories</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">ASF Sponsorship Program</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">ASF Thanks</a></li>
+</ul>
+<h1 id="subprojects">Subprojects</h1>
+<ul>
+<li><a href="/batik/">Batik</a></li>
+<li><a href="/fop/">FOP</a></li>
+<li><a href="/commons/">Commons</a></li>
+</ul>
+<form name="search" id="search" action="http://www.google.com/search" method="get">
+ <input value="xmlgraphics.apache.org" name="sitesearch" type="hidden"/>
+ <input type="text" name="q" id="query" /><br />
+ <input type="submit" id="submit" value="Search" />
+</form>
+ </div>
+
+ <div id="bannertext">
+ <a href="/"><img src="/images/apache-xml-graphics.gif" alt="The Apache XML Graphics Project" width="220" heigh="51" /></a>
+ <h1>Extending Batik</h1>
+ </div>
+ <p><a href="/">Home</a> » <a href="/batik/">Batik</a> » <a href="/batik/using/">Using</a></p>
+ </div>
+ <div id="content" class="grid_16"><div class="section-content"><p>This page provides an overview of the built in extension mechanisms of Batik. As an open source project, people can of course make any extension they feel is interesting, however Batik has been designed with several forms of extension in mind.</p>
+<p>In general, extensions are added through the Service Provider Interface mechanism as described in the <a href="http://java.sun.com/j2se/1.4/docs/guide/jar/jar.html#Service Provider">jar file documentation</a> . This allows for the extension of Batik simply by adding a new jar file(s) to the class path, and thus no modification of the Batik source is required!
+If you feel that the Batik team has overlooked an important area for extension please let your feelings be known on the mailing lists.</p>
+<h1 id="customXMLTags">Custom XML elements</h1>
+<p>First one must ask what it means to support custom XML elements? There are three basic options Batik considers:</p>
+<dl>
+<dt>Having your elements appear in the DOM tree</dt>
+<dd>As long as your custom elements are well formed XML they will appear in the SVG DOM tree. When rendering Batik will skip branches of the tree that use elements it doesnât know about (so even if standard SVG elements are child nodes they will not be displayed). Note that you must make use of XML namespaces for your personal elements even if you are not planning on validating the XML.</dd>
+</dl>
+<p>This can be useful if you want to add extra pieces of data into the standard SVG drawing. These might be annotations, or other application specific data. In general this wouldnât be particularly useful with squiggle (the SVG browser) or the rasterizer, but might be very useful if you were writing a custom browser, rasterizer, or pre/post processing tools.</p>
+<dl>
+<dt>Adding functionality to your custom element DOM objects</dt>
+<dd>If you need your elements to use a custom element subclass in the DOM tree (for behavioral or performance reasons) then you need to provide an <a href="#domExtension">extension to the Batik DOM</a> .</dd>
+</dl>
+<p>Doing this gives you the opportunity to override the standard methods on DOM elements, or to provide additional methods to your DOM elements. For example, you may wish to add specialized get and set methods for attributes on your custom elements, so that they can be manipulated more easily than just using the string-based <code>getAttribute</code> and <code>setAttribute</code> methods provided by DOM Core.</p>
+<dl>
+<dt>Having your custom elements be rendered</dt>
+<dd>Probably the most common reason to develop custom elements is to add new rendering primitives to the SVG language. In this case you must provide an <a href="#bridgeExtension">extension to the Batik bridge</a> . The bridge extension is resposible for constructing the class(es) that will handle the rendering of the new primitive in Batik.</dd>
+</dl>
+<p>In most cases it will also be necessary to write a DOM extension to make the element behave like other SVG elements (most notably for support of styling).</p>
+<h2 id="domExtension">Writing a Batik DOM extension</h2>
+<p>The ability to extend the elements used in the SVG DOM tree allows users to provide implementations for nodes that can be used in place of Batikâs default implementation of a node. This may be done for a variety of reasons, but is most commonly done to extend the behavior of standard node calls (such as to include styling in attribute lookup), or to implement the DOM interface for an element.</p>
+<p>The key class for building the DOM tree is <a href="../javadoc/org/apache/batik/dom/ExtensibleSVGDOMImplementation.html">org.apache.batik.dom.ExtensibleSVGDOMImplementation</a> . When an instance of this class is constructed it searches for instances of the <a href="../javadoc/org/apache/batik/dom/svg/DomExtension.html">org.apache.batik.dom.svg.DomExtension</a> Service Provider Interface. It then calls the <code>registerTags</code> method, passing itself as the only parameter. This method typically would typically call <code>registerCustomElementFactory</code> for each element that it wishes to handle.</p>
+<p>With Batik the most likely reason to extend a node is to provide proper CSS styling of the node attributes. To this end Batik provides a class you can extend: <a href="../javadoc/org/apache/batik/extension/PrefixableStylableExtensionElement.html">org.apache.batik.extension.PrefixableStylableExtensionElement</a> . If you derive a new DOM class from this class you are only required to implement three methods: <code>getLocalName</code> , <code>getNamespaceURI</code> , and <code>newNode</code> (plus constructors). If all you want is proper style support (commonly the case) then you are done implementing your element at this point.</p>
+<p>The distribution comes with a number of examples:</p>
+<ul>
+<li>
+<p><code>org.apache.batik.extension.svg.BatikStarElement</code> </p>
+</li>
+<li>
+<p><code>org.apache.batik.extension.svg.BatikRegularPolygonElement</code> </p>
+</li>
+<li>
+<p><code>org.apache.batik.extension.svg.BatikHistogramNormalizationElement</code> </p>
+</li>
+<li>
+<p><code>org.apache.batik.extension.svg.SolidColorElement</code> </p>
+</li>
+<li>
+<p><code>org.apache.batik.extension.svg.ColorSwitchElement</code> </p>
+</li>
+</ul>
+<p>Included with these examples is <code>org.apache.batik.extension.svg.BatikDomExtension</code> , which is the required instance of <code>DomExtension</code> used to register the elements with the <code>ExtensibleSVGDOMImplementation</code> .</p>
+<p>If your new element requires new âpresentation attributesâ (XML attributes that can be modified through CSS, or, depending on your viewpoint, the other way aroundâCSS properties that can be specified using XML attributes), you will also need to extend the CSS engine. This can be done by registering a custom CSS value factory. Both of the color examples do this (see <code>BatikDomExtension</code> ).</p>
+<h2 id="bridgeExtension">Writing a Batik bridge extension</h2>
+<p>Before you write a bridge extension it may be useful to understand what role the bridge package plays in Batik. The bridge package is responsible for creating and maintaining elements in the Graphics Vector Toolkit (GVT) tree based on the corresponding element in the SVG DOM. This is done because, for a variety of reasons, the SVG DOM is not well suited for rendering, thus the GVT tree is used for all rendering and transcoding operations.</p>
+<p>The key class for managing this link is the <a href="../javadoc/org/apache/batik/bridge/BridgeContext.html">BridgeContext</a> . This class maintains an association between a element name with namespace and a particular bridge instance that will handle it. The work of constructing the proper entity or entities in the GVT tree is then deferred to the <a href="../javadoc/org/apache/batik/bridge/Bridge.html">Bridge</a> registered for a particular element. If no bridge is regiestered nothing is done.</p>
+<p>New associations can be added by implementors of the <a href="../javadoc/org/apache/batik/bridge/BridgeExtension.html">BridgeExtension</a> Service Provider Interface. This interface has a number of methods that provide information about the particular extension being registered (including contact information, and the list of implemented extensions). It also has a <code>registerTags</code> method which is responsible for registering the bridge instances with a <code>BridgeContext</code> . All the built-in bridges are bundled together with a <code>BridgeExtension</code> (the <a href="../javadoc/org/apache/batik/bridge/SVGBridgeExtension.html">org.apache.batik.bridge.SVGBridgeExtension</a> class), as are the example extensions ( <a href="../javadoc/org/apache/batik/extension/svg/BatikBridgeExtension.html">org.apache.batik.extension.svg</a> ), so these are both good places to start.</p>
+<p>The <code>Bridge</code> interface itself is very simple. It only includes methods to get the namespace and local name of the element the bridge is responsible for. This interface is then extended for each of the major concepts present in SVG:</p>
+<dl>
+<dt><a href="#graphicsNodeBridge">GraphicsNodeBridge</a></dt>
+<dd>These are probably the most common SVG elements, as they represent graphic elements in the âvisibleâ SVG tree. These are the elements most other bridges modify in some way (by clipping, masking, filtering, etc).</dd>
+</dl>
+<p><em>Example SVG elements:</em> <code>svg</code> , <code>g</code> , <code>path</code> , <code>rect</code> .</p>
+<p><em>Example extension bridges:</em> <code>BatikRegularPolygonElementBridge</code> , <code>BatikStarElementBridge</code> .</p>
+<dl>
+<dt>FilterBridge</dt>
+<dd>This handles the SVG <code>filter</code> element. If you wanted to implement a new element that could be referenced from the <code>filter</code> attribute on an SVG graphics node then you would need to subclass this bridge. However, adding new types of filters to the existing SVG <code>filter</code> element is accomplished via the FilterPrimitiveBridge.</dd>
+</dl>
+<p><em>Example SVG element:</em> <code>filter</code> </p>
+<dl>
+<dt><a href="#filterPrimitiveBridge">FilterPrimitiveBridge</a></dt>
+<dd>This constructs an element in the filter chain applied to an SVG graphics node.</dd>
+</dl>
+<p><em>Example SVG elements:</em> <code>feBlend</code> , <code>feCompose</code> , <code>feGaussianBlur</code> .</p>
+<p><em>Example extension bridge:</em> <code>BatikHistogramNormalizationElementBridge</code> </p>
+<dl>
+<dt><a href="#paintBridge">PaintBridge</a></dt>
+<dd>This constructs a Java <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/awt/Paint.html">Paint</a> object to be used in filling or stroking graphic elements.</dd>
+</dl>
+<p><em>Example SVG elements:</em> <code>gradient</code> , <code>pattern</code> .</p>
+<p><em>Example extension bridge:</em> <code>ColorSwitchBridge</code> .</p>
+<dl>
+<dt>ClipBridge</dt>
+<dd>This constructs a <a href="../javadoc/org/apache/batik/ext/awt/image/renderable/ClipRable.html">ClipRable</a> to apply to a graphics node. This provides a path that data is clipped to.</dd>
+</dl>
+<p><em>Example SVG element:</em> <code>clipPath</code> .</p>
+<dl>
+<dt>MarkerBridge</dt>
+<dd>This constructs a <a href="../javadoc/org/apache/batik/gvt/Marker.html">Marker</a> for annotating the path of a graphics node.</dd>
+</dl>
+<p><em>Example SVG element:</em> <code>marker</code> .</p>
+<dl>
+<dt>MaskBridge</dt>
+<dd>This constructs a mask filter to apply to a graphics node. Mask filters typically modify the alpha channel of the graphics node output to make portions fully or partially transparent that wouldnât be otherwise.</dd>
+</dl>
+<p><em>Example SVG element:</em> <code>mask</code> .</p>
+<p>Extension writers are free to work with any of the above bridges, however the three most common are likely to be the <code>GraphicsNodeBridge</code> , the <code>FilterPrimitiveBridge</code> , and the <code>PaintBridge</code> (each of which has example extensions available for inspection). Each of these interfaces has several very useful subclasses that handle much of the common behavior among elements.</p>
+<p>In some simple cases it is possible to provide only an extension to the bridge and achieve your desired effect, however in most cases you will find that for your element to behave like a normal SVG element (for example, to support styling) you will need to provide a DOM extension as well.</p>
+<h3 id="graphicsNodeBridge">GraphicsNodeBridge</h3>
+<p>The graphics node bridge is oriented around constructing a new <a href="../javadoc/org/apache/batik/gvt/GraphicsNode.html">GraphicsNode</a> in the GVT tree. The <code>GraphicsNode</code> is the basic object that makes up the GVT tree. Each <code>GraphicsNode</code> has a <code>paint</code> method that is responsible for painting the object (including considering clipping, masking, filtering, and opacity for the node).</p>
+<p>If you want to you can implement the <a href="../javadoc/org/apache/batik/bridge/GraphicsNodeBridge.html">GraphicsNodeBridge</a> interface directly, or you can subclass the <a href="../javadoc/org/apache/batik/bridge/AbstractGraphicsNodeBridge.html">AbstractGraphicsNodeBridge</a> class. This gives you the most flexibility since you can construct your new subclass of <code>GraphicsNode</code> , where you can implement the paint method to do essentially anything you want. This is quite involved, however, and the steps necessary to create a full <code>GraphicsNodeBridge</code> are not detailed here.</p>
+<p>However, if you just want to generate a custom filled or stroked shape the easiest way is to subclass one of the following two classes. In this case you are essentially only responsible for constructing a standard Java <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/awt/Shape.html">Shape</a> object to describe the desired area to operate on:</p>
+<dl>
+<dt>SVGShapeElementBridge</dt>
+<dd>Subclasses of this class only need to implement <code>buildShape</code> , <code>getNamespaceURI</code> , and <code>getLocalName</code> . <code>buildShape</code> generally constructs a <code>Shape</code> object and sets it on the provided <code>shapeNode</code> object, however it may adjust other features of the given shape node.</dd>
+<dt>SVGDecoratedShapeElementBridge</dt>
+<dd>This is very similar to <code>SVGShapeElementBridge</code> , except that it also handles the standard marker properties. Markers will be placed at the end of each segment of the path that describes the shape.</dd>
+</dl>
+<p>If you decide that you need to implement a new subclass of <code>GraphicsNode</code> it is strongly suggested that you extend <a href="../javadoc/org/apache/batik/gvt/AbstractGraphicsNode.html">AbstractGraphicsNode</a> , as this class does much of the work to behave like other rendered elements in SVG (like clipping, filtering and masking). In this case you implement the <code>primitivePaint</code> method instead of the <code>paint</code> method.</p>
+<h3 id="filterPrimitiveBridge">FilterPrimitiveBridge</h3>
+<p>The <a href="../javadoc/org/apache/batik/bridge/FilterPrimitiveBridge.html">FilterPrimitiveBridge</a> is concerned with the construction of individual elements of the filter chain. Unlike graphics nodes, which generally just draw new objects on top of the destination, filters take existing image data and modify it to apply effects.</p>
+<p>This part of GVT rendering is based on the Java2D <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/awt/image/renderable/RenderableImage.html">java.awt.image.renderable.RenderableImage</a> and <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/awt/image/renderable/RenderedImage.html">java.awt.image.RenderedImage</a> interfaces. These provide a convenient framework to handle image processing (an inherently resolution dependent operation) in the resolution independent system defined by SVG.</p>
+<p>The <code>org.apache.batik.ext.awt.image</code> package hierarchy contains a large set of generally useful extensions to the core JDK classes and methods, that help to implement SVG-related graphics operations.</p>
+<p>Note that the <code>FilterPrimitiveBridge</code> is invoked once for each reference to the <code>filter</code> element that the filter primitive is part of. So if a filter effect is used a half dozen times the <code>createFilter</code> method will be called a half dozen times, even though the element may only appear once in the file. This means that it is safe for the filters returned to be âfixedâ for a particular <code>GraphicsNode</code> being filtered.</p>
+<p>You will notice that Batik uses extended versions of the standard <code>RenderableImage</code> and <code>RenderedImage</code> interfaces to provide additional information about surrounding requirements for operations as well as a few convenience methods. These interfaces are called: <a href="../javadoc/org/apache/batik/ext/awt/image/renderable/Filter.html">org.apache.batik.ext.awt.image.renderable.Filter</a> and <a href="../javadoc/org/apache/batik/ext/awt/image/rendered/CacheableRed.html">org.apache.batik.ext.awt.image.rendered.CacheableRed</a> . Batik contains simple wrapper classes that can take the default JDK <code>RenderableImage</code> and <code>RenderedImage</code> interfaces. Within the codebase the naming convention âRedâ for classes implementing <code>RenderedImage</code> and âRableâ for classes implementing <code>RenderableImage</code> is commonly used (âRedâ is to be pronounced like the color, and âRableâ is to be prono
unced like âhorribleâ with a silent âhâ).</p>
+<p>The <code>FilterPrimitiveBridge</code> has only one method, <code>createFilter</code> , that must construct an instance of <code>Filter</code> to perform the required operation. This is still a fairly complex task given the general need to support accessing the various standard sources of image data. To this end there is a provided subclass, <a href="../javadoc/org/apache/batik/bridge/AbstractSVGFilterPrimitiveElementBridge.html">AbstractSVGFilterPrimitiveElementBridge</a> , that provides convenience methods to handle many common tasks.</p>
+<p>Generally the bulk of the work in writing a filter extension is the writing of the concrete <code>Filter</code> class, not tying it into the GVT tree. Batik does contain several base classes that make this processes a bit easier: <a href="../javadoc/org/apache/batik/ext/awt/image/renderable/AbstractRable.html">org.apache.batik.ext.awt.image.renderable.AbstractRable</a> , <a href="../javadoc/org/apache/batik/ext/awt/image/rendered/AbstractRed.html">org.apache.batik.ext.awt.image.rendered.AbstractRed</a> , and <a href="../javadoc/org/apache/batik/ext/awt/image/rendered/AbstractTiledRed.html">org.apache.batik.ext.awt.image.rendered.AbstractTiledRed</a> , <a href="../javadoc/org/apache/batik/ext/awt/image/rendered/TiledRed.html">TiledRed</a> ties into the Batik tile cache (use this with caution as it is a complex area of the Batik code).</p>
+<p>The <code>org.apache.batik.ext.awt.image.rendered</code> and <code>org.apache.batik.ext.awt.image.renderable</code> packages contain quite a number of fairly general examples covering most common cases, please refer to them for more detail.</p>
+<h3 id="paintBridge">PaintBridge</h3>
+<p>The <a href="../javadoc/org/apache/batik/bridge/PaintBridge.html">PaintBridge</a> constructs an instance of <code>java.awt.Paint</code> to be used to fill or stroke shapes/text (part of the paint server architecture of SVG).</p>
+<p>Like the filter primitive bridge, the <code>PaintBridge</code> is invoked for each reference to the paint. This makes it possible to customize the <code>Paint</code> returned for the particular element to be painted.</p>
+<p>This is how gradients and patterns are implemented in Batik, so it is possible to construct rather complex paint effects through this mechanism.</p>
+<p>For paints you are mostly on your own, because unlike the other cases there arenât any really generally useful base classes to derive off, the closest is the <a href="../javadoc/org/apache/batik/bridge/AbstractSVGGradientElementBridge.html">AbstractSVGGradientElementBridge</a> , which is used to handle most of the radial and linear gradient attributes.</p>
+<p>The existing gradient paint implementations are in the <code>org.apache.batik.ext.awt</code> , and the pattern implementation is in <code>org.apache.batik.gvt</code> since it requires access to GVT internals.</p>
+<h1 id="imageTagFormats">New image file formats</h1>
+<p>When Batik encounters an <code>image</code> element and it determines the element does not reference an SVG file, it defers the loading of the referenced image to <a href="../javadoc/org/apache/batik/ext/awt/image/spi/ImageTagRegistry.html">org.apache.batik.ext.awt.image.spi.ImageTagRegistry</a> . This class maintains a list of <a href="../javadoc/org/apache/batik/ext/awt/image/spi/RegistryEntry.html">RegistryEntry</a> s, generally one for each format.</p>
+<p>Since the formats supported natively by Batik are also implemented through this mechanism. The <a href="../javadoc/org/apache/batik/ext/awt/image/codec/jpeg/JPEGRegistryEntry.html">JPEGRegistryEntry</a> and <a href="../javadoc/org/apache/batik/ext/awt/image/codec/png/PNGRegistryEntry.html">PNGRegistryEntry</a> classes should be used as good references for extensions.</p>
+<h2 id="RegistryEntry">RegistryEntry</h2>
+<p>There are currently two flavors of <code>RegistryEntry</code> :</p>
+<dl>
+<dt>URLRegistryEntry</dt>
+<dd>A <a href="../javadoc/org/apache/batik/ext/awt/image/spi/URLRegistryEntry.html">URLRegistryEntry</a> takes a <a href="../javadoc/org/apache/batik/util/ParsedURL.html">ParsedURL</a> and tries to decide if the URL is intended for it. This group of entries is mostly intended to handle alternate network protocols. It can also be useful for interfacing with libraries that want a URL instead of a stream.</dd>
+<dt>StreamRegistryEntry</dt>
+<dd>A <a href="../javadoc/org/apache/batik/ext/awt/image/spi/StreamRegistryEntry.html">StreamRegistryEntry</a> works with a markable <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/io/InputStream.html">InputStream</a> . This is the preferred form of registry entry as it generally avoids opening a potentially expensive connection multiple times, instead it opens the stream once and relies on mark and reset to allow entries to check the stream.</dd>
+</dl>
+<h2 id="helper-classes-helperclasses">Helper classes ## {#Helper+classes}</h2>
+<p>There exists quite a number of classes to assist in implementing a <code>RegistryEntry</code> . It is strongly recommended that you review these classes and make use of them where appropriate. They will likely save you time and improve the integration with Batik.</p>
+<dl>
+<dt>MagicNumberRegistryEntry</dt>
+<dd><a href="../javadoc/org/apache/batik/ext/awt/image/spi/MagicNumberRegistryEntry.html">MagicNumberRegistryEntry</a> is an abstract class that can handle the <code>isCompatibleStream</code> method for formats that make use of âmagic numbers.â Magic numbers are a well known sequence of bytes at a well known offset in the file, that are commonly used to identify image file formats.</dd>
+<dt>RedRable</dt>
+<dd><a href="../javadoc/org/apache/batik/ext/awt/image/renderable/RedRable.html">RedRable</a> takes any <code>java.awt.image.RenderedImage</code> and wraps it into a <code>Filter</code> (Batikâs subinterface of <code>RenderableImage</code> ). This is very useful for <em>single resolution</em> file formats.</dd>
+<dt>DeferRable</dt>
+<dd><a href="../javadoc/org/apache/batik/ext/awt/image/renderable/DeferRable.html">DeferRable</a> allows one to load the image in a background thread, rather than hold up the construction of the GVT tree while reading the image (useful since reading the image is generally I/O bound, so it makes a good background task). This is used by most of the current image readers.</dd>
+<dt>AbstractRable</dt>
+<dd><a href="../javadoc/org/apache/batik/ext/awt/image/renderable/AbstractRable.html">AbstractRable</a> is an abstract base class that makes it relatively easy to implement the Filter interface.</dd>
+<dt>AbstractRed</dt>
+<dd><a href="../javadoc/org/apache/batik/ext/awt/image/rendered/AbstractRed.html">AbstractRed</a> is an abstract base class that makes it relatively easy to implement the <a href="../javadoc/org/apache/batik/ext/awt/image/rendered/CacheableRed.html">CacheableRed</a> interface (Batik's subclass of <code>RenderedImage</code> ).</dd>
+</dl>
+<h1 id="urlProtocols">New URL protocols</h1>
+<p>For a variety of reasons (not the least of which is the heavy use of the <code>data:</code> URL protocol in SVG), several parts of Batik use a <a href="../javadoc/org/apache/batik/util/ParsedURL.html">ParsedURL</a> instead of the JDKâs <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/net/URL.html">java.net.URL</a> class.</p>
+<p><code>ParsedURL</code> offers a few advantages over the JDKâs <code>URL</code> class. First, it is designed to make minimal use of exceptions, so it is possible to use it to parse a malformed URL and get âthe good partsâ. Second, it is extensible, so support for new URL protocols can be added, even those that change the normal parsing rules for URLs (such as our friend the <code>data:</code> protocol). Third, it can automatically check a when a stream can be opened for common compression types and decode them for you (this behavior can also be bypassed if needed).</p>
+<p>The service class is <a href="../javadoc/org/apache/batik/util/ParsedURLProtocolHandler.html">org.apache.batik.util.ParsedURLProtocolHandler</a> . This interface consists of three methods: one returns the protocol to be handled, one is for parsing an absolute URL string and one is for parsing relative URL strings. Both the parsing methods return an object of type <a href="../javadoc/org/apache/batik/util/ParsedURLData.html">ParsedURLData</a> (the instance may of course be a subclass of <code>ParsedURLData</code> ).</p>
+<p>The <code>ParsedURLData</code> class holds all the data and implements all the stream handling commands for the <code>ParsedURL</code> class. This allows <code>ParsedURLProtocolHandler</code> s to return custom subclasses for particular protocols.</p>
+<h1 id="interpreters">Additional script interpreters</h1>
+<p>While conforming SVG browsers need support only ECMAScript as a scripting language, Batik can support any scripting language given the right glue to connect it to the rest of the system.</p>
+<p>Script interpreters are also handled via the Service Provider Interface, The interface that needs to be implemented to expose a new interpreter to Batik is <a href="../javadoc/org/apache/batik/script/InterpreterFactory.html">InterpreterFactory</a> . This class has two methods: <code>getMimeType</code> , which returns a string that specifies what script type this intepreter handles (specifically, what the <code>type</code> attribute of <code>script</code> elements must be for them to be handled by this intepreter), and <code>createInterpreter</code> , which creates an instance of the <a href="../javadoc/org/apache/batik/script/Interpreter.html">Interpreter</a> interface.</p>
+<p>Batik comes with implementations of <code>Interpreter</code> and <code>IntepreterFactory</code> to support TCL and Python script in SVG documents, if the Jacl and Jython distributions are installed, respectively. See the classes in the <code>org.apache.batik.script.jacl</code> and <code>org.apache.batik.script.jython</code> packages to guidance on how to implement the interpreter interfaces, and the <a href="../install.html">installation notes</a> on what jar files are needed for TCL and Python support.</p></div></div>
+ <div class="clear"></div>
+
+ <div id="footer">
+ <a alt="Apache Software Foundation" href="http://www.apache.org">
+ <img id="asf-logo" alt="Apache Software Foundation" src="/images/feather-small.gif"/ width="100">
+ </a>
+ <div class="copyright">
+ <p>
+ Copyright © 2011 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, Apache XML Graphics, the Apache feather logo, and the Apache XML Graphics logos are
+ trademarks of <a href="http://www.apache.org">The Apache Software Foundation</a>. All other
+ marks mentioned may be trademarks or registered trademarks of their respective owners.
+ <br />
+ </p>
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/xmlgraphics/trunk/content/batik/using/index.html
==============================================================================
--- websites/staging/xmlgraphics/trunk/content/batik/using/index.html (added)
+++ websites/staging/xmlgraphics/trunk/content/batik/using/index.html Sun Apr 15 05:46:22 2012
@@ -0,0 +1,97 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+ <head>
+ <title>Using Batik</title>
+
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ <meta property="og:image" content="http://www.apache.org/images/asf_logo.gif" />
+<!--
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/style.css">
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/code.css">
+-->
+ <link href="/css/xmlgraphics.css" rel="stylesheet" type="text/css">
+
+ </style>
+
+
+
+
+
+ </head>
+
+ <body>
+ <div id="banner">
+ </div>
+
+ <div id="navigation">
+ <h1 id="xml-graphics">XML Graphics</h1>
+<ul>
+<li><a href="/">Overview</a></li>
+<li><a href="/team.html">Who We Are</a></li>
+<li><a href="/legal.html">Legal Stuff</a></li>
+<li><a href="/charter.html">Project Charter</a></li>
+<li><a href="/mail.html">Mailing Lists</a></li>
+<li><a href="/repo.html">Code Repositories</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">ASF Sponsorship Program</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">ASF Thanks</a></li>
+</ul>
+<h1 id="subprojects">Subprojects</h1>
+<ul>
+<li><a href="/batik/">Batik</a></li>
+<li><a href="/fop/">FOP</a></li>
+<li><a href="/commons/">Commons</a></li>
+</ul>
+<form name="search" id="search" action="http://www.google.com/search" method="get">
+ <input value="xmlgraphics.apache.org" name="sitesearch" type="hidden"/>
+ <input type="text" name="q" id="query" /><br />
+ <input type="submit" id="submit" value="Search" />
+</form>
+ </div>
+
+ <div id="bannertext">
+ <a href="/"><img src="/images/apache-xml-graphics.gif" alt="The Apache XML Graphics Project" width="220" heigh="51" /></a>
+ <h1>Using Batik</h1>
+ </div>
+ <p><a href="/">Home</a> » <a href="/batik/">Batik</a> » <a href="/batik/using/">Using</a></p>
+ </div>
+ <div id="content" class="grid_16"><div class="section-content"><p>The Batik toolkit has a number of modules that can be used to provide SVG support to your application. This section includes resources for explaining how to use these modules.</p>
+<dl>
+<dt>Architecture</dt>
+<dd>The <a href="../using/architecture.html">architecture</a> page gives an overview of how the various modules in Batik fit together.</dd>
+<dt>Javadoc APIs</dt>
+<dd>The <a href="../using/../javadoc/">Javadoc APIs</a> document all of the classes packaged with Batik.</dd>
+<dt>DOM API</dt>
+<dd>The <a href="../using/dom-api.html">DOM API</a> page explains how to use the DOM interfaces to create and render SVG documents.</dd>
+<dt>Parsers</dt>
+<dd>The <a href="../using/parsers.html">Parsers</a> page describes the parser classes that can be used for parsing the microsyntaxes of SVG (such as path data and transform lists).</dd>
+<dt>Scripting</dt>
+<dd>The scripting pages ( <a href="../using/scripting/ecmascript.html">Scriping with ECMAScript</a> , <a href="../using/scripting/java.html">Scripting with Java</a> and <a href="../using/scripting/security.html">Security</a> ) document how to programmatically manipulate SVG documents, and how script interpreters can be used and extended in Batik.</dd>
+<dt>SVG generator</dt>
+<dd>The <a href="../using/svg-generator.html">SVG Generator</a> page documents the <code>SVGGraphics2D</code> class, which can be used to construct SVG documents from Java2D drawing commands.</dd>
+<dt>Swing components</dt>
+<dd>The <a href="../using/swing.html">Swing components</a> page describes the SVG canvas component, the primary method for displaying SVG content in Swing applications.</dd>
+<dt>Transcoder API</dt>
+<dd>The <a href="../using/transcoder.html">Transcoder API</a> page explains how to use the transcoder classes to convert SVG content to other formats (raster or vector).</dd>
+<dt>Extending Batik</dt>
+<dd>The <a href="../using/extending.html">Extending Batik</a> page lists the parts of the Batik API that are extensible and explains how to add functionality to the existing modules.</dd>
+</dl></div></div>
+ <div class="clear"></div>
+
+ <div id="footer">
+ <a alt="Apache Software Foundation" href="http://www.apache.org">
+ <img id="asf-logo" alt="Apache Software Foundation" src="/images/feather-small.gif"/ width="100">
+ </a>
+ <div class="copyright">
+ <p>
+ Copyright © 2011 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, Apache XML Graphics, the Apache feather logo, and the Apache XML Graphics logos are
+ trademarks of <a href="http://www.apache.org">The Apache Software Foundation</a>. All other
+ marks mentioned may be trademarks or registered trademarks of their respective owners.
+ <br />
+ </p>
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/xmlgraphics/trunk/content/batik/using/parsers.html
==============================================================================
--- websites/staging/xmlgraphics/trunk/content/batik/using/parsers.html (added)
+++ websites/staging/xmlgraphics/trunk/content/batik/using/parsers.html Sun Apr 15 05:46:22 2012
@@ -0,0 +1,150 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+ <head>
+ <title>Parser module</title>
+
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ <meta property="og:image" content="http://www.apache.org/images/asf_logo.gif" />
+<!--
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/style.css">
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/code.css">
+-->
+ <link href="/css/xmlgraphics.css" rel="stylesheet" type="text/css">
+
+ </style>
+
+
+
+
+
+ </head>
+
+ <body>
+ <div id="banner">
+ </div>
+
+ <div id="navigation">
+ <h1 id="xml-graphics">XML Graphics</h1>
+<ul>
+<li><a href="/">Overview</a></li>
+<li><a href="/team.html">Who We Are</a></li>
+<li><a href="/legal.html">Legal Stuff</a></li>
+<li><a href="/charter.html">Project Charter</a></li>
+<li><a href="/mail.html">Mailing Lists</a></li>
+<li><a href="/repo.html">Code Repositories</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">ASF Sponsorship Program</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">ASF Thanks</a></li>
+</ul>
+<h1 id="subprojects">Subprojects</h1>
+<ul>
+<li><a href="/batik/">Batik</a></li>
+<li><a href="/fop/">FOP</a></li>
+<li><a href="/commons/">Commons</a></li>
+</ul>
+<form name="search" id="search" action="http://www.google.com/search" method="get">
+ <input value="xmlgraphics.apache.org" name="sitesearch" type="hidden"/>
+ <input type="text" name="q" id="query" /><br />
+ <input type="submit" id="submit" value="Search" />
+</form>
+ </div>
+
+ <div id="bannertext">
+ <a href="/"><img src="/images/apache-xml-graphics.gif" alt="The Apache XML Graphics Project" width="220" heigh="51" /></a>
+ <h1>Parser module</h1>
+ </div>
+ <p><a href="/">Home</a> » <a href="/batik/">Batik</a> » <a href="/batik/using/">Using</a></p>
+ </div>
+ <div id="content" class="grid_16"><div class="section-content"><p>SVG has a number of microsyntaxes that are used within attribute values, such as the <code>transform</code> attribute on <code>SVGTransformable</code> elements, and the path data <code>d</code> attribute on <code>path</code> elements. Since these are not trivial to parse, this functionality has been factored out into a separate package that can be used by other SVG-processing applications if needed.</p>
+<h1 id="parsersHandlersAndProducers">Parsers, handlers and producers</h1>
+<p>In the parser module, each microsyntax is supported by a pair of classes: a parser and a handler. The parser is a class that implements the <a href="../javadoc/org/apache/batik/parser/Parser.html">Parser</a> interface, which has methods to parse values from a <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/io/Reader.html">Reader</a> or a <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/String.html">String</a> . The handler is an interface specific to the microsyntax that will have its methods called whenever the corresponding element in the input is parsed. For those handler interfaces that have more than one method, adapter classes are provided (named <code>Default</code> *).</p>
+<p>Parsers can also have an error handler associated with them, whose single method <code>error</code> will be called when there is a problem parsing the input. If an error handler is not associated with a parser, a <a href="../javadoc/org/apache/batik/parser/ParseException.html">ParseException</a> will be thrown if an error occurs.</p>
+<p>The microsyntaxes supported by the parser module are:</p>
+<dl>
+<dt>Angles</dt>
+<dd>Implemented by <a href="../javadoc/org/apache/batik/parser/AngleParser.html">AngleParser</a> , handled with <a href="../javadoc/org/apache/batik/parser/AngleHandler.html">AngleHandler</a> . This parser is used for parsing angles formed by a floating point number followed by <code>deg</code> , <code>grad</code> or <code>rad</code> . It is not currently used by the rest of the Batik codebase.</dd>
+<dt>Clock values</dt>
+<dd>Implemented by <a href="../javadoc/org/apache/batik/parser/ClockParser.html">ClockParser</a> , handled with <a href="../javadoc/org/apache/batik/parser/ClockHandler.html">ClockHandler</a> . This parser is used for parsing SMIL <a href="http://www.w3.org/TR/smil-animation/#Timing-ClockValueSyntax">clock values</a> .</dd>
+<dt>Fragment identifiers</dt>
+<dd>Implemented by <a href="../javadoc/org/apache/batik/parser/FragmentIdentifierParser.html">FragmentIdentifierParser</a> , handled with <a href="../javadoc/org/apache/batik/parser/FragmentIdentifierHandler.html">FragmentIdentifierHandler</a> . This parser is used for parsing the various formats of <a href="http://www.w3.org/TR/SVG11/linking.html#SVGFragmentIdentifiers">fragment identifier</a> that SVG allows.</dd>
+<dt>Lengths</dt>
+<dd>Implemented by <a href="../javadoc/org/apache/batik/parser/LengthParser.html">LengthParser</a> , handled with <a href="../javadoc/org/apache/batik/parser/LengthHandler.html">LengthHandler</a> . This parser is used for parsing SVG length values.</dd>
+<dt>Length lists</dt>
+<dd>Implemented by <a href="../javadoc/org/apache/batik/parser/LengthListParser.html">LengthListParser</a> , handled with <a href="../javadoc/org/apache/batik/parser/LengthListHandler.html">LengthListHandler</a> . This parser is used for parsing lists of comma or space separated SVG lengths.</dd>
+<dt>Numbers</dt>
+<dd>Implemented by <a href="../javadoc/org/apache/batik/parser/NumberListParser.html">NumberListParser</a> , handled with <a href="../javadoc/org/apache/batik/parser/NumberListHandler.html">NumberListHandler</a> . This parser is used for parsing SVG number values.</dd>
+<dt>Number lists</dt>
+<dd>Implemented by <a href="../javadoc/org/apache/batik/parser/NumberListParser.html">NumberListParser</a> , handled with <a href="../javadoc/org/apache/batik/parser/NumberListHandler.html">NumberListHandler</a> . This parser is used for parsing lists of comma or space separated SVG numbers.</dd>
+<dt>Path data</dt>
+<dd>Implemented by <a href="../javadoc/org/apache/batik/parser/PathParser.html">PathParser</a> , handled with <a href="../javadoc/org/apache/batik/parser/PathHandler.html">PathHandler</a> . This parser is used for parsing SVG path data, as found in <code>path</code> element <code>d</code> attributes.</dd>
+<dt>Points</dt>
+<dd>Implemented by <a href="../javadoc/org/apache/batik/parser/PointsParser.html">PointsParser</a> , handled with <a href="../javadoc/org/apache/batik/parser/PointsHandler.html">PointsHandler</a> . This parser is used for parsing point lists, as found in <code>polygon</code> element <code>points</code> attributes.</dd>
+<dt>Preserve aspect ratio values</dt>
+<dd>Implemented by <a href="../javadoc/org/apache/batik/parser/PreserveAspectRatioParser.html">PreserveAspectRatioParser</a> , handled with <a href="../javadoc/org/apache/batik/parser/PreserveAspectRatioHandler.html">PreserveAspectRatioHandler</a> . This parser is used for parsing the values found in the <code>preserveAspectRatio</code> attribute of <code>svg</code> elements.</dd>
+<dt>Transform lists</dt>
+<dd>Implemented by <a href="../javadoc/org/apache/batik/parser/TransformListParser.html">TransformListParser</a> , handled with <a href="../javadoc/org/apache/batik/parser/TransformListHandler.html">TransformListHandler</a> . This parser is used for parsing transform lists, as found in the <code>transform</code> attribute of any transformable element.</dd>
+</dl>
+<p>Some microsyntaxes also have a corresponding producer class, which is an implementation of the handler interface that generates an object while parsing.</p>
+<h1 id="examples">Examples</h1>
+<p>The following example code demonstrates how to use the parser classes to parse a list of points:
+import java.awt.geom.Point2D;
+import java.util.LinkedList;
+import java.util.List;</p>
+<p>import org.apache.batik.parser.DefaultPointsHandler;
+import org.apache.batik.parser.ParseException;
+import org.apache.batik.parser.PointsHandler;
+import org.apache.batik.parser.PointsParser;</p>
+<p>public class PointsParserExample {</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">List</span> <span class="n">extractPoints</span><span class="p">(</span><span class="n">String</span> <span class="n">s</span><span class="p">)</span> <span class="n">throws</span> <span class="n">ParseException</span> <span class="p">{</span>
+ <span class="n">final</span> <span class="n">LinkedList</span> <span class="n">points</span> <span class="o">=</span> <span class="k">new</span> <span class="n">LinkedList</span><span class="p">();</span>
+ <span class="n">PointsParser</span> <span class="n">pp</span> <span class="o">=</span> <span class="k">new</span> <span class="n">PointsParser</span><span class="p">();</span>
+ <span class="n">PointsHandler</span> <span class="n">ph</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultPointsHandler</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">point</span><span class="p">(</span><span class="n">float</span> <span class="n">x</span><span class="p">,</span> <span class="n">float</span> <span class="n">y</span><span class="p">)</span> <span class="n">throws</span> <span class="n">ParseException</span> <span class="p">{</span>
+ <span class="n">Point2D</span> <span class="n">p</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Point2D</span><span class="o">.</span><span class="n">Float</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">);</span>
+ <span class="n">points</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">p</span><span class="p">);</span>
+ <span class="p">}</span>
+ <span class="p">};</span>
+ <span class="n">pp</span><span class="o">.</span><span class="n">setPointsHandler</span><span class="p">(</span><span class="n">ph</span><span class="p">);</span>
+ <span class="n">pp</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="n">s</span><span class="p">);</span>
+ <span class="k">return</span> <span class="n">points</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>}
+This example uses the <a href="../javadoc/org/apache/batik/parser/AWTTransformProducer.html">AWTTransformProducer</a> class to generate an <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/awt/geom/AffineTransform.html">AffineTransform</a> object from an SVG transform list:
+import java.awt.geom.AffineTransform;</p>
+<p>import org.apache.batik.parser.AWTTransformProducer;
+import org.apache.batik.parser.ParseException;
+import org.apache.batik.parser.TransformListParser;</p>
+<p>public class TransformParserExample {</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">AffineTransform</span> <span class="n">parseTransformList</span><span class="p">(</span><span class="n">String</span> <span class="n">s</span><span class="p">)</span> <span class="n">throws</span> <span class="n">ParseException</span> <span class="p">{</span>
+ <span class="n">TransformListParser</span> <span class="n">p</span> <span class="o">=</span> <span class="k">new</span> <span class="n">TransformListParser</span><span class="p">();</span>
+ <span class="n">AWTTransformProducer</span> <span class="n">tp</span> <span class="o">=</span> <span class="k">new</span> <span class="n">AWTTransformProducer</span><span class="p">();</span>
+ <span class="n">p</span><span class="o">.</span><span class="n">setTransformListHandler</span><span class="p">(</span><span class="n">tp</span><span class="p">);</span>
+ <span class="n">p</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="n">s</span><span class="p">);</span>
+ <span class="k">return</span> <span class="n">tp</span><span class="o">.</span><span class="n">getAffineTransform</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>}</p></div></div>
+ <div class="clear"></div>
+
+ <div id="footer">
+ <a alt="Apache Software Foundation" href="http://www.apache.org">
+ <img id="asf-logo" alt="Apache Software Foundation" src="/images/feather-small.gif"/ width="100">
+ </a>
+ <div class="copyright">
+ <p>
+ Copyright © 2011 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, Apache XML Graphics, the Apache feather logo, and the Apache XML Graphics logos are
+ trademarks of <a href="http://www.apache.org">The Apache Software Foundation</a>. All other
+ marks mentioned may be trademarks or registered trademarks of their respective owners.
+ <br />
+ </p>
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/xmlgraphics/trunk/content/batik/using/scripting/ecmascript.html
==============================================================================
--- websites/staging/xmlgraphics/trunk/content/batik/using/scripting/ecmascript.html (added)
+++ websites/staging/xmlgraphics/trunk/content/batik/using/scripting/ecmascript.html Sun Apr 15 05:46:22 2012
@@ -0,0 +1,198 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+ <head>
+ <title>Scripting with ECMAScript</title>
+
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ <meta property="og:image" content="http://www.apache.org/images/asf_logo.gif" />
+<!--
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/style.css">
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/code.css">
+-->
+ <link href="/css/xmlgraphics.css" rel="stylesheet" type="text/css">
+
+ </style>
+
+
+
+
+
+ </head>
+
+ <body>
+ <div id="banner">
+ </div>
+
+ <div id="navigation">
+ <h1 id="xml-graphics">XML Graphics</h1>
+<ul>
+<li><a href="/">Overview</a></li>
+<li><a href="/team.html">Who We Are</a></li>
+<li><a href="/legal.html">Legal Stuff</a></li>
+<li><a href="/charter.html">Project Charter</a></li>
+<li><a href="/mail.html">Mailing Lists</a></li>
+<li><a href="/repo.html">Code Repositories</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">ASF Sponsorship Program</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">ASF Thanks</a></li>
+</ul>
+<h1 id="subprojects">Subprojects</h1>
+<ul>
+<li><a href="/batik/">Batik</a></li>
+<li><a href="/fop/">FOP</a></li>
+<li><a href="/commons/">Commons</a></li>
+</ul>
+<form name="search" id="search" action="http://www.google.com/search" method="get">
+ <input value="xmlgraphics.apache.org" name="sitesearch" type="hidden"/>
+ <input type="text" name="q" id="query" /><br />
+ <input type="submit" id="submit" value="Search" />
+</form>
+ </div>
+
+ <div id="bannertext">
+ <a href="/"><img src="/images/apache-xml-graphics.gif" alt="The Apache XML Graphics Project" width="220" heigh="51" /></a>
+ <h1>Scripting with ECMAScript</h1>
+ </div>
+ <p><a href="/">Home</a> » <a href="/batik/">Batik</a> » <a href="/batik/using/">Using</a> » <a href="/batik/using/scripting/">Scripting</a></p>
+ </div>
+ <div id="content" class="grid_16"><div class="section-content"><p>This page is a brief introduction to scripting SVG documents with ECMAScript, and how Batikâs ECMAScript environment can be extended.</p>
+<h1 id="scriptingBasics">Scripting basics</h1>
+<p>As the ECMAScript language (the standardised version of JavaScript) is one of the most popular scripting languages, and as the SVG specification states that an SVG conforming implementation must support it, SVG documents processed by Batik support scripting with ECMAScript using Mozillaâs ECMAScript interpreter, <a href="http://www.mozilla.org/rhino/">Rhino</a> .</p>
+<p>There are two places in an SVG file where you can put scripts.</p>
+<p>The first one is in the <code>script</code> element, where you can place any code, including function definitions, to be executed just before the document <code>SVGLoad</code> event is fired.
+<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
+ <script type="text/ecmascript">
+ // ECMAScript code to be executed
+ </script></p>
+<p><!-- Remainder of the document... -->
+</svg>
+You can also attach script to respond to user or document events using attributes on SVG elements. As shown in the previous example, the scripting language must be set on the <code>script</code> element. However, for event handling the default language type <code>text/ecmascript</code> is assumed. If you want to change it you can use the <code>contentScriptType</code> attribute on the <code>svg</code> element.</p>
+<p>The event attribute can contain any script code to execute when the event reaches the element (as described by the <a href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-flow">DOM event flow</a> ) in either the bubbling or at-target phases. The following example will change the <code>rect</code> to be filled in blue when it is clicked.
+<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
+ <rect x="0" y="0" width="10" height="10"
+ onclick="evt.target.setAttribute('fill', 'blue')"/>
+</svg>
+Note that inside the event attribute script, there is a variable called <code>evt</code> that is a reference to the <a href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-Event">Event</a> object that represents the event that is being handled.</p>
+<p>For more information on using scripting in SVG you can have a look at:</p>
+<ul>
+<li>
+<p>the <a href="http://www.w3.org/TR/SVG11/script.html">scripting chapter of the SVG specification</a> , for advanced information on scripting in SVG, and</p>
+</li>
+<li>
+<p>the <a href="http://www.ecma.ch/ecma1/stand/ecma-262.htm">ECMAScript specification</a> , for advanced information on the ECMAScript language.</p>
+</li>
+</ul>
+<h1 id="rhinoFeatures">Using Rhino features</h1>
+<p>Rhino has a number of features beyond those supported by standard ECMAScript interpreters, and these can be used with Batik. One useful feature is that ECMAScript code can use Java classes and objects, and not just the standard ECMAScript primitive types and host objects exposed by Batik.</p>
+<p>To create an instance of a Java class from ECMAScript, you first need to import the package in which it resides. This is done using the <code>importPackage</code> global function that Rhino provides. For example, to import the <code>javax.swing.JFrame</code> class, you use:
+importPackage(Packages.javax.swing);
+This then exposes a global property for each class in the <code>javax.swing</code> package that you can use to create a new object of this class, similar to a <code>import javax.swing.*;</code> statement in Java. We can use the exposed <code>JFrame</code> property to create a new instance of this class:
+var frame = new JFrame("My test frame");
+Note how an ECMAScript string value is passed as the parameter to <code>JFrame</code> âs constructor. Rhino will attempt to convert ECMAScript values into appropriate Java primitive types or objects to make underlying constructor or method calls. In this instance, the ECMAScript string value is converted into a <code>java.lang.String</code> object to be passed to the constructor.</p>
+<p>Now that we have a reference to this Java object, we can call any method on it as we usually would from Java code. The following complete example demonstrates this, where clicking the green circle will pop up a frame:
+<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
+ <circle cx="50" cy="50" r="50" fill="green" onclick="showFrame()"/>
+ <script type="text/ecmascript">
+ importPackage(Packages.javax.swing);</p>
+<div class="codehilite"><pre><span class="n">function</span> <span class="n">showFrame</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">var</span> <span class="n">frame</span> <span class="o">=</span> <span class="k">new</span> <span class="n">JFrame</span><span class="p">(</span><span class="s">"My test frame"</span><span class="p">);</span>
+ <span class="n">var</span> <span class="n">label</span> <span class="o">=</span> <span class="k">new</span> <span class="n">JLabel</span><span class="p">(</span><span class="s">"Hello from Java objects created in ECMAScript!"</span><span class="p">);</span>
+ <span class="n">label</span><span class="o">.</span><span class="n">setHorizontalAlignment</span><span class="p">(</span><span class="n">SwingConstants</span><span class="o">.</span><span class="n">CENTER</span><span class="p">);</span>
+ <span class="n">frame</span><span class="o">.</span><span class="n">getContentPane</span><span class="p">()</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">label</span><span class="p">);</span>
+ <span class="n">frame</span><span class="o">.</span><span class="n">setSize</span><span class="p">(</span><span class="mi">400</span><span class="p">,</span> <span class="mi">100</span><span class="p">);</span>
+ <span class="n">frame</span><span class="o">.</span><span class="n">setVisible</span><span class="p">(</span><span class="n">true</span><span class="p">);</span>
+ <span class="n">frame</span><span class="o">.</span><span class="n">setDefaultCloseOperation</span><span class="p">(</span><span class="n">WindowConstants</span><span class="o">.</span><span class="n">DISPOSE_ON_CLOSE</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p></script>
+</svg>
+For more information on scripting Java classes from ECMAScript code, see Rhino's <a href="http://www.mozilla.org/rhino/ScriptingJava.html">Scripting Java</a> document.</p>
+<h1 id="customizingRhino">Customizing the Rhino interpreter</h1>
+<p>A useful example of customization of the Rhino interpreter comes from the fact that the ECMAScript specification doesnât provide any predefined I/O facilities to interact with the console. However, it is very common for ECMAScript compatible languages to provide a function named <code>print</code> to output messages to the console. We will describe here an example of cutomization of the Batik Rhino interpreter to add such functionality to it.</p>
+<p>You should first subclass the default Batik ECMAScript interpreter to add the functionality to it as below.
+import org.apache.batik.script.rhino.RhinoInterpreter;</p>
+<p>import java.net.URL;</p>
+<p>import org.mozilla.javascript.Context;
+import org.mozilla.javascript.Function;
+import org.mozilla.javascript.Scriptable;
+import org.mozilla.javascript.ScriptableObject;
+import org.mozilla.javascript.PropertyException;</p>
+<p>public class ExtendedRhinoInterpreter extends RhinoInterpreter {</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">ExtendedRhinoInterpreter</span><span class="p">(</span><span class="n">URL</span> <span class="n">documentURL</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">super</span><span class="p">(</span><span class="n">documentURL</span><span class="p">);</span>
+
+ <span class="sr">//</span> <span class="n">Array</span> <span class="n">of</span> <span class="n">functions</span> <span class="n">to</span> <span class="n">put</span> <span class="n">in</span> <span class="n">the</span> <span class="n">global</span> <span class="n">object</span><span class="o">.</span>
+ <span class="n">final</span> <span class="n">String</span><span class="o">[]</span> <span class="n">names</span> <span class="o">=</span> <span class="p">{</span> <span class="s">"print"</span> <span class="p">}</span>
+ <span class="n">try</span> <span class="p">{</span>
+ <span class="sr">//</span> <span class="n">Add</span> <span class="n">the</span> <span class="n">functions</span> <span class="n">to</span> <span class="n">the</span> <span class="n">global</span> <span class="n">object</span><span class="o">.</span>
+ <span class="n">getGlobalObject</span><span class="p">()</span><span class="o">.</span><span class="n">defineFunctionProperties</span>
+ <span class="p">(</span><span class="n">names</span><span class="p">,</span> <span class="n">ExtendedRhinoInterpreter</span><span class="o">.</span><span class="n">class</span><span class="p">,</span>
+ <span class="n">ScriptableObject</span><span class="o">.</span><span class="n">DONTENUM</span><span class="p">);</span>
+ <span class="p">}</span> <span class="n">catch</span> <span class="p">(</span><span class="n">PropertyException</span> <span class="n">e</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">throw</span> <span class="k">new</span> <span class="n">Error</span><span class="p">(</span><span class="n">e</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+
+<span class="n">public</span> <span class="n">static</span> <span class="n">void</span> <span class="k">print</span><span class="p">(</span><span class="n">Context</span> <span class="n">cx</span><span class="p">,</span> <span class="n">Scriptable</span> <span class="n">thisObj</span><span class="p">,</span>
+ <span class="n">Object</span><span class="o">[]</span> <span class="n">args</span><span class="p">,</span> <span class="n">Function</span> <span class="n">funObj</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="nb">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">args</span><span class="o">.</span><span class="nb">length</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">i</span> <span class="o">></span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">System</span><span class="o">.</span><span class="n">out</span><span class="o">.</span><span class="k">print</span><span class="p">(</span><span class="s">" "</span><span class="p">);</span>
+ <span class="p">}</span>
+
+ <span class="sr">//</span> <span class="n">Convert</span> <span class="n">the</span> <span class="n">ECMAScript</span> <span class="n">value</span> <span class="n">into</span> <span class="n">a</span> <span class="n">string</span> <span class="n">form</span><span class="o">.</span>
+ <span class="n">String</span> <span class="n">s</span> <span class="o">=</span> <span class="n">Context</span><span class="o">.</span><span class="n">toString</span><span class="p">(</span><span class="n">args</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span>
+ <span class="n">System</span><span class="o">.</span><span class="n">out</span><span class="o">.</span><span class="k">print</span><span class="p">(</span><span class="n">s</span><span class="p">);</span>
+ <span class="p">}</span>
+ <span class="n">System</span><span class="o">.</span><span class="n">out</span><span class="o">.</span><span class="n">println</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>}
+Now, you need to tell to Batik to use this interpreter instead of the default one. For that, you must first define a factory to create instances of your interpreter.
+import org.apache.batik.script.Interpreter;
+import org.apache.batik.script.rhino.RhinoInterpreterFactory;</p>
+<p>public class ExtendedRhinoInterpreterFactory extends RhinoInterpreterFactory {</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">Interpreter</span> <span class="n">createInterpreter</span><span class="p">(</span><span class="n">URL</span> <span class="n">documentURL</span><span class="p">,</span> <span class="n">boolean</span> <span class="n">isSVG12</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="k">new</span> <span class="n">ExtendedRhinoInterpreter</span><span class="p">(</span><span class="n">documentURL</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>}
+Then, you must build an <a href="../../javadoc/org/apache/batik/script/InterpreterPool.html">IntepreterPool</a> that will use this factory, and then set the pool on the <a href="../../javadoc/org/apache/batik/bridge/BridgeContext.html">BridgeContext</a> of your application.
+org.apache.batik.bridge.BridgeContext ctx = ...;
+org.apache.batik.script.InterpreterPool pool =
+ new org.apache.batik.script.InterpreterPool();
+InterpreterFactory f = new ExtendedRhinoInterpreterFactory();</p>
+<p>// Register the interpreter factory for all four MIME types that
+// Batik normally supports for ECMAScript.
+pool.putInterpreterFactory("text/ecmascript", f);
+pool.putInterpreterFactory("text/javascript", f);
+pool.putInterpreterFactory("application/ecmascript", f);
+pool.putInterpreterFactory("application/javascript", f);
+ctx.setIntepreterPool(pool);
+For example if you are using the Batik SVG browser application you should be able to use the previous piece of code on a subclass of the <a href="../../javadoc/org/apache/batik/swing/JSVGCanvas.html">JSVGCanvas</a> class in the <code>createBridgeContext()</code> method.</p>
+<p>For further information on working with Rhino, consult the <a href="http://www.mozilla.org/rhino/">Rhino website</a> .</p></div></div>
+ <div class="clear"></div>
+
+ <div id="footer">
+ <a alt="Apache Software Foundation" href="http://www.apache.org">
+ <img id="asf-logo" alt="Apache Software Foundation" src="/images/feather-small.gif"/ width="100">
+ </a>
+ <div class="copyright">
+ <p>
+ Copyright © 2011 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, Apache XML Graphics, the Apache feather logo, and the Apache XML Graphics logos are
+ trademarks of <a href="http://www.apache.org">The Apache Software Foundation</a>. All other
+ marks mentioned may be trademarks or registered trademarks of their respective owners.
+ <br />
+ </p>
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/xmlgraphics/trunk/content/batik/using/scripting/java.html
==============================================================================
--- websites/staging/xmlgraphics/trunk/content/batik/using/scripting/java.html (added)
+++ websites/staging/xmlgraphics/trunk/content/batik/using/scripting/java.html Sun Apr 15 05:46:22 2012
@@ -0,0 +1,236 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+ <head>
+ <title>Scripting With Java</title>
+
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ <meta property="og:image" content="http://www.apache.org/images/asf_logo.gif" />
+<!--
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/style.css">
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/code.css">
+-->
+ <link href="/css/xmlgraphics.css" rel="stylesheet" type="text/css">
+
+ </style>
+
+
+
+
+
+ </head>
+
+ <body>
+ <div id="banner">
+ </div>
+
+ <div id="navigation">
+ <h1 id="xml-graphics">XML Graphics</h1>
+<ul>
+<li><a href="/">Overview</a></li>
+<li><a href="/team.html">Who We Are</a></li>
+<li><a href="/legal.html">Legal Stuff</a></li>
+<li><a href="/charter.html">Project Charter</a></li>
+<li><a href="/mail.html">Mailing Lists</a></li>
+<li><a href="/repo.html">Code Repositories</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">ASF Sponsorship Program</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">ASF Thanks</a></li>
+</ul>
+<h1 id="subprojects">Subprojects</h1>
+<ul>
+<li><a href="/batik/">Batik</a></li>
+<li><a href="/fop/">FOP</a></li>
+<li><a href="/commons/">Commons</a></li>
+</ul>
+<form name="search" id="search" action="http://www.google.com/search" method="get">
+ <input value="xmlgraphics.apache.org" name="sitesearch" type="hidden"/>
+ <input type="text" name="q" id="query" /><br />
+ <input type="submit" id="submit" value="Search" />
+</form>
+ </div>
+
+ <div id="bannertext">
+ <a href="/"><img src="/images/apache-xml-graphics.gif" alt="The Apache XML Graphics Project" width="220" heigh="51" /></a>
+ <h1>Scripting With Java</h1>
+ </div>
+ <p><a href="/">Home</a> » <a href="/batik/">Batik</a> » <a href="/batik/using/">Using</a> » <a href="/batik/using/scripting/">Scripting</a></p>
+ </div>
+ <div id="content" class="grid_16"><div class="section-content"><p>This page explains how to manipulate the DOM tree of an SVG document from a Java program.</p>
+<h1 id="Swing">How to manipulate a document in a JSVGCanvas</h1>
+<p>The follow code template demonstrates how to manipulate an SVG document displayed in a <a href="../../javadoc/org/apache/batik/swing/JSVGCanvas.html">JSVGCanvas</a> directly from a Java program.
+You donât have to worry about graphics updates; after each event listener invocation the canvas is updated if needed.import java.awt.event.WindowAdapter;
+import java.awt.event.WindowEvent;</p>
+<p>import javax.swing.JFrame;</p>
+<p>import org.apache.batik.swing.JSVGCanvas;
+import org.apache.batik.swing.svg.SVGLoadEventDispatcherAdapter;
+import org.apache.batik.swing.svg.SVGLoadEventDispatcherEvent;
+import org.apache.batik.script.Window;</p>
+<p>import org.w3c.dom.Document;
+import org.w3c.dom.Element;
+import org.w3c.dom.events.Event;
+import org.w3c.dom.events.EventListener;
+import org.w3c.dom.events.EventTarget;</p>
+<p>public class SVGApplication {</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">static</span> <span class="n">void</span> <span class="n">main</span><span class="p">(</span><span class="n">String</span><span class="o">[]</span> <span class="n">args</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">new</span> <span class="n">SVGApplication</span><span class="p">();</span>
+<span class="p">}</span>
+
+<span class="n">JFrame</span> <span class="n">frame</span><span class="p">;</span>
+<span class="n">JSVGCanvas</span> <span class="n">canvas</span><span class="p">;</span>
+<span class="n">Document</span> <span class="n">document</span><span class="p">;</span>
+<span class="n">Window</span> <span class="n">window</span><span class="p">;</span>
+
+<span class="n">public</span> <span class="n">SVGApplication</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">frame</span> <span class="o">=</span> <span class="k">new</span> <span class="n">JFrame</span><span class="p">();</span>
+ <span class="n">canvas</span> <span class="o">=</span> <span class="k">new</span> <span class="n">JSVGCanvas</span><span class="p">();</span>
+ <span class="sr">//</span> <span class="n">Forces</span> <span class="n">the</span> <span class="n">canvas</span> <span class="n">to</span> <span class="n">always</span> <span class="n">be</span> <span class="n">dynamic</span> <span class="n">even</span> <span class="k">if</span> <span class="n">the</span> <span class="n">current</span>
+ <span class="sr">//</span> <span class="n">document</span> <span class="n">does</span> <span class="ow">not</span> <span class="n">contain</span> <span class="n">scripting</span> <span class="ow">or</span> <span class="n">animation</span><span class="o">.</span>
+ <span class="n">canvas</span><span class="o">.</span><span class="n">setDocumentState</span><span class="p">(</span><span class="n">JSVGCanvas</span><span class="o">.</span><span class="n">ALWAYS_DYNAMIC</span><span class="p">);</span>
+ <span class="n">canvas</span><span class="o">.</span><span class="n">addSVGLoadEventDispatcherListener</span>
+ <span class="p">(</span><span class="k">new</span> <span class="n">SVGLoadEventDispatcherAdapter</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">svgLoadEventDispatchStarted</span>
+ <span class="p">(</span><span class="n">SVGLoadEventDispatcherEvent</span> <span class="n">e</span><span class="p">)</span> <span class="p">{</span>
+ <span class="sr">//</span> <span class="n">At</span> <span class="n">this</span> <span class="nb">time</span> <span class="n">the</span> <span class="n">document</span> <span class="n">is</span> <span class="n">available</span><span class="o">...</span>
+ <span class="n">document</span> <span class="o">=</span> <span class="n">canvas</span><span class="o">.</span><span class="n">getSVGDocument</span><span class="p">();</span>
+ <span class="sr">//</span> <span class="o">...</span><span class="ow">and</span> <span class="n">the</span> <span class="n">window</span> <span class="n">object</span> <span class="n">too</span><span class="o">.</span>
+ <span class="n">window</span> <span class="o">=</span> <span class="n">canvas</span><span class="o">.</span><span class="n">getUpdateManager</span><span class="p">()</span><span class="o">.</span>
+ <span class="n">getScriptingEnvironment</span><span class="p">()</span><span class="o">.</span><span class="n">createWindow</span><span class="p">();</span>
+ <span class="sr">//</span> <span class="n">Registers</span> <span class="n">the</span> <span class="n">listeners</span> <span class="n">on</span> <span class="n">the</span> <span class="n">document</span>
+ <span class="sr">//</span> <span class="n">just</span> <span class="n">before</span> <span class="n">the</span> <span class="n">SVGLoad</span> <span class="n">event</span> <span class="n">is</span>
+ <span class="sr">//</span> <span class="n">dispatched</span><span class="o">.</span>
+ <span class="n">registerListeners</span><span class="p">();</span>
+ <span class="sr">//</span> <span class="n">It</span> <span class="n">is</span> <span class="nb">time</span> <span class="n">to</span> <span class="nb">pack</span> <span class="n">the</span> <span class="n">frame</span><span class="o">.</span>
+ <span class="n">frame</span><span class="o">.</span><span class="nb">pack</span><span class="p">();</span>
+ <span class="p">}</span>
+ <span class="p">});</span>
+
+ <span class="n">frame</span><span class="o">.</span><span class="n">addWindowListener</span><span class="p">(</span><span class="k">new</span> <span class="n">WindowAdapter</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">windowOpened</span><span class="p">(</span><span class="n">WindowEvent</span> <span class="n">e</span><span class="p">)</span> <span class="p">{</span>
+ <span class="sr">//</span> <span class="n">The</span> <span class="n">canvas</span> <span class="n">is</span> <span class="n">ready</span> <span class="n">to</span> <span class="n">load</span> <span class="n">the</span> <span class="n">base</span> <span class="n">document</span>
+ <span class="sr">//</span> <span class="n">now</span><span class="p">,</span> <span class="n">from</span> <span class="n">the</span> <span class="n">AWT</span> <span class="n">thread</span><span class="o">.</span>
+ <span class="n">canvas</span><span class="o">.</span><span class="n">setURI</span><span class="p">(</span><span class="s">"doc.svg"</span><span class="p">);</span>
+ <span class="p">}</span>
+ <span class="p">});</span>
+
+ <span class="n">frame</span><span class="o">.</span><span class="n">getContentPane</span><span class="p">()</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">canvas</span><span class="p">);</span>
+ <span class="n">frame</span><span class="o">.</span><span class="n">setSize</span><span class="p">(</span><span class="mi">800</span><span class="p">,</span> <span class="mi">600</span><span class="p">);</span>
+ <span class="n">frame</span><span class="o">.</span><span class="n">show</span><span class="p">();</span>
+<span class="p">}</span>
+
+<span class="n">public</span> <span class="n">void</span> <span class="n">registerListeners</span><span class="p">()</span> <span class="p">{</span>
+ <span class="sr">//</span> <span class="n">Gets</span> <span class="n">an</span> <span class="n">element</span> <span class="n">from</span> <span class="n">the</span> <span class="n">loaded</span> <span class="n">document</span><span class="o">.</span>
+ <span class="n">Element</span> <span class="n">elt</span> <span class="o">=</span> <span class="n">document</span><span class="o">.</span><span class="n">getElementById</span><span class="p">(</span><span class="s">"elt-id"</span><span class="p">);</span>
+ <span class="n">EventTarget</span> <span class="n">t</span> <span class="o">=</span> <span class="p">(</span><span class="n">EventTarget</span><span class="p">)</span><span class="n">elt</span><span class="p">;</span>
+
+ <span class="sr">//</span> <span class="n">Adds</span> <span class="n">a</span> <span class="s">'onload'</span> <span class="n">listener</span>
+ <span class="n">t</span><span class="o">.</span><span class="n">addEventListener</span><span class="p">(</span><span class="s">"SVGLoad"</span><span class="p">,</span> <span class="k">new</span> <span class="n">OnLoadAction</span><span class="p">(),</span> <span class="n">false</span><span class="p">);</span>
+
+ <span class="sr">//</span> <span class="n">Adds</span> <span class="n">a</span> <span class="s">'onclick'</span> <span class="n">listener</span>
+ <span class="n">t</span><span class="o">.</span><span class="n">addEventListener</span><span class="p">(</span><span class="s">"click"</span><span class="p">,</span> <span class="k">new</span> <span class="n">OnClickAction</span><span class="p">(),</span> <span class="n">false</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="n">public</span> <span class="n">class</span> <span class="n">OnLoadAction</span> <span class="n">implements</span> <span class="n">EventListener</span> <span class="p">{</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">handleEvent</span><span class="p">(</span><span class="n">Event</span> <span class="n">evt</span><span class="p">)</span> <span class="p">{</span>
+ <span class="sr">//</span> <span class="n">Perform</span> <span class="n">some</span> <span class="n">actions</span> <span class="n">here</span><span class="o">...</span>
+
+ <span class="sr">//</span> <span class="o">...</span><span class="k">for</span> <span class="n">example</span> <span class="n">start</span> <span class="n">an</span> <span class="n">animation</span> <span class="n">loop:</span>
+ <span class="n">window</span><span class="o">.</span><span class="n">setInterval</span><span class="p">(</span><span class="k">new</span> <span class="n">Animation</span><span class="p">(),</span> <span class="mi">50</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+
+<span class="n">public</span> <span class="n">class</span> <span class="n">OnClickAction</span> <span class="n">implements</span> <span class="n">EventListener</span> <span class="p">{</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">handleEvent</span><span class="p">(</span><span class="n">Event</span> <span class="n">evt</span><span class="p">)</span> <span class="p">{</span>
+ <span class="sr">//</span> <span class="n">Perform</span> <span class="n">some</span> <span class="n">actions</span> <span class="n">here</span><span class="o">...</span>
+
+ <span class="sr">//</span> <span class="o">...</span><span class="k">for</span> <span class="n">example</span> <span class="n">schedule</span> <span class="n">an</span> <span class="n">action</span> <span class="k">for</span> <span class="n">later:</span>
+ <span class="n">window</span><span class="o">.</span><span class="n">setTimeout</span><span class="p">(</span><span class="k">new</span> <span class="n">DelayedTask</span><span class="p">(),</span> <span class="mi">500</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+
+<span class="n">public</span> <span class="n">class</span> <span class="n">Animation</span> <span class="n">implements</span> <span class="n">Runnable</span> <span class="p">{</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">run</span><span class="p">()</span> <span class="p">{</span>
+ <span class="sr">//</span> <span class="n">Insert</span> <span class="n">animation</span> <span class="n">code</span> <span class="n">here</span><span class="o">...</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+
+<span class="n">public</span> <span class="n">class</span> <span class="n">DelayedTask</span> <span class="n">implements</span> <span class="n">Runnable</span> <span class="p">{</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">run</span><span class="p">()</span> <span class="p">{</span>
+ <span class="sr">//</span> <span class="n">Perform</span> <span class="n">some</span> <span class="n">actions</span> <span class="n">here</span><span class="o">...</span>
+
+ <span class="sr">//</span> <span class="o">...</span><span class="k">for</span> <span class="n">example</span> <span class="n">displays</span> <span class="n">an</span> <span class="n">alert</span> <span class="n">dialog:</span>
+ <span class="n">window</span><span class="o">.</span><span class="n">alert</span><span class="p">(</span><span class="s">"Delayed Action invoked!"</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>}</p>
+<h1 id="Threads">Writing thread-safe code</h1>
+<p>The DOM listeners registered on the SVG document are called from the canvas update thread. To avoid race conditions, do not manipulate the DOM tree from another thread.</p>
+<p>The way to switch from an external thread to the canvas update thread is to use the following code:
+// Returns immediately
+canvas.getUpdateManager().getUpdateRunnableQueue().
+ invokeLater(new Runnable() {
+ public void run() {
+ // Insert some actions on the DOM here
+ }
+ });
+or:
+// Waits until the Runnable is invoked
+canvas.getUpdateManager().getUpdateRunnableQueue().
+ invokeAndWait(new Runnable() {
+ public void run() {
+ // Insert some actions on the DOM here
+ }
+ });
+Like with event listeners, when a <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Runnable.html">Runnable</a> is invoked from the update thread, the graphics are updated.
+It is very dangerous to call <code>invokeAndWait</code> from the Swing event thread. This is the only thread that can be used to interact with Swing components. In some cases DOM calls may need to query the canvas for information (such as actual Swing component size, etc). If this happens you will get a thread deadlock. You should only make invokeAndWait calls from âthird partyâ threads.</p>
+<h1 id="SVGDOM">Using the SVG DOM</h1>
+<p>Batik provides a fairly complete implementation of the SVG DOM. The SVG DOM provides all the functionality most applications require. In particular, the DOM implements DOM Events, including mutation and UI Events. As an example, DOM events allow you to get notified when the cursor moves over elements of interest:
+// Element of Interest.
+Element theElem = ...;
+((EventTarget) theElem).addEventListener("mouseover", mouseOverListener, true);
+where <code>mouseOverListener</code> implements the <a href="http://java.sun.com/j2se/1.5.0/docs/api/org/w3c/dom/events/EventListener.html">org.w3c.dom.events.EventListener</a> interface. This interface consists of the method:
+void handleEvent(Event evt);
+This is called whenever the event occurs with the element it is registered on. It is worth reviewing the DOM Events specification as there are many useful features to this interface that are not immediately obvious.</p>
+<p>It is also worth looking at the DOM interfaces defined by the SVG specification as they provide a large number of useful methods, in particular those of <a href="../../javadoc/org/w3c/dom/svg/SVGLocatable.html">SVGLocatable</a> :
+// Returns Bounding box of SVG Element.
+public SVGRect getBBox ( );
+// Returns the transformation matrix to the screen.
+public SVGMatrix getScreenCTM ( );
+// Returns the transformation matrix to the given element.
+public SVGMatrix getTransformToElement ( SVGElement element )
+ throws SVGException;
+In particular, <code>getScreenCTM</code> is very useful for taking the <code>clientX</code> and <code>clientY</code> attributes of the DOM <a href="http://java.sun.com/j2se/1.5.0/docs/api/org/w3c/dom/events/UIEvent.html">UIEvent</a> and mapping them to the coordinate system of an element in the SVG document:
+SVGMatrix mat = elem.getScreenCTM();
+SVGMatrix imat = mat.inverse();
+SVGPoint cPt = document.getRootElement().createSVGPoint();
+cPt.setX(uiEvt.getClientX());
+cPt.setY(uiEvt.getClientY());
+cPt = cPt.matrixTransform(imat);</p>
+<h1 id="javaInDocument">Referencing Java code from a document</h1>
+<p>Batik implements the Java bindings for SVG, and thus allows Java code to be referenced from <code>script</code> elements. This feature is available to any application of Batik that uses the bridge module (for example the Swing component and the transcoders).</p>
+<p>In order to use this extension, the <code>type</code> attribute of a <code>script</code> element must be set to <code>application/java-archive</code> . In addition, the <code>xlink:href</code> attribute must be the URI of a jar file that contains the code to run.</p>
+<p>The manifest of this jar file must contains an entry of the form:
+SVG-Handler-Class: classname
+where <em>classname</em> must be the name of a class that implements the <a href="../../javadoc/org/w3c/dom/svg/EventListenerInitializer.html">org.w3c.dom.svg.EventListenerInitializer</a> interface. Just before the document <code>SVGLoad</code> event is fired, an instance of this class is created, and this instance has its <code>initializeEventListeners</code> method invoked. Note that there is no way to specify Java handlers in event attributes on SVG elements, so having the <code>initializeEventListeners</code> call <code>addEventListener</code> on a node is the only way to attach a Java listener from within the document.</p>
+<p>The class specified by <code>SVG-Handler-Class</code> can be contained directly in the jar file, but it is also possible for it to be contained in a jar file added to the classpath using the <code>Class-Path</code> entry of the manifest.</p></div></div>
+ <div class="clear"></div>
+
+ <div id="footer">
+ <a alt="Apache Software Foundation" href="http://www.apache.org">
+ <img id="asf-logo" alt="Apache Software Foundation" src="/images/feather-small.gif"/ width="100">
+ </a>
+ <div class="copyright">
+ <p>
+ Copyright © 2011 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, Apache XML Graphics, the Apache feather logo, and the Apache XML Graphics logos are
+ trademarks of <a href="http://www.apache.org">The Apache Software Foundation</a>. All other
+ marks mentioned may be trademarks or registered trademarks of their respective owners.
+ <br />
+ </p>
+ </div>
+ </div>
+ </body>
+</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: commits-help@xmlgraphics.apache.org