com.caverock.androidsvg

Class SVG

java.lang.Object

com.caverock.androidsvg.SVG

public class SVG
extends java.lang.Object

AndroidSVG is a library for reading, parsing and rendering SVG documents on Android devices.

All interaction with AndroidSVG is via this class.

Typically, you will call one of the SVG loading and parsing classes then call the renderer, passing it a canvas to draw upon.

Usage summary

• Use one of the static getFromX() methods to read and parse the SVG file. They will return an instance of this class.
• Call one of the renderToX() methods to render the document.

Usage example

 SVG  svg = SVG.getFromAsset(getContext().getAssets(), svgPath);
 svg.registerExternalFileResolver(myResolver);

 Bitmap  newBM = Bitmap.createBitmap(width, height, Bitmap.Config.ARGB_8888);
 Canvas  bmcanvas = new Canvas(newBM);
 bmcanvas.drawRGB(255, 255, 255);  // Clear bg to white

 svg.renderToCanvas(bmcanvas, null, getResources().getDisplayMetrics().xdpi, SVG.AspectRatioAlignment.xMidYMid, true);
 
 

For more detailed information on how to use this library, see the documentation at http://code.google.com/p/androidsvg/

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SVG.AspectRatioAlignment Determines how the document is to me positioned relative to the viewport (normally the canvas).
static class	SVG.AspectRatioScale Determine whether the scaled document fills the viewport entirely or is scaled to fill the viewport without overflowing.

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.String	getDocumentDescription() Returns the contents of the <desc> element in the SVG document.
float	getDocumentHeight(float dpi) Returns the height of the document as specified in the SVG file.
java.lang.String	getDocumentSVGVersion() Returns the SVG version number as provided in the root <svg> tag of the document.
java.lang.String	getDocumentTitle() Returns the contents of the <title> element in the SVG document.
float	getDocumentWidth(float dpi) Returns the width of the document as specified in the SVG file.
static SVG	getFromAsset(android.content.res.AssetManager assetManager, java.lang.String filename) Read and parse an SVG from the assets folder.
static SVG	getFromInputStream(java.io.InputStream is) Read and parse an SVG from the given InputStream.
static SVG	getFromResource(android.content.Context context, int resourceId) Read and parse an SVG from the given resource location.
static SVG	getFromString(java.lang.String svg) Read and parse an SVG from the given String.
java.lang.String	getVersion() Returns the version number of this library.
java.util.Set<java.lang.String>	getViewList() Returns a list of ids for all <view> elements in this SVG document.
void	registerExternalFileResolver(SVGExternalFileResolver fileResolver) Register an SVGExternalFileResolver instance that the renderer should use when resolving external references such as images and fonts.
void	renderToCanvas(android.graphics.Canvas canvas) Renders this SVG document to a Canvas object.
void	renderToCanvas(android.graphics.Canvas canvas, android.graphics.RectF viewPort) Renders this SVG document to a Canvas object.
void	renderToCanvas(android.graphics.Canvas canvas, android.graphics.RectF viewPort, float defaultDPI, SVG.AspectRatioAlignment alignment, SVG.AspectRatioScale scale) Renders this SVG document to a Canvas object.
android.graphics.Picture	renderToPicture() Renders this SVG document to a Picture object.
android.graphics.Picture	renderToPicture(int widthInPixels, int heightInPixels) Renders this SVG document to a Picture object.
android.graphics.Picture	renderToPicture(int widthInPixels, int heightInPixels, float defaultDPI, SVG.AspectRatioAlignment alignment, SVG.AspectRatioScale scale) Renders this SVG document to a Picture object.
void	renderViewToCanvas(java.lang.String viewId, android.graphics.Canvas canvas) Renders this SVG document to a Canvas using the specified view defined in the document.
void	renderViewToCanvas(java.lang.String viewId, android.graphics.Canvas canvas, android.graphics.RectF viewPort) Renders this SVG document to a Canvas using the specified view defined in the document.
void	renderViewToCanvas(java.lang.String viewId, android.graphics.Canvas canvas, android.graphics.RectF viewPort, float defaultDPI) Renders this SVG document to a Canvas using the specified view defined in the document.
android.graphics.Picture	renderViewToPicture(java.lang.String viewId, int widthInPixels, int heightInPixels) Renders this SVG document to a Picture object using the specified view defined in the document.
android.graphics.Picture	renderViewToPicture(java.lang.String viewId, int widthInPixels, int heightInPixels, float defaultDPI) Renders this SVG document to a Picture object using the specified view defined in the document.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getFromInputStream

public static SVG getFromInputStream(java.io.InputStream is)
                              throws SVGParseException

Read and parse an SVG from the given InputStream.

Parameters:

is - the input stream from which to read the file.

Returns:

an SVG instance on which you can call one of the render methods.

Throws:

SVGParseException - if there is an error parsing the document.

getFromString

public static SVG getFromString(java.lang.String svg)
                         throws SVGParseException

Read and parse an SVG from the given String.

Parameters:

svg - the String instance containing the SVG document.

Returns:

an SVG instance on which you can call one of the render methods.

Throws:

SVGParseException - if there is an error parsing the document.

getFromResource

public static SVG getFromResource(android.content.Context context,
                  int resourceId)
                           throws SVGParseException

Read and parse an SVG from the given resource location.

Parameters:

context - the Android context of the resource.

resourceId - the resource identifier of the SVG document.

Returns:

an SVG instance on which you can call one of the render methods.

Throws:

SVGParseException - if there is an error parsing the document.

getFromAsset

public static SVG getFromAsset(android.content.res.AssetManager assetManager,
               java.lang.String filename)
                        throws SVGParseException,
                               java.io.IOException

Read and parse an SVG from the assets folder.

Parameters:

assetManager - the AssetManager instance to use when reading the file.

filename - the filename of the SVG document within assets.

Returns:

an SVG instance on which you can call one of the render methods.

Throws:

SVGParseException - if there is an error parsing the document.

java.io.IOException - if there is some IO error while reading the file.

registerExternalFileResolver

public void registerExternalFileResolver(SVGExternalFileResolver fileResolver)

Register an SVGExternalFileResolver instance that the renderer should use when resolving external references such as images and fonts.

Parameters:

fileResolver - the resolver to use.

renderToPicture

public android.graphics.Picture renderToPicture()

Renders this SVG document to a Picture object.

An attempt will be made to determine a suitable initial viewport from the contents of the SVG file. If an appropriate viewport can't be determined, a default viewport of 512x512 will be used.

Returns:

a Picture object suitable for later rendering using Canvas.drawPicture()

renderToPicture

public android.graphics.Picture renderToPicture(int widthInPixels,
                                       int heightInPixels)

Renders this SVG document to a Picture object.

Parameters:

widthInPixels - the width of the initial viewport

heightInPixels - the height of the initial viewport

Returns:

a Picture object suitable for later rendering using Canvas.darwPicture()

renderToPicture

public android.graphics.Picture renderToPicture(int widthInPixels,
                                       int heightInPixels,
                                       float defaultDPI,
                                       SVG.AspectRatioAlignment alignment,
                                       SVG.AspectRatioScale scale)

Renders this SVG document to a Picture object.

Parameters:

widthInPixels - the width of the initial viewport

heightInPixels - the height of the initial viewport

defaultDPI - the default DPI value to use when calculating the size of physical units such as cm, pt etc. May be over-ridden by the document.

alignment - the type of alignment desired when calculating how to fit the document to the viewport. If null, the default xMidYMid will be used.

scale - the degree of scaling to be applied to the document to fit the viewport. If null, the default of MEET will be used.

Returns:

a Picture object suitable for later rendering using Canvas.drawPicture().

renderViewToPicture

public android.graphics.Picture renderViewToPicture(java.lang.String viewId,
                                           int widthInPixels,
                                           int heightInPixels)

Renders this SVG document to a Picture object using the specified view defined in the document.

A View is an special element in a SVG documents that describes a rectangular area in the document. Calling this method with a viewId will result in the specified view being positioned and scaled to the viewport. In other words, use renderToPicture() to render the whole document, or use this method instead to render just a part of it.

Parameters:

viewId - the id of a view element in the document that defines which section of the document is to be visible.

widthInPixels - the width of the initial viewport.

heightInPixels - the height of the initial viewport.

Returns:

a Picture object suitable for later rendering using Canvas.drawPicture(), or null if the viewId was not found.

renderViewToPicture

public android.graphics.Picture renderViewToPicture(java.lang.String viewId,
                                           int widthInPixels,
                                           int heightInPixels,
                                           float defaultDPI)

Renders this SVG document to a Picture object using the specified view defined in the document.

A View is an special element in a SVG documents that describes a rectangular area in the document. Calling this method with a viewId will result in the specified view being positioned and scaled to the viewport. In other words, use renderToPicture() to render the whole document, or use this method instead to render just a part of it.

Parameters:

viewId - the id of a view element in the document that defines which section of the document is to be visible.

widthInPixels - the width of the initial viewport

heightInPixels - the height of the initial viewport

defaultDPI - the default DPI value to use when calculating the size of physical units such as cm, pt etc.

Returns:

a Picture object suitable for later rendering using Canvas.drawPicture(), or null if the viewId was not found.

renderToCanvas

public void renderToCanvas(android.graphics.Canvas canvas)

Renders this SVG document to a Canvas object.

Parameters:

canvas - the canvas to which the document should be rendered.

renderToCanvas

public void renderToCanvas(android.graphics.Canvas canvas,
                  android.graphics.RectF viewPort)

Renders this SVG document to a Canvas object.

Parameters:

canvas - the canvas to which the document should be rendered.

viewPort - the bounds of the area on the canvas you want the SVG rendered, or null for the whole canvas.

renderToCanvas

public void renderToCanvas(android.graphics.Canvas canvas,
                  android.graphics.RectF viewPort,
                  float defaultDPI,
                  SVG.AspectRatioAlignment alignment,
                  SVG.AspectRatioScale scale)

Renders this SVG document to a Canvas object.

The defaultDPI (dots per inch) parameter tells the renderer what DPI to use when calculating the size of any real world units that appear in the file. An example would be "20mm". The default for most desktop SVG renderers is 96, matching the DPI of a standard desktop monitor. You can choose to use this value, or supply the DPI of your device if you wish.

Note that the file itself could override the DPI value you supply anyway. For example, if your file's root <SVG> element was defined as follows:

 <svg width="8cm" height="8cm" viewBox="0 0 400 400">
 
 

AndroidSVG would use a DPI of 127 rather than any value you supply (50 pixels per centimetre corresponds to a DPI of 127).

The alignment and scale parameters control how the document is positioned within the viewPort. See the definition for SVG.AspectRatioAlignment and SVG.AspectRatioScale for more information.

Parameters:

canvas - the canvas to which the document should be rendered.

viewPort - the bounds of the area on the canvas you want the SVG rendered, or null for the whole canvas.

defaultDPI - the default DPI value to use when calculating the size of physical units such as cm, pt etc. May be over-ridden by the document.

alignment - the type of alignment desired when calculating how to fit the document to the viewport. If null, the default xMidYMid will be used.

scale - the degree of scaling to be applied to the document to fit the viewport. If null, the default of MEET will be used.

renderViewToCanvas

public void renderViewToCanvas(java.lang.String viewId,
                      android.graphics.Canvas canvas)

Renders this SVG document to a Canvas using the specified view defined in the document.

A View is an special element in a SVG documents that describes a rectangular area in the document. Calling this method with a viewId will result in the specified view being positioned and scaled to the viewport. In other words, use renderToPicture() to render the whole document, or use this method instead to render just a part of it.

If the <view> could not be found, nothing will be drawn.

Parameters:

viewId - the id of a view element in the document that defines which section of the document is to be visible.

canvas - the canvas to which the document should be rendered.

renderViewToCanvas

public void renderViewToCanvas(java.lang.String viewId,
                      android.graphics.Canvas canvas,
                      android.graphics.RectF viewPort)

Renders this SVG document to a Canvas using the specified view defined in the document.

A View is an special element in a SVG documents that describes a rectangular area in the document. Calling this method with a viewId will result in the specified view being positioned and scaled to the viewport. In other words, use renderToPicture() to render the whole document, or use this method instead to render just a part of it.

If the <view> could not be found, nothing will be drawn.

Parameters:

viewId - the id of a view element in the document that defines which section of the document is to be visible.

canvas - the canvas to which the document should be rendered.

viewPort - the bounds of the area on the canvas you want the SVG rendered, or null for the whole canvas.

renderViewToCanvas

public void renderViewToCanvas(java.lang.String viewId,
                      android.graphics.Canvas canvas,
                      android.graphics.RectF viewPort,
                      float defaultDPI)

Renders this SVG document to a Canvas using the specified view defined in the document.

A View is an special element in a SVG documents that describes a rectangular area in the document. Calling this method with a viewId will result in the specified view being positioned and scaled to the viewport. In other words, use renderToPicture() to render the whole document, or use this method instead to render just a part of it.

If the <view> could not be found, nothing will be drawn.

Parameters:

viewId - the id of a view element in the document that defines which section of the document is to be visible.

canvas - the canvas to which the document should be rendered.

viewPort - the bounds of the area on the canvas you want the SVG rendered, or null for the whole canvas.

defaultDPI - the default DPI value to use when calculating the size of physical units such as cm, pt etc. May be over-ridden by the document.

getVersion

public java.lang.String getVersion()

Returns the version number of this library.

Returns:

the version number in string format

getDocumentTitle

public java.lang.String getDocumentTitle()

Returns the contents of the <title> element in the SVG document.

Returns:

title contents if declared, otherwise an empty string.

getDocumentDescription

public java.lang.String getDocumentDescription()

Returns the contents of the <desc> element in the SVG document.

Returns:

desc contents if declared, otherwise an empty string.

getDocumentSVGVersion

public java.lang.String getDocumentSVGVersion()

Returns the SVG version number as provided in the root <svg> tag of the document.

Returns:

the version string if declared, otherwise an empty string.

getViewList

public java.util.Set<java.lang.String> getViewList()

Returns a list of ids for all <view> elements in this SVG document.

The returned view ids could be used when calling and of the renderToXForView() methods.

Returns:

the list of id strings.

getDocumentWidth

public float getDocumentWidth(float dpi)

Returns the width of the document as specified in the SVG file.

If the width in the document is specified in pixels, that value will be returned. If the value is listed with a physical unit such as "cm", then the dpi parameter will be used to convert that value to pixels. If the width is missing, or in a form which can't be converted to pixels, such as "100%" for example, -1 will be returned.

Parameters:

dpi - the DPI value to use when converting real-world values such as "cm" (centimetres).

Returns:

the width in pixels, or -1 if there is no width available.

getDocumentHeight

public float getDocumentHeight(float dpi)

Returns the height of the document as specified in the SVG file.

If the height in the document is specified in pixels, that value will be returned. If the value is listed with a physical unit such as "cm", then the dpi parameter will be used to convert that value to pixels. If the height is missing, or in a form which can't be converted to pixels, such as "100%" for example, -1 will be returned.

Parameters:

dpi - the DPI value to use when converting real-world values such as "cm" (centimetres).

Returns:

the height in pixels, or -1 if there is no height available.