public class

SVG

extends Object
java.lang.Object
   ↳ com.caverock.androidsvg.SVG

Class Overview

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 background to white

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

Summary

Public Methods
float getDocumentAspectRatio()
Returns the aspect ratio of the document as a width/height fraction.
String getDocumentDescription()
Returns the contents of the <desc> element in the SVG document.
float getDocumentHeight()
Returns the height of the document as specified in the SVG file.
PreserveAspectRatio getDocumentPreserveAspectRatio()
Return the "preserveAspectRatio" attribute of the root <svg> element in the form of an PreserveAspectRatio object.
String getDocumentSVGVersion()
Returns the SVG version number as provided in the root <svg> tag of the document.
String getDocumentTitle()
Returns the contents of the <title> element in the SVG document.
RectF getDocumentViewBox()
Returns the viewBox attribute of the current SVG document.
float getDocumentWidth()
Returns the width of the document as specified in the SVG file.
static SVG getFromAsset(AssetManager assetManager, String filename)
Read and parse an SVG from the assets folder.
static SVG getFromInputStream(InputStream is)
Read and parse an SVG from the given InputStream.
static SVG getFromResource(Resources resources, int resourceId)
Read and parse an SVG from the given resource location.
static SVG getFromResource(Context context, int resourceId)
Read and parse an SVG from the given resource location.
static SVG getFromString(String svg)
Read and parse an SVG from the given String.
float getRenderDPI()
Get the current render DPI setting.
static String getVersion()
Returns the version number of this library.
Set<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(Canvas canvas, RectF viewPort)
Renders this SVG document to a Canvas object.
void renderToCanvas(Canvas canvas)
Renders this SVG document to a Canvas object.
Picture renderToPicture(int widthInPixels, int heightInPixels)
Renders this SVG document to a Picture object.
Picture renderToPicture()
Renders this SVG document to a Picture object.
void renderViewToCanvas(String viewId, Canvas canvas)
Renders this SVG document to a Canvas using the specified view defined in the document.
void renderViewToCanvas(String viewId, Canvas canvas, RectF viewPort)
Renders this SVG document to a Canvas using the specified view defined in the document.
Picture renderViewToPicture(String viewId, int widthInPixels, int heightInPixels)
Renders this SVG document to a Picture object using the specified view defined in the document.
void setDocumentHeight(float pixels)
Change the height of the document by altering the "height" attribute of the root <svg> element.
void setDocumentHeight(String value)
Change the height of the document by altering the "height" attribute of the root <svg> element.
void setDocumentPreserveAspectRatio(PreserveAspectRatio preserveAspectRatio)
Change the document positioning by altering the "preserveAspectRatio" attribute of the root <svg> element.
void setDocumentViewBox(float minX, float minY, float width, float height)
Change the document view box by altering the "viewBox" attribute of the root <svg> element.
void setDocumentWidth(float pixels)
Change the width of the document by altering the "width" attribute of the root <svg> element.
void setDocumentWidth(String value)
Change the width of the document by altering the "width" attribute of the root <svg> element.
void setRenderDPI(float dpi)
Set the DPI (dots-per-inch) value to use when rendering.
[Expand]
Inherited Methods
From class java.lang.Object

Public Methods

public float getDocumentAspectRatio ()

Returns the aspect ratio of the document as a width/height fraction.

If the width or height of the document are listed with a physical unit such as "cm", then the current renderDPI setting will be used to convert that value to pixels.

If the width or height cannot be determined, -1 will be returned.

Returns
  • the aspect ratio as a width/height fraction, or -1 if the ratio cannot be determined.
Throws
IllegalArgumentException if there is no current SVG document loaded.

public String getDocumentDescription ()

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

Returns
  • desc contents if available, otherwise an empty string.
Throws
IllegalArgumentException if there is no current SVG document loaded.

public float getDocumentHeight ()

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 current RenderDPI value 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.

Returns
  • the height in pixels, or -1 if there is no height available.
Throws
IllegalArgumentException if there is no current SVG document loaded.

public PreserveAspectRatio getDocumentPreserveAspectRatio ()

Return the "preserveAspectRatio" attribute of the root <svg> element in the form of an PreserveAspectRatio object.

Returns
  • the preserveAspectRatio setting of the document's root <svg> element.
Throws
IllegalArgumentException if there is no current SVG document loaded.

public 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.
Throws
IllegalArgumentException if there is no current SVG document loaded.

public String getDocumentTitle ()

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

Returns
  • title contents if available, otherwise an empty string.
Throws
IllegalArgumentException if there is no current SVG document loaded.

public RectF getDocumentViewBox ()

Returns the viewBox attribute of the current SVG document.

Returns
  • the document's viewBox attribute as a android.graphics.RectF object, or null if not set.
Throws
IllegalArgumentException if there is no current SVG document loaded.

public float getDocumentWidth ()

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 current RenderDPI value 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.

Returns
  • the width in pixels, or -1 if there is no width available.
Throws
IllegalArgumentException if there is no current SVG document loaded.

public static SVG getFromAsset (AssetManager assetManager, String filename)

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.
IOException if there is some IO error while reading the file.

public static SVG getFromInputStream (InputStream is)

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.

public static SVG getFromResource (Resources resources, int resourceId)

Read and parse an SVG from the given resource location.

Parameters
resources the set of Resources in which to locate the file.
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.

public static SVG getFromResource (Context context, int resourceId)

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.

public static SVG getFromString (String svg)

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.

public float getRenderDPI ()

Get the current render DPI setting.

Returns
  • the DPI value

public static String getVersion ()

Returns the version number of this library.

Returns
  • the version number in string format

public Set<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 renderViewToX() methods.

Returns
  • the list of id strings.
Throws
IllegalArgumentException if there is no current SVG document loaded.

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.

public void renderToCanvas (Canvas canvas, 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.

public void renderToCanvas (Canvas canvas)

Renders this SVG document to a Canvas object. The full width and height of the canvas will be used as the viewport into which the document will be rendered.

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

public 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()

public 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()

public void renderViewToCanvas (String viewId, 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.

public void renderViewToCanvas (String viewId, Canvas canvas, 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.

public Picture renderViewToPicture (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 document 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.

public void setDocumentHeight (float pixels)

Change the height of the document by altering the "height" attribute of the root <svg> element.

Parameters
pixels The new value of height in pixels.
Throws
IllegalArgumentException if there is no current SVG document loaded.

public void setDocumentHeight (String value)

Change the height of the document by altering the "height" attribute of the root <svg> element.

Parameters
value A valid SVG 'length' attribute, such as "100px" or "10cm".
Throws
SVGParseException if value cannot be parsed successfully.
IllegalArgumentException if there is no current SVG document loaded.

public void setDocumentPreserveAspectRatio (PreserveAspectRatio preserveAspectRatio)

Change the document positioning by altering the "preserveAspectRatio" attribute of the root <svg> element. See the documentation for PreserveAspectRatio for more information on how positioning works.

Parameters
preserveAspectRatio the new preserveAspectRatio setting for the root <svg> element.
Throws
IllegalArgumentException if there is no current SVG document loaded.

public void setDocumentViewBox (float minX, float minY, float width, float height)

Change the document view box by altering the "viewBox" attribute of the root <svg> element.

The viewBox generally describes the bounding box dimensions of the document contents. A valid viewBox is necessary if you want the document scaled to fit the canvas or viewport the document is to be rendered into.

By setting a viewBox that describes only a portion of the document, you can reproduce the effect of image sprites.

Parameters
minX the left coordinate of the viewBox in pixels
minY the top coordinate of the viewBox in pixels.
width the width of the viewBox in pixels
height the height of the viewBox in pixels
Throws
IllegalArgumentException if there is no current SVG document loaded.

public void setDocumentWidth (float pixels)

Change the width of the document by altering the "width" attribute of the root <svg> element.

Parameters
pixels The new value of width in pixels.
Throws
IllegalArgumentException if there is no current SVG document loaded.

public void setDocumentWidth (String value)

Change the width of the document by altering the "width" attribute of the root <svg> element.

Parameters
value A valid SVG 'length' attribute, such as "100px" or "10cm".
Throws
SVGParseException if value cannot be parsed successfully.
IllegalArgumentException if there is no current SVG document loaded.

public void setRenderDPI (float dpi)

Set the DPI (dots-per-inch) value to use when rendering. The DPI setting is used in the conversion of "physical" units - such an "pt" or "cm" - to pixel values. The default DPI is 96.

You should not normally need to alter the DPI from the default of 96 as recommended by the SVG and CSS specifications.

Parameters
dpi the DPI value that the renderer should use.