JSVGCanvas Tutorial


	Introduction

The goal of the JSVGCanvas is to provide a Swing component that can used to display SVG documents. With the JSVGCanvas, 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.

Creating a JSVGCanvas

Event Handling

Interactor


	Creating a JSVGCanvas

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 the swing tutorial. The JSVGCanvas is also a JavaBean so it can be used in visual application builders.

Note: If you try this example, do not forget to set your classpath so that it contains the Batik classes and resources, and Crimson (lib/crimson-parser.jar).


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

The SVG Application


	Event Handling

Each time you set a URI or an SVG DOM tree to the JSVGCanvas (using the setURI or setSVGDocument 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:

SVGDocumentLoaderListener -
This listener provides a set of methods that can be used to track SVGDocumentLoaderEvent events. It describes the loading phase: contructing an SVG DOM tree using an SVG file.

GVTTreeBuilderListener -
This listener provides a set of methods that can be used to track GVTTreeBuilderEvent 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.

SVGLoadEventDispatcherListener -
This listener provides a set of methods that can be used to track SVGLoadEventDispatcherEvent events. It describes the DOM SVGLoad event dispatch phase.
This event is triggered only in dynamic documents.

GVTTreeRendererListener -
This listener provides a set of methods that can be used to track GVTTreeRendererEvent events. It describes the rendering phase: constructing an image using a GVT tree.
In dynamic documents this event is fired only once for the initial rendering.

UpdateManagerListener -
This listener provides a set of methods that can be used to track UpdateManagerEvent 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.
Only dynamic documents trigger this event.

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.

For static documents, you can assume that the JSVGCanvas has completed its job (parsing, building and rendering) when the gvtRenderingCompleted method call is called, following a setURI or a setSVGDocument method call.
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 updateManagerStopped method.


	Interactor

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 Interactor interface. Then, you can register this new interactor to the component using the getInteractors().add method.