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

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

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

 <!-- ========================================================================= -->
 <!-- author 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>
 </s1>

 <!-- ##################################################################### -->
 <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>

 <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>

 <!-- ##################################################################### -->
 <s1 title="Event Handling">

 <p>

 Each time you set a URI or a 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, and finally rendered. The
 proper way to be notified of those different phases is to implement a listener
 and attach it to the component. There are three 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>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 /><br />
 </dd>

 </dl>

 <p>

 Those listeners give a complete description of the different steps of those
 three phases (including error states). Adapter classes are available to ease the
 creation of new listener implementation.

 </p>

 <p>

 You can assume that the JSVGCanvas has completed its job (parsing, building and
 rendering) when the <code>gvtRenderingCompleted</code> method call is called and
 following a setURI or a setSVGDocument method call.

 </p>

 </s1>

 <!-- ##################################################################### -->
 <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>
	<?xml version="1.0"?>
	<!DOCTYPE document SYSTEM "./dtd/document-v10.dtd">

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

	<!-- ========================================================================= -->
	<!-- author 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>
	</s1>

	<!-- ##################################################################### -->
	<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>

	<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>

	<!-- ##################################################################### -->
	<s1 title="Event Handling">

	<p>

	Each time you set a URI or a 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, and finally rendered. The
	proper way to be notified of those different phases is to implement a listener
	and attach it to the component. There are three 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>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 /><br />
	</dd>

	</dl>

	<p>

	Those listeners give a complete description of the different steps of those
	three phases (including error states). Adapter classes are available to ease the
	creation of new listener implementation.

	</p>

	<p>

	You can assume that the JSVGCanvas has completed its job (parsing, building and
	rendering) when the <code>gvtRenderingCompleted</code> method call is called and
	following a setURI or a setSVGDocument method call.

	</p>

	</s1>

	<!-- ##################################################################### -->
	<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>