You are viewing a plain text version of this content. The canonical link for it is here.
Posted to batik-commits@xmlgraphics.apache.org by ca...@apache.org on 2006/11/20 06:25:32 UTC
svn commit: r477052 [6/8] - in /xmlgraphics/batik/trunk: ./
documentation-sources/ documentation-sources/classes/
documentation-sources/conf/ documentation-sources/content/
documentation-sources/content/demo/ documentation-sources/content/xdocs/
docume...
Added: xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/dom-api.xml
URL: http://svn.apache.org/viewvc/xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/dom-api.xml?view=auto&rev=477052
==============================================================================
--- xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/dom-api.xml (added)
+++ xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/dom-api.xml Sun Nov 19 21:25:24 2006
@@ -0,0 +1,243 @@
+<?xml version="1.0"?>
+
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+
+<!-- ========================================================================= -->
+<!-- author tkormann@apache.org -->
+<!-- version $Id: domTutorial.xml 201374 2004-08-18 07:17:26Z vhardy $ -->
+<!-- ========================================================================= -->
+
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>SVG DOM API</title>
+ </header>
+
+ <body>
+ <p>
+ The <a href="http://www.w3.org/dom/">Document Object Model</a> (DOM)
+ is an API for XML documents. It defines the logical structure of documents and
+ the way a document is accessed and manipulated. This page shows how to create
+ an SVG document using the DOM API.
+ </p>
+
+ <section id="gettingStarted">
+ <title>Getting started</title>
+ <p>
+ The DOM API defines an interface called
+ <a class="class" href="http://java.sun.com/j2se/1.5.0/docs/api/org/w3c/dom/DOMImplementation.html">DOMImplementation</a>,
+ which represents the boostrap of any DOM implementation. The role of
+ this class is to bootstrap a particular implementation of the DOM by
+ providing a method to create a
+ <a class="class" href="http://java.sun.com/j2se/1.5.0/docs/api/org/w3c/dom/Document.html">Document</a>.
+ Then, the concrete <code>Document</code> represents an XML document and
+ also acts like a factory for the various DOM objects such as
+ <a class="class" href="http://java.sun.com/j2se/1.5.0/docs/api/org/w3c/dom/Element.html">Element</a>,
+ <a class="class" href="http://java.sun.com/j2se/1.5.0/docs/api/org/w3c/dom/Attr.html">Attr</a>
+ and
+ <a class="class" href="http://java.sun.com/j2se/1.5.0/docs/api/org/w3c/dom/Text.html">Text</a>.
+ </p>
+
+ <p>
+ How to get an instance of the <code>DOMImplementation</code> interface depends
+ on the DOM implementation you are using. In Batik, the DOM implementation is
+ located in the package <code>org.apache.batik.dom.svg</code> and the class is
+ named
+ <a class="class" href="http://xmlgraphics.apache.org/batik/javadoc/org/apache/batik/dom/svg/SVGDOMImplementation.html">SVGDOMImplementation</a>.
+ The following example shows how to get a concrete
+ <code>DOMImplementation</code> object.
+ </p>
+
+ <source>import org.w3c.dom.DOMImplementation;
+import org.apache.batik.dom.svg.SVGDOMImplementation;
+
+DOMImplementation impl = SVGDOMImplementation.getDOMImplementation();</source>
+
+ <p>
+ Once you have an instance of a <code>DOMImplementation</code>, you are not
+ relying on Batik-specific code any more and ready to use the DOM API.
+ </p>
+
+ </section>
+
+ <section id="creating">
+ <title>Creating a Document</title>
+
+ <p>
+ Using the <code>DOMImplementation</code>, you are now able to create a
+ <code>Document</code>. The following example illustrates how to create an SVG
+ document. Note that the Batikâs DOM implementation can be
+ used to represent either an SVG document fragment or any kind of XML
+ document. Note that by choosing the namespace URI and the local name of
+ the root element of SVG, we are creating an SVG document.
+ </p>
+
+ <source>import org.apache.batik.dom.svg.SVGDOMImplementation;
+import org.w3c.dom.Document;
+
+// We are using a constant available on the SVGDOMImplementation,
+// but we could have used "http://www.w3.org/2000/svg".
+String svgNS = SVGDOMImplementation.SVG_NAMESPACE_URI;
+DOMImplementation impl = SVGDOMImplementation.getDOMImplementation();
+<strong>Document doc = impl.createDocument(svgNS, "svg", null);</strong>
+ </source>
+
+ <p>
+ As we have created an SVG <code>Document</code>, we can cast this document to an
+ <a class="class" href="../javadoc/org/w3c/dom/svg/SVGDocument.html">SVGDocument</a>
+ (defined in the <code>org.w3c.dom.svg</code> package) if needed.
+ </p>
+
+ </section>
+
+ <section id="buildsvgdoc">
+ <title>Building an SVG Document</title>
+
+ <p>
+ Finally, using the <code>Document</code> object, we are now able to
+ construct SVG content. Note that the document created before supports both
+ generic XML and SVG. Though the DOM implementation of Batik is an SVG DOM
+ implementation, the SVG-specific methods that rely on the document having
+ been rendered (particularly geometry related methods, such as
+ <a href="../javadoc/org/w3c/dom/svg/SVGLocatable.html#getBBox()">SVGLocatable.getBBox</a>)
+ cannot be used at this point.
+ </p>
+ <p>
+ The document can be built using DOM Level 2 Core methods. The following
+ example shows how to create a red rectangle located at (10, 20), with a
+ size of (100, 50) placed in a (400, 450) SVG canvas:
+ </p>
+
+ <source>
+import org.apache.batik.dom.svg.SVGDOMImplementation;
+import org.w3c.dom.Document;
+import org.w3c.dom.Element;
+
+DOMImplementation impl = SVGDOMImplementation.getDOMImplementation();
+String svgNS = SVGDOMImplementation.SVG_NAMESPACE_URI;
+Document doc = impl.createDocument(svgNS, "svg", null);
+
+// Get the root element (the 'svg' element).
+<strong>Element svgRoot = doc.getDocumentElement();</strong>
+
+// Set the width and height attributes on the root 'svg' element.
+<strong>svgRoot.setAttributeNS(null, "width", "400");</strong>
+svgRoot.setAttributeNS(null, "height", "450");
+
+// Create the rectangle.
+<strong>Element rectangle = doc.createElementNS(svgNS, "rect");</strong>
+rectangle.setAttributeNS(null, "x", "10");
+rectangle.setAttributeNS(null, "y", "20");
+rectangle.setAttributeNS(null, "width", "100");
+rectangle.setAttributeNS(null, "height", "50");
+rectangle.setAttributeNS(null, "fill", "red");
+
+// Attach the rectangle to the root 'svg' element.
+<strong>svgRoot.appendChild(rectangle);</strong>
+ </source>
+
+ <p>
+ The example given constructs a document equivalent to parsing the
+ following SVG file:
+ </p>
+
+ <source><![CDATA[<svg xmlns="http://www.w3.org/2000/svg" width="400" height="450">
+ <rect x="10" y="20" width="100" height="50" fill="red"/>
+</svg>]]></source>
+
+ </section>
+
+ <section id="createdocfromsvgfile">
+ <title>Creating a Document from an SVG file</title>
+
+ <p>
+ With Batik, you can also create an SVG DOM tree from a URI, an
+ <a class="class" href="http://java.sun.com/j2se/1.5.0/docs/api/java/io/InputStream.html">InputStream</a>,
+ or a
+ <a class="class" href="http://java.sun.com/j2se/1.5.0/docs/api/java/io/Reader.html">Reader</a>,
+ using the
+ <a class="class" href="../javadoc/org/apache/batik/dom/util/SAXDocumentFactory.html">SAXSVGDocumentFactory</a>.
+ The following example illustrates how to create an SVG document from a
+ URI using the <code>SAXSVGDocumentFactory</code> class.
+ </p>
+
+ <source>import java.io.IOException;
+
+import org.apache.batik.dom.svg.SAXSVGDocumentFactory;
+import org.apache.batik.util.XMLResourceDescriptor;
+
+import org.w3c.dom.Document;
+
+try {
+ String parser = XMLResourceDescriptor.getXMLParserClassName();
+ SAXSVGDocumentFactory f = new SAXSVGDocumentFactory(parser);
+ String uri = "http://www.example.org/diagram.svg";
+ <strong>Document doc = f.createDocument(uri);</strong>
+} catch (IOException ex) {
+ // ...
+}
+ </source>
+
+ <p>
+ As we have created an SVG <code>Document</code>, we can cast this document to an
+ <code>SVGDocument</code> (defined in the <code>org.w3c.dom.svg</code> package)
+ if needed.
+ </p>
+ </section>
+
+ <section id="rendering">
+ <title>Rendering an SVG Document</title>
+
+ <p>
+ Batik provides several ways to use an SVG DOM tree. Two modules can be
+ immediately used to render your SVG document.
+ </p>
+ <dl>
+ <dt>JSVGCanvas</dt>
+ <dd>
+ <p>
+ The
+ <a class="class" href="../javadoc/org/apache/batik/swing/JSVGCanvas.html">JSVGCanvas</a>
+ is a Swing component that can display SVG document. A SVG document can
+ be specified using a URI or an SVG DOM tree (using the
+ <a class="class" href="../javadoc/org/apache/batik/swing/JSVGCanvas.html#setSVGDocument(Document)">setSVGDocument</a>
+ method). For futher information about the <code>JSVGCanvas</code>,
+ see the <a href="site:swing">Swing components module
+ documentation</a>.
+ </p>
+ </dd>
+ <dt>ImageTranscoder</dt>
+ <dd>
+ The
+ <a class="class" href="../javadoc/org/apache/batik/transcoder/image/ImageTranscoder.html">ImageTranscoder</a>
+ is a transcoder that can take a URI, an <code>InputStream</code> or an
+ SVG DOM tree and produces a raster image (such JPEG, PNG or TIFF).
+ By creating a
+ <a class="class" href="../javadoc/org/apache/batik/transcoder/TranscoderInput.html">TranscoderInput</a>
+ object with the SVG DOM tree, you will be able to transform your SVG
+ content to a raster image. For futher information, see the
+ <a href="site:transcoder">transcoder module documentation</a>.
+ </dd>
+ </dl>
+
+ </section>
+
+</body>
+</document>
Propchange: xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/dom-api.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/extending.xml
URL: http://svn.apache.org/viewvc/xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/extending.xml?view=auto&rev=477052
==============================================================================
--- xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/extending.xml (added)
+++ xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/extending.xml Sun Nov 19 21:25:24 2006
@@ -0,0 +1,745 @@
+<?xml version="1.0"?>
+
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+
+<!-- ====================================================================== -->
+<!-- author Thomas.DeWeese@kodak.com -->
+<!-- version $Id: extendingBatik.xml 201374 2004-08-18 07:17:26Z vhardy $ -->
+<!-- ====================================================================== -->
+
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Extending Batik</title>
+ </header>
+
+ <body>
+ <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.3/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!
+ </p>
+ <note>
+ If you feel that the Batik team has overlooked an
+ important area for extension please let your feelings be
+ known on the mailing lists.
+ </note>
+
+ <section id="customXMLTags">
+ <title>Custom XML elements</title>
+ <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>
+ <p>
+ 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.
+ </p>
+ <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>
+ </dd>
+
+ <dt>Adding functionality to your custom element DOM objects</dt>
+ <dd>
+ <p>
+ 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>.
+ </p>
+ <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>
+ </dd>
+
+ <dt>Having your custom elements be rendered</dt>
+ <dd>
+ <p>
+ 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.
+ </p>
+ <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>
+ </dd>
+ </dl>
+
+ <section id="domExtension">
+ <title>Writing a Batik DOM extension</title>
+ <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 class="class" 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 class="class" 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 class="class" 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><code>org.apache.batik.extension.svg.BatikStarElement</code></li>
+ <li><code>org.apache.batik.extension.svg.BatikRegularPolygonElement</code></li>
+ <li><code>org.apache.batik.extension.svg.BatikHistogramNormalizationElement</code></li>
+ <li><code>org.apache.batik.extension.svg.SolidColorElement</code></li>
+ <li><code>org.apache.batik.extension.svg.ColorSwitchElement</code></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>
+ </section>
+
+ <section id="bridgeExtension">
+ <title>Writing a Batik bridge extension</title>
+ <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 class="class" 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 class="class" 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 class="class" 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 class="class" href="../javadoc/org/apache/batik/bridge/SVGBridgeExtension.html">org.apache.batik.bridge.SVGBridgeExtension</a>
+ class), as are the example extensions
+ (<a class="class" 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>
+ <p>
+ 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).
+ </p>
+ <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>
+ </dd>
+ <dt>FilterBridge</dt>
+ <dd>
+ <p>
+ 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.
+ </p>
+ <p>
+ <em>Example SVG element:</em> <code>filter</code>
+ </p>
+ </dd>
+ <dt><a href="#filterPrimitiveBridge">FilterPrimitiveBridge</a></dt>
+ <dd>
+ <p>
+ This constructs an element in the filter chain
+ applied to an SVG graphics node.
+ </p>
+ <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>
+ </dd>
+ <dt><a href="#paintBridge">PaintBridge</a></dt>
+ <dd>
+ <p>
+ This constructs a Java
+ <a class="class" 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.
+ </p>
+ <p>
+ <em>Example SVG elements:</em>
+ <code>gradient</code>, <code>pattern</code>.
+ </p>
+ <p>
+ <em>Example extension bridge:</em>
+ <code>ColorSwitchBridge</code>.
+ </p>
+ </dd>
+ <dt>ClipBridge</dt>
+ <dd>
+ <p>
+ This constructs a
+ <a class="class" 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.
+ </p>
+ <p>
+ <em>Example SVG element:</em> <code>clipPath</code>.
+ </p>
+ </dd>
+ <dt>MarkerBridge</dt>
+ <dd>
+ <p>
+ This constructs a
+ <a class="class" href="../javadoc/org/apache/batik/gvt/Marker.html">Marker</a>
+ for annotating the path of a graphics node.
+ </p>
+ <p>
+ <em>Example SVG element:</em> <code>marker</code>.
+ </p>
+ </dd>
+ <dt>MaskBridge</dt>
+ <dd>
+ <p>
+ 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.
+ </p>
+ <p>
+ <em>Example SVG element:</em> <code>mask</code>.
+ </p>
+ </dd>
+ </dl>
+
+ <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>
+
+ <section id="graphicsNodeBridge">
+ <title>GraphicsNodeBridge</title>
+ <p>
+ The graphics node bridge is oriented around
+ constructing a new
+ <a class="class" 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 class="class" href="../javadoc/org/apache/batik/bridge/GraphicsNodeBridge.html">GraphicsNodeBridge</a>
+ interface directly, or you can subclass the
+ <a class="class" 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 class="class" 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>
+ <p>
+ 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.
+ </p>
+ </dd>
+ <dt>SVGDecoratedShapeElementBridge</dt>
+ <dd>
+ <p>
+ 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.
+ </p>
+ </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 class="class" 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>
+ </section>
+
+ <section id="filterPrimitiveBridge">
+ <title>FilterPrimitiveBridge</title>
+ <p>
+ The
+ <a class="class" 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 class="class" 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 class="class" 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 class="class" href="../javadoc/org/apache/batik/ext/awt/image/renderable/Filter.html">org.apache.batik.ext.awt.image.renderable.Filter</a>
+ and
+ <a class="class" 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 pronounced 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 class="class" 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 class="class" href="../javadoc/org/apache/batik/ext/awt/image/renderable/AbstractRable.html">org.apache.batik.ext.awt.image.renderable.AbstractRable</a>,
+ <a class="class" href="../javadoc/org/apache/batik/ext/awt/image/rendered/AbstractRed.html">org.apache.batik.ext.awt.image.rendered.AbstractRed</a>,
+ and
+ <a class="class" href="../javadoc/org/apache/batik/ext/awt/image/rendered/AbstractTiledRed.html">org.apache.batik.ext.awt.image.rendered.AbstractTiledRed</a>,
+ <a class="class" 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>
+ </section>
+
+ <section id="paintBridge">
+ <title>PaintBridge</title>
+ <p>
+ The
+ <a class="class" 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 class="class" 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>
+ </section>
+ </section>
+ </section>
+
+ <section id="imageTagFormats">
+ <title>New image file formats</title>
+ <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 class="class" 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 class="class" 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 class="class" href="../javadoc/org/apache/batik/ext/awt/image/codec/jpeg/JPEGRegistryEntry.html">JPEGRegistryEntry</a>
+ and
+ <a class="class" href="../javadoc/org/apache/batik/ext/awt/image/codec/png/PNGRegistryEntry.html">PNGRegistryEntry</a>
+ classes should be used as good references for extensions.
+ </p>
+ <section>
+ <title>RegistryEntry</title>
+ <p>
+ There are currently two flavors of <code>RegistryEntry</code>:
+ </p>
+ <dl>
+ <dt>URLRegistryEntry</dt>
+ <dd>
+ <p>
+ A
+ <a class="class" href="../javadoc/org/apache/batik/ext/awt/image/spi/URLRegistryEntry.html">URLRegistryEntry</a>
+ takes a
+ <a class="class" 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.
+ </p>
+ </dd>
+ <dt>StreamRegistryEntry</dt>
+ <dd>
+ <p>
+ A
+ <a class="class" href="../javadoc/org/apache/batik/ext/awt/image/spi/StreamRegistryEntry.html">StreamRegistryEntry</a>
+ works with a markable
+ <a class="class" 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.
+ </p>
+ </dd>
+ </dl>
+ </section>
+
+ <section>
+ <title>Helper classes</title>
+ <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>
+ <p>
+ <a class="class" 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.
+ </p>
+ </dd>
+ <dt>RedRable</dt>
+ <dd>
+ <p>
+ <a class="class" 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.
+ </p>
+ </dd>
+ <dt>DeferRable</dt>
+ <dd>
+ <p>
+ <a class="class" 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.
+ </p>
+ </dd>
+ <dt>AbstractRable</dt>
+ <dd>
+ <p>
+ <a class="class" 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.
+ </p>
+ </dd>
+ <dt>AbstractRed</dt>
+ <dd>
+ <p>
+ <a class="class" 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 class="class" href="../javadoc/org/apache/batik/ext/awt/image/rendered/CacheableRed.html">CacheableRed</a>
+ interface (Batik's subclass of <code>RenderedImage</code>).
+ </p>
+ </dd>
+ </dl>
+ </section>
+ </section>
+
+ <section id="urlProtocols">
+ <title>New URL protocols</title>
+ <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 class="class" href="../javadoc/org/apache/batik/util/ParsedURL.html">ParsedURL</a>
+ instead of the JDKâs
+ <a class="class" 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 class="class" 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 class="class" 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>
+ </section>
+
+ <section id="interpreters">
+ <title>Additional script interpreters</title>
+
+ <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 class="class" 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 class="class" 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="site:install">installation notes</a> on what jar files are
+ needed for TCL and Python support.
+ </p>
+ </section>
+ </body>
+</document>
Propchange: xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/extending.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/glossary.xml
URL: http://svn.apache.org/viewvc/xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/glossary.xml?view=auto&rev=477052
==============================================================================
--- xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/glossary.xml (added)
+++ xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/glossary.xml Sun Nov 19 21:25:24 2006
@@ -0,0 +1,82 @@
+<?xml version="1.0"?>
+
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+
+<!-- ========================================================================= -->
+<!-- author vincent.hardy@eng.sun.com -->
+<!-- version $Id: glossary.xml 201374 2004-08-18 07:17:26Z vhardy $ -->
+<!-- ========================================================================= -->
+
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Batik Glossary</title>
+ </header>
+
+ <body>
+ <section id="Bridge">
+ <title>Bridge</title>
+ <p>
+ A bridge is a class that handles an element in an SVG document, either
+ by constructing a corresponding node in the GVT tree, or by informing
+ the user agent that it has encountered the element.
+ </p>
+ </section>
+
+ <section id="GVT">
+ <title>GVT (Graphic Vector Toolkit)</title>
+ <p>
+ GVT (Graphic Vector Toolkit) is an object oriented framework that
+ describes complex 2D graphics in terms of a tree of Java objects. GVT
+ is used in Batik to represent how SVG images are to be rendered.
+ </p>
+ </section>
+
+ <section id="SVGDOM">
+ <title>SVG DOM</title>
+ <p>
+ The SVG DOM (Document Object Model) defines the API that programming
+ languages use to interact with SVG documents. There are different âbindingsâ
+ of the DOM API for different languages. For example, there is an ECMAScript
+ binding that allows SVG scripts to access or modify SVG documents, for example
+ in reaction to events. There is also a Java binding which allows Java
+ programs to dynamically interact with SVG documents. The Java binding
+ and the ECMAScript binding are both available in Batik.
+ </p>
+ </section>
+
+ <section id="SVGGenerator">
+ <title>SVG Generator</title>
+ <p>
+ The SVG Generator is a module of Batik that allows Java applications
+ to create SVG content without needing specific knowledge of SVG. Applications
+ doing graphics in Java use an API, embodied by the
+ <code>Graphics2D</code> class, to do all their rendering operations.
+ They use the same code, but different implementations of that API, to
+ render to various outputs such as a screen or a printer. The SVG
+ Generator is another implementation of that API that, instead of
+ drawing to a screen or a printer, generates SVG content. Because it
+ implements the same API as for printing or drawing to the screen, the
+ same code that does screen rendering and printing can be used with the
+ generator to generate SVG content.
+ </p>
+ </section>
+ </body>
+</document>
Propchange: xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/glossary.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/index.xml
URL: http://svn.apache.org/viewvc/xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/index.xml?view=auto&rev=477052
==============================================================================
--- xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/index.xml (added)
+++ xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/index.xml Sun Nov 19 21:25:24 2006
@@ -0,0 +1,134 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+
+<!-- ========================================================================= -->
+<!-- author cam@mcc.id.au -->
+<!-- version $Id$ -->
+<!-- ========================================================================= -->
+
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Using Batik</title>
+ </header>
+
+ <body>
+ <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>
+ <p>
+ The <a href="site:architecture">architecture</a> page gives an
+ overview of how the various modules in Batik fit together.
+ </p>
+ </dd>
+ <dt>Javadoc APIs</dt>
+ <dd>
+ <p>
+ The <a href="site:javadoc">Javadoc APIs</a> document all
+ of the classes packaged with Batik.
+ </p>
+ </dd>
+ <!--dt>CSS engine</dt>
+ <dd>
+ <p>
+ The <a href="site:css">CSS engine</a> page describes how to use
+ the CSS 2 engine that comes with Batik.
+ </p>
+ </dd-->
+ <dt>DOM API</dt>
+ <dd>
+ <p>
+ The <a href="site:dom-api">DOM API</a> page explains how to use the
+ DOM interfaces to create and render SVG documents.
+ </p>
+ </dd>
+ <dt>Parsers</dt>
+ <dd>
+ <p>
+ The <a href="site:parsers">Parsers</a> page describes the parser
+ classes that can be used for parsing the microsyntaxes of SVG
+ (such as path data and transform lists).
+ </p>
+ </dd>
+ <dt>Scripting</dt>
+ <dd>
+ <p>
+ The scripting pages (<a href="site:ecmascript">Scriping with
+ ECMAScript</a>, <a href="site:java">Scripting with
+ Java</a> and <a href="site:security">Security</a>)
+ document how to programmatically manipulate SVG documents, and how
+ script interpreters can be used and extended in Batik.
+ </p>
+ </dd>
+ <dt>SVG generator</dt>
+ <dd>
+ <p>
+ The <a href="site:generator">SVG Generator</a> page documents the
+ <code>SVGGraphics2D</code> class, which can be used to construct
+ SVG documents from Java2D drawing commands.
+ </p>
+ </dd>
+ <dt>Swing components</dt>
+ <dd>
+ <p>
+ The <a href="site:swing">Swing components</a> page describes the
+ SVG canvas component, the primary method for displaying SVG content
+ in Swing applications.
+ </p>
+ </dd>
+ <dt>Transcoder API</dt>
+ <dd>
+ <p>
+ The <a href="site:transcoder">Transcoder API</a> page explains how
+ to use the transcoder classes to convert SVG content to other formats
+ (raster or vector).
+ </p>
+ </dd>
+ <dt>Extending Batik</dt>
+ <dd>
+ <p>
+ The <a href="site:extending">Extending Batik</a> page lists the parts
+ of the Batik API that are extensible and explains how to add
+ functionality to the existing modules.
+ </p>
+ </dd>
+ <!--dt>Batik in an applet</dt>
+ <dd>
+ <p>
+ The <a href="site:applet">Batik in an applet</a> page explains how
+ Batik can be used in a Java applet in a web page.
+ </p>
+ </dd>
+ <dt>Glossary</dt>
+ <dd>
+ <p>
+ Finally, the <a href="site:glossary">Glossary page</a> explains common Batik
+ terminology used in this section.
+ </p>
+ </dd-->
+ </dl>
+ </body>
+</document>
Propchange: xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/index.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/parsers.xml
URL: http://svn.apache.org/viewvc/xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/parsers.xml?view=auto&rev=477052
==============================================================================
--- xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/parsers.xml (added)
+++ xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/parsers.xml Sun Nov 19 21:25:24 2006
@@ -0,0 +1,262 @@
+<?xml version="1.0"?>
+
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+
+<!-- ========================================================================= -->
+<!-- author cam@mcc.id.au -->
+<!-- version $Id$ -->
+<!-- ========================================================================= -->
+
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Parser module</title>
+ </header>
+
+ <body>
+ <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>
+
+ <section id="parsersHandlersAndProducers">
+ <title>Parsers, handlers and producers</title>
+
+ <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 class="class" href="../javadoc/org/apache/batik/parser/Parser.html">Parser</a>
+ interface, which has methods to parse values from a
+ <a class="class" href="http://java.sun.com/j2se/1.5.0/docs/api/java/io/Reader.html">Reader</a>
+ or a
+ <a class="class" 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 class="class" 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>
+ <p>
+ Implemented by
+ <a class="class" href="../javadoc/org/apache/batik/parser/AngleParser.html">AngleParser</a>,
+ handled with
+ <a class="class" 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.
+ </p>
+ </dd>
+ <dt>Clock values</dt>
+ <dd>
+ <p>
+ Implemented by
+ <a class="class" href="../javadoc/org/apache/batik/parser/ClockParser.html">ClockParser</a>,
+ handled with
+ <a class="class" 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>
+ <p>
+ Implemented by
+ <a class="class" href="../javadoc/org/apache/batik/parser/FragmentIdentifierParser.html">FragmentIdentifierParser</a>,
+ handled with
+ <a class="class" href="../javadoc/org/apache/batik/parser/FragmentIdentifierHandler.html">FragmentIdentifierHandler</a>.
+ Tihs 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.
+ </p>
+ </dd>
+ <dt>Lengths</dt>
+ <dd>
+ <p>
+ Implemented by
+ <a class="class" href="../javadoc/org/apache/batik/parser/LengthParser.html">LengthParser</a>,
+ handled with
+ <a class="class" href="../javadoc/org/apache/batik/parser/LengthHandler.html">LengthHandler</a>.
+ Tihs parser is used for parsing SVG length values.
+ </p>
+ </dd>
+ <dt>Length lists</dt>
+ <dd>
+ <p>
+ Implemented by
+ <a class="class" href="../javadoc/org/apache/batik/parser/LengthListParser.html">LengthListParser</a>,
+ handled with
+ <a class="class" href="../javadoc/org/apache/batik/parser/LengthListHandler.html">LengthListHandler</a>.
+ Tihs parser is used for parsing lists of comma or space separated
+ SVG lengths.
+ </p>
+ </dd>
+ <dt>Numbers</dt>
+ <dd>
+ <p>
+ Implemented by
+ <a class="class" href="../javadoc/org/apache/batik/parser/NumberListParser.html">NumberListParser</a>,
+ handled with
+ <a class="class" href="../javadoc/org/apache/batik/parser/NumberListHandler.html">NumberListHandler</a>.
+ Tihs parser is used for parsing SVG number values.
+ </p>
+ </dd>
+ <dt>Number lists</dt>
+ <dd>
+ <p>
+ Implemented by
+ <a class="class" href="../javadoc/org/apache/batik/parser/NumberListParser.html">NumberListParser</a>,
+ handled with
+ <a class="class" href="../javadoc/org/apache/batik/parser/NumberListHandler.html">NumberListHandler</a>.
+ Tihs parser is used for parsing lists of comma or space separated
+ SVG numbers.
+ </p>
+ </dd>
+ <dt>Path data</dt>
+ <dd>
+ <p>
+ Implemented by
+ <a class="class" href="../javadoc/org/apache/batik/parser/PathParser.html">PathParser</a>,
+ handled with
+ <a class="class" 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.
+ </p>
+ </dd>
+ <dt>Points</dt>
+ <dd>
+ <p>
+ Implemented by
+ <a class="class" href="../javadoc/org/apache/batik/parser/PointsParser.html">PointsParser</a>,
+ handled with
+ <a class="class" 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.
+ </p>
+ </dd>
+ <dt>Preserve aspect ratio values</dt>
+ <dd>
+ <p>
+ Implemented by
+ <a class="class" href="../javadoc/org/apache/batik/parser/PreserveAspectRatioParser.html">PreserveAspectRatioParser</a>,
+ handled with
+ <a class="class" 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.
+ </p>
+ </dd>
+ <dt>Transform lists</dt>
+ <dd>
+ <p>
+ Implemented by
+ <a class="class" href="../javadoc/org/apache/batik/parser/TransformListParser.html">TransformListParser</a>,
+ handled with
+ <a class="class" 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.
+ </p>
+ </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>
+ </section>
+
+ <section id="examples">
+ <title>Examples</title>
+
+ <p>
+ The following example code demonstrates how to use the parser classes
+ to parse a list of points:
+ </p>
+
+ <source>import java.awt.geom.Point2D;
+import java.util.LinkedList;
+import java.util.List;
+
+import org.apache.batik.parser.DefaultPointsHandler;
+import org.apache.batik.parser.ParseException;
+import org.apache.batik.parser.PointsHandler;
+import org.apache.batik.parser.PointsParser;
+
+public class PointsParserExample {
+
+ public List extractPoints(String s) throws ParseException {
+ final LinkedList points = new LinkedList();
+ PointsParser pp = new PointsParser();
+ PointsHandler ph = new DefaultPointsHandler() {
+ public void point(float x, float y) throws ParseException {
+ Point2D p = new Point2D.Float(x, y);
+ points.add(p);
+ }
+ };
+ pp.setPointsHandler(ph);
+ pp.parse(s);
+ return points;
+ }
+}</source>
+
+ <p>
+ This example uses the
+ <a class="class" href="../javadoc/org/apache/batik/parser/AWTTransformProducer.html">AWTTransformProducer</a>
+ class to generate an
+ <a class="class" href="http://java.sun.com/j2se/1.5.0/docs/api/java/awt/geom/AffineTransform.html">AffineTransform</a>
+ object from an SVG transform list:
+ </p>
+
+ <source>import java.awt.geom.AffineTransform;
+
+import org.apache.batik.parser.AWTTransformProducer;
+import org.apache.batik.parser.ParseException;
+import org.apache.batik.parser.TransformListParser;
+
+public class TransformParserExample {
+
+ public AffineTransform parseTransformList(String s) throws ParseException {
+ TransformListParser p = new TransformListParser();
+ AWTTransformProducer tp = new AWTTransformProducer();
+ p.setTransformListHandler(tp);
+ p.parse(s);
+ return tp.getAffineTransform();
+ }
+}
+</source>
+ </section>
+ </body>
+</document>
Propchange: xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/parsers.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/scripting/ecmascript.xml
URL: http://svn.apache.org/viewvc/xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/scripting/ecmascript.xml?view=auto&rev=477052
==============================================================================
--- xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/scripting/ecmascript.xml (added)
+++ xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/scripting/ecmascript.xml Sun Nov 19 21:25:24 2006
@@ -0,0 +1,268 @@
+<?xml version="1.0"?>
+
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+
+<!-- ========================================================================= -->
+<!-- author cjolif@ilog.fr -->
+<!-- version $Id: scriptIntro.xml 201374 2004-08-18 07:17:26Z vhardy $ -->
+<!-- ========================================================================= -->
+
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Scripting with ECMAScript</title>
+ </header>
+
+ <body>
+ <p>
+ This page is a brief introduction to scripting SVG documents with
+ ECMAScript, and how Batik's ECMAScript environment can be extended.
+ </p>
+
+ <section id="scriptingBasics">
+ <title>Scripting basics</title>
+ <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.
+ </p>
+ <source><![CDATA[<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
+ <script type="text/ecmascript">
+ // ECMAScript code to be executed
+ </script>
+
+ <!-- Remainder of the document... -->
+</svg>]]></source>
+ <p>
+ 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.
+ </p>
+ <source><![CDATA[<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>]]></source>
+ <p>
+ Note that inside the event attribute script, there is a variable
+ called <code>evt</code> that is a reference to the
+ <a class="class" 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>
+ 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
+ </li>
+ <li>
+ the <a href="http://www.ecma.ch/ecma1/stand/ecma-262.htm">ECMAScript
+ specification</a>, for advanced information on the ECMAScript
+ language.
+ </li>
+ </ul>
+ </section>
+
+ <section id="rhinoFeatures">
+ <title>Using Rhino features</title>
+
+ <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:
+ </p>
+ <source>importPackage(Packages.javax.swing);</source>
+ <p>
+ 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:
+ </p>
+ <source>var frame = new JFrame("My test frame");</source>
+ <p>
+ 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:
+ </p>
+ <source><![CDATA[<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);
+
+ function showFrame() {
+ var frame = new JFrame("My test frame");
+ var label = new JLabel("Hello from Java objects created in ECMAScript!");
+ label.setHorizontalAlignment(SwingConstants.CENTER);
+ frame.getContentPane().add(label);
+ frame.setSize(400, 100);
+ frame.setVisible(true);
+ frame.setDefaultCloseOperation(WindowConstants.DISPOSE_ON_CLOSE);
+ }
+ </script>
+</svg>]]></source>
+
+ <p>
+ 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>
+ </section>
+
+ <section id="customizingRhino">
+ <title>Customizing the Rhino interpreter</title>
+
+ <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.
+ </p>
+ <source>import org.apache.batik.script.rhino.RhinoInterpreter;
+
+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;
+
+public class ExtendedRhinoInterpreter extends RhinoIntepreter {
+
+ public ExtendedRhinoInterpreter() {
+
+ // Array of functions to put in the global object.
+ final String[] names = { "print" }
+ try {
+ // Add the functions to the global object.
+ getGlobalObject().defineFunctionProperties
+ (names, ExtendedRhinoIntepreter.class,
+ ScriptableObject.DONTENUM);
+ } catch (PropertyException e) {
+ throw new Error(e);
+ }
+ }
+
+ public static void print(Context cx, Scriptable thisObj,
+ Object[] args, Function funObj) {
+ for (int i = 0; i < args.length; i++) {
+ if (i > 0) {
+ System.out.print(" ");
+ }
+
+ // Convert the ECMAScript value into a string form.
+ String s = Context.toString(args[i]);
+ System.out.print(s);
+ }
+ System.out.println();
+ }
+}</source>
+ <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.
+ </p>
+ <source>import org.apache.batik.script.Interpreter;
+import org.apache.batik.script.InterpreterFactory;
+
+public class ExtendedRhinoInterpreterFactory implements InterpreterFactory {
+
+ public Interpreter createInterpreter() {
+ return new ExtendedRhinoInterpreter();
+ }
+}</source>
+ <p>
+ Then, you must build an
+ <a class="class" href="../../javadoc/org/apache/batik/script/InterpreterPool.html">IntepreterPool</a>
+ that will use this factory, and then set the pool on the
+ <a class="class" href="../../javadoc/org/apache/batik/bridge/BridgeContext.html">BridgeContext</a>
+ of your application.
+ </p>
+ <source>org.apache.batik.bridge.BridgeContext ctx = ...;
+org.apache.batik.script.InterpreterPool pool =
+ new org.apache.batik.script.InterpreterPool();
+pool.putInterpreterFactory("text/ecmascript",
+ new ExtendedRhinoInterpreterFactory());
+ctx.setIntepreterPool(pool);</source>
+ <p>
+ 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 class="class" 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>
+ </section>
+ </body>
+</document>
Propchange: xmlgraphics/batik/trunk/documentation-sources/content/xdocs/using/scripting/ecmascript.xml
------------------------------------------------------------------------------
svn:eol-style = native