org.apache.batik.swing.svg
Class JSVGComponent

java.lang.Object
  |
  +--java.awt.Component
        |
        +--java.awt.Container
              |
              +--javax.swing.JComponent
                    |
                    +--org.apache.batik.swing.gvt.JGVTComponent
                          |
                          +--org.apache.batik.swing.svg.JSVGComponent

All Implemented Interfaces:

java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable

Direct Known Subclasses:

JSVGCanvas

public class JSVGComponent

extends JGVTComponent

This class represents a swing component that can display SVG documents. This component also lets you translate, zoom and rotate the document being displayed. This is the fundamental class for rendering SVG documents in a swing application.

Rendering Process

The rendering process can be broken down into five phases. Not all of those steps are required - depending on the method used to specify the SVG document to display, but basically the steps in the rendering process are:

1. Building a DOM tree

   If the loadSVGDocument(String) method is used, the SVG file is parsed and an SVG DOM Tree is built.

2. Building a GVT tree

   Once an SVGDocument is created (using the step 1 or if the setSVGDocument(SVGDocument) method has been used) - a GVT tree is constructed. The GVT tree is the data structure used internally to render an SVG document. see the org.apache.batik.gvt package.

3. Executing the SVGLoad event handlers

   If the document is dynamic, the scripts are initialized and the SVGLoad event is dispatched before the initial rendering.

4. Rendering the GVT tree

   Then the GVT tree is rendered. see the org.apache.batik.gvt.renderer package.

5. Running the document

   If the document is dynamic, the update threads are started.

Those steps are performed in a separate thread. To be notified to what happens and eventually perform some operations - such as resizing the window to the size of the document or get the SVGDocument built via a URI, five different listeners are provided (one per step): SVGDocumentLoaderListener, GVTTreeBuilderListener, SVGLoadEventDispatcherListener, GVTTreeRendererListener, UpdateManagerListener.

Each listener has methods to be notified of the start of a phase, and methods to be notified of the end of a phase. A phase cannot start before the preceding has finished.

The following example shows how you can get the size of an SVG document. Note that due to how SVG is designed (units, percentages...), the size of an SVG document can be known only once the SVGDocument has been analyzed (ie. the GVT tree has been constructed).

 final JSVGComponent svgComp = new JSVGComponent();
 svgComp.loadSVGDocument("foo.svg");
 svgComp.addGVTTreeBuilderListener(new GVTTreeBuilderAdapter() {
     public void gvtBuildCompleted(GVTTreeBuilderEvent evt) {
         Dimension2D size = svgComp.getSVGDocumentSize();
         // ...
     }
 });
 

The second example shows how you can access to the DOM tree when a URI has been used to display an SVG document.

 final JSVGComponent svgComp = new JSVGComponent();
 svgComp.loadSVGDocument("foo.svg");
 svgComp.addSVGDocumentLoaderListener(new SVGDocumentLoaderAdapter() {
     public void documentLoadingCompleted(SVGDocumentLoaderEvent evt) {
         SVGDocument svgDoc = svgComp.getSVGDocument();
         //...
     }
 });
 

Conformed to the single thread rule of swing, the listeners are executed in the swing thread. The sequence of the method calls for a particular listener and the order of the listeners themselves are guaranteed.

User Agent

The JSVGComponent can pick up some informations to a user agent. The SVGUserAgent provides a way to control the resolution used to display an SVG document (controling the pixel to millimeter conversion factor), perform an operation in respond to a click on an hyperlink, control the default language to use, or specify a user stylesheet, or how to display errors when an error occured while building/rendering a document (invalid XML file, missing attributes...).

See Also:

Serialized Form

Inner Class Summary

protected class	JSVGComponent.BridgeUserAgent To hide the user-agent methods.
protected static class	JSVGComponent.BridgeUserAgentWrapper The user-agent wrapper, which call the methods in the event thread.
protected class	JSVGComponent.SVGListener To hide the listener methods.

Inner classes inherited from class org.apache.batik.swing.gvt.JGVTComponent

JGVTComponent.Listener

Inner classes inherited from class javax.swing.JComponent

javax.swing.JComponent.AccessibleJComponent

Inner classes inherited from class java.awt.Container

java.awt.Container.AccessibleAWTContainer

Inner classes inherited from class java.awt.Component

java.awt.Component.AccessibleAWTComponent

Field Summary

static int	ALWAYS_DYNAMIC Means that all document must be considered as dynamic.
static int	ALWAYS_STATIC Means that all document must be considered as static.
static int	AUTODETECT Means that the component must auto detect whether the current document is static or dynamic.
protected BridgeContext	bridgeContext The current bridge context.
protected SVGDocumentLoader	documentLoader The document loader.
protected int	documentState The document state.
protected static java.util.Set	FEATURES
protected java.lang.String	fragmentIdentifier The current document fragment identifier.
protected GVTTreeBuilder	gvtTreeBuilder The GVT tree builder.
protected java.util.List	gvtTreeBuilderListeners The GVT tree builder listeners.
protected boolean	isDynamicDocument Whether the current document has dynamic features.
protected java.util.List	linkActivationListeners The link activation listeners.
protected DocumentLoader	loader The concrete bridge document loader.
protected SVGDocumentLoader	nextDocumentLoader The next document loader to run.
protected GVTTreeBuilder	nextGVTTreeBuilder The next GVT tree builder to run.
protected UpdateManager	nextUpdateManager The next update manager.
protected SVGDocument	svgDocument The current SVG document.
protected java.util.List	svgDocumentLoaderListeners The document loader listeners.
protected SVGLoadEventDispatcher	svgLoadEventDispatcher The SVGLoadEventDispatcher.
protected java.util.List	svgLoadEventDispatcherListeners The SVG onload dispatcher listeners.
protected SVGUserAgent	svgUserAgent The SVG user agent.
protected UpdateManager	updateManager The update manager.
protected java.util.List	updateManagerListeners The update manager listeners.
protected UserAgent	userAgent The user agent.

Fields inherited from class org.apache.batik.swing.gvt.JGVTComponent

disableInteractions, doubleBufferedRendering, eventDispatcher, eventsEnabled, gvtRoot, gvtTreeRenderer, gvtTreeRendererListeners, image, initialTransform, interactor, interactors, listener, needRender, overlays, paintingTransform, progressivePaint, progressivePaintThread, renderer, rendererFactory, renderingTransform, selectableText, suspendInteractions, textSelectionManager

Fields inherited from class javax.swing.JComponent

accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

JSVGComponent()
Creates a new JSVGComponent.

JSVGComponent(SVGUserAgent ua, boolean eventsEnabled, boolean selectableText)
Creates a new JSVGComponent.

Method Summary

void	addGVTTreeBuilderListener(GVTTreeBuilderListener l) Adds a GVTTreeBuilderListener to this component.
void	addLinkActivationListener(LinkActivationListener l) Adds a LinkActivationListener to this component.
void	addSVGDocumentLoaderListener(SVGDocumentLoaderListener l) Adds a SVGDocumentLoaderListener to this component.
void	addSVGLoadEventDispatcherListener(SVGLoadEventDispatcherListener l) Adds a SVGLoadEventDispatcherListener to this component.
void	addUpdateManagerListener(UpdateManagerListener l) Adds a UpdateManagerListener to this component.
protected void	computeRenderingTransform() Computes the transform used for rendering.
protected BridgeContext	createBridgeContext() Creates a new bridge context.
protected ImageRenderer	createImageRenderer() Creates a new renderer.
protected JGVTComponent.Listener	createListener() Creates an instance of Listener.
protected UserAgent	createUserAgent() Creates a UserAgent.
void	flushImageCache() Removes all images from the image cache.
java.lang.String	getFragmentIdentifier() Returns the current's document fragment identifier.
SVGDocument	getSVGDocument() Returns the current SVG document.
java.awt.geom.Dimension2D	getSVGDocumentSize() Returns the size of the SVG document.
UpdateManager	getUpdateManager() Returns the current update manager.
protected void	handleException(java.lang.Exception e) Handles an exception.
boolean	isDynamic() Tells whether the component use dynamic features to process the current document.
void	loadSVGDocument(java.lang.String url) Loads a SVG document from the given URL.
protected java.util.List	mergeRectangles(java.util.List rects, int x1, int y1, int x2, int y2) Merges the given Rectangles.
void	removeGVTTreeBuilderListener(GVTTreeBuilderListener l) Removes a GVTTreeBuilderListener from this component.
void	removeLinkActivationListener(LinkActivationListener l) Removes a LinkActivationListener from this component.
void	removeSVGDocumentLoaderListener(SVGDocumentLoaderListener l) Removes a SVGDocumentLoaderListener from this component.
void	removeSVGLoadEventDispatcherListener(SVGLoadEventDispatcherListener l) Removes a SVGLoadEventDispatcherListener from this component.
void	removeUpdateManagerListener(UpdateManagerListener l) Removes a UpdateManagerListener from this component.
protected void	renderGVTTree() Renders the GVT tree.
void	resumeProcessing() Resumes the processing of the current document.
void	setDocumentState(int state) Sets the document state.
void	setFragmentIdentifier(java.lang.String fi) Sets the current fragment identifier.
void	setSVGDocument(SVGDocument doc) Sets the SVG document to display.
void	showAlert(java.lang.String message) Shows an alert dialog box.
boolean	showConfirm(java.lang.String message) Shows a confirm dialog box.
java.lang.String	showPrompt(java.lang.String message) Shows a prompt dialog box.
java.lang.String	showPrompt(java.lang.String message, java.lang.String defaultValue) Shows a prompt dialog box.
protected void	startSVGLoadEventDispatcher(GraphicsNode root) Starts a SVGLoadEventDispatcher thread.
void	stopProcessing() Stops the processing of the current document.
void	suspendProcessing() Suspend the processing of the current document.
protected void	updateRenderingTransform() Updates the value of the transform used for rendering.

Methods inherited from class org.apache.batik.swing.gvt.JGVTComponent

addGVTTreeRendererListener, deselectAll, flush, flush, getDoubleBufferedRendering, getGraphicsNode, getInitialTransform, getInteractors, getOffScreen, getOverlays, getPaintingTransform, getProgressivePaint, getRenderingTransform, getSelectionOverlayColor, getSelectionOverlayStrokeColor, immediateRepaint, initializeEventHandling, isSelectionOverlayXORMode, paintComponent, releaseRenderingReferences, removeGVTTreeRendererListener, resetRenderingTransform, scheduleGVTRendering, select, setDoubleBufferedRendering, setGraphicsNode, setGraphicsNode, setPaintingTransform, setProgressivePaint, setRenderingTransform, setSelectionOverlayColor, setSelectionOverlayStrokeColor, setSelectionOverlayXORMode

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getAccessibleContext, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getConditionForKeyStroke, getDebugGraphicsOptions, getGraphics, getHeight, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getUIClassID, getVerifyInputWhenFocusTarget, getVisibleRect, getWidth, getX, getY, grabFocus, hasFocus, hide, isDoubleBuffered, isFocusCycleRoot, isFocusTraversable, isLightweightComponent, isManagingFocus, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isPreferredSizeSet, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintImmediately, paintImmediately, paramString, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processFocusEvent, processKeyBinding, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setDebugGraphicsOptions, setDoubleBuffered, setEnabled, setFont, setForeground, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update, updateUI

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getLayout, insets, invalidate, isAncestorOf, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setLayout, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getGraphicsConfiguration, getInputContext, getInputMethodRequests, getLocale, getLocation, getLocationOnScreen, getName, getParent, getPeer, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, imageUpdate, inside, isDisplayable, isEnabled, isLightweight, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

AUTODETECT

public static final int AUTODETECT

Means that the component must auto detect whether the current document is static or dynamic.

ALWAYS_DYNAMIC

public static final int ALWAYS_DYNAMIC

Means that all document must be considered as dynamic.

ALWAYS_STATIC

public static final int ALWAYS_STATIC

Means that all document must be considered as static.

documentLoader

protected SVGDocumentLoader documentLoader

The document loader.

nextDocumentLoader

protected SVGDocumentLoader nextDocumentLoader

The next document loader to run.

loader

protected DocumentLoader loader

The concrete bridge document loader.

gvtTreeBuilder

protected GVTTreeBuilder gvtTreeBuilder

The GVT tree builder.

nextGVTTreeBuilder

protected GVTTreeBuilder nextGVTTreeBuilder

The next GVT tree builder to run.

svgLoadEventDispatcher

protected SVGLoadEventDispatcher svgLoadEventDispatcher

The SVGLoadEventDispatcher.

updateManager

protected UpdateManager updateManager

The update manager.

nextUpdateManager

protected UpdateManager nextUpdateManager

The next update manager.

svgDocument

protected SVGDocument svgDocument

The current SVG document.

svgDocumentLoaderListeners

protected java.util.List svgDocumentLoaderListeners

The document loader listeners.

gvtTreeBuilderListeners

protected java.util.List gvtTreeBuilderListeners

The GVT tree builder listeners.

svgLoadEventDispatcherListeners

protected java.util.List svgLoadEventDispatcherListeners

The SVG onload dispatcher listeners.

linkActivationListeners

protected java.util.List linkActivationListeners

The link activation listeners.

updateManagerListeners

protected java.util.List updateManagerListeners

The update manager listeners.

userAgent

protected UserAgent userAgent

The user agent.

svgUserAgent

protected SVGUserAgent svgUserAgent

The SVG user agent.

bridgeContext

protected BridgeContext bridgeContext

The current bridge context.

fragmentIdentifier

protected java.lang.String fragmentIdentifier

The current document fragment identifier.

isDynamicDocument

protected boolean isDynamicDocument

Whether the current document has dynamic features.

documentState

protected int documentState

The document state.

FEATURES

protected static final java.util.Set FEATURES

Constructor Detail

JSVGComponent

public JSVGComponent()

Creates a new JSVGComponent.

JSVGComponent

public JSVGComponent(SVGUserAgent ua,
                     boolean eventsEnabled,
                     boolean selectableText)

Creates a new JSVGComponent.

Parameters:

ua - a SVGUserAgent instance or null.

eventEnabled - Whether the GVT tree should be reactive to mouse and key events.

selectableText - Whether the text should be selectable.

Method Detail

isDynamic

public boolean isDynamic()

Tells whether the component use dynamic features to process the current document.

setDocumentState

public void setDocumentState(int state)

Sets the document state. The given value must be one of AUTODETECT, ALWAYS_DYNAMIC or ALWAYS_STATIC.

getUpdateManager

public UpdateManager getUpdateManager()

Returns the current update manager.

resumeProcessing

public void resumeProcessing()

Resumes the processing of the current document.

suspendProcessing

public void suspendProcessing()

Suspend the processing of the current document.

stopProcessing

public void stopProcessing()

Stops the processing of the current document.

Overrides:

stopProcessing in class JGVTComponent

loadSVGDocument

public void loadSVGDocument(java.lang.String url)

Loads a SVG document from the given URL. Note: Because the loading is multi-threaded, the current SVG document is not garanteed to be updated after this method returns. The only way to be notified a document has been loaded is to listen to the SVGDocumentLoaderEvents.

setSVGDocument

public void setSVGDocument(SVGDocument doc)

Sets the SVG document to display.

getSVGDocument

public SVGDocument getSVGDocument()

Returns the current SVG document.

getSVGDocumentSize

public java.awt.geom.Dimension2D getSVGDocumentSize()

Returns the size of the SVG document.

getFragmentIdentifier

public java.lang.String getFragmentIdentifier()

Returns the current's document fragment identifier.

setFragmentIdentifier

public void setFragmentIdentifier(java.lang.String fi)

Sets the current fragment identifier.

flushImageCache

public void flushImageCache()

Removes all images from the image cache.

createBridgeContext

protected BridgeContext createBridgeContext()

Creates a new bridge context.

startSVGLoadEventDispatcher

protected void startSVGLoadEventDispatcher(GraphicsNode root)

Starts a SVGLoadEventDispatcher thread.

createImageRenderer

protected ImageRenderer createImageRenderer()

Creates a new renderer.

Overrides:

createImageRenderer in class JGVTComponent

computeRenderingTransform

protected void computeRenderingTransform()

Computes the transform used for rendering.

Overrides:

computeRenderingTransform in class JGVTComponent

updateRenderingTransform

protected void updateRenderingTransform()

Updates the value of the transform used for rendering.

Overrides:

updateRenderingTransform in class JGVTComponent

renderGVTTree

protected void renderGVTTree()

Renders the GVT tree.

Overrides:

renderGVTTree in class JGVTComponent

handleException

protected void handleException(java.lang.Exception e)

Handles an exception.

Overrides:

handleException in class JGVTComponent

addSVGDocumentLoaderListener

public void addSVGDocumentLoaderListener(SVGDocumentLoaderListener l)

Adds a SVGDocumentLoaderListener to this component.

removeSVGDocumentLoaderListener

public void removeSVGDocumentLoaderListener(SVGDocumentLoaderListener l)

Removes a SVGDocumentLoaderListener from this component.

addGVTTreeBuilderListener

public void addGVTTreeBuilderListener(GVTTreeBuilderListener l)

Adds a GVTTreeBuilderListener to this component.

removeGVTTreeBuilderListener

public void removeGVTTreeBuilderListener(GVTTreeBuilderListener l)

Removes a GVTTreeBuilderListener from this component.

addSVGLoadEventDispatcherListener

public void addSVGLoadEventDispatcherListener(SVGLoadEventDispatcherListener l)

Adds a SVGLoadEventDispatcherListener to this component.

removeSVGLoadEventDispatcherListener

public void removeSVGLoadEventDispatcherListener(SVGLoadEventDispatcherListener l)

Removes a SVGLoadEventDispatcherListener from this component.

addLinkActivationListener

public void addLinkActivationListener(LinkActivationListener l)

Adds a LinkActivationListener to this component.

removeLinkActivationListener

public void removeLinkActivationListener(LinkActivationListener l)

Removes a LinkActivationListener from this component.

addUpdateManagerListener

public void addUpdateManagerListener(UpdateManagerListener l)

Adds a UpdateManagerListener to this component.

removeUpdateManagerListener

public void removeUpdateManagerListener(UpdateManagerListener l)

Removes a UpdateManagerListener from this component.

showAlert

public void showAlert(java.lang.String message)

Shows an alert dialog box.

showPrompt

public java.lang.String showPrompt(java.lang.String message)

Shows a prompt dialog box.

showPrompt

public java.lang.String showPrompt(java.lang.String message,
                                   java.lang.String defaultValue)

Shows a prompt dialog box.

showConfirm

public boolean showConfirm(java.lang.String message)

Shows a confirm dialog box.

createListener

protected JGVTComponent.Listener createListener()

Creates an instance of Listener.

Overrides:

createListener in class JGVTComponent

createUserAgent

protected UserAgent createUserAgent()

Creates a UserAgent.

mergeRectangles

protected java.util.List mergeRectangles(java.util.List rects,
                                         int x1,
                                         int y1,
                                         int x2,
                                         int y2)

Merges the given Rectangles.