| <?xml version="1.0"?> |
| <!DOCTYPE document SYSTEM "./dtd/document-v10.dtd"> |
| |
| <!-- |
| |
| Copyright 2001-2002,2004 The Apache Software Foundation |
| |
| Licensed 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$ --> |
| <!-- ========================================================================= --> |
| |
| <document> |
| <header> |
| <title>JSVGCanvas Tutorial</title> |
| <subtitle>A brief introduction to the JSVGCanvas</subtitle> |
| <authors> |
| <person name="Thierry Kormann" email="tkormann@apache.org"/> |
| </authors> |
| </header> |
| |
| <body> |
| |
| <!-- ##################################################################### --> |
| <s1 title="Introduction"> |
| <p> |
| |
| The goal of the <code>JSVGCanvas</code> is to provide a Swing component that can |
| used to display SVG documents. With the <code>JSVGCanvas</code>, you can easily |
| display an SVG document (from a URI or a DOM tree) and manipulate it - such as |
| rotating, zooming, panning, selecting text, or activating hyperlinks. First this |
| document explains how to create a JSVGCanvas and integrate it in a Swing |
| application. Then, it descibes some advanced features such as the listener |
| mecanism used to track all events that occured while displaying or manipulating |
| an SVG document. |
| |
| </p> |
| |
| <ul> |
| <li><link href="#creatingJSVGCanvas">Creating a JSVGCanvas</link></li> |
| <li><link href="#eventhandling">Event Handling</link></li> |
| <li><link href="#interactor">Interactor</link></li> |
| </ul> |
| </s1> |
| |
| <!-- ##################################################################### --> |
| <anchor id="creatingJSVGCanvas"/> |
| <s1 title="Creating a JSVGCanvas"> |
| |
| <p> |
| |
| The following example illustrates how to create a JSVGCanvas. A JSVGCanvas is |
| Swing component that follows the Swing design rule. It means that the component |
| is not thread safe and all operations must be done as described in <link |
| href="http://java.sun.com/docs/books/tutorial/uiswing/overview/threads.html">the |
| swing tutorial</link>. The JSVGCanvas is also a <link |
| href="http://java.sun.com/products/javabeans/">JavaBean</link> so it can be used |
| in visual application builders. |
| |
| </p> |
| |
| <p> |
| |
| <em>Note:</em> If you try this example, do not forget to set your |
| classpath so that it contains the Batik classes and resources, as well |
| as Xerces (lib/xerces_2_5_0.jar) and the XML API's jar (lib/xml-apis.jar). |
| </p> |
| |
| <source> |
| |
| import java.awt.*; |
| import java.awt.event.*; |
| import java.io.*; |
| import javax.swing.*; |
| |
| import org.apache.batik.swing.JSVGCanvas; |
| import org.apache.batik.swing.gvt.GVTTreeRendererAdapter; |
| import org.apache.batik.swing.gvt.GVTTreeRendererEvent; |
| import org.apache.batik.swing.svg.SVGDocumentLoaderAdapter; |
| import org.apache.batik.swing.svg.SVGDocumentLoaderEvent; |
| import org.apache.batik.swing.svg.GVTTreeBuilderAdapter; |
| import org.apache.batik.swing.svg.GVTTreeBuilderEvent; |
| |
| public class SVGApplication { |
| |
| public static void main(String[] args) { |
| JFrame f = new JFrame("Batik"); |
| SVGApplication app = new SVGApplication(f); |
| f.getContentPane().add(app.createComponents()); |
| |
| f.addWindowListener(new WindowAdapter() { |
| public void windowClosing(WindowEvent e) { |
| System.exit(0); |
| } |
| }); |
| f.setSize(400, 400); |
| f.setVisible(true); |
| } |
| |
| JFrame frame; |
| JButton button = new JButton("Load..."); |
| JLabel label = new JLabel(); |
| JSVGCanvas svgCanvas = new JSVGCanvas(); |
| |
| public SVGApplication(JFrame f) { |
| frame = f; |
| } |
| |
| public JComponent createComponents() { |
| final JPanel panel = new JPanel(new BorderLayout()); |
| |
| JPanel p = new JPanel(new FlowLayout(FlowLayout.LEFT)); |
| p.add(button); |
| p.add(label); |
| |
| panel.add("North", p); |
| panel.add("Center", svgCanvas); |
| |
| // Set the button action. |
| button.addActionListener(new ActionListener() { |
| public void actionPerformed(ActionEvent ae) { |
| JFileChooser fc = new JFileChooser("."); |
| int choice = fc.showOpenDialog(panel); |
| if (choice == JFileChooser.APPROVE_OPTION) { |
| File f = fc.getSelectedFile(); |
| try { |
| svgCanvas.setURI(f.toURL().toString()); |
| } catch (IOException ex) { |
| ex.printStackTrace(); |
| } |
| } |
| } |
| }); |
| |
| // Set the JSVGCanvas listeners. |
| svgCanvas.addSVGDocumentLoaderListener(new SVGDocumentLoaderAdapter() { |
| public void documentLoadingStarted(SVGDocumentLoaderEvent e) { |
| label.setText("Document Loading..."); |
| } |
| public void documentLoadingCompleted(SVGDocumentLoaderEvent e) { |
| label.setText("Document Loaded."); |
| } |
| }); |
| |
| svgCanvas.addGVTTreeBuilderListener(new GVTTreeBuilderAdapter() { |
| public void gvtBuildStarted(GVTTreeBuilderEvent e) { |
| label.setText("Build Started..."); |
| } |
| public void gvtBuildCompleted(GVTTreeBuilderEvent e) { |
| label.setText("Build Done."); |
| frame.pack(); |
| } |
| }); |
| |
| svgCanvas.addGVTTreeRendererListener(new GVTTreeRendererAdapter() { |
| public void gvtRenderingPrepare(GVTTreeRendererEvent e) { |
| label.setText("Rendering Started..."); |
| } |
| public void gvtRenderingCompleted(GVTTreeRendererEvent e) { |
| label.setText(""); |
| } |
| }); |
| |
| return panel; |
| } |
| } |
| </source> |
| |
| <figure src="images/svgapplication.gif" alt="The SVG Application"/> |
| |
| </s1> |
| |
| <!-- ##################################################################### --> |
| <anchor id="eventhandling"/> |
| <s1 title="Event Handling"> |
| |
| <p> |
| |
| Each time you set a URI or an SVG DOM tree to the JSVGCanvas (using the |
| <code>setURI</code> or <code>setSVGDocument</code> method), the specified |
| document is first parsed (in case of a URI), built, rendered and optionally |
| updated. The proper way to be notified of those different phases is to |
| implement a listener and attach it to the component. There are five types |
| of listener: |
| |
| </p> |
| |
| <dl> |
| <dt>SVGDocumentLoaderListener</dt> |
| <dd> |
| |
| This listener provides a set of methods that can be used to track |
| <code>SVGDocumentLoaderEvent</code> events. It describes the loading phase: |
| contructing an SVG DOM tree using an SVG file. |
| |
| <br /><br /> |
| </dd> |
| |
| <dt>GVTTreeBuilderListener</dt> |
| <dd> |
| |
| This listener provides a set of methods that can be used to track |
| <code>GVTTreeBuilderEvent</code> events. It describes the building phase: |
| contructing a GVT (Graphics Vector Toolkit) tree using an SVG DOM tree. The GVT |
| tree will then be used to render the document. |
| |
| <br /><br /> |
| </dd> |
| |
| <dt>SVGLoadEventDispatcherListener</dt> |
| <dd> |
| |
| This listener provides a set of methods that can be used to track |
| <code>SVGLoadEventDispatcherEvent</code> events. It describes the |
| DOM <code>SVGLoad</code> event dispatch phase.<br/> |
| This event is triggered only in dynamic documents. |
| <br /><br /> |
| </dd> |
| |
| <dt>GVTTreeRendererListener</dt> |
| <dd> |
| |
| This listener provides a set of methods that can be used to track |
| <code>GVTTreeRendererEvent</code> events. It describes the rendering phase: |
| constructing an image using a GVT tree.<br/> |
| In dynamic documents this event is fired only once for the initial rendering. |
| |
| <br /><br /> |
| </dd> |
| |
| <dt>UpdateManagerListener</dt> |
| <dd> |
| |
| This listener provides a set of methods that can be used to track |
| <code>UpdateManagerEvent</code> events. It describes the running phase: |
| the update manager is started and then it can be suspended, resumed or |
| stopped, and graphics updates can be tracked. |
| <br/> |
| Only dynamic documents trigger this event. |
| |
| <br /><br /> |
| </dd> |
| |
| |
| </dl> |
| |
| <p> |
| |
| Those listeners give a complete description of the different steps of those |
| five phases (including error states). Adapter classes are available to ease the |
| creation of new listener implementation. |
| |
| </p> |
| |
| <p> |
| |
| For static documents, you can assume that the JSVGCanvas has completed its job (parsing, building and rendering) |
| when the <code>gvtRenderingCompleted</code> method call is called, following a <code>setURI</code> or a <code>setSVGDocument</code> method call. |
| <br/> |
| In case of dynamic documents, the end of the computations (parsing, building, |
| SVGLoad dispatch, initial rendering and updates) is marked by a call to the |
| <code>updateManagerStopped</code> method. |
| </p> |
| |
| </s1> |
| |
| <!-- ##################################################################### --> |
| <anchor id="interactor"/> |
| <s1 title="Interactor"> |
| |
| <p> |
| |
| The JSVGCanvas provides a set of build-in interactors that let the users |
| manipulate the displayed document - including zoom, pan and rotate. Interactors |
| are dedicated to user inputs. If you want to add new behaviors to the |
| JSVGCanvas, you can implement the <code>Interactor</code> interface. Then, you |
| can register this new interactor to the component using the |
| <code>getInteractors().add</code> method. |
| |
| </p> |
| </s1> |
| |
| |
| </body> |
| </document> |
| |