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

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