Class JSVGComponent

All Implemented Interfaces:
ImageObserver, MenuContainer, 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...).

Version:
$Id: JSVGComponent.java 1831615 2018-05-15 09:50:53Z ssteiner $
See Also:
  • Field Details

    • AUTODETECT

      public static final int AUTODETECT
      Means that the component must auto detect whether the current document is static or dynamic.
      See Also:
    • ALWAYS_DYNAMIC

      public static final int ALWAYS_DYNAMIC
      Means that all document must be considered as dynamic. Indicates that all DOM listeners should be registered. This supports 'interactivity' (anchors and cursors), as well as DOM modifications listeners to update the GVT rendering tree.
      See Also:
    • ALWAYS_STATIC

      public static final int ALWAYS_STATIC
      Means that all document must be considered as static. Indicates that no DOM listeners should be registered. In this case the generated GVT tree should be totally independent of the DOM tree (in practice text holds references to the source text elements for font resolution).
      See Also:
    • ALWAYS_INTERACTIVE

      public static final int ALWAYS_INTERACTIVE
      Means that all document must be considered as interactive. Indicates that DOM listeners should be registered to support, 'interactivity' this includes anchors and cursors, but does not include support for DOM modifications.
      See Also:
    • SCRIPT_ALERT

      public static final String SCRIPT_ALERT
      String constant for the resource with the text for a script alert dialog. Must have a substitution for one string.
      See Also:
    • SCRIPT_PROMPT

      public static final String SCRIPT_PROMPT
      String constant for the resource with the text for a script prompt dialog. Must have a substitution for one string.
      See Also:
    • SCRIPT_CONFIRM

      public static final String SCRIPT_CONFIRM
      String constant for the resource with the text for a script confim dialog. Must have a substitution for one string.
      See Also:
    • 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 org.w3c.dom.svg.SVGDocument svgDocument
      The current SVG document.
    • svgDocumentLoaderListeners

      protected List svgDocumentLoaderListeners
      The document loader listeners.
    • gvtTreeBuilderListeners

      protected List gvtTreeBuilderListeners
      The GVT tree builder listeners.
    • svgLoadEventDispatcherListeners

      protected List svgLoadEventDispatcherListeners
      The SVG onload dispatcher listeners.
    • linkActivationListeners

      protected List linkActivationListeners
      The link activation listeners.
    • updateManagerListeners

      protected 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 String fragmentIdentifier
      The current document fragment identifier.
    • isDynamicDocument

      protected boolean isDynamicDocument
      Whether the current document has dynamic features.
    • isInteractiveDocument

      protected boolean isInteractiveDocument
      Whether the current document has dynamic features.
    • selfCallingDisableInteractions

      protected boolean selfCallingDisableInteractions
      Set to true before component calls setDisableInteractors so it knows that the users isn't the one calling it.
    • userSetDisableInteractions

      protected boolean userSetDisableInteractions
      Set to true if the user ever calls setDisableInteractions
    • documentState

      protected int documentState
      The document state.
    • prevComponentSize

      protected Dimension prevComponentSize
    • afterStopRunnable

      protected Runnable afterStopRunnable
    • updateOverlay

      protected SVGUpdateOverlay updateOverlay
    • recenterOnResize

      protected boolean recenterOnResize
    • viewingTransform

      protected AffineTransform viewingTransform
    • animationLimitingMode

      protected int animationLimitingMode
      The animation limiting mode.
    • animationLimitingAmount

      protected float animationLimitingAmount
      The amount of animation limiting.
    • jsvgComponentListener

      protected JSVGComponent.JSVGComponentListener jsvgComponentListener
      The JGVTComponentListener.
    • FEATURES

      protected static final Set FEATURES
  • Constructor Details

    • 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.
      eventsEnabled - Whether the GVT tree should be reactive to mouse and key events.
      selectableText - Whether the text should be selectable.
  • Method Details

    • dispose

      public void dispose()
    • setDisableInteractions

      public void setDisableInteractions(boolean b)
      Description copied from class: JGVTComponent
      Turn off all 'interactor' objects (pan, zoom, etc) if 'b' is true, turn them on if 'b' is false.
      Overrides:
      setDisableInteractions in class JGVTComponent
    • clearUserSetDisableInteractions

      public void clearUserSetDisableInteractions()
      Clears the boolean that indicates the 'user' has set disable interactions so that the canvas uses the value from documents.
    • updateZoomAndPanEnable

      public void updateZoomAndPanEnable(Document doc)
      Enables/Disables Zoom And Pan based on the zoom and pan attribute of the currently installed document, Unless the user has set the Interactions State.
    • getRecenterOnResize

      public boolean getRecenterOnResize()
      Indicates if the canvas should recenter the content after the canvas is resized. If true it will try and keep the point that was at the center at the center after resize. Otherwise the upper left corner will be kept at the same point.
    • setRecenterOnResize

      public void setRecenterOnResize(boolean recenterOnResize)
      Returns sate of the recenter on resize flag.
    • isDynamic

      public boolean isDynamic()
      Tells whether the component use dynamic features to process the current document.
    • isInteractive

      public boolean isInteractive()
      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. This only effects the loading of subsequent documents, it has no effect on the currently loaded document.
    • getUpdateManager

      public UpdateManager getUpdateManager()
      Returns the current update manager. The update manager becomes available after the first rendering completes. You can be notifed when the rendering completes by registering a GVTTreeRendererListener with the component and waiting for the gvtRenderingCompleted event. An UpdateManager is only created for Dynamic documents. By default the Canvas attempts to autodetect dynamic documents by looking for script elements and/or event attributes in the document, if it does not find these it assumes the document is static. Callers of this method will almost certainly want to call setDocumentState(ALWAYS_DYNAMIC) before loading the document (with setURI, setDocument, setSVGDocument etc.) so that an UpdateManager is always created (even for apparently static documents).
    • 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(String url)
      Loads a SVG document from the given URL. Note: Because the loading is multi-threaded, the current SVG document is not guaranteed to be updated after this method returns. The only way to be notified a document has been loaded is to listen to the SVGDocumentLoaderEvents.
    • startDocumentLoader

      private void startDocumentLoader()
      Starts a loading thread.
    • setDocument

      public void setDocument(Document doc)
      Sets the Document to display. If the document does not use Batik's SVG DOM Implemenation it will be cloned into that implementation. In this case you should use 'getSVGDocument()' to get the actual DOM that is attached to the rendering interface. Note that the preparation for rendering and the rendering itself occur asynchronously so you need to register event handlers if you want to know when the document is truly displayed. Notes for documents that you want to change in Java: From this point on you may only modify the the document in the UpdateManager thread @see #getUpdateManager. In many cases you also need to tell Batik to treat the document as a dynamic document by calling setDocumentState(ALWAYS_DYNAMIC).
    • setSVGDocument

      public void setSVGDocument(org.w3c.dom.svg.SVGDocument doc)
      Sets the SVGDocument to display. If the document does not use Batik's SVG DOM Implemenation it will be cloned into that implementation. In this case you should use 'getSVGDocument()' to get the actual DOM that is attached to the rendering interface. Note that the preparation for rendering and the rendering itself occur asynchronously so you need to register event handlers if you want to know when the document is truly displayed. Notes for documents that you want to change in Java. From this point on you may only modify the the document in the UpdateManager thread @see #getUpdateManager. In many cases you also need to tell Batik to treat the document as a dynamic document by calling setDocumentState(ALWAYS_DYNAMIC).
    • stopThenRun

      protected void stopThenRun(Runnable r)
      This method calls stop processing waits for all threads to die then runs the Runnable in the event queue thread. It returns immediately.
    • installSVGDocument

      protected void installSVGDocument(org.w3c.dom.svg.SVGDocument doc)
      This does the real work of installing the SVG Document after the update manager from the previous document (if any) has been properly 'shut down'.
    • startGVTTreeBuilder

      protected void startGVTTreeBuilder()
      Starts a tree builder.
    • getSVGDocument

      public org.w3c.dom.svg.SVGDocument getSVGDocument()
      Returns the current SVG document.
    • getSVGDocumentSize

      public Dimension2D getSVGDocumentSize()
      Returns the size of the SVG document.
    • getFragmentIdentifier

      public String getFragmentIdentifier()
      Returns the current's document fragment identifier.
    • setFragmentIdentifier

      public void setFragmentIdentifier(String fi)
      Sets the current fragment identifier.
    • flushImageCache

      public void flushImageCache()
      Removes all images from the image cache.
    • setGraphicsNode

      public void setGraphicsNode(GraphicsNode gn, boolean createDispatcher)
      Description copied from class: JGVTComponent
      Sets the GVT tree to display.
      Overrides:
      setGraphicsNode in class JGVTComponent
    • createBridgeContext

      protected BridgeContext createBridgeContext(SVGOMDocument doc)
      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
    • getCanvasGraphicsNode

      public CanvasGraphicsNode getCanvasGraphicsNode()
    • getCanvasGraphicsNode

      protected CanvasGraphicsNode getCanvasGraphicsNode(GraphicsNode gn)
    • getViewingTransform

      public AffineTransform getViewingTransform()
    • getViewBoxTransform

      public AffineTransform getViewBoxTransform()
      Returns the transform from viewBox coords to screen coords
    • computeRenderingTransform

      protected boolean computeRenderingTransform()
      Computes the transform used for rendering. Returns true if the component needs to be repainted.
      Overrides:
      computeRenderingTransform in class JGVTComponent
    • calculateViewingTransform

      protected AffineTransform calculateViewingTransform(String fragIdent, org.w3c.dom.svg.SVGSVGElement svgElt)
    • updateRenderingTransform

      protected boolean updateRenderingTransform()
      Updates the value of the transform used for rendering. Return true if a repaint is required, otherwise false.
      Overrides:
      updateRenderingTransform in class JGVTComponent
    • renderGVTTree

      protected void renderGVTTree()
      Renders the GVT tree.
      Overrides:
      renderGVTTree in class JGVTComponent
    • handleException

      protected void handleException(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(String message)
      Shows an alert dialog box.
    • showPrompt

      public String showPrompt(String message)
      Shows a prompt dialog box.
    • showPrompt

      public String showPrompt(String message, String defaultValue)
      Shows a prompt dialog box.
    • showConfirm

      public boolean showConfirm(String message)
      Shows a confirm dialog box.
    • setMySize

      public void setMySize(Dimension d)
      This method is called when the component knows the desired size of the window (based on width/height of outermost SVG element). The default implementation simply calls setPreferredSize, and invalidate. However it is often useful to pack the window containing this component.
    • setAnimationLimitingNone

      public void setAnimationLimitingNone()
      Sets the animation limiting mode to "none".
    • setAnimationLimitingCPU

      public void setAnimationLimitingCPU(float pc)
      Sets the animation limiting mode to a percentage of CPU.
      Parameters:
      pc - the maximum percentage of CPU to use (0 < pc ≤ 1)
    • setAnimationLimitingFPS

      public void setAnimationLimitingFPS(float fps)
      Sets the animation limiting mode to a number of frames per second.
      Parameters:
      fps - the maximum number of frames per second (fps > 0)
    • getInterpreter

      public Interpreter getInterpreter(String type)
      Returns the Interpreter being used for script of the given MIME type.
      Parameters:
      type - The MIME type the returned Interpreter handles.
    • setBridgeContextAnimationLimitingMode

      protected void setBridgeContextAnimationLimitingMode()
      Sets the animation limiting mode on the current bridge context.
    • createListener

      protected JGVTComponent.Listener createListener()
      Creates an instance of Listener.
      Overrides:
      createListener in class JGVTComponent
    • createUserAgent

      protected UserAgent createUserAgent()
      Creates a UserAgent.